@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.10.8.md

@@ -0,0 +1,53 @@
+# Upgrade Guide — v0.10.8
+
+<!-- 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
+
+### Temporal Coherence Checker
+
+New module that detects when draft content reflects outdated thinking — perspectives the agent has since evolved past. Born from a real incident: a draft written weeks earlier used "death" framing for a concept the agent had since reframed as "choice," creating public incoherence.
+
+**`TemporalCoherenceChecker`** (`src/core/TemporalCoherenceChecker.ts`):
+- Compares draft content against agent identity documents (AGENT.md, reflections), published content timeline (PlatformActivityRegistry), and canonical state quick facts (CanonicalState)
+- Uses `IntelligenceProvider` for LLM-based evaluation with configurable severity capping
+- Returns structured results: `COHERENT`, `EVOLVED`, or `OUTDATED` assessment with specific issues
+- Gracefully degrades to "no issues" when no IntelligenceProvider is configured
+
+**Integration points:**
+- Standalone: `checker.check(draftContent)` → `TemporalCoherenceResult`
+- With PlatformActivityRegistry: Auto-loads published content timeline for comparison
+- With CanonicalState: Auto-loads agent's current positions on key topics
+- With CoherenceGate: Can be combined for layered pre-publish safety
+
+**Configuration:**
+- `stateDocuments`: Custom paths to identity documents (default: AGENT.md, .instar/reflections.md)
+- `maxSeverity`: Cap severity at WARN to prevent temporal checks from blocking (recommended)
+- `maxCharsPerDocument`: Control prompt budget (default: 2000)
+- `timelineWindowHours`: How far back to look in published content (default: 720 = 30 days)
+
+### Convergence Check — 7th Criterion
+
+The heuristic convergence check (`convergence-check.sh`) now includes a 7th criterion: **temporal_staleness**. Catches language patterns suggesting stale drafts ("I used to think", "back when I first", "my early understanding", "before I learned", etc.). Zero-cost pre-filter — no LLM calls.
+
+Updated both the template file and the PostUpdateMigrator inline fallback.
+
+## What to Tell Your User
+
+- **"Your agent won't accidentally post outdated thinking"**: If your agent's understanding has evolved since a draft was written, the temporal coherence checker catches the mismatch before publishing. Think of it as a "is this still what I think?" check.
+
+- **"The convergence check now catches 7 anti-patterns"**: The pre-messaging quality gate now includes temporal staleness detection alongside capability claims, commitment overreach, settling, experiential fabrication, sycophancy, and URL provenance.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Temporal coherence check (LLM) | `new TemporalCoherenceChecker(config)` then `checker.check(draft)` |
+| Temporal staleness heuristic | Automatic — included in convergence-check.sh criterion #7 |
+| Severity capping | Set `maxSeverity: 'WARN'` in config to prevent temporal blocking |
+| Published content timeline | Pass `activityRegistry` to auto-load comparison timeline |
+| Canonical state integration | Pass `canonicalState` to include quick facts in evaluation |

package/upgrades/0.10.9.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — v0.10.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
+
+**SemanticMemory disk I/O error now includes diagnostic guidance**: When SQLite fails to open `semantic.db` due to a disk I/O error (SQLITE_IOERR), the degradation report now includes actionable instructions — specifically to run `df -h` to check disk space and the path to the affected database file. Previously this was an opaque error message with no indication of how to recover.
+
+## What to Tell Your User
+
+- **Clearer disk errors**: If your knowledge graph fails to load with a disk error, Instar will now tell you exactly what to check and which file is affected. Makes it much easier to diagnose "disk full" situations.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Actionable SemanticMemory disk error messages | Automatic — shown in server startup output and Telegram alerts |

package/upgrades/0.11.0.md

