instar 0.28.94 → 0.28.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.94",
+  "version": "0.28.95",
   "description": "Persistent autonomy infrastructure for AI agents",
   "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-12T03:32:09.889Z",
-  "instarVersion": "0.28.94",
+  "generatedAt": "2026-05-12T03:45:48.737Z",
+  "instarVersion": "0.28.95",
   "entryCount": 188,
   "entries": {
     "hook:session-start": {
@@ -392,7 +392,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -400,7 +400,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -408,7 +408,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -416,7 +416,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -424,7 +424,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -432,7 +432,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -440,7 +440,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -448,7 +448,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -456,7 +456,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -464,7 +464,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -472,7 +472,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -480,7 +480,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -488,7 +488,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -496,7 +496,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -504,7 +504,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -512,7 +512,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -520,7 +520,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -528,7 +528,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -536,7 +536,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -544,7 +544,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -552,7 +552,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -560,7 +560,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -568,7 +568,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -576,7 +576,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -584,7 +584,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -592,7 +592,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -600,7 +600,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -608,7 +608,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -616,7 +616,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -624,7 +624,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -632,7 +632,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -640,7 +640,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -648,7 +648,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -656,7 +656,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -664,7 +664,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -672,7 +672,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -680,7 +680,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -688,7 +688,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -696,7 +696,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -704,7 +704,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -712,7 +712,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -720,7 +720,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -728,7 +728,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -744,7 +744,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "690932aef39fa834ed8afe75b5703469755a7fcfa80ef764518a9c26026ef8b2",
+      "contentHash": "9df68db931c7a6d25a2696c15783e6f3729e047cf4f625a56abb39fe40f4a685",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/0.28.95.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- 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
+
+PromiseBeacon's heartbeat messages used to give the user no idea what was being tracked ("still working — snapshot unchanged since last beat") and ran forever even when nothing was changing, producing extended runs of context-free hourglass spam on Telegram. This release fixes three things:
+
+- Every heartbeat now appends a `re: <promise excerpt>` suffix so the user can see which watched promise it's about.
+- Beacons auto-pause after a run of consecutive unchanged-snapshot heartbeats (default 12 cycles, ≈2h at 10-min cadence). When the threshold is hit, the beacon emits one final "auto-paused after long quiet — reply 'keep watching' on this topic to resume" message and stops firing. Status stays `pending` — this is non-terminal suppression, not delivery or violation. New optional Commitment fields: `beaconPaused`, `beaconPausedReason`, `beaconPausedAt`, `beaconAutoPauseAfterUnchanged`, `consecutiveUnchanged`.
+- New endpoint `POST /commitments/:id/resume` clears the paused flags and resets the counter; PromiseBeacon re-arms on the `resumed` event. A literal "keep watching" detector in the Telegram inbound path calls this endpoint for any paused beacons on the originating topic and now reports per-call success ("⏳ resumed N watchers", "⏳ resumed X of Y watchers", or "⚠️ couldn't resume — try again").
+
+Honors PROMISE-BEACON-SPEC.md line 161 ("suggest, don't auto-close"): this is auto-pause, not auto-delivery — `status` stays `pending` and the beacon can be resumed at any time.
+
+## What to Tell Your User
+
+- "I'll now tell you what I'm tracking in every progress update, instead of just saying 'still working'."
+- "If a watcher goes silent for too long with no change, I'll send one last note and stop pestering you. Reply 'keep watching' on that topic and I'll pick it back up."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Heartbeat shows which promise is being tracked | automatic |
+| Beacon auto-pauses after extended silence | automatic (default 12 unchanged cycles) |
+| Resume a paused beacon | `POST /commitments/:id/resume` or reply "keep watching" on the topic |
+
+## Evidence
+
+<!-- REQUIRED if this release claims to fix a bug. -->
+<!-- Unit tests passing is NOT evidence. Provide ONE of: -->
+<!--   (a) Reproduction steps + observed before/after on a live system. -->
+<!--       Include log excerpts, observed command output, or behavior -->
+<!--       description. Make it specific enough that a future reader can -->
+<!--       re-run it and see the same thing. -->
+<!--   (b) "Not reproducible in dev — [concrete reason]" if the failure -->
+<!--       mode truly can't be exercised locally (race conditions, -->
+<!--       event-driven paths requiring external signals, etc). -->
+<!--                                                                 -->
+<!-- If this release doesn't claim a bug fix (pure feature / refactor), -->
+<!-- leave this section blank or delete it — it's only enforced when -->
+<!-- "What Changed" describes a fix. -->
+
+**Reproduction (live):** Telegram topic 9210 ("threadline dev") on the echo agent. Three commitments (CMT-381, CMT-382, CMT-383) were detected by CommitmentSentinel after three separate threadline-send actions over ~28 minutes; each one became a beacon-enabled commitment with `agentResponse` "Sent threadline message to <recipient>, awaiting reply." All three fired heartbeats independently on the default 10-min cadence. tmux output was idle, so every heartbeat hit the unchanged-snapshot branch and rotated through `TEMPLATED_VARIANTS` then `AT_RISK_VARIANTS`, producing ~30+ context-free hourglass messages between 18:35 and 19:55. None of the messages identified which commitment they were about. Withdrawn via `POST /commitments/:id/withdraw` to stop the spam.
+
+**Fix verification (unit):** New test file `tests/unit/PromiseBeacon-ux-fixes.test.ts` covers the three failure modes the live reproduction exposed:
+- `appends a "re: <promise excerpt>" suffix to every templated heartbeat` — passes; the heartbeat text contains the truncated `agentResponse`.
+- `auto-pauses after N consecutive unchanged-snapshot heartbeats and emits a final resume hint` — passes; with threshold=3, the 4th unchanged-snapshot heartbeat emits the auto-pause message and subsequent fires emit nothing.
+- `a resumed beacon re-arms via the resumed event handler` — passes; calling `tracker.resume(id)` re-arms PromiseBeacon's timer via the new `resumed` event.
+
+**Fix verification (live, post-merge):** will be performed by enabling beaconEnabled on a fresh test commitment on a quiet topic and confirming (a) the heartbeat text contains the promise excerpt, (b) the beacon auto-pauses after the configured threshold, (c) replying "keep watching" on the topic resumes it. Reported in the release notes for the next version after merge.

package/upgrades/side-effects/promise-beacon-ux-fixes.md

@@ -0,0 +1,146 @@
+<!--
+  Side-Effects Review — PromiseBeacon UX fixes
+  Phase 4 artifact for /instar-dev pass on echo/promise-beacon-ux-fixes.
+-->
+
+# Side-Effects Review — PromiseBeacon UX fixes
+
+**Version / slug:** `promise-beacon-ux-fixes`
+**Date:** `2026-05-12`
+**Author:** `echo`
+**Second-pass reviewer:** `pending`
+
+## Summary of the change
+
+PromiseBeacon's heartbeat templates ("still working — snapshot unchanged since last beat") gave the user no context about which promise was being watched, and heartbeats ran forever even when nothing was changing. Three commitments stacked on the same Telegram topic produced ~30+ context-free "no observable progress" messages over an evening with no way to stop them short of opening the dashboard. This change:
+
+1. Includes a truncated form of the promise text in every heartbeat so the user can see what's being tracked.
+2. Adds an auto-pause: after N consecutive unchanged-snapshot heartbeats (default N=12, ~2h at 10-min cadence), the beacon emits one final "auto-paused — reply 'keep watching' to resume" message and stops firing. Non-terminal; status stays `pending`.
+3. Adds `POST /commitments/:id/resume` and a literal "keep watching" detector in the Telegram inbound path that calls it for any paused beacon on the originating topic.
+
+Files touched:
+- `src/monitoring/CommitmentTracker.ts` — new optional schema fields (`beaconPaused`, `beaconPausedReason`, `beaconPausedAt`, `beaconAutoPauseAfterUnchanged`, `consecutiveUnchanged`); `resume(id)` method.
+- `src/monitoring/PromiseBeacon.ts` — promise-text excerpt in heartbeat composition; consecutive-unchanged counter; auto-pause flow; paused-state gate in `fire` and `schedule`.
+- `src/server/routes.ts` — `POST /commitments/:id/resume`.
+- `src/commands/server.ts` — extend `telegram.onMessageLogged` with literal "keep watching" detector that calls the resume endpoint.
+- Tests: new files under `tests/unit/` and `tests/integration/`.
+
+Decision points the change interacts with:
+- PromiseBeacon's heartbeat composition path (template selection, LLM call gating).
+- PromiseBeacon's scheduling path (timer arming, suppression checks).
+- Commitment lifecycle (new non-terminal state combination: `pending + beaconPaused`).
+- Telegram inbound path (new literal-match detector that triggers a server-side action).
+
+## Decision-point inventory
+
+- `PromiseBeacon.fire` heartbeat-template selection — **modify** — adds promise-text prefix to every template; adds auto-pause branch.
+- `PromiseBeacon.schedule` arming guard — **modify** — skips arming when `beaconPaused`.
+- `CommitmentTracker.resume(id)` — **add** — non-terminal flag clear + counter reset.
+- `POST /commitments/:id/resume` — **add** — API entrypoint for resume.
+- Telegram `onMessageLogged` literal-match — **add** — produces resume signal that calls the new endpoint.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The auto-pause has no block/allow surface — it stops outbound heartbeats from this agent, doesn't reject inputs. Strictly speaking it could "over-stop" if the user genuinely wanted updates on a long-running silent process. Mitigation: the final pause message tells the user how to resume; the resume path itself is idempotent.
+
+The "keep watching" detector uses literal substring match (`/keep[\s-]?watching/i`). False positives:
+- A user typing "I want to keep watching the build logs" while not intending to resume a beacon. Cost: a paused beacon resumes; user gets one more heartbeat and can re-pause by ignoring it (it'll auto-pause again after N cycles) or by withdrawing the commitment.
+- Whichever paused beacons exist on the topic all resume simultaneously, not selectively. Cost: minor; same recovery path.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- The literal detector won't match paraphrases ("keep an eye on it", "stay on it", "don't give up"). Intentional: per signal-vs-authority, a brittle detector with blocking authority is forbidden. The detector is structurally simple by design. The final auto-pause message tells the user the exact phrase to use.
+- If the user wants to resume one specific paused beacon out of many, this implementation resumes all paused beacons on the topic. A future iteration could accept "keep watching <commitment-id>".
+- The auto-pause counter is per-commitment; multiple beacons on the same topic still produce N heartbeats each before pausing. The total heartbeat volume on a topic is not bounded by this change — only the per-beacon volume.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The auto-pause counter belongs in PromiseBeacon — it's the only thing that knows the snapshot-hash and the consecutive-unchanged history. Putting it elsewhere would require lifting that state up.
+
+The resume endpoint mirrors the existing `/deliver` and `/withdraw` endpoints on `/commitments/:id` — it's at the same layer as those, which is correct.
+
+The Telegram "keep watching" detector lives in `server.ts`'s existing `onMessageLogged` extension because that's where every inbound message is observed once already (for PresenceProxy + TopicMemory). Adding a third small hook there is cheaper than building a new fan-out point. The detector itself is brittle by design (regex), but it only produces a signal — the resume endpoint is the authority for whether to act.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] No — the brittle parts (counter, regex) hold no blocking authority over messages or behavior. The counter triggers a structural state transition (pause); the regex triggers a structural state transition (resume). Neither blocks or modifies an inbound user message.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+The auto-pause counter is mechanics, not judgment (signal-vs-authority §"When this principle does NOT apply" — "Idempotency keys and dedup at the transport layer... not a judgment call — it's mechanics"). It counts identical snapshot hashes; that's a structural fact.
+
+The "keep watching" detector is a brittle regex that calls a structural API. The API itself is symmetric with `/withdraw` — idempotent, no judgment, just toggles state. A false positive resumes a paused beacon, which costs one more heartbeat and re-pauses if still idle. No message is blocked, filtered, or rejected; no agent behavior is constrained beyond the toggle.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The auto-pause check sits inside `PromiseBeacon.fire` after the existing suppression/ownership/quiet-hours checks. It runs only when those passed and templated-unchanged branch was taken. It does not shadow `beaconSuppressed` (which is for boot-cap / spend-cap, distinct semantics) — `beaconPaused` is a new orthogonal non-terminal flag with `resolved-by` `/resume` (not by the existing suppression-clear path).
+- **Double-fire:** The "keep watching" detector lives inside the same `onMessageLogged` callback chain that already feeds PresenceProxy. Calling the resume endpoint enqueues a single mutate operation per matched commitment; no duplicate timers are created because `schedule()` clears any existing timer before arming.
+- **Races:** Concurrent withdraw + resume on the same commitment: the existing `mutate(id, fn)` queue serializes writes; resume is rejected by `mutate` if the commitment is already terminal (withdrawn).
+- **Feedback loops:** Resume → fire → snapshot unchanged → counter increments → re-pauses after N cycles. This is the intended steady state when a watched task is genuinely idle; the user can resume again. There is no autonomous loop that re-resumes itself.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** No. PromiseBeacon state is per-agent.
+- **Other users of the install base:** Yes — every instar agent ships with PromiseBeacon. After this change, every install gets the new heartbeat text format, the auto-pause behavior, and the Telegram resume detector. The new endpoint is additive (no behavior change for callers that don't use it).
+- **External systems:** The Telegram messages emitted change format (now include promise text). Anyone tooling against the exact "still working — snapshot unchanged since last beat" string would break; we know of no such consumer outside test fixtures.
+- **Persistent state:** Three new optional fields on the Commitment schema. Forward-compatible: missing fields default to "not paused, counter at zero, threshold default 12." Existing commitments load cleanly without migration.
+- **Timing / runtime:** The 12-cycle threshold at default 10-min cadence yields ~2-hour silence before auto-pause. Tunable per-commitment via `beaconAutoPauseAfterUnchanged`. Quiet hours and boot-cap interactions unchanged.
+
+---
+
+## 7. Rollback cost
+
+Pure code change. Schema additions are optional. Revert the commit and ship the next patch — existing agents will continue to use whatever schema they had; new fields are simply ignored. No data migration. No agent state repair. Users see the previous (broken) UX again until a roll-forward fix; not a regression in correctness, only in UX.
+
+---
+
+## Conclusion
+
+The change addresses the user-reported spam directly: heartbeats now say what they're tracking, beacons stop themselves after extended silence, and the user can resume them from Telegram. The signal-vs-authority principle is honored: the brittle parts (counter, regex) only trigger structural state transitions, never block or judge messages. Schema additions are backward-compatible and rollback is a code revert. Clear to ship after Phase 5 second-pass review (required: change touches outbound messaging composition and commitment lifecycle).
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** echo (Phase-5 independent pass)
+**Independent read of the artifact: concern → resolved**
+
+Concerns raised, with resolutions:
+
+- **Misleading resume ack on failure.** In `src/commands/server.ts` the "keep watching" handler `await`ed `fetch` to `/commitments/:id/resume` inside a `try`/`catch` that only `console.warn`'d on throw, never checked the HTTP response, and then unconditionally posted `⏳ resumed N watcher(s) on this topic.` to the user. A 404 (not paused / terminal), a 5xx, or a thrown fetch (server restart, partial outage) would all result in the user being told the beacon resumed when it did not.
+  **Fix applied:** the handler now inspects `response.ok` per call, counts successes, and tailors the ack: `⏳ resumed N watcher(s)` on full success, `⏳ resumed X of Y watchers — N didn't resume` on partial success, `⚠️ couldn't resume the watcher(s) on this topic — try again or open the dashboard` on total failure or fetch throw.
+- **Cold-mirror write of `consecutiveUnchanged` had no consumer.** The cold mirror was written every fire but never consulted by `fire()` or the threshold check (which uses `hot.consecutiveUnchanged`). Write amplification on the CAS queue with no benefit and a footgun for a future reader.
+  **Fix applied:** dropped the per-cycle cold write. The field is now written only at the pause boundary (with a comment in `autoPause()`) and on resume (set to 0). The schema field carries a docstring marking it as a non-authoritative observability mirror — hot-state is authoritative during a live run.
+
+Lower-priority observations (not blocking):
+- Over-match on "keep watching": "I'll keep watching the build logs", "good — keep watching for the alert" both resume any paused beacons on the topic. Cost is bounded (one more heartbeat, re-pauses) and matches the artifact's analysis. Acceptable.
+- `beaconSuppressed` × `beaconPaused` interaction: traced through — `fire()` early-exits on `beaconSuppressed` before reaching the auto-pause branch, so the two flags are mutually exclusive within a single fire. `schedule()` correctly rejects when either is set. No race.
+- Backwards-compat for existing commitments: `hot.consecutiveUnchanged` initializes to 0 in `loadHotState`'s defaults block (not undefined/NaN), and `beaconAutoPauseAfterUnchanged ?? defaultAutoPauseAfterUnchanged` falls back cleanly. Confirmed safe.
+- Spec line 161 ("suggest, don't auto-close"): this change is auto-PAUSE (`status` stays `pending`, resumable, no delivery semantics). Does not violate.
+
+---
+
+## Evidence pointers
+
+- Originating user report: Telegram topic 9429 ("progress update bug"), 2026-05-12.
+- Withdrawn runaway commitments providing the live reproduction: CMT-381, CMT-382, CMT-383 on topic 9210.
+- Spec extended (not violated): docs/specs/PROMISE-BEACON-SPEC.md (auto-pause is a new non-terminal suppression; auto-close-on-reply explicitly NOT added per spec line 161).