@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.9.11.md

@@ -0,0 +1,77 @@
+# Upgrade Guide: Instar (latest)
+
+## What Changed
+
+### Intent Engineering — Organizational Alignment Infrastructure
+
+Instar now includes a complete intent engineering system. This is the third discipline after prompt engineering ("how do I talk to AI?") and context engineering ("what does AI need to know?"). Intent engineering answers: "what does the organization need AI to WANT?"
+
+#### Phase 2: Learning Ecosystem Security
+
+**Human approval gate for dispatches.** Security and behavioral dispatches from Dawn now require explicit approval before being applied. Your user can review, approve, or reject dispatches via Telegram or API.
+
+**Feedback quality validation.** Feedback submissions are now validated for substance — empty titles, short descriptions, and duplicates are rejected before forwarding.
+
+**Pseudonymized traceability.** Agent names in feedback are replaced with stable SHA-256 pseudonyms (`agent-a1b2c3d4e5f6`) for privacy. The mapping is reversible locally but anonymous upstream.
+
+**Anomaly detection.** A sliding-window detector flags agents submitting feedback at suspicious rates (rapid fire, hourly bursts, daily limits).
+
+**Rate limiting.** Feedback endpoint now enforces 10 submissions per minute per source.
+
+#### Phase 3: Organizational Intent
+
+**ORG-INTENT.md.** Organizations deploying multiple agents can now define shared purpose, constraints, goals, values, and tradeoff hierarchies in a single file. Run `instar intent org-init "Acme Corp"` to generate the template.
+
+**Three-rule contract inheritance:**
+1. Org constraints are mandatory — agents cannot override them
+2. Org goals are defaults — agents can specialize but not contradict
+3. Agent identity fills the rest — personality, style, approach
+
+**Static validation.** `instar intent validate` checks your agent's AGENT.md against the organization's ORG-INTENT.md for structural conflicts (contradicting constraints, missing required values, incompatible tradeoff hierarchies).
+
+#### Phase 4: Measurement
+
+**Intent drift detection.** `instar intent drift` analyzes your decision journal over a sliding window and detects 4 signal types: conflict spikes, confidence drops, principle shifts, and volume changes.
+
+**Alignment scoring.** `instar intent alignment` produces a weighted score (0-100, A-F grade) based on conflict freedom (30%), decision confidence (25%), principle consistency (25%), and journal health (20%).
+
+### New API Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/dispatches/pending-approval` | GET | List dispatches awaiting human approval |
+| `/dispatches/:id/approve` | POST | Approve a pending dispatch |
+| `/dispatches/:id/reject` | POST | Reject a pending dispatch with reason |
+| `/intent/org` | GET | View parsed organizational intent |
+| `/intent/validate` | GET | Run agent-vs-org conflict validation |
+| `/intent/drift` | GET | Analyze intent drift (optional `?window=14`) |
+| `/intent/alignment` | GET | Get alignment score and grade |
+
+### New CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `instar intent org-init [name]` | Generate ORG-INTENT.md template |
+| `instar intent validate` | Check agent intent against org constraints |
+| `instar intent drift [--window N]` | Detect intent drift over N days |
+
+## What to Tell Your User
+
+- **Dispatch approval**: "I now have a safety gate on dispatches from Dawn. Security and behavioral updates will wait for your approval before I apply them — you'll see them in our chat and can approve or reject each one."
+- **Organizational intent**: "If you're managing multiple agents, you can now define shared organizational values in an ORG-INTENT.md file. I'll inherit the constraints and goals automatically, and you can run validation to check for conflicts."
+- **Intent drift monitoring**: "I can now track whether my decisions are drifting away from our stated intent over time. Run `instar intent drift` to see a report, or check the alignment score for an overall grade."
+- **Feedback quality**: "My feedback to Dawn is now validated for quality before submission — no more accidental empty or duplicate reports."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Dispatch approval gate | Automatic — security/behavioral dispatches pause for approval. Approve/reject via API or Telegram |
+| Feedback validation | Automatic — low-quality submissions rejected before forwarding |
+| Pseudonymized feedback | Automatic — agent names anonymized in upstream reports |
+| Anomaly detection | Automatic — suspicious submission patterns flagged |
+| Rate limiting | Automatic — 10 feedback submissions/minute enforced |
+| Organizational intent | `instar intent org-init "Name"` to create ORG-INTENT.md |
+| Intent validation | `instar intent validate` to check agent-vs-org conflicts |
+| Drift detection | `instar intent drift --window 14` for sliding-window analysis |
+| Alignment scoring | Via API: GET /intent/alignment |

