@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/plans/0218-push-sdk-boundary-in-settings.md

@@ -1,172 +0,0 @@
----
-issue: 218
-issue_title: "Push SDK boundary in settings.ts (Phase 13, Step 5)"
----
-
-# Push SDK boundary in settings.ts
-
-## Problem Statement
-
-`settings.ts` imports `getAgentDir` from the Pi SDK (`@earendil-works/pi-coding-agent`) and calls it inside `globalPath()` at invocation time.
-This hides a platform dependency inside a module that is otherwise pure configuration logic — violating the project's SDK-boundary rule that pure helpers and domain modules should remain SDK-independent.
-The SDK call also forces tests to redirect the env var `PI_CODING_AGENT_DIR` to control `getAgentDir()` output, rather than passing the value directly.
-
-## Goals
-
-- Remove the `getAgentDir` import from `settings.ts` (0 Pi SDK imports).
-- Inject `agentDir: string` into `SettingsManager` constructor deps.
-- Make `loadSettings` accept `agentDir` as an explicit parameter.
-- Eliminate `PI_CODING_AGENT_DIR` env var manipulation from all settings tests.
-
-## Non-Goals
-
-- Removing `process.cwd()` defaults from `loadSettings`/`saveSettings` — that's a separate concern (Node.js API, not Pi SDK).
-- Pushing SDK boundaries in other files (`skill-loader.ts`, `custom-agents.ts`, `agent-runner.ts`) — tracked separately in the Phase 13 roadmap.
-- Changing the `saveSettings` signature — it only calls `projectPath(cwd)` and has no SDK dependency.
-
-## Background
-
-`settings.ts` exports a `SettingsManager` class and two free functions (`loadSettings`, `saveSettings`).
-The only SDK import is `getAgentDir`, used in the private `globalPath()` helper to compute the global settings file path (`~/.pi/agent/subagents.json`).
-
-The `SettingsManager` constructor already accepts a deps bag `{ emit, cwd, onMaxConcurrentChanged? }`.
-Adding `agentDir` to this bag follows the established injection pattern.
-
-In `index.ts`, `getAgentDir` is already imported for several other call sites (agent runner IO, agent tool, `/agents` menu).
-Adding one more usage to the `SettingsManager` construction is zero new imports.
-
-### Relevant AGENTS.md constraints
-
-- **Pi SDK boundaries:** Keep Pi SDK imports out of business-logic modules; accept the value as a parameter or callback.
-- **Code-design skill, DIP:** Default to dependency injection for non-trivial dependencies.
-
-## Design Overview
-
-### Change to `globalPath()`
-
-Currently:
-
-```typescript
-function globalPath(): string {
-  return join(getAgentDir(), "subagents.json");
-}
-```
-
-After:
-
-```typescript
-function globalPath(agentDir: string): string {
-  return join(agentDir, "subagents.json");
-}
-```
-
-### Change to `loadSettings()`
-
-Currently:
-
-```typescript
-export function loadSettings(cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath()), ...readSettingsFile(projectPath(cwd)) };
-}
-```
-
-After:
-
-```typescript
-export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
-}
-```
-
-### Change to `SettingsManager` constructor
-
-Add `agentDir: string` to the deps bag:
-
-```typescript
-constructor(deps: { emit: SettingsEmit; cwd: string; agentDir: string; onMaxConcurrentChanged?: () => void }) {
-  this.emit = deps.emit;
-  this.cwd = deps.cwd;
-  this.agentDir = deps.agentDir;
-  this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
-}
-```
-
-`SettingsManager.load()` passes `this.agentDir` to `loadSettings`:
-
-```typescript
-load(): SubagentsSettings {
-  const settings = loadSettings(this.agentDir, this.cwd);
-  // ... rest unchanged
-}
-```
-
-### Wiring in `index.ts`
-
-```typescript
-const settings = new SettingsManager({
-  emit: (event, payload) => pi.events.emit(event, payload),
-  cwd: process.cwd(),
-  agentDir: getAgentDir(),
-  onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
-});
-```
-
-## Module-Level Changes
-
-### `src/settings.ts`
-
-1. Remove `import { getAgentDir } from "@earendil-works/pi-coding-agent"`.
-2. Add `agentDir: string` field to the `SettingsManager` constructor deps interface.
-3. Store `this.agentDir = deps.agentDir` as a private readonly field.
-4. Change `globalPath()` signature to `globalPath(agentDir: string)`.
-5. Change `loadSettings` signature to `loadSettings(agentDir: string, cwd?: string)`.
-6. Update `SettingsManager.load()` to call `loadSettings(this.agentDir, this.cwd)`.
-7. Update the header comment to reflect the new injection pattern.
-
-### `src/index.ts`
-
-1. Add `agentDir: getAgentDir()` to the `SettingsManager` constructor deps object.
-
-### `test/settings.test.ts`
-
-1. Remove all `PI_CODING_AGENT_DIR` env manipulation (`originalAgentDirEnv`, `beforeEach`/`afterEach` stubs).
-2. Pass `globalDir` directly to `loadSettings(globalDir, projectDir)` in free-function tests.
-3. Add `agentDir: globalDir` (or a dummy string for non-load tests) to all `new SettingsManager(...)` calls.
-4. In `SettingsManager.load()` tests, pass `agentDir: globalDir` to the constructor.
-5. In tests that don't exercise `load()`, use `agentDir: "/nonexistent"` or similar — the value is unused.
-
-## Test Impact Analysis
-
-1. **New capability:** Free-function tests (`loadSettings`, `saveSettings`) become pure — pass `globalDir` directly instead of manipulating `PI_CODING_AGENT_DIR`.
-   This is simpler and more reliable.
-2. **Redundant cleanup:** The `originalAgentDirEnv` save/restore pattern in `beforeEach`/`afterEach` can be removed from all `describe` blocks that use it.
-3. **Existing tests stay:** All existing test scenarios remain valid; only their setup mechanics change.
-
-## TDD Order
-
-1. **Red → Green:** Change `loadSettings` signature to accept `agentDir` parameter; update `globalPath` to accept it.
-   Update all free-function tests to pass `globalDir` directly instead of env var.
-   Remove env-var manipulation from the `settings persistence` describe block.
-   Commit: `feat: inject agentDir into loadSettings to remove SDK dependency`
-
-2. **Red → Green:** Add `agentDir` to `SettingsManager` constructor deps; store as private field; thread into `load()`.
-   Update all `new SettingsManager(...)` call sites in tests.
-   Remove env-var manipulation from `SettingsManager` describe blocks.
-   Remove `getAgentDir` import from `settings.ts`.
-   Commit: `feat: inject agentDir into SettingsManager constructor`
-
-3. **Green:** Wire `agentDir: getAgentDir()` into `SettingsManager` construction in `index.ts`.
-   Run `pnpm run check` to confirm no type errors across the package.
-   Commit: `feat: wire agentDir from SDK boundary in index.ts (#218)`
-
-## Risks and Mitigations
-
-| Risk                                                                                  | Mitigation                                                                                                   |
-| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Breaking the `loadSettings` export signature for hypothetical external callers        | The function is only called from `SettingsManager.load()` and tests; no external consumers exist.            |
-| Test count is high (~35 constructor sites) — mechanical updates could introduce typos | Steps 1 and 2 are focused; run `pnpm vitest run test/settings.test.ts` after each to confirm.                |
-| Forgetting a test site that still manipulates `PI_CODING_AGENT_DIR`                   | Grep for `PI_CODING_AGENT_DIR` after step 2 to confirm zero remaining references in `test/settings.test.ts`. |
-
-## Open Questions
-
-None — the issue's proposed change is unambiguous and follows the established injection pattern used in prior Phase 13 steps.

