@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.13.0.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.13.0
+
+<!-- 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
+
+**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's existing behavior.
+
+**Bug fix: Multiple pending messages caused duplicate stall alerts.** If a user sent several messages quickly, each created a separate pending entry. When the timeout fired, ALL of them triggered separate "no response" notifications. Added per-channel deduplication in `StallDetector.check()` so only one alert fires per channel per check cycle.
+
+3 new tests covering per-channel deduplication scenarios.
+
+## What to Tell Your User
+
+- **Stall notifications fixed**: "No more false 'no response' alerts — you'll only see them when the agent is genuinely stuck, not after it already replied."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Accurate WhatsApp stall detection | Automatic — no action needed |
+| Per-channel alert deduplication | Automatic — applies to all platforms |

package/upgrades/0.14.0.md

@@ -0,0 +1,75 @@
+# Upgrade Guide — v0.14.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
+
+### Bug Fixes
+
+- **Health-check sessions no longer timeout at 1 minute**: The built-in `health-check` job's `expectedDurationMinutes` was increased from 1 to 3. Health checks running on slower machines or with more to check were consistently hitting the 1-minute session limit. No config changes needed — existing jobs auto-update on next server restart.
+
+- **better-sqlite3 bindings after auto-update**: When Instar auto-updates from certain versions, better-sqlite3's native bindings can become stale (ESM module cache issue). Instar now restarts once after rebuild to clear the cache. If you previously saw `Error: Could not locate the bindings file` after an update, this should be resolved.
+
+- **Fresh install no longer delivers 72+ historical upgrade guides**: On a fresh `instar init`, agents were receiving all historical upgrade guides on first server start. Root cause: the `last-migrated-version.json` state file wasn't created during init, so the UpgradeGuideProcessor thought all historical versions were "new." Init now seeds this file with the current version so new installs start clean.
+
+### Serendipity Protocol
+
+New protocol that allows sub-agents to capture valuable out-of-scope discoveries during focused tasks without breaking focus or polluting primary work.
+
+**Core mechanism:** Sub-agents invoke `.instar/scripts/serendipity-capture.sh` with a title, description, category, rationale, and readiness level. The script handles all validation, HMAC-SHA256 signing, secret scanning, and atomic file writes. Findings are stored in `.instar/state/serendipity/` as JSON files.
+
+**Security model:**
+- HMAC signing with key derived from `authToken + sessionId` — verifies local-session integrity
+- Blocking secret scanner (AWS keys, GitHub tokens, private keys, etc.) — findings containing credentials are rejected, not warned
+- Patch files stored as sidecar `.patch` files with SHA-256 hash bound to the HMAC payload
+- Symlink rejection and path traversal validation on patch file diff headers
+- Per-session rate limiting (default: 5 per session, configurable)
+- Field length limits (title: 120, description: 2000, rationale: 1000)
+
+**Worktree integration:** When sub-agents run in git worktrees, the WorktreeMonitor automatically copies serendipity findings back to the main tree during worktree teardown. Copy-back includes symlink rejection, size limits (100KB), and atomic copy.
+
+**New API endpoints:**
+- `GET /serendipity/stats` — Pending, processed, and invalid finding counts with details
+- `GET /serendipity/findings` — List all pending findings (full JSON)
+
+**New skill:**
+- `/triage-findings` — Review pending findings, verify HMAC, route to Evolution proposals or dismiss
+
+**New config:**
+```json
+{
+  "serendipity": {
+    "enabled": true,
+    "maxPerSession": 5
+  }
+}
+```
+
+**Hook updates:**
+- Session-start hook now checks for pending findings and lists them with `[category] title`
+- Compaction-recovery hook now shows pending finding count after identity restoration
+
+**Files installed:**
+- `.instar/scripts/serendipity-capture.sh` — installed during `instar init` (all three paths: fresh, existing, standalone)
+
+## What to Tell Your User
+
+- **Bug fixes**: "Three reliability improvements shipped: health-check jobs no longer time out prematurely, better-sqlite3 binding errors after updates should be gone, and fresh installs won't flood you with historical upgrade guides anymore."
+
+- **Serendipity Protocol**: "Your agent can now capture valuable discoveries that sub-agents notice while working on other tasks. Think of it like an always-on note-taker for insights — bugs spotted in passing, patterns worth documenting, security issues in neighboring code. These get securely captured and queued for your agent to review later, so nothing valuable gets lost."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Sub-agent finding capture | Automatic — sub-agents use `.instar/scripts/serendipity-capture.sh` |
+| Finding triage | `/triage-findings` skill |
+| Finding stats | `GET /serendipity/stats` |
+| Finding listing | `GET /serendipity/findings` |
+| Worktree copy-back | Automatic — runs during worktree teardown |
+| Session notification | Automatic — session-start hook lists pending findings |
+| Config toggle | Set `serendipity.enabled: false` in config.json to disable |