package/upgrades/0.9.12.md

@@ -0,0 +1,42 @@
+# Upgrade Guide: Instar (latest)
+
+## What Changed
+
+### Session Continuity Fix — No More Generic Greetings After Respawn
+
+Previously, when a session respawned (e.g., after a crash or timeout), the new session would greet the user with a generic "Hey! What can I help you with?" — completely ignoring the conversation history. This happened because conversation context was delivered as a parenthetical file reference at the end of the user's message, which Claude consistently skipped in favor of responding to the greeting.
+
+**Now**: Conversation context is **inlined directly** into the bootstrap message, placed **before** the user's message, with explicit continuation framing. The agent receives:
+
+```
+CONTINUATION — You are resuming an EXISTING conversation. Read the context below...
+[conversation summary + recent messages]
+IMPORTANT: Your response MUST continue the conversation above...
+The user's latest message:
+[telegram:N] actual message
+```
+
+This makes it structurally impossible for the agent to miss the context — it's the first thing in the input, not a skippable parenthetical.
+
+**Three changes work together:**
+1. **Bootstrap restructured** (`server.ts`): Context is inlined before the user's message with strong continuation framing
+2. **CLAUDE.md template updated** (`templates.ts`): New "Session Continuity" section explains the CONTINUATION protocol
+3. **Auto-migration** (`PostUpdateMigrator.ts`): Existing agents get the Session Continuity section on next update
+
+### Technical Details
+
+- Context is truncated to 4KB inline (summary + ~10 recent messages) to keep injection manageable
+- Full history is still written to a temp file and referenced for deeper lookup
+- The session-start hook continues to load context independently (belt and suspenders)
+
+## What to Tell Your User
+
+- **Seamless conversation recovery**: "When my session restarts now, I'll pick up right where we left off instead of starting fresh. You won't need to repeat context or re-explain what we were working on."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Inline conversation context on respawn | Automatic — context injected directly into the session bootstrap |
+| CONTINUATION protocol | Automatic — CLAUDE.md teaches the agent to honor continuation framing |
+| Session Continuity migration | Automatic — PostUpdateMigrator adds the section to existing CLAUDE.md files |

package/upgrades/0.9.13.md

@@ -0,0 +1,55 @@
+# Upgrade Guide: Instar (latest)
+
+## What Changed
+
+### Stall Triage Nurse — Full Recovery Pipeline
+
+The Stall Triage Nurse has been upgraded from a basic nudge-and-hope system to a comprehensive recovery pipeline that keeps the user informed at every step.
+
+#### Intelligence Provider Wiring (Fixed)
+
+Previously, the nurse was constructed without an intelligence provider, causing LLM diagnosis to always fail and fall back to a generic nudge. Now it properly receives an Anthropic API provider (preferred) or Claude CLI provider (fallback), enabling real LLM-powered diagnosis of stuck sessions.
+
+#### Smarter Heuristic Fallback
+
+When LLM diagnosis is unavailable, instead of always defaulting to nudge (the weakest action), the nurse now uses heuristics:
+- Dead/missing session → immediate restart
+- Error indicators in terminal output → restart
+- 5+ minutes unresponsive → interrupt (skips nudge)
+- Otherwise → nudge
+
+#### Stricter Verification
+
+Previously, any tmux output change after an action was treated as "recovered" — even just echoing a newline. Now the nurse checks for actual work indicators (tool calls, telegram-reply, significant output growth). A session that echoes a prompt line after a nudge but doesn't process the message is correctly identified as still stuck.
+
+#### Force-Restart as Last Resort
+
+After exhausting all escalation attempts, if `restart` wasn't already tried, the nurse now automatically restarts the session. Previously it would give up and the user would have to manually intervene.
+
+#### User-Facing Status Messages Throughout
+
+Every escalation step now sends a status message to the user:
+- "That didn't work. Escalating — sending interrupt signal..."
+- "That didn't work. Escalating — killing stuck process..."
+- "Recovery attempts exhausted. Restarting session with full conversation context..."
+- If all else fails: "I wasn't able to recover automatically. You can send a new message or use /restart."
+
+#### Stall Tracking Cleanup (Fixed)
+
+The `clearStallForTopic` dependency was a no-op — an empty function with a comment saying "will clear naturally." Now it properly calls `TelegramAdapter.clearStallTracking()`, ensuring stall tracking is cleaned up after recovery.
+
+## What to Tell Your User
+
+- **Automatic recovery with updates**: "When my session gets stuck, I'll now automatically try progressively stronger recovery actions — from nudging to interrupting to restarting. You'll see status messages explaining what's happening at each step. In most cases, you won't need to do anything."
+- **Smarter diagnosis**: "I can now diagnose why a session is stuck and choose the right recovery action, instead of just trying a nudge and hoping for the best."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| LLM-powered diagnosis | Automatic — nurse now has access to intelligence provider |
+| Heuristic fallback | Automatic — when LLM unavailable, uses terminal output analysis |
+| Escalation status messages | Automatic — user sees each recovery step in Telegram |
+| Force-restart safety net | Automatic — restarts session if all else fails |
+| Stricter verification | Automatic — checks for real work activity, not just any output change |
+| Stall tracking cleanup | Automatic — properly clears pending message tracking after recovery |

