@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.9.29.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### Proactive GitHub CLI Setup During Installation
+
+The setup launcher now actively ensures the GitHub CLI (`gh`) is available before the wizard starts, enabling agent restore from GitHub backups on new machines.
+
+**What happens now:**
+1. Launcher detects if `gh` is installed
+2. If not, tries to install via `brew install gh` (macOS) or `apt install gh` (Linux)
+3. Checks authentication status
+4. Passes `ghStatus` (ready/installed/auth-needed/unavailable) to the wizard
+
+**The wizard uses ghStatus to guide the user:**
+- `ready` → scans GitHub for `instar-*` repos, offers restore
+- `auth-needed` → walks user through `gh auth login --web`
+- `unavailable` → asks "Have you used Instar before?" and helps install manually
+- No state silently blocks the restore path
+
+### Setup Wizard Decision Tree Improvements
+
+The wizard now handles every `ghStatus` value with a clear next step instead of silently falling through to "set up new agent."
+
+## What to Tell Your User
+
+When setting up Instar on a new machine, the setup process now actively helps you connect to GitHub so it can find any existing agent backups. If the GitHub CLI isn't installed, we'll help you install it. If it's not signed in, we'll walk you through sign-in. No silent skips — every step has clear guidance.
+
+## Summary of New Capabilities
+
+- **Proactive gh install**: Setup launcher tries to install GitHub CLI automatically
+- **ghStatus context**: Wizard receives explicit status instead of silent failure
+- **auth-needed flow**: Wizard walks through GitHub sign-in when gh is installed but not authed
+- **unavailable flow**: Wizard asks about prior usage and helps install gh manually

package/upgrades/0.9.32.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — v0.9.32
+
+## What Changed
+
+### Git Sync Job — Now Enabled by Default
+
+The `git-sync` job is now **enabled by default** for all agents. Non-technical users don't need to know about it — it just works in the background.
+
+**How it works invisibly:**
+- Gate script silently skips if there's no git repo or no remote configured
+- Gate skips if nothing needs syncing (no local or remote changes)
+- Only spawns a Claude session when actual sync work is needed
+- Zero cost when idle — no session, no tokens
+
+**What changed from v0.9.32:**
+- `enabled: true` by default (was `false`)
+- Gate now checks for remote existence — agents without a remote never trigger a sync
+- Existing agents: `refreshJobs` auto-enables git-sync if git + remote are detected
+
+**For existing agents upgrading:** If you had git-sync disabled from the previous version and your project has a git remote, it will be auto-enabled on next update. If you have no git remote, nothing changes.
+
+## What to Tell Your User
+
+No action required. Git sync now works automatically for agents with a git remote. If your project has no git remote, nothing changes.
+
+## Summary of New Capabilities
+
+- **git-sync auto-enabled**: Works invisibly for agents with git + remote
+- **Remote detection in gate**: Prevents wasteful sessions for repo-only (no remote) agents
+- **Auto-enable migration**: Existing disabled git-sync jobs get enabled when git + remote detected

package/upgrades/0.9.36.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### Guardian Job Network
+
+Five new guardian jobs added to the default job set. These run automatically in the background to maintain agent coherence:
+
+- **degradation-digest** (4h): Groups repeated degradation patterns and escalates trends
+- **state-integrity-check** (6h): Cross-validates state file consistency, detects orphans and bloat
+- **memory-hygiene** (12h): Reviews MEMORY.md for stale entries, duplicates, and quality issues
+- **guardian-pulse** (8h): Meta-monitor that verifies other jobs are running and healthy
+- **session-continuity-check** (4h): Verifies sessions produce lasting artifacts
+
+All guardian jobs use gates for zero-token pre-screening and are silent when healthy.
+
+**For existing agents:** New jobs are automatically added on next update via `refreshJobs()`. No manual configuration needed.
+
+## What to Tell Your User
+
+Your agent now has built-in self-monitoring. Five new background jobs watch for issues like state corruption, memory bloat, and silent job failures. They run automatically and only alert when something needs attention.
+
+## Summary of New Capabilities
+
+- **Guardian network**: 5 new self-monitoring jobs for agent coherence
+- **Zero-token gates**: Jobs only run when there's actual work to do
+- **Automatic deployment**: Existing agents get new jobs on next update

package/upgrades/0.9.8.md