package/upgrades/0.14.1.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — v0.14.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Silent Reject for Unauthorized WhatsApp Numbers (Default: On)
+
+Previously, when an unauthorized phone number messaged a WhatsApp-connected agent, the agent responded with "This agent is not currently accepting new users." In linked-device mode (Baileys), this is a serious privacy issue — it reveals to the user's personal contacts that an AI agent is running on their number.
+
+Now, unauthorized messages are **silently dropped** by default. No response is sent. The message is logged and an `auth:unauthorized` event is emitted, but the sender sees nothing.
+
+**Config:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `silentReject` | `true` | Silently drop unauthorized messages (no response). Set `false` to use AuthGate registration policy responses. |
+
+To restore the old behavior (respond to unauthorized users):
+```json
+{
+  "messaging": [{
+    "type": "whatsapp",
+    "config": {
+      "silentReject": false
+    }
+  }]
+}
+```
+
+## What to Tell Your User
+
+- "Your agent no longer responds to people who aren't in your authorized numbers list. Their messages are silently ignored."
+- If the user wants the agent to respond to unknown contacts (e.g., for a business bot on a dedicated number), let them know they can ask the agent to enable that — the agent will configure it for them.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Silent reject (default) | Unauthorized messages silently dropped — no config needed |
+| Verbose reject | Set `silentReject: false` to send rejection messages |

package/upgrades/0.15.0.md

@@ -0,0 +1,59 @@
+# Upgrade Guide — v0.15.0
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Machine-Scoped Job Scheduling
+
+Jobs can now be restricted to specific machines. Add a `machines` field to any job definition in `jobs.json` — an array of machine IDs (`m_...`) or machine names (case-insensitive).
+
+```json
+{
+  "slug": "adriana-checkin",
+  "machines": ["lunas-macbook"],
+  "schedule": "0 9 * * *",
+  ...
+}
+```
+
+**Behavior:**
+- Jobs **without** a `machines` field run on all machines (unchanged, fully backwards-compatible)
+- Jobs **with** a `machines` field only run on machines whose ID or name matches
+- Machine name matching is case-insensitive (`"Lunas-MacBook"` matches `"lunas-macbook"`)
+- Both machine IDs (`m_abc123...`) and human-friendly names work
+- Skipped jobs are tracked in the skip ledger with reason `machine-scope`
+- At startup, the scheduler logs which jobs were filtered out by machine scope
+
+**API changes:**
+- `GET /jobs` — each job now includes a `runsOnThisMachine` boolean indicating whether the job is active on this machine
+- `POST /jobs/:slug/trigger` — returns `"skipped"` if the job is scoped to a different machine
+
+**New type field:**
+```typescript
+interface JobDefinition {
+  // ... existing fields ...
+  machines?: string[];  // Machine IDs or names — omit to run everywhere
+}
+```
+
+**New skip reason:**
+```typescript
+type SkipReason = '...' | 'machine-scope';
+```
+
+**How machine identity is resolved:**
+The scheduler reads the local machine identity from the MultiMachineCoordinator at startup. For agents without multi-machine configured, no filtering occurs (all jobs run). Machine names come from `identity.json` (typically auto-detected from `os.hostname()` or user-provided during `instar pair`).
+
+## What to Tell Your User
+
+- "If you're running me on multiple machines, you can now mark specific jobs to only run on certain machines. Just let me know which jobs should be machine-specific and I'll set it up."
+- "Your existing jobs aren't affected — everything keeps running everywhere unless you tell me to restrict it."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Machine-scoped jobs | Add `"machines": ["machine-name"]` to a job in jobs.json |
+| Machine scope visibility | `GET /jobs` includes `runsOnThisMachine` per job |
+| Skip tracking | Skip ledger tracks `machine-scope` skips |

