@gotgenes/pi-subagents 6.9.1 → 6.9.3

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.9.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.2...pi-subagents-v6.9.3) (2026-05-22)
+
+
+### Documentation
+
+* add issue numbers to Phase 8 roadmap steps ([77fee40](https://github.com/gotgenes/pi-packages/commit/77fee402ebc445171f3768f2eea1bba242ce9723))
+* add Phase 8 roadmap — testability, display extraction, menu decomposition ([37a0520](https://github.com/gotgenes/pi-packages/commit/37a0520e32a93f4c9bffd5a728882c68e9811024))
+* clean up architecture.md progress tracking ([e006032](https://github.com/gotgenes/pi-packages/commit/e00603209b9c21cb1bef41c34eeb71c1cc338117))
+* **retro:** add retro notes for issue [#116](https://github.com/gotgenes/pi-packages/issues/116) ([701dca8](https://github.com/gotgenes/pi-packages/commit/701dca8075221aa4c36e19e2d54d43c74863ea57))
+
+## [6.9.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.1...pi-subagents-v6.9.2) (2026-05-22)
+
+
+### Documentation
+
+* mark E2 type housekeeping done in architecture ([#116](https://github.com/gotgenes/pi-packages/issues/116)) ([89f18a8](https://github.com/gotgenes/pi-packages/commit/89f18a82fac39b4a62be8e440355b859afaa6d2f))
+* plan type housekeeping and small structural cleanups ([#116](https://github.com/gotgenes/pi-packages/issues/116)) ([e1cbd26](https://github.com/gotgenes/pi-packages/commit/e1cbd269961a1bff3b11e2e916733a79c39a087d))
+* **retro:** add retro notes for issue [#115](https://github.com/gotgenes/pi-packages/issues/115) ([05b8809](https://github.com/gotgenes/pi-packages/commit/05b88093f7b70ea886b6c7cb5f0cc96161a95df6))
+
 ## [6.9.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.0...pi-subagents-v6.9.1) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -322,10 +322,15 @@ Target: every mutable state bag becomes a class, every dependency bag narrows to
 The work is sequenced so each change makes the next change easy.
 See the [Encapsulation roadmap](#encapsulation-roadmap) section for the full breakdown.
 
+### Phase 8: Testability, display extraction, and menu decomposition
+
+Target: eliminate `vi.mock()` module mocking in the two most fragile test suites by injecting IO-touching collaborators; consolidate shared test fixtures; extract display helpers into a reusable module; decompose the largest UI file.
+
+See the [Phase 8 roadmap](#phase-8-roadmap) section for the full breakdown.
+
 ## Structural refactoring roadmap
 
-Phases 1–5 are complete.
-Phase 7 (encapsulation and dependency narrowing) is the active structural track.
+Phases 1–5 and 7 are complete.
 See `git log` for the full history; issue references are preserved below for traceability.
 
 | Phase              | Issue              | Summary                                                               |
@@ -379,137 +384,105 @@ This section describes the Phase 7 targets: encapsulating mutable state into cla
 
 Each step is sequenced so it makes the next step easier.
 
-### Current smells
+### Resolved smells
+
+All nine smells identified at the start of Phase 7 were resolved:
 
-| Smell                          | Location                                     | Evidence                                                                                                                                                                          |
-| ------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ~~Global mutable state~~       | ~~`agent-types.ts`~~                         | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                         |
-| Closure bag as class           | `createNotificationSystem()`                 | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                               |
-| ~~Mutable state bag~~          | ~~`AgentActivity` (7 fields)~~               | **Fixed #110**: `AgentActivityTracker` class; `ui-observer.ts` calls transition methods; widget, notification, agent-tool use read-only accessors                                 |
-| ~~Settings relay~~             | ~~`AgentMenuDeps` (13 fields)~~              | **Fixed #109**: `SettingsManager` class; 6 callback fields collapsed to `settings: SettingsManager`; `AgentMenuDeps` now 8 fields                                                 |
-| ~~Post-construction mutation~~ | ~~`AgentRecord` non-transition state~~       | **Fixed #111**: `ExecutionState`, `WorktreeState`, `NotificationState` collaborators; `pendingSteers` moved to `AgentManager`; stats encapsulated behind mutation methods         |
-| ~~Fire-and-forget callbacks~~  | ~~`AgentManagerOptions`~~                    | **Fixed #112**: `AgentManagerObserver` interface; `observer` replaces 3 callbacks; `index.ts` constructs one observer object instead of 3 closure lambdas                         |
-| ~~Duplicate `SpawnOptions`~~   | ~~`service.ts` + `agent-manager.ts`~~        | **Fixed #113**: internal type renamed to `AgentSpawnConfig`; public `SpawnOptions` in `service.ts` unchanged                                                                      |
-| Type dumping ground            | `types.ts`                                   | `NotificationDetails` used only by notification/renderer; ~~`DEFAULT_AGENT_NAMES` moved to `AgentTypeRegistry` (#108)~~; `AgentConfig` (21 fields) consumers use 2–4 each         |
-| ~~Wide dependency bags~~       | ~~`AgentToolDeps` (9), `AgentMenuDeps` (8)~~ | **Fixed #114**: `AgentToolDeps` 9 → 6; `AgentMenuDeps` 8 → 7; `emitEvent` removed from both; description text derived from registry; `agentActivity` narrowed to typed interfaces |
+| Smell                      | Resolution                                                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Global mutable state       | `AgentTypeRegistry` class (#108); `reloadCustomAgents` callback removed from dep bags                                                      |
+| Closure bag as class       | `NotificationManager` class (#116); `pendingNudges` and timer state are private fields                                                     |
+| Mutable state bag          | `AgentActivityTracker` class (#110); transition methods replace external writes                                                            |
+| Settings relay             | `SettingsManager` class (#109); 6 callback fields collapsed to one object                                                                  |
+| Post-construction mutation | `ExecutionState`, `WorktreeState`, `NotificationState` collaborators (#111); stats behind mutation methods                                 |
+| Fire-and-forget callbacks  | `AgentManagerObserver` interface (#112); one observer object replaces 3 closure lambdas                                                    |
+| Duplicate `SpawnOptions`   | Internal type renamed to `AgentSpawnConfig` (#113); public `SpawnOptions` unchanged                                                        |
+| Type dumping ground        | `NotificationDetails`, `ParentSnapshot`, `EnvInfo` moved to their natural modules (#116); narrow subsets defined                           |
+| Wide dependency bags       | `AgentToolDeps` 9 → 6, `AgentMenuDeps` 8 → 7 (#114); `emitEvent` removed; description text derived from registry; `agentActivity` narrowed |
 
 ### Step A: Extract state into classes (foundation, parallel)
 
 These three extractions are independent and can proceed in any order.
 Each eliminates a category of global/closure state and gives orphaned callbacks a natural home.
 
-#### A1. `AgentTypeRegistry` class (#108)
+#### A1. AgentTypeRegistry class (#108)
 
-Wrap the module-scoped `agents` Map and free functions in `agent-types.ts` into an injectable class.
-`reloadCustomAgents` (currently a callback threaded through `AgentToolDeps` and `AgentMenuDeps`) becomes `registry.reload()`.
-`DEFAULT_AGENT_NAMES` moves from `types.ts` to the registry.
+Wrapped the module-scoped `agents` Map and free functions in `agent-types.ts` into an injectable class.
+`reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`; replaced by `registry.reload()`.
+`DEFAULT_AGENT_NAMES` moved from `types.ts` to the registry.
 
-Impact: eliminates global mutable state, enables test isolation without module resets, removes `reloadCustomAgents` callback from 2 dependency bags.
-
-#### ~~A2. `SettingsManager` class (#109)~~ — **Done**
+#### A2. SettingsManager class (#109, #118)
 
 Encapsulated settings load/save/apply cycle into `SettingsManager` (in `settings.ts`).
 Owns `defaultMaxTurns`, `graceTurns`, `maxConcurrent` with normalizing property accessors.
-Absorbed `SettingsAppliers`, `applyAndEmitLoaded`, `saveAndEmitChanged`.
+Added `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` — each owns the full consequence chain: normalize → set in memory → notify callback → persist → emit event → return toast.
 The 6 settings-related fields in `AgentMenuDeps` collapsed to `settings: AgentMenuSettings`.
-`AgentManager` reads `maxConcurrent` via injected `getMaxConcurrent` function.
-`SubagentRuntime.defaultMaxTurns` and `.graceTurns` removed.
-
-Impact: reduced `AgentMenuDeps` from 13 → 8 fields; `AgentToolDeps` from 8 → 7 fields.
-
-#### ~~A2b. `SettingsManager` apply methods (#118)~~ — **Done**
-
-Added `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` to `SettingsManager`.
-Each owns the full consequence chain: normalize → set in memory → notify callback → persist → emit event → return toast.
-`SettingsManager` accepts an `onMaxConcurrentChanged` callback (wired to `manager.notifyConcurrencyChanged()` at init).
-`notifyConcurrencyChanged` removed from `AgentMenuManager`; `showSettings` now makes a single apply call per setting.
 
-Impact: eliminates LoD / Tell-Don't-Ask violation in `showSettings`; menu no longer coordinates between settings and manager.
-
-#### ~~A3. `AgentActivityTracker` class (#110)~~ — **Done**
+#### A3. AgentActivityTracker class (#110)
 
 Wrapped the 7-field mutable `AgentActivity` interface in an `AgentActivityTracker` class (`src/ui/agent-activity-tracker.ts`).
-`ui-observer.ts` calls transition methods (`onToolStart`, `onToolEnd`, `onMessageStart`, `onMessageUpdate`, `onTurnEnd`, `onUsageUpdate`, `setSession`).
-The notification system, widget, conversation viewer, and agent-tool use read-only accessors.
-The shared map on `SubagentRuntime` is now `Map<string, AgentActivityTracker>`.
-
-Impact: eliminates output-argument writes in `ui-observer.ts`, makes the mutation contract explicit.
+`ui-observer.ts` calls transition methods; consumers use read-only accessors.
+The shared map on `SubagentRuntime` is `Map<string, AgentActivityTracker>`.
 
-### ~~Step B: Split `AgentRecord` lifecycle state (#111)~~ — **Done**
+### Step B: Split AgentRecord lifecycle state (#111)
 
 Split post-construction mutation into phase-specific collaborators, each born complete:
 
-- **`ExecutionState`** (`session`, `outputFile`) — constructed in `onSessionCreated`, attached as `record.execution`.
-- **`WorktreeState`** (`path`, `branch`, `cleanupResult`) — constructed at worktree setup, attached as `record.worktreeState`.
-- **`NotificationState`** (`toolCallId`, `resultConsumed`) — constructed by `AgentManager.spawn()` when `toolCallId` is provided in `AgentSpawnConfig`, attached as `record.notification`.
-- **`pendingSteers`** moved to `Map<string, string[]>` on `AgentManager`; steer-tool and service-adapter call `manager.queueSteer()`.
-- Stats (`toolUses`, `lifetimeUsage`, `compactionCount`) encapsulated behind mutation methods (`incrementToolUses`, `addUsage`, `incrementCompactions`) with read-only getters.
+- **`ExecutionState`** (`session`, `outputFile`) — constructed in `onSessionCreated`.
+- **`WorktreeState`** (`path`, `branch`, `cleanupResult`) — constructed at worktree setup.
+- **`NotificationState`** (`toolCallId`, `resultConsumed`) — constructed by `AgentManager.spawn()` when `toolCallId` is provided.
+- **`pendingSteers`** moved to `Map<string, string[]>` on `AgentManager`.
+- Stats encapsulated behind mutation methods with read-only getters.
 - `AgentRecordInit` trimmed from 19 optional fields to 4 construction-time fields.
 
-Each piece is born complete at the moment its information is available.
-The record doesn't accumulate half-baked state — it receives fully constructed collaborators.
+### Step C: Replace AgentManager callbacks with observer (#112)
 
-### Step C: Replace `AgentManager` callbacks with observer (#112) ✅
-
-**Done.**
 `AgentManagerObserver` interface replaces `onStart`/`onComplete`/`onCompact`.
 `index.ts` constructs one observer object instead of 3 closure lambdas.
 `AgentManagerOptions` drops from 9 → 7 fields.
 
-### Step D: Disambiguate `SpawnOptions` and narrow dependency bags
-
-With the registry class, settings manager, and observer in place, the dependency bags shrink naturally.
+### Step D: Disambiguate SpawnOptions and narrow dependency bags
 
-#### D1. Disambiguate `SpawnOptions` (#113) ✅
+#### D1. Disambiguate SpawnOptions (#113)
 
-**Done.**
 Internal `SpawnOptions` in `agent-manager.ts` renamed to `AgentSpawnConfig`.
-Public `SpawnOptions` in `service.ts` is unchanged.
+Public `SpawnOptions` in `service.ts` unchanged.
 
-#### D2. Narrow `AgentToolDeps` and `AgentMenuDeps` (#114) ✅
+#### D2. Narrow AgentToolDeps and AgentMenuDeps (#114)
 
-**Done.**
-`AgentToolDeps` 9 → 6: removed `emitEvent` (moved to `AgentManagerObserver.onAgentCreated`), `typeListText`, `availableTypesText` (derived inside `createAgentTool`); `agentActivity` narrowed to `AgentActivityAccess`.
-`AgentMenuDeps` 8 → 7: removed dead `emitEvent` field; `agentActivity` narrowed to `AgentActivityReader`.
-`buildTypeListText` extracted to `tools/helpers.ts`.
+| Bag             | Before   | After | How                                                                                                         |
+| --------------- | -------- | ----- | ----------------------------------------------------------------------------------------------------------- |
+| `AgentToolDeps` | 9 fields | 6     | `emitEvent` → observer; `typeListText`/`availableTypesText` derived from registry; `agentActivity` narrowed |
+| `AgentMenuDeps` | 8 fields | 7     | Dead `emitEvent` removed; `agentActivity` narrowed to read-only `AgentActivityReader`                       |
 
-| Bag             | Before   | After | How                                                                                                           |
-| --------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------- |
-| `AgentToolDeps` | 9 fields | 6     | `emitEvent` → observer; `typeListText`/`availableTypesText` derived from registry; `agentActivity` narrowed   |
-| `AgentMenuDeps` | 8 fields | 7     | Dead `emitEvent` removed; `agentActivity` narrowed to read-only `AgentActivityReader`                         |
+### Step E: Decompose large files and relocate types
 
-### Step E: Decompose large files and relocate types (parallel)
+#### E1. Split agent-tool.ts foreground/background (#115)
 
-#### E1. Split `agent-tool.ts` foreground/background (#115) ✅
-
-**Done.**
-Fixed two upstream API gaps before extracting: `onSessionCreated` now receives `(session, record)` (eliminating a `listAgents()` reverse-search), and `AgentSpawnConfig` accepts `toolCallId` (moving `NotificationState` wiring into `AgentManager.spawn()`).
 Extracted `foreground-runner.ts` (~175 lines) and `background-spawner.ts` (~116 lines).
-`agent-tool.ts` reduced from 579 → 411 lines (orchestrator + rendering).
+`agent-tool.ts` reduced from 579 → 411 lines.
 
 #### E2. Type housekeeping (#116)
 
-- Move `NotificationDetails` from `types.ts` to `notification.ts`.
-- Move `DEFAULT_AGENT_NAMES` from `types.ts` to the registry.
-- Move `ParentSnapshot` from `types.ts` to `parent-snapshot.ts`.
-- Move `EnvInfo` from `types.ts` to `env.ts`.
-- Convert `createNotificationSystem` closure to `NotificationManager` class.
-- Convert `ConversationViewer` constructor from 6 positional parameters to an options bag.
-- Define narrow `AgentConfig` subset interfaces for consumers that use 2–4 fields of the 21-field type.
-
-### Expected impact
-
-| Metric                                     | Before                                                                           | After   |
-| ------------------------------------------ | -------------------------------------------------------------------------------- | ------- |
-| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                     | **0** ✓ |
-| Closure-bag "classes"                      | ~~2~~ 1 (`createNotificationSystem`; settings free functions **fixed #109**)     | 0       |
-| Externally-mutated state bags              | ~~2~~ ~~1~~ **0** (`AgentRecord` **fixed #111**; `AgentActivity` **fixed #110**) | 0 ✓     |
-| `AgentManagerOptions` fields               | 8                                                                                | 5       |
-| `AgentToolDeps` fields                     | ~~9~~ **6** (−3 text fields derived; −1 emitEvent → observer; activity narrowed) | 6 ✓     |
-| `AgentMenuDeps` fields                     | ~~13~~ **7** (−6 settings #109; −1 registry #108; −1 dead emitEvent #114)        | 7 ✓     |
-| `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                           | 0       |
-| Callbacks threaded through deps            | ~~8~~ 0 remaining settings callbacks (**fixed #109**); `emitEvent` ×3 remain     | 0       |
-| Types in `types.ts` without a natural home | 4                                                                                | 0       |
+- Moved `NotificationDetails`, `ParentSnapshot`, `EnvInfo` to their natural modules.
+- Converted `createNotificationSystem` closure to `NotificationManager` class.
+- Converted `ConversationViewer` constructor from 7 positional parameters to `ConversationViewerOptions` bag.
+- Defined `AgentIdentity` and `AgentPromptConfig` narrow subsets; `buildAgentPrompt` narrowed to `AgentPromptConfig`.
+
+### Phase 7 results
+
+| Metric                                     | Before | After |
+| ------------------------------------------ | ------ | ----- |
+| Module-scoped mutable state                | 1      | 0     |
+| Closure-bag "classes"                      | 2      | 0     |
+| Externally-mutated state bags              | 2      | 0     |
+| `AgentManagerOptions` fields               | 9      | 7     |
+| `AgentToolDeps` fields                     | 9      | 6     |
+| `AgentMenuDeps` fields                     | 13     | 7     |
+| `SpawnOptions` callback fields             | 6      | 1     |
+| `RunOptions` callback fields               | 6      | 1     |
+| Callbacks threaded through deps            | 8      | 0     |
+| Types in `types.ts` without a natural home | 4      | 0     |
 
 ### Dependency graph
 
@@ -527,6 +500,135 @@ E2 (Type housekeeping) ── can start after A1, runs parallel to later steps
 
 ---
 
+## Phase 8 roadmap
+
+Phase 7 eliminated all structural smells (mutable state, closure bags, callback threading, wide dependency bags).
+Phase 8 targets the next layer: testability friction, display module cohesion, and menu decomposition.
+
+The test suite (690 tests, 1.4:1 test-to-code ratio) is comprehensive but uneven in quality.
+Two files — `session-config.test.ts` and `agent-runner.test.ts` — account for 11 of 12 total `vi.mock()` calls and rely heavily on verifying internal call sequences rather than observable outputs.
+This fragility is a symptom of production code that imports IO-touching collaborators directly instead of receiving them through injection.
+
+The display and menu improvements were identified during Phase 7 but deferred because they don't gate encapsulation work.
+They are included here because the display extraction unblocks menu decomposition.
+
+### Test pain points
+
+| Symptom                       | Location                                                | Root cause                                                        |
+| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
+| 7 `vi.mock()` calls           | `agent-runner.test.ts`                                  | Runner imports prompts, memory, skills, env, session-dir directly |
+| 4 `vi.mock()` calls           | `session-config.test.ts`                                | Assembler imports prompts, memory, skills directly                |
+| 52 `as any` casts             | Across test suite                                       | SDK session/context interfaces too wide to construct in tests     |
+| 3× duplicated `mockSession()` | agent-manager, record-observer, ui-observer tests       | No shared test fixture                                            |
+| 3× duplicated `makeDeps()`    | agent-tool, background-spawner, foreground-runner tests | No shared tool-deps fixture                                       |
+| Weak assertions               | lifecycle, renderer, session-config tests               | `toHaveBeenCalled()` without args, `toContain()` on large strings |
+
+Contrast with the well-designed test suites: `agent-manager.test.ts` (1 mock, DI via `AgentRunner` interface), `notification.test.ts` (0 mocks, pure functions + DI), and `agent-tool.test.ts` (0 mocks, tests via deps bag).
+The pattern is clear: modules that accept collaborators through injection produce resilient tests; modules that import collaborators directly produce fragile mock-heavy tests.
+
+### Step F: Shared test fixtures (#131)
+
+Consolidate duplicated mock factories into `test/helpers/`.
+
+1. `createMockSession()` — subscribable event bus with `emit()` helper; replaces 3 hand-rolled copies.
+2. `createToolDeps()` — builds `AgentToolDeps` with sensible defaults and override support; replaces 3 `makeDeps()` copies.
+
+Impact: reduces test boilerplate; single source of truth for mock shapes; changes to dep interfaces propagate automatically.
+
+### Step G: Inject IO collaborators into session-config (#132)
+
+`assembleSessionConfig` is described as a pure assembler, but it directly imports three IO-touching functions: `preloadSkills` (reads `.pi/skills` files), `buildMemoryBlock` (reads `MEMORY.md`), and `buildReadOnlyMemoryBlock` (reads `MEMORY.md`).
+It also imports `buildAgentPrompt`, which is pure but mocked anyway because tests verify call arguments instead of output properties.
+
+Inject these as an `AssemblerIO` parameter:
+
+```typescript
+export interface AssemblerIO {
+  preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
+  buildMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
+  buildReadOnlyMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
+  buildAgentPrompt: (config: AgentPromptConfig, cwd: string, env: EnvInfo, parentPrompt: string, extras: PromptExtras) => string;
+}
+```
+
+The production call site in `agent-runner.ts` passes the real implementations.
+Tests pass stubs or let real implementations run against controlled inputs.
+
+Impact: eliminates all 4 `vi.mock()` calls in `session-config.test.ts`; tests verify `SessionConfig` output properties instead of mock call arguments; the assembler becomes truly pure.
+
+### Step H: Inject SDK boundary into agent-runner (#133)
+
+`agent-runner.ts` has 7 module mocks because it imports `createAgentSession`, `DefaultResourceLoader`, `SessionManager`, and `SettingsManager` from the Pi SDK, plus `detectEnv`, `deriveSubagentSessionDir`, and `assembleSessionConfig` from sibling modules.
+
+After Step G, `assembleSessionConfig` no longer needs mocking (its own IO is injected).
+The remaining SDK dependencies can be injected via a narrow `RunnerIO` interface:
+
+```typescript
+export interface RunnerIO {
+  createSession: (opts: SessionOptions) => AgentSession;
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoader;
+  createSessionManager: (cwd: string) => SessionManager;
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  deriveSessionDir: (parentFile: string) => string;
+}
+```
+
+The production call site in `agent-manager.ts` passes a `RunnerIO` built from the real SDK imports.
+Tests pass a stub `RunnerIO` without `vi.mock()`.
+
+Impact: eliminates 5–7 `vi.mock()` calls in `agent-runner.test.ts`; tests verify behavior (turn limits, tool filtering, response collection) through injected fakes; refactoring internal structure no longer breaks tests.
+
+### Step I: Reduce `as any` casts in tests (#134)
+
+With Steps G and H, many `as any` casts disappear because tests construct narrow injectable interfaces instead of wide SDK types.
+Remaining casts are addressed by:
+
+1. Defining a `TestSession` type in `test/helpers/` that satisfies `SubscribableSession` + the fields tests actually read.
+2. Replacing `const mockCtx = { cwd: "/tmp" } as any` with properly typed `AssemblerContext` or `ParentSnapshot` objects.
+3. Using `satisfies` assertions where possible instead of `as any`.
+
+Target: reduce `as any` count from 52 to under 10.
+
+### Step J: Extract display helpers (#135)
+
+`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`:
+
+- Pure formatters: `formatTokens`, `formatSessionTokens`, `formatTurns`, `formatMs`, `formatDuration`.
+- Display helpers: `getDisplayName`, `getPromptModeLabel`, `buildInvocationTags`, `describeActivity`.
+- Constants: `SPINNER`, `ERROR_STATUSES`, `TOOL_DISPLAY`.
+
+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.
+
+### Step K: Decompose agent-menu.ts (#136)
+
+`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.
+
+### Step dependencies
+
+```text
+F (Shared fixtures) ──────────────────────────────┐
+                                                    │
+G (session-config IO injection) ──────────────────┤
+  └── H (agent-runner SDK injection) ────────────┤
+        └── I (Reduce as-any) ────────────────────┘
+
+J (Display extraction) ──────────────────────────┐
+  └── K (Menu decomposition) ────────────────────┘
+```
+
+Steps F through I (testability) and Steps J through K (display/menu) are independent tracks that can proceed in parallel.
+
+---
+
 ## Relationship with upstream
 
 This fork (`@gotgenes/pi-subagents` in the [gotgenes/pi-packages] monorepo) is now a hard fork of [tintinweb/pi-subagents].

package/docs/plans/0116-type-housekeeping.md

@@ -0,0 +1,351 @@
+---
+issue: 116
+issue_title: "refactor(pi-subagents): type housekeeping and small structural cleanups"
+---
+
+# Type housekeeping and small structural cleanups
+
+## Problem Statement
+
+`types.ts` is a type dumping ground — it collects types that don't have a natural home because the module that should own them didn't exist yet.
+With foundation extractions (#108 registry, `parent-snapshot.ts`, `env.ts`, `notification.ts`) now in place, most of these types have a natural home.
+Several other small housekeeping items share the same "polish" character: a closure-bag factory that is a class in disguise, a positional constructor that creates test friction, and a 22-field `AgentConfig` interface consumed by modules that touch 2–4 of its fields.
+
+## Goals
+
+- Move `NotificationDetails` to `notification.ts`, `ParentSnapshot` to `parent-snapshot.ts`, and `EnvInfo` to `env.ts`.
+- Convert `createNotificationSystem` closure to a `NotificationManager` class.
+- Convert `ConversationViewer` constructor from 7 positional parameters to an options bag.
+- Define narrow `AgentConfig` subset interfaces for consumers that use only a few fields.
+- Leave `types.ts` containing only genuinely cross-cutting types: `SubagentType`, `MemoryScope`, `IsolationMode`, `AgentConfig`, `AgentInvocation`, `ShellExec`, and re-exports (`AgentRecord`, `ThinkingLevel`).
+
+## Non-Goals
+
+- Refactoring `AgentConfig` itself (field additions, removals, renames).
+- Changing the `NotificationDeps` interface shape.
+- Modifying `agent-menu.ts` to use narrow subsets — it legitimately reads most `AgentConfig` fields as a config editor/viewer.
+- Touching `invocation-config.ts` — it already receives `AgentConfig | undefined` and only reads invocation-default fields; narrowing its parameter is a separate concern.
+
+## Background
+
+### Prerequisite status
+
+| Issue | Title                             | Status  |
+| ----- | --------------------------------- | ------- |
+| #108  | Extract `AgentTypeRegistry` class | ✅ Done |
+
+`DEFAULT_AGENT_NAMES` was already moved to `AgentTypeRegistry.DEFAULT_AGENT_NAMES` as part of #108.
+The remaining work from the issue's checklist is type relocations, two structural conversions, and narrow subset interfaces.
+
+### Current `types.ts` exports
+
+| Export                                             | Kind      | Should stay?                    |
+| -------------------------------------------------- | --------- | ------------------------------- |
+| `AgentRecord` (re-export)                          | class     | ✅ Cross-cutting                |
+| `AgentRecordInit`, `AgentRecordStatus` (re-export) | type      | ✅ Cross-cutting                |
+| `ThinkingLevel` (re-export)                        | type      | ✅ Cross-cutting                |
+| `SubagentType`                                     | type      | ✅ Cross-cutting                |
+| `MemoryScope`                                      | type      | ✅ Cross-cutting                |
+| `IsolationMode`                                    | type      | ✅ Cross-cutting                |
+| `AgentConfig`                                      | interface | ✅ Cross-cutting                |
+| `AgentInvocation`                                  | interface | ✅ Cross-cutting                |
+| `ShellExec`                                        | type      | ✅ Cross-cutting                |
+| `NotificationDetails`                              | interface | ❌ Move to `notification.ts`    |
+| `ParentSnapshot`                                   | interface | ❌ Move to `parent-snapshot.ts` |
+| `EnvInfo`                                          | interface | ❌ Move to `env.ts`             |
+
+### `createNotificationSystem` closure analysis
+
+The factory in `notification.ts` shares `pendingNudges` (a `Map`) and timer state across 4 inner functions (`cancelNudge`, `scheduleNudge`, `sendCompletion`, `cleanupCompleted`, `dispose`).
+This is a class in disguise — mutable state + methods that read/write it.
+Converting to a `NotificationManager` class makes the state explicit and lets tests use instance methods directly.
+
+### `ConversationViewer` constructor
+
+The constructor takes 7 positional parameters:
+
+```typescript
+constructor(tui, session, record, activity, theme, done, registry)
+```
+
+Every test must reconstruct all 7 in order.
+An options bag reduces friction and is resilient to new parameters.
+
+### `AgentConfig` field usage by consumer
+
+| Consumer                                                   | Fields used                                                                                  |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `agent-widget.ts` (`getDisplayName`, `getPromptModeLabel`) | `name`, `displayName`, `promptMode`                                                          |
+| `tools/helpers.ts` (`formatAgentList`)                     | `name`, `description`, `model`                                                               |
+| `prompts.ts` (`buildAgentPrompt`)                          | `name`, `promptMode`, `systemPrompt`                                                         |
+| `session-config.ts` (`assembleSessionConfig`)              | `name`, `model`, `thinking`, `maxTurns`, `extensions`, `skills`, `memory`, `disallowedTools` |
+| `agent-menu.ts`                                            | Nearly all fields (config viewer/editor)                                                     |
+
+Natural clusters for narrow interfaces:
+
+- **`AgentIdentity`**: `name`, `displayName`, `description`, `promptMode` — UI display and agent listing.
+- **`AgentPromptConfig`**: `name`, `promptMode`, `systemPrompt` — prompt assembly.
+
+`session-config.ts` uses 8 fields; narrowing it yields limited value vs. complexity.
+`invocation-config.ts` receives `AgentConfig | undefined` and reads invocation-default fields; this is a separate concern.
+
+## Design Overview
+
+### Type relocations
+
+Move each type to its natural home module and re-export from `types.ts` during an interim step.
+After updating all importers to point at the new home, remove the re-export.
+This two-phase approach (move + re-export, then update importers + remove re-export) avoids a big-bang commit.
+
+However, since importers are few (2–4 each) and the types are only used internally, a single step per type is simpler: move the type, update all importers in the same commit.
+
+### `NotificationManager` class
+
+Replace the `createNotificationSystem` factory with a class that owns its state:
+
+```typescript
+export class NotificationManager {
+  private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(private deps: NotificationDeps) {}
+
+  cancelNudge(key: string): void { /* ... */ }
+  sendCompletion(record: AgentRecord): void { /* ... */ }
+  cleanupCompleted(id: string): void { /* ... */ }
+  dispose(): void { /* ... */ }
+
+  // private helpers
+  private scheduleNudge(key: string, send: () => void, delay?: number): void { /* ... */ }
+  private emitIndividualNudge(record: AgentRecord): void { /* ... */ }
+}
+```
+
+The `NotificationSystem` interface stays as-is — `NotificationManager implements NotificationSystem`.
+The `NotificationDeps` interface is unchanged.
+Callers in `index.ts` switch from `createNotificationSystem(deps)` to `new NotificationManager(deps)`.
+
+Consumer call site (index.ts):
+
+```typescript
+const notifications = new NotificationManager({
+  sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
+  agentActivity: runtime.agentActivity,
+  markFinished: (id) => runtime.markFinished(id),
+  updateWidget: () => runtime.updateWidget(),
+});
+```
+
+### `ConversationViewer` options bag
+
+Replace positional parameters with a named options interface:
+
+```typescript
+export interface ConversationViewerOptions {
+  tui: TUI;
+  session: AgentSession;
+  record: AgentRecord;
+  activity: AgentActivityTracker | undefined;
+  theme: Theme;
+  done: (result: undefined) => void;
+  registry: AgentConfigLookup;
+}
+
+export class ConversationViewer {
+  constructor(private options: ConversationViewerOptions) {
+    // destructure into private fields or use options.field access
+  }
+}
+```
+
+The existing private fields (`tui`, `session`, `record`, etc.) become reads from `this.options.*` or are destructured in the constructor to named private fields.
+The constructor body (session subscription) is unchanged.
+
+### Narrow `AgentConfig` subset interfaces
+
+Define two narrow interfaces in `types.ts` and make `AgentConfig` extend them:
+
+```typescript
+/** UI display and agent listing — name, display name, description, prompt mode. */
+export interface AgentIdentity {
+  name: string;
+  displayName?: string;
+  description: string;
+  promptMode: "replace" | "append";
+}
+
+/** Prompt assembly — name, prompt mode, system prompt. */
+export interface AgentPromptConfig {
+  name: string;
+  promptMode: "replace" | "append";
+  systemPrompt: string;
+}
+
+export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
+  // remaining fields unchanged
+}
+```
+
+Then update consumers to accept the narrow interface:
+
+- `agent-widget.ts`: `getDisplayName(type, registry)` and `getPromptModeLabel(type, registry)` — these go through `AgentConfigLookup.resolveAgentConfig()`, which returns `AgentConfig`.
+  The narrowing applies to the *return type usage*, not the function signature.
+  No change needed here — the function already destructures only `displayName`, `name`, `promptMode`.
+- `tools/helpers.ts`: `formatAgentList` reads `description`, `model` — these are not in `AgentIdentity`.
+  `model` is session-config territory.
+  Leave as-is.
+- `prompts.ts`: `buildAgentPrompt(config: AgentPromptConfig, ...)` — narrow the parameter type.
+- `AgentConfigLookup.resolveAgentConfig()` return type stays `AgentConfig` — the registry always has the full config.
+
+Since `AgentConfig extends AgentIdentity, AgentPromptConfig`, any code passing an `AgentConfig` to a function expecting the narrow type works without casts.
+
+## Module-Level Changes
+
+### Modified files
+
+1. **`src/types.ts`**
+   - Remove `NotificationDetails`, `ParentSnapshot`, `EnvInfo` interface definitions.
+   - Add `AgentIdentity` and `AgentPromptConfig` interfaces.
+   - Make `AgentConfig` extend `AgentIdentity` and `AgentPromptConfig`.
+   - Remove fields from `AgentConfig` body that are now inherited (`name`, `displayName`, `description`, `promptMode`, `systemPrompt`).
+
+2. **`src/notification.ts`**
+   - Add `NotificationDetails` interface (moved from `types.ts`).
+   - Replace `createNotificationSystem` factory with `NotificationManager` class implementing `NotificationSystem`.
+   - Export `NotificationManager` (named export) and keep `NotificationSystem` interface export.
+   - Remove `createNotificationSystem` export.
+
+3. **`src/parent-snapshot.ts`**
+   - Add `ParentSnapshot` interface (moved from `types.ts`).
+
+4. **`src/env.ts`**
+   - Add `EnvInfo` interface (moved from `types.ts`).
+
+5. **`src/prompts.ts`**
+   - Change `config` parameter type from `AgentConfig` to `AgentPromptConfig`.
+   - Update import to use `AgentPromptConfig` from `./types.js`.
+
+6. **`src/index.ts`**
+   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
+   - Replace `createNotificationSystem(deps)` with `new NotificationManager(deps)`.
+   - Update import: `NotificationManager` from `./notification.js`.
+
+7. **`src/renderer.ts`**
+   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
+
+8. **`src/agent-runner.ts`**
+   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
+
+9. **`src/agent-manager.ts`**
+   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
+
+10. **`src/session-config.ts`**
+    - Update `EnvInfo` import from `./types.js` to `./env.js`.
+
+11. **`src/ui/conversation-viewer.ts`**
+    - Define `ConversationViewerOptions` interface.
+    - Replace 7 positional constructor parameters with single `options: ConversationViewerOptions` parameter.
+    - Assign private fields from `options` in constructor body.
+
+### Unchanged files
+
+- `src/agent-types.ts` — `DEFAULT_AGENT_NAMES` already moved in #108.
+- `src/invocation-config.ts` — narrowing is a separate concern.
+- `src/ui/agent-menu.ts` — legitimately uses most `AgentConfig` fields.
+
+### Test files
+
+12. **`test/notification.test.ts`**
+    - Replace `createNotificationSystem(deps)` calls with `new NotificationManager(deps)`.
+    - Update import.
+    - All existing assertions stay — the public API is identical.
+
+13. **`test/conversation-viewer.test.ts`**
+    - Replace positional `new ConversationViewer(tui, session, record, activity, theme, done, registry)` calls with `new ConversationViewer({ tui, session, record, activity, theme, done, registry })`.
+    - All existing assertions stay.
+
+14. **`test/prompts.test.ts`**
+    - Verify existing test fixtures satisfy `AgentPromptConfig` (they should — tests already pass `name`, `promptMode`, `systemPrompt`).
+    - May need to narrow mock type annotations.
+
+15. **Other test files importing relocated types** (`test/parent-snapshot.test.ts`, `test/renderer.test.ts`)
+    - Update import paths if they import directly from `types.ts` (most import from the source module already).
+
+## Test Impact Analysis
+
+1. **New unit tests enabled:**
+   - `NotificationManager` as a class can be tested with standard `new` + method calls — no factory indirection.
+     However, the existing factory tests are already clean and simply switch to `new NotificationManager(deps)`.
+     No fundamentally new test capabilities.
+
+2. **Existing tests that simplify:**
+   - `conversation-viewer.test.ts` — the options bag makes test construction more readable and resilient to parameter additions.
+     Each test only needs to specify the fields it cares about (with a helper providing defaults).
+   - `prompts.test.ts` — narrower `AgentPromptConfig` parameter means test fixtures can omit 19 irrelevant `AgentConfig` fields.
+
+3. **Existing tests that must stay as-is:**
+   - `notification.test.ts` — all factory tests stay, just switch constructor syntax.
+   - `conversation-viewer.test.ts` — all render and input tests stay, just switch constructor syntax.
+   - `parent-snapshot.test.ts`, `env.test.ts`, `renderer.test.ts` — behavior unchanged.
+
+## TDD Order
+
+1. **Move `NotificationDetails` from `types.ts` to `notification.ts`.**
+   Cut the interface from `types.ts`, paste into `notification.ts`.
+   Update importers: `index.ts`, `renderer.ts` (change import from `./types.js` to `./notification.js`).
+   `notification.ts` already imports from `./types.js` for `AgentRecord` — no circular dependency.
+   Run `pnpm run check`.
+   Commit: `refactor: move NotificationDetails to notification.ts`
+
+2. **Move `ParentSnapshot` from `types.ts` to `parent-snapshot.ts`.**
+   Cut the interface from `types.ts`, paste into `parent-snapshot.ts`.
+   Update importers: `agent-manager.ts`, `agent-runner.ts` (change import from `./types.js` to `./parent-snapshot.js`).
+   Run `pnpm run check`.
+   Commit: `refactor: move ParentSnapshot to parent-snapshot.ts`
+
+3. **Move `EnvInfo` from `types.ts` to `env.ts`.**
+   Cut the interface from `types.ts`, paste into `env.ts`.
+   Update importers: `session-config.ts`, `prompts.ts` (change import from `./types.js` to `./env.js`).
+   `env.ts` already imports `ShellExec` from `./types.js` — no circular dependency.
+   Run `pnpm run check`.
+   Commit: `refactor: move EnvInfo to env.ts`
+
+4. **Convert `createNotificationSystem` to `NotificationManager` class.**
+   Replace the factory with a class implementing `NotificationSystem`.
+   Move `pendingNudges` and timer logic to private instance state.
+   Convert inner functions to methods.
+   Keep `NotificationSystem` interface, `NotificationDeps` interface, and `NUDGE_HOLD_MS` constant unchanged.
+   Remove `createNotificationSystem` export, add `NotificationManager` export.
+   Update `index.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`.
+   Update `test/notification.test.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`, update import.
+   Run `pnpm vitest run test/notification.test.ts`.
+   Commit: `refactor: convert createNotificationSystem to NotificationManager class`
+
+5. **Convert `ConversationViewer` constructor to options bag.**
+   Define `ConversationViewerOptions` interface.
+   Replace 7 positional parameters with `options: ConversationViewerOptions`.
+   Assign private fields from options in constructor body.
+   Update all call sites in `test/conversation-viewer.test.ts` and `src/index.ts` (or wherever `new ConversationViewer(...)` is called).
+   Run `pnpm vitest run test/conversation-viewer.test.ts`.
+   Commit: `refactor: convert ConversationViewer to options bag constructor`
+
+6. **Define narrow `AgentIdentity` and `AgentPromptConfig` interfaces.**
+   Add interfaces to `types.ts`.
+   Make `AgentConfig` extend both; remove inherited fields from `AgentConfig` body.
+   Narrow `prompts.ts` `buildAgentPrompt` parameter from `AgentConfig` to `AgentPromptConfig`.
+   Update `test/prompts.test.ts` type annotations if needed.
+   Run `pnpm run check` and `pnpm vitest run`.
+   Commit: `refactor: define AgentIdentity and AgentPromptConfig subset interfaces`
+
+## Risks and Mitigations
+
+| Risk                                                                                    | Mitigation                                                                                                                                    |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Moving types breaks import paths in files not caught by grep                            | Run `pnpm run check` (full `tsc --noEmit`) after each type relocation step.                                                                   |
+| `NotificationManager` class changes test mock patterns (e.g., spreading instances)      | Tests already use the factory return as an opaque object — switching to `new` is mechanical. No spread patterns in notification tests.        |
+| `ConversationViewer` options bag breaks all test call sites at once                     | All 314 lines of tests use the same 7-arg pattern. A search-and-replace handles it. The options bag is a single-step change.                  |
+| `AgentConfig extends AgentIdentity, AgentPromptConfig` changes structural compatibility | `extends` is purely additive — existing code passing `AgentConfig` anywhere still works. Narrowed consumers gain type safety, nothing breaks. |
+| `prompts.ts` parameter narrowing breaks callers passing `AgentConfig`                   | `AgentConfig extends AgentPromptConfig`, so all existing call sites are compatible without changes.                                           |
+
+## Open Questions
+
+- Whether to define an `AgentSessionConfig` subset for `session-config.ts` (8 fields) — deferred because the narrowing ratio (8 of 22) yields less clarity benefit than `AgentIdentity` (4 of 22) or `AgentPromptConfig` (3 of 22).

package/docs/retro/0115-decompose-agent-tool.md

@@ -0,0 +1,51 @@
+---
+issue: 115
+issue_title: "refactor(pi-subagents): decompose agent-tool.ts into foreground/background modules"
+---
+
+# Retro: #115 — decompose agent-tool.ts into foreground/background modules
+
+## Final Retrospective (2026-05-21T22:30:00-04:00)
+
+### Session summary
+
+Decomposed the 579-line `tools/agent-tool.ts` into focused modules: `foreground-runner.ts` (spinner, streaming, cleanup) and `background-spawner.ts` (activity setup, notification wiring), with `agent-tool.ts` remaining as the orchestrator (411 lines).
+Before extracting, fixed two upstream API gaps: widened `onSessionCreated` callback to `(session, record)` to eliminate a `listAgents()` reverse-search, and added `toolCallId` to `AgentSpawnConfig` so the manager wires `NotificationState` at spawn time.
+Test count increased from 641 to 690.
+Released as `pi-subagents-v6.9.1`.
+
+### Observations
+
+#### What went well
+
+- The revised plan (after user feedback) was structurally clean — fixing API gaps first made the extraction trivial; each extracted module received only what it needed without workarounds.
+- TDD execution was smooth: 6 steps, all green after each commit, only minor deviations (type annotation issue, `index.ts` call-site fix).
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` (user-caught) — The initial plan was a mechanical code-move that defined 4 new interfaces (`ForegroundRunDeps`, `BackgroundSpawnDeps`, `ForegroundRunParams`, `BackgroundSpawnParams`) to paper over two upstream API gaps: a `listAgents()` reverse-search in the foreground `onSessionCreated` callback, and a post-spawn `record.notification` mutation in the background path.
+  The user asked *"What dependencies are still missing for these split tools, that they want, rather than some low level state or collaborators that they have?"*
+  — redirecting me to fix the API surface before extracting.
+  Impact: entire plan rewritten (~15 minutes), but the revised plan was significantly cleaner and the implementation went smoothly.
+
+- `missing-context` (self-identified) — During step 5 (foreground extraction), two tests in `foreground-runner.test.ts` failed because mock sessions were `{}` objects lacking a `subscribe` method required by `subscribeUIObserver`.
+  The function's dependency on `SubscribableSession` (requiring `.subscribe()`) wasn't accounted for in the test mock.
+  Impact: one test fix cycle (~2 minutes), no rework.
+
+- `missing-context` (self-identified) — Annotating `runForeground` with an explicit `Promise<AgentToolResult<any>>` return type widened the content array type from `{ type: "text", text: string }[]` to `(TextContent | ImageContent)[]`, breaking existing `content[0].text` patterns in tests.
+  Fixed by removing the explicit annotation and letting TypeScript infer the narrow type.
+  Impact: three edit cycles to diagnose and fix (~5 minutes).
+
+- `missing-context` (self-identified) — Step 1 removed `listAgents` from `AgentToolManager` but didn't update the construction site in `index.ts`.
+  `pnpm run check` caught it in step 4.
+  Impact: one-line fix in the same commit, no rework.
+
+#### What caused friction (user side)
+
+- The initial plan's size and mechanical nature required a user redirect.
+  The `/plan-issue` prompt's Design Overview section asks to sketch consumer call sites for *new collaborators*, but the same Tell-Don't-Ask check should apply to *extracted* modules' interactions with their upstream dependencies.
+  A prompt tweak could help the agent catch this pattern earlier.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added extraction-specific Tell-Don't-Ask verification step to the Design Overview section: sketch the extracted module's upstream interactions before planning the extraction, fix API gaps first.

package/docs/retro/0116-type-housekeeping.md

@@ -0,0 +1,42 @@
+---
+issue: 116
+issue_title: "refactor(pi-subagents): type housekeeping and small structural cleanups"
+---
+
+# Retro: #116 — type housekeeping and small structural cleanups
+
+## Final Retrospective (2026-05-21T23:00:00Z)
+
+### Session summary
+
+Planned and executed 6 refactoring steps for issue #116: relocated 3 misplaced types from `types.ts` to their natural home modules, converted `createNotificationSystem` closure to a `NotificationManager` class, switched `ConversationViewer` to an options-bag constructor, and defined `AgentIdentity`/`AgentPromptConfig` narrow subset interfaces.
+All 690 tests stayed green throughout; no behavioral changes.
+Released as `pi-subagents-v6.9.2`.
+
+### Observations
+
+#### What went well
+
+- The Python script approach for bulk-converting 16 `ConversationViewer` positional constructor calls to options-bag syntax was efficient and correct on the first attempt — all 17 tests passed immediately after the conversion.
+- Proactive `grep -rn 'new ConversationViewer'` before step 5 caught the `agent-menu.ts` call site that the plan's Module-Level Changes section had omitted, avoiding a broken commit.
+- The architecture doc update was clean — 5 targeted edits to mark E2 done, update smells table, and fix metrics.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In all three type-relocation steps (1–3), I updated source-file imports but did not pre-flight grep for test-file imports of the relocated symbol.
+  Each time, `pnpm run check` caught the stale test import, requiring an extra edit-check round trip.
+  This happened with `test/renderer.test.ts` (step 1), `test/agent-runner.test.ts` + `test/agent-runner-extension-tools.test.ts` (step 2), and `test/prompts.test.ts` (step 3).
+  Impact: 3 unnecessary edit-check cycles; no broken commits since the type checker caught every case before `git commit`.
+
+- `missing-context` — In step 4, the first `Edit` call on `src/index.ts` failed because the autoformatter had merged the `NotificationDetails` type import (added in step 1) into the existing notification import line, changing the text I expected.
+  Had to re-read the file to find the current import text.
+  Impact: one wasted edit call plus a file read; added ~10 seconds of friction.
+
+#### What caused friction (user side)
+
+- No friction observed — the user's prompts were clear and the `/tdd-plan` and `/ship-issue` templates provided all needed structure.
+
+### Takeaway
+
+When relocating a type or symbol, always run `grep -rn 'SymbolName' src/ test/` before editing to identify *all* importers upfront — both source and test files.
+This avoids the repeated pattern of "edit source → type-check fails on test → fix test → type-check again."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.9.1",
+  "version": "6.9.3",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -14,10 +14,11 @@ import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
 import { NotificationState } from "./notification-state.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
-import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 import type { WorktreeManager } from "./worktree.js";
 import { WorktreeState } from "./worktree-state.js";
 

package/src/agent-runner.ts

@@ -15,9 +15,10 @@ import {
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
 import { detectEnv } from "./env.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
 import { assembleSessionConfig } from "./session-config.js";
 import { deriveSubagentSessionDir } from "./session-dir.js";
-import type { ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
+import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];

package/src/env.ts

@@ -3,7 +3,13 @@
  */
 
 import { debugLog } from "./debug.js";
-import type { EnvInfo, ShellExec } from "./types.js";
+import type { ShellExec } from "./types.js";
+
+export interface EnvInfo {
+  isGitRepo: boolean;
+  branch: string;
+  platform: string;
+}
 
 export async function detectEnv(exec: ShellExec, cwd: string): Promise<EnvInfo> {
   let isGitRepo = false;

package/src/index.ts

@@ -18,7 +18,7 @@ import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { buildEventData, createNotificationSystem } from "./notification.js";
+import { buildEventData, type NotificationDetails, NotificationManager } from "./notification.js";
 import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
 import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
@@ -28,7 +28,6 @@ import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
 import { createSteerTool } from "./tools/steer-tool.js";
-import { type NotificationDetails } from "./types.js";
 import { createAgentsMenuHandler } from "./ui/agent-menu.js";
 import {
   AgentWidget,
@@ -48,7 +47,7 @@ export default function (pi: ExtensionAPI) {
   // ---- Notification system ----
   // runtime.widget is assigned after AgentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
-  const notifications = createNotificationSystem({
+  const notifications = new NotificationManager({
     sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
     agentActivity: runtime.agentActivity,
     markFinished: (id) => runtime.markFinished(id),

package/src/notification.ts

@@ -1,8 +1,23 @@
 import { debugLog } from "./debug.js";
-import type { AgentRecord, NotificationDetails } from "./types.js";
+import type { AgentRecord } from "./types.js";
 import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
 import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+  id: string;
+  description: string;
+  status: string;
+  toolUses: number;
+  turnCount: number;
+  maxTurns?: number;
+  totalTokens: number;
+  durationMs: number;
+  outputFile?: string;
+  error?: string;
+  resultPreview: string;
+}
+
 // ---- Pure helpers (exported for unit testing) ----
 
 /** Escape XML special characters to prevent injection in structured notifications. */
@@ -129,23 +144,43 @@ export interface NotificationSystem {
 
 const NUDGE_HOLD_MS = 200;
 
-export function createNotificationSystem(deps: NotificationDeps): NotificationSystem {
-  const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+export class NotificationManager implements NotificationSystem {
+  private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
 
-  function cancelNudge(key: string) {
-    const timer = pendingNudges.get(key);
+  constructor(private deps: NotificationDeps) {}
+
+  cancelNudge(key: string): void {
+    const timer = this.pendingNudges.get(key);
     if (timer != null) {
       clearTimeout(timer);
-      pendingNudges.delete(key);
+      this.pendingNudges.delete(key);
     }
   }
 
-  function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
-    cancelNudge(key);
-    pendingNudges.set(
+  sendCompletion(record: AgentRecord): void {
+    this.deps.agentActivity.delete(record.id);
+    this.deps.markFinished(record.id);
+    this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
+    this.deps.updateWidget();
+  }
+
+  cleanupCompleted(id: string): void {
+    this.deps.agentActivity.delete(id);
+    this.deps.markFinished(id);
+    this.deps.updateWidget();
+  }
+
+  dispose(): void {
+    for (const timer of this.pendingNudges.values()) clearTimeout(timer);
+    this.pendingNudges.clear();
+  }
+
+  private scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS): void {
+    this.cancelNudge(key);
+    this.pendingNudges.set(
       key,
       setTimeout(() => {
-        pendingNudges.delete(key);
+        this.pendingNudges.delete(key);
         try {
           send();
         } catch (err) {
@@ -155,41 +190,21 @@ export function createNotificationSystem(deps: NotificationDeps): NotificationSy
     );
   }
 
-  function emitIndividualNudge(record: AgentRecord) {
+  private emitIndividualNudge(record: AgentRecord): void {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
     const outputFile = record.execution?.outputFile;
     const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
-    deps.sendMessage(
+    this.deps.sendMessage(
       {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, deps.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500, this.deps.agentActivity.get(record.id)),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );
   }
-
-  function sendCompletion(record: AgentRecord) {
-    deps.agentActivity.delete(record.id);
-    deps.markFinished(record.id);
-    scheduleNudge(record.id, () => emitIndividualNudge(record));
-    deps.updateWidget();
-  }
-
-  function cleanupCompleted(id: string) {
-    deps.agentActivity.delete(id);
-    deps.markFinished(id);
-    deps.updateWidget();
-  }
-
-  function dispose() {
-    for (const timer of pendingNudges.values()) clearTimeout(timer);
-    pendingNudges.clear();
-  }
-
-  return { cancelNudge, sendCompletion, cleanupCompleted, dispose };
 }

package/src/parent-snapshot.ts

@@ -4,7 +4,26 @@
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildParentContext } from "./context.js";
-import type { ParentSnapshot } from "./types.js";
+
+/**
+ * Plain data snapshot of the parent session state captured at spawn time.
+ * Replaces live `ExtensionContext` references so queued agents don't read stale state.
+ */
+export interface ParentSnapshot {
+  /** Parent working directory. */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  systemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  model: unknown;
+  /** Model registry for resolving config.model strings and creating sessions. */
+  modelRegistry: {
+    find(provider: string, modelId: string): unknown;
+    getAvailable?(): Array<{ provider: string; id: string }>;
+  };
+  /** Pre-built parent conversation text (when inheritContext was requested). */
+  parentContext?: string;
+}
 
 /**
  * Build an immutable snapshot of the parent session state.

package/src/prompts.ts

@@ -2,7 +2,8 @@
  * prompts.ts — System prompt builder for agents.
  */
 
-import type { AgentConfig, EnvInfo } from "./types.js";
+import type { EnvInfo } from "./env.js";
+import type { AgentPromptConfig } from "./types.js";
 
 /** Extra sections to inject into the system prompt (memory, skills, etc.). */
 export interface PromptExtras {
@@ -27,7 +28,7 @@ export interface PromptExtras {
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(
-  config: AgentConfig,
+  config: AgentPromptConfig,
   cwd: string,
   env: EnvInfo,
   parentSystemPrompt?: string,

package/src/renderer.ts

@@ -1,5 +1,5 @@
 import { Text } from "@earendil-works/pi-tui";
-import type { NotificationDetails } from "./types.js";
+import type { NotificationDetails } from "./notification.js";
 import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
 
 /** Narrow theme interface — only the methods the renderer actually calls. */

package/src/session-config.ts

@@ -15,10 +15,11 @@ import {
   getMemoryToolNames,
   getReadOnlyMemoryToolNames,
 } from "./agent-types.js";
+import type { EnvInfo } from "./env.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
-import type { EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
+import type { SubagentType, ThinkingLevel } from "./types.js";
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 

package/src/types.ts

@@ -18,11 +18,23 @@ export type MemoryScope = "user" | "project" | "local";
 /** Isolation mode for agent execution. */
 export type IsolationMode = "worktree";
 
-/** Unified agent configuration — used for both default and user-defined agents. */
-export interface AgentConfig {
+/** UI display and agent listing — name, display name, description, prompt mode. */
+export interface AgentIdentity {
   name: string;
   displayName?: string;
   description: string;
+  promptMode: "replace" | "append";
+}
+
+/** Prompt assembly — name, prompt mode, system prompt. */
+export interface AgentPromptConfig {
+  name: string;
+  promptMode: "replace" | "append";
+  systemPrompt: string;
+}
+
+/** Unified agent configuration — used for both default and user-defined agents. */
+export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
   builtinToolNames?: string[];
   /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
   disallowedTools?: string[];
@@ -33,8 +45,6 @@ export interface AgentConfig {
   model?: string;
   thinking?: ThinkingLevel;
   maxTurns?: number;
-  systemPrompt: string;
-  promptMode: "replace" | "append";
   /** Default for spawn: fork parent conversation. undefined = caller decides. */
   inheritContext?: boolean;
   /** Default for spawn: run in background. undefined = caller decides. */
@@ -64,48 +74,6 @@ export interface AgentInvocation {
   isolation?: IsolationMode;
 }
 
-/** Details attached to custom notification messages for visual rendering. */
-export interface NotificationDetails {
-  id: string;
-  description: string;
-  status: string;
-  toolUses: number;
-  turnCount: number;
-  maxTurns?: number;
-  totalTokens: number;
-  durationMs: number;
-  outputFile?: string;
-  error?: string;
-  resultPreview: string;
-
-}
-
-/**
- * Plain data snapshot of the parent session state captured at spawn time.
- * Replaces live `ExtensionContext` references so queued agents don't read stale state.
- */
-export interface ParentSnapshot {
-  /** Parent working directory. */
-  cwd: string;
-  /** Parent's effective system prompt (for append-mode agents). */
-  systemPrompt: string;
-  /** Parent's current model instance (fallback when agent config has no model). */
-  model: unknown;
-  /** Model registry for resolving config.model strings and creating sessions. */
-  modelRegistry: {
-    find(provider: string, modelId: string): unknown;
-    getAvailable?(): Array<{ provider: string; id: string }>;
-  };
-  /** Pre-built parent conversation text (when inheritContext was requested). */
-  parentContext?: string;
-}
-
-export interface EnvInfo {
-  isGitRepo: boolean;
-  branch: string;
-  platform: string;
-}
-
 /**
  * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
  * Matches the shape of `pi.exec()` without carrying an SDK dependency.

package/src/ui/agent-menu.ts

@@ -220,7 +220,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
 
     await ctx.ui.custom<undefined>(
       (tui: any, theme: any, _keybindings: any, done: any) => {
-        return new ConversationViewer(tui, session, record, activity, theme, done, deps.registry);
+        return new ConversationViewer({ tui, session, record, activity, theme, done, registry: deps.registry });
       },
       {
         overlay: true,

package/src/ui/conversation-viewer.ts

@@ -20,6 +20,16 @@ const MIN_VIEWPORT = 3;
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 export const VIEWPORT_HEIGHT_PCT = 70;
 
+export interface ConversationViewerOptions {
+  tui: TUI;
+  session: AgentSession;
+  record: AgentRecord;
+  activity: AgentActivityTracker | undefined;
+  theme: Theme;
+  done: (result: undefined) => void;
+  registry: AgentConfigLookup;
+}
+
 export class ConversationViewer implements Component {
   private scrollOffset = 0;
   private autoScroll = true;
@@ -27,16 +37,23 @@ export class ConversationViewer implements Component {
   private lastInnerW = 0;
   private closed = false;
 
-  constructor(
-    private tui: TUI,
-    private session: AgentSession,
-    private record: AgentRecord,
-    private activity: AgentActivityTracker | undefined,
-    private theme: Theme,
-    private done: (result: undefined) => void,
-    private registry: AgentConfigLookup,
-  ) {
-    this.unsubscribe = session.subscribe(() => {
+  private tui: TUI;
+  private session: AgentSession;
+  private record: AgentRecord;
+  private activity: AgentActivityTracker | undefined;
+  private theme: Theme;
+  private done: (result: undefined) => void;
+  private registry: AgentConfigLookup;
+
+  constructor(options: ConversationViewerOptions) {
+    this.tui = options.tui;
+    this.session = options.session;
+    this.record = options.record;
+    this.activity = options.activity;
+    this.theme = options.theme;
+    this.done = options.done;
+    this.registry = options.registry;
+    this.unsubscribe = options.session.subscribe(() => {
       if (this.closed) return;
       this.tui.requestRender();
     });