@gotgenes/pi-subagents 18.0.0 → 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/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