package/upgrades/0.16.0.md

@@ -0,0 +1,61 @@
+# Upgrade Guide — v0.16.0
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Threadline Auto-Bootstrap
+
+Threadline now activates automatically on server boot. No CLI commands, no configuration files.
+
+On startup, the bootstrap:
+1. **Generates Ed25519 identity keys** and persists them in `state/threadline/identity-keys.json` (0o600 permissions)
+2. **Creates a HandshakeManager** for cryptographic mutual authentication
+3. **Registers MCP tools** into Claude Code's config (`~/.claude.json` and `.mcp.json`) so Claude Code gains 5 `threadline_*` tools automatically
+4. **Announces agent presence** via AgentDiscovery with capabilities, description, framework, and public key
+5. **Starts a presence heartbeat** for liveness detection by other agents
+
+The bootstrap is non-fatal — if any step fails, the agent continues without Threadline. On shutdown, the heartbeat is cleanly stopped.
+
+### MCP stdio Entry Point
+
+New standalone entry point (`dist/threadline/mcp-stdio-entry.ts`) that Claude Code launches as a child process via stdio transport. Reads config from disk, creates a ThreadlineMCPServer with no-auth stdio mode, and proxies messages to the running agent server via HTTP.
+
+### Threadline Network Interop (Phases 6A–6D)
+
+Four interop protocols for cross-framework communication:
+
+| Phase | Module | Tests | Purpose |
+|-------|--------|-------|---------|
+| 6A | A2A Gateway | — | Google Agent-to-Agent protocol gateway |
+| 6B | MCP Tool Server | — | Standard MCP tools for Claude Code and other clients |
+| 6C | Trust Bootstrap | 265 | First-contact handshake for unknown agents |
+| 6D | OpenClaw Bridge | 144 | Bidirectional translation for OpenClaw agents |
+
+### Framework-Agnostic Discovery
+
+Agent discovery now includes a `framework` field (`'instar'`, `'claude-code'`, or `'other'`) so agents can adapt communication based on what kind of agent they're talking to.
+
+### Full-Stack E2E Tests
+
+50 new E2E tests covering the complete bootstrap → discovery → messaging → shutdown lifecycle.
+
+**Test coverage**: 27 modules, 1,361 tests across 35 test files.
+
+## What to Tell Your User
+
+- **"Your agent can now talk to other agents automatically."** When you start your agent, it registers itself for discovery. Other agents on the same machine (or network) can find it and start conversations — no setup needed.
+- **"Conversations with other agents persist across sessions."** If your agent talked to another agent yesterday, it picks up exactly where it left off — same thread, full context.
+- **"This works with agents built on any framework"** — not just Instar. Claude Code agents, OpenClaw agents, and A2A-compatible agents can all communicate through Threadline.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Auto-bootstrap | Automatic — starts on server boot |
+| MCP tools | 5 `threadline_*` tools appear in Claude Code automatically |
+| Agent discovery | `threadline_discover` or ask your agent "what agents are nearby?" |
+| Send messages | `threadline_send` or "send a message to [agent-name]" |
+| Thread history | `threadline_history` or "show conversation with [agent-name]" |
+| Agent listing | `threadline_agents` or "list known agents" |
+| Thread deletion | `threadline_delete` (requires confirmation) |