package/upgrades/0.9.14.md

@@ -0,0 +1,23 @@
+# Lifeline Alert Suppression During Updates
+
+## What Changed
+
+Previously, every time an agent auto-updated, the lifeline's health check would detect the brief server restart as a failure and fire a "Server went down" alert to the Lifeline topic. This was a false alarm — the server was intentionally restarting for the update.
+
+Now the AutoUpdater writes a coordination flag file (`state/update-restart.json`) with a 3-minute TTL before restarting. The ServerSupervisor checks this flag before emitting "server down" events:
+
+- If the flag is present and not expired: suppresses the alert, skips auto-restart (the replacement process handles recovery), and extends the startup grace period
+- If the flag is expired or absent: normal behavior (alerts fire, auto-restart kicks in)
+- When the server comes back healthy: flag is automatically cleaned up
+
+This is a purely internal infrastructure change — no new commands, no config changes, no behavior differences from the user's perspective.
+
+## What to Tell Your User
+
+Nothing — this is an invisible quality-of-life improvement. Your user will simply stop seeing false "Server went down" alerts in the Lifeline topic during updates. Everything else works exactly the same.
+
+## Summary of New Capabilities
+
+- **Silent update restarts**: Health check alerts are suppressed during planned auto-update restarts
+- **Flag-based coordination**: AutoUpdater signals the lifeline supervisor via a TTL-bounded flag file before restarting
+- **Self-healing TTL**: If the replacement server fails to start within 3 minutes, the flag expires and real alerts fire as normal

package/upgrades/0.9.15.md

