@gotgenes/pi-subagents 7.2.5 → 7.2.7

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.7](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.6...pi-subagents-v7.2.7) (2026-05-25)
+
+
+### Documentation
+
+* plan decompose showAgentDetail ([#206](https://github.com/gotgenes/pi-packages/issues/206)) ([fe575a0](https://github.com/gotgenes/pi-packages/commit/fe575a0f2727bdcdaa4dd977f7b2db4d6cb6e9f3))
+* **retro:** add planning stage notes for issue [#206](https://github.com/gotgenes/pi-packages/issues/206) ([057bbb6](https://github.com/gotgenes/pi-packages/commit/057bbb666b8d1c89d70936a837fc028512368fcc))
+* **retro:** add retro notes for issue [#205](https://github.com/gotgenes/pi-packages/issues/205) ([b9abe3b](https://github.com/gotgenes/pi-packages/commit/b9abe3ba050468d71015eb77262afb4093c8289f))
+* **retro:** add TDD stage notes for issue [#206](https://github.com/gotgenes/pi-packages/issues/206) ([88fdfc2](https://github.com/gotgenes/pi-packages/commit/88fdfc222950ce63e0a8f9273d3bff234ffa0538))
+* update complexity table after showAgentDetail decomposition ([8d8a396](https://github.com/gotgenes/pi-packages/commit/8d8a396bbfbe0e4d86dc37aceb53df613868bd26))
+
+## [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

@@ -466,12 +466,10 @@ Bags with 10+ fields are the highest priority for decomposition.
 
 Functions with cyclomatic complexity ≥ 21 (critical threshold):
 
-| Function            | Cyclomatic | Cognitive | File                        | Concern                            |
-| ------------------- | ---------- | --------- | --------------------------- | ---------------------------------- |
-| `showAgentDetail`   | 25         | 33        | `ui/agent-config-editor.ts` | Agent detail/edit view             |
-| `renderWidgetLines` | 25         | 44        | `ui/widget-renderer.ts`     | Renders widget status lines        |
-| `ejectAgent`        | 21         | 20        | `ui/agent-config-editor.ts` | Eject agent to filesystem          |
-| `update`            | 21         | 31        | `ui/agent-widget.ts`        | Widget lifecycle + polling         |
+| 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      |
 
 ### Churn hotspots
 
@@ -599,155 +597,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 +616,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 +624,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 +632,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 +647,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 +663,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 +678,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 +703,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/plans/0206-decompose-show-agent-detail.md

@@ -0,0 +1,211 @@
+---
+issue: 206
+issue_title: "Decompose showAgentDetail (cognitive 33)"
+---
+
+# Decompose `showAgentDetail`
+
+## Problem Statement
+
+`showAgentDetail` in `ui/agent-config-editor.ts` has cognitive complexity 33 (CRITICAL per fallow health).
+It interleaves menu-option computation, user-choice dispatch, and three inline action handlers (edit, delete, reset) in a single 67-line function.
+`ejectAgent` in the same file has cognitive complexity 20 from its 14-branch frontmatter builder.
+Phase 12, Step 2 targets cognitive complexity < 10 per function.
+
+## Goals
+
+- Extract menu-option computation and inline action handlers into separate functions, each with cognitive complexity < 10.
+- Extract frontmatter building from `ejectAgent` into a pure function.
+- Preserve all existing behavior — no user-visible or API changes.
+- Add unit tests for the two new exported pure functions.
+
+## Non-Goals
+
+- Decomposing `renderWidgetLines` (#205), `update` (#207), or shared test fixtures (#208) — sibling Phase 12 steps.
+- Changing the menu structure, option labels, or action semantics.
+- Decomposing `disableAgent` or `enableAgent` — their cognitive complexity is already manageable (< 15).
+
+## Background
+
+`agent-config-editor.ts` was extracted from `agent-menu.ts` in Phase 8 (#136).
+The file exposes a single factory `createAgentConfigEditor` that returns `{ showAgentDetail }`.
+Internally the factory closes over `fileOps`, `registry`, `personalAgentsDir`, and `projectAgentsDir`.
+
+Three action handlers already exist as closure-level functions: `ejectAgent`, `disableAgent`, `enableAgent`.
+The remaining three actions — Edit, Delete, and Reset to default — are inlined in `showAgentDetail`'s if/else dispatch chain.
+
+The existing test suite (`test/ui/agent-config-editor.test.ts`, 18 tests) covers all menu-option combinations and action branches through the public `showAgentDetail` entry point.
+
+### Complexity sources
+
+`showAgentDetail` (cognitive 33):
+
+1. Menu-option building — 4-branch if/else chain with 3 boolean conditions (`disabled`, `isDefault`, `file`).
+2. Action dispatch — 6-branch if/else chain based on `choice`.
+3. Inline Edit handler — 3 nested `if` guards (`file`, `content`, `edited !== content`).
+4. Inline Delete handler — nested `if (file)` + `if (confirmed)`.
+5. Inline Reset handler — nested `if (file)` + `if (confirmed)`.
+
+`ejectAgent` (cognitive 20):
+
+1. Location selection + overwrite check — 2 early returns with nested ifs.
+2. Frontmatter field building — 14 conditional `if`/`else if` branches.
+
+## Design Overview
+
+### Extracted from `showAgentDetail`
+
+#### `buildMenuOptions` (exported, pure)
+
+```typescript
+export function buildMenuOptions(
+  cfg: { isDefault?: boolean; enabled?: boolean },
+  file: string | undefined,
+): string[]
+```
+
+Accepts the minimal config shape and file path.
+Returns the menu option array.
+Pure computation — no IO, no side effects.
+Exported for direct unit testing.
+
+#### `handleEdit` (closure-internal)
+
+Handles the Edit action: reads the file, opens the editor, writes if changed.
+Signature: `(ui: MenuUI, name: string, file: string) => Promise<void>`.
+Called only when `file` is defined (guaranteed by menu-option construction).
+
+#### `handleDelete` (closure-internal)
+
+Handles the Delete action: confirms with user, removes file, reloads registry.
+Signature: `(ui: MenuUI, name: string, file: string) => Promise<void>`.
+
+#### `handleReset` (closure-internal)
+
+Handles the Reset to default action: confirms, removes override file, reloads registry.
+Signature: `(ui: MenuUI, name: string, file: string) => Promise<void>`.
+
+### Extracted from `ejectAgent`
+
+#### `buildEjectContent` (exported, pure)
+
+```typescript
+export function buildEjectContent(cfg: AgentConfig): string
+```
+
+Builds the full `.md` file content (frontmatter + system prompt) for an ejected agent.
+Pure function — no IO.
+Exported for direct unit testing.
+
+### After refactoring
+
+`showAgentDetail` becomes a thin orchestrator (~15 lines):
+
+```typescript
+async function showAgentDetail(ui: MenuUI, name: string) {
+  if (registry.resolveType(name) == null) {
+    ui.notify(`Agent config not found for "${name}".`, "warning");
+    return;
+  }
+  const cfg = registry.resolveAgentConfig(name);
+  const file = fileOps.findAgentFile(name, agentDirs());
+
+  const choice = await ui.select(name, buildMenuOptions(cfg, file));
+  if (!choice || choice === "Back") return;
+
+  if (choice === "Edit" && file) await handleEdit(ui, name, file);
+  else if (choice === "Delete" && file) await handleDelete(ui, name, file);
+  else if (choice === "Reset to default" && file) await handleReset(ui, name, file);
+  else if (choice.startsWith("Eject")) await ejectAgent(ui, name, cfg);
+  else if (choice === "Disable") await disableAgent(ui, name);
+  else if (choice === "Enable") await enableAgent(ui, name);
+}
+```
+
+Cognitive complexity: ~5 (one null-check early return + flat dispatch chain with no nesting).
+
+`ejectAgent` becomes:
+
+```typescript
+async function ejectAgent(ui: MenuUI, name: string, cfg: AgentConfig) {
+  const location = await ui.select("Choose location", [...]);
+  if (!location) return;
+  const targetDir = location.startsWith("Project") ? projectAgentsDir : personalAgentsDir;
+  const targetPath = join(targetDir, `${name}.md`);
+  if (fileOps.exists(targetPath)) {
+    const overwrite = await ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+    if (!overwrite) return;
+  }
+  fileOps.write(targetPath, buildEjectContent(cfg));
+  registry.reload();
+  ui.notify(`Ejected ${name} to ${targetPath}`, "info");
+}
+```
+
+Cognitive complexity: ~6 (two early returns, one ternary, one nested if).
+
+## Module-Level Changes
+
+### Changed: `src/ui/agent-config-editor.ts`
+
+- Add exported `buildMenuOptions(cfg, file)` — pure function extracted from `showAgentDetail`.
+- Add exported `buildEjectContent(cfg)` — pure function extracted from `ejectAgent`.
+- Add closure-internal `handleEdit(ui, name, file)` — extracted from `showAgentDetail` inline logic.
+- Add closure-internal `handleDelete(ui, name, file)` — extracted from `showAgentDetail` inline logic.
+- Add closure-internal `handleReset(ui, name, file)` — extracted from `showAgentDetail` inline logic.
+- Simplify `showAgentDetail` to orchestrate: resolve → build menu → select → dispatch.
+- Simplify `ejectAgent` to delegate frontmatter building to `buildEjectContent`.
+
+No exports are removed or renamed.
+The public API (`createAgentConfigEditor` returning `{ showAgentDetail }`) is unchanged.
+
+### Changed: `test/ui/agent-config-editor.test.ts`
+
+- Add `describe("buildMenuOptions")` with tests for each menu-option combination (5 cases from existing tests, restructured as direct function calls).
+- Add `describe("buildEjectContent")` with tests for minimal config and config with all optional fields.
+- Existing `showAgentDetail` tests remain unchanged as integration coverage.
+
+### Changed: `docs/architecture/architecture.md`
+
+- Update the complexity hotspots table: `showAgentDetail` drops from 25/33 to ~5/5; `ejectAgent` drops from 21/20 to ~6/6.
+
+## Test Impact Analysis
+
+1. **New tests enabled:** Direct unit tests for `buildMenuOptions` (pure function with 5 state combinations) and `buildEjectContent` (pure function with many optional fields).
+   These were previously impossible to test in isolation because the logic was embedded in async UI flows.
+2. **Existing tests that stay:** All 18 `showAgentDetail` tests remain as integration coverage — they exercise the full resolve → menu → dispatch → action pipeline.
+3. **No tests become redundant:** The existing menu-option-structure tests (5 tests) overlap with `buildMenuOptions` unit tests, but they remain valuable as integration tests verifying the full flow produces the correct menu.
+
+## TDD Order
+
+1. **Red → Green:** Add `buildMenuOptions` unit tests (5 cases: default no-file, default with-file, custom with-file, disabled-default with-file, disabled-custom with-file).
+   Export `buildMenuOptions` as a pure function.
+   Extract the menu-option computation from `showAgentDetail` into it.
+   Verify all existing tests pass.
+   Commit: `refactor: extract buildMenuOptions from showAgentDetail`
+
+2. **Red → Green:** Extract `handleEdit`, `handleDelete`, `handleReset` as closure-internal functions.
+   Simplify `showAgentDetail` dispatch to a flat if/else chain calling named handlers.
+   Verify all existing tests pass.
+   Commit: `refactor: extract inline handlers from showAgentDetail`
+
+3. **Red → Green:** Add `buildEjectContent` unit tests (minimal config, config with all optional fields, config with array extensions/skills).
+   Export `buildEjectContent` as a pure function.
+   Extract the frontmatter-building logic from `ejectAgent` into it.
+   Verify all existing tests pass.
+   Commit: `refactor: extract buildEjectContent from ejectAgent`
+
+4. **Docs:** Update the complexity hotspots table in `docs/architecture/architecture.md`.
+   Commit: `docs: update complexity table after showAgentDetail decomposition`
+
+## Risks and Mitigations
+
+| Risk                                                                           | Mitigation                                                                                                     |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `buildMenuOptions` return order must match existing select mock expectations   | Unit tests verify exact array equality; integration tests remain as safety net.                                |
+| `buildEjectContent` frontmatter field ordering is load-bearing for eject tests | Unit tests verify the full content string; existing eject integration test uses `stringContaining` (flexible). |
+| Closure-internal handlers share mutable `fileOps`/`registry` references        | No change from current behavior — they already close over these references.                                    |
+
+## Open Questions
+
+None — the decomposition is mechanical extraction of existing code into named functions.

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,64 @@
+---
+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.
+
+## Stage: Final Retrospective (2026-05-25T15:41:48Z)
+
+### Session summary
+
+All three stages (planning, TDD implementation, shipping) completed in a single session.
+Four refactor commits extracted `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow` from `renderWidgetLines`, reducing cognitive complexity from 44 to <10 per function.
+Released as `pi-subagents-v7.2.6`.
+
+### Observations
+
+#### What went well
+
+- The planning-through-shipping pipeline was efficient: plan → 4 TDD steps → ship → release in one session with no rework.
+- The plan correctly identified all four extraction targets and ordered TDD steps to avoid intermediate breakage.
+- All 23 existing `widget-renderer.test.ts` tests passed throughout with zero modifications — the existing test coverage was at the right abstraction level for this refactoring.
+- The `architecture.md` Phase 12 update (issue links, refactoring table row) was a clean opportunistic addition.
+
+#### What caused friction (agent side)
+
+- `other` (Edit tool limitation) — The Edit tool introduced a stray double-backtick when inserting `assembleOverflow`'s body, caused by JSON escaping colliding with nested template literal backticks.
+  The same limitation then prevented matching `oldText` containing nested template literals in the `renderWidgetLines` overflow block.
+  Required two Python-based line-level fixes via bash.
+  Impact: ~3 extra tool calls; self-identified and self-corrected.
+
+#### What caused friction (user side)
+
+- No friction observed.

package/docs/retro/0206-decompose-show-agent-detail.md

@@ -0,0 +1,36 @@
+---
+issue: 206
+issue_title: "Decompose showAgentDetail (cognitive 33)"
+---
+
+# Retro: #206 — Decompose showAgentDetail (cognitive 33)
+
+## Stage: Planning (2026-05-25T12:00:00Z)
+
+### Session summary
+
+Produced a 4-step plan to decompose `showAgentDetail` (cognitive 33) and `ejectAgent` (cognitive 20) in `ui/agent-config-editor.ts`.
+The plan extracts two exported pure functions (`buildMenuOptions`, `buildEjectContent`) with dedicated unit tests, plus three closure-internal handlers (`handleEdit`, `handleDelete`, `handleReset`).
+
+### Observations
+
+- Three of the six action handlers (`ejectAgent`, `disableAgent`, `enableAgent`) were already extracted as closure functions — only Edit, Delete, and Reset were inlined in the dispatch chain.
+- `buildMenuOptions` and `buildEjectContent` are ideal pure-function extractions: complex branching logic with no IO dependencies, previously untestable in isolation.
+- The existing 18 integration tests through `showAgentDetail` provide a strong safety net — no risk of behavior regression during extraction.
+- Chose to scope `ejectAgent` decomposition into this issue since the issue's outcome says "< 10 per function" and `ejectAgent` is at cognitive 20 in the same file.
+- `disableAgent` and `enableAgent` were explicitly deferred — their cognitive complexity is manageable and decomposing them would add scope without meaningful benefit.
+
+## Stage: Implementation — TDD (2026-05-25T11:55:00Z)
+
+### Session summary
+
+Completed all 4 TDD steps. 3 `refactor:` commits extract `buildMenuOptions`, the three inline handlers, and `buildEjectContent`; 1 `docs:` commit updates the architecture table.
+Test count grew from 21 to 33 (+12 new unit tests for the two exported pure functions).
+
+### Observations
+
+- A `newText: null` bug in the Edit tool corrupted `agent-config-editor.ts` during step 1; recovered immediately by rewriting the file with `Write`.
+- The test used `thinking: "auto"` which is not a valid `ThinkingLevel` — fixed by changing to `"low"` before the final commit; the type error was caught by `pnpm run check` after the TDD step.
+- `buildMenuOptions` extracted cleanly with early-return style (no `let menuOptions` intermediate); the refactored function passes all 5 new unit tests and all 21 existing integration tests.
+- `handleEdit`, `handleDelete`, and `handleReset` are closure-internal; they drop the outer `if (file)` guard since the menu only shows those options when `file` is defined.
+- `buildEjectContent` extracted from `ejectAgent` reduces `ejectAgent` to a thin IO function (~10 lines); no behavior change verified by the existing eject integration tests.

package/package.json

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

package/src/ui/agent-config-editor.ts

@@ -12,6 +12,55 @@ import type { AgentConfig } from "#src/types";
 import type { AgentFileOps } from "#src/ui/agent-file-ops";
 import type { MenuUI } from "#src/ui/agent-menu";
 
+// ---- Pure helpers ----
+
+/** Compute the menu option list for the agent detail view. */
+export function buildMenuOptions(
+  cfg: { isDefault?: boolean; enabled?: boolean },
+  file: string | undefined,
+): string[] {
+  const isDefault = cfg.isDefault === true;
+  const disabled = cfg.enabled === false;
+
+  if (disabled && file) {
+    return isDefault
+      ? ["Enable", "Edit", "Reset to default", "Delete", "Back"]
+      : ["Enable", "Edit", "Delete", "Back"];
+  }
+  if (isDefault && !file) {
+    return ["Eject (export as .md)", "Disable", "Back"];
+  }
+  if (isDefault && file) {
+    return ["Edit", "Disable", "Reset to default", "Delete", "Back"];
+  }
+  return ["Edit", "Disable", "Delete", "Back"];
+}
+
+/** Build the `.md` file content (frontmatter + system prompt) for an ejected agent. */
+export function buildEjectContent(cfg: AgentConfig): string {
+  const fmFields: string[] = [];
+  fmFields.push(`description: ${cfg.description}`);
+  if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`);
+  fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") ?? "all"}`);
+  if (cfg.model) fmFields.push(`model: ${cfg.model}`);
+  if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`);
+  if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
+  fmFields.push(`prompt_mode: ${cfg.promptMode}`);
+  if (cfg.extensions === false) fmFields.push("extensions: false");
+  else if (Array.isArray(cfg.extensions))
+    fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
+  if (cfg.skills === false) fmFields.push("skills: false");
+  else if (Array.isArray(cfg.skills))
+    fmFields.push(`skills: ${cfg.skills.join(", ")}`);
+  if (cfg.disallowedTools?.length)
+    fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
+  if (cfg.inheritContext) fmFields.push("inherit_context: true");
+  if (cfg.runInBackground) fmFields.push("run_in_background: true");
+  if (cfg.isolated) fmFields.push("isolated: true");
+  if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
+  return `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
+}
+
 // ---- Factory ----
 
 export function createAgentConfigEditor(
@@ -30,65 +79,52 @@ export function createAgentConfigEditor(
       return;
     }
     const cfg = registry.resolveAgentConfig(name);
-
     const file = fileOps.findAgentFile(name, agentDirs());
-    const isDefault = cfg.isDefault === true;
-    const disabled = cfg.enabled === false;
-
-    let menuOptions: string[];
-    if (disabled && file) {
-      menuOptions = isDefault
-        ? ["Enable", "Edit", "Reset to default", "Delete", "Back"]
-        : ["Enable", "Edit", "Delete", "Back"];
-    } else if (isDefault && !file) {
-      menuOptions = ["Eject (export as .md)", "Disable", "Back"];
-    } else if (isDefault && file) {
-      menuOptions = ["Edit", "Disable", "Reset to default", "Delete", "Back"];
-    } else {
-      menuOptions = ["Edit", "Disable", "Delete", "Back"];
-    }
 
-    const choice = await ui.select(name, menuOptions);
+    const choice = await ui.select(name, buildMenuOptions(cfg, file));
     if (!choice || choice === "Back") return;
 
-    if (choice === "Edit" && file) {
-      const content = fileOps.read(file);
-      if (content !== undefined) {
-        const edited = await ui.editor(`Edit ${name}`, content);
-        if (edited !== undefined && edited !== content) {
-          fileOps.write(file, edited);
-          registry.reload();
-          ui.notify(`Updated ${file}`, "info");
-        }
-      }
-    } else if (choice === "Delete") {
-      if (file) {
-        const confirmed = await ui.confirm(
-          "Delete agent",
-          `Delete ${name} (${file})?`,
-        );
-        if (confirmed) {
-          fileOps.remove(file);
-          registry.reload();
-          ui.notify(`Deleted ${file}`, "info");
-        }
-      }
-    } else if (choice === "Reset to default" && file) {
-      const confirmed = await ui.confirm(
-        "Reset to default",
-        `Delete override ${file} and restore embedded default?`,
-      );
-      if (confirmed) {
-        fileOps.remove(file);
-        registry.reload();
-        ui.notify(`Restored default ${name}`, "info");
-      }
-    } else if (choice.startsWith("Eject")) {
-      await ejectAgent(ui, name, cfg);
-    } else if (choice === "Disable") {
-      await disableAgent(ui, name);
-    } else if (choice === "Enable") {
-      await enableAgent(ui, name);
+    if (choice === "Edit" && file) await handleEdit(ui, name, file);
+    else if (choice === "Delete" && file) await handleDelete(ui, name, file);
+    else if (choice === "Reset to default" && file)
+      await handleReset(ui, name, file);
+    else if (choice.startsWith("Eject")) await ejectAgent(ui, name, cfg);
+    else if (choice === "Disable") await disableAgent(ui, name);
+    else if (choice === "Enable") await enableAgent(ui, name);
+  }
+
+  async function handleEdit(ui: MenuUI, name: string, file: string) {
+    const content = fileOps.read(file);
+    if (content === undefined) return;
+    const edited = await ui.editor(`Edit ${name}`, content);
+    if (edited !== undefined && edited !== content) {
+      fileOps.write(file, edited);
+      registry.reload();
+      ui.notify(`Updated ${file}`, "info");
+    }
+  }
+
+  async function handleDelete(ui: MenuUI, name: string, file: string) {
+    const confirmed = await ui.confirm(
+      "Delete agent",
+      `Delete ${name} (${file})?`,
+    );
+    if (confirmed) {
+      fileOps.remove(file);
+      registry.reload();
+      ui.notify(`Deleted ${file}`, "info");
+    }
+  }
+
+  async function handleReset(ui: MenuUI, name: string, file: string) {
+    const confirmed = await ui.confirm(
+      "Reset to default",
+      `Delete override ${file} and restore embedded default?`,
+    );
+    if (confirmed) {
+      fileOps.remove(file);
+      registry.reload();
+      ui.notify(`Restored default ${name}`, "info");
     }
   }
 
@@ -112,30 +148,7 @@ export function createAgentConfigEditor(
       if (!overwrite) return;
     }
 
-    const fmFields: string[] = [];
-    fmFields.push(`description: ${cfg.description}`);
-    if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`);
-    fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") ?? "all"}`);
-    if (cfg.model) fmFields.push(`model: ${cfg.model}`);
-    if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`);
-    if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
-    fmFields.push(`prompt_mode: ${cfg.promptMode}`);
-    if (cfg.extensions === false) fmFields.push("extensions: false");
-    else if (Array.isArray(cfg.extensions))
-      fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
-    if (cfg.skills === false) fmFields.push("skills: false");
-    else if (Array.isArray(cfg.skills))
-      fmFields.push(`skills: ${cfg.skills.join(", ")}`);
-    if (cfg.disallowedTools?.length)
-      fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
-    if (cfg.inheritContext) fmFields.push("inherit_context: true");
-    if (cfg.runInBackground) fmFields.push("run_in_background: true");
-    if (cfg.isolated) fmFields.push("isolated: true");
-    if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
-
-    const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
-
-    fileOps.write(targetPath, content);
+    fileOps.write(targetPath, buildEjectContent(cfg));
     registry.reload();
     ui.notify(`Ejected ${name} to ${targetPath}`, "info");
   }

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);
 }