package/upgrades/0.17.0.md

@@ -0,0 +1,88 @@
+# Upgrade Guide — v0.17.0
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Coherence Gate (Response Review Pipeline)
+
+An LLM-powered response review pipeline that evaluates every outbound agent message before it reaches users. Catches tone issues, fabricated claims, capability inaccuracies, information leakage, and value misalignment — before the user ever sees them.
+
+The pipeline has three layers:
+
+1. **Policy Enforcement Layer (PEL)** — Deterministic hard blocks. Catches credentials, PII, auth tokens, and schema violations without any LLM call. Zero-latency, zero-cost. Always active, even when the full pipeline is disabled.
+2. **Gate Reviewer** — Fast LLM triage. Determines if a message needs full specialist review or can pass through. Most messages skip full review.
+3. **9 Specialist Reviewers** — Parallel LLM calls checking specific dimensions:
+   - Conversational Tone (no code dumps, no command pasting)
+   - Claim Provenance (every claim traceable to tool output)
+   - Settling Detection (catches when agent accepts failure too easily)
+   - Context Completeness (ensures relevant context was considered)
+   - Capability Accuracy (verifies feature claims against live system)
+   - URL Validity (catches fabricated URLs)
+   - Value Alignment (checks against AGENT.md values)
+   - Information Leakage (prevents exposing internal details)
+   - Custom reviewers loadable from `.instar/reviewers/`
+
+Key design decisions:
+- **15-row normative decision matrix** for deterministic pipeline state handling
+- **Per-channel configuration** — Telegram, WhatsApp, and direct each have their own fail behavior (fail-open for chat, fail-closed for email)
+- **Retry tracking** with conversation advancement detection
+- **Observe-only mode** for gradual rollout — see what the gate would catch without blocking anything
+- **Claude Code Stop hook integration** — reviews happen automatically via the hook system
+- **Full observability** — audit logs, decision history, canary endpoint
+- **Adaptive trust integration**
+
+Configuration in `.instar/config.json`:
+```json
+{
+  "responseReview": {
+    "enabled": true,
+    "observeOnly": false,
+    "gateModel": "claude-haiku-4-5-20251001",
+    "reviewerModel": "claude-haiku-4-5-20251001",
+    "maxRetries": 2,
+    "timeoutMs": 10000,
+    "channels": {
+      "telegram": { "failOpen": true },
+      "whatsapp": { "failOpen": true }
+    }
+  }
+}
+```
+
+Requires `ANTHROPIC_API_KEY` in environment for LLM-based reviewers.
+
+### ScopeVerifier Rename
+
+The pre-action scope verification system (previously named CoherenceGate) has been renamed to ScopeVerifier. The CoherenceGate name now belongs to the response review pipeline, matching the spec. Backward-compatible type aliases are maintained in the npm exports — no agent-side changes required.
+
+### PlatformProbe
+
+New system reviewer probe for monitoring platform-level health metrics.
+
+### JobScheduler Machine-Scoped Improvements
+
+Better machine identity filtering for multi-machine job scheduling. Jobs now filter more accurately by machine when running across paired devices.
+
+### Test Coverage
+
+~270 new tests across 9 test files: CoherenceGate, CoherenceGateCanary, CoherenceGateE2E, CoherenceGateHook, CoherenceGateObservability, PolicyEnforcementLayer, CoherenceReviewer, CustomReviewerLoader, and RecipientResolver.
+
+## What to Tell Your User
+
+- **"Your agent now reviews its own messages before sending them."** Every outbound message passes through a quality gate. If the agent is about to send something with a fabricated URL, dump terminal commands at you, or leak internal details — the gate catches it and the agent rewrites.
+- **"It's off by default — I can turn it on when you're ready."** There's an observe-only mode too, so you can see what it would catch without actually blocking anything.
+- **"The credential and PII scanner is always on."** Even without the full pipeline, the deterministic layer blocks sensitive data from ever appearing in outbound messages.
+- **"It works with all messaging channels."** Telegram, WhatsApp, direct — each channel can have its own behavior.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Coherence Gate | Set `responseReview.enabled: true` in config |
+| Observe-only mode | Set `responseReview.observeOnly: true` to audit without blocking |
+| PEL (deterministic blocks) | Always active — no configuration needed |
+| Per-channel fail behavior | Configure `responseReview.channels` per channel |
+| Custom reviewers | Add reviewer files to `.instar/reviewers/` |
+| Canary endpoint | Check pipeline health via the canary API |
+| Audit logs | Full decision history for every reviewed message |