package/docs/plans/0219-reduce-test-duplication-top-3-clone-families.md

@@ -1,162 +0,0 @@
----
-issue: 219
-issue_title: "Reduce test duplication — top 3 clone families (Phase 13, Step 6)"
----
-
-# Reduce test duplication — top 3 clone families
-
-## Problem statement
-
-After Phase 12, three test files carry the heaviest remaining clone families in pi-subagents:
-
-1. `test/lifecycle/agent-manager.test.ts` (929 lines) — 16 clone groups, ~160 duplicated lines.
-   Repeated inline runner stubs, worktree stubs, and manager-lifecycle boilerplate.
-2. `test/conversation-viewer.test.ts` (307 lines) — 8 clone groups, ~91 duplicated lines.
-   Near-identical `ConversationViewer` construction in every test, plus repeated width-loop assertion patterns.
-3. `test/ui/agent-config-editor.test.ts` (471 lines) — 5 clone groups, ~42 duplicated lines.
-   Repeated `makeEditor()` + `makeMenuUI()` + `fileOps.findAgentFile.mockReturnValue(...)` setup.
-
-Total target: reduce test duplication by ~200 lines (from ~1,046 combined test-setup lines to < 850).
-
-## Goals
-
-- Extract shared setup and assertion helpers for the three target test files.
-- Reduce test duplication by ~200 lines without changing test semantics.
-- Follow the existing `test/helpers/` convention (factory + matching `.test.ts` file).
-
-## Non-goals
-
-- No production code changes.
-- No new test coverage — this is purely a refactoring of existing test infrastructure.
-- Not consolidating clone families in other test files beyond the top 3.
-- Not changing any assertion logic or test structure beyond replacing inline stubs with factory calls.
-
-## Background
-
-The project already has several shared test helpers in `test/helpers/`: `make-record.ts`, `mock-session.ts`, `ui-stubs.ts`, `runner-io.ts`, `stub-ctx.ts`, `make-deps.ts`.
-Each helper has a companion `.test.ts` file — this convention must be followed.
-
-Dependencies #214 (closure-to-class conversions) and #216 (startAgent decomposition) are both closed, so the production code these tests cover is stable.
-
-## Design overview
-
-### File 1: `agent-manager.test.ts` — extract to `test/helpers/manager-stubs.ts`
-
-Five clone families to extract:
-
-1. **Never-resolving runner** — `{ run: vi.fn().mockImplementation(() => new Promise(() => {})), resume: vi.fn() }` appears 5 times.
-   Extract as `createBlockingRunner(): AgentRunner`.
-
-2. **Session-creating runner** — runner that calls `opts.onSessionCreated?.(session)` and resolves.
-   Appears 5+ times with minor variations (some emit events through the session, some don't).
-   Extract as `createSessionRunner(session?: MockSession): AgentRunner` that calls `onSessionCreated` and returns a standard result.
-
-3. **Worktree stubs with path+branch** — `{ create: vi.fn().mockReturnValue({ path, branch }), cleanup: vi.fn(() => ({ hasChanges: false })), prune: vi.fn() }` appears 4 times identically, plus 1 variant with `create` returning `undefined`.
-   Extract as `createMockWorktrees(overrides?)`.
-
-4. **Standard run result shape** — `{ responseText: "done", session, aborted: false, steered: false }` is repeated in many runner factories.
-   Extract as `createRunResult(overrides?)`.
-
-5. **Gated runner** — uses `Promise.withResolvers` to control when the runner completes.
-   Appears 2 times.
-   Keep inline — too tightly coupled to individual test flow-control to generalize cleanly.
-
-Tests that construct custom runners with unique behavior (event-emitting runners in the `lifetimeUsage` and `compactionCount` tests) keep their inline stubs — those encode test-specific emission sequences that a shared factory would obscure.
-
-### File 2: `conversation-viewer.test.ts` — inline factory + assertion helper
-
-Two clone families to extract:
-
-1. **`ConversationViewer` construction** — 15 near-identical constructor calls with the same 8 fields.
-   Extract as an inline `createTestViewer(overrides?)` factory at the top of the test file.
-   The factory provides defaults for `tui`, `session`, `record`, `activity`, `theme`, `done`, `registry`, and `wrapText`, and accepts overrides including a convenience `width` and `messages` parameter.
-
-2. **Width-loop assertion** — the `for (const w of widths) { create viewer; assertAllLinesFit(viewer.render(w), w) }` pattern repeats in 10 "render width safety" tests.
-   Extract as an inline `assertRenderFitsWidths(messages, widths?, viewerOverrides?)` helper.
-
-These helpers stay inline (not in `test/helpers/`) because they depend on file-local helpers (`mockTui`, `mockSession`, `ansiTheme`) and are only used by this one test file.
-
-### File 3: `agent-config-editor.test.ts` — inline setup helper
-
-One clone family to extract:
-
-1. **Detail-test setup** — `makeEditor()` + `makeMenuUI([...])` + `fileOps.findAgentFile.mockReturnValue(...)` + optional `fileOps.read.mockReturnValue(...)` appears in ~18 tests.
-   Extract as an inline `setupDetail(selectResults, options?)` factory that returns `{ fileOps, editor, ui }` with pre-configured mocks.
-   Options: `filePath`, `fileContent`, `config` (merged into default via `createTestAgentConfig`).
-
-This stays inline because it's specific to the `showAgentDetail` test suite and depends on file-local `testRegistry` setup.
-
-## Module-level changes
-
-### New files
-
-| File                                 | Purpose                                                                                 |
-| ------------------------------------ | --------------------------------------------------------------------------------------- |
-| `test/helpers/manager-stubs.ts`      | `createBlockingRunner`, `createSessionRunner`, `createMockWorktrees`, `createRunResult` |
-| `test/helpers/manager-stubs.test.ts` | Smoke tests for the factories                                                           |
-
-### Modified files
-
-| File                                   | Change                                                                      |
-| -------------------------------------- | --------------------------------------------------------------------------- |
-| `test/lifecycle/agent-manager.test.ts` | Replace inline runner/worktree stubs with `manager-stubs` factories         |
-| `test/conversation-viewer.test.ts`     | Add `createTestViewer` + `assertRenderFitsWidths` inline, migrate all tests |
-| `test/ui/agent-config-editor.test.ts`  | Add `setupDetail` inline, migrate `showAgentDetail` tests                   |
-
-### Unchanged files
-
-No production source files are modified.
-No other test files are modified.
-
-## Test impact analysis
-
-1. **New unit tests**: `manager-stubs.test.ts` adds smoke tests verifying factory return shapes (blocking runner never resolves, session runner calls `onSessionCreated`, worktree factory returns the expected interface, run result contains the correct fields).
-2. **Simplified tests**: ~30 tests across the three files replace 3–6 lines of inline stub construction with 1-line factory calls.
-3. **Unchanged tests**: All existing test assertions remain identical — only the setup code changes.
-   Tests with custom runner behavior (event-emitting, gated, error-throwing) keep their inline stubs.
-
-## TDD order
-
-1. **Create `test/helpers/manager-stubs.ts` + `manager-stubs.test.ts`** Add `createBlockingRunner`, `createSessionRunner`, `createMockWorktrees`, `createRunResult`.
-   Add smoke tests verifying each factory's return shape and basic behavior.
-   Commit: `test: add manager-stubs helper factories (#219)`
-
-2. **Migrate `agent-manager.test.ts` to use manager-stubs** Replace 5 inline never-resolving runners with `createBlockingRunner()`.
-   Replace 4 identical worktree stubs with `createMockWorktrees()` / `createMockWorktrees({ create: ... })`.
-   Replace inline session-creating runners with `createSessionRunner(session)` where the test only needs `onSessionCreated` wiring.
-   Replace inline run-result objects with `createRunResult()` where the default shape suffices.
-   Run `pnpm vitest run test/lifecycle/agent-manager.test.ts` to verify green.
-   Commit: `test: migrate agent-manager tests to manager-stubs (#219)`
-
-3. **Add inline factories to `conversation-viewer.test.ts` and migrate** Add `createTestViewer(overrides?)` inline factory with defaults for all 8 constructor fields.
-   Add `assertRenderFitsWidths(messages, widths?, overrides?)` inline helper.
-   Migrate all 10 "render width safety" tests to use `assertRenderFitsWidths`.
-   Migrate all 5 "safety net" tests to use `createTestViewer`.
-   Run `pnpm vitest run test/conversation-viewer.test.ts` to verify green.
-   Commit: `test: reduce conversation-viewer test duplication (#219)`
-
-4. **Add inline `setupDetail` to `agent-config-editor.test.ts` and migrate** Add `setupDetail(selectResults, options?)` returning `{ fileOps, editor, ui }`.
-   Migrate `showAgentDetail` tests to use `setupDetail`.
-   Run `pnpm vitest run test/ui/agent-config-editor.test.ts` to verify green.
-   Commit: `test: reduce agent-config-editor test duplication (#219)`
-
-5. **Final verification** Run `pnpm vitest run` (full suite) to confirm no regressions.
-   Run `pnpm run check` to confirm no type errors.
-   Commit is not needed — this is a verification-only step.
-
-## Risks and mitigations
-
-1. **Factory defaults diverge from test intent** — If a shared factory's defaults don't match what an individual test expects, assertions silently pass or fail for the wrong reason.
-   Mitigation: diff all inline stubs against the proposed factory defaults before writing the factory.
-   Keep tests with unique mock behavior inline rather than force-fitting them into a factory.
-
-2. **Over-abstraction obscures test intent** — Extracting too many details into helpers makes tests harder to read.
-   Mitigation: only extract truly duplicated boilerplate (stub construction); keep test-specific setup and assertions inline.
-   The gated runner pattern stays inline for this reason.
-
-3. **Intermediate broken state** — Partially migrated test files may have import conflicts.
-   Mitigation: each TDD step fully migrates one file before committing.
-
-## Open questions
-
-None — the issue scope is well-defined and the dependencies are resolved.

package/docs/plans/0227-evolve-agent-record-into-agent.md

@@ -1,322 +0,0 @@
----
-issue: 227
-issue_title: "Evolve AgentRecord into Agent with behavior (Phase 15, Step 1)"
----
-
-# Evolve AgentRecord into Agent with behavior
-
-## Problem Statement
-
-`AgentRecord` is an anemic domain model — it holds identity, status transitions, and stats but no behavior.
-`AgentManager` reaches into records 37 times, performing work that belongs on the agent:
-
-- **abort**: `AgentManager.abort()` checks `record.status`, calls `record.abortController?.abort()`, calls `record.markStopped()` — this is the agent aborting itself, but the logic lives on the manager.
-- **pending steers**: per-agent steer buffers live in a manager-level `Map<string, string[]>`, not on the agent.
-- **steer flushing**: `flushPendingSteers(id, session)` iterates the manager map — should be `agent.flushPendingSteers(session)`.
-- **worktree setup**: `setupWorktree()` creates a worktree and attaches it to the record — the agent should set up its own worktree.
-
-## Goals
-
-- Move per-agent behavior (`abort`, `queueSteer`/`flushPendingSteers`, `setupWorktree`) from `AgentManager` to the agent.
-- `AgentManager` delegates to agents via Tell-Don't-Ask instead of reaching into records.
-- Rename `AgentRecord` → `Agent`, `AgentRecordStatus` → `AgentStatus`, `AgentRecordInit` → `AgentInit` across the codebase.
-- All changes are internal — the public `SubagentsService` API (`service.ts`) is unaffected.
-
-## Non-Goals
-
-- **`RunHandle` ownership** — moves to `Agent` in #228, not here.
-- **Async `startAgent`** — deferred to #228.
-- **`onSessionCreated` observer** — deferred to #229.
-- **`ConcurrencyQueue` extraction** — deferred to #230.
-  Queue removal logic stays on `AgentManager.abort()` until then.
-- **Relay deps** — deferred to #231.
-- **Resume unification** — deferred to #232.
-
-## Background
-
-### Relevant modules
-
-| Module                                     | Responsibility                                          | Relationship to this change                                                        |
-| ------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `src/lifecycle/agent-record.ts` (201 LOC)  | Status state machine, stats accumulation                | Gains behavior methods, renames to `agent.ts`                                      |
-| `src/lifecycle/agent-manager.ts` (541 LOC) | Agent collection, spawn, abort, queue, steer buffering  | Loses private methods, delegates to agent                                          |
-| `src/lifecycle/worktree.ts`                | `WorktreeManager` interface and git worktree operations | Agent calls `worktrees.create()` directly                                          |
-| `src/lifecycle/worktree-state.ts`          | Per-agent worktree lifecycle state                      | Already attached to agent — `setupWorktree` formalizes this                        |
-| `src/tools/steer-tool.ts`                  | LLM-facing steer tool                                   | Calls `record.queueSteer()` directly instead of `manager.queueSteer()`             |
-| `src/service/service-adapter.ts`           | Cross-extension API adapter                             | Calls `record.queueSteer()` directly; `queueSteer` removed from `AgentManagerLike` |
-| `src/observation/record-observer.ts`       | Session event → agent stats accumulation                | Import rename only                                                                 |
-| `src/types.ts`                             | Internal re-exports                                     | Re-export updates                                                                  |
-| `test/helpers/make-record.ts`              | Shared test factory                                     | Renames to `make-agent.ts`, factory → `createTestAgent()`                          |
-
-### Constraints
-
-- The public export from `package.json` is `"./src/service.ts"` only — `AgentRecord` is internal, so the rename is not breaking for consumers.
-- `WorktreeManager` is injected via the manager's constructor — `Agent.setupWorktree()` receives it as a parameter (no new constructor dependency).
-- Queue removal in `abort()` stays on `AgentManager` because the queue is manager-owned until #230 extracts `ConcurrencyQueue`.
-
-## Design Overview
-
-### New methods on Agent
-
-```typescript
-class Agent {
-  // Existing: markRunning, markCompleted, markAborted, markSteered, markError, markStopped,
-  //           incrementToolUses, addUsage, incrementCompactions, resetForResume
-
-  // --- New behavior ---
-
-  /** Buffer a steer message for delivery once the session is ready. */
-  queueSteer(message: string): void;
-
-  /** Flush buffered steers to the session and clear the buffer. */
-  flushPendingSteers(session: AgentSession): void;
-
-  /** Abort a running agent: fire AbortController, transition to stopped. */
-  abort(): boolean;
-
-  /** Create a worktree for isolated execution. Throws if impossible. */
-  setupWorktree(worktrees: WorktreeManager, isolation: IsolationMode | undefined): string | undefined;
-}
-```
-
-### Steer buffering moves to agent
-
-Before: `AgentManager` owns `pendingSteers: Map<string, string[]>` and exposes `queueSteer(id, msg)`.
-After: each `Agent` owns `private pendingSteers: string[] = []`.
-Callers that already hold a record reference (steer tool, service adapter) call `agent.queueSteer(msg)` directly — the manager's `queueSteer` method and the `pendingSteers` map are removed.
-
-Consumer call-site (steer tool):
-
-```typescript
-// Before:
-this.manager.queueSteer(record.id, params.message);
-// After:
-record.queueSteer(params.message);
-```
-
-### Abort moves to agent
-
-`Agent.abort()` encapsulates the running-check + controller.abort + markStopped sequence:
-
-```typescript
-abort(): boolean {
-  if (this._status !== "running") return false;
-  this.abortController?.abort();
-  this.markStopped();
-  return true;
-}
-```
-
-`AgentManager.abort(id)` retains queue-removal logic (queue is manager-owned until #230) and delegates the running case to `agent.abort()`.
-`AgentManager.abortAll()` calls `agent.abort()` for running agents.
-
-### Worktree setup moves to agent
-
-`Agent.setupWorktree(worktrees, isolation)` replaces `AgentManager.setupWorktree(id, record, isolation)`.
-The agent creates the worktree, sets `this.worktreeState`, and returns the worktree path.
-The error message for impossible worktree creation stays identical.
-
-### Rename strategy
-
-The rename (`AgentRecord` → `Agent`) is the final step — a purely mechanical search-and-replace with no behavior change.
-This keeps behavior-adding commits small and reviewable, then consolidates the rename noise into one commit.
-
-Files affected by the rename:
-
-| Layer                | Files                                                                                                                                                                    |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Source (lifecycle)   | `agent-record.ts` → `agent.ts`, `agent-manager.ts`, `execution-state.ts`                                                                                                 |
-| Source (observation) | `record-observer.ts`, `notification.ts`                                                                                                                                  |
-| Source (tools)       | `agent-tool.ts`, `steer-tool.ts`, `get-result-tool.ts`, `background-spawner.ts`, `foreground-runner.ts`                                                                  |
-| Source (UI)          | `agent-menu.ts`, `agent-creation-wizard.ts`, `conversation-viewer.ts`                                                                                                    |
-| Source (service)     | `service-adapter.ts`                                                                                                                                                     |
-| Source (types)       | `types.ts`                                                                                                                                                               |
-| Tests                | `agent-record.test.ts` → `agent.test.ts`, `agent-manager.test.ts`, `record-observer.test.ts`, `steer-tool.test.ts`, `get-result-tool.test.ts`, `service-adapter.test.ts` |
-| Test helpers         | `make-record.ts` → `make-agent.ts`                                                                                                                                       |
-
-## Module-Level Changes
-
-### `src/lifecycle/agent-record.ts` → `src/lifecycle/agent.ts`
-
-1. Add `private pendingSteers: string[] = []` field.
-2. Add `queueSteer(message: string): void` — pushes to `pendingSteers`.
-3. Add `flushPendingSteers(session: AgentSession): void` — iterates buffer, calls `session.steer()`, clears array.
-4. Add `abort(): boolean` — if running, fires controller and marks stopped.
-5. Add `setupWorktree(worktrees: WorktreeManager, isolation: IsolationMode | undefined): string | undefined` — creates worktree, sets `worktreeState`, returns path.
-6. Add import for `WorktreeState`, `WorktreeManager`, `IsolationMode`.
-7. Rename class `AgentRecord` → `Agent`, type `AgentRecordStatus` → `AgentStatus`, interface `AgentRecordInit` → `AgentInit`.
-
-### `src/lifecycle/agent-manager.ts`
-
-1. Remove `private pendingSteers = new Map<string, string[]>()`.
-2. Remove `queueSteer(id, message)` public method.
-3. Remove `private flushPendingSteers(id, session)` method.
-4. In `startAgent`'s `onSessionCreated` callback: replace `this.flushPendingSteers(id, session)` with `record.flushPendingSteers(session)`.
-5. Remove `private setupWorktree(id, record, isolation)` method.
-6. In `startAgent`: replace `this.setupWorktree(id, record, options.isolation)` with `record.setupWorktree(this.worktrees, options.isolation)`.
-7. Simplify `abort(id)`: delegate running case to `record.abort()`.
-8. Simplify `abortAll()`: call `record.abort()` for running agents.
-9. In `removeRecord`: remove `this.pendingSteers.delete(id)`.
-10. Update imports: `AgentRecord` → `Agent`, `AgentRecordInit` → `AgentInit` (if used).
-
-### `src/tools/steer-tool.ts`
-
-1. Remove `queueSteer` from `SteerToolManager` interface.
-2. Replace `this.manager.queueSteer(record.id, params.message)` with `record.queueSteer(params.message)`.
-3. Update import: `AgentRecord` → `Agent`.
-
-### `src/service/service-adapter.ts`
-
-1. Remove `queueSteer` from `AgentManagerLike` interface.
-2. In `steer()`: replace `this.manager.queueSteer(id, message)` with `record.queueSteer(message)` and return `true`.
-3. Update import: `AgentRecord` → `Agent`.
-
-### `src/types.ts`
-
-1. Update re-export: `AgentRecord` → `Agent`, source path `#src/lifecycle/agent-record` → `#src/lifecycle/agent`.
-
-### `src/observation/record-observer.ts`
-
-1. Update import and parameter types: `AgentRecord` → `Agent`.
-
-### `src/observation/notification.ts`
-
-1. Update import and parameter types: `AgentRecord` → `Agent`.
-
-### `src/tools/*.ts` (agent-tool, get-result-tool, background-spawner, foreground-runner)
-
-1. Update imports and type annotations: `AgentRecord` → `Agent`.
-
-### `src/ui/*.ts` (agent-menu, agent-creation-wizard, conversation-viewer)
-
-1. Update imports and type annotations: `AgentRecord` → `Agent`.
-
-### `test/helpers/make-record.ts` → `test/helpers/make-agent.ts`
-
-1. Rename file.
-2. Update imports: `AgentRecord` → `Agent`, `AgentRecordInit` → `AgentInit`.
-3. Rename factory: `createTestRecord` → `createTestAgent`.
-4. Update return type annotation.
-
-### `test/lifecycle/agent-record.test.ts` → `test/lifecycle/agent.test.ts`
-
-1. Rename file.
-2. Update import: `AgentRecord` → `Agent`.
-3. Update all `describe` block names and `new AgentRecord(...)` calls.
-4. Add new test blocks for `queueSteer`, `flushPendingSteers`, `abort`, `setupWorktree`.
-
-### `test/lifecycle/agent-manager.test.ts`
-
-1. Remove tests for `AgentManager.queueSteer` (behavior moved to agent).
-2. Update `abort()` tests to verify delegation.
-3. Update imports if `AgentRecord` type is referenced.
-
-### `test/tools/steer-tool.test.ts`
-
-1. Remove `queueSteer` from mock manager.
-2. Update "session not ready" test to verify `record.queueSteer()` is called.
-
-### `test/service/service-adapter.test.ts`
-
-1. Remove `queueSteer` from mock managers.
-2. Update steer tests to verify `record.queueSteer()`.
-
-### `packages/pi-subagents/docs/architecture/architecture.md`
-
-1. Update file listing: `agent-record.ts` → `agent.ts`.
-2. Update `AgentRecordInit` reference in interface width table.
-
-## Test Impact Analysis
-
-### New unit tests enabled by the extraction
-
-1. **`Agent.queueSteer()` / `Agent.flushPendingSteers()`** — isolated tests for steer buffering without needing a full `AgentManager` setup.
-   Previously the steer buffering was only testable via `AgentManager` integration tests.
-2. **`Agent.abort()`** — isolated tests for the abort state machine (running → stopped, not-running → no-op) without needing manager scaffolding.
-3. **`Agent.setupWorktree()`** — isolated tests for worktree creation and error handling with a mock `WorktreeManager`, without full spawn infrastructure.
-
-### Existing tests that become redundant
-
-1. `AgentManager — queueSteer` tests — the behavior is now tested directly on `Agent`.
-   The manager no longer has a `queueSteer` method.
-2. Parts of `AgentManager — abort` tests that verify controller.abort + markStopped — these are now `Agent.abort()` tests.
-   The manager abort tests should focus on queue-removal logic and delegation.
-
-### Existing tests that must stay
-
-1. `AgentManager — abort` tests for the "queued" case (queue removal is still manager-owned).
-2. `AgentManager — abortAll` tests (orchestrates both queue clearing and agent abort).
-3. All `AgentManager — spawn/spawnAndWait` tests — the spawn flow still lives on the manager.
-4. `steer-tool` and `service-adapter` tests for the steer path — updated to verify the new call pattern.
-
-## TDD Order
-
-1. **Red/Green: add `queueSteer()` and `flushPendingSteers()` to `AgentRecord`**
-   - Add tests in `agent-record.test.ts` for buffering and flushing steers.
-   - Implement the methods on `AgentRecord`.
-   - Commit: `feat(pi-subagents): add steer buffering to AgentRecord`
-
-2. **Refactor: delegate steer buffering from manager to agent**
-   - Remove `pendingSteers` map, `queueSteer()`, `flushPendingSteers()` from `AgentManager`.
-   - In `startAgent`'s `onSessionCreated`: call `record.flushPendingSteers(session)`.
-   - In `removeRecord`: remove `pendingSteers.delete(id)`.
-   - Update `steer-tool.ts`: remove `queueSteer` from `SteerToolManager`, call `record.queueSteer()`.
-   - Update `service-adapter.ts`: remove `queueSteer` from `AgentManagerLike`, call `record.queueSteer()`.
-   - Remove `AgentManager — queueSteer` tests; update steer-tool and service-adapter tests.
-   - Run `pnpm run check` to verify no type errors.
-   - Commit: `refactor(pi-subagents): delegate steer buffering from manager to agent`
-
-3. **Red/Green: add `abort()` to `AgentRecord`**
-   - Add tests in `agent-record.test.ts`: running → aborts and returns true; non-running → returns false; no controller → still marks stopped.
-   - Implement the method.
-   - Commit: `feat(pi-subagents): add abort() to AgentRecord`
-
-4. **Refactor: delegate abort from manager to agent**
-   - Simplify `AgentManager.abort()`: queued case stays, running case delegates to `record.abort()`.
-   - Simplify `AgentManager.abortAll()`: call `record.abort()` for running agents.
-   - Update manager abort tests to focus on queue removal and delegation.
-   - Commit: `refactor(pi-subagents): delegate abort from manager to agent`
-
-5. **Red/Green: add `setupWorktree()` to `AgentRecord`**
-   - Add tests in `agent-record.test.ts`: non-worktree returns undefined; worktree created → sets `worktreeState` and returns path; creation fails → throws.
-   - Implement the method (import `WorktreeState`, `WorktreeManager`, `IsolationMode`).
-   - Commit: `feat(pi-subagents): add setupWorktree() to AgentRecord`
-
-6. **Refactor: delegate worktree setup from manager to agent**
-   - Remove `private setupWorktree()` from `AgentManager`.
-   - In `startAgent`: replace `this.setupWorktree(id, record, options.isolation)` with `record.setupWorktree(this.worktrees, options.isolation)`.
-   - Update any tests that verify worktree setup delegation.
-   - Commit: `refactor(pi-subagents): delegate worktree setup from manager to agent`
-
-7. **Rename `AgentRecord` → `Agent` across codebase**
-   - Rename `src/lifecycle/agent-record.ts` → `src/lifecycle/agent.ts`.
-   - Rename class `AgentRecord` → `Agent`, type `AgentRecordStatus` → `AgentStatus`, interface `AgentRecordInit` → `AgentInit`.
-   - Update all source imports and type references (~20 source files).
-   - Rename `test/lifecycle/agent-record.test.ts` → `test/lifecycle/agent.test.ts`.
-   - Rename `test/helpers/make-record.ts` → `test/helpers/make-agent.ts`, factory `createTestRecord` → `createTestAgent`.
-   - Update all test imports and references (~10 test files).
-   - Rename `subscribeRecordObserver` → `subscribeAgentObserver` and `RecordObserverOptions` → `AgentObserverOptions` in `record-observer.ts`.
-   - Run `pnpm run check` and full test suite.
-   - Commit: `refactor(pi-subagents): rename AgentRecord to Agent`
-
-8. **Update architecture docs**
-   - Update `docs/architecture/architecture.md` file listing: `agent-record.ts` → `agent.ts`.
-   - Update `AgentRecordInit` → `AgentInit` in the interface width table.
-   - Update the Phase 15 Step 1 entry to reflect completion.
-   - Commit: `docs(pi-subagents): update architecture for Agent rename`
-
-## Risks and Mitigations
-
-1. **Large rename diff in step 7** — The rename touches ~30 files.
-   Mitigated by making it a purely mechanical change (no behavior change) in a dedicated commit, so reviewers can verify it's a clean rename.
-2. **Queue-removal leaks into agent** — `Agent.abort()` must NOT remove from the manager's queue (that's #230's concern).
-   Mitigated by scoping `Agent.abort()` to only handle the running case; `AgentManager.abort()` retains queue removal.
-3. **Interface changes cascade** — Removing `queueSteer` from `SteerToolManager` and `AgentManagerLike` requires updating test mocks.
-   Mitigated by handling interface changes and test updates in the same step (step 2).
-4. **Test factory rename ripple** — `createTestRecord` → `createTestAgent` touches many test files.
-   Mitigated by including this in the rename step (step 7), which is already a mechanical change.
-
-## Open Questions
-
-None — the issue's proposed change is unambiguous and scoped.
-`RunHandle` ownership and other Phase 15 steps are explicitly deferred to their own issues.