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