@gotgenes/pi-subagents 17.0.0 → 17.0.1

package/docs/architecture/history/phase-18-reconsider-ui.md

@@ -0,0 +1,166 @@
+# Phase 18: Reconsider UI from first principles
+
+## Summary
+
+Phase 18 disentangled the activity tier from the core and recorded a first-principles decision about the UI's direction and distribution.
+Steps 1–5 (the spine) removed the activity-tier entanglement: run state was consolidated onto `SubagentState`, `AgentActivityTracker` and `ui-observer` were deleted, and the widget was made a pure reactive consumer of lifecycle events.
+Steps 6–7 delivered independent hygiene: the public event contract was reconciled (breaking) and residual test clone families were consolidated.
+Step 8 captured the outcome as [ADR-0004] — a per-component UI decision recorded to gateway Phase 19.
+
+All eight steps are closed: [#420], [#421], [#422], [#423], [#424], [#425], [#426], [#427].
+
+## Health metrics
+
+Baseline at the start of Phase 18 (end of Phase 17):
+
+| Metric                                   | Phase 18 start                                                     | Phase 18 end                          |
+| ---------------------------------------- | ------------------------------------------------------------------ | ------------------------------------- |
+| Health score                             | 78/100 (B)                                                         | 78/100 (B)                            |
+| Source LOC                               | 7,751 (62 files)                                                   | 7,650 (61 files)                      |
+| Dead code                                | 0 files, 0 exports                                                 | 0 files, 0 exports                    |
+| Maintainability index                    | 90.9 (good)                                                        | 90.9 (good)                           |
+| Avg cyclomatic complexity                | 1.4                                                                | 1.4                                   |
+| P90 cyclomatic complexity                | 2                                                                  | 2                                     |
+| Fallow refactoring targets               | 0                                                                  | 0                                     |
+| Production duplication                   | 11 lines (1 internal clone group in `agent-config-editor.ts`)      | 11 lines (1 internal clone group)     |
+| Test duplication                         | 28 clone groups, 503 lines                                         | 14 clone groups (below <15 target)    |
+| Tests                                    | 1,031 passing                                                      | 1,047 passing                         |
+| Activity-tier modules slated for removal | `ui-observer.ts` (61) + `agent-activity-tracker.ts` (84) = 145 LOC | Deleted in Step 3                     |
+
+## Findings
+
+Six findings told one story — the activity tier had metastasized out of the UI and into the core.
+
+1. **UI state lives on the core runtime.**
+   `SubagentRuntime.agentActivity: Map<string, AgentActivityTracker>` puts a UI streaming-state map on the core composition root.
+   `SubagentRuntime` owns session-scoped lifecycle state; `AgentActivityTracker` (active tools, response text, turn count) is pure rendering state the core never reads.
+   Category C (coupling).
+2. **Core spawn tools wire UI streaming.**
+   `foreground-runner.ts` and `background-spawner.ts` construct `AgentActivityTracker`, call `subscribeUIObserver` (a second session subscription parallel to the core's own `record-observer`), call `setSession`, and populate or delete the activity map and drive the widget (`ensureTimer`, `update`, `markFinished`).
+   Their own doc comments list "AgentActivityTracker creation, UI observer subscription" as responsibilities.
+   Category C (mixed responsibility, parameter relay).
+3. **The LLM-facing tool depends on the widget.**
+   `AgentTool` takes a 4-method `widget` dependency plus `runtime.agentActivity` and calls `this.widget.setUICtx(ctx.ui)`.
+   Every `AgentTool` unit test must stub the widget and the activity map (`createToolDeps`), although the tool's real concern is dispatch — testability friction marking a domain seam.
+   Category C/D.
+4. **Two parallel observers split the run-metric domain.**
+   Each child session gets two subscriptions: `record-observer` accumulates `SubagentState` (tool uses, usage, compactions) and `ui-observer` accumulates `AgentActivityTracker` (active tools, response text, turn count).
+   `turnCount` is a genuine run metric that lives only in the UI tracker, so `notification.ts` and the foreground result text reach into the tracker to recover it.
+   Category C (anemic split, duplication).
+5. **A core observation concern reaches into UI state.**
+   `NotificationManager` holds the activity map and reads `turnCount`/`maxTurns` from it to build notification details, and deletes entries from it.
+   Category C (Law of Demeter).
+6. **The public event contract is both vacant and incomplete.**
+   `SUBAGENT_EVENTS.ACTIVITY = "subagents:activity"` is declared in the service surface and the lifecycle-events table but is never emitted anywhere — a vacant hook the "no vacant hooks" rule forbids.
+   Meanwhile three emitted channels (`subagents:failed`, `subagents:compacted`, `subagents:created`) are absent from the constant map.
+   Category A/E.
+
+## Steps
+
+The spine (Steps 1–5) removes the activity-tier entanglement, leaving the core a pure orchestrator whose run state lives in one place and whose UI is a reactive consumer of broadcast events plus discrete queries.
+Steps 6–7 are independent hygiene.
+Step 8 is the user-driven UI reconsideration the disentangled core finally makes possible — a decision about the UI's distribution once it is substitutable, not optional.
+
+The deeper target in the [first-principles refinement] — metrics as a pure observer projection rather than mutable fields — is deliberately **not** forced here.
+Folding the live activity onto the record (the single owner of run state, consistent with Phase 17's `SubagentState`) removes the duplication without inventing the asynchronous-observation seam the `improvement-discovery` skill warns is essential, not structural.
+
+1. **✅ Fold run metrics and live activity onto the core record (pure addition) — complete (v16.5.0).**
+   ([#420]) Target: `lifecycle/subagent-state.ts`, `observation/record-observer.ts`, `lifecycle/subagent.ts`.
+   Extend the single owned run-state value object with `turnCount`, active tools, and response text; have the already-subscribed `record-observer` handle `turn_end`, `tool_execution_start`, `message_start`, `message_update`; expose read-only `turnCount`/`maxTurns`/`activeTools`/`responseText` getters on `Subagent`.
+   `AgentActivityTracker` still exists; nothing reads the new getters yet (tidy-first).
+   Smell: Category C. Outcome: `Subagent` is the single home for all run state; getters available for migration.
+   Landed: `SubagentState` owns `turnCount`/`activeTools`/`responseText` plus their transition methods; `record-observer` populates them on a single subscription; `Subagent` exposes the four read-only getters; +27 tests (1031 → 1058).
+2. **✅ Migrate every activity reader to the record getters — complete.**
+   ([#421]) Target: `ui/widget-renderer.ts`, `ui/conversation-viewer.ts`, `ui/agent-menu.ts`, `tools/foreground-runner.ts`, `observation/notification.ts`.
+   Switch each reader from `AgentActivityTracker` to the record getters added in Step 1 (widget-renderer reads activity off `listAgents()`; viewer/menu drop the `activity` param; notification reads `turnCount`/`maxTurns` off the record).
+   Smell: Category C (Law of Demeter).
+   Outcome: no consumer references `AgentActivityTracker`.
+   Landed: `WidgetAgent` folds the live-activity fields and a `contextPercent` projection; `AgentWidget` projects records; `ConversationViewer`, `AgentsMenuHandler`, `buildDetails`, and `buildNotificationDetails` read off the record; `NotificationSystem.cleanupCompleted` removed; `SubagentEventsObserver` returns early on consumed results; +8 tests (1058 → 1066).
+3. **✅ Delete `AgentActivityTracker` and `ui-observer`; drop the activity map from the runtime and spawn tools — complete.**
+   ([#422]) Target: `ui/agent-activity-tracker.ts` (delete), `ui/ui-observer.ts` (delete), `runtime.ts`, `tools/foreground-runner.ts`, `tools/background-spawner.ts`.
+   The spawn tools stop constructing trackers, subscribing, and populating maps; `SubagentRuntime.agentActivity` is removed.
+   Smell: Category A + C. Outcome: −145 LOC, one session subscription per child, runtime holds zero UI state.
+   Landed: deleted `agent-activity-tracker.ts` (84) + `ui-observer.ts` (61) and their unit suites; dropped the `agentActivity` parameter from `runForeground`/`spawnBackground`, the `AgentActivityAccess` interface, and the `AgentToolRuntime`/`SubagentRuntime` activity-map fields; the foreground `observer.onSessionCreated` keeps `recordRef`/`fgId` binding and `widget.ensureTimer`; −34 tests (1066 → 1032).
+4. **✅ Make the widget self-drive from lifecycle events — complete.**
+   ([#423]) Target: `ui/agent-widget.ts`, `observation/composite-subagent-observer.ts` (new), `index.ts`.
+   The widget starts/stops its timer in response to started/created/completed notifications instead of tool calls; spawn tools no longer call `ensureTimer`/`update`/`markFinished`.
+   Smell: Category C (coupling direction).
+   Outcome: the widget is a reactive consumer; no inbound calls from core spawn tools.
+   Landed: `AgentWidget implements SubagentManagerObserver` (starts the 80 ms loop on `onSubagentStarted`/`onSubagentCreated`, re-renders on `onSubagentCompleted`/`onSubagentCompacted`); a new `CompositeSubagentObserver` fans the manager's single observer slot out to `[eventsObserver, widget]` (wired in `index.ts`, keeping `SubagentManager` unchanged); dropped the `widget` parameter and `ForegroundWidgetDeps`/`BackgroundWidgetDeps` interfaces from both spawners, deleted `AgentWidget.markFinished` (redundant with `seedFinishedAgents`), made `ensureTimer` private, and narrowed `AgentToolWidget` to `setUICtx`; +11 tests (1032 → 1043, then −4 with the dropped spawner widget-driving tests → 1039).
+5. **✅ Drop the widget dependency from the `subagent` tool — complete.**
+   ([#424]) Target: `tools/agent-tool.ts`, `test/helpers/make-deps.ts`.
+   `AgentTool` loses its `widget` constructor param (UICtx capture stays in `ToolStartHandler`); `createToolDeps` sheds the widget stub.
+   The activity-map (`agentActivity`) dependency this step originally named was already removed from the tool and runtime in Step 3 ([#422]), so only `widget` remained to drop.
+   Smell: Category C/D.
+   Outcome: the LLM tool depends only on manager/runtime/settings/registry; fixture drops 1 field.
+   Landed: removed the `widget` constructor param and the redundant `this.widget.setUICtx(ctx.ui)` call from `AgentTool.execute`, deleted the `AgentToolWidget` interface and its `UICtx` import, updated the sole `index.ts` call site, and dropped the `widget` field/stub plus two now-obsolete tests (`agent-tool` UICtx capture, `make-deps` widget defaults) — UICtx capture is pinned by `handlers/tool-start.test.ts`; −2 tests (1039 → 1037).
+6. **✅ Reconcile the public event contract — complete.**
+   ([#425]) Target: `service/service.ts`, the lifecycle-events table in [architecture.md](../architecture.md).
+   Remove the vacant `ACTIVITY` channel (or emit a real broadcast for it) and add the emitted `failed`/`compacted`/`created` channels so declared constants match emitted events.
+   Smell: Category A/E.
+   Outcome: declared channels equal emitted channels; no vacant hook.
+   Landed: removed `SUBAGENT_EVENTS.ACTIVITY` (breaking) and added `FAILED`/`COMPACTED`/`CREATED`/`STEERED` — `subagents:steered` (from `steer-tool.ts`) was also emitted-but-undeclared, so all four emitted agent-lifecycle channels are now declared; corrected the stale `subagents:completed` payload in the lifecycle-events table to the real `buildEventData` shape; +1 test (1037 → 1038).
+7. **✅ Consolidate residual test clone families — complete.**
+   ([#426]) Target: `test/settings.test.ts` + `test/layered-settings.test.ts`, `test/lifecycle/create-subagent-session.test.ts`, `test/ui/agent-config-editor.test.ts`.
+   Extract shared fixtures for the clone families fallow reports that the spine does not already rewrite.
+   Smell: Category D. Outcome: test clone groups drop below 15.
+   Landed: extracted `test/helpers/tmp-settings-dirs.ts` (global+project tmp-dir fixture) and `test/helpers/capture-warn.ts` (a `console.warn` capture helper), each with a paired self-test; table-drove the `create-subagent-session` post-bind membership cases and the `agent-config-editor` menu + confirm-remove cases into `it.each`; pi-subagents test clone groups dropped from 24 to 14 (below the <15 target); +9 tests (1038 → 1047).
+8. **✅ Reconsider the UI direction (first-principles ADR) — complete.**
+   ([#427]) Target: `docs/decisions/`, `ui/`.
+   The spine already made the UI _substitutable_; this step decides its _distribution_, not whether the experiment is possible.
+   The goal is **substitutable, not optional**: a human needs some surface, but the specific UI is replaceable — the way Pi ships a default TUI built on the same public API any extension targets.
+   The disentangled core stays byte-for-byte identical whether or not a given UI consumer is installed (the composition test), so a replacement UI is a downstream concern even though _some_ UI is not.
+   Unlike the worktrees provider seam (generative, rationed — one provider the core consults), the UI is an observational consumer (unlimited, the core never waits on it) reading the broadcast-plus-query surface, which is why packaging it is the secondary question and decoupling it was the real win.
+   Two standing concerns are the evidence this decision weighs and the better boundaries the reconsideration is meant to surface:
+   - **Truncated transcript.**
+     The conversation viewer shows a truncated view, yet `Subagent.messages` already exposes the full history and the core already persists each child as a standard Pi session JSONL (`outputFile`) — the limit is the bespoke overlay's rendering, not data access.
+   - **Foreground widget redundancy.**
+     In foreground the tool's inline `onUpdate` stream already shows progress, so the above-editor widget duplicates it; the widget earns its keep only for background agents — a per-mode judgment the fused UI cannot vary.
+   Candidate redesign to record: replace the bespoke overlay with "open the child session in the same viewer Pi uses for any session," following the recursive-Pi insight and the already-persisted session file.
+   Judge the widget, conversation viewer, and `/agents` menu per component — keep, shrink, extract to `@gotgenes/pi-subagents-ui`, or remove — and capture the decision in an ADR that gateways Phase 19.
+   Smell: Category E (organization / boundary).
+   Outcome: a recorded per-component decision motivated by the two concerns; the inherited UI is substitutable and no longer preserved by default.
+   Landed: [ADR-0004] records the per-component decision — (A) shrink the widget to background agents only; (B) remove the bespoke `ConversationViewer`, replacing it with native session navigation over the persisted child JSONL (`switchSession`/`loadEntriesFromFile`, mechanism gated on a Phase 19 spike); (C) dissolve the `/agents` command (remove the create wizard and the agent-types config editor, re-home running-agent visibility onto the widget + session navigation, extract settings to a focused `/subagents:settings` command); (D) keep the surviving UI in-core (substitutable, not extracted).
+   The ADR gateways Phase 19, which implements these decisions under its own plan; no runtime code changed in this step.
+
+## Step dependency diagram
+
+```mermaid
+flowchart TB
+    S1["1 — Fold metrics + activity onto record (#420) ✅"]
+    S2["2 — Migrate readers to record getters (#421) ✅"]
+    S3["3 — Delete tracker + ui-observer, drop activity map (#422) ✅"]
+    S4["4 — Widget self-drives on events (#423) ✅"]
+    S5["5 — Drop widget dep from subagent tool (#424) ✅"]
+    S6["6 — Reconcile public event contract (#425) ✅"]
+    S7["7 — Consolidate test clone families (#426) ✅"]
+    S8["8 — Reconsider UI direction, ADR (#427) ✅"]
+
+    S1 --> S2 --> S3 --> S4 --> S5 --> S8
+    S6
+    S7
+```
+
+## Parallel tracks
+
+- **Track A — Disentangle the activity tier (spine):** Steps 1, 2, 3.
+  Strictly ordered; each is a safe lift-and-shift over the previous.
+- **Track B — Decouple widget and tool wiring:** Steps 4, 5.
+  Begins once the activity map is gone (Step 3).
+- **Track C — Public-contract hygiene:** Step 6.
+  Independent; can land any time.
+- **Track D — Test consolidation:** Step 7.
+  Independent; can land any time.
+- **Track E — UI reconsideration:** Step 8.
+  Gated on the spine and Track B (the UI must be a clean consumer first).
+
+[ADR-0004]: ../../decisions/0004-reconsider-ui-direction.md
+[first-principles refinement]: ../architecture.md#first-principles-refinement-and-the-deeper-target
+[#420]: https://github.com/gotgenes/pi-packages/issues/420
+[#421]: https://github.com/gotgenes/pi-packages/issues/421
+[#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
+[#426]: https://github.com/gotgenes/pi-packages/issues/426
+[#427]: https://github.com/gotgenes/pi-packages/issues/427

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

@@ -0,0 +1,220 @@
+---
+status: accepted
+date: 2026-06-18
+---
+
+# 0004 — Reconsider the UI direction from first principles
+
+## Status
+
+Accepted.
+Completes Phase 18 (reconsider the UI) and gateways Phase 19 (implement the recorded decisions).
+Decision-only: this ADR changes no runtime code.
+The inherited UI stays live until Phase 19 acts on these decisions.
+
+## Context
+
+Phase 18's spine (Steps 1–7, #420 through #426) disentangled the activity tier from the core.
+The core now owns all run state in one place (`SubagentState`), the widget self-drives from lifecycle events, the LLM-facing `subagent` tool no longer depends on the widget, and the public event contract's declared channels equal its emitted channels.
+The UI is therefore a pure reactive consumer of the broadcast-plus-query surface — _substitutable_.
+
+This final step decides the UI's _direction and distribution_, not whether substitution is possible.
+The goal is **substitutable, not optional**: a human needs some surface, but the specific UI is replaceable — the way Pi ships a default TUI built on the same public API any extension targets.
+The disentangled core stays byte-for-byte identical whether or not a given UI consumer is installed (the composition invariant), so a replacement UI is a downstream concern even though _some_ UI is not.
+
+Unlike the worktrees provider seam (generative, rationed — one provider the core consults), the UI is an observational consumer (unlimited, the core never waits on it).
+That asymmetry is why packaging the UI is the secondary question and decoupling it was the real win.
+
+Three operator-framed concerns shape the per-component judgment.
+
+1. **Foreground progress is already shown by the tool call.**
+   In foreground the `subagent` tool's inline `onUpdate` stream renders progress well; the above-editor widget duplicates it.
+2. **Background agents have no tool-call display.**
+   When agents run in the background there is no inline stream, so _something_ must indicate their state — and multiple subagents can run in parallel, so that surface must represent N concurrent agents at once.
+3. **Operator visibility into a subagent's session is a distinct, richer need.**
+   "Switch into a subagent's session, scroll/read it, switch between subagents, and exit back to root" is a navigation interaction, not a live overlay.
+   The core already persists each child as a standalone Pi session JSONL at `Subagent.outputFile`, and `Subagent.messages` exposes the full history — so the data was never the limit; the bespoke, width-capped `ConversationViewer` overlay was.
+
+### Relevant Pi SDK surface
+
+Verified against `@earendil-works/pi-coding-agent@0.79.1`:
+
+- `ExtensionActions.switchSession(sessionPath, { withSession })` switches the **active** session to a different session file.
+  It is a full active-session takeover: it fires `session_before_switch` / `session_shutdown`, invalidates the current session context (`setBeforeSessionInvalidate` exists for host-owned UI teardown), and returns `{ cancelled }`.
+  The switched-to session is fully interactive — `ReplacedSessionContext` exposes `sendUserMessage`.
+- `session-manager` exports `loadEntriesFromFile(filePath)` / `parseSessionEntries(content)`, which read a session file's entries without switching — the read-only alternative to a full takeover.
+
+## Decision
+
+Judge each UI component on the first principles above, then record the distribution.
+
+### A — Foreground widget: shrink to background agents only
+
+The above-editor widget duplicates the foreground tool's inline `onUpdate` stream.
+The widget survives **only** as the background-agent status surface (concern 2): foreground runs suppress it, the inline stream is authoritative there, and the background surface keeps the widget's existing per-agent tree so it represents N parallel agents at once.
+The change is _when_ the widget shows (background-only), not _what_ it shows.
+
+### B — Conversation viewer: replace the bespoke overlay with native session navigation
+
+Remove the bespoke `ConversationViewer` overlay.
+Operator visibility (concern 3) is served by Pi's own session machinery applied to the already-persisted child session file, not a hand-rolled transcript renderer — the recursive-Pi insight applied to `Subagent.outputFile`.
+
+The illustrative call shape (Phase 19, not final):
+
+```typescript
+// "View running agents" → pick a child → switch into its persisted session
+const child = manager.getRecord(id);
+if (child?.outputFile) {
+  await ctx.switchSession(child.outputFile);
+  // operator reads/scrolls in Pi's native viewer; a later switch returns to root
+}
+```
+
+This is Tell-Don't-Ask (hand Pi the session path; Pi owns the viewer) and keeps the core free of transcript-rendering code.
+
+This decision records the _direction_ (native session machinery over a bespoke renderer), not the _mechanism_.
+`switchSession` is a full active-session takeover and is interactive, so the operator UX is gated on a Phase 19 spike that chooses between (i) true `switchSession` round-trips and (ii) a read-only transcript built from `loadEntriesFromFile` that renders Pi-standard entries without leaving the root session.
+See "Phase 19 entry criteria."
+
+### C — `/agents` menu: dissolve the monolithic command into focused surfaces
+
+The single `/agents` command bundles four unrelated jobs; split them, and do not keep all in one command.
+Managing agent _definitions_ through the menu earns no keep — creating or editing agents is better done with other tools (directly in Pi, or a real text editor / IDE).
+
+- **Create new agent (wizard)** → **remove.**
+  An operator generates a new agent `.md` by asking a Pi agent directly (more capable than a fixed wizard) or by writing the file in an editor.
+- **Agent types (list + config editor)** → **remove.**
+  Viewing and editing agent definitions is better served by opening the `.md` files directly in an editor/IDE.
+- **Running agents (visibility)** → **keep the responsibility, re-home it.**
+  _Something_ must own running-agent visibility; it moves onto the background widget (Decision A) plus the native session navigation (Decision B), not a bespoke in-menu overlay.
+- **Settings (concurrency / max turns / grace turns)** → **extract to a focused command** (e.g. `/subagents:settings`).
+  Some value, but it does not belong bundled with agent management.
+
+### D — Distribution: keep the surviving UI in-core (substitutable, not extracted)
+
+The spine already made the UI substitutable; a replacement UI is a downstream concern that targets the public broadcast-plus-query surface.
+The surviving UI — the background widget, a focused settings command, and the session-navigation glue — **stays in-core** as a reactive consumer.
+Extraction to a separate `@gotgenes/pi-subagents-ui` package is **not** chosen now.
+
+This answers the issue's headline question — the UI's _distribution_ — with "keep in core, substitutable," recorded explicitly rather than left implicit.
+Extraction remains an available future option precisely because the composition invariant holds: the core is byte-for-byte identical with or without a given UI consumer.
+It would be revisited if a second, materially different UI consumer appears, or if the in-core UI starts to pull SDK or rendering concerns back into core modules.
+
+## Consequences
+
+- The inherited UI is no longer preserved by default; each component now has a recorded fate (shrink / replace / dissolve) motivated by the first principles, not by inheritance.
+- Phase 18 is complete.
+  This ADR gateways Phase 19, which implements the decisions (background-only widget, native session navigation, `/agents` decomposition, `/subagents:settings` extraction) under its own plan and issues.
+- No interim regression: this ADR removes nothing.
+  The widget, the `ConversationViewer`, and the full `/agents` menu stay live until Phase 19 replaces them.
+- Phase 19 must preserve the spine's invariants when it acts on these decisions: the runtime holds zero UI state (#422), the widget is a reactive consumer with no inbound calls from core spawn tools (#423), the LLM tool depends only on manager/runtime/settings/registry (#424), and declared event channels equal emitted channels with no vacant hook (#425).
+  These are pinned today by the existing observer/widget/event-contract suites, which Phase 19 inherits.
+
+## Phase 19 entry criteria
+
+The following are open and must be resolved by a Phase 19 spike before committing to a mechanism; they are deliberately not decided here.
+
+- **Root-continuity during a session switch.**
+  `switchSession` invalidates the current session context — does the root's in-flight turn survive a switch-out-and-return, and what is the correct "return to root" gesture?
+  Resolve before committing to true `switchSession` round-trips.
+- **View-only vs interactive.**
+  A switched-to child session is interactive (`sendUserMessage`).
+  Decide whether steering a child from its own session is desirable, or whether the viewer should be strictly read-only (favoring the `loadEntriesFromFile` transcript path).
+- **Parallel-agent navigation.**
+  With N background agents running, decide the operator's gesture to pick which child to view and to cycle between them — driven from the background widget, a dedicated command, or both.
+- **Settings command namespace.**
+  Confirm the final command name/namespace for the extracted settings surface (`/subagents:settings` vs another form) against how sibling packages register namespaced commands.
+
+The agent create/edit surfaces are **not** open questions: both are removed (Decision C).
+
+## Addendum (2026-06-20): Phase 19 entry-criteria answers ([#446])
+
+The Phase 19 Step 1 spike ([#446]) resolved all four entry criteria.
+Evidence comes from the bundled `@earendil-works/pi-coding-agent` SDK surface (`packages/pi-subagents/node_modules/@earendil-works/pi-coding-agent/dist`) and a throwaway vitest harness run against a **real child session JSONL** (a 43-entry subagent session: 1 `session` header carrying a `parentSession` backref, 1 `model_change`, 1 `thinking_level_change`, 40 `message` entries).
+The harness was discarded after observation; no production source changed.
+
+### Finding 0 — `loadEntriesFromFile` is not part of the package's public surface
+
+The original "Relevant Pi SDK surface" section cited `loadEntriesFromFile` as the read-only alternative to a switch.
+The spike found it is **not reachable** from `@earendil-works/pi-coding-agent`, and that this is not a types/runtime mismatch — the type barrel and the runtime barrel agree, both omitting it.
+`loadEntriesFromFile` is defined in the deep module `core/session-manager.ts` (annotated `/** Exported for testing */`), but the public barrel `src/index.ts` (→ `dist/index.d.ts` + `dist/index.js`) re-exports only a curated subset of that module — including `parseSessionEntries` but **not** `loadEntriesFromFile`.
+The `package.json` `exports` map exposes only `"."` → the barrel, so the deep import `@earendil-works/pi-coding-agent/dist/core/session-manager.js` is not a supported entry point either.
+`tsc` correctly rejects `import { loadEntriesFromFile } from "@earendil-works/pi-coding-agent"` with `TS2305: Module … has no exported member 'loadEntriesFromFile'`; the throwaway Vitest harness only reached a runtime `is not a function` because esbuild strips types without type-checking (the package's own `pnpm run check` would have caught it at compile time).
+This is not version-specific: the barrel omits it identically in both the pinned `0.79.1` and the latest `0.79.8`, so an SDK upgrade does not surface it — Step 4 should not chase one.
+The viable read-only path is therefore `parseSessionEntries(readFileSync(outputFile, "utf8"))` — `parseSessionEntries` _is_ public (both types and runtime) — which the harness confirmed returns the full `FileEntry[]` transcript with no session switch and no active-session mutation.
+Step 4 ([#445]) should read the file itself and call `parseSessionEntries`, not `loadEntriesFromFile`.
+
+Upstream references:
+
+- Barrel that omits it: [`packages/coding-agent/src/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/index.ts).
+- Test-annotated definition: [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/session-manager.ts).
+
+### Finding 1 — the read-only transcript renders entirely on public Pi APIs (no bespoke renderer)
+
+The read-only path returns raw `FileEntry[]`, so _something_ must render them.
+The spike found that every piece needed to turn those entries into a Pi-standard transcript is already re-exported through the public root barrel — so Step 4 wires Pi's own machinery rather than re-implementing the formatting the bespoke `ConversationViewer`/`message-formatters.ts` carried.
+This matters because ADR-0004 Decision B's `switchSession` sketch implied "Pi owns the viewer"; the read-only path keeps that property at the _component_ level (Pi renders each entry) without the active-session takeover.
+
+The verified public pipeline (all symbols confirmed present in `dist/index.d.ts`, the root barrel):
+
+1. **Load** — `parseSessionEntries(readFileSync(record.outputFile, "utf8")): FileEntry[]` (Finding 0).
+2. **Bridge** — `buildSessionContext(entries, leafId?, byId?): SessionContext` turns the entries into `{ messages: AgentMessage[], thinkingLevel, model }`, handling tree traversal, compaction, and branch summaries along the path.
+   Note `buildSessionContext` takes `SessionEntry[]`, so drop the leading `SessionHeader` (`type: "session"`) that `parseSessionEntries` includes.
+3. **Render** — one of:
+   - **Text:** `serializeConversation(messages: Message[]): string` (from `core/compaction`) for a plain-text dump.
+   - **TUI:** the per-entry components `AssistantMessageComponent`, `UserMessageComponent`, `ToolExecutionComponent`, `BashExecutionComponent`, `CompactionSummaryMessageComponent`, `BranchSummaryMessageComponent`, `CustomMessageComponent`, `SkillInvocationMessageComponent` (from `modes/interactive/components`), plus `renderDiff`, for a scrollable native transcript.
+
+Unlike `loadEntriesFromFile`, all of these _are_ public (both types and runtime).
+So the read-only viewer is buildable end-to-end on supported APIs, and ADR-0004 Decision B's "keep the core free of transcript-rendering code" holds — the rendering is Pi's, imported, not hand-rolled.
+
+Upstream references:
+
+- Component barrel: [`packages/coding-agent/src/modes/interactive/components/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/modes/interactive/components/index.ts).
+- `serializeConversation`: [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/compaction/utils.ts).
+
+### Criterion 1 — Root-continuity during a session switch: avoid the switch
+
+`switchSession` is a full active-session takeover: it fires `session_before_switch` (cancellable) and then tears the current runtime down via `session_shutdown` (whose `targetSessionFile` field marks a replacement-driven shutdown).
+The root's in-flight turn does **not** survive the takeover — the runtime that owns that turn is invalidated — and a "return to root" would require a second `switchSession(rootSessionFile)` that re-incurs the teardown on the way back.
+Because background agents run precisely while the operator keeps working at root, a true `switchSession` round-trip is hostile to a root with a turn in flight.
+
+**Answer:** do not use `switchSession` for navigation.
+The read-only transcript path (Criterion 2) sidesteps root-continuity entirely — it never touches the active session, so there is no return gesture to get wrong.
+
+### Criterion 2 — View-only vs interactive: read-only
+
+`ReplacedSessionContext` (handed to a `switchSession` `withSession` callback) extends `ExtensionCommandContext` and exposes `sendUserMessage`/`sendMessage`, so a switched-to child session is interactive.
+But operator visibility (concern 3) is framed as "switch in, scroll/read, switch between, exit back to root" — a navigation interaction, not a live steering overlay — and steering already has a home (`steer_subagent` tool / the widget).
+Adding in-session steering would create a second, redundant steering surface.
+
+**Answer:** the viewer is strictly **read-only**, loaded via `parseSessionEntries(readFileSync(record.outputFile))` (Finding 0) and rendered through Pi's public entry components (Finding 1) without leaving the root session.
+This also resolves Criterion 1 by construction.
+
+### Criterion 3 — Parallel-agent navigation: command-first
+
+With N background agents running, the operator needs a gesture to pick which child to view.
+The background widget (Decision A, [#444]) already represents N parallel agents as a per-agent tree, making it the natural eventual selection surface; a flat command gives a non-widget entry point that lists running background agents and lets the operator pick one keyed on `record.outputFile`.
+
+**Answer:** Step 4 ([#445]) ships a **command** as the primary, unit-testable selection surface (list background agents → pick → render that child's transcript read-only), with a widget gesture as an optional later enhancement.
+"Both" remains the eventual target; command-first is the Step 4 starting point because it does not depend on the widget shrink ([#444]) landing first.
+
+### Criterion 4 — Settings command name: `/subagents-settings`
+
+Sibling packages register flat, hyphenated command names with no `:` namespace: `registerCommand("agents", …)` (this package), `"colgrep-reindex"`, `"permission-system"`.
+A `/subagents:settings` form would be inconsistent with every existing command in the repo, and `/agents-settings` wrongly implies it manages agent definitions (which Decision C removes).
+
+**Answer:** confirm **`/subagents-settings`** (flat, hyphenated) for Step 2 ([#447]).
+Reject the tentative `/subagents:settings` and the `/agents-settings` alternative.
+
+### Net mechanism for Phase 19
+
+- Session navigation (Step 4, [#445]): a read-only transcript, surfaced through a flat command; no `switchSession`, no `loadEntriesFromFile`.
+  The pipeline is `parseSessionEntries(readFileSync(record.outputFile, "utf8"))` → drop the `SessionHeader` → `buildSessionContext(...).messages` → render via Pi's public entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / … ) or `serializeConversation` (Findings 0 and 1).
+- Settings command (Step 2, [#447]): `/subagents-settings`.
+
+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).
+
+[#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