@@ -0,0 +1,146 @@
+# Upgrade Guide — v0.11.0
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Playbook — Adaptive Context Engineering
+
+This is the biggest feature addition since the evolution system. Playbook gives you a living, adaptive knowledge base that makes every session smarter than the last.
+
+**The problem it solves:** Your CLAUDE.md and MEMORY.md are static — the same blob loads every time regardless of what you're doing. Over time, context that matters for one task drowns out context needed for another. And there's no way for the system to automatically learn which context actually helps.
+
+**What Playbook is:** A curated manifest of context items (facts, lessons, patterns, safety rules), each with metadata about *when* to load it (triggers), *how much* it costs (tokens), and *how useful* it's been (scores). The assembly engine selects only what's relevant for the current moment. The lifecycle engine scores what helped, decays what didn't, and deduplicates.
+
+### How to Set It Up
+
+**Step 1: Initialize**
+```bash
+instar playbook init
+```
+
+This creates the playbook directory structure at `.instar/playbook/` with a bootstrap manifest containing starter context items (safety rules, identity principles).
+
+**Step 2: Verify health**
+```bash
+instar playbook doctor
+```
+
+Doctor checks 7 dimensions: Python version, scripts availability, manifest integrity, HMAC signing, history chain, config, and schemas. All should pass.
+
+**Step 3: Add your first context item**
+
+Think about the most important lesson you've learned working with your user. Add it:
+
+```bash
+instar playbook add '{
+  "id": "/lessons/my-first-lesson",
+  "category": "lesson",
+  "content": "Description of the lesson",
+  "tags": {"domains": ["development"], "qualifiers": []},
+  "load_triggers": ["session-start"],
+  "tokens_est": 25,
+  "status": "active"
+}'
+```
+
+**Step 4: Check your manifest**
+```bash
+instar playbook status
+instar playbook list
+```
+
+**Step 5: Preview assembly**
+
+See what would load for a session-start trigger:
+```bash
+instar playbook assemble --triggers session-start
+```
+
+### Building Your Knowledge Base Over Time
+
+The real value of Playbook comes from accumulation. After each session, consider:
+
+1. **Did I learn something that cost time?** → Add it as a lesson item
+2. **Did I discover a pattern my user relies on?** → Add it as a pattern item
+3. **Did a safety issue arise?** → Add it as a safety item with `compaction` trigger
+4. **Is something in MEMORY.md critical enough to survive compaction?** → Migrate it to a Playbook item with appropriate triggers
+
+### Running the Lifecycle
+
+Periodically (or as a scheduled job), run:
+```bash
+instar playbook evaluate
+```
+
+This scores items based on usefulness, decays stale ones, catches near-duplicates, and screens for PII. Items that consistently help rise in assembly priority. Items that don't gradually fade.
+
+### Sharing Context Between Agents
+
+If you work alongside other agents, you can import their context:
+```bash
+instar playbook mount /path/to/other-agent/playbook/context-manifest.json --name shared-lessons
+```
+
+Mounts are integrity-verified (SHA-256 hash at mount time, verified on use). Only `global`-scoped items are accepted — user-specific context stays with its agent.
+
+### All CLI Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `instar playbook init` | Create playbook directory and bootstrap manifest |
+| `instar playbook doctor` | Health check (7 dimensions) |
+| `instar playbook status` | Manifest overview |
+| `instar playbook list` | All context items with metadata |
+| `instar playbook add '<json>'` | Add a context item |
+| `instar playbook search --tag <tag>` | Find items by tag |
+| `instar playbook assemble --triggers <t>` | Preview trigger-based assembly |
+| `instar playbook evaluate` | Run lifecycle (score, decay, dedup) |
+| `instar playbook validate` | Validate manifest against schema |
+| `instar playbook mount <path>` | Import context from another agent |
+| `instar playbook unmount <name>` | Remove a mounted context source |
+| `instar playbook export` | Export manifest |
+| `instar playbook import <path>` | Import manifest |
+| `instar playbook eject` | Copy bundled scripts to local directory for customization |
+| `instar playbook user-export --user-id <id>` | GDPR data export |
+| `instar playbook user-delete --user-id <id> --confirm` | GDPR right to erasure |
+| `instar playbook user-audit --user-id <id>` | Audit trail for a user |
+
+### Suggested Job for Lifecycle
+
+Consider adding a scheduled job to run lifecycle evaluation periodically:
+
+```json
+{
+  "slug": "playbook-lifecycle",
+  "schedule": "0 */8 * * *",
+  "enabled": true,
+  "execute": {
+    "type": "command",
+    "value": "instar playbook evaluate --json"
+  },
+  "gate": null,
+  "description": "Evaluate playbook: score usefulness, decay stale items, deduplicate"
+}
+```
+
+## What to Tell Your User
+
+- **"Your agent now has adaptive memory."** Instead of loading the same context blob every session, the agent curates a knowledge base of lessons, patterns, and facts — and selects what's relevant based on what it's doing. Over time, the system learns which context actually helps and prioritizes it.
+
+- **"Run `instar playbook init` to get started."** After that, the agent builds its knowledge base naturally as it works. No ongoing configuration needed.
+
+- **"Context can be shared between agents."** If you run multiple agents, they can import each other's lessons with integrity verification. Knowledge compounds across your whole fleet.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Adaptive context manifest | `instar playbook init` to start, items accumulate over time |
+| Trigger-based assembly | Items load based on session-start, public-action, compaction triggers |
+| Usefulness scoring | `instar playbook evaluate` — items that help rise, stale ones fade |
+| Cross-agent context sharing | `instar playbook mount <path>` with SHA-256 integrity verification |
+| GDPR/CCPA compliance | `instar playbook user-export/user-delete/user-audit` |
+| Manifest health check | `instar playbook doctor` — 7-dimension verification |
+| HMAC integrity | Cryptographic signatures prevent tampering, failsafe fallback |
+| 19 CLI commands | Full management via `instar playbook <command>` |