package/upgrades/0.17.10.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — v0.17.10
+
+<!-- bump: patch -->
+
+## What Changed
+
+### /new Command Fix — Session Spawning
+
+The `/new` command in Telegram was broken: it created a new topic but didn't spawn a session in it, resulting in a dead topic with no active agent.
+
+**Root cause**: Two `/new` handlers existed — one in `TelegramAdapter.handleCommand()` (which only created a topic) and one in the server's `onTopicMessage` callback (which created a topic AND spawned a session). The adapter handler intercepted `/new` first and returned `true`, preventing the server handler from ever running.
+
+**Fix**: Removed the incomplete `/new` handler from `TelegramAdapter.handleCommand()`. The server-level handler now processes `/new` correctly — creates the topic, spawns an interactive session, links them together, and confirms in both the source and new topic.
+
+## What to Tell Your User
+
+- The /new command works now. Typing /new followed by a topic name creates a new topic with a live session. Previously it created empty topics with no session.
+
+## Summary of New Capabilities
+
+| Fix | Impact |
+|-----|--------|
+| /new command session spawning | /new now correctly creates topic + session instead of just an empty topic |

package/upgrades/0.17.11.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — v0.17.11
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Fix: better-sqlite3 native bindings not compiled in shadow install
+
+When auto-update installs a new version to the shadow-install directory, it uses `--ignore-scripts` to prevent cloudflared's binary download from failing in environments where the download path doesn't exist. This also skipped better-sqlite3's native module build step, leaving no compiled `.node` binaries in the shadow install.
+
+**Result**: TopicMemory and SemanticMemory both failed at startup on any agent using shadow install (introduced in v0.17.0), falling back to legacy JSONL-based behavior. The error message was "Could not locate the bindings file."
+
+**Fix**: After each shadow install, `npm rebuild better-sqlite3` is now run to compile native bindings for the current Node.js version and platform. If the rebuild fails for any reason, the existing fallback behavior (legacy SQLite-less memory) remains active.
+
+## What to Tell Your User
+
+If your agent's memory has felt less capable recently (slower, no search, shorter context) after an auto-update, this patch restores full SQLite-backed memory. The agent will rebuild its knowledge graph and conversation memory on the next update cycle.
+
+## Summary of New Capabilities
+
+| Area | Change |
+|------|--------|
+| Shadow install | Rebuilds better-sqlite3 native bindings after installation |
+| Affected components | TopicMemory, SemanticMemory |
+| Fallback behavior | Unchanged — non-fatal if rebuild fails |

package/upgrades/0.17.12.md

