# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

The idle-session reaper verifies idleness by reading a session's transcript, but the
probe was called with an empty project directory (`projectDir: ''`), so it looked at
`~/.claude/projects//<id>.jsonl` — a path that never exists — and EVERY session came
back "transcript-unresolved." That made the reaper structurally unable to prove any
session idle, so it kept everything (the residual blocker after #952/#955/#958). Fix:
pass the agent's real session-launch cwd (`config.projectDir`) so the transcript
resolves.

New optional `transcriptProjectDir()` dep on `SessionReaper` (wired to
`config.projectDir`); StaleSessionBackstop probe fixed the same way.

## What to Tell Your User

Nothing required — internal reaper wiring; the reaper stays opt-in. For operators
enabling it: the reaper can now actually read transcripts to confirm a session is idle
before reaping (it previously couldn't, and kept everything).

## Summary of New Capabilities

- `SessionReaperDeps.transcriptProjectDir()` — supplies the agent's launch cwd so the
  fallback probe resolves the real transcript path. Absent ⇒ '' ⇒ unresolved ⇒ KEEP
  (safe default preserved).

## Evidence

`tests/unit/session-reaper.test.ts` (hermetic, HOME-overridden): fallback probe resolves
a real transcript when `transcriptProjectDir` is wired (→ reap-eligible), stays
`transcript-unresolved` (KEEP) when absent. 37/37 green. `tsc --noEmit` clean.

## Scope (honest)

Keystone of the resource chain (#952 → #955 → #958 → this): the prior unblocks only take
effect once the reaper can verify idle, which this enables. Does NOT flip the reaper live
(still dry-run, validated by observation). Does NOT address the transcript pile-up it
surfaced (echo: 151,814 files / 5.9 GB across 132 project dirs) — a separate retention
follow-up.
