instar 0.23.12 → 0.23.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.23.12",
+  "version": "0.23.13",
   "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-03-19T05:57:28.344Z",
-  "instarVersion": "0.23.12",
+  "generatedAt": "2026-03-19T21:30:47.368Z",
+  "instarVersion": "0.23.13",
   "entryCount": 170,
   "entries": {
     "hook:session-start": {
@@ -311,7 +311,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -319,7 +319,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -327,7 +327,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -335,7 +335,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -343,7 +343,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -351,7 +351,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -359,7 +359,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -367,7 +367,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -375,7 +375,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -383,7 +383,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -391,7 +391,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -399,7 +399,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -407,7 +407,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -415,7 +415,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -423,7 +423,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -431,7 +431,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -439,7 +439,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -447,7 +447,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -455,7 +455,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -463,7 +463,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -471,7 +471,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -479,7 +479,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -487,7 +487,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -495,7 +495,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -503,7 +503,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -511,7 +511,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -519,7 +519,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -527,7 +527,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -535,7 +535,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -543,7 +543,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -551,7 +551,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -559,7 +559,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -567,7 +567,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -575,7 +575,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -583,7 +583,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -591,7 +591,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -599,7 +599,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -607,7 +607,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -615,7 +615,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -623,7 +623,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -631,7 +631,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -639,7 +639,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -647,7 +647,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -663,7 +663,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "3194d71cd195d16eae57176c21f4fa98abfe0eb8344ea985369aed42cf207ef7",
+      "contentHash": "b422a1d7c8b9152d4aeaff02c086c8722415bb15e50768bdf7666db094d3f7b2",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1335,7 +1335,7 @@
       "type": "subsystem",
       "domain": "communication",
       "sourcePath": "src/lifeline/TelegramLifeline.ts",
-      "contentHash": "e87a82c62a5cba682d6d78ed023f684d559b88ccef7420a070d0ea55c82053a1",
+      "contentHash": "58649005f188f7fe655223a7cf4e9e83998ab7af72e5bc1bc94a97c42bfe553f",
       "since": "2025-01-01"
     },
     "subsystem:orphan-process-reaper": {

package/upgrades/0.23.10.md

@@ -0,0 +1,19 @@
+# v0.23.10 — Self-Recovery & ESM Compatibility
+
+## What Changed
+
+Two stability improvements that make agents more resilient:
+
+**Zombie session detection**: Sessions that finish their work but sit idle at the Claude prompt now get automatically killed after 15 minutes. Previously, these zombie sessions would accumulate until the max session limit was reached, blocking health checks, server restarts, and eventually crashing the lifeline process entirely.
+
+**ESM project compatibility**: The boot wrapper now correctly uses `.cjs` extension for projects with `"type": "module"` in their package.json. Previously, the boot wrapper was always generated as `.js`, which Node treated as ESM in module-type projects, causing `require is not defined` crashes. The plist self-heal also now recognizes `.cjs` boot wrappers as valid, preventing unnecessary regeneration.
+
+## What to Tell Your User
+
+Your agent is now better at recovering from stuck states on its own. If sessions were piling up and causing your agent to become unresponsive, that should stop happening. If you had trouble with the agent crashing on startup in a project that uses ES modules, that's also fixed now.
+
+## Summary of New Capabilities
+
+- Idle prompt detection kills zombie Claude sessions after 15 minutes of inactivity
+- Boot wrapper uses .cjs extension for ESM-compatible projects
+- Plist self-heal accepts both .js and .cjs boot wrappers

package/upgrades/0.23.11.md

@@ -0,0 +1,21 @@
+# v0.23.11 — Deeper Native Module Self-Recovery
+
+## What Changed
+
+The pre-flight SQLite binding check now exercises the native layer more thoroughly. Previously it only tested that the module could be imported, but some version mismatches cause runtime crashes (C++ mutex errors) rather than import failures. Now the check opens an in-memory database and runs a pragma, catching these deeper incompatibilities before the server starts.
+
+The rebuild fallback path is also now shadow-install-aware — it tries rebuilding in the shadow install's node_modules before falling back to global. This ensures agents running via shadow installs (the standard deployment) get their native modules rebuilt correctly.
+
+Combined with the v0.23.8 zombie session reaper and v0.23.10 ESM boot wrapper fix, agents should now self-recover from the most common crash patterns without manual intervention.
+
+## What to Tell Your User
+
+- **Self-healing native modules**: "If your Node.js version changes, I can now detect and fix the incompatibility automatically on startup. No more manual rebuilds needed."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Deeper native binding check | Automatic on server startup |
+| Shadow-install-aware rebuild | Automatic fallback during rebuild |
+| Mutex crash detection | Automatic — catches previously undetectable crashes |

package/upgrades/0.23.13.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a critical gap in the Telegram lifeline's API call handling. The lifeline's `apiCall` method had no handling for HTTP 429 (Too Many Requests) responses from the Telegram API. When Telegram rate-limited the bot, the lifeline threw a generic error, but callers kept sending more messages — each hitting the rate limit again, generating 13,700+ error lines in stderr and creating a cascade of failed requests.
+
+The fix adds the same retry_after-aware handling that TelegramAdapter already has:
+- Parse the `retry_after` field from Telegram's 429 response
+- Wait the specified duration before retrying
+- Retry up to 3 times with proper backoff
+- Throw a clear error after max retries instead of cascading
+
+This was the root cause of massive stderr spam during message bursts (e.g., server restart notifications, queue ack confirmations).
+
+## What to Tell Your User
+
+- **Rate limit handling**: "My emergency communication channel is now smarter about Telegram's rate limits. If Telegram asks me to slow down, I'll wait and retry instead of flooding error logs. This means more reliable message delivery during busy periods."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Lifeline 429 rate-limit handling | Automatic — retries with backoff on Telegram rate limits |

package/upgrades/NEXT.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Dashboard link auto-refresh**: New `POST /telegram/dashboard-refresh` endpoint triggers the existing dashboard URL edit-in-place logic. Paired with a new `dashboard-link-refresh` job that runs every 5 minutes (no LLM, just a curl). If the tunnel URL hasn't changed, Telegram silently skips the edit.
+- **Lifeline 429 handling**: The `apiCall` helper in lifeline now recognizes HTTP 429 (rate limit) responses and backs off automatically instead of treating them as hard failures.
+- **Telegraph confirmation gate**: Publishing to Telegraph now requires explicit confirmation, and each page gets its own access token for tracking.
+- **CI pipeline reliability**: Publish workflow now derives the next version from npm (not package.json), eliminating version collision races. CI gate uses the stable test suite, matching the main CI workflow.
+
+## What to Tell Your User
+
+- **"Your dashboard link stays fresh now"**: The pinned dashboard message in Telegram auto-updates every 5 minutes. If the tunnel URL changes (like after a restart), the link fixes itself — no need to ask for a new one.
+- **"Publishing is more reliable"**: Telegraph publishing now asks for confirmation before going live, and the deploy pipeline has been hardened against the version collision issues that were causing failed releases.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Dashboard link refresh | Automatic via job, or `POST /telegram/dashboard-refresh` |
+| Telegraph confirmation gate | Automatic — prompts before publishing |
+| Rate-limit backoff | Automatic in lifeline API calls |