@gotgenes/pi-subagents 10.0.1 → 10.2.0

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

@@ -0,0 +1,322 @@
+---
+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.

package/docs/plans/0228-async-start-agent-dissolve-run-handle.md

@@ -0,0 +1,288 @@
+---
+issue: 228
+issue_title: "Convert startAgent to async/await, move run lifecycle to Agent (Phase 15, Step 2)"
+---
+
+# Convert startAgent to async/await, dissolve RunHandle into Agent
+
+## Problem Statement
+
+`startAgent` is synchronous and uses `.then()`/`.catch()` to handle the runner promise.
+This forces a promise-chain callback style even though `Agent` (as of #227) already owns per-agent behavior.
+
+`RunHandle` is a private class in `agent-manager.ts` that does 6 things — 5 of which are Agent concerns (status transitions, worktree cleanup, execution state updates, listener lifecycle, signal wiring).
+The only non-Agent concern is `onFinished`, a callback that connects to the manager's concurrency queue drain.
+
+`resume()` duplicates the same pattern manually: subscribe observer, try/catch with `markCompleted`/`markError`, finally unsub.
+Issue #232 wants to unify resume with the run lifecycle, and the architecture doc says "resume becomes a 4-line delegation."
+If we just move `RunHandle` to `Agent` as a separate class, `resume()` still can't use it naturally — the signatures differ.
+But if we dissolve `RunHandle` into Agent methods, both paths use the same primitives.
+
+## Goals
+
+- Zero `.then()`/`.catch()` in `agent-manager.ts`.
+- Dissolve `RunHandle` into Agent methods: `completeRun`, `failRun`, `wireSignal`, `attachObserver`, `releaseListeners`, `onRunFinished` setter.
+- `startAgent` is a straightforward async method: setup → await → handle result.
+- `spawn()` assigns `record.promise = this.startAgent(...)`.
+- Prepare the ground for #232 (resume unification) by giving Agent the run lifecycle primitives that `resume()` can reuse.
+
+## Non-Goals
+
+- **Resume unification** — deferred to #232.
+  That issue will use the new Agent methods to simplify `AgentManager.resume()`.
+- **`onSessionCreated` observer** — deferred to #229.
+  The `onSessionCreated` callback in `startAgent` stays as-is.
+- **`ConcurrencyQueue` extraction** — deferred to #230.
+- **Relay deps** — deferred to #231.
+
+## Background
+
+### Relevant modules
+
+| Module                                 | LOC | Relationship to this change                                   |
+| -------------------------------------- | --- | ------------------------------------------------------------- |
+| `src/lifecycle/agent-manager.ts`       | 492 | Loses `RunHandle` class (~85 LOC), `startAgent` becomes async |
+| `src/lifecycle/agent.ts`               | 260 | Gains run lifecycle methods (~80 LOC)                         |
+| `src/lifecycle/agent-runner.ts`        | —   | Exports `RunResult` type, now imported by `agent.ts`          |
+| `test/lifecycle/agent.test.ts`         | 501 | Gains ~120 LOC of run lifecycle tests                         |
+| `test/lifecycle/agent-manager.test.ts` | 768 | One assertion update (`Promise<void>`)                        |
+
+### What RunHandle does today
+
+| Concern                                                                | RunHandle method     | Who should own it                               |
+| ---------------------------------------------------------------------- | -------------------- | ----------------------------------------------- |
+| Listener lifecycle (unsub + detachFn)                                  | `releaseListeners()` | Agent — per-run cleanup handles                 |
+| Run completion (worktree cleanup, status transition, execution update) | `complete(result)`   | Agent — all state mutations target Agent fields |
+| Run failure (error marking, best-effort worktree cleanup)              | `fail(err)`          | Agent — same                                    |
+| Signal wiring (parent abort → child abort)                             | `wireSignal()`       | Agent — per-run handle, released on completion  |
+| Observer attachment (session event subscription)                       | `attachObserver()`   | Agent — per-run handle, released on completion  |
+| onFinished callback (concurrency drain)                                | `fireOnFinished()`   | Manager concern, but just a stored `() => void` |
+
+Five of six are Agent concerns.
+RunHandle reaches into `this.record` for every operation and talks through `this.record.worktreeState` to a stranger.
+
+### Dependency flow (no cycles)
+
+`agent.ts` gains a type-only import of `RunResult` from `agent-runner.ts`.
+`agent-runner.ts` imports from `agent-manager.ts` (not `agent.ts`), so no cycle is created.
+
+### Constraints from AGENTS.md
+
+- `promise` type change from `Promise<string>` to `Promise<void>` is internal — `Agent` is not exported from `package.json`.
+- Worktree setup hoist preserves the synchronous-throw contract in `spawn()` (callers rely on catching `isolation: "worktree"` errors synchronously).
+
+## Design Overview
+
+### Dissolve RunHandle into Agent methods
+
+Agent gains per-run listener fields and run lifecycle methods:
+
+```typescript
+class Agent {
+  // --- Per-run listener state (released on completion or resume reset) ---
+  private _unsub?: () => void;
+  private _detachFn?: () => void;
+  private _onRunFinished?: () => void;
+
+  /** Wire a parent AbortSignal so it stops this agent when fired. */
+  wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void;
+
+  /** Store the record-observer unsubscribe handle. */
+  attachObserver(unsub: () => void): void;
+
+  /** Release observer + signal listener handles. */
+  releaseListeners(): void;
+
+  /** Set the callback fired once when the run finishes (for concurrency drain). */
+  setOnRunFinished(fn: () => void): void;
+
+  /** Complete a run: release listeners, worktree cleanup, status transition,
+      execution update, fire onRunFinished. */
+  completeRun(result: RunResult, worktrees: WorktreeManager): void;
+
+  /** Fail a run: mark error, release listeners, best-effort worktree cleanup,
+      fire onRunFinished. */
+  failRun(err: unknown, worktrees: WorktreeManager): void;
+}
+```
+
+`completeRun` and `failRun` take `worktrees: WorktreeManager` as a parameter rather than storing it on Agent.
+Worktrees are only needed at run end — storing the reference would widen Agent's dependency surface for a single use.
+
+Consumer call-site after the change (`startAgent`):
+
+```typescript
+record.setOnRunFinished(
+  options.isBackground ? () => this.finalizeBackgroundRun(record) : undefined,
+);
+record.wireSignal(options.signal, () => this.abort(id));
+try {
+  const result = await this.runner.run(...);
+  record.completeRun(result, this.worktrees);
+} catch (err) {
+  record.failRun(err, this.worktrees);
+}
+```
+
+### Narrow `promise` to `Promise<void>`
+
+The resolved string value of `record.promise` is dead — every consumer just `await`s it and reads `record.result`.
+One test asserts `resolves.toBe("done")`; all others use `await record.promise`.
+Narrowing to `Promise<void>` first makes the async conversion clean (async `startAgent` naturally returns `Promise<void>`).
+
+### Hoist worktree setup from `startAgent` to callers
+
+`record.setupWorktree()` can throw synchronously (strict isolation failure).
+`spawn()` catches this and removes the orphan record.
+`drainQueue()` catches it and marks the record as errored.
+
+If `startAgent` becomes `async`, synchronous throws become rejected promises — neither caller catches them.
+Fix: move `record.setupWorktree()` into the callers' existing try-catch blocks before calling async `startAgent`.
+`startAgent` reads `record.worktreeState?.path` for the cwd instead.
+
+### `resetForResume` releases listeners
+
+After dissolution, `resetForResume` must call `releaseListeners()` and clear `_onRunFinished` to prevent stale handles from a previous run leaking into the resumed run.
+
+## Module-Level Changes
+
+### `src/lifecycle/agent.ts`
+
+1. Add per-run listener fields: `_unsub`, `_detachFn`, `_onRunFinished`.
+2. Add `wireSignal(signal, onAbort)` — logic from `RunHandle.wireSignal`.
+3. Add `attachObserver(unsub)` — logic from `RunHandle.attachObserver`.
+4. Add `releaseListeners()` — logic from `RunHandle.releaseListeners` (public).
+5. Add `setOnRunFinished(fn)` — stores the callback.
+6. Add private `fireOnRunFinished()` — idempotent clear-then-call pattern from `RunHandle.fireOnFinished`.
+7. Add `completeRun(result, worktrees)` — logic from `RunHandle.complete`, returns `void` (not `string`).
+8. Add `failRun(err, worktrees)` — logic from `RunHandle.fail`.
+9. Update `resetForResume` — call `releaseListeners()` and clear `_onRunFinished`.
+10. Change `promise` type from `Promise<string>` to `Promise<void>` (on both `AgentInit` and the class field).
+11. Add imports: `type RunResult` from `agent-runner`, `debugLog` from `debug`.
+
+### `src/lifecycle/agent-manager.ts`
+
+1. Delete `RunHandle` class (~85 lines).
+2. Remove `import type { RunResult }` (moved to `agent.ts`; `AgentRunner` import stays).
+3. Convert `startAgent` to `async`, returning `Promise<void>`.
+4. Replace RunHandle creation with Agent method calls: `record.setOnRunFinished(...)`, `record.wireSignal(...)`.
+5. Replace `handle.attachObserver(...)` with `record.attachObserver(...)` in `onSessionCreated`.
+6. Replace `.then()`/`.catch()` chain with `try { await ...; record.completeRun(...) } catch { record.failRun(...) }`.
+7. Remove `record.promise = this.runner.run(...)` assignment — `record.promise` is now assigned by `spawn`/`drainQueue`.
+8. In `spawn()`: hoist `record.setupWorktree(...)` before `startAgent` call (inside existing try-catch); assign `record.promise = this.startAgent(...)`.
+9. In `drainQueue()`: hoist `record.setupWorktree(...)` before `startAgent` call (inside existing try-catch); assign `record.promise = this.startAgent(...)`.
+10. In `startAgent`: remove `record.setupWorktree()` call; read `record.worktreeState?.path` for cwd.
+11. Update `waitForAll` filter: `Promise<string>` → `Promise<void>`.
+
+### `test/lifecycle/agent.test.ts`
+
+1. Add `describe("Agent — completeRun")` — status transitions (completed/aborted/steered), worktree cleanup with branch append, execution state update, `onRunFinished` fires once, listeners released.
+2. Add `describe("Agent — failRun")` — marks error, best-effort worktree cleanup, `onRunFinished` fires once, listeners released.
+3. Add `describe("Agent — wireSignal")` — connects parent signal to abort callback, `releaseListeners` detaches.
+4. Add `describe("Agent — attachObserver / releaseListeners")` — stores unsub, calls it on release, idempotent.
+5. Update `describe("Agent — resetForResume")` — verify listeners are released and `_onRunFinished` is cleared.
+
+### `test/lifecycle/agent-manager.test.ts`
+
+1. Update one assertion: `resolves.toBe("done")` → `resolves.toBeUndefined()`.
+
+### `packages/pi-subagents/docs/architecture/architecture.md`
+
+1. Update Phase 15 smell table — mark `startAgent` callback row as resolved.
+2. Update Step 2 description to note RunHandle dissolution (not just async conversion).
+3. Update Step 6 (#232) description — RunHandle no longer exists; Agent already has `completeRun`/`failRun`/`releaseListeners` that `resume()` can use directly.
+
+## Test Impact Analysis
+
+### New unit tests enabled by the dissolution
+
+1. **`Agent.completeRun()`** — isolated tests for run completion logic (status transitions based on `RunResult` flags, worktree cleanup, execution update, onRunFinished firing) without needing a full `AgentManager` scaffold with a mock runner.
+2. **`Agent.failRun()`** — isolated tests for error handling and best-effort cleanup.
+3. **`Agent.wireSignal()` / `Agent.attachObserver()` / `Agent.releaseListeners()`** — isolated tests for listener lifecycle without spawning a real agent.
+
+These behaviors were previously only testable through `AgentManager` integration tests that required setting up a mock runner, worktrees, and observer.
+
+### Existing tests that must stay
+
+1. All `AgentManager — spawn/spawnAndWait` tests — they verify the full spawn flow including async orchestration.
+2. All worktree isolation tests — they verify the synchronous-throw contract in `spawn()`.
+3. All queue/concurrency tests — they verify the manager's orchestration around `drainQueue`.
+4. All completion/notification tests — they verify end-to-end flow through the observer.
+
+### Existing tests that change
+
+1. One assertion in `agent-manager.test.ts`: `resolves.toBe("done")` → `resolves.toBeUndefined()` (promise type narrowing).
+
+## TDD Order
+
+1. **Narrow `Agent.promise` from `Promise<string>` to `Promise<void>`**
+   - Change `AgentInit.promise` and `Agent.promise` field types.
+   - In `startAgent`: wrap `.then()` callback body in braces (discard `handle.complete` return); remove `return ""` from `.catch()` callback.
+   - Update `waitForAll` filter type guard.
+   - Update one test assertion: `resolves.toBe("done")` → `resolves.toBeUndefined()`.
+   - Run `pnpm run check` + `pnpm vitest run`.
+   - Commit: `refactor(pi-subagents): narrow Agent.promise to Promise<void>`
+
+2. **Red/Green: add run lifecycle methods to Agent**
+   - Red: add tests in `agent.test.ts` for `completeRun`, `failRun`, `wireSignal`, `attachObserver`/`releaseListeners`, `resetForResume` listener cleanup.
+   - Green: implement the methods on `Agent` — `wireSignal`, `attachObserver`, `releaseListeners`, `setOnRunFinished`, `fireOnRunFinished`, `completeRun`, `failRun`; update `resetForResume`.
+   - Add `import type { RunResult }` and `import { debugLog }` to `agent.ts`.
+   - Run `pnpm run check` + `pnpm vitest run`.
+   - Commit: `feat(pi-subagents): add run lifecycle methods to Agent`
+
+3. **Replace RunHandle with Agent methods in `startAgent`, delete RunHandle**
+   - Replace `new RunHandle(record, this.worktrees, onFinished)` with `record.setOnRunFinished(onFinished)`.
+   - Replace `handle.wireSignal(...)` with `record.wireSignal(...)`.
+   - Replace `handle.attachObserver(...)` with `record.attachObserver(...)`.
+   - Replace `handle.complete(result)` with `record.completeRun(result, this.worktrees)`.
+   - Replace `handle.fail(err)` with `record.failRun(err, this.worktrees)`.
+   - Delete `RunHandle` class.
+   - Remove `import type { RunResult }` from `agent-manager.ts` (moved to `agent.ts`).
+   - Run `pnpm run check` + `pnpm vitest run`.
+   - Commit: `refactor(pi-subagents): replace RunHandle with Agent run lifecycle methods`
+
+4. **Hoist worktree setup from `startAgent` to callers**
+   - In `spawn()`: move `record.setupWorktree(this.worktrees, options.isolation)` before `this.startAgent()`, inside the existing try-catch.
+   - In `drainQueue()`: move `record.setupWorktree(this.worktrees, next.args.options.isolation)` before `this.startAgent()`, inside its try-catch.
+   - In `startAgent`: remove `record.setupWorktree()` call; use `record.worktreeState?.path` for `context.cwd`.
+   - Existing worktree isolation tests pass unchanged.
+   - Run `pnpm run check` + `pnpm vitest run`.
+   - Commit: `refactor(pi-subagents): hoist worktree setup from startAgent to callers`
+
+5. **Convert `startAgent` to async/await**
+   - Make `startAgent` async, returning `Promise<void>`.
+   - Replace `.then()`/`.catch()` chain with `try { const result = await this.runner.run(...); record.completeRun(result, this.worktrees); } catch (err) { record.failRun(err, this.worktrees); }`.
+   - Remove `record.promise = this.runner.run(...)` assignment from inside `startAgent`.
+   - In `spawn()`: assign `record.promise = this.startAgent(id, record, args)`.
+   - In `drainQueue()`: assign `record.promise = this.startAgent(next.id, record, next.args)`.
+   - Run `pnpm run check` + `pnpm vitest run`.
+   - Commit: `refactor(pi-subagents): convert startAgent to async/await`
+
+6. **Update architecture docs**
+   - Mark Phase 15 Step 2 smell row as resolved.
+   - Update Step 2 description to note RunHandle dissolution.
+   - Update Step 6 (#232) description: RunHandle no longer exists; Agent has `completeRun`/`failRun`/`releaseListeners` that `resume()` can use directly.
+   - Commit: `docs(pi-subagents): update architecture for async startAgent`
+
+## Risks and Mitigations
+
+1. **`resetForResume` must release listeners** — If not updated, resumed agents retain stale listener handles from the previous run.
+   Mitigated by step 2 explicitly updating `resetForResume` to call `releaseListeners()` and clear `_onRunFinished`, with a test.
+
+2. **Worktree hoist changes observer-throw semantics** — Currently, if `observer.onAgentStarted()` throws inside `startAgent`, `spawn()`'s try-catch catches it and removes the record.
+   After async conversion, that throw becomes a rejected promise.
+   This is a pre-existing inconsistency (`onAgentCompleted` is already wrapped in try-catch, `onAgentStarted` is not) and observers should not throw.
+   Mitigated by noting the inconsistency; a future step could add try-catch around `onAgentStarted`.
+
+3. **Agent grows by ~80 LOC** — Dissolving RunHandle adds methods to an already-substantial class.
+   Mitigated by the fact that these methods replace logic that already operated on Agent's fields — they belong here by SRP.
+   The net effect on `agent-manager.ts` is -85 LOC (RunHandle deletion), so the total codebase shrinks.
+
+4. **`completeRun` takes `worktrees` parameter instead of storing it** — This means every caller must pass worktrees.
+   Mitigated by there being exactly two callers today (startAgent and the future resume), both of which already have access to worktrees.
+   Storing it would widen Agent's dependency surface for a single use.
+
+## Open Questions
+
+None — the design direction (dissolve rather than move) is settled.
+The `worktrees` parameter vs. stored-reference question is resolved in favor of the parameter (ISP).