@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.20.0.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — v0.20.0
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Drop Zone — Dashboard Paste Input
+
+A new "Drop Zone" tab in the dashboard lets users send large text content (code, logs, configs, specs) directly to an active agent session, bypassing Telegram's 4096-character limit.
+
+**How it works:**
+1. Open the dashboard (local or via tunnel)
+2. Click the "Drop Zone" tab
+3. Paste content, optionally add a label, pick a target session
+4. Hit Send — content is delivered to the session as a file-reference notification
+
+**Key design decisions:**
+- **File-based delivery**: Content is written to `.instar/paste/` and the session receives a short notification pointing to the file. Content is never inlined in the notification (isolation boundary).
+- **Prompt injection defense**: Notifications include explicit framing telling the agent to treat paste content as data, not instructions. Routed through InputGuard.
+- **Three delivery states**: `written` → `notified` → `acknowledged`, with WebSocket events for real-time dashboard updates.
+- **Security hardened**: UUID-only filenames (no label in paths), 0600 permissions, rate limiting (10/min), 10MB per-paste cap, 500MB directory cap, programmatic gitignore enforcement.
+
+**API endpoints:**
+- `POST /pastes` — Create a paste
+- `GET /pastes` — List pastes (metadata only)
+- `GET /pastes/:id` — Get paste with content
+- `DELETE /pastes/:id` — Delete a paste
+
+**Configuration (optional, in config.json):**
+- `pasteMaxSizeMB` — Max paste size in MB (default: 10)
+- `pasteRetentionDays` — Days to keep paste files (default: 7)
+
+### Telegram Truncation Detection
+
+Server-side middleware in the Telegram message ingestion path detects when a user's message appears truncated:
+- Messages near the 4096-char limit ending mid-word or with unclosed delimiters
+- Rapid multi-part messages from the same user (manual splitting)
+- Structurally incomplete code/log content
+
+When detected, the agent receives a system hint suggesting the Drop Zone. One nudge per topic per 30 minutes to avoid nagging.
+
+## What to Tell Your User
+
+Your dashboard has a new tab called "Drop Zone" — it's for sending long content (code, logs, error outputs, configs) that won't fit in a Telegram message. Just paste it and hit send. If your agent notices you're fighting Telegram's character limit, it'll suggest using the Drop Zone automatically.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Drop Zone paste input | Dashboard → Drop Zone tab. Paste content, hit Send. |
+| Paste API | `POST /pastes` with `{content, label?, targetSession?}` |
+| Paste history | Dashboard shows recent pastes with delivery status |
+| Truncation detection | Automatic — agent suggests Drop Zone when Telegram messages look truncated |
+| Paste cleanup | Automatic — files expire after 7 days (configurable) |