package/upgrades/0.12.0.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — v0.12.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
+
+Guided Setup with scenario-aware discovery pipeline. The setup wizard now automatically discovers agents, repos, and organizational context before asking the user questions.
+
+- **Discovery module** (`src/commands/discovery.ts`): 4-source agent scanning (local filesystem, registry with zombie validation, GitHub personal repos, GitHub org repos). Resolves into one of 8 scenarios via a 3-axis topology matrix (repo/standalone, single/multi-user, single/multi-machine).
+- **Setup refactored** (`src/commands/setup.ts`): Structured JSON context replaces ad-hoc strings. UNTRUSTED data delimiters for GitHub data passed to LLM wizard. Non-interactive mode (`--non-interactive`) for CI/CD with recovery key generation. File permissions (chmod 0600) on configs containing secrets.
+- **Wizard skill updated**: Privacy disclosure before data collection. Phase 0 rewired to parse structured JSON blocks. Scenario resolution table + step counter per scenario.
+- **Security**: Path traversal protection, name/URL validation, clone URL allowlist, graceful degradation when `gh` CLI unavailable.
+
+## What to Tell Your User
+
+- **Guided Setup**: "Setup is now smarter — it discovers your existing agents, repos, and team structure automatically before asking you anything. Run `instar setup` to try the new flow."
+- **CI/CD Support**: "You can now run `instar setup --non-interactive` for automated deployments. It generates a recovery key so you can resume if something goes wrong."
+- **Privacy**: "Setup now tells you exactly what data it will collect and why before scanning your GitHub repos."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Guided discovery | `instar setup` (automatic) |
+| Non-interactive setup | `instar setup --non-interactive` |
+| Agent discovery | `instar discover` (standalone) |
+| 8-scenario topology | Automatic — resolved from discovered context |

package/upgrades/0.12.1.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — v0.12.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+Setup wizard Entry Point B (no agent in CWD) now has improved agent listing consistency:
+- Every discovered agent in `merged_agents` appears in the AskUserQuestion options
+- Local agents shown as informational with "already running" explanation
+- GitHub agents listed with "Restore X" options
+- Prevents confusion when agents appear in summary text but not in choices
+
+## What to Tell Your User
+
+- **Setup wizard polish**: "The setup screen now clearly shows which agents you can restore from GitHub and which are already running locally. No more confusing mentions of agents without actions."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Improved wizard agent display | Automatic — just run `npx instar` |