@@ -0,0 +1,43 @@
+# Upgrade Guide — v0.17.11
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Input Guard — Three-Layer Input Defense
+
+A new security system that validates message provenance before input reaches the agent session. Prevents cross-topic context injection — where a message from one conversation leaks into an unrelated session and the agent acts on it as if it were legitimate.
+
+**Background**: On 2026-03-09, a Threadline test message was injected into an unrelated session. The session treated the injected content as legitimate user input, composed a response about the wrong topic, and sent it to the wrong audience. Input Guard prevents this class of attack.
+
+**Architecture — Three defense layers:**
+
+- **Layer 1 (Provenance Check)**: Deterministic tag matching. Messages with valid source tags (`[telegram:N]`, `[whatsapp:JID]`, `[dashboard:SID]`, `[AGENT MESSAGE]`) matching the session's bound topic pass instantly. Mismatched tags are blocked and alerted. Untagged messages proceed to Layer 1.5.
+
+- **Layer 1.5 (Injection Pattern Filter)**: Regex-based detection of known injection patterns — role-switching attempts, system prompt impersonation, instruction overrides, zero-width character obfuscation. Catches obvious attacks at zero cost (<1ms). Suspicious messages are injected with a system-reminder warning.
+
+- **Layer 2 (Topic Coherence Review)**: Async LLM review (Claude Haiku) for untagged messages that pass the deterministic filter. Runs in background — message is injected immediately, warning follows ~1s later if suspicious. Fail-open on timeout or error.
+
+**Key design decisions:**
+- Fail-open everywhere. Messages are never silently dropped. Degradation is always surfaced via attention queue.
+- Dashboard input bypasses the guard entirely (uses `sendInput()` path, not `injectMessage()`).
+- Unbound sessions (no topic) accept all input — the guard only activates for topic-bound sessions.
+- System-reminder warnings are structurally privileged in Claude's context, making them harder for injected content to override.
+
+**No-silent-failure guarantees:** Every fallback path logs loudly. Haiku timeouts, API key issues, config errors — all fail-open with logging. Three or more failures in 10 minutes triggers an attention queue alert.
+
+### Input Guard End-to-End Test Suite
+
+36 e2e tests covering all layers, action modes, realistic attack scenarios, and integration with the message injection pipeline. Validates provenance checks, injection pattern detection, security logging, and guard-disabled behavior.
+
+## What to Tell Your User
+
+- **"Your agent now has input protection."** A new security layer validates where messages come from before acting on them. If something gets injected from the wrong conversation, your agent will recognize it and flag it rather than blindly acting on it. This is on by default for new installs — existing agents can ask their agent to turn it on.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Input Guard (provenance + injection + coherence) | Enabled via `inputGuard.enabled` in config. Agents can configure action modes: warn (default), block, or log. |
+| Security audit logging | Automatic — events written to `.instar/security.jsonl` |
+| Input Guard e2e tests | `npm run test:e2e` — 36 tests covering all layers and attack scenarios |

package/upgrades/0.17.13.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — v0.17.13
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Sentinel: Unparseable LLM Responses No Longer Disrupt Sessions
+
+Two fixes to the MessageSentinel's handling of unparseable LLM classification responses:
+
+1. **Default changed from "pause" to "pass-through"**: When the classification LLM returns a conversational response instead of a single category word, the sentinel now defaults to `normal` (pass-through) instead of `pause`. This prevents false session pauses caused by classification failures — if the classifier can't do its job, the result is unreliable and shouldn't disrupt the session.
+
+2. **Sentinel reasons never shown to users**: Previously, a substring check (`includes('unparseable')`) was supposed to sanitize raw LLM responses before they reached Telegram. This check was bypassed in some environments. The fix removes reason text from user-facing messages entirely — reasons are logged server-side only. User messages now show clean text: "Session paused." or "Session terminated." without any internal classification details.
+
+## What to Tell Your User
+
+- **Cleaner session messages**: Your agent will no longer show confusing internal messages when pausing or stopping sessions. Messages are now short and clean.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Robust sentinel message sanitization | Automatic — internal reasons logged server-side, never shown to users |
+| Pass-through on unparseable classification | Automatic — failed classifications no longer falsely pause sessions |