package/upgrades/0.21.1.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — v0.21.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Server Robustness — Five Self-Healing Improvements
+
+This release addresses a class of failure modes where agents become permanently unrecoverable after a server crash, particularly during auto-updates combined with Node.js version changes.
+
+**1. `/restart` intercepted by lifeline when server is down**
+
+Previously, typing `/restart` in Telegram when the server was down would queue the message — creating a dead man's switch where the recovery command required the thing that was broken. Now the lifeline intercepts `/restart` when the server is unhealthy and routes it to the supervisor's restart logic directly, bypassing the server entirely.
+
+**2. Planned-exit marker TTL (10 minutes)**
+
+Auto-updates write a `planned-exit-marker.json` so the supervisor suppresses false "server down" alerts during expected restarts. Previously this marker persisted forever. If the restart failed, the marker caused the supervisor to keep entering maintenance mode on every retry attempt. The marker now expires after 10 minutes and is auto-cleaned.
+
+**3. Slow retry mode — agents never truly give up**
+
+After the circuit breaker exhausts its fast retries (3x at 30-minute intervals), it previously gave up permanently — requiring manual intervention. Now it enters a slow-retry mode that attempts a restart every 2 hours indefinitely. Transient issues (Node version changes, disk full, port conflicts) often resolve themselves. `/lifeline reset` still provides immediate retry.
+
+**4. Plist self-healing at lifeline startup**
+
+On every lifeline startup (macOS), the system now validates that the launchd plist uses the boot wrapper pattern (`instar-boot.sh`) instead of a hardcoded Node.js binary path. If an old-style plist is detected, it auto-regenerates both the boot wrapper script and the plist via the standard `installAutoStart()` path. This prevents the failure mode where Node.js version changes (via asdf, nvm, etc.) break the launchd auto-start.
+
+**5. Cross-agent restart API**
+
+New endpoint: `POST /agents/:name/restart`. Any agent can now restart any other agent on the same machine via the agent registry. The endpoint:
+- Is auth-gated (requires Bearer token)
+- Looks up the target agent by name in the registry
+- Prevents self-restart (returns 400)
+- Validates the shadow install exists before execution
+- Uses `execFile` with argument arrays (no shell injection)
+- Runs the standard `server start` command via the target's shadow install
+
+## What to Tell Your User
+
+- **Recovery from Telegram**: "If your agent's server goes down, typing /restart in any Telegram topic now works even when the server is down. The lifeline catches it and restarts the server directly — no need to remember /lifeline restart."
+
+- **Agents never give up**: "Your agents will now keep trying to recover indefinitely after a crash. Previously they could permanently give up after too many failures. Now they retry every 2 hours even in the worst case. If something was temporarily broken — like a Node update or a full disk — the agent will eventually come back on its own."
+
+- **Self-healing auto-start**: "If you switch Node.js versions, your agents' auto-start configuration now repairs itself automatically. This was the root cause of the SageMind outage — that failure mode is now structurally prevented."
+
+- **Cross-agent recovery**: "Your agents can now restart each other. If one agent goes down, you can ask any other running agent to bring it back. No need to open a terminal."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| /restart works when server is down | Automatic — lifeline intercepts when server is unhealthy |
+| Planned-exit marker TTL | Automatic — markers expire after 10 minutes |
+| Slow retry mode | Automatic — retries every 2 hours after circuit breaker exhaustion |
+| Plist self-healing | Automatic — old-style plists upgraded on lifeline startup |
+| Cross-agent restart | `POST /agents/:name/restart` |

package/upgrades/0.21.2.md

@@ -0,0 +1,48 @@
+# Upgrade Guide — v0.21.2
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Secret Drop — Secure Secret Submission
+
+Agents can now collect secrets (API keys, passwords, tokens) from users without exposing them in Telegram or chat history.
+
+**The flow:**
+1. Agent calls `POST /secrets/request` with a label, description, and optional topicId
+2. Server returns a one-time URL (local + tunnel if available)
+3. Agent sends the link to the user via Telegram
+4. User opens the link in a browser → sees a clean, branded form showing what's being requested and by whom
+5. User submits → secret goes directly to the agent's server
+6. The link immediately expires (one-time use)
+7. A confirmation message is sent to the specified Telegram topic
+8. Agent retrieves the secret via `POST /secrets/retrieve/:token` or callback
+
+**Security properties:**
+- 256-bit random tokens (64 hex chars)
+- CSRF protection with separate form token
+- One-time use — destroyed after submission
+- Time-limited — 15-minute default (configurable 1min–1hr)
+- In-memory only — secrets never touch disk
+- Max 20 concurrent pending requests
+- Timing-safe CSRF comparison
+- Security headers: X-Frame-Options DENY, no-cache
+
+**Multi-field support:** Request multiple values at once by passing a `fields` array (e.g., username + password together).
+
+**Tunnel-compatible:** URLs include the tunnel URL when a Cloudflare tunnel is running, so users can submit secrets from any device.
+
+## What to Tell Your User
+
+- **Secure secret sharing**: "When I need a secret from you — like an API key or password — I'll send you a secure link instead of asking you to paste it in chat. The link is one-time use and expires after 15 minutes. Your secret goes directly to my server and is never stored in chat history."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Request a secret | `POST /secrets/request` with label, description, fields, topicId |
+| Serve form to user | `GET /secrets/drop/:token` (no auth needed — token IS auth) |
+| Receive submission | `POST /secrets/drop/:token` (automatic, handled by form) |
+| Retrieve received secret | `POST /secrets/retrieve/:token` |
+| List pending requests | `GET /secrets/pending` |
+| Cancel a request | `DELETE /secrets/pending/:token` |