@@ -0,0 +1,125 @@
+# Upgrade Guide: Instar 0.9.8
+
+## What Changed
+
+### StallTriageNurse — LLM-Powered Session Recovery
+
+Previously, when a user sent a Telegram message and the session didn't respond within 2 minutes, the system sent a generic fallback message: "Your message hasn't been processed yet." There was no intelligence behind it — no diagnosis of what was wrong, no attempt to fix it, no escalation if the first fix didn't work. Users were left waiting, unsure if their message was lost, if the session crashed, or if it was just busy.
+
+Now Instar includes a **StallTriageNurse** — an LLM-powered diagnostic and recovery system that automatically:
+
+1. **Detects** when a message goes unanswered for 2+ minutes
+2. **Gathers context** — captures the last 50 lines of terminal output, checks session liveness, pulls recent message history
+3. **Diagnoses** the problem using an LLM (via your IntelligenceProvider or direct Anthropic API), analyzing terminal output to determine exactly what's happening
+4. **Treats** the session with the right action:
+   - `status_update` — session is actively working, just slow. Tells the user to wait.
+   - `nudge` — session might be waiting for input. Sends an Enter keystroke.
+   - `interrupt` — session is stuck in a loop. Sends Escape.
+   - `unstick` — session has a hung process. Sends Ctrl+C.
+   - `restart` — session is dead or crashed. Respawns it entirely.
+5. **Verifies** the action worked (waits, then checks if output changed or session came alive)
+6. **Escalates** if the first action didn't work — steps up through the treatment chain automatically (up to `maxEscalations`, default 2)
+
+### Dead Session Short-Circuit
+
+If a session is detected as dead or missing, the nurse skips the LLM entirely and immediately restarts it. No wasted API calls for an obvious problem.
+
+### Cooldown Protection
+
+After triaging a topic, the nurse enters a cooldown period (default 3 minutes) to prevent hammering the same session with repeated recovery attempts. Cooldowns are per-topic.
+
+### Concurrent Triage Prevention
+
+If a triage is already in progress for a topic (e.g., the LLM is still diagnosing), a second stall detection for the same topic returns immediately with `already_triaging` rather than spawning a duplicate.
+
+### Health Check Integration
+
+The nurse's status is now visible in your server's health check. The `/health` endpoint shows:
+- Whether the triage nurse is active
+- How many cases are currently being triaged
+- How many past triages have been recorded
+
+### Triage API Endpoints
+
+Three new API endpoints let you monitor and manually trigger the nurse:
+
+| Endpoint | Method | What It Does |
+|----------|--------|-------------|
+| `/triage/status` | GET | Current nurse status: enabled, active cases, history count, cooldowns |
+| `/triage/history?limit=N` | GET | Past triage records (default: all, capped at 50) |
+| `/triage/trigger` | POST | Manually trigger triage for a topic (body: `{ topicId, sessionName }`) |
+
+### State Persistence
+
+Triage history survives server restarts via StateManager. When the server comes back up, the nurse loads its history and continues tracking.
+
+### Event System
+
+The nurse emits typed events you can listen to for observability or custom integrations:
+
+| Event | When |
+|-------|------|
+| `triage:started` | Triage begins for a topic |
+| `triage:diagnosed` | LLM diagnosis received |
+| `triage:treated` | Action executed |
+| `triage:escalated` | Action failed, escalating to next level |
+| `triage:resolved` | Problem fixed |
+| `triage:failed` | All escalations exhausted |
+
+### Configuration
+
+Enable the nurse in your `config.json` under `monitoring`:
+
+```json
+{
+  "monitoring": {
+    "triage": {
+      "enabled": true,
+      "cooldownMs": 180000,
+      "verifyDelayMs": 10000,
+      "maxEscalations": 2,
+      "useIntelligenceProvider": true
+    }
+  }
+}
+```
+
+- `enabled` — Turn on/off (default: true when configured)
+- `apiKey` — Anthropic API key (falls back to `ANTHROPIC_API_KEY` env var)
+- `cooldownMs` — Minimum time between triages for same topic (default: 180000ms = 3 min)
+- `verifyDelayMs` — How long to wait before checking if an action worked (default: 10000ms = 10 sec)
+- `maxEscalations` — Max times to try a stronger action before giving up (default: 2)
+- `useIntelligenceProvider` — Use your configured IntelligenceProvider instead of direct API calls (default: true)
+
+If you don't have `monitoring.triage` in your config, the nurse won't be created. If you already have an `ANTHROPIC_API_KEY` in your environment and add the config block, it will work immediately.
+
+## What to Tell Your User
+
+Pick what's relevant to your relationship:
+
+- **Reliability**: "When you send me a message and I don't respond within a couple of minutes, there's now an automatic recovery system that diagnoses what's wrong and fixes it — whether I'm stuck on a long task, waiting for input, or need a restart. You'll get a message explaining what's happening instead of silence."
+- **Transparency**: "If I stall, you'll see a message explaining exactly what's going on — like 'Your session is running a long build, hang tight' or 'Session was unresponsive, restarting now.' No more mystery silence."
+- **Self-healing**: "The system can now recover from most session problems on its own — it tries progressively stronger fixes and only gives up after exhausting all options. Most stalls resolve without you needing to do anything."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| LLM-powered stall diagnosis | Automatic — triggers when message unanswered for 2+ minutes |
+| 5-action treatment chain | Automatic — status_update, nudge, interrupt, unstick, restart |
+| Escalation with verification | Automatic — tries stronger actions if previous one didn't work |
+| Dead session short-circuit | Automatic — instantly restarts dead/missing sessions (no LLM needed) |
+| Cooldown protection | Automatic — prevents repeated triage on same topic within 3 minutes |
+| Triage status API | `GET /triage/status` — check nurse health and active cases |
+| Triage history API | `GET /triage/history?limit=10` — review past recovery attempts |
+| Manual triage trigger | `POST /triage/trigger` with `{ topicId, sessionName }` — force a triage |
+| Health check integration | Automatic — nurse status appears in `/health` response |
+| State persistence | Automatic — history survives server restarts |
+| Event-driven observability | Listen to `triage:*` events for custom integrations |
+| Configuration | Add `monitoring.triage` block to `config.json` to enable |
+
+**What you should do:**
+1. Add the `monitoring.triage` config block to your `config.json` if it's not already there
+2. Verify your `ANTHROPIC_API_KEY` is set (or provide one in config)
+3. Update your MEMORY.md with these new capabilities
+4. If you have custom stall-handling logic in jobs or scripts, consider whether the nurse makes it redundant