package/upgrades/0.12.10.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.12.10
+
+## What Changed
+
+This release eliminates notification spam caused by restart loops and state loss:
+
+1. **AutoUpdater dedup state persistence**: `notifiedVersionMismatch` and `lastNotifiedRestartVersion` are now saved to the state file. Previously these were in-memory only, so every server restart reset the dedup counters, causing repeated "Just updated to vX.Y.Z" messages.
+
+2. **Lifeline rate limit persistence**: `lastServerDownNotifyAt` and `suppressedServerDownCount` are now written to `state/lifeline-rate-limit.json`. Previously, every restart reset the 5-minute rate limit, causing floods of "Server went down: Health check failed" messages.
+
+3. **Supervisor restart loop detection**: `ServerSupervisor.checkRestartRequest()` now tracks how many times it has restarted for a given target version via `state/restart-version-count.json`. After 2 restarts for the same version, it stops and logs "restart loop detected" instead of continuing the cycle.
+
+4. **Dashboard edit-in-place**: `TelegramAdapter.broadcastDashboardUrl()` now tries to edit the existing pinned message via `editMessageText` before falling back to send+pin. This eliminates unread badges on the Dashboard topic during server restarts. The message ID is persisted in `state/dashboard-message.json`.
+
+## What to Tell Your User
+
+- **No more notification spam**: "The firehose of repeated update and health check messages is fixed. The server now remembers what it already told you, even across restarts."
+- **Dashboard stays clean**: "The Dashboard topic won't show unread badges anymore. The link updates silently in place."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Persistent notification dedup | Automatic — no configuration needed |
+| Restart loop detection | Automatic — stops after 2 restarts for the same version |
+| Dashboard edit-in-place | Automatic — edits existing pinned message instead of posting new ones |

package/upgrades/0.12.11.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v0.12.11
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a notification loop bug in the auto-updater where `gatedRestart()` set the notification dedup state (`lastNotifiedRestartVersion`) in memory but never called `saveState()` before the process exited. On restart, the dedup state was lost, causing the "Just updated to vX.Y.Z. Restarting to pick up the changes." notification to repeat every ~5 minutes indefinitely.
+
+Three-layer fix:
+1. **State persistence before restart**: `saveState()` is now called inside `gatedRestart()` immediately before `requestRestart()`, ensuring dedup state survives process exit.
+2. **Restart cooldown (30 min)**: New `lastRestartRequestedAt` and `lastRestartRequestedVersion` fields are persisted. If a restart was already requested for the same version within 30 minutes, it's skipped entirely. This is a safety net for binary path mismatches (e.g., npx cache vs global install).
+3. **State fields persisted in auto-updater.json**: `lastRestartRequestedAt` and `lastRestartRequestedVersion` are now saved and loaded alongside the existing dedup fields.
+
+## What to Tell Your User
+
+- **Update notification fix**: "The repeated 'Just updated' notifications should stop now. The server was getting stuck in a restart loop because it forgot it had already notified you. That's fixed."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Notification dedup persistence | Automatic — no action needed |
+| Restart cooldown (30 min) | Automatic — prevents rapid restart cycling |

