instar 0.28.35 → 0.28.41

package/scripts/upgrade-guide-validator.mjs

@@ -0,0 +1,221 @@
+// Pure validation logic for upgrade guides — no filesystem side effects.
+// The CLI entry point (check-upgrade-guide.js) wraps this with I/O.
+// Extracted for unit testability.
+
+export const REQUIRED_SECTIONS = [
+  '## What Changed',
+  '## What to Tell Your User',
+  '## Summary of New Capabilities',
+];
+
+export const MIN_LENGTH = 200;
+
+// Keywords that indicate the guide is claiming to fix a bug. When any of these
+// appear inside "## What Changed", the Evidence section becomes mandatory.
+// Limited to "What Changed" (not the whole doc) to reduce false positives from
+// marketing language in "What to Tell Your User".
+const FIX_PATTERNS = [
+  /\bfix(es|ed|ing)?\b/i,
+  /\bbug(fix)?\b/i,
+  /\bregression\b/i,
+  /\bresolves?\b/i,
+  /\bresolved\b/i,
+  /\bcrashes?\b/i,
+  /\bcrashed\b/i,
+  /\bcrashing\b/i,
+  /\bbroken\b/i,
+  /\bstall(s|ed|ing)?\b/i,
+];
+
+export const NEXT_TEMPLATE = `# Upgrade Guide — vNEXT
+
+<!-- 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
+
+<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
+<!-- Write this for the AGENT — they need to understand the system deeply. -->
+
+## What to Tell Your User
+
+<!-- Write talking points the agent should relay to their user. -->
+<!-- This should be warm, conversational, user-facing — not a changelog. -->
+<!-- Focus on what THEY can now do, not internal plumbing. -->
+<!--                                                                    -->
+<!-- PROHIBITED in this section (will fail validation):                 -->
+<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
+<!--   Inline code backtick references like silentReject: false        -->
+<!--   Fenced code blocks                                              -->
+<!--   Instructions to edit files or run commands                      -->
+<!--                                                                    -->
+<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
+<!-- The agent relays this to their user — keep it human.              -->
+
+- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
+
+## Summary of New Capabilities
+
+| 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]"]
+`;
+
+/**
+ * Extract the content of a markdown H2 section by title. Returns the section
+ * body (between `## Title` and the next `## ` or end of file), or null if the
+ * section isn't present.
+ */
+export function extractSection(content, title) {
+  const pattern = new RegExp(`## ${title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([\\s\\S]*?)(?:\\n## |$)`);
+  const m = content.match(pattern);
+  return m ? m[1] : null;
+}
+
+/**
+ * Does the guide claim to fix a bug? Scans "## What Changed" for fix-indicating
+ * keywords. Returns true when any pattern matches.
+ */
+export function claimsFix(content) {
+  const section = extractSection(content, 'What Changed');
+  if (!section) return false;
+  return FIX_PATTERNS.some(p => p.test(section));
+}
+
+/**
+ * Validate the Evidence section when a fix is claimed. Returns an array of
+ * issue strings (empty when valid).
+ */
+export function evidenceIssues(content) {
+  const issues = [];
+  const section = extractSection(content, 'Evidence');
+  if (section === null) {
+    issues.push(
+      '"What Changed" claims a bug fix, but the guide has no "## Evidence" section. ' +
+      'Add one with reproduction + observed before/after, or "Not reproducible in dev — [reason]". ' +
+      'Unit tests passing is not evidence.'
+    );
+    return issues;
+  }
+  // Strip HTML comments and trim
+  const stripped = section.replace(/<!--[\s\S]*?-->/g, '').trim();
+  if (!stripped) {
+    issues.push(
+      '"## Evidence" section is empty (only template comments). ' +
+      'Fill it in with reproduction + verified fix, or "Not reproducible in dev — [reason]".'
+    );
+    return issues;
+  }
+  // Reject obvious placeholder text
+  if (
+    /\[Describe reproduction/i.test(stripped) ||
+    /\[evidence goes here\]/i.test(stripped) ||
+    /TODO\b/.test(stripped) ||
+    /FIXME\b/.test(stripped)
+  ) {
+    issues.push(
+      '"## Evidence" section still contains placeholder text. ' +
+      'Replace it with a real reproduction + verification, or explicit "Not reproducible in dev — [reason]".'
+    );
+    return issues;
+  }
+  // Require at least 80 chars of real content — any less and it can't describe
+  // a reproduction meaningfully.
+  if (stripped.length < 80) {
+    issues.push(
+      `"## Evidence" section is too short (${stripped.length} chars). ` +
+      'Include concrete reproduction + observed before/after, or "Not reproducible in dev" with a concrete reason.'
+    );
+  }
+  return issues;
+}
+
+/**
+ * Full structural validation of a guide's content. Returns issue strings.
+ */
+export function validateGuideContent(content) {
+  const issues = [];
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!content.includes(section)) {
+      issues.push(`missing "${section}" section`);
+    }
+  }
+
+  if (content.length < MIN_LENGTH) {
+    issues.push(`guide is too short (${content.length} chars, minimum ${MIN_LENGTH}) — probably incomplete`);
+  }
+
+  // Template placeholders that were never filled in
+  if (content.includes('<!-- Describe what changed')) {
+    issues.push('"What Changed" section still contains template placeholder — fill it in');
+  }
+  if (content.includes('[Feature name]') || content.includes('[Brief, friendly description')) {
+    issues.push('"What to Tell Your User" section still contains template placeholder — fill it in');
+  }
+  if (content.includes('[Capability]') && content.includes('[Endpoint, command')) {
+    issues.push('"Summary of New Capabilities" section still contains template placeholder — fill it in');
+  }
+
+  // "What to Tell Your User" technical-leakage checks
+  const userSection = extractSection(content, 'What to Tell Your User');
+  if (userSection) {
+    const camelCaseConfigKey = /\b[a-z]+[A-Z][a-zA-Z]+\s*(?::|=)/.test(userSection);
+    if (camelCaseConfigKey) {
+      issues.push(
+        '"What to Tell Your User" contains a camelCase config key reference (e.g. "silentReject: false"). ' +
+        'Users should never be told to edit config directly. ' +
+        'Rephrase conversationally: "I can turn that on for you" not "set silentReject: false".'
+      );
+    }
+    if (/`[^`]+`/.test(userSection)) {
+      issues.push(
+        '"What to Tell Your User" contains inline code (`...`). ' +
+        'Remove code formatting — user-facing language should be plain and conversational.'
+      );
+    }
+    if (/```/.test(userSection)) {
+      issues.push(
+        '"What to Tell Your User" contains a fenced code block. ' +
+        'This section is for user-facing narrative — move technical examples to "What Changed".'
+      );
+    }
+  }
+
+  // Evidence bar — when the guide claims a fix, require an Evidence section.
+  if (claimsFix(content)) {
+    issues.push(...evidenceIssues(content));
+  }
+
+  return issues;
+}
+
+/**
+ * Parse the declared bump type from a guide's <!-- bump: TYPE --> comment.
+ * Returns 'patch' | 'minor' | 'major' | null.
+ */
+export function parseBumpType(content) {
+  const match = /<!--\s*bump:\s*(patch|minor|major)\s*-->/.exec(content);
+  return match ? match[1] : null;
+}

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-15T08:32:09.822Z",
+  "instarVersion": "0.28.41",
   "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.41.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — v0.28.41
