instar 0.23.11 → 0.23.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.23.11",
+  "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-19T03:16:40.994Z",
-  "instarVersion": "0.23.11",
+  "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.12.md

@@ -0,0 +1,30 @@
+# 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
+
+Added sleep/wake recovery infrastructure for macOS environments. When a machine sleeps and wakes, SQLite WAL locks can go stale and tunnel connections drop silently. This release adds:
+
+- **WAL checkpoint methods** on TopicMemory and SemanticMemory — `checkpoint()` flushes stale WAL locks after macOS sleep/wake, preventing "database is locked" errors that previously required manual restart.
+- **TunnelManager recovery** — `forceStop()` cleanly tears down zombie tunnel processes, and `enableAutoReconnect()` provides exponential-backoff reconnection when tunnels drop during sleep/wake cycles.
+- **TelegramAdapter resilience** — catches silent connection failures from the Telegram API that occur after network state changes, with automatic retry logic.
+
+These changes target the most common failure mode for agents running on developer laptops: machine sleep causing cascading failures across memory, tunnels, and messaging.
+
+## What to Tell Your User
+
+- **Sleep/wake recovery**: "If your machine goes to sleep and wakes back up, I can now recover automatically — my database connections, tunnels, and messaging all reconnect without needing a restart."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| WAL checkpoint after sleep/wake | Automatic — called by StallTriageNurse on stall detection |
+| Tunnel auto-reconnect | Automatic with exponential backoff |
+| Tunnel force-stop | Available via TunnelManager API for manual recovery |
+| Telegram silent-failure catch | Automatic — adapter retries on connection loss |

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

@@ -1,35 +1,23 @@
 # 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
 
-<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
-<!-- Write this for the AGENT — they need to understand the system deeply. -->
+- **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
 
-<!-- Write talking points the agent should relay to their user. -->
-<!-- This should be warm, conversational, user-facing — not a changelog. -->
-<!-- Focus on what THEY can now do, not internal plumbing. -->
-<!--                                                                    -->
-<!-- PROHIBITED in this section (will fail validation):                 -->
-<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
-<!--   Inline code backtick references like silentReject: false        -->
-<!--   Fenced code blocks                                              -->
-<!--   Instructions to edit files or run commands                      -->
-<!--                                                                    -->
-<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
-<!-- The agent relays this to their user — keep it human.              -->
-
-- **[Feature name]**: "[Brief, friendly description of what this means for the 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 |
 |-----------|-----------|
-| [Capability] | [Endpoint, command, or "automatic"] |
+| 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 |