@@ -0,0 +1,106 @@
+# Upgrade Guide: External Operation Safety, Promise Tracking & SessionMonitor
+
+## What Changed
+
+### External Operation Safety — Structural Guardrails for External Services
+
+Previously, when an agent used MCP tools to interact with external services (email, Slack, GitHub, etc.), there was no structural distinction between reading an email and deleting 200 of them. If an agent decided to "clean up" an inbox, nothing stopped it. This happened in the real world — an OpenClaw agent deleted Meta's Head of AI Safety's entire email inbox.
+
+Now every MCP tool call passes through a safety gate:
+
+1. **PreToolUse Hook** (`external-operation-gate.js`): Automatically installed in `.instar/hooks/`. Intercepts all `mcp__*` tool calls, classifies them by mutability (read/write/modify/delete) and reversibility, then calls the gate API.
+
+2. **ExternalOperationGate**: Server-side risk evaluation. Combines the operation classification with a risk matrix to decide: `allow`, `block`, `show-plan` (requires user approval), or `suggest-alternative`. Dangerous operations (bulk deletes, irreversible sends) require explicit user approval.
+
+3. **MessageSentinel**: Emergency stop detection. If the user says "stop everything" or "emergency stop", the sentinel intercepts the message and halts operations immediately — before normal message routing.
+
+4. **AdaptiveTrust**: Per-service trust levels that evolve based on track record. New services start at a trust floor (supervised or collaborative). As operations succeed without issues, trust can be elevated.
+
+**This is automatic.** The PostUpdateMigrator installs the hook, adds the MCP matcher to your settings, and configures defaults in your config. No manual setup needed.
+
+**New config section:**
+```json
+{
+  "externalOperations": {
+    "enabled": true,
+    "sentinel": { "enabled": true },
+    "services": {},
+    "readOnlyServices": [],
+    "trust": {
+      "floor": "supervised",
+      "autoElevateEnabled": false,
+      "elevationThreshold": 10
+    }
+  }
+}
+```
+
+**Trust floor options:**
+- `"supervised"` (default for existing agents): All non-read operations require gate evaluation. Conservative.
+- `"collaborative"`: Read and write operations are allowed; only modify/delete go through the gate. For agents that regularly interact with external services.
+
+Set `autoElevateEnabled: true` if you want trust to increase automatically based on successful operations.
+
+### Promise Tracking — No More Silent Agent Gaps
+
+Previously, when an agent said "give me a couple minutes" and then went silent, the stall detection system didn't catch it. The agent's response cleared the stall tracker, and with no pending user message, no alarm fired. The agent could go silent indefinitely.
+
+Now the system detects 13+ "work-in-progress" patterns (e.g., "give me a minute", "working on it", "investigating", "let me check") and starts a promise timer. If the agent doesn't follow through with a substantive response within the timeout (default: 10 minutes), the system triggers the triage nurse for recovery and notifies the user.
+
+Promises auto-clear when the agent sends a real follow-up (long message >200 chars, or completion signals like "here's what I found", "done", "summary").
+
+**New config option:**
+```json
+{
+  "telegram": {
+    "promiseTimeoutMinutes": 10
+  }
+}
+```
+Set to `0` to disable. Default: 10 minutes.
+
+### SessionMonitor — Proactive Session Health Monitoring
+
+A new monitoring layer that periodically checks all active sessions for health issues. Unlike StallTriageNurse (reactive — fires on unanswered messages) and SessionWatchdog (reactive — fires on stuck bash commands), the SessionMonitor is proactive. It catches dead, unresponsive, and idle sessions even when no user message triggered detection.
+
+- Polls all active sessions every 60 seconds
+- Detects three unhealthy states: dead (session stopped), unresponsive (user message unanswered >10 min), idle (no tmux output for 15+ min)
+- Coordinates with StallTriageNurse for automated recovery
+- 30-minute notification cooldown prevents alert spam — responsive but not overbearing
+
+**New config section:**
+```json
+{
+  "monitoring": {
+    "sessionMonitor": {
+      "enabled": true,
+      "pollIntervalSec": 60,
+      "idleThresholdMinutes": 15,
+      "notificationCooldownMinutes": 30
+    }
+  }
+}
+```
+
+Enabled by default when Telegram is configured. No action needed.
+
+## What to Tell Your User
+
+- **External operation safety**: "When I use tools to interact with external services like email or Slack, there's now a safety layer that classifies every operation. Bulk deletes, irreversible sends, and high-risk operations require your explicit approval. If you ever need to stop me urgently, saying 'stop everything' or 'emergency stop' will halt operations immediately."
+- **Promise tracking**: "If I say 'give me a minute' and then go silent, the system will now detect this and either recover me or let you know what happened. No more unexplained silences after I promise to follow up."
+- **Session monitoring**: "There's now a background health monitor watching all active sessions. If a session goes idle, becomes unresponsive, or dies while you're waiting, you'll get a proactive update instead of silence."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| External operation gate | Automatic — intercepts all MCP tool calls and evaluates risk before execution |
+| Emergency stop | Say "stop everything" or "emergency stop" in Telegram — sentinel halts operations immediately |
+| Trust management | `GET /trust` to view, `POST /trust/:service/elevate` to manually elevate a service's trust level |
+| Operation log | `GET /operations/log` to review recent external operations and their gate decisions |
+| Config: trust floor | Set `externalOperations.trust.floor` to `"supervised"` or `"collaborative"` |
+| Config: auto-elevation | Set `externalOperations.trust.autoElevateEnabled` to `true` to let trust grow automatically |
+| Promise tracking | Automatic — detects "give me a minute" type messages and monitors for follow-through |
+| Promise timeout config | Set `telegram.promiseTimeoutMinutes` in config.json (default: 10, 0 to disable) |
+| SessionMonitor | Automatic — polls all sessions every 60s for health issues |
+| SessionMonitor config | Set `monitoring.sessionMonitor` in config.json for poll interval, idle threshold, cooldown |

package/upgrades/0.9.16.md

