@gotgenes/pi-subagents 6.12.0 → 6.13.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [6.13.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.12.1...pi-subagents-v6.13.0) (2026-05-23)
+
+
+### Features
+
+* add AgentFileOps interface and FsAgentFileOps ([#136](https://github.com/gotgenes/pi-packages/issues/136)) ([9625de6](https://github.com/gotgenes/pi-packages/commit/9625de60ace3cf58ad59c2d533f18fd7cdb8bba9))
+
+
+### Documentation
+
+* plan agent-menu decomposition ([#136](https://github.com/gotgenes/pi-packages/issues/136)) ([41ca6a6](https://github.com/gotgenes/pi-packages/commit/41ca6a6612cbc167a5b3d336ffb94d3f9666868f))
+* **retro:** add retro notes for issue [#135](https://github.com/gotgenes/pi-packages/issues/135) ([83e255b](https://github.com/gotgenes/pi-packages/commit/83e255b4a5e6a56a287c933e4a5fa0b28121529e))
+* update architecture for agent-menu decomposition ([#136](https://github.com/gotgenes/pi-packages/issues/136)) ([dba90e8](https://github.com/gotgenes/pi-packages/commit/dba90e86693e3480004a7c305d5082cb5a930d3f))
+
+## [6.12.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.12.0...pi-subagents-v6.12.1) (2026-05-22)
+
+
+### Documentation
+
+* mark Step J done, add ui/display.ts to module listing ([#135](https://github.com/gotgenes/pi-packages/issues/135)) ([37ced45](https://github.com/gotgenes/pi-packages/commit/37ced45e1a0287aa78e588cb8bc7905c0f969637))
+* plan display helper extraction from agent-widget ([#135](https://github.com/gotgenes/pi-packages/issues/135)) ([9e65e7d](https://github.com/gotgenes/pi-packages/commit/9e65e7d93bf47d4c4582d367d2f31a2386a5cc8c))
+* **retro:** add retro notes for issue [#134](https://github.com/gotgenes/pi-packages/issues/134) ([775ce99](https://github.com/gotgenes/pi-packages/commit/775ce99710153d4ebcf40f773eae21553c7f8a82))
+
 ## [6.12.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.11.0...pi-subagents-v6.12.0) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -68,6 +68,7 @@ notification.ts           — completion nudges, custom message renderer
 renderer.ts               — notification TUI component
 record-observer.ts        — session-event observer for record statistics
 
+ui/display.ts             — pure formatters, display helpers, and shared types (Theme, AgentDetails)
 ui/agent-widget.ts        — above-editor live status widget
 ui/agent-menu.ts          — /agents slash command menu
 ui/conversation-viewer.ts — scrollable session overlay
@@ -272,7 +273,10 @@ src/
 │   └── tool-start.ts         — tool_execution_start handler
 ├── notification.ts           — completion nudges, custom renderer
 ├── renderer.ts               — notification TUI component
-├── ui/agent-menu.ts          — /agents slash command menu
+├── ui/agent-menu.ts          — /agents slash command menu (orchestration, listing, settings)
+├── ui/agent-config-editor.ts — agent detail view (edit/delete/eject/disable/enable)
+├── ui/agent-creation-wizard.ts — agent creation (AI-generation and manual-form)
+├── ui/agent-file-ops.ts      — AgentFileOps interface + FsAgentFileOps implementation
 ├── service-adapter.ts        — SubagentsService implementation wrapping AgentManager
 └── (existing domain modules unchanged)
 ```
@@ -564,28 +568,23 @@ Production changes:
 
 Remaining 15 `as any` casts are: 8 menu-handler `ctx as any` (deferred — requires `AgentManager.spawn` to accept `ParentSnapshot` directly), 2 `print-mode.test.ts` (same ExtensionContext/API pattern), 2 private-field test access, 1 `createSession` SDK bridge in `index.ts`, 1 `foreground-runner.ts` `AgentToolResult<any>` detail, 1 `stub-ctx.ts` comment.
 
-### Step J: Extract display helpers (#135)
+### Step J: Extract display helpers (#135) ✓ done
 
-`agent-widget.ts` (600 lines) exports 11 helper functions and constants that are used by both the widget and the menu.
-Extract these into `ui/display.ts`:
+`ui/display.ts` now contains all pure formatters, display helpers, constants, and shared types (`Theme`, `AgentDetails`).
+`agent-widget.ts` dropped from 522 → ~340 lines.
+All consumer modules (menu, tools, renderer, conversation viewer) import from `ui/display.ts` directly.
+`test/agent-widget.test.ts` renamed to `test/display.test.ts`.
 
-- Pure formatters: `formatTokens`, `formatSessionTokens`, `formatTurns`, `formatMs`, `formatDuration`.
-- Display helpers: `getDisplayName`, `getPromptModeLabel`, `buildInvocationTags`, `describeActivity`.
-- Constants: `SPINNER`, `ERROR_STATUSES`, `TOOL_DISPLAY`.
+### Step K: Decompose agent-menu.ts (#136) ✅
 
-Impact: `agent-widget.ts` drops from 600 → ~420 lines; shared display logic has a single import point; menu and tool modules stop importing from the widget.
+`agent-menu.ts` (668 lines) decomposed into four modules:
 
-### Step K: Decompose agent-menu.ts (#136)
+1. `ui/agent-file-ops.ts` — `AgentFileOps` interface (`exists`, `read`, `write`, `remove`, `ensureDir`, `findAgentFile`) + `FsAgentFileOps` production implementation.
+2. `ui/agent-config-editor.ts` — `showAgentDetail` with edit/delete/reset/eject/disable/enable transitions (~200 lines).
+3. `ui/agent-creation-wizard.ts` — AI-generation and manual-form creation paths (~250 lines).
+4. `ui/agent-menu.ts` — menu orchestration, agent listing, running-agent viewer, settings form (~300 lines).
 
-`agent-menu.ts` (650 lines) has 8 distinct responsibilities: menu FSM, agent listing, config editing, agent ejection, two creation wizards, running-agent viewer, and settings form.
-Filesystem operations (read/write/delete agent `.md` files) are scattered throughout.
-
-1. Extract `AgentFileOps` interface — `read`, `write`, `delete`, `findAgentFile` — abstracting the fs calls.
-2. Extract `ui/agent-config-editor.ts` — `showAgentDetail` with enable/disable/reset/delete transitions.
-3. Extract `ui/agent-creation-wizard.ts` — both AI-generation and manual form paths.
-4. Leave menu orchestration, settings form, and running-agent viewer in `agent-menu.ts` (~200 lines).
-
-Impact: `agent-menu.ts` drops from 650 → ~200 lines; extracted modules receive `AgentFileOps` via injection; wizard logic becomes independently testable.
+Impact: `agent-menu.ts` dropped from 668 → 296 lines; extracted modules receive `AgentFileOps` via injection; `vi.mock("node:fs")` eliminated from `agent-menu.test.ts`.
 
 ### Step dependencies
 

package/docs/plans/0135-extract-display-helpers.md

@@ -0,0 +1,182 @@
+---
+issue: 135
+issue_title: "Extract display helpers from `agent-widget.ts`"
+---
+
+# Extract display helpers from agent-widget.ts
+
+## Problem Statement
+
+`agent-widget.ts` (522 lines) exports 11 helper functions and constants that are general-purpose display utilities with no dependency on the widget's lifecycle or state.
+Six other source modules (`agent-menu.ts`, `conversation-viewer.ts`, `renderer.ts`, `agent-tool.ts`, `foreground-runner.ts`, `get-result-tool.ts`) and two tool support modules (`helpers.ts`, `background-spawner.ts`) import formatting functions or display types from the widget — creating a false dependency on a lifecycle-heavy UI module.
+
+This is Phase 8, Step J of the architecture plan.
+
+## Goals
+
+- Extract pure formatters, display helpers, constants, and associated types into `ui/display.ts`.
+- Update all import sites to import from `ui/display.ts` instead of `ui/agent-widget.ts`.
+- Reduce `agent-widget.ts` to only the `AgentWidget` class and its immediate dependencies (`UICtx`, private helpers).
+- Unblock Step K (menu decomposition, #136) — extracted menu sub-modules will import display helpers without pulling in the widget.
+
+## Non-Goals
+
+- Decomposing `agent-menu.ts` — deferred to #136 (Step K).
+- Changing any runtime behavior or public API.
+- Extracting `UICtx` — it is a widget-lifecycle type used only by `AgentWidget`, `runtime.ts`, and `index.ts`.
+
+## Background
+
+The architecture doc (Phase 8 roadmap, Step J) prescribes exactly which symbols to extract.
+The `code-design` skill's "Helpers stay in the file" rule applies: these helpers have accumulated to the point where they warrant their own module and tests.
+AGENTS.md's "one concern per file" constraint also supports the extraction.
+
+### Symbols to extract
+
+#### Pure formatters (zero runtime dependencies)
+
+1. `formatTokens(count)` — compact token count ("33.8k token").
+2. `formatSessionTokens(tokens, percent, theme, compactions)` — annotated token string with threshold colors.
+3. `formatTurns(turnCount, maxTurns)` — turn counter with optional limit.
+4. `formatMs(ms)` — milliseconds → "1.2s".
+5. `formatDuration(startedAt, completedAt)` — timestamp pair → human duration.
+
+#### Display helpers (registry lookup only)
+
+6. `getDisplayName(type, registry)` — resolved display name for an agent type.
+7. `getPromptModeLabel(type, registry)` — "twin" for append mode, undefined otherwise.
+8. `buildInvocationTags(invocation)` — config tags array from invocation options.
+9. `describeActivity(activeTools, responseText)` — human-readable activity string.
+
+#### Constants
+
+10. `SPINNER` — braille spinner frames.
+11. `ERROR_STATUSES` — set of error/non-success status strings.
+12. `TOOL_DISPLAY` — tool name → action verb mapping (private, moves with `describeActivity`).
+
+#### Types
+
+13. `Theme` — used in `formatSessionTokens` signature; must co-locate.
+14. `AgentDetails` — display metadata interface used by tools; no widget dependency.
+
+`UICtx` stays in `agent-widget.ts` — it defines the widget's host contract and is only consumed by the widget class, `runtime.ts`, and `index.ts`.
+
+### Current import graph (agent-widget.ts consumers)
+
+| Consumer                           | Symbols imported                                                                                                                    |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `ui/conversation-viewer.ts`        | `buildInvocationTags`, `describeActivity`, `formatDuration`, `formatSessionTokens`, `getDisplayName`, `getPromptModeLabel`, `Theme` |
+| `ui/agent-menu.ts`                 | `formatDuration`, `getDisplayName`                                                                                                  |
+| `tools/agent-tool.ts`              | `AgentDetails`, `buildInvocationTags`, `formatMs`, `formatTurns`, `getDisplayName`, `getPromptModeLabel`, `SPINNER`, `UICtx`        |
+| `tools/foreground-runner.ts`       | `AgentDetails`, `describeActivity`, `formatMs`, `SPINNER`                                                                           |
+| `tools/get-result-tool.ts`         | `formatDuration`, `getDisplayName`                                                                                                  |
+| `tools/helpers.ts`                 | `AgentDetails`, `formatTokens`                                                                                                      |
+| `tools/background-spawner.ts`      | `AgentDetails`                                                                                                                      |
+| `renderer.ts`                      | `formatMs`, `formatTokens`, `formatTurns`                                                                                           |
+| `runtime.ts`                       | `UICtx`                                                                                                                             |
+| `index.ts`                         | `AgentWidget`, `UICtx`                                                                                                              |
+| `test/agent-widget.test.ts`        | `formatSessionTokens`, `getDisplayName`, `getPromptModeLabel`                                                                       |
+| `test/conversation-viewer.test.ts` | `Theme`                                                                                                                             |
+
+### Post-extraction import graph
+
+After extraction, `ui/agent-widget.ts` imports `display.ts` for the symbols it still uses internally (e.g., `getDisplayName`, `formatMs`, `formatTurns`, `formatSessionTokens`, `ERROR_STATUSES`, `SPINNER`, `describeActivity`).
+All other consumers switch their imports from `./agent-widget.js` to `./display.js` (or `../ui/display.js` for `tools/` and `renderer.ts`).
+
+Only `index.ts` and `runtime.ts` continue to import from `agent-widget.ts` (for `AgentWidget` class and `UICtx` type).
+`tools/agent-tool.ts` splits its import: `UICtx` from `agent-widget.ts`, everything else from `display.ts`.
+
+## Design Overview
+
+This is a pure code-motion refactoring — no behavior changes.
+
+### New module: `ui/display.ts`
+
+Contains all 12 exported symbols (5 formatters, 4 display helpers, 3 constants) plus 2 types (`Theme`, `AgentDetails`) and 1 private helper (`truncateLine`, used by `describeActivity`).
+
+The module's only imports are:
+
+- `AgentConfigLookup` from `../agent-types.js` (type-only, for `getDisplayName`/`getPromptModeLabel`).
+- `SubagentType`, `AgentInvocation` from `../types.js` (type-only).
+
+No SDK imports, no runtime dependencies — exactly the kind of pure utility module the code-design skill prescribes.
+
+### Residual `agent-widget.ts`
+
+After extraction, `agent-widget.ts` contains:
+
+- `UICtx` type (widget host contract).
+- `AgentWidget` class (~340 lines) with its private helpers.
+- Imports from `./display.js` for the format/display functions used in rendering.
+
+## Module-Level Changes
+
+### New files
+
+| File                | Contents                                                                                                                                                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/display.ts` | All extracted symbols: `Theme`, `AgentDetails`, `SPINNER`, `ERROR_STATUSES`, `TOOL_DISPLAY`, `formatTokens`, `formatSessionTokens`, `formatTurns`, `formatMs`, `formatDuration`, `getDisplayName`, `getPromptModeLabel`, `buildInvocationTags`, `describeActivity`, private `truncateLine`. |
+
+### Modified files
+
+| File                               | Change                                                                                                                                                                     |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/agent-widget.ts`           | Remove all extracted symbols. Add `import` from `./display.js` for symbols `AgentWidget` still uses internally. Keep `UICtx`, `AgentWidget` class, private widget helpers. |
+| `src/ui/conversation-viewer.ts`    | Change import path from `./agent-widget.js` to `./display.js`.                                                                                                             |
+| `src/ui/agent-menu.ts`             | Change import path from `./agent-widget.js` to `./display.js`.                                                                                                             |
+| `src/tools/agent-tool.ts`          | Split import: `UICtx` from `../ui/agent-widget.js`; all others from `../ui/display.js`.                                                                                    |
+| `src/tools/foreground-runner.ts`   | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/tools/get-result-tool.ts`     | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/tools/helpers.ts`             | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/tools/background-spawner.ts`  | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/renderer.ts`                  | Change import path from `./ui/agent-widget.js` to `./ui/display.js`.                                                                                                       |
+| `test/agent-widget.test.ts`        | Change import path to `../src/ui/display.js`. Rename file to `test/display.test.ts` since it tests extracted functions.                                                    |
+| `test/conversation-viewer.test.ts` | Change `Theme` import from `../src/ui/agent-widget.js` to `../src/ui/display.js`.                                                                                          |
+
+### Unchanged files
+
+| File             | Reason                                                              |
+| ---------------- | ------------------------------------------------------------------- |
+| `src/runtime.ts` | Imports only `UICtx` — stays in `agent-widget.ts`.                  |
+| `src/index.ts`   | Imports `AgentWidget` and `UICtx` — both stay in `agent-widget.ts`. |
+
+## Test Impact Analysis
+
+1. The extraction enables dedicated `display.test.ts` that tests formatting functions in isolation without any widget class ceremony.
+   The existing `agent-widget.test.ts` already tests only extracted functions (`formatSessionTokens`, `getDisplayName`, `getPromptModeLabel`) — it becomes `display.test.ts` with no assertion changes, just a file rename and import path update.
+2. No existing tests become redundant — the current test file already exercises the extracted layer exclusively.
+3. No existing tests need assertion changes — this is a pure code-motion refactoring with no behavior change.
+
+## TDD Order
+
+1. **Create `ui/display.ts` with all extracted symbols; update `agent-widget.ts` to import from it.**
+   Move the 12 exported symbols, 2 types, and 1 private helper to `ui/display.ts`.
+   Remove them from `agent-widget.ts` and add imports from `./display.js` for symbols the `AgentWidget` class still references.
+   Commit: `refactor: extract display helpers into ui/display.ts (#135)`
+
+2. **Update all consumer imports to point at `ui/display.ts`.**
+   Update the 8 source files (`conversation-viewer.ts`, `agent-menu.ts`, `agent-tool.ts`, `foreground-runner.ts`, `get-result-tool.ts`, `helpers.ts`, `background-spawner.ts`, `renderer.ts`) to import from the new module.
+   Commit: `refactor: update imports to use ui/display.ts (#135)`
+
+3. **Rename test file and update test imports.**
+   Rename `test/agent-widget.test.ts` → `test/display.test.ts`.
+   Update import path to `../src/ui/display.js`.
+   Update `Theme` import in `test/conversation-viewer.test.ts`.
+   Commit: `test: rename agent-widget test to display test (#135)`
+
+4. **Verify: run `pnpm run check` and `pnpm vitest run`.**
+   Confirm type-checking and all tests pass.
+   No commit needed — validation step.
+
+## Risks and Mitigations
+
+| Risk                                                 | Mitigation                                                                                                             |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Missed import site causes runtime `undefined` import | Grep confirmed all 10 source consumers and 2 test consumers above. Step 4 validates with type-check + full test suite. |
+| `TOOL_DISPLAY` made public unintentionally           | Keep it non-exported in `display.ts` (only `describeActivity` uses it).                                                |
+| Circular dependency `display.ts` ↔ `agent-widget.ts` | `display.ts` has no imports from `agent-widget.ts`. `agent-widget.ts` imports from `display.ts` — one-directional.     |
+| Re-export churn for downstream consumers             | No downstream consumers — these are all internal module imports, not public API.                                       |
+
+## Open Questions
+
+None — the architecture doc and issue specify the exact extraction set and target module.

package/docs/plans/0136-decompose-agent-menu.md

@@ -0,0 +1,300 @@
+---
+issue: 136
+issue_title: "Decompose `agent-menu.ts`"
+---
+
+# Decompose agent-menu into config editor, creation wizard, and file-ops abstraction
+
+## Problem Statement
+
+`agent-menu.ts` (668 lines) has 8 distinct responsibilities: menu FSM orchestration, agent listing, config editing, agent ejection, two creation wizards, running-agent viewer, and settings form.
+Filesystem operations (`readFileSync`, `writeFileSync`, `unlinkSync`, `existsSync`, `mkdirSync`) are scattered across 10+ call sites with no abstraction layer, forcing tests to use `vi.mock("node:fs")` rather than injecting stubs.
+
+## Goals
+
+- Extract an `AgentFileOps` interface abstracting all filesystem calls, with a production `FsAgentFileOps` implementation.
+- Extract `ui/agent-config-editor.ts` (~170 lines) containing `showAgentDetail` with eject/disable/enable/edit/delete/reset transitions.
+- Extract `ui/agent-creation-wizard.ts` (~200 lines) containing both the AI-generation and manual-form creation paths.
+- Leave menu FSM, agent listing, running-agent viewer, and settings form in `agent-menu.ts` (~280 lines).
+- Each extracted module receives dependencies via injection — no direct `node:fs` imports outside `FsAgentFileOps`.
+- Enable unit testing of config editor and creation wizard without `vi.mock("node:fs")`.
+
+## Non-Goals
+
+- Refactoring the settings form or running-agent viewer — they stay in `agent-menu.ts`.
+- Changing any user-facing behavior or menu flow.
+- Extracting `showAllAgentsList` — it is menu orchestration (presents the list, delegates to editor for detail).
+- Deduplicating the YAML frontmatter builders in eject and manual wizard (structurally different content shapes).
+
+## Background
+
+### Prerequisite
+
+Issue #135 (extract display helpers) is **implemented** — `ui/display.ts` exists and provides `formatDuration`, `getDisplayName`, and other formatters.
+Extracted menu sub-modules can import display helpers without pulling in the widget.
+
+### Existing IO-injection convention
+
+The codebase uses injectable IO interfaces to decouple domain logic from `node:fs` and the Pi SDK:
+
+- `AssemblerIO` in `session-config.ts` — 4 methods for prompt assembly IO.
+- `RunnerIO` in `agent-runner.ts` — 7 methods for session creation IO.
+
+Both follow the same pattern: interface defined in the module that uses it, production implementation wired at the edge (`index.ts`), test stubs injected directly.
+
+### Current fs call inventory in agent-menu.ts
+
+| Function                         | fs calls                                                      |
+| -------------------------------- | ------------------------------------------------------------- |
+| `findAgentFile`                  | `existsSync` ×2                                               |
+| `showAgentDetail` (edit)         | `readFileSync`, `writeFileSync`                               |
+| `showAgentDetail` (delete/reset) | `unlinkSync`                                                  |
+| `ejectAgent`                     | `mkdirSync`, `existsSync`, `writeFileSync`                    |
+| `disableAgent`                   | `readFileSync`, `writeFileSync`, `mkdirSync`, `writeFileSync` |
+| `enableAgent`                    | `readFileSync`, `writeFileSync`, `unlinkSync`                 |
+| `showGenerateWizard`             | `mkdirSync`, `existsSync` ×2                                  |
+| `showManualWizard`               | `mkdirSync`, `existsSync`, `writeFileSync`                    |
+
+### Current test file
+
+`agent-menu.test.ts` (212 lines) uses `vi.mock("node:fs")` with `vi.hoisted` stubs.
+Only 7 tests exist — they cover the top-level menu, agent listing, projectAgentsDir injection, and settings delegation.
+No tests exercise config-editor transitions (edit/delete/eject/disable/enable) or creation wizards.
+
+## Design Overview
+
+### AgentFileOps interface
+
+A narrow interface abstracting all agent `.md` file operations:
+
+```typescript
+interface AgentFileOps {
+  exists(filePath: string): boolean;
+  read(filePath: string): string | undefined;
+  write(filePath: string, content: string): void;
+  remove(filePath: string): void;
+  ensureDir(dirPath: string): void;
+  findAgentFile(name: string, dirs: string[]): string | undefined;
+}
+```
+
+Design notes:
+
+- `read` returns `undefined` when the file does not exist (wraps `readFileSync` with a try/catch).
+- `write` ensures parent directories exist before writing (internalizes `mkdirSync`).
+- `ensureDir` is needed separately because `showGenerateWizard` creates the directory before spawning an agent that writes via Pi's tool (not via `AgentFileOps.write`).
+- `findAgentFile` takes an ordered list of directories and returns the first matching path.
+  The current code returns `{ path, location }` but only `showAgentDetail` uses `location` (for a confirmation dialog) — the full path already conveys the location to the user, so a plain `string | undefined` return suffices.
+
+### FsAgentFileOps production implementation
+
+Thin wrapper over `node:fs` synchronous APIs:
+
+```typescript
+class FsAgentFileOps implements AgentFileOps {
+  exists(filePath: string): boolean {
+    return existsSync(filePath);
+  }
+  read(filePath: string): string | undefined {
+    try { return readFileSync(filePath, "utf-8"); }
+    catch { return undefined; }
+  }
+  write(filePath: string, content: string): void {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, "utf-8");
+  }
+  remove(filePath: string): void {
+    unlinkSync(filePath);
+  }
+  ensureDir(dirPath: string): void {
+    mkdirSync(dirPath, { recursive: true });
+  }
+  findAgentFile(name: string, dirs: string[]): string | undefined {
+    for (const dir of dirs) {
+      const p = join(dir, `${name}.md`);
+      if (existsSync(p)) return p;
+    }
+    return undefined;
+  }
+}
+```
+
+### Extracted module patterns
+
+Both extracted modules follow the existing factory-function pattern (`createAgentsMenuHandler(deps)`) with narrow deps interfaces per ISP:
+
+Config editor call-site sketch (from orchestrator):
+
+```typescript
+const editor = createAgentConfigEditor({
+  fileOps: deps.fileOps,
+  registry: deps.registry,
+  personalAgentsDir: deps.personalAgentsDir,
+  projectAgentsDir: deps.projectAgentsDir,
+});
+// ...
+await editor.showAgentDetail(ctx, agentName);
+```
+
+Creation wizard call-site sketch (from orchestrator):
+
+```typescript
+const wizard = createAgentCreationWizard({
+  fileOps: deps.fileOps,
+  manager: deps.manager,
+  registry: deps.registry,
+  personalAgentsDir: deps.personalAgentsDir,
+  projectAgentsDir: deps.projectAgentsDir,
+});
+// ...
+await wizard.showCreateWizard(ctx);
+```
+
+### Deps interfaces (ISP-compliant)
+
+```typescript
+// agent-config-editor.ts
+interface AgentConfigEditorDeps {
+  fileOps: AgentFileOps;
+  registry: AgentTypeRegistry;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+
+// agent-creation-wizard.ts
+interface AgentCreationWizardDeps {
+  fileOps: AgentFileOps;
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+The config editor does not need `manager` (no agent spawning).
+The creation wizard does not need `agentActivity`, `getModelLabel`, or `settings`.
+
+### Updated AgentMenuDeps
+
+```typescript
+interface AgentMenuDeps {
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  agentActivity: AgentActivityReader;
+  getModelLabel: (type: string, registry?: ModelRegistry) => string;
+  settings: AgentMenuSettings;
+  fileOps: AgentFileOps;          // ← new
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+The single new field (`fileOps`) replaces all direct `node:fs` imports.
+
+## Module-Level Changes
+
+### New files
+
+1. `src/ui/agent-file-ops.ts` — `AgentFileOps` interface + `FsAgentFileOps` class.
+2. `src/ui/agent-config-editor.ts` — `AgentConfigEditorDeps` interface, `createAgentConfigEditor` factory.
+   Moves in: `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent`.
+3. `src/ui/agent-creation-wizard.ts` — `AgentCreationWizardDeps` interface, `createAgentCreationWizard` factory.
+   Moves in: `showCreateWizard`, `showGenerateWizard`, `showManualWizard`.
+4. `test/ui/agent-file-ops.test.ts` — unit tests for `FsAgentFileOps`.
+5. `test/ui/agent-config-editor.test.ts` — unit tests for config editor transitions with injected `AgentFileOps` stubs.
+6. `test/ui/agent-creation-wizard.test.ts` — unit tests for wizard paths with injected stubs.
+
+### Modified files
+
+1. `src/ui/agent-menu.ts`:
+   - Remove `import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs"`.
+   - Remove `findAgentFile`, `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent`, `showCreateWizard`, `showGenerateWizard`, `showManualWizard` (~375 lines removed).
+   - Add `fileOps: AgentFileOps` to `AgentMenuDeps`.
+   - Import and instantiate `createAgentConfigEditor` and `createAgentCreationWizard`.
+   - Update `showAllAgentsList` to call `editor.showAgentDetail(ctx, agentName)`.
+   - Update `showAgentsMenu` to call `wizard.showCreateWizard(ctx)`.
+   - Re-export `AgentMenuManager` (still needed by the wizard deps).
+   - Net result: ~280 lines (orchestration, listing, running agents, settings).
+2. `src/index.ts`:
+   - Import `FsAgentFileOps` from `./ui/agent-file-ops.js`.
+   - Construct `new FsAgentFileOps()` and pass as `fileOps` in the `createAgentsMenuHandler` call.
+3. `test/ui/agent-menu.test.ts`:
+   - Remove `vi.mock("node:fs")` and `vi.hoisted` stubs entirely.
+   - Add `fileOps` stub to `makeDeps` factory.
+   - Rewrite the "projectAgentsDir injection" test to verify that the orchestrator delegates to the editor (or move to `agent-config-editor.test.ts`).
+
+### Removed symbols
+
+Grep confirms these functions are only referenced within `agent-menu.ts` (closures inside `createAgentsMenuHandler`) — no external consumers:
+
+- `findAgentFile` — moves to `agent-config-editor.ts` (reimplemented via `AgentFileOps.findAgentFile`).
+- `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent` — move to `agent-config-editor.ts`.
+- `showCreateWizard`, `showGenerateWizard`, `showManualWizard` — move to `agent-creation-wizard.ts`.
+
+## Test Impact Analysis
+
+### New unit tests enabled by extraction
+
+1. **Config editor transitions** — `showAgentDetail` has 6 menu paths (edit, delete, reset, eject, disable, enable) with sub-branches (confirm/cancel, file exists/not-exists, default/custom agent).
+   Currently untestable in isolation because the functions are closures inside `createAgentsMenuHandler`.
+   After extraction, each transition is testable with injected `AgentFileOps` stubs — no `vi.mock("node:fs")` needed.
+2. **Creation wizard flows** — generate wizard (spawn + check result) and manual wizard (multi-step form → write file) are currently untested.
+   After extraction, both are testable with injected stubs for `AgentFileOps` and `AgentMenuManager.spawnAndWait`.
+3. **FsAgentFileOps** — thin tests verifying the production fs wrapper (read returns undefined on missing file, write ensures parent dirs, findAgentFile checks directories in order).
+
+### Existing tests that become redundant
+
+The "projectAgentsDir injection" test (`agent-menu.test.ts`) navigates through the main menu → agent types → agent detail, then asserts `mockExistsSync` was called with the correct path.
+After extraction, this end-to-end path tests orchestration + editor together; a focused test in `agent-config-editor.test.ts` replaces it.
+The orchestrator test can be simplified to verify it delegates to the editor.
+
+### Existing tests that stay as-is
+
+- Menu structure tests (shows options, reload, running agents) — these test the orchestrator directly.
+- Settings delegation tests — these test code that remains in `agent-menu.ts`.
+
+## TDD Order
+
+### Cycle 1: AgentFileOps interface and FsAgentFileOps
+
+1. `test:` write `test/ui/agent-file-ops.test.ts` — tests for `read` (existing file, missing file), `write` (ensures parent dir), `remove`, `exists`, `ensureDir`, `findAgentFile` (first-match ordering, no match).
+2. `feat:` implement `src/ui/agent-file-ops.ts` — interface + `FsAgentFileOps` class.
+3. Commit: `feat: add AgentFileOps interface and FsAgentFileOps (#136)`.
+
+### Cycle 2: Extract agent-config-editor
+
+1. `test:` write `test/ui/agent-config-editor.test.ts` — tests for `showAgentDetail` transitions: edit (save/cancel), delete (confirm/cancel), reset-to-default (confirm/cancel), eject (project/personal location, overwrite check), disable (existing file toggle, new disable-only file), enable (remove enabled:false line, remove empty override file).
+   All tests inject stub `AgentFileOps` — no `vi.mock`.
+2. `refactor:` create `src/ui/agent-config-editor.ts` — move `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent` from `agent-menu.ts`.
+   Replace direct fs calls with `deps.fileOps.*` calls.
+   Replace the closure `findAgentFile` with `deps.fileOps.findAgentFile(name, [deps.projectAgentsDir, deps.personalAgentsDir])`.
+3. `refactor:` update `src/ui/agent-menu.ts` — add `fileOps` to `AgentMenuDeps`, import `createAgentConfigEditor`, wire into `showAllAgentsList`.
+4. `refactor:` update `src/index.ts` — import `FsAgentFileOps`, pass `fileOps: new FsAgentFileOps()` in deps.
+5. `test:` update `test/ui/agent-menu.test.ts` — add `fileOps` stub to `makeDeps`, rewrite the "projectAgentsDir injection" test to verify orchestrator→editor delegation.
+6. Run `pnpm run check` (interface change).
+7. Commit: `refactor: extract agent-config-editor from agent-menu (#136)`.
+
+### Cycle 3: Extract agent-creation-wizard
+
+1. `test:` write `test/ui/agent-creation-wizard.test.ts` — tests for `showCreateWizard` (location + method selection), `showGenerateWizard` (spawn success, spawn error, overwrite check), `showManualWizard` (full form flow, overwrite check, tool/model/thinking selections).
+   All tests inject stub `AgentFileOps` + `AgentMenuManager` — no `vi.mock`.
+2. `refactor:` create `src/ui/agent-creation-wizard.ts` — move `showCreateWizard`, `showGenerateWizard`, `showManualWizard` from `agent-menu.ts`.
+   Replace direct fs calls with `deps.fileOps.*` calls.
+3. `refactor:` update `src/ui/agent-menu.ts` — import `createAgentCreationWizard`, wire into `showAgentsMenu`.
+   Remove the `import { ... } from "node:fs"` line (no longer needed).
+4. `test:` remove `vi.mock("node:fs")` and `vi.hoisted` stubs from `test/ui/agent-menu.test.ts` entirely.
+5. Run `pnpm run check`.
+6. Commit: `refactor: extract agent-creation-wizard from agent-menu (#136)`.
+
+## Risks and Mitigations
+
+| Risk                                                                                                      | Mitigation                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Circular dependency between orchestrator and editor (editor calling back to menu)                         | The editor's `showAgentDetail` does not recurse to the agent list — the orchestrator does (`showAllAgentsList` calls editor then recurses itself). No circular dependency.                            |
+| `FsAgentFileOps.write` silently creates parent directories when callers expect the directory to not exist | `write` mirrors current behavior — every call site already calls `mkdirSync` before `writeFileSync`. The consolidation only changes where the `mkdirSync` happens, not whether it runs.               |
+| Adding `fileOps` to `AgentMenuDeps` breaks existing test factory                                          | Cycle 2 updates `makeDeps` in the same commit — the interface change and call-site update land together per the testing skill's single-call-site rule.                                                |
+| Generate wizard spawns an agent that writes via Pi tools, not via `AgentFileOps.write`                    | The wizard uses `fileOps.ensureDir` for directory creation and `fileOps.exists` for the post-spawn success check. The spawned agent's file write is outside the menu's control and is not abstracted. |
+
+## Open Questions
+
+- None — the issue's proposed changes section is unambiguous and the prerequisite (#135) is already implemented.

package/docs/retro/0134-reduce-as-any-casts.md

@@ -0,0 +1,56 @@
+---
+issue: 134
+issue_title: "Reduce `as any` casts in test suite"
+---
+
+# Retro: #134 — Reduce as-any casts in test suite
+
+## Final Retrospective (2026-05-22T17:00:00Z)
+
+### Session summary
+
+Reduced `as any` casts from 93 to 15 across the pi-subagents package.
+Production changes added type guards (`getToolCallName`, `isBashExecution`), narrowed `SubagentRuntime.widget` to `WidgetLike`, typed `CreateSessionOptions.settingsManager` as `SettingsManager`, and fixed `ResourceLoaderOptions.appendSystemPromptOverride` to match the SDK.
+Test improvements introduced `toAgentSession()`, `STUB_CTX`, and `makeRegistry()` helpers to centralise unavoidable bridge casts.
+Also fixed 3 pre-existing lint issues.
+
+This session also included #133 (plan + implement + ship) which preceded the #134 work.
+
+### Observations
+
+#### What went well
+
+- The user's Kent Beck prompt ("make the change that makes the change easy") redirected the plan from test-only fixes to targeted production changes, yielding cleaner results — `WidgetLike`, type guards, and SDK-typed options eliminated casts that would have been impossible to remove from tests alone.
+- The user's TDA observation on the `MenuCtx` step caught a deep architectural issue (context threaded 4 layers just to relay to `buildParentSnapshot`).
+  Skipping step 4 was the right call — attempting it would have added a production cast or cascaded changes through 6+ files.
+
+#### What caused friction (agent side)
+
+1. `rabbit-hole` — Step 1 planning involved extensive analysis of whether `CreateSessionOptions` could use full SDK types.
+   Spent significant reasoning tracing `ModelRegistry` / `SessionManager` private fields, structural compatibility, `ParentSnapshot` constructibility, and `ResourceLoader` interface width before concluding that only `settingsManager` and the callback signature could be fixed.
+   The plan's claim "widen to SDK types" was optimistic about class-with-private-fields constraints.
+   Impact: added friction but no rework — the conclusion was correct, just slow to reach.
+
+2. `wrong-abstraction` — Step 4 (`MenuCtx`) attempted to mechanically narrow the handler parameter without questioning why `ctx` was threaded 4 layers deep.
+   Partially implemented the `MenuCtx` interface before the user's "What am I misunderstanding?"
+   prompt exposed the real issue: a TDA violation where intermediate functions carry `ExtensionContext` only to relay it.
+   Impact: partial implementation reverted via `git checkout src/ui/agent-menu.ts`; ~10 minutes of wasted edits.
+
+3. `instruction-violation` (user-caught) — Used `pnpm exec biome check --write --unsafe` instead of `pnpm run lint:fix` to fix pre-existing lint issues.
+   The `/tdd-plan` prompt explicitly says "run `pnpm run lint:fix`."
+   Impact: no functional difference (same result), but violated the established convention and used an unnecessary `--unsafe` flag.
+
+4. `instruction-violation` (user-caught) — Dismissed pre-existing lint issues as "not from our changes" without fixing them.
+   The user asked "Why do we have pre-existing lint issues?"
+   — the correct action was to fix them immediately rather than noting and ignoring them.
+   Impact: required an extra commit (`style: fix pre-existing lint issues`) that should have been folded into an earlier step.
+
+#### What caused friction (user side)
+
+- The user's interventions on the `MenuCtx` step and lint issues were both valuable redirections that improved the outcome.
+  No mechanical overhead identified — each intervention was strategic judgment that the agent couldn't have reached alone.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — added "Verify green baseline" section (check + lint + test before starting TDD); added "Fix all failures — including pre-existing ones" to the end-of-cycle lint step.
+2. `.pi/prompts/build-plan.md` — same baseline check and fix-all rule for non-TDD plans.