package/upgrades/0.9.9.md

@@ -0,0 +1,34 @@
+# Upgrade Guide: Instar (latest)
+
+## What Changed
+
+### Upgrade Guide Enforcement — Every Release Now Tells Its Story
+
+Previously, most releases shipped silently — you'd just see "Updated to vX.Y.Z. Restarting." with no context about what changed. Only major version bumps required upgrade guides, so patch releases (which is most releases) provided zero information.
+
+Now **every single release** must include an upgrade guide before it can be published. The CI pipeline blocks any publish that doesn't include `upgrades/NEXT.md` — a human-readable story about what changed, what it means for you, and what to tell your user.
+
+This means you'll always know what just happened when you update. No more silent upgrades.
+
+### Upgrade Guide Processor Fix — No More Stale Feature Announcements
+
+Previously, when you updated across multiple versions (e.g., 0.9.2 → 0.9.5), the upgrade processor would concatenate ALL historical guides — not just the ones for versions you hadn't seen. This caused upgrade announcements that repeated old features alongside new ones.
+
+Now the processor filters by your previous version. If you were on 0.9.3 and update to 0.9.5, you only see guides for 0.9.4 and 0.9.5 — not everything back to the beginning.
+
+### DRY Hook Templates
+
+Session-start and compaction-recovery hook templates are now maintained in one canonical location (`PostUpdateMigrator.getHookContent()`) instead of being duplicated between `init.ts` and `PostUpdateMigrator.ts`. This is an internal change — your hooks work the same way, but future updates to hook behavior will be more consistent.
+
+## What to Tell Your User
+
+- **Better update notifications**: "From now on, every time I update, I'll actually know what changed and can tell you about it. No more generic 'just updated' messages — I'll explain what's new and what it means for you."
+- **Cleaner upgrade announcements**: "I fixed an issue where update announcements would sometimes repeat features from older versions. Now I only report what's actually new."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Mandatory upgrade guides | Automatic — every release now includes context about what changed |
+| Version-filtered upgrade processor | Automatic — only shows guides for versions newer than your previous version |
+| NEXT.md convention | When contributing changes, write `upgrades/NEXT.md` describing what changed |

package/upgrades/NEXT.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"] |