@gotgenes/pi-subagents 18.0.1 → 18.0.3

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

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

package/docs/plans/0144-consolidate-observation-model.md

@@ -1,263 +0,0 @@
----
-issue: 144
-issue_title: "Consolidate observation model (Phase 9, Step L)"
----
-
-# Consolidate observation model
-
-## Problem Statement
-
-`record-observer.ts` and `ui-observer.ts` independently count tool uses and accumulate lifetime usage from the same session events.
-`AgentRecord` owns `_toolUses` and `_lifetimeUsage` (accumulated by the record observer), while `AgentActivityTracker` maintains its own `_toolUses` and `_lifetimeUsage` (accumulated by the UI observer).
-Consumers use `activity?.toolUses ?? record.toolUses` fallbacks to paper over the ambiguity.
-
-Separately, 15+ callsites navigate `record.execution?.session` and `record.execution?.outputFile`, leaking the `ExecutionState` structure to every consumer.
-
-Finally, `NotificationDeps` (4 fields) is a dependency bag on a class where every method uses every field — plain constructor parameters are simpler.
-
-## Goals
-
-- Remove `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker` so stats have a single source of truth on `AgentRecord`.
-- Update UI consumers (widget, conversation viewer, notification, foreground runner) to read stats from `AgentRecord` instead of the tracker.
-- Remove the `onToolEnd` counter and `onUsageUpdate` accumulator from `AgentActivityTracker`, keeping only live UI state (active tools, response text, turn count).
-- Stop the UI observer from duplicating `tool_execution_end` counting and `message_end` usage accumulation.
-- Add `session` and `outputFile` convenience getters on `AgentRecord` to hide the `execution?.` traversal.
-- Replace `NotificationDeps` interface with plain parameters on `NotificationManager` constructor.
-
-## Non-Goals
-
-- Splitting `AgentWidget` rendering into pure functions (Step P / #148 — depends on this work).
-- Narrowing `ExtensionContext` for menu handlers (Step N / #146 — independent track).
-- Injecting text wrapping into `ConversationViewer` (Step O / #147 — independent track).
-
-## Background
-
-### Dual counting
-
-Both observers subscribe to the same session events:
-
-| Event                 | `record-observer.ts`         | `ui-observer.ts`                      |
-| --------------------- | ---------------------------- | ------------------------------------- |
-| `tool_execution_end`  | `record.incrementToolUses()` | `tracker.onToolEnd()` → `_toolUses++` |
-| `message_end` (usage) | `record.addUsage(delta)`     | `tracker.onUsageUpdate(delta)`        |
-
-The widget reads `bg?.toolUses ?? a.toolUses` and the conversation viewer reads `this.activity?.toolUses ?? this.record.toolUses`, preferring the tracker when alive and falling back to the record.
-After this change, there is one source: `AgentRecord`.
-
-### `execution?.` traversal
-
-`ExecutionState` holds `session` and `outputFile`.
-These are set once when the agent session is created (`agent-manager.ts` line 276).
-Consumers reach through `record.execution?.session` and `record.execution?.outputFile` in 12 distinct locations across 7 files.
-Convenience getters on `AgentRecord` eliminate the traversal and hide the `ExecutionState` structure.
-
-### `NotificationDeps` bag
-
-`NotificationManager` receives 4 fields via `NotificationDeps`: `sendMessage`, `agentActivity`, `markFinished`, `updateWidget`.
-Every method on the class uses every field.
-Per code-design convention (dependency width), a 4-field interface where every consumer uses every field is fine as a bag, but the architecture doc explicitly calls for plain parameters here.
-This is a mechanical change.
-
-## Design Overview
-
-### AgentActivityTracker changes
-
-Remove `_toolUses`, `_lifetimeUsage`, `onToolEnd`, `onUsageUpdate`, `toolUses` getter, and `lifetimeUsage` getter.
-Retain: `_activeTools`, `_toolKeySeq`, `_responseText`, `_session`, `_turnCount`, `_maxTurns`, and their associated transition methods and getters.
-
-`onToolStart` stays (tracks active tools for the widget spinner).
-A new `onToolDone(toolName)` method replaces `onToolEnd` — it removes the tool from `_activeTools` without incrementing any counter.
-This rename clarifies that the method only manages the active-tool display set.
-
-### UI observer changes
-
-The UI observer stops calling counter/accumulator methods:
-
-- `tool_execution_end` handler: calls `tracker.onToolDone(name)` (active-tool tracking only).
-- `message_end` handler: removed entirely (no more usage accumulation).
-  The `onUpdate?.()` call for usage re-render moves to the record observer path via the existing widget update flow.
-
-### AgentRecord convenience getters
-
-```typescript
-get session(): AgentSession | undefined {
-  return this.execution?.session;
-}
-
-get outputFile(): string | undefined {
-  return this.execution?.outputFile;
-}
-```
-
-Callers change from `record.execution?.session` to `record.session`.
-The `execution` field remains writable (set by `AgentManager`), but consumers no longer need to know about `ExecutionState`.
-
-### Consumer migration
-
-| File                       | Before                                             | After                                            |
-| -------------------------- | -------------------------------------------------- | ------------------------------------------------ |
-| `agent-widget.ts`          | `bg?.toolUses ?? a.toolUses`                       | `a.toolUses`                                     |
-| `agent-widget.ts`          | `getLifetimeTotal(bg?.lifetimeUsage)`              | `getLifetimeTotal(a.lifetimeUsage)`              |
-| `agent-widget.ts`          | `getSessionContextPercent(bg?.session)`            | `getSessionContextPercent(a.session)`            |
-| `conversation-viewer.ts`   | `this.activity?.toolUses ?? this.record.toolUses`  | `this.record.toolUses`                           |
-| `conversation-viewer.ts`   | `getLifetimeTotal(this.activity?.lifetimeUsage)`   | `getLifetimeTotal(this.record.lifetimeUsage)`    |
-| `conversation-viewer.ts`   | `getSessionContextPercent(this.activity?.session)` | `getSessionContextPercent(this.record.session)`  |
-| `notification.ts`          | `record.execution?.session`                        | `record.session`                                 |
-| `notification.ts`          | `record.execution?.outputFile`                     | `record.outputFile`                              |
-| `tools/get-result-tool.ts` | `record.execution?.session`                        | `record.session`                                 |
-| `tools/steer-tool.ts`      | `record.execution?.session`                        | `record.session`                                 |
-| `agent-menu.ts`            | `record.execution?.session`                        | `record.session`                                 |
-| `service-adapter.ts`       | `record.execution?.session`                        | `record.session`                                 |
-| `agent-manager.ts`         | `record.execution?.session`                        | `record.session` (in dispose paths)              |
-| `foreground-runner.ts`     | `fgState.toolUses`                                 | `record.toolUses` (in final result)              |
-| `foreground-runner.ts`     | `formatLifetimeTokens(fgState)`                    | `formatLifetimeTokens(record)` (in final result) |
-
-### NotificationManager refactoring
-
-Replace:
-
-```typescript
-export interface NotificationDeps { … }
-constructor(private deps: NotificationDeps) {}
-```
-
-With:
-
-```typescript
-constructor(
-  private sendMessage: NotificationDeps["sendMessage"],
-  private agentActivity: Map<string, AgentActivityTracker>,
-  private markFinished: (id: string) => void,
-  private updateWidget: () => void,
-) {}
-```
-
-Internal references change from `this.deps.sendMessage(…)` to `this.sendMessage(…)`.
-The `NotificationDeps` interface is removed.
-
-### Foreground runner streaming
-
-During foreground execution, `streamUpdate` reads `fgState.toolUses` and `formatLifetimeTokens(fgState)` for live spinner updates.
-After removing these from the tracker, `streamUpdate` must read from the record instead.
-The record is available only after `spawnAndWait` returns the record reference via `onSessionCreated`.
-Before that callback fires, tool uses and usage are both zero — the tracker never had meaningful data at that point either.
-`streamUpdate` will capture a `let recordRef: AgentRecord | undefined` and read `recordRef?.toolUses ?? 0` during the spinner phase.
-After `onSessionCreated`, `recordRef` is set and subsequent spinner ticks read live values from the record.
-
-## Module-Level Changes
-
-### Modified files
-
-1. `src/ui/agent-activity-tracker.ts` — Remove `_toolUses`, `_lifetimeUsage`, `onToolEnd`, `onUsageUpdate`, `toolUses` getter, `lifetimeUsage` getter.
-   Rename remaining tool-end logic to `onToolDone`.
-   Remove `addUsage` and `UsageDelta` imports.
-2. `src/ui/ui-observer.ts` — Call `tracker.onToolDone` instead of `tracker.onToolEnd`.
-   Remove `message_end` usage accumulation block.
-3. `src/agent-record.ts` — Add `get session()` and `get outputFile()` convenience getters.
-   Import `AgentSession` type for the return type.
-4. `src/notification.ts` — Remove `NotificationDeps` interface.
-   Change `NotificationManager` constructor to plain parameters.
-   Replace `this.deps.*` with `this.*`.
-   Change `record.execution?.session` → `record.session`, `record.execution?.outputFile` → `record.outputFile`.
-5. `src/ui/agent-widget.ts` — Read `a.toolUses`, `a.lifetimeUsage`, `a.session` instead of `bg?.toolUses ?? a.toolUses` etc.
-6. `src/ui/conversation-viewer.ts` — Read `this.record.toolUses`, `this.record.lifetimeUsage`, `this.record.session` instead of fallback pattern.
-7. `src/tools/get-result-tool.ts` — `record.execution?.session` → `record.session`.
-8. `src/tools/steer-tool.ts` — `record.execution?.session` → `record.session`.
-9. `src/ui/agent-menu.ts` — `record.execution?.session` → `record.session`.
-10. `src/service-adapter.ts` — `record.execution?.session` → `record.session`.
-11. `src/agent-manager.ts` — `record.execution?.session` → `record.session` in dispose paths.
-    Keep the `record.execution = { session, outputFile }` assignment unchanged (that's the write path).
-12. `src/tools/foreground-runner.ts` — Read `record.toolUses` and `formatLifetimeTokens(record)` for final result.
-    Capture `recordRef` for streaming phase.
-13. `src/tools/helpers.ts` — `buildDetails`: read `record.toolUses` and `record.lifetimeUsage` (already does); remove optional `activity` parameter's usage of `toolUses`/`lifetimeUsage` if present (verify).
-14. `src/index.ts` — Update `NotificationManager` construction from bag to plain parameters.
-15. `src/tools/background-spawner.ts` — `record?.execution?.outputFile` → `record?.outputFile`.
-
-### Test files modified
-
-1. `test/ui/agent-activity-tracker.test.ts` — Remove tests for `toolUses`, `lifetimeUsage`, `onToolEnd`, `onUsageUpdate`.
-   Add tests for `onToolDone` (active-tool removal without counting).
-2. `test/ui/ui-observer.test.ts` — Update `tool_execution_end` expectations (calls `onToolDone` not `onToolEnd`).
-   Remove `message_end` usage accumulation tests.
-3. `test/notification.test.ts` — Update `makeDeps()` factory to use plain parameters.
-   Or update `NotificationManager` construction call to match new signature.
-4. `test/agent-record.test.ts` — Add tests for `session` and `outputFile` getters.
-5. `test/conversation-viewer.test.ts` — Remove mock activity tracker usage for stats; tests use record stats directly.
-
-## Test Impact Analysis
-
-### New unit tests enabled
-
-1. `AgentRecord.session` and `AgentRecord.outputFile` getters — straightforward getter tests on the record class.
-2. `AgentActivityTracker.onToolDone` — verifies active-tool removal without side effects on a counter.
-
-### Existing tests that become simpler
-
-1. `agent-activity-tracker.test.ts` — 4 test blocks for `toolUses`, `lifetimeUsage`, `onToolEnd`, `onUsageUpdate` can be removed.
-   The `onToolDone` replacement needs fewer assertions (no counter check).
-2. `ui-observer.test.ts` — The `message_end` usage accumulation tests can be removed.
-   The `tool_execution_end` test simplifies (verifies active-tool removal only).
-3. `notification.test.ts` — The `makeDeps()` helper changes shape but stays the same size.
-4. `conversation-viewer.test.ts` — Tests that mock `activity.toolUses` and `activity.lifetimeUsage` can simplify to reading from the record.
-
-### Existing tests that must stay
-
-1. `record-observer.test.ts` — All tests remain as-is.
-   The record observer is the sole source of `incrementToolUses` and `addUsage` calls now.
-2. `agent-record.test.ts` — All existing tests for `incrementToolUses`, `addUsage`, `incrementCompactions` remain.
-3. `notification.test.ts` — Pure helper tests (`escapeXml`, `getStatusLabel`, `formatTaskNotification`, `buildNotificationDetails`, `buildEventData`) remain unchanged.
-
-## TDD Order
-
-1. **Red→Green: `AgentRecord` convenience getters.**
-   Add tests for `record.session` and `record.outputFile` (returns `undefined` when no execution, delegates when set).
-   Implement the getters.
-   Commit: `feat: add session and outputFile convenience getters to AgentRecord (#144)`
-
-2. **Green→Green: Migrate callsites from `execution?.` to convenience getters.**
-   Update all 12 callsites across 7 files (`notification.ts`, `agent-widget.ts`, `agent-menu.ts`, `get-result-tool.ts`, `steer-tool.ts`, `service-adapter.ts`, `agent-manager.ts`, `background-spawner.ts`).
-   No test changes needed — existing tests pass.
-   Run `pnpm run check` to verify.
-   Commit: `refactor: use AgentRecord.session and .outputFile convenience getters (#144)`
-
-3. **Red→Green: Rename `onToolEnd` to `onToolDone` and remove counter.**
-   Update `agent-activity-tracker.test.ts`: remove `onToolEnd` counter tests, add `onToolDone` tests (active-tool removal only, no `toolUses` assertion).
-   Implement: rename method, remove `_toolUses++`.
-   Update `ui-observer.ts` to call `onToolDone`.
-   Update `ui-observer.test.ts` expectations.
-   Commit: `refactor: rename AgentActivityTracker.onToolEnd to onToolDone (#144)`
-
-4. **Red→Green: Remove `_toolUses` and `_lifetimeUsage` from tracker.**
-   Update `agent-activity-tracker.test.ts`: remove `toolUses` getter, `lifetimeUsage` getter, and `onUsageUpdate` test blocks.
-   Implement: remove `_toolUses`, `_lifetimeUsage`, `toolUses` getter, `lifetimeUsage` getter, `onUsageUpdate` method, `UsageDelta` type, `addUsage` import.
-   Update `ui-observer.ts`: remove `message_end` usage accumulation block.
-   Update `ui-observer.test.ts`: remove `message_end` usage tests.
-   Run `pnpm run check` to catch any remaining references.
-   Commit: `refactor: remove duplicate stats from AgentActivityTracker (#144)`
-
-5. **Green→Green: Migrate UI consumers to read stats from `AgentRecord`.**
-   Update `agent-widget.ts`: replace `bg?.toolUses ?? a.toolUses` → `a.toolUses`, `bg?.lifetimeUsage` → `a.lifetimeUsage`, `bg?.session` → `a.session`.
-   Update `conversation-viewer.ts`: replace `activity?.toolUses ?? record.toolUses` → `record.toolUses`, `activity?.lifetimeUsage` → `record.lifetimeUsage`, `activity?.session` → `record.session`.
-   Update `foreground-runner.ts`: read stats from record instead of tracker for final result.
-   Capture `recordRef` for streaming phase.
-   Update `conversation-viewer.test.ts` if any tests mock activity stats.
-   Commit: `refactor: read stats from AgentRecord in UI consumers (#144)`
-
-6. **Red→Green: Replace `NotificationDeps` with plain parameters.**
-   Update `notification.test.ts`: change `makeDeps()` → individual parameters in `NotificationManager` constructor calls.
-   Implement: remove `NotificationDeps` interface, change constructor to plain parameters, replace `this.deps.*` with `this.*`.
-   Update `index.ts`: change `NotificationManager` construction to pass individual arguments.
-   Commit: `refactor: dissolve NotificationDeps into plain constructor parameters (#144)`
-
-## Risks and Mitigations
-
-| Risk                                                                                              | Mitigation                                                                                                                                                                                                                                                  |
-| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Foreground streaming reads stale `recordRef` before `onSessionCreated` fires                      | Before `onSessionCreated`, both tracker and record have zero stats — behavior is unchanged.  Capture `recordRef` as `undefined` initially and guard with `??`.                                                                                              |
-| Widget reads `a.toolUses` but `a` is the snapshot from `listAgents()` — might be stale            | `listAgents()` returns live `AgentRecord` references (not copies), so `a.toolUses` reflects the latest record-observer increment.                                                                                                                           |
-| Removing `lifetimeUsage` from tracker breaks `formatLifetimeTokens(fgState)` in foreground runner | Step 5 explicitly migrates this callsite to `formatLifetimeTokens(record)`.  The TDD order places the removal (step 4) before the migration (step 5), but step 4's `pnpm run check` will catch the type error and both steps can be merged if needed.       |
-| `buildDetails` in `helpers.ts` accepts an `activity` parameter for `turnCount`/`maxTurns`         | `turnCount` and `maxTurns` remain on the tracker — only `toolUses` and `lifetimeUsage` are removed.  `buildDetails` reads `record.toolUses` and `record.lifetimeUsage` already; it reads `activity?.turnCount` and `activity?.maxTurns` which remain valid. |
-
-## Open Questions
-
-- None — the architecture doc prescribes the exact changes and the design is straightforward.