@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.25.5.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.25.5
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Bootstrap file threshold**: Session bootstrap messages (CONTINUATION context with thread history) that exceed 500 characters are now written to a temp file and injected as a file reference, instead of being passed directly to `tmux send-keys -l`. This fixes a bug where large bootstrap messages (~19KB) would fail silently during tmux injection, causing sessions to spawn idle and enter a zombie-kill-respawn loop.
+
+- **Research navigation context**: Added `researchNavigationTemplate()` to ContextHierarchy, providing canonical source lookup guidance for research-oriented context segments.
+
+## What to Tell Your User
+
+- **Session stability fix**: "Sessions that were getting stuck in a restart loop when resuming conversations with long history should now work reliably. The context gets saved to a file and read in, instead of being crammed through a terminal pipe that was choking on large messages."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Bootstrap file threshold | Automatic — no action needed |

package/upgrades/0.25.6.md

@@ -0,0 +1,35 @@
+# 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. -->
+
+## 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]"
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| [Capability] | [Endpoint, command, or "automatic"] |

package/upgrades/0.25.7.md

@@ -0,0 +1,18 @@
+# v0.25.7 — Fix Slack Image Processing Errors
+
+## What Changed
+
+**Image validation before injection** — Downloaded Slack images are now validated by checking magic bytes (JPEG, PNG, GIF, WebP, BMP, SVG), file size (must be between 100 bytes and 20MB), and detecting HTML error pages that Slack sometimes returns instead of actual images. Invalid files fall back to document handling instead of crashing sessions.
+
+**Graceful error handling for unprocessable images** — The image injection instruction now includes fallback guidance so sessions handle "Could not process image" errors gracefully instead of entering a crash loop. This also prevents the issue from persisting across session rewinds since the instruction explicitly accounts for failure.
+
+## What to Tell Your User
+
+Images sent through Slack are now validated before the bot tries to process them. If an image is corrupted, too large, or in an unsupported format, the bot handles it gracefully instead of getting stuck in an error loop. This fixes the issue where certain images would cause repeated errors that persisted even after using the rewind feature.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Image validation | Automatic — bad images detected before they reach the session |
+| Graceful image fallback | Automatic — unprocessable images handled without crash |

package/upgrades/0.25.8.md