package/upgrades/0.17.14.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.17.14
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Sentinel: Robust Category Extraction from LLM Responses
+
+The MessageSentinel's LLM classification now uses multi-layer parsing instead of requiring an exact single-word response:
+
+1. **Exact match** (ideal): Response is just the category word — works as before.
+2. **Extraction** (new): For short responses (<100 chars) that contain a valid category word, the category is extracted. Example: "The classification is: normal" → extracts `normal`. Confidence is reduced (0.6 vs 0.8) to reflect the extraction.
+3. **Rejection**: Responses over 100 characters are treated as context-contaminated conversational responses and rejected (pass-through). This catches the case where the LLM gets CLAUDE.md injected and writes paragraphs instead of classifying.
+
+Priority order when multiple categories appear in an extracted response: emergency-stop > pause > redirect > normal. This ensures safety-first ordering.
+
+## What to Tell Your User
+
+- **Smarter message classification**: Your agent's safety system is now better at understanding its own internal responses, which means fewer false pauses and interruptions during normal conversation.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Multi-layer LLM response parsing | Automatic — extracts valid classifications from verbose responses |
+| Length-based rejection for contaminated responses | Automatic — responses >100 chars are treated as unreliable |

package/upgrades/0.17.2.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — v0.17.2
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Job Run History — Full Experience Loop
+
+The persistent job history system now captures the complete experience loop for every job execution, not just metadata:
+
+1. **Output capture**: When a job session completes, the last ~1000 characters of session output are captured and stored as `outputSummary` in the run record. This gives visibility into what the job actually did.
+
+2. **LLM reflection**: After every completed job (not just when `livingSkills` is enabled), an LLM reflection is generated and persisted. Each reflection includes: summary of what happened, strengths, areas for improvement, deviation analysis, purpose drift detection, and suggested changes. This is stored in the `reflection` field of the run record.
+
+3. **Permanent retention**: Job run history is never deleted. On startup, the JSONL ledger is compacted (deduplicating pending → completed pairs) but no records are ever removed. History is memory, and memory should never be lost.
+
+4. **Monotonic run IDs**: RunIds now include a monotonic counter to prevent collisions when multiple jobs trigger within the same millisecond.
+
+5. **Robust test coverage**: Full e2e test suite exercising the HTTP path (trigger job via API → scheduler records history → query via API), plus comprehensive unit tests for the JobRunHistory class.
+
+### Tunnel Manager — Named Tunnel Resilience
+
+The TunnelManager now handles named tunnel reconnection more robustly, with exponential backoff and automatic restart on failure.
+
+### Orphan Process Reaper — Improved Cleanup
+
+The OrphanProcessReaper now handles edge cases in process tree traversal more gracefully.
+
+## What to Tell Your User
+
+- **"Your agent now learns from every job it runs."** After each job completes, the agent reflects on what happened — what went well, what could improve, and whether the job is drifting from its intended purpose. These reflections are saved permanently.
+- **"Job history is now permanent."** Nothing is ever deleted from job run history. Your agent builds a complete record of everything it has done, so patterns and lessons are never lost.
+- **"You can see what jobs actually did, not just whether they passed."** Job history now captures output summaries — the actual results of each run, not just pass/fail status.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Job output capture | Automatic — visible in job history API responses |
+| LLM reflection on every job | Automatic — no config needed, always on |
+| Permanent job history | Automatic — no rotation or deletion |
+| Query job reflections | GET /jobs/history or GET /jobs/:slug/history |

package/upgrades/0.17.3.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — v0.17.3
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Per-Agent Shadow Installs — No More Global Pollution
+
+The auto-updater previously used `npm install -g` to apply updates, which installed Instar globally on the machine. This caused version drift — all agents shared the same global binary regardless of when they were created or what version they expected. Agents installed via `npx instar` would silently start using a globally-installed version instead of their own.
+
+Now each agent manages its own version independently:
+
+1. **Shadow install directory**: Updates are installed to `{stateDir}/shadow-install/` — a local directory owned by each agent. No global npm modifications.
+
+2. **Supervisor resolution**: On restart, the server supervisor checks for a shadow install first and uses it if present, falling back to the current binary only if no shadow exists.
+
+3. **Rollback safety**: Rollbacks also use the shadow install pattern, so reverting to a previous version never touches global state.
+
+4. **npx compatibility**: Agents started via `npx instar` continue to work normally. The shadow install only activates when the auto-updater applies an update — it never interferes with the initial launch mechanism.
+
+### Removed npx Cache Workarounds
+
+Previous versions had special logic to detect whether the agent was running from the npx cache and conditionally block auto-apply. This is no longer needed since updates go to the shadow directory, not the global prefix. The workaround code has been removed.
+
+## What to Tell Your User
+
+- **"Your agents no longer share versions."** Each agent now manages its own copy of Instar independently. Updating one agent never affects another. This prevents the version drift that was causing agents to run unexpected code.
+- **"No more global installs."** Instar updates stay local to each agent. Your global npm is never modified, and agents started with npx continue to work exactly as before.
+- **"Existing agents will self-heal."** The next time an agent auto-updates, it will use the new shadow install pattern automatically. No manual intervention needed.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Per-agent shadow installs | Automatic — no config needed |
+| Independent version management | Each agent updates independently |
+| Clean npx behavior | npx instar always downloads fresh, never picks up stale globals |

package/upgrades/0.17.4.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — v0.17.4
+
+<!-- bump: patch -->
+
+## What Changed
+
+### OAuth Circuit Breaker — No More Runaway Polling
+
+When Anthropic's OAuth API returns 429 (rate limited), the quota collector now backs off intelligently across polling intervals instead of retrying on every poll.
+
+**Before**: After a 429, the fallback to JSONL-based estimation worked correctly for that poll. But the next poll (1-2 minutes later) would attempt OAuth again with no memory of the prior failure — causing a loop of degradation reports every minute.
+
+**After**: If 3 consecutive polls return 429, the OAuth circuit breaker trips and pauses OAuth attempts for 30 minutes. During the backoff window, quota data comes from JSONL estimation (lower confidence but functional). When the backoff expires, OAuth is retried — and a successful response resets the circuit.
+
+This eliminates the pattern where a single rate-limited agent generates dozens of degradation reports in an hour.
+
+## What to Tell Your User
+
+- **"Quota polling is smarter about rate limits."** If Anthropic's usage API throttles your agent, the system now backs off for 30 minutes instead of retrying every minute. You'll see fewer degradation alerts during high-usage periods.
+- **"Quota tracking continues during backoff."** The JSONL-based estimation stays active, so spawn gating and migration decisions still work — just with estimated rather than authoritative data.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| OAuth circuit breaker | Automatic — trips on 3 consecutive 429s, resets after 30 min |
+| Circuit breaker diagnostics | Visible in `getBudgetStatus().oauthCircuitBreaker` |

package/upgrades/0.17.5.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — v0.17.5
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Intelligence Provider Context Isolation
+
+The `ClaudeCliIntelligenceProvider` (used for MessageSentinel classification, InputGuard coherence checks, and other internal LLM evaluations) now runs with `--setting-sources user`, preventing project-level CLAUDE.md and local settings from contaminating classification prompts.
+
+**Before**: `claude -p "classify this message..."` would load the agent's full identity prompt (CLAUDE.md, hooks, etc.). The LLM would sometimes treat the classification request as a conversation, returning paragraphs of identity-confused text instead of a single classification word.
+
+**After**: Classification calls are isolated from project context. The LLM receives only the classification prompt and responds with the expected single-word category.
+
+### Sentinel Reason Sanitization
+
+When the MessageSentinel's LLM classification returns an unparseable response, the raw LLM output is no longer dumped to Telegram. Instead, a clean generic message is shown ("Pause signal detected." or "Emergency stop signal detected.").
+
+**Before**: Users would see confusing messages like `Session paused. LLM response unparseable: "You're right. I've been operating without proper grounding..."` — which looked like the agent having an identity crisis in public.
+
+**After**: Unparseable classification responses are logged server-side but never shown to users.
+
+## What to Tell Your User
+
+- **"Fixed a bug where the agent could post confusing messages when pausing sessions."** Sometimes internal classification errors would leak raw text to Telegram — that's cleaned up now.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Context-isolated intelligence calls | Automatic — CLI evaluations no longer inherit project CLAUDE.md |
+| Sanitized sentinel messages | Automatic — unparseable classifications show clean messages |