@gotgenes/pi-subagents 7.2.4 → 7.2.6

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.2.6](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.5...pi-subagents-v7.2.6) (2026-05-25)
+
+
+### Documentation
+
+* archive Phase 11 to history, add Phase 11 to refactoring table ([2c617f2](https://github.com/gotgenes/pi-packages/commit/2c617f2c752ea935d55878ba58fce997985086b5))
+* plan decompose renderWidgetLines ([#205](https://github.com/gotgenes/pi-packages/issues/205)) ([88d09cd](https://github.com/gotgenes/pi-packages/commit/88d09cdad53bc3f215c069b8d6da6a44e10b5af7))
+* **retro:** add planning stage notes for issue [#205](https://github.com/gotgenes/pi-packages/issues/205) ([14afc1f](https://github.com/gotgenes/pi-packages/commit/14afc1ff82d61828fdac9373f31cb68ebfc1a2e7))
+* **retro:** add retro notes for issue [#196](https://github.com/gotgenes/pi-packages/issues/196) ([cfc7d94](https://github.com/gotgenes/pi-packages/commit/cfc7d94f72b120a4550f73e2d1cf00822db759c2))
+* **retro:** add TDD stage notes for issue [#205](https://github.com/gotgenes/pi-packages/issues/205) ([a676078](https://github.com/gotgenes/pi-packages/commit/a6760789898435e5b552941124de6f32be21407e))
+
+## [7.2.5](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.4...pi-subagents-v7.2.5) (2026-05-25)
+
+
+### Documentation
+
+* mark Phase 11 Layer 3 and Layer 4 complete ([bf71795](https://github.com/gotgenes/pi-packages/commit/bf71795649a5b3c14a2b3ff16b2109d131a0ed32))
+* plan convert AgentRunner and AgentsMenuHandler to classes ([#196](https://github.com/gotgenes/pi-packages/issues/196)) ([cd0bd1f](https://github.com/gotgenes/pi-packages/commit/cd0bd1fdec0c87655bdb38f8243084df807b676a))
+* **retro:** add planning stage notes for issue [#196](https://github.com/gotgenes/pi-packages/issues/196) ([677d4bf](https://github.com/gotgenes/pi-packages/commit/677d4bf6619f13eba8d17181efab04cc67e47bbd))
+* **retro:** add TDD stage notes for issue [#196](https://github.com/gotgenes/pi-packages/issues/196) ([72d24ba](https://github.com/gotgenes/pi-packages/commit/72d24ba56b8dc7668ff350ad3f0ba027b996d26e))
+
 ## [7.2.4](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.3...pi-subagents-v7.2.4) (2026-05-25)
 
 

package/docs/architecture/architecture.md

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

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

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

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

@@ -0,0 +1,268 @@
+---
+issue: 196
+issue_title: "Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts"
+---
+
+# Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts
+
+## Problem Statement
+
+Two remaining closure factories in pi-subagents mask class-shaped code:
+
+1. `createAgentRunner(runnerIO)` captures `RunnerIO` and returns `{ run, resume }` — the `AgentRunner` interface already exists but lacks a concrete class implementation.
+2. `createAgentsMenuHandler({...})` captures an 8-field deps object and returns a handler function.
+
+With #195 (tool factory → class conversions) complete, these are the last two closure factories.
+After converting them, `index.ts` can be simplified: adapter closures drop, fan-out decreases, and the composition root becomes pure object construction.
+
+## Goals
+
+- Convert `createAgentRunner` factory to a concrete `ConcreteAgentRunner` class implementing `AgentRunner`.
+- Convert `createAgentsMenuHandler` factory to an `AgentsMenuHandler` class.
+- Internalize the `getModelLabel` closure from `index.ts` into `AgentsMenuHandler` (it uses `resolveModel` and `getModelLabelFromConfig`, both pure functions the class can import directly).
+- Pass `AgentManager` directly as the `manager` param (it structurally satisfies `AgentMenuManager`), eliminating 3 adapter closures.
+- Simplify `index.ts` by removing eliminated adapter closures and unused imports.
+- Update architecture doc to mark Layer 3 and Layer 4 as done.
+
+## Non-Goals
+
+- Changing `runAgent()` or `resumeAgent()` function signatures — they remain as free functions called by the class.
+- Removing the `AgentRunner` interface — it stays as the contract for `AgentManager`.
+- Removing `RunnerIO` type — it stays as the IO boundary for `runAgent()`.
+- Changing the `AgentMenuManager` interface — it stays as the narrow contract; `AgentManager` satisfies it structurally.
+- Removing `AgentMenuDeps` — it is replaced by the class constructor; the type itself is removed.
+- Refactoring `NotificationManager`, `SettingsManager`, or `SessionLifecycleHandler` — those are already class-shaped.
+- Phase 12 work (decompose `renderWidgetLines`, consolidate test duplication).
+
+## Background
+
+### Phase 11 layer structure
+
+Phase 11 in `docs/architecture/architecture.md` converts closure factories to classes in four layers:
+
+- Layer 0: `SessionContext` interface (#192) ✓
+- Layer 1: Runtime owns context queries (#193) ✓
+- Layer 2: Align interfaces for structural typing (#194) ✓
+- Layer 3: Convert closure factories to classes (#195 tools ✓, #196 runner + menu)
+- Layer 4: Simplify `index.ts` (#196)
+
+Issue #196 completes Layer 3 (runner + menu) and Layer 4 (index.ts simplification).
+
+### Current state
+
+`createAgentRunner` (3 lines) wraps `runAgent`/`resumeAgent` in an object literal:
+
+```typescript
+export function createAgentRunner(io: RunnerIO): AgentRunner {
+  return {
+    run: (snapshot, type, prompt, options) => runAgent(snapshot, type, prompt, options, io),
+    resume: resumeAgent,
+  };
+}
+```
+
+`createAgentsMenuHandler` (200+ lines) captures 8 deps and returns a handler function.
+The deps bag includes `getModelLabel` (a closure built in `index.ts`) and `agentActivity` (a `Map` from runtime).
+
+`index.ts` currently has ~23 arrow closures and 27 imports at 229 lines.
+
+### Structural typing confirmation
+
+`AgentManager` already has `listAgents()`, `getRecord()`, and `spawnAndWait()` methods that structurally satisfy `AgentMenuManager`.
+The `spawnAndWait` parameter type (`Omit<AgentSpawnConfig, "isBackground">`) is a superset of the menu's `{ description, maxTurns }`, so structural typing matches.
+
+## Design Overview
+
+### ConcreteAgentRunner
+
+A minimal class that implements `AgentRunner` by delegating to the free functions:
+
+```typescript
+export class ConcreteAgentRunner implements AgentRunner {
+  constructor(private readonly io: RunnerIO) {}
+
+  async run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult> {
+    return runAgent(snapshot, type, prompt, options, this.io);
+  }
+
+  async resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string> {
+    return resumeAgent(session, prompt, options);
+  }
+}
+```
+
+The factory function `createAgentRunner` is removed.
+The free functions `runAgent`, `resumeAgent`, `getAgentConversation`, and `normalizeMaxTurns` remain exported — they are used directly by tests and other modules.
+
+### AgentsMenuHandler
+
+The class replaces `createAgentsMenuHandler` and `AgentMenuDeps`.
+Constructor params are the subset of deps that are true collaborators:
+
+```typescript
+export class AgentsMenuHandler {
+  constructor(
+    private readonly manager: AgentMenuManager,
+    private readonly registry: AgentTypeRegistry,
+    private readonly agentActivity: AgentActivityReader,
+    private readonly settings: AgentMenuSettings,
+    private readonly fileOps: AgentFileOps,
+    private readonly personalAgentsDir: string,
+    private readonly projectAgentsDir: string,
+  ) {}
+
+  async handle(ctx: { ui: MenuUI; modelRegistry: ModelRegistry; parentSnapshot: ParentSnapshot }): Promise<void> { ... }
+}
+```
+
+Key design decisions:
+
+1. **`agentActivity` stays as a constructor param** — it is a collaborator used in `viewAgentConversation`.
+   The issue's proposed signature omits it, but the class needs it at runtime.
+2. **`getModelLabel` is internalized** — the class imports `resolveModel` and `getModelLabelFromConfig` directly and computes the label in a private method.
+   This eliminates the closure from `index.ts` and removes the `getModelLabel` field from the deps interface.
+3. **`AgentMenuDeps` is removed** — the class constructor replaces it.
+4. **The `handle` method** replaces the returned function.
+   The inner helpers (`showAgentsMenu`, `showAllAgentsList`, etc.) become private methods.
+
+### index.ts simplification
+
+After both conversions:
+
+```typescript
+// Before (adapter closures):
+const agentsMenuHandler = createAgentsMenuHandler({
+  manager: {
+    listAgents: () => manager.listAgents(),
+    getRecord: (id) => manager.getRecord(id),
+    spawnAndWait: (...) => manager.spawnAndWait(...),
+  },
+  registry,
+  agentActivity: runtime.agentActivity,
+  getModelLabel: (type, modelRegistry) => { ... },  // 7-line closure
+  settings,
+  fileOps: new FsAgentFileOps(),
+  personalAgentsDir: join(getAgentDir(), 'agents'),
+  projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
+});
+
+// After:
+const agentsMenu = new AgentsMenuHandler(
+  manager, registry, runtime.agentActivity,
+  settings, new FsAgentFileOps(),
+  join(getAgentDir(), 'agents'),
+  join(process.cwd(), '.pi', 'agents'),
+);
+```
+
+Eliminated closures: 4 (3 manager method adapters + 1 getModelLabel closure).
+Eliminated imports: `getModelLabelFromConfig`, `resolveModel` (from index.ts), `createAgentRunner`, `type RunnerIO`, `createAgentsMenuHandler`.
+
+Remaining adapter closures in `index.ts` (~15) are necessary: event handler registrations, SDK factory callbacks, `pi.sendMessage`/`pi.exec` adapters.
+These are structural — they bridge the Pi SDK's callback-based API to the extension's object-oriented internals.
+
+## Module-Level Changes
+
+### `src/lifecycle/agent-runner.ts`
+
+- Add `ConcreteAgentRunner` class implementing `AgentRunner`.
+- Remove `createAgentRunner` factory function.
+- Keep all free functions (`runAgent`, `resumeAgent`, `getAgentConversation`, `normalizeMaxTurns`) and all types exported.
+
+### `src/ui/agent-menu.ts`
+
+- Replace `createAgentsMenuHandler` factory with `AgentsMenuHandler` class.
+- Remove `AgentMenuDeps` interface.
+- Add private `getModelLabel` method (internalizes the closure from `index.ts`).
+- Convert inner functions (`showAgentsMenu`, `showAllAgentsList`, `showRunningAgents`, `viewAgentConversation`, `showSettings`) to private methods.
+- Add imports: `resolveModel` from `#src/session/model-resolver`, `getModelLabelFromConfig` from `#src/tools/helpers`.
+- Keep exported interfaces: `AgentMenuManager`, `AgentMenuSettings`, `AgentActivityReader`, `MenuUI`.
+
+### `src/index.ts`
+
+- Replace `createAgentRunner(runnerIO)` with `new ConcreteAgentRunner(runnerIO)`.
+- Replace `createAgentsMenuHandler({...})` with `new AgentsMenuHandler(...)`.
+- Replace `agentsMenuHandler({...})` with `agentsMenu.handle({...})`.
+- Remove adapter closures for `manager.listAgents`, `manager.getRecord`, `manager.spawnAndWait`, and `getModelLabel`.
+- Remove unused imports: `createAgentRunner`, `type RunnerIO` → `ConcreteAgentRunner`; `createAgentsMenuHandler` → `AgentsMenuHandler`; `getModelLabelFromConfig`, `resolveModel`.
+- Net effect: ~15 lines removed, 5 imports removed.
+
+### `docs/architecture/architecture.md`
+
+- Mark Layer 3 remaining items (runner, menu) as done.
+- Mark Layer 4 as done.
+- Update the factory→class table entries for `createAgentRunner` and `createAgentsMenuHandler` with ✓.
+
+## Test Impact Analysis
+
+### `test/lifecycle/agent-runner.test.ts` (and siblings)
+
+No changes needed.
+Tests call `runAgent()` and `resumeAgent()` directly — they never use `createAgentRunner`.
+The `ConcreteAgentRunner` class is a trivial two-method delegation wrapper tested implicitly through `index.ts` integration and explicitly through one new unit test.
+
+### `test/ui/agent-menu.test.ts`
+
+Tests need updating:
+
+1. Replace `createAgentsMenuHandler(makeDeps())` with `new AgentsMenuHandler(...)`.
+2. Replace `handler(params)` with `handler.handle(params)`.
+3. Remove `getModelLabel` from `makeDeps()` — it is now an internal method.
+4. Remove `AgentMenuDeps` import; update `makeDeps` to construct positional args or a helper that returns a handler directly.
+
+No test logic changes — only call-site updates for the new API shape.
+
+### New tests
+
+One new unit test for `ConcreteAgentRunner`: verify it delegates `run` and `resume` to the underlying functions.
+
+## TDD Order
+
+1. **Add `ConcreteAgentRunner` class alongside factory.**
+   Add the class to `agent-runner.ts`, keep `createAgentRunner` temporarily.
+   Add a unit test verifying delegation.
+   `test: add ConcreteAgentRunner delegation test`
+
+2. **Switch `index.ts` to `ConcreteAgentRunner`, remove factory.**
+   Replace `createAgentRunner(runnerIO)` with `new ConcreteAgentRunner(runnerIO)`.
+   Remove the `createAgentRunner` factory function.
+   Update imports.
+   `refactor: replace createAgentRunner with ConcreteAgentRunner class`
+
+3. **Convert `createAgentsMenuHandler` to `AgentsMenuHandler` class.**
+   Replace factory function with class.
+   Move inner functions to private methods.
+   Internalize `getModelLabel` as a private method.
+   Remove `AgentMenuDeps` interface.
+   `refactor: convert createAgentsMenuHandler to AgentsMenuHandler class`
+
+4. **Update `agent-menu.test.ts` for class API.**
+   Replace `createAgentsMenuHandler(makeDeps())` with class construction.
+   Replace `handler(params)` with `handler.handle(params)`.
+   Remove `getModelLabel` from test deps.
+   All existing tests pass with updated call sites.
+   `test: update agent-menu tests for AgentsMenuHandler class`
+
+5. **Simplify `index.ts` wiring.**
+   Replace `createAgentsMenuHandler({...})` with `new AgentsMenuHandler(...)`.
+   Pass `manager` directly (structural typing).
+   Remove adapter closures and unused imports.
+   `refactor: simplify index.ts wiring for AgentsMenuHandler`
+
+6. **Update architecture doc.**
+   Mark Layer 3 remaining items and Layer 4 as done in `docs/architecture/architecture.md`.
+   `docs: mark Phase 11 Layer 3 and Layer 4 complete`
+
+## Risks and Mitigations
+
+| Risk                                                             | Mitigation                                                                                                                     |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `AgentManager` might not structurally satisfy `AgentMenuManager` | Confirmed: `listAgents()`, `getRecord()`, `spawnAndWait()` signatures are compatible. `pnpm run check` in step 5 verifies.     |
+| Internalized `getModelLabel` might diverge from the closure      | The private method uses the same `resolveModel` and `getModelLabelFromConfig` imports — identical logic, just moved.           |
+| Tests that use `AgentMenuDeps` type break when removed           | Step 4 updates all test call sites before step 5 changes production code. The test file is 215 lines — manageable in one step. |
+| `agentActivity` missing from constructor                         | Included in the class constructor (diverging from the issue's proposed signature which omits it).                              |
+
+## Open Questions
+
+None — the issue's proposed design is clear and the implementation is mechanical.
+The one deviation (keeping `agentActivity` as a constructor param) is necessary and minimal.