@gotgenes/pi-subagents 7.2.8 → 7.3.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.3.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.0...pi-subagents-v7.3.1) (2026-05-25)
+
+
+### Bug Fixes
+
+* add parameter type annotations to shared test fixture factories ([2953adc](https://github.com/gotgenes/pi-packages/commit/2953adc5761dd4aa2d3c592ea5f8856161e01e3a))
+
+
+### Documentation
+
+* plan extract shared test fixtures ([#208](https://github.com/gotgenes/pi-packages/issues/208)) ([22fafed](https://github.com/gotgenes/pi-packages/commit/22fafed860134f00f1b5d6cb7c87fa42be7dcf09))
+* **retro:** add planning stage notes for issue [#208](https://github.com/gotgenes/pi-packages/issues/208) ([aaa9d5d](https://github.com/gotgenes/pi-packages/commit/aaa9d5d0a4654b2ebb25a7ad4d11a3a54db7c206))
+* **retro:** add retro notes for issue [#207](https://github.com/gotgenes/pi-packages/issues/207) ([3b97a5c](https://github.com/gotgenes/pi-packages/commit/3b97a5c5b3fbb98a78ba280fbdbbdf55f61d82fc))
+* **retro:** add TDD stage notes for issue [#208](https://github.com/gotgenes/pi-packages/issues/208) ([65d0606](https://github.com/gotgenes/pi-packages/commit/65d0606167e531518bd8de4d33f91c6080e21723))
+* update Phase 12 Step 4 to reference test/helpers/ ([8e9e406](https://github.com/gotgenes/pi-packages/commit/8e9e406bfe12487f67363b223d037664f842acce))
+
+## [7.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.8...pi-subagents-v7.3.0) (2026-05-25)
+
+
+### Features
+
+* extract assembleWidgetState from agent-widget update ([c63fdac](https://github.com/gotgenes/pi-packages/commit/c63fdacdb184f989598ebafbf595cc9c01c9d3a0))
+
+
+### Documentation
+
+* plan decompose update in agent-widget.ts ([#207](https://github.com/gotgenes/pi-packages/issues/207)) ([5ae2e74](https://github.com/gotgenes/pi-packages/commit/5ae2e74385753cd8e68504f767539aff019e5d08))
+* plan decompose update in agent-widget.ts ([#207](https://github.com/gotgenes/pi-packages/issues/207)) ([fb30d98](https://github.com/gotgenes/pi-packages/commit/fb30d98fc0fcc2c3cd6f016b78251cdb4caf6d96))
+* **retro:** add planning stage notes for issue [#207](https://github.com/gotgenes/pi-packages/issues/207) ([1624d2d](https://github.com/gotgenes/pi-packages/commit/1624d2d4aef5fee77db319940de7e2a3e93a8a27))
+* **retro:** add planning stage notes for issue [#207](https://github.com/gotgenes/pi-packages/issues/207) ([931ff0e](https://github.com/gotgenes/pi-packages/commit/931ff0ea3810d87a35f49b3b671d1ef4d88d55f7))
+* **retro:** add TDD stage notes for issue [#207](https://github.com/gotgenes/pi-packages/issues/207) ([770940a](https://github.com/gotgenes/pi-packages/commit/770940a3ff5c6b7ddd84ac35a4352ffc6c7c189e))
+* update complexity hotspots after widget decomposition ([5848a17](https://github.com/gotgenes/pi-packages/commit/5848a173158f13fa58ccd357edf9a310559f92e1))
+
 ## [7.2.8](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.7...pi-subagents-v7.2.8) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -466,10 +466,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 
 Functions with cyclomatic complexity ≥ 21 (critical threshold):
 
-| Function            | Cyclomatic | Cognitive | File                        | Concern                         |
-| ------------------- | ---------- | --------- | --------------------------- | ------------------------------- |
-| `renderWidgetLines` | 25         | 44        | `ui/widget-renderer.ts`     | Renders widget status lines     |
-| `update`            | 21         | 31        | `ui/agent-widget.ts`        | Widget lifecycle + polling      |
+No functions remain above the critical threshold — all hotspots resolved in Phase 12.
 
 ### Churn hotspots
 
@@ -640,10 +637,10 @@ The 3 heaviest clone families:
 - `agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts` (54+51+24 lines)
 - `agent-manager.test.ts` (18 internal clone groups, 210 duplicated lines)
 
-Extract shared factories into `test/fixtures/` modules.
+Extract shared factories into `test/helpers/` modules.
 
-- Target: new `test/fixtures/` modules
-- Outcome: test duplication reduced by ~400 lines
+- Target: new `test/helpers/runner-io.ts` and `test/helpers/ui-stubs.ts` modules
+- Outcome: test duplication reduced by ~250 lines
 
 ## Refactoring history
 

package/docs/plans/0207-decompose-agent-widget-update.md

@@ -0,0 +1,242 @@
+---
+issue: 207
+issue_title: "Decompose update in agent-widget.ts (cognitive 31)"
+---
+
+# Decompose `update` in `agent-widget.ts`
+
+## Problem Statement
+
+`update` in `ui/agent-widget.ts` has cognitive complexity 31 (CRITICAL per fallow health).
+It mixes agent state categorization, widget teardown, status bar management, and widget registration dispatch in a single 70-line method.
+Phase 12, Step 3 targets cognitive complexity < 10 per function.
+
+## Goals
+
+- Extract `assembleWidgetState` as an exported pure function (agent list → lightweight counts/flags) that is directly unit-testable.
+- Extract `clearWidget` as a private method encapsulating the "nothing to show" teardown path.
+- Extract `updateStatusBar` as a private method encapsulating status text computation and conditional update.
+- Simplify `update` to a thin orchestrator: guard → assemble → if idle clear → else update status + register.
+- Target: cognitive complexity < 10 for every function in the file.
+
+## Non-Goals
+
+- Decomposing `renderWidgetLines` (#205, done), `showAgentDetail` (#206, done), or shared test fixtures (#208) — sibling Phase 12 steps.
+- Extracting a separate timer-manager class — the timer lifecycle (`ensureTimer` + `clearWidget`) is two lines of `setInterval`/`clearInterval`.
+- Changing the widget's visual output, status bar format, registration timing, or timer interval.
+- Narrowing the `AgentManager` dependency to an interface — tracked separately.
+- Adding end-to-end tests for `AgentWidget` — the widget depends on the Pi TUI context.
+- Changing `dispose` behavior — it remains a shutdown-only teardown path.
+
+## Background
+
+`agent-widget.ts` was substantially decomposed in #148 (Phase 9, Step P), which extracted pure rendering into `widget-renderer.ts`.
+The widget shrank from 374 to ~198 lines.
+`update` remained as a 70-line orchestrator with five interwoven concerns:
+
+1. **Guard** — early return when `uiCtx` is not yet set.
+2. **Agent state categorization** — counting running/queued/finished agents from `listAgents()`.
+3. **Clear path** — unregistering widget, clearing status, stopping timer, cleaning stale `finishedTurnAge` entries.
+4. **Status bar update** — computing status text from running/queued counts, conditionally calling `setStatus`.
+5. **Widget lifecycle** — incrementing `widgetFrame`, registering the widget factory on first use, calling `requestRender()` on subsequent ticks.
+
+Concerns 3–4 consume counts from concern 2 but each has a distinct responsibility.
+
+`categorizeAgents` in `widget-renderer.ts` performs a similar filter but returns full `WidgetAgent[]` arrays for rendering.
+`assembleWidgetState` returns lightweight counts for lifecycle decisions — different outputs for different consumers, not duplication.
+
+No existing tests cover `AgentWidget` methods — `test/widget-renderer.test.ts` covers the rendering layer.
+
+### Complexity sources in `update` (cognitive 31)
+
+1. Agent counting loop with 3-branch if/else (`status` checks + `shouldShowFinished`) — contributes ~6.
+2. Conditional widget clear path: nested checks for `widgetRegistered`, `lastStatusText`, `widgetInterval`, plus a `for`-loop with nested `if` for stale-entry cleanup — contributes ~12.
+3. Status text computation with conditional `if (hasActive)` and nested `if`/push branches — contributes ~5.
+4. Conditional status update (`newStatusText !== this.lastStatusText`) — contributes ~2.
+5. Widget registration dispatch (`if (!widgetRegistered) ... else ...`) — contributes ~4.
+
+### `dispose` is not a duplication target
+
+`dispose` (10 lines, cognitive ~2) and `update`'s idle path share *some* statements — `clearInterval`, `setWidget(undefined)`, `setStatus(undefined)`, flag resets — but differ in two ways:
+
+- **Guards:** `update`'s idle path guards each call (`if (widgetRegistered)`, `if (lastStatusText !== undefined)`) to avoid redundant SDK calls during repeated timer ticks.
+  `dispose` unconditionally calls `setWidget`/`setStatus` (when `uiCtx` exists) as a correctness guarantee during shutdown.
+- **Stale-entry cleanup:** `update`'s idle path cleans `finishedTurnAge` entries for agents no longer in `listAgents()`.
+  `dispose` skips this — the Map is about to be garbage collected.
+
+Per the code-design skill ("duplication is far cheaper than the wrong abstraction" — verify structural context before extracting), these are different lifecycle semantics.
+`dispose` stays as-is; `clearWidget` is extracted only from `update`'s idle path.
+
+## Design Overview
+
+### `assembleWidgetState` (exported, pure)
+
+```typescript
+/** Minimal agent shape needed for widget lifecycle decisions. */
+interface AgentSummary {
+  readonly id: string;
+  readonly status: string;
+  readonly completedAt?: number;
+}
+
+export interface WidgetState {
+  readonly runningCount: number;
+  readonly queuedCount: number;
+  readonly hasFinished: boolean;
+  readonly hasActive: boolean;
+}
+
+export function assembleWidgetState(
+  agents: readonly AgentSummary[],
+  shouldShowFinished: (agentId: string, status: string) => boolean,
+): WidgetState
+```
+
+The input uses a local `AgentSummary` interface (3 fields) rather than `WidgetAgent` (10+ fields).
+This follows ISP — `assembleWidgetState` only reads `id`, `status`, and `completedAt`.
+Tests can pass plain objects without constructing full agent fixtures.
+`AgentRecord` satisfies `AgentSummary` structurally, so no adapter is needed at the call site.
+
+`hasActive` is derived from the counts (`runningCount > 0 || queuedCount > 0`) but included for call-site readability.
+Only `assembleWidgetState` constructs `WidgetState`, so consistency is guaranteed.
+
+### `clearWidget` (private method)
+
+Encapsulates `update`'s "nothing to show" teardown path:
+
+- Unregister widget via `setWidget("agents", undefined)` if `widgetRegistered`.
+- Clear status via `setStatus("subagents", undefined)` if `lastStatusText` is set.
+- Stop timer via `clearInterval` if `widgetInterval` is running.
+- Reset lifecycle flags (`widgetRegistered`, `tui`, `lastStatusText`, `widgetInterval`).
+- Clean stale `finishedTurnAge` entries (agents no longer in `allAgents`).
+
+Accepts `allAgents` as a parameter for the stale-entry cleanup.
+
+```typescript
+private clearWidget(allAgents: readonly AgentSummary[]): void
+```
+
+`dispose` does **not** delegate to `clearWidget` — see "dispose is not a duplication target" above.
+
+### `updateStatusBar` (private method)
+
+Encapsulates the status text concern:
+
+- Compute status text from `runningCount` / `queuedCount` (undefined when `!hasActive`).
+- Call `setStatus("subagents", text)` only when text differs from `lastStatusText`.
+- Cache the new value in `lastStatusText`.
+
+```typescript
+private updateStatusBar(state: WidgetState): void
+```
+
+### After refactoring
+
+```typescript
+update() {
+  if (!this.uiCtx) return;
+
+  const allAgents = this.manager.listAgents();
+  const state = assembleWidgetState(allAgents, (id, status) => this.shouldShowFinished(id, status));
+
+  if (!state.hasActive && !state.hasFinished) {
+    this.clearWidget(allAgents);
+    return;
+  }
+
+  this.updateStatusBar(state);
+  this.widgetFrame++;
+
+  if (!this.widgetRegistered) {
+    this.uiCtx.setWidget("agents", (tui, theme) => {
+      this.tui = tui;
+      return {
+        render: () => this.renderWidget(tui, theme),
+        invalidate: () => {
+          this.widgetRegistered = false;
+          this.tui = undefined;
+        },
+      };
+    }, { placement: "aboveEditor" });
+    this.widgetRegistered = true;
+  } else {
+    this.tui?.requestRender();
+  }
+}
+```
+
+Cognitive complexity: ~4 (one guard early return + one if/else branch + flat registration dispatch).
+
+### Complexity budget
+
+| Function              | Estimated cognitive complexity                  |
+| --------------------- | ----------------------------------------------- |
+| `assembleWidgetState` | ~3 (flat loop with 3 branches)                  |
+| `clearWidget`         | ~6 (4 guards + loop with if)                    |
+| `updateStatusBar`     | ~4 (hasActive check + diff check)               |
+| `update` (after)      | ~4 (guard + idle check + registration dispatch) |
+| `dispose` (unchanged) | ~2                                              |
+
+All under 10.
+
+## Module-Level Changes
+
+### Changed: `src/ui/agent-widget.ts`
+
+- Add local `AgentSummary` interface (3 fields: `id`, `status`, `completedAt?`).
+- Add exported `WidgetState` interface.
+- Add exported `assembleWidgetState(agents, shouldShowFinished)` pure function.
+- Add private `clearWidget(allAgents)` method — extracted from `update`'s idle path.
+- Add private `updateStatusBar(state)` method — extracted from `update`'s status bar logic.
+- Simplify `update` to orchestrate: guard → assemble → if idle clear → else update status + register.
+- `dispose` is unchanged.
+
+No exports are removed or renamed.
+The public API (`AgentWidget` class with `setUICtx`, `onTurnStart`, `ensureTimer`, `markFinished`, `update`, `dispose`) is unchanged.
+`UICtx` type stays exported.
+
+### Unchanged: `test/widget-renderer.test.ts`
+
+No changes — this file covers `widget-renderer.ts` functions, not `agent-widget.ts`.
+
+### Changed: `docs/architecture/architecture.md`
+
+- Update the complexity hotspots table: remove `update` row (no longer ≥ 21 cyclomatic).
+- Also remove the `renderWidgetLines` row if #205 is already implemented (it is — closed).
+
+## Test Impact Analysis
+
+1. **New tests enabled:** Direct unit tests for `assembleWidgetState` — a pure function accepting plain objects.
+   Tests cover: empty list, running-only, queued-only, finished-only, mixed states, `shouldShowFinished` filtering, agents without `completedAt` excluded from finished.
+   The narrow `AgentSummary` input type means test fixtures are 3-field objects — no need for full agent records.
+2. **No existing tests become redundant** — there are currently no tests for `AgentWidget`.
+3. **No existing tests must change** — `test/widget-renderer.test.ts` (23 tests) exercises the renderer layer and is unaffected.
+
+## TDD Order
+
+1. **Red → Green:** Write unit tests for `assembleWidgetState` covering all agent status combinations.
+   Add the `AgentSummary` interface, `WidgetState` interface, and `assembleWidgetState` function as exported module-level items.
+   Implement to make tests pass.
+   Commit: `feat: extract assembleWidgetState from agent-widget update`
+
+2. **Refactor:** Wire `update` to use `assembleWidgetState`.
+   Extract `clearWidget(allAgents)` method from the idle path.
+   Extract `updateStatusBar(state)` method from the status bar logic.
+   All existing tests pass (no behavior change, no export changes, `dispose` unchanged).
+   Commit: `refactor: decompose update into clearWidget and updateStatusBar`
+
+3. **Docs:** Update the complexity hotspots table in `docs/architecture/architecture.md`.
+   Remove both `renderWidgetLines` (done in #205) and `update` rows.
+   Commit: `docs: update complexity hotspots after widget decomposition`
+
+## Risks and Mitigations
+
+| Risk                                                                                                            | Mitigation                                                                                                                                                                             |
+| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assembleWidgetState` has overlapping categorization with `categorizeAgents` in `widget-renderer.ts`            | Different outputs for different consumers: counts+flags for lifecycle vs. full arrays for rendering. Not duplication.                                                                  |
+| No existing tests for `AgentWidget` — refactoring risks are higher for `clearWidget`/`updateStatusBar`          | The pure function `assembleWidgetState` is tested directly. The method extractions are mechanical code moves with no semantic change — the type checker verifies structural integrity. |
+| `clearWidget` guards redundant SDK calls (`if (widgetRegistered)`) — caller might expect unconditional teardown | Only `update`'s idle path calls `clearWidget`. `dispose` stays as-is with its own unconditional teardown semantics.                                                                    |
+
+## Open Questions
+
+None — the decomposition is a mechanical extraction of existing code into named functions and methods, following the pattern established by Phase 12 Steps 1 and 2.

package/docs/plans/0208-extract-shared-test-fixtures.md

@@ -0,0 +1,298 @@
+---
+issue: 208
+issue_title: "Extract shared test fixtures to reduce test duplication"
+---
+
+# Extract shared test fixtures
+
+## Problem Statement
+
+Test duplication across the pi-subagents package is 1,367 lines (7.2%) across 23 files (67 clone groups per fallow analysis).
+The three heaviest clone families are:
+
+1. Runner IO tests (`agent-runner.test.ts` + `agent-runner-extension-tools.test.ts` + `concrete-agent-runner.test.ts`): 60-line shared setup — `createRunnerIO()`, `AgentConfigLookup` stub, `ParentSnapshot` constant.
+2. Menu/wizard UI tests (`agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts`): 54+51+24 lines — `makeFileOps()`, `makeUI()`, `makeManager()`, `AgentConfig` defaults, `ParentSnapshot` constant.
+3. `agent-manager.test.ts` internal: 18 clone groups, 210 duplicated lines — repetitive `manager.spawn(...)` call patterns.
+
+Issue #131 (closed) already extracted `createMockSession`, `createToolDeps`, and `createTestRecord` into `test/helpers/`.
+This issue targets the remaining duplication families.
+
+## Goals
+
+- Extract `createRunnerIO()` and `createAgentLookup()` into `test/helpers/runner-io.ts` — single source of truth for the `RunnerIO` and `AgentConfigLookup` stubs used by runner tests.
+- Extract `makeFileOps()`, `makeMenuUI()`, `makeMenuManager()`, and `createTestAgentConfig()` into `test/helpers/ui-stubs.ts` — shared factories for the three UI test files.
+- Consolidate `agent-manager.test.ts` internal duplication with local helper functions (`spawnBg`, `spawnFg`).
+- Replace local `ParentSnapshot` definitions with the existing `STUB_SNAPSHOT` from `test/helpers/stub-ctx.ts` where possible.
+- Remove stale `buildMemoryBlock` and `buildReadOnlyMemoryBlock` stubs from the `createRunnerIO` factory (these methods no longer exist on `AssemblerIO`).
+- Target: ~250 lines of test duplication removed.
+
+## Non-Goals
+
+- Extracting session mock factories from the runner tests — each file's session factory serves a specialized purpose (`createSession(finalText)`, `createSessionWithExtensionToolRegistration(beforeBind, afterBind)`, `makeSession(text)`) and the variance is structural, not incidental.
+- Extracting `makeSettings()` from `agent-menu.test.ts` — only used in one file.
+- Extracting `makeHandler()` / `makeEditor()` / `makeDeps()` wrapper functions that compose collaborator stubs for specific handlers — too tightly coupled to each file's test structure.
+- Extracting the mutable `agentConfigMock` pattern from `agent-runner-extension-tools.test.ts` — its per-test config mutation is inherently local.
+- Decomposing UI complexity (Steps 1–3 of Phase 12, issues #205, #206, #207) — separate issues.
+
+## Background
+
+### Existing test helpers
+
+`test/helpers/` already contains shared factories from issue #131:
+
+| File              | Exports                                   | Used by                                                 |
+| ----------------- | ----------------------------------------- | ------------------------------------------------------- |
+| `mock-session.ts` | `createMockSession()`, `toAgentSession()` | agent-manager, record-observer, ui-observer tests       |
+| `make-deps.ts`    | `createToolDeps()`                        | agent-tool, background-spawner, foreground-runner tests |
+| `make-record.ts`  | `createTestRecord()`                      | tool tests, UI tests                                    |
+| `stub-ctx.ts`     | `STUB_CTX`, `STUB_SNAPSHOT`               | tool tests (via `make-deps.ts`)                         |
+
+The new factories follow the same pattern: shared files in `test/helpers/` with optional unit tests.
+
+### Architecture doc reference
+
+Phase 12, Step 4 in `docs/architecture/architecture.md` (lines 637–644) calls for `test/fixtures/` modules.
+We use `test/helpers/` instead to follow the existing convention established in issue #131.
+The architecture doc reference will be updated as part of this work.
+
+### Interface shapes
+
+`RunnerIO` = `EnvironmentIO & SessionFactoryIO` (in `src/lifecycle/agent-runner.ts`):
+
+```typescript
+interface EnvironmentIO {
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  getAgentDir: () => string;
+  deriveSessionDir: (parentSessionFile: string | undefined, cwd: string) => string;
+}
+
+interface SessionFactoryIO {
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
+  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
+  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  assemblerIO: AssemblerIO;
+}
+```
+
+`AssemblerIO` (in `src/session/session-config.ts`) has only `preloadSkills` and `buildAgentPrompt`.
+The existing test factories in `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` include stale `buildMemoryBlock` and `buildReadOnlyMemoryBlock` stubs that no longer match the interface — the shared factory will omit them.
+
+### Duplication diff: default values across copies
+
+Before extracting, the following differences across copies were identified:
+
+**`createRunnerIO` / `makeIO`:**
+
+| Field                                  | agent-runner    | extension-tools | concrete-agent-runner |
+| -------------------------------------- | --------------- | --------------- | --------------------- |
+| `assemblerIO.buildMemoryBlock`         | present (stale) | present (stale) | absent                |
+| `assemblerIO.buildReadOnlyMemoryBlock` | present (stale) | absent          | absent                |
+| Other fields                           | identical       | identical       | identical             |
+
+**`ParentSnapshot` stubs:**
+
+| Field                        | agent-runner    | extension-tools | concrete-agent-runner | agent-manager   | agent-menu/wizard | STUB_SNAPSHOT     |
+| ---------------------------- | --------------- | --------------- | --------------------- | --------------- | ----------------- | ----------------- |
+| `cwd`                        | "/tmp"          | "/tmp"          | "/workspace"          | "/tmp"          | "/test"           | "/test"           |
+| `systemPrompt`               | "parent prompt" | "parent prompt" | ""                    | "parent prompt" | ""                | "test prompt"     |
+| `model`                      | undefined       | undefined       | {}                    | undefined       | {}                | undefined         |
+| `modelRegistry.find`         | vi.fn()         | vi.fn()         | vi.fn()               | vi.fn()         | `() => undefined` | `() => undefined` |
+| `modelRegistry.getAvailable` | vi.fn()         | vi.fn()         | —                     | —               | —                 | —                 |
+
+None of the consumer tests assert on `cwd`, `systemPrompt`, `model`, or `modelRegistry.find` return values — these fields are passed through to functions that are already mocked.
+Using `STUB_SNAPSHOT` is safe for all consumers.
+
+**`makeFileOps`:** character-for-character identical in all three UI test files.
+
+**`makeUI`:** identical core in wizard and config-editor; agent-menu wraps it in an outer `{ ui, modelRegistry, parentSnapshot }` object.
+
+**`makeManager`:** identical in agent-menu and wizard.
+
+**`testDefaultAgentConfig`:** identical in agent-menu and config-editor (same 9 fields).
+
+## Design Overview
+
+### `test/helpers/runner-io.ts`
+
+Two exports:
+
+```typescript
+/** Shared RunnerIO stub factory for agent-runner tests. */
+function createRunnerIO(assemblerOverrides?: Partial<AssemblerIOStub>): RunnerIOStub;
+
+/** Shared AgentConfigLookup stub. Returns a static Explore config by default. */
+function createAgentLookup(config?: Partial<AgentConfig>): AgentLookupStub;
+```
+
+`createRunnerIO` builds the full `RunnerIO` stub shape.
+The `assemblerIO` sub-object defaults to stubs for `preloadSkills` and `buildAgentPrompt` only (matching the current `AssemblerIO` interface).
+`assemblerOverrides` lets tests customize individual methods without rebuilding the entire factory.
+
+`createAgentLookup` returns `{ resolveAgentConfig, getToolNamesForType }` wrapping a static config.
+The default config is the Explore agent used in `agent-runner.test.ts` and `concrete-agent-runner.test.ts`.
+Tests that need per-test config mutation (extension-tools) keep their local mutable wrapper but use the default config as a starting point.
+
+Return types are deliberately unannotated (per testing skill) so `vi.fn()` stubs retain their `Mock<...>` methods.
+
+### `test/helpers/ui-stubs.ts`
+
+Four exports:
+
+```typescript
+/** FileOps stub — identical across all three UI test files. */
+function makeFileOps(): FileOpsStub;
+
+/** MenuUI stub with sequential select responses. */
+function makeMenuUI(selectResults?: (string | undefined)[]): MenuUIStub;
+
+/** Manager stub for UI tests (listAgents, getRecord, spawnAndWait). */
+function makeMenuManager(): MenuManagerStub;
+
+/** AgentConfig factory with sensible defaults and override support. */
+function createTestAgentConfig(overrides?: Partial<AgentConfig>): AgentConfig;
+```
+
+`makeMenuUI` returns the flat UI shape (select, input, confirm, editor, notify, custom).
+`agent-menu.test.ts` wraps this locally into its `{ ui, modelRegistry, parentSnapshot }` structure — the wrapping stays in the test file because it's specific to `AgentsMenuHandler`'s interface.
+
+### `agent-manager.test.ts` local helpers
+
+Two local helpers reduce the 42 repetitive `manager.spawn(...)` calls:
+
+```typescript
+function spawnBg(mgr: AgentManager, prompt = "test", desc = prompt) {
+  return mgr.spawn(STUB_SNAPSHOT, "general-purpose", prompt, {
+    description: desc,
+    isBackground: true,
+  });
+}
+
+function spawnFg(mgr: AgentManager, prompt = "test", desc = prompt) {
+  return mgr.spawnAndWait(STUB_SNAPSHOT, "general-purpose", prompt, {
+    description: desc,
+  });
+}
+```
+
+These stay local because they are only needed in this file.
+They also replace the local `mockSnapshot` with the imported `STUB_SNAPSHOT`.
+
+## Module-Level Changes
+
+### New files
+
+1. `test/helpers/runner-io.ts` — exports `createRunnerIO()`, `createAgentLookup()`.
+2. `test/helpers/runner-io.test.ts` — unit tests: verifies stub shape satisfies `RunnerIO`, override merging, default config shape.
+3. `test/helpers/ui-stubs.ts` — exports `makeFileOps()`, `makeMenuUI()`, `makeMenuManager()`, `createTestAgentConfig()`.
+4. `test/helpers/ui-stubs.test.ts` — unit tests: verifies stub shapes, sequential select behavior, config override merging.
+
+### Modified files
+
+1. `test/lifecycle/agent-runner.test.ts` — remove local `createRunnerIO()`, `mockAgentLookup`, `snapshot`, `exec`; import from helpers.
+2. `test/lifecycle/agent-runner-extension-tools.test.ts` — remove local `createRunnerIO()`, `snapshot`; import from helpers; keep local mutable `agentConfigMock` and `mockAgentLookup` (they use the mutable wrapper pattern).
+3. `test/lifecycle/concrete-agent-runner.test.ts` — remove local `makeIO()`, `registry`, `snapshot`; import from helpers.
+4. `test/lifecycle/agent-manager.test.ts` — remove local `mockSnapshot`; import `STUB_SNAPSHOT`; add local `spawnBg()` and `spawnFg()` helpers; update all `manager.spawn(mockSnapshot, ...)` calls.
+5. `test/ui/agent-menu.test.ts` — remove local `makeFileOps()`, `makeManager()`, `testDefaultAgentConfig`, `stubParentSnapshot`; import from helpers; keep local `makeSettings()` and `makeHandler()`.
+6. `test/ui/agent-creation-wizard.test.ts` — remove local `makeFileOps()`, `makeManager()`, `stubParentSnapshot`; import from helpers; keep local `makeDeps()`.
+7. `test/ui/agent-config-editor.test.ts` — remove local `makeFileOps()`, `testDefaultConfig`, `testCustomConfig`; import from helpers; keep local `makeEditor()`.
+
+### Doc updates
+
+1. `docs/architecture/architecture.md` — update Phase 12 Step 4 reference from `test/fixtures/` to `test/helpers/` (lines 640, 642).
+
+## Test Impact Analysis
+
+1. The new factory unit tests (`runner-io.test.ts`, `ui-stubs.test.ts`) verify shared fixture behavior that was previously only implicitly tested through consumer test files.
+   This enables targeted debugging when a mock shape drifts from the production interface.
+2. No existing tests become redundant — consumer tests exercise distinct production behavior that the factory tests do not cover.
+3. All existing tests stay as-is in terms of assertions.
+   Only the setup code (local factory → shared import) changes.
+4. The removal of stale `buildMemoryBlock` and `buildReadOnlyMemoryBlock` stubs from `createRunnerIO` is safe because `AssemblerIO` no longer declares these methods — structural typing means they were always no-ops.
+
+## TDD Order
+
+1. **Red → Green: `createRunnerIO` and `createAgentLookup` factories.**
+   Write `test/helpers/runner-io.test.ts` — verify `createRunnerIO()` returns a shape satisfying `RunnerIO` (`EnvironmentIO & SessionFactoryIO`), verify `assemblerIO` override merging, verify `createAgentLookup()` returns the default Explore config and accepts overrides.
+   Implement `test/helpers/runner-io.ts`.
+   Run: `pnpm vitest run test/helpers/runner-io.test.ts`.
+   Commit: `test: add createRunnerIO and createAgentLookup shared test fixtures`
+
+2. **Green: migrate `agent-runner.test.ts` to shared runner-io factories.**
+   Import `createRunnerIO`, `createAgentLookup` from helpers.
+   Import `STUB_SNAPSHOT` from `stub-ctx.ts`.
+   Remove local `createRunnerIO()`, `mockAgentLookup`, `snapshot`.
+   Run: `pnpm vitest run test/lifecycle/agent-runner.test.ts`.
+   Commit: `test: use shared runner-io fixtures in agent-runner tests`
+
+3. **Green: migrate `agent-runner-extension-tools.test.ts` to shared `createRunnerIO`.**
+   Import `createRunnerIO` from helpers.
+   Import `STUB_SNAPSHOT` from `stub-ctx.ts`.
+   Remove local `createRunnerIO()` and `snapshot`.
+   Keep local `agentConfigMock` and `mockAgentLookup` (mutable wrapper pattern).
+   Run: `pnpm vitest run test/lifecycle/agent-runner-extension-tools.test.ts`.
+   Commit: `test: use shared createRunnerIO in extension-tools tests`
+
+4. **Green: migrate `concrete-agent-runner.test.ts` to shared factories.**
+   Import `createRunnerIO`, `createAgentLookup` from helpers.
+   Import `STUB_SNAPSHOT` from `stub-ctx.ts`.
+   Remove local `makeIO()`, `registry`, `snapshot`.
+   Run: `pnpm vitest run test/lifecycle/concrete-agent-runner.test.ts`.
+   Commit: `test: use shared runner-io fixtures in concrete-agent-runner tests`
+
+5. **Red → Green: UI stub factories.**
+   Write `test/helpers/ui-stubs.test.ts` — verify `makeFileOps()` shape, `makeMenuUI()` sequential select behavior, `makeMenuManager()` shape, `createTestAgentConfig()` default and override merging.
+   Implement `test/helpers/ui-stubs.ts`.
+   Run: `pnpm vitest run test/helpers/ui-stubs.test.ts`.
+   Commit: `test: add shared UI stub factories`
+
+6. **Green: migrate `agent-config-editor.test.ts` to shared UI stubs.**
+   Import `makeFileOps`, `makeMenuUI`, `createTestAgentConfig` from helpers.
+   Remove local `makeFileOps()`, `makeUI()`, `testDefaultConfig`; derive `testCustomConfig` from `createTestAgentConfig`.
+   Run: `pnpm vitest run test/ui/agent-config-editor.test.ts`.
+   Commit: `test: use shared UI stubs in agent-config-editor tests`
+
+7. **Green: migrate `agent-creation-wizard.test.ts` to shared UI stubs.**
+   Import `makeFileOps`, `makeMenuUI`, `makeMenuManager` from helpers.
+   Import `STUB_SNAPSHOT` from `stub-ctx.ts`.
+   Remove local `makeFileOps()`, `makeUI()`, `makeManager()`, `stubParentSnapshot`.
+   Run: `pnpm vitest run test/ui/agent-creation-wizard.test.ts`.
+   Commit: `test: use shared UI stubs in agent-creation-wizard tests`
+
+8. **Green: migrate `agent-menu.test.ts` to shared UI stubs.**
+   Import `makeFileOps`, `makeMenuUI`, `makeMenuManager`, `createTestAgentConfig` from helpers.
+   Import `STUB_SNAPSHOT` from `stub-ctx.ts`.
+   Remove local `makeFileOps()`, `makeManager()`, `testDefaultAgentConfig`, `stubParentSnapshot`.
+   Adapt `makeHandler()` to wrap `makeMenuUI()` into its `{ ui, modelRegistry, parentSnapshot }` shape.
+   Keep local `makeSettings()`.
+   Run: `pnpm vitest run test/ui/agent-menu.test.ts`.
+   Commit: `test: use shared UI stubs in agent-menu tests`
+
+9. **Green: consolidate `agent-manager.test.ts` internal duplication.**
+   Import `STUB_SNAPSHOT` from `stub-ctx.ts`.
+   Remove local `mockSnapshot`.
+   Add local `spawnBg()` and `spawnFg()` helpers.
+   Update all ~42 `manager.spawn(mockSnapshot, ...)` calls to use `spawnBg()`.
+   Update `spawnAndWait` calls to use `spawnFg()`.
+   Run: `pnpm vitest run test/lifecycle/agent-manager.test.ts`.
+   Commit: `test: consolidate agent-manager spawn patterns with local helpers`
+
+10. **Docs: update architecture doc reference.**
+    Update `docs/architecture/architecture.md` Phase 12 Step 4 to reference `test/helpers/` instead of `test/fixtures/`.
+    Commit: `docs: update Phase 12 Step 4 to reference test/helpers/`
+
+## Risks and Mitigations
+
+| Risk                                                                                                          | Mitigation                                                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STUB_SNAPSHOT` shape differs from local snapshots (`cwd`, `model`, `systemPrompt` values)                    | Verified: no consumer tests assert on these field values. The snapshot is passed through to fully-mocked functions. Run full test suite after each migration step.                       |
+| Removing stale `buildMemoryBlock`/`buildReadOnlyMemoryBlock` stubs breaks a test that somehow depends on them | These methods don't exist on `AssemblerIO` — any code accessing them would be a TypeScript error in production. Vitest's esbuild won't catch this, so run `pnpm run check` after step 2. |
+| Wider mock shape in `createRunnerIO` causes false-positive tests (runner tests pass when they should fail)    | The production `RunnerIO` interface is already narrow; extra mock methods are harmless. Existing assertions on specific mock calls catch regressions.                                    |
+| `makeMenuUI` sequential-select pattern breaks when agent-menu wraps it differently                            | Agent-menu's `makeHandler()` composes the wrapping locally. The shared factory returns only the flat UI shape, avoiding coupling to any specific consumer's wrapping structure.          |
+| `agent-manager.test.ts` `spawnBg()` helper hides important spawn options from test readers                    | Helper uses default values matching the most common pattern. Tests that need non-default options (e.g., `description: "first"`) pass explicit arguments, preserving readability.         |
+
+## Open Questions
+
+- Should `STUB_SNAPSHOT` be updated to use `vi.fn()` for `modelRegistry.find` instead of `() => undefined`?
+  Currently it uses plain functions, but some runner tests use `vi.fn()`.
+  Decide during implementation — if no test asserts on `find` call counts, plain functions are fine.

package/docs/retro/0207-decompose-agent-widget-update.md

@@ -0,0 +1,92 @@
+---
+issue: 207
+issue_title: "Decompose update in agent-widget.ts (cognitive 31)"
+---
+
+# Retro: #207 — Decompose `update` in `agent-widget.ts`
+
+## Stage: Planning (2026-05-25T04:12:00Z)
+
+### Session summary
+
+Planned the decomposition of `update` (cognitive complexity 31) into an exported pure `assembleWidgetState` function, a `clearWidget` method, and an `updateStatusBar` method.
+The plan follows the Phase 12 pattern established by Steps 1 and 2 (#205, #206) — extract pure functions where possible, otherwise extract methods, and simplify the original function to a thin orchestrator.
+
+### Observations
+
+- The sibling plans (#205, #206) provided a clear template for this plan — structure, section ordering, and test impact analysis all followed the established pattern.
+- There are **no existing tests** for `AgentWidget` — the only testable concern is the newly extracted `assembleWidgetState` pure function.
+  The rest of the refactoring is a mechanical extraction verified by the type checker.
+- `categorizeAgents` in `widget-renderer.ts` does a similar filter but returns full arrays (for rendering), while `assembleWidgetState` returns lightweight counts (for lifecycle decisions).
+  Different outputs for different consumers — no duplication concern.
+- No `ask_user` was needed — the issue's "Proposed change" section was unambiguous and the design pattern was well-established by the two preceding Phase 12 steps.
+
+## Stage: Planning — revision (2026-05-25T16:00:00Z)
+
+### Session summary
+
+Reviewed and revised the prior plan after a thorough code audit of `agent-widget.ts`, `widget-renderer.ts`, `agent-record.ts`, and `runtime.ts`.
+Three design changes were made to the original plan.
+
+### Observations
+
+- **Narrowed the input type:** Changed `assembleWidgetState` from accepting `WidgetAgent[]` (10+ fields) to a local `AgentSummary` interface (3 fields: `id`, `status`, `completedAt?`).
+  The original plan violated ISP — the function only reads 3 fields, so requiring full `WidgetAgent` fixtures in tests would be needless friction.
+  `AgentRecord` satisfies `AgentSummary` structurally, so no adapter is needed at the call site.
+- **Kept `dispose` independent:** The original plan made `dispose` delegate to `clearWidget`, but `dispose` and `update`'s idle path have different lifecycle semantics — `dispose` uses unconditional teardown (correctness guarantee), while `update`'s idle path uses guarded calls (avoiding redundant SDK calls during repeated ticks).
+  `dispose` also skips stale-entry cleanup (the Map is about to be GC'd).
+  Per the code-design skill's Sandi Metz principle, this is structural duplication that should not be extracted.
+- **Added complexity budget table:** Explicitly estimated cognitive complexity for each extracted function to verify the < 10 target is achievable across the board.
+
+## Stage: Implementation — TDD (2026-05-25T13:10:00Z)
+
+### Session summary
+
+Completed all three TDD steps from the plan.
+`assembleWidgetState` was extracted and tested with 16 unit tests covering all status combinations; `clearWidget` and `updateStatusBar` were extracted as private methods simplifying `update` to a thin orchestrator.
+Test count went from 868 to 884 (+16 tests across 55 files, up from 54).
+
+### Observations
+
+- No deviations from the plan.
+  The non-null assertion (`this.uiCtx!`) in `clearWidget` and `updateStatusBar` is safe because both methods are only called from `update` after the `if (!this.uiCtx) return` guard.
+- The `AgentSummary` interface and narrow test fixtures worked exactly as planned — test objects are plain 3-field literals, no `createTestRecord` needed.
+- The complexity hotspots table in `architecture.md` now has no rows (both `renderWidgetLines` from #205 and `update` from this issue are resolved).
+  The section note was updated to reflect that Phase 12 cleared all critical hotspots.
+- `pnpm fallow dead-code` (from repo root) passed with no issues.
+
+## Stage: Final Retrospective (2026-05-25T13:15:00Z)
+
+### Session summary
+
+Issue #207 shipped as `pi-subagents-v7.3.0` with zero deviations from the revised plan.
+The session covered plan revision, TDD implementation (16 new tests, 868 → 884), shipping, and CI verification.
+
+### Observations
+
+#### What went well
+
+- The plan revision caught three real design issues before implementation started: ISP violation in the function parameter type, incorrect `dispose` → `clearWidget` delegation, and missing complexity budget.
+  Fixing these upfront meant the TDD execution had zero deviations and zero rework.
+- The narrow `AgentSummary` type (3 fields) made test fixtures trivial plain objects — no `createTestRecord` or factory infrastructure needed.
+  This validated the ISP improvement concretely.
+- The `dispose` independence decision (Sandi Metz principle applied to lifecycle semantics) kept `dispose` at its current 10-line simplicity while `clearWidget` got its own guarded teardown logic.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The original planning session (prior to this one) used `WidgetAgent[]` as the input type without checking which fields `assembleWidgetState` actually reads.
+  The `code-design` skill already says "do not pass a shared dependency bag to functions that only use a subset of it" but the principle wasn't applied to the proposed function signature.
+  Impact: required a full plan revision session; no rework in implementation because it was caught before TDD started.
+- `wrong-abstraction` — The original plan proposed `dispose` → `clearWidget` delegation as "eliminating duplication" without evaluating whether the two methods have the same lifecycle semantics.
+  `dispose` uses unconditional teardown (shutdown correctness); `clearWidget` uses guarded calls (avoiding redundant SDK calls during repeated timer ticks).
+  Impact: same as above — caught in revision, no implementation rework.
+
+#### What caused friction (user side)
+
+- The user's "I don't yet trust the plan" intervention was the key moment that improved the design.
+  Without it, the plan would have been implemented with the wider type and the `dispose` delegation.
+  This was effective judgment — the user identified that a mechanical plan for a mechanical refactoring still warranted critical design review.
+
+### Changes made
+
+1. Added two sentences to `.pi/prompts/plan-issue.md` Design Overview section: ISP check for new function parameter types, and structural-duplication check when consolidating methods into a shared helper.

package/docs/retro/0208-extract-shared-test-fixtures.md

@@ -0,0 +1,45 @@
+---
+issue: 208
+issue_title: "Extract shared test fixtures to reduce test duplication"
+---
+
+# Retro: #208 — Extract shared test fixtures to reduce test duplication
+
+## Stage: Implementation — TDD (2026-05-25T21:00:00Z)
+
+### Session summary
+
+Completed all 10 TDD steps plus a type-fix commit.
+Created 4 new files (`runner-io.ts`, `runner-io.test.ts`, `ui-stubs.ts`, `ui-stubs.test.ts`) and migrated 7 existing test files.
+Test count grew from 884 → 913 (+29 tests in new helper unit tests).
+
+### Observations
+
+- Vitest v4 changed `vi.fn()` without implementation annotation to type `Mock<Procedure | Constructable>`, which is NOT assignable to specific function signatures in production interfaces.
+  The fix was to add typed implementation annotations (`vi.fn((_path: string): boolean => false)`) to all vi.fn() stubs in the shared factories.
+  This was a new friction point not anticipated in the plan.
+- The plan's `assemblerOverrides` parameter in `createRunnerIO()` was removed because the `??` union typing caused `Mock<Procedure | Constructable> | Mock<specific-fn>` which TypeScript couldn't resolve as assignable to `RunnerIO`.
+  No consumer test actually used the override parameter, so removing it simplified both the implementation and the type story.
+- The `findAgentFile` signature in `AgentFileOps` is `(name: string, dirs: string[])` — the second parameter is `string[]`, not a second string as initially assumed from test patterns.
+  This was caught by `pnpm run check`.
+- The `agent-config-editor.test.ts` migration removed the `import type { AgentConfig }` import that was still needed by `buildEjectContent` tests further down the file.
+  Also caught by `pnpm run check`.
+- `STUB_SNAPSHOT` replacement was safe: no consumer test asserts on snapshot field values.
+  The `mockSnapshot` in `agent-manager.test.ts` had `systemPrompt: "parent prompt"` vs `STUB_SNAPSHOT`'s `"test prompt"` but this caused no test failures.
+- Architecture doc was updated to reference `test/helpers/` (correcting `test/fixtures/` from the original entry).
+
+## Stage: Planning (2026-05-25T20:00:00Z)
+
+### Session summary
+
+Analyzed the three heaviest test clone families identified by fallow and designed a 10-step TDD plan to extract shared factories into `test/helpers/`.
+Decided to follow the existing `test/helpers/` convention rather than the `test/fixtures/` directory mentioned in the issue and architecture doc.
+
+### Observations
+
+- Issue #131 (closed) already extracted `createMockSession`, `createToolDeps`, and `createTestRecord` — this issue targets the remaining duplication.
+- The `createRunnerIO` factory in `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` includes stale `buildMemoryBlock` and `buildReadOnlyMemoryBlock` stubs that no longer match the `AssemblerIO` interface — the shared factory will clean these up as a side benefit.
+- Session mock factories in the runner tests are structurally specialized (each serves a different test purpose) and were explicitly scoped as non-goals — extracting them would create a confusing multi-mode factory.
+- The `agent-runner-extension-tools.test.ts` uses a mutable `agentConfigMock.current` pattern that doesn't fit into a shared static factory — only `createRunnerIO` is shared from that file.
+- `STUB_SNAPSHOT` from `stub-ctx.ts` can replace all 5 local `ParentSnapshot` definitions — verified no test asserts on the specific field values.
+- The `agent-manager.test.ts` internal duplication (~42 repetitive spawn calls) is best handled with local `spawnBg()`/`spawnFg()` helpers rather than cross-file extraction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.2.8",
+  "version": "7.3.1",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/ui/agent-widget.ts

@@ -14,6 +14,42 @@ import { renderWidgetLines } from "#src/ui/widget-renderer";
 
 // ---- Types ----
 
+/** Minimal agent shape needed for widget lifecycle decisions. */
+interface AgentSummary {
+  readonly id: string;
+  readonly status: string;
+  readonly completedAt?: number;
+}
+
+/** Lightweight state snapshot used by AgentWidget.update() to decide what to show. */
+export interface WidgetState {
+  readonly runningCount: number;
+  readonly queuedCount: number;
+  readonly hasFinished: boolean;
+  /** True when runningCount > 0 || queuedCount > 0. Included for call-site readability. */
+  readonly hasActive: boolean;
+}
+
+/**
+ * Count agents by status and return a lightweight state snapshot.
+ * Pure function — no IO, no side effects. Exported for direct unit testing.
+ */
+export function assembleWidgetState(
+  agents: readonly AgentSummary[],
+  shouldShowFinished: (agentId: string, status: string) => boolean,
+): WidgetState {
+  let runningCount = 0;
+  let queuedCount = 0;
+  let hasFinished = false;
+  for (const a of agents) {
+    if (a.status === "running") { runningCount++; }
+    else if (a.status === "queued") { queuedCount++; }
+    else if (a.completedAt && shouldShowFinished(a.id, a.status)) { hasFinished = true; }
+  }
+  const hasActive = runningCount > 0 || queuedCount > 0;
+  return { runningCount, queuedCount, hasFinished, hasActive };
+}
+
 export type UICtx = {
   setStatus(key: string, text: string | undefined): void;
   setWidget(
@@ -108,55 +144,59 @@ export class AgentWidget {
     });
   }
 
-  /** Force an immediate widget update. */
-  update() {
-    if (!this.uiCtx) return;
-    const allAgents = this.manager.listAgents();
-
-    // Lightweight existence checks — full categorization happens in renderWidget()
-    let runningCount = 0;
-    let queuedCount = 0;
-    let hasFinished = false;
-    for (const a of allAgents) {
-      if (a.status === "running") { runningCount++; }
-      else if (a.status === "queued") { queuedCount++; }
-      else if (a.completedAt && this.shouldShowFinished(a.id, a.status)) { hasFinished = true; }
+  /**
+   * Unregister the widget, clear the status bar, stop the interval timer, and
+   * purge stale `finishedTurnAge` entries for agents no longer in `allAgents`.
+   * Called only from `update`'s idle path — not from `dispose`.
+   */
+  private clearWidget(allAgents: readonly AgentSummary[]): void {
+    if (this.widgetRegistered) {
+      this.uiCtx!.setWidget("agents", undefined);
+      this.widgetRegistered = false;
+      this.tui = undefined;
     }
-    const hasActive = runningCount > 0 || queuedCount > 0;
-
-    // Nothing to show — clear widget
-    if (!hasActive && !hasFinished) {
-      if (this.widgetRegistered) {
-        this.uiCtx.setWidget("agents", undefined);
-        this.widgetRegistered = false;
-        this.tui = undefined;
-      }
-      if (this.lastStatusText !== undefined) {
-        this.uiCtx.setStatus("subagents", undefined);
-        this.lastStatusText = undefined;
-      }
-      if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
-      // Clean up stale entries
-      for (const [id] of this.finishedTurnAge) {
-        if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
-      }
-      return;
+    if (this.lastStatusText !== undefined) {
+      this.uiCtx!.setStatus("subagents", undefined);
+      this.lastStatusText = undefined;
     }
+    if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
+    for (const [id] of this.finishedTurnAge) {
+      if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
+    }
+  }
 
-    // Status bar — only call setStatus when the text actually changes
+  /**
+   * Compute the status bar text from the current widget state and call
+   * `setStatus` only when it differs from the last cached value.
+   */
+  private updateStatusBar(state: WidgetState): void {
     let newStatusText: string | undefined;
-    if (hasActive) {
+    if (state.hasActive) {
       const statusParts: string[] = [];
-      if (runningCount > 0) statusParts.push(`${runningCount} running`);
-      if (queuedCount > 0) statusParts.push(`${queuedCount} queued`);
-      const total = runningCount + queuedCount;
+      if (state.runningCount > 0) statusParts.push(`${state.runningCount} running`);
+      if (state.queuedCount > 0) statusParts.push(`${state.queuedCount} queued`);
+      const total = state.runningCount + state.queuedCount;
       newStatusText = `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`;
     }
     if (newStatusText !== this.lastStatusText) {
-      this.uiCtx.setStatus("subagents", newStatusText);
+      this.uiCtx!.setStatus("subagents", newStatusText);
       this.lastStatusText = newStatusText;
     }
+  }
+
+  /** Force an immediate widget update. */
+  update() {
+    if (!this.uiCtx) return;
+
+    const allAgents = this.manager.listAgents();
+    const state = assembleWidgetState(allAgents, (id, status) => this.shouldShowFinished(id, status));
+
+    if (!state.hasActive && !state.hasFinished) {
+      this.clearWidget(allAgents);
+      return;
+    }
 
+    this.updateStatusBar(state);
     this.widgetFrame++;
 
     // Register widget callback once; subsequent updates use requestRender()