@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.12.22.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v0.12.22
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed WhatsApp QR pairing flow in the setup wizard:
+
+- **Dashboard-first approach**: The wizard now navigates to the dashboard UI, authenticates with the PIN, and clicks the WhatsApp button to render the QR — instead of trying to hit `/whatsapp/qr` directly in the browser (which fails because that API requires Bearer auth headers that browsers can't pass via URL).
+- **QR initialization retry**: Added retry loop (up to 30 seconds) for when the WhatsApp adapter hasn't generated its first QR code yet after server start.
+- **Removed WhatsApp Web fallback**: WhatsApp Web creates a competing linked device session that conflicts with the Baileys adapter. The wizard no longer suggests opening web.whatsapp.com.
+- **API QR fallback**: If dashboard rendering fails, the wizard fetches QR data via curl with auth and renders it in the browser via JavaScript.
+
+## What to Tell Your User
+
+- **Smoother WhatsApp setup**: "The QR code pairing flow is more reliable now — it properly uses the dashboard to display the QR code."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Dashboard-based QR pairing | Automatic during setup — navigates to dashboard, authenticates, opens QR panel |
+| QR initialization retry | Automatic — waits up to 30s for adapter to generate first QR |

package/upgrades/0.12.23.md

@@ -0,0 +1,44 @@
+# Instar v0.12.23 — WhatsApp Setup Bug Fixes & Regression Tests
+
+## What Changed
+
+Three critical WhatsApp setup bugs fixed with comprehensive regression tests:
+
+1. **Baileys peer dependency resolution** — Replaced `require.resolve()` with dynamic `import()` for Baileys detection. `require.resolve()` fails in npx contexts because it resolves relative to the npx cache, not the user's project. Now tries both v6 (`@whiskeysockets/baileys`) and v7 (`baileys`) package names everywhere.
+
+2. **Baileys 405 infinite reconnect loop** — When WhatsApp returns HTTP 405 (protocol version mismatch), the backend now logs a clear error with upgrade instructions and does NOT attempt to reconnect. Previously this caused an infinite reconnect loop since 405 errors never resolve by retrying.
+
+3. **Dashboard QR polling silent failures** — The dashboard QR code polling now surfaces errors instead of silently returning null. Handles 401/403 with authentication failure messages, other HTTP errors with status codes, and network errors with connection failure messages.
+
+Added 22 regression tests covering all three issues.
+
+## What to Tell Your User
+
+- **WhatsApp setup reliability**: "WhatsApp pairing should work much more smoothly now — we fixed several issues that could cause the setup to fail silently or get stuck in loops."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Improved Baileys detection | Automatic — works in npx and global install contexts |
+| 405 error handling | Automatic — clear error message instead of infinite retry |
+| Dashboard QR error visibility | Automatic — errors now shown in dashboard UI |
+
+## Files Changed
+
+- `src/commands/whatsapp.ts` — New `isBaileysInstalled()` helper using dynamic import
+- `src/messaging/backends/BaileysBackend.ts` — v6/v7 import fallback + 405 error handling
+- `src/messaging/shared/EncryptedAuthStore.ts` — v6/v7 import fallback
+- `dashboard/index.html` — QR polling error surfacing
+- `src/server/AgentServer.ts` — Warning log for missing dashboard auth config
+- `tests/unit/whatsapp-setup-issues.test.ts` — 22 regression tests covering all 3 issues
+
+## How to Upgrade
+
+Updates are applied automatically via the AutoUpdater's shadow install mechanism. For manual upgrade:
+
+```bash
+npx instar@latest
+```
+
+No configuration changes required. All fixes are internal improvements to error handling and dependency resolution.

package/upgrades/0.12.24.md

@@ -0,0 +1,24 @@
+# Instar v0.12.24 — Mandatory Messaging Gate in Setup Wizard
+
+## What Changed
+
+Fixed a critical setup wizard bug where skipping Bitwarden/secret management caused the wizard to also skip messaging setup entirely. The wizard would declare "All done!" without ever asking the user to configure Telegram or WhatsApp.
+
+**Root cause:** The wizard agent interpreted "skip Bitwarden" as "skip everything downstream," including messaging. There was also an escape hatch in the completion section that allowed declaring setup complete without messaging.
+
+**Fixes:**
+1. Added explicit "CRITICAL GATE" language to Phase 3 stating that no previous skip cascades to messaging
+2. Added pre-completion checklist (Step 5d) that programmatically checks for messaging config before allowing "All done!"
+3. Changed the "no messaging configured" fallback from a graceful completion to a "GO BACK to Phase 3" instruction
+4. Added 5 regression tests for the mandatory messaging gate
+
+## What to Tell Your User
+
+- **Setup reliability**: "The setup wizard will now always walk you through messaging setup, even if you skip other optional steps like Bitwarden. Messaging is the whole point — it won't let you finish without it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Mandatory messaging gate | Automatic — wizard enforces messaging setup before completion |
+| Pre-completion checklist | Automatic — verifies messaging config exists before "All done!" |

package/upgrades/0.12.25.md

@@ -0,0 +1,55 @@
+# Instar v0.12.25 — Baileys v7 Migration & Complete WhatsApp Fix
+
+## What Changed
+
+**Migrated from Baileys v6 to v7** — the core fix for all WhatsApp setup failures.
+
+### Issue 1: Baileys dependency resolution
+- Moved from `@whiskeysockets/baileys` (v6, peer dependency) to `baileys` (v7, optional dependency)
+- v7 is now bundled with instar — no separate install needed
+- Import order changed: v7 tried first, v6 as fallback for backward compatibility
+
+### Issue 2: Connection failure detection
+- Fixed error detection for non-Boom errors (v6 used Boom, v7 may use plain Error objects)
+- Now checks `error.output.statusCode`, `error.statusCode`, `error.data.reason`, AND `error.message`
+- Terminal failures (405, 403, "Connection Failure") no longer trigger reconnect loops
+- Errors now surface via `setLastError()` on the adapter for dashboard display
+- Removed deprecated `printQRInTerminal` option
+
+### Issue 3: Pairing code timing
+- Moved `requestPairingCode()` inside the `connection: 'open'` handler
+- Previously called immediately after socket creation (before connection was stable)
+- Added try/catch with descriptive error message
+
+### Issue 4: Dashboard QR panel timeout
+- Added 30-second timeout for QR code appearance
+- Timeout shows clear error message with upgrade instructions
+- Dashboard now displays adapter error messages from the `/whatsapp/qr` endpoint
+- Added `escapeHtml` helper for safe error display
+- Poll responses now include `error` field from adapter status
+
+### Issue 5: Wizard pre-flight check
+- Added mandatory Baileys pre-flight check before WhatsApp configuration
+- Detects v6 (warns + upgrades), v7 (proceeds), or missing (installs)
+- Added QR timeout check with clear failure messaging and retry instructions
+- Added one-retry-then-offer-Telegram fallback
+
+### Testing
+- 37 regression tests covering all 5 issues (up from 22)
+- 20 setup wizard completeness tests
+- 57 total WhatsApp-related tests, all passing
+
+## What to Tell Your User
+
+- **WhatsApp now works**: "We've upgraded to the latest Baileys version. WhatsApp pairing should actually work now — the old version was incompatible with WhatsApp's current protocol."
+- **No manual install needed**: "Baileys is now included with instar. You don't need to install it separately."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Baileys v7 bundled | Automatic — included as optional dependency |
+| Terminal failure detection | Automatic — stops reconnect loops on 405/403/"Connection Failure" |
+| Dashboard error display | Automatic — errors shown in QR panel with 30s timeout |
+| Pairing code after connection | Automatic — requests pairing code only after connection is open |
+| Wizard pre-flight check | Automatic — verifies Baileys before WhatsApp setup |

package/upgrades/0.12.26.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — v0.12.26
+
+<!-- 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
+
+Fixed three critical WhatsApp setup bugs:
+
+1. **Baileys peer dependency resolution**: Replaced `require.resolve()` with dynamic `import()` for detecting Baileys. The old approach failed in npx contexts because `require.resolve()` resolves relative to the npx cache directory, not the user's project. All detection points now try both v6 (`@whiskeysockets/baileys`) and v7 (`baileys`) package names.
+
+2. **405 infinite reconnect loop**: When WhatsApp returns HTTP 405 (usually meaning the Baileys version is outdated and WhatsApp changed its protocol), the backend now logs a clear upgrade message and stops — no reconnection attempts. Previously this caused an infinite reconnect loop.
+
+3. **Dashboard QR polling silent failures**: The dashboard's QR code polling previously swallowed errors silently. Now surfaces 401/403 auth failures, HTTP errors with status codes, and network connection errors visibly in the UI.
+
+Added 22 regression tests covering all three issues.
+
+## What to Tell Your User
+
+- **WhatsApp setup reliability**: "WhatsApp pairing should work much more smoothly now — we fixed several issues that could cause the setup to fail silently or get stuck in loops."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Improved Baileys detection | Automatic — works in npx and global install contexts |
+| 405 error handling | Automatic — clear error message instead of infinite retry |
+| Dashboard QR error visibility | Automatic — errors now shown in dashboard UI |

package/upgrades/0.12.27.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.12.27
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed session resume reliability. The LLM resume validator was rejecting all resume attempts because it only sampled the last 4KB of Claude JSONL files — which typically contain progress/system entries without readable content. Now samples from both HEAD (first 16KB, containing the initial prompt) and TAIL (last 32KB), extracting from multiple entry types (message.content, type-based entries, slug fields).
+
+Additionally, resume UUIDs from the TopicResumeMap (authoritative source — saved at session kill time for the specific topic) now skip LLM validation entirely, since the mapping is already guaranteed correct.
+
+## What to Tell Your User
+
+- **Session resume works now**: When sessions are killed for inactivity and you send a new message, the session will properly resume where it left off instead of starting fresh every time.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Reliable session resume | Automatic — sessions killed for inactivity will resume via `--resume` when a new message arrives |

package/upgrades/0.12.28.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.12.28
+
+<!-- bump: patch -->
+
+## What Changed
+
+Added a pre-flight `ensureSqliteBindings()` check that runs once at server startup, before TopicMemory or SemanticMemory initialize. If `better-sqlite3`'s native bindings fail to load (the "Could not locate the bindings file" error that happens when Node.js version changes), the server now auto-rebuilds them immediately, so all SQLite subsystems start healthy.
+
+Previously, the auto-rebuild logic was embedded inside the TopicMemory initialization block, which is guarded by `if (telegram)`. Agents without Telegram configured would see SemanticMemory fail with a binding error because the rebuild never ran.
+
+## What to Tell Your User
+
+- **Improved startup reliability**: "Your agent's knowledge graph (SemanticMemory) now starts up cleanly even when the Node.js version has changed. No manual `npm rebuild` needed."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Auto-rebuild better-sqlite3 at startup | Automatic — runs before any SQLite subsystem initializes |

package/upgrades/0.12.29.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — v0.12.29
+
+<!-- bump: patch -->
+
+## What Changed
+
+### WhatsApp Baileys Robustness (preventing 405 errors)
+
+1. **Dynamic WA Web version fetching**: `BaileysBackend.connect()` now calls `fetchLatestWaWebVersion()` from Baileys before creating the socket. This prevents 405 (Method Not Allowed) errors caused by stale hardcoded protocol versions. Falls back gracefully to Baileys defaults if the fetch fails.
+
+2. **Platform identifier fix**: The browser config now defaults to `['Mac OS', 'Chrome', '14.4.1']` which maps to `Platform.MACOS`. Some Baileys versions defaulted to `Platform.WEB` which WhatsApp servers reject for new device pairing.
+
+3. **User-configurable overrides**: New `version` and `browser` fields in `BaileysConfig` allow users to override the protocol version and platform identifier without patching Baileys files. Set via `config.json` under the WhatsApp messaging config or nested `baileys` key.
+
+### Config.json backup protection
+
+Before running post-update migrations on server startup, `config.json` is now backed up to `config.json.backup`. This protects against accidental data loss if a migration or re-scaffold operation wipes the config.
+
+### Server restart command
+
+New `instar server restart [name]` command that handles service manager lifecycle correctly:
+- **macOS**: Uses `launchctl bootout` + `bootstrap` to properly cycle the launchd service
+- **Linux**: Uses `systemctl --user restart` for systemd
+- **No autostart**: Falls back to `stop` + `start`
+
+This solves the debugging problem where killing a launchd-managed server just caused it to respawn with the old code.
+
+## What to Tell Your User
+
+- **WhatsApp reliability**: "WhatsApp connections are now more resilient. The system automatically fetches the latest protocol version instead of relying on a hardcoded one that can go stale. This prevents the 405 connection failures we hit."
+- **Server restart**: "There's now an `instar server restart` command that handles launchd properly. No more zombie respawns when you need to restart with new code."
+- **Config safety**: "Your config.json is now backed up before any upgrade migration runs, so you won't lose your settings if something goes wrong."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Dynamic WA version fetch | Automatic — happens on every WhatsApp connect |
+| Custom WA version override | Set `version: [2, 3000, XXXXXXX]` in WhatsApp config |
+| Custom browser/platform override | Set `browser: ["Mac OS", "Chrome", "14.4.1"]` in WhatsApp config |
+| Server restart | `instar server restart [agent-name]` |
+| Config backup | Automatic — happens before post-update migration |

package/upgrades/0.12.3.md

@@ -0,0 +1,22 @@
+# Upgrade Guide — v0.12.3
+
+<!-- bump: patch -->
+
+## What Changed
+
+Setup wizard Entry Point B no longer uses `AskUserQuestion` for the agent selection step. The multichoice overlay in Claude Code's terminal was hiding the agent summary text above it, causing users to miss agents that were listed but visually truncated.
+
+The fix:
+- `buildAgentSummary()` now generates inline numbered options (e.g., "1. Restore bob", "2. Restore dude", "3. Start fresh") as part of the deterministic summary text.
+- The skill instructions now say "DO NOT use AskUserQuestion here" and instead tell the wizard to display the summary verbatim and wait for the user to type their choice.
+- This eliminates the overlay-hiding-context problem entirely.
+
+## What to Tell Your User
+
+- **Setup wizard improvement**: "The agent discovery screen now shows all your options inline instead of in a popup menu. Everything is visible at once — no more hidden agents."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Inline agent selection | Automatic — just run `npx instar` |

package/upgrades/0.12.31.md

@@ -0,0 +1,24 @@
+# v0.12.31 — Fix false "no response" stall notifications
+
+## What Changed
+
+**Bug fix: WhatsApp stall detector wasn't clearing on agent response.** When the agent sent a reply via WhatsApp, the stall tracker wasn't notified. This meant the 5-minute "no response" timer kept running even after the agent had already replied, generating false alerts.
+
+- Added `clearStallForChannel()` call in WhatsAppAdapter's `send()` method (matching TelegramAdapter behavior)
+- Handles both JID and raw channelId formats for reliable matching
+
+**Bug fix: Multiple pending messages caused duplicate stall alerts.** If a user sent several messages quickly (e.g., "Hey!", "Who is this?"), each created a separate pending entry. When the timeout fired, ALL of them would trigger separate "no response" notifications — spamming the user with 3+ identical alerts.
+
+- Added per-channel deduplication in `StallDetector.check()` — once one alert fires for a channel, all other pending entries for that channel are silently marked as alerted
+
+**3 new tests** covering per-channel deduplication scenarios.
+
+## What to Tell Your User
+
+Your WhatsApp stall notifications are now accurate. Previously, you might have seen "No response after 5 minutes" alerts even after the agent had already replied — especially if you sent multiple messages quickly. That's fixed now.
+
+## Summary of New Capabilities
+
+- Accurate stall detection for WhatsApp conversations
+- No more duplicate/false "no response" notifications
+- Stall detector deduplicates alerts per channel across all platforms

package/upgrades/0.12.32.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — v0.12.32
+
+<!-- bump: patch -->
+
+## What Changed
+
+### WhatsApp Self-Chat Support (Critical Fix)
+
+Two bugs were preventing personal agents from receiving messages sent from the user's own phone via self-chat:
+
+1. **LID JID handling**: WhatsApp's Linked Identity (LID) JID format (`272404173598970@lid`) doesn't contain a real phone number. `jidToPhone()` now returns `null` for `@lid` JIDs instead of extracting a meaningless number. The WhatsApp adapter maps `@lid` JIDs to the connected phone number stored during backend initialization.
+
+2. **fromMe filter replaced with outbound ID tracking**: The blanket `if (msg.key.fromMe) continue` filter was dropping ALL messages from the user's account, including self-chat commands. Since Baileys connects as a linked device, every message the user sends shows `fromMe=true`. Now, outbound message IDs are tracked in a `Set`, and only messages the *bot* sent are filtered — user-typed self-chat messages pass through.
+
+3. **Accept both notify and append message types**: The `messages.upsert` handler now accepts both `type=notify` (real-time incoming) and `type=append` (outbound echoes, self-chat). This ensures self-chat messages aren't dropped by the type filter.
+
+### PhoneUtils improvements
+
+- `jidToPhone()` returns `null` for `@lid` JIDs (prevents fake phone number extraction)
+- `isJid()` now recognizes `@lid` JIDs
+- New `isLidJid()` helper for explicit LID detection
+
+## What to Tell Your User
+
+- **Self-chat works**: "You can now send messages to yourself on WhatsApp and your agent will process them as commands. This is the primary use case for personal agents."
+- **No configuration needed**: "The fix is automatic — LID JIDs are mapped to your connected phone number."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Self-chat support | Send yourself a WhatsApp message — agent processes it |
+| LID JID mapping | Automatic — maps to connected phone number |
+| Outbound echo filtering | Automatic — bot's own messages are tracked and filtered |

package/upgrades/0.12.33.md

@@ -0,0 +1,62 @@
+# Upgrade Guide — v0.12.33
+
+<!-- bump: patch -->
+
+## What Changed
+
+### WhatsApp Group Support (Phase 1)
+
+Agents can now participate in WhatsApp group conversations. When added to a group, the agent can respond to @mentions or all messages (configurable per group).
+
+**Config:**
+
+```json
+{
+  "messaging": [{
+    "type": "whatsapp",
+    "config": {
+      "groups": {
+        "enabled": true,
+        "authorizedGroups": ["120363187170797617@g.us"],
+        "defaultActivation": "mention",
+        "maxContextMessages": 50,
+        "agentName": "Dude"
+      }
+    }
+  }]
+}
+```
+
+**Features:**
+- Group message authorization (`authorizedGroups` allowlist, empty = allow all)
+- Activation modes: `mention` (respond only when @mentioned) or `always` (respond to all messages)
+- Per-group activation overrides via `groupOverrides`
+- Text-based triggers: messages starting with agent name activate the agent in mention mode
+- Recent message context buffer (default 50 messages per group) — gives the agent conversation context when activated
+- Sender identification from `msg.key.participant` — proper attribution in groups
+- @mention detection from Baileys `contextInfo.mentionedJid`
+
+### BaileysBackend: Participant & Mention Forwarding
+
+The `messages.upsert` handler now extracts and forwards:
+- `msg.key.participant` — the sender's JID within group messages
+- `contextInfo.mentionedJid` — list of @mentioned users
+
+These are passed through the `onMessage` handler to the adapter.
+
+## What to Tell Your User
+
+- **Groups**: "Your agent can now be added to WhatsApp groups. Configure `groups.enabled: true` in your WhatsApp config, add authorized group JIDs, and choose whether the agent responds to @mentions only or all messages."
+- **Self-chat still works**: This builds on v0.12.32's self-chat support — private messaging and groups work simultaneously.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Group messaging | Set `groups.enabled: true` in WhatsApp config |
+| Group authorization | List group JIDs in `authorizedGroups` (empty = all) |
+| Mention activation | Default mode — agent responds when @mentioned |
+| Always-on activation | Set `defaultActivation: "always"` for responsive groups |
+| Per-group overrides | Use `groupOverrides: { "jid": { "activation": "always" } }` |
+| Agent name trigger | Set `agentName` to activate via text (e.g., "@Dude what's up?") |
+| Context buffer | Last N messages per group available as context |

package/upgrades/0.12.34.md

@@ -0,0 +1,59 @@
+# Upgrade Guide — v0.12.34
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Agent Identity Prefix (Default: On)
+
+Agent outbound messages are now prefixed with the agent's name for visual identity separation. Since Baileys connects as a linked device on the user's WhatsApp account, all agent messages previously appeared indistinguishable from user-typed messages. The prefix solves this.
+
+**Default behavior** (no config needed):
+
+> *[Agent]* The CI is green. Last deploy was 2 hours ago.
+
+**With custom agent name:**
+
+> *[Dude]* The CI is green. Last deploy was 2 hours ago.
+
+**Config:**
+
+```json
+{
+  "messaging": [{
+    "type": "whatsapp",
+    "config": {
+      "agentName": "Dude",
+      "prefixEnabled": true,
+      "messagePrefix": "*[Dude]* "
+    }
+  }]
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `agentName` | `"Agent"` | Agent display name, used in prefix and group mentions |
+| `prefixEnabled` | `true` | Prepend agent name to outbound messages |
+| `messagePrefix` | `"*[{agentName}]* "` | Custom prefix format (WhatsApp markdown supported) |
+
+To disable the prefix: set `prefixEnabled: false`.
+
+### Group Mention Fallback
+
+Group mention detection now falls back to the top-level `agentName` when `groups.agentName` is not set. Previously, text-based triggers (e.g., "@Dude what's up?") only worked if `agentName` was explicitly set inside the `groups` config block.
+
+## What to Tell Your User
+
+- **Prefix**: "Your agent's messages now show who sent them — look for the bold `[AgentName]` prefix at the start of each message. You can customize or disable this in your WhatsApp config."
+- **Existing users**: The prefix is on by default. If the user prefers unmarked messages, set `prefixEnabled: false`.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Agent identity prefix | Default on — messages start with `*[Agent]*` |
+| Custom agent name | Set `agentName: "YourName"` in WhatsApp config |
+| Custom prefix format | Set `messagePrefix: "🤖 *Bot:* "` for custom styling |
+| Disable prefix | Set `prefixEnabled: false` |
+| Group name fallback | Set `agentName` at top level — groups inherit it |

package/upgrades/0.12.4.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.12.4
+
+<!-- bump: patch -->
+
+## What Changed
+
+`AskUserQuestion` is now completely banned from the setup wizard. A new `## CRITICAL: NEVER Use AskUserQuestion` section at the top of the skill prohibits its use at any step. All choice points now use inline numbered text options with typed user responses.
+
+The previous fix (v0.12.3) only addressed Entry Point B. This fix applies the same pattern globally — every step that presents options now uses inline numbered text instead of the multichoice overlay.
+
+## What to Tell Your User
+
+- **Setup wizard improvement**: "All wizard choices now show inline instead of in popup menus. No more hidden or truncated text."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Overlay-free wizard | Automatic — just run `npx instar` |

package/upgrades/0.12.5.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — v0.12.5
+
+<!-- bump: patch -->
+
+## What Changed
+
+Silent updates: auto-updates are now completely invisible to the user unless active sessions will be interrupted.
+
+Three notification sources silenced:
+
+1. **AutoUpdater.gatedRestart()** — when no sessions are running, restart is now silent (console.log only, no Telegram). Previously always sent "Just updated to vX. Restarting to pick up the changes." even when nobody was working.
+
+2. **AutoUpdater.applyPendingUpdate()** — when no restart is needed, the "Just updated to vX" notification is now silent. Previously always sent a Telegram message.
+
+3. **Post-restart upgrade guide delivery** — the dedicated Claude session (UpgradeNotifyManager) that spawned after restart to message the user about "what's new" is disabled. The pending upgrade guide file is preserved and injected into the agent's context at the next natural session start via ContextHierarchy. No separate notification session is spawned.
+
+Notifications that STILL fire (correctly):
+- Pre-restart warning when sessions ARE active ("Server restarting in N seconds, M sessions will resume")
+- Forced restart after max deferral when sessions won't finish
+- Deferral warnings (first warning + final warning) for active sessions
+- Update failure notifications (so the user knows something went wrong)
+
+## What to Tell Your User
+
+- **Silent updates**: "Updates now happen completely in the background. You'll only be notified if an update needs to restart the server while you have active sessions running."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Silent updates | Automatic — updates no longer send notifications unless sessions are active |

package/upgrades/0.12.6.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — v0.12.6
+
+<!-- bump: patch -->
+
+## What Changed
+
+Jobs now default to **quiet mode** (`on-alert`). Instead of sending a Telegram notification on every job completion, jobs are silent unless:
+
+1. **The job failed** — failures always notify (via consecutive failure alerts)
+2. **The session signaled attention** — if the LLM running the job includes `[ATTENTION] reason` in its output, that triggers a notification
+
+The `telegramNotify` field on job definitions now accepts three values:
+- `true` — always notify on completion (legacy behavior, opt-in)
+- `false` — never notify
+- `"on-alert"` — only notify on failure or explicit attention signal (**new default**)
+
+When `telegramNotify` is undefined (the common case), it defaults to `"on-alert"`.
+
+**Topic creation is now lazy for on-alert jobs.** Topics are only created when the job actually has something to report, instead of being created eagerly at scheduler startup. This prevents a flood of empty job topics on fresh installs.
+
+**Attention protocol injection:** Job sessions in on-alert mode receive a preamble instructing the LLM to use `[ATTENTION] reason` when it finds something noteworthy. This gives the agent a way to break through quiet mode when it matters.
+
+## What to Tell Your User
+
+- **Quieter notifications**: "Jobs are now quiet by default. You'll only get notified when a job actually finds something that needs your attention or when something goes wrong. No more firehose of routine job completions."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Quiet job mode (default) | Automatic — all jobs default to on-alert mode |
+| Explicit always-notify | Set `"telegramNotify": true` in jobs.json for jobs you want to always hear from |
+| Attention signaling | Include `[ATTENTION] reason` in job output to break through quiet mode |
+| Lazy topic creation | Automatic — topics created only when needed |

package/upgrades/0.12.7.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — v0.12.7
+
+<!-- bump: patch -->
+
+## What Changed
+
+Two bug fixes that affect all agents.
+
+**SystemReviewer TypeError fixed.** The SystemReviewer was throwing `TypeError: Cannot read properties of undefined (reading 'includes')` in a burst pattern on startup. Root cause: the constructor spread `{ disabledProbes: undefined }` over the defaults, overriding the default `[]` array with `undefined`. Now the constructor filters out `undefined` values before merging, preserving all defaults.
+
+**Scheduler now enabled by default on fresh install.** `instar init` was creating configs with `scheduler.enabled: false`, meaning freshly initialized agents had jobs defined but none running. Git sync, health checks, and other default jobs were silently inactive until manually enabled. Fresh installs now start with `scheduler.enabled: true`.
+
+## What to Tell Your User
+
+- **SystemReviewer errors are resolved.** "Those TypeError bursts you may have seen from SystemReviewer on startup are fixed."
+- **For newly initialized agents**: "Jobs now run from the start. No need to manually enable the scheduler."
+- **For existing agents with scheduler disabled**: "If your agent was initialized before this version and you want scheduled jobs to run, set `scheduler.enabled: true` in your `.instar/config.json` and restart the server."
+
+## Summary of New Capabilities
+
+| Fix | What it does |
+|-----|-------------|
+| SystemReviewer TypeError | No more burst TypeError errors on startup — `disabledProbes` defaults correctly to `[]` |
+| Scheduler default | Fresh `instar init` creates agents with scheduler running immediately |

package/upgrades/0.12.8.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — v0.12.8
+
+<!-- bump: patch -->
+
+## What Changed
+
+Three fixes targeting notification spam from the update loop and lifeline:
+
+**1. Update Loop Breaker (AutoUpdater)**
+If `lastAppliedVersion` matches the detected latest version, the auto-updater now skips re-applying the update. This breaks the update→restart→detect→update loop that occurred when the restarted server's binary path didn't match the globally installed version (e.g., npx cache vs global install). A one-time notification is sent explaining the mismatch.
+
+**2. Restart Notification Dedup (AutoUpdater)**
+The "Just updated to vX" notification now only fires once per version, not on every restart attempt. Prevents the wall of identical "Just updated to v0.12.7. Restarting to pick up the changes." messages.
+
+**3. Lifeline Notification Rate Limiting (TelegramLifeline)**
+"Server went down: Health check failed" notifications are rate-limited to one per 30 minutes. Subsequent occurrences within the window are suppressed and counted. When the rate limit expires and a new alert fires, it includes the count of suppressed notifications.
+
+## What to Tell Your User
+
+- **Quieter updates**: "The server no longer spams notifications when updating. You'll see one update message, and if something goes wrong with the restart, one lifeline alert — not dozens."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Update loop prevention | Automatic — no more repeated update-restart cycles |
+| Restart notification dedup | Automatic — one notification per version |
+| Lifeline rate limiting | Automatic — max one "server down" alert per 30 minutes |

package/upgrades/0.12.9.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — v0.12.9
+
+<!-- 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
+
+- **Dashboard pin rotation**: Old pinned messages are unpinned before pinning the latest dashboard link, preventing pin clutter in the Dashboard topic.
+- **First-run mute guidance**: On first dashboard pin, a guidance message is sent explaining how to mute the Dashboard topic for a cleaner notification experience.
+- **Update loop breaker**: AutoUpdater now tracks `lastAppliedVersion` to prevent re-applying the same version in a loop.
+- **Lifeline rate-limiting**: "Server went down" notifications are rate-limited to 1 per 30 minutes to prevent notification spam during crash loops.
+- **Restart notification dedup**: "Just updated to vX" messages are sent only once per version, not on every restart.
+- **12 regression tests** for notification spam prevention scenarios.
+
+## What to Tell Your User
+
+- **Quieter notifications**: "Dashboard and restart notifications are now smarter — no more duplicate pins or repeated update messages. Your Telegram topics should be much less noisy."
+- **Mute guidance**: "When the dashboard first pins, you'll get a one-time tip on how to mute that topic if you prefer a quieter setup."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Dashboard pin rotation | Automatic — old pins cleared before new ones |
+| Mute guidance | Automatic — sent once on first dashboard pin |
+| Update loop prevention | Automatic — no action needed |
+| Notification rate-limiting | Automatic — server-down alerts max 1/30min |