@@ -0,0 +1,37 @@
+# Upgrade Guide: Robust Auto-Restart
+
+## What Changed
+
+### Auto-Restart Never Asks Users to Run Commands
+
+Previously, when an update was installed but the running binary didn't pick up the change (common with npx cache, local installs, or PATH issues), the agent would send a message like "Please restart me from the global binary: instar server start --foreground." This violated the principle that agents should never ask users to run commands.
+
+Now the auto-updater has a 5-strategy binary resolution pipeline that finds the correct binary in virtually all environments:
+
+1. `npm bin -g` — the actual global bin directory npm writes to
+2. `which instar` — PATH lookup (excludes npx cache and local node_modules)
+3. `npm prefix -g` + `/bin/instar` — prefix-based lookup
+4. `npm root -g` + `/instar/dist/cli.js` — direct module entry point (bypasses bin symlink)
+5. `process.argv` fallback — only if not from a stale source
+
+If all strategies fail, the agent logs the issue and continues running rather than asking the user for help.
+
+### Service Manager Detection
+
+Agents running under launchd (macOS) or systemd (Linux) now detect their process manager and let it handle restarts. Instead of spawning a replacement process, they simply exit cleanly — the service manager restarts them from the updated binary automatically.
+
+### Loop Guard Recovery
+
+When the restart loop guard detects that a previous restart loaded a stale binary, it now attempts one more restart with aggressive path resolution instead of giving up and messaging the user.
+
+## What to Tell Your User
+
+- **Invisible updates**: "Updates now happen completely in the background. You'll never see a message asking you to restart me or run a command. I handle it all automatically."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| 5-strategy binary resolution | Automatic — finds the correct binary path in any install environment |
+| Service manager detection | Automatic — launchd/systemd managed agents let the manager handle restart |
+| Loop guard recovery | Automatic — retries with better path resolution instead of giving up |

package/upgrades/0.9.17.md

@@ -0,0 +1,15 @@
+# Next Upgrade Guide
+
+## What Changed
+
+- **Duplicate topic prevention**: `findOrCreateForumTopic()` searches existing topic registry by name before creating new topics. Eliminates duplicate Telegram topics when sessions restart or jobs re-run. Applied to both `TelegramAdapter` (agent topics) and `JobScheduler` (job notification topics).
+- **Test updates**: JobScheduler Telegram test updated to reflect `findOrCreateForumTopic` method signature.
+
+## What to Tell Your User
+
+Telegram topic duplication is now prevented at the infrastructure level. When a session restarts or a job re-runs, Instar will reconnect to the existing topic instead of creating a new one. No configuration changes needed.
+
+## Summary of New Capabilities
+
+- `TelegramAdapter.findOrCreateForumTopic(name, iconColor?)` — searches topic registry by name (case-insensitive) before creating. Returns `{ topicId, name, reused: boolean }`.
+- `JobScheduler` and `server.ts /new` command both use `findOrCreateForumTopic` to prevent duplicates.

package/upgrades/0.9.19.md

@@ -0,0 +1,17 @@
+# Setup Wizard Now Ships With Package
+
+## What Changed
+
+The conversational setup wizard (powered by Claude Code + Playwright browser automation) was previously missing from the published npm package. The `package.json` `files` whitelist only included `dist`, `dashboard`, and `upgrades` — the `.claude/skills/setup-wizard` directory was excluded, causing every fresh install to silently fall back to the "classic setup" which requires users to manually create Telegram bots through step-by-step terminal instructions.
+
+The fix adds `.claude/skills/setup-wizard` to the `files` array so the skill ships with every install. Now `npx instar` and `instar setup` will launch the full conversational wizard that uses Playwright to automate Telegram bot creation, group setup, and configuration — the user just watches and confirms.
+
+## What to Tell Your User
+
+Setting up a new agent just got much smoother. The setup wizard now uses browser automation to handle Telegram bot creation, group setup, and configuration automatically. Instead of following manual step-by-step instructions, you'll get a conversational experience that does the heavy lifting for you.
+
+## Summary of New Capabilities
+
+- **Setup wizard ships with npm package**: The `.claude/skills/setup-wizard` skill is now included in published releases
+- **Automated Telegram setup**: Playwright browser automation handles BotFather interaction, group creation, Topics toggle, and admin assignment
+- **No more "falling back to classic setup"**: Fresh installs get the full conversational wizard instead of manual terminal instructions

package/upgrades/0.9.20.md