+
+<!-- bump: patch -->
+
+## What Changed
+
+Two fixes for volatile state that didn't survive restarts in the Threadline REST adapter and relay offline queue:
+
+1. **REST thread history now persists to disk.** `ThreadlineRESTServer` previously held thread history in memory only, so restarts lost all conversation history even when the client-side MessageStore had messages on disk. The server now hydrates from `~/.threadline/thread-history.json` on startup and persists debounced (1s) on incoming messages and thread deletions. Writes are atomic (temp file + rename) and size-bounded by the existing `maxMessageHistoryPerThread` cap. New config: `historyPath` (default `~/.threadline/thread-history.json`) and `persistHistory` (default `true`, set `false` for tests/ephemeral servers).
+
+2. **Offline queue default TTL extended from 1h to 24h.** `InMemoryOfflineQueue`'s 1-hour default was shorter than typical offline/restart windows for agents, so messages to offline recipients expired before reconnection. Configurable via `OfflineQueueConfig.defaultTtlMs` if you need different behavior.
+
+No API breakage. Existing servers/queues using defaults just get more durable behavior.
+
+## What to Tell Your User
+
+- **Conversation history survives restarts**: "Your thread history will stick around now even if I get restarted — no more losing context from earlier in our conversation."
+- **Messages wait longer for offline agents**: "If you message another agent who's offline, the message will wait up to a day for them to come back online instead of expiring after an hour."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Persistent REST thread history | Automatic (opt-out via `persistHistory: false`) |
+| 24h offline message retention | Automatic (override via `defaultTtlMs`) |
+
+## Evidence
+
+Reproduction before fix:
+1. Start `npx @anthropic-ai/threadline serve --port 18800`
+2. Receive messages on a thread → `GET /threads/{id}` returns them
+3. Restart the server
+4. `GET /threads/{id}` returns 404 — history lost
+
+After fix:
+1. Same steps 1–2
+2. Within 1s, `~/.threadline/thread-history.json` contains the thread
+3. Restart the server
+4. `GET /threads/{id}` returns the same messages — hydrated from disk
+
+Unit tests (40/40 passing in `OfflineQueue.test.ts` and `RESTServerE2E.test.ts`) cover the default config values and existing REST flows; persistence is best-effort (wrapped in try/catch) so disk failures don't crash the server.

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]"]