@gotgenes/pi-subagents 10.1.0 → 10.2.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [10.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.1.0...pi-subagents-v10.2.0) (2026-05-27)
+
+
+### Features
+
+* **pi-subagents:** add run lifecycle methods to Agent ([2a378f1](https://github.com/gotgenes/pi-packages/commit/2a378f1c82e977bdfee25931ab449757e364d589))
+
+
+### Documentation
+
+* **pi-subagents:** update architecture for async startAgent ([941eb10](https://github.com/gotgenes/pi-packages/commit/941eb109e71e4c51d5bb37a2a46ffc12f618d949))
+* plan async startAgent and RunHandle dissolution ([#228](https://github.com/gotgenes/pi-packages/issues/228)) ([647adf8](https://github.com/gotgenes/pi-packages/commit/647adf853fec63ea53afd63bc8204c89a6194bbe))
+* **retro:** add planning stage notes for issue [#228](https://github.com/gotgenes/pi-packages/issues/228) ([8dd9f8a](https://github.com/gotgenes/pi-packages/commit/8dd9f8ab7082c08e424b1b4a9557253af2ce584b))
+* **retro:** add retro notes for issue [#227](https://github.com/gotgenes/pi-packages/issues/227) ([78a4d64](https://github.com/gotgenes/pi-packages/commit/78a4d645f524465c64bf0b6ba1bcca37858e8721))
+* **retro:** add TDD stage notes for issue [#228](https://github.com/gotgenes/pi-packages/issues/228) ([ab497c5](https://github.com/gotgenes/pi-packages/commit/ab497c57723666d0635a0a08f9eecc06576da549))
+
 ## [10.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.0.1...pi-subagents-v10.1.0) (2026-05-27)
 
 

package/docs/architecture/architecture.md

@@ -55,7 +55,7 @@ flowchart TB
         direction TB
         AgentManager["AgentManager<br/>(spawn, queue, abort)"]
         AgentRunner["agent-runner<br/>(session, turns, results)"]
-        AgentRecord["Agent<br/>(status, behavior: abort/steer/worktree)"]
+        Agent["Agent<br/>(status, behavior: abort/steer/worktree/run lifecycle)"]
         ParentSnapshot["ParentSnapshot<br/>(frozen parent state)"]
         Worktree["worktree<br/>(git isolation)"]
     end
@@ -101,7 +101,7 @@ flowchart TB
 
 ```mermaid
 classDiagram
-    class AgentRecord {
+    class Agent {
         +id: string
         +type: SubagentType
         +description: string
@@ -124,6 +124,12 @@ classDiagram
         +queueSteer(message)
         +flushPendingSteers(session)
         +setupWorktree(worktrees, isolation)
+        +completeRun(result, worktrees)
+        +failRun(err, worktrees)
+        +wireSignal(signal, onAbort)
+        +attachObserver(unsub)
+        +releaseListeners()
+        +setOnRunFinished(fn)
     }
 
     class AgentManager {
@@ -160,7 +166,7 @@ classDiagram
         +hasRunning(): boolean
     }
 
-    AgentManager --> AgentRecord : creates/manages
+    AgentManager --> Agent : creates/manages
     AgentManager --> ParentSnapshot : receives at spawn
     SubagentsService --> AgentManager : wraps via adapter
     AgentManager --> AgentTypeRegistry : resolves types
@@ -266,7 +272,6 @@ src/
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── execution-state.ts          session/output phase state
 │   ├── permission-bridge.ts        optional bridge to pi-permission-system registry
-│   ├── run-handle.ts               per-run cleanup lifecycle
 │   ├── worktree.ts                 git worktree isolation
 │   ├── worktree-state.ts           worktree phase state
 │   └── usage.ts                    token usage tracking
@@ -684,21 +689,22 @@ See [phase-14-strip-policy.md](history/phase-14-strip-policy.md) for details.
 Phase 15 addresses the anemic domain model in the lifecycle layer.
 `AgentRecord` is a data bag — identity, status transitions, and stats — but no behavior.
 `AgentManager` reaches into records 37 times, doing work that belongs on the agent.
-Per-agent state (pending steers, abort logic, run lifecycle) is scattered across the manager, `RunHandle`, and a manager-level Map.
+Per-agent state (pending steers, abort logic, run lifecycle) was scattered across the manager, `RunHandle`, and a manager-level Map.
+`RunHandle` has been dissolved into `Agent` methods — see Step 2.
 
 The scheduling concern (queue, concurrency counter, drain) is tangled into `AgentManager` alongside collection management and run orchestration.
 `notifyConcurrencyChanged()` is a scheduling method exposed as a public API so settings can poke the queue — a cross-concern leak.
 
 ### Findings summary
 
-| Finding                                                       | Category     | Impact | Risk | Priority |
-| ------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
-| `AgentRecord` is anemic — no behavior, manager reaches in 37× | B: Oversized | 5      | 3    | 15       |
-| Scheduling tangled into `AgentManager` (3 fields, 3 methods)  | A: Coupling  | 4      | 2    | 12       |
-| `startAgent` uses `.then()`/`.catch()` instead of async/await | C: Callbacks | 3      | 2    | 10       |
-| `onSessionCreated` callback flows through 3 layers            | C: Callbacks | 3      | 2    | 10       |
-| `resume()` duplicates observer subscribe/unsubscribe pattern  | A: Redundant | 2      | 1    | 8        |
-| `exec`/`registry` relay-only deps on `AgentManager`           | C: Coupling  | 2      | 1    | 6        |
+| Finding                                                           | Category     | Impact | Risk | Priority |
+| ----------------------------------------------------------------- | ------------ | ------ | ---- | -------- |
+| `AgentRecord` is anemic — no behavior, manager reaches in 37×     | B: Oversized | 5      | 3    | 15       |
+| Scheduling tangled into `AgentManager` (3 fields, 3 methods)      | A: Coupling  | 4      | 2    | 12       |
+| ~~`startAgent` uses `.then()`/`.catch()` instead of async/await~~ | C: Callbacks | 3      | 2    | ✅       |
+| `onSessionCreated` callback flows through 3 layers                | C: Callbacks | 3      | 2    | 10       |
+| `resume()` duplicates observer subscribe/unsubscribe pattern      | A: Redundant | 2      | 1    | 8        |
+| `exec`/`registry` relay-only deps on `AgentManager`               | C: Coupling  | 2      | 1    | 6        |
 
 ### Step 1: Evolve AgentRecord into Agent with behavior — [#227] ✅ Complete
 
@@ -713,15 +719,17 @@ Move per-agent behavior from `AgentManager` into the agent:
 - Smell: B (anemic domain model) + C (manager reaching into records)
 - Outcome: `AgentManager` delegates via Tell-Don't-Ask; per-agent state lives on the agent
 
-### Step 2: Convert startAgent to async/await — [#228]
+### Step 2: Convert startAgent to async/await — [#228] ✅ Complete
 
-Convert `startAgent` from synchronous (returns void, assigns `record.promise` to a `.then()`/`.catch()` chain) to `async` (returns `Promise<void>`, uses try/catch).
+Converted `startAgent` to `async` with `try/catch` and dissolved `RunHandle` into `Agent` methods.
 `spawn()` assigns `record.promise = this.startAgent(...)` instead of calling `startAgent()` synchronously.
+`Agent` gained run lifecycle methods: `completeRun`, `failRun`, `wireSignal`, `attachObserver`, `releaseListeners`, `setOnRunFinished`.
+Worktree setup was hoisted to callers (`spawn`, `drainQueue`) to preserve the synchronous-throw contract.
 
 - Depends on: #227
-- Target: `src/lifecycle/agent-manager.ts`
+- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/agent.ts`
 - Smell: C (raw promise callbacks)
-- Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`
+- Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`; `RunHandle` deleted; Agent owns run lifecycle
 
 ### Step 3: Replace onSessionCreated callback with observer method — [#229]
 
@@ -751,10 +759,10 @@ Move them to `ConcreteAgentRunner` construction.
 - Smell: C (relay-only dependencies)
 - Outcome: `AgentManager` loses 2 fields; `AgentManagerOptions` shrinks from 7 to 5 fields
 
-### Step 6: Unify resume() with RunHandle pattern — [#232]
+### Step 6: Unify resume() with Agent run lifecycle methods — [#232]
 
-After #227 moves `RunHandle` ownership to the `Agent`, `resume()` on `AgentManager` becomes a 4-line delegation to `agent.resume(runner, prompt, signal)`.
-The agent manages its own observer subscription lifecycle.
+After #228 dissolved `RunHandle` into Agent methods (`completeRun`, `failRun`, `releaseListeners`), `resume()` on `AgentManager` becomes a short delegation to `agent.resume(runner, prompt, signal)`.
+The agent manages its own observer subscription lifecycle using the same methods that `startAgent` uses.
 
 - Depends on: #227, #228
 - Target: `src/lifecycle/agent-manager.ts`

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).

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

@@ -35,3 +35,46 @@ Test count went from 977 to 986 across 62 test files.
 - Biome auto-formatted several test files during the rename commit; re-staged and re-committed.
 - Pre-completion reviewer returned **WARN** for 4 stale diagram/table references in `architecture.md` and the `package-pi-subagents` skill table; all fixed before the final commit.
 - No deviations from the plan's behavior design; the `queueSteer` removal from manager interfaces worked exactly as anticipated in the retro notes.
+
+## Stage: Final Retrospective (2026-05-27T17:22:00Z)
+
+### Session summary
+
+Completed all stages in a single session: planning, 8 TDD steps, pre-completion review, shipping, and release as `pi-subagents-v10.1.0`.
+Three behaviors (`abort`, steer buffering, worktree setup) moved from `AgentManager` to `Agent`, followed by a codebase-wide rename (33 files).
+
+### Observations
+
+#### What went well
+
+- The "add behavior first, rename last" strategy kept behavior-adding commits small (1–2 files each) and the rename commit purely mechanical.
+- Planning identified that `queueSteer` could be removed from `AgentManagerLike` and `SteerToolManager` entirely — this simplified the delegation step and eliminated an unnecessary indirection layer.
+- Pre-completion reviewer caught 4 stale Mermaid diagram references and a skill table entry that the plan's step 8 did not anticipate; all fixed before shipping.
+
+#### What caused friction (agent side)
+
+1. `scope-drift` — Added `AgentInit` and `AgentStatus` to the `types.ts` re-export barrel during the rename step without verifying any file imports them from that path.
+   Impact: fallow flagged dead code, triggering a 4-call suppression trial (`unused-export` → `unused-types` → `unused-type`), then the user identified the real fix (remove the speculative re-exports entirely), requiring a follow-up `fix:` commit after docs were already done.
+2. `missing-context` — During the mechanical rename (step 7), `sed` commands matched `#test/helpers/make-record` but missed the relative import `"./helpers/make-record"` in `conversation-viewer.test.ts`.
+   Impact: `pnpm run check` caught it in 1 tool call; minimal rework.
+3. `missing-context` — The fallow skill documents `unused-export` as a suppression kind but not `unused-type`.
+   Impact: 3 wrong guesses before the correct suppression syntax.
+   Self-identified after fallow's error message suggested the correct kind name.
+
+#### What caused friction (user side)
+
+- The user's question about whether the fallow suppressions could be removed in a future step was a valuable prompt — it surfaced that the re-exports were speculative and could be removed immediately.
+  Earlier intervention (e.g., during the TDD stage when the suppressions were added) would have avoided the `fix:` commit.
+
+### Diagnostic details
+
+- **Model-performance correlation** — Pre-completion reviewer ran as `pre-completion-reviewer` subagent (default model); appropriate for judgment-heavy work (doc staleness, code design review).
+  No model mismatches.
+- **Feedback-loop gap analysis** — `pnpm run check` was run after every delegation step (steps 2, 4, 6, 7) and after every behavior-adding step (steps 1, 3, 5).
+  Verification was incremental throughout, not deferred to the end.
+  The `conversation-viewer.test.ts` import miss in step 7 was caught immediately by the type checker.
+
+### Changes made
+
+1. `.pi/skills/fallow/SKILL.md` — Added `unused-type` suppression example alongside existing `unused-export` example.
+2. `AGENTS.md` — Added "no speculative re-exports" rule to Code Style section.

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

@@ -0,0 +1,42 @@
+---
+issue: 228
+issue_title: "Convert startAgent to async/await, move run lifecycle to Agent (Phase 15, Step 2)"
+---
+
+# Retro: #228 — Convert startAgent to async/await, move run lifecycle to Agent
+
+## Stage: Planning (2026-05-27T20:00:00Z)
+
+### Session summary
+
+Planned the async `startAgent` conversion and decided to dissolve `RunHandle` into Agent methods rather than moving it as a separate class.
+Identified three preparatory steps (narrow promise type, add Agent methods, hoist worktree setup) that make the final async conversion a minimal diff.
+
+### Observations
+
+- The original issue proposed `Agent.createRunHandle()` as a factory, keeping RunHandle as a separate class.
+  Analysis showed 5 of 6 RunHandle concerns are Agent state mutations — RunHandle is doing work that belongs on Agent.
+  The clincher was `resume()` in `agent-manager.ts`: it duplicates RunHandle's pattern manually, and #232 wants to unify them.
+  Dissolving RunHandle gives both `startAgent` and `resume` the same primitives (`completeRun`, `failRun`, `releaseListeners`).
+- The synchronous-throw contract in `spawn()` for worktree failures requires hoisting `record.setupWorktree()` out of `startAgent` before the async conversion.
+  Without this prep step, async `startAgent` would turn the throw into a rejected promise that `spawn()` doesn't catch.
+- `promise: Promise<string>` → `Promise<void>` is safe because the resolved string is dead — every consumer reads `record.result` instead.
+  Only one test assertion reads the resolved value.
+- `completeRun`/`failRun` take `worktrees: WorktreeManager` as a parameter rather than storing it on Agent (ISP — only needed at run end, exactly two callers).
+
+## Stage: Implementation — TDD (2026-05-27T20:40:00Z)
+
+### Session summary
+
+Implemented all 6 TDD steps: narrowed `promise` to `Promise<void>`, added 6 run lifecycle methods to Agent (+19 tests), replaced `RunHandle` with Agent methods (-85 LOC), hoisted worktree setup to callers, converted `startAgent` to async/await, and updated architecture docs.
+Test count: 986 → 1005.
+
+### Observations
+
+- Step 1 (promise narrowing) required fixing 3 additional test files not listed in the plan: `make-agent.test.ts`, `service-adapter.test.ts`, `get-result-tool.test.ts`.
+  All were trivial `Promise.resolve("done")` → `Promise.resolve()` changes and a cast removal.
+- The lift-and-shift approach worked cleanly — each of the 5 implementation commits was small and independently green.
+  The most impactful commit was step 3 (replace RunHandle, -96/+6 lines) which was risk-free because step 2 had already introduced the Agent methods.
+- Pre-completion reviewer returned WARN for stale `AgentRecord` and `run-handle.ts` references in `architecture.md` class diagram and layout listing.
+  These were pre-existing staleness from #227's rename that wasn't fully propagated to Mermaid diagrams.
+  Fixed by amending the docs commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-manager.ts

@@ -12,7 +12,7 @@ import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import { debugLog } from "#src/debug";
 import { Agent } from "#src/lifecycle/agent";
-import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
+import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 
@@ -21,95 +21,6 @@ import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
-/**
- * RunHandle - per-run lifecycle object that owns cleanup state.
- *
- * Owns the observer unsubscribe and parent-signal detach handles acquired during
- * a run. Exposes `complete()` and `fail()` as the only way to finish a run,
- * eliminating mutable closure variables from `startAgent`.
- * `fireOnFinished` is idempotent - safe to call from both success and error paths.
- */
-class RunHandle {
-  private unsub?: () => void;
-  private detachFn?: () => void;
-  private onFinished?: () => void;
-
-  constructor(
-    private readonly record: Agent,
-    private readonly worktrees: WorktreeManager,
-    onFinished?: () => void,
-  ) {
-    this.onFinished = onFinished;
-  }
-
-  /** Wire a parent AbortSignal so it stops this agent when fired. */
-  wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
-    if (!signal) return;
-    const listener = () => onAbort();
-    signal.addEventListener("abort", listener, { once: true });
-    this.detachFn = () => signal.removeEventListener("abort", listener);
-  }
-
-  /** Store the record-observer unsubscribe handle (called from onSessionCreated). */
-  attachObserver(unsub: () => void): void {
-    this.unsub = unsub;
-  }
-
-  /** Complete a run successfully - clean up, transition record, fire onFinished. */
-  complete(result: RunResult): string {
-    this.releaseListeners();
-
-    let finalResult = result.responseText;
-    if (this.record.worktreeState) {
-      const wtResult = this.record.worktreeState.performCleanup(this.worktrees, this.record.description);
-      if (wtResult.hasChanges && wtResult.branch) {
-        finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
-      }
-    }
-
-    if (result.aborted) this.record.markAborted(finalResult);
-    else if (result.steered) this.record.markSteered(finalResult);
-    else this.record.markCompleted(finalResult);
-
-    // Update execution with the final session/outputFile from the runner
-    this.record.execution = {
-      session: result.session,
-      outputFile: result.sessionFile ?? this.record.execution?.outputFile,
-    };
-
-    this.fireOnFinished();
-    return result.responseText;
-  }
-
-  /** Fail a run - mark error, best-effort worktree cleanup, fire onFinished. */
-  fail(err: unknown): void {
-    this.record.markError(err);
-    this.releaseListeners();
-
-    if (this.record.worktreeState) {
-      try {
-        this.record.worktreeState.performCleanup(this.worktrees, this.record.description);
-      } catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
-    }
-
-    this.fireOnFinished();
-  }
-
-  private releaseListeners(): void {
-    this.unsub?.();
-    this.unsub = undefined;
-    this.detachFn?.();
-    this.detachFn = undefined;
-  }
-
-  /** Fire the onFinished callback at most once. */
-  private fireOnFinished(): void {
-    const fn = this.onFinished;
-    this.onFinished = undefined;
-    fn?.();
-  }
-}
-
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
 /** Observer interface for agent lifecycle notifications. */
@@ -252,10 +163,11 @@ export class AgentManager {
       return id;
     }
 
-    // startAgent can throw (e.g. strict worktree-isolation failure) - clean
+    // setupWorktree can throw (e.g. strict worktree-isolation failure) - clean
     // up the record so callers don't see an orphan in `listAgents()`.
     try {
-      this.startAgent(id, record, args);
+      record.setupWorktree(this.worktrees, options.isolation);
+      record.promise = this.startAgent(id, record, args);
     } catch (err) {
       this.agents.delete(id);
       throw err;
@@ -264,49 +176,49 @@ export class AgentManager {
   }
 
   /** Actually start an agent (called immediately or from queue drain). */
-  private startAgent(id: string, record: Agent, { snapshot, type, prompt, options }: SpawnArgs) {
-    const worktreeCwd = record.setupWorktree(this.worktrees, options.isolation);
-
+  private async startAgent(id: string, record: Agent, { snapshot, type, prompt, options }: SpawnArgs): Promise<void> {
     record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
     this.observer?.onAgentStarted(record);
 
-    const handle = new RunHandle(
-      record, this.worktrees,
+    record.setOnRunFinished(
       options.isBackground ? () => this.finalizeBackgroundRun(record) : undefined,
     );
-    handle.wireSignal(options.signal, () => this.abort(id));
+    record.wireSignal(options.signal, () => this.abort(id));
 
     const runConfig = this.getRunConfig?.();
-    record.promise = this.runner.run(snapshot, type, prompt, {
-      context: {
-        exec: this.exec,
-        registry: this.registry,
-        cwd: worktreeCwd,
-        parentSession: options.parentSession,
-      },
-      model: options.model,
-      maxTurns: options.maxTurns,
-      defaultMaxTurns: runConfig?.defaultMaxTurns,
-      graceTurns: runConfig?.graceTurns,
-      isolated: options.isolated,
-      thinkingLevel: options.thinkingLevel,
-      signal: record.abortController!.signal,
-      onSessionCreated: (session) => {
-        // Capture the session file path early so it's available for display
-        // before the run completes (e.g. in background agent status messages).
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
-        const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
-        record.execution = { session, outputFile };
-        record.flushPendingSteers(session);
-        handle.attachObserver(subscribeAgentObserver(session, record, {
-          onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
-        }));
-        options.onSessionCreated?.(session, record);
-      },
-    })
-      .then((result) => handle.complete(result))
-      .catch((err: unknown) => { handle.fail(err); return ""; });
+    try {
+      const result = await this.runner.run(snapshot, type, prompt, {
+        context: {
+          exec: this.exec,
+          registry: this.registry,
+          cwd: record.worktreeState?.path,
+          parentSession: options.parentSession,
+        },
+        model: options.model,
+        maxTurns: options.maxTurns,
+        defaultMaxTurns: runConfig?.defaultMaxTurns,
+        graceTurns: runConfig?.graceTurns,
+        isolated: options.isolated,
+        thinkingLevel: options.thinkingLevel,
+        signal: record.abortController!.signal,
+        onSessionCreated: (session) => {
+          // Capture the session file path early so it's available for display
+          // before the run completes (e.g. in background agent status messages).
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
+          const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
+          record.execution = { session, outputFile };
+          record.flushPendingSteers(session);
+          record.attachObserver(subscribeAgentObserver(session, record, {
+            onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
+          }));
+          options.onSessionCreated?.(session, record);
+        },
+      });
+      record.completeRun(result, this.worktrees);
+    } catch (err) {
+      record.failRun(err, this.worktrees);
+    }
   }
 
   /** Decrement background counter, notify observer (crash-safe), and drain the queue. */
@@ -323,7 +235,8 @@ export class AgentManager {
       const record = this.agents.get(next.id);
       if (record?.status !== "queued") continue;
       try {
-        this.startAgent(next.id, record, next.args);
+        record.setupWorktree(this.worktrees, next.args.options.isolation);
+        record.promise = this.startAgent(next.id, record, next.args);
       } catch (err) {
         // Late failure (e.g. strict worktree-isolation) - surface on the record
         // so the user/agent can see it via /agents, then keep draining.
@@ -471,7 +384,7 @@ export class AgentManager {
       const pending = [...this.agents.values()]
         .filter(r => r.status === "running" || r.status === "queued")
         .map(r => r.promise)
-        .filter((p): p is Promise<string> => p != null);
+        .filter((p): p is Promise<void> => p != null);
       if (pending.length === 0) break;
       await Promise.allSettled(pending);
     }

package/src/lifecycle/agent.ts

@@ -16,6 +16,8 @@
  */
 
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { debugLog } from "#src/debug";
+import type { RunResult } from "#src/lifecycle/agent-runner";
 import type { ExecutionState } from "#src/lifecycle/execution-state";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
@@ -44,7 +46,7 @@ export interface AgentInit {
 	error?: string;
 	abortController?: AbortController;
 	invocation?: AgentInvocation;
-	promise?: Promise<string>;
+	promise?: Promise<void>;
 }
 
 export class Agent {
@@ -83,7 +85,7 @@ export class Agent {
 	/** AbortController for cancelling this agent. Set at construction; used only by AgentManager. */
 	readonly abortController?: AbortController;
 	/** Promise for the full agent run (including post-processing). Set once by AgentManager. */
-	promise?: Promise<string>;
+	promise?: Promise<void>;
 
 	// Phase-specific collaborators — each born complete when their info becomes available
 	execution?: ExecutionState;
@@ -248,12 +250,90 @@ export class Agent {
 		this._pendingSteers = [];
 	}
 
-	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
+	/** Reset for resume: running status, new startedAt, clear completedAt/result/error/listeners. */
 	resetForResume(startedAt: number): void {
 		this._status = "running";
 		this._startedAt = startedAt;
 		this._completedAt = undefined;
 		this._result = undefined;
 		this._error = undefined;
+		this.releaseListeners();
+		this._onRunFinished = undefined;
+	}
+
+	// --- 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 {
+		if (!signal) return;
+		const listener = () => onAbort();
+		signal.addEventListener("abort", listener, { once: true });
+		this._detachFn = () => signal.removeEventListener("abort", listener);
+	}
+
+	/** Store the record-observer unsubscribe handle. */
+	attachObserver(unsub: () => void): void {
+		this._unsub = unsub;
+	}
+
+	/** Release observer + signal listener handles. */
+	releaseListeners(): void {
+		this._unsub?.();
+		this._unsub = undefined;
+		this._detachFn?.();
+		this._detachFn = undefined;
+	}
+
+	/** Set the callback fired once when the run finishes (for concurrency drain). */
+	setOnRunFinished(fn: (() => void) | undefined): void {
+		this._onRunFinished = fn;
+	}
+
+	/** Fire the onRunFinished callback at most once. */
+	private fireOnRunFinished(): void {
+		const fn = this._onRunFinished;
+		this._onRunFinished = undefined;
+		fn?.();
+	}
+
+	/** Complete a run: release listeners, worktree cleanup, status transition, execution update, fire onRunFinished. */
+	completeRun(result: RunResult, worktrees: WorktreeManager): void {
+		this.releaseListeners();
+
+		let finalResult = result.responseText;
+		if (this.worktreeState) {
+			const wtResult = this.worktreeState.performCleanup(worktrees, this.description);
+			if (wtResult.hasChanges && wtResult.branch) {
+				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+			}
+		}
+
+		if (result.aborted) this.markAborted(finalResult);
+		else if (result.steered) this.markSteered(finalResult);
+		else this.markCompleted(finalResult);
+
+		this.execution = {
+			session: result.session,
+			outputFile: result.sessionFile ?? this.execution?.outputFile,
+		};
+
+		this.fireOnRunFinished();
+	}
+
+	/** Fail a run: mark error, release listeners, best-effort worktree cleanup, fire onRunFinished. */
+	failRun(err: unknown, worktrees: WorktreeManager): void {
+		this.markError(err);
+		this.releaseListeners();
+
+		if (this.worktreeState) {
+			try {
+				this.worktreeState.performCleanup(worktrees, this.description);
+			} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
+		}
+
+		this.fireOnRunFinished();
 	}
 }