package/upgrades/0.12.12.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v0.12.12
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed the auto-updater notification spam loop. Three root causes addressed:
+
+1. **`lastAppliedVersion` set from `applyUpdate()` return value**: When `npm install -g` updated files in-place, `getInstalledVersion()` immediately returned the new version, causing `applyUpdate()` to return `newVersion: previousVersion` (the old version). The loop breaker (`lastAppliedVersion === latestVersion`) never matched because `lastAppliedVersion` was the old version. Fix: AutoUpdater now uses `targetVersion` (the version it intended to install) for the loop breaker, not the potentially-stale `result.newVersion`.
+
+2. **`getInstalledVersion()` read from disk on every call**: After `npm install -g` replaces files at the running binary's location, `getInstalledVersion()` would return the new version even though the running process has old code in memory. This caused `check()` inside `applyUpdate()` to return `updateAvailable: false`, leading to `restartNeeded: false` (no restart despite stale in-memory code). Fix: `getInstalledVersion()` now caches the version on first call, representing the actual running process version.
+
+3. **`restartNeeded: false` skipped restart for stale processes**: When `applyUpdate()` returned `restartNeeded: false` (due to the above issues), the AutoUpdater skipped `gatedRestart()`. But the running process had old code that needed replacing. Fix: AutoUpdater always calls `gatedRestart()` after a successful apply, since the in-memory code is always stale after an update. The existing loop breaker prevents infinite restart cycles.
+
+## What to Tell Your User
+
+- **Update notification spam fixed**: The repeated "Just updated to vX.Y.Z. Restarting to pick up the changes." messages every 5 minutes should stop after this update lands. The root cause was a version comparison bug that prevented the auto-updater from recognizing it had already applied the update.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Spam-free auto-updates | Automatic — no action needed |

package/upgrades/0.12.13.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.12.13
+
+<!-- bump: patch -->
+
+## What Changed
+
+Job topics that were eagerly created by versions before v0.12.7 (when `on-alert` became the default notification mode) are now cleaned up on startup. When `ensureJobTopics` runs, it detects stale topic mappings for jobs in `on-alert` or `never` mode, closes the Telegram forum topics, and removes the mappings from state. This eliminates the visual noise of empty job topics cluttering the Telegram group.
+
+The cleanup is idempotent — topics that are already closed or deleted are handled gracefully.
+
+## What to Tell Your User
+
+- **Quieter Telegram**: "Job topics that were created before the quiet-by-default update will be automatically cleaned up. Your Telegram group should be much less cluttered now — only jobs that actually need your attention will have topics."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Stale job topic cleanup | Automatic on startup — no action needed |

package/upgrades/0.12.14.md

@@ -0,0 +1,21 @@
+# Upgrade Guide — v0.12.14
+
+<!-- bump: patch -->
+
+## What Changed
+
+- **Coherence monitor notifications now show check names on first line.** Previously, the batched notification only showed "Coherence: 1 issue(s):" with the actual failed check names truncated (they were on the second line, which formatDigest drops). Now the first line reads e.g. "Coherence: config-parity failed (1 issue)" so the attention topic message is immediately informative.
+
+- **External process alerts reduced to once per 24 hours.** The OrphanProcessReaper was generating repeated alerts about external Claude processes (VS Code, terminal sessions) every digest cycle. These are normal processes and the alerts were noise. Now alerts fire at most once per 24h with a summary count and total memory, not individual PID listings.
+
+## What to Tell Your User
+
+- **Clearer attention messages**: "Coherence alerts in the attention topic now tell you *what* failed, not just that something failed. No more cryptic 'Coherence: 1 issue(s):' with no details."
+- **Less noise from external process alerts**: "You won't see repeated warnings about VS Code/terminal Claude processes anymore — those are normal and now only surface once a day."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Informative coherence alerts | Automatic — attention topic messages now include check names |
+| Quieter external process reporting | Automatic — 24h cooldown on external process alerts |

