@gotgenes/pi-subagents 17.3.0 → 17.5.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [17.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.4.0...pi-subagents-v17.5.0) (2026-06-23)
+
+
+### Features
+
+* **pi-subagents:** add file-snapshot transcript source ([06a9ee3](https://github.com/gotgenes/pi-packages/commit/06a9ee39b5f529f770c39cf8d8bdcefd1511bb7d))
+* **pi-subagents:** retain evicted-agent descriptors in the manager ([3128e2a](https://github.com/gotgenes/pi-packages/commit/3128e2a44b94be9b976b74d24cf5127ca0944074))
+* **pi-subagents:** source evicted-agent transcripts from disk in /subagent-sessions ([b4da762](https://github.com/gotgenes/pi-packages/commit/b4da762b0574b49e028518c62e7b2f11acaf1ad4))
+
+## [17.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.3.0...pi-subagents-v17.4.0) (2026-06-23)
+
+
+### Features
+
+* add getToolDefinition accessor on subagent record ([#462](https://github.com/gotgenes/pi-packages/issues/462)) ([e0bfdac](https://github.com/gotgenes/pi-packages/commit/e0bfdacec33120d0f52e6294f3676f4776aee4af))
+* expose getToolDefinition on the transcript source seam ([#462](https://github.com/gotgenes/pi-packages/issues/462)) ([669f5ff](https://github.com/gotgenes/pi-packages/commit/669f5ff71523122ebb011adc6875b54d7001d53a))
+* render /subagent-sessions transcript with Pi per-entry components ([#462](https://github.com/gotgenes/pi-packages/issues/462)) ([b832a43](https://github.com/gotgenes/pi-packages/commit/b832a437c97378f701033ef8e98c6f7805d7e7a8))
+
 ## [17.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.2.0...pi-subagents-v17.3.0) (2026-06-22)
 
 

package/docs/architecture/architecture.md

@@ -918,9 +918,9 @@ The end state deletes `agent-menu.ts` — the god-command that bundles four unre
 Rather than surgically mutate that doomed module (and the #1 churn hotspot `index.ts`) once per option, Phase 19 first stands up the replacement surfaces additively, then removes the now-orphaned subtree in a single terminal cut.
 This keeps every responsibility's old surface live until its replacement exists (ADR-0004's no-interim-regression invariant), turns the three replacement steps into genuinely parallel work (none touch `agent-menu.ts`), and reduces `index.ts` edits from four surgical removals to one deregistration.
 
-Seven steps in three phases:
+Seven numbered steps in three phases, plus two follow-ups (Steps 4a–4b) carved from the #445 slice:
 
-- **Phase A — stand up replacements (additive):** spike, settings command, background widget, native session navigation (Steps 1–4).
+- **Phase A — stand up replacements (additive):** spike, settings command, background widget, native session navigation and its renderer/source follow-ups (Steps 1–4, 4a–4b).
 - **Phase B — dissolve `/agents` (terminal cut):** delete the orphaned subtree in two deletion commits, one per subtree (Steps 5–6).
 - **Phase C — test health:** consolidate the test clones that survive the cut (Step 7).
 
@@ -987,7 +987,7 @@ Outcome: widget shows only background agents; foreground/widget duplication elim
 
 `Release: independent`
 
-### Step 4 — Implement native session navigation ([#445])
+### ✅ Step 4 — Implement native session navigation ([#445])
 
 Smell: Category C (coupling) — the bespoke `ConversationViewer` re-implements session-transcript rendering when Pi's own machinery targets the already-persisted child session JSONL.
 This step adds the new surface alongside the existing viewer; it does not touch `agent-menu.ts`.
@@ -1013,11 +1013,48 @@ Outcome: operator views any subagent's session through Pi's native machinery —
 Landed ([#445], sliced): #445 shipped the first releasable vertical slice — the `/subagent-sessions` command (`src/ui/session-navigator.ts`), the pure selection/sourcing/text-render core (`src/ui/session-navigation.ts`), and the typed `agentMessages` accessor (`SessionMessage` on `SubagentSession`/`Subagent`).
 It is **live-source only** behind a renderer-agnostic `TranscriptSource` seam, rendered via Pi's `serializeConversation` text.
 With the `manager.listAgents()`-only candidate set, no listed record is ever session-disposed (dispose-and-delete are atomic), so the file-snapshot branch has no reachable caller and was deferred to keep `fallow dead-code` clean.
-Two follow-ups complete the step behind the same seam: (a) upgrade the renderer from `serializeConversation` text to Pi's per-entry TUI components; (b) broaden the candidate set to evicted agents and add the file-snapshot source (`parseSessionEntries` → `buildSessionContext`).
-The step heading stays unchecked until both land.
+Step 4 (#445, the slice) is complete and released (`pi-subagents` v17.3.0); the remaining work is now tracked as two follow-up steps behind the same seam: Step 4a ([#462]) upgrades the renderer from `serializeConversation` text to Pi's per-entry TUI components (gates Step 5 for rendering parity); Step 4b ([#463]) broadens the candidate set to evicted agents and adds the file-snapshot source (`parseSessionEntries` → `buildSessionContext`, independent).
 
 `Release: independent` (spike-gated)
 
+### ✅ Step 4a — Upgrade native-navigation renderer to Pi TUI components ([#462])
+
+Smell: Category C (coupling) — the #445 slice renders the transcript as `serializeConversation` plain text, while the bespoke `ConversationViewer` it replaces renders richer per-message formatting.
+Until the native renderer reaches parity, the terminal cut (Step 5) cannot delete the bespoke viewer without a fidelity regression.
+This step swaps the renderer behind the existing `TranscriptSource` seam (`src/ui/session-navigation.ts` / `session-navigator.ts`) for Pi's per-entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / …); selection and sourcing are untouched.
+
+Gates Step 5: per [ADR-0004]'s no-interim-regression invariant, the native navigator must reach rendering parity with the bespoke viewer before Step 5 deletes it.
+
+Outcome: native session navigation renders at parity with the removed `ConversationViewer`; Step 5 can delete the bespoke viewer with no fidelity regression.
+
+Landed ([#462]): the renderer now mounts Pi's per-entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / `BashExecutionComponent` / `UserMessageComponent` / `CompactionSummaryMessageComponent` / `BranchSummaryMessageComponent` / `SkillInvocationMessageComponent`) into a `Container`, mirroring Pi's own `renderSessionContext` mapping.
+The `TranscriptOverlay` caches that `Container` and rebuilds it on source change only (Pi's `rebuildChatFromMessages` path), keeping the lightweight `◍` streaming indicator.
+Tool calls render with their real `ToolDefinition`, resolved through a dependency-safe `getToolDefinition` read accessor on the record (mirroring `agentMessages`) surfaced on the `TranscriptSource` seam — no inbound call into the core.
+The pure `session-navigation.ts` sheds `renderTranscriptLines`/`serializeConversation`; rendering now lives in the SDK/TUI `session-navigator.ts`, which threads `cwd` from the command context.
+`custom`-role messages are skipped (the bespoke viewer never rendered them either).
+Selection and sourcing are untouched; native navigation now renders at parity, unblocking Step 5 for rendering fidelity.
+
+`Release: independent`
+
+### ✅ Step 4b — File-snapshot source for evicted agents ([#463])
+
+Smell: Category C (coupling) — the #445 slice sources transcripts live from `manager.listAgents()` only; an agent evicted by the 10-minute cleanup sweep has a persisted session JSONL but no live record, so it is unreachable.
+This step adds the file-snapshot `TranscriptSource` branch (`parseSessionEntries(readFile(outputFile))` → drop the `SessionHeader` → `buildSessionContext(...).messages`) and broadens the candidate set to evicted agents, behind the same seam; the renderer is untouched.
+
+Independent: this is a new capability the bespoke viewer never had, so it gates nothing and is not a Step 5 prerequisite.
+Best sequenced after Step 4a (shared renderer), but carries no hard dependency.
+
+Outcome: the operator can view a fully-evicted agent's transcript from its persisted session file; the dual-source design recorded in [ADR-0004] Addendum 2 is fully realized.
+
+Landed ([#463]): `fileSnapshotSource(outputFile, readFile)` lands in the pure `session-navigation.ts` (`parseSessionEntries` → drop the `SessionHeader` → `buildSessionContext(...).messages`; a static no-subscribe, no-streaming source).
+The candidate set is broadened via **manager-retained descriptors**, not a directory scan: the persisted child session carries no subagent `type`/`description` (those live only on the in-memory record), so a scan would yield degraded labels and parse every file per open.
+Instead `SubagentManager.cleanup()` stashes a lightweight `EvictedSubagent` descriptor (label fields + `outputFile`, no messages) before disposing a record with a persisted file, exposed via `listEvicted()` and cleared by `clearCompleted()`/`dispose()`.
+`NavigationEntry` became a `live | evicted` discriminated union; the handler selects `liveSource` vs `fileSnapshotSource` by kind inside a `try/catch` (an unreadable file notifies and skips), and `index.ts` injects `readFileSync`.
+Evicted entries carry an `· evicted (snapshot)` label marker.
+Coverage is in-session evictions (the sweep's only targets); old-session orphan files — the ones a scan would surface with degraded labels — are out of scope.
+
+`Release: independent`
+
 ### Step 5 — Dissolve `/agents` and remove the conversation-viewer subtree ([#442])
 
 Smell: Category A (dead subsystem) plus Category B (oversized) — once Steps 2–4 re-home all four menu responsibilities, the `/agents` command and everything reachable only from `agent-menu.ts` is an unreferenced subtree.
@@ -1079,20 +1116,25 @@ flowchart LR
     S1["✅ Step 1 - Spike (#446)"]
     S2["✅ Step 2 - Settings command (#447)"]
     S3["✅ Step 3 - Background widget (#444)"]
-    S4["Step 4 - Native session nav (#445)"]
+    S4["✅ Step 4 - Native session nav slice (#445)"]
+    S4a["✅ Step 4a - Renderer to TUI components (#462)"]
+    S4b["✅ Step 4b - File-snapshot source (#463)"]
     S5["Step 5 - Dissolve /agents + viewer (#442)"]
     S6["Step 6 - Remove definition mgmt (#441)"]
     S7["Step 7 - Test clones (#443)"]
 
     S1 --> S4
+    S4 --> S4a
+    S4 --> S4b
     S2 --> S5
     S3 --> S5
-    S4 --> S5
+    S4a --> S5
     S5 --> S6
     S6 --> S7
 ```
 
-The terminal cut (Step 5) depends on all three replacements — settings (Step 2), widget (Step 3), and session navigation (Step 4) — because each of the four `/agents` options must have its responsibility re-homed before its branch can die.
+The terminal cut (Step 5) depends on all three replacements — settings (Step 2), widget (Step 3), and session navigation **at rendering parity** (Step 4a, which completes the #445 slice) — because each of the four `/agents` options must have its responsibility re-homed, and the viewer replacement at parity, before its branch can die.
+Step 4b (file-snapshot source) is a new capability and gates nothing.
 The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes it explicit.
 
 ### Parallel tracks
@@ -1100,6 +1142,7 @@ The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes i
 - **Track A — Replacements (Steps 1–4):** the spike gates session navigation (Step 1 → Step 4); settings (Step 2) and the background widget (Step 3) are independent of the spike and of each other.
   None of these steps edits `agent-menu.ts`, so they carry no shared-file collision on the menu — genuinely parallelizable, unlike the prior plan's Steps 2/3/5, which all collided on `agent-menu.ts` and `index.ts`.
   Steps 2 and 4 each append a command registration to `index.ts` (additive, low-conflict).
+  Steps 4a (renderer parity) and 4b (file-snapshot source) complete the #445 slice behind its `TranscriptSource` seam; Step 4a gates Step 5, Step 4b is independent.
 - **Track B — Dissolution (Steps 5 → 6):** the terminal cut, gated on all of Track A landing.
   Hub-first ordering is forced: Step 5 deletes `agent-menu.ts` (orphaning the leaves), then Step 6 `git rm`s the now-orphaned definition-management subtree.
 - **Track C — Test health (Step 7):** clone consolidation, run after the cut so no surviving helper is extracted into a doomed file.
@@ -1108,7 +1151,7 @@ The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes i
 
 - **Batch "dissolve-agents":** Steps 5, 6 (ship together; tail = Step 6).
   Depends on Steps 2, 3, 4 already merged.
-- Independently releasable: Steps 1, 2, 3, 4, 7.
+- Independently releasable: Steps 1, 2, 3, 4, 4a, 4b, 7.
 
 ## Refactoring history
 
@@ -1230,5 +1273,7 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#445]: https://github.com/gotgenes/pi-packages/issues/445
 [#446]: https://github.com/gotgenes/pi-packages/issues/446
 [#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#462]: https://github.com/gotgenes/pi-packages/issues/462
+[#463]: https://github.com/gotgenes/pi-packages/issues/463
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md
 [ADR-0004]: ../decisions/0004-reconsider-ui-direction.md

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

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

package/docs/plans/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