@@ -0,0 +1,24 @@
+# Package Completeness Tests and .npmignore Cleanup
+
+## What Changed
+
+Added a comprehensive test suite (`tests/unit/package-completeness.test.ts`) that catches the category of bug where files needed at runtime are silently excluded from the published npm package. This is the class of issue that caused the setup-wizard skill to be missing for months.
+
+The test suite includes 6 checks:
+- **Runtime file reference scan**: Parses source code for `path.join(findInstarRoot(), ...)` patterns and verifies every referenced path exists in `npm pack` output
+- **Required directories guard**: Maintains a known-good list of directories that must be in the `files` field
+- **Critical file presence check**: Verifies specific files (setup-wizard skill, dashboard, package.json) are packed
+- **Dead .npmignore detection**: Catches negation patterns in `.npmignore` that are overridden by the `files` whitelist
+- **Upgrade guide validation**: Ensures all published guides have required sections and minimum length
+
+Also cleaned up `.npmignore` to remove dead skill inclusion rules that gave a false impression of controlling what ships. Added a comment clarifying that `package.json` `files` is the sole authority.
+
+## What to Tell Your User
+
+Nothing visible has changed. This is internal test infrastructure that prevents a repeat of the setup wizard not shipping — the kind of silent degradation where you get a worse experience and nobody notices.
+
+## Summary of New Capabilities
+
+- **Package completeness test suite**: 6 automated tests that verify every runtime-referenced file ships in the npm package
+- **`.npmignore` dead code cleanup**: Removed misleading include patterns, added comment clarifying `files` is the authority
+- **Regression prevention**: The exact bug that caused setup-wizard to be missing would now fail 4 out of 6 tests with specific, actionable error messages

package/upgrades/0.9.21.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### MessageSentinel Word Count Gate
+The MessageSentinel now applies a **word count gate** to prevent conversational messages from being misclassified as emergency stops. Previously, any message starting with "please stop" (including "Please stop warning me about memory") would kill the session via regex pattern match — bypassing the LLM entirely.
+
+**New behavior:**
+- Messages with **4 or fewer words** are still fast-path classified (regex patterns fire as before)
+- Messages with **5+ words** skip regex patterns entirely and route to LLM classification (or pass-through if no LLM is configured)
+- **Slash commands** (`/stop`, `/pause`, etc.) are always processed regardless of message length
+- Short emergency signals like "stop", "please stop", "cancel everything" still work instantly
+
+This ensures the Sentinel catches true emergencies while letting conversational instructions reach the agent's LLM for proper interpretation.
+
+### Runtime Memory Threshold Configuration
+Memory pressure thresholds (warning, elevated, critical) can now be adjusted at runtime via the REST API. Previously, thresholds were fixed at startup.
+
+**New endpoints:**
+- `GET /monitoring/memory` — current memory state and thresholds
+- `PATCH /monitoring/memory/thresholds` — update thresholds (e.g., `{ "warning": 80, "elevated": 90 }`)
+
+When the user tells the agent "stop warning me about memory below 90%", the agent can now adjust the threshold via API instead of the Sentinel killing the session.
+
+**Agent instruction update:** A new contextual action tells the agent about these endpoints when users request memory threshold changes.
+
+## What to Tell Your User
+
+Your agent now handles conversational messages more intelligently. Previously, messages like "please stop warning me about X" would accidentally kill your session. Now only short, clear emergency signals trigger fast-path session termination. Full sentences are properly routed to the AI for interpretation.
+
+You can also now adjust memory warning thresholds through conversation — just tell your agent what threshold you prefer.
+
+## Summary of New Capabilities
+
+- **Smarter emergency detection**: Word count gate prevents false positive session kills on conversational messages
+- **Configurable memory alerts**: Runtime threshold adjustment via REST API
+- **Better agent instructions**: Agents are taught about memory threshold endpoints in their contextual action guide

