@gotgenes/pi-subagents 7.3.0 → 7.3.2

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

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

package/docs/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.

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

@@ -54,3 +54,39 @@ Test count went from 868 to 884 (+16 tests across 55 files, up from 54).
 - The complexity hotspots table in `architecture.md` now has no rows (both `renderWidgetLines` from #205 and `update` from this issue are resolved).
   The section note was updated to reflect that Phase 12 cleared all critical hotspots.
 - `pnpm fallow dead-code` (from repo root) passed with no issues.
+
+## Stage: Final Retrospective (2026-05-25T13:15:00Z)
+
+### Session summary
+
+Issue #207 shipped as `pi-subagents-v7.3.0` with zero deviations from the revised plan.
+The session covered plan revision, TDD implementation (16 new tests, 868 → 884), shipping, and CI verification.
+
+### Observations
+
+#### What went well
+
+- The plan revision caught three real design issues before implementation started: ISP violation in the function parameter type, incorrect `dispose` → `clearWidget` delegation, and missing complexity budget.
+  Fixing these upfront meant the TDD execution had zero deviations and zero rework.
+- The narrow `AgentSummary` type (3 fields) made test fixtures trivial plain objects — no `createTestRecord` or factory infrastructure needed.
+  This validated the ISP improvement concretely.
+- The `dispose` independence decision (Sandi Metz principle applied to lifecycle semantics) kept `dispose` at its current 10-line simplicity while `clearWidget` got its own guarded teardown logic.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The original planning session (prior to this one) used `WidgetAgent[]` as the input type without checking which fields `assembleWidgetState` actually reads.
+  The `code-design` skill already says "do not pass a shared dependency bag to functions that only use a subset of it" but the principle wasn't applied to the proposed function signature.
+  Impact: required a full plan revision session; no rework in implementation because it was caught before TDD started.
+- `wrong-abstraction` — The original plan proposed `dispose` → `clearWidget` delegation as "eliminating duplication" without evaluating whether the two methods have the same lifecycle semantics.
+  `dispose` uses unconditional teardown (shutdown correctness); `clearWidget` uses guarded calls (avoiding redundant SDK calls during repeated timer ticks).
+  Impact: same as above — caught in revision, no implementation rework.
+
+#### What caused friction (user side)
+
+- The user's "I don't yet trust the plan" intervention was the key moment that improved the design.
+  Without it, the plan would have been implemented with the wider type and the `dispose` delegation.
+  This was effective judgment — the user identified that a mechanical plan for a mechanical refactoring still warranted critical design review.
+
+### Changes made
+
+1. Added two sentences to `.pi/prompts/plan-issue.md` Design Overview section: ISP check for new function parameter types, and structural-duplication check when consolidating methods into a shared helper.