@gotgenes/pi-subagents 10.2.0 → 10.2.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.2.0...pi-subagents-v10.2.1) (2026-05-27)
+
+
+### Documentation
+
+* **pi-subagents:** renumber Phase 15 steps to match execution order ([598bb65](https://github.com/gotgenes/pi-packages/commit/598bb653ac8b63756e8c00dfcf19d3167e2dbc37))
+* **pi-subagents:** revise Phase 15 roadmap for Agent-born-complete vision ([e04583e](https://github.com/gotgenes/pi-packages/commit/e04583e75bfc1314674a6f3181762a26733fb830))
+* plan push exec/registry relay deps to runner construction ([#231](https://github.com/gotgenes/pi-packages/issues/231)) ([646b4d5](https://github.com/gotgenes/pi-packages/commit/646b4d5085e0f7d36a397b43b3b46e0537c3141f))
+* **retro:** add planning stage notes for issue [#231](https://github.com/gotgenes/pi-packages/issues/231) ([dc0daee](https://github.com/gotgenes/pi-packages/commit/dc0daee634c17cf2a40336e27f551bfa2ce0e249))
+* **retro:** add retro notes for issue [#228](https://github.com/gotgenes/pi-packages/issues/228) ([d5b563b](https://github.com/gotgenes/pi-packages/commit/d5b563b6484cbd6a89cd7e9e87ebd431aed128fc))
+* **retro:** add TDD stage notes for issue [#231](https://github.com/gotgenes/pi-packages/issues/231) ([28094ae](https://github.com/gotgenes/pi-packages/commit/28094ae812141ea1c93a22be50ed29d31b7a979a))
+* update architecture for runner self-contained ([#231](https://github.com/gotgenes/pi-packages/issues/231)) ([80dd339](https://github.com/gotgenes/pi-packages/commit/80dd339d7dee9b312b52af2b74756c5748619a49))
+
 ## [10.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v10.1.0...pi-subagents-v10.2.0) (2026-05-27)
 
 

package/docs/architecture/architecture.md

@@ -599,23 +599,21 @@ export interface ParentSessionInfo {
 
 `AgentSpawnConfig` now carries `parentSession?: ParentSessionInfo` instead of three flat optional fields.
 
-#### RunOptions (12 fields → extract RunContext) — done ([#169][169])
+#### RunOptions (12 fields → extract RunContext) — done ([#169][169]), updated by [#231]
 
-The `RunOptions` bag mixes execution parameters with context information.
-`RunContext` was extracted and nested as `RunOptions.context`:
+`RunContext` was extracted and nested as `RunOptions.context` in #169.
+Issue #231 moved the two static dependencies (`exec`, `registry`) to `RunnerDeps` on `ConcreteAgentRunner`, leaving `RunContext` with only per-call fields:
 
 ```typescript
-/** Parent execution context — where/who is running. */
+/** Per-call execution context — fields that vary per spawn. */
 export interface RunContext {
-  exec: ShellExec;
-  registry: AgentConfigLookup;
   cwd?: string;
   parentSession?: ParentSessionInfo;
 }
 ```
 
 The remaining `RunOptions` fields (`model`, `maxTurns`, `signal`, `isolated`, `thinkingLevel`, `defaultMaxTurns`, `graceTurns`, `onSessionCreated`) are genuine execution parameters.
-`RunOptions` now has 9 fields: 1 nested `context: RunContext` plus 8 flat execution fields.
+`RunOptions` now has 9 fields: 1 nested `context: RunContext` (2 per-call fields) plus 8 flat execution fields.
 
 #### SessionConfig (11 fields → extract ToolFilterConfig) — done ([#168][168])
 
@@ -686,25 +684,66 @@ See [phase-14-strip-policy.md](history/phase-14-strip-policy.md) for details.
 
 ## Improvement roadmap (Phase 15 — domain model evolution)
 
-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) was scattered across the manager, `RunHandle`, and a manager-level Map.
-`RunHandle` has been dissolved into `Agent` methods — see Step 2.
+Phase 15 evolves `Agent` from a passive state machine into an object that **owns its entire execution lifecycle**.
+
+Steps 1–2 (complete) moved per-agent behavior from `AgentManager` onto `Agent`: abort, steer buffering, worktree setup, and run lifecycle methods (`completeRun`, `failRun`).
+However, Agent still cannot *run itself*.
+`AgentManager.startAgent()` orchestrates the entire execution: calling the runner, handling session creation, wiring observers, and cleaning up worktrees.
+The manager reaches into Agent 10 times across `spawn()` + `startAgent()` — writing to `notification`, `execution`, and `promise` after construction, passing its own `worktrees` and `runner` as method arguments, and threading `onSessionCreated` callbacks through three layers.
+
+The remaining steps address this by making **Agent born complete**: constructed with all dependencies and configuration, owning its entire execution lifecycle.
+
+### Architecture target
+
+Agent receives three concerns at construction:
+
+| Concern     | Fields                                                                        | Lifetime                  |
+| ----------- | ----------------------------------------------------------------------------- | ------------------------- |
+| Identity    | id, type, description, invocation                                             | Immutable                 |
+| Run config  | snapshot, prompt, model, isolation, maxTurns, thinking, signal, parentSession | Immutable per-run         |
+| Shared deps | runner, worktrees                                                             | Shared service references |
+
+`Agent.run()` encapsulates the full execution lifecycle:
+
+1. Set up worktree internally (knows its own isolation mode, has worktrees).
+2. Call `this.runner.run()` (has the runner).
+3. Handle session creation internally: set `execution`, flush pending steers, attach record-observer.
+4. Notify lifecycle observer (started, session created, completed, compacted).
+5. Clean up worktree on completion or error.
+6. Transition status.
+
+`AgentManager` becomes a collection manager + concurrency controller:
+
+- Creates complete Agent objects, stores them in the map.
+- Decides when to run (immediate or queue) and calls `agent.run()`.
+- Provides high-level actions: abort, list, cleanup.
+- Does *not* own the runner, worktrees, or any run-orchestration logic.
+
+The queue stores agent IDs, not `SpawnArgs`.
+When capacity opens, the manager looks up the agent and calls `agent.run()` — the agent already has everything.
+
+The `onSessionCreated` callback that currently threads through `AgentSpawnConfig` → `startAgent` → `RunOptions` → runner disappears.
+Agent handles session creation internally during `run()` and notifies external observers via the lifecycle observer pattern.
+
+The synchronous-throw contract for worktree failure (introduced in Step 2's hoist) is replaced by a uniform async error surface.
+Worktree failures inside `agent.run()` propagate through the promise.
+For background agents, errors surface via `get_subagent_result` and appear in `/agents`.
+For foreground agents, `spawnAndWait` awaits the promise naturally.
 
 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    | ✅       |
-| `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    | ✅       |
+| Agent cannot run itself — manager orchestrates 10 external touches | C: Coupling  | 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    | subsumed |
+| `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
 
@@ -731,43 +770,54 @@ Worktree setup was hoisted to callers (`spawn`, `drainQueue`) to preserve the sy
 - Smell: C (raw promise callbacks)
 - Outcome: zero `.then()`/`.catch()` in `agent-manager.ts`; `RunHandle` deleted; Agent owns run lifecycle
 
-### Step 3: Replace onSessionCreated callback with observer method — [#229]
+### Step 3: Push exec/registry relay deps to runner construction — [#231] ✅
 
-Add `onSessionCreated(agent, session)` to `AgentManagerObserver`.
-Remove the `onSessionCreated` callback from `AgentSpawnConfig`.
-Tool-layer code subscribes via the observer pattern instead of passing callbacks through the spawn config.
+`exec` and `registry` moved from `AgentManager` to `ConcreteAgentRunner` via a new `RunnerDeps` interface.
+`RunContext` shrunk from 4 to 2 per-call fields (`cwd`, `parentSession`).
+`AgentManagerOptions` shrunk from 7 to 5 fields.
 
-- Target: `src/lifecycle/agent-manager.ts`, `src/tools/background-spawner.ts`, `src/tools/foreground-runner.ts`
-- Smell: C (callback flowing through 3 layers)
-- Outcome: `AgentSpawnConfig` loses one callback field; session notification uses the observer pattern
+- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/agent-runner.ts`, `src/index.ts`
+- Smell: C (relay-only dependencies)
+- Outcome: `AgentManager` loses 2 fields; `AgentManagerOptions` shrinks from 7 to 5 fields; runner is self-contained
+
+### Step 4: Agent born complete — Agent.run() absorbs startAgent — [#229]
+
+Agent receives `runner`, `worktrees`, and a lifecycle observer at construction.
+Agent creates its own `NotificationState` from `parentSession.toolCallId` — no external write.
+`Agent.run()` encapsulates the entire execution lifecycle: worktree setup, runner invocation, session-creation handling, observer wiring, worktree cleanup, and status transitions.
+`startAgent` is deleted from `AgentManager`.
+The `onSessionCreated` callback is removed from `AgentSpawnConfig` — Agent handles session creation internally and notifies via the lifecycle observer.
+`SpawnArgs` is deleted — Agent has its config from construction.
+
+`AgentManager.spawn()` becomes: create complete Agent, put in map, call `agent.run()` or queue the agent ID.
+
+- Depends on: #228, #231
+- Target: `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`, `src/tools/background-spawner.ts`, `src/tools/foreground-runner.ts`
+- Smell: C (manager orchestrates 10 external touches on Agent) + C (callback flowing through 3 layers)
+- Outcome: Agent owns its entire execution lifecycle; `startAgent`, `SpawnArgs`, `onSessionCreated` callback deleted; zero post-construction writes from `AgentManager`
 
-### Step 4: Extract ConcurrencyQueue from AgentManager — [#230]
+### Step 5: Extract ConcurrencyQueue from AgentManager — [#230]
 
 Extract `queue[]`, `runningBackground`, `_getMaxConcurrent`, `drainQueue()`, `finalizeBackgroundRun()` into a `ConcurrencyQueue` class.
+The queue stores agent IDs — not `SpawnArgs`.
+Drain calls `agent.run()` directly — no worktree setup, no args threading.
 `SettingsManager` talks to the queue directly — `notifyConcurrencyChanged()` is eliminated from `AgentManager`.
 
+- Depends on: #229
 - Target: new `src/lifecycle/concurrency-queue.ts`, `src/lifecycle/agent-manager.ts`, `src/index.ts`
 - Smell: A (tangled concerns) + C (cross-concern leak via `notifyConcurrencyChanged`)
-- Outcome: `AgentManager` loses 3 fields, 3 methods (~40 lines); scheduling is independently testable
-
-### Step 5: Push exec/registry relay deps to runner construction — [#231]
-
-`AgentManager` receives `exec` and `registry` in its constructor but only relays them to `runner.run()` via `context`.
-Move them to `ConcreteAgentRunner` construction.
-
-- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/agent-runner.ts`, `src/index.ts`
-- Smell: C (relay-only dependencies)
-- Outcome: `AgentManager` loses 2 fields; `AgentManagerOptions` shrinks from 7 to 5 fields
+- Outcome: `AgentManager` loses 3 fields, 3 methods (~40 lines); scheduling is independently testable; queue interface is trivial (agent has everything)
 
-### Step 6: Unify resume() with Agent run lifecycle methods — [#232]
+### Step 6: Agent.resume() with internal observer lifecycle — [#232]
 
-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.
+Agent has the runner from construction.
+`Agent.resume(prompt, signal)` manages its own observer subscription lifecycle using the same internal wiring as `run()`.
+`AgentManager.resume()` becomes a one-liner delegation to `agent.resume(prompt, signal)` — no manual `subscribeRecordObserver` / try-finally.
 
-- Depends on: #227, #228
-- Target: `src/lifecycle/agent-manager.ts`
+- Depends on: #229
+- Target: `src/lifecycle/agent.ts`, `src/lifecycle/agent-manager.ts`
 - Smell: A (duplicated observer subscribe/unsubscribe pattern)
-- Outcome: no manual `subscribeRecordObserver` / try-finally in the manager
+- Outcome: `AgentManager.resume()` is a 4-line delegation; observer lifecycle is Agent-internal
 
 ### Step dependency diagram
 
@@ -775,28 +825,32 @@ The agent manages its own observer subscription lifecycle using the same methods
 flowchart LR
     S1["Step 1<br/>Agent with behavior"]
     S2["Step 2<br/>async startAgent"]
-    S3["Step 3<br/>onSessionCreated observer"]
-    S4["Step 4<br/>ConcurrencyQueue"]
-    S5["Step 5<br/>relay deps"]
-    S6["Step 6<br/>resume unification"]
+    S3["Step 3<br/>runner self-contained"]
+    S4["Step 4<br/>Agent.run()"]
+    S5["Step 5<br/>ConcurrencyQueue"]
+    S6["Step 6<br/>Agent.resume()"]
 
     S1 --> S2
-    S1 --> S6
-    S2 --> S6
-    S3 ~~~ S4
-    S4 ~~~ S5
+    S2 --> S4
+    S3 --> S4
+    S4 --> S5
+    S4 --> S6
 ```
 
 ### Tracks
 
-1. **Track A — Domain model** (Steps 1, 2, 6): Agent with behavior, async runs, resume unification.
-   Sequential — each depends on the previous.
-2. **Track B — Decoupling** (Steps 3, 4, 5): independent, can proceed in parallel with Track A.
+1. **Track A — Foundation** (Step 3): Runner becomes self-contained.
+   No dependencies on other Phase 15 steps; can start immediately.
+2. **Track B — Agent lifecycle** (Steps 4, 6): Agent born complete, owns run + resume.
+   Step 4 depends on Track A + Step 2.
+   Step 6 depends on Step 4.
+3. **Track C — Scheduling** (Step 5): ConcurrencyQueue extraction.
+   Depends on Step 4 (queue drains via `agent.run()`).
 
 ## Improvement roadmap (Phase 16 — invert dependencies)
 
 Phase 16 completes the architectural inversion by removing the outbound permission bridge and the `extensions: false` / `isolated` concepts.
-It depends on Phase 15's observer pattern (#229) as the replacement mechanism.
+It depends on Phase 15's lifecycle observer (#229) as the replacement mechanism.
 
 Phase 16 is scoped but not yet broken into steps.
 Key changes:
@@ -856,7 +910,7 @@ Detailed records are preserved in per-phase history files:
 | Phase 12           | #205, #206, #207, #208                                     | renderWidgetLines, showAgentDetail, widget update, shared test fixtures                                                                                  |
 | Phase 13           | #214, #215, #216, #217, #218, #219                         | Closure-to-class, buildParentContext, startAgent decomp, overwrite guard, settings SDK, test duplication                                                 |
 | Phase 14           | #237, #238, #239, #242                                     | Remove disallowed_tools, remove extensions filtering, collapse filterActiveTools, rename Agent to subagent                                               |
-| Phase 15           | #227, #228, #229, #230, #231, #232                         | Agent domain model, async startAgent, onSessionCreated observer, ConcurrencyQueue, relay deps, resume unification                                        |
+| Phase 15           | #227, #228, #231, #229, #230, #232                         | Agent domain model, async startAgent, runner self-contained, Agent.run(), ConcurrencyQueue, Agent.resume()                                               |
 
 The remaining open issue is #22 (parent-session resolution), a cross-extension track that does not gate the structural work.
 

package/docs/plans/0231-push-exec-registry-to-runner.md

@@ -0,0 +1,245 @@
+---
+issue: 231
+issue_title: "Push exec/registry relay deps to runner construction (Phase 15, Step 3)"
+---
+
+# Push exec/registry relay deps to runner construction
+
+## Problem Statement
+
+`AgentManager` receives `exec` and `registry` in its constructor but never uses them directly.
+They are stored as fields solely to relay them into `runner.run()` via the `RunContext` parameter.
+This makes `AgentManager` wider than necessary and prevents the runner from being self-contained — a prerequisite for #229 (Agent.run() absorbs startAgent).
+
+## Goals
+
+- Move `exec` and `registry` from `AgentManager` construction to `ConcreteAgentRunner` construction.
+- Remove `exec` and `registry` from `AgentManagerOptions` (7 → 5 fields).
+- Remove `exec` and `registry` from `RunContext` (4 → 2 fields).
+- Group runner-owned dependencies in a `RunnerDeps` interface: `{ io, exec, registry }`.
+- Replace `runAgent()`'s `io: RunnerIO` parameter with `deps: RunnerDeps`.
+
+## Non-Goals
+
+- Dissolving `RunContext` entirely — it shrinks to `{ cwd?, parentSession? }`, which is still a coherent per-call grouping.
+  Issue #229 will likely dissolve it when `Agent.run()` calls the runner directly.
+- Changing the `AgentRunner` interface's `run()` signature — callers continue to pass `RunOptions` with `context: RunContext`.
+  `ConcreteAgentRunner` merges its stored deps before calling `runAgent()`.
+- Touching `resume()` or `resumeAgent()` — they don't use `exec` or `registry`.
+
+## Background
+
+Issue #169 extracted `RunContext` from `RunOptions` to group the 4 parent-context fields: `exec`, `registry`, `cwd`, `parentSession`.
+The doc comment describes them as "parent environment and identity" fields.
+However, 2 of the 4 fields (`exec`, `registry`) are static — identical across every `run()` call — while the other 2 (`cwd`, `parentSession`) vary per spawn.
+The static pair are relay-only dependencies on `AgentManager`: stored at construction, never read, only forwarded.
+
+From the code-design skill, this is a **parameter relay** smell: intermediaries (`AgentManager`) carry fields they never use, only to thread them to the endpoint (`runAgent`).
+The fix: put them on the object the endpoint owns — the runner.
+
+### Key references
+
+- `src/lifecycle/agent-manager.ts` — stores `exec` and `registry`, relays them at lines 193–194.
+- `src/lifecycle/agent-runner.ts` — `RunContext` interface (line 125), `ConcreteAgentRunner` class (line 189), `runAgent()` free function (line 236).
+- `src/index.ts` — constructs both `ConcreteAgentRunner` and `AgentManager` (lines 148–157).
+- Phase 15 roadmap in `docs/architecture/architecture.md` § Step 3.
+
+## Design Overview
+
+### RunnerDeps — grouping runner-owned dependencies
+
+A new `RunnerDeps` interface groups the three dependencies that the runner owns:
+
+```typescript
+export interface RunnerDeps {
+  io: RunnerIO;
+  exec: ShellExec;
+  registry: AgentConfigLookup;
+}
+```
+
+`ConcreteAgentRunner` takes `RunnerDeps` at construction:
+
+```typescript
+export class ConcreteAgentRunner implements AgentRunner {
+  constructor(private readonly deps: RunnerDeps) {}
+
+  run(snapshot, type, prompt, options) {
+    return runAgent(snapshot, type, prompt, options, this.deps);
+  }
+}
+```
+
+`runAgent()` changes its last parameter from `io: RunnerIO` to `deps: RunnerDeps`:
+
+```typescript
+export async function runAgent(
+  snapshot: ParentSnapshot,
+  type: SubagentType,
+  prompt: string,
+  options: RunOptions,
+  deps: RunnerDeps,
+): Promise<RunResult> {
+  const effectiveCwd = options.context?.cwd ?? snapshot.cwd;
+  const env = await deps.io.detectEnv(deps.exec, effectiveCwd);
+  // ...
+  const cfg = assembleSessionConfig(type, ..., deps.registry, deps.io.assemblerIO);
+  // ...
+}
+```
+
+### RunContext shrinks
+
+`RunContext` loses `exec` and `registry`:
+
+```typescript
+export interface RunContext {
+  /** Override working directory (e.g. for worktree isolation). */
+  cwd?: string;
+  /** Parent session identity (file path + session ID). */
+  parentSession?: ParentSessionInfo;
+}
+```
+
+The `AgentRunner.run()` interface is unchanged — callers still pass `RunOptions` with `context: RunContext`.
+`ConcreteAgentRunner.run()` reads `exec` and `registry` from its own `deps` instead of from `options.context`.
+
+### AgentManager loses 2 fields
+
+`AgentManagerOptions` removes `exec` and `registry`.
+`AgentManager` removes the corresponding private fields and the `this.exec` / `this.registry` relay in `startAgent()`.
+The `context` object constructed in `startAgent()` shrinks from 4 fields to 2:
+
+```typescript
+context: {
+  cwd: record.worktreeState?.path,
+  parentSession: options.parentSession,
+},
+```
+
+### Wiring in index.ts
+
+```typescript
+const runner = new ConcreteAgentRunner({
+  io: runnerIO,
+  exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+  registry,
+});
+
+const manager = new AgentManager({
+  runner,
+  worktrees: new GitWorktreeManager(process.cwd()),
+  observer,
+  getMaxConcurrent: () => settings.maxConcurrent,
+  getRunConfig: () => settings,
+});
+```
+
+## Module-Level Changes
+
+### `src/lifecycle/agent-runner.ts`
+
+1. Add `RunnerDeps` interface (exported): `{ io: RunnerIO; exec: ShellExec; registry: AgentConfigLookup }`.
+2. Remove `exec` and `registry` from `RunContext`.
+   Update doc comment to reflect the 2 remaining per-call fields.
+3. Update `ConcreteAgentRunner` constructor: accept `RunnerDeps` instead of `RunnerIO`.
+4. Update `ConcreteAgentRunner.run()`: pass `this.deps` to `runAgent()`.
+5. Update `runAgent()`: change last parameter from `io: RunnerIO` to `deps: RunnerDeps`.
+   Replace `io.` references with `deps.io.`, `options.context.exec` with `deps.exec`, `options.context.registry` with `deps.registry`.
+
+### `src/lifecycle/agent-manager.ts`
+
+1. Remove `exec: ShellExec` and `registry: AgentTypeRegistry` from `AgentManagerOptions`.
+2. Remove `private readonly exec` and `private readonly registry` fields from `AgentManager`.
+3. Remove assignment of `this.exec` and `this.registry` in the constructor.
+4. Remove `exec: this.exec` and `registry: this.registry` from the `context` object in `startAgent()`.
+5. Remove `ShellExec` and `AgentTypeRegistry` imports (verify no other references first).
+
+### `src/index.ts`
+
+1. Move `exec` and `registry` from the `AgentManager` constructor call to `ConcreteAgentRunner`:
+   `new ConcreteAgentRunner({ io: runnerIO, exec: ..., registry })`.
+2. Remove `exec` and `registry` from the `AgentManager({...})` constructor argument.
+
+### `test/lifecycle/agent-runner.test.ts`
+
+1. Update all `runAgent(..., io)` calls to `runAgent(..., { io, exec, registry: mockAgentLookup })`.
+2. Remove `exec` and `registry` from `context:` objects in `RunOptions`.
+   `context: { exec, registry: mockAgentLookup }` → `context: {}` or `{}`.
+
+### `test/lifecycle/agent-runner-extension-tools.test.ts`
+
+1. Same pattern as `agent-runner.test.ts`: update `runAgent(..., io)` last param and strip `exec`/`registry` from `context:`.
+
+### `test/lifecycle/concrete-agent-runner.test.ts`
+
+1. Update `new ConcreteAgentRunner(io)` → `new ConcreteAgentRunner({ io, exec: vi.fn(), registry })`.
+2. Remove `exec` and `registry` from the `context:` in `runner.run()` call options.
+
+### `test/lifecycle/agent-manager.test.ts`
+
+1. Remove `exec: vi.fn()` and `registry: testRegistry` from `createManager()` factory.
+2. Remove the `testRegistry` construction and `AgentTypeRegistry` import if no other references exist.
+
+### `test/helpers/runner-io.ts`
+
+1. No structural changes needed — `createRunnerIO()` returns the `RunnerIO` shape, which is unchanged.
+   However, add a `createRunnerDeps()` convenience factory that bundles `{ io: createRunnerIO(), exec: vi.fn(), registry: createAgentLookup() }` for runner test files.
+
+### `docs/architecture/architecture.md`
+
+1. Update the `RunContext` code block in § "RunOptions (12 fields → extract RunContext)" to show only `cwd` and `parentSession`.
+2. Update the field-count description (4 → 2 per-call fields).
+3. Mark Step 3 as complete in the Phase 15 roadmap.
+
+## Test Impact Analysis
+
+1. No new test surfaces are needed — this is a pure mechanical refactoring (moving constructor parameters).
+   The existing runner and manager test suites fully cover the behavior.
+2. No existing tests become redundant — all tests exercise the same interactions, just with deps flowing through a different path.
+3. Existing `agent-manager.test.ts` tests remain as-is in coverage scope.
+   They verify `AgentManager` behavior (spawning, queueing, abort, etc.) independent of runner deps.
+4. Existing `agent-runner.test.ts` and `concrete-agent-runner.test.ts` tests remain.
+   They verify `runAgent()` and `ConcreteAgentRunner` behavior.
+   Call-site patterns change but assertions stay the same.
+
+## TDD Order
+
+1. **Add `RunnerDeps` interface and update `runAgent()` parameter** — define `RunnerDeps`, change `runAgent()`'s last param from `io` to `deps`, update internal references.
+   Update `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` call sites.
+   Commit: `refactor: add RunnerDeps and update runAgent parameter (#231)`
+
+2. **Update `ConcreteAgentRunner` to accept `RunnerDeps`** — change constructor from `RunnerIO` to `RunnerDeps`, update `.run()` to pass `this.deps`.
+   Update `concrete-agent-runner.test.ts`.
+   Add `createRunnerDeps()` helper to `test/helpers/runner-io.ts`.
+   Commit: `refactor: ConcreteAgentRunner accepts RunnerDeps (#231)`
+
+3. **Remove `exec` and `registry` from `RunContext`** — shrink the interface to 2 fields, update doc comment.
+   Strip `exec`/`registry` from `context:` in all runner test call sites.
+   Run `pnpm run check` to verify no stale references.
+   Commit: `refactor: remove exec and registry from RunContext (#231)`
+
+4. **Remove `exec` and `registry` from `AgentManager`** — remove from `AgentManagerOptions`, remove class fields, remove relay in `startAgent()`, clean up imports.
+   Update `agent-manager.test.ts` factory.
+   Commit: `refactor: remove relay deps from AgentManager (#231)`
+
+5. **Update wiring in `index.ts`** — move `exec` and `registry` from `AgentManager` construction to `ConcreteAgentRunner` construction.
+   Commit: `refactor: wire exec and registry to ConcreteAgentRunner (#231)`
+
+6. **Update architecture docs** — update `RunContext` description and field counts, mark Step 3 complete.
+   Commit: `docs: update architecture for runner self-contained (#231)`
+
+## Risks and Mitigations
+
+1. **Test churn** — ~20 `runAgent()` call sites change their last parameter pattern.
+   Mitigation: mechanical find-and-replace; assertions stay identical.
+2. **Step ordering** — Steps 3 and 4 both remove `exec`/`registry` from different types.
+   If done in the wrong order, intermediate commits may not type-check.
+   Mitigation: Step 1–2 add the new path (`deps`), Step 3 removes from `RunContext` (runner side), Step 4 removes from `AgentManager` (manager side), Step 5 wires them together.
+   Each commit is independently valid.
+3. **Import cleanup** — removing `exec`/`registry` from `AgentManager` may leave unused imports (`ShellExec`, `AgentTypeRegistry`).
+   Mitigation: grep for other usages before removing; `pnpm run check` catches unused imports.
+
+## Open Questions
+
+- None — the issue scope is narrow and the design is straightforward.

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

@@ -40,3 +40,41 @@ Test count: 986 → 1005.
 - 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.
+
+## Stage: Final Retrospective (2026-05-27T21:46:00Z)
+
+### Session summary
+
+Completed all stages (plan, TDD, ship, retro) in a single session.
+Dissolved `RunHandle` into 6 Agent methods, converted `startAgent` to async/await, released as `pi-subagents-v10.2.0`.
+Test delta: 986 → 1005 (+19).
+
+### Observations
+
+#### What went well
+
+- The user's two redirecting questions during planning ("What's the change that makes this easier?"
+  and "Tell me more about RunHandle — is there something that should replace it?") transformed a mechanical "move the class" plan into a "dissolve the abstraction" plan.
+  The dissolve approach is architecturally superior and sets up #232 (resume unification) for free.
+- The lift-and-shift decomposition (introduce Agent methods alongside `RunHandle`, then swap and delete) produced 5 independently-green commits.
+  The riskiest commit (step 3: delete `RunHandle`, -96/+6 lines) was trivially safe because step 2 had already proven the replacement methods.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — The agent planned around the issue's proposed `Agent.createRunHandle()` factory without questioning whether `RunHandle` should exist as a separate class.
+  The user had to ask two redirecting questions to push the analysis deeper.
+  Impact: plan was rewritten before commit (no wasted implementation), but the user spent two turns guiding analysis the agent should have done proactively.
+- `missing-context` — Plan step 1 (narrow `Promise<string>` to `Promise<void>`) listed only `agent-manager.test.ts` for updates but missed 3 additional test files (`make-agent.test.ts`, `service-adapter.test.ts`, `get-result-tool.test.ts`) that construct `Promise<string>` values.
+  The testing skill says "grep for all test files" for type changes — this was not applied during planning.
+  Impact: caught by `pnpm run check` in the same step, no rework.
+
+#### What caused friction (user side)
+
+- No friction observed.
+  The user's questioning style (asking "what does it do?
+  who needs it?"
+  rather than prescribing the solution) was collaborative and effective.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added relocation-dissolution heuristic: when an issue proposes moving a class, list callers and fields touched to check if it should be dissolved into the owner instead.

package/docs/retro/0231-push-exec-registry-to-runner.md

@@ -0,0 +1,40 @@
+---
+issue: 231
+issue_title: "Push exec/registry relay deps to runner construction (Phase 15, Step 3)"
+---
+
+# Retro: #231 — Push exec/registry relay deps to runner construction
+
+## Stage: Planning (2026-05-27T21:53:10Z)
+
+### Session summary
+
+Produced a 6-step TDD plan to move `exec` and `registry` from `AgentManager` to `ConcreteAgentRunner` via a new `RunnerDeps` interface.
+The plan keeps `RunContext` (shrunk to 2 per-call fields) rather than dissolving it — #229 will likely dissolve it when `Agent.run()` calls the runner directly.
+
+### Observations
+
+- Confirmed `exec` and `registry` are pure relay deps on `AgentManager` — stored at construction, used only at lines 193–194 to forward into `runner.run()`.
+- Chose `RunnerDeps` bag over separate positional params on `ConcreteAgentRunner` and `runAgent()` — groups all three runner-owned deps (`io`, `exec`, `registry`) in one interface, and `runAgent()` stays at 5 parameters.
+- `AgentManagerOptions.registry` uses the concrete `AgentTypeRegistry` class; `RunContext.registry` uses the narrow `AgentConfigLookup` interface.
+  The new `RunnerDeps.registry` uses `AgentConfigLookup` (ISP).
+- Test churn is moderate (~20 `runAgent()` call sites change last param pattern) but mechanical — assertions stay identical.
+- Added a `createRunnerDeps()` test helper to `runner-io.ts` to reduce per-file boilerplate in runner tests.
+
+## Stage: Implementation — TDD (2026-05-27T22:05:32Z)
+
+### Session summary
+
+Implemented the 6-step plan in 4 commits (steps 3–5 merged).
+All 1005 tests pass; no test count change.
+Pre-completion reviewer returned PASS.
+
+### Observations
+
+- Plan steps 3, 4, and 5 could not be separate commits: removing `exec`/`registry` from `RunContext` (step 3) immediately caused TypeScript excess-property errors in `AgentManager` (step 4) and `index.ts` (step 5).
+  Merged all three into one commit.
+  The testing skill’s rule “when a TDD step changes an interface that has a single call site, the step must include updating that call site” applies.
+- Shrinking `RunContext` to all-optional fields made pre-existing `as never` casts in `test/helpers/manager-stubs.test.ts` unnecessary (eslint `no-unnecessary-type-assertion`).
+  Fixed as a lint cleanup in the doc commit.
+- The `sed`-based bulk replacement for `runAgent(..., io)` → `runAgent(..., { io, exec, registry: mockAgentLookup })` missed one multi-line call site (the `rejects.toThrow` test wrapping the call in `expect()`).
+  Caught immediately by the test run.

package/package.json

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

package/src/index.ts

@@ -24,7 +24,7 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
-import { ConcreteAgentRunner, type RunnerIO } from "#src/lifecycle/agent-runner";
+import { ConcreteAgentRunner, type RunnerDeps } from "#src/lifecycle/agent-runner";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { GitWorktreeManager } from "#src/lifecycle/worktree";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
@@ -132,25 +132,27 @@ export default function (pi: ExtensionAPI) {
     },
   };
 
-  const runnerIO: RunnerIO = {
-    detectEnv,
-    getAgentDir,
-    createResourceLoader: (opts) => new DefaultResourceLoader(opts),
-    deriveSessionDir: deriveSubagentSessionDir,
-    createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
-    createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),
-    createSession: (opts) => createAgentSession(opts as any),
-    assemblerIO: {
-      preloadSkills,
-      buildAgentPrompt,
+  const runnerDeps: RunnerDeps = {
+    io: {
+      detectEnv,
+      getAgentDir,
+      createResourceLoader: (opts) => new DefaultResourceLoader(opts),
+      deriveSessionDir: deriveSubagentSessionDir,
+      createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
+      createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),
+      createSession: (opts) => createAgentSession(opts as any),
+      assemblerIO: {
+        preloadSkills,
+        buildAgentPrompt,
+      },
     },
+    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+    registry,
   };
 
   const manager = new AgentManager({
-    runner: new ConcreteAgentRunner(runnerIO),
+    runner: new ConcreteAgentRunner(runnerDeps),
     worktrees: new GitWorktreeManager(process.cwd()),
-    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
-    registry,
     observer,
     getMaxConcurrent: () => settings.maxConcurrent,
     getRunConfig: () => settings,

package/src/lifecycle/agent-manager.ts

@@ -9,7 +9,6 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 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 } from "#src/lifecycle/agent-runner";
@@ -19,7 +18,7 @@ import type { WorktreeManager } from "#src/lifecycle/worktree";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
-import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, IsolationMode, SubagentType, ThinkingLevel } from "#src/types";
 
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
@@ -38,8 +37,6 @@ const DEFAULT_MAX_CONCURRENT = 4;
 export interface AgentManagerOptions {
   runner: AgentRunner;
   worktrees: WorktreeManager;
-  exec: ShellExec;
-  registry: AgentTypeRegistry;
   /** Injected getter for the concurrency limit - owned by SettingsManager. */
   getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
@@ -94,8 +91,6 @@ export class AgentManager {
   private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
-  private readonly exec: ShellExec;
-  private readonly registry: AgentTypeRegistry;
   private readonly _getMaxConcurrent: () => number;
   private getRunConfig?: () => RunConfig;
 
@@ -106,8 +101,6 @@ export class AgentManager {
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
     this.worktrees = options.worktrees;
-    this.exec = options.exec;
-    this.registry = options.registry;
     this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
@@ -190,8 +183,6 @@ export class AgentManager {
     try {
       const result = await this.runner.run(snapshot, type, prompt, {
         context: {
-          exec: this.exec,
-          registry: this.registry,
           cwd: record.worktreeState?.path,
           parentSession: options.parentSession,
         },

package/src/lifecycle/agent-runner.ts

@@ -114,19 +114,27 @@ export interface SessionFactoryIO {
  */
 export type RunnerIO = EnvironmentIO & SessionFactoryIO;
 
+/**
+ * Dependencies owned by the runner — injected at construction time.
+ *
+ * Groups the IO boundary with the two static domain deps (exec, registry)
+ * that every run() call needs but that do not vary per call.
+ */
+export interface RunnerDeps {
+  io: RunnerIO;
+  exec: ShellExec;
+  registry: AgentConfigLookup;
+}
+
 // ── Public interfaces ─────────────────────────────────────────────────────────
 
 /**
- * Parent execution context - where/who is running.
+ * Per-call execution context — fields that vary per spawn.
  *
- * Groups the four fields that describe the parent environment and identity,
- * separating them from the per-call execution parameters in RunOptions.
+ * Static dependencies (exec, registry) live on RunnerDeps; this interface
+ * carries only the two per-call fields that AgentManager supplies at spawn time.
  */
 export interface RunContext {
-  /** Shell-exec callback for detectEnv - injected from pi.exec(). */
-  exec: ShellExec;
-  /** Agent config lookup - provides resolveAgentConfig and getToolNamesForType. */
-  registry: AgentConfigLookup;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
   /** Parent session identity (file path + session ID). */
@@ -182,15 +190,16 @@ export interface AgentRunner {
 }
 
 /**
- * Concrete AgentRunner backed by a RunnerIO boundary.
+ * Concrete AgentRunner backed by RunnerDeps.
  *
- * Captures io at construction time so AgentManager remains IO-unaware.
+ * Captures IO, exec, and registry at construction time so AgentManager
+ * remains unaware of runner-internal dependencies.
  */
 export class ConcreteAgentRunner implements AgentRunner {
-  constructor(private readonly io: RunnerIO) {}
+  constructor(private readonly deps: RunnerDeps) {}
 
   run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult> {
-    return runAgent(snapshot, type, prompt, options, this.io);
+    return runAgent(snapshot, type, prompt, options, this.deps);
   }
 
   resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string> {
@@ -253,11 +262,11 @@ export async function runAgent(
   type: SubagentType,
   prompt: string,
   options: RunOptions,
-  io: RunnerIO,
+  deps: RunnerDeps,
 ): Promise<RunResult> {
   // Resolve working directory upfront - needed for detectEnv before assembly.
   const effectiveCwd = options.context.cwd ?? snapshot.cwd;
-  const env = await io.detectEnv(options.context.exec, effectiveCwd);
+  const env = await deps.io.detectEnv(deps.exec, effectiveCwd);
 
   // Assemble session configuration (synchronous, no SDK objects).
   const cfg = assembleSessionConfig(
@@ -275,11 +284,11 @@ export async function runAgent(
       thinkingLevel: options.thinkingLevel,
     },
     env,
-    options.context.registry,
-    io.assemblerIO,
+    deps.registry,
+    deps.io.assemblerIO,
   );
 
-  const agentDir = io.getAgentDir();
+  const agentDir = deps.io.getAgentDir();
 
   // Load extensions/skills: true → load; false → don't.
   // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md - upstream's
@@ -287,7 +296,7 @@ export async function runAgent(
   // would defeat prompt_mode: replace and isolated: true. Parent context, if
   // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
   // is embedded in systemPromptOverride) or inherit_context (conversation).
-  const loader = io.createResourceLoader({
+  const loader = deps.io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
     noExtensions: !cfg.extensions,
@@ -303,15 +312,15 @@ export async function runAgent(
   // Create a persisted SessionManager so transcripts are written in Pi's
   // official JSONL format. Falls back to a temp directory when the parent
   // session is not persisted (e.g. headless/API mode).
-  const sessionDir = io.deriveSessionDir(options.context.parentSession?.parentSessionFile, cfg.effectiveCwd);
-  const sessionManager = io.createSessionManager(cfg.effectiveCwd, sessionDir);
+  const sessionDir = deps.io.deriveSessionDir(options.context.parentSession?.parentSessionFile, cfg.effectiveCwd);
+  const sessionManager = deps.io.createSessionManager(cfg.effectiveCwd, sessionDir);
   sessionManager.newSession({ parentSession: options.context.parentSession?.parentSessionId });
 
-  const { session } = await io.createSession({
+  const { session } = await deps.io.createSession({
     cwd: cfg.effectiveCwd,
     agentDir,
     sessionManager,
-    settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
+    settingsManager: deps.io.createSettingsManager(cfg.effectiveCwd, agentDir),
     modelRegistry: snapshot.modelRegistry,
     model: cfg.model,
     tools: cfg.toolNames,