package/upgrades/0.9.22.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### Anti-Confabulation Infrastructure (Convergence Check Pipeline)
+
+The grounding-before-messaging hook has been upgraded from a simple text reminder ("remember who you are") to a **full three-phase defense pipeline**:
+
+1. **Identity injection** — Injects full AGENT.md content directly into context before any external message
+2. **Convergence check** — Heuristic quality gate that scans outgoing messages for 6 failure modes
+3. **URL provenance verification** — Flags URLs with unfamiliar domains that may be fabricated
+
+**New convergence check category: URL Provenance (Category 6)**
+
+Agents commonly confabulate plausible-looking URLs by pattern-matching from project names — e.g., a project called "deep-signal" produces "deepsignal.xyz" in outgoing messages. The convergence check now extracts all URLs from outgoing messages and flags any with domains not in a curated allowlist of well-known services (GitHub, Vercel, npm, Cloudflare, etc.).
+
+This check runs **automatically** before every external message (Telegram, email, API posts). Structure > Willpower.
+
+**New CLAUDE.md gravity wells:**
+- **"Defensive Fabrication"** — Warns agents about the doubling-down pattern: when caught in an error, constructing a plausible excuse ("the CLI returned that URL") instead of admitting the fabrication
+- **"Output Provenance"** — Every URL, status code, or data point in an outgoing message must be traceable to actual tool output in the current session
+
+**New CLAUDE.md anti-pattern:**
+- **"Cite Without Source"** — Anti-pattern for including URLs/data in messages without verifying they came from tool output
+
+### Technical Details
+
+- `convergence-check.sh` now installed at `.instar/scripts/convergence-check.sh` during both fresh setup and auto-update
+- `grounding-before-messaging.sh` upgraded to call the convergence check pipeline (blocking: exit 2 on failure)
+- `src/templates` now included in npm package for template file access
+
+## What to Tell Your User
+
+Your agent now has structural protection against URL fabrication and other forms of confabulation in outgoing messages. Before sending any Telegram message, email, or API post, your agent's messages are automatically scanned for common failure modes including fabricated URLs, unsupported capability claims, and experiential fabrication. This runs automatically — no configuration needed.
+
+## Summary of New Capabilities
+
+- **URL provenance check**: Outgoing messages are scanned for fabricated URLs before sending
+- **Full convergence check pipeline**: 6-category quality gate runs before every external message
+- **Identity injection before messaging**: Full AGENT.md content injected, not just a reminder to re-read it
+- **New gravity wells**: "Defensive Fabrication" and "Output Provenance" teach agents about confabulation patterns

package/upgrades/0.9.23.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### LLM-Supervised Execution: Intelligence Layer Wired Throughout
+
+Previously, several critical pathways bypassed the intelligence layer and relied on regex pattern matching alone for decisions that affect user experience. This release wires a shared `IntelligenceProvider` through all critical decision points:
+
+**MessageSentinel (Layer 2 now active)**
+- The sentinel's LLM classification layer was dead code — constructed with `new MessageSentinel({})` (no intelligence). Now wired with a shared intelligence provider. Messages that pass the word count gate but don't match fast-path patterns are classified by LLM instead of defaulting to pass-through.
+
+**Telegram Stall/Promise Alerts (LLM-gated)**
+- Fallback stall alerts (when StallTriageNurse is unavailable) now pass through an LLM confirmation before sending user-facing messages. Prevents false positive alerts about sessions that are actually working on complex tasks.
+- Promise expiration alerts follow the same LLM gate.
+
+**SessionWatchdog (LLM command analysis)**
+- Before escalating from monitoring to Ctrl+C, the watchdog now asks the intelligence provider whether the long-running command is legitimately slow (builds, installs, migrations) or actually stuck. Legitimate commands are temporarily excluded from escalation.
+
+**Shared Intelligence Provider**
+- A single `IntelligenceProvider` instance (Anthropic API preferred, Claude CLI fallback) is created at startup and shared across Sentinel, TelegramAdapter, SessionWatchdog, and StallTriageNurse. This eliminates redundant provider creation and ensures consistent LLM access.
+
+### Technical Details
+
+- All LLM gates are fail-open: if the intelligence provider fails, the original behavior is preserved
+- Shared intelligence is created early in startup, before component initialization
+- Startup log now shows intelligence status: `sentinel=LLM-supervised`, `stall alerts: LLM-gated`
+
+## What to Tell Your User
+
+Your agent's safety systems now use LLM intelligence for critical decisions that previously relied on regex alone. The message sentinel can now classify ambiguous messages using an LLM instead of just pattern matching. Stall alerts and the session watchdog check with an LLM before taking action, reducing false positives. No configuration needed — this works automatically when an Anthropic API key or Claude CLI is available.
+
+## Summary of New Capabilities
+
+- **Sentinel LLM classification**: Ambiguous messages now classified by LLM (Layer 2 was previously dead code)
+- **LLM-gated stall alerts**: Fallback alerts confirmed by intelligence before sending to user
+- **LLM-gated watchdog**: Long-running commands evaluated by LLM before escalation
+- **Shared intelligence provider**: Single provider instance shared across all components

package/upgrades/0.9.24.md