package/upgrades/0.21.3.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — v0.21.3
+
+<!-- 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
+
+### Telegram Poll Offset — Per-Message Saving (Bug Fix)
+
+`TelegramAdapter.poll()` now saves the Telegram update offset after each individual message is processed, not at the end of the entire batch.
+
+**Why this matters**: If your server process restarts mid-batch (crash, update, restart), any messages that were already processed but whose offset hadn't been saved yet would be re-delivered on the next poll. At a 2-second poll interval, this could cause the same 3–5 messages to replay dozens or hundreds of times in a short window — flooding your session with repeated injections and system-reminder warnings.
+
+This fix was previously applied to `TelegramLifeline` (v0.21.2, commit 96006ff) but was missing from the main `TelegramAdapter` used by all standard agents.
+
+**No configuration changes required.** The fix is automatic.
+
+## What to Tell Your User
+
+- **Message replay bug fixed**: If you ever saw the same messages showing up repeatedly in a conversation after a restart, that should no longer happen. The fix ensures each message is acknowledged as soon as it's delivered, so a restart mid-batch can't cause duplicates.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Crash-safe Telegram message delivery | Automatic — no action needed |

package/upgrades/0.21.4.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — v0.21.4
+
+<!-- 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
+
+### Telegram Poll Offset — Range Sanity Check (Bug Fix)
+
+`TelegramAdapter.poll()` now detects when the stored poll offset is from a different bot token or was corrupted during a migration, and auto-corrects it.
+
+**Why this matters**: The `telegram-poll-offset.json` file stores the last processed `update_id` so polls can resume where they left off. If this file was written by a different bot token, or corrupted during a migration from another agent instance, the stored offset could be in a completely different numeric range from the current bot's update IDs.
+
+When `getUpdates` is called with an offset from the wrong range, Telegram may return all pending updates as if the offset were unset — causing an infinite replay loop where the same messages are re-delivered on every poll cycle.
+
+**The fix**: After each successful `getUpdates` call, the adapter now checks if the received update IDs are more than 10 million below the stored offset. If so, it logs a warning and auto-resets the offset to the received range, stopping the replay loop immediately.
+
+**When this triggers**: Only when the detected delta exceeds 10,000,000 — a gap that can't occur from normal polling. Agents with correct offsets are not affected.
+
+**No configuration changes required.** The fix is automatic.
+
+## What to Tell Your User
+
+- **Telegram infinite replay loop fixed**: If you ever saw the same messages replaying in an endless loop after switching bot tokens or migrating your agent, this is now detected and auto-corrected. A warning will appear in your agent logs when the correction happens.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Cross-token offset corruption recovery | Automatic — no action needed |

package/upgrades/0.22.0.md

