@gotgenes/pi-subagents 6.9.2 → 6.9.3

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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)
 
 

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,136 +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()`~~             | **Fixed #116**: `NotificationManager` class; `pendingNudges` and timer state are private fields                                                                                   |
-| ~~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`~~                               | **Fixed #116**: `NotificationDetails` → `notification.ts`; `ParentSnapshot` → `parent-snapshot.ts`; `EnvInfo` → `env.ts`; `AgentIdentity` and `AgentPromptConfig` narrow subsets  |
-| ~~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)~~ — **Done**
+#### E2. Type housekeeping (#116)
 
-- Moved `NotificationDetails` from `types.ts` to `notification.ts`.
-- Moved `ParentSnapshot` from `types.ts` to `parent-snapshot.ts` (`DEFAULT_AGENT_NAMES` was already moved in #108).
-- Moved `EnvInfo` from `types.ts` to `env.ts`.
+- 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; `AgentConfig extends` both; `buildAgentPrompt` narrowed to `AgentPromptConfig`.
-
-### Expected impact
-
-| Metric                                     | Before                                                                                 | After   |
-| ------------------------------------------ | -------------------------------------------------------------------------------------- | ------- |
-| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                           | **0** ✓ |
-| Closure-bag "classes"                      | ~~2~~ ~~1~~ **0** (`createNotificationSystem` **fixed #116**; settings **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** ✓ (all moved #116)                                                         | 0 ✓     |
+- 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
 
@@ -526,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/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.2",
+  "version": "6.9.3",
   "exports": {
     ".": "./src/service.ts"
   },