instar 1.3.32 → 1.3.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.32",
+  "version": "1.3.34",
   "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-27T22:28:16.266Z",
-  "instarVersion": "1.3.32",
+  "generatedAt": "2026-05-27T22:51:12.342Z",
+  "instarVersion": "1.3.34",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {
@@ -401,7 +401,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -409,7 +409,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -417,7 +417,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -425,7 +425,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -433,7 +433,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -441,7 +441,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -449,7 +449,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -457,7 +457,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -465,7 +465,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -473,7 +473,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -481,7 +481,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -489,7 +489,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -497,7 +497,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -505,7 +505,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -513,7 +513,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -521,7 +521,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -529,7 +529,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -537,7 +537,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -545,7 +545,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -553,7 +553,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -561,7 +561,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -569,7 +569,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -577,7 +577,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -585,7 +585,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -593,7 +593,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -601,7 +601,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -609,7 +609,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -617,7 +617,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -625,7 +625,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -633,7 +633,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -641,7 +641,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -649,7 +649,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -657,7 +657,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -665,7 +665,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -673,7 +673,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -681,7 +681,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -689,7 +689,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -697,7 +697,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -705,7 +705,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -713,7 +713,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -721,7 +721,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -729,7 +729,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -737,7 +737,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -753,7 +753,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bab755f0fac6c0294987980226d9e86e0c66dbc907bb63e7e069752c69227a12",
+      "contentHash": "96fab9a3a4a73c46881b736f94f8ddb60f93426a0b62411cafb8752fdd61526c",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1449,7 +1449,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "1ea8e7160275776b2e410635588d2db3cc56083324dff60488cc5e3a41cf2025",
+      "contentHash": "d82518a55c08f4a3272996194be47868415b904f407d1fcec7c43cbcd0ac1275",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/upgrades/1.3.31.md

@@ -4,26 +4,25 @@
 
 ## What Changed
 
-Notify-on-stop, Layer A: when an autonomous run reaches a terminal exit — it completed, ran out of its time budget, or was emergency-stopped — the agent now sends one plain-English Telegram to the run's topic explaining why it stopped. Previously these reasons were only written to stderr (the terminal the user can't see), so an autonomous run could end in silence unless the agent remembered to send a wrap-up. This bakes the "a session either keeps going OR tells you why it stopped" guarantee into the stop hook itself.
+Notify-on-stop, Layer B: when the Unjustified Stop Gate judges a stop unjustified-but-unblockable (`continue` in shadow mode — the gate wants to keep going but shadow can't block, so the session silently stalls) or ambiguous (`escalate`), and the stopping session is **unattended** (an autonomous run), the user now gets one coalesced plain-English heads-up ("a background run stopped mid-task — want me to pick it back up?"). Previously the gate saw these and could do nothing the user could observe.
 
-The notice is best-effort and non-blocking (a delivery hiccup never blocks the exit), fires at most once per run, and reuses the existing Telegram reply transport + the run's existing topic (no new topic is ever created).
+Tightly bounded to stay near-silent: only those two genuinely-stuck decision classes, only unattended sessions, at most once per session per 30 minutes, coalesced onto the single system (lifeline) topic. Routine turn-ends, blocked-and-continued stops, and transient fail-opens stay silent. Default ON (Justin's explicit "tell me why it stopped"); disable with `monitoring.notifyOnStop.enabled=false`.
 
-Existing agents receive the notify-enabled hook automatically: the autonomous-stop-hook capability marker is bumped, so the marker+fingerprint migration re-deploys the updated hook to stock installs on update (customized hooks are left untouched).
+Pairs with Layer A (autonomous-run terminal-exit notices, shipped in #437). Together: a session either keeps going, or the user is told why it stopped.
 
 ## What to Tell Your User
 
-- When one of my autonomous runs finishes (or times out, or is stopped), you now get a short heads-up explaining why — no more silent endings.
+- If one of my background runs stalls mid-task when it shouldn't have, you now get a single heads-up — even when the watchdog can't restart it itself.
 
 ## Summary of New Capabilities
 
 | Capability | How to Use |
 |-----------|-----------|
-| Autonomous-run terminal exits send a Telegram explaining why | Automatic; one message per run to the run's topic |
+| Unjustified mid-task stalls on unattended sessions surface one coalesced Telegram | Automatic (default on); `monitoring.notifyOnStop.enabled=false` to disable |
 
 ## Evidence
 
-- Hook: `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh` (`notify_terminal_stop` at all 6 terminal exits).
-- Migration: `src/core/PostUpdateMigrator.ts` (capability marker → `notify_terminal_stop`).
-- Tests: `tests/unit/autonomous-stop-hook-notify.test.ts` (9 — static wiring, functional delivery via the real extracted helper, migration).
-- Spec: `docs/specs/NOTIFY-ON-STOP-SPEC.md` (approved) + `.eli16.md`. Side-effects: `upgrades/side-effects/notify-on-stop-layer-a.md`.
-- Layer B (watchdog-caught mid-task stalls) ships separately under the same spec.
+- `src/monitoring/StopNotifier.ts` (decision matrix + attended-gate + dedup); wired via `src/server/routes.ts` (evaluate route), `src/commands/server.ts` (construction), `src/server/AgentServer.ts` (forward).
+- Config: `monitoring.notifyOnStop` in `src/core/types.ts`.
+- Tests: `tests/unit/StopNotifier.test.ts` (21 — both sides of every decision boundary, gates, dedup) + `tests/unit/stop-notifier-wiring.test.ts` (6 — no dead code).
+- Spec: `docs/specs/NOTIFY-ON-STOP-SPEC.md` (approved). Side-effects: `upgrades/side-effects/notify-on-stop-layer-b.md`.

package/upgrades/1.3.33.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Notify-on-stop, Layer B.** When the Unjustified Stop Gate judges a stop unjustified-but-unblockable (`continue` in shadow mode — the gate wants to keep going but shadow can't block, so the session silently stalls) or ambiguous (`escalate`), and the stopping session is **unattended** (an autonomous run), the user now gets one coalesced plain-English heads-up ("a background run stopped mid-task — want me to pick it back up?"). Previously the gate saw these and could do nothing the user could observe.
+
+Tightly bounded to stay near-silent: only those two genuinely-stuck decision classes, only unattended sessions, at most once per session per 30 minutes, coalesced onto the single system (lifeline) topic. Routine turn-ends, blocked-and-continued stops, and transient fail-opens stay silent. Default ON (Justin's explicit "tell me why it stopped"); disable with `monitoring.notifyOnStop.enabled=false`. Pairs with Layer A (autonomous-run terminal-exit notices).
+
+**Feedback Factory Migration — dry-run/compare machinery.** Next increment of the migration (spec `docs/specs/feedback-factory-migration.md`, approved). Ships the safety harness that lets the ported Instar processor run safely against Portal's live database during the cutover — without ever being able to change it. Three new internal modules under `src/feedback-factory/`:
+
+- **`store/ReadOnlyShadowStore.ts`** — a read-only wrapper around the feedback data layer. Reads pass through; every write throws. The structural guarantee that the dry-run can never mutate the curated bug history (Portal stays the sole writer through cutover).
+- **`processor/parity.ts`** — the comparator for the three order-independent invariants the migration spec pins: per-cluster fingerprint, terminal status, and recurrence count. Recomputing fingerprints over the live clusters and diffing them is the highest-signal check — it catches any Python↔TypeScript divergence on real production titles.
+- **`dryrun/dryRunCompare.ts`** — the runner: reads the clusters, compares the invariants, writes a JSONL audit trail, and returns a verdict. `divergent === true` is the signal that blocks cutover.
+
+Still internal building blocks — not yet wired into any route or job, so no behavioral change. The live database adapter behind the read-only seam lands once Dawn hands off the read credentials.
+
+## What to Tell Your User
+
+- If one of my background runs stalls mid-task when it shouldn't have, you now get a single heads-up — even when the watchdog can't restart it itself.
+- On the feedback system: this is the safety harness for moving it in-house. It lets me run my new version *alongside* Dawn's, reading the same live data, and prove they make identical decisions — while making it physically impossible for my version to touch the real records. The comparison is built to ignore harmless ordering differences and only flag *real* disagreements.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Unjustified mid-task stalls on unattended sessions surface one coalesced Telegram | Automatic (default on); `monitoring.notifyOnStop.enabled=false` to disable |
+| Read-only shadow store (write-guard) | Internal `src/feedback-factory/store/ReadOnlyShadowStore.ts` — wraps any `FeedbackStore`; writes throw |
+| Parity invariant comparator | Internal `src/feedback-factory/processor/parity.ts` — `compareInvariants()` |
+| Dry-run/compare runner | Internal `src/feedback-factory/dryrun/dryRunCompare.ts` — `runDryRunCompare(source, opts)` → verdict + JSONL |
+
+## Evidence
+
+- **Notify-on-stop Layer B:** `src/monitoring/StopNotifier.ts` (decision matrix + attended-gate + dedup); wired via `src/server/routes.ts`, `src/commands/server.ts`, `src/server/AgentServer.ts`. Config: `monitoring.notifyOnStop` in `src/core/types.ts`. Tests: `tests/unit/StopNotifier.test.ts` (21) + `tests/unit/stop-notifier-wiring.test.ts` (6). Spec: `docs/specs/NOTIFY-ON-STOP-SPEC.md`. Side-effects: `upgrades/side-effects/notify-on-stop-layer-b.md`.
+- **Feedback-factory dry-run:** 21 new unit tests across the three modules, all green; full feedback-factory unit dir 128/128 green; `tsc --noEmit` clean. Both-sides-of-boundary: every read delegates AND every write throws (with the offending method name); the comparator asserts no-divergence on matching data plus a real divergence for each invariant; the runner covers the clean path, a divergent corpus, the JSONL audit trail, return-only mode, and the never-mutates-the-source guarantee. Faithful to the reference: per-cluster fingerprint is derived exactly as the Python's `cmd_backfill_fingerprints` (`computeFingerprint(cluster.type, cluster.title)`). Side-effects: `upgrades/side-effects/feedback-factory-dryrun.md`.

package/upgrades/1.3.34.md

@@ -0,0 +1,37 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**TelegramAdapter can now run a second bot cleanly (groundwork for agent-to-agent Telegram
+comms).** Two internal additions, both shipping dark (nothing uses them yet): (1) a
+non-primary Telegram adapter can namespace its own state files under a sub-directory, so two
+bots in one process never clobber each other's poll-offset / registry / message-log /
+attention files; and (2) inbound Telegram messages now expose whether the sender is a bot
+(`is_bot`) and any `sender_chat` — the structural input a later update uses to tell an
+agent-sent message from a human typing the same text. The primary bot's behavior and state
+paths are byte-for-byte unchanged.
+
+## What to Tell Your User
+
+- Nothing changes in how your agent behaves today — this is plumbing for a later feature
+  (agents messaging each other over Telegram). Your agent's own Telegram keeps working
+  exactly as before.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Multi-instance `TelegramAdapter` | Internal — `new TelegramAdapter(cfg, stateDir, { subDir, suppressLifelineAutoCreate })`; primary (no opts) unchanged |
+| Sender-identity on inbound messages | Internal — `message.from.is_bot` + `message.sender_chat` exposed on the update type |
+
+## Evidence
+
+**Net-new groundwork, not a bug fix.** Proven by a dedicated test asserting the load-bearing
+safety property — a PRIMARY adapter's four state-file paths are byte-for-byte the historical
+`{stateDir}/...` values (this code runs the agent's own Telegram, so an unchanged primary is
+the non-negotiable invariant) — plus that a `subDir` adapter namespaces all four files and
+shares no path with the primary. The existing Telegram suites (71 tests across 5 files) pass
+unchanged as the regression guard. `tsc --noEmit` clean. The wiring that consumes these
+(the agent-message recipient handler + `sendAgentMessage`) lands in the follow-up PR.

package/upgrades/side-effects/feedback-factory-dryrun.md

@@ -0,0 +1,93 @@
+# Side-effects review — feedback-factory dry-run/compare + ReadOnlyShadowStore
+
+Spec: `docs/specs/feedback-factory-migration.md` (converged v2, approved 2026-05-26).
+Increment: the Phase-1/3 dry-run/compare machinery — `ReadOnlyShadowStore` (write-guard),
+`parity.ts` (invariant comparator), `dryRunCompare.ts` (runner + `ParitySource` seam).
+Purely additive: three new `src/feedback-factory/` files + three new unit test files; zero
+edits to existing code.
+
+## What this ships
+
+The mechanism that lets the ported Instar processor run **read-only against Portal's live
+canonical DB** and have its decisions compared to Portal's, with Portal remaining the sole
+writer through cutover (the one-shared-DB precondition that prevents split-brain). Three
+order-independent invariants per spec §2.3:
+
+1. **Fingerprint (per cluster)** — `computeFingerprint(cluster.type, cluster.title)` recomputed
+   over Portal's live clusters and diffed against the stored value. Pure, no replay, fully
+   order-independent. The highest-signal gate (catches byte-level Python↔JS divergence on real
+   production titles). Faithful to the reference's `cmd_backfill_fingerprints` (:256).
+2. **Terminal status** — keyed by fingerprint, not raw slug clusterId.
+3. **Recurrence/cycling count** — keyed by fingerprint.
+
+`result.divergent === true` is the structural signal that blocks Phase 4 cutover.
+
+## Over-block / under-block
+
+- **ReadOnlyShadowStore**: deliberately over-strict on writes — every one of the 6 mutating
+  methods throws. This is the correct direction: the failure we are guarding against
+  (corrupting Portal's curated bug history) is catastrophic and irreversible, while a false
+  block is a loud, immediate, recoverable error at the seam. No under-block path exists: there
+  is no method that silently no-ops a write.
+- **Fingerprint comparator**: skips clusters with no stored fingerprint (pre-backfill rows) —
+  prevents the false positive of flagging "divergence" against an empty string. It does NOT
+  skip any cluster that *has* a fingerprint, so it cannot under-block a real divergence.
+- **Outcome comparator (status/recurrence)**: treats a fingerprint present on only one side as
+  a divergence (`missing-instar` / `missing-portal`) rather than ignoring it — chosen to
+  surface grouping disagreements rather than hide them. This is the conservative (over-surface)
+  direction, appropriate for a cutover gate.
+
+## Level-of-abstraction fit
+
+- The comparator is **pure** (no I/O) and lives beside the other pure processor logic in
+  `processor/`. The runner owns the I/O (read source + JSONL append) and lives in a new
+  `dryrun/` directory — matching the existing separation (pure decision logic vs. composition).
+- `ParitySource` is the single read-only seam. The Prisma-over-Postgres adapter is the only
+  production implementation and is intentionally NOT built here (credentials-gated — see
+  Deferrals). The interface is the contract Dawn confirmed her adapter slots into.
+- `ReadOnlyShadowStore` wraps the existing `FeedbackStore` interface rather than inventing a
+  new one — it is a faithful decorator, so any present or future `FeedbackStore` consumer can
+  be made read-only without changes.
+
+## Signal-vs-authority compliance
+
+This increment is **signal-only**, not authority. It produces a verdict (`divergent`) and a
+JSONL audit trail; it takes no action — no cutover, no migration, no messaging, no mutation.
+The authority to advance Phase 4 remains with the operator + Dawn's line-by-line review. This
+matches the Instar separation: a brittle/automated comparator detects and emits; a
+higher-context human/gate decides. The runner cannot itself flip any switch.
+
+## Interactions
+
+- **Portal's canonical DB**: read-only by construction (ShadowStore guard + read-only
+  `ParitySource`). The runner only ever reads + appends to a *local* JSONL log. No write path
+  to Portal exists in this code.
+- **The ported processor (`process.ts` → `processUnprocessed`)**: the runner does NOT call it
+  (it would write). The comparator uses only the pure functions. The ShadowStore guard is the
+  backstop if a future caller wires `processUnprocessed` against a shadow store by mistake —
+  it throws at the first write instead of corrupting data.
+- **Existing feedback-factory tests**: unaffected (additive change; full unit dir green —
+  128 tests including the 21 new).
+- **No config, hook, route, template, or migration surface is touched** — so no Migration
+  Parity / Agent Awareness obligation is triggered by *this* increment (those land with the
+  receiver/dispatch wiring + observability increments, which DO touch routes/templates).
+
+## Rollback cost
+
+Trivial and isolated. Three new `src/` files + three new test files, no edits elsewhere,
+nothing wired into server startup or routes yet. Reverting the commit removes the files with
+zero downstream impact — nothing imports them in production paths. No data migration, no
+state, no deployed surface.
+
+## Deferrals
+
+- The **Prisma-over-Postgres `ParitySource` adapter** is not built in this increment.
+  Reason: it requires Dawn's read-only Postgres credentials + `prisma db pull` against the live
+  schema (a genuine external dependency, not avoidable work). The `ParitySource` interface +
+  `InMemoryParitySource` make the runner fully buildable and testable now; the live adapter
+  slots in behind the interface the moment credentials land. <!-- tracked: topic-12476 -->
+- **Auto-derivation of Instar's status/recurrence outcomes (invariants 2 & 3) from a
+  point-in-time read** is not built. Reason: a faithful replay needs window-START cluster state,
+  which a current-state read cannot supply; the outcomes must come from a snapshot / full-history
+  export. The comparator + runner accept those outcome lists as inputs today, so the path is
+  complete pending the data source. <!-- tracked: topic-12476 -->