instar 0.28.93 → 0.28.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.93",
+  "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:17:21.147Z",
-  "instarVersion": "0.28.93",
+  "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.94.md

@@ -0,0 +1,60 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+### Project-scope Phase 1b PR 2 — drift cache + cost ledger
+
+Second PR of project-scope Phase 1b. Adds two persistent-state
+primitives the drift checker has been operating without since v0.28.93:
+
+- **Verdict cache** — `ProjectDriftCheckerCache`. 24-hour TTL,
+  mtime-fast-path before computing the cache key, disk-backed
+  snapshot at `.instar/drift-verdict-cache.json` so the cache
+  survives restarts. When file mtimes match the recorded entry and
+  template version + model id are unchanged, the prior verdict is
+  returned without re-hashing or calling the model. When content
+  changes, the cache key shifts and the LLM is consulted again.
+
+- **Cost ledger** — `DriftSpendLedger`. Daily-rotated append-only
+  JSONL at `.instar/drift-spend-YYYY-MM-DD.jsonl` enforcing the
+  spec's $1/day per-agent spend cap. Strict-greater-than boundary
+  (equal-to-cap is allowed; one cent over is not). Pre-reservation
+  rows are append-only and reconciled with the actual spend after
+  the call. Lock-coordinated on `.instar/local/drift-spend.lock`
+  via proper-lockfile (same convention as AgentRegistry and
+  SharedStateLedger). 30-day retention; older files are pruned
+  through `SafeFsExecutor.safeRmSync`.
+
+Both are optional fields on `ProjectDriftChecker`'s config. The
+v0.28.93 contract — neither cache nor ledger — is preserved
+exactly when neither is passed. Wiring into the round runner
+(consumer) ships in the next PR.
+
+## What to Tell Your User
+
+- **Drift checks won't burn budget**: I now have a daily spending cap
+  on the model calls that power drift checks, plus a cache so I don't
+  pay for the same check twice. You don't have to do anything; it just
+  works. If I ever hit the daily limit, I escalate to you rather than
+  silently overspending.
+
+## Summary of New Capabilities
+
+- `ProjectDriftCheckerCache` class — sha256-keyed verdict cache with
+  24-hour TTL, mtime fast-path, and disk-backed snapshot at
+  `.instar/drift-verdict-cache.json`. Avoids redundant LLM calls when
+  spec + referenced files are unchanged.
+- `DriftSpendLedger` class — daily-rotated JSONL cost ledger
+  (`.instar/drift-spend-YYYY-MM-DD.jsonl`) enforcing a $1-per-agent
+  per-UTC-day spend cap. Lock-coordinated via proper-lockfile. Exposes
+  `reserve()`, `reconcile()`, `spentToday()`, `pruneOlderThan()`,
+  and the `OverBudgetError` thrown class.
+- `ProjectDriftChecker` config now accepts optional `cache`, `ledger`,
+  and `estimatedCostPerCallUsd` fields. Backwards-compatible: passing
+  neither preserves the v0.28.93 contract.

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.