@gotgenes/pi-subagents 17.5.0 → 18.0.1

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v18.0.0...pi-subagents-v18.0.1) (2026-06-24)
+
+
+### Documentation
+
+* **pi-subagents:** refresh README for /subagents:settings and /subagents:sessions ([#470](https://github.com/gotgenes/pi-packages/issues/470)) ([945341f](https://github.com/gotgenes/pi-packages/commit/945341fc5527a2e9371d261e0eb1340d09b72f31))
+
+## [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/README.md

@@ -18,7 +18,7 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
 - **In-process & native** — agents run inside the same pi runtime (no spawned subprocesses), sharing tool names, calling conventions, and UI patterns (`subagent`, `get_subagent_result`, `steer_subagent`) — feels native
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
-- **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
+- **Session transcripts** — open any subagent's full session transcript (running or evicted) in pi's native read-only viewer via `/subagents:sessions`
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
@@ -116,7 +116,7 @@ The LLM receives structured `<task-notification>` XML for parsing, while the use
 The `general-purpose` agent is a **parent twin** — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does.
 Explore and Plan use `replace` mode: the parent prompt is the cacheable base and their specialist read-only instructions are appended last, giving them the final say.
 
-Default agents can be **ejected** (`/agents` → select agent → Eject) to export them as `.md` files for customization, **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
+Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
 
 ## Custom Agents
 
@@ -223,31 +223,22 @@ The message interrupts after the current tool execution.
 
 ## Commands
 
-| Command   | Description                       |
-| --------- | --------------------------------- |
-| `/agents` | Interactive agent management menu |
+| Command               | Description                                            |
+| --------------------- | ------------------------------------------------------ |
+| `/subagents:settings` | Configure subagent settings (concurrency, turn limits) |
+| `/subagents:sessions` | View a subagent's session transcript (read-only)       |
 
-The `/agents` command opens an interactive menu:
+### `/subagents:settings`
 
-```text
-Running agents (2) — 1 running, 1 done     ← only shown when agents exist
-Agent types (6)                             ← unified list: defaults + custom
-Create new agent                            ← manual wizard or AI-generated
-Settings                                    ← max concurrency, max turns, grace turns
-```
+Interactive list to tune runtime settings — max concurrency, default max turns, and grace turns.
+Changes persist across pi restarts (see [Persistent Settings](#persistent-settings)).
+
+### `/subagents:sessions`
+
+Pick any subagent — running or already evicted — and read its full session transcript in pi's native per-entry viewer.
+Read-only: no steering, no session takeover (steering lives in the `steer_subagent` tool and the background widget).
 
-- **Agent types** — unified list with source indicators: `•` (project), `◦` (global), `✕` (disabled).
-  Select an agent to manage it:
-  - **Default agents** (no override): Eject (export as `.md`), Disable
-  - **Default agents** (ejected/overridden): Edit, Disable, Reset to default, Delete
-  - **Custom agents**: Edit, Disable, Delete
-  - **Disabled agents**: Enable, Edit, Delete
-- **Eject** — writes the embedded default config as a `.md` file to project or personal location, so you can customize it
-- **Disable/Enable** — toggle agent availability.
-  Disabled agents stay visible in the list (marked `✕`) and can be re-enabled
-- **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do and a sub-agent writes the `.md` file).
-  Any name is allowed, including default agent names (overrides them)
-- **Settings** — configure max concurrency, default max turns, and grace turns at runtime
+Creating and editing agent definitions is not a command — write an agent `.md` file in your editor, or ask a pi session to generate one (see [Custom Agents](#custom-agents)).
 
 ## Graceful Max Turns
 
@@ -274,13 +265,13 @@ Foreground agents bypass the queue — they block the parent anyway.
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns) persist across pi restarts.
+Runtime tuning values set via `/subagents:settings` (max concurrency, default max turns, grace turns) persist across pi restarts.
 Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults.
-  Edit by hand; the `/agents` menu never writes here.
+  Edit by hand; the `/subagents:settings` command never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides.
-  Written by `/agents` → Settings.
+  Written by `/subagents:settings`.
 
 **Precedence:** project overrides global on any field present in both.
 Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`).
@@ -297,10 +288,10 @@ cat > ~/.pi/agent/subagents.json <<'EOF'
 EOF
 ```
 
-Every project now starts with concurrency 16 and grace 10, without ever touching the menu.
-Individual projects can still override via `/agents` → Settings.
+Every project now starts with concurrency 16 and grace 10, without ever touching the command.
+Individual projects can still override via `/subagents:settings`.
 
-**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/agents` toast to a warning with `(session only; failed to persist)`.
+**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/subagents:settings` toast to a warning with `(session only; failed to persist)`.
 
 ## Events
 
@@ -315,7 +306,7 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 | `subagents:steered`          | Steering message sent                                   | `id`, `message`                                                                                                      |
 | `subagents:compacted`        | Agent's session successfully compacted                  | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount` |
 | `subagents:settings_loaded`  | Persisted settings applied at extension init            | `settings` (merged global + project)                                                                                 |
-| `subagents:settings_changed` | `/agents` → Settings mutation was applied               | `settings`, `persisted` (`boolean` — `false` on write failure)                                                       |
+| `subagents:settings_changed` | `/subagents:settings` mutation was applied              | `settings`, `persisted` (`boolean` — `false` on write failure)                                                       |
 
 `tokens.total` = `input + output + cacheWrite`.
 `cacheRead` is excluded — each turn's `cacheRead` is the cumulative cached prefix re-read on that one API call, so summing per-message would over-count it.

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