@gotgenes/pi-subagents 6.16.3 → 6.17.1

package/docs/architecture/history/phase-1-api-boundary.md

@@ -0,0 +1,8 @@
+# Phase 1: Export SubagentsService from this package
+
+Added the `SubagentsService` interface, serializable types, `Symbol.for()` accessor functions, and `SUBAGENT_EVENTS` constants as public exports.
+Wired `service-adapter.ts` to wrap `AgentManager` and call `publishSubagentsService()` at extension init.
+
+## Related issues
+
+- #48 — Export SubagentsService from this package

package/docs/architecture/history/phase-2-remove-scheduling.md

@@ -0,0 +1,9 @@
+# Phase 2: Remove scheduling
+
+Deleted `schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`.
+Removed the `schedule` parameter from the `Agent` tool schema.
+Removed scheduler setup and lifecycle hooks from `index.ts`.
+
+## Related issues
+
+- #52 — Remove scheduling

package/docs/architecture/history/phase-3-remove-rpc-groupjoin.md

@@ -0,0 +1,11 @@
+# Phase 3: Remove group-join, ad-hoc RPC; replace output-file
+
+Deleted `group-join.ts`, `cross-extension-rpc.ts` (#49).
+Replaced `output-file.ts` with `SessionManager.create()` + `session-dir.ts` (#61).
+Simplified `index.ts` to use direct individual notifications.
+Lifecycle events emitted on `pi.events` for external consumers.
+
+## Related issues
+
+- #49 — Remove group-join and ad-hoc RPC
+- #61 — Replace output-file with JSONL session transcripts

package/docs/architecture/history/phase-4-implement-service.md

@@ -0,0 +1,8 @@
+# Phase 4: Implement and publish SubagentsService
+
+Wired `service-adapter.ts` to wrap `AgentManager` and call `publishSubagentsService()` at extension init.
+Model strings are resolved inside the adapter.
+
+## Related issues
+
+- #48 — Implement and publish SubagentsService

package/docs/architecture/history/phase-5-decompose-index.md

@@ -0,0 +1,42 @@
+# Phase 5: Decompose index.ts
+
+Extracted tools, notifications, activity tracking, event handlers, and the `/agents` command into separate modules.
+Created `SubagentRuntime` factory to hold session-scoped state.
+
+## index.ts decomposition
+
+The original monolithic `index.ts` has been decomposed into focused modules:
+
+```text
+src/
+├── index.ts                  - slimmed entry point: init, tool registration
+├── runtime.ts                - SubagentRuntime: session-scoped state + methods
+├── tools/
+│   ├── agent-tool.ts         - Agent tool definition, parameter validation, dispatch
+│   ├── foreground-runner.ts  - foreground execution loop (spinner, streaming, result)
+│   ├── background-spawner.ts - background spawn (activity setup, notification wiring)
+│   ├── get-result-tool.ts    - get_subagent_result tool
+│   ├── steer-tool.ts         - steer_subagent tool
+│   └── helpers.ts            - shared tool utilities (textResult, buildDetails, getStatusNote, ...)
+├── handlers/
+│   ├── lifecycle.ts          - session_start, session_before_switch, session_shutdown
+│   └── tool-start.ts         - tool_execution_start handler
+├── notification.ts           - completion nudges, custom renderer
+├── renderer.ts               - notification TUI component
+├── ui/agent-menu.ts          - /agents slash command menu (orchestration, listing, settings)
+├── ui/agent-config-editor.ts - agent detail view (edit/delete/eject/disable/enable)
+├── ui/agent-creation-wizard.ts - agent creation (AI-generation and manual-form)
+├── ui/agent-file-ops.ts      - AgentFileOps interface + FsAgentFileOps implementation
+├── service-adapter.ts        - SubagentsService implementation wrapping AgentManager
+└── (existing domain modules unchanged)
+```
+
+Each extracted module receives narrow constructor-injected dependencies rather than closing over module-level state.
+Handlers call methods on narrow runtime interfaces - no raw field writes, no `widget!` reach-throughs.
+
+## Related issues
+
+- #54 — Decompose index.ts
+- #69 — SubagentRuntime factory
+- #70 — Handler extraction
+- #87 — Runtime methods

package/docs/architecture/history/phase-7-encapsulation.md

@@ -0,0 +1,173 @@
+# Phase 7: Encapsulation and dependency narrowing
+
+Every mutable state bag became a class, every dependency bag narrowed to what its consumer uses, every callback became either a method on a collaborator or an event on an observable.
+
+## AgentManager decomposition
+
+AgentManager was decomposed in three steps to untangle record management, concurrency control, and execution orchestration.
+
+### Step 1: Record state machine (#98, #102)
+
+Extracted status-transition methods (`markRunning`, `markCompleted`, `markAborted`, `markSteered`, `markError`, `markStopped`, `resetForResume`) onto `AgentRecord`.
+Replaced scattered field writes across 6 sites with encapsulated transition methods.
+Issue #102 consolidated test `AgentRecord` construction into a shared factory.
+
+### Step 2: Parent snapshot (#99)
+
+Replaced live `ctx: ExtensionContext` capture in `SpawnArgs` with an immutable `ParentSnapshot` data object.
+The snapshot is taken once at spawn time; queued agents execute against frozen state rather than a potentially stale session reference.
+`runAgent()` accepts `ParentSnapshot` instead of `ctx`.
+`pi: ExtensionAPI` was removed from `SpawnArgs` - `runAgent()` accepts a `ShellExec` function instead.
+
+### Step 3: Session-event observation (#100)
+
+Replaced three-layer callback threading with direct session subscriptions.
+`record-observer.ts` subscribes to the session to update record statistics (tool uses, lifetime usage, compaction count).
+`ui/ui-observer.ts` subscribes to the session to stream UI state (active tools, response text, turn count).
+`SpawnOptions` and `RunOptions` dropped all `on*` callback fields except `onSessionCreated` (which delivers the session object to enable external subscriptions).
+
+### Realized impact
+
+| Metric                            | Before | After                   |
+| --------------------------------- | ------ | ----------------------- |
+| `SpawnOptions` callback fields    | 6      | 1 (`onSessionCreated`)  |
+| `RunOptions` callback fields      | 6      | 1 (`onSessionCreated`)  |
+| Callback layers                   | 3      | 0 (direct subscription) |
+| Live `ctx` references in queue    | 1      | 0 (snapshot)            |
+| Scattered status-transition sites | 6      | 1 (state machine)       |
+
+## Encapsulation roadmap
+
+Phase 7 encapsulated mutable state into classes, replaced callbacks with semantic components, and narrowed dependency bags.
+
+Each step was sequenced so it made the next step easier.
+
+### Resolved smells
+
+All nine smells identified at the start of Phase 7 were resolved:
+
+| 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)
+
+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.
+
+#### A2. SettingsManager class (#109, #118)
+
+Encapsulated settings load/save/apply cycle into `SettingsManager` (in `settings.ts`).
+Owns `defaultMaxTurns`, `graceTurns`, `maxConcurrent` with normalizing property accessors.
+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`.
+
+#### 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; consumers use read-only accessors.
+The shared map on `SubagentRuntime` is `Map<string, AgentActivityTracker>`.
+
+### Step B: Split AgentRecord lifecycle state (#111)
+
+Split post-construction mutation into phase-specific collaborators, each born complete:
+
+- **`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.
+
+### Step C: Replace AgentManager callbacks with observer (#112)
+
+`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
+
+#### D1. Disambiguate SpawnOptions (#113)
+
+Internal `SpawnOptions` in `agent-manager.ts` renamed to `AgentSpawnConfig`.
+Public `SpawnOptions` in `service.ts` unchanged.
+
+#### D2. Narrow AgentToolDeps and AgentMenuDeps (#114)
+
+| 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
+
+#### E1. Split agent-tool.ts foreground/background (#115)
+
+Extracted `foreground-runner.ts` (~175 lines) and `background-spawner.ts` (~116 lines).
+`agent-tool.ts` reduced from 579 → 411 lines.
+
+#### E2. Type housekeeping (#116)
+
+- 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
+
+```mermaid
+flowchart LR
+    A1["A1: Registry"] --> D2["D2: Narrow deps"]
+    A2["A2: Settings"] --> A2b["A2b: Apply"] --> D2
+    A3["A3: Activity Tracker"] --> D2
+    B["B: Record lifecycle"] --> D2
+    B --> C["C: Observer"] --> D1["D1: SpawnOptions"] --> D2
+    D2 --> E1["E1: agent-tool split"]
+    A1 --> E2["E2: Type housekeeping"]
+```
+
+## Related issues
+
+- #98 — Record state machine
+- #99 — Parent snapshot
+- #100 — Session-event observation
+- #102 — Consolidated test AgentRecord construction
+- #108 — AgentTypeRegistry class
+- #109 — SettingsManager class
+- #110 — AgentActivityTracker class
+- #111 — Split AgentRecord lifecycle state
+- #112 — Replace AgentManager callbacks with observer
+- #113 — Disambiguate SpawnOptions
+- #114 — Narrow AgentToolDeps and AgentMenuDeps
+- #115 — Split agent-tool.ts foreground/background
+- #116 — Type housekeeping
+- #118 — SettingsManager apply methods

package/docs/architecture/history/phase-8-testability.md

@@ -0,0 +1,103 @@
+# Phase 8: Testability, display extraction, and menu decomposition
+
+Eliminated `vi.mock()` module mocking in the two most fragile test suites by injecting IO-touching collaborators; consolidated shared test fixtures; extracted display helpers into a reusable module; decomposed the largest UI file.
+
+Steps G and H eliminated 11 of the original 12 `vi.mock()` calls in the runner tests, removing fragile call-sequence assertions in favour of injected stubs.
+Step G resolved `session-config.test.ts`; Step H resolved both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`.
+
+The display and menu improvements were identified during Phase 7 but deferred because they did not gate encapsulation work.
+The display extraction unblocked menu decomposition.
+
+## Test pain points (resolved)
+
+| Symptom                                                       | Resolution                                                     |
+| ------------------------------------------------------------- | -------------------------------------------------------------- |
+| 7 `vi.mock()` calls in `agent-runner.test.ts`                 | Step H (#133): injected `RunnerIO` stubs                       |
+| 7 `vi.mock()` calls in `agent-runner-extension-tools.test.ts` | Step H (#133): same                                            |
+| 52 `as any` casts across test suite                           | Step I (#134): reduced to 15                                   |
+| 3× duplicated `mockSession()`                                 | Step F (#131): shared `createMockSession()` in `test/helpers/` |
+| 3× duplicated `makeDeps()`                                    | Step F (#131): shared `createToolDeps()` in `test/helpers/`    |
+
+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) - confirmed the pattern: 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)
+
+Consolidated duplicated mock factories into `test/helpers/`.
+
+1. `createMockSession()` - subscribable event bus with `emit()` helper; replaced 3 hand-rolled copies.
+2. `createToolDeps()` - builds `AgentToolDeps` with sensible defaults and override support; replaced 3 `makeDeps()` copies.
+3. `makeRecord()` - `AgentRecord` factory with sensible defaults; replaced scattered inline construction.
+4. `STUB_CTX` - shared stub `ExtensionContext` constant; centralised unavoidable bridge casts.
+
+Impact: reduced 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` now accepts `io: AssemblerIO` as a required parameter.
+`index.ts` constructs the real `AssemblerIO` from direct imports via the `RunnerIO.assemblerIO` field (wired in Step H).
+`session-config.test.ts` injects stubs - all 4 `vi.mock()` calls eliminated, assertions shifted to `SessionConfig` output properties.
+
+## Step H: Inject SDK boundary into agent-runner (#133)
+
+`runAgent()` now accepts `io: RunnerIO` as a required parameter bundling all IO collaborators: `detectEnv`, `getAgentDir`, `createResourceLoader`, `deriveSessionDir`, `createSessionManager`, `createSettingsManager`, `createSession`, and `assemblerIO`.
+
+`createAgentRunner(io: RunnerIO): AgentRunner` factory captures the boundary at construction time so `AgentManager` and the `AgentRunner` interface remain unchanged.
+`index.ts` constructs the real `RunnerIO` from Pi SDK imports and sibling modules.
+
+Impact: all 7 `vi.mock()` calls eliminated from both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`; tests verify behavior (turn limits, tool filtering, response collection) through injected stubs; SDK imports moved to the extension entry point.
+
+## Step I: Reduce `as any` casts in tests (#134)
+
+Reduced `as any` count from 93 to 15 (plus 13 explicit `as unknown as T` bridge casts).
+
+Production changes:
+
+- `ResourceLoaderOptions.appendSystemPromptOverride` typed to match `DefaultResourceLoaderOptions`; `createResourceLoader` factory cast removed from `index.ts`.
+- `CreateSessionOptions.settingsManager` / `RunnerIO.createSettingsManager` typed as `SettingsManager`.
+- `WidgetLike` interface in `runtime.ts` narrows the widget field.
+- Local `ToolCallContent` / `BashExecutionMessage` type guards replace `as any` duck-typing in `conversation-viewer.ts` and `agent-runner.ts`.
+- `textResult()` return no longer casts `details as any`.
+- `toAgentSession()` helper and `STUB_CTX` constant centralise unavoidable bridge casts.
+
+Remaining 15 `as any` casts are: 8 menu-handler `ctx as any` (deferred - requires `AgentManager.spawn` to accept `ParentSnapshot` directly), 2 `print-mode.test.ts` (same ExtensionContext/API pattern), 2 private-field test access, 1 `createSession` SDK bridge in `index.ts`, 1 `foreground-runner.ts` `AgentToolResult<any>` detail, 1 `stub-ctx.ts` comment.
+
+## Step J: Extract display helpers (#135)
+
+`ui/display.ts` now contains all pure formatters, display helpers, constants, and shared types (`Theme`, `AgentDetails`).
+`agent-widget.ts` dropped from 522 → ~340 lines.
+All consumer modules (menu, tools, renderer, conversation viewer) import from `ui/display.ts` directly.
+`test/agent-widget.test.ts` renamed to `test/display.test.ts`.
+
+## Step K: Decompose agent-menu.ts (#136)
+
+`agent-menu.ts` (668 lines) decomposed into four modules:
+
+1. `ui/agent-file-ops.ts` - `AgentFileOps` interface (`exists`, `read`, `write`, `remove`, `ensureDir`, `findAgentFile`) + `FsAgentFileOps` production implementation.
+2. `ui/agent-config-editor.ts` - `showAgentDetail` with edit/delete/reset/eject/disable/enable transitions (~200 lines).
+3. `ui/agent-creation-wizard.ts` - AI-generation and manual-form creation paths (~250 lines).
+4. `ui/agent-menu.ts` - menu orchestration, agent listing, running-agent viewer, settings form (~300 lines).
+
+Impact: `agent-menu.ts` dropped from 668 → 296 lines; extracted modules receive `AgentFileOps` via injection; `vi.mock("node:fs")` eliminated from `agent-menu.test.ts`.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    subgraph testability["Testability track"]
+        F["F: Shared fixtures"] --> G["G: session-config IO"] --> H["H: agent-runner SDK"] --> I["I: Reduce as-any"]
+    end
+    subgraph display["Display track"]
+        J["J: Display extraction"] --> K["K: Menu decomposition"]
+    end
+```
+
+The two tracks are independent and can proceed in parallel.
+
+## Related issues
+
+- #131 — Shared test fixtures
+- #132 — Inject IO collaborators into session-config
+- #133 — Inject SDK boundary into agent-runner
+- #134 — Reduce as-any casts in tests
+- #135 — Extract display helpers
+- #136 — Decompose agent-menu.ts

package/docs/architecture/history/phase-9-observation-ctx.md

@@ -0,0 +1,122 @@
+# Phase 9: Observation consolidation, ctx elimination, and remaining mocks
+
+Target: consolidate the dual observation model so stats live in one place; remove `ExtensionContext` from all internal APIs; eliminate remaining `vi.mock()` calls and `as any` casts; split widget rendering from lifecycle; apply dependency bag convention.
+
+## Current smells
+
+| Smell                                             | Location                                                                  | Evidence                                                                                                                       | Severity |
+| ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| `execute` does config resolution for its callees  | `agent-tool.ts` (145-line `execute`)                                      | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep | Medium   |
+| ~~Wide `ctx` in menu handlers~~                   | ~~`agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts`~~ | Resolved by #146: `MenuUI` interface introduced; 42 `ctx as any` casts eliminated across 5 test files                          | Done     |
+| ~~Direct SDK import in `conversation-viewer.ts`~~ | ~~`conversation-viewer.test.ts`~~                                         | Resolved by #147: `wrapText` injected via `ConversationViewerOptions`; `vi.mock("@earendil-works/pi-tui")` eliminated          | Done     |
+| ~~Widget mixes rendering, lifecycle, and state~~  | ~~`agent-widget.ts` (370 lines)~~                                         | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                         | Done     |
+| `deps.` prefix noise in function bodies           | remaining modules across tools, UI, service-adapter                       | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line      | Low      |
+
+## Dependency bag convention
+
+Applied incrementally as each step touches a module:
+
+- **≤4 fields** - accept as plain parameters; drop the interface.
+- **≥5 fields** - keep a named interface but destructure in the function signature (`{ manager, widget }: ForegroundDeps`) so the function body uses bare names, not `deps.foo`.
+
+This eliminates the `deps.` prefix noise across ~124 callsites in 12 modules.
+
+## Step L: Consolidate observation model (#144)
+
+Removed `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
+UI consumers read stats from `AgentRecord` instead of the tracker.
+The UI observer retains event subscriptions for re-render triggers but no longer accumulates stats independently.
+
+Add `session` and `outputFile` convenience getters on `AgentRecord` to hide the `execution?.` traversal.
+The 15+ callsites that navigate `record.execution?.session` simplify to `record.session`.
+
+Apply the dependency bag convention to touched modules: `NotificationDeps` (4 fields) becomes plain parameters on `NotificationManager` constructor.
+
+Impact: eliminates dual counting; removes `??` fallback pattern from widget and conversation viewer; hides `ExecutionState` structure from consumers.
+
+## Step M: Decompose execute and push ExtensionContext to the boundary (#145)
+
+Extracted config resolution into `resolveSpawnConfig` (pure function in `spawn-config.ts`).
+Injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` so `execute` no longer reads `ctx` beyond `ctx.ui` (already delegated to `widget.setUICtx`).
+`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
+`service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
+`foreground-runner` and `background-spawner` receive `ResolvedSpawnConfig` + domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
+
+Dissolved `ForegroundDeps`, `BackgroundDeps`, and `AdapterDeps` into plain parameters.
+`AgentToolDeps` is destructured in the `createAgentTool` signature.
+
+After this step, `ExtensionContext` appears only in:
+
+- `index.ts` closures (wired at extension startup)
+- `service-adapter.ts` (cross-extension boundary)
+- Menu handlers (addressed by Step N)
+
+Impact: `execute` dropped from ~145 to ~25 lines; eliminated 16-field parameter bags; eliminated `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`; foreground/background runner tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
+
+## Step N: Narrow UI context for menu handlers (#146)
+
+Defined `MenuUI` interface (exported from `agent-menu.ts`) with `select`, `confirm`, `input`, `notify`, `editor`, and `custom` methods — the exact subset `ctx.ui` methods used by menu handlers.
+All inner functions in `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts` now accept `(ui: MenuUI)` instead of `(ctx: ExtensionContext)`.
+`index.ts` passes `ctx.ui`, `ctx.modelRegistry`, and `buildParentSnapshot(ctx)` to the handler.
+
+`AgentMenuManager.spawnAndWait` and `WizardManager.spawnAndWait` both accept `ParentSnapshot` (enabled by Step M).
+Creation wizard threads `parentSnapshot` from `showCreateWizard(ui, parentSnapshot)` → `showGenerateWizard(ui, parentSnapshot, targetDir)` → `manager.spawnAndWait(parentSnapshot, ...)`.
+
+Applied the dependency bag convention:
+
+- `AgentConfigEditorDeps` (4 fields), `GetResultDeps` (4 fields), `SteerToolDeps` (4 fields) dissolved into plain parameters.
+- `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) kept as interfaces, destructured in the function signature.
+
+After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures and `service-adapter.ts` (cross-extension bridge).
+
+Impact: eliminated 42 `ctx as any` casts across 5 test files (`agent-menu.test.ts`: 8, `agent-config-editor.test.ts`: 20, `agent-creation-wizard.test.ts`: 14); tests construct plain `MenuUI`-shaped objects with no cast.
+
+## Step O: Inject text wrapping into ConversationViewer (#147)
+
+Accepted `wrapText: (text: string, width: number) => string[]` via `ConversationViewerOptions`.
+`agent-menu.ts` passes the real `wrapTextWithAnsi` import at the `ConversationViewer` construction site.
+Tests inject a stub or the real function directly via options — no module-level mock needed.
+
+Applied the dependency bag convention: `ConversationViewerOptions` is now destructured in the constructor signature.
+
+Impact: eliminated the hoisted `vi.mock("@earendil-works/pi-tui")` from `conversation-viewer.test.ts`; 1 test deleted (mock-mechanism sentinel); net −1 test.
+
+## Step P: Split AgentWidget rendering (#148)
+
+Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
+The widget is now a thin lifecycle/polling wrapper (198 lines, down from 374) that delegates to pure render functions.
+Rendering functions receive data (agent list, activity map, registry) and return formatted strings - testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    subgraph observation["Observation track"]
+        L["L: Consolidate observation #144"] --> P["P: Split widget rendering #148"]
+    end
+    subgraph ctx["ctx elimination track"]
+        M["M: Decompose execute / push ctx #145"] --> N["N: Narrow UI context #146"]
+    end
+    O["O: Inject text wrapping #147"]
+```
+
+The three tracks are independent of each other.
+
+## Projected impact
+
+| Metric                             | Before                   | After                    |
+| ---------------------------------- | ------------------------ | ------------------------ |
+| `vi.mock()` calls remaining        | 4                        | 1 (`print-mode.test.ts`) |
+| `as any` casts remaining           | 45                       | ~5                       |
+| Independent tool-use counters      | 2                        | 1                        |
+| `record.execution?.` traversals    | 15+                      | 0                        |
+| `ExtensionContext` in domain types | 1 (`AgentManager.spawn`) | 0                        |
+| `deps.` prefix accesses            | ~124                     | 0                        |
+
+## Related issues
+
+- #144 — Consolidate observation model
+- #145 — Decompose execute and push ExtensionContext to boundary
+- #146 — Narrow UI context for menu handlers
+- #147 — Inject text wrapping into ConversationViewer
+- #148 — Split AgentWidget rendering

package/docs/plans/0147-inject-wrap-text-into-conversation-viewer.md

@@ -0,0 +1,166 @@
+---
+issue: 147
+issue_title: "Inject text wrapping into ConversationViewer (Phase 9, Step O)"
+---
+
+# Inject text wrapping into ConversationViewer
+
+## Problem Statement
+
+`ConversationViewer` calls `wrapTextWithAnsi` directly from `@earendil-works/pi-tui` in four places inside `buildContentLines`.
+Because the function is a module-level binding, tests must intercept it via a hoisted `vi.mock("@earendil-works/pi-tui")` factory that replaces the entire TUI module.
+This is the last `vi.mock` on an SDK module in the test suite, added specifically to exercise the overwidth-clamping safety net.
+
+## Goals
+
+- Accept `wrapText: (text: string, width: number) => string[]` via `ConversationViewerOptions`.
+- Destructure `ConversationViewerOptions` in the constructor signature (dependency bag convention).
+- Replace all four `wrapTextWithAnsi` calls in `buildContentLines` with `this.wrapText`.
+- Remove `wrapTextWithAnsi` from `conversation-viewer.ts`'s `@earendil-works/pi-tui` import.
+- Pass `wrapTextWithAnsi` at the production call site in `agent-menu.ts`.
+- Eliminate the hoisted `vi.mock("@earendil-works/pi-tui")` from `conversation-viewer.test.ts`.
+
+## Non-Goals
+
+- Injecting `truncateToWidth` or any other TUI function (only `wrapTextWithAnsi` is relevant here).
+- Changing the overwidth-clamping behavior of `buildContentLines`.
+- Touching `agent-widget.ts` (tracked separately as Issue #148, Step P — already closed).
+
+## Background
+
+`ui/conversation-viewer.ts` is the live conversation overlay rendered when a user selects an agent in the `/agents` menu.
+Its `buildContentLines` method formats messages from the agent session into displayable lines, calling `wrapTextWithAnsi` to soft-wrap text to the available terminal width.
+
+The overwidth-clamping safety net (`truncateToWidth` applied after `wrapTextWithAnsi`) exists because a prior upstream bug returned lines wider than the requested width.
+The `vi.mock` in the test is the mechanism for simulating that bug by returning overwidth strings from `wrapTextWithAnsi`.
+
+The only production call site for `new ConversationViewer(...)` is in the `viewAgentConversation` closure inside `createAgentsMenuHandler` in `ui/agent-menu.ts`.
+
+Architecture reference: `docs/architecture/architecture.md` § Phase 9, Step O.
+
+## Design Overview
+
+### `ConversationViewerOptions` — add `wrapText`
+
+```typescript
+export interface ConversationViewerOptions {
+  tui: TUI;
+  session: AgentSession;
+  record: AgentRecord;
+  activity: AgentActivityTracker | undefined;
+  theme: Theme;
+  done: (result: undefined) => void;
+  registry: AgentConfigLookup;
+  wrapText: (text: string, width: number) => string[];
+}
+```
+
+The field is **required** — it must be supplied at every construction site.
+No default is provided; the default would be an invisible SDK dependency hidden inside the class.
+
+### Constructor destructuring
+
+The constructor adopts the dependency bag convention — destructure the options object rather than accessing via `options.*`:
+
+```typescript
+constructor({
+  tui, session, record, activity, theme, done, registry, wrapText,
+}: ConversationViewerOptions) {
+  this.tui = tui;
+  this.session = session;
+  // … etc.
+  this.wrapText = wrapText;
+  this.unsubscribe = session.subscribe(() => { … });
+}
+```
+
+### Production wiring — `agent-menu.ts`
+
+`agent-menu.ts` statically imports `wrapTextWithAnsi` from `@earendil-works/pi-tui` and passes it when constructing `ConversationViewer`:
+
+```typescript
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+// …
+return new ConversationViewer({
+  tui, session, record, activity, theme, done, registry,
+  wrapText: wrapTextWithAnsi,
+});
+```
+
+Adding `wrapText` to `AgentMenuDeps` and threading it through the closure would violate the Law of Demeter — `AgentMenuDeps` has no conceptual ownership of a text-wrapping function.
+The `viewAgentConversation` closure is the direct consumer; the import belongs there.
+
+### Test strategy
+
+After DI, tests pass `wrapText` directly in `ConversationViewerOptions`:
+
+- **"render width safety" tests**: pass `wrapText: wrapTextWithAnsi` (real function, statically imported — no mock).
+- **"safety net" tests**: pass a stub `wrapText: () => ["X".repeat(width + 50)]` inline in options — no `vi.mock` needed.
+- The "mock is intercepting wrapTextWithAnsi" test is removed (it verified the mock mechanism, not viewer behavior).
+- The module-level `wrapOverride` variable and the `vi.mock` block are removed entirely.
+- The `await import("@earendil-works/pi-tui")` and `await import("../src/ui/conversation-viewer.js")` dynamic imports are converted to ordinary top-level `import` statements.
+
+## Module-Level Changes
+
+| File                               | Change                                                                                                                                                                                                                                                       |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/ui/conversation-viewer.ts`    | Add `wrapText` field to `ConversationViewerOptions`; add `private wrapText` field; destructure options in constructor; replace 4× `wrapTextWithAnsi(...)` with `this.wrapText(...)`; remove `wrapTextWithAnsi` from the `@earendil-works/pi-tui` import line |
+| `src/ui/agent-menu.ts`             | Add `import { wrapTextWithAnsi } from "@earendil-works/pi-tui"`; pass `wrapText: wrapTextWithAnsi` in `viewAgentConversation`                                                                                                                                |
+| `test/conversation-viewer.test.ts` | Convert top-level dynamic `await import()` to static imports; remove `vi.mock`, `wrapOverride`, and "mock is intercepting" test; add `wrapText` to every `new ConversationViewer({…})` call; update safety-net tests to pass inline stub `wrapText`          |
+
+No symbols are removed from exported API (`ConversationViewerOptions`, `ConversationViewer`, `VIEWPORT_HEIGHT_PCT` all remain).
+The `wrapText` addition to `ConversationViewerOptions` is a breaking change for any external consumers that construct `ConversationViewer` — check for usages outside this package.
+
+Grep check: `ConversationViewer` appears only in `src/ui/conversation-viewer.ts`, `src/ui/agent-menu.ts`, and `test/conversation-viewer.test.ts` — no other files construct it.
+
+## Test Impact Analysis
+
+1. **New unit-test capability**: The safety-net tests can now inject exactly the stub they need without patching a module.
+   Each test is self-contained and immediately legible — the stub is declared inline at the call site.
+
+2. **Tests that become redundant**: The "mock is intercepting wrapTextWithAnsi" test verified the test mechanism, not production behavior.
+   It is deleted.
+   The `wrapOverride` reset in `beforeEach` is no longer needed.
+
+3. **Tests that stay**: All "render width safety" tests and all overwidth-clamping tests remain; they exercise real viewer behavior with real or controlled inputs.
+
+## TDD Order
+
+### Cycle 1 — Add `wrapText` field and update production wiring
+
+1. **Red**: Update one `new ConversationViewer({…})` in the test to include `wrapText: vi.fn()` — TypeScript rejects the unknown field.
+2. **Green**:
+   - Add `wrapText: (text: string, width: number) => string[]` to `ConversationViewerOptions`.
+   - Add `private wrapText: (text: string, width: number) => string[]` field to the class.
+   - Destructure options in the constructor; assign `this.wrapText = wrapText`.
+   - Replace all four `wrapTextWithAnsi(...)` calls with `this.wrapText(...)` in `buildContentLines`.
+   - Remove `wrapTextWithAnsi` from the `@earendil-works/pi-tui` import in `conversation-viewer.ts`.
+   - In `agent-menu.ts`: add static import of `wrapTextWithAnsi` from `@earendil-works/pi-tui`; pass `wrapText: wrapTextWithAnsi`.
+   - Update **all** `new ConversationViewer({…})` calls in `conversation-viewer.test.ts` to include `wrapText`.
+     "Render width safety" tests pass `wrapText: wrapTextWithAnsi` (real function, still imported via the existing `vi.mock` shim for now).
+     Safety-net tests pass a stub inline: `wrapText: () => ["X".repeat(w + 50)]`.
+   - Delete the "mock is intercepting wrapTextWithAnsi" test.
+3. **Verify**: `pnpm vitest run test/conversation-viewer.test.ts` passes.
+4. **Commit**: `feat: inject wrapText into ConversationViewer (Phase 9, Step O) (#147)`
+
+### Cycle 2 — Remove the module mock
+
+1. **Red**: Remove the `vi.mock("@earendil-works/pi-tui", …)` block, the `wrapOverride` variable, and the `beforeEach(() => { wrapOverride = null; })` reset.
+   Convert `const { visibleWidth } = await import("@earendil-works/pi-tui")` to `import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui"`.
+   Convert `const { ConversationViewer } = await import("../src/ui/conversation-viewer.js")` to `import { ConversationViewer } from "../src/ui/conversation-viewer.js"`.
+   Run tests — they should still pass (the mock was no longer needed after Cycle 1).
+2. **Green**: Tests pass without any module mock.
+3. **Verify**: `pnpm vitest run test/conversation-viewer.test.ts` and `pnpm run check` both pass.
+4. **Commit**: `refactor: remove vi.mock from conversation-viewer tests (#147)`
+
+## Risks and Mitigations
+
+| Risk                                                                              | Mitigation                                                                                             |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Missing a `new ConversationViewer({…})` call site in tests                        | Grep confirms only `test/conversation-viewer.test.ts` constructs the viewer; all instances are in-file |
+| TypeScript missing the `private wrapText` field type                              | Use `pnpm run check` after Cycle 1 to verify no type errors                                            |
+| The dynamic `await import()` pattern in tests was necessary for some other reason | The only purpose was to run after `vi.mock` hoisting; once the mock is gone, static imports work fine  |
+
+## Open Questions
+
+None — the issue's "Changes" section is unambiguous and the call-site inventory is small.