@gotgenes/pi-subagents 7.3.1 → 7.4.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.2...pi-subagents-v7.4.0) (2026-05-25)
+
+
+### Features
+
+* add model attribution to formatAssistantMessage ([76f2ada](https://github.com/gotgenes/pi-packages/commit/76f2adaa6bad9d1a3b15a3ba208b3ab96e07ecd1))
+* add model attribution to getAgentConversation ([c186c37](https://github.com/gotgenes/pi-packages/commit/c186c370b975e5ef6596d9a3d7719c720a580640))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#214](https://github.com/gotgenes/pi-packages/issues/214) ([7e39c96](https://github.com/gotgenes/pi-packages/commit/7e39c96563517661c1c8c7f250402115b232a097))
+
+## [7.3.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.1...pi-subagents-v7.3.2) (2026-05-25)
+
+
+### Documentation
+
+* mark Phase 13 Step 1 complete ([8d62590](https://github.com/gotgenes/pi-packages/commit/8d62590aeded8aba25df96ea2fbba6581572eaf7))
+* **pi-subagents:** link Phase 13 issues [#214](https://github.com/gotgenes/pi-packages/issues/214)–[#219](https://github.com/gotgenes/pi-packages/issues/219) in architecture roadmap ([636a1e5](https://github.com/gotgenes/pi-packages/commit/636a1e500319b9ce1007c0a571dd13199cdd2606))
+* **pi-subagents:** propose Phase 13 improvement roadmap ([caf2a53](https://github.com/gotgenes/pi-packages/commit/caf2a5376c69744db1743a9362096e764d9524b1))
+* plan convert remaining closure factories to classes ([#214](https://github.com/gotgenes/pi-packages/issues/214)) ([2225920](https://github.com/gotgenes/pi-packages/commit/222592007e2ce29d5e6d5678a303f6cb781dae39))
+* **retro:** add planning stage notes for issue [#214](https://github.com/gotgenes/pi-packages/issues/214) ([3072e61](https://github.com/gotgenes/pi-packages/commit/3072e618f08080065ef9f3c7520ff44e8dbc84b4))
+* **retro:** add retro notes for issue [#208](https://github.com/gotgenes/pi-packages/issues/208) ([1436396](https://github.com/gotgenes/pi-packages/commit/1436396d71e79cbbf519877e9dc899000ebd0001))
+* **retro:** add TDD stage notes for issue [#214](https://github.com/gotgenes/pi-packages/issues/214) ([201e1eb](https://github.com/gotgenes/pi-packages/commit/201e1ebbaba66e0d83cc006ef77b711c22fb1bb8))
+
 ## [7.3.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.3.0...pi-subagents-v7.3.1) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -431,36 +431,38 @@ These are fire-and-forget broadcast events — no request IDs, no reply channels
 
 ### Health metrics
 
-| Metric                    | Value                        |
-| ------------------------- | ---------------------------- |
-| Health score              | 75/100 (B)                   |
-| Total LOC                 | 8,218 (53 files)             |
-| Dead code                 | 0 files, 0 exports           |
-| Maintainability index     | 90.7 (good)                  |
-| Avg cyclomatic complexity | 1.5                          |
-| P90 cyclomatic complexity | 2                            |
-| Production duplication    | 18 lines (1 clone group)     |
-| Test duplication          | 71 clone groups, 1,424 lines |
+| Metric                     | Value                                |
+| -------------------------- | ------------------------------------ |
+| Health score               | 78/100 (B)                           |
+| Total LOC                  | 8,180 (53 files)                     |
+| Test LOC                   | 12,026                               |
+| Dead code                  | 0 files, 0 exports                   |
+| Maintainability index      | 90.7 (good)                          |
+| Avg cyclomatic complexity  | 1.5                                  |
+| P90 cyclomatic complexity  | 2                                    |
+| Production duplication     | 20 lines (1 clone group)             |
+| Test duplication           | 59 clone groups, 1,046 lines         |
+| Fallow refactoring targets | 1 (buildParentContext, cognitive 30) |
 
 ### Dependency bag inventory
 
 These interfaces carry hidden dependencies that obscure true coupling.
 Bags with 10+ fields are the highest priority for decomposition.
 
-| Interface                   | Fields                                                 | Consumers                                         | Severity |
-| --------------------------- | ------------------------------------------------------ | ------------------------------------------------- | -------- |
-| `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done   |
-| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done   |
-| `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done   |
-| `SessionConfig`             | 8 (ToolFilterConfig nested)                            | agent-runner (output of assembler)                | ✓ done   |
-| `NotificationDetails`       | 10                                                     | notification                                      | Medium   |
-| `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Medium   |
-| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done   |
-| `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Medium   |
-| `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done   |
-| `AgentMenuDeps`             | 8                                                      | agent-menu                                        | Low      |
-| `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low      |
-| `AgentRecordInit`           | 8                                                      | agent-record                                      | Low      |
+| Interface                   | Fields                                                 | Consumers                                         | Severity  |
+| --------------------------- | ------------------------------------------------------ | ------------------------------------------------- | --------- |
+| `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done    |
+| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done    |
+| `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done    |
+| `SessionConfig`             | 8 (ToolFilterConfig nested)                            | agent-runner (output of assembler)                | ✓ done    |
+| `NotificationDetails`       | 10                                                     | notification                                      | Low (DTO) |
+| `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Low (SDK) |
+| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done    |
+| `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Low (SDK) |
+| `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done    |
+| `AgentMenuDeps`             | 8                                                      | agent-menu                                        | ✓ done    |
+| `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low       |
+| `AgentRecordInit`           | 8                                                      | agent-record                                      | Low       |
 
 ### Complexity hotspots
 
@@ -472,18 +474,22 @@ No functions remain above the critical threshold — all hotspots resolved in Ph
 
 Files with highest commit frequency × complexity (accelerating trend):
 
-| Score | File                  | Commits |
-| ----- | --------------------- | ------- |
-| 85.7  | `index.ts`            | 65      |
-| 35.9  | `agent-manager.ts`    | 31      |
-| 25.9  | `ui/agent-menu.ts`    | 26      |
-| 23.3  | `tools/agent-tool.ts` | 30      |
+| Score | File                        | Commits | Trend          |
+| ----- | --------------------------- | ------- | -------------- |
+| 43.3  | `index.ts`                  | 81      | ▲ accelerating |
+| 26.0  | `ui/agent-menu.ts`          | 33      | ▲ accelerating |
+| 13.6  | `tools/agent-tool.ts`       | 41      | ▲ accelerating |
+| 13.3  | `ui/conversation-viewer.ts` | 16      | ▲ accelerating |
+| 12.6  | `ui/agent-config-editor.ts` | 10      | ▼ cooling      |
+| 11.7  | `ui/agent-widget.ts`        | 14      | ▲ accelerating |
+
+Note: accelerating trends reflect recent refactoring phases, not feature churn.
+Once structural work stabilizes, these are expected to cool.
 
 ### Production duplication
 
-The 18-line clone group between `agent-runner.ts` and `message-formatters.ts` was resolved in #172.
-`ToolCallContent`, `getToolCallName`, and `extractAssistantContent` now live in `session/content-items.ts`.
-No known production duplication remains.
+The prior clone group between `agent-runner.ts` and `message-formatters.ts` was resolved in #172.
+One 20-line clone group remains between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` — both implement the same overwrite-guard + write + reload + notify pattern.
 
 ### Proposed bag decompositions
 
@@ -600,51 +606,125 @@ Phase 11 converted all closure factories to classes, eliminating adapter closure
 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 (complete)
+
+Phase 12 decomposed the three remaining high-complexity UI functions and extracted shared test fixtures.
+All four steps are closed: [#205], [#206], [#207], [#208].
+
+## Improvement roadmap (Phase 13)
+
+Phase 13 addresses the remaining fallow refactoring target, `agent-manager.ts` oversized method, production duplication, SDK boundary coupling, and the heaviest test clone families.
+Health score target: 80+ (A).
+
+### Findings summary
+
+| Finding                                                          | Category       | Impact | Risk | Priority |
+| ---------------------------------------------------------------- | -------------- | ------ | ---- | -------- |
+| 3 remaining closure factories (Phase 11 survivors)               | C: Coupling    | 4      | 2    | 16       |
+| `buildParentContext` cognitive 30 (only fallow target)           | B: Oversized   | 3      | 1    | 15       |
+| `startAgent` in agent-manager.ts (~130 LOC method)               | B: Oversized   | 4      | 3    | 12       |
+| Test duplication: 59 clone groups, 1,046 lines                   | D: Testability | 3      | 2    | 12       |
+| Overwrite guard duplicated across UI modules (20 lines)          | A: Redundant   | 2      | 1    | 10       |
+| `settings.ts` calls SDK function `getAgentDir()` at module level | C: Coupling    | 2      | 1    | 10       |
+
+### Step 1: Convert remaining closure factories to classes — [#214] ✓
+
+Three closure factories converted to classes in [#214].
+
+| Factory → Class                                        | File                          | Captures                                 |
+| ------------------------------------------------------ | ----------------------------- | ---------------------------------------- |
+| `createAgentConfigEditor()` → `AgentConfigEditor`      | `ui/agent-config-editor.ts`   | `fileOps`, `registry`, 2 dirs            |
+| `createAgentCreationWizard()` → `AgentCreationWizard`  | `ui/agent-creation-wizard.ts` | `fileOps`, `manager`, `registry`, 2 dirs |
+| `createSubagentsService()` → `SubagentsServiceAdapter` | `service/service-adapter.ts`  | `manager`, `resolveModel`, `runtime`     |
+
+- Smell: C (coupling — deps hidden in closure scope instead of explicit on class)
+- Outcome: 0 remaining closure factories (excluding pure-function factories), deps visible as constructor parameters
 
-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 2: Decompose `buildParentContext` (cognitive 30) — [#215]
 
-### Step 1: Decompose `renderWidgetLines` (cognitive 44) — [#205]
+`buildParentContext` in `session/context.ts` is the only remaining fallow refactoring target.
+The function loops over branch entries with 3 type-check branches, each with sub-branches for role or summary.
+Extract per-entry-type formatters: `formatMessageEntry(entry)` and `formatCompactionEntry(entry)`.
 
-`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.
+- Target: `src/session/context.ts`
+- Smell: B (oversized function)
+- Outcome: cognitive complexity < 10, function < 15 LOC
 
-- Target: `src/ui/widget-renderer.ts`
-- Outcome: cognitive complexity < 10
+### Step 3: Decompose `startAgent` in `agent-manager.ts` — [#216]
 
-### Step 2: Decompose `showAgentDetail` (cognitive 33) — [#206]
+`startAgent` is a ~130-line private method that chains worktree setup → state transitions → observer notification → abort-signal wiring → runner invocation → `.then()` completion handler (~35 lines) → `.catch()` error handler (~15 lines).
+Both the `.then()` and `.catch()` blocks share common finalization logic (background counter decrement, observer notification, queue drain, worktree cleanup, detach signal).
 
-`showAgentDetail` in `ui/agent-config-editor.ts` handles display, edit, eject, and delete flows.
-Extract sub-functions per menu action.
+Extract:
 
-- Target: `src/ui/agent-config-editor.ts`
-- Outcome: cognitive complexity < 10
+1. `handleRunCompletion(record, options, result)` — worktree cleanup, state transition, execution update, observer notification.
+2. `handleRunError(record, options, err)` — error marking, worktree cleanup.
+3. `finalizeBackgroundRun(record)` — shared `runningBackground--`, observer, `drainQueue()`.
 
-### Step 3: Decompose `update` in `agent-widget.ts` (cognitive 31) — [#207]
+- Target: `src/lifecycle/agent-manager.ts`
+- Smell: B (oversized method) + A (duplicated finalization logic in then/catch)
+- Outcome: no method > 40 LOC, `agent-manager.ts` < 480 LOC
 
-`update` mixes timer lifecycle, agent list assembly, render delegation, and visibility state.
-Extract `assembleWidgetState` (pure) and timer management.
+### Step 4: Extract overwrite guard from UI — [#217]
 
-- Target: `src/ui/agent-widget.ts`
-- Outcome: cognitive complexity < 10
+The 20-line pattern duplicated between `agent-config-editor.ts:138–151` and `agent-creation-wizard.ts:231–250` checks file existence, prompts for confirmation, writes the file, reloads the registry, and notifies the user.
+Extract a shared `writeAgentFile(fileOps, ui, registry, targetPath, content, label)` function.
 
-### Step 4: Extract shared test fixtures — [#208]
+- Target: new `src/ui/agent-file-writer.ts`, consumers `src/ui/agent-config-editor.ts` and `src/ui/agent-creation-wizard.ts`
+- Smell: A (production duplication)
+- Outcome: 0 production clone groups
 
-The 3 heaviest clone families:
+### Step 5: Push SDK boundary in `settings.ts` — [#218]
 
-- `agent-runner.test.ts` + `agent-runner-extension-tools.test.ts` (60-line shared setup)
-- `agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts` (54+51+24 lines)
-- `agent-manager.test.ts` (18 internal clone groups, 210 duplicated lines)
+`globalPath()` calls `getAgentDir()` (a Pi SDK function) at invocation time.
+This hides a platform dependency inside a module that is otherwise pure configuration logic.
+Inject `agentDir: string` as a constructor parameter to `SettingsManager` and pass the global settings path from the boundary in `index.ts`.
+
+- Target: `src/settings.ts`, `src/index.ts`
+- Smell: C (platform type threading)
+- Outcome: `settings.ts` has 0 Pi SDK imports, `loadSettings`/`saveSettings` become fully testable without SDK stubs
+
+### Step 6: Reduce test duplication — top 3 clone families — [#219]
+
+The three heaviest remaining clone families after Phase 12:
+
+1. `agent-manager.test.ts` — 16 clone groups, 160 duplicated lines.
+   Extract shared setup/assertion helpers into `test/helpers/manager-stubs.ts`.
+2. `conversation-viewer.test.ts` — 8 clone groups, 91 duplicated lines.
+   Extract entry-builder helpers into existing `test/helpers/` or inline factory.
+3. `agent-config-editor.test.ts` — 5 clone groups, 42 duplicated lines.
+   Extract shared setup helpers.
+
+- Target: `test/lifecycle/agent-manager.test.ts`, `test/conversation-viewer.test.ts`, `test/ui/agent-config-editor.test.ts`
+- Smell: D (test duplication)
+- Outcome: test duplication reduced by ~200 lines (from 1,046 to < 850)
+
+### Step dependency diagram
+
+```mermaid
+flowchart LR
+    S1["Step 1\nclosure to class"]
+    S2["Step 2\nbuildParentContext"]
+    S3["Step 3\nstartAgent decomp"]
+    S4["Step 4\noverwrite guard"]
+    S5["Step 5\nsettings SDK"]
+    S6["Step 6\ntest duplication"]
+
+    S1 --> S4
+    S1 --> S6
+    S3 --> S6
+    S2 ~~~ S5
+```
 
-Extract shared factories into `test/helpers/` modules.
+### Tracks
 
-- Target: new `test/helpers/runner-io.ts` and `test/helpers/ui-stubs.ts` modules
-- Outcome: test duplication reduced by ~250 lines
+1. **Track A — Structural** (Steps 1, 3): closure-to-class conversions and method decomposition.
+2. **Track B — Complexity and coupling** (Steps 2, 5): independent, can proceed in parallel with Track A.
+3. **Track C — Duplication** (Steps 4, 6): Step 4 depends on Step 1 (overwrite guard lives in files being converted); Step 6 depends on Steps 1 and 3 (production code they test changes first).
 
 ## Refactoring history
 
-Phases 1–5 and 7–11 are complete.
+Phases 1–5 and 7–12 are complete.
 Phase 6 (UI extraction to a separate package) is deferred.
 Detailed records are preserved in per-phase history files:
 
@@ -661,6 +741,7 @@ Detailed records are preserved in per-phase history files:
 | 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)                 |
+| 12    | Complexity reduction and test fixture extraction    | Complete | [phase-12-complexity-test-fixtures.md](history/phase-12-complexity-test-fixtures.md) |
 
 ### Structural refactoring issues
 
@@ -677,6 +758,7 @@ Detailed records are preserved in per-phase history files:
 | 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                                                                                  |
+| Phase 13           | #214, #215, #216, #217, #218, #219                         | Closure-to-class, buildParentContext, startAgent decomp, overwrite guard, settings SDK, test duplication                                                 |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 
@@ -704,3 +786,9 @@ The upstream test suite is run periodically as a regression canary for the agent
 [#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
+[#214]: https://github.com/gotgenes/pi-packages/issues/214
+[#215]: https://github.com/gotgenes/pi-packages/issues/215
+[#216]: https://github.com/gotgenes/pi-packages/issues/216
+[#217]: https://github.com/gotgenes/pi-packages/issues/217
+[#218]: https://github.com/gotgenes/pi-packages/issues/218
+[#219]: https://github.com/gotgenes/pi-packages/issues/219

package/docs/architecture/history/phase-12-complexity-test-fixtures.md

@@ -0,0 +1,55 @@
+# Phase 12: Complexity reduction and test fixture extraction
+
+## Summary
+
+Phase 12 decomposed the three remaining high-complexity UI functions and extracted shared test fixtures into `test/helpers/`.
+
+## Steps
+
+### Step 1: Decompose `renderWidgetLines` (cognitive 44) — [#205]
+
+`renderWidgetLines` in `ui/widget-renderer.ts` handled agent-status formatting, tree connectors, overflow, and empty states.
+Extracted per-status renderers and a tree-connector utility.
+
+- Target: `src/ui/widget-renderer.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 2: Decompose `showAgentDetail` (cognitive 33) — [#206]
+
+`showAgentDetail` in `ui/agent-config-editor.ts` handled display, edit, eject, and delete flows.
+Extracted 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) — [#207]
+
+`update` mixed timer lifecycle, agent list assembly, render delegation, and visibility state.
+Extracted `assembleWidgetState` (pure) and timer management.
+
+- Target: `src/ui/agent-widget.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 4: Extract shared test fixtures — [#208]
+
+The 3 heaviest clone families:
+
+- `agent-runner.test.ts` + `agent-runner-extension-tools.test.ts` (60-line shared setup)
+- `agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts` (54+51+24 lines)
+- `agent-manager.test.ts` (18 internal clone groups, 210 duplicated lines)
+
+Extracted shared factories into `test/helpers/runner-io.ts` and `test/helpers/ui-stubs.ts`.
+Test duplication reduced from 71 clone groups (1,424 lines) to 59 clone groups (1,046 lines).
+
+## Metrics change
+
+| Metric                     | Before                 | After                  |
+| -------------------------- | ---------------------- | ---------------------- |
+| Health score               | 75/100 (B)             | 78/100 (B)             |
+| Fallow refactoring targets | 4                      | 1                      |
+| Test duplication           | 71 groups, 1,424 lines | 59 groups, 1,046 lines |
+
+[#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/plans/0214-convert-remaining-closure-factories-to-classes.md

@@ -0,0 +1,261 @@
+---
+issue: 214
+issue_title: "Convert remaining closure factories to classes (Phase 13, Step 1)"
+---
+
+# Convert remaining closure factories to classes
+
+## Problem Statement
+
+Three closure factories survived Phase 11 — each captures dependencies in closure scope and returns a method bag, the exact pattern Phase 11 eliminated elsewhere.
+Converting them to classes makes dependencies explicit as constructor parameters and aligns with the class-based pattern established in Phase 11.
+
+## Goals
+
+- Convert `createAgentConfigEditor()` to an `AgentConfigEditor` class.
+- Convert `createAgentCreationWizard()` to an `AgentCreationWizard` class.
+- Convert `createSubagentsService()` to a `SubagentsServiceAdapter` class implementing `SubagentsService`.
+- Remove the `AgentCreationWizardDeps` interface (the class constructor replaces it).
+- Update `AgentsMenuHandler` to store typed class instances instead of `ReturnType<typeof ...>`.
+- Update `index.ts` to construct `SubagentsServiceAdapter` with `new`.
+- 0 remaining closure factories (excluding pure-function factories like `createNotificationRenderer`).
+
+## Non-Goals
+
+- Changing any behavior — all conversions are purely structural.
+- Extracting the shared overwrite guard between `AgentConfigEditor` and `AgentCreationWizard` — that is #218.
+- Reducing test duplication in `agent-config-editor.test.ts` — that is #219.
+- Decomposing `buildParentContext` or `startAgent` — those are #215 and #216.
+- Modifying `createNotificationRenderer()` — it returns a pure render function with no captured state.
+
+## Background
+
+### Phase 11 precedent
+
+Phase 11 converted all closure factories in tools, runner, and menu layers to classes.
+Issues #195 and #196 established the pattern:
+
+- Closure-captured deps become constructor parameters stored as `private readonly` fields.
+- Nested functions become private methods.
+- Consumer call sites change from `createFoo(deps)` to `new Foo(deps)`.
+- Tests update `makeXxx()` helpers to use `new` instead of calling the factory.
+
+### Current state
+
+| Factory                       | File                          | Captures                                 | Returns                                     |
+| ----------------------------- | ----------------------------- | ---------------------------------------- | ------------------------------------------- |
+| `createAgentConfigEditor()`   | `ui/agent-config-editor.ts`   | `fileOps`, `registry`, 2 dirs            | `{ showAgentDetail }` (7 nested async fns)  |
+| `createAgentCreationWizard()` | `ui/agent-creation-wizard.ts` | `fileOps`, `manager`, `registry`, 2 dirs | `{ showCreateWizard }` (3 nested async fns) |
+| `createSubagentsService()`    | `service/service-adapter.ts`  | `manager`, `resolveModel`, `runtime`     | 7-method `SubagentsService`                 |
+
+### Consumer sites
+
+- `AgentsMenuHandler` (in `agent-menu.ts`) constructs both UI factories in its constructor and stores them as `private readonly` fields typed as `ReturnType<typeof createAgentConfigEditor>` and `ReturnType<typeof createAgentCreationWizard>`.
+- `index.ts` calls `createSubagentsService(manager, resolveModel, runtime)` and passes the result to `publishSubagentsService`.
+
+### Structural typing
+
+`AgentCreationWizardDeps` is only used within `agent-creation-wizard.ts` — no external imports.
+The class constructor replaces the deps interface entirely.
+
+## Design Overview
+
+### AgentConfigEditor
+
+Deps become positional constructor parameters (matching the factory's positional signature):
+
+```typescript
+export class AgentConfigEditor {
+  constructor(
+    private readonly fileOps: AgentFileOps,
+    private readonly registry: AgentTypeRegistry,
+    private readonly personalAgentsDir: string,
+    private readonly projectAgentsDir: string,
+  ) {}
+
+  private agentDirs(): string[] { ... }
+  async showAgentDetail(ui: MenuUI, name: string): Promise<void> { ... }
+  private async handleEdit(ui: MenuUI, name: string, file: string): Promise<void> { ... }
+  private async handleDelete(ui: MenuUI, name: string, file: string): Promise<void> { ... }
+  private async handleReset(ui: MenuUI, name: string, file: string): Promise<void> { ... }
+  private async ejectAgent(ui: MenuUI, name: string, cfg: AgentConfig): Promise<void> { ... }
+  private async disableAgent(ui: MenuUI, name: string): Promise<void> { ... }
+  private async enableAgent(ui: MenuUI, name: string): Promise<void> { ... }
+}
+```
+
+The pure helper functions `buildMenuOptions` and `buildEjectContent` remain as exported free functions — they have no captured state and their tests exercise them independently.
+
+### AgentCreationWizard
+
+Deps become positional constructor parameters (dissolving `AgentCreationWizardDeps`):
+
+```typescript
+export class AgentCreationWizard {
+  constructor(
+    private readonly fileOps: AgentFileOps,
+    private readonly manager: WizardManager,
+    private readonly registry: WizardRegistry,
+    private readonly personalAgentsDir: string,
+    private readonly projectAgentsDir: string,
+  ) {}
+
+  async showCreateWizard(ui: MenuUI, parentSnapshot: ParentSnapshot): Promise<void> { ... }
+  private async showGenerateWizard(ui: MenuUI, parentSnapshot: ParentSnapshot, targetDir: string): Promise<void> { ... }
+  private async showManualWizard(ui: MenuUI, targetDir: string): Promise<void> { ... }
+}
+```
+
+`WizardManager` and `WizardRegistry` interfaces remain exported — they define the narrow contracts for the class's collaborators.
+
+### SubagentsServiceAdapter
+
+The class implements `SubagentsService` directly:
+
+```typescript
+export class SubagentsServiceAdapter implements SubagentsService {
+  constructor(
+    private readonly manager: AgentManagerLike,
+    private readonly resolveModel: (input: string, registry: ModelRegistry) => unknown,
+    private readonly runtime: ServiceRuntimeLike,
+  ) {}
+
+  spawn(type: string, prompt: string, options?: SpawnOptions): string { ... }
+  getRecord(id: string): SubagentRecord | undefined { ... }
+  listAgents(): SubagentRecord[] { ... }
+  abort(id: string): boolean { ... }
+  async steer(id: string, message: string): Promise<boolean> { ... }
+  async waitForAll(): Promise<void> { ... }
+  hasRunning(): boolean { ... }
+}
+```
+
+`AgentManagerLike` and `ServiceRuntimeLike` interfaces remain exported — they define the narrow contracts.
+The `toSubagentRecord` helper remains an exported free function — it is pure and tested independently.
+
+### AgentsMenuHandler updates
+
+The `editor` and `wizard` fields change from `ReturnType<typeof ...>` to the concrete class types:
+
+```typescript
+private readonly editor: AgentConfigEditor;
+private readonly wizard: AgentCreationWizard;
+```
+
+Construction changes from `createAgentConfigEditor(...)` to `new AgentConfigEditor(...)` and from `createAgentCreationWizard({...})` to `new AgentCreationWizard(...)`.
+
+## Module-Level Changes
+
+### `src/ui/agent-config-editor.ts`
+
+- Replace `createAgentConfigEditor` factory function with `AgentConfigEditor` class.
+- `agentDirs()` becomes a private method.
+- `showAgentDetail`, `handleEdit`, `handleDelete`, `handleReset`, `ejectAgent`, `disableAgent`, `enableAgent` become class methods (`showAgentDetail` is public, rest are private).
+- `buildMenuOptions` and `buildEjectContent` remain as exported free functions.
+
+### `src/ui/agent-creation-wizard.ts`
+
+- Replace `createAgentCreationWizard` factory function with `AgentCreationWizard` class.
+- Remove `AgentCreationWizardDeps` interface.
+- `showCreateWizard` becomes a public method; `showGenerateWizard` and `showManualWizard` become private methods.
+- `WizardManager` and `WizardRegistry` interfaces remain exported.
+
+### `src/service/service-adapter.ts`
+
+- Replace `createSubagentsService` factory function with `SubagentsServiceAdapter` class implementing `SubagentsService`.
+- `AgentManagerLike` and `ServiceRuntimeLike` interfaces remain exported.
+- `toSubagentRecord` remains an exported free function.
+- Add import for `SpawnOptions` from `#src/service/service` (needed for the `spawn` method signature).
+
+### `src/ui/agent-menu.ts`
+
+- Replace `ReturnType<typeof createAgentConfigEditor>` with `AgentConfigEditor`.
+- Replace `ReturnType<typeof createAgentCreationWizard>` with `AgentCreationWizard`.
+- Update constructor body: `new AgentConfigEditor(...)` instead of `createAgentConfigEditor(...)`.
+- Update constructor body: `new AgentCreationWizard(...)` instead of `createAgentCreationWizard({...})`.
+- Update imports: `AgentConfigEditor` instead of `createAgentConfigEditor`, `AgentCreationWizard` instead of `createAgentCreationWizard`.
+
+### `src/index.ts`
+
+- Replace `createSubagentsService(manager, resolveModel, runtime)` with `new SubagentsServiceAdapter(manager, resolveModel, runtime)`.
+- Update import: `SubagentsServiceAdapter` instead of `createSubagentsService`.
+
+### `docs/architecture/architecture.md`
+
+- Mark Step 1 of Phase 13 as complete.
+- Update the factory table to show conversions done.
+
+## Test Impact Analysis
+
+### `test/ui/agent-config-editor.test.ts`
+
+- Update `makeEditor()` helper: replace `createAgentConfigEditor(...)` with `new AgentConfigEditor(...)`.
+- Update import: `AgentConfigEditor` instead of `createAgentConfigEditor`.
+- No test logic changes — all existing assertions remain valid.
+- The `makeEditor()` helper centralizes the factory call, so only 1 line changes.
+
+### `test/ui/agent-creation-wizard.test.ts`
+
+- Replace all `createAgentCreationWizard(deps)` calls with `new AgentCreationWizard(deps.fileOps, deps.manager, deps.registry, deps.personalAgentsDir, deps.projectAgentsDir)`.
+- Update import: `AgentCreationWizard` instead of `createAgentCreationWizard`.
+- This file has ~18 call sites that each construct the wizard inline; each changes from `createAgentCreationWizard(deps)` to `new AgentCreationWizard(deps.fileOps, deps.manager, deps.registry, deps.personalAgentsDir, deps.projectAgentsDir)`.
+- Alternatively, add a `makeWizard(deps)` helper to centralize construction, then each call site becomes `makeWizard(deps)`.
+- No test logic changes.
+
+### `test/service/service-adapter.test.ts`
+
+- Replace all `createSubagentsService(manager, resolveModel, runtime)` calls with `new SubagentsServiceAdapter(manager, resolveModel, runtime)`.
+- Update import: `SubagentsServiceAdapter` instead of `createSubagentsService`.
+- ~12 call sites change; each is a mechanical find-and-replace.
+- Update `describe` block names from `createSubagentsService —` to `SubagentsServiceAdapter —`.
+- No test logic changes.
+
+### No new tests needed
+
+The conversions are structural — existing tests fully cover all behavior.
+Adding "verify it's a class" tests would test the language, not the code.
+
+## TDD Order
+
+1. **Convert `createAgentConfigEditor` to `AgentConfigEditor` class.**
+   Replace factory with class in `agent-config-editor.ts`.
+   Update `makeEditor()` in `agent-config-editor.test.ts`.
+   Update `agent-menu.ts` field types and constructor.
+   Remove factory function.
+   Verify: `pnpm vitest run test/ui/agent-config-editor.test.ts` and `pnpm run check`.
+   `refactor: convert createAgentConfigEditor to AgentConfigEditor class`
+
+2. **Convert `createAgentCreationWizard` to `AgentCreationWizard` class.**
+   Replace factory with class in `agent-creation-wizard.ts`.
+   Remove `AgentCreationWizardDeps` interface.
+   Update all call sites in `agent-creation-wizard.test.ts` (add `makeWizard` helper to centralize construction).
+   Update `agent-menu.ts` field type and constructor.
+   Remove factory function.
+   Verify: `pnpm vitest run test/ui/agent-creation-wizard.test.ts` and `pnpm run check`.
+   `refactor: convert createAgentCreationWizard to AgentCreationWizard class`
+
+3. **Convert `createSubagentsService` to `SubagentsServiceAdapter` class.**
+   Replace factory with class in `service-adapter.ts`.
+   Update all call sites in `service-adapter.test.ts`.
+   Update `describe` block names.
+   Update `index.ts` import and construction.
+   Remove factory function.
+   Verify: `pnpm vitest run test/service/service-adapter.test.ts` and `pnpm run check`.
+   `refactor: convert createSubagentsService to SubagentsServiceAdapter class`
+
+4. **Update architecture doc.**
+   Mark Phase 13 Step 1 as complete in `docs/architecture/architecture.md`.
+   `docs: mark Phase 13 Step 1 complete`
+
+## Risks and Mitigations
+
+| Risk                                                                           | Mitigation                                                                                                            |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `AgentCreationWizard` test has ~18 inline factory calls that all need updating | Add a `makeWizard(deps)` test helper to centralize construction — same pattern used in `agent-config-editor.test.ts`. |
+| `SubagentsServiceAdapter` class might not satisfy `SubagentsService` interface | The class uses `implements SubagentsService`, so `pnpm run check` catches any mismatches at compile time.             |
+| Spreading a class instance in tests produces a plain object lacking methods    | Not applicable — none of the test files spread factory results. Tests call methods directly on the returned object.   |
+| `AgentCreationWizardDeps` removal might break external consumers               | Verified: the interface is only used within `agent-creation-wizard.ts` itself. No external imports.                   |
+
+## Open Questions
+
+None — the conversions are mechanical and follow the established Phase 11 pattern.