@gotgenes/pi-subagents 17.5.0 → 18.0.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## [18.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.5.0...pi-subagents-v18.0.0) (2026-06-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-subagents:** The /agents command is removed. Its responsibilities are now served by: /subagents:settings (configure concurrency and turn limits), /subagents:sessions (read-only session transcript viewing), and the always-on background widget (running-agent visibility).
+* **pi-subagents:** the /subagents-settings and /subagent-sessions commands are renamed to /subagents:settings and /subagents:sessions.
+
+### Features
+
+* **pi-subagents:** dissolve /agents and remove the conversation-viewer subtree ([cb813f2](https://github.com/gotgenes/pi-packages/commit/cb813f2c5fac7c0b5fa62eecf7f0665671382c1c))
+* **pi-subagents:** namespace commands under subagents: ([23bf99e](https://github.com/gotgenes/pi-packages/commit/23bf99e8662a2b89b2816a14e5f2801fd6c74159))
+
 ## [17.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.4.0...pi-subagents-v17.5.0) (2026-06-23)
 
 

package/docs/architecture/architecture.md

@@ -81,8 +81,8 @@ flowchart TB
     subgraph ui["UI domain"]
         direction TB
         Widget["agent-widget<br/>(live status)"]
-        ConvViewer["conversation-viewer<br/>(session overlay)"]
-        Menu["agent-menu<br/>(slash command)"]
+        Sessions["session-navigator<br/>(session view)"]
+        Settings["subagents-settings<br/>(settings command)"]
     end
 
     AgentTool --> SubagentManager
@@ -341,14 +341,10 @@ src/
 ├── ui/                             user-facing presentation
 │   ├── agent-widget.ts             above-editor live status widget
 │   ├── widget-renderer.ts          pure rendering for widget
-│   ├── agent-menu.ts               /agents slash command menu
-│   ├── agent-config-editor.ts      agent detail/edit view (AgentConfigEditor class)
-│   ├── 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-file-ops.ts           filesystem abstraction
-│   ├── agent-file-writer.ts        overwrite-guard + write + reload + notify helper
-│   └── display.ts                  pure formatters and shared types
+│   ├── display.ts                  pure formatters and shared types
+│   ├── subagents-settings.ts       /subagents:settings command handler
+│   ├── session-navigation.ts       pure session-selection and transcript-source logic
+│   └── session-navigator.ts        /subagents:sessions command handler
 │
 └── handlers/                       event handlers
     ├── index.ts                    barrel re-export
@@ -363,7 +359,7 @@ Record statistics (tool uses, token usage, compaction counts) and live activity
 This is the single per-child session subscription — all run state lives on the `Subagent` record.
 
 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).
+The `/subagents:sessions` navigator reads messages via `Subagent.agentMessages` and subscribes to updates via `Subagent.subscribeToUpdates()` — no direct `AgentSession` reference (#277).
 
 ## Cross-extension architecture
 
@@ -373,7 +369,7 @@ flowchart TD
         direction TB
         exports["SubagentsService API<br/>publish / getSubagentsService<br/>SubagentRecord, SubagentStatus"]
         engine["Tools: subagent, get_subagent_result,<br/>steer_subagent<br/>SubagentManager, createSubagentSession, SubagentSession"]
-        ui_int["Internal UI: widget, viewer,<br/>/agents menu"]
+        ui_int["Internal UI: widget, session-navigator,<br/>subagents-settings"]
     end
 
     core -- "Symbol.for on globalThis" --> sched["scheduling extension<br/>(hypothetical)"]
@@ -406,7 +402,7 @@ They declare this package as an optional peer dependency and use dynamic import
 - Token usage tracking.
 - Session directory derivation and persisted `SessionManager` for subagent transcripts.
 - Settings persistence.
-- Internal UI (widget, conversation viewer, `/agents` menu) — these stay until the API boundary is proven, then move to a separate extension.
+- Internal UI (widget, `/subagents:sessions` session navigator, `/subagents:settings` command) — the conversation viewer and `/agents` menu were removed in Phase 19 (Steps 5–6, [#442], [#441]) per [ADR-0004].
 
 ### What the core dropped
 
@@ -560,7 +556,7 @@ In the target state, pi-subagents publishes events and a provider seam; other pa
 
 - **pi-permission-system** (observational) subscribes to child-session lifecycle events, detects subagent execution context in the child, and gates tool calls at runtime.
 - **pi-subagents-worktrees** (generative) registers a `WorkspaceProvider` that prepares a git worktree at run-start and tears it down after, supplying the child's cwd.
-- **pi-subagents-ui** (future, under reconsideration — see the [first-principles refinement](#first-principles-refinement-and-the-deeper-target)) subscribes to the broadcast and the query/behavior interfaces; whether the inherited widget, conversation viewer, and `/agents` menu survive is judged on our principles, not preserved by default.
+- **pi-subagents-ui** (future, under reconsideration — see the [first-principles refinement](#first-principles-refinement-and-the-deeper-target)) subscribes to the broadcast and the query/behavior interfaces; the conversation viewer and `/agents` menu were removed in Phase 19 per [ADR-0004]; the surviving UI (widget, session navigator, settings command) stays in-core.
 - **Any future extension** (OTel, auditing, cost tracking) subscribes to the same events without pi-subagents knowing.
 
 Composition test: install neither extension, only permissions, only workspaces, or both — the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
@@ -1055,7 +1051,7 @@ Coverage is in-session evictions (the sweep's only targets); old-session orphan
 
 `Release: independent`
 
-### Step 5 — Dissolve `/agents` and remove the conversation-viewer subtree ([#442])
+### ✅ 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).
@@ -1070,11 +1066,16 @@ Target files:
 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.
+Actual approach (vs. original plan): a tidy-first preparatory commit first extracted `MenuUI` from `agent-menu.ts` into a new `src/ui/menu-ui.ts` module, breaking the bidirectional type cycle — the hub imported the wizard/editor classes while the leaves imported back the `MenuUI` type.
+Without the prep commit, deleting either subtree first would have left the other half referencing a deleted module.
+`index.ts` also shed the now-dead `join` (node:path) and `buildParentSnapshot` imports in addition to the two module imports.
+The `menu-ui.ts` module is transient and is removed with the wizard/editor in Step 6.
+
+Outcome: ✅ `/agents` dissolved; −767 LOC source (menu hub + viewer + formatters); −812 LOC test; largest test function eliminated; `index.ts` dewired.
 
 `Release: batch "dissolve-agents"`
 
-### Step 6 — Remove the orphaned agent-definition management subtree ([#441])
+### ✅ 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).
@@ -1091,6 +1092,10 @@ These files are orphaned by Step 5, so this is a pure `git rm` with no surviving
 
 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.
 
+Landed ([#441]): deleted `agent-creation-wizard.ts`, `agent-config-editor.ts`, `agent-file-ops.ts`, `agent-file-writer.ts`, and `menu-ui.ts` (orphaned transient) from `src/ui/`, plus their four test files.
+`test/helpers/ui-stubs.ts` pruned to `makeMenuUI` only (still consumed by `subagents-settings.test.ts`); `makeFileOps`, `makeMenuManager`, and `createTestSubagentConfig` removed with their `ui-stubs.test.ts` describe blocks.
+Production duplication: 0 lines (confirmed by `fallow dupes`); `fallow dead-code`: clean. 16 test clone groups remain — Step 7 consolidation target.
+
 `Release: batch "dissolve-agents"`
 
 ### Step 7 — Consolidate remaining test clone families ([#443])
@@ -1119,8 +1124,8 @@ flowchart LR
     S4["✅ Step 4 - Native session nav slice (#445)"]
     S4a["✅ Step 4a - Renderer to TUI components (#462)"]
     S4b["✅ Step 4b - File-snapshot source (#463)"]
-    S5["Step 5 - Dissolve /agents + viewer (#442)"]
-    S6["Step 6 - Remove definition mgmt (#441)"]
+    S5["✅ Step 5 - Dissolve /agents + viewer (#442)"]
+    S6["✅ Step 6 - Remove definition mgmt (#441)"]
     S7["Step 7 - Test clones (#443)"]
 
     S1 --> S4

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

@@ -255,6 +255,23 @@ The cleanup sweep instead stashes a lightweight `EvictedSubagent` descriptor (la
 This covers in-session evictions — the sweep's only targets, since a fresh manager per session never reloads prior-process subagents.
 The "render from the file snapshot" mechanism for an evicted agent (above) is unchanged; only the candidate-set _enumeration_ is pinned to descriptors.
 
+## Addendum 3 (2026-06-23): adopt the `subagents:` colon namespace, superseding Criterion 4
+
+This addendum reverses **Criterion 4**, which confirmed flat, hyphenated command names (`/subagents-settings`) and rejected `/subagents:settings`.
+The two registered commands are renamed: `/subagents-settings` → `/subagents:settings` and `/subagent-sessions` → `/subagents:sessions`.
+This is a breaking change to the command surface.
+
+**Why revise.**
+Criterion 4 surveyed only in-repo siblings (`agents`, `colgrep-reindex`, `permission-system`) and concluded a `:` namespace would be inconsistent with every existing command.
+That survey missed the broader Pi ecosystem: `@eko24ive/pi-ask` establishes the colon convention with `answer:again` and `ask:replay`, grouping a package's commands under a shared prefix.
+The colon namespace reads as a deliberate grouping gesture (`subagents:settings`, `subagents:sessions` clearly belong to one package) where the hyphen form blurs into an ordinary command name.
+The newer ecosystem signal outweighs the original in-repo-only consistency argument.
+
+**Scope.**
+This change is pi-subagents-only.
+Whether the colon convention becomes repo-wide (renaming `colgrep-reindex`, `permission-system`, etc.) is deferred — not decided here.
+`/agents` is intentionally left flat: it is slated for removal in the Phase 18 / Step 5 menu retirement, so namespacing it would be churn on a command being deleted.
+
 [#444]: https://github.com/gotgenes/pi-packages/issues/444
 [#445]: https://github.com/gotgenes/pi-packages/issues/445
 [#446]: https://github.com/gotgenes/pi-packages/issues/446

package/docs/plans/0441-remove-agent-definition-management-subtree.md

@@ -0,0 +1,180 @@
+---
+issue: 441
+issue_title: "pi-subagents: remove the orphaned agent-definition management subtree"
+---
+
+# Remove the orphaned agent-definition management subtree
+
+## Release Recommendation
+
+**Release:** ship now — batch "dissolve-agents" tail (this issue completes the batch)
+
+This issue is Phase 19 Step 6, the tail of release batch "dissolve-agents" (Steps 5–6) in `docs/architecture/architecture.md`.
+Step 5 ([#442], commit `cb813f2c`) landed a breaking `feat(pi-subagents)!:` that is still **unreleased** — it sits after the latest tag `pi-subagents-v17.5.0`.
+Landing this tail completes the batch and lets release-please cut the major bump that carries Step 5's `/agents` removal.
+
+## Problem Statement
+
+ADR-0004 Decision C removes both agent-definition surfaces: creating a new agent is better done by asking a Pi session directly (more capable than a fixed wizard) or by writing the `.md` file in an editor, and viewing or editing definitions is better served by opening the `.md` files in an editor or IDE.
+Phase 19 Step 5 ([#442]) deleted `agent-menu.ts` — the only importer of the creation wizard, config editor, and their file-ops helpers — so this subtree is now pure dead code.
+This step is the second of two deletion commits in the Phase 19 terminal cut: a clean `git rm` of the orphaned modules, with no surviving references and no edit to any doomed file.
+
+## Goals
+
+- Delete the orphaned creation wizard, config editor, and their two file-ops helper modules, plus their tests.
+- Delete the transient `menu-ui.ts` module, orphaned once its only consumers (the wizard and editor) are gone.
+- Prune the now-unused helpers from `test/helpers/ui-stubs.ts`, keeping only the helper a surviving test still uses.
+- Drive the package's remaining production duplication to zero (the 11-line internal clone in `disableAgent`/`ejectAgent` dies with `agent-config-editor.ts`).
+- This is **not** a breaking change at this step: the modules are already unreachable after Step 5, so deleting them changes no observable behavior — the user-facing removal already shipped (unreleased) in Step 5's `feat!:`.
+
+## Non-Goals
+
+- No change to `index.ts` — it already references none of the deleted symbols (verified by grep); the dewiring happened in Step 5.
+- No change to the surviving UI modules (`agent-widget.ts`, `display.ts`, `session-navigation.ts`, `session-navigator.ts`, `subagents-settings.ts`, `widget-renderer.ts`).
+- No change to `subagents-settings.ts`, which carries its own `SubagentsSettingsUI` interface and never depended on `MenuUI`.
+- Test clone consolidation (Phase 19 Step 7, [#443]) — runs after this cut so no surviving helper is extracted into a doomed file.
+
+## Background
+
+Relevant modules and their current dependency facts (verified against `main`):
+
+- `src/ui/agent-creation-wizard.ts` (235 LOC) — `AgentCreationWizard` class; imports `AgentFileOps`, `writeAgentFile`, and `MenuUI` from its siblings.
+- `src/ui/agent-config-editor.ts` (201 LOC) — `AgentConfigEditor` class plus `buildMenuOptions`/`buildEjectContent`; imports `AgentFileOps`, `writeAgentFile`, and `MenuUI`.
+  Contains the package's only remaining production clone (the 11-line `disableAgent`/`ejectAgent` block).
+- `src/ui/agent-file-ops.ts` (59 LOC) — `AgentFileOps` interface + `FsAgentFileOps`; only consumers were the wizard and editor.
+- `src/ui/agent-file-writer.ts` (55 LOC) — `writeAgentFile` + narrow interfaces; only consumers were the wizard and editor.
+- `src/ui/menu-ui.ts` (9 LOC) — the `MenuUI` interface, extracted in Step 5's tidy-first prep commit (`bb03efd7`) to break a bidirectional type cycle.
+  After this step deletes the wizard and editor, `menu-ui.ts` has zero importers.
+  The architecture doc marks it for removal here: its current-state directory listing reads `menu-ui.ts transient: MenuUI interface (removed with wizard/editor in #441)` (line 346), and the Step 5 entry states "The `menu-ui.ts` module is transient and is removed with the wizard/editor in Step 6" (line 1076).
+
+Orphan verification (grep across `src/`, excluding the doomed files themselves): **no** surviving importer of any of the five modules or their exported symbols (`AgentCreationWizard`, `AgentConfigEditor`, `FsAgentFileOps`, `writeAgentFile`, `MenuUI`).
+`src/index.ts` references none of them.
+
+Test-helper facts (`test/helpers/ui-stubs.ts`), evaluated **after** the four doomed test files are deleted:
+
+- `makeMenuUI` — still imported by `test/ui/subagents-settings.test.ts` → **survives**.
+- `makeFileOps` — only remaining importer is its own self-test `ui-stubs.test.ts` → orphan.
+- `makeMenuManager` (including the wizard `spawnAndWait` relay) — only remaining importer is `ui-stubs.test.ts` → orphan.
+- `createTestSubagentConfig` (and its private `DEFAULT_TEST_AGENT_CONFIG`) — only remaining importer is `ui-stubs.test.ts` → orphan.
+
+AGENTS.md constraints that apply:
+
+- Run `pnpm fallow dead-code` locally before pushing — CI gates on it.
+- Conventional Commits; reference the issue as `(#441)` in the subject, never `Closes #441`.
+- `pnpm` only; package-scoped scripts via `pnpm --filter @gotgenes/pi-subagents`.
+
+## Design Overview
+
+This is a deletion-only change — no new collaborators, no shared-interface edits, no behavior moved.
+There is nothing to extract and no decision model beyond "delete the orphans, leave `fallow` clean."
+
+Two clarifications where the issue body is less precise than the authoritative architecture doc:
+
+1. **`menu-ui.ts` is in scope.**
+   The issue body's "Proposed change" lists only the four modules, but `menu-ui.ts` is orphaned by the same cut and the architecture doc (lines 346, 1076) explicitly schedules its removal here.
+   Deleting it in the same commit as the wizard/editor avoids a dangling `import type { MenuUI }` and a `fallow dead-code` flag.
+
+2. **`makeMenuManager` is removed whole, not just its `spawnAndWait` field.**
+   The issue body says to prune the "wizard `spawnAndWait` relay," but after the four test files are deleted, `makeMenuManager`'s only remaining caller is its own self-test.
+   A test helper whose sole consumer is its own unit test is exactly the residual clutter the Phase 19 cut eliminates, so the whole helper (and its `describe` block) goes.
+   The architecture doc's Step 6 phrasing — "delete … `spawnAndWait` from `makeMenuManager` **if no surviving consumer remains**; delete the file outright once all consumers are gone" — licenses this: no real consumer remains.
+   `ui-stubs.ts` itself survives because `makeMenuUI` still has a real consumer.
+
+End state of `test/helpers/ui-stubs.ts`: a single `makeMenuUI` export plus its file header.
+End state of `test/helpers/ui-stubs.test.ts`: the `makeMenuUI` `describe` block only.
+
+Commit-type rationale: deleting already-unreachable code is `refactor(pi-subagents):` — it neither adds a feature nor fixes a bug, and it changes no observable behavior at this step.
+The release is driven by Step 5's unreleased `feat!:` already in the queue, not by this commit's type.
+
+## Module-Level Changes
+
+Source (deleted):
+
+- `src/ui/agent-creation-wizard.ts` — deleted (235 LOC).
+- `src/ui/agent-config-editor.ts` — deleted (201 LOC); removes the 11-line internal production clone.
+- `src/ui/agent-file-ops.ts` — deleted (59 LOC).
+- `src/ui/agent-file-writer.ts` — deleted (55 LOC).
+- `src/ui/menu-ui.ts` — deleted (9 LOC); orphaned once the wizard and editor are gone.
+
+Tests (deleted):
+
+- `test/ui/agent-creation-wizard.test.ts` — deleted (296 LOC).
+- `test/ui/agent-config-editor.test.ts` — deleted (392 LOC).
+- `test/ui/agent-file-ops.test.ts` — deleted (112 LOC).
+- `test/ui/agent-file-writer.test.ts` — deleted (148 LOC).
+
+Tests (pruned, not deleted):
+
+- `test/helpers/ui-stubs.ts` — remove `makeFileOps`, `makeMenuManager`, `createTestSubagentConfig`, and the private `DEFAULT_TEST_AGENT_CONFIG`; keep `makeMenuUI`.
+  Also drop the file's `import type { AgentConfig }` — it serves only the removed helpers, and `makeMenuUI` references no package-local type.
+- `test/helpers/ui-stubs.test.ts` — remove the `makeFileOps`, `makeMenuManager`, and `createTestSubagentConfig` `describe` blocks and the now-unused imports; keep the `makeMenuUI` `describe` block.
+
+Docs (updated):
+
+- `docs/architecture/architecture.md` — in the current-state directory tree (lines ~341–346), remove the five deleted `ui/` entries including the `menu-ui.ts` transient line; add a `Landed` note to the Step 6 entry and mark it ✅, mirroring the Step 5 entry's format.
+- `.pi/skills/package-pi-subagents/SKILL.md` — update the UI domain-table row: module count `11` → `6`, and drop "creation wizard, config editor" from the responsibility summary.
+
+Doc-reference grep results (the removed symbols / mechanism):
+
+- `docs/plans/*` and `docs/retro/*` and `docs/architecture/history/*` mention the deleted modules only as **historical record** of prior phases (extraction, narrowing, clone removal).
+  Per markdown conventions these are immutable records of completed work — do not rewrite them.
+- The only **current-state** docs that describe the live layout are `architecture.md` (directory tree + Step 6 entry) and `SKILL.md` (UI domain row), both listed above.
+
+## Test Impact Analysis
+
+This is a deletion, not an extraction, so the standard extraction lenses invert:
+
+1. **New tests enabled:** none — nothing new is created.
+2. **Tests that become redundant:** all four deleted test files exercised only the deleted modules; they go with their subjects.
+   The three pruned `ui-stubs.test.ts` `describe` blocks tested helpers that no longer exist.
+3. **Tests that must stay as-is:** `test/ui/subagents-settings.test.ts` (the surviving real consumer of `makeMenuUI`) and the `makeMenuUI` `describe` block in `ui-stubs.test.ts` — both genuinely exercise the surviving helper.
+
+After the cut, `pnpm --filter @gotgenes/pi-subagents run test` must stay green with the reduced suite.
+
+## Invariants at risk
+
+This step touches surfaces that Phase 19 Step 5 ([#442]) and earlier phases refactored, but only by deleting them, so no earlier `Outcome:` is regressed — it is fulfilled:
+
+- Step 5's outcome ("`/agents` dissolved; the definition-management leaves orphaned for Step 6") is the precondition this step consumes.
+  Verification that the leaves are still orphaned is the grep in Background (no surviving importer) — the standing guarantee that nothing re-wired them between Step 5 landing and this step.
+- The "production duplication → 0 lines" target in the Phase 19 health-metrics table is met when `agent-config-editor.ts` is deleted.
+  Pin: `pnpm fallow dupes` after the cut shows no production clone group.
+
+No green-suite regression risk exists because no surviving code path is modified; the type checker and `fallow dead-code` are the guards that the deletion is complete and clean.
+
+## Step Order
+
+This is a pure-deletion plan with no red→green cycles, so it routes to `/build-plan`, not `/tdd-plan`.
+Two commits, ordered for reviewability.
+
+1. **Remove the orphaned subtree and prune the test helpers.**
+   `git rm` the five source modules and four test files; prune `test/helpers/ui-stubs.ts` and `test/helpers/ui-stubs.test.ts` to `makeMenuUI` only.
+   The `menu-ui.ts` deletion and the four-module deletion go together — deleting them in one commit means no dangling `import type { MenuUI }` ever exists at the type-check boundary.
+   The helper prune rides in the same commit as the test-file deletion that orphans the helpers, so `fallow dead-code` sees a consistent state.
+   Verify: `pnpm --filter @gotgenes/pi-subagents run check`, `… run test`, `pnpm fallow dead-code`, and `pnpm fallow dupes` (expect no production clone group) all green.
+   Commit: `refactor(pi-subagents): remove orphaned agent-definition management subtree (#441)`.
+
+2. **Update the current-state docs.**
+   Edit `docs/architecture/architecture.md` (directory tree + Step 6 `Landed`/✅ note) and `.pi/skills/package-pi-subagents/SKILL.md` (UI domain row count + summary).
+   Verify: `pnpm run lint` (rumdl) green.
+   Commit: `docs(pi-subagents): record agent-definition subtree removal (#441)`.
+
+## Risks and Mitigations
+
+- **Risk:** a non-obvious importer of one of the five modules exists and the deletion breaks the type check.
+  **Mitigation:** the Background grep already confirms zero `src/` importers and `index.ts` is clean; the Step 1 `check` is the backstop.
+- **Risk:** pruning `ui-stubs.ts` removes a helper a surviving test still imports.
+  **Mitigation:** verified `makeMenuUI` is the only helper imported outside the doomed test files (by `subagents-settings.test.ts`); it is explicitly kept.
+- **Risk:** deleting `menu-ui.ts` was not anticipated by the issue body and could be seen as scope creep.
+  **Mitigation:** it is mandated by the architecture doc (lines 346, 1076) and is a forced consequence of the orphan analysis; documented in Design Overview.
+- **Risk:** `refactor:` commit type fails to trigger the batch release.
+  **Mitigation:** Step 5's unreleased `feat(pi-subagents)!:` (`cb813f2c`, after `v17.5.0`) is already queued; release-please cuts the major bump on the next release regardless of this commit's type.
+  `/ship-issue` reads the `**Release:** ship now — batch tail` marker and releases.
+
+## Open Questions
+
+None.
+The two interpretation points (deleting `menu-ui.ts`; removing `makeMenuManager` whole) are resolved in Design Overview against the authoritative architecture doc and orphan analysis, not deferred.
+
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#443]: https://github.com/gotgenes/pi-packages/issues/443

package/docs/plans/0442-dissolve-agents-conversation-viewer.md

@@ -0,0 +1,195 @@
+---
+issue: 442
+issue_title: "pi-subagents: dissolve /agents and remove the conversation-viewer subtree"
+---
+
+# Dissolve `/agents` and remove the conversation-viewer subtree
+
+## Release Recommendation
+
+**Release:** mid-batch — defer (batch "dissolve-agents"); confirm at ship time
+
+This is Phase 19 Step 5, the first of the two deletion commits in release batch "dissolve-agents" (Steps 5–6).
+The batch tail is Step 6 ([#441]); per the architecture roadmap's `Release batches` subsection the two ship together, and the operator has confirmed: do not release until both [#442] and [#441] have landed on `main`.
+Hold the release-please PR open after this issue merges; the release is cut when [#441] (the tail) lands.
+
+## Problem Statement
+
+Phase 19 Steps 2–4 re-homed all four `/agents` menu responsibilities: settings moved to the `/subagents:settings` command, running-agent visibility moved to the background widget, and session viewing moved to native session navigation (`/subagents:sessions`).
+With those replacements live, the `/agents` command and everything reachable only from `agent-menu.ts` is an orphaned subtree.
+This issue performs the first of two terminal-cut deletions: dissolve the `/agents` command and delete the conversation-viewer subtree (`agent-menu.ts`, `conversation-viewer.ts`, `message-formatters.ts`, and their tests).
+Deleting the hub `agent-menu.ts` wholesale — rather than surgically narrowing it once per option — is what orphans the definition-management leaves, so the hub must go first (it statically imports the wizard, editor, and file-ops, and dynamically imports the viewer).
+
+## Goals
+
+- Remove the `/agents` slash command and its menu hub (`agent-menu.ts`).
+- Delete the conversation-viewer subtree: `conversation-viewer.ts` (the bespoke session overlay) and `message-formatters.ts` (its only consumer), plus all three tests.
+- Dewire `index.ts`: drop the `registerCommand("agents", …)` block, the `AgentsMenuHandler` and `FsAgentFileOps` imports/construction, and the now-dead `join` and `buildParentSnapshot` imports.
+- Keep `pnpm run check`, `pnpm run lint`, `pnpm run test`, and `pnpm fallow dead-code` green at every commit by breaking the hub↔leaf type cycle first (see Design Overview).
+- Leave the agent-definition-management leaves (`agent-creation-wizard.ts`, `agent-config-editor.ts`, `agent-file-ops.ts`, `agent-file-writer.ts`) orphaned but compiling, for [#441] to `git rm`.
+
+This change is **breaking**: removing the `/agents` command alters observable behavior on upgrade with no user edit.
+The deletion commit uses `feat(pi-subagents)!:` with a `BREAKING CHANGE:` footer naming the replacements (`/subagents:settings`, `/subagents:sessions`, the background widget).
+
+## Non-Goals
+
+- Deleting the agent-definition-management subtree (`agent-creation-wizard.ts`, `agent-config-editor.ts`, `agent-file-ops.ts`, `agent-file-writer.ts`) and the transient `menu-ui.ts` — that is [#441] (Step 6), the batch tail.
+- Consolidating residual test clone families — that is [#443] (Step 7), which runs after the cut.
+- Cleaning up `test/helpers/ui-stubs.ts` (`makeFileOps`, `makeMenuManager`, `createTestSubagentConfig`) — its helpers still have surviving consumers (the wizard/editor tests) until [#441].
+- The holistic architecture-doc refresh (health-metrics final numbers, the domain Mermaid diagram, the complexity tables, migrating Phase 19 to `docs/architecture/history/`) — deferred to the batch tail [#441] to avoid editing the same analytical tables twice, since they also reference files [#441] deletes.
+
+## Background
+
+Relevant modules and their current coupling:
+
+- `src/ui/agent-menu.ts` (331 LOC) — the `AgentsMenuHandler` god-command; statically imports `AgentConfigEditor` and `AgentCreationWizard` (constructs them), and dynamically imports `ConversationViewer` in `viewAgentConversation`.
+  Defines three exported interfaces: `AgentMenuManager`, `AgentMenuSettings`, and `MenuUI`.
+- `src/ui/conversation-viewer.ts` (241 LOC) — the bespoke scrollable session overlay; its only consumer is `agent-menu.ts`'s dynamic `import("./conversation-viewer")`.
+- `src/ui/message-formatters.ts` (195 LOC) — pure per-message-type formatters; its only consumer is `ConversationViewer`.
+- `src/index.ts` — registers the `/agents` command, constructs `AgentsMenuHandler` (wiring in `FsAgentFileOps` and the two agents dirs), and uses `join` + `buildParentSnapshot` only inside that block.
+
+The hub↔leaf type cycle (the key constraint):
+
+- `agent-menu.ts` value-imports the wizard and editor classes.
+- `agent-creation-wizard.ts` and `agent-config-editor.ts` each `import type { MenuUI } from "#src/ui/agent-menu"` and use `MenuUI` as a parameter type throughout.
+
+This is a bidirectional cycle: the hub imports the leaf classes; the leaves import the hub's `MenuUI` type.
+Deleting either subtree first leaves the other half referencing a deleted module, so `tsc --noEmit` (which type-checks all of `src` + `test`) fails.
+The issue's premise that the leaves become "pure orphans" once the hub is gone holds for *runtime* reachability but not at the *type* level — the `MenuUI` back-import keeps them coupled.
+
+Constraints from AGENTS.md / package skill:
+
+- Each commit must leave the repo in a valid state (`pnpm run check` green).
+- This package builds public `.d.ts` bundles; none of the deleted modules are part of the public surface (`service.ts`, `layered-settings.ts`), so no `verify:public-types` impact.
+- `MenuUI`, `AgentMenuManager`, `AgentMenuSettings` are internal — not exported from any package subpath.
+
+## Design Overview
+
+Resolve the cycle with a **tidy-first** preparatory move (per the operator's decision and the `code-design` skill's "preparatory refactoring"): relocate the `MenuUI` interface to its own surviving module before deleting the hub.
+
+Only `MenuUI` needs to survive the cut — `AgentMenuManager` and `AgentMenuSettings` have no consumers outside the hub (verified) and die with it.
+`MenuUI` is self-contained (its members reference only SDK-shaped primitives), so the extracted module carries no upstream-dependency baggage and introduces no Tell-Don't-Ask or output-argument smell.
+
+New module `src/ui/menu-ui.ts`:
+
+```typescript
+/** Narrow UI interface — only the ctx.ui methods menu handlers actually call. */
+export interface MenuUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  confirm(title: string, message: string): Promise<boolean>;
+  input(title: string, defaultValue?: string): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  editor(title: string, content: string): Promise<string | undefined>;
+  custom<R>(component: any, options?: any): Promise<R>;
+}
+```
+
+Consumer call sites after the move (the leaves import the relocated type unchanged):
+
+```typescript
+// agent-creation-wizard.ts / agent-config-editor.ts
+import type { MenuUI } from "#src/ui/menu-ui";
+async showCreateWizard(ui: MenuUI, parentSnapshot: ParentSnapshot): Promise<void> { … }
+```
+
+`menu-ui.ts` is **transient**: after this issue it is imported only by the wizard and editor (both alive until [#441]), so it has live consumers and stays off the fallow dead-code list.
+[#441] deletes the wizard, editor, and `menu-ui.ts` together, so the transient module never outlives its consumers.
+
+Two-commit sequence within this issue:
+
+1. `refactor(pi-subagents): extract MenuUI to its own module` — pure move; repoints the hub, wizard, and editor imports.
+   Green.
+2. `feat(pi-subagents)!: dissolve /agents and remove the conversation-viewer subtree` — delete the three source files + three tests, dewire `index.ts`, update docs.
+   Green (wizard/editor now import `MenuUI` from the surviving `menu-ui.ts`; the hub is gone).
+
+Edge cases / verifications already confirmed:
+
+- `subagents-settings.ts` defines its own `SubagentsSettingsUI` interface — it does **not** import `MenuUI`, so the relocation does not touch the surviving settings command.
+- `test/helpers/ui-stubs.ts`'s `makeMenuUI` is structurally typed and does **not** import the `MenuUI` type, so no test-helper repointing is needed.
+- After dewiring, `join` (node:path) and `buildParentSnapshot` are used nowhere else in `index.ts` (verified) and their imports are removed; `getAgentDir`, `process.cwd`, `registry`, `settings`, and `manager` retain other live uses and stay.
+- `FsAgentFileOps` becomes production-unused after the `index.ts` construction is removed, but `test/ui/agent-file-ops.test.ts` still imports it, so fallow (syntactic import analysis) keeps it off the dead-code list until [#441].
+- Deleting the consumers does not orphan any local export: `formatDuration`/`getDisplayName`/`getModelLabelFromConfig` retain other consumers, and `wrapTextWithAnsi` is an external `@earendil-works/pi-tui` import.
+
+## Module-Level Changes
+
+Commit 1 — extract `MenuUI` (refactor):
+
+- Add `src/ui/menu-ui.ts` — the `MenuUI` interface (moved verbatim from `agent-menu.ts`).
+- `src/ui/agent-menu.ts` — remove the `MenuUI` interface definition; import `MenuUI` from `#src/ui/menu-ui`.
+- `src/ui/agent-creation-wizard.ts` — change `import type { MenuUI } from "#src/ui/agent-menu"` to `from "#src/ui/menu-ui"`.
+- `src/ui/agent-config-editor.ts` — same import repoint.
+
+Commit 2 — dissolve `/agents` and delete the viewer subtree (feat!):
+
+- Delete `src/ui/agent-menu.ts`, `src/ui/conversation-viewer.ts`, `src/ui/message-formatters.ts`.
+- Delete `test/ui/agent-menu.test.ts`, `test/conversation-viewer.test.ts`, `test/message-formatters.test.ts`.
+- `src/index.ts`:
+  - Remove the `import { FsAgentFileOps } from "#src/ui/agent-file-ops"` and `import { AgentsMenuHandler } from "#src/ui/agent-menu"` lines.
+  - Remove the now-dead `import { join } from "node:path"` and `import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot"` lines.
+  - Remove the `// ---- /agents interactive menu ----` comment, the `agentsMenu` construction, and the `registerCommand("agents", …)` block.
+  - Remove the `/agents — Interactive agent management menu` line from the top-of-file `Commands:` doc comment.
+- `packages/pi-subagents/docs/architecture/architecture.md` — update the current-state `ui/` file tree (remove the `agent-menu.ts`, `conversation-viewer.ts`, `message-formatters.ts` entries; add a `menu-ui.ts` entry), and annotate the Step 5 roadmap entry's `Outcome:` to record the actual approach (the `MenuUI` relocation prep; `index.ts` import-removal also drops `join`/`buildParentSnapshot`).
+  The structural-analysis tables, domain Mermaid diagram, and health-metrics numbers are deferred to the batch tail [#441] (see Non-Goals).
+- `.pi/skills/package-pi-subagents/SKILL.md` — update the UI domain row: count `13` → `11`, and drop "conversation viewer, /agents menu" from the responsibility description (keep "creation wizard, config editor" — those survive until [#441]).
+
+The Step 5 `Outcome:` line in `architecture.md` currently asserts "no edit to doomed files" and "`index.ts` edited once."
+Both are now slightly inaccurate: the tidy-first prep repoints the doomed wizard/editor `MenuUI` import (one line each), and `index.ts` also sheds two now-dead imports.
+The annotation should reflect this, not leave the stale claim.
+
+## Test Impact Analysis
+
+This is a deletion, not an extraction-for-testability, so no new unit tests are enabled.
+
+1. New tests enabled: none.
+2. Tests that become redundant / removed: `test/ui/agent-menu.test.ts`, `test/conversation-viewer.test.ts`, `test/message-formatters.test.ts` (the largest test function by LOC) — they exercise deleted production code and are deleted with it.
+3. Tests that must stay as-is: the wizard/editor tests (`test/ui/agent-creation-wizard.test.ts`, `test/ui/agent-config-editor.test.ts`) keep compiling against the relocated `MenuUI` and survive until [#441]; `test/ui/subagents-settings.test.ts`, the session-navigation tests, and `test/ui/agent-widget.test.ts` pin the replacement surfaces and must stay green (see Invariants at risk).
+
+## Invariants at risk
+
+The cut removes surfaces whose responsibilities Steps 2–4 already re-homed.
+Each replacement's invariant must remain green after this deletion:
+
+- Settings management (Step 2, [#447]) → pinned by `test/ui/subagents-settings.test.ts`.
+  The `/subagents:settings` command and `SubagentsSettingsHandler` are untouched here.
+- Running-agent visibility (Step 3, [#444]) → pinned by `test/ui/agent-widget.test.ts`.
+  The background widget is untouched.
+- Session viewing (Step 4 / 4a, [#445]) → pinned by the session-navigation / session-navigator tests.
+  The `/subagents:sessions` command is untouched.
+
+The deletion touches none of those files, so the full suite (minus the three deleted tests) staying green is the verification that no replacement regressed.
+
+## Implementation Order
+
+This issue has no red→green test cycles (a pure interface move plus deletions verified by the existing suite), so it is a build-style change — the next step is `/build-plan`, not `/tdd-plan`.
+
+1. `refactor(pi-subagents): extract MenuUI to its own module`
+   - Add `src/ui/menu-ui.ts`; remove the interface from `agent-menu.ts` and import it; repoint the wizard and editor imports.
+   - Verify: `pnpm run check`, `pnpm run lint`, `pnpm run test`, `pnpm fallow dead-code` all green.
+2. `feat(pi-subagents)!: dissolve /agents and remove the conversation-viewer subtree`
+   - Delete the three source files and three tests; dewire `index.ts`; update `architecture.md` file tree + Step 5 `Outcome:`; update `SKILL.md` UI row.
+   - `BREAKING CHANGE:` footer: the `/agents` command is removed; its responsibilities are served by `/subagents:settings` (configure concurrency/turn limits), `/subagents:sessions` (read-only transcript viewing), and the always-on background widget (running-agent visibility).
+   - Verify: `pnpm run check`, `pnpm run lint`, `pnpm run test`, `pnpm fallow dead-code` green; confirm `/agents` no longer registers and `menu-ui.ts` retains its wizard/editor consumers.
+
+## Risks and Mitigations
+
+- Risk: deleting the hub before the leaves breaks `tsc` via the `MenuUI` back-import.
+  Mitigation: the tidy-first Commit 1 relocates `MenuUI` to a surviving module so Commit 2 compiles; verified that only the wizard and editor consume `MenuUI` and that `subagents-settings.ts` and `ui-stubs.ts` do not.
+- Risk: `FsAgentFileOps` becomes production-unused and trips `fallow dead-code`.
+  Mitigation: verified `test/ui/agent-file-ops.test.ts` still imports it; fallow's syntactic import analysis keeps it live until [#441].
+  Run `pnpm fallow dead-code` after Commit 2 to confirm.
+- Risk: the transient `menu-ui.ts` looks like speculative indirection.
+  Mitigation: it is short-lived by design (one issue), has two live consumers immediately, and is deleted by the batch tail [#441]; the alternative (inlining a throwaway type into doomed files, or merging [#441] into [#442]) was considered and rejected via the operator decision.
+- Risk: stale architecture docs mid-batch (the domain diagram and tables still show the deleted modules between [#442] and [#441]).
+  Mitigation: accepted deliberately — the analytical-table refresh is batched into the tail [#441] to avoid double-editing tables that [#441] also touches; the current-state file tree and SKILL.md count are kept accurate at each commit.
+
+## Open Questions
+
+None.
+The hub↔leaf type-cycle resolution (relocate `MenuUI`, keep two commits) and the release-timing (defer until [#441] lands) were settled with the operator during planning.
+
+[#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
+[#447]: https://github.com/gotgenes/pi-packages/issues/447

package/docs/retro/0441-remove-agent-definition-management-subtree.md

@@ -0,0 +1,45 @@
+---
+issue: 441
+issue_title: "pi-subagents: remove the orphaned agent-definition management subtree"
+---
+
+# Retro: #441 — pi-subagents: remove the orphaned agent-definition management subtree
+
+## Stage: Planning (2026-06-23T00:00:00Z)
+
+### Session summary
+
+Produced a deletion-only plan for Phase 19 Step 6: `git rm` the orphaned creation wizard, config editor, and their two file-ops helpers (plus tests), prune `test/helpers/ui-stubs.ts` to just `makeMenuUI`, and update the two current-state docs.
+Verified against `main` that the five modules are pure orphans (no `src/` importer, `index.ts` clean) and that this is the unreleased tail of release batch "dissolve-agents".
+The plan routes to `/build-plan` (no test cycles) with two commits.
+
+### Observations
+
+- Two deviations from the issue body, both forced by the codebase + the authoritative architecture doc rather than by preference, so no `ask_user` gate was used:
+  1. `menu-ui.ts` (the `MenuUI` interface) must also be deleted — it is orphaned by the same cut, and `architecture.md` lines 346/1076 explicitly schedule its removal under #441.
+     The issue body omits it.
+  2. `makeMenuManager` is removed whole, not just its `spawnAndWait` field — after the four test files go, its only consumer is its own self-test, so it is residual clutter.
+     The architecture doc's "if no surviving consumer remains" phrasing licenses this.
+- `ui-stubs.ts` survives because `makeMenuUI` still has a real consumer (`subagents-settings.test.ts`); only the three other helpers (and the private `DEFAULT_TEST_AGENT_CONFIG` + the `AgentConfig` import) are pruned.
+- Commit type is `refactor(pi-subagents):`, not `feat!:` — deleting already-unreachable code changes no observable behavior at this step.
+  The release is driven by Step 5's unreleased breaking `feat!:` (`cb813f2c`, after tag `pi-subagents-v17.5.0`); landing this tail lets release-please cut the major bump.
+- Production duplication goes to zero when `agent-config-editor.ts` is deleted (the 11-line `disableAgent`/`ejectAgent` clone); pin with `pnpm fallow dupes`.
+- Historical docs under `docs/plans/`, `docs/retro/`, and `docs/architecture/history/` mention the deleted modules only as records of completed phases — left untouched per convention; only `architecture.md` current-state and `SKILL.md` are updated.
+
+## Stage: Implementation — Build (2026-06-23T17:00:00Z)
+
+### Session summary
+
+Executed the two-commit plan: `git rm` the five orphaned `src/ui/` modules and four test files in one atomic commit; pruned `test/helpers/ui-stubs.ts` and `ui-stubs.test.ts` to `makeMenuUI` only in the same commit.
+Second commit updated `architecture.md` (directory tree, Step 6 ✅ and Landed note, Mermaid node) and `SKILL.md` (UI domain row 11→6).
+Three additional doc-fixup commits addressed stale `architecture.md` prose (domain flowchart, cross-extension diagram, "What the core owns," "Composition model") deferred from #442.
+All checks green: 62 test files / 950 tests, `fallow dead-code` clean, `fallow dupes` shows 0 production clone groups.
+
+### Observations
+
+- The pre-completion reviewer surfaced five stale `architecture.md` sections not covered by the plan's declared doc scope — all carried over from #442's retro note "Deferred the holistic architecture-doc refresh … to the batch tail [#441]."
+  Required three extra doc-fixup commits (`e440d0d1`, `04b13812`, and the SKILL.md file-count fix) beyond the plan's two.
+  **Lesson:** when a retro note explicitly defers a doc refresh to the batch tail, include it in the batch-tail plan's "Module-Level Changes" doc section so it isn't discovered only by the reviewer.
+- `makeMenuManager` was removed whole (not just its `spawnAndWait` relay) because its only post-cut consumer was its own self-test — exactly the right call, consistent with the planning decision.
+- Final file count in `src/`: 57 (was 58 in SKILL.md header; now corrected).
+- Pre-completion reviewer: **PASS** (third dispatch, after two WARN rounds on the stale doc sections).