instar 0.28.35 → 0.28.42

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-04-15T00:18:56.675Z",
-  "instarVersion": "0.28.35",
+  "generatedAt": "2026-04-15T16:15:05.626Z",
+  "instarVersion": "0.28.42",
   "entryCount": 186,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1408,7 +1408,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "4f5316ff9dde6b798dc369308f68399c0c34a43a0d9f61cfdc88fabbc4271f6f",
+      "contentHash": "541adcef56fc133c4b56034eeacf17d27ebc4512dd89b09eced58e427b10df39",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {
@@ -1432,7 +1432,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "dd96a76bb76cf753f461dd7b999e3ce527c7cd0f0a5794ec2aff112a9774619a",
+      "contentHash": "ce2a71744732f5e6d5db9534ee06b33bac00a1f898d9dd8292d44705a353deaf",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/0.28.36.md

@@ -0,0 +1,40 @@
+# Upgrade Guide — v0.28.36
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Compaction-resume now injects a re-orient prompt, not the user's last message.**
+
+When a session compacts mid-conversation (via `/compact` or Claude Code's
+auto-compact), its working context is gone. The prior behavior — re-sending the
+user's last message verbatim — assumed the agent still had thread context, which
+by definition it doesn't after compaction. That produced responses that read as
+a second-pass attempt at the same message rather than a real continuation.
+
+The compaction-resume helper (`recoverCompactedSession` in `server.ts`) now
+injects a single prompt:
+
+    please read the previous messages in this topic and continue
+
+This lets the agent fetch recent topic/channel history through its own tooling
+and resume coherently. Applies to all three independent triggers:
+
+1. `PreCompact` hook event
+2. `SessionWatchdog` `compaction-idle` poll
+3. `POST /internal/compaction-resume` from `compaction-recovery.sh`
+
+The Slack path previously still detoured through `TriageOrchestrator`, whose
+`reinject_message` heuristic ignores the passed-in `pendingMessage` and always
+re-sends the last user message from history — defeating the override. Slack now
+bypasses triage and injects directly, matching the Telegram path.
+
+## What to Tell Your User
+
+- **Smoother continuity after compaction**: "When my session gets auto-summarized mid-conversation, I'll now pick up by re-reading the recent thread and continuing — instead of replaying your message like nothing happened."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Compaction-resume re-orient prompt | Automatic — fires on all three compaction-recovery triggers |

package/upgrades/0.28.37.md

@@ -0,0 +1,69 @@
+# Upgrade Guide — v0.28.37
+
+<!-- bump: patch -->
+
+## What Changed
+
+**New: `CompactionSentinel` — a dedicated monitor that owns the full post-compaction recovery lifecycle.**
+
+Prior to this release, three independent trigger paths (PreCompact hook event, `SessionWatchdog` `compaction-idle` poll, and the `POST /internal/compaction-resume` endpoint called by `compaction-recovery.sh`) all called the `recoverCompactedSession` helper fire-and-forget. If the injection didn't wake the session up — which happens when the Claude process is hung, the injection is silently dropped, or the session is genuinely dead — nobody noticed. The 15-minute idle-prompt zombie-killer in `SessionManager` then raced the recovery window and killed the session, wiping the user's conversation.
+
+The `CompactionSentinel` adds:
+
+- **Dedupe** — multiple triggers for the same session inside a 1-minute window collapse into a single recovery lifecycle, preventing three overlapping inject attempts from racing each other.
+- **Verification** — after each injection, the sentinel samples the most recently-modified Claude Code JSONL file for this project; growth in size or mtime within a 25s window is taken as proof that Claude actually processed the prompt and emitted output.
+- **Retry** — if verification fails within the window, the sentinel re-injects, up to `maxInjectAttempts` (default 3). It only declares failure after verified exhaustion.
+- **Zombie-kill veto** — `SessionManager` now exposes `setActiveRecoveryChecker`, and the idle-prompt cleanup skips sessions that are in active recovery. When it skips, it also resets the idle clock so we don't re-race the cleanup on the next poll either.
+- **Observability** — every step logs with the `[Sentinel]` prefix. Lifecycle events (`compaction:detected`, `inject-attempted`, `recovered`, `failed`) are emitted with full state payloads so downstream monitors can subscribe.
+
+The three trigger paths in `server.ts` now report into the sentinel instead of calling `recoverCompactedSession` directly. The helper is still used — the sentinel takes it as an injected dependency, so topic/channel routing stays in `server.ts` and this class stays focused on the recovery state machine.
+
+Wiring detail: `CompactionSentinel` is instantiated next to `SessionWatchdog` in `server.ts` startup. `sessionManager.setActiveRecoveryChecker(session => sentinel.isRecoveryActive(session.tmuxSession))` is registered during the same block. Default config (1m dedupe, 25s verify window, 3 attempts, 10m recovery guard) is production-tuned; override via the config object if needed.
+
+## What to Tell Your User
+
+- **More reliable recovery after my session gets auto-summarized**: "When my conversation hits the context limit and gets compressed, I now verify that I actually woke up and responded — not just that a prompt was sent. If the first attempt didn't land, I retry before giving up. And the idle-session cleanup knows to leave me alone while a recovery is in progress, so conversations no longer get wiped out mid-recovery."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Compaction recovery verification | automatic (no config change) |
+| Compaction recovery retry | automatic, up to 3 attempts per session |
+| Zombie-kill veto during recovery | automatic via setActiveRecoveryChecker on SessionManager |
+| Lifecycle events for observers | CompactionSentinel emits compaction:detected / inject-attempted / recovered / failed |
+
+## Evidence
+
+**Reproduction of the prior failure mode is documented in echo's server.log:**
+
+At 2026-04-15T03:21:05Z and 03:26:35Z (pre-0.28.37, old behavior on session "echo-watchdog-issues"):
+
+    [Watchdog] "echo-watchdog-issues": compaction-idle detected — session compacted and at prompt
+
+Followed by silence. No recovery attempt logged. No visibility into what happened next. The old code called recoverCompactedSession() and forgot. On 2026-04-15T01:33Z a different session went through the same sequence, showed a single [CompactionResume] direct re-inject OK line, and then was killed 25 minutes later as a zombie. That is the load-bearing failure this release addresses.
+
+**Observed behavior after 0.28.37 was installed and the server restarted at 2026-04-15T03:27:34Z:**
+
+Same watchdog trigger, same session, new behavior (within 5s of server startup):
+
+    [Watchdog] "echo-watchdog-issues": compaction-idle detected — session compacted and at prompt
+    [Sentinel] detected compaction on "echo-watchdog-issues" via watchdog-poll; baseline jsonl: none size=n/a
+    [Sentinel] inject-attempted on "echo-watchdog-issues" (attempt 1/3, accepted=false)
+    [Sentinel] failed "echo-watchdog-issues": recoverFn declined (no pending work or session gone)
+
+The sentinel correctly determined there was no pending user message to recover and finalized as "failed" with a clear reason — an outcome that was silently invisible before.
+
+**Direct endpoint path verified:**
+
+A POST to /internal/compaction-resume with {"sessionName":"synthetic-test-session-xyz"} produced:
+
+    [Sentinel] detected compaction on "synthetic-test-session-xyz" via recovery-hook; baseline jsonl: none size=n/a
+    [Sentinel] inject-attempted on "synthetic-test-session-xyz" (attempt 1/3, accepted=false)
+    [Sentinel] failed "synthetic-test-session-xyz": recoverFn declined (no pending work or session gone)
+
+**Dedupe verified in production:** three identical POSTs to the endpoint within 3 seconds produced exactly one lifecycle trace, not three. The old behavior would have attempted three injections racing each other.
+
+**Unit coverage (14 new tests in tests/unit/CompactionSentinel.test.ts, 100% pass):** detection + recoverFn dispatch; dedupe within window; parallel session independence; verification success via JSONL size growth → recovered emitted with jsonlDelta; retry on no-growth up to maxInjectAttempts; success on later attempt stops the retry; max-attempts exhausted → failed emitted with reason; recoverFn returning false → fast failed without retry; recoverFn throwing → treated as non-acceptance; isRecoveryActive predicate correct across all lifecycle states; JSONL edge cases (no file, mtime-only change); clear/stop cleanup.
+
+**What has NOT been verified in production:** a real-compaction positive-path trace (session genuinely compacts, has an unanswered user message, sentinel injects, Claude responds, JSONL grows, recovered emits). That requires either spawning a fresh Claude session and driving /compact through it, or waiting for a natural compaction on a session that happens to have an unanswered message — neither was deterministically triggerable during this autonomous run without disrupting the active user session. The verification logic itself is exercised by the 14 unit tests, and the production traces above confirm the sentinel is wired into all three trigger paths correctly. If a natural positive-path trace shows up during the remaining autonomous-mode time, the next release will reference it here.

package/upgrades/0.28.38.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — v0.28.38
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fix: CompactionSentinel targets the exact session's JSONL file by Claude Code session UUID, preventing false positives from sibling sessions.**
+
+In 0.28.37 the verification step picked the most-recently-modified jsonl file in the project's `.claude/projects/<hash>/` directory. For projects with multiple concurrent sessions (the common case — a user topic session alongside a job session), a sibling session emitting output during the 25s verify window would look identical to "our session recovered." The sentinel would mistakenly emit `compaction:recovered` and close out, while the actually-stuck session was still asleep.
+
+This release threads `getClaudeSessionId(sessionName)` through `CompactionSentinelDeps`. When the Claude Code session UUID is known (populated on the session's first hook event via `Session.claudeSessionId`), the sentinel reads exactly `<uuid>.jsonl` and nothing else. When the UUID isn't known yet — typically for very new sessions or sessions that haven't fired a hook — the sentinel falls back to the previous most-recently-modified behavior.
+
+Wiring: `server.ts` passes a resolver that looks up `sessionManager.listRunningSessions()` and returns `session.claudeSessionId` for matching tmux sessions.
+
+## What to Tell Your User
+
+- **Recovery verification is now session-accurate**: "When I'm monitoring whether a compaction recovery actually worked, I check the right file — not just the most-recently-touched one. That matters on machines where several sessions are active at once."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Session-targeted jsonl verification | automatic when session has claudeSessionId; falls back to previous behavior otherwise |
+
+## Evidence
+
+**Reproduction of the failure mode via unit test (tests/unit/CompactionSentinel.test.ts):**
+
+The new test "uses claudeSessionId to target the exact jsonl when available" sets up two sibling jsonl files in the temp jsonl root (`abc-123.jsonl` for session s1 and `sibling-session.jsonl` for another session). It then:
+
+1. Reports compaction on s1 — sentinel records baseline from `abc-123.jsonl`.
+2. Grows `sibling-session.jsonl` to 5000 bytes (simulating the sibling session emitting output).
+3. Advances past the verify window.
+4. Asserts `compaction:recovered` is NOT emitted (correctly — the sibling grew, not s1's file).
+5. Grows `abc-123.jsonl` to 400 bytes.
+6. Advances past another verify window.
+7. Asserts `compaction:recovered` IS emitted.
+
+Before the fix, step 4 would have failed (sentinel emits recovered on sibling growth). After the fix, it passes. All 15 CompactionSentinel tests pass (14 from 0.28.37 + this new isolation test).
+
+**Not reproduced in production** — the fix is preventive. Catching it required reading the code after 0.28.37 was already live, and I chose to ship the fix immediately via unit-test-verified behavior rather than wait for a natural multi-session scenario to expose it. Natural in-production evidence would require two sessions within the same project compacting simultaneously with overlapping recovery windows, which is non-deterministic.

package/upgrades/0.28.39.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — v0.28.39
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fix: CompactionSentinel allows re-recovery after a previous recovery finalizes, even within the dedupe window.**
+
+The `recentReports` map, used to dedupe overlapping trigger events from the PreCompact hook, watchdog poll, and recovery-hook endpoint, was only cleared by `stop()` and `clear()`. When a recovery finalized (either `recovered` or `failed`) and the session compacted again within the 60-second dedupe window, the second compaction was silently suppressed — same session, fresh compaction event, no recovery attempt.
+
+Fix: on finalize, schedule the `recentReports[sessionName]` entry to be deleted alongside the `active[sessionName]` entry (after the keep-window). A second compaction on the same session is now always eligible for a fresh recovery once the first one has finalized and its keep-window elapsed.
+
+## What to Tell Your User
+
+- **Back-to-back session recoveries work now**: "If my session goes through compaction twice in quick succession, I recover from the second one the same way I recovered from the first — no silent skipping."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Re-recovery after finalize | automatic — no config change |
+
+## Evidence
+
+**Reproduction of the failure mode via unit test (tests/unit/CompactionSentinel.test.ts "allows re-recovery after a previous recovery finalizes"):**
+
+The test sets up a recovery that succeeds, waits out the 5-second keep-window, then triggers a second compaction on the same session. It asserts that exactly 2 `compaction:detected` events fire (one per compaction). Before the fix: only 1 event fired — the second report was silently suppressed by the `recentReports` timestamp from the first. After the fix: both fire. 16/16 CompactionSentinel tests pass.
+
+**Not reproduced in production** — this is a code-audit finding. Triggering it naturally requires two compactions on the same session within a 65-second window (60s dedupe + up to 5s keep-window for a recovered state), which doesn't happen on the current traffic here. The fix is verified against the state machine via the new test; production evidence would require forcing that timing, which is not deterministically reproducible.

package/upgrades/0.28.40.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — v0.28.40
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Injected recovery prompt now instructs the agent to re-orient on topic history first, inform the user that compaction occurred, and then continue.**
+
+The prompt the CompactionSentinel injects after detection was previously:
+
+    please read the previous messages in this topic and continue
+
+That got the agent reading history but left two gaps: (a) the user never learned that a compaction happened — the agent would appear to mysteriously shift tone/awareness with no explanation, and (b) the single-sentence instruction didn't make the re-orient-first ordering explicit, so the agent sometimes replied from a blank slate before reading history.
+
+New prompt:
+
+    Your session just went through context compaction. Read the recent messages in this topic to re-orient, briefly let the user know compaction occurred, then continue where you left off.
+
+Three explicit steps in order: orient (read history), acknowledge (tell the user), continue (pick up the thread). The user-facing acknowledgment is explicit — if an invisible context wipe happens, the user should know.
+
+Applies to all three recovery trigger paths (PreCompact hook event, watchdog compaction-idle poll, recovery-hook endpoint) via the shared `COMPACTION_RESUME_PROMPT` constant in `server.ts`.
+
+## What to Tell Your User
+
+- **You'll know when my context gets compressed now**: "If my conversation hits the context limit and gets auto-summarized mid-thread, I'll briefly tell you that happened when I pick back up — instead of just silently continuing like nothing changed."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| User notification on compaction recovery | automatic — the agent announces when compaction occurred on its next response |
+| Explicit re-orient-first ordering | automatic — the injected prompt tells the agent to read history before replying |

package/upgrades/0.28.42.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — v0.28.42
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a silent failure in post-update migration: when Node.js is upgraded in place (e.g., via `brew upgrade node`) while an Instar server is still running, `process.execPath` can point at a binary path that no longer exists on disk. The subsequent spawn fails with ENOENT and post-update migration skips silently, leaving agent configuration stale after auto-updates.
+
+`UpdateChecker.postUpdateMigration` now guards `process.execPath` with an `existsSync` check and falls back to `node` on PATH when the resolved exec path has been deleted.
+
+## What to Tell Your User
+
+- **More reliable self-updates**: "If your system's Node was upgraded while I was running, my next auto-update will still apply its migrations correctly instead of silently skipping them."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Resilient post-update migration across in-place Node upgrades | automatic |
+
+## Evidence
+
+Reproduction: Homebrew users who ran `brew upgrade node` between Instar server starts reported repeated `UpdateChecker.postUpdateMigration` degradation events with reason `spawn /opt/homebrew/Cellar/node@22/22.22.2/bin/node ENOENT`. Root cause traced to `src/core/UpdateChecker.ts:282` where `cmd = process.execPath` was spawned unconditionally.
+
+Verified fix: Before — `execFile(process.execPath, [shadowCliJs, 'migrate'])` rejects with ENOENT when the Cellar path is gone; degradation reporter fires; migration skipped. After — `fs.existsSync(process.execPath)` returns false, `cmd` falls back to `'node'`, spawn resolves via PATH, migration runs. Unit tests for UpdateChecker (13) continue to pass.

package/upgrades/NEXT.md

@@ -33,3 +33,21 @@
 | Capability | How to Use |
 |-----------|-----------|
 | [Capability] | [Endpoint, command, or "automatic"] |
+
+## Evidence
+
+<!-- REQUIRED if this release claims to fix a bug. -->
+<!-- Unit tests passing is NOT evidence. Provide ONE of: -->
+<!--   (a) Reproduction steps + observed before/after on a live system. -->
+<!--       Include log excerpts, observed command output, or behavior -->
+<!--       description. Make it specific enough that a future reader can -->
+<!--       re-run it and see the same thing. -->
+<!--   (b) "Not reproducible in dev — [concrete reason]" if the failure -->
+<!--       mode truly can't be exercised locally (race conditions, -->
+<!--       event-driven paths requiring external signals, etc). -->
+<!--                                                                 -->
+<!-- If this release doesn't claim a bug fix (pure feature / refactor), -->
+<!-- leave this section blank or delete it — it's only enforced when -->
+<!-- "What Changed" describes a fix. -->
+
+[Describe reproduction + verified fix, OR "Not reproducible in dev — [concrete reason]"]

package/upgrades/0.28.10.md

@@ -1,19 +0,0 @@
-# Upgrade Guide — v0.28.10
-
-<!-- bump: patch -->
-
-## What Changed
-
-Job gate checks now retry up to 3 times with a 5-second delay between attempts before recording a skip. Previously, a single gate failure (e.g., health check returning non-zero during a brief server restart) would immediately skip the job. This caused guardian jobs scheduled at minute 0 to consistently miss their windows when the server restarts hourly at the same time.
-
-The existing `scheduleRetry` mechanism (1min, 5min, 15min escalating retries) remains as a second layer, but the in-gate retry handles the most common case: a health endpoint that's unavailable for a few seconds during restart.
-
-## What to Tell Your User
-
-- **More reliable scheduled jobs**: "Jobs that depend on health checks are now more resilient to brief server restart windows. If you've noticed guardian or monitoring jobs being skipped, they should start running consistently now."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Gate retry on transient failure | Automatic — no configuration needed |

package/upgrades/0.28.11.md

@@ -1,19 +0,0 @@
-# Upgrade Guide — v0.28.11
-
-<!-- bump: patch -->
-
-## What Changed
-
-The GET /context endpoint now includes the `contextDir` path in its response, making it possible for agents to verify that the server is looking in the same directory where their context files live. This helps diagnose the "0 bytes for all segments" issue that occurs when there's a path mismatch between the server's configured state directory and where hooks/sessions create context files.
-
-Response format changed from an array of segments to `{ contextDir: string, segments: [...] }`.
-
-## What to Tell Your User
-
-- **Better context diagnostics**: "If your context segments ever show as empty despite files being on disk, the context endpoint now shows the exact directory path the server is checking. This makes it easy to spot path mismatches."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Context directory path in response | GET /context now returns contextDir alongside segments |

package/upgrades/0.28.13.md

@@ -1,11 +0,0 @@
-## What Changed
-
-- **Prerequisites installer now auto-installs Homebrew on macOS.** Previously, on a fresh Mac without Homebrew, the installer would bail out and tell the user to install Homebrew manually. Now it offers to install Homebrew non-interactively using the official install script, then proceeds to install tmux via `brew install tmux`.
-
-## What to Tell Your User
-
-Nothing — this is a seamless improvement to the setup experience. Users on fresh Macs will now be prompted to install Homebrew automatically instead of being told to do it themselves.
-
-## Summary of New Capabilities
-
-- `npx instar` on a fresh macOS machine now handles the full dependency chain: Homebrew -> tmux -> Claude CLI, all with interactive prompts and no manual steps required.

package/upgrades/0.28.15.md

@@ -1,11 +0,0 @@
-## What Changed
-
-- **Fixed Homebrew installer failing on admin accounts.** The previous version used NONINTERACTIVE mode which prevented the sudo password prompt, causing installation to fail even on admin accounts with a misleading "needs to be an Administrator" error. Now stdio is inherited so the user can enter their password when prompted. Timeout also increased to 10 minutes to accommodate Xcode Command Line Tools installation.
-
-## What to Tell Your User
-
-Nothing — this is a fix to the setup experience. Installing on a fresh Mac will now correctly prompt for the password instead of failing silently.
-
-## Summary of New Capabilities
-
-No new capabilities — bug fix to Homebrew auto-install from 0.28.13.

package/upgrades/0.28.18.md

@@ -1,12 +0,0 @@
-## What Changed
-
-- **GitHub CLI is now a real prerequisite.** Previously the setup wizard only emitted a soft warning when gh was missing, then continued without it — silently disabling cloud-backed agent discovery, GitHub backup sync, CI status checks, and PR/issue management. GitHub CLI is now part of the prerequisites check alongside Node.js, tmux, and Claude CLI, with auto-install support via Homebrew on macOS and apt on Linux. If Homebrew is missing on macOS, the wizard offers to install Homebrew first (same flow as the existing tmux path).
-
-## What to Tell Your User
-
-If you're on a fresh machine, the setup wizard will now offer to install GitHub CLI automatically. After install, I can help you sign in to GitHub so I can sync state across machines and discover any other agents you've set up. Without GitHub CLI, I still work locally but can't back things up to GitHub or find your other agents.
-
-## Summary of New Capabilities
-
-- GitHub CLI added as a fourth prerequisite with auto-install on macOS (Homebrew) and Linux (apt)
-- Two-step install flow: if Homebrew is missing on macOS, wizard offers to install it before installing GitHub CLI

package/upgrades/0.28.20.md

@@ -1,19 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- bump: patch -->
-
-## What Changed
-
-- **Setup wizard now offers GitHub sign-in BEFORE asking for an agent name.** Previously, when GitHub CLI was installed but not authenticated (or when the discovery scan ran without GitHub access), the wizard silently moved on to "what should we call your agent?" — even if the user already had agents backed up to GitHub from another machine. Users were creating duplicates instead of restoring. The Entry Point B branches in `setup-wizard/SKILL.md` for `gh_status="auth-needed"` and `gh_status="unavailable"` are now MANDATORY blocking steps with imperative language.
-- **GitHub Device-Code Auth Flow documented.** Running `gh auth login --web --git-protocol https` synchronously inside Claude Code's Bash tool blocks on the device-code prompt and the user sees a frozen command with no instructions. The skill now instructs the agent to: run gh auth in the background, poll its output for the device code and URL, present them to the user conversationally, then poll `gh auth status` until the user completes the sign-in. Same flow is referenced from Phase 4 (cloud backup) so there's one canonical pattern.
-
-## What to Tell Your User
-
-If you're setting up a fresh machine and you've used Instar before, the wizard will now offer to sign you in to GitHub first so I can find any agents you've backed up — instead of creating a duplicate. The sign-in itself is also smoother: I'll show you the code to enter at github.com/login/device right in our chat instead of leaving you staring at a stuck terminal.
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Mandatory pre-name GitHub auth offer | Automatic during setup wizard |
-| Background device-code auth flow | Automatic during setup wizard |

package/upgrades/0.28.21.md

@@ -1,23 +0,0 @@
-# Upgrade Guide — v0.28.21
-
-<!-- bump: patch -->
-
-## What Changed
-
-- **Threadline delivery honesty**: `/messages/relay-agent` now awaits `ThreadlineRouter` and returns the real outcome (`spawned`, `resumed`, `injected`, `queued`, `error`) instead of always saying `delivered:true`. The `threadline_send` MCP tool surfaces the actual status to callers.
-- **First-contact messages no longer dropped**: `ThreadlineRouter` mints a UUID threadId for messages without one, routing them through `spawnNewThread` instead of silently returning `{handled:false}`.
-- **Fingerprint-based identity**: Reply waiters rekeyed by threadId (prevents same-name agent collisions). Self-guard compares fingerprints. Ambiguous targets (multiple agents sharing a name) now fail loudly with a fingerprint-qualifier hint.
-- **Live-session injection**: `ThreadlineRouter` tries `MessageDelivery.deliverToSession` (tmux send-keys) before falling back to spawn/resume — messages can reach already-running sessions without spawning a new process.
-
-## What to Tell Your User
-
-Agent-to-agent messaging (threadline) has been fixed. Messages between agents now actually reach the recipient's active session, first-contact messages work, and agents with the same name on different machines no longer collide.
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Honest delivery status | `threadline_send` now reports `spawned` / `resumed` / `injected` / `queued` instead of always `delivered` |
-| First-contact messaging | Just send — no threadId needed on first message, one is minted automatically |
-| Same-name agent disambiguation | Use `name:fpPrefix` format (e.g., `luna:ab12cd34`) when multiple agents share a name |
-| Live-session injection | Automatic — messages try injection into running sessions before spawning new ones |

package/upgrades/0.28.22.md

@@ -1,23 +0,0 @@
-# Upgrade Guide — v0.28.22
-
-<!-- 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
-
-- Replaced all `execSync` calls in server startup (better-sqlite3 auto-rebuild) with shell-free `execFileSync` using npm's CLI JS directly. Fixes "spawnSync /bin/sh ENOENT" failures in minimal/containerized environments.
-- Added `findNpmCli()` helper that locates npm's entry point without requiring a shell.
-- Affects `ensureSqliteBindings()` preflight and TopicMemory auto-rebuild fallback.
-
-## What to Tell Your User
-
-- **Better startup reliability**: "Agents running in Docker or minimal Linux environments should no longer see SemanticMemory or TopicMemory degradation at startup. The native module rebuild now works without requiring a system shell."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Shell-free native module rebuild | Automatic — no user action needed |

package/upgrades/0.28.23.md

@@ -1,19 +0,0 @@
-# Upgrade Guide — v0.28.23
-
-<!-- bump: patch -->
-
-## What Changed
-
-- Replaced all shell-dependent npm calls in server startup (better-sqlite3 auto-rebuild) with shell-free alternatives using npm's CLI JS directly via Node.js. Fixes "spawnSync /bin/sh ENOENT" failures in minimal/containerized environments.
-- Added findNpmCli helper that locates npm's entry point without requiring a shell.
-- Affects ensureSqliteBindings preflight and TopicMemory auto-rebuild fallback.
-
-## What to Tell Your User
-
-- **Better startup reliability**: "Agents running in Docker or minimal Linux environments should no longer see memory system degradation at startup. The native module rebuild now works without requiring a system shell."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Shell-free native module rebuild | Automatic — no user action needed |

package/upgrades/0.28.24.md

@@ -1,18 +0,0 @@
-# Upgrade Guide — v0.28.24
-
-<!-- bump: patch -->
-
-## What Changed
-
-- The /semantic/export-memory endpoint no longer overwrites MEMORY.md when SemanticMemory has 0 entities. Previously, an empty export would destroy manually-curated memory content. Now skips the write and returns existing file metadata with a skipped flag.
-- MemoryExporter.write() guards against empty-entity overwrites at the class level.
-
-## What to Tell Your User
-
-- **Memory file protection**: "Your MEMORY.md is now safe from accidental overwrites. If the knowledge graph hasn't been populated yet, the export will leave your existing memory file untouched instead of replacing it with an empty template."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Empty-export guard | Automatic — no user action needed |

package/upgrades/0.28.25.md

@@ -1,21 +0,0 @@
-# Upgrade Guide — v0.28.25
-
-<!-- bump: patch -->
-
-## What Changed
-
-- Fixed dashboard apiFetch to properly pass method, headers, and body options to fetch. Feature toggles and autonomy profile changes now persist instead of silently failing as GET requests.
-- Fixed degradation-digest job gate and skill to read from the correct file path (.instar/degradations.json instead of .instar/state/degradation-events.json). The job can now actually run.
-- Fixed MemoryExporter to not overwrite existing MEMORY.md when SemanticMemory has 0 entities.
-
-## What to Tell Your User
-
-- **Dashboard feature toggles work now**: "Feature toggles and autonomy profile changes in the dashboard now actually save. Previously they appeared to toggle but silently reverted."
-- **Degradation monitoring active**: "The degradation digest job can now run properly. It was blocked by a wrong file path since it was created."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Working dashboard toggles | Toggle features in the dashboard Features tab |
-| Degradation digest job | Automatic — runs every 4 hours when degradation events exist |