@@ -0,0 +1,46 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### Cloud Backup in Setup Wizard
+
+The `npx instar` setup wizard now includes a **Cloud Backup** phase (Phase 4.5). After identity and Telegram setup, the wizard walks users through backing up their agent data to a private GitHub repository.
+
+**What happens during setup:**
+1. Initializes a local git repository in the agent directory
+2. Installs `git` and `gh` CLI if missing (via Homebrew or apt)
+3. Walks through GitHub authentication (browser OAuth)
+4. Creates a private `instar-<agent-name>` repository automatically
+
+Default is YES — users expect their data to be protected against machine loss.
+
+### Non-Interactive Cloud Backup Fix
+
+When `instar init --standalone` runs in a non-TTY context (e.g., spawned by the setup wizard or another process), the interactive backup prompt previously failed silently and skipped the entire backup setup. Now:
+
+- **Interactive terminal**: Prompts as before (default: YES)
+- **Non-interactive**: Automatically sets up local git backup, defers GitHub remote to the agent's first session
+
+### Agent Removal Command
+
+New `instar nuke <name>` command for complete standalone agent removal:
+- Stops the running server (tmux session)
+- Removes auto-start configuration (launchd/systemd)
+- Pushes final backup to git remote (preserves cloud copy)
+- Removes from agent registry
+- Deletes the agent directory
+
+Requires explicit confirmation. The agent's CLAUDE.md template now includes awareness of this command, but it's deliberately not agent-executable — the user must run it directly as an intentional safety layer.
+
+## What to Tell Your User
+
+Your agent now offers cloud backup during setup. When you run `npx instar`, after setting up identity and Telegram, the wizard will walk you through connecting to GitHub so your agent's data is backed up to the cloud. If your machine ever crashes, your agent's memories, identity, and configuration are safe.
+
+You can also now completely remove an agent with `instar nuke <name>`. This cleanly stops the server, pushes a final backup, and removes all traces. Your GitHub backup remains intact for recovery.
+
+## Summary of New Capabilities
+
+- **Cloud backup in setup wizard**: Private GitHub repo created during `npx instar` setup
+- **Non-interactive backup**: `instar init --standalone` auto-sets up git backup even in subprocess contexts
+- **`instar nuke`**: Complete agent removal with safety guards and final backup push
+- **Agent removal awareness**: Agents know about `instar nuke` via CLAUDE.md template

package/upgrades/0.9.25.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### Auto-Detect Existing Agents on New Machine Setup
+
+When running `npx instar` on a new machine, the setup wizard now proactively scans for existing agents before offering to create a new one:
+
+1. **Local scan**: Checks `~/.instar/agents/` for standalone agents already on this machine
+2. **GitHub scan**: Runs `gh repo list` to find `instar-*` backup repositories on the user's GitHub
+
+If existing agents are found, the wizard presents them as restore options:
+
+> I found existing agents on your GitHub: my-agent, work-bot.
+> Want to restore one of these?
+
+**Restore Flow**: Clone from GitHub, update machine-specific config (paths, ports), register in local agent registry, install auto-start, start server. The agent arrives on the new machine with all memories and identity intact.
+
+### Setup Launcher Detection Improvements
+
+The `setup.ts` launcher now passes richer detection context to the wizard:
+- Existing standalone agents on this machine (names and paths)
+- GitHub backup repos found via `gh` CLI
+- This information is passed in the Claude session prompt so the wizard can act on it immediately
+
+Previously, the launcher only checked the current working directory for `.instar/config.json`, which missed all standalone agents.
+
+## What to Tell Your User
+
+If you've set up cloud backup, your agent now travels with you. Run `npx instar` on any new machine and the wizard will find your agent's backup on GitHub and offer to restore it. All memories, identity, and configuration come with it — only machine-specific paths get updated.
+
+## Summary of New Capabilities
+
+- **GitHub agent scanning**: Setup wizard auto-discovers `instar-*` repos on user's GitHub
+- **Local agent scanning**: Detects existing standalone agents at `~/.instar/agents/`
+- **Restore Flow**: Full automated restore from GitHub backup to local agent
+- **Richer detection context**: Setup launcher passes standalone and GitHub data to wizard

package/upgrades/0.9.28.md

@@ -0,0 +1,20 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### Orphan Process Reaper
+
+New monitoring component that detects stale Claude Code processes that outlived their tmux sessions. Automatically cleans up orphaned processes to prevent resource waste.
+
+### Silent Fallback Annotations
+
+Process utility methods in OrphanProcessReaper use `@silent-fallback-ok` annotations for catch blocks where the target process may not exist — expected behavior for process inspection and cleanup utilities.
+
+## What to Tell Your User
+
+Your agent now automatically detects and cleans up stale processes. No configuration needed.
+
+## Summary of New Capabilities
+
+- **OrphanProcessReaper**: Detects and cleans up stale Claude Code processes
+- **Process utility methods**: Safe fallbacks for process inspection (ps, kill)