@gotgenes/pi-subagents 17.2.0 → 17.3.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [17.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.2.0...pi-subagents-v17.3.0) (2026-06-22)
+
+
+### Features
+
+* add /subagent-sessions read-only navigation command ([#445](https://github.com/gotgenes/pi-packages/issues/445)) ([341385c](https://github.com/gotgenes/pi-packages/commit/341385cf1f0c9f5ae1d3035c5b3b34bc3e636c92))
+* add subagent session selection and live transcript source ([#445](https://github.com/gotgenes/pi-packages/issues/445)) ([7173647](https://github.com/gotgenes/pi-packages/commit/71736478c37af2c6ceaebc3ce0ee5a85e75ab1cb))
+* add typed agentMessages accessor on subagent record ([#445](https://github.com/gotgenes/pi-packages/issues/445)) ([3bd49e3](https://github.com/gotgenes/pi-packages/commit/3bd49e37feea2cca52c706f7e765b8ae934ab9fe))
+
 ## [17.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.1.0...pi-subagents-v17.2.0) (2026-06-20)
 
 

package/docs/architecture/architecture.md

@@ -500,6 +500,9 @@ Everything else — permissions, worktree/workspace isolation, UI, telemetry —
 
 The rationale and the full reasoning chain that led here are recorded in [`docs/decisions/0002-extensions-on-a-minimal-core.md`](../decisions/0002-extensions-on-a-minimal-core.md).
 
+A separate, longer-horizon note — [`client-server-opportunities.md`](./client-server-opportunities.md) — records what Pi's eventual client-server split (Mario Zechner's session-sync unification) would unlock for pi-subagents: viewing live subagent sessions, viewing suspended ones, and operators interacting with a subagent through an editor.
+That architecture is not on the near-term roadmap; the note captures the opportunity so it is on record.
+
 ### Two extension surfaces
 
 Extensions attach through exactly two surfaces, distinguished by the direction of information flow.
@@ -990,16 +993,28 @@ Smell: Category C (coupling) — the bespoke `ConversationViewer` re-implements
 This step adds the new surface alongside the existing viewer; it does not touch `agent-menu.ts`.
 Target files:
 
-- New `src/ui/session-navigator.ts` (or a widget gesture, per Step 1's answer to parallel-agent navigation) — operator picks one of N background agents and views its persisted session via the spike-chosen mechanism, keyed on `record.outputFile`.
-- `src/index.ts` — register the new navigation surface (command and/or widget gesture, per the spike).
+- New `src/ui/session-navigator.ts` — a flat command that lists any subagent with a live record or a persisted session file (foreground included, never background-filtered), lets the operator pick one, and renders that child's transcript read-only.
+- New typed accessor on `Subagent`/`SubagentSession` returning `record.messages` as `AgentMessage[]` (the boundary currently widens it to `readonly unknown[]`).
+- `src/index.ts` — register the new command; the background widget ([#444]) is an optional secondary selection gesture, not a dependency.
 
 ADR-0004 Decision B: "Tell-Don't-Ask — hand Pi the session path; Pi owns the viewer."
-Mechanism (confirmed by the Step 1 spike, [ADR-0004] addendum): a **read-only** transcript rendered from `parseSessionEntries(readFileSync(record.outputFile, "utf8"))`, surfaced through a flat command — **not** `switchSession` (a full takeover that invalidates the root's in-flight turn) and **not** `loadEntriesFromFile` (a test-only export of the SDK's `core/session-manager` module that the package's public barrel does not re-export, in both `0.79.1` and `0.79.8`).
+Mechanism (confirmed by the Step 1 spike and revised by [ADR-0004] Addendum 2): a **read-only** (non-interactive) transcript **dual-sourced by liveness**, rendered through Pi's own public entry components (no bespoke renderer).
+
+- **Tracked agent** (still in `manager.listAgents()`) — render live from the in-memory record: `record.messages` for history, `record.subscribeToUpdates()` to re-render on streaming updates, and `record.activeTools` / `record.responseText` for the running-agent streaming indicator.
+- **Evicted / untracked agent** — render from the file snapshot: `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages`.
+
+Both sources yield `AgentMessage[]`, so one Pi-component renderer serves both: Pi's public entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / …) or `serializeConversation` (see the [ADR-0004] addendum, Findings 0 and 1).
+Neither `switchSession` (a full takeover that invalidates the root's in-flight turn) nor `loadEntriesFromFile` (a test-only export the package's public barrel does not re-export, in both `0.79.1` and `0.79.8`) is used.
 `Subagent.outputFile` already exposes the persisted child session JSONL path via `subagentSession?.outputFile` — no new SDK dependency.
-Rendering uses Pi's own public APIs (no bespoke renderer): `parseSessionEntries` → drop the `SessionHeader` → `buildSessionContext(...).messages` → Pi's public entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / …) or `serializeConversation` (see the [ADR-0004] addendum, Findings 0 and 1).
 The new surface stands up while the old `viewAgentConversation`/`ConversationViewer` path still works; the bespoke viewer is removed only by the terminal cut (Step 5).
 
-Outcome: operator views a child agent's persisted session through Pi's native machinery; the new surface coexists with the old viewer until Step 5.
+Outcome: operator views any subagent's session through Pi's native machinery — live for a running agent, a file snapshot for an evicted one; the new surface coexists with the old viewer until Step 5.
+
+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.
 
 `Release: independent` (spike-gated)
 

package/docs/architecture/client-server-opportunities.md

@@ -0,0 +1,127 @@
+# Client-server architecture: opportunities for pi-subagents
+
+This note is forward-looking.
+Pi's client-server split is **not on the near-term roadmap** — it is a long-term vision recorded in Mario Zechner's [pi session sync unification][session-sync] plan.
+This document captures what that architecture would let pi-subagents do, so the opportunity is on record alongside the existing [Target architecture](./architecture.md#target-architecture) section.
+
+It assumes the session-sync plan's shape:
+
+- `AgentSession` owns all authoritative intra-session state and emits all sync events.
+- `AgentSessionServer` owns multiple `AgentSession` runtimes, session lifecycle, client subscriptions, snapshots, and deltas.
+- `AgentSessionClient` is the only thing a renderer (interactive mode, web mode) talks to.
+- The sync model is **snapshot plus delta**: a client joins a session, receives one canonical snapshot, then a stream of deltas.
+- Commands go up; state deltas come down.
+- A client can `watch` (read-only) or `join` (interactive) a session, and can hold synchronized caches for many sessions at once.
+- Session lifecycle (`new`, `resume`, `fork`, `import`, `join`, `leave`, `watch`, `unwatch`) is normal server API, not hidden local runtime replacement.
+
+## The key realization
+
+A subagent **is** a child `AgentSession`. pi-subagents already creates one via `createSubagentSession`, drives its turn loop through `SubagentSession`, and disposes it.
+
+Today that child session is an in-process object visible only through machinery pi-subagents had to invent because Pi has no session-sync client:
+
+- `record-observer` re-derives live activity from raw session events.
+- the 80 ms `SubagentManager.listAgents()` widget poll.
+- the [#277] Law-of-Demeter accessors (`Subagent.getConversation()`, `.messages`, `.subscribeToUpdates()`, `.getContextPercent()`) that re-expose session internals.
+- the bespoke `ConversationViewer`, and [ADR-0004]'s replacement, native session navigation.
+- [ADR-0004]'s dual-source-by-liveness split (tracked agent → in-memory record; evicted → file snapshot).
+
+Every one of those is pi-subagents reinventing an `AgentSessionClient`.
+The session-sync plan supplies the real one.
+If subagent child sessions are registered as first-class sessions in the `AgentSessionServer`, all three target capabilities reduce to the same primitive the operator's own session already uses: `watch`/`join` a session id, receive a snapshot, then a delta stream.
+
+## Capability 1 — viewing live subagent sessions
+
+`watchSession(subagentSessionId)` gives the operator's client a canonical `SessionSnapshot` (current streaming message, pending tool executions with partial results, queue contents, context usage, active tools) followed by the live delta stream (`message_update`, `tool_execution_start/update/end`, `turn_start/end`).
+
+What changes versus today:
+
+1. **Late-join correctness.**
+   The snapshot carries in-flight state, so an operator attaching to an already-running subagent immediately sees its current streaming message and pending tools — not just future events.
+   Today the conversation viewer only catches future deltas plus whatever happens to be in the in-memory record.
+2. **The widget and viewer become thin renderers** of synchronized session state.
+   The 80 ms poll, `record-observer`, and the [#277] accessors disappear — they were all substitutes for `subscribeSession`.
+3. **A unified, reconnect-safe live session list.**
+   The global event scope (`session_created`, `session_status_changed` idle/busy) means the operator sees every subagent the instant it spawns, with a live status badge per agent — replacing both `listAgents()` polling and the hand-rolled `subagents:*` broadcast tier.
+4. **Multi-session client state** lets one operator client hold synchronized caches for N subagents at once.
+   This is the clean foundation for the parallel-agent navigation gesture that [ADR-0004]'s spike (entry-criterion #3) struggled to design — tabbed or split views of multiple live subagents fall out of the model with no redesign.
+
+## Capability 2 — viewing suspended subagent sessions
+
+Today "suspended" is a dead end: once a background subagent completes and `disposeSession()` fires, the live `AgentSession` is gone, and the only artifact is the persisted JSONL read one-shot via `parseSessionEntries`.
+That is a static file dump with no liveness and no path back to interaction.
+
+Under the server model, the live/suspended distinction collapses at the client.
+Session lifecycle is normal server API (`resume_session`, `join_session`, `import_session`), so a suspended subagent is just a session the server can rehydrate from `SessionManager` on demand:
+
+1. The operator calls `joinSession(id)` (or the server lazily reloads the `AgentSession` from JSONL when a client joins a dormant session), gets a snapshot, and renders it through the same components as a live session.
+   [ADR-0004]'s two-code-path split (in-memory record vs file snapshot) stops being the client's problem — whether the session is resident or rehydrated is the server's private concern.
+2. A genuinely paused subagent (one parked by the `ConcurrencyLimiter` awaiting capacity, or deliberately held) becomes representable: the server holds the runtime idle, the operator can `watch` its frozen state, and then sees it transition to `busy` via `session_status_changed` when capacity frees up.
+3. Subagents can outlive the operator's TUI.
+   Because the server is a separate process, if the operator's interactive client restarts it reconnects and re-lists or re-joins subagent sessions that survived — impossible in today's single-process model.
+
+## Capability 3 — operators interacting via an editor and submitting messages
+
+Today the only inbound channel to a running subagent is `steer_subagent` — a single buffer-or-deliver message through `Subagent.steer`.
+No editor, no takeover, no real conversation.
+
+The plan's `join` versus `watch` split is the right primitive:
+
+1. **`watch` is read-only** (Capability 1).
+   **`join` is interactive participation**: the operator's client sends session commands scoped to the subagent's session id — `prompt`, `abort`, `set model`, `set thinking level`, `set active tools`, `navigate tree`, `compact`, `run bash`.
+2. **Editor flow.**
+   The operator opens the subagent session in their client, types in the editor (editor text, focus, and overlays are explicitly client-local UI state, never synchronized), and submits a `prompt` command targeting the subagent's session id.
+   The command goes up; the server applies it to the subagent's `AgentSession` (which already owns prompt submission, queued steering, and follow-up messages); canonical deltas flow back down to all subscribers.
+   This is precisely "commands go up, state deltas come down," applied to a subagent session instead of the operator's own.
+3. **`steer` generalizes into the full command surface.**
+   pi-subagents' bespoke buffer-or-deliver logic (`Subagent.steer` rejecting when not running) is subsumed by `AgentSession`'s queued-steering machinery, and the custom buffering becomes redundant.
+4. **Multiple clients on one session.**
+   The plan supports this explicitly, with deltas broadcast to all subscribers including the initiator, so an operator can jump into a subagent the parent agent spawned, inject guidance, and the parent's view stays consistent.
+5. **Fork and rewind, not just append.**
+   `navigate tree` plus `fork_session` let an operator rewind a subagent or fork it at an entry — full session editing, far beyond appending a steer message.
+
+## What pi-subagents itself becomes
+
+This validates and sharpens the direction the architecture doc is already heading. pi-subagents' stated core job — spawn a child session derived from the parent, run the turn loop, track and stream and collect the result, gate concurrency, support resume, and publish its lifecycle — is almost exactly the `AgentSessionServer`'s job for child sessions.
+
+- **The observation tier dissolves.**
+  This confirms [Phase 18]'s own finding that "the activity/metrics push tier is provisional" — under the server it genuinely does not need to exist in pi-subagents.
+- **The recursion principle gets its real substrate.**
+  The architecture doc's "a subagent is a recursive Pi" framing maps directly onto the plan's session model: a subagent session is just another session in the server, with the same snapshot, delta, and command surface.
+- **pi-subagents keeps only its semantic layer** — agent type, description, result text, token totals, concurrency admission, and the recursion guard — the things a generic session server does not know.
+  The liveness and activity channel rides on session sync instead of a hand-rolled broadcast.
+
+### Bespoke machinery the server would retire
+
+| Today (pi-subagents reinvents it)                                        | Under the server architecture                              |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `record-observer` re-deriving live activity                              | `subscribeSession` delta stream                            |
+| 80 ms `listAgents()` widget poll                                         | `session_created` / `session_status_changed` global events |
+| [#277] accessors (`messages`, `subscribeToUpdates`, `getContextPercent`) | `SessionSnapshot` + deltas                                 |
+| `ConversationViewer` / native session navigation                         | client renders the snapshot through Pi's own components    |
+| dual-source-by-liveness split                                            | server rehydrates; client sees one session shape           |
+| `steer_subagent` buffer-or-deliver                                       | `join` + `prompt` / queued-steering commands               |
+| `subagents:*` activity broadcasts                                        | session sync (semantic events stay; liveness moves)        |
+
+## Prerequisites and open questions
+
+Being honest about the constraints the plan itself raises:
+
+1. **Registry-local provider state is a hard prerequisite** (the plan states this explicitly).
+   Subagents run in-process under a multi-session server — exactly the scenario where process-global provider registration would corrupt one session's model view from another's extension load. pi-subagents is well-positioned (it already snapshots model and registry into `ParentSnapshot`), but the underlying Pi change must land first.
+2. **The recursion guard stays pi-subagents' invariant.**
+   A subagent session created through the server must still have pi-subagents' three tools stripped, and an operator-joined subagent must not be able to spawn observers of itself in a loop.
+3. **Workspace context must travel in the snapshot.**
+   Subagents can run in a different cwd or git worktree (`pi-subagents-worktrees`).
+   The plan's `SessionSnapshot.cwd` field already accounts for this, so an operator's client renders and interacts in the correct workspace.
+4. **Operator-submitted versus parent-submitted command permissions.**
+   Commands an operator joins and submits flow through the subagent's `AgentSession`, so pi-permission-system's in-child gating still applies — but whether an operator's `run bash` or `prompt` should carry a different permission posture than the parent agent's is a genuine open design question, not something to assume.
+
+## Net assessment
+
+This architecture turns all three capabilities from bespoke, fragile features pi-subagents must build and maintain into thin clients of one uniform session-sync surface — and in doing so lets pi-subagents shed most of the observation infrastructure it only built because that surface did not exist yet.
+
+[session-sync]: https://jot.mariozechner.at/s/zgzbq9n4f4mfck
+[ADR-0004]: ../decisions/0004-reconsider-ui-direction.md
+[Phase 18]: ./architecture.md#phase-18-complete
+[#277]: https://github.com/gotgenes/pi-packages/issues/277

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

@@ -214,6 +214,40 @@ Reject the tentative `/subagents:settings` and the `/agents-settings` alternativ
 
 This keeps bespoke transcript rendering out of the package (rendering is Pi's own public components), adds no inbound call from the UI to the core, and preserves the Phase 18 spine invariants (#422–#425).
 
+## Addendum 2 (2026-06-20): Step 4 sourcing — live record plus file snapshot ([#445])
+
+This addendum revises the first addendum's Criterion 2 answer for Step 4 ([#445]).
+The "strictly read-only, file-only" sourcing and the "not a live overlay" framing are superseded by the dual-source decision below; everything else from the spike stands.
+
+**Why revise.**
+The spike's mechanism — `parseSessionEntries(readFileSync(record.outputFile))` read once — serves a _completed_ subagent well but is a frozen snapshot for a _running_ one: it shows only what was flushed to disk at open time and does not stream.
+The clarified desired behavior is to see the **live** activity of any subagent _and_ the activity of a completed subagent.
+The bespoke `ConversationViewer` being removed in Step 5 already delivers both — it subscribes to the live in-memory record (`record.subscribeToUpdates()`) and renders `record.messages` plus a streaming indicator built from `record.activeTools` / `record.responseText`.
+That liveness comes from the in-memory record, not the persisted file, so a file-only viewer drops it.
+
+**Decision — dual-source, one renderer.**
+Step 4 sources the transcript by liveness and renders both sources through the same Pi public entry components (Finding 1 holds — no bespoke renderer):
+
+- **Tracked agent (still in `manager.listAgents()`)** — render from the live in-memory record: `record.messages` for history, `record.subscribeToUpdates()` to re-render on streaming updates, and `record.activeTools` / `record.responseText` for the running-agent streaming indicator.
+  This is live.
+- **Evicted / untracked agent** — render from the file snapshot: `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages` (Findings 0 and 1).
+
+Both sources yield `AgentMessage[]`, so a single Pi-component renderer serves both.
+
+**Type-boundary note.**
+`SubagentSession.messages` is deliberately widened to `readonly unknown[]` at the core boundary (`src/lifecycle/subagent-session.ts`), even though the underlying `_session.messages` is the SDK's `AgentMessage[]`.
+Step 4 should add a typed accessor that returns `AgentMessage[]` (or narrow at the boundary) rather than feeding `unknown[]` into Pi's components.
+This is a read accessor on the existing record — it adds no inbound call from the UI to the core and does not regress the Phase 18 spine invariants.
+
+**Still read-only (non-interactive).**
+The viewer remains strictly non-interactive: Criterion 2's anti-redundant-steering rationale stands (steering lives in the `steer_subagent` tool and the widget), and Criterion 1's rejection of `switchSession` is unchanged — "live" here means the in-memory subscription, not an active-session takeover.
+
+**Candidate set (revises Criterion 3).**
+The selection command lists **any subagent with a live record or a persisted session file** — foreground agents included, not only running background agents.
+This matches the bespoke viewer's current reach (gated on `record.isSessionReady()`, never background-filtered) and avoids an interim regression.
+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.
+
 [#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

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

@@ -0,0 +1,365 @@
+---
+issue: 445
+issue_title: "pi-subagents: implement native session navigation for any subagent (live or completed)"
+---
+
+# Native session navigation for subagents (live transcript, text renderer)
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 19 Step 4 ([#445]) carries `Release: independent` (spike-gated) in the architecture roadmap.
+The only batch defined in Phase 19 is "dissolve-agents" (Steps 5–6, [#442]/[#441]); Step 4 is an additive replacement surface that stands up alongside the bespoke viewer and is not part of that batch.
+It ships on its own.
+
+## Problem Statement
+
+The operator can view a subagent's conversation only through the bespoke `ConversationViewer` overlay, reachable inside the monolithic `/agents` menu.
+That overlay re-implements session-transcript rendering — message formatting, a streaming indicator, scroll chrome — even though Pi already persists each child as a standalone session JSONL and ships its own session-rendering machinery.
+ADR-0004 Decision B replaces the bespoke overlay with **native session navigation**: a flat command that lists the session's subagents, lets the operator pick one, and renders that child's transcript read-only through Pi's own components.
+
+ADR-0004 Addendum 2 (the Step 1 spike, [#446]) refines the sourcing: a file read is a *snapshot* (good for a completed agent, frozen for a running one), so the transcript is **dual-sourced by liveness** — live from the in-memory record for a tracked agent, a file snapshot for an evicted one — rendered through one renderer.
+
+This issue is deliberately **sliced** (see Decomposition below).
+It stands up the complete navigation UX — list → pick → read-only, live transcript — behind a renderer-agnostic source seam, using Pi's `serializeConversation` as the first renderer.
+Upgrading that renderer to Pi's per-entry TUI components, and broadening the candidate set to evicted agents, are named follow-ups.
+
+## Goals
+
+- Add a flat `/subagent-sessions` command that lists navigable subagents (`manager.listAgents()`, gated on `isSessionReady()`), lets the operator pick one, and renders its transcript **read-only** (non-interactive) in a scrollable overlay.
+- Source the transcript **live** from the in-memory record: history from a new typed `agentMessages` accessor, live re-render via `record.subscribeToUpdates()`, and a running-agent streaming indicator from `record.activeTools` / `record.responseText`.
+- Render through Pi's own `serializeConversation` (no bespoke message-formatting code) behind a `TranscriptSource` seam, so a follow-up swaps in Pi's per-entry TUI components without touching selection or sourcing.
+- Add a typed `agentMessages` accessor on `SubagentSession` and `Subagent` returning `readonly SessionMessage[]` (the boundary currently widens `messages` to `readonly unknown[]`).
+- Stand the new surface up **alongside** the existing `viewAgentConversation` / `ConversationViewer` path — it is removed only by Phase 19 Step 5 ([#442]).
+
+Non-breaking: this is pure addition.
+No existing export, command, default, or behavior changes.
+
+## Non-Goals
+
+- Do **not** implement the **file-snapshot** source branch (`parseSessionEntries` → `buildSessionContext`) in this issue.
+  With the `listAgents()`-only candidate set, no listed record is ever session-disposed (see Background), so the file branch has **no reachable caller** here — implementing it now would be dead code that fails the `fallow dead-code` gate.
+  It ships with the follow-up that broadens the candidate set to evicted agents.
+- Do **not** use Pi's per-entry TUI components (`AssistantMessageComponent` / `ToolExecutionComponent` / …) as the renderer in this issue — that is the named renderer follow-up.
+- Do **not** add in-session steering or any interactive gesture — steering stays in `steer_subagent` and the widget; the viewer is strictly read-only.
+- Do **not** use `switchSession` or `loadEntriesFromFile` (per the ADR-0004 addendum).
+- Do **not** touch `agent-menu.ts`, `conversation-viewer.ts`, or `message-formatters.ts` — they stay live until Step 5 ([#442]).
+- Do **not** wire a widget selection gesture — the command is the primary surface; a widget gesture ([#444]) is an optional later enhancement.
+
+## Background
+
+Relevant existing modules:
+
+- `src/lifecycle/subagent-session.ts` — `SubagentSession` wraps one SDK `AgentSession`.
+  Its `get messages(): readonly unknown[]` returns `this._session.messages as readonly unknown[]` — deliberately widened at the core boundary.
+  It already exposes `subscribe(fn)`, `outputFile`, `getContextPercent()`.
+- `src/lifecycle/subagent.ts` — `Subagent` delegates `get messages(): readonly unknown[]`, `subscribeToUpdates(fn)`, `get outputFile()`, `isSessionReady()`, `get activeTools()`, `get responseText()`, `get status()` to its `subagentSession` / `state`.
+  These are the exact accessors the bespoke `ConversationViewer` reads — the new navigator reads the same surface.
+- `src/lifecycle/subagent-manager.ts` — `listAgents()` returns tracked `Subagent[]` (newest first).
+  `cleanup()` (every 60 s) and `clearCompleted()` call `removeRecord(id, record)`, which calls `record.disposeSession()` **then** `agents.delete(id)` atomically.
+  `disposeSession()` disposes the wrapped session but does **not** null `subagentSession`; however, because dispose-and-delete are atomic, **no record that remains in `listAgents()` is ever session-disposed**.
+  Consequence: with the `listAgents()`-only candidate set, every listed, session-ready record has a live (non-disposed) session — so the live source is always valid and the file-snapshot branch is unreachable (drives the Non-Goal above).
+- `src/ui/conversation-viewer.ts` — the bespoke overlay being replaced (deleted in Step 5).
+  Reads `record.messages`, subscribes via `record.subscribeToUpdates()`, renders a streaming indicator from `record.activeTools` / `record.responseText`, and owns its own scroll chrome (up/down/pageUp/pageDown/home/end/esc).
+  The new navigator must **not** import from it or from `message-formatters.ts` (both doomed in Step 5).
+- `src/ui/agent-menu.ts` — `viewAgentConversation(ui, record)` gates on `record.isSessionReady()` and opens the overlay via `ui.custom<undefined>((tui, theme, _kb, done) => new ConversationViewer({...}), { overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "70%" } })`.
+  This is the wiring shape the navigator mirrors.
+- `src/ui/subagents-settings.ts` ([#447]) — the precedent for an additive, flat, narrow-interface command extracted from the menu.
+- `src/ui/display.ts` — `getDisplayName(type, registry)`, `formatDuration(startedAt, completedAt)`, `getPromptModeLabel(type, registry)` for option labels.
+- `src/types.ts` — shared type barrel; already imports SDK types (`AgentSessionEvent`, `ThinkingLevel`).
+- `src/index.ts` — constructs `manager`, `registry`, and `settings`, and registers commands (`agents`, `subagents-settings`).
+  Sibling commands use flat hyphenated names with no `:` namespace.
+
+Pi SDK facts verified for this plan:
+
+- `parseSessionEntries`, `buildSessionContext`, `serializeConversation`, `SessionContext`, `FileEntry`, `SessionEntry`, and the per-entry components are all re-exported from the public `@earendil-works/pi-coding-agent` barrel; `loadEntriesFromFile` is **not** (confirmed in `dist/index.d.ts`).
+- `SessionContext.messages` is typed `AgentMessage[]` (`AgentMessage` from `@earendil-works/pi-agent-core`, which is **not** a direct dependency).
+  Derive the type from the barrel-exported `SessionContext` rather than adding a dependency: `type SessionMessage = SessionContext["messages"][number]`.
+- `serializeConversation(messages: Message[]): string` takes a **mutable** `Message[]` (from `@earendil-works/pi-ai`).
+  The accessor returns `readonly SessionMessage[]`, so the renderer must spread (`serializeConversation([...messages])`); the spread also resolves the readonly→mutable mismatch.
+  `AgentMessage` assignability to `Message` is verified in TDD step 2 (Pi itself feeds `buildSessionContext` output to serialization, so it is expected to hold); if it does not, narrow via a typed adapter at the renderer boundary.
+
+AGENTS.md / package constraints:
+
+- pi-subagents is a minimal core; surviving UI is an **in-core reactive consumer** with no inbound calls into the core.
+  The new `agentMessages` accessor is a read-only getter — it adds no inbound call and preserves the Phase 18 spine invariants ([#422]–[#425]).
+- Keep Pi SDK *coupling* out of pure helpers: the pure module uses only Pi's pure utility functions (`serializeConversation`) and an **injected** file/registry, so it stays unit-testable; the overlay component and command handler are SDK/TUI consumers (allowed to import SDK/TUI directly).
+- Use narrow interface types (not the concrete `Subagent` class) at the seam — concrete class types leak private fields into test mocks.
+
+## Design Overview
+
+Two new modules split pure logic from SDK/TUI wiring, plus a typed accessor on the record.
+
+### Typed `agentMessages` accessor (boundary narrowing)
+
+`src/types.ts` gains a derived alias (no new dependency):
+
+```typescript
+import type { SessionContext } from "@earendil-works/pi-coding-agent";
+
+/** One message in a child session's history, typed from Pi's SessionContext. */
+export type SessionMessage = SessionContext["messages"][number];
+```
+
+`SubagentSession` and `Subagent` each gain a typed read accessor alongside the existing widened `messages`:
+
+```typescript
+// SubagentSession
+get agentMessages(): readonly SessionMessage[] {
+  return this._session.messages;
+}
+
+// Subagent
+get agentMessages(): readonly SessionMessage[] {
+  return this.subagentSession?.agentMessages ?? [];
+}
+```
+
+`_session.messages` is already `AgentMessage[]` (= `SessionMessage[]`), so this is a typed view of the same data — no cast through `unknown`.
+The widened `messages` getter stays (other readers depend on it); `agentMessages` is the typed accessor the navigator uses.
+
+### `session-navigation.ts` — pure selection, source, and text rendering
+
+A pure module (SDK pure-utility imports only; no TUI, no `ExtensionAPI`).
+It declares narrow interfaces for the record fields it reads (ISP — not the concrete `Subagent`).
+
+```typescript
+/** The record fields the navigator reads to label and source a transcript. */
+export interface NavigableSubagent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+  readonly activeTools: ReadonlyMap<string, string>;
+  readonly responseText: string;
+  readonly agentMessages: readonly SessionMessage[];
+  isSessionReady(): boolean;
+  subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+}
+
+/** A navigable entry: the record plus its display label. */
+export interface NavigationEntry {
+  readonly record: NavigableSubagent;
+  readonly label: string;
+}
+
+/** Liveness-agnostic transcript source consumed by the renderer. */
+export interface TranscriptSource {
+  /** Current message history. */
+  getMessages(): readonly SessionMessage[];
+  /** Subscribe to live updates; returns an unsubscribe, or undefined for a static snapshot. */
+  subscribe(onChange: () => void): (() => void) | undefined;
+  /** Running-agent streaming state, or undefined when not streaming. */
+  streaming(): { activeTools: ReadonlyMap<string, string>; responseText: string } | undefined;
+}
+```
+
+Functions:
+
+- `listNavigableAgents(agents, registry): NavigationEntry[]` — keep records with `isSessionReady()`, map each to a label (`getDisplayName` · description · status · `formatDuration`).
+- `liveSource(record: NavigableSubagent): TranscriptSource` — `getMessages` → `record.agentMessages`; `subscribe` → `record.subscribeToUpdates`; `streaming` → `{ activeTools, responseText }` when `record.status === "running"`, else `undefined`.
+- `renderTranscriptLines(source, opts): string[]` — `serializeConversation([...source.getMessages()])` split on `\n`, then append a minimal streaming indicator (active tool names + a truncated `responseText` preview) when `source.streaming()` is defined; return `[]`-safe content for an empty history (`"(no messages yet)"`).
+
+`renderTranscriptLines` carries **no bespoke message formatting** — the transcript text is Pi's `serializeConversation` output; only the small streaming indicator is local (a few lines), and it does not import the doomed `message-formatters.ts`.
+
+### `session-navigator.ts` — overlay component + command handler
+
+SDK/TUI consumer.
+
+- `TranscriptOverlay` — a read-only scrollable `Component`: on construct, subscribe via `source.subscribe(() => tui.requestRender())`; each `render(width)` calls `renderTranscriptLines(source)` and paints a scrolling viewport with header/footer chrome and key handling (up/down, pageUp/pageDown, home/end, esc/q to close); `dispose()` unsubscribes.
+  Scroll math mirrors the bespoke viewer's behavior but the content comes from `renderTranscriptLines` (the bespoke viewer is deleted in Step 5; this is fresh code with its own tests, not a clone of doomed code).
+- `SessionNavigatorHandler` — `handle({ ui, agents, registry })`:
+
+```typescript
+async handle({ ui, agents, registry }: SessionNavigatorParams): Promise<void> {
+  const entries = listNavigableAgents(agents, registry);
+  if (entries.length === 0) { ui.notify("No subagent sessions to view.", "info"); return; }
+  const choice = await ui.select("Subagent sessions", entries.map(e => e.label));
+  const entry = entries.find(e => e.label === choice);
+  if (!entry) return;
+  const source = liveSource(entry.record);
+  await ui.custom<undefined>(
+    (tui, theme, _kb, done) => new TranscriptOverlay({ tui, theme, source, done, wrapText: wrapTextWithAnsi }),
+    { overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "70%" } },
+  );
+}
+```
+
+`SessionNavigatorParams` / `SessionNavigatorUI` are narrow interfaces declaring only `select`, `notify`, and `custom` — the methods the handler uses.
+
+### Registration call site (`index.ts`)
+
+```typescript
+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 });
+  },
+});
+```
+
+`manager.listAgents()` is called in the handler registration (the navigator never holds a manager reference — it receives the snapshot), keeping the navigator a pure reactive consumer with no inbound core call.
+
+### Consumer call-site sketch (Tell-Don't-Ask / LoD check)
+
+`liveSource` does not reach through the record to a stranger: it reads the record's own getters (`agentMessages`, `status`, `activeTools`, `responseText`) and delegates subscription to `record.subscribeToUpdates`.
+The renderer talks only to `TranscriptSource`, never to the record — so the component renderer follow-up swaps the source's internals (file vs live) and the renderer (text vs components) independently.
+No output arguments: nothing writes back into the record or the source.
+
+### Decomposition and follow-ups (Kent Beck: make the change easy, then make the easy change)
+
+This issue is the first releasable vertical slice.
+The `TranscriptSource` seam is the "change made easy" — it decouples *how messages are sourced* from *how they are rendered*, so each follow-up is a localized swap:
+
+1. **Renderer upgrade (named follow-up):** replace `renderTranscriptLines`/`TranscriptOverlay`'s `serializeConversation` text path with Pi's per-entry TUI components (`AssistantMessageComponent` / `ToolExecutionComponent` / …) behind the same `TranscriptSource`.
+   Selection and sourcing are untouched.
+2. **Evicted-agent source (named follow-up):** broaden the candidate set beyond `listAgents()` and add the **file-snapshot** `TranscriptSource` (`parseSessionEntries(readFileSync(outputFile))` → drop `SessionHeader` → `buildSessionContext(...).messages`) for agents no longer tracked.
+   This is where the dual-source design lands its second branch; the renderer is untouched.
+
+Recommendation: file these two as Phase 19 follow-up issues at ship time, and update the architecture roadmap's Step 4 description (which currently scopes dual-source + components as one step) to reflect the slice.
+
+### Design-review findings
+
+| Smell               | Location                         | Evidence                                                                                     | Result                                                                             |
+| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Wide interface      | `NavigableSubagent` (11 members) | `listNavigableAgents` reads 7 label fields; `liveSource` reads `agentMessages`/streaming/sub | Acceptable — two consumers split the surface; both are real reads, no unused field |
+| LoD violation       | `session-navigation.ts`          | `liveSource` reads record getters + delegates `subscribeToUpdates`; no `record.x.y.z` chains | None                                                                               |
+| Output argument     | `session-navigation.ts`          | source/renderer return values; never write back into the record                              | None                                                                               |
+| Concrete-class leak | seam interfaces                  | navigator depends on `NavigableSubagent`/`TranscriptSource`, not the concrete `Subagent`     | None — narrow interfaces                                                           |
+
+The new collaborators each own behavior (`liveSource` returns a stateful subscription view; `TranscriptOverlay` owns scroll state and the subscription lifecycle; `renderTranscriptLines` returns rendered lines) — not procedure-splitting.
+
+### Edge cases
+
+- Empty candidate set → `ui.notify("No subagent sessions to view.", "info")`, return.
+- Operator cancels `select` (`undefined`) or the label is stale → return, no overlay.
+- Empty message history (`agentMessages.length === 0`) → render `"(no messages yet)"`.
+- Running agent → streaming indicator appended; a `subscribeToUpdates` event triggers re-render with the latest `agentMessages` + streaming state.
+- Completed tracked agent → `streaming()` returns `undefined` (status not `running`); transcript is the final `agentMessages`, no indicator; `subscribe` still attaches harmlessly.
+- `subscribeToUpdates` returns `undefined` (no live session) → cannot happen for a `listAgents()`-gated, session-ready record, but the overlay tolerates `undefined` (no subscription, static render).
+- Very narrow terminal width → overlay returns `[]` below a minimum width, matching the bespoke viewer.
+
+## Module-Level Changes
+
+- **New** `src/ui/session-navigation.ts` — `NavigableSubagent`, `NavigationEntry`, `TranscriptSource` interfaces; `listNavigableAgents`, `liveSource`, `renderTranscriptLines` functions.
+- **New** `src/ui/session-navigator.ts` — `TranscriptOverlay` component, `SessionNavigatorHandler` class, `SessionNavigatorParams` / `SessionNavigatorUI` narrow interfaces.
+- **Changed** `src/types.ts` — add `export type SessionMessage = SessionContext["messages"][number]` and the `SessionContext` type import.
+- **Changed** `src/lifecycle/subagent-session.ts` — add `get agentMessages(): readonly SessionMessage[]`.
+- **Changed** `src/lifecycle/subagent.ts` — add `get agentMessages(): readonly SessionMessage[]`.
+- **Changed** `src/index.ts` — import `SessionNavigatorHandler`, construct it, register the `subagent-sessions` command (sole call site of the new export).
+- **New** `test/ui/session-navigation.test.ts` — unit tests for `listNavigableAgents`, `liveSource`, `renderTranscriptLines`.
+- **New** `test/ui/session-navigator.test.ts` — unit tests for `TranscriptOverlay` render/scroll/key handling and `SessionNavigatorHandler` select→custom wiring.
+- **Changed** `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/subagent.test.ts` — add `agentMessages` accessor tests.
+
+No removed or renamed exports — grep for removed symbols is not applicable (pure addition).
+
+Doc / skill grep results:
+
+- `docs/architecture/architecture.md` Step 4 currently describes the **full** dual-source + components scope and names `src/ui/session-navigator.ts` and the typed accessor.
+  This issue narrows that scope (live-source + text renderer).
+  Update the Step 4 description to reflect the slice and the two named follow-ups — defer the status-line flip and the rescoping edit to ship time (matches the [#447] precedent), or fold a short rescoping note in this issue if preferred.
+- `.pi/skills/package-pi-subagents/SKILL.md` lists the UI domain by count (`ui/` = 10 modules); this adds two files (→ 12).
+  The table is a coarse summary not maintained per-file — leave for a later Phase 19 doc-sync unless the operator asks otherwise.
+- No `src/`/`test/` references to a removed symbol (nothing is removed); the bespoke `ConversationViewer` and `message-formatters.ts` are untouched and keep their tests.
+
+## Test Impact Analysis
+
+1. **New tests enabled.**
+   `listNavigableAgents`, `liveSource`, and `renderTranscriptLines` are pure and unit-testable against narrow `NavigableSubagent` / `TranscriptSource` stubs — no full `Subagent`, `TUI`, or `AgentSession` construction.
+   This is strictly more focused than `conversation-viewer.test.ts`, which builds a full record + TUI to exercise transcript rendering.
+   The `agentMessages` accessor gets direct unit tests on both `SubagentSession` and `Subagent`.
+2. **Existing tests that become redundant.**
+   None in this issue.
+   `conversation-viewer.test.ts` and `message-formatters.test.ts` still exercise the live, still-shipping bespoke overlay; they are removed only when Step 5 ([#442]) deletes those modules.
+3. **Existing tests that must stay as-is.**
+   All bespoke-viewer and menu tests stay unchanged — this issue does not touch `agent-menu.ts`, `conversation-viewer.ts`, or `message-formatters.ts`.
+
+## Invariants at risk
+
+This issue adds two modules, one accessor, and one command registration; it does not touch the Phase 18 spine that prior steps refactored.
+The relevant `Outcome:` invariants and their pins:
+
+- **[#422] — runtime holds zero UI state.**
+  The navigator holds its own overlay/scroll state; nothing is pushed onto the runtime.
+  Pinned by `runtime.test.ts` / the service spine tests; unchanged.
+- **[#423] — widget/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 `agentMessages` accessor is a read-only getter.
+  No inbound call into the core.
+  A focused navigator test asserts the handler reads only through its injected `agents` + record getters.
+- **[#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 (`test/service`, `test/observation`); unchanged.
+
+A later phase step (the renderer / evicted-source follow-ups) must not regress these with a green suite — the navigator-reads-only test pins #423 for the seam.
+
+## TDD Order
+
+1. **Red→Green: typed `agentMessages` accessor.**
+   Test surface: `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/subagent.test.ts`.
+   Tests: `SubagentSession.agentMessages` returns the wrapped session's typed messages; `Subagent.agentMessages` delegates to the session and returns `[]` when no session.
+   Implementation: add `SessionMessage` to `src/types.ts` (with the `SessionContext` import); add the two getters.
+   Run `pnpm run check` (verifies `SessionContext["messages"][number]` resolves and `_session.messages` is assignable).
+   Commit: `feat: add typed agentMessages accessor on subagent record (#445)`.
+2. **Red→Green: pure selection, live source, and text rendering.**
+   Test surface: `test/ui/session-navigation.test.ts`.
+   Tests:
+   - `listNavigableAgents` keeps only `isSessionReady()` records and builds the expected labels (name · description · status · duration); empty input → `[]`.
+   - `liveSource.getMessages` returns the record's `agentMessages`; `subscribe` delegates to `subscribeToUpdates`; `streaming()` returns state only when `status === "running"`, else `undefined`.
+   - `renderTranscriptLines` returns `serializeConversation` output split into lines; appends the streaming indicator when streaming; returns the empty-history placeholder for `[]`.
+   Implementation: create `src/ui/session-navigation.ts` with the three interfaces and three functions.
+   Verify `AgentMessage`→`Message` assignability for `serializeConversation([...messages])` here; if it fails, add a typed adapter at the boundary.
+   Commit: `feat: add subagent session selection and live transcript source (#445)`.
+3. **Red→Green: read-only overlay component + `/subagent-sessions` command.**
+   Test surface: `test/ui/session-navigator.test.ts`.
+   Tests:
+   - `TranscriptOverlay.render(width)` paints the current `renderTranscriptLines` content with chrome; scroll keys move the viewport; `esc`/`q` calls `done`; `dispose()` unsubscribes; a `subscribe` callback triggers `tui.requestRender`.
+   - `SessionNavigatorHandler.handle`: empty entries → `notify` + no `custom`; cancel at `select` → no `custom`; a valid pick → `custom` opened with a `liveSource` for the chosen record (assert via a `makeMenuUI`-style stub).
+   Implementation: create `src/ui/session-navigator.ts`; register the command in `src/index.ts` (sole call site).
+   Run `pnpm run check` immediately (the registration is the only consumer of the new handler export — both must compile together).
+   Run `pnpm fallow dead-code` before pushing (confirms no unreachable file-source branch slipped in).
+   Commit: `feat: add /subagent-sessions read-only navigation command (#445)`.
+
+Steps 2 and 3 may be folded if preferred, but keeping the pure logic (with its stub-only tests) separate from the TUI/SDK wiring keeps each commit self-contained.
+
+## Risks and Mitigations
+
+- **Risk: `AgentMessage` is not assignable to `serializeConversation`'s `Message[]`.**
+  Mitigation: verify in TDD step 2 (`pnpm run check`); Pi feeds `buildSessionContext` output to serialization, so it is expected to hold.
+  If not, add a typed adapter (`toMessages(messages): Message[]`) at the renderer boundary — the seam isolates the fix to `renderTranscriptLines`.
+- **Risk: implementing the file-snapshot branch creates dead code (no caller under `listAgents()`-only) and fails `fallow dead-code`.**
+  Mitigation: this issue ships the **live source only** behind the seam; the file source is a named follow-up.
+  `pnpm fallow dead-code` runs before push.
+- **Risk: importing the doomed `message-formatters.ts` / `conversation-viewer.ts` couples the navigator to code Step 5 deletes.**
+  Mitigation: the navigator imports neither; the streaming indicator is a small local helper and the transcript text is Pi's `serializeConversation`.
+- **Risk: the new overlay duplicates the bespoke viewer's scroll chrome (apparent duplication).**
+  Mitigation: the bespoke viewer is deleted in Step 5, so there is no lasting duplication; the new overlay is fresh code with its own tests and a different content source (`renderTranscriptLines` vs bespoke `formatMessage`).
+- **Risk: command-name choice.**
+  Mitigation: `subagent-sessions` follows the flat-hyphenated sibling convention (`agents`, `subagents-settings`); confirm at ship time (see Open Questions).
+- **Risk: the architecture roadmap's Step 4 description diverges from the sliced scope.**
+  Mitigation: update the Step 4 description and file the two follow-ups at ship time.
+
+## Open Questions
+
+- **Command name** — `subagent-sessions` is proposed (flat, hyphenated, sibling-consistent).
+  Alternatives: `subagent-transcript`, `view-subagent`, `subagents-view`.
+  Confirm at ship time; the command is not yet shipped, so it is cheaply renamable.
+- **Whether to rescope the architecture roadmap's Step 4 entry in this issue or defer** to a Phase 19 doc-sync — decide at ship time (matches the [#447] precedent).
+- **Whether to file the two named follow-ups (renderer upgrade, evicted-agent source) now or after this slice lands** — recommended at ship time so the roadmap stays accurate.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#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
+[#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

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,57 @@
+---
+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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "17.2.0",
+  "version": "17.3.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 });
+    },
+  });
 }

package/src/lifecycle/subagent-session.ts

@@ -19,6 +19,7 @@ import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
 import { getSessionContextPercent, type SessionStatsLike } from "#src/lifecycle/usage";
 import { extractText } from "#src/session/context";
 import { getAgentConversation } from "#src/session/conversation";
+import type { SessionMessage } from "#src/types";
 
 /** Outcome of one turn loop. */
 export interface TurnLoopResult {
@@ -178,6 +179,11 @@ export class SubagentSession {
     return this._session.messages as readonly unknown[];
   }
 
+  /** The session's message history, typed for Pi's session-rendering machinery. */
+  get agentMessages(): readonly SessionMessage[] {
+    return this._session.messages;
+  }
+
   /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
   dispose(): void {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations

package/src/lifecycle/subagent.ts

@@ -20,7 +20,7 @@ import { WorkspaceBracket } from "#src/lifecycle/workspace-bracket";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeSubagentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
-import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SessionMessage, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Per-subagent lifecycle observer — created by SubagentManager for each spawn. */
 export interface SubagentLifecycleObserver {
@@ -162,6 +162,11 @@ export class Subagent {
 		return this.subagentSession?.messages ?? [];
 	}
 
+	/** The session's message history typed for Pi's session-rendering machinery, or empty if no session. */
+	get agentMessages(): readonly SessionMessage[] {
+		return this.subagentSession?.agentMessages ?? [];
+	}
+
 	constructor(init: SubagentInit) {
 		// Identity
 		this.id = init.id;

package/src/types.ts

@@ -3,13 +3,22 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
-import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent, SessionContext as SdkSessionContext } from "@earendil-works/pi-coding-agent";
 import type { ModelRegistry } from "#src/session/model-resolver";
 
 
 export { Subagent } from "#src/lifecycle/subagent";
 export type { AgentSessionEvent, ThinkingLevel };
 
+/**
+ * One message in a child session's history, typed from Pi's `SessionContext`.
+ *
+ * Derived from the barrel-exported `SessionContext` (whose `messages` field is
+ * `AgentMessage[]`) so the package needs no direct dependency on
+ * `@earendil-works/pi-agent-core`, which is not re-exported from the public barrel.
+ */
+export type SessionMessage = SdkSessionContext["messages"][number];
+
 /**
  * Narrow session interface for event subscription.
  * Used by record-observer — only the subscribe method is needed.

package/src/ui/session-navigation.ts

@@ -0,0 +1,114 @@
+/**
+ * session-navigation.ts — Pure selection and transcript-sourcing for native session navigation.
+ *
+ * Splits the unit-testable core of the `/subagent-sessions` command from its TUI
+ * wiring (`session-navigator.ts`): which subagents are navigable, how a picked
+ * agent's transcript is sourced (live, in this slice), and how the transcript
+ * renders to plain text via Pi's own `serializeConversation`.
+ *
+ * The `TranscriptSource` seam decouples *how messages are sourced* (live record
+ * here; a file snapshot in a follow-up) from *how they render* (text here; Pi's
+ * per-entry components in a follow-up). The renderer talks only to this seam.
+ */
+
+import { serializeConversation } from "@earendil-works/pi-coding-agent";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { SubagentStatus } from "#src/lifecycle/subagent-state";
+import type { AgentSessionEvent, SessionMessage, SubagentType } from "#src/types";
+import { describeActivity, formatDuration, getDisplayName } from "#src/ui/display";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The record fields the navigator reads to label and live-source a transcript. */
+export interface NavigableSubagent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+  readonly activeTools: ReadonlyMap<string, string>;
+  readonly responseText: string;
+  readonly agentMessages: readonly SessionMessage[];
+  isSessionReady(): boolean;
+  subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+}
+
+/** A navigable entry: a record plus the label shown in the picker. */
+export interface NavigationEntry {
+  readonly record: NavigableSubagent;
+  readonly label: string;
+}
+
+/** Running-agent streaming state, surfaced by a live source. */
+export interface StreamingState {
+  readonly activeTools: ReadonlyMap<string, string>;
+  readonly responseText: string;
+}
+
+/** Liveness-agnostic transcript source consumed by the renderer. */
+export interface TranscriptSource {
+  /** Current message history. */
+  getMessages(): readonly SessionMessage[];
+  /** Subscribe to changes; returns an unsubscribe, or undefined for a static snapshot. */
+  subscribe(onChange: () => void): (() => void) | undefined;
+  /** Running-agent streaming state, or undefined when not streaming. */
+  streaming(): StreamingState | undefined;
+}
+
+/** Filter the agents to those with a viewable session and label each for the picker. */
+export function listNavigableAgents(
+  agents: readonly NavigableSubagent[],
+  registry: AgentConfigLookup,
+): NavigationEntry[] {
+  return agents
+    .filter((record) => record.isSessionReady())
+    .map((record) => ({ record, label: buildLabel(record, registry) }));
+}
+
+/** Source a transcript live from an in-memory record (this slice's only source). */
+export function liveSource(record: NavigableSubagent): TranscriptSource {
+  return {
+    getMessages: () => record.agentMessages,
+    subscribe: (onChange) => record.subscribeToUpdates(() => onChange()),
+    streaming: () =>
+      record.status === "running"
+        ? { activeTools: record.activeTools, responseText: record.responseText }
+        : undefined,
+  };
+}
+
+/** Render a source's transcript to plain text lines via Pi's `serializeConversation`. */
+export function renderTranscriptLines(source: TranscriptSource): string[] {
+  const messages = source.getMessages();
+  const lines =
+    messages.length === 0 ? ["(no messages yet)"] : serializeConversation(toMessages(messages)).split("\n");
+
+  const streaming = source.streaming();
+  if (streaming) {
+    lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
+  }
+  return lines;
+}
+
+/**
+ * Bridge the session's `AgentMessage[]` to `serializeConversation`'s `Message[]`.
+ *
+ * `AgentMessage` is a superset of `Message` (it adds session-display variants such
+ * as `BashExecutionMessage`); `serializeConversation` renders the shared shape and
+ * best-effort text for the rest. `Message` is not re-exported from the public
+ * `@earendil-works/pi-ai` barrel, so the parameter type is referenced via the
+ * function signature rather than imported by name.
+ */
+function toMessages(
+  messages: readonly SessionMessage[],
+): Parameters<typeof serializeConversation>[0] {
+  return messages as unknown as Parameters<typeof serializeConversation>[0];
+}
+
+function buildLabel(record: NavigableSubagent, registry: AgentConfigLookup): string {
+  const name = getDisplayName(record.type, registry);
+  const duration = formatDuration(record.startedAt, record.completedAt);
+  return `${name} (${record.description}) · ${record.toolUses} tools · ${record.status} · ${duration}`;
+}

package/src/ui/session-navigator.ts

@@ -0,0 +1,237 @@
+/**
+ * session-navigator.ts — The `/subagent-sessions` command: pick a subagent and
+ * read its transcript through Pi's own session-rendering text.
+ *
+ * SDK/TUI consumer half of native session navigation. The unit-testable core
+ * (selection, sourcing, text rendering) lives in `session-navigation.ts`; this
+ * module wires that core to the command picker and a read-only scrollable overlay.
+ *
+ * The overlay is strictly read-only — steering stays in the `steer_subagent` tool
+ * and the widget. It consumes a `TranscriptSource`, so the renderer-upgrade and
+ * evicted-agent-source follow-ups swap the source/renderer without touching it.
+ */
+
+import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { Theme } from "#src/ui/display";
+import {
+  listNavigableAgents,
+  liveSource,
+  type NavigableSubagent,
+  renderTranscriptLines,
+  type TranscriptSource,
+} from "#src/ui/session-navigation";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Chrome lines: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES = 6;
+const MIN_VIEWPORT = 3;
+const VIEWPORT_HEIGHT_PCT = 70;
+
+/** Component factory shape Pi's `ui.custom` invokes to mount an overlay. */
+export type OverlayComponentFactory<R> = (
+  tui: TUI,
+  theme: Theme,
+  keybindings: unknown,
+  done: (result: R) => void,
+) => Component;
+
+/** Narrow UI interface — only the `ctx.ui` methods the navigator calls. */
+export interface SessionNavigatorUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  custom<R>(component: OverlayComponentFactory<R>, options?: unknown): Promise<R>;
+}
+
+/** Parameters for one `/subagent-sessions` invocation. */
+export interface SessionNavigatorParams {
+  ui: SessionNavigatorUI;
+  agents: readonly NavigableSubagent[];
+  registry: AgentConfigLookup;
+}
+
+/** Options for the read-only transcript overlay. */
+export interface TranscriptOverlayOptions {
+  tui: TUI;
+  theme: Theme;
+  source: TranscriptSource;
+  done: (result: undefined) => void;
+  wrapText: (text: string, width: number) => string[];
+}
+
+/**
+ * Handler for the `/subagent-sessions` slash command.
+ *
+ * Lists navigable subagents, lets the operator pick one, and opens its transcript
+ * read-only. Receives the agent snapshot (`manager.listAgents()`) rather than the
+ * manager, so it stays a reactive consumer with no inbound call into the core.
+ */
+export class SessionNavigatorHandler {
+  async handle({ ui, agents, registry }: SessionNavigatorParams): Promise<void> {
+    const entries = listNavigableAgents(agents, registry);
+    if (entries.length === 0) {
+      ui.notify("No subagent sessions to view.", "info");
+      return;
+    }
+
+    const choice = await ui.select(
+      "Subagent sessions",
+      entries.map((entry) => entry.label),
+    );
+    const entry = entries.find((candidate) => candidate.label === choice);
+    if (!entry) return;
+
+    const source = liveSource(entry.record);
+    await ui.custom<undefined>(
+      (tui, theme, _keybindings, done) =>
+        new TranscriptOverlay({ tui, theme, source, done, wrapText: wrapTextWithAnsi }),
+      {
+        overlay: true,
+        overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
+      },
+    );
+  }
+}
+
+/**
+ * Read-only scrollable transcript overlay.
+ *
+ * Re-renders on every source update (live agents); the transcript text is Pi's
+ * `serializeConversation` output from `renderTranscriptLines` — this class owns
+ * only scroll state and chrome, no message formatting.
+ */
+export class TranscriptOverlay implements Component {
+  private scrollOffset = 0;
+  private autoScroll = true;
+  private unsubscribe: (() => void) | undefined;
+  private closed = false;
+
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly source: TranscriptSource;
+  private readonly done: (result: undefined) => void;
+  private readonly wrapText: (text: string, width: number) => string[];
+
+  constructor({ tui, theme, source, done, wrapText }: TranscriptOverlayOptions) {
+    this.tui = tui;
+    this.theme = theme;
+    this.source = source;
+    this.done = done;
+    this.wrapText = wrapText;
+    this.unsubscribe = source.subscribe(() => {
+      if (this.closed) return;
+      this.tui.requestRender();
+    });
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.closed = true;
+      this.done(undefined);
+      return;
+    }
+
+    const totalLines = this.buildContentLines(this.innerWidth()).length;
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, totalLines - viewportHeight);
+
+    if (matchesKey(data, "up") || matchesKey(data, "k")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "down") || matchesKey(data, "j")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
+      this.autoScroll = false;
+    } else if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "home")) {
+      this.scrollOffset = 0;
+      this.autoScroll = false;
+    } else if (matchesKey(data, "end")) {
+      this.scrollOffset = maxScroll;
+      this.autoScroll = true;
+    }
+  }
+
+  render(width: number): string[] {
+    if (width < 6) return [];
+    const th = this.theme;
+    const innerW = width - 4;
+    const lines: string[] = [];
+
+    const pad = (s: string, len: number): string => s + " ".repeat(Math.max(0, len - visibleWidth(s)));
+    const row = (content: string): string =>
+      th.fg("border", "│") + " " + truncateToWidth(pad(content, innerW), innerW) + " " + th.fg("border", "│");
+    const hrTop = th.fg("border", `╭${"─".repeat(width - 2)}╮`);
+    const hrBot = th.fg("border", `╰${"─".repeat(width - 2)}╯`);
+    const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+
+    lines.push(hrTop);
+    lines.push(row(th.bold("Subagent session")));
+    lines.push(hrMid);
+
+    const contentLines = this.buildContentLines(innerW);
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, contentLines.length - viewportHeight);
+    if (this.autoScroll) this.scrollOffset = maxScroll;
+    const visibleStart = Math.min(this.scrollOffset, maxScroll);
+    const visible = contentLines.slice(visibleStart, visibleStart + viewportHeight);
+    for (let i = 0; i < viewportHeight; i++) lines.push(row(visible[i] ?? ""));
+
+    lines.push(hrMid);
+    const scrollPct =
+      contentLines.length <= viewportHeight
+        ? "100%"
+        : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
+    const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
+    const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn · Esc close");
+    const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
+    lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
+    lines.push(hrBot);
+
+    return lines;
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  invalidate(): void {
+    /* no cached state to clear */
+  }
+
+  // fallow-ignore-next-line unused-class-member
+  dispose(): void {
+    this.closed = true;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  // ---- Private ----
+
+  private innerWidth(): number {
+    return Math.max(0, this.tui.terminal.columns - 4);
+  }
+
+  private viewportHeight(): number {
+    const maxRows = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
+    return Math.max(MIN_VIEWPORT, maxRows - CHROME_LINES);
+  }
+
+  private buildContentLines(innerW: number): string[] {
+    if (innerW <= 0) return [];
+    const wrapped: string[] = [];
+    for (const line of renderTranscriptLines(this.source)) {
+      if (line === "") {
+        wrapped.push("");
+        continue;
+      }
+      wrapped.push(...this.wrapText(line, innerW));
+    }
+    return wrapped.map((l) => truncateToWidth(l, innerW));
+  }
+}