package/upgrades/0.12.15.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.12.15
+
+<!-- bump: patch -->
+
+## What Changed
+
+Notification messages sent to Agent Attention topics have been completely rewritten for clarity:
+
+1. **NotificationBatcher.formatDigest**: Removed the terse `--- Summary (N items) ---` headers and `CATEGORY:` grouping. Messages now show their full content in chronological order, making each notification self-contained and readable.
+
+2. **Coherence Monitor notifications**: Instead of `Coherence: output-sanity, readiness-auth-token failed (2 issues)`, each failure is now translated into a narrative explanation with a suggested action (e.g., "Security: API Unprotected — Your agent's API has no authentication token... Reply 'fix auth' to generate one.").
+
+3. **Orphan Process Reaper notifications**: Instead of `1 external Claude process(es) detected (231MB total). Use API /monitoring/processes to inspect.`, now says something like "Found 1 Claude process running outside your agent (using 231MB of memory). This is usually from VS Code... Reply 'clean processes' to free up the memory."
+
+4. **System Reviewer (Doctor) notifications**: Instead of `[DOCTOR] CRITICAL: Lifeline Supervisor failed`, now provides context like "Your agent's automatic restart system (lifeline) has stopped working... Reply 'fix lifeline' to restart it."
+
+## What to Tell Your User
+
+- **Clearer notifications**: "Your Agent Attention messages are now easier to understand. Instead of technical codes, you'll see plain-language explanations of what happened and what you can do about it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Narrative notifications | Automatic — all system notifications now use plain language |
+| Suggested actions in notifications | Reply to Agent Attention with the suggested command |

package/upgrades/0.12.16.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — v0.12.16
+
+<!-- bump: patch -->
+
+## What Changed
+
+1. **Narrative notification messages** (0.12.15): Notification messages in Agent Attention are now human-readable with plain-language explanations instead of technical codes.
+
+2. **Fix command handler** (0.12.16): Users can now reply directly to notification messages with suggested actions. The server handles these commands mechanically — no Claude session is spawned.
+
+Available fix commands (only work in the Agent Attention topic):
+- `fix auth` — Generate and save an API authentication token
+- `fix dashboard` — Generate a dashboard PIN
+- `fix shadow` — Remove local shadow installations blocking auto-updates
+- `fix output` — Re-run output sanity check and report results
+- `fix lifeline` — Provides instructions for restarting the lifeline
+- `clean processes` — Kill external Claude processes to free memory
+- `restart` — Request a graceful server restart
+- `restart sessions` — Find and clean up stuck sessions
+
+Commands are intercepted before session routing, so they're instant and free (no Claude API usage).
+
+## What to Tell Your User
+
+- **Reply to fix**: "When your agent reports an issue, it now suggests an action you can take. Just reply with the suggested command (like 'fix auth' or 'clean processes') and the agent will handle it automatically — no waiting for a session to start."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Narrative notifications | Automatic — all system notifications use plain language |
+| Fix commands | Reply to Agent Attention with the suggested command |
+| Instant command handling | Commands execute server-side — no Claude session needed |

package/upgrades/0.12.17.md

@@ -0,0 +1,38 @@
+# Upgrade Guide — v0.12.17
+
+<!-- bump: patch -->
+
+## What Changed
+
+1. **Autonomy profile system**: New `AutonomyProfileManager` with four levels (supervised, guided, autonomous, fully-autonomous). Agents can operate at different autonomy levels with corresponding notification and approval behaviors. Includes `AutonomySkill` for agents to self-assess and request elevation.
+
+2. **Trust elevation tracking**: `TrustElevationTracker` records trust-building events (successful jobs, user approvals, clean operations) and supports time-based decay. Feeds into autonomy profile decisions.
+
+3. **Dispatch scope enforcement**: `DispatchScopeEnforcer` ensures jobs only take actions within their declared scope. Prevents scope creep during autonomous operation.
+
+4. **Execution journal**: `ExecutionJournal` provides provenance tracking for all autonomous actions — what was done, why, and what the outcome was.
+
+5. **Pattern analyzer and reflection**: `PatternAnalyzer` identifies recurring patterns across job executions. `ReflectionConsolidator` and `JobReflector` enable structured learning from completed work. New `instar reflect` CLI command.
+
+6. **Autonomous evolution**: `AutonomousEvolution` subsystem for agents to propose and track their own improvements within trust boundaries.
+
+7. **Topic resume map**: `TopicResumeMap` enables session handoff by tracking which Telegram topics map to which sessions, supporting clean resume on respawn.
+
+8. **Auto-spawn history fix**: When a new session auto-spawns for a Telegram topic (both local and remote HTTP path), it now fetches JSONL thread history and includes it in the bootstrap message — matching the existing `respawnSessionForTopic` behavior. Previously, sessions spawned via the HTTP auto-spawn path had no conversation context.
+
+## What to Tell Your User
+
+- **Autonomy profiles**: "Your agent can now operate at different autonomy levels. Start supervised, and as trust builds through successful operations, the agent can handle more independently."
+- **Execution journal**: "Every autonomous action your agent takes is now logged with full provenance — you can always see what happened and why."
+- **Session continuity fix**: "When a session hands off to a new one, the new session now gets the full conversation history. No more 'what were we talking about?' moments."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Autonomy profiles | `GET /autonomy` dashboard, `POST /autonomy/profile` to set level |
+| Trust elevation | Automatic — tracks trust events over time |
+| Dispatch scope | Automatic — enforces declared job scopes |
+| Execution journal | `GET /journal` — full audit trail of autonomous actions |
+| Pattern analysis | `instar reflect` CLI command |
+| Auto-spawn history | Automatic — new sessions get thread context |

