@gotgenes/pi-subagents 17.1.0 → 17.3.0

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

@@ -0,0 +1,81 @@
+---
+issue: 444
+issue_title: "pi-subagents: shrink the agent widget to background runs only"
+---
+
+# Retro: #444 — pi-subagents: shrink the agent widget to background runs only
+
+## Stage: Planning (2026-06-20T18:47:05Z)
+
+### Session summary
+
+Produced a numbered implementation plan for Phase 19 Step 3: shrink `AgentWidget` to background agents only by funneling both `manager.listAgents()` call sites (`update()` and `renderWidget()`) through a single private `listBackgroundAgents()` accessor that applies `record.invocation?.runInBackground === true` once at the source.
+Confirmed the change is single-package (`pi-subagents`), non-breaking, and `Release: independent` per the architecture roadmap.
+
+### Observations
+
+- Issue author is the operator (`gotgenes`) and the proposed change is unambiguous, so the `ask-user` gate was skipped.
+  The design is a legitimate improvement (removes the two-site duplication and fixes the latent inconsistency), not procedure-splitting.
+- `widget-renderer.ts` needs **no** code change — it has no foreground-specific path; filtering at the data source in `agent-widget.ts` is sufficient.
+  Listed in Module-Level Changes only to record the verification.
+- Key risk is mass test breakage: the existing `update()`-driven fixtures (two `makeWidget` helpers + the projection test's `createTestSubagent`) would all be filtered out once the predicate lands.
+  Mitigated with a tidy-first TDD step 1 that adds `invocation: { runInBackground: true }` to fixtures while the filter does not yet exist (inert), so step 2 only adds new tests.
+- `assembleWidgetState` pure-function tests are unaffected — they call the function directly with `AgentSummary[]`, bypassing the accessor.
+- Verified `clearWidget`'s stale-purge has no regression: foreground agents are never seeded into `finishedTurnAge`, so purging against the background-only list is correct.
+- Doc grep surfaced one stale prose line (`README.md:64` "showing all active agents"); SKILL.md and `comparison-with-upstream.md` references remain accurate.
+- Deferred (Open Question): relabeling the widget heading `Agents` → `Background agents` — out of scope for this issue.
+
+## Stage: Implementation — TDD (2026-06-20T19:47:34Z)
+
+### Session summary
+
+Executed all three planned TDD cycles plus one reviewer-driven cleanup: (1) `test:` migrated the `agent-widget.test.ts` fixtures to a background invocation, (2) `feat:` added the private `listBackgroundAgents()` accessor and routed both `update()` and `renderWidget()` through it, (3) `docs:` updated `README.md` and marked roadmap Step 3 ✅.
+Test count went from 24 to 26 in `agent-widget.test.ts` (two new background-only filtering tests); full pi-subagents suite is 1064 passing.
+
+### Observations
+
+- The tidy-first fixture migration worked exactly as planned — adding `invocation: { runInBackground: true }` was inert (suite stayed green) until the filter landed, so step 2 was a pure addition with no fixture churn.
+- New-test fixtures default the shared `makeWidget` helper to background invocation via `{ invocation: { runInBackground: true }, ...a }`, letting per-agent `invocation` override for the mixed/foreground cases in the new `describe` block.
+- `widget-renderer.ts` needed no change, as the plan predicted — the filter at the single `listBackgroundAgents()` funnel is sufficient.
+- Pre-completion reviewer: PASS.
+  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/docs/retro/0447-extract-subagents-settings-command.md

@@ -44,3 +44,48 @@ Full suite, `tsc`, root lint, and `fallow dead-code` all green.
 - Pre-completion reviewer: WARN.
   Reviewer warnings: one non-blocking finding — `.pi/skills/package-pi-subagents/SKILL.md` records `ui/` as 10 modules (now 11); the plan intentionally deferred this coarse-summary update to a later Phase 19 doc-sync.
   No FAILs; all deterministic checks PASS, verbatim-lift fidelity and ISP of both narrow interfaces confirmed.
+
+## Stage: Final Retrospective (2026-06-20T18:36:58Z)
+
+### Session summary
+
+Shipped Phase 19 Step 2 (#447) end to end across planning, TDD, and ship stages, releasing `pi-subagents` `17.1.0`.
+The one off-script event was a user-reported Mermaid syntax error in `architecture.md`, which I localized by extracting all six diagram blocks and running `mmdc` on each, then fixed by quoting the offending flowchart node labels.
+Execution was otherwise clean: two green TDD cycles (+11 tests), a WARN pre-completion review (one intentionally-deferred doc finding), and a correct `UNSTABLE`/`GITHUB_TOKEN` release-merge fallback.
+
+### Observations
+
+#### What went well
+
+- Localizing the Mermaid error with the diagram name wrong: the user called it the "State dependency diagram" but the broken block was the "Step dependency diagram" flowchart.
+  Rather than guess from the ambiguous name (I had glanced at the `stateDiagram-v2` lifecycle and the `classDiagram` first), I scripted extraction of all six `mermaid` fences and ran `mmdc` on each — block 6 failed with `got 'PS'`, pinpointing the exact line.
+  Brute-force validation beat name-matching.
+- The release-merge fallback worked exactly as the ship prompt describes: `release_pr_merge` refused on `merge_state: UNSTABLE`, the status-check rollup was empty (the `GITHUB_TOKEN` no-checks case), and `gh pr merge 450 --rebase` + `git pull --ff-only` landed `17.1.0` linearly.
+
+#### What caused friction (agent side)
+
+- `missing-context` (prior session) — the broken diagram was authored in `74e2374f docs: mark Phase 19 Step 1 spike complete (#446)`: a flowchart node label `S1[✅ Step 1 - Spike (#446)]` with unquoted parentheses, which Mermaid parses as a nested round-node shape (`Expecting ... got 'PS'`).
+  It was committed without an `mmdc` pass and slipped through `pnpm run lint` (rumdl validates markdown, not Mermaid semantics) and CI.
+  Impact: surfaced two sessions later as a user-caught defect; one extra `docs:` fix commit (`90ca6e2d`) this session.
+  Root cause is a coverage gap: the `mermaid` skill's pitfall list does not mention parentheses/shape-delimiter characters in node labels, so the exact failure mode was undocumented.
+
+#### What caused friction (user side)
+
+- None material.
+  The diagram-name mismatch ("State" vs "Step" dependency diagram) added one or two orienting reads but did not cause rework — the all-blocks `mmdc` sweep absorbed the ambiguity.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer` on `anthropic/claude-sonnet-4-6` (judgment-heavy review work); appropriate match, no over/under-powered mismatch.
+- **Escalation-delay tracking** — the Mermaid detour resolved in ~5 progress-making tool calls (extract blocks → `mmdc` each → read error → quote labels → re-validate); not a rabbit-hole, no subagent escalation warranted.
+- **Unused-tool detection** — none; `mmdc` (the correct validator) was used directly.
+- **Feedback-loop gap analysis** — verification ran incrementally throughout TDD (per-file `vitest` in each red/green, `pnpm run check` right after the interface-bearing wiring step, full suite + root lint + `fallow dead-code` at the end), not just terminally.
+
+### Changes made
+
+1. `.pi/skills/mermaid/SKILL.md` — added a "Parentheses and special characters in node labels" pitfall (with the `S1[✅ Step 1 - Spike (#446)]` WRONG/RIGHT example from this session) covering the `(`/`[`/`{`/`:` shape-delimiter trap that produced the `got 'PS'` parse error.
+
+### Follow-up (not implemented — suggest a GitHub issue + `/plan-issue`)
+
+1. **CI Mermaid-validation gate** — run `mmdc` over every `mermaid` fence as part of `pnpm run lint` or a pre-commit hook, so a broken diagram (like `74e2374f`'s unquoted-parens node) fails at author time instead of surviving to a user-caught defect.
+   Out of retro scope (infra, touches `package.json`/lint config/hooks); record as its own issue.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "17.1.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