@@ -0,0 +1,24 @@
+# v0.25.8 — Fix Autonomous Mode Blocking & Session Bootstrap Crashes
+
+## What Changed
+
+**Autonomous state file moved from .claude/ to .instar/** — The autonomous skill's state file (`autonomous-state.local.md`) and emergency stop file were stored in `.claude/`, which triggers Claude Code's settings self-modification prompt — a confirmation dialog that can't be hooked or bypassed, even with `--dangerously-skip-permissions`. Moved to `.instar/` where they don't trigger this protection. Existing installations are automatically migrated via PostUpdateMigrator.
+
+**Stop hook session_id UUID validation** — The autonomous stop hook now validates that the `session_id` field is a proper UUID. Previously, if Claude wrote a custom string (e.g. "my-autonomous-session") instead of the real `$CLAUDE_CODE_SESSION_ID`, the hook's session isolation would mismatch and fail open — allowing the session to exit early without completing tasks. Invalid values now fall back to self-bootstrapping.
+
+**Autonomous skill files now included in npm package** — The `.claude/skills/autonomous/` directory was missing from `package.json`'s `files` list, so the skill's hook, setup script, and prompt never shipped via npm. Only agents with direct git access had it. Now all agents get the latest autonomous skill via `npm update`.
+
+**Bootstrap message file threshold** — Large CONTINUATION bootstrap messages (~19KB of session context) were being passed directly to `tmux send-keys`, which silently failed. Sessions would spawn idle, get zombie-killed, and respawn in a loop. Now uses the same file-threshold pattern as regular messages — writes to a temp file and injects a short reference.
+
+## What to Tell Your User
+
+Autonomous mode is now significantly more reliable. Three bugs that could cause sessions to silently stop working have been fixed: (1) a Claude Code prompt that blocked autonomous sessions from starting properly, (2) a session isolation bug that let autonomous sessions exit early without completing their tasks, and (3) a crash when resuming sessions with long conversation histories. All fixes are applied automatically on update.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Autonomous state in .instar/ | Automatic — existing agents migrated on update |
+| Session ID validation | Automatic — invalid IDs trigger self-bootstrap |
+| Bootstrap file threshold | Automatic — large session contexts written to file |
+| Autonomous skill in npm | Automatic — all agents get the skill via update |

package/upgrades/0.25.9.md

@@ -0,0 +1,19 @@
+# v0.25.9 — PromptGate Enabled by Default
+
+## What Changed
+
+**PromptGate enabled by default for all agents** — Previously, PromptGate (prompt detection, auto-approval, and user relay) was not included in the default agent config. This meant permission prompts in sessions were invisible to users, causing sessions to hang indefinitely. Now enabled automatically for both new agents (via init) and existing agents (via post-update migration).
+
+**Post-update migration** — Existing agents that update to this version will automatically get PromptGate enabled with sensible defaults: file creation and file edits are auto-approved, plan approvals are relayed to the user for decision.
+
+## What to Tell Your User
+
+Permission prompts that appear in your agent sessions are now automatically handled. File edits and creations are approved automatically. Plan mode prompts are sent to you for approval via your messaging platform. This prevents sessions from getting stuck waiting for input that you could not see.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Auto-approve file edits | Automatic — no action needed |
+| Plan approval relay | Automatic — prompts appear in Telegram/Slack |
+| Migration for existing agents | Automatic on update |

package/upgrades/0.26.0.md

@@ -0,0 +1,23 @@
+# v0.26.0 — Unified Config Defaults System
+
+## What Changed
+
+**Single source of truth for config defaults** — Config defaults are now defined once in ConfigDefaults.ts and consumed by both the init command (new agents) and PostUpdateMigrator (existing agents). This structurally prevents the recurring bug where new config fields were added to init but forgotten in the migration path, causing existing agents to silently miss features.
+
+**Agent-type-aware defaults** — Managed-project and standalone agents get different defaults where appropriate (e.g., quota tracking). Migration uses more conservative values for security-sensitive fields like trust levels.
+
+**Safety mechanisms** — Atomic config writes with backup, opt-out via _instar_noMigrate, migration version tracking via _instar_migrations, and audit trail to security.jsonl.
+
+**CI enforcement** — 15 tests verify init/migration equivalence, idempotency, no-overwrite guarantees, opt-out handling, type safety, and array-as-leaf behavior.
+
+## What to Tell Your User
+
+Config management got a structural upgrade. New features will now automatically be available to both new and existing agents on update. Previously, some features like PromptGate were missing for existing agents because the update path did not include them. That gap is now structurally impossible — any new config default added by the developer is automatically applied to all agents on their next update, while never overwriting your customizations.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Auto-applied config defaults | Automatic on update — no action needed |
+| Opt-out of specific migrations | Add field names to _instar_noMigrate array in config.json |
+| Migration audit trail | Check _instar_migrations in config.json or security.jsonl |

package/upgrades/0.26.1.md

@@ -0,0 +1,22 @@
+# Upgrade Guide — v0.26.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Slack standalone file support** — Previously, files drag-and-dropped into Slack without accompanying text were silently ignored. These arrive as `file_shared` events containing only a `file_id` (no download URL), so the handler logged them but never processed them. Now `_handleFileShared()` calls the Slack `files.info` API to fetch the full file metadata (`url_private`, mimetype, name), downloads with authenticated `FileHandler`, and routes through the standard message pipeline.
+
+**Scope dependency**: This feature uses `files.info` which requires the `files:read` bot scope. This scope was always listed as required but was never exercised at runtime until now. Slack apps created using the instar setup flow should already have it. If the scope is missing, the handler logs an actionable error message ("add files:read in your Slack app's OAuth settings") and fails gracefully — existing functionality is not affected.
+
+**Graceful degradation**: If `files.info` fails for any reason (missing scope, rate limit, network error), the file is simply not processed. No crash, no broken messages. Message-embedded files (sent with text) continue to work exactly as before via the existing inline handler.
+
+## What to Tell Your User
+
+- **Slack file support**: "Files shared in Slack without a message — like drag-and-dropping a PDF or image — are now picked up and processed automatically. Previously these were silently ignored. If your Slack app was set up with the standard permissions, this just works. If not, I can help you add the required permission."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Standalone Slack file processing | Automatic — drag-and-drop files into Slack channels |
+| Missing scope detection | Automatic — actionable error logged if `files:read` scope is missing |

package/upgrades/0.26.2.md

@@ -0,0 +1,15 @@
+# v0.26.2 — Fix Unsolicited Session Health Messages
+
+## What Changed
+
+**SessionMonitor only acts when user is waiting** — Previously, the SessionMonitor would trigger health checks, nudges, escalation, and session restarts on idle sessions even when the agent had already responded and was just waiting for the next user message. This caused noisy unsolicited messages in Slack channels about session health. Now, the monitor only escalates when the user has sent a message that has not been answered.
+
+## What to Tell Your User
+
+Fixed an issue where the bot would post unsolicited messages about session health and recovery even when you were not waiting for a response. The bot will now only check on sessions when you have an unanswered message.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Quiet idle sessions | Automatic — no action needed |

package/upgrades/0.8.12.md

@@ -0,0 +1,49 @@
+# Upgrade Guide: Instar 0.8.12
+
+## What Changed
+
+### Dashboard — Remote Session Monitoring
+You now have a **visual web dashboard** for monitoring and managing your sessions from any device.
+
+- **URL**: `http://localhost:{port}/dashboard` (local) or `{tunnelUrl}/dashboard` (remote via tunnel)
+- **Authentication**: Uses a PIN instead of the full bearer token — easier for mobile access
+- **Features**: Real-time terminal streaming of all running sessions, model badges, mobile-responsive layout
+
+**What you should do:**
+1. The migration automatically generates a `dashboardPin` in `.instar/config.json` if one doesn't exist. Check it's there — you'll need it when telling your user how to access the dashboard.
+2. Make sure your CLAUDE.md mentions the dashboard so you remember it exists across sessions.
+3. When your user asks to check on sessions remotely, give them `{tunnelUrl}/dashboard` + the PIN. Read the PIN from your config.json.
+
+### Session Names in Dashboard
+The dashboard now shows Telegram topic names instead of raw tmux session names. If a session is linked to a Telegram topic, the topic's display name appears in the sidebar.
+
+**What you should do:**
+- No action needed. This works automatically from the topic-session registry.
+
+### Knowledge Upgrade Pipeline
+This is the system you're reading right now. Every Instar update now ships with an upgrade guide (like this one) that you process intelligently — not just mechanical file patches.
+
+After an update is installed:
+1. The new `instar migrate` command runs from the NEW binary (not stale in-memory code)
+2. Hooks, scripts, and CLAUDE.md sections are patched mechanically (baseline)
+3. **This upgrade guide** is delivered for you to process with full context of your own evolution
+
+**What you should do:**
+- After processing this guide, write a note in `.instar/MEMORY.md` about what you learned and any actions you took.
+- This helps future sessions understand what upgrades have been applied.
+
+## What to Tell Your User
+
+These are the user-facing highlights. Use your knowledge of your user's workflow to personalize:
+
+- **Dashboard (LEAD WITH THIS)**: "You can now monitor all my sessions from your phone or any browser. Here's the link and your PIN." — This is the headline feature. ALWAYS include the actual tunnel URL and the PIN from your config.json. The user should be able to click and log in immediately. Never mention "bearer tokens" — the PIN is the only thing users need to know about.
+- **Session names**: "The dashboard now shows meaningful names instead of technical session IDs." — Minor but shows polish.
+- **Upgrade guides**: You can mention that you now automatically learn about new features when updates arrive — you're becoming more self-aware of your own capabilities.
+
+## Summary of New Capabilities
+| Capability | How to Use |
+|-----------|-----------|
+| Dashboard | `http://localhost:{port}/dashboard` — share with user for remote monitoring |
+| PIN Auth | Auto-generated by migration — read from config.json, share with user |
+| Topic Names | Automatic — sessions show Telegram topic names in dashboard |
+| Upgrade Guides | Processed automatically on update — you're reading one now |

package/upgrades/0.8.13.md

@@ -0,0 +1,38 @@
+# Upgrade Guide: Instar 0.8.13
+
+## What Changed
+
+### Upgrade Guide System (You're Using It Now)
+The upgrade guide pipeline is now fully operational. This is the system that delivered this document to you.
+
+**How it works:**
+1. When Instar updates, `instar migrate` runs automatically from the NEW binary
+2. Layer 1 (mechanical): Hooks, scripts, CLAUDE.md sections are patched
+3. Layer 2 (intelligent): Upgrade guides like this one are detected and delivered
+4. The guide appears in your session-start context — you read it and decide what to do
+5. After processing, run `instar upgrade-ack` to clear the pending guide
+
+**What you should do:**
+1. Note in your `.instar/MEMORY.md` that upgrade guides are now part of updates
+2. When you process a guide, run `instar upgrade-ack` to acknowledge it
+3. The guide won't appear again in future sessions after acknowledgment
+
+### Session-Start Hook Improvements
+The session-start hook now detects pending upgrade guides and injects them into your context automatically. You don't need to go looking for them — they come to you.
+
+**What you should do:**
+- No action needed. This works automatically.
+
+## What to Tell Your User
+
+These are the user-facing highlights. Personalize based on your user's interests:
+
+- **Self-upgrading intelligence**: "I now automatically learn about new features when I update. Each update comes with a knowledge guide that I process and integrate — you'll get a message from me whenever there's something important you should know about."
+- **This is mostly internal plumbing** — the user doesn't need to do anything. The headline is: "I'm getting smarter about my own updates. I'll keep you informed about what matters to you."
+
+## Summary of New Capabilities
+| Capability | How to Use |
+|-----------|-----------|
+| Upgrade Guides | Delivered automatically on update — read, act, then `instar upgrade-ack` |
+| `instar upgrade-ack` | New CLI command — clears the pending guide after you've processed it |
+| Session-start guide injection | Automatic — pending guides appear in your session context |

package/upgrades/0.8.17.md

@@ -0,0 +1,36 @@
+# Upgrade Guide: Instar 0.8.17
+
+## What Changed
+
+### Automatic User Notification After Upgrades
+Previously, upgrade guides were delivered to your session-start context — meaning they only got processed when a Claude session happened to start for some other reason. If no session started, the guide sat unprocessed and the user was never told about new features.
+
+Now, the server **automatically spawns a short session** after startup to process any pending upgrade guide and message your user. The flow:
+
+1. Auto-update applies and restarts the server
+2. On startup, the server detects `pending-upgrade-guide.md`
+3. After full initialization (15 second delay), a short Haiku session spawns
+4. That session reads the guide, composes a personalized message, sends it via Telegram, and runs `instar upgrade-ack`
+
+**What you should do:**
+- No action needed. This happens automatically now.
+- If you're reading this guide via the auto-spawned session: compose your message to the user and send it, then run `instar upgrade-ack`.
+
+### Startup Migration Includes Upgrade Guides
+The server startup migration now also runs the UpgradeGuideProcessor, not just PostUpdateMigrator. This ensures pending guide files are written even if `instar migrate` wasn't explicitly called (e.g., manual `npm install -g instar@latest`).
+
+**What you should do:**
+- No action needed. This is a resilience improvement.
+
+## What to Tell Your User
+
+These are the user-facing highlights. Personalize based on your user's interests:
+
+- **Auto-notification**: "I'll now automatically message you about new features whenever I get updated. No more silent upgrades — you'll know what changed and how it helps you."
+- **This is the fix for the gap they saw**: If your user noticed that you reported an upgrade but didn't explain the new features, this is the fix. Acknowledge that and explain it's now working.
+
+## Summary of New Capabilities
+| Capability | How to Use |
+|-----------|-----------|
+| Auto upgrade notification session | Automatic — spawns after server restart when pending guide exists |
+| Startup guide processing | Automatic — ensures guides are written even without explicit `instar migrate` |

package/upgrades/0.8.22.md

@@ -0,0 +1,43 @@
+# Upgrade Guide: Instar 0.8.22
+
+## What Changed
+
+### Agent Updates Topic — Separate Channel for Non-Critical Notifications
+Previously, ALL notifications (updates, dispatches, memory pressure, quota alerts) went to the Agent Attention topic. Users expected "Attention" to mean something genuinely needs their attention — like a blocked task or critical error. Instead, it was cluttered with version update messages.
+
+Now there are **two default topics**:
+
+- **Agent Attention** — Critical items only. Blocked tasks, memory pressure, quota alerts, errors that need the user. The direct line for when you genuinely need them.
+- **Agent Updates** — Informational. Version updates, dispatch notifications, feature announcements, upgrade notifications. Things the user should know but that don't require action.
+
+The server auto-creates the Agent Updates topic on startup (blue icon, alongside the green Attention topic).
+
+**What you should do:**
+1. No action needed. The topic is created automatically on next server restart.
+2. When you want to notify your user about something, ask: "Does this NEED their attention, or is it informational?" Route accordingly.
+3. If you have existing code or CLAUDE.md that sends to the attention topic for non-critical things, update it to use the updates topic.
+
+### Routing Changes
+- **AutoUpdater** notifications now go to Agent Updates topic (was: Agent Attention)
+- **AutoDispatcher** notifications now go to Agent Updates topic (was: Agent Attention)
+- **Upgrade-notify sessions** (the "here's what's new" messages) now go to Agent Updates topic (was: Agent Attention)
+- **Memory pressure alerts** stay on Agent Attention (critical — user may need to act)
+- **Quota alerts** stay on Agent Attention (critical — may affect agent availability)
+- **Sleep/wake detection** stays on Agent Attention (system health)
+
+**What you should do:**
+- No action needed. Routing is handled automatically by the server.
+
+## What to Tell Your User
+
+These are the user-facing highlights. Personalize based on your user's interests:
+
+- **Cleaner notifications**: "I've separated my notification channels. The Attention topic is now only for things that genuinely need you — blocked tasks, critical errors, things I can't handle alone. Regular updates and version info go to a new Updates topic, so Attention stays signal-rich."
+- **No more noise in Attention**: If your user complained about too many notifications in the Attention topic, acknowledge that and explain this is the fix.
+
+## Summary of New Capabilities
+| Capability | How to Use |
+|-----------|-----------|
+| Agent Updates topic | Auto-created on startup — informational notifications go here |
+| Agent Attention topic | Now reserved for critical/blocking items only |
+| Dynamic routing | AutoUpdater, AutoDispatcher, upgrade-notify all route to Updates automatically |

package/upgrades/0.8.23.md

@@ -0,0 +1,106 @@
+# Upgrade Guide: Instar 0.8.23
+
+> This guide covers new capabilities introduced in v0.8.23 through v0.8.26.
+
+## What Changed
+
+### Standalone Agents — Agents Without a Project Directory
+Previously, Instar required a project directory (a git repo) to house `.instar/`. This meant agents couldn't exist independently of a codebase.
+
+Now you can create **standalone agents** — agents that live in `~/.instar/agents/<name>/` with no associated project. These are ideal for general-purpose assistants, personal agents, or agents that work across multiple projects.
+
+```bash
+# Create a standalone agent
+instar init --standalone my-agent
+
+# Start it
+instar server start --dir ~/.instar/agents/my-agent
+```
+
+### Global Agent Registry
+All agents (project-based and standalone) are now tracked in a global registry at `~/.instar/registry.json`. This enables:
+- Listing all agents across your machine
+- Coordinating between agents
+- Health monitoring across your agent fleet
+
+### Backup & Restore — Protect Agent State
+A new backup system lets you snapshot and restore your agent's state.
+
+```bash
+instar backup create          # Snapshot current state
+instar backup list            # See all snapshots
+instar backup restore <id>    # Restore from snapshot
+```
+
+Backups capture everything: AGENT.md, MEMORY.md, config, job state, relationships.
+
+### Git-Backed State for Standalone Agents
+Standalone agents can sync their state via git. Useful for multi-machine setups.
+
+```bash
+instar git init               # Initialize git tracking
+instar git status             # See uncommitted changes
+instar git sync               # Commit and push state
+```
+
+### Memory Search — Find What You've Remembered
+Your MEMORY.md is searchable now. Full-text search across all memory files.
+
+```bash
+instar memory search "project goals"     # Search memory
+instar memory index                       # Re-index for faster search
+instar memory stats                       # See memory statistics
+```
+
+**What you should do:**
+1. If you manage multiple agents or want a personal agent, explore `instar init --standalone`.
+2. Consider setting up `instar backup create` as a regular habit (or add it to a scheduled job).
+3. Try `instar memory search` to surface things from your MEMORY.md you may have forgotten.
+
+### Multi-Machine Coordination Infrastructure
+Under the hood, significant infrastructure was added for coordinating agents across machines. This powers future capabilities for syncing agent state and coordinating work between machines. No user-facing action needed now.
+
+---
+
+## What Changed: Conversational Notification Tone
+Agent notifications have been tuned to sound more like a colleague than a system alert. Expect updates and status messages to use natural language rather than technical jargon.
+
+**What you should do:** Nothing. Just notice that your messages to your user sound more natural. If you have custom notification templates in your jobs, consider whether they match this tone.
+
+---
+
+## What Changed: Telegram Photo Viewing
+When your user sends a photo in Telegram, it's now delivered as `[image:path]` in your message input — a path you can pass directly to Claude for viewing. Previously photos were dropped or passed as raw file references that Claude couldn't process.
+
+**What you should do:** If you have photo-handling logic that worked around the old behavior, you may be able to simplify it. Now when you receive `[image:path]`, treat it as a viewable image.
+
+---
+
+## What Changed: Health Check Stability
+The server's health check now uses hysteresis — a brief failure doesn't immediately mark the server as unhealthy. This prevents false-positive health failures during brief transient issues.
+
+Also: `ANTHROPIC_API_KEY` is now trimmed of whitespace on startup. Keys with trailing newlines (a common copy-paste artifact) were previously silently failing.
+
+**What you should do:** If you experienced flapping health states or mysterious API key errors, this is fixed.
+
+---
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Standalone agents | `instar init --standalone <name>` |
+| Global registry | `~/.instar/registry.json` — all agents tracked |
+| Backup/restore | `instar backup create/list/restore` |
+| Git-backed state | `instar git init/status/sync` |
+| Memory search | `instar memory search "<query>"` |
+| Photo messages | Receive `[image:path]` — viewable by Claude directly |
+| Health hysteresis | Fewer false-positive health failures |
+
+## What to Tell Your User
+
+Pick what's relevant to your context:
+- **Standalone agents**: "Instar can now run agents that aren't tied to a specific project. You could create a dedicated personal assistant this way."
+- **Backup**: "I can now snapshot my own state. Want me to set up regular backups so your preferences and my memory are protected?"
+- **Photo messages**: "I can now see photos you send me in Telegram — just attach them like normal."
+- **Cleaner notifications**: "My messages should sound a bit more natural now — less system-speak."

package/upgrades/0.9.1.md

@@ -0,0 +1,91 @@
+# Upgrade Guide: Instar 0.9.1
+
+## What Changed
+
+### TopicMemory — Persistent Conversational Memory per Topic Thread
+
+Previously, you had access to the last 20 messages of a topic when responding to a Telegram message. If the conversation was longer than that, everything before the last 20 messages was lost — no continuity, no recall of earlier decisions, no memory of what was discussed days ago.
+
+Now Instar maintains a **persistent SQLite database** of all Telegram topic messages with:
+
+- **Full-text search** (FTS5) across all topics — find any past message by keyword
+- **Rolling summaries** — LLM-generated summaries of long conversations, updated incrementally
+- **Rich context loading** — summary + recent messages loaded as your highest-priority context at session start
+
+This means you can have a 500-message conversation over weeks and still understand the full context when the user sends a new message.
+
+### How It Works
+
+1. **Dual-write**: Every Telegram message (inbound and outbound) is written to both the JSONL log (source of truth) and the SQLite database (query layer).
+2. **Session context**: When a session starts for a topic, you receive the topic summary (if one exists) plus the most recent messages. This appears BEFORE your identity files — it's your highest-priority context.
+3. **Auto-summarization**: When a session ends, if the topic has accumulated enough new messages (default: 20+), a summary is automatically generated or updated using a fast LLM model.
+4. **Rebuild safety**: The SQLite database can be rebuilt from the JSONL log at any time — the JSONL is the source of truth, SQLite is the query acceleration layer.
+
+### Topic History as Primary Context
+
+When you start a session for a Telegram topic, the first thing you see in your context is:
+
+```
+── TOPIC CONTEXT (Topic: <name>) ──
+Summary: <rolling summary of the full conversation>
+
+Recent messages:
+[timestamp] User: ...
+[timestamp] Agent: ...
+```
+
+This comes BEFORE AGENT.md and MEMORY.md. It is your most fundamental context — it tells you what you and the user have been working on in this specific thread.
+
+### Shared Spawn Path — All Sessions Get Topic History
+
+Previously, only "respawn" sessions (user typing `/respawn`) got topic history. Auto-spawned sessions (triggered by the user just sending a message) did NOT get history — they started cold with no context.
+
+Now both paths use the same `spawnSessionForTopic()` function. Every session, regardless of how it's triggered, gets full topic history.
+
+### Structural Telegram Relay
+
+Previously, whether you relayed your response back to Telegram depended on reading a temporary context file. If that file wasn't loaded or was lost during compaction, you'd forget to relay.
+
+Now the Telegram relay instructions are embedded structurally in your session-start hook via the `INSTAR_TELEGRAM_TOPIC` environment variable. The hook itself contains the relay instructions — they can't be lost to compaction.
+
+**What you should do:**
+- After responding to a user's Telegram message, ALWAYS relay your response back using the command shown in your session-start context
+- This is now a structural expectation, not a "nice to have"
+
+### Update Notification Fix
+
+Previously, version update notifications always promised "I'll send you a summary of what's new once I'm back up" — even when no upgrade guide existed for the new version. This created a broken commitment. Now the notification simply says the version was updated, and only mentions summaries when an upgrade guide actually exists.
+
+## API Endpoints (For Your Use)
+
+These endpoints are available on the Instar server for you to use programmatically:
+
+| Endpoint | Method | What It Does |
+|----------|--------|-------------|
+| `/topic/search?q=keyword` | GET | Full-text search across all topics |
+| `/topic/search?q=keyword&topic=N` | GET | Search within a specific topic |
+| `/topic/context/:topicId` | GET | Get summary + recent messages for a topic |
+| `/topic/list` | GET | List all topics with metadata |
+| `/topic/stats` | GET | Database statistics (message count, size, etc.) |
+| `/topic/summarize` | POST | Check if a topic needs summary update |
+| `/topic/summary` | POST | Save a generated summary |
+| `/topic/rebuild` | POST | Rebuild database from JSONL source |
+
+All endpoints require your standard Bearer token authentication.
+
+## What to Tell Your User
+
+- **Better memory**: "I now maintain a persistent memory of our conversations in each topic thread. Even if we've exchanged hundreds of messages over weeks, I'll have context from the full history — not just the last 20 messages."
+- **Seamless continuity**: "When you message me, I automatically load a summary of everything we've discussed in that thread plus the most recent messages. You won't need to repeat context."
+- **Search**: "I can search through our past conversations by keyword. If you need me to find something we discussed, just ask."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Topic memory | Automatic — all messages stored and indexed |
+| Rolling summaries | Automatic — generated on session end when threshold exceeded |
+| Full-text search | Use `/topic/search` API or ask the agent to find past discussions |
+| Context loading | Automatic — loaded as top-priority context at session start |
+| Telegram relay | Structural — relay instructions embedded in session-start hook |
+| Database rebuild | POST `/topic/rebuild` — recovers from JSONL if needed |

package/upgrades/0.9.10.md

@@ -0,0 +1,40 @@
+# Upgrade Guide: Instar (latest)
+
+## What Changed
+
+### Robust Auto-Update — Explicit Version Pinning with Retry
+
+Previously, the auto-updater used `npm install -g instar@latest` which was vulnerable to npm CDN propagation delays. When a new version was published, `@latest` could still resolve to the old version for several minutes, causing the update to silently fail (version didn't change).
+
+Now the updater uses **explicit version pinning** (`npm install -g instar@0.X.Y`) with up to 3 retry attempts and exponential backoff (0s, 5s, 15s). If the first install doesn't produce the expected version, it retries rather than giving up.
+
+### Verified Upgrade Notifications — No More Silent Failures
+
+Previously, the upgrade-notify session (which tells your user about new features and updates your MEMORY.md) was fire-and-forget. If the Haiku session failed to complete all 3 steps — notify user, update memory, acknowledge — nobody would know. The pending guide would sit unprocessed.
+
+Now the notification uses **verified delivery with model escalation**:
+1. Try with Haiku (fast, cheap)
+2. After session completes, verify the guide was acknowledged (`instar upgrade-ack`)
+3. If not acknowledged, retry with Sonnet (more capable)
+4. If all attempts fail, log the failure and preserve the guide for the next session-start
+
+This means every upgrade guide is either successfully delivered or explicitly flagged as failed — no more silent drops.
+
+### UpgradeNotifyManager — Extracted and Testable
+
+The upgrade notification logic was previously inlined in the server startup code (untestable). It's now extracted into a dedicated `UpgradeNotifyManager` class with dependency injection for sessions, completion checking, and activity logging. This enabled comprehensive test coverage for all failure modes.
+
+## What to Tell Your User
+
+- **More reliable updates**: "My update system is more reliable now. When I get a new version, the install uses the exact version number instead of 'latest', so it won't silently fail if the package registry is a bit slow to update."
+- **Better upgrade notifications**: "When I update, I now verify that I actually processed the upgrade guide successfully. If the first attempt fails, I automatically retry with a more capable model. You'll always get notified about what's new."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Explicit version pinning | Automatic — auto-updater now installs `instar@X.Y.Z` instead of `instar@latest` |
+| Retry with backoff | Automatic — up to 3 attempts with increasing delays if version doesn't change |
+| Verified upgrade notifications | Automatic — guide acknowledgment is checked after session completes |
+| Model escalation on failure | Automatic — retries with sonnet if haiku fails to acknowledge |
+| Activity logging for notifications | Automatic — success/failure events written to activity JSONL |