@gotgenes/pi-subagents 16.6.0 → 17.0.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.0.0...pi-subagents-v17.0.1) (2026-06-20)
+
+
+### Bug Fixes
+
+* **pi-subagents:** exclude disabled agents from the subagent tool description ([#448](https://github.com/gotgenes/pi-packages/issues/448)) ([9a43414](https://github.com/gotgenes/pi-packages/commit/9a43414b3e15f0c978db9d468b737b13b801fdb2))
+* **pi-subagents:** return an error when spawning a disabled agent type ([#448](https://github.com/gotgenes/pi-packages/issues/448)) ([0e0225e](https://github.com/gotgenes/pi-packages/commit/0e0225e167596217dc7b1d99dd6269600d65326b))
+
+## [17.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.6.0...pi-subagents-v17.0.0) (2026-06-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* SUBAGENT_EVENTS.ACTIVITY ("subagents:activity") is removed. It was never emitted, so no consumer could act on it, and there is no replacement — the activity tier was removed in Phase 18. Consumers should subscribe to the now-declared FAILED, COMPACTED, CREATED, and STEERED channels instead.
+
+### Features
+
+* reconcile SUBAGENT_EVENTS with emitted channels ([#425](https://github.com/gotgenes/pi-packages/issues/425)) ([ba0c48b](https://github.com/gotgenes/pi-packages/commit/ba0c48b294123c1498db2040b1037adcd7ad4e4e))
+
 ## [16.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.5.0...pi-subagents-v16.6.0) (2026-06-17)
 
 

package/dist/public.d.ts

@@ -154,7 +154,10 @@ interface SubagentsService {
 declare const SUBAGENT_EVENTS: {
     readonly STARTED: "subagents:started";
     readonly COMPLETED: "subagents:completed";
-    readonly ACTIVITY: "subagents:activity";
+    readonly FAILED: "subagents:failed";
+    readonly COMPACTED: "subagents:compacted";
+    readonly CREATED: "subagents:created";
+    readonly STEERED: "subagents:steered";
 };
 /** Publish the SubagentsService on globalThis for cross-extension access. */
 declare function publishSubagentsService(service: SubagentsService): void;

package/docs/architecture/architecture.md

@@ -13,8 +13,8 @@ This document describes the architecture of the pi-subagents fork: a focused, co
 4. **No time-based scheduling** — cron-style timed dispatch (upstream's `schedule.ts` subsystem) is removed from the core (#52).
    Timed dispatch is a separate concern that any extension can implement by calling `spawn()` on the published API.
    The max-concurrent admission gate is not scheduling in this sense — concurrency management stays in core.
-5. **UI extraction is deferred** — the widget, conversation viewer, and `/agents` command menu stay in the core for now.
-   They are the first candidate for extraction once the API boundary is proven stable.
+5. **UI is an in-core, substitutable consumer** — [ADR-0004](../decisions/0004-reconsider-ui-direction.md) records the per-component decision: the widget shrinks to background agents only, the bespoke conversation viewer is replaced by native session navigation, the `/agents` command is dissolved into focused surfaces, and the surviving UI stays in the core as a reactive consumer (not extracted to a separate package).
+   Extraction remains an available future option because the composition invariant holds — the core is byte-for-byte identical with or without a given UI consumer.
 6. **Snapshot, don't capture** — mutable parent state (ctx, session, model) is read once at spawn time and frozen into a `ParentSnapshot` data object.
    No live references survive past the spawn call.
 7. **Subscribe, don't thread** — observation of agent progress uses direct session-event subscription, not callback parameters threaded through multiple layers.
@@ -63,9 +63,8 @@ flowchart TB
 
     subgraph observation["Observation domain"]
         direction TB
-        RecordObserver["record-observer<br/>(stats via events)"]
+        RecordObserver["record-observer<br/>(stats + live activity via events)"]
         Notification["notification<br/>(completion nudges)"]
-        UIObserver["ui-observer<br/>(streaming state)"]
     end
 
     subgraph tools["Tools domain"]
@@ -95,8 +94,8 @@ flowchart TB
     SessionConfig --> Prompts & Env
     AgentTypeRegistry --> DefaultAgents & CustomAgents
     RecordObserver -.->|subscribes| SubagentSession
-    UIObserver -.->|subscribes| SubagentSession
     Widget -.->|polls| SubagentManager
+    SubagentManager -.->|notifies| Widget
 ```
 
 ### Key domain types
@@ -258,7 +257,7 @@ sequenceDiagram
     Asm-->>Factory: SessionConfig
     Factory->>Child: create session + bind extensions
     Factory-->>Ag: SubagentSession (born complete)
-    Note over Ag: agent-observer + ui-observer subscribe to session events
+    Note over Ag: record-observer subscribes to session events
     Ag->>Sub: runTurnLoop(prompt, opts)
     Sub->>Child: prompt + drive turn loop
     Child-->>Sub: result text
@@ -322,6 +321,7 @@ src/
 │   ├── notification.ts             completion nudges
 │   ├── notification-state.ts       per-agent notification tracking
 │   ├── renderer.ts                 notification TUI component
+│   ├── composite-subagent-observer.ts fans manager notifications out to multiple observers
 │   └── subagent-events-observer.ts manager lifecycle observer (event emission + persistence + notification)
 │
 ├── service/                        cross-extension API boundary
@@ -346,10 +346,8 @@ src/
 │   ├── agent-creation-wizard.ts    agent creation (AgentCreationWizard class)
 │   ├── conversation-viewer.ts      scrollable session overlay
 │   ├── message-formatters.ts       pure per-message-type formatters (extracted from conversation-viewer)
-│   ├── agent-activity-tracker.ts   live activity state tracker
 │   ├── agent-file-ops.ts           filesystem abstraction
 │   ├── agent-file-writer.ts        overwrite-guard + write + reload + notify helper
-│   ├── ui-observer.ts              session-event observer for streaming
 │   └── display.ts                  pure formatters and shared types
 │
 └── handlers/                       event handlers
@@ -361,11 +359,11 @@ src/
 
 ### Observation model
 
-Record statistics (tool uses, token usage, compaction counts) are updated by `record-observer.ts`, which subscribes directly to session events.
-UI streaming (active tools, response text, turn counts) is handled by `ui/ui-observer.ts`, which subscribes to the same session events independently.
-Neither observer wraps or forwards the other — both subscribe directly to the session.
+Record statistics (tool uses, token usage, compaction counts) and live activity (active tools, response text, turn counts) are updated by `record-observer.ts`, which subscribes directly to session events.
+This is the single per-child session subscription — all run state lives on the `Subagent` record.
 
-The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes to session events via `Subagent.subscribeToUpdates()` and reads messages via `Subagent.messages` — no direct `AgentSession` reference (#277).
+The widget reads agent state by polling the records exposed via `SubagentManager.listAgents()` every 80 ms; that poll loop is now started by the manager's lifecycle notifications (the widget subscribes as a `SubagentManagerObserver` fanned out through `CompositeSubagentObserver`), not by inbound calls from the spawn tools.
+The conversation viewer subscribes to session events via `Subagent.subscribeToUpdates()` and reads messages via `Subagent.messages` — no direct `AgentSession` reference (#277).
 
 ## Cross-extension architecture
 
@@ -483,11 +481,14 @@ If Pi gains a native service registry ([earendil-works/pi#4207]), these accessor
 
 The core emits events on `pi.events` that any extension can observe:
 
-| Channel               | Payload                                     | When                 |
-| --------------------- | ------------------------------------------- | -------------------- |
-| `subagents:started`   | `{ id, type, description }`                 | Agent begins running |
-| `subagents:completed` | `{ id, type, status, result?, error? }`     | Agent finishes       |
-| `subagents:activity`  | `{ id, toolName?, textDelta?, turnCount? }` | Streaming progress   |
+| Channel               | Payload                                                                             | When                                          |
+| --------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------- |
+| `subagents:started`   | `{ id, type, description }`                                                         | Agent begins running                          |
+| `subagents:completed` | `{ id, type, description, status, result?, error?, toolUses, durationMs, tokens? }` | Agent finishes successfully                   |
+| `subagents:failed`    | same as `completed` (`buildEventData` shape)                                        | Agent ends in `error`/`stopped`/`aborted`     |
+| `subagents:compacted` | `{ id, type, description, reason, tokensBefore, compactionCount }`                  | Child session compacts                        |
+| `subagents:created`   | `{ id, type, description, isBackground }`                                           | Background agent created (pre-admission)      |
+| `subagents:steered`   | `{ id, message }`                                                                   | Steering message delivered to a running agent |
 
 These are fire-and-forget broadcast events — no request IDs, no reply channels.
 
@@ -894,173 +895,232 @@ All nine steps are closed: [#381], [#373], [#374], [#375], [#376], [#377], [#378
 [#415] migrated `pi-subagents-worktrees` to `loadLayeredSettings` after the Step 9 published release.
 See [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md) for the full findings, step outcomes, dependency diagram, and tracks.
 
-## Phase 18 Reconsider UI from first principles
-
-After 17 phases the core is in very good shape: health 78/100 (B), zero dead code, zero fallow refactoring targets, average cyclomatic 1.4.
-The one structural debt that remains is not spread thin across the core — it is concentrated in a single place: the UI's live-streaming state (the "activity tier") is woven into the core's runtime, spawn tools, the LLM-facing `subagent` tool, and the notification path.
-This is the entanglement the [first-principles refinement](#first-principles-refinement-and-the-deeper-target) predicted — "the activity/metrics push tier is provisional; its only reactive consumer is the inherited widget" — observed in the code.
-Disentangling it is what lets the core reach a great state, and it is the prerequisite to any "reconsider the UI" decision: today the UI cannot be a clean consumer because the core does its streaming bookkeeping for it.
-
-### Findings
-
-Six findings tell one story — the activity tier has 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 doc's lifecycle-events table but is never emitted anywhere — a vacant hook the doc's own "no vacant hooks" rule forbids.
-   Meanwhile three emitted channels (`subagents:failed`, `subagents:compacted`, `subagents:created`) are absent from the constant map.
-   Category A/E.
+## Phase 18 (complete)
 
-### Health metrics
+Phase 18 disentangled the activity tier from the core and recorded a first-principles decision about the UI's direction.
+Steps 1–5 (the spine) consolidated all run state onto `SubagentState`, deleted `AgentActivityTracker` and `ui-observer` (−145 LOC), and made the widget a pure reactive consumer of lifecycle events with no inbound calls from core spawn tools.
+Step 6 reconciled the public event contract (breaking: removed the vacant `SUBAGENT_EVENTS.ACTIVITY` channel; added `FAILED`, `COMPACTED`, `CREATED`, `STEERED`).
+Step 7 consolidated residual test clone families, dropping from 24 to 14 clone groups (below the <15 target).
+Step 8 captured the per-component UI decisions in [ADR-0004]: the widget shrinks to background agents only; the bespoke `ConversationViewer` is replaced by native session navigation (a read-only transcript via `parseSessionEntries`, per the Step 1 spike — see [ADR-0004]'s addendum); the `/agents` command is dissolved (remove the create wizard and agent-types editor, extract settings to a focused command); the surviving UI stays in-core as a substitutable reactive consumer.
+Source LOC decreased from 7,751 (62 files) to 7,650 (61 files); tests grew from 1,031 to 1,047.
+All eight steps are closed: [#420], [#421], [#422], [#423], [#424], [#425], [#426], [#427].
+See [phase-18-reconsider-ui.md](history/phase-18-reconsider-ui.md) for the full findings, step outcomes, dependency diagram, and tracks.
+
+## Phase 19 (proposed)
+
+Phase 19 implements the per-component UI decisions recorded in [ADR-0004]: shrink the widget to background-only, replace the bespoke conversation viewer with native session navigation, dissolve the monolithic `/agents` menu, and keep the surviving UI in-core.
+
+The sequencing follows Kent Beck's "make the change easy, then make the easy change."
+The end state deletes `agent-menu.ts` — the god-command that bundles four unrelated jobs — and everything reachable only from it.
+Rather than surgically mutate that doomed module (and the #1 churn hotspot `index.ts`) once per option, Phase 19 first stands up the replacement surfaces additively, then removes the now-orphaned subtree in a single terminal cut.
+This keeps every responsibility's old surface live until its replacement exists (ADR-0004's no-interim-regression invariant), turns the three replacement steps into genuinely parallel work (none touch `agent-menu.ts`), and reduces `index.ts` edits from four surgical removals to one deregistration.
+
+Seven steps in three phases:
+
+- **Phase A — stand up replacements (additive):** spike, settings command, background widget, native session navigation (Steps 1–4).
+- **Phase B — dissolve `/agents` (terminal cut):** delete the orphaned subtree in two deletion commits, one per subtree (Steps 5–6).
+- **Phase C — test health:** consolidate the test clones that survive the cut (Step 7).
+
+### Health metrics (Phase 18 → Phase 19 target)
+
+| Metric                 | Phase 18 (current)       | Phase 19 target      |
+| ---------------------- | ------------------------ | -------------------- |
+| Health score           | 78/100 (B)               | 83/100 (B+)          |
+| Source LOC             | 7,650 (61 files)         | ~6,780 (~55 files)   |
+| Production duplication | 11 lines (1 group)       | 0 lines              |
+| Test clone groups      | 16                       | ≤ 10                 |
+| Top churn hotspot      | `index.ts` (103 commits) | `index.ts` (cooling) |
+
+### ✅ Step 1 — Spike: resolve ADR-0004 entry criteria ([#446])
+
+Smell: Category C (coupling boundary) — four open decisions block the session-navigation implementation.
+Target: `docs/decisions/0004-reconsider-ui-direction.md` addendum.
+
+The four entry criteria from ADR-0004:
+
+1. **Root-continuity:** Does the root's in-flight turn survive `ctx.switchSession()` and a return gesture?
+2. **View-only vs interactive:** `switchSession` (full interactive takeover) or `loadEntriesFromFile` (read-only transcript built from JSONL)?
+3. **Parallel-agent navigation:** Operator gesture to select which of N background agents to view (from the widget, a command, or both).
+4. **Settings command name:** `/subagents-settings`, `/agents-settings`, or another form consistent with sibling packages?
+
+Produce a minimal spike (observed test or PoC against a real session) that answers each question, then record the answers as an addendum to ADR-0004.
+No production source files change; the spike closes when the ADR addendum is merged.
+
+Outcome: ADR-0004 updated with all four entry-criteria answers; Step 4 unblocked.
+
+`Release: independent`
+
+### Step 2 — Extract settings to a focused `/subagents-settings` command ([#447])
+
+Smell: Category E (naming/organization) — settings are buried inside the monolithic `/agents` command per ADR-0004 Decision C. This step is purely additive: it stands up the new surface without touching `agent-menu.ts`.
+Target files:
+
+- New `src/ui/subagents-settings.ts` — `SubagentsSettingsHandler` lifted from `AgentsMenuHandler.showSettings`, carrying its own narrow `SubagentsSettingsManager` interface (the three `apply*` methods and three readonly accessors only).
+- `src/index.ts` — register the new command (name confirmed by Step 1); pass `settings` directly.
+- New `test/ui/subagents-settings.test.ts` — unit tests for the extracted handler.
+
+`showSettings` depends only on `this.settings` (the self-contained `AgentMenuSettings` shape), so the extraction copies that logic into a new file with zero coupling to the wizard, editor, or viewer.
+The old in-menu Settings option keeps working until the terminal cut deletes `agent-menu.ts` wholesale — there is no surgical removal of `showSettings` or `AgentMenuSettings` from the doomed file.
+
+Outcome: new `subagents-settings.ts` (~80 LOC) and focused command registered; `agent-menu.ts` untouched.
+
+`Release: independent`
+
+### Step 3 — Shrink widget to background agents only ([#444])
+
+Smell: Category C (coupling) — the widget shows all agents including foreground ones, duplicating the `subagent` tool's inline `onUpdate` stream for foreground runs.
+Target files:
+
+- `src/ui/agent-widget.ts` — funnel both `manager.listAgents()` call sites (`update()` and `renderWidget()`) through a single private accessor, then flip that accessor to background-only via `record.invocation?.runInBackground === true`.
+- `src/ui/widget-renderer.ts` — verify no foreground-specific rendering path survives.
+- `test/ui/agent-widget.test.ts` — add background-only filtering tests; update assertions.
+
+The widget calls `listAgents()` at two sites today — `update()` (feeding `seedFinishedAgents`, `assembleWidgetState`, and `clearWidget`) and `renderWidget()` (the tree map).
+Filtering at only one site leaves the other rendering foreground agents, so the enabling move is to route both through one accessor and apply the predicate once at the source.
+`Subagent.invocation.runInBackground` is the reliable signal: set by `spawn-config.ts` → `AgentInvocation.runInBackground` → stored on `Subagent.invocation`.
+ADR-0004 Decision A: foreground runs suppress the widget; the inline `onUpdate` stream is authoritative there.
+
+Outcome: widget shows only background agents; foreground/widget duplication eliminated; the background predicate lives at a single funnel.
+
+`Release: independent`
 
-| Metric                                   | Value                                                              |
-| ---------------------------------------- | ------------------------------------------------------------------ |
-| Health score                             | 78/100 (B)                                                         |
-| Source LOC                               | 7,751 (62 files)                                                   |
-| Dead code                                | 0 files, 0 exports                                                 |
-| Maintainability index                    | 90.9 (good)                                                        |
-| Avg cyclomatic complexity                | 1.4                                                                |
-| P90 cyclomatic complexity                | 2                                                                  |
-| Fallow refactoring targets               | 0                                                                  |
-| Production duplication                   | 11 lines (1 internal clone group in `agent-config-editor.ts`)      |
-| Test duplication                         | 28 clone groups, 503 lines                                         |
-| Activity-tier modules slated for removal | `ui-observer.ts` (61) + `agent-activity-tracker.ts` (84) = 145 LOC |
-
-### 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](#first-principles-refinement-and-the-deeper-target) — 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.**
-   ([#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.
-4. **Make the widget self-drive from lifecycle events.**
-   ([#423]) Target: `ui/agent-widget.ts`, `lifecycle/subagent-manager.ts` (observer), `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.
-5. **Drop the widget and activity-map dependencies from the `subagent` tool.**
-   ([#424]) Target: `tools/agent-tool.ts`, `test/helpers/make-deps.ts`.
-   `AgentTool` loses its `widget` and `agentActivity` constructor params (UICtx capture stays in `ToolStartHandler`); `createToolDeps` sheds the widget and map stubs.
-   Smell: Category C/D.
-   Outcome: the LLM tool depends only on manager/runtime/settings/registry; fixture drops 2 fields.
-6. **Reconcile the public event contract.**
-   ([#425]) Target: `service/service.ts`, this document's lifecycle-events table.
-   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.
-7. **Consolidate residual test clone families.**
-   ([#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.
-8. **Reconsider the UI direction (first-principles ADR).**
-   ([#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.
+### Step 4 — Implement native session navigation ([#445])
+
+Smell: Category C (coupling) — the bespoke `ConversationViewer` re-implements session-transcript rendering when Pi's own machinery targets the already-persisted child session JSONL.
+This step adds the new surface alongside the existing viewer; it does not touch `agent-menu.ts`.
+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).
+
+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`).
+`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.
+
+`Release: independent` (spike-gated)
+
+### Step 5 — Dissolve `/agents` and remove the conversation-viewer subtree ([#442])
+
+Smell: Category A (dead subsystem) plus Category B (oversized) — once Steps 2–4 re-home all four menu responsibilities, the `/agents` command and everything reachable only from `agent-menu.ts` is an unreferenced subtree.
+This is the first of two deletion commits (split by subtree).
+The hub `agent-menu.ts` is deleted here, not surgically narrowed, and deleting it is what orphans the leaf subtrees — so it must precede the definition-management deletion (Step 6), because `agent-menu.ts` statically imports the wizard, editor, and file-ops, and dynamically imports the viewer.
+Target files:
+
+- `src/index.ts` — remove the `registerCommand("agents", …)` block, the `AgentsMenuHandler` construction and import, and the `FsAgentFileOps` import/construction (its only use is wiring the menu).
+- Delete `src/ui/agent-menu.ts` (331 LOC) and `test/ui/agent-menu.test.ts` (185 LOC).
+- Delete `src/ui/conversation-viewer.ts` (241 LOC) and `test/conversation-viewer.test.ts` (239 LOC) — its only consumer is `agent-menu.ts`'s dynamic import, gone with the hub.
+- Delete `src/ui/message-formatters.ts` (195 LOC) and `test/message-formatters.test.ts` (388 LOC, the largest test function by LOC) — its only consumer is `ConversationViewer`.
+
+Running-agent visibility is now owned by the background widget (Step 3); session navigation replaces the bespoke overlay (Step 4); settings live in `/subagents-settings` (Step 2).
+Deleting the hub in one move avoids any surgical edit to the doomed file and leaves the definition-management leaves orphaned for Step 6.
+
+Outcome: `/agents` dissolved; −767 LOC source (menu hub + viewer + formatters); −812 LOC test; largest test function eliminated; `index.ts` edited once (deregistration), never surgically narrowed.
+
+`Release: batch "dissolve-agents"`
+
+### Step 6 — Remove the orphaned agent-definition management subtree ([#441])
+
+Smell: Category A (dead subsystem) — the creation wizard and config editor are removed per ADR-0004 Decision C; after Step 5 deletes their only importer (`agent-menu.ts`), they and their file-ops helpers are pure orphans.
+This is the second deletion commit (split by subtree).
+Target files:
+
+- Delete `src/ui/agent-creation-wizard.ts` (233 LOC) and `test/ui/agent-creation-wizard.test.ts` (296 LOC).
+- Delete `src/ui/agent-config-editor.ts` (199 LOC) and `test/ui/agent-config-editor.test.ts` (392 LOC) — eliminates the 11-line internal production clone in `disableAgent`/`ejectAgent`, the package's only remaining production duplication.
+- Delete `src/ui/agent-file-ops.ts` (59 LOC) and `test/ui/agent-file-ops.test.ts` (112 LOC) — only consumers were wizard + editor.
+- Delete `src/ui/agent-file-writer.ts` (55 LOC) and `test/ui/agent-file-writer.test.ts` (148 LOC) — only consumers were wizard + editor.
+- `test/helpers/ui-stubs.ts` — delete `makeFileOps`, `createTestSubagentConfig`, and `spawnAndWait` from `makeMenuManager` if no surviving consumer remains; delete the file outright once all consumers are gone.
+
+An operator generates a new agent `.md` by asking a Pi session directly (more capable than a fixed wizard) or by writing the file in an editor; viewing and editing definitions is served by opening the `.md` files in an editor or IDE.
+These files are orphaned by Step 5, so this is a pure `git rm` with no surviving references and no edit to any doomed file.
+
+Outcome: −546 LOC source (wizard + editor + file-ops + file-writer); −948 LOC test; production duplication → 0 lines; 1 production and 1 test clone group eliminated.
+
+`Release: batch "dissolve-agents"`
+
+### Step 7 — Consolidate remaining test clone families ([#443])
+
+Smell: Category D (testability) — 16 clone groups at Phase 18 end; the terminal cut (Steps 5–6) removes ~4 groups; remaining groups are extraction targets.
+Run after the cut so no helper is extracted into a file the cut then deletes.
+Target files:
+
+- `test/lifecycle/subagent-manager.test.ts` — extract a shared assertion helper for 3 clone families (23 lines across groups at :92/:109, :282/:330, and :323 shared with `subagent.test.ts`).
+- `test/ui/agent-widget.test.ts` — merge the duplicate `makeWidget` helper defined twice across two `describe` blocks (14-line clone at :225/:284).
+- `test/session/session-config.test.ts` — extract a shared fixture for the 16-line internal clone (lines 131–146 / 151–166).
+- `test/lifecycle/concurrency-limiter.test.ts` — extract shared setup for the 10-line clone (lines 21–30 / 148–155).
+- `test/tools/spawn-config.test.ts` — extract a shared fixture for the 9-line clone (lines 22–30 / 35–43).
+
+Outcome: test clone groups ≤ 10 (from 16); `subagent-manager.test.ts` uses shared factory helpers.
+
+`Release: independent`
 
 ### 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
+flowchart LR
+    S1[✅ Step 1 - Spike (#446)]
+    S2[Step 2 - Settings command (#447)]
+    S3[Step 3 - Background widget (#444)]
+    S4[Step 4 - Native session nav (#445)]
+    S5[Step 5 - Dissolve /agents + viewer (#442)]
+    S6[Step 6 - Remove definition mgmt (#441)]
+    S7[Step 7 - Test clones (#443)]
+
+    S1 --> S4
+    S2 --> S5
+    S3 --> S5
+    S4 --> S5
+    S5 --> S6
+    S6 --> S7
 ```
 
+The terminal cut (Step 5) depends on all three replacements — settings (Step 2), widget (Step 3), and session navigation (Step 4) — because each of the four `/agents` options must have its responsibility re-homed before its branch can die.
+The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes it explicit.
+
 ### 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).
+- **Track A — Replacements (Steps 1–4):** the spike gates session navigation (Step 1 → Step 4); settings (Step 2) and the background widget (Step 3) are independent of the spike and of each other.
+  None of these steps edits `agent-menu.ts`, so they carry no shared-file collision on the menu — genuinely parallelizable, unlike the prior plan's Steps 2/3/5, which all collided on `agent-menu.ts` and `index.ts`.
+  Steps 2 and 4 each append a command registration to `index.ts` (additive, low-conflict).
+- **Track B — Dissolution (Steps 5 → 6):** the terminal cut, gated on all of Track A landing.
+  Hub-first ordering is forced: Step 5 deletes `agent-menu.ts` (orphaning the leaves), then Step 6 `git rm`s the now-orphaned definition-management subtree.
+- **Track C — Test health (Step 7):** clone consolidation, run after the cut so no surviving helper is extracted into a doomed file.
+
+### Release batches
+
+- **Batch "dissolve-agents":** Steps 5, 6 (ship together; tail = Step 6).
+  Depends on Steps 2, 3, 4 already merged.
+- Independently releasable: Steps 1, 2, 3, 4, 7.
 
 ## Refactoring history
 
-Phases 1–5, 7–17 are complete.
-Phase 6 (UI extraction to a separate package) is deferred → Phase 18.
+Phases 1–5, 7–18 are complete.
+Phase 6 (UI extraction to a separate package) was deferred to Phase 18; its intent was resolved by [ADR-0004] (Phase 18 Step 8).
 Detailed records are preserved in per-phase history files:
 
-| Phase | Title                                               | Status              | History                                                                              |
-| ----- | --------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------ |
-| 1     | Export SubagentsService API boundary                | Complete            | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
-| 2     | Remove scheduling subsystem                         | Complete            | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
-| 3     | Remove group-join, RPC; replace output-file         | Complete            | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
-| 4     | Implement and publish SubagentsService              | Complete            | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
-| 5     | Decompose index.ts                                  | Complete            | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
-| 6     | Extract UI to separate package                      | Deferred → Phase 18 | —                                                                                    |
-| 7     | Encapsulation and dependency narrowing              | Complete            | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
-| 8     | Testability, display extraction, menu decomposition | Complete            | [phase-8-testability.md](history/phase-8-testability.md)                             |
-| 9     | Observation consolidation, ctx elimination          | Complete            | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
-| 10    | Domain organization, bag decomposition, complexity  | Complete            | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
-| 11    | Closure factories to classes                        | Complete            | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
-| 12    | Complexity reduction and test fixture extraction    | Complete            | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
-| 13    | Remaining structural smells                         | Complete            | [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md)                 |
-| 14    | Strip policy from core                              | Complete            | [phase-14-strip-policy.md](history/phase-14-strip-policy.md)                         |
-| 15    | Domain model evolution                              | Complete            | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
-| 16    | Invert dependencies (extensions on a minimal core)  | Complete            | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
-| 17    | Core consolidation                                  | Complete            | [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md)             |
-| 18    | Reconsider UI (first principles)                    | In progress         | this document, [Phase 18](#phase-18-reconsider-ui-from-first-principles)             |
+| Phase | Title                                               | Status                 | History                                                                              |
+| ----- | --------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------ |
+| 1     | Export SubagentsService API boundary                | Complete               | [phase-1-api-boundary.md](history/phase-1-api-boundary.md)                           |
+| 2     | Remove scheduling subsystem                         | Complete               | [phase-2-remove-scheduling.md](history/phase-2-remove-scheduling.md)                 |
+| 3     | Remove group-join, RPC; replace output-file         | Complete               | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
+| 4     | Implement and publish SubagentsService              | Complete               | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
+| 5     | Decompose index.ts                                  | Complete               | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
+| 6     | Extract UI to separate package                      | Superseded by ADR-0004 | —                                                                                    |
+| 7     | Encapsulation and dependency narrowing              | Complete               | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
+| 8     | Testability, display extraction, menu decomposition | Complete               | [phase-8-testability.md](history/phase-8-testability.md)                             |
+| 9     | Observation consolidation, ctx elimination          | Complete               | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
+| 10    | Domain organization, bag decomposition, complexity  | Complete               | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
+| 11    | Closure factories to classes                        | Complete               | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
+| 12    | Complexity reduction and test fixture extraction    | Complete               | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
+| 13    | Remaining structural smells                         | Complete               | [phase-13-remaining-smells.md](history/phase-13-remaining-smells.md)                 |
+| 14    | Strip policy from core                              | Complete               | [phase-14-strip-policy.md](history/phase-14-strip-policy.md)                         |
+| 15    | Domain model evolution                              | Complete               | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
+| 16    | Invert dependencies (extensions on a minimal core)  | Complete               | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
+| 17    | Core consolidation                                  | Complete               | [phase-17-core-consolidation.md](history/phase-17-core-consolidation.md)             |
+| 18    | Reconsider UI (first principles)                    | Complete               | [phase-18-reconsider-ui.md](history/phase-18-reconsider-ui.md)                       |
 
 ### Structural refactoring issues
 
@@ -1084,6 +1144,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 16 (abandoned) | #256 (superseded), #257 (parked), #258, #259 (not planned) | Agent collaborator architecture — replaced by the inversion approach above ([ADR-0002])                                                                                                        |
 | Phase 17             | #381, #373, #374, #375, #376, #377, #378, #379, #380       | ConcurrencyLimiter, SubagentState, run-start encapsulation, run collaborators, events observer, widget decoupling, lifecycle test fixtures, UI/tools test fixtures, settings-loader extraction |
 | Phase 17 (follow-on) | #412, #415                                                 | Session-mock builder unification, worktrees settings-helper migration                                                                                                                          |
+| Phase 18             | #420, #421, #422, #423, #424, #425, #426, #427             | Fold metrics onto record, migrate readers, delete activity tier, widget self-drives, drop widget from tool, reconcile event contract, consolidate test clones, UI-direction ADR                |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -1147,4 +1208,12 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#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
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#443]: https://github.com/gotgenes/pi-packages/issues/443
+[#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
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md
+[ADR-0004]: ../decisions/0004-reconsider-ui-direction.md