@gotgenes/pi-subagents 18.0.1 → 18.0.2

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

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

@@ -1,268 +0,0 @@
----
-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/0444-shrink-widget-to-background-agents.md

@@ -1,156 +0,0 @@
----
-issue: 444
-issue_title: "pi-subagents: shrink the agent widget to background runs only"
----
-
-# Shrink the agent widget to background runs only
-
-## Release Recommendation
-
-**Release:** ship independently
-
-Phase 19 Step 3 ([architecture roadmap][arch]) is tagged `Release: independent` — it is not a member of any release batch.
-The change is self-contained to `agent-widget.ts` and its tests, touches no public surface, and ADR-0004 explicitly notes it is "independent of the spike."
-
-## Problem Statement
-
-The above-editor agent widget currently renders every agent — foreground and background alike.
-For foreground runs the `subagent` tool's inline `onUpdate` stream already renders live progress, so the widget duplicates that display (ADR-0004 Decision A).
-The widget should survive only as the **background-agent status surface**: the one place with no inline tool-call display, which must represent N parallel background agents at once.
-
-There is also a latent inconsistency to fix.
-`AgentWidget` calls `manager.listAgents()` at two sites — `update()` (which feeds `seedFinishedAgents`, `assembleWidgetState`, and `clearWidget`) and `renderWidget()` (the tree map).
-Filtering at only one site would leave the other rendering foreground agents.
-
-## Goals
-
-- The widget shows only background agents (`record.invocation?.runInBackground === true`); foreground agents never appear.
-- Both `listAgents()` call sites are funneled through a single private accessor that applies the background predicate once at the source.
-- The foreground/widget duplication called out by ADR-0004 Decision A is eliminated.
-- This is a UI behavior refinement, not a public-API or config change — it is **non-breaking** (no exported surface, default, or config shape changes on upgrade).
-
-## Non-Goals
-
-- Relabeling the widget heading from `Agents` to `Background agents` (see Open Questions) — not requested; keep scope tight.
-- Any change to `widget-renderer.ts` rendering logic — it has no foreground-specific path; the fix lives entirely at the data source in `agent-widget.ts`.
-- Other `listAgents()` consumers (`agent-menu.ts`) — those are removed wholesale by Phase 19 Step 5 ([#442]), out of scope here.
-- Native session navigation ([#445], Step 4) and the `/subagents-settings` extraction ([#447], Step 2).
-
-## Background
-
-Relevant modules:
-
-- `src/ui/agent-widget.ts` — `AgentWidget implements SubagentManagerObserver`; self-drives an 80 ms render loop from lifecycle events (Step 4 self-drive, [#423]).
-  `update()` reads `manager.listAgents()` into a local `allAgents`, then passes it to `seedFinishedAgents()`, `assembleWidgetState()`, and (on the idle path) `clearWidget()`.
-  `renderWidget(tui, theme)` independently calls `manager.listAgents().map(r => this.toWidgetAgent(r))` to build the tree.
-- `src/ui/widget-renderer.ts` — pure rendering; `renderWidgetLines()` categorizes agents into running/queued/finished and emits tree lines.
-  It has no knowledge of foreground vs. background — it renders whatever list it receives.
-- `Subagent.invocation` (`src/lifecycle/subagent.ts`) — a readonly `AgentInvocation | undefined` set once at construction.
-  `AgentInvocation.runInBackground` (`src/types.ts`) is the reliable signal: set by `spawn-config.ts` → `AgentInvocation.runInBackground` → stored on `Subagent.invocation`.
-- `AgentSummary` (in `agent-widget.ts`) — the minimal `{ id, status, completedAt }` shape consumed by `assembleWidgetState`/`clearWidget`.
-  `Subagent` is structurally assignable to it, so the accessor can return `Subagent[]` without an interface change.
-
-Constraint from AGENTS.md / package skill: pi-subagents is a minimal core; this is a consumer-side UI behavior change with no policy or core impact.
-
-## Design Overview
-
-Introduce one private accessor on `AgentWidget` and route both existing call sites through it:
-
-```typescript
-/** Background agents only — the widget's sole audience (ADR-0004 Decision A). */
-private listBackgroundAgents(): Subagent[] {
-  return this.manager
-    .listAgents()
-    .filter(record => record.invocation?.runInBackground === true);
-}
-```
-
-Call-site changes:
-
-- `update()` — replace `const allAgents = this.manager.listAgents();` with `const backgroundAgents = this.listBackgroundAgents();` and rename the downstream references (`seedFinishedAgents`, `assembleWidgetState`, `clearWidget`).
-- `renderWidget()` — replace `this.manager.listAgents().map(...)` with `this.listBackgroundAgents().map(...)`.
-
-The predicate `record.invocation?.runInBackground === true` is applied exactly once, at the funnel.
-`undefined` invocation (or `runInBackground` absent/false) is treated as foreground and excluded.
-
-Edge cases verified:
-
-- **`clearWidget` stale-purge:** it deletes `finishedTurnAge` entries for IDs "no longer in the list."
-  Because `seedFinishedAgents` only ever seeds from the background-filtered list, no foreground agent is ever tracked, so purging against the background-only list cannot drop a still-relevant entry — no behavior regression.
-- **Queued agents:** the concurrency limiter queues only background agents (foreground bypasses the queue), so they carry `runInBackground === true` and remain visible; the queued-count display stays accurate.
-- **All-foreground case:** `update()` sees an empty background list → `assembleWidgetState` reports no active/finished → `clearWidget` → widget never registers. `renderWidget()` is consequently never invoked.
-- **Mixed case (the latent bug):** one background running + one foreground running → `update()` registers the widget (1 background active); `renderWidget()` must also filter, or it renders both.
-  Routing both sites through the accessor closes this.
-
-## Module-Level Changes
-
-- `src/ui/agent-widget.ts` — add private `listBackgroundAgents()`; route `update()` and `renderWidget()` through it; rename the `update()` local `allAgents` → `backgroundAgents`.
-- `src/ui/widget-renderer.ts` — **no change.**
-  Verified there is no foreground-specific rendering path; filtering at the data source is sufficient.
-  Listed only to record the verification.
-- `test/ui/agent-widget.test.ts` — migrate existing widget fixtures to set `invocation: { runInBackground: true }` (otherwise the new filter excludes them); add background-only filtering tests.
-- `packages/pi-subagents/README.md` — line ~64, change "showing all active agents" → "showing active background agents" (stale prose once foreground is excluded).
-- `packages/pi-subagents/docs/architecture/architecture.md` — mark Step 3 ✅ with a `Landed`/`Outcome` note; the `src/ui/agent-widget.ts` tree caption at line ~342 stays accurate (generic "live status widget").
-
-Grep sweep performed for stale references to "all agents" / "showing all active agents" across `src/`, `test/`, `.pi/skills/package-pi-subagents/SKILL.md`, and `docs/`:
-
-- `README.md:64` — stale, updated above.
-- `.pi/skills/package-pi-subagents/SKILL.md:57` ("widget ─polls─→ Subagent records (listAgents)") — still accurate (it does poll `listAgents`, now filtered); no edit.
-- `docs/comparison-with-upstream.md:29`, `architecture.md:342` — generic "live above-editor widget"; remain accurate.
-
-## Test Impact Analysis
-
-1. **New tests enabled by the change:**
-   - `update()` excludes foreground agents — an all-foreground agent list leaves the widget unregistered (`lastContent()` undefined).
-   - `renderWidget()` excludes foreground agents — a mixed background+foreground list renders only the background agent's description in the tree (the foreground description is absent).
-     This pins the previously-latent two-site inconsistency.
-2. **Tests that become redundant:** none are removed.
-   The existing widget-behavior fixtures (`makeWidget` in the two `describe` blocks, plus the projection test's `createTestSubagent`) are migrated to set `invocation: { runInBackground: true }` so they continue to exercise the same lifecycle/seeding/self-drive behavior under the new filter.
-3. **Tests that must stay as-is:** the `assembleWidgetState` pure-function suite — it calls the pure function directly with `AgentSummary[]`, not through the accessor, so it is unaffected by the filter and continues to pin the counting logic.
-
-## Invariants at risk
-
-This step touches `agent-widget.ts`, which prior phases already refactored.
-The fixture migration must keep these invariants pinned (the tests stay, only their `invocation` field is added):
-
-- **Self-drive from lifecycle ([#423]):** `onSubagentStarted`/`onSubagentCreated` start the 80 ms timer and render; `onSubagentCompleted`/`onSubagentCompacted` render.
-  Pinned by the "self-drives from lifecycle notifications" describe block — fixtures migrated to background invocation so the manager stub's agents survive the filter.
-- **`seedFinishedAgents` idempotency / linger aging ([#374]):** finished agents seed once, age out after 1 turn (errors after 2), and `update()` never advances the age without a turn.
-  Pinned by the "update self-seeds finished agents" describe block — fixtures migrated to background invocation.
-
-A later step must not regress these with a green suite; the migration preserves the assertions verbatim apart from the `invocation` field.
-
-## TDD Order
-
-1. **`test:` migrate widget fixtures to background invocation (preparatory / tidy-first).**
-   Surface: `test/ui/agent-widget.test.ts`.
-   Add `invocation: { runInBackground: true }` to the `makeWidget` agent stubs (both `describe` blocks) and to the projection test's `createTestSubagent` call.
-   No production change — the filter does not exist yet, so the field is inert and the suite stays green.
-   This makes the next step a clean addition rather than a mass fixture rewrite.
-   Commit: `test: set background invocation on agent-widget fixtures (#444)`.
-2. **`feat:` filter the widget to background agents only.**
-   Red: add (a) an all-foreground list leaves the widget unregistered, and (b) a mixed background+foreground list renders only the background agent in `renderWidget()`.
-   Green: add the private `listBackgroundAgents()` accessor; route both `update()` and `renderWidget()` through it; rename the `update()` local to `backgroundAgents`.
-   Commit: `feat: shrink agent widget to background runs only (#444)`.
-3. **`docs:` update widget docs for background-only behavior.**
-   Update `README.md` ("all active agents" → "active background agents") and mark Phase 19 Step 3 ✅ with a `Landed`/`Outcome` note in `docs/architecture/architecture.md`.
-   Commit: `docs: note background-only widget in README and roadmap (#444)`.
-
-## Risks and Mitigations
-
-- **Mass test breakage when the filter lands** — every `update()`-driven fixture would be filtered out and assertions would fail.
-  Mitigation: TDD step 1 migrates all fixtures first (inert until the filter exists), so step 2 only adds new tests.
-- **A foreground agent the operator expected to see disappears** — intended per ADR-0004 Decision A; the inline `onUpdate` stream is authoritative for foreground runs.
-- **`clearWidget` stale-purge dropping a relevant entry** — analyzed in Design Overview; foreground agents are never seeded, so purging against the background-only list is correct.
-
-## Open Questions
-
-- Should the widget heading read `Background agents` instead of `Agents`?
-  Deferred — not in the issue scope; revisit if the bare label reads as ambiguous in practice.
-
-[arch]: ../architecture/architecture.md
-[#442]: https://github.com/gotgenes/pi-packages/issues/442
-[#445]: https://github.com/gotgenes/pi-packages/issues/445
-[#447]: https://github.com/gotgenes/pi-packages/issues/447
-[#423]: https://github.com/gotgenes/pi-packages/issues/423
-[#374]: https://github.com/gotgenes/pi-packages/issues/374