@gotgenes/pi-subagents 17.3.0 → 17.5.0

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/0445-native-session-navigation.md

@@ -55,3 +55,68 @@ Pre-completion reviewer returned PASS.
 - **Reviewer verdict: PASS.**
   Two WARN notes, both intentional and plan-sanctioned: Step 4 heading unchecked (correct for a partial slice) and the deferred `SKILL.md` count.
 - **Open at ship time:** confirm command name `subagent-sessions`; file the two follow-up issues (component renderer; evicted-agent file source).
+
+## Stage: User Note (2026-06-22T18:26:37Z)
+
+When new issues are identified during planning, file them before leaving the planning stage rather than deferring to ship time.
+Two motivations: the planning session uses a very capable model, and it already has all the context needed to write the issues well.
+Applied here: the two follow-up issues (#462 renderer upgrade, #463 file-snapshot source) were identified during planning but filed only at ship time — they should have been created at the end of the planning commit instead.
+
+## Stage: Final Retrospective (2026-06-22T18:28:31Z)
+
+### Session summary
+
+One continuous session carried #445 from planning through TDD, ship, and a mid-session retro note.
+It delivered the sliced Phase 19 Step 4 — the `/subagent-sessions` command, the live `TranscriptSource`, and the typed `agentMessages` accessor — across three `feat:` commits plus docs, released as `pi-subagents` v17.3.0, with two follow-ups (#462, #463) filed at ship.
+Execution was notably clean: the plan anticipated both hard risks, and every implementation slip was absorbed by the feedback loops within its active TDD cycle.
+
+### Observations
+
+#### What went well
+
+1. **The plan pre-empted the two hardest risks.**
+   `AgentMessage`→`Message` non-assignability and the unreachable file-snapshot branch were both called out in planning and both materialized exactly as predicted; the planned mitigations (the `toMessages` adapter; shipping the live source only) applied with zero rework.
+2. **The `TranscriptSource` seam earned its keep.**
+   The pure `session-navigation.ts` was unit-tested with light stubs (no full `Subagent`/`TUI`/`AgentSession`), and the seam cleanly hosts both deferred follow-ups — testability justified it independent of the follow-ups.
+3. **Tight, incremental feedback loops.**
+   Per-cycle affected-file test runs, `pnpm run check` after every type-touching step, and full suite + lint + `fallow dead-code` after the last step caught every slip within seconds.
+4. **Two `ask_user` rounds during planning converted a large issue into a releasable slice** (the operator's Kent Beck nudge) — the central design win of the issue.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — wrote test assertions before checking helper behavior: `formatMs` yields `3.0s` not `3s`, `getDisplayName` falls back to `Agent`, `TOOL_DISPLAY` keys are lowercase, and `AgentTypeRegistry` takes `() => new Map()` not `() => []`.
+   Impact: ~4 assertion fixes within one Green iteration; no rework beyond the cycle.
+2. `missing-context` — `SessionContext` name collision: imported the SDK type into `types.ts` without noticing a local `SessionContext` interface already existed.
+   Impact: one aliasing edit (`SdkSessionContext`), caught immediately by biome `noRedeclare`.
+3. `other` (mechanical) — a stray `}` when wrapping a new `describe` block (AGENTS.md already warns about brace-pair edits), and `SessionMessage` imported from the wrong module in the navigator test.
+   Impact: one fix each, caught by autoformat and `tsc`.
+4. `instruction-violation` (self-identified, hook-caught) — two lint nits the `testing` skill already documents: an unnecessary optional chain and an unnecessary `!` on `mock.calls[0][0]`.
+   Impact: two inline fixes; no rework.
+
+None of the agent-side slips caused rework beyond their active TDD cycle — the autoformat/biome/`tsc`/vitest/pre-commit loops absorbed all of them.
+
+#### What caused friction (user side)
+
+1. The dominant cross-session finding (recorded separately as the User Note stage): follow-up issues identified during planning (#462, #463) were filed only at ship time.
+   The workflow itself encodes the deferral — the plan said "file at ship time" and `/ship-issue` step 4c creates them.
+   The operator wants them filed during planning, while the capable planning model still holds full context.
+   Opportunity: move follow-up creation into `/plan-issue`.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer` on `anthropic/claude-sonnet-4-6`, a judgment-heavy review task; appropriate match.
+  Planning ran on a capable model, which the operator explicitly values.
+  No mismatch.
+- **Escalation-delay tracking** — no rabbit-holes; the longest same-area sequence was 4 assertion fixes inside one Green iteration (under the 5-call flag).
+- **Unused-tool detection** — the `missing-context` slips were caught trivially by running tests; reading `display.ts` helpers first would have pre-empted them, but the cost was negligible and no Explore/`colgrep` dispatch was warranted.
+- **Feedback-loop gap analysis** — verification ran incrementally and completely (per-cycle tests, `check` after type changes, full gate after the last step); no gap.
+  This is a win, not a gap.
+
+### Changes made
+
+Moved follow-up issue creation from ship time to planning time, with the backstop relocated to pre-completion (operator-directed):
+
+1. `.pi/prompts/plan-issue.md` — added a `## File follow-up issues` section before `## Commit`: file plan-named follow-ups during planning with `gh issue create` and record each number in the plan; nothing speculative.
+2. `.pi/agents/pre-completion-reviewer.md` — added checklist section `2i. Planned follow-up issues` and its report stanza: WARN when the plan names a follow-up but records no issue number; also added the case to the severity model's WARN list.
+3. `.pi/prompts/ship-issue.md` — removed step `4c. Create planned follow-up issues` (follow-ups are now filed during planning; the close comment in step 5 references the recorded numbers).
+4. `AGENTS.md` — extended the pre-completion-reviewer coverage enumeration to include planned follow-up filing.

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

@@ -0,0 +1,105 @@
+---
+issue: 462
+issue_title: "pi-subagents: upgrade /subagent-sessions renderer to Pi per-entry TUI components"
+---
+
+# Retro: #462 — pi-subagents: upgrade /subagent-sessions renderer to Pi per-entry TUI components
+
+## Stage: Planning (2026-06-22T00:00:00Z)
+
+### Session summary
+
+Planned Phase 19 Step 4a: swap the `/subagent-sessions` renderer from `serializeConversation` plain text to Pi's per-entry TUI components behind the existing `TranscriptSource` seam.
+Verified the SDK surface (per-entry components, `parseSkillBlock`, `getMarkdownTheme`, `ToolDefinition`, `AgentSession.getToolDefinition`) and mirrored Pi's own `renderSessionContext`/`rebuildChatFromMessages` mapping.
+Wrote a four-step TDD plan at `packages/pi-subagents/docs/plans/0462-navigation-renderer-tui-components.md` and committed it.
+
+### Observations
+
+- Three design decisions were surfaced via `ask_user` and locked by the operator:
+  1. **Rebuild-on-change** (mirror Pi's `rebuildChatFromMessages`) over incremental `updateContent`/`updateResult` — the seam exposes only a full `getMessages()` snapshot plus a coarse `onChange`, so incremental would still diff snapshots while replicating Pi's `pendingTools` streaming state machine for marginal benefit.
+  2. **Keep the lightweight `◍ describeActivity` text indicator** — this absorbs the high-frequency streaming text, so the persisted component tree only changes at message granularity, which is what keeps rebuild-on-change cheap.
+  3. **Wire real tool definitions** — the operator flagged a dependency-inversion risk ("can't `SubagentManager` track this?").
+     Resolved dependency-safely: the SDK `AgentSession` already exposes `getToolDefinition(name)`, so a new read accessor on `SubagentSession`/`Subagent` (mirroring the existing `agentMessages` accessor) surfaces it through the record and onto the `TranscriptSource` seam — arrows stay inward, no `SubagentManager` bookkeeping.
+- Key structural move: the component renderer must leave the pure `session-navigation.ts` (per-entry components need `TUI`/`cwd`/`markdownTheme`) and live in the SDK/TUI `session-navigator.ts`.
+  The pure module sheds `renderTranscriptLines`/`serializeConversation` entirely, becoming selection + sourcing only.
+- The `renderTranscriptLines` removal, overlay rewrite, `session-navigation.ts` edits, `index.ts` `cwd` wiring, and test updates must land in **one commit** (TDD step 3) — removing the export breaks the overlay and its tests at the type level.
+- Non-breaking internal renderer swap; `Release: independent` per the roadmap.
+  Step 4a gates Step 5 ([#442]) for rendering parity but is not part of any release batch.
+- Follow-up [#463] (Step 4b, file-snapshot source) already exists and is open — referenced as a Non-Goal, nothing new to file.
+- Parity is defined as *using Pi's own components*, not byte-equality with the bespoke viewer; `custom`-role messages are skipped (the bespoke viewer never rendered them either), noted as an Open Question.
+
+## Stage: Implementation — TDD (2026-06-22T21:30:00Z)
+
+### Session summary
+
+Executed all four planned TDD steps: the `getToolDefinition` read accessor on `SubagentSession`/`Subagent`, the seam method on `TranscriptSource`/`NavigableSubagent`, the per-entry component renderer + overlay rewrite + `cwd` wiring, and the architecture doc flip (Step 4a `✅`).
+The renderer now mounts Pi's interactive components into a cached `Container` rebuilt on source change, mirroring Pi's `renderSessionContext`.
+Test count went from 1084 to 1088 (+4 net: +4 accessor/seam tests, +3 new navigator tests, −3 removed `renderTranscriptLines` tests), all green; one post-review `test:` commit pins invariant #423.
+
+### Observations
+
+- The production code (`session-navigation.ts`, `session-navigator.ts`, `index.ts`) type-checked clean on the first `tsc` run — the SDK message-union narrowing (`switch (message.role)`), component construction, and `updateResult(toolResultMessage)` all resolved without casts.
+  `SessionMessage` (= the SDK `AgentMessage` union) narrows by `role` even though `@earendil-works/pi-agent-core` is not a direct dependency.
+- Two deviations from the plan's Module-Level Changes, both intentional: (1) `src/types.ts` was *not* changed — `ToolDefinition` is imported directly from `@earendil-works/pi-coding-agent` in each consumer rather than re-exported through the barrel (avoids a speculative re-export `fallow` would flag); (2) `test/helpers/mock-session.ts` gained a `getToolDefinition` stub (needed for the step-1 accessor tests, not listed in the plan).
+- Pi's per-entry components read a *global* interactive theme initialized by `initTheme()`; Pi does this at startup, but tests had to call `initTheme(undefined, false)` in `beforeAll`.
+  An early probe with `AssistantMessageComponent` passed without it, but `UserMessageComponent`/`ToolExecutionComponent` throw `"Theme not initialized"` — so the global-theme dependency is component-specific and only surfaced once the broader role set was exercised.
+- `setComplete`'s `TruncationResult` param requires more fields than `BashExecutionMessage` carries, so the bash component is completed with `undefined` truncation info (command + output still render).
+  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.3.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 });
+      await sessionNavigator.handle({
+        ui: ctx.ui,
+        agents: manager.listAgents(),
+        evicted: manager.listEvicted(),
+        registry,
+        cwd: ctx.cwd,
+        readFile: (path) => readFileSync(path, "utf8"),
+      });
     },
   });
 }