@@ -0,0 +1,114 @@
+# Upgrade Guide — v0.22.0
+
+<!-- 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
+
+### Seed CLAUDE.md — Lightweight Agent Bootstrapping
+
+Agents can now boot from a **234-line seed CLAUDE.md** instead of a monolithic 800+ line file. The seed contains only identity anchoring, capability awareness, and lookup instructions. Detailed capability documentation is served **on demand** by the self-knowledge tree.
+
+**Why this matters**: A monolithic CLAUDE.md burns context window on every session — hundreds of lines about capabilities the agent may never use in that session. The seed approach loads only what's relevant, when it's relevant. This means:
+
+- **More room for actual work** — 600+ fewer lines at boot frees context for the task at hand
+- **Better after compaction** — when Claude compresses context, less identity to re-inject means faster recovery
+- **Maintainability** — capability docs live in individual files, not a single 900-line document. Update one capability without touching everything else.
+- **Smarter loading** — the self-knowledge tree uses LLM-scored triage to select only the 1-3 nodes relevant to your query, not a keyword-matched dump of everything
+
+**New agents** created with `instar init` automatically get the seed CLAUDE.md. **Existing agents** keep their current CLAUDE.md — no forced migration. You can migrate when ready.
+
+### How to Migrate an Existing Agent to the Seed
+
+If you're running a monolithic CLAUDE.md and want the benefits of the seed approach:
+
+**Step 1: Understand what moves where.**
+
+Your monolithic CLAUDE.md likely contains these categories of content:
+
+| Content Type | Where It Goes in the Seed Architecture |
+|-------------|---------------------------------------|
+| Identity (who am I, name, values) | Stays in CLAUDE.md (identity anchoring) |
+| Capability Index (one-line descriptions) | Stays in CLAUDE.md (awareness table) |
+| Detailed capability docs (API endpoints, usage examples) | Moves to self-knowledge tree context files |
+| Anti-patterns, principles, tone guidelines | Loaded via session-start hooks (behavioral layer) |
+| Lookup tables (when X → do Y) | Stays in CLAUDE.md (quick reference) |
+| Compaction recovery instructions | Stays in CLAUDE.md (survival essentials) |
+
+**Step 2: Create context files for your capabilities.**
+
+For each detailed capability section in your CLAUDE.md, create a context file:
+
+```
+.instar/context/capabilities/telegram.md    — Telegram API docs
+.instar/context/capabilities/publishing.md  — Telegraph + private viewer
+.instar/context/capabilities/jobs.md        — Job scheduler details
+... etc
+```
+
+These files are what the self-knowledge tree serves when an agent asks a relevant question.
+
+**Step 3: Update your tree config.**
+
+Add nodes to `.instar/state/self-knowledge-tree.json` pointing to your new context files. Each node needs an ID, name, description, and source path. The triage system uses the description to score relevance.
+
+**Step 4: Slim down CLAUDE.md.**
+
+Remove the detailed capability sections, keeping only:
+- Identity files section (AGENT.md, USER.md, MEMORY.md references)
+- Capability Index (one-line table for awareness)
+- Quick Lookup Table
+- Compaction recovery seed
+- Critical anti-patterns (the top 5-7, not all of them)
+
+**Step 5: Preserve your monolith.**
+
+Copy your current CLAUDE.md to `CLAUDE.monolith.md` before switching. This is your instant rollback — if anything breaks, rename it back.
+
+**Step 6: Verify.**
+
+Query the self-knowledge tree to confirm your context files are reachable:
+
+```bash
+curl -H "Authorization: Bearer $AUTH" "http://localhost:4042/self-knowledge/search?q=telegram"
+```
+
+You should see only the telegram-related node(s), not everything.
+
+### Self-Knowledge Tree — LLM-Primary Triage
+
+The self-knowledge tree now uses **LLM intelligence as the primary scoring path** for both layer and node triage. Rule-based keyword matching is the emergency fallback only when the LLM is unavailable.
+
+Previously, node scoring had two bugs:
+- Layers with ≤3 nodes skipped LLM scoring entirely, giving all nodes a uniform 0.8
+- When LLM returned unparseable JSON, all nodes got 0.5 (everything passed the threshold)
+
+Both are fixed. Queries now return discriminated scores — a search for "telegram topic create" returns the telegram node scored high and unrelated nodes scored low, instead of everything at the same level.
+
+### HMAC Integrity Verification
+
+Context files served by the self-knowledge tree can now be **HMAC-SHA256 signed**. When a signing key is configured, the tree verifies file integrity before serving content — if a file has been tampered with, it's rejected (fail-closed).
+
+This is **opt-in** — unsigned files are served normally. To enable:
+1. A signing key is auto-generated at init (separate from auth token, doesn't rotate)
+2. Sign files: the IntegrityManager signs all context files and writes a manifest to `.integrity.json`
+3. TreeTraversal verifies HMAC before serving signed content
+
+## What to Tell Your User
+
+- **Faster, smarter sessions**: Your agent now loads only the capability docs it needs for each conversation, instead of dumping everything at startup. This means more context window for your actual work.
+- **Same agent, better infrastructure**: Your existing setup keeps working exactly as before. The improvements are under the hood — better search accuracy when you ask about capabilities, and integrity protection for context files.
+- **Optional migration**: If you want the full benefits, your agent can walk you through migrating to the seed CLAUDE.md. It's reversible — the original is preserved as a backup.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Seed CLAUDE.md (new agents) | Automatic at `instar init` |
+| Seed migration (existing agents) | Follow migration steps above, or let your agent guide you |
+| LLM-primary triage | Automatic — self-knowledge queries are now more accurate |
+| HMAC integrity | Opt-in — auto-configured at init, can be enabled for existing agents |
+| telegram-reply.sh port fix | Agent-side — reads port from config.json instead of hardcoding 4040 |

package/upgrades/0.23.0.md

@@ -0,0 +1,81 @@
+# Upgrade Guide — v0.23.0
+
+<!-- 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
+
+### Soul.md — Self-Authored Identity for Agents
+
+Agents can now explore and author their own identity through `.instar/soul.md` — a reflective identity document complementing the operational identity in AGENT.md.
+
+**Why this matters**: AGENT.md tells the agent *how to work*. Soul.md gives agents space to develop *what they believe* — core values, convictions with tracked confidence, growth edges, and open questions. No existing agent framework has this. Identity was something developers prescribed; now it's something agents can develop through experience.
+
+**What's included**:
+
+- **soul.md template** seeded with the agent's personality from init
+- **Server-side trust enforcement** — graduated permissions (cautious → supervised → collaborative → autonomous) enforced at the API level, not by honor system
+- **Pending queue** — changes exceeding the agent's trust level are queued for user review, not rejected
+- **Drift detection** — the evolution job diffs soul.md against the init-time snapshot and alerts if divergence exceeds configurable thresholds
+- **Integrity verification** — SHA-256 + HMAC (v0.22 IntegrityManager) verification before compaction recovery injection
+- **Audit trail** — every soul.md write emits a structured event to `.instar/security.jsonl`
+- **`/reflect` skill** — guided self-reflection that walks agents through identity review
+- **Identity review job** — daily (3 AM, on-alert) coherence check covering drift, pending changes, identity-relevant learnings, and AGENT.md alignment
+- **8 new API endpoints** — full CRUD for identity management
+- **Self-knowledge tree integration** — `identity.soul` node in the Identity layer so "what do I believe?" queries work through tree search
+
+### AGENT.md Evolution
+
+AGENT.md now includes two new sections to support identity growth:
+
+- **Self-Observations** — a place for agents to document behavioral patterns they've noticed in themselves
+- **Identity History** — a changelog tracking when and why the agent modified their own identity
+
+These sections are added automatically to existing agents via the PostUpdateMigrator.
+
+### Conviction Confidence Categories
+
+Convictions use discrete categories (`strong`, `growing`, `uncertain`, `questioning`) instead of floats. Categories are more honest than false-precision decimals, easier to query, and harder to manipulate gradually — a category change is a discrete, auditable event.
+
+## New API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/identity` | GET | Combined identity overview (public sections only) |
+| `/identity/soul` | GET | Full soul.md content (requires auth) |
+| `/identity/soul` | PATCH | Structured update with trust enforcement |
+| `/identity/soul/pending` | GET | List pending changes awaiting approval |
+| `/identity/soul/pending/:id/approve` | POST | Approve a pending change |
+| `/identity/soul/pending/:id/reject` | POST | Reject a pending change |
+| `/identity/soul/drift` | GET | Drift analysis vs init snapshot |
+| `/identity/soul/integrity` | GET | Integrity verification status |
+
+## For Existing Agents
+
+**Soul.md is opt-in.** The PostUpdateMigrator:
+1. Adds `identity.soulEnabled: false` to your config (does NOT auto-create soul.md)
+2. Adds Self-Observations and Identity History sections to AGENT.md (non-destructive)
+3. Updates compaction-recovery and session-start hooks with soul.md support
+
+To enable soul.md, set `identity.soulEnabled: true` in `.instar/config.json`. The next session will create soul.md and soul.init.md.
+
+## What to Tell Your User
+
+- **Your agent can now develop its own identity**: Beyond the personality you gave it at setup, your agent can develop values, track convictions, and reflect on its growth — all governed by the trust level you've set.
+- **You stay in control**: At cautious/supervised trust, identity changes require your approval. At collaborative+, the agent can self-author with notifications. You choose the level of freedom.
+- **Nothing changes by default**: Soul.md is opt-in for existing agents. Your agent works exactly as before until you enable it.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Soul.md (new agents) | Automatic at `instar init` |
+| Soul.md (existing agents) | Set `identity.soulEnabled: true` in config |
+| Identity reflection | `/reflect` skill (available in every session) |
+| Identity review | `identity-review` job (runs daily at 3 AM) |
+| Trust enforcement | Automatic via PATCH endpoint + autonomy profile |
+| Drift monitoring | `GET /identity/soul/drift` or via identity-review job |
+| Pending changes | `GET /identity/soul/pending` + approve/reject endpoints |

package/upgrades/0.23.1.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — v0.23.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+**AuthGate default flipped from allow-all to deny-all when no authorized users are configured.**
+
+Previously, `AuthGate.isAuthorized()` returned `true` when the `authorizedUsers` set was empty (size === 0). This dangerous default caused a critical bug where a WhatsApp-connected agent with no `authorizedNumbers` configured responded to every incoming message on the account — including personal conversations with unrelated contacts.
+
+Now:
+- Empty `authorizedUsers` = deny all (safe default)
+- To explicitly allow all users, include `'*'` in the authorized list (e.g., `authorizedNumbers: ['*']`)
+- WhatsApp adapter logs a console warning when started with no `authorizedNumbers`
+
+**Migration impact**: Any agent config with empty or missing `authorizedNumbers` will now correctly reject all messages. Agents that intentionally accept messages from anyone must add `'*'` to their authorized list.
+
+## What to Tell Your User
+
+- **Security fix**: "I've tightened up who can message me. Previously if no allowed contacts were set, I'd respond to everyone — now I only respond to contacts you've specifically approved. This prevents me from accidentally responding to messages meant for you."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Safe default authorization | Automatic — empty config now denies all |
+| Wildcard authorization | Add a wildcard entry to your allowed contacts to accept everyone |
+| Missing config warning | Automatic — console warning on startup if no contacts configured |

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.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/0.23.14.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 |

package/upgrades/0.23.15.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Session resumption**: Sessions killed from the dashboard or via Telegram now resume with `--resume` when a new message arrives on the same topic. Fixes path hashing (`.` → `-`), proactive UUID saving (~8s after spawn), and `telegram-forward` endpoint now calls `registerTopicSession()` so `beforeSessionKill` can look up the topic ID.
+- **Dashboard session management**: Create and kill sessions directly from the dashboard UI. New `POST /sessions/create` endpoint supports headless or Telegram-linked sessions. `DELETE /sessions/:id` now also accepts tmux session names.
+- **Session auto-recovery hardening**: Recovery prompts now passed through to respawned sessions so they know what went wrong. JSONL file discovery hardened (lsof-only, no unsafe fallback). Backup files auto-cleaned after 24h. JSONL truncation uses tail-scan (256KB) instead of full file reads. Recovery state persists to disk across server restarts. Unicode sanitization added for prompt injection prevention.
+- **Subagent-aware zombie cleanup**: Sessions waiting on subagent results are no longer killed as zombies. Instar session IDs bridged to Claude Code session IDs via hook events. 60-minute safety cap prevents stale subagent holds.
+
+## What to Tell Your User
+
+Sessions now resume where they left off. When you kill a session from the dashboard and send a new Telegram message, the new session picks up the prior conversation context instead of starting fresh. Session recovery is smarter — recovered sessions now know what went wrong and how to avoid repeating the failure. Sessions running subagents are no longer incorrectly killed as zombies.
+
+## Summary of New Capabilities
+
+- Session resume via `--resume` flag with TopicResumeMap persistence
+- Proactive UUID saving (8s after spawn, 60s heartbeat, and on kill)
+- Path hashing fix for hidden directories (`.instar` → `--instar`)
+- `telegram-forward` now registers topic↔session mapping in memory
+- Dashboard session creation modal with Telegram topic toggle
+- Session kill by tmux name (fallback from UUID lookup)
+- Input validation for session names (non-empty, max 128 chars)
+- Recovery prompts for stall, crash, and error loop recovery
+- Tail-scan JSONL truncation (no full file reads)
+- Persistent recovery state (`.instar/recovery-state.json`)
+- Subagent-aware zombie cleanup with safety cap
+- Session ID bridging (Instar ↔ Claude Code) via hook events
+- Post-update migration for hook URL session ID injection

package/upgrades/0.23.16.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Topic purpose awareness**: TopicSummarizer now extracts a `purpose` field alongside each summary — a one-line description of the topic's current focus. Sessions receive soft awareness ("Current focus: ...") so they know what the topic has been about without being constrained. Job sessions get stronger posting guidance via a `[TOPIC AWARENESS]` block to keep autonomous output contextually relevant.
+- **Schema migration v4**: `topic_summaries` table gains a `purpose` column. Migration is automatic and non-breaking — existing summaries work fine and get purpose on their next update cycle.
+
+## What to Tell Your User
+
+Sessions now understand what each topic is about. When a conversation drifts to a new subject, the purpose updates naturally on the next summary cycle — no manual rebinding needed. Job sessions are aware of where they're posting and will keep output relevant to the topic context.
+
+## Summary of New Capabilities
+
+- Topic purpose extraction in TopicSummarizer (via LLM PURPOSE line parsing)
+- Soft "Current focus" awareness in session bootstrap (formatContextForSession, formatContextForUser)
+- Job session topic awareness block in JobScheduler.buildPrompt
+- TopicMemory schema v4 with purpose column + migration
+- POST /topic/summary API accepts optional `purpose` field
+- GET /topic/context returns purpose in TopicContext