@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0426-consolidate-residual-test-clone-families.md

@@ -1,235 +0,0 @@
----
-issue: 426
-issue_title: "pi-subagents: consolidate residual test clone families"
----
-
-# Consolidate residual test clone families
-
-## Release Recommendation
-
-**Release:** ship independently
-
-The architecture roadmap (`docs/architecture/architecture.md`, Phase 18, step 7) tags this issue "Independent of the disentanglement spine — can land at any time" and carries no `Release: batch` annotation.
-It is a test-only consolidation with no production-surface change, so it ships on its own.
-
-## Problem Statement
-
-fallow reports a long tail of test clone groups in `pi-subagents` (currently 24 test clone groups across the suite).
-A handful of these clone families are stable test scaffolding — tmp-directory setup, repeated arrange-then-act blocks, and near-identical menu-assertion cases — that the Phase 18 disentanglement spine does not rewrite as a side effect.
-They warrant their own shared fixtures rather than riding along with a production refactor.
-
-The goal is to extract shared fixtures for the clone families fallow identifies in the four named test files, dropping the package's test clone-group count below 15.
-
-## Goals
-
-- Eliminate the cross-file tmp-directory + `writeGlobal`/`writeProject` duplication between `test/settings.test.ts` and `test/layered-settings.test.ts` via a shared fixture helper.
-- Eliminate the three internal clone groups in `test/lifecycle/create-subagent-session.test.ts` by extracting the repeated arrange (factory session + deps) while keeping each `createSubagentSession(...)` act explicit.
-- Eliminate the four internal clone groups in `test/ui/agent-config-editor.test.ts` — convert the menu-option-structure cases to a table-driven `it.each` and hoist the shared `filePath`/arrange in the Edit/Delete blocks.
-- Land the package below 15 test clone groups (the four files contribute exactly 10 of the current 24 groups → 14 remaining).
-- Keep the full `vitest` suite green and the assertion strength unchanged (no behavioral coverage loss).
-
-This change is **not breaking** — it touches only test files and adds test-only helpers; no production module, export, or default changes.
-
-## Non-Goals
-
-- The production-code clone in `src/ui/agent-config-editor.ts` (the `location`/`targetDir`/`targetPath` block, dup `ff960d84`) — the issue scopes to *test* clone families; a production extraction is a separate concern.
-- The remaining test clone groups outside the four named files (`subagent-manager.test.ts`, `subagent.test.ts`, `concurrency-limiter.test.ts`, `workspace-bracket.test.ts`, `session-config.test.ts`, `get-result-tool.test.ts`, `spawn-config.test.ts`, `agent-creation-wizard.test.ts`, `agent-file-ops.test.ts`, `agent-menu.test.ts`, `agent-widget.test.ts`).
-  The cross-file group `5d8dbd48` (`subagent-manager.test.ts` ↔ `subagent.test.ts`) is explicitly left alone — neither side is a target file.
-- The cross-package `vitest.config.ts` clone (`e5e6691e`, 6 instances) — not a `pi-subagents` test-suite group and not in scope.
-- Phase 18 step 8 ([#427]), the UI-direction ADR — a separate, later step.
-
-## Background
-
-Relevant existing test-helper conventions live in `packages/pi-subagents/test/helpers/`:
-
-- `make-deps.ts`, `make-spawn-config.ts`, `make-subagent.ts`, `manager-stubs.ts`, `mock-session.ts`, `stub-ctx.ts`, `subagent-session-io.ts`, `ui-stubs.ts` — each exports `createX`/`makeX` factory functions with matching `*.test.ts` self-tests.
-- `subagent-session-io.ts` already exports `createFactorySession`, `createSubagentSessionDeps`, `createSubagentSessionIO`, `createAgentLookup`, `createChildLifecycleMock` — the create-subagent-session consolidation builds on these.
-- `ui-stubs.ts` already exports `createTestSubagentConfig`, `makeFileOps`, `makeMenuUI` — the agent-config-editor consolidation builds on these.
-
-Constraints from the `testing` skill that shape this plan:
-
-- **Do not wrap the system-under-test call in a helper to eliminate a duplication-metric clone — the repeated act is the test subject, not duplication to remove.**
-  Consolidate the *arrange*, not the *act*.
-  For `create-subagent-session`, extract the factory-session + deps arrange but keep `await createSubagentSession(...)` written out in each test.
-- **Group shared setup in a describe-scoped `beforeEach` and keep the act explicit** when the arrangement is uniform.
-- A table-driven `it.each` keeps the act visible in the parameterized body (run once per row) and is the right tool for the menu-option-structure cases — it is not a helper that hides the act.
-- Test-only refactors carry the `test:` conventional-commit type.
-
-Each helper module in `test/helpers/` ships a paired `*.test.ts`; any new shared helper follows that convention.
-
-## Design Overview
-
-This is a refactor verified by the existing suite staying green plus a falling fallow clone count — there are no new red→green behavior cycles.
-Three independent consolidations, each scoped to its file(s).
-
-### 1. Settings tmp-dir fixture (cross-file)
-
-`test/settings.test.ts` and `test/layered-settings.test.ts` both stand up two `mkdtempSync` directories in `beforeEach`, tear them down in `afterEach`, and define identical `writeGlobal`/`writeProject` helpers (clone groups `21d1fb01`, `4003c0e7` span both files; `4fc062db` is internal to `layered-settings.test.ts`).
-
-Extract a shared fixture into `test/helpers/tmp-settings-dirs.ts`:
-
-```typescript
-export interface SettingsDirs {
-  globalDir: string; // agentDir / global scope
-  projectDir: string; // cwd / project scope
-  globalFile: (filename?: string) => string;
-  projectFile: (filename?: string) => string;
-  writeGlobal: (obj: unknown, filename?: string) => void;
-  writeProject: (obj: unknown, filename?: string) => void;
-}
-
-// Caller wires it into beforeEach/afterEach:
-export function createSettingsDirs(filename: string): SettingsDirs;
-export function disposeSettingsDirs(dirs: SettingsDirs): void;
-```
-
-Each test file calls `createSettingsDirs(...)` in `beforeEach` and `disposeSettingsDirs(...)` in `afterEach`, then references `dirs.writeGlobal` / `dirs.writeProject`.
-`settings.test.ts` uses `"subagents.json"`; `layered-settings.test.ts` uses its `FILENAME` constant.
-The malformed-settings warn-assertion clone inside `layered-settings.test.ts` (`4fc062db`, two adjacent `it` blocks) collapses into a single `it.each` over `[malformed-global, malformed-project]` rows that share the spy-assert body.
-
-Interaction sketch (consumer call site, ~5 lines):
-
-```typescript
-let dirs: SettingsDirs;
-beforeEach(() => { dirs = createSettingsDirs("subagents.json"); });
-afterEach(() => { disposeSettingsDirs(dirs); });
-it("loads from global when no project file", () => {
-  dirs.writeGlobal({ maxConcurrent: 16 });
-  expect(loadSettings(dirs.globalDir, dirs.projectDir)).toEqual({ maxConcurrent: 16 });
-});
-```
-
-The helper owns only filesystem scaffolding (Tell-Don't-Ask: callers ask it to write, not for raw paths to write themselves); it does not import or know about `loadSettings`/`loadLayeredSettings`, so the act stays in the test.
-
-### 2. create-subagent-session arrange helper (internal)
-
-Clone groups `48ff1484`, `c92feb70`, `5fbe9ebb` all live in the `createSubagentSession — post-bind recursion guard` describe block (lines ~204–262).
-Each test repeats:
-
-```typescript
-const session = createFactorySession({ toolsBeforeBind, toolsAfterBind });
-io.createSession.mockResolvedValue({ session });
-await createSubagentSession(
-  { snapshot: STUB_SNAPSHOT, type: "Explore" },
-  createSubagentSessionDeps({ io, exec, registry: mockAgentLookup }),
-);
-const postBindArgs = session.setActiveToolsByName.mock.calls[0][0];
-```
-
-The variation is the factory tool-list config and the assertions; the act is identical.
-Add two file-local arrange helpers (the factory mocks differ per test, so a describe-scoped `beforeEach` cannot fully arrange):
-
-```typescript
-function arrangeFactory(opts?: Parameters<typeof createFactorySession>[0]) {
-  const session = createFactorySession(opts);
-  io.createSession.mockResolvedValue({ session });
-  return session;
-}
-function defaultDeps() {
-  return createSubagentSessionDeps({ io, exec, registry: mockAgentLookup });
-}
-```
-
-Each test becomes `const session = arrangeFactory({...}); await createSubagentSession({ snapshot: STUB_SNAPSHOT, type: "Explore" }, defaultDeps());` — the act line stays written out.
-The remaining two-line arrange+act sequence falls below fallow's clone threshold.
-These helpers stay file-local (one consumer file), so no new `test/helpers/` module is needed.
-
-### 3. agent-config-editor table-driven menu cases (internal)
-
-Clone groups `4ac7b228`, `a8e71e9c` (×3), `e36d2314` cluster in the "Menu option structure" block (lines ~104–139); `23fe1f93` is in the Edit/Delete blocks (~180–210).
-
-- **Menu-option-structure cases** → one `it.each` table.
-  Each existing case differs only in (a) the `resolveAgentConfig` mock (default vs. custom vs. disabled) and (b) the expected option array.
-  Model the rows as `{ name, config, filePath, expected }` and run the shared act once per row:
-
-  ```typescript
-  it.each([
-    { name: "default agent, no file", config: testDefaultConfig, filePath: undefined,
-      expected: ["Eject (export as .md)", "Disable", "Back"] },
-    // …one row per existing menu-structure case…
-  ])("shows $name options", async ({ config, filePath, expected }) => {
-    vi.spyOn(testRegistry, "resolveAgentConfig").mockReturnValue(config);
-    const { editor, ui } = setupDetail([undefined], filePath ? { filePath } : {});
-    await editor.showAgentDetail(ui, "test-agent");
-    expect((ui.select.mock.calls[0][1] as string[])).toEqual(expected);
-  });
-  ```
-
-  The act (`editor.showAgentDetail(...)`) stays visible in the table body.
-- **Edit/Delete block (`23fe1f93`)** → hoist the shared `const filePath = "/project/.pi/agents/test-agent.md"` to a describe-scoped constant and keep each `await editor.showAgentDetail(...)` act explicit; the residual per-test arrange (`setupDetail`, `ui.editor`/`ui.confirm` resolution) stays inline because it carries the test's intent.
-
-No change to `setupDetail`, `makeEditor`, or `ui-stubs.ts` — they already provide the right arrange seam.
-
-## Module-Level Changes
-
-- `test/helpers/tmp-settings-dirs.ts` — **new**: shared tmp-dir fixture (`createSettingsDirs`, `disposeSettingsDirs`, `SettingsDirs` type, `writeGlobal`/`writeProject`).
-- `test/helpers/tmp-settings-dirs.test.ts` — **new**: self-test for the fixture (follows the `test/helpers/*.test.ts` convention — every helper module ships a paired test).
-- `test/settings.test.ts` — **changed**: replace inline tmp-dir `beforeEach`/`afterEach`/`writeGlobal`/`writeProject` with the shared fixture.
-- `test/layered-settings.test.ts` — **changed**: same fixture swap; fold the two adjacent malformed-settings warn cases into one `it.each`.
-- `test/lifecycle/create-subagent-session.test.ts` — **changed**: add file-local `arrangeFactory`/`defaultDeps`; rewrite the post-bind-guard tests to call them while keeping each `createSubagentSession(...)` act explicit.
-- `test/ui/agent-config-editor.test.ts` — **changed**: convert the menu-option-structure cases to `it.each`; hoist the shared `filePath` in the Edit/Delete blocks.
-
-No `src/` files change.
-No SKILL.md, architecture-doc, or README references to the affected test internals exist to update — these are intra-test fixtures (verified: the architecture roadmap references the *issue* `#426`, not the specific helpers).
-The roadmap step's status flips to ✅ in a follow-up doc pass at ship time, not in this plan (consistent with how steps 1–6 were marked).
-
-## Test Impact Analysis
-
-This issue *is* a test-maintenance change, so the standard extraction lens is inverted:
-
-1. **New tests enabled** — only the new `tmp-settings-dirs.test.ts`, a self-test pinning the shared fixture's filesystem behavior (writes land at the right global/project paths; dispose removes both dirs).
-   No production seam is newly testable.
-2. **Tests becoming redundant** — none are removed outright.
-   The two malformed-settings cases in `layered-settings.test.ts` merge into one `it.each` (two rows = same two assertions, no coverage loss); the agent-config-editor menu cases merge into one `it.each` (one row per former case, identical assertions).
-   The total assertion set is preserved; only the surrounding arrange is deduplicated.
-3. **Tests that must stay as-is** — the act in every consolidated test (`loadSettings`/`loadLayeredSettings`/`createSubagentSession`/`showAgentDetail`) stays written out per the `testing` skill rule; the distinct intent of each Edit/Delete case (write vs. no-write vs. cancel) stays inline.
-
-## Invariants at risk
-
-The four target files belong to surfaces earlier Phase 17/18 steps refactored (`subagent-session-io.ts` fixtures from #378/#412; `create-subagent-session` from #257/#265; `agent-config-editor` UI from the disentanglement spine).
-The invariant at risk is purely **coverage preservation** — a consolidation must not silently drop an assertion.
-Each consolidation step is gated by:
-
-- The full `vitest` suite staying green (test count must not *drop* except by the deliberate `it.each` merges, whose row count equals the former case count).
-- Running `pnpm fallow dupes` after each step to confirm the targeted clone groups disappear and no new ones appear.
-
-No production `Outcome:`/`Landed:` invariant from a prior roadmap step is touched, because no `src/` file changes.
-
-## Refactor Order
-
-These are refactor (not red→green) steps: each makes a consolidation, verifies the suite stays green and the targeted clone groups drop, then commits with `test:`.
-Order is independent — the three consolidations do not depend on each other — but listed for clean, reviewable commits.
-
-1. **Shared settings tmp-dir fixture.**
-   Add `test/helpers/tmp-settings-dirs.ts` + `tmp-settings-dirs.test.ts`; migrate `test/settings.test.ts` and `test/layered-settings.test.ts` to it; fold the two malformed-settings cases in `layered-settings.test.ts` into one `it.each`.
-   Verify: `pnpm --filter @gotgenes/pi-subagents exec vitest run test/settings.test.ts test/layered-settings.test.ts test/helpers/tmp-settings-dirs.test.ts` green; `pnpm fallow dupes` shows `21d1fb01`, `4003c0e7`, `4fc062db` gone.
-   Commit: `test: extract shared settings tmp-dir fixture (#426)`.
-2. **create-subagent-session arrange helpers.**
-   Add file-local `arrangeFactory`/`defaultDeps`; rewrite the post-bind-guard tests to use them with the act kept explicit.
-   Verify: `pnpm --filter @gotgenes/pi-subagents exec vitest run test/lifecycle/create-subagent-session.test.ts` green; clone groups `48ff1484`, `c92feb70`, `5fbe9ebb` gone.
-   Commit: `test: consolidate create-subagent-session post-bind arrange (#426)`.
-3. **agent-config-editor table-driven menu cases.**
-   Convert the menu-option-structure cases to `it.each`; hoist the shared `filePath` in the Edit/Delete blocks.
-   Verify: `pnpm --filter @gotgenes/pi-subagents exec vitest run test/ui/agent-config-editor.test.ts` green; clone groups `4ac7b228`, `a8e71e9c`, `e36d2314`, `23fe1f93` gone.
-   Commit: `test: table-drive agent-config-editor menu cases (#426)`.
-4. **Final verification.**
-   Run the full suite (`pnpm --filter @gotgenes/pi-subagents exec vitest run`), `pnpm run check`, `pnpm run lint`, `pnpm fallow dead-code` (catch orphaned imports left by removed inline helpers), and `pnpm fallow dupes` to confirm the package's test clone-group count is below 15 (expected: 24 → 14).
-   No separate commit unless cleanup is needed.
-
-## Risks and Mitigations
-
-- **Risk: an `it.each` merge silently drops an assertion.**
-  Mitigation: map each former `it` to exactly one table row with the same assertions; confirm the post-merge test count equals (old count − merged duplicates) and the suite stays green.
-- **Risk: removing an inline `writeGlobal`/`writeProject` leaves an orphaned import** (Biome `noUnusedImports` is warning-level, exit 0).
-  Mitigation: step 4 runs `pnpm fallow dead-code`; re-check each migrated file's imports (`mkdirSync`, `writeFileSync`, `mkdtempSync`, `rmSync`, `tmpdir`, `join`) after the fixture swap.
-- **Risk: a helper that wraps the act re-introduces the "act is the subject" smell.**
-  Mitigation: the design keeps every `loadSettings`/`createSubagentSession`/`showAgentDetail` call written out in the test body; helpers cover arrange only.
-- **Risk: the fixture's `filename` parameterization diverges from the two call sites' expectations** (`subagents.json` vs. `FILENAME`).
-  Mitigation: `createSettingsDirs(filename)` takes the filename explicitly; the self-test pins both path shapes.
-
-## Open Questions
-
-- Whether to also dissolve the production clone in `src/ui/agent-config-editor.ts` (dup `ff960d84`) — deferred as a Non-Goal; revisit if the Phase 18 UI-direction ADR (#427) reworks that file anyway.
-- Whether a shared tmp-dir fixture should live in a cross-package location (other packages stand up similar dirs) — out of scope; keep it `pi-subagents`-local until a second consumer appears.
-
-[#427]: https://github.com/gotgenes/pi-packages/issues/427

package/docs/plans/0427-reconsider-ui-direction.md

@@ -1,212 +0,0 @@
----
-issue: 427
-issue_title: "pi-subagents: reconsider the UI direction from first principles (ADR)"
----
-
-# Reconsider the UI direction from first principles (ADR)
-
-## Release Recommendation
-
-**Release:** ship independently
-
-Phase 18 carries no `Release:` batch annotation in the architecture roadmap, so this issue ships on its own.
-It is a decision-only ADR plus an architecture-doc update — docs-only, no runtime change — and it completes the Phase 18 roadmap, gateway-ing the (separately planned) Phase 19 implementation.
-
-## Problem Statement
-
-Phase 18's spine (Steps 1–7) disentangled the activity tier from the core, leaving the inherited UI a pure reactive consumer of the broadcast-plus-query surface.
-The UI is now _substitutable_.
-This final step (Step 8, [#427]) decides the UI's _direction and distribution_, not whether substitution is possible — and records the decision in an ADR that gateways Phase 19.
-
-The decision is **per component** (widget, conversation viewer, `/agents` menu) and per the architecture's own first principles: keep, shrink, extract to a separate package, or remove — judged on our terms, not preserved by default.
-Two standing concerns are the evidence:
-
-- **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.
-- **Truncated transcript** — the bespoke conversation viewer renders a custom, capped transcript, yet each child is already persisted as a standard Pi session JSONL (`outputFile`); the limit is the bespoke overlay, not data access.
-
-## Goals
-
-- Write `docs/decisions/0004-reconsider-ui-direction.md` recording a per-component decision for the widget, the conversation viewer, and the `/agents` menu.
-- Record the **distribution** decision: the surviving UI stays in-core as a reactive consumer (substitutable, not extracted to a separate package now).
-- Record the open feasibility questions for the native-session-navigation direction as Phase 19 spike gates (not pretend-resolved).
-- Update `docs/architecture/architecture.md`: mark Phase 18 Step 8 complete, mark Phase 18 complete, and add a forward pointer to ADR-0004 / Phase 19.
-- This is a **decision-only** ADR — no `src/` or `test/` changes; the implementation lands in the separately-planned Phase 19.
-
-## Non-Goals
-
-- No UI code changes (no widget edit, no viewer removal, no menu decomposition, no new `/subagents:settings` command).
-  Those are Phase 19 implementation, planned and shipped separately.
-- No new `@gotgenes/pi-subagents-ui` package — extraction is explicitly _not_ chosen now.
-- No resolution of the `switchSession` mechanics (root-continuity, view-only-vs-interactive) — the ADR records these as Phase 19 spike entry criteria.
-- No full Phase 19 roadmap — the arch-doc update adds only a forward pointer; Phase 19's steps are planned in their own pass.
-- No SKILL.md edits — `package-pi-subagents` SKILL describes the UI domain's module count, which changes only when Phase 19 code lands.
-
-## Background
-
-Relevant modules and how they relate:
-
-- `src/ui/agent-widget.ts` (~290 LOC) — `AgentWidget implements SubagentManagerObserver`; self-drives an 80 ms render loop from lifecycle events (Step 4, [#423]), renders running/completed agents above the editor.
-- `src/ui/conversation-viewer.ts` (~241 LOC) — bespoke `ConversationViewer` overlay; subscribes to `record.subscribeToUpdates`, renders a live, width-capped transcript of one agent's `messages`, plus a streaming indicator.
-- `src/ui/agent-menu.ts` (~331 LOC) + `agent-config-editor.ts`, `agent-creation-wizard.ts`, `agent-file-ops.ts` — the `/agents` command.
-  Four entries: **Running agents** (→ `ConversationViewer`), **Agent types** (→ `AgentConfigEditor` view/edit/enable/disable), **Create new agent** (→ `AgentCreationWizard`), **Settings** (max concurrency / default max turns / grace turns, written to layered settings).
-- `src/tools/foreground-runner.ts` — foreground runs stream progress via the tool's inline `onUpdate` callback; the result is rendered by `result-renderer.ts` (caps display at 50 lines).
-- The core persists each child as a standalone Pi session JSONL at `Subagent.outputFile`; `Subagent.messages` exposes full history.
-
-Pi SDK surface relevant to the candidate redesign (verified against `@earendil-works/pi-coding-agent@0.79.1`):
-
-- `ExtensionActions.switchSession(sessionPath, { withSession })` — switches the **active** session to a different session file; fires `session_before_switch` / `session_shutdown` and invalidates the current session context (`setBeforeSessionInvalidate` exists for host-owned UI teardown).
-  Returns `{ cancelled }`.
-  The switched-to session is fully interactive — `ReplacedSessionContext` exposes `sendUserMessage`.
-- `session-manager` exports `loadEntriesFromFile(filePath)` / `parseSessionEntries(content)` — read a session file's entries without switching (the read-only alternative).
-
-Constraint from AGENTS.md / the package SKILL: pi-subagents is a minimal core, open for extension and closed for modification; the UI is an _observational consumer_ (unlimited, the core never waits on it), distinct from the rationed generative `WorkspaceProvider` seam.
-The ADR records a consumer-design decision; it must not introduce any new inbound dependency from the core onto the UI.
-
-## Design Overview
-
-The ADR records four decisions, each motivated by the first principles in the architecture doc's "first-principles refinement."
-
-### Decision A — Foreground widget: shrink to background agents only
-
-The above-editor widget duplicates the foreground tool's inline `onUpdate` stream.
-Decision: the widget survives **only** as the background-agent status surface (concern (b): background agents have no tool-call display, so _something_ must indicate their state).
-Foreground runs suppress the widget; the inline stream is authoritative there.
-
-Multiple subagents can run in parallel, so the background surface must represent N concurrent agents at once — the widget's existing per-agent tree already does this; the change is _when_ it shows (background-only), not _what_ it shows.
-
-### Decision B — Conversation viewer: replace the bespoke overlay with native session navigation
-
-Concern (c) — "let the operator switch into a subagent's session, scroll/read it, switch between subagents, and exit back to root" — is a richer interaction than a live overlay.
-The core already persists each child as a standalone Pi session JSONL, so this maps onto Pi's own session machinery rather than a bespoke renderer.
-
-Decision (direction): **remove `ConversationViewer`**; the operator navigates into a child's persisted session via Pi's native viewer and back to root.
-The bespoke, width-capped transcript is replaced by the same viewer Pi uses for any session — the recursive-Pi insight applied to the already-persisted session file.
-
-Candidate call-site shape (Phase 19, illustrative — verifies the interaction pattern, not final):
-
-```typescript
-// "View running agents" → pick a child → switch into its persisted session
-const child = manager.getRecord(id);
-if (child?.outputFile) {
-  await ctx.switchSession(child.outputFile);
-  // operator reads/scrolls in Pi's native viewer; a later switch returns to root
-}
-```
-
-This is Tell-Don't-Ask (hand Pi the session path; Pi owns the viewer) and keeps the core free of transcript-rendering code.
-
-Open mechanics (recorded in the ADR, resolved by a Phase 19 spike — see Open Questions): `switchSession` is a full active-session takeover (not a view-only overlay), it invalidates the current session context, and the switched-to session is interactive.
-The spike decides whether the operator UX is (i) true `switchSession` round-trips, or (ii) a read-only transcript built from `loadEntriesFromFile` that renders Pi-standard entries without leaving root.
-The ADR records the _direction_ (native session machinery over a bespoke renderer) and gates the mechanism on the spike.
-
-### Decision C — `/agents` menu: dissolve the monolithic command into focused surfaces
-
-The single `/agents` command bundles four unrelated jobs.
-Decision (direction): split them; do not keep all in one command.
-The operator does not value managing agent definitions through the menu at all — creating or editing agents is firmly better done with other tools (directly in Pi, or a real text editor / IDE), so both of those surfaces are **removed outright**, not merely deprioritized.
-
-- **Create new agent (wizard)** → **remove.**
-  An operator generates a new agent `.md` by asking a Pi agent directly (more capable than a fixed wizard) or by writing the file in an editor — the wizard earns no keep.
-- **Agent types (list + config editor)** → **remove.**
-  Viewing and editing agent definitions is better served by opening the `.md` files directly in an editor/IDE; the in-menu config editor earns no keep.
-- **Running agents (visibility)** → **keep the responsibility, re-home it.**
-  _Something_ must own running-agent visibility; it moves onto the background widget (Decision A) plus the native session navigation (Decision B), not a bespoke in-menu overlay.
-- **Settings (concurrency / max turns / grace turns)** → **extract to a focused command** (e.g. `/subagents:settings`).
-  Some value, but it does not belong bundled with agent management.
-
-### Decision D — Distribution: keep the surviving UI in-core (substitutable, not extracted)
-
-The spine already made the UI substitutable — a replacement UI is a downstream concern that targets the public broadcast-plus-query surface.
-Decision: the surviving UI (background widget + a settings command + session-navigation glue) **stays in-core** as a reactive consumer.
-Extraction to `@gotgenes/pi-subagents-ui` is _not_ chosen now; it remains an available future option precisely because the core is byte-for-byte identical with or without a given UI consumer (the composition invariant).
-
-This answers the issue's headline question — the UI's _distribution_ — with "keep in core, substitutable," recorded explicitly rather than left implicit.
-
-## Module-Level Changes
-
-This is a decision-only ADR; the only files touched are docs.
-
-- **New:** `packages/pi-subagents/docs/decisions/0004-reconsider-ui-direction.md`.
-  Frontmatter (`status: accepted`, `date: <ISO date>`), then `# 0004 — ...`, `## Status`, `## Context`, `## Decision` (Decisions A–D), `## Consequences`, `## Phase 19 entry criteria` (the spike gates + per-component implementation handles).
-- **Changed:** `packages/pi-subagents/docs/architecture/architecture.md`:
-  - Phase 18 Step 8 (`### Steps`, item 8) — mark complete with a `Landed:` bullet referencing ADR-0004 and the recorded decisions.
-  - Step dependency diagram node `S8` — append a ✅ marker (matching S1–S7) so the diagram is consistent.
-  - The phase summary table row `| 18 | Reconsider UI (first principles) | In progress |` → `Complete`, and add the per-phase pointer to the ADR.
-  - Add a forward-pointer line gateway-ing Phase 19 (implementation of the recorded decisions, planned separately).
-  - Add a `[#427]` reference usage is already present; no new link-ref definition needed.
-    Add an ADR-0004 reference link if the doc cites it by path.
-
-No `src/`, `test/`, or SKILL.md changes — every removed-symbol / reworded-mechanism check is therefore vacuous for this issue (no symbols removed, no runtime mechanism reworded).
-The architecture doc's UI-domain module count and health metrics are _not_ edited here — they change when Phase 19 code lands.
-
-## Test Impact Analysis
-
-None — this is a docs-only ADR.
-
-1. No new unit tests are enabled (no extraction, no behavior change).
-2. No existing tests become redundant (no code removed).
-3. No tests must stay-as-is for a layer being extracted (nothing is extracted in this issue).
-
-The Phase 19 implementation that acts on these decisions will carry its own Test Impact Analysis when it is planned.
-
-## Invariants at risk
-
-None regressed by this issue — it changes no code, so every Phase 18 spine outcome stays green by construction.
-
-The ADR _records_ that Phase 19 must preserve these spine invariants when it implements the decisions:
-
-- Step 3 ([#422]) outcome "runtime holds zero UI state" — Phase 19 must not re-introduce UI state on the core when wiring the background-only widget or session navigation.
-- Step 4/5 ([#423], [#424]) outcome "the widget is a reactive consumer; no inbound calls from core spawn tools / the LLM tool depends only on manager/runtime/settings/registry" — the background-only restriction and the `/agents` decomposition must keep the dependency direction inward.
-- Step 6 ([#425]) outcome "declared channels equal emitted channels; no vacant hook" — any new navigation surface must consume existing broadcast/query channels, not add a vacant one.
-
-These are pinned today by the existing observer/widget/event-contract suites; Phase 19 inherits them.
-
-## Build Order
-
-Docs-only — no red→green test cycles.
-Numbered build steps, each a single reviewable commit.
-
-1. **Write ADR-0004.**
-   Author `docs/decisions/0004-reconsider-ui-direction.md` with Status / Context / Decision (A–D) / Consequences / Phase 19 entry criteria, capturing the `switchSession` findings and open mechanics.
-   Verify: `pnpm run lint` passes (rumdl markdown rules); the ADR states a decision for every component named in [#427].
-   Commit: `docs: add ADR-0004 reconsidering the UI direction (#427)`.
-2. **Update the architecture doc.**
-   Mark Phase 18 Step 8 complete (Landed bullet → ADR-0004), append ✅ to the `S8` diagram node, flip the phase table row to Complete, and add the Phase 19 forward pointer.
-   Verify: `pnpm run lint` passes; the `[#427]` reference still resolves; no orphaned link-ref definitions (MD053); Phase 18 reads as complete end-to-end.
-   Commit: `docs: mark Phase 18 complete and gateway Phase 19 (#427)`.
-
-(Both steps may be folded into one commit if preferred; kept separate here because they touch different documents with different review concerns.)
-
-## Risks and Mitigations
-
-- **Risk:** the ADR over-commits to `switchSession` before its mechanics are understood, locking Phase 19 into an infeasible UX.
-  **Mitigation:** the ADR records the _direction_ (native session machinery over a bespoke renderer) and explicitly gates the _mechanism_ on a Phase 19 spike, listing the read-only `loadEntriesFromFile` fallback as a first-class alternative.
-- **Risk:** removing the conversation viewer and the running-agents menu entry leaves a visibility gap before Phase 19 ships.
-  **Mitigation:** this issue removes _nothing_ — it only records decisions; the viewer/menu stay live until Phase 19 replaces them, so there is no interim regression.
-- **Risk:** the arch-doc edits silently drop an enclosing structure (the Steps list, the diagram fence, the phase table).
-  **Mitigation:** anchor edits on unique adjacent lines, re-read each edited region after editing, and run `pnpm run lint` to confirm the Mermaid fence and tables still parse.
-- **Risk:** a future reader treats the recorded "keep in core" distribution decision as permanent.
-  **Mitigation:** the ADR frames extraction as a still-available option enabled by the composition invariant, with the conditions under which it would be revisited.
-
-## Open Questions
-
-These are recorded in the ADR as Phase 19 spike entry criteria, not resolved here:
-
-- **Root-continuity during a session switch.**
-  `switchSession` invalidates the current session context — does the root's in-flight turn survive a switch-out-and-return, and what is the correct "return to root" gesture?
-  Spike before committing Phase 19 to true `switchSession` round-trips.
-- **View-only vs interactive.**
-  A switched-to child session is interactive (`sendUserMessage`).
-  Is steering a child from its own session desirable, or should the viewer be strictly read-only (favoring the `loadEntriesFromFile` transcript path)?
-- **Parallel-agent navigation.**
-  With N background agents running, what is the operator's gesture to pick which child to view and to cycle between them — driven from the background widget, a dedicated command, or both?
-- **Settings command namespace.**
-  Confirm the final command name/namespace for the extracted settings surface (`/subagents:settings` vs another form) against how sibling packages register namespaced commands.
-
-The agent create/edit surfaces are _not_ open questions: the operator firmly removes both (managing agent definitions belongs in an editor/IDE or a Pi agent, not the menu).
-
-[#422]: https://github.com/gotgenes/pi-packages/issues/422
-[#423]: https://github.com/gotgenes/pi-packages/issues/423
-[#424]: https://github.com/gotgenes/pi-packages/issues/424
-[#425]: https://github.com/gotgenes/pi-packages/issues/425
-[#427]: https://github.com/gotgenes/pi-packages/issues/427

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

@@ -1,180 +0,0 @@
----
-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