package/upgrades/0.12.18.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — v0.12.18
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Proactive Resume Heartbeat** — Previously, when a Telegram-linked session crashed unexpectedly (rather than being actively killed by the reaper), the Claude session UUID was lost because `persistResumeMapping` only ran at kill time. By then, the process was already dead and the UUID couldn't be discovered.
+
+Now, `TopicResumeMap.refreshResumeMappings()` runs every 60 seconds, continuously updating the topic-to-UUID mapping for all active topic-linked sessions. This means the resume map always has a recent UUID on file, even if the session crashes between heartbeats.
+
+Technical changes:
+- `TopicResumeMap`: Added `refreshResumeMappings(topicSessions)` method with tmux liveness checks and multi-session UUID deduplication
+- `TelegramAdapter`: Added `getAllTopicSessions()` to enumerate active topic-to-session mappings
+- `server.ts`: Wired 60s heartbeat interval that feeds topic sessions into the resume map
+- Constructor now accepts optional `tmuxPath` parameter
+
+## What to Tell Your User
+
+- **Session resume reliability**: "When your Telegram sessions restart, they now reliably resume from where they left off using claude --resume. Previously, if a session crashed unexpectedly, the next session would start fresh. Now the system continuously tracks session IDs so crashes don't lose context."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Proactive resume heartbeat | Automatic — runs every 60s for all topic-linked sessions |
+| `TopicResumeMap.refreshResumeMappings()` | Called by server heartbeat with `telegram.getAllTopicSessions()` |
+| `TelegramAdapter.getAllTopicSessions()` | Returns Map of topic-to-session mappings |

package/upgrades/0.12.19.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — v0.12.19
+
+<!-- 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
+
+Three-layer defense against post-compaction incoherent Telegram responses:
+
+1. **compaction-recovery.sh** now detects unanswered user messages in topic history after compaction. Uses `INSTAR_TELEGRAM_TOPIC` env var (set at spawn) with fallback to lifeline topic. Unanswered messages are surfaced with hard directives requiring substantive responses.
+
+2. **New `telegram-topic-context.sh` UserPromptSubmit hook** fires on every incoming `[telegram:N]` message. Fetches recent topic history from the Instar server API, formats it as conversation context, and detects unanswered user messages — preventing the "Hey! What's up?" failure after compaction or session restart.
+
+3. **PostUpdateMigrator** now installs the `telegram-topic-context.sh` hook and wires `UserPromptSubmit` into `.claude/settings.json` during migration. Idempotent — safe to run multiple times.
+
+The unanswered detection algorithm: walk messages chronologically, track consecutive user messages. Any agent response resets the queue. Whatever remains pending at end = unanswered messages that need substantive responses.
+
+## What to Tell Your User
+
+- **Smarter Telegram responses**: "Your agent now automatically reads recent conversation history before responding to Telegram messages. No more generic greetings after context compaction — the agent will address what you actually said."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Unanswered message detection (compaction) | Automatic — fires on compaction recovery |
+| Per-message Telegram context injection | Automatic — UserPromptSubmit hook on `[telegram:N]` messages |
+| UserPromptSubmit settings migration | Automatic — PostUpdateMigrator adds hook on next update |

