@gotgenes/pi-subagents 7.2.5 → 7.2.6

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.2.6](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.5...pi-subagents-v7.2.6) (2026-05-25)
+
+
+### Documentation
+
+* archive Phase 11 to history, add Phase 11 to refactoring table ([2c617f2](https://github.com/gotgenes/pi-packages/commit/2c617f2c752ea935d55878ba58fce997985086b5))
+* plan decompose renderWidgetLines ([#205](https://github.com/gotgenes/pi-packages/issues/205)) ([88d09cd](https://github.com/gotgenes/pi-packages/commit/88d09cdad53bc3f215c069b8d6da6a44e10b5af7))
+* **retro:** add planning stage notes for issue [#205](https://github.com/gotgenes/pi-packages/issues/205) ([14afc1f](https://github.com/gotgenes/pi-packages/commit/14afc1ff82d61828fdac9373f31cb68ebfc1a2e7))
+* **retro:** add retro notes for issue [#196](https://github.com/gotgenes/pi-packages/issues/196) ([cfc7d94](https://github.com/gotgenes/pi-packages/commit/cfc7d94f72b120a4550f73e2d1cf00822db759c2))
+* **retro:** add TDD stage notes for issue [#205](https://github.com/gotgenes/pi-packages/issues/205) ([a676078](https://github.com/gotgenes/pi-packages/commit/a6760789898435e5b552941124de6f32be21407e))
+
 ## [7.2.5](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.4...pi-subagents-v7.2.5) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -599,155 +599,18 @@ export type RunnerIO = EnvironmentIO & SessionFactoryIO;
 `RunnerIO` is kept as a type alias for the intersection.
 All existing consumers satisfy both sub-interfaces via structural typing with no call-site changes.
 
-## Improvement roadmap (Phase 11)
+## Phase 11 (complete)
 
-Phase 11 converts closure factories to classes, eliminating the adapter closure density in `index.ts` (the package's #1 churn hotspot: 128 commits, accelerating, fan-out 25).
-The approach is layered: each step makes the next step trivial.
-
-> "Make the change that makes the change easy." —Kent Beck
-
-### Findings
-
-| Metric                    | Value                                      |
-| ------------------------- | ------------------------------------------ |
-| Health score              | 75/100 (B)                                 |
-| #1 hotspot                | `index.ts` (128 commits, accelerating)     |
-| Dead exports              | 0 (down from 1; Layer 2 removed re-export) |
-| Production duplication    | 0                                          |
-| Test duplication          | 1,396 lines (69 clone groups, 22 files)    |
-| `as any` casts in index   | 1 (down from 5; Layer 1 resolved 4)        |
-| Adapter closures in index | 40 (down from 44; Layers 1–2 resolved 4)   |
-| Index fan-out             | 25 imports                                 |
-
-### Root cause
-
-The 44 adapter closures in `index.ts` exist because the tool factories accept narrow interfaces that don't structurally match the real objects.
-The real objects can't satisfy the interfaces because:
-
-1. ~~`SubagentRuntime.currentCtx` is typed `{ pi: unknown; ctx: unknown }` — so every consumer must `as any` cast to read fields.~~
-   Resolved by Layer 0 (#192) + Layer 1 (#193).
-2. ~~Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) live as closures in index.ts instead of methods on the state holder.~~
-   Resolved by Layer 1 (#193).
-3. ~~`AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).~~
-   Resolved by Layer 2 (#194).
-4. ~~`AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).~~
-   Resolved by Layer 2 (#194).
-
-Fix these structural misalignments and the class conversions become mechanical.
-
-### Layer 0: Define `SessionContext` narrow interface ([#192][192])
-
-`SubagentRuntime` currently types its context as `unknown` to avoid SDK coupling.
-But `ExtensionContext` is exported by the SDK — the `unknown` is a historical choice, not a constraint.
-Define a narrow `SessionContext` interface capturing the 5 fields runtime actually needs:
-
-```typescript
-export interface SessionContext {
-  readonly cwd: string;
-  readonly model: unknown;
-  readonly modelRegistry: ModelRegistry | undefined;
-  getSystemPrompt(): string;
-  readonly sessionManager: {
-    getSessionFile(): string | undefined;
-    getSessionId(): string;
-    getBranch(): unknown[];
-  };
-}
-```
-
-- Target: `src/types.ts`
-- Smell: Category C (platform type threading)
-- Outcome: typed foundation for Layers 1–4; no `as any` needed by consumers of `SubagentRuntime`
-
-### Layer 1: `SubagentRuntime` stores typed context, owns its queries ([#193][193]) ✓ done
-
-Change `currentCtx` from `{ pi: unknown; ctx: unknown }` to `SessionContext | undefined`.
-The single `as SessionContext` cast moves into `handleSessionStart` — the boundary where the SDK hands us the value.
-Add typed methods: `buildSnapshot(inheritContext)`, `getModelInfo()`, `getSessionInfo()`.
-
-- Target: `src/runtime.ts`, `src/handlers/lifecycle.ts`, `src/service/service-adapter.ts`, `src/index.ts`
-- Smell: Category C (closure queries on mutable field → methods on state owner)
-- Outcome: 3 closure queries in index.ts → 0; `SubagentRuntime` is self-sufficient for tool deps
-- Enables: Layer 3 (tools accept `SubagentRuntime` directly)
-
-### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194]) ✓ done
-
-Three alignment changes:
-
-1. **Move `getMaxConcurrent` off `AgentToolManager`** — it reads from `SettingsManager`, not `AgentManager`.
-   The tool already receives `settings`; read it from there.
-2. **Rename widget methods** — align `SubagentRuntime` method names with `AgentToolWidget` (either rename `updateWidget()` → `update()` on runtime, or rename the interface to match).
-3. **Remove dead re-export** — `getToolCallName` in `ui/message-formatters.ts` (fallow finding).
-
-After this step, `AgentManager` structurally satisfies `AgentToolManager` and `SubagentRuntime` structurally satisfies `AgentToolWidget`.
-
-- Target: `src/tools/agent-tool.ts` (interface), `src/runtime.ts` (method names), `src/ui/message-formatters.ts`
-- Smell: Category C (source mismatch, name mismatch) + Category A (dead export)
-- Outcome: structural typing connects real objects to tool interfaces without adapters; 0 dead exports (fallow clean)
-- Enables: Layer 3 (class constructors accept real objects directly)
-
-### Layer 3: Convert closure factories to classes ([#195][195], [#196][196]) ✓ done
-
-All closure factories converted to classes. ✓ Tool factories in [#195][195]; runner and menu in [#196][196]:
-
-| Factory                          | Class                   | Constructor params                                                   |
-| -------------------------------- | ----------------------- | -------------------------------------------------------------------- |
-| `createAgentTool({...})`         | `AgentTool` ✓           | `manager`, `runtime`, `settings`, `registry`                         |
-| `createGetResultTool(...)`       | `GetResultTool` ✓       | `manager`, `notifications`, `registry`                               |
-| `createSteerTool(...)`           | `SteerTool` ✓           | `manager`, `events`                                                  |
-| `createAgentRunner(runnerIO)`    | `ConcreteAgentRunner` ✓ | `io: RunnerIO`                                                       |
-| `createAgentsMenuHandler({...})` | `AgentsMenuHandler` ✓   | `manager`, `registry`, `agentActivity`, `settings`, `fileOps`, paths |
-
-Each class satisfies the existing interface via structural typing.
-The `defineTool()` wrapper moves into a `toToolDefinition()` method on each tool class.
-`getModelLabel` internalized into `AgentsMenuHandler` (was a 7-line closure in `index.ts`).
-
-- Target: `src/tools/*.ts`, `src/lifecycle/agent-runner.ts`, `src/ui/agent-menu.ts`
-- Smell: Category C (closure factories masquerading as classes)
-- Outcome: deps are constructor params (inspectable, testable); no captured closures
-- Enables: Layer 4 (index.ts simplification)
-
-### Layer 4: Simplify index.ts (included in [#196][196]) ✓ done
-
-With all factories converted to classes and `AgentManager` satisfying `AgentMenuManager` structurally:
-
-```typescript
-const agentsMenu = new AgentsMenuHandler(
-  manager, registry, runtime.agentActivity,
-  settings, new FsAgentFileOps(),
-  join(getAgentDir(), "agents"),
-  join(process.cwd(), ".pi", "agents"),
-);
-```
-
-Eliminated: 4 adapter closures (3 manager method adapters + `getModelLabel`), 4 unused imports.
-Remaining ~15 closures are structural (event registrations, SDK factory callbacks).
-
-- Target: `src/index.ts`
-- Smell: Category B (god file) + Category C (adapter closure density)
-- Outcome: adapter closure count reduced; `AgentManager` passed directly without wrappers; churn hotspot stabilized
-
-### Step dependencies
-
-```mermaid
-flowchart LR
-    L0["Layer 0: SessionContext interface"] --> L1["Layer 1: Runtime owns queries"]
-    L1 --> L3["Layer 3: Classes replace factories"]
-    L2["Layer 2: Align interfaces"] --> L3
-    L3 --> L4["Layer 4: Simplify index.ts"]
-```
-
-Layers 0 and 2 are independent of each other.
-Layer 1 depends on Layer 0.
-Layer 3 depends on both Layer 1 and Layer 2.
-Layer 4 depends on Layer 3.
+Phase 11 converted all closure factories to classes, eliminating adapter closure density in `index.ts`.
+Four layers: SessionContext typing → runtime query methods → interface alignment → class conversions → index.ts simplification.
+See [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md) for details.
 
 ## Improvement roadmap (Phase 12)
 
 Phase 12 addresses the remaining fallow refactoring targets and test duplication.
 These are independent of Phase 11 and can proceed in parallel if desired.
 
-### Step 1: Decompose `renderWidgetLines` (cognitive 44)
+### Step 1: Decompose `renderWidgetLines` (cognitive 44) — [#205]
 
 `renderWidgetLines` in `ui/widget-renderer.ts` handles agent-status formatting, tree connectors, overflow, and empty states.
 Extract per-status renderers and a tree-connector utility.
@@ -755,7 +618,7 @@ Extract per-status renderers and a tree-connector utility.
 - Target: `src/ui/widget-renderer.ts`
 - Outcome: cognitive complexity < 10
 
-### Step 2: Decompose `showAgentDetail` (cognitive 33)
+### Step 2: Decompose `showAgentDetail` (cognitive 33) — [#206]
 
 `showAgentDetail` in `ui/agent-config-editor.ts` handles display, edit, eject, and delete flows.
 Extract sub-functions per menu action.
@@ -763,7 +626,7 @@ Extract sub-functions per menu action.
 - Target: `src/ui/agent-config-editor.ts`
 - Outcome: cognitive complexity < 10
 
-### Step 3: Decompose `update` in `agent-widget.ts` (cognitive 31)
+### Step 3: Decompose `update` in `agent-widget.ts` (cognitive 31) — [#207]
 
 `update` mixes timer lifecycle, agent list assembly, render delegation, and visibility state.
 Extract `assembleWidgetState` (pure) and timer management.
@@ -771,7 +634,7 @@ Extract `assembleWidgetState` (pure) and timer management.
 - Target: `src/ui/agent-widget.ts`
 - Outcome: cognitive complexity < 10
 
-### Step 4: Extract shared test fixtures
+### Step 4: Extract shared test fixtures — [#208]
 
 The 3 heaviest clone families:
 
@@ -786,7 +649,7 @@ Extract shared factories into `test/fixtures/` modules.
 
 ## Refactoring history
 
-Phases 1–5 and 7–10 are complete.
+Phases 1–5 and 7–11 are complete.
 Phase 6 (UI extraction to a separate package) is deferred.
 Detailed records are preserved in per-phase history files:
 
@@ -802,6 +665,7 @@ Detailed records are preserved in per-phase history files:
 | 8     | Testability, display extraction, menu decomposition | Complete | [phase-8-testability.md](history/phase-8-testability.md)                             |
 | 9     | Observation consolidation, ctx elimination          | Complete | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
 | 10    | Domain organization, bag decomposition, complexity  | Complete | [phase-10-structural-decomposition.md](history/phase-10-structural-decomposition.md) |
+| 11    | Closure factories to classes                        | Complete | [phase-11-closure-to-class.md](history/phase-11-closure-to-class.md)                 |
 
 ### Structural refactoring issues
 
@@ -816,6 +680,8 @@ Detailed records are preserved in per-phase history files:
 | Testability        | #131, #132, #133, #134, #135, #136                         | Shared fixtures, session-config IO, runner SDK boundary, as-any reduction, display extraction, menu decomposition                                        |
 | Observation/ctx    | #144, #145, #146, #147, #148                               | Observation consolidation, execute decomposition, UI context, text wrapping injection, widget rendering split                                            |
 | Phase 10           | #164, #165, #166, #167, #168, #169, #170, #171, #172       | Domain directories, ResolvedSpawnConfig, ParentSessionInfo, RunnerIO split, ToolFilterConfig, RunContext, buildContentLines, renderResult, content-items |
+| Phase 11           | #192, #193, #194, #195, #196                               | SessionContext, runtime queries, interface alignment, tool classes, runner/menu classes, index.ts simplification                                         |
+| Phase 12           | #205, #206, #207, #208                                     | renderWidgetLines, showAgentDetail, widget update, shared test fixtures                                                                                  |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -839,8 +705,7 @@ The upstream test suite is run periodically as a regression canary for the agent
 [167]: https://github.com/gotgenes/pi-packages/issues/167
 [168]: https://github.com/gotgenes/pi-packages/issues/168
 [169]: https://github.com/gotgenes/pi-packages/issues/169
-[192]: https://github.com/gotgenes/pi-packages/issues/192
-[193]: https://github.com/gotgenes/pi-packages/issues/193
-[194]: https://github.com/gotgenes/pi-packages/issues/194
-[195]: https://github.com/gotgenes/pi-packages/issues/195
-[196]: https://github.com/gotgenes/pi-packages/issues/196
+[#205]: https://github.com/gotgenes/pi-packages/issues/205
+[#206]: https://github.com/gotgenes/pi-packages/issues/206
+[#207]: https://github.com/gotgenes/pi-packages/issues/207
+[#208]: https://github.com/gotgenes/pi-packages/issues/208

package/docs/architecture/history/phase-11-closure-to-class.md

@@ -0,0 +1,100 @@
+# Phase 11: Closure factories to classes
+
+Target: convert all closure factories to classes, eliminating adapter closure density in `index.ts` (the package's #1 churn hotspot) and making the composition root a pure construction site.
+
+## Root cause
+
+The 44 adapter closures in `index.ts` existed because tool factories accepted narrow interfaces that didn't structurally match the real objects.
+Four structural misalignments prevented direct wiring:
+
+1. `SubagentRuntime.currentCtx` was typed `{ pi: unknown; ctx: unknown }` — every consumer had to `as any` cast.
+2. Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) lived as closures in `index.ts` instead of methods on the state holder.
+3. `AgentToolManager` mixed fields from `AgentManager` and `SettingsManager` (source mismatch).
+4. `AgentToolWidget` used different method names than `SubagentRuntime` (name mismatch).
+
+## Layer 0: Define SessionContext narrow interface (#192)
+
+Defined a `SessionContext` interface capturing the 5 fields `SubagentRuntime` actually needs.
+Replaced the `{ pi: unknown; ctx: unknown }` typing with `SessionContext | undefined`.
+
+Impact: typed foundation for all subsequent layers; no `as any` needed by consumers.
+
+## Layer 1: SubagentRuntime stores typed context, owns its queries (#193)
+
+Changed `currentCtx` to `SessionContext | undefined`.
+The single `as SessionContext` cast moved into `handleSessionStart` — the SDK boundary.
+Added typed methods: `buildSnapshot(inheritContext)`, `getModelInfo()`, `getSessionInfo()`.
+
+Impact: 3 closure queries in `index.ts` → 0; 4 `as any` casts eliminated; `SubagentRuntime` is self-sufficient for tool deps.
+
+## Layer 2: Align interfaces for structural typing (#194)
+
+Three alignment changes:
+
+1. Moved `getMaxConcurrent` off `AgentToolManager` — it reads from `SettingsManager`, not `AgentManager`.
+2. Renamed widget methods — aligned `SubagentRuntime` method names with `AgentToolWidget`.
+3. Removed dead re-export `getToolCallName` in `ui/message-formatters.ts`.
+
+Impact: `AgentManager` structurally satisfies `AgentToolManager`; `SubagentRuntime` structurally satisfies `AgentToolWidget`; 0 dead exports.
+
+## Layer 3: Convert closure factories to classes (#195, #196)
+
+All five closure factories converted to classes:
+
+| Factory                          | Class                 | Issue |
+| -------------------------------- | --------------------- | ----- |
+| `createAgentTool({...})`         | `AgentTool`           | #195  |
+| `createGetResultTool(...)`       | `GetResultTool`       | #195  |
+| `createSteerTool(...)`           | `SteerTool`           | #195  |
+| `createAgentRunner(runnerIO)`    | `ConcreteAgentRunner` | #196  |
+| `createAgentsMenuHandler({...})` | `AgentsMenuHandler`   | #196  |
+
+Each class satisfies the existing interface via structural typing.
+Tool classes expose `toToolDefinition()` for Pi tool registration.
+`getModelLabel` internalized into `AgentsMenuHandler` (was a 7-line closure in `index.ts`).
+
+Impact: deps are constructor params (inspectable, testable); no captured closures.
+
+## Layer 4: Simplify index.ts (#196)
+
+With all factories converted and `AgentManager` satisfying `AgentMenuManager` structurally:
+
+- 4 adapter closures eliminated (3 manager method adapters + `getModelLabel`).
+- 4 unused imports removed.
+- Remaining ~15 closures are structural (event registrations, SDK factory callbacks).
+
+Impact: adapter closure count halved; `AgentManager` passed directly without wrappers; churn hotspot stabilized.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    L0["Layer 0: SessionContext #192"] --> L1["Layer 1: Runtime queries #193"]
+    L1 --> L3["Layer 3: Classes #195 #196"]
+    L2["Layer 2: Align interfaces #194"] --> L3
+    L3 --> L4["Layer 4: Simplify index.ts #196"]
+```
+
+Layers 0 and 2 were independent.
+Layer 1 depended on Layer 0.
+Layer 3 depended on both Layer 1 and Layer 2.
+Layer 4 depended on Layer 3.
+
+## Impact
+
+| Metric                         | Before     | After                 |
+| ------------------------------ | ---------- | --------------------- |
+| Health score                   | 75/100 (B) | 76/100 (B)            |
+| Adapter closures in `index.ts` | 44         | ~15 (structural only) |
+| `as any` casts in `index.ts`   | 5          | 1 (SDK boundary)      |
+| Dead exports                   | 1          | 0                     |
+| Closure factories              | 5          | 0                     |
+| `index.ts` fan-out             | 25 imports | 21 imports            |
+
+## Related issues
+
+- #192 — Define SessionContext narrow interface
+- #193 — Runtime owns context queries
+- #194 — Align tool interfaces for structural typing
+- #195 — Convert tool factories to classes
+- #196 — Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts

package/docs/plans/0205-decompose-render-widget-lines.md

@@ -0,0 +1,140 @@
+---
+issue: 205
+issue_title: "Decompose renderWidgetLines (cognitive 44)"
+---
+
+# Decompose `renderWidgetLines`
+
+## Problem Statement
+
+`renderWidgetLines` in `ui/widget-renderer.ts` has cognitive complexity 44 (CRITICAL per fallow health).
+It handles agent categorization, per-status line building with tree connectors, non-overflow assembly with last-connector fixup, and overflow-budget assembly — all in a single 106-line function.
+This is the highest-complexity function remaining in the codebase (Phase 12, Step 1).
+
+## Goals
+
+- Extract distinct concerns into separate pure functions, each with cognitive complexity < 10.
+- Preserve all existing behavior — no visual or behavioral changes.
+- Keep all extracted functions in `widget-renderer.ts` (they are private helpers, not a separate module).
+
+## Non-Goals
+
+- Decomposing `showAgentDetail` (#206), `update` (#207), or shared test fixtures (#208) — those are sibling Phase 12 steps.
+- Changing the widget's visual output or tree-connector style.
+- Modifying `renderFinishedLine` or `renderRunningLines` — those are already single-concern functions.
+
+## Background
+
+`widget-renderer.ts` was extracted from `AgentWidget` in #148.
+The per-agent renderers (`renderFinishedLine`, `renderRunningLines`) are already clean single-concern functions.
+The remaining complexity lives entirely in `renderWidgetLines`, which orchestrates categorization, section building, and assembly.
+
+The function has five interwoven concerns:
+
+1. **Agent categorization** — filtering into running/queued/finished buckets.
+2. **Section building** — rendering each bucket into pre-formatted line arrays with `├─` tree connectors.
+3. **Heading construction** — choosing icon/color based on active vs. finished-only.
+4. **Non-overflow assembly** — concatenating sections when under `MAX_WIDGET_LINES`, then fixing the last connector (`├─` → `└─`).
+5. **Overflow assembly** — budget-based prioritized assembly (running > queued > finished) with an overflow indicator line.
+
+## Design Overview
+
+Extract four helper functions from the body of `renderWidgetLines`:
+
+### `categorizeAgents`
+
+Accepts the agents array and `shouldShowFinished` callback.
+Returns `{ running, queued, finished }` arrays.
+Pure filter — no rendering.
+
+### `buildSections`
+
+Accepts categorized agents, `activityMap`, `registry`, `spinnerFrame`, `theme`, and a `truncate` function.
+Returns `{ finishedLines, runningLines, queuedLine }` — the pre-formatted line arrays with `├─` connectors.
+Calls `renderFinishedLine` and `renderRunningLines` internally.
+
+### `assembleWithinBudget`
+
+Accepts `finishedLines`, `runningLines`, `queuedLine`, and the heading line.
+Handles the non-overflow path: concatenates sections and fixes the last tree connector (`├─` → `└─`, `│` → space).
+Returns the assembled `string[]`.
+
+### `assembleOverflow`
+
+Accepts `finishedLines`, `runningLines`, `queuedLine`, heading line, `maxBody` budget, `truncate`, and `theme`.
+Handles the overflow path: budget-based prioritized assembly with an overflow indicator.
+Returns the assembled `string[]`.
+
+After extraction, `renderWidgetLines` becomes a thin orchestrator:
+
+```typescript
+export function renderWidgetLines(params: { ... }): string[] {
+  const { running, queued, finished } = categorizeAgents(agents, shouldShowFinished);
+  if (running.length === 0 && queued.length === 0 && finished.length === 0) return [];
+
+  const truncate = (line: string) => truncateToWidth(line, terminalWidth);
+  const heading = buildHeadingLine(running, queued, truncate, theme);
+  const sections = buildSections(running, queued, finished, activityMap, registry, spinnerFrame, theme, truncate);
+  const totalBody = sections.finishedLines.length + sections.runningLines.length * 2 + (sections.queuedLine ? 1 : 0);
+
+  if (totalBody <= MAX_WIDGET_LINES - 1) {
+    return assembleWithinBudget(heading, sections);
+  }
+  return assembleOverflow(heading, sections, MAX_WIDGET_LINES - 1, truncate, theme);
+}
+```
+
+Each helper is a pure function with a single concern and low branching.
+
+## Module-Level Changes
+
+### Changed: `src/ui/widget-renderer.ts`
+
+- Add `categorizeAgents` (private) — extracts the three `agents.filter(...)` calls.
+- Add `buildSections` (private) — extracts the three section-building loops.
+- Add `assembleWithinBudget` (private) — extracts the non-overflow assembly + connector fixup.
+- Add `assembleOverflow` (private) — extracts the overflow-budget assembly + indicator line.
+- Simplify `renderWidgetLines` to a thin orchestrator calling the four helpers.
+
+No exports are added, removed, or renamed.
+No other files change.
+
+## Test Impact Analysis
+
+1. No new unit tests for the extracted helpers are needed — they are private functions tested through `renderWidgetLines`.
+   The existing `renderWidgetLines` tests in `test/widget-renderer.test.ts` (8 tests) cover all branches: single running, mixed agents, filtered finished, overflow priority, empty arrays, dim heading.
+2. No existing tests become redundant — they all exercise `renderWidgetLines` end-to-end, which is the correct level for assembly logic.
+3. All existing tests must stay as-is — the extraction is purely internal.
+
+## TDD Order
+
+1. **Red → Green:** Extract `categorizeAgents` and call it from `renderWidgetLines`.
+   All existing tests pass (no behavior change).
+   Commit: `refactor: extract categorizeAgents from renderWidgetLines`
+
+2. **Red → Green:** Extract `buildSections` and call it from `renderWidgetLines`.
+   All existing tests pass.
+   Commit: `refactor: extract buildSections from renderWidgetLines`
+
+3. **Red → Green:** Extract `assembleWithinBudget` and call it from `renderWidgetLines`.
+   All existing tests pass.
+   Commit: `refactor: extract assembleWithinBudget from renderWidgetLines`
+
+4. **Red → Green:** Extract `assembleOverflow` and call it from `renderWidgetLines`.
+   All existing tests pass.
+   Commit: `refactor: extract assembleOverflow from renderWidgetLines`
+
+5. **Verify:** Run `pnpm run check` and `pnpm vitest run test/widget-renderer.test.ts` to confirm no regressions.
+   Commit: n/a (verification only).
+
+## Risks and Mitigations
+
+| Risk                                                                        | Mitigation                                                                                                                             |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Tree-connector fixup logic is fragile (string replacement on Unicode chars) | Keep the fixup in `assembleWithinBudget` as-is — same logic, just relocated. Existing tests verify exact connector output.             |
+| Extracted helpers have many parameters                                      | Accept a `sections` object from `buildSections` to bundle `finishedLines`, `runningLines`, `queuedLine` — avoids long parameter lists. |
+| Intermediate commits break tests                                            | Each extraction step is self-contained — the function body moves into a helper and the call site replaces it in the same commit.       |
+
+## Open Questions
+
+None — the decomposition is purely mechanical extraction of existing code into named helpers.

package/docs/retro/0196-convert-runner-menu-to-classes.md

@@ -40,3 +40,34 @@ All type-check, lint, and dead-code gates pass clean.
 - `AgentManager` structurally satisfies `AgentMenuManager` with no adapter closures — confirmed by `pnpm run check` passing immediately.
 - The `agent-menu.test.ts` refactor replaced `Partial<AgentMenuDeps>` overrides with a `makeHandler(opts)` helper that returns both the handler and collaborator stubs, which is cleaner for assertion.
 - `rumdl` emitted 3 warnings in `pnpm run lint` — these are pre-existing and unrelated to this change (lint passes for markdown linting, the warnings are from biome/eslint steps that auto-fixed nothing).
+
+## Stage: Final Retrospective (2026-05-25T15:04:47Z)
+
+### Session summary
+
+Completed all three stages (planning, TDD, shipping) in one sitting.
+Issue #196 shipped as `pi-subagents-v7.2.5`.
+All closure factories in pi-subagents are now classes; Phase 11 (Layers 3 + 4) is complete.
+
+### Observations
+
+#### What went well
+
+- The three-session lifecycle (plan → TDD → ship) completed cleanly in a single sitting with no user corrections.
+- Structural typing confirmation during planning paid off — `AgentManager` satisfied `AgentMenuManager` without adapter closures, and `pnpm run check` passed immediately after the wiring change.
+- The `makeHandler(opts)` test helper pattern (returning handler + collaborator stubs) was cleaner than the `Partial<AgentMenuDeps>` spread approach it replaced.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan separated factory removal (step 3) from call-site update (step 5), even though the testing skill already has a rule: "When a TDD step changes an interface that has a single call site, the step must include updating that call site."
+  The planner treated this as a testing concern and didn't apply it during plan authoring.
+  Impact: steps 3 and 5 had to be merged at implementation time, producing a commit message explaining the deviation.
+  Added a cross-reference to `plan-issue.md`.
+
+#### What caused friction (user side)
+
+Nothing notable — the user's issue was well-specified and the three `/` commands ran without intervention.
+
+### Changes made
+
+1. Added single-call-site rule to `.pi/prompts/plan-issue.md` TDD Order section: when a step removes a factory/export with one call site, include the call-site update in the same step.

package/docs/retro/0205-decompose-render-widget-lines.md

@@ -0,0 +1,36 @@
+---
+issue: 205
+issue_title: "Decompose renderWidgetLines (cognitive 44)"
+---
+
+# Retro: #205 — Decompose renderWidgetLines
+
+## Stage: Planning (2026-05-25T15:27:45Z)
+
+### Session summary
+
+Planned the decomposition of `renderWidgetLines` (cognitive complexity 44) into four private helper functions: `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow`.
+Also updated `architecture.md` Phase 12 steps with issue links (#205–#208) and added a Phase 12 row to the structural refactoring issues table.
+
+### Observations
+
+- The function's complexity comes from five interwoven concerns (categorization, section building, heading, non-overflow assembly with connector fixup, overflow-budget assembly) — but the extraction is mechanical since all logic is already pure and stateless.
+- No new tests are needed — the existing 8 tests in `widget-renderer.test.ts` cover all branches end-to-end and remain the correct test level for assembly logic.
+- The tree-connector fixup (swapping `├─` → `└─` via string replacement on Unicode chars) is the most fragile part; it stays as-is inside `assembleWithinBudget` rather than being further decomposed.
+- A `sections` return object from `buildSections` bundles `finishedLines`, `runningLines`, and `queuedLine` to avoid long parameter lists on the assembly helpers.
+
+## Stage: Implementation — TDD (2026-05-25T15:35:10Z)
+
+### Session summary
+
+Completed all four TDD steps: extracted `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow` from `renderWidgetLines`.
+All 23 `widget-renderer.test.ts` tests pass throughout; no new tests were added.
+Full suite (856 tests, 54 files) is green; type check and lint are clean.
+
+### Observations
+
+- **Stray backtick during `assembleOverflow` extraction:** The Edit tool introduced a double-backtick (`\`\``) at the end of the nested template literal on the overflow indicator line — the inner template literal's closing backtick concatenated with the outer template's closing backtick, creating a parse error.
+  Required Python-based line-level surgery to fix since the Edit tool cannot reliably match nested template literals through JSON escaping.
+- The `renderWidgetLines` `else` block removal also required Python because the Edit tool's `oldText` matching is unreliable when the target contains nested template literals with backticks.
+- Aside from the template-literal matching friction, all extractions were purely mechanical; no logic changes were needed.
+- The final `renderWidgetLines` is a clean 12-line orchestrator; each helper is well under complexity 10.

package/package.json

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

package/src/ui/widget-renderer.ts

@@ -127,6 +127,135 @@ export function renderRunningLines(
 /** Maximum number of rendered lines before overflow collapse kicks in. */
 const MAX_WIDGET_LINES = 12;
 
+interface AgentCategories {
+	running: WidgetAgent[];
+	queued: WidgetAgent[];
+	finished: WidgetAgent[];
+}
+
+/** Partition agents into rendering buckets. */
+function categorizeAgents(
+	agents: readonly WidgetAgent[],
+	shouldShowFinished: (agentId: string, status: string) => boolean,
+): AgentCategories {
+	return {
+		running: agents.filter(a => a.status === "running"),
+		queued: agents.filter(a => a.status === "queued"),
+		finished: agents.filter(
+			a => a.status !== "running" && a.status !== "queued" && a.completedAt != null
+				&& shouldShowFinished(a.id, a.status),
+		),
+	};
+}
+
+interface WidgetSections {
+	finishedLines: string[];
+	runningLines: [string, string][];
+	queuedLine: string | undefined;
+}
+
+/** Render each agent bucket into pre-formatted lines with ├─ tree connectors. */
+function buildSections(
+	categories: AgentCategories,
+	activityMap: ReadonlyMap<string, WidgetActivity>,
+	registry: AgentConfigLookup,
+	spinnerFrame: number,
+	theme: Theme,
+	truncate: (line: string) => string,
+): WidgetSections {
+	const finishedLines: string[] = [];
+	for (const a of categories.finished) {
+		finishedLines.push(truncate(theme.fg("dim", "\u251C\u2500") + " " + renderFinishedLine(a, activityMap.get(a.id), registry, theme)));
+	}
+
+	const runningLines: [string, string][] = [];
+	for (const a of categories.running) {
+		const [header, act] = renderRunningLines(a, activityMap.get(a.id), registry, spinnerFrame, theme);
+		runningLines.push([
+			truncate(theme.fg("dim", "\u251C\u2500") + ` ${header}`),
+			truncate(theme.fg("dim", "\u2502  ") + act),
+		]);
+	}
+
+	const queuedLine = categories.queued.length > 0
+		? truncate(theme.fg("dim", "\u251C\u2500") + ` ${theme.fg("muted", "\u25E6")} ${theme.fg("dim", `${categories.queued.length} queued`)}`)
+		: undefined;
+
+	return { finishedLines, runningLines, queuedLine };
+}
+
+/**
+ * Assemble widget lines when total body fits within MAX_WIDGET_LINES.
+ * Fixes the last tree connector: ├─ → └─, and │ → space for the running-agent activity line.
+ */
+function assembleWithinBudget(heading: string, sections: WidgetSections): string[] {
+	const { finishedLines, runningLines, queuedLine } = sections;
+	const lines: string[] = [heading, ...finishedLines];
+	for (const pair of runningLines) lines.push(...pair);
+	if (queuedLine) lines.push(queuedLine);
+
+	// Fix last connector: swap \u251C\u2500 \u2192 \u2514\u2500.
+	if (lines.length > 1) {
+		const last = lines.length - 1;
+		lines[last] = lines[last].replace("\u251C\u2500", "\u2514\u2500");
+		if (runningLines.length > 0 && !queuedLine) {
+			if (last >= 2) {
+				lines[last - 1] = lines[last - 1].replace("\u251C\u2500", "\u2514\u2500");
+				lines[last] = lines[last].replace("\u2502  ", "   ");
+			}
+		}
+	}
+	return lines;
+}
+
+/**
+ * Assemble widget lines when total body exceeds MAX_WIDGET_LINES.
+ * Prioritizes running > queued > finished and appends an overflow indicator.
+ */
+function assembleOverflow(
+	heading: string,
+	sections: WidgetSections,
+	maxBody: number,
+	truncate: (line: string) => string,
+	theme: Theme,
+): string[] {
+	const { finishedLines, runningLines, queuedLine } = sections;
+	const lines: string[] = [heading];
+	let budget = maxBody - 1;
+	let hiddenRunning = 0;
+	let hiddenFinished = 0;
+
+	for (const pair of runningLines) {
+		if (budget >= 2) {
+			lines.push(...pair);
+			budget -= 2;
+		} else {
+			hiddenRunning++;
+		}
+	}
+
+	if (queuedLine && budget >= 1) {
+		lines.push(queuedLine);
+		budget--;
+	}
+
+	for (const fl of finishedLines) {
+		if (budget >= 1) {
+			lines.push(fl);
+			budget--;
+		} else {
+			hiddenFinished++;
+		}
+	}
+
+	const overflowParts: string[] = [];
+	if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
+	if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
+	const overflowText = overflowParts.join(", ");
+	lines.push(truncate(theme.fg("dim", "\u2514\u2500") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`));
+	return lines;
+}
+
 /** Pure rendering of the widget body. Returns lines to display. */
 export function renderWidgetLines(params: {
 	agents: readonly WidgetAgent[];
@@ -139,12 +268,7 @@ export function renderWidgetLines(params: {
 }): string[] {
 	const { agents, activityMap, registry, spinnerFrame, terminalWidth, theme, shouldShowFinished } = params;
 
-	const running = agents.filter(a => a.status === "running");
-	const queued = agents.filter(a => a.status === "queued");
-	const finished = agents.filter(a =>
-		a.status !== "running" && a.status !== "queued" && a.completedAt
-		&& shouldShowFinished(a.id, a.status),
-	);
+	const { running, queued, finished } = categorizeAgents(agents, shouldShowFinished);
 
 	const hasActive = running.length > 0 || queued.length > 0;
 	const hasFinished = finished.length > 0;
@@ -155,82 +279,22 @@ export function renderWidgetLines(params: {
 	const headingColor = hasActive ? "accent" : "dim";
 	const headingIcon = hasActive ? "\u25CF" : "\u25CB";
 
-	// Build sections separately for overflow-aware assembly.
-	const finishedLines: string[] = [];
-	for (const a of finished) {
-		finishedLines.push(truncate(theme.fg("dim", "\u251C\u2500") + " " + renderFinishedLine(a, activityMap.get(a.id), registry, theme)));
-	}
-
-	const runningLines: [string, string][] = [];
-	for (const a of running) {
-		const [header, act] = renderRunningLines(a, activityMap.get(a.id), registry, spinnerFrame, theme);
-		runningLines.push([
-			truncate(theme.fg("dim", "\u251C\u2500") + ` ${header}`),
-			truncate(theme.fg("dim", "\u2502  ") + act),
-		]);
-	}
-
-	const queuedLine = queued.length > 0
-		? truncate(theme.fg("dim", "\u251C\u2500") + ` ${theme.fg("muted", "\u25E6")} ${theme.fg("dim", `${queued.length} queued`)}`)
-		: undefined;
+	const { finishedLines, runningLines, queuedLine } = buildSections(
+		{ running, queued, finished },
+		activityMap,
+		registry,
+		spinnerFrame,
+		theme,
+		truncate,
+	);
 
 	// Assemble with overflow cap (heading takes 1 line).
 	const maxBody = MAX_WIDGET_LINES - 1;
 	const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
-
-	const lines: string[] = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
+	const heading = truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"));
 
 	if (totalBody <= maxBody) {
-		lines.push(...finishedLines);
-		for (const pair of runningLines) lines.push(...pair);
-		if (queuedLine) lines.push(queuedLine);
-
-		// Fix last connector: swap \u251C\u2500 \u2192 \u2514\u2500 and \u2502 \u2192 space for activity lines.
-		if (lines.length > 1) {
-			const last = lines.length - 1;
-			lines[last] = lines[last].replace("\u251C\u2500", "\u2514\u2500");
-			if (runningLines.length > 0 && !queuedLine) {
-				if (last >= 2) {
-					lines[last - 1] = lines[last - 1].replace("\u251C\u2500", "\u2514\u2500");
-					lines[last] = lines[last].replace("\u2502  ", "   ");
-				}
-			}
-		}
-	} else {
-		// Overflow — prioritize: running > queued > finished.
-		let budget = maxBody - 1;
-		let hiddenRunning = 0;
-		let hiddenFinished = 0;
-
-		for (const pair of runningLines) {
-			if (budget >= 2) {
-				lines.push(...pair);
-				budget -= 2;
-			} else {
-				hiddenRunning++;
-			}
-		}
-
-		if (queuedLine && budget >= 1) {
-			lines.push(queuedLine);
-			budget--;
-		}
-
-		for (const fl of finishedLines) {
-			if (budget >= 1) {
-				lines.push(fl);
-				budget--;
-			} else {
-				hiddenFinished++;
-			}
-		}
-
-		const overflowParts: string[] = [];
-		if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
-		if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
-		const overflowText = overflowParts.join(", ");
-		lines.push(truncate(theme.fg("dim", "\u2514\u2500") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`));
+		return assembleWithinBudget(heading, { finishedLines, runningLines, queuedLine });
 	}
-
-	return lines;
+	return assembleOverflow(heading, { finishedLines, runningLines, queuedLine }, maxBody, truncate, theme);
 }