@gotgenes/pi-subagents 17.5.0 → 18.0.1

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/plans/0443-consolidate-remaining-test-clone-families.md

@@ -0,0 +1,268 @@
+---
+issue: 443
+issue_title: "pi-subagents: consolidate remaining test clone families"
+---
+
+# Consolidate remaining test clone families
+
+## Release Recommendation
+
+**Release:** ship independently
+
+This is Phase 19 Step 7 (Track C — test health), tagged `Release: independent` in the architecture roadmap.
+It depends only on the terminal cut (Steps 5–6, [#441] / [#442], both closed) having landed, which it has.
+No other roadmap step is gated on it, so it ships on its own.
+
+## Problem Statement
+
+`fallow dupes` reports test clone families in `pi-subagents`.
+The issue (written at the Phase 18 end) named five files and a "≤ 10 clone groups (from 16)" target, on the premise that each clone is an extractable shared fixture.
+
+Re-running fallow against current `main` (after the terminal cut shifted line numbers and the Phase-19 UI surfaces added new test files) shows the live picture differs from the issue's snapshot.
+There are **16** `pi-subagents` test clone families today, but they split into two kinds:
+
+1. Genuine *arrange / fixture / helper* duplication — safe to extract.
+2. The repeated *system-under-test call* (`resolveSpawnConfig`, `assembleSessionConfig`, `schedule`) — which the `testing` skill explicitly says **not** to wrap in a helper just to clear a duplication metric, because the repeated act *is* the test subject.
+
+Several of the issue's five named targets fall into category 2.
+The operator confirmed (planning `ask_user`) a **guardrail-first** approach over the **full live set** of clones: extract only genuine fixtures, leave act-clones in place and documented, and address the new Phase-19 UI clones the issue never anticipated.
+
+## Goals
+
+- Extract genuine (non-act) test duplication into shared or hoisted helpers, following the package's `test/helpers/*.ts` convention.
+- Clear the clone families that are legitimately arrange/fixture/result-extraction boilerplate.
+- Keep the full suite green at every step — the existing tests are the safety net for their own refactor.
+- Reach the issue's `≤ 10` clone-group target *honestly*, without wrapping any system-under-test call.
+- Document the residual act-clones as intentional in the plan, so a future fallow pass does not re-flag them as oversight.
+
+## Non-Goals
+
+- Do **not** wrap or extract the repeated system-under-test call to clear a clone metric (the `testing`-skill guardrail).
+  These act-clones are left in place by design:
+  - `test/tools/spawn-config.test.ts` — repeated `resolveSpawnConfig(...)` calls (`dup:9b42a569`, `dup:ef875c08`).
+  - `test/session/session-config.test.ts` — repeated `assembleSessionConfig(...)` calls (`dup:539a8ca2`).
+  - `test/lifecycle/concurrency-limiter.test.ts` — repeated `schedule(...)` sequences (`dup:ff841f05`).
+  - `test/lifecycle/subagent-manager.test.ts` — `spawnBg` + `await promise` act blocks (`dup:29158516`, `dup:082c007e`).
+  - `test/lifecycle/subagent.test.ts` — `agent.run()` act block (`dup:a3814745`).
+  - `test/tools/get-result-tool.test.ts` — `execute(...)` act block (`dup:230828a8`, 5 lines, marginal).
+- No production-source changes — this is test-only.
+- No change to test *assertions* or behavior coverage; only the arrange/setup ceremony is consolidated.
+- No new fallow rule or config change.
+
+## Background
+
+- Phase 19 Step 7 in `packages/pi-subagents/docs/architecture/architecture.md` ([#443]) — the roadmap entry, `Release: independent`.
+- The terminal cut ([#441], [#442]) removed `agent-menu.ts`, the conversation viewer, and the definition-management subtree, deleting ~4 of the Phase-18 clone groups automatically and shifting the line numbers in the issue's target list.
+- The Phase-19 replacement surfaces added new test files the issue could not have named: `test/ui/session-navigation.test.ts` and `test/ui/session-navigator.test.ts` ([#445], [#462], [#463]), which carry the largest genuine clone (an identical `makeNavigable` factory duplicated across both files).
+- Shared-fixture convention: `test/helpers/<name>.ts` exporting named helpers, imported via the `#test/helpers/<name>` path alias, each with a companion `<name>.test.ts` (e.g. `make-subagent.ts` + `make-subagent.test.ts`).
+- The `testing` skill rule that drives the guardrail: "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."
+
+## Design Overview
+
+### Clone classification (live fallow output vs. issue)
+
+| Fingerprint    | Location                                                                      | Kind                                           | Disposition                 |
+| -------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- | --------------------------- |
+| `dup:1d5dc276` | `ui/agent-widget.test.ts` :229 / :292                                         | duplicated `makeWidget` helper                 | **Extract** (hoist)         |
+| `dup:e29e4749` | `ui/session-navigation.test.ts` :23 / `ui/session-navigator.test.ts` :47      | duplicated `makeNavigable` factory (identical) | **Extract** (shared helper) |
+| `dup:6268a42f` | `ui/session-navigator.test.ts` :201 / :229                                    | captured-overlay invocation boilerplate        | **Extract** (local helper)  |
+| `dup:ea0a1bce` | `ui/session-navigator.test.ts` :220 / :243                                    | captured-overlay invocation boilerplate        | **Extract** (local helper)  |
+| `dup:b0d55079` | `lifecycle/subagent-manager.test.ts` :92 / :109                               | `resultConsumed`-observer arrange              | **Extract** (local helper)  |
+| `dup:080c5017` | `lifecycle/subagent.test.ts` :257 / :273                                      | "ready subagent" arrange                       | **Extract** (local helper)  |
+| `dup:5d8dbd48` | `lifecycle/subagent-manager.test.ts` :376 / `lifecycle/subagent.test.ts` :717 | resume-events mock body (cross-file)           | **Extract** (shared helper) |
+| `dup:f4c08c00` | `lifecycle/workspace-bracket.test.ts` :90 / :97                               | prepared-bracket arrange                       | **Extract** (local helper)  |
+| `dup:9b42a569` | `tools/spawn-config.test.ts` :43 / :56                                        | `resolveSpawnConfig` act                       | Leave (Non-Goal)            |
+| `dup:ef875c08` | `tools/spawn-config.test.ts` :81 / :95                                        | `resolveSpawnConfig` act                       | Leave (Non-Goal)            |
+| `dup:539a8ca2` | `session/session-config.test.ts` :131 / :151                                  | `assembleSessionConfig` act                    | Leave (Non-Goal)            |
+| `dup:ff841f05` | `lifecycle/concurrency-limiter.test.ts` :21 / :148                            | `schedule` act                                 | Leave (Non-Goal)            |
+| `dup:29158516` | `lifecycle/subagent-manager.test.ts` :335 / :383                              | `spawnBg` + await act                          | Leave (Non-Goal)            |
+| `dup:082c007e` | `lifecycle/subagent-manager.test.ts` :410 / :422                              | `spawnBg` + await act                          | Leave (Non-Goal)            |
+| `dup:a3814745` | `lifecycle/subagent.test.ts` :504 / :533                                      | `agent.run()` act                              | Leave (Non-Goal)            |
+| `dup:230828a8` | `tools/get-result-tool.test.ts` :81 / :89                                     | `execute` act (5 lines)                        | Leave (Non-Goal)            |
+
+Extracting the eight **Extract** families clears those fingerprints and drops the count from 16 to **8** — below the issue's `≤ 10` target — with no act-clone wrapped. (The four primary UI/lifecycle extractions alone reach 10; the cross-file and workspace-bracket arrange extractions take it to 8.)
+
+### Shared-helper extractions (cross-file → `test/helpers/`)
+
+Two clones span two files each, so their helpers must live in `test/helpers/` (the package convention for shared fixtures, with a companion test):
+
+`test/helpers/make-navigable.ts`:
+
+```typescript
+import type { NavigableSubagent } from "#src/ui/session-navigation";
+
+export function makeNavigable(overrides: Partial<NavigableSubagent> = {}): NavigableSubagent {
+  return {
+    id: "agent-1",
+    type: "general-purpose",
+    description: "Test task",
+    status: "completed",
+    startedAt: 1000,
+    completedAt: 4000,
+    toolUses: 2,
+    activeTools: new Map(),
+    responseText: "",
+    agentMessages: [],
+    isSessionReady: () => true,
+    subscribeToUpdates: vi.fn(() => () => {}),
+    getToolDefinition: vi.fn(() => undefined),
+    ...overrides,
+  };
+}
+```
+
+The two source copies are byte-identical (verified with `diff`), so this is a pure lift with no reconciliation.
+Both call sites import it: `import { makeNavigable } from "#test/helpers/make-navigable";`.
+
+`test/helpers/mock-session.ts` (extend the existing helper) — add a resume-events emitter for `dup:5d8dbd48`:
+
+```typescript
+export function emitResumeUsageAndCompaction(session: MockSession): void {
+  session.emit({ type: "message_end", message: { role: "assistant", usage: { input: 70, output: 30, cacheWrite: 5 } } });
+  session.emit({ type: "compaction_end", aborted: false, result: { tokensBefore: 999 }, reason: "overflow" });
+}
+```
+
+Both `subagent-manager.test.ts` and `subagent.test.ts` set this inside a `mockImplementation(async () => { …; return "second"; })`, so the helper emits the events and each call site keeps its own `mockImplementation` wrapper and `return`. (Adding to the already-shared `mock-session.ts` avoids a one-function new module; its companion `mock-session.test.ts` gains a case.)
+
+### Local-helper extractions (single-file)
+
+These stay file-local (the convention reserves `test/helpers/` for cross-file sharing); each is a `function` declared once at the top of its `describe`/module and called from each test, with the **act left explicit** in every test:
+
+- `ui/agent-widget.test.ts` — the `makeWidget(agents)` helper is currently declared *twice* (one per `describe`).
+  Hoist a single copy to module scope (above the first `describe`) and delete the second.
+  The second `describe` uses `vi.useFakeTimers()` in `beforeEach`, but `makeWidget` does not touch timers, so a module-scope definition serves both.
+- `ui/session-navigator.test.ts` — extract a `renderCapturedOverlay(ui): string[]` helper that performs the repeated `const factory = ui.custom.mock.calls[0][0] as (…) => Component; return factory(mockTui(), ansiTheme(), undefined, vi.fn()).render(80);`.
+  This is *result extraction* (reading what the SUT produced), not the act (`new SessionNavigatorHandler().handle(…)` stays explicit in each test).
+  The `#423` reactive-consumer invariant assertion (`expect(record.getToolDefinition).not.toHaveBeenCalled()`) lives in the test body, untouched by the helper.
+- `lifecycle/subagent-manager.test.ts` — extract a local `seedResultConsumedObserver()` returning `{ manager, record, seenConsumed: () => boolean | undefined }` for the two Bug-1 tests; the act (`markConsumed()` before/after `await record.promise`) stays in each test.
+- `lifecycle/subagent.test.ts` — extract a local `makeReadySubagent()` returning `{ agent }` (build `makeSubagent()`, push a message onto a `createMockSession()`, wire `createSubagentSessionStub`/`toSubagentSession`); the act (reading `agent.messages` vs `agent.agentMessages`) stays in each test.
+- `lifecycle/workspace-bracket.test.ts` — extract a local `preparedBracket(addendum?)` async helper that builds the workspace, constructs the `WorkspaceBracket`, and awaits `prepare(ctx)`, returning the bracket; the act (`bracket.dispose(outcome)`) stays in each test.
+
+### Guardrail rationale (why the act-clones stay)
+
+`spawn-config.test.ts` already extracts its arrange (`makeModelInfo`, `testRegistry`, `defaultSettings`); the only remaining duplication is the four-argument `resolveSpawnConfig(...)` call — the SUT.
+`session-config.test.ts`'s clone is the six-argument `assembleSessionConfig(...)` SUT call.
+`concurrency-limiter.test.ts`'s clone is the `schedule(...)` act sequence.
+Wrapping any of these would hide the test subject behind a helper, exactly the anti-pattern the `testing` skill names.
+They are recorded in Non-Goals so a later fallow pass reads them as deliberate.
+
+### Design-review check
+
+The `design-review` checklist (dependency width, Law of Demeter, output arguments, shared-interface changes) targets production wiring.
+This change touches only test arrange code and introduces no production collaborator or shared-interface change, so the checklist finds nothing applicable.
+The new `makeNavigable` helper follows ISP — it returns a full `NavigableSubagent` because both consumers (`listNavigableAgents` fixtures and `SessionNavigatorHandler` records) need the whole shape; there is no unused-field smell.
+
+## Module-Level Changes
+
+New files:
+
+- `packages/pi-subagents/test/helpers/make-navigable.ts` — shared `makeNavigable` factory.
+- `packages/pi-subagents/test/helpers/make-navigable.test.ts` — companion test (per convention).
+
+Changed files:
+
+- `packages/pi-subagents/test/helpers/mock-session.ts` — add `emitResumeUsageAndCompaction(session)`.
+- `packages/pi-subagents/test/helpers/mock-session.test.ts` — add a case for the new emitter.
+- `packages/pi-subagents/test/ui/session-navigation.test.ts` — delete local `makeNavigable`, import the shared one.
+- `packages/pi-subagents/test/ui/session-navigator.test.ts` — delete local `makeNavigable`, import the shared one; add `renderCapturedOverlay` local helper and migrate its two clone sites.
+- `packages/pi-subagents/test/ui/agent-widget.test.ts` — hoist `makeWidget` to a single module-scope definition; delete the duplicate.
+- `packages/pi-subagents/test/lifecycle/subagent-manager.test.ts` — add `seedResultConsumedObserver` local helper (migrate `:92`/`:109`); migrate the `dup:5d8dbd48` resume-mock site to `emitResumeUsageAndCompaction`.
+- `packages/pi-subagents/test/lifecycle/subagent.test.ts` — add `makeReadySubagent` local helper (migrate `:257`/`:273`); migrate the `dup:5d8dbd48` resume-mock site to `emitResumeUsageAndCompaction`.
+- `packages/pi-subagents/test/lifecycle/workspace-bracket.test.ts` — add `preparedBracket` local helper; migrate the four construct-and-prepare sites.
+
+Documentation:
+
+- `packages/pi-subagents/docs/architecture/architecture.md` — Phase 19 Step 7 currently states "Outcome: test clone groups ≤ 10 (from 16); `subagent-manager.test.ts` uses shared factory helpers."
+  Update the Outcome to record the achieved count (8) and that the residual six families are intentional act-clones (left per the `testing` guardrail), so the roadmap and fallow stay reconciled.
+  No layout/complexity table references these test files, so no other architecture edit is needed.
+- No `package-pi-subagents` SKILL.md reference to these helpers or counts — grep confirms no doc symbol to update beyond the architecture Outcome line.
+
+## Test Impact Analysis
+
+1. **New lower-level tests enabled.**
+   `make-navigable.test.ts` and the new `mock-session.test.ts` case pin the shared helpers' default shapes directly — previously each consumer test re-encoded the defaults inline.
+   These are the only genuinely new tests; the rest is arrange consolidation.
+2. **Tests made redundant.**
+   None are removed.
+   The behavior assertions in every migrated test stay exactly as-is; only their arrange/setup lines collapse into a helper call.
+   The local copies of `makeNavigable`/`makeWidget` are deleted (duplication removed), not their tests.
+3. **Tests that must stay as-is.**
+   All act-clone tests (Non-Goals list) keep their explicit SUT call.
+   The `session-navigator.test.ts` `#423` reactive-consumer assertions stay in the test body; `renderCapturedOverlay` only factors out the overlay-rendering boilerplate, not the assertions.
+
+## Invariants at risk
+
+- **`#423` reactive-consumer invariant** (`SessionNavigatorHandler` sources the transcript and never reads tool definitions off the record): pinned by `expect(record.getToolDefinition).not.toHaveBeenCalled()` in `session-navigator.test.ts`.
+  The `renderCapturedOverlay` extraction must leave that assertion in the test body, not absorb it.
+- **Resume usage/compaction accumulation** (`#420`/`#421`/Phase 17 observer lifecycle): pinned by the resume tests in both `subagent-manager.test.ts` and `subagent.test.ts`.
+  `emitResumeUsageAndCompaction` must emit the identical event payloads (`input:70 output:30 cacheWrite:5`, `tokensBefore:999`, `reason:"overflow"`); the migrated tests assert on these exact numbers, so a value drift would surface as a red test in the same step.
+- **Widget background-only filter** (`#444`/`#423`): the hoisted `makeWidget` must keep the `runInBackground: true` default merge (`{ invocation: { runInBackground: true }, ...a }`) — both `describe` copies already share it, so the hoist preserves it verbatim.
+
+Each invariant is already covered by an existing assertion; no new pinning test is required beyond the helper companion tests.
+
+## TDD Order
+
+This is a test-only refactor: there is no new product behavior, so the "green" gate at each step is the **existing suite staying green** after the arrange is consolidated.
+Each step is independently committable and leaves the suite green.
+Run the affected file(s) with `pnpm --filter @gotgenes/pi-subagents exec vitest run <path>` and the full suite before the final commit (shared `test/helpers` changes touch multiple files).
+
+1. **Shared `makeNavigable` fixture.**
+   Add `test/helpers/make-navigable.ts` and `make-navigable.test.ts` (companion: assert default shape + an override).
+   Delete the two local copies in `session-navigation.test.ts` / `session-navigator.test.ts` and import from `#test/helpers/make-navigable`.
+   Run both UI files green.
+   Commit: `test(pi-subagents): extract shared makeNavigable test fixture`.
+2. **`agent-widget` makeWidget hoist.**
+   Hoist one `makeWidget` to module scope; delete the duplicate in the second `describe`.
+   Run `agent-widget.test.ts` green.
+   Commit: `test(pi-subagents): hoist duplicated makeWidget helper`.
+3. **`session-navigator` captured-overlay helper.**
+   Add `renderCapturedOverlay(ui)` and migrate the two clone sites (`dup:6268a42f`, `dup:ea0a1bce`), keeping the `#423` assertions inline.
+   Run `session-navigator.test.ts` green.
+   Commit: `test(pi-subagents): extract captured-overlay render helper`.
+4. **`subagent-manager` resultConsumed arrange + resume-events emitter.**
+   Add `emitResumeUsageAndCompaction` to `mock-session.ts` (+ companion case).
+   Add local `seedResultConsumedObserver` and migrate `:92`/`:109`.
+   Migrate the resume-mock site (`dup:5d8dbd48` manager half) to the emitter.
+   Run `subagent-manager.test.ts` + `mock-session.test.ts` green.
+   Commit: `test(pi-subagents): consolidate subagent-manager arrange helpers`.
+5. **`subagent` ready-subagent arrange + resume-events emitter.**
+   Add local `makeReadySubagent` and migrate `:257`/`:273`.
+   Migrate the resume-mock site (`dup:5d8dbd48` subagent half) to `emitResumeUsageAndCompaction`.
+   Run `subagent.test.ts` green (this clears the cross-file `dup:5d8dbd48` once both halves use the emitter).
+   Commit: `test(pi-subagents): consolidate subagent ready-state arrange`.
+6. **`workspace-bracket` prepared-bracket arrange.**
+   Add local `preparedBracket(addendum?)` and migrate the four construct-and-prepare sites.
+   Run `workspace-bracket.test.ts` green.
+   Commit: `test(pi-subagents): extract preparedBracket setup helper`.
+7. **Verify + document.**
+   Run the full suite, `pnpm run check`, `pnpm run lint`, and `pnpm fallow dupes --workspace @gotgenes/pi-subagents` to confirm the eight target fingerprints are gone and the count is ≤ 10.
+   Update the Phase 19 Step 7 Outcome line in `architecture.md` to the achieved count and the intentional-residual note.
+   Commit: `docs(pi-subagents): reconcile Phase 19 Step 7 outcome with achieved clone count`.
+
+## Risks and Mitigations
+
+- **Risk: hoisting `makeWidget` past the fake-timers `beforeEach` changes timing.**
+  Mitigation: `makeWidget` constructs objects only (no timer calls); the `vi.useFakeTimers()` lives in the second `describe`'s `beforeEach`, unaffected by where the helper is declared.
+  Step 2 runs the file green to confirm.
+- **Risk: the resume-events emitter drifts from one of the two call sites' expected numbers.**
+  Mitigation: both sites currently use identical payloads (verified); the migrated tests assert the exact numbers, so any drift fails red in steps 4–5.
+- **Risk: a `test/helpers` change silently breaks an unrelated importer.**
+  Mitigation: `mock-session.ts` is widely imported; the change is purely additive (new export), and step 4 runs the full suite.
+- **Risk: orphaned imports after deleting local helpers (Biome `noUnusedImports` is warning-level).**
+  Mitigation: after each deletion, re-check the file's imports (e.g. `vi` may still be used elsewhere; `NavigableSubagent` import in the UI files is type-only and still referenced).
+  The step 7 `pnpm run lint` is the backstop.
+- **Risk: fallow re-flags the intentional act-clones in a future audit.**
+  Mitigation: the Non-Goals list and the architecture Outcome note record them as deliberate.
+
+## Open Questions
+
+- None.
+  The guardrail-first / full-live-set scope was settled via the planning `ask_user`; no follow-up issue is warranted because the residual act-clones are intentional, not deferred work.
+
+[#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
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#462]: https://github.com/gotgenes/pi-packages/issues/462
+[#463]: https://github.com/gotgenes/pi-packages/issues/463

package/docs/plans/0470-refresh-readme-command-surface.md

@@ -0,0 +1,159 @@
+---
+issue: 470
+issue_title: "pi-subagents: README still documents the removed /agents command and omits /subagents:settings and /subagents:sessions"
+---
+
+# Refresh pi-subagents README to the post-Phase-19 command surface
+
+## Release Recommendation
+
+**Release:** ship independently
+
+This is a standalone documentation fix.
+It is not a member of any architecture-roadmap step or `Release: batch` — the `dissolve-agents` batch (Steps 5–6, [#442]/[#441]) already shipped as `pi-subagents-v18.0.0`, and this issue corrects README staleness that batch left behind.
+There is no code change and nothing to batch with, so it ships on its own.
+
+## Problem Statement
+
+The Phase 19 terminal cut ([#442], [#441]) removed the `/agents` command, the bespoke conversation viewer, and the agent creation wizard / config editor, replacing them with `/subagents:settings`, `/subagents:sessions`, and the always-on background widget.
+`packages/pi-subagents/README.md` was never updated and still documents the deleted surface as if it were live.
+This shipped to npm with `pi-subagents-v18.0.0`, so the published package's README actively misleads users toward commands and menu actions that no longer exist.
+
+## Goals
+
+- Replace every reference to the removed `/agents` interactive menu with the current focused commands `/subagents:settings` and `/subagents:sessions`.
+- Remove the **Conversation viewer** feature bullet — the live-scrolling overlay was deleted; transcript viewing is now served by `/subagents:sessions`.
+- Remove the **eject** customization story from the Default Agent Types section — the eject/disable/enable/edit/delete menu is gone; customization is now "override by creating `.pi/agents/<name>.md`" and disabling stays `enabled: false` frontmatter (per ADR-0004 Decision C).
+- Rewrite the **Commands** section to document the two real commands instead of the deleted `/agents` menu tree.
+- Correct the **Persistent Settings** section's `/agents` → Settings references to `/subagents:settings`.
+- Correct the **Events** table's `subagents:settings_changed` description (currently "`/agents` → Settings mutation").
+- Add a feature bullet (or amend an existing one) so the read-only session navigation surface (`/subagents:sessions`) is discoverable in the Features list, since the deleted Conversation viewer bullet was its only nearby mention.
+
+## Non-Goals
+
+- No source, test, or behavior changes — this is a pure documentation edit.
+  `src/`, `test/`, the architecture doc, and the ADRs are already accurate (architecture.md lines 405/559 already describe the Phase 19 outcome) and are not touched.
+- No rewrite of accurate sections (Quick Start, UI widget render examples, Default Agent Types table, Custom Agents, Tools, Graceful Max Turns, Concurrency, Worktree Isolation, migration notes, For Extension Authors).
+- No new screenshots or media.
+  The widget render examples in the **UI** section already describe the background-only widget accurately and stay as-is.
+- No change to the `subagents.json` settings-file layering description (global `~/.pi/agent/subagents.json` + project `.pi/subagents.json`) — that mechanism is unchanged; only the command name that writes the project file changed.
+
+## Background
+
+Relevant current surface (verified against `src/index.ts`):
+
+- `pi.registerCommand("subagents:settings", …)` → `SubagentsSettingsHandler.handle({ ui })` — interactive list to set max concurrency, default max turns, and grace turns at runtime (`src/ui/subagents-settings.ts`).
+  This is the re-homed Settings job from the old `/agents` menu; it still persists to the same `subagents.json` files.
+- `pi.registerCommand("subagents:sessions", …)` → `SessionNavigatorHandler.handle({ … agents, evicted, registry, cwd, readFile })` — read-only transcript navigation over `manager.listAgents()` and `manager.listEvicted()`, so any subagent (live or evicted) is navigable (`src/ui/session-navigation.ts`, `session-navigator.ts`).
+
+ADR-0004 Decision C (`docs/decisions/0004-reconsider-ui-direction.md`) is the authority for the customization story the README must now tell:
+
+- Create-new-agent wizard → removed.
+  An operator generates a new agent `.md` by asking a Pi session directly or by writing the file in an editor.
+- Agent-types list + config editor → removed.
+  Viewing/editing definitions is done by opening the `.md` files in an editor/IDE.
+- The eject convenience no longer exists; overriding a default agent is done by creating `.pi/agents/<name>.md` with the same name, and disabling stays `enabled: false` frontmatter.
+
+AGENTS.md constraint that applies: this is a single-package README change, so it lives in `packages/pi-subagents/docs/plans/`.
+The README documents commands, not module filenames, which is exactly why the Phase 19 module-name doc-staleness check missed it (the issue's own root-cause note, Refs [#442]/[#441]).
+
+## Design Overview
+
+Pure prose edit, no decision model or data shapes.
+The README is restructured section-by-section to describe the live surface.
+The one structural choice is how to present the two commands in the **Commands** section: keep the existing two-column command table (`| Command | Description |`) with two rows, then a short subsection per command describing what it opens, instead of the old single-command-plus-menu-tree layout.
+
+### Commands section — target shape (illustrative)
+
+```markdown
+## Commands
+
+| Command               | Description                                            |
+| --------------------- | ------------------------------------------------------ |
+| `/subagents:settings` | Configure subagent settings (concurrency, turn limits) |
+| `/subagents:sessions` | View a subagent's session transcript (read-only)       |
+
+### `/subagents:settings`
+
+Interactive list to tune runtime settings — max concurrency, default max turns, and grace turns.
+Changes persist across pi restarts (see 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).
+```
+
+The command descriptions in the table are copied verbatim from the `registerCommand` calls in `src/index.ts` so the README matches what `/help` shows.
+
+### Customization story — Default Agent Types section
+
+Replace the eject sentence (line 119) with two retained mechanisms only:
+
+```markdown
+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.
+```
+
+(The "ejected … to export them as `.md` files" clause is dropped entirely — there is no eject UI to produce the export.)
+
+## Module-Level Changes
+
+Single file: `packages/pi-subagents/README.md`.
+Line numbers are against the current README (from the issue's "Affected lines"); each is a prose edit, not a code change.
+
+1. **Line 21 — Features list, Conversation viewer bullet.**
+   Remove the `**Conversation viewer**` bullet (it describes selecting an agent in `/agents` to open a live overlay).
+   In its place, add a bullet for read-only session navigation, e.g. `**Session transcripts** — open any subagent's full session transcript (running or evicted) in a read-only viewer via /subagents:sessions`.
+2. **Line 119 — Default Agent Types, eject sentence.**
+   Reword to drop eject; keep override + disable (see Design Overview snippet).
+3. **Lines ~226–303 — Commands + Persistent Settings sections.**
+   - Rewrite the **Commands** section (table row `/agents` and the entire interactive-menu code block + bullet list, lines ~228–252) to document `/subagents:settings` and `/subagents:sessions` per the target shape above.
+   - In **Persistent Settings**, replace each `/agents` → Settings reference (lines 277, 281, 283, 301) with `/subagents:settings`, and "the `/agents` menu never writes here" (line 281) with "the `/subagents:settings` command never writes here", and "without ever touching the menu" (line 300) with "without ever touching the command".
+   - Line 303 failure-behavior sentence: change "the `/agents` toast" to "the `/subagents:settings` toast".
+4. **Line 318 — Events table, `subagents:settings_changed` row.**
+   Change the "When" cell from "`/agents` → Settings mutation was applied" to "`/subagents:settings` mutation was applied".
+
+Doc-staleness cross-checks performed (per plan-issue checklist):
+
+- Grepped the README for every removed term (`/agents`, `eject`/`Eject`, `conversation viewer`, `wizard`, `Create new agent`, `interactive menu`, `menu`) — all occurrences are enumerated in the steps above (lines 21, 119, 228, 230, 235, 241–248, 277, 281, 283, 300, 301, 303, 318).
+- Confirmed no other `packages/pi-subagents/docs/` file or `.pi/skills/package-pi-subagents/SKILL.md` references `/agents` as a live command needing update (architecture.md already describes the Phase 19 removal as past tense; the SKILL.md describes `/subagents:settings`/`/subagents:sessions` already).
+- The **UI** widget-render examples and the **Default Agent Types** table are accurate post-Phase-19 and are left unchanged — verify they are not contradicted by the edits.
+
+## Test Impact Analysis
+
+Not applicable — documentation-only change with no test surface.
+There is no executable behavior to cover; correctness is verified by `pnpm run lint` (rumdl markdown rules) and visual review against `src/index.ts`'s registered commands.
+
+## Invariants at risk
+
+None.
+This change touches no code surface a prior phase step refactored; the Phase 19 spine invariants ([#422]–[#425]) are pinned by existing source/observer/event-contract suites and are untouched by a README edit.
+
+## Build Order
+
+This is a `/build-plan` (docs-only) change, executed as a single reviewable commit — no red→green cycles.
+
+1. Edit `packages/pi-subagents/README.md` per all four Module-Level Changes steps in one pass.
+   Apply one-sentence-per-line formatting (markdown-conventions skill) to all rewritten prose.
+   Suggested commit message: `docs(pi-subagents): refresh README for /subagents:settings and /subagents:sessions (#470)`.
+2. Verify: run `pnpm --filter @gotgenes/pi-subagents run lint` (or `pnpm run lint` at root) to confirm rumdl passes, and re-grep the README for `/agents`, `eject`, `wizard`, `conversation viewer` to confirm zero stale references remain.
+   Cross-check the two command descriptions against `src/index.ts` `registerCommand` strings.
+
+## Risks and Mitigations
+
+- **Risk: missing a stale reference.**
+  Mitigation: the grep in Module-Level Changes enumerated every occurrence; the build step re-greps after editing to confirm none survive.
+- **Risk: command description drift from the actual `/help` text.**
+  Mitigation: copy the table descriptions verbatim from the `registerCommand` calls in `src/index.ts`.
+- **Risk: markdown lint failure on the rewritten Commands table or code fences.**
+  Mitigation: follow markdown-conventions (compact table style, fenced-block languages, sequential numbering) and run `pnpm run lint` before committing.
+
+## Open Questions
+
+None.
+The issue is the operator's own, the surface is verified against source, and no follow-up work is named.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#425]: https://github.com/gotgenes/pi-packages/issues/425