@gotgenes/pi-subagents 17.2.0 → 17.4.0

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

@@ -0,0 +1,338 @@
+---
+issue: 462
+issue_title: "pi-subagents: upgrade /subagent-sessions renderer to Pi per-entry TUI components"
+---
+
+# Upgrade `/subagent-sessions` renderer to Pi per-entry TUI components
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 19 Step 4a ([#462]) carries `Release: independent` in the architecture roadmap.
+It swaps the renderer behind the existing `TranscriptSource` seam; it is not a member of Phase 19's only batch ("dissolve-agents", Steps 5–6, [#442]/[#441]).
+Step 4a gates Step 5 ([#442]) for rendering parity, but a gate is a sequencing dependency, not a release batch — this step ships on its own once it lands.
+
+## Problem Statement
+
+The #445 slice ([#445]) stood up native session navigation — list → pick → read-only scrollable transcript — behind a renderer-agnostic `TranscriptSource` seam, using Pi's `serializeConversation` plain text as the first renderer.
+That text dump is lower fidelity than the bespoke `ConversationViewer` it is slated to replace, which renders richer per-message formatting (tool call/result blocks, bash execution, markdown).
+ADR-0004 Decision B's full intent is native-fidelity rendering through Pi's **own** interactive components ([ADR-0004] Addendum, Finding 1): `AssistantMessageComponent`, `ToolExecutionComponent`, `UserMessageComponent`, `BashExecutionComponent`, `CompactionSummaryMessageComponent`, `BranchSummaryMessageComponent`, and the skill-block components.
+This follow-up swaps the renderer behind the same seam — selection and sourcing are untouched — so the native navigator reaches rendering parity with the bespoke viewer, which unblocks Step 5's deletion of that viewer without a fidelity regression.
+
+## Goals
+
+- Replace the `serializeConversation` text path with a per-entry Pi TUI component tree, mirroring Pi's own `renderSessionContext` message→component mapping.
+- Drive the component tree by **rebuild-on-change**: on each `TranscriptSource` change, clear and reconstruct the cached component `Container` from the current message snapshot (Pi's own `rebuildChatFromMessages` path); each paint reuses the cached tree, so markdown highlighting does not re-run per frame.
+- Render tool calls at full fidelity by passing each tool's real `ToolDefinition`, sourced through a new dependency-safe `getToolDefinition` read accessor on the record (mirroring the existing `agentMessages` accessor) and surfaced on the `TranscriptSource` seam.
+- Keep the existing lightweight `◍ describeActivity` streaming-indicator line for a running agent's live activity (the high-frequency streaming text it absorbs is why rebuild-on-change stays cheap).
+- Confirm rendering parity with the bespoke `ConversationViewer` so Step 5 ([#442]) can delete it with no fidelity regression.
+
+Non-breaking: this is an internal renderer swap behind the seam.
+No public export, command name, default, or observable behavior changes.
+The internal `renderTranscriptLines` export is removed, but its only consumers are within this package (the overlay and its tests).
+
+## Non-Goals
+
+- Do **not** implement the **file-snapshot** source branch (`parseSessionEntries` → `buildSessionContext`) or broaden the candidate set to evicted agents — that is Step 4b ([#463]), independent and unblocked by this step.
+- Do **not** add in-session steering or any interactive gesture — the overlay stays strictly read-only; steering remains in `steer_subagent` and the widget.
+- Do **not** touch `agent-menu.ts`, `conversation-viewer.ts`, or `message-formatters.ts` — they stay live until the terminal cut (Step 5, [#442]).
+- Do **not** change `listNavigableAgents` selection or the `liveSource` sourcing semantics — only the renderer changes, plus the additive `getToolDefinition` accessor.
+- Do **not** render `custom`-role messages through `CustomMessageComponent` — it requires the session's `extensionRunner.getMessageRenderer`, which the navigator does not hold (see Open Questions); custom messages are skipped, matching the bespoke viewer, which never rendered them either.
+
+## Background
+
+Relevant existing modules:
+
+- `src/ui/session-navigation.ts` (pure) — owns selection and sourcing: `listNavigableAgents`, `liveSource`, and the interfaces `NavigableSubagent`, `NavigationEntry`, `StreamingState`, `TranscriptSource`.
+  It currently also owns `renderTranscriptLines(source): string[]` (the `serializeConversation` text path) and its `toMessages` adapter — these are text rendering via a pure SDK utility.
+- `src/ui/session-navigator.ts` (SDK/TUI consumer) — owns `TranscriptOverlay` (a read-only scrollable `Component`) and `SessionNavigatorHandler`.
+  `TranscriptOverlay.buildContentLines` currently calls `renderTranscriptLines(this.source)`, then wraps each line with the injected `wrapText`.
+- `src/lifecycle/subagent-session.ts` — `SubagentSession` wraps `_session: AgentSession`.
+  It already exposes `get agentMessages(): readonly SessionMessage[]` returning `this._session.messages`.
+  The SDK `AgentSession` exposes `getToolDefinition(name: string): ToolDefinition | undefined` (a definition-first registry retained per session).
+- `src/lifecycle/subagent.ts` — `Subagent` delegates `get agentMessages()` to `this.subagentSession?.agentMessages ?? []`; this is the exact pattern the new `getToolDefinition` accessor follows.
+- `src/ui/display.ts` — `describeActivity(activeTools, responseText)`, `getDisplayName`, `formatDuration`.
+- `src/index.ts` — registers the `subagent-sessions` command; the handler already receives `ctx` (which carries `ctx.cwd: string` and `ctx.ui`).
+
+Pi SDK facts verified for this plan (against the bundled `@earendil-works/pi-coding-agent`):
+
+- The per-entry components are all re-exported from the public root barrel: `AssistantMessageComponent`, `UserMessageComponent`, `ToolExecutionComponent`, `BashExecutionComponent`, `CompactionSummaryMessageComponent`, `BranchSummaryMessageComponent`, `SkillInvocationMessageComponent`, `CustomMessageComponent`.
+  `parseSkillBlock`, `getMarkdownTheme`, and the `ToolDefinition` type are also public.
+- Component constructors are heterogeneous and stateful (`Container` subclasses):
+  - `AssistantMessageComponent(message?, hideThinkingBlock?, markdownTheme?, hiddenThinkingLabel?)`.
+  - `UserMessageComponent(text: string, markdownTheme?)`.
+  - `ToolExecutionComponent(toolName, toolCallId, args, options, toolDefinition, ui: TUI, cwd: string)`, with `updateResult(result)` called separately to attach the tool result.
+  - `BashExecutionComponent(command, ui: TUI, excludeFromContext?)`, with `appendOutput` / `setComplete`.
+  - `CompactionSummaryMessageComponent(message, markdownTheme?)` / `BranchSummaryMessageComponent(message, markdownTheme?)`.
+- Pi's own message→component mapping is `interactive-mode.ts`'s `renderSessionContext(sessionContext)` (and the `addMessageToChat` helper it calls); `rebuildChatFromMessages()` is `chatContainer.clear()` + `renderSessionContext(buildSessionContext())`.
+  This plan mirrors that mapping; the `toolResult` → pending-tool match (`renderedPendingTools.get(toolCallId).updateResult(message)`) is reproduced.
+- `Container` (from `@earendil-works/pi-tui`) exposes `addChild`, `clear`, and `render(width): string[]`, which stacks children vertically — so a `Container` of per-entry components renders to the `string[]` the existing scroll overlay already consumes.
+- No higher-level "message list" / "transcript" renderer is exported from the SDK — the mapping must be mirrored, not imported.
+
+AGENTS.md / package constraints:
+
+- pi-subagents is a minimal core; the navigator is an in-core reactive consumer with **no inbound call** into the core.
+  The new `getToolDefinition` accessor is a read-only getter (like `agentMessages`) — it adds no inbound call and preserves the Phase 18 spine invariants ([#422]–[#425]).
+  This is the dependency-safe answer to "wire real tool definitions": arrows still point inward (navigator → record getter → wrapped `AgentSession.getToolDefinition`); `SubagentManager` tracks nothing extra and no dependency is inverted.
+- Keep Pi SDK *coupling* out of pure helpers: per-entry components require a `TUI`, `cwd`, and `markdownTheme`, so the component-building renderer lives in the SDK/TUI module `session-navigator.ts`, not in the pure `session-navigation.ts`.
+  The `serializeConversation` text renderer leaves the pure module entirely.
+- Use narrow interface types (not the concrete `Subagent`) at the seam — unchanged from the slice.
+
+## Design Overview
+
+The `TranscriptSource` seam is the change point.
+Its sourcing surface (`getMessages` / `subscribe` / `streaming`) is unchanged except for one additive method (`getToolDefinition`); the **renderer** moves from the pure module into the SDK/TUI module and changes shape from text to a component tree.
+
+### Dependency-safe tool definitions
+
+The SDK `AgentSession` already retains a definition-first tool registry and exposes `getToolDefinition(name)`.
+A new read accessor surfaces it through the record, mirroring `agentMessages`:
+
+```typescript
+// SubagentSession
+getToolDefinition(name: string): ToolDefinition | undefined {
+  return this._session.getToolDefinition(name);
+}
+
+// Subagent
+getToolDefinition(name: string): ToolDefinition | undefined {
+  return this.subagentSession?.getToolDefinition(name);
+}
+```
+
+This is a pure outward read — no inbound call, no `SubagentManager` bookkeeping, no dependency inversion.
+
+### Seam: `TranscriptSource` gains `getToolDefinition`
+
+`TranscriptSource` (and the `NavigableSubagent` record interface it sources from) gain the lookup; `liveSource` delegates to the record:
+
+```typescript
+export interface TranscriptSource {
+  getMessages(): readonly SessionMessage[];
+  subscribe(onChange: () => void): (() => void) | undefined;
+  streaming(): StreamingState | undefined;
+  getToolDefinition(name: string): ToolDefinition | undefined; // new
+}
+```
+
+A future file-snapshot source (Step 4b) returns `undefined` here → generic fallback tool rendering, with no renderer change.
+Placing the lookup on the seam (not on the renderer's separate params) keeps the seam the single change point across both follow-ups.
+
+### Renderer: per-entry component tree (`session-navigator.ts`)
+
+A new function builds a `Container` of per-entry components from a message snapshot, mirroring `renderSessionContext`:
+
+```typescript
+function buildTranscriptComponents(
+  messages: readonly SessionMessage[],
+  opts: { tui: TUI; cwd: string; markdownTheme: MarkdownTheme; getToolDefinition: (name: string) => ToolDefinition | undefined },
+): Container {
+  const container = new Container();
+  const pendingTools = new Map<string, ToolExecutionComponent>();
+  for (const message of messages) {
+    switch (message.role) {
+      case "assistant": { /* AssistantMessageComponent + per-toolCall ToolExecutionComponent (track pending by id) */ }
+      case "toolResult": { /* pendingTools.get(toolCallId)?.updateResult(message) */ }
+      case "user": { /* parseSkillBlock → SkillInvocation(+UserMessage) | UserMessageComponent */ }
+      case "bashExecution": { /* BashExecutionComponent + appendOutput + setComplete */ }
+      case "compactionSummary": { /* CompactionSummaryMessageComponent */ }
+      case "branchSummary": { /* BranchSummaryMessageComponent */ }
+      // custom: skipped (no message renderer available — see Open Questions)
+    }
+  }
+  return container;
+}
+```
+
+`ToolExecutionComponent` is constructed with `opts.getToolDefinition(content.name)` for its definition, `opts.tui`, and `opts.cwd`, and `{ showImages: false }` (the read-only viewer does not render images).
+Spacers between entries follow Pi's own spacing in `addMessageToChat`.
+
+### Overlay: rebuild-on-change with a cached `Container`
+
+`TranscriptOverlay` caches the component tree and rebuilds it only when the source changes — never per frame:
+
+```typescript
+// constructor: build once, then subscribe
+this.content = this.rebuild();
+this.unsubscribe = source.subscribe(() => {
+  if (this.closed) return;
+  this.content = this.rebuild();      // rebuild on change only
+  this.tui.requestRender();
+});
+
+private rebuild(): Container {
+  return buildTranscriptComponents(this.source.getMessages(), {
+    tui: this.tui, cwd: this.cwd, markdownTheme: this.markdownTheme,
+    getToolDefinition: (name) => this.source.getToolDefinition(name),
+  });
+}
+
+private buildContentLines(innerW: number): string[] {
+  const lines = this.content.render(innerW);           // components own their own wrapping
+  const streaming = this.source.streaming();
+  if (streaming) lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
+  return lines.map((l) => truncateToWidth(l, innerW)); // defensive truncate; no re-wrap
+}
+```
+
+The per-frame `render(width)` chrome (header/footer/scroll math) is unchanged; only the content source changes from `renderTranscriptLines(source)` to the cached `Container`.
+Because the components already wrap to width, the overlay no longer re-wraps each line — the injected `wrapText` collaborator is removed from `TranscriptOverlayOptions` and the handler call site.
+
+### Handler / registration
+
+`SessionNavigatorParams` gains `cwd: string`; `index.ts` passes `ctx.cwd`:
+
+```typescript
+await sessionNavigator.handle({ ui: ctx.ui, agents: manager.listAgents(), registry, cwd: ctx.cwd });
+```
+
+The handler obtains `markdownTheme` via `getMarkdownTheme()` (current theme; Pi has initialized it at startup) and threads `cwd` + `markdownTheme` into the `TranscriptOverlay` it mounts through `ui.custom`.
+`manager.listAgents()` is still called in the registration, never inside the navigator — the navigator stays a reactive consumer with no inbound core call.
+
+### Consumer call-site sketch (Tell-Don't-Ask / LoD check)
+
+The renderer talks only to `TranscriptSource`: it reads `source.getMessages()` and `source.getToolDefinition(name)`, never reaching through the record to a stranger.
+`liveSource.getToolDefinition` delegates to `record.getToolDefinition` (the record's own getter), which delegates to the wrapped `AgentSession` internally — a one-hop delegation, not a `record.session.x.y` chain.
+No output arguments: the renderer constructs and returns a `Container`; nothing writes back into the record or the source.
+
+### Design-review findings
+
+| Smell                          | Location                       | Evidence                                                                                             | Result                                                            |
+| ------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Dependency width               | `TranscriptSource` (4 methods) | renderer reads `getMessages`/`streaming`/`getToolDefinition`; overlay reads `subscribe`              | Acceptable — cohesive sourcing seam; every method is a real read  |
+| LoD violation                  | `liveSource.getToolDefinition` | one-hop delegation `record.getToolDefinition` → `AgentSession.getToolDefinition`                     | None — delegation through the record's own getter, no chain       |
+| Output argument                | `buildTranscriptComponents`    | returns a `Container`; `updateResult` mutates the tool component it owns, not a received bag         | None                                                              |
+| Concrete-class leak            | seam interfaces                | renderer depends on `TranscriptSource`, not the concrete `Subagent`                                  | None — narrow interface                                           |
+| Pi SDK coupling in pure module | `session-navigation.ts`        | component rendering moves out to `session-navigator.ts`; pure module keeps selection + sourcing only | Improved — pure module sheds the `serializeConversation` renderer |
+
+The new collaborator (`buildTranscriptComponents`) gives behavior to data — it maps message data to stateful components and returns a renderable tree — not procedure-splitting.
+
+### Edge cases
+
+- Empty history (`getMessages()` is `[]`) → empty `Container`; the overlay renders an empty viewport (no crash); the existing "no sessions" notify path is unchanged at the selection layer.
+- Running agent → component tree for finalized messages plus the appended `◍ describeActivity` indicator; a `subscribeToUpdates` event rebuilds the tree and re-renders.
+- A partially-streamed assistant message present in `getMessages()` → rendered by `AssistantMessageComponent`; the indicator also shows activity (parity with the bespoke viewer, which showed both).
+- `toolResult` with no matching pending tool (out-of-order / truncated history) → no-op (matches Pi's `renderedPendingTools.get` miss).
+- `getToolDefinition` returns `undefined` (definition not registered, or a future file source) → `ToolExecutionComponent` generic fallback rendering.
+- Very narrow terminal width → `render` returns `[]` below the minimum width (unchanged chrome guard).
+
+## Module-Level Changes
+
+- **Changed** `src/types.ts` — re-export or reference the SDK `ToolDefinition` type for the seam interfaces (import from `@earendil-works/pi-coding-agent`); confirm a consumer imports it from the barrel if added there (no speculative re-export).
+- **Changed** `src/lifecycle/subagent-session.ts` — add `getToolDefinition(name): ToolDefinition | undefined` delegating to `this._session.getToolDefinition(name)`.
+- **Changed** `src/lifecycle/subagent.ts` — add `getToolDefinition(name): ToolDefinition | undefined` delegating to `this.subagentSession?.getToolDefinition(name)`.
+- **Changed** `src/ui/session-navigation.ts` — add `getToolDefinition` to `NavigableSubagent` and `TranscriptSource`; `liveSource` delegates it.
+  **Remove** `renderTranscriptLines`, its `toMessages` adapter, and the `serializeConversation` + `describeActivity` imports (rendering moves to `session-navigator.ts`).
+- **Changed** `src/ui/session-navigator.ts` — add `buildTranscriptComponents`; rewrite `TranscriptOverlay` to cache + rebuild the `Container` (drop `wrapText` from `TranscriptOverlayOptions`); add `describeActivity`, `getMarkdownTheme`, `Container`, and the per-entry component imports; add `cwd` (+ `markdownTheme` wiring) to `SessionNavigatorParams`/the overlay.
+- **Changed** `src/index.ts` — pass `cwd: ctx.cwd` into `sessionNavigator.handle(...)`.
+- **Changed** `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/subagent.test.ts` — add `getToolDefinition` accessor tests.
+- **Changed** `test/ui/session-navigation.test.ts` — remove the `renderTranscriptLines` describe block; add `liveSource.getToolDefinition` delegation; add `getToolDefinition` to the `makeNavigable` factory.
+- **Changed** `test/ui/session-navigator.test.ts` — assert component-rendered content (text still appears via markdown), add a tool-call render test (stub `getToolDefinition`), add `getToolDefinition` to `fakeSource`/`makeNavigable`, pass `cwd` in handler tests, drop `wrapText`.
+
+Removed-symbol grep: `renderTranscriptLines` is the sole removed export.
+Its consumers are `src/ui/session-navigator.ts` (rewritten this issue) and `test/ui/session-navigation.test.ts` (block removed); confirmed no other `src/`/`test/` references and no `.pi/skills/package-pi-subagents/SKILL.md` mention.
+
+Doc / skill updates:
+
+- `docs/architecture/architecture.md` — flip Step 4a's status to landed (mirroring the Step 4 "Landed" note style) and update the Phase 19 Mermaid node label `S4a` from pending to done; record that the native navigator now renders at parity, unblocking Step 5.
+  Defer the status-line/Mermaid flip to ship time if preferred (matches the [#447] precedent), but the rescoping note belongs in this issue's doc step.
+- `.pi/skills/package-pi-subagents/SKILL.md` — the UI domain count is a coarse summary (no file added or removed here); leave unless the operator asks otherwise.
+
+## Test Impact Analysis
+
+1. **New tests enabled.**
+   The `getToolDefinition` accessor gets direct unit tests on `SubagentSession` and `Subagent` (mirroring `agentMessages`).
+   The component renderer is exercised through `TranscriptOverlay` against a `fakeSource` — asserting that message text renders (via the components) and that a tool call renders with its definition.
+2. **Existing tests that become redundant.**
+   The `renderTranscriptLines` describe block in `session-navigation.test.ts` is removed — the function it tests is gone (rendering moved and changed shape).
+   No other tests become redundant.
+3. **Existing tests that must stay as-is.**
+   `listNavigableAgents` and `liveSource` selection/sourcing tests stay (selection and sourcing semantics are unchanged; `liveSource` only gains the `getToolDefinition` delegation).
+   All bespoke-viewer and menu tests (`conversation-viewer.test.ts`, `message-formatters.test.ts`, `agent-menu.test.ts`) stay untouched — Step 5 deletes those.
+
+## Invariants at risk
+
+This issue swaps a renderer behind the seam, adds one read accessor, and threads `cwd`; it does not touch the Phase 18 spine.
+The relevant `Outcome:` invariants and their pins:
+
+- **[#422] — runtime holds zero UI state.**
+  The overlay holds its own cached `Container` + scroll state; nothing is pushed onto the runtime.
+  Pinned by the runtime/service-spine tests; unchanged.
+- **[#423] — UI is a reactive consumer with no inbound calls from core spawn tools.**
+  The navigator reads via the injected `manager.listAgents()` snapshot and record getters only; the new `getToolDefinition` accessor is a read-only getter.
+  Pinned by the navigator-reads-only test from the slice (extend it to assert the handler reads `getToolDefinition` only through the source).
+- **[#424] — the `subagent` tool depends only on manager/runtime/settings/registry.**
+  No tool change.
+- **[#425] — declared event channels equal emitted channels, no vacant hook.**
+  The navigator subscribes to existing record updates; it declares/emits no new channel.
+  Pinned by the events-contract suite; unchanged.
+
+A later phase step (Step 4b file source, Step 5 deletion) must not regress these with a green suite — the navigator-reads-only test pins #423 for the seam.
+
+## TDD Order
+
+1. **Red→Green: `getToolDefinition` read accessor on the record.**
+   Test surface: `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/subagent.test.ts`.
+   Tests: `SubagentSession.getToolDefinition` delegates to the wrapped session; `Subagent.getToolDefinition` delegates to the session and returns `undefined` when no session.
+   Implementation: reference the SDK `ToolDefinition` type (via `src/types.ts` or a direct import); add the two getters.
+   Run `pnpm run check` (verifies `AgentSession.getToolDefinition` resolves).
+   Commit: `feat: add getToolDefinition accessor on subagent record (#462)`.
+2. **Red→Green: surface `getToolDefinition` on the seam (additive).**
+   Test surface: `test/ui/session-navigation.test.ts`.
+   Tests: `liveSource.getToolDefinition` delegates to `record.getToolDefinition`; add `getToolDefinition` to the `makeNavigable` factory.
+   Implementation: add `getToolDefinition` to `NavigableSubagent` and `TranscriptSource`; `liveSource` delegates.
+   This step is pure addition — `renderTranscriptLines` still exists and compiles.
+   Commit: `feat: expose getToolDefinition on the transcript source seam (#462)`.
+3. **Red→Green: component-tree renderer + overlay rewrite + `cwd` wiring.**
+   Test surface: `test/ui/session-navigator.test.ts` (+ remove the `renderTranscriptLines` block from `test/ui/session-navigation.test.ts`).
+   Tests:
+   - `TranscriptOverlay.render` paints component-rendered content for user/assistant messages (text appears); a tool call renders via `ToolExecutionComponent` using a stubbed `getToolDefinition`; the `◍` streaming indicator still appends while running; rebuild-on-change re-renders after a `subscribe` callback; `esc`/`q` calls `done`; `dispose` unsubscribes.
+   - `SessionNavigatorHandler.handle`: empty entries → `notify`, no `custom`; cancel → no `custom`; valid pick → `custom` opened with an overlay sourced from the picked record and the passed `cwd`.
+   Implementation (one commit — removing `renderTranscriptLines` breaks the overlay and its tests at the type level, so the rewrite, the export removal, the test updates, and the `index.ts` call-site update land together):
+   - Add `buildTranscriptComponents` and rewrite `TranscriptOverlay` (cached `Container`, rebuild-on-change, drop `wrapText`) in `session-navigator.ts`.
+   - Remove `renderTranscriptLines`/`toMessages`/`serializeConversation`/`describeActivity` from `session-navigation.ts`.
+   - Add `cwd` to `SessionNavigatorParams`; update `index.ts` to pass `ctx.cwd`.
+   - Remove the `renderTranscriptLines` describe block from `session-navigation.test.ts`.
+   Run `pnpm run check` immediately (shared-interface + single-call-site change) and `pnpm fallow dead-code` before pushing (confirms no orphaned helper after the renderer move).
+   Commit: `feat: render /subagent-sessions transcript with Pi per-entry components (#462)`.
+4. **Docs: record rendering parity and flip Step 4a.**
+   Test surface: none (docs).
+   Update `docs/architecture/architecture.md` Step 4a status to landed and the `S4a` Mermaid node; note the native navigator now renders at parity, unblocking Step 5.
+   Commit: `docs: mark native-navigation renderer upgrade landed (#462)`.
+
+## Risks and Mitigations
+
+- **Risk: Pi's per-entry components depend on interactive-mode globals (e.g. `initTheme`) not initialized in this context.**
+  Mitigation: the navigator runs inside a live Pi session where theme is already initialized; `getMarkdownTheme()` returns the active theme.
+  The overlay-render tests construct components against a mock `TUI` and assert text appears — a smoke test that the components render outside interactive mode.
+  If a component throws without a global, narrow the role set or supply the missing default at the boundary.
+- **Risk: rebuilding the component tree re-runs markdown highlighting and is expensive under live streaming.**
+  Mitigation: rebuild happens on **source change only** (cached `Container`), not per frame, and the high-frequency streaming text is absorbed by the `◍` indicator (so the tree changes at message granularity).
+  Incremental `updateContent`/`updateResult` reconciliation remains a clean follow-up behind the same seam if profiling ever shows cost (track-and-watch).
+- **Risk: `ToolExecutionComponent` needs `cwd`/`tui`/options not previously threaded.**
+  Mitigation: `cwd` comes from `ctx.cwd` (verified present on the command context), `tui` from the `ui.custom` factory, options default to `{ showImages: false }`.
+- **Risk: removing `renderTranscriptLines` and its tests leaves orphaned imports.**
+  Mitigation: Step 3 removes the `serializeConversation`/`describeActivity` imports from `session-navigation.ts` in the same commit; `pnpm fallow dead-code` and a re-read of the file confirm no orphans (Biome `noUnusedImports` is warning-level).
+- **Risk: parity is asserted only by "text appears", missing richer formatting differences.**
+  Mitigation: the goal is *native-fidelity via Pi's own components* — using the same components Pi uses **is** the parity definition; the tests assert the component path is taken (tool call renders via `ToolExecutionComponent`, bash via `BashExecutionComponent`), not byte-equality with the bespoke output.
+
+## Open Questions
+
+- **`custom`-role messages** — `CustomMessageComponent` requires the session's `extensionRunner.getMessageRenderer(customType)`, which the navigator does not hold.
+  This issue skips custom messages (the bespoke viewer never rendered them either, so this is not a parity regression).
+  If custom-message fidelity is later wanted, a follow-up would surface a message-renderer lookup on the seam — not filed now (speculative).
+- **Step 4a doc flip timing** — flip the architecture status line and Mermaid node in this issue's doc step, or defer to a Phase 19 doc-sync ([#447] precedent); the plan does it in-issue (TDD step 4) by default.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#462]: https://github.com/gotgenes/pi-packages/issues/462
+[#463]: https://github.com/gotgenes/pi-packages/issues/463
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#424]: https://github.com/gotgenes/pi-packages/issues/424
+[#425]: https://github.com/gotgenes/pi-packages/issues/425
+
+[ADR-0004]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/decisions/0004-reconsider-ui-direction.md

package/docs/retro/0444-shrink-widget-to-background-agents.md

@@ -41,3 +41,41 @@ Test count went from 24 to 26 in `agent-widget.test.ts` (two new background-only
   One non-blocking naming WARN — `clearWidget`'s `allAgents` parameter and JSDoc were stale after the refactor (it now receives only background agents); fixed in a follow-up `refactor:` commit (`backgroundAgents`).
   Landed as a separate commit rather than amending the feat commit because HEAD was already the `docs:` commit and the fix must not land in a `docs:` commit.
 - All gates green: `pnpm run check`, root `pnpm run lint`, full vitest (1064), `pnpm fallow dead-code`.
+
+## Stage: Final Retrospective (2026-06-20T22:41:58Z)
+
+### Session summary
+
+Shipped Phase 19 Step 3 end-to-end across three stages (plan → TDD → ship) in one continuous session, releasing `@gotgenes/pi-subagents` v17.2.0.
+The change funnels both `manager.listAgents()` call sites through a single `listBackgroundAgents()` accessor so the above-editor widget shows only background agents.
+Execution was unusually clean: no rabbit holes, no user corrections, one reviewer-caught naming miss resolved in a single follow-up commit.
+
+### Observations
+
+#### What went well
+
+- Tidy-first preparatory step paid off as designed.
+  TDD step 1 (`test:` migrate fixtures to background invocation) was inert until the filter landed, turning the behavior change in step 2 into a pure addition with zero fixture churn mid-cycle.
+  This is the `code-design` skill's "make the change easy, then make the easy change" applied to a test suite — worth reusing whenever a new predicate will retroactively exclude existing fixtures.
+- The pre-completion reviewer caught semantic drift that all four deterministic gates missed.
+  `tsc`, `pnpm run lint`, vitest (1064), and `pnpm fallow dead-code` all passed the stale `clearWidget(allAgents)` parameter — a name whose meaning narrowed to background-only but which no tool flags, because a misleading-but-valid identifier is neither a type nor a lint error.
+  This is the reviewer's distinct value: naming/comment staleness after a rename.
+
+#### What caused friction (agent side)
+
+- `other` (incomplete rename) — during the `feat:` step I renamed the local `allAgents` → `backgroundAgents` in `update()` but left the `clearWidget` parameter (a separate scope receiving the same value) named `allAgents`, along with its JSDoc.
+  Impact: one extra `refactor:` commit (`319e7df3`); ~2 minutes.
+  No rework to logic.
+  Reviewer-caught, not self-caught.
+
+#### What caused friction (user side)
+
+- None.
+  The operator delegated the full plan/TDD/ship/retro workflow and it ran without correction or mid-course steering.
+  No earlier-context opportunity identified.
+
+### Changes made
+
+1. Added this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0444-shrink-widget-to-background-agents.md`.
+
+No `AGENTS.md` or prompt changes: the one friction point (an incomplete rename) was reviewer-caught with trivial cost, and the wins (tidy-first fixture migration, pre-completion reviewer value) are already covered by the `code-design` and `testing` skills — nothing actionable to encode.

package/docs/retro/0445-native-session-navigation.md

@@ -0,0 +1,122 @@
+---
+issue: 445
+issue_title: "pi-subagents: implement native session navigation for any subagent (live or completed)"
+---
+
+# Retro: #445 — pi-subagents: implement native session navigation for any subagent (live or completed)
+
+## Stage: Planning (2026-06-22T00:00:00Z)
+
+### Session summary
+
+Produced `docs/plans/0445-native-session-navigation.md`, a sliced plan for Phase 19 Step 4.
+The operator (issue author) chose Pi's per-entry TUI-component renderer as the eventual target but explicitly invited a Kent Beck "make the change easy, then make the easy change" breakdown into incremental, releasable additions, and chose `manager.listAgents()`-only as the candidate set.
+The plan scopes #445 to the first releasable vertical slice — full list → pick → read-only live transcript using `serializeConversation` text rendering behind a renderer-agnostic `TranscriptSource` seam — and names two follow-ups (TUI-component renderer; evicted-agent file source).
+
+### Observations
+
+- **Two `ask_user` rounds drove scope.**
+  Round 1: renderer choice (text vs TUI components) and candidate-set scope.
+  Round 2: decomposition strategy.
+  The operator's note on round 1 ("If this sounds large, it's probably because it is... what would Kent Beck do") reframed the whole plan from one big issue into a sliced first release.
+- **Key architectural finding — the file-snapshot branch is unreachable in #445.**
+  `SubagentManager.removeRecord` calls `record.disposeSession()` then `agents.delete(id)` atomically, and `disposeSession()` does not null `subagentSession`.
+  So no record in `listAgents()` is ever session-disposed; with the `listAgents()`-only candidate set, every listed session-ready record has a live session, and the dual-source "evicted/untracked → file" branch has no caller.
+  Implementing it now would be dead code that fails the `fallow dead-code` gate.
+  This sharpened the slice: #445 ships the **live source only** behind the seam.
+- **Type-boundary plan.** `AgentMessage` is not in the `@earendil-works/pi-coding-agent` barrel and `@earendil-works/pi-agent-core` is not a dependency, so the plan derives `SessionMessage = SessionContext["messages"][number]` from the barrel-exported `SessionContext` rather than adding a dep. `serializeConversation` takes a mutable `Message[]`, so the renderer spreads (`serializeConversation([...messages])`); `AgentMessage`→`Message` assignability is flagged as a TDD step-2 `pnpm run check` verification with a typed-adapter fallback.
+- **Seam justifies its weight via testability, not just the follow-up.** `TranscriptSource` + narrow `NavigableSubagent` interfaces let the pure module be unit-tested with light stubs (no full `Subagent`/`TUI`/`AgentSession`), and decouple the renderer (text→components) from sourcing (live→file) for the two named follow-ups.
+- **Doomed-code avoidance.**
+  The navigator must not import `message-formatters.ts` or `conversation-viewer.ts` (both deleted in Step 5, [#442]); the streaming indicator is a small local helper and the transcript text is Pi's `serializeConversation`.
+- **Open item for ship time:** the architecture roadmap's Step 4 description currently scopes full dual-source + components as one step and will need rescoping to match the slice, plus filing the two follow-up issues.
+  Command name `subagent-sessions` is proposed but flagged confirmable.
+- Release: ship independently (roadmap Step 4 is `Release: independent`, spike-gated; not part of the "dissolve-agents" batch).
+
+## Stage: Implementation — TDD (2026-06-22T18:03:26Z)
+
+### Session summary
+
+Implemented the sliced #445 in three TDD cycles: (1) the typed `agentMessages` accessor (`SessionMessage` on `SubagentSession`/`Subagent`); (2) the pure `session-navigation.ts` (selection, `liveSource`, `renderTranscriptLines`); (3) the `session-navigator.ts` overlay + `/subagent-sessions` command + `index.ts` wiring.
+Test count went 1064 → 1084 (+20).
+Pre-completion reviewer returned PASS.
+
+### Observations
+
+- **`AgentMessage` is NOT assignable to `serializeConversation`'s `Message[]`** (the plan's flagged risk materialized): `AgentMessage` is a superset adding session-display variants like `BashExecutionMessage`.
+  Applied the planned mitigation — a private `toMessages` adapter casting via `as unknown as Parameters<typeof serializeConversation>[0]` (`Message` is not re-exported from the `@earendil-works/pi-ai` barrel, so the type is referenced through the function signature rather than imported by name).
+- **`SessionContext` name collision:** `types.ts` already declares a local `SessionContext` interface, so the SDK import is aliased — `import type { SessionContext as SdkSessionContext }` — and `SessionMessage = SdkSessionContext["messages"][number]`.
+- **`describeActivity` survives in `display.ts`** (not the doomed `message-formatters.ts`), so the streaming indicator reuses it — the navigator imports neither doomed module, as planned.
+- **File-snapshot branch confirmed unreachable and omitted:** with the `listAgents()`-only candidate set, no listed record is ever session-disposed (dispose-and-delete are atomic), so the live source is always valid; implementing the file branch would have been dead code.
+  `fallow dead-code` is clean.
+- **Minor deviation:** `test/helpers/mock-session.ts` gained an `agentMessages` getter on the session stub (needed for the `Subagent.agentMessages` delegation test) — a small fixture addition not itemized in the plan's Module-Level Changes.
+- **Two lint nits caught by the pre-commit hook** (both per the testing skill): an unnecessary optional chain on a destructured array element, and an unnecessary `!` on `mock.calls[0][0]` — both fixed inline.
+- **Architecture doc:** added a "Landed ([#445], sliced)" note to Step 4; did **not** mark the step `✅` because the component renderer and evicted-agent file source are deferred follow-ups.
+  `SKILL.md` `ui/` module count (10 → 12) left for a later Phase 19 doc-sync, per the plan.
+- **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,49 @@
+---
+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.

package/package.json

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

package/src/index.ts

@@ -47,6 +47,7 @@ import { SteerTool } from "#src/tools/steer-tool";
 import { FsAgentFileOps } from "#src/ui/agent-file-ops";
 import { AgentsMenuHandler } from "#src/ui/agent-menu";
 import { AgentWidget } from "#src/ui/agent-widget";
+import { SessionNavigatorHandler } from "#src/ui/session-navigator";
 import { SubagentsSettingsHandler } from "#src/ui/subagents-settings";
 
 export default function (pi: ExtensionAPI) {
@@ -192,4 +193,15 @@ export default function (pi: ExtensionAPI) {
       await subagentsSettings.handle({ ui: ctx.ui });
     },
   });
+
+  // ---- /subagent-sessions command ----
+
+  const sessionNavigator = new SessionNavigatorHandler();
+
+  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 });
+    },
+  });
 }