@gotgenes/pi-subagents 17.4.0 → 17.5.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [17.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.4.0...pi-subagents-v17.5.0) (2026-06-23)
+
+
+### Features
+
+* **pi-subagents:** add file-snapshot transcript source ([06a9ee3](https://github.com/gotgenes/pi-packages/commit/06a9ee39b5f529f770c39cf8d8bdcefd1511bb7d))
+* **pi-subagents:** retain evicted-agent descriptors in the manager ([3128e2a](https://github.com/gotgenes/pi-packages/commit/3128e2a44b94be9b976b74d24cf5127ca0944074))
+* **pi-subagents:** source evicted-agent transcripts from disk in /subagent-sessions ([b4da762](https://github.com/gotgenes/pi-packages/commit/b4da762b0574b49e028518c62e7b2f11acaf1ad4))
+
 ## [17.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.3.0...pi-subagents-v17.4.0) (2026-06-23)
 
 

package/docs/architecture/architecture.md

@@ -1036,16 +1036,23 @@ Selection and sourcing are untouched; native navigation now renders at parity, u
 
 `Release: independent`
 
-### Step 4b — File-snapshot source for evicted agents ([#463])
+### ✅ Step 4b — File-snapshot source for evicted agents ([#463])
 
 Smell: Category C (coupling) — the #445 slice sources transcripts live from `manager.listAgents()` only; an agent evicted by the 10-minute cleanup sweep has a persisted session JSONL but no live record, so it is unreachable.
-This step adds the file-snapshot `TranscriptSource` branch (`parseSessionEntries(readFile(outputFile))` → drop the `SessionHeader` → `buildSessionContext(...).messages`) and broadens the candidate set to enumerate evicted agents, behind the same seam; the renderer is untouched.
+This step adds the file-snapshot `TranscriptSource` branch (`parseSessionEntries(readFile(outputFile))` → drop the `SessionHeader` → `buildSessionContext(...).messages`) and broadens the candidate set to evicted agents, behind the same seam; the renderer is untouched.
 
 Independent: this is a new capability the bespoke viewer never had, so it gates nothing and is not a Step 5 prerequisite.
 Best sequenced after Step 4a (shared renderer), but carries no hard dependency.
 
 Outcome: the operator can view a fully-evicted agent's transcript from its persisted session file; the dual-source design recorded in [ADR-0004] Addendum 2 is fully realized.
 
+Landed ([#463]): `fileSnapshotSource(outputFile, readFile)` lands in the pure `session-navigation.ts` (`parseSessionEntries` → drop the `SessionHeader` → `buildSessionContext(...).messages`; a static no-subscribe, no-streaming source).
+The candidate set is broadened via **manager-retained descriptors**, not a directory scan: the persisted child session carries no subagent `type`/`description` (those live only on the in-memory record), so a scan would yield degraded labels and parse every file per open.
+Instead `SubagentManager.cleanup()` stashes a lightweight `EvictedSubagent` descriptor (label fields + `outputFile`, no messages) before disposing a record with a persisted file, exposed via `listEvicted()` and cleared by `clearCompleted()`/`dispose()`.
+`NavigationEntry` became a `live | evicted` discriminated union; the handler selects `liveSource` vs `fileSnapshotSource` by kind inside a `try/catch` (an unreadable file notifies and skips), and `index.ts` injects `readFileSync`.
+Evicted entries carry an `· evicted (snapshot)` label marker.
+Coverage is in-session evictions (the sweep's only targets); old-session orphan files — the ones a scan would surface with degraded labels — are out of scope.
+
 `Release: independent`
 
 ### Step 5 — Dissolve `/agents` and remove the conversation-viewer subtree ([#442])
@@ -1111,7 +1118,7 @@ flowchart LR
     S3["✅ Step 3 - Background widget (#444)"]
     S4["✅ Step 4 - Native session nav slice (#445)"]
     S4a["✅ Step 4a - Renderer to TUI components (#462)"]
-    S4b["Step 4b - File-snapshot source (#463)"]
+    S4b["✅ Step 4b - File-snapshot source (#463)"]
     S5["Step 5 - Dissolve /agents + viewer (#442)"]
     S6["Step 6 - Remove definition mgmt (#441)"]
     S7["Step 7 - Test clones (#443)"]

package/docs/decisions/0004-reconsider-ui-direction.md

@@ -248,7 +248,15 @@ This matches the bespoke viewer's current reach (gated on `record.isSessionReady
 A foreground agent is navigable only _after_ it completes — while it runs, the root turn is blocked on it — whereas a background agent is navigable live.
 The background widget ([#444]) remains the optional secondary selection gesture for background agents; the command is the primary, unit-testable surface.
 
+**Evicted-agent candidate set ([#463]).**
+Step 4b realizes the file-snapshot branch for fully-evicted agents.
+The candidate set is broadened via **manager-retained descriptors**, not a directory scan of the tasks directory: the persisted child session carries no subagent `type`/`description` (those live only on the in-memory record), so a scan yields degraded labels and parses every file per picker open.
+The cleanup sweep instead stashes a lightweight `EvictedSubagent` descriptor (label fields + `outputFile`, no messages) before disposing a record, preserving rich labels and bounded memory.
+This covers in-session evictions — the sweep's only targets, since a fresh manager per session never reloads prior-process subagents.
+The "render from the file snapshot" mechanism for an evicted agent (above) is unchanged; only the candidate-set _enumeration_ is pinned to descriptors.
+
 [#444]: https://github.com/gotgenes/pi-packages/issues/444
 [#445]: https://github.com/gotgenes/pi-packages/issues/445
 [#446]: https://github.com/gotgenes/pi-packages/issues/446
 [#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#463]: https://github.com/gotgenes/pi-packages/issues/463

package/docs/plans/0463-file-snapshot-source-evicted-agents.md

@@ -0,0 +1,306 @@
+---
+issue: 463
+issue_title: "pi-subagents: add file-snapshot source to /subagent-sessions for evicted agents"
+---
+
+# File-snapshot source for evicted agents in `/subagent-sessions`
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Architecture roadmap Phase 19 Step 4b ([#463]) carries `Release: independent`.
+This is a new capability the bespoke viewer never had — it gates nothing and is not a Step 5 prerequisite — so it ships on its own once landed.
+
+## Problem Statement
+
+The [#445] native-session-navigation slice sources transcripts live, from `manager.listAgents()` only.
+The manager's cleanup sweep (`SubagentManager.cleanup()`, every 60 s) disposes a completed/stopped/errored record 10 minutes after it finishes — `disposeSession()` frees the heavy in-memory session (its message history included) and the record is deleted from the map.
+The lightweight session JSONL persists on disk at `Subagent.outputFile`, but with no live record the agent is unreachable from `/subagent-sessions`.
+
+This step makes a fully-evicted agent navigable: it adds the file-snapshot `TranscriptSource` branch the #445 seam was designed for, and broadens the picker's candidate set to include evicted agents.
+
+## Goals
+
+- Implement `fileSnapshotSource(outputFile, readFile)` in `src/ui/session-navigation.ts`: `parseSessionEntries(readFile(outputFile))` → drop the `SessionHeader` → `buildSessionContext(...).messages` → a static (no-subscribe, no-streaming) `TranscriptSource`.
+- Broaden the `/subagent-sessions` candidate set to include evicted agents, deduped against live records.
+- Render an evicted agent's transcript read-only from its persisted file when picked; the renderer (`buildTranscriptComponents`) and overlay (`TranscriptOverlay`) are untouched.
+- Inject `readFile` as a parameter so the pure module performs no `fs` calls.
+
+This change is **not** breaking: it is additive (a new source branch and a broadened candidate set); no existing behavior, output shape, or default changes for a tracked agent.
+
+## Non-Goals
+
+- No directory scan of the tasks directory and no surfacing of prior-process orphan session files (see Design Overview → Candidate-set decision).
+- No change to the cleanup sweep's 10-minute eviction policy or to `disposeSession()`.
+- No renderer or overlay changes — `session-navigator.ts`'s `buildTranscriptComponents` / `TranscriptOverlay` / `addMessageComponents` are unchanged (Step 4a, [#462], already brought them to parity).
+- No `switchSession` / `loadEntriesFromFile` (rejected by the Step 1 spike, [#446]).
+- No live re-read or file-watching of the snapshot — a file source is a static snapshot by design.
+
+## Background
+
+Relevant modules:
+
+- `src/ui/session-navigation.ts` — the pure, unit-testable core: `NavigableSubagent` (narrow record view), `NavigationEntry`, `TranscriptSource`, `listNavigableAgents(agents, registry)`, `liveSource(record)`, `buildLabel(record, registry)`.
+  It imports SDK *types* only (`ToolDefinition`) and the lifecycle type `SubagentStatus`.
+- `src/ui/session-navigator.ts` — the SDK/TUI consumer half: `SessionNavigatorHandler` (picker + source selection) and `TranscriptOverlay` (read-only scrollable renderer).
+  The handler already calls `liveSource(entry.record)`; the source is the only seam that varies.
+- `src/lifecycle/subagent-manager.ts` — `listAgents()` (sorted live records), `cleanup()` (the 10-minute sweep), `clearCompleted()` (new-session wipe, called from `handlers/lifecycle.ts` on `session_start` / `session_before_switch`), `removeRecord()` (`disposeSession()` + `agents.delete`).
+- `src/lifecycle/subagent.ts` — `Subagent` exposes `id`, `type`, `description` (readonly), and getters `status`, `startedAt`, `completedAt`, `toolUses`, `outputFile`.
+- `src/index.ts` — registers `subagent-sessions`, calling `sessionNavigator.handle({ ui, agents: manager.listAgents(), registry, cwd })`.
+
+SDK functions (`@earendil-works/pi-coding-agent`): `parseSessionEntries(content): FileEntry[]`, `buildSessionContext(entries: SessionEntry[]): { messages: AgentMessage[]; … }`, and the types `SessionEntry` / `SessionHeader`.
+`FileEntry = SessionHeader | SessionEntry`; only the header has `type: "session"`, so `entries.filter((e): e is SessionEntry => e.type !== "session")` is a sound type guard.
+`SessionMessage` (the navigator's message type) is `SessionContext["messages"][number]` = `AgentMessage`, so `buildSessionContext(...).messages` matches `TranscriptSource.getMessages()` with no cast.
+
+Constraints from AGENTS.md / skills that apply:
+
+- `code-design` SDK-boundary guideline: pure helpers should avoid SDK *runtime* imports.
+  `fileSnapshotSource` calls the SDK runtime functions `parseSessionEntries` / `buildSessionContext` directly (see Design Overview → SDK-runtime decision); there is no `no-restricted-imports` lint rule, and the module already depends on SDK types.
+- `testing`: components used by `session-navigator.ts` need `initTheme(undefined, false)` in `beforeAll` (already present in `session-navigator.test.ts`).
+- `fallow dead-code`: a new export with no caller fails the gate.
+  Producers (`fileSnapshotSource`, `listEvicted`) gain their caller in the integration step within the same push; the pushed tip is dead-code-clean (see Risks).
+
+## Design Overview
+
+### Candidate-set decision — manager-retained descriptors (not a directory scan)
+
+The issue proposes enumerating persisted JSONL files in the tasks directory.
+The persisted child session carries **no** subagent `type` or `description` — those live only on the in-memory `Subagent` record; the file holds only the conversation plus a header (`id`, `timestamp`, `cwd`, `parentSession`).
+A directory scan therefore yields degraded labels (agent type → generic placeholder; curated `description` → a raw first-prompt snippet or filename) and must parse every file on every picker open.
+
+Decision (confirmed with the operator): the manager retains a lightweight **descriptor** at eviction time instead.
+When `cleanup()` disposes a record that has a persisted file, it first copies the record's label fields plus `outputFile` into a separate `evicted` map (no messages — the heavy state is still freed, so memory stays bounded by the number of subagents spawned, not their transcripts).
+The picker's candidate set is `live ∪ evicted`, deduped by id, with identical rich labels for both.
+
+Coverage: this surfaces agents evicted **in the current root session** — which are the cleanup sweep's only targets.
+A fresh `SubagentManager` is created per session and `clearCompleted()` runs on `session_start`, so prior-process subagents are never reloaded into the manager; the only files a directory scan would *additionally* surface are old-session orphans, which are exactly the ones with degraded labels.
+Picking an evicted agent still reads its file to render (the messages are gone from memory regardless) — so `fileSnapshotSource` is required either way; the descriptor only feeds the *label*.
+
+### SDK-runtime decision — call `parseSessionEntries` / `buildSessionContext` directly
+
+`fileSnapshotSource` imports and calls these SDK runtime functions directly rather than injecting them.
+Rationale: they are deterministic parsers of Pi's own session format; the injected `readFile` already provides the unit-test seam (a fake `readFile` returning fixture JSONL fully exercises parse → drop-header → build → messages), so injecting the parsers adds wiring without testability gain.
+There is no `no-restricted-imports` rule, and `session-navigation.ts` already imports SDK types.
+
+### Data shapes
+
+`EvictedSubagent` — the descriptor, owned by lifecycle (the manager constructs it), imported as a type by the UI (the UI already imports `SubagentStatus` from lifecycle):
+
+```typescript
+// src/lifecycle/subagent-manager.ts
+export interface EvictedSubagent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+  readonly outputFile: string;
+}
+```
+
+`NavigationEntry` changes from `{ record, label }` to a discriminated union so the handler can pick the source by kind:
+
+```typescript
+// src/ui/session-navigation.ts
+export type NavigationEntry =
+  | { readonly kind: "live"; readonly label: string; readonly record: NavigableSubagent }
+  | { readonly kind: "evicted"; readonly label: string; readonly outputFile: string };
+```
+
+`buildLabel` is narrowed to a per-call interface (ISP) that both a `NavigableSubagent` and an `EvictedSubagent` satisfy, and gains an `evicted` marker:
+
+```typescript
+interface LabelFields {
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+}
+
+function buildLabel(fields: LabelFields, registry: AgentConfigLookup, evicted = false): string {
+  const name = getDisplayName(fields.type, registry);
+  const duration = formatDuration(fields.startedAt, fields.completedAt);
+  const marker = evicted ? " · evicted (snapshot)" : "";
+  return `${name} (${fields.description}) · ${fields.toolUses} tools · ${fields.status} · ${duration}${marker}`;
+}
+```
+
+### `fileSnapshotSource`
+
+```typescript
+export function fileSnapshotSource(
+  outputFile: string,
+  readFile: (path: string) => string,
+): TranscriptSource {
+  const entries = parseSessionEntries(readFile(outputFile));
+  const sessionEntries = entries.filter(
+    (entry): entry is SessionEntry => entry.type !== "session",
+  );
+  const { messages } = buildSessionContext(sessionEntries);
+  return {
+    getMessages: () => messages,
+    subscribe: () => undefined, // static snapshot — no live updates
+    streaming: () => undefined, // never streaming
+    getToolDefinition: () => undefined, // no live tool registry off disk
+  };
+}
+```
+
+### `listNavigableAgents` (broadened) and the handler call site
+
+```typescript
+export function listNavigableAgents(
+  agents: readonly NavigableSubagent[],
+  evicted: readonly EvictedSubagent[],
+  registry: AgentConfigLookup,
+): NavigationEntry[] {
+  const live = agents
+    .filter((record) => record.isSessionReady())
+    .map((record): NavigationEntry => ({ kind: "live", record, label: buildLabel(record, registry) }));
+  const liveIds = new Set(agents.map((record) => record.id));
+  const evictedEntries = evicted
+    .filter((d) => !liveIds.has(d.id))
+    .map((d): NavigationEntry => ({ kind: "evicted", outputFile: d.outputFile, label: buildLabel(d, registry, true) }));
+  return [...live, ...evictedEntries];
+}
+```
+
+Dedup is keyed by `id` (both shapes carry it) rather than `outputFile`: a record leaves `listAgents()` at the same instant its descriptor is captured, so the sets cannot overlap; the filter is defensive.
+Order is live-then-evicted, which is already recency-ordered (evicted agents completed > 10 min ago).
+
+Handler consumer sketch (Tell-Don't-Ask: the entry tells the handler its kind; the handler asks the right source constructor — no reach-through into the record's internals):
+
+```typescript
+const entry = entries.find((candidate) => candidate.label === choice);
+if (!entry) return;
+let source: TranscriptSource;
+try {
+  source = entry.kind === "live" ? liveSource(entry.record) : fileSnapshotSource(entry.outputFile, readFile);
+} catch {
+  ui.notify("Could not read the session transcript file.", "error");
+  return;
+}
+// …unchanged: getMarkdownTheme(), ui.custom(new TranscriptOverlay({ source, … }))
+```
+
+### Manager retention sketch
+
+```typescript
+private readonly evicted = new Map<string, EvictedSubagent>();
+
+private cleanup() {
+  const cutoff = Date.now() - 10 * 60_000;
+  for (const [id, record] of this.agents) {
+    if (record.status === "running" || record.status === "queued") continue;
+    if ((record.completedAt ?? 0) >= cutoff) continue;
+    if (record.outputFile) this.evicted.set(id, toEvictedSubagent(record));
+    this.removeRecord(id, record);
+  }
+}
+
+listEvicted(): EvictedSubagent[] {
+  return [...this.evicted.values()].sort((a, b) => b.startedAt - a.startedAt);
+}
+```
+
+`clearCompleted()` and `dispose()` also `this.evicted.clear()` — descriptors belong to the session that evicted them, so a new session starts empty.
+`toEvictedSubagent(record)` copies the eight fields; it is a private helper (or a free function in the module) and reads `record.outputFile` only after the `if (record.outputFile)` guard, so the `outputFile` field is always a defined `string`.
+
+### Edge cases
+
+- **`outputFile` undefined at eviction** (headless / never-persisted session) → no descriptor captured; nothing to navigate.
+- **File deleted/unreadable after eviction** → `fileSnapshotSource`'s eager read throws; the handler's `try/catch` notifies and returns without opening the overlay.
+- **Empty or header-only JSONL** → `buildSessionContext` returns `messages: []`; the overlay renders an empty transcript (no crash).
+- **No navigable sessions at all** (no live, no evicted) → existing `ui.notify("No subagent sessions to view.", "info")` path, unchanged.
+
+## Module-Level Changes
+
+- `src/lifecycle/subagent-manager.ts` — add the `EvictedSubagent` interface (exported), the `evicted` map field, descriptor capture in `cleanup()`, `evicted.clear()` in `clearCompleted()` and `dispose()`, the `listEvicted()` method, and the `toEvictedSubagent` helper.
+  Import `SubagentType` (already in `#src/types`) and `SubagentStatus` (`#src/lifecycle/subagent-state`) for the interface.
+- `src/ui/session-navigation.ts` — add `fileSnapshotSource`; import `EvictedSubagent` (type), and the SDK runtime `parseSessionEntries` / `buildSessionContext` plus the `SessionEntry` type; change `NavigationEntry` to the discriminated union; broaden `listNavigableAgents` to `(agents, evicted, registry)`; narrow `buildLabel` to `LabelFields` + `evicted` flag.
+- `src/ui/session-navigator.ts` — `SessionNavigatorParams` gains `evicted: readonly EvictedSubagent[]` and `readFile: (path: string) => string`; the handler selects the source by `entry.kind` inside a `try/catch`.
+  No change to `TranscriptOverlay`, `buildTranscriptComponents`, `addMessageComponents`, or `addUserComponents`.
+- `src/index.ts` — add `import { readFileSync } from "node:fs"`; the `subagent-sessions` handler passes `evicted: manager.listEvicted()` and `readFile: (path) => readFileSync(path, "utf8")`.
+- `docs/architecture/architecture.md` — mark Step 4b ([#463]) **Landed** with a note recording the descriptor-vs-scan decision and that ADR-0004 Addendum 2's dual-source design is now realized; flip the `S4b` node label in the step-dependency Mermaid diagram to ✅.
+- `docs/decisions/0004-reconsider-ui-direction.md` — optional one-line note under Addendum 2 that Step 4b chose manager-retained descriptors over a directory scan (the addendum's "evicted/untracked" wording said file snapshot for *rendering*, which still holds; only the *candidate-set* mechanism is being pinned down).
+
+No SKILL update: the package SKILL's UI section references no session-navigation internals and the file/domain counts are unchanged (no new module — `fileSnapshotSource` joins the existing `session-navigation.ts`).
+The architecture LOC/complexity tables are explicit end-of-phase snapshots, not per-file inventories, so a ~30-LOC addition does not update them.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled by this change:**
+   - `fileSnapshotSource` (pure, in `session-navigation.test.ts`): fixture JSONL via a fake `readFile` → assert `getMessages()` equals the parsed messages, the `SessionHeader` is dropped, and `subscribe()` / `streaming()` / `getToolDefinition()` return `undefined`.
+   - `listNavigableAgents` with evicted descriptors: evicted entries appear with the `· evicted (snapshot)` marker; an evicted descriptor whose id matches a live record is deduped out.
+   - `SubagentManager.listEvicted()` (in `subagent-manager.test.ts`): after advancing fake timers past the cutoff, a completed agent with an `outputFile` produces a descriptor; one without an `outputFile` does not; `clearCompleted()` empties the set.
+   - `SessionNavigatorHandler` evicted path (in `session-navigator.test.ts`): picking an evicted label opens an overlay sourced from `readFile`; a throwing `readFile` notifies and skips the overlay.
+2. **Tests that become redundant:** none — the live-source tests still exercise the tracked-agent branch.
+3. **Tests that must stay as-is:** the existing `liveSource`, `listNavigableAgents` (live-only), `TranscriptOverlay`, and live-source handler tests — they pin the tracked-agent behavior this change must not regress.
+
+## Invariants at risk
+
+Step 4 (#445) and Step 4a (#462) established invariants on the navigation surface; this step must preserve them:
+
+- **Handler is a reactive consumer with no inbound call into the core** (Invariant #423/#445).
+  Pinned by the existing `session-navigator.test.ts` assertion `expect(record.getToolDefinition).not.toHaveBeenCalled()` in the live-source handler test.
+  The evicted path reads only `entry.outputFile` (a string) + the injected `readFile`; it makes no inbound call into a record.
+- **Read-only, non-interactive overlay** (#445/#446).
+  The file source returns `subscribe: () => undefined` and `streaming: () => undefined`; the overlay's existing read-only behavior is unchanged.
+  Pinned by the existing overlay tests.
+- **Renderer parity via Pi per-entry components** (#462).
+  The renderer is untouched; both sources still yield `SessionMessage[]` into the same `buildTranscriptComponents`.
+  Pinned by the existing `TranscriptOverlay` render tests.
+
+No new test is needed for these — existing tests already pin them; the integration step keeps them green.
+
+## TDD Order
+
+1. **`fileSnapshotSource` (pure, additive).**
+   Surface: `test/ui/session-navigation.test.ts`.
+   Red: a `describe("fileSnapshotSource")` with a fake `readFile` returning fixture JSONL (a `session` header line + a couple of `message` entries) — assert messages parsed, header dropped, and the three static-source methods return `undefined`.
+   Green: implement `fileSnapshotSource` and the SDK runtime imports.
+   Commit: `test(pi-subagents): cover file-snapshot transcript source` then `feat(pi-subagents): add file-snapshot transcript source` (or a single `feat` commit with test + impl).
+2. **Manager evicted-descriptor retention (additive).**
+   Surface: `test/lifecycle/subagent-manager.test.ts`.
+   Red: with fake timers, advance past the 10-minute cutoff and assert `listEvicted()` returns a descriptor for a completed agent with an `outputFile`, none for one without, and an empty set after `clearCompleted()`.
+   Green: add `EvictedSubagent`, the `evicted` map, capture in `cleanup()`, `clear()` in `clearCompleted()`/`dispose()`, `listEvicted()`, and `toEvictedSubagent`.
+   Run `pnpm run check` after this commit (new exported interface).
+   Commit: `feat(pi-subagents): retain evicted-agent descriptors in the manager`.
+3. **Integrate: broaden the candidate set and dual-source the handler (breaking the `NavigationEntry` shape).**
+   This step changes `NavigationEntry` and `listNavigableAgents`'s signature, so the handler, `index.ts` call site, and both UI test files break and are updated together.
+   Surfaces: `src/ui/session-navigation.ts`, `src/ui/session-navigator.ts`, `src/index.ts`, `test/ui/session-navigation.test.ts`, `test/ui/session-navigator.test.ts`.
+   Red: update `listNavigableAgents` tests to the union shape and add the evicted-entry (marker + dedup) cases; add the handler evicted-path tests (file source + throwing-`readFile` notify).
+   Green: change `NavigationEntry` to the union, broaden `listNavigableAgents`, narrow `buildLabel`, add `evicted` + `readFile` to `SessionNavigatorParams`, switch the handler source by kind inside `try/catch`, and wire `manager.listEvicted()` + `readFileSync` in `index.ts`.
+   Run `pnpm run check` (shared interface change with a single non-test call site).
+   Commit: `feat(pi-subagents): source evicted-agent transcripts from disk in /subagent-sessions`.
+4. **Docs.**
+   Update `docs/architecture/architecture.md` Step 4b to Landed (descriptor decision + dual-source realized) and the `S4b` diagram node to ✅; add the optional Addendum 2 note in `docs/decisions/0004-reconsider-ui-direction.md`.
+   Commit: `docs(pi-subagents): mark Phase 19 Step 4b landed (#463)`.
+
+## Risks and Mitigations
+
+- **Transient dead code between steps 1–2 and 3.**
+  `fileSnapshotSource` and `listEvicted()` have no caller until step 3.
+  CI / pre-completion `fallow dead-code` runs on the pushed tip, which is clean once step 3 lands; all steps ship in one push.
+  Mitigation: do not run `/ship-issue` before step 3 is committed.
+- **`buildSessionContext` / `parseSessionEntries` behavior on malformed JSONL.**
+  Mitigation: the handler `try/catch` covers a throwing read/parse; a TDD fixture exercises a valid header-plus-messages file, and an empty-messages case confirms a graceful empty render.
+- **Memory: the `evicted` map grows over a long session.**
+  Each descriptor is eight scalar fields (no messages), bounded by subagents spawned; the heavy session objects are still disposed.
+  `clearCompleted()` resets it per session.
+- **Divergence from the issue's "enumerate persisted JSONL files" wording.**
+  Documented and operator-confirmed (descriptors over scan, for rich labels and bounded IO); the architecture/ADR notes record the rationale so the file-scan option is not silently lost.
+
+## Open Questions
+
+None — the candidate-set strategy and the evicted-entry marker were resolved with the operator during planning.
+
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#446]: https://github.com/gotgenes/pi-packages/issues/446
+[#462]: https://github.com/gotgenes/pi-packages/issues/462
+[#463]: https://github.com/gotgenes/pi-packages/issues/463

package/docs/retro/0462-navigation-renderer-tui-components.md

@@ -47,3 +47,59 @@ Test count went from 1084 to 1088 (+4 net: +4 accessor/seam tests, +3 new naviga
   Pi's own JS passes `{ truncated: true }` but that path is untyped.
 - Pre-completion reviewer verdict: **WARN** (no failures; 3 non-blocking findings).
   Reviewer warnings: (1) `package-pi-subagents/SKILL.md` UI module count is stale (10 listed vs 13 actual) — predates this issue, plan left it deliberately; (2) `addMessageComponents` mutates the received `pendingTools` accumulator (output-argument pattern) — intentional, mirrors Pi's own `renderedPendingTools` local and was plan-reviewed; (3) invariant #423 held and is type-enforced but lacked an explicit spy pin — **addressed** by the follow-up `test:` commit asserting the handler never calls `record.getToolDefinition` directly.
+
+## Stage: Final Retrospective (2026-06-23T00:00:00Z)
+
+### Session summary
+
+Shipped Phase 19 Step 4a end-to-end across plan → TDD → ship: `/subagent-sessions` now renders through Pi's own per-entry interactive components behind the unchanged `TranscriptSource` seam, released as `pi-subagents` v17.4.0.
+Execution was notably clean — six commits, no rework of production code, CI green on the first push, and the only two friction points (a missing `initTheme()` in tests, a wrong post-review assertion) were each self-caught and resolved in a single iteration.
+
+### Observations
+
+#### What went well
+
+1. **Upfront SDK verification in planning paid off at implementation.**
+   Planning inspected the actual component constructors, the `renderSessionContext` mapping, and `AgentSession.getToolDefinition` in `node_modules/**/*.d.ts` before committing to a design.
+   Result: the production code (`session-navigation.ts`, `session-navigator.ts`, `index.ts`) type-checked clean on the *first* `tsc` run during TDD — the SDK message-union narrowing and component construction needed no casts.
+2. **Probe-driven de-risking.**
+   Before the renderer rewrite, a throwaway `_probe-theme.test.ts` confirmed `getMarkdownTheme()` + a Pi component render works outside interactive mode — validating the riskiest assumption cheaply, then deleted.
+3. **The operator's planning interjections were strategic, not mechanical.**
+   Rather than picking an `ask_user` option, the operator asked "what update frequency are we anticipating?"
+   and flagged a dependency-inversion risk on tool definitions.
+   Both redirects improved the design: the frequency analysis justified rebuild-on-change, and the inversion concern led to the dependency-safe `getToolDefinition` read accessor (discovered on the SDK, not invented).
+4. **Incremental verification throughout.**
+   Targeted `vitest` per Red→Green step, `pnpm run check` immediately after each shared-interface change, then full suite + root lint + `fallow dead-code` before each commit — no end-of-session verification pile-up.
+5. **Pre-completion review caught a real gap and the fix's own bug was caught by the loop.**
+   The reviewer flagged the missing #423 spy pin; while adding it, an over-assertion (`getToolDefinition` called on a no-toolCall fixture) failed the test run and was removed before committing.
+
+#### What caused friction (agent side)
+
+1. `missing-context` (self-identified) — the `initTheme()` requirement for Pi's interactive components.
+   The de-risking probe exercised only `AssistantMessageComponent`, which happens *not* to read the global theme, so the probe passed and gave false confidence.
+   The real tests then threw `"Theme not initialized"` from `UserMessageComponent`/`ToolExecutionComponent`.
+   Impact: one extra Red cycle (4 failing tests) → added `beforeAll(() => initTheme(undefined, false))`; no production rework.
+2. `other` (self-identified) — a wrong second assertion in the post-review #423 pin (`expect(record.getToolDefinition).toHaveBeenCalled()` on a fixture whose assistant message had no `toolCall`, so the lookup never fires).
+   Impact: one failed test run, immediately diagnosed and the bad assertion removed; ~1 iteration.
+
+#### What caused friction (user side)
+
+- None.
+  The operator's interventions were timely and strategic (see What went well #3); no context was withheld and no correction was reactive.
+
+### Diagnostic details
+
+- **Feedback-loop gap analysis** — no gap.
+  Verification ran incrementally: per-step targeted `vitest`, `pnpm run check` after each interface change, full suite + lint + `fallow` before commits.
+  Both friction points were caught by running tests *before* committing, not after.
+- **Escalation-delay tracking** — no rabbit holes; each friction point resolved in a single iteration (well under the 5-tool-call threshold).
+- **Probe-coverage note** — the `initTheme()` miss is a probe *coverage* gap, not a tool-availability gap: a one-variant probe (`AssistantMessageComponent`) did not validate the environment dependency of the broader component set actually used.
+- **Model-performance / unused-tool** — nothing notable.
+  The only subagent dispatch (`pre-completion-reviewer`) is purpose-built for judgment-heavy review; SDK inspection used direct `grep`/`bash` over `.d.ts` files, which was appropriate.
+
+### Changes made
+
+1. `.pi/skills/package-pi-subagents/SKILL.md` — added a `## Testing` note: tests mounting Pi's per-entry interactive components must call `initTheme(undefined, false)` in `beforeAll`, with the component-specific / false-confidence caveat.
+2. `.pi/skills/package-pi-subagents/SKILL.md` — corrected the stale UI domain module count (10 → 13) and extended its responsibility blurb to include session navigation.
+3. `.pi/skills/testing/SKILL.md` — extended the existing "Exploration before planning" disposable-probe bullet to require exercising the full input variety (variant-specific environment dependencies defeat a one-representative probe).
+   Placement confirmed with the operator: kept in the `testing` skill (loaded by both `/plan-issue` and `/tdd-plan`) next to the sibling rule, rather than duplicated into the plan prompt.

package/docs/retro/0463-file-snapshot-source-evicted-agents.md

@@ -0,0 +1,49 @@
+---
+issue: 463
+issue_title: "pi-subagents: add file-snapshot source to /subagent-sessions for evicted agents"
+---
+
+# Retro: #463 — pi-subagents: add file-snapshot source to /subagent-sessions for evicted agents
+
+## Stage: Planning (2026-06-23T00:00:00Z)
+
+### Session summary
+
+Produced a 4-step plan for the Phase 19 Step 4b file-snapshot source: implement `fileSnapshotSource(outputFile, readFile)` in the pure `session-navigation.ts`, broaden the `/subagent-sessions` candidate set to evicted agents, and dual-source the handler by `NavigationEntry.kind`.
+The central design fork — how evicted agents enter the picker — was resolved with the operator via `ask_user`.
+
+### Observations
+
+- **Eviction is memory management.**
+  The cleanup sweep's `disposeSession()` frees the in-memory message history; the transcript survives only on disk.
+  So rendering an evicted agent *always* reads the file (`fileSnapshotSource`) regardless of candidate-set strategy — the strategy only affects the picker *label*.
+- **Persisted child sessions carry no `type`/`description`.**
+  The JSONL has only the conversation plus a header (`id`, `timestamp`, `cwd`, `parentSession`).
+  A directory scan (the issue's literal wording) would therefore produce degraded labels and parse every file per open.
+- **Decision: manager-retained descriptors over directory scan.**
+  The manager stashes a tiny no-messages `EvictedSubagent` descriptor in `cleanup()` before `removeRecord`, cleared in `clearCompleted()`/`dispose()`.
+  Rich labels identical to live entries, bounded memory, no per-open parse.
+  Coverage is limited to in-session evictions — which are the sweep's only targets, since a fresh manager per session never reloads prior-process subagents.
+  Operator confirmed; an `(evicted)` snapshot marker was also chosen for the label.
+- **`NavigationEntry` becomes a discriminated union** (`live` | `evicted`); this breaks the handler, the `index.ts` call site, and both UI test files, so step 3 folds all of them into one commit.
+- **SDK-runtime call kept direct.** `fileSnapshotSource` calls `parseSessionEntries` / `buildSessionContext` directly rather than injecting them — the injected `readFile` already provides the unit-test seam, and there is no `no-restricted-imports` rule.
+- **Transient dead-code risk noted:** `fileSnapshotSource` and `listEvicted()` have no caller until step 3; flagged not to ship before step 3 lands (CI/`fallow` gate the pushed tip).
+- Release: independent (Phase 19 Step 4b roadmap tag).
+
+## Stage: Implementation — TDD (2026-06-23T13:00:00Z)
+
+### Session summary
+
+Executed all 4 plan steps in order: (1) `fileSnapshotSource` in the pure `session-navigation.ts`, (2) manager-retained `EvictedSubagent` descriptors (`cleanup` capture, `listEvicted`, `clearCompleted`/`dispose` clear), (3) the breaking `NavigationEntry` discriminated union + handler dual-source + `index.ts` wiring + all test updates in one commit, (4) architecture/ADR doc updates.
+Test count went from 1088 to 1099 (+11); full suite, `check`, root `lint`, and `fallow dead-code` all green.
+
+### Observations
+
+- **No deviations from the plan.**
+  All steps landed as written; Module-Level Changes matched the touched files exactly.
+- **Exploratory probe paid off.**
+  A disposable script confirmed `buildSessionContext` auto-detects the leaf with no `leafId`, the `type !== "session"` filter drops the header, and empty entries yield `[]` — validating the `fileSnapshotSource` shape before writing the test.
+- **Two ESLint auto-fixes during commit hooks:** a stray `!` non-null assertion in the manager test (step 2) and four `entry?.kind` optional chains on a non-nullish destructured `entry` (`@typescript-eslint/no-unnecessary-condition`, step 3).
+  Both fixed and re-committed; `check` + tests confirmed green after.
+- **Transient dead code** between steps 1–2 and 3 (predicted in the plan) cleared at the step-3 tip; final `fallow dead-code` is clean.
+- **Pre-completion reviewer: PASS** — deterministic checks, code design, test artifacts, Mermaid render, and all three cross-step invariants (no inbound core call, read-only overlay, renderer parity) verified; no follow-ups deferred.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "17.4.0",
+  "version": "17.5.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -11,6 +11,7 @@
  *   /agents                 — Interactive agent management menu
  */
 
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
   createAgentSession,
@@ -201,7 +202,14 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("subagent-sessions", {
     description: "View a subagent's session transcript (read-only)",
     handler: async (_args, ctx) => {
-      await sessionNavigator.handle({ ui: ctx.ui, agents: manager.listAgents(), registry, cwd: ctx.cwd });
+      await sessionNavigator.handle({
+        ui: ctx.ui,
+        agents: manager.listAgents(),
+        evicted: manager.listEvicted(),
+        registry,
+        cwd: ctx.cwd,
+        readFile: (path) => readFileSync(path, "utf8"),
+      });
     },
   });
 }

package/src/lifecycle/subagent-manager.ts

@@ -14,12 +14,31 @@ import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { Subagent, type SubagentLifecycleObserver } from "#src/lifecycle/subagent";
 import type { SubagentSession } from "#src/lifecycle/subagent-session";
-import { SubagentState } from "#src/lifecycle/subagent-state";
+import { SubagentState, type SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
+/**
+ * A lightweight snapshot of a subagent evicted by the 10-minute cleanup sweep.
+ *
+ * The sweep frees the heavy in-memory session (its message history included);
+ * this descriptor retains only the fields the session navigator needs to label
+ * the agent in the picker, plus the persisted `outputFile` to source its
+ * transcript from disk. Carries no messages, so memory stays bounded.
+ */
+export interface EvictedSubagent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+  readonly outputFile: string;
+}
+
 /** Observer interface for agent lifecycle notifications. */
 export interface SubagentManagerObserver {
   onSubagentStarted(record: Subagent): void;
@@ -65,6 +84,8 @@ export interface AgentSpawnConfig {
 
 export class SubagentManager {
   private agents = new Map<string, Subagent>();
+  /** Descriptors of agents removed by the cleanup sweep, keyed by id — navigable from disk. */
+  private readonly evicted = new Map<string, EvictedSubagent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: SubagentManagerObserver;
   private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
@@ -220,6 +241,11 @@ export class SubagentManager {
     );
   }
 
+  /** Descriptors of agents evicted by the cleanup sweep, most recent first. */
+  listEvicted(): EvictedSubagent[] {
+    return [...this.evicted.values()].sort((a, b) => b.startedAt - a.startedAt);
+  }
+
   abort(id: string): boolean {
     const record = this.agents.get(id);
     if (!record) return false;
@@ -245,6 +271,9 @@ export class SubagentManager {
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
       if ((record.completedAt ?? 0) >= cutoff) continue;
+      // Retain a navigable descriptor before freeing the heavy session. Only an
+      // agent with a persisted file can be sourced from disk after eviction.
+      if (record.outputFile) this.evicted.set(id, toEvictedSubagent(record, record.outputFile));
       this.removeRecord(id, record);
     }
   }
@@ -258,6 +287,8 @@ export class SubagentManager {
       if (record.status === "running" || record.status === "queued") continue;
       this.removeRecord(id, record);
     }
+    // Evicted descriptors belong to the session that swept them — a new session starts empty.
+    this.evicted.clear();
   }
 
   /** Whether any agents are still running or queued. */
@@ -314,5 +345,20 @@ export class SubagentManager {
       record.disposeSession();
     }
     this.agents.clear();
+    this.evicted.clear();
   }
 }
+
+/** Capture an evicted agent's navigable fields from its record. */
+function toEvictedSubagent(record: Subagent, outputFile: string): EvictedSubagent {
+  return {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    status: record.status,
+    startedAt: record.startedAt,
+    completedAt: record.completedAt,
+    toolUses: record.toolUses,
+    outputFile,
+  };
+}

package/src/ui/session-navigation.ts

@@ -12,8 +12,9 @@
  * components require a `TUI`, `cwd`, and markdown theme.
  */
 
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { buildSessionContext, parseSessionEntries, type SessionEntry, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EvictedSubagent } from "#src/lifecycle/subagent-manager";
 import type { SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { AgentSessionEvent, SessionMessage, SubagentType } from "#src/types";
 import { formatDuration, getDisplayName } from "#src/ui/display";
@@ -37,10 +38,24 @@ export interface NavigableSubagent {
   getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
-/** A navigable entry: a record plus the label shown in the picker. */
-export interface NavigationEntry {
-  readonly record: NavigableSubagent;
-  readonly label: string;
+/**
+ * A navigable entry plus the label shown in the picker.
+ *
+ * A `live` entry sources its transcript from the in-memory record; an `evicted`
+ * entry sources it from the persisted session file (the record is gone).
+ */
+export type NavigationEntry =
+  | { readonly kind: "live"; readonly label: string; readonly record: NavigableSubagent }
+  | { readonly kind: "evicted"; readonly label: string; readonly outputFile: string };
+
+/** The fields `buildLabel` reads — shared by a live record and an evicted descriptor. */
+interface LabelFields {
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
 }
 
 /** Running-agent streaming state, surfaced by a live source. */
@@ -61,14 +76,52 @@ export interface TranscriptSource {
   getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
-/** Filter the agents to those with a viewable session and label each for the picker. */
+/**
+ * Label every navigable subagent for the picker: live records with a viewable
+ * session, then agents evicted by the cleanup sweep (deduped against live ids).
+ */
 export function listNavigableAgents(
   agents: readonly NavigableSubagent[],
+  evicted: readonly EvictedSubagent[],
   registry: AgentConfigLookup,
 ): NavigationEntry[] {
-  return agents
+  const live = agents
     .filter((record) => record.isSessionReady())
-    .map((record) => ({ record, label: buildLabel(record, registry) }));
+    .map((record): NavigationEntry => ({ kind: "live", record, label: buildLabel(record, registry) }));
+  const liveIds = new Set(agents.map((record) => record.id));
+  const evictedEntries = evicted
+    .filter((descriptor) => !liveIds.has(descriptor.id))
+    .map((descriptor): NavigationEntry => ({
+      kind: "evicted",
+      outputFile: descriptor.outputFile,
+      label: buildLabel(descriptor, registry, true),
+    }));
+  return [...live, ...evictedEntries];
+}
+
+/**
+ * Source a transcript from a persisted child-session JSONL snapshot.
+ *
+ * For an agent evicted from the manager's map by the 10-minute cleanup sweep:
+ * the in-memory record (and its message history) is gone, but the session file
+ * survives on disk. Reads the file, drops the `SessionHeader`, and resolves the
+ * message list via Pi's own parser. A static snapshot — no subscription, no
+ * streaming, no live tool registry. `readFile` is injected so this module makes
+ * no `fs` calls.
+ */
+export function fileSnapshotSource(
+  outputFile: string,
+  readFile: (path: string) => string,
+): TranscriptSource {
+  const entries = parseSessionEntries(readFile(outputFile));
+  const sessionEntries = entries.filter((entry): entry is SessionEntry => entry.type !== "session");
+  const { messages } = buildSessionContext(sessionEntries);
+  return {
+    getMessages: () => messages,
+    subscribe: () => undefined,
+    streaming: () => undefined,
+    getToolDefinition: () => undefined,
+  };
 }
 
 /** Source a transcript live from an in-memory record (this slice's only source). */
@@ -84,8 +137,9 @@ export function liveSource(record: NavigableSubagent): TranscriptSource {
   };
 }
 
-function buildLabel(record: NavigableSubagent, registry: AgentConfigLookup): string {
-  const name = getDisplayName(record.type, registry);
-  const duration = formatDuration(record.startedAt, record.completedAt);
-  return `${name} (${record.description}) · ${record.toolUses} tools · ${record.status} · ${duration}`;
+function buildLabel(fields: LabelFields, registry: AgentConfigLookup, evicted = false): string {
+  const name = getDisplayName(fields.type, registry);
+  const duration = formatDuration(fields.startedAt, fields.completedAt);
+  const marker = evicted ? " · evicted (snapshot)" : "";
+  return `${name} (${fields.description}) · ${fields.toolUses} tools · ${fields.status} · ${duration}${marker}`;
 }

package/src/ui/session-navigator.ts

@@ -38,9 +38,10 @@ import {
   visibleWidth,
 } from "@earendil-works/pi-tui";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EvictedSubagent } from "#src/lifecycle/subagent-manager";
 import type { SessionMessage } from "#src/types";
 import { describeActivity, type Theme } from "#src/ui/display";
-import { listNavigableAgents, liveSource, type NavigableSubagent, type TranscriptSource } from "#src/ui/session-navigation";
+import { fileSnapshotSource, listNavigableAgents, liveSource, type NavigableSubagent, type TranscriptSource } from "#src/ui/session-navigation";
 
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -68,9 +69,13 @@ export interface SessionNavigatorUI {
 export interface SessionNavigatorParams {
   ui: SessionNavigatorUI;
   agents: readonly NavigableSubagent[];
+  /** Descriptors of agents evicted by the cleanup sweep, sourced from disk when picked. */
+  evicted: readonly EvictedSubagent[];
   registry: AgentConfigLookup;
   /** Working directory for tool-call rendering (relative path display). */
   cwd: string;
+  /** Reads a persisted session file for the file-snapshot source. */
+  readFile: (path: string) => string;
 }
 
 /** Options for the read-only transcript overlay. */
@@ -91,8 +96,8 @@ export interface TranscriptOverlayOptions {
  * manager, so it stays a reactive consumer with no inbound call into the core.
  */
 export class SessionNavigatorHandler {
-  async handle({ ui, agents, registry, cwd }: SessionNavigatorParams): Promise<void> {
-    const entries = listNavigableAgents(agents, registry);
+  async handle({ ui, agents, evicted, registry, cwd, readFile }: SessionNavigatorParams): Promise<void> {
+    const entries = listNavigableAgents(agents, evicted, registry);
     if (entries.length === 0) {
       ui.notify("No subagent sessions to view.", "info");
       return;
@@ -105,7 +110,13 @@ export class SessionNavigatorHandler {
     const entry = entries.find((candidate) => candidate.label === choice);
     if (!entry) return;
 
-    const source = liveSource(entry.record);
+    let source: TranscriptSource;
+    try {
+      source = entry.kind === "live" ? liveSource(entry.record) : fileSnapshotSource(entry.outputFile, readFile);
+    } catch {
+      ui.notify("Could not read the session transcript file.", "error");
+      return;
+    }
     const markdownTheme = getMarkdownTheme();
     await ui.custom<undefined>(
       (tui, theme, _keybindings, done) =>