package/upgrades/0.12.2.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — v0.12.2
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fix: Deterministic agent listing in setup wizard**
+
+The setup wizard's agent listing is now generated deterministically in setup.ts code, not by the LLM. Previously the wizard LLM would enumerate agents from JSON data and sometimes truncate the list (e.g., showing only 1 of 2 GitHub agents in the summary while correctly including both in the options). Now a pre-formatted `AGENT SUMMARY` block is passed to the wizard with instructions to display it verbatim.
+
+Technical: `buildAgentSummary()` in setup.ts generates the formatted text. The wizard skill.md instructs the LLM to display the `--- BEGIN AGENT SUMMARY ---` block as-is rather than generating its own listing.
+
+**Fix: Playbook commands (add, status, list, etc.) now correctly locate the manifest**
+
+The `PLAYBOOK_CONFIG` environment variable was not being set when Instar launched playbook Python scripts. Fixed by adding `makePlaybookEnv(stateDir)` helper.
+
+## What to Tell Your User
+
+- **Reliable agent listing**: "The setup screen now consistently shows all your agents — no more missing entries."
+- **Playbook commands fixed**: "The `instar playbook` commands were failing with a 'General error' — that's now fixed."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Deterministic agent summary | Automatic — run `npx instar` |
+| Playbook add/status/list working | Run `instar playbook status` or `instar playbook add --content "..."` |

package/upgrades/0.12.20.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — v0.12.20
+
+<!-- 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
+
+The setup wizard now presents both Telegram and WhatsApp as messaging options during Phase 3 (Messaging Setup), instead of assuming Telegram-only. Telegram remains the recommended default, but WhatsApp (Baileys or Business API) is offered as a first-class alternative. Phase 4g (WhatsApp Setup) now detects whether it's the primary choice or being added as a second channel and adjusts its flow accordingly.
+
+Wizard completeness tests updated to match the new phase naming (`Phase 3: Messaging Setup`).
+
+## What to Tell Your User
+
+- **Messaging choice during setup**: "You now get to choose between Telegram and WhatsApp when setting up your agent. Telegram is still recommended for its topic threads, but if you prefer WhatsApp, it's fully supported as your primary messaging platform."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| WhatsApp as primary messaging option | Choose option 2 during setup wizard Phase 3 |
+| Add second messaging channel | Available in reconfigure menu after initial setup |

package/upgrades/0.12.21.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — v0.12.21
+
+<!-- bump: patch -->
+
+## What Changed
+
+WhatsApp Baileys pairing is now fully automated during setup wizard. Instead of telling users to "check the server logs for a pairing code" and run `tmux attach`, the wizard now:
+
+1. Starts the server automatically
+2. Opens a browser with the dashboard QR code (or WhatsApp Web as fallback)
+3. Walks the user through scanning the QR with their phone
+4. Polls the connection status and confirms when paired
+5. Falls back to pairing code method if QR fails
+6. Falls back to manual relay of pairing code if no browser tools available
+
+The wizard also sends a WhatsApp greeting message after pairing (mirroring the Telegram Lifeline greeting), and does NOT declare "All done" until WhatsApp is actually connected.
+
+## What to Tell Your User
+
+- **WhatsApp setup is now hands-free**: "Setting up WhatsApp is now just as smooth as Telegram — the wizard handles everything automatically. You just scan a QR code when prompted."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Browser-automated WhatsApp QR pairing | Automatic during setup wizard when Baileys is selected |
+| WhatsApp greeting on setup completion | Automatic — agent introduces itself via WhatsApp |
+| QR → pairing code fallback | Automatic if QR scanning fails after 2 minutes |