@jopqior/pi-subagents 1.0.0

package/docs/architecture/history/phase-21-classification-model-boundary.md

@@ -0,0 +1,107 @@
+# Phase 21: Classification predicates, resume completion, model boundary
+
+Phase 21 is a lean, three-step phase.
+Discovery (2026-07-17: architecture-doc reading, issue sweep, fallow baseline, repeated-discriminator sweep, entry-point trace, craftsmanship scout) found the declared target architecture essentially complete: fallow reports 0 refactoring targets, 0 dead code, 0 duplication, and the craftsmanship scout refuted both fallow "giant test file" flags and found only scattered boy-scout polish.
+Three cause-level Category C findings survived — two already filed as issues, one the explicitly deferred remainder of Phase 20 Step 4 — and they are the whole phase.
+No polish step is manufactured to fill the ceiling; the scout's scattered findings (`mock.calls[N][idx]` indexing in the two lifecycle test suites, the `settings.ts` `sanitize()` range-check triplication, `createManager`'s nullish-coalescing density) are handed to the `tidy-first` boy-scout path.
+
+## Health metrics
+
+| Metric                                                            | Phase 20 (end) | Phase 21 target | Recompute                                                                                                             |
+| ----------------------------------------------------------------- | -------------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Health score                                                      | 78/100 (B)     | ≥ 78 (B)        | `pnpm fallow health --score --workspace @gotgenes/pi-subagents`                                                       |
+| Multi-status classification groupings outside `subagent-state.ts` | 11             | ≤ 2 → 2 ✅      | `grep -rEn 'status [!=]== "[a-z]+" (\|\||&&) ' packages/pi-subagents/src --include="*.ts" \| grep -vc subagent-state` |
+| `model`/`parentModel` typed `unknown` in `src/`                   | 7              | 0 ✅            | `grep -rEn "model\??: unknown\|parentModel\??: unknown" packages/pi-subagents/src --include="*.ts" \| wc -l`          |
+| Direct `this.mark*` calls inside `resume()`                       | 2              | 0               | `sed -n '/async resume(/,/^\t}/p' packages/pi-subagents/src/lifecycle/subagent.ts \| grep -c 'this\.mark'`            |
+| Dead code / production duplication                                | 0 / 0          | 0 / 0           | `pnpm fallow dead-code --workspace @gotgenes/pi-subagents` / `pnpm fallow dupes --workspace @gotgenes/pi-subagents`   |
+
+All three targeted metrics were confirmed delivered at archive time (recomputed 2026-07): the classification-grouping grep lands at 2, the `model`/`parentModel` `unknown` grep lands at 0, and the `resume()` `this.mark*` grep lands at 0.
+The recomputed health score reproduces 78/100 (B) using the `--hotspots --targets` form (the bare `--score` form reports 88 A on this workspace — the two forms diverge, and 78 B is the form the baseline was computed with).
+
+## ✅ Step 1 — Add classification predicates to `SubagentState` ([#563])
+
+Cause: the state machine owns its six status transitions (design principle 9, "state owns its mutations") but not what a status _means_ — consumers re-derive the is-active (`running \|\| queued`), terminal-error (`error \|\| stopped \|\| aborted`), and steer/run-eligibility groupings at 11 sites across 8 files, so adding a status means finding every grouping and a missed one diverges silently.
+Fallow is structurally blind to this smell (scattered one-line conditionals never form a token-run clone); the repeated-discriminator sweep is the detector, and it corroborates [#563]'s site list exactly.
+Smell: Category C (repeated discriminator / anemic classification).
+Target files: `src/lifecycle/subagent-state.ts` (instance predicates such as `isActive()` / `isTerminalError()` / `canBeSteered()`, plus exported status-level predicate functions for DTO consumers, with the instance predicates delegating so the module stays the single owner); consumers in `src/lifecycle/subagent.ts`, `src/lifecycle/subagent-manager.ts`, `src/tools/get-result-tool.ts`, `src/tools/background-spawner.ts`, `src/ui/widget-renderer.ts`, `src/ui/agent-widget.ts`, `src/ui/session-navigation.ts`, `src/observation/renderer.ts`, `src/observation/subagent-events-observer.ts`.
+The per-status renderer arms (`result-renderer.ts`, `widget-renderer.ts` status→icon maps, `resolveStatusPresentation`) are legitimate presentation dispatch and stay.
+Outcome: multi-status classification groupings outside `subagent-state.ts` drop 11 → ≤ 2 (any residual site is a single-status presentation or wait check, not a re-derived grouping).
+Impact 3 / Risk 1 / Priority 15.
+
+Landed: `isActiveStatus` / `isTerminalErrorStatus` / `isRunningStatus` are exported from `subagent-state.ts` as the single decision point; `SubagentState` (and the delegating `Subagent`) gained `isActive()` / `isTerminalError()` / `isRunning()` / `canBeSteered()`, both instance and status-level predicates delegating to the same functions.
+Record holders (`subagent-manager.ts` ×4, `get-result-tool.ts`, `subagent.ts` `guardedRun`/`steer`/`abort`, `subagent-events-observer.ts`) call the instance methods; DTO holders (`widget-renderer.ts`, `renderer.ts`, `session-navigation.ts`) call the exported functions, with `NotificationDetails.status` and `WidgetAgent.status` tightened to `SubagentStatus`.
+The three targeted groupings are gone outside `subagent-state.ts`; the grep lands at 2 (meets ≤ 2), both residuals being presentation/single-status the phase excludes — `result-renderer.ts`'s `completed \|\| steered` renderer arm and `get-result-tool.ts`'s `running` wait guard.
+
+Release: independent
+
+## ✅ Step 2 — Route resume termination through the completion channel ([#466])
+
+Cause: dual completion channels — `Subagent.resume()` terminates via direct `markCompleted`/`markError` and never invokes `onRunFinished`, so the manager-level observer chain (public `subagents:completed`/`failed` events, `subagents:record` persistence, completion notification) never observes a resumed completion; completion signalling is fused to the _first_ run instead of owned by run termination generally.
+This is a user-visible bug: after a resume, the persisted history shows the pre-resume result and external `SUBAGENT_EVENTS` subscribers never see the second finish.
+Smell: Category C (coupling/boundary flaw), plus `bug`.
+Design decision to resolve at `/plan-issue` time: a distinct resumed-completion event versus a `resumed: true` discriminator on the existing channels — the issue leans distinct-event because the once-per-session `session-created` → `disposed` child-lifecycle arc is load-bearing for pi-permission-system's registry bracket.
+Invariant: do not perturb the child-lifecycle event ordering.
+Target files: `src/lifecycle/subagent.ts` (share the termination path with `completeRun`/`failRun`), `src/lifecycle/subagent-session.ts` (`resumeTurnLoop` result shape), `src/observation/subagent-events-observer.ts`, `src/service/service.ts` (`SUBAGENT_EVENTS`, if a new channel is chosen), and this document's lifecycle-events table.
+Soft-depends on Step 1: both edit `subagent.ts`'s status guards, and Step 1's predicates make the shared termination guard cleaner.
+Outcome: direct `this.mark*` calls inside `resume()` drop 2 → 0; a resumed completion produces a notification, an updated persisted record, and a public event, each pinned by a regression test.
+Impact 4 / Risk 2 / Priority 16.
+
+Landed: the design decision resolved to a **distinct** `subagents:resumed` channel (single channel — the payload's `status`/`error` discriminate completed from error) and a **silent** child-lifecycle (no `subagents:child:*` on resume), so `subagent-session.ts` was untouched (`resumeTurnLoop` stays `Promise<string>`).
+`Subagent.resume()` now routes through new `completeResume`/`failResume` methods (the two direct `this.mark*` calls in `resume()` are gone), which fire a new optional `SubagentLifecycleObserver.onResumeFinished`; `buildObserver()` maps it, background-gated, onto a new required `SubagentManagerObserver.onSubagentResumed`.
+`SubagentEventsObserver.onSubagentResumed` emits `subagents:resumed` (via the shared `persistAndNotify` extracted from `onSubagentCompleted`) and re-appends `subagents:record`; the notification stays consumption-gated.
+Regression tests pin the emit/append/notify chain, the observer wiring, and the background-only gate.
+
+Release: independent
+
+## ✅ Step 3 — Finish typing the model boundary ([#611])
+
+Cause: the SDK model boundary is half-typed — Phase 20 Step 4 typed the resolver/tools layer against `Model<any>` but explicitly deferred the snapshot/session-assembly thread, leaving `model: unknown` at 7 sites, an `as Model<any>` cast in `src/runtime.ts`, and a `ctx.modelRegistry!` assertion in `src/lifecycle/parent-snapshot.ts`.
+Feasibility probed against the real surface: `ExtensionContext.model: Model<any> \| undefined` and `ModelRegistry` are exported by `@earendil-works/pi-coding-agent` (`dist/core/extensions/types.d.ts`), and `src/session/model-resolver.ts` already imports `Model<any>` from `@earendil-works/pi-ai`.
+Smell: Category C (platform type threading).
+Target files: `src/lifecycle/parent-snapshot.ts`, `src/types.ts` (`SessionContext.model`), `src/session/session-config.ts`, `src/lifecycle/create-subagent-session.ts`, `src/runtime.ts`.
+Outcome: `model`/`parentModel` `unknown` sites drop 7 → 0; the `runtime.ts` cast and the `parent-snapshot.ts` non-null assertion are removed.
+Impact 3 / Risk 1 / Priority 15.
+
+Landed: `SessionContext.model` / `ParentSnapshot.model` / `AssemblerContext.parentModel` / `AssemblerOptions.model` / `SessionConfig.model` and `resolveDefaultModel`'s parameter and return are typed against `Model<any>` (imported from `@earendil-works/pi-ai`); the `modelRegistry` fields on `SessionContext`, `ParentSnapshot`, `AssemblerContext`, and `CreateSessionOptions` are typed against the shared `ModelRegistry` (from `model-resolver`), collapsing the two duplicated inline structural types.
+`SessionContext.modelRegistry` is now non-optional (matching the SDK's `ExtensionContext`), which let the `parent-snapshot.ts` `ctx.modelRegistry!` assertion and the `runtime.ts` `as Model<any>` cast both drop.
+The recompute grep lands at 0.
+
+Release: independent
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    S1["✅ Step 1 (#563)<br/>Classification predicates"] -.soft.-> S2["✅ Step 2 (#466)<br/>Resume completion channel"]
+    S3["✅ Step 3 (#611)<br/>Type the model boundary"]
+```
+
+## Parallel tracks
+
+- **Track A — Tell-don't-ask:** Steps 1 → 2 (soft ordering; both edit `subagent.ts`).
+- **Track B — SDK boundary:** Step 3 (fully independent).
+
+## Release batches
+
+- No batches; every step is independently releasable.
+- Independently releasable: Steps 1, 2, 3.
+- Step 2 lands as `fix:` — the phase's unhidden release vehicle; Steps 1 and 3 land as `refactor:` (hidden changelog types) and auto-batch into the next unhidden release.
+
+## Deferred work (explicit dispositions, 2026-07-17)
+
+- [#451] (CI/lint gate validating Mermaid diagrams with `mmdc`) — deferred with rationale: repo-level CI tooling, not pi-subagents structure; it does not belong to a package structural phase.
+  Second consecutive sweep, so this is an explicit decision, not a silent re-defer.
+- [#465], [#482], [#608] (feature requests) and [#519], [#600], [#610] (cross-package pi-permission-system tracks) — deferred with rationale: feature and cross-package work that does not gate this package's structural phase.
+  Step 2 ([#466]) is a prerequisite for [#465]'s ask-back design, so landing this phase unblocks that track.
+- Craftsmanship polish (scout inventory: `mock.calls[N][idx]` → `toHaveBeenCalledWith` in `test/lifecycle/subagent.test.ts` and `test/lifecycle/subagent-manager.test.ts`, `settings.ts` `sanitize()` range-check triplication, `createManager` fixture density, two `as any` private-state reaches) — deferred to the `tidy-first` boy-scout path; all clusters scored below the phase-step bar and the scout recommends incidental pickup.
+
+[#451]: https://github.com/gotgenes/pi-packages/issues/451
+[#465]: https://github.com/gotgenes/pi-packages/issues/465
+[#466]: https://github.com/gotgenes/pi-packages/issues/466
+[#482]: https://github.com/gotgenes/pi-packages/issues/482
+[#519]: https://github.com/gotgenes/pi-packages/issues/519
+[#563]: https://github.com/gotgenes/pi-packages/issues/563
+[#600]: https://github.com/gotgenes/pi-packages/issues/600
+[#608]: https://github.com/gotgenes/pi-packages/issues/608
+[#610]: https://github.com/gotgenes/pi-packages/issues/610
+[#611]: https://github.com/gotgenes/pi-packages/issues/611

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