# 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 |
