@gotgenes/pi-subagents 10.2.1 → 11.0.0

package/docs/retro/0229-agent-born-complete.md

@@ -0,0 +1,47 @@
+---
+issue: 229
+issue_title: "Agent born complete: Agent.run() absorbs startAgent (Phase 15, Step 4)"
+---
+
+# Retro: #229 — Agent born complete: Agent.run() absorbs startAgent
+
+## Stage: Planning (2026-05-27T18:00:00Z)
+
+### Session summary
+
+Produced a 9-step TDD plan for absorbing `AgentManager.startAgent()` into `Agent.run()`.
+Key design decisions: per-agent `AgentLifecycleObserver` interface passed at construction (chosen over callback fields and EventEmitter), and fully async worktree error surface (chosen over split sync/async).
+
+### Observations
+
+- **Observer pattern chosen over callbacks:** The per-agent `AgentLifecycleObserver` interface replaces three separate mechanisms (`onSessionCreated` callback, `setOnRunFinished`, `onCompact` callback).
+  All methods are optional, composed by `AgentManager.buildObserver()` per spawn.
+- **`ParentSessionInfo`/`CompactionInfo` relocation needed:** `agent.ts` importing from `agent-manager.ts` would create a circular type import (agent-manager already imports `Agent`).
+  Moving both types to `types.ts` in step 1 avoids the cycle.
+- **`AgentInit` grows wide (15+ optional fields):** Making run-config fields optional preserves backward compat for the 55+ `new Agent()` calls in tests.
+  Noted as a known smell — follow-up issues (#230 ConcurrencyQueue, potential `AgentInit` restructuring) may address this.
+- **Async error surface changes tool behavior:** `background-spawner.ts`'s try/catch around `manager.spawn()` becomes unreachable for worktree errors.
+  Keeping it for robustness; the error surfaces on `record.error` instead.
+- **Lift-and-shift TDD order:** Steps 3–5 incrementally change `AgentInit`, `setupWorktree`, and `completeRun`/`failRun` before step 6 adds `Agent.run()`.
+  This avoids a single massive step that rewrites everything at once.
+
+## Stage: Implementation — TDD (2026-05-28T01:00:00Z)
+
+### Session summary
+
+Completed all 9 TDD steps in 9 commits (plus 2 planning/retro docs commits).
+Test count went from 1005 to 1020 (+15 tests).
+`AgentManager.startAgent()`, `SpawnArgs`, and `onSessionCreated` callback are deleted.
+`Agent.run()` now owns the full execution lifecycle.
+
+### Observations
+
+- **Steps 7–8 merged in practice:** The tool-layer `onSessionCreated` → `observer` migration (step 8) had to be done alongside the `AgentSpawnConfig` change (step 7) because removing the `onSessionCreated` field broke compilation of `background-spawner.ts` and `foreground-runner.ts`.
+  This was expected — they share the same type.
+- **`setupWorktree` kept public:** The plan called for making it private in step 4, but it was kept public through step 6 since the manager still called it.
+  After step 7 (Agent.run() absorbs the call), it could be made private; left as a minor follow-up (reviewer flagged as WARN).
+- **`isBackground` removed from Agent storage:** The field was declared on `AgentInit` but Agent never reads it — the manager resolves `isBackground` before construction (setting initial status and composing the observer).
+  Biome flagged it as unused; removed from stored fields, kept on `AgentInit` for the manager's use.
+- **Worktree error surface confirmed async:** The `agent-manager.test.ts` test for synchronous worktree throw was rewritten to verify the error surfaces on `record.error` after awaiting the promise.
+  `background-spawner.ts` try/catch around `spawn()` retained for robustness.
+- **Pre-completion reviewer:** WARN — 3 non-blocking findings: `setupWorktree` not marked private, `isBackground` dead field on `AgentInit`, and `package-pi-subagents` SKILL.md Phase 15 description referencing deleted `startAgent`.

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

@@ -38,3 +38,34 @@ Pre-completion reviewer returned PASS.
   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.
+
+## Stage: Final Retrospective (2026-05-27T22:43:52Z)
+
+### Session summary
+
+Shipped #231 cleanly: CI passed on first push, issue closed, release `pi-subagents-v10.2.1` published.
+The entire issue (plan → TDD → ship) completed in one sitting with no user intervention needed.
+
+### Observations
+
+#### What went well
+
+- The `RunnerDeps` design was unambiguous — the `ask_user` gate in planning correctly identified the one genuine design choice (`RunContext` fate) and got user input before proceeding.
+- Pre-completion reviewer returned PASS with zero findings, confirming the mechanical refactoring was clean.
+- Merging plan steps 3–5 during TDD was the right call; the testing skill rule about single-call-site interfaces caught the plan's error before any broken commit landed.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan listed steps 3, 4, and 5 as separate commits and claimed "each commit is independently valid," but removing fields from `RunContext` (step 3) immediately caused TypeScript excess-property errors in `AgentManager` (step 4) and `index.ts` (step 5).
+  The existing `/plan-issue` rule (line 109) covers removing exports with single call sites, but did not trigger recognition because this was *shrinking* an interface, not removing one.
+  Impact: the TDD agent had to merge three steps on the fly — no rework, but the plan was misleading.
+- `missing-context` — The `sed`-based bulk replacement for `runAgent(..., io)` missed one multi-line call site where `}, io)` appeared on a different line than the opening `runAgent(`.
+  Impact: one extra manual edit; caught immediately by the test run.
+
+#### What caused friction (user side)
+
+- No friction observed — the user's involvement was limited to confirming the `RunContext` design choice during planning.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added a rule under TDD Order: when a step removes fields from an interface, include downstream object-literal call-site updates in the same step (TypeScript excess property checking).

package/package.json

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

package/src/lifecycle/agent-manager.ts

@@ -8,26 +8,22 @@
 
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
-import { Agent } from "#src/lifecycle/agent";
+import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
 import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 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, SubagentType, ThinkingLevel } from "#src/types";
-
-export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
+import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Observer interface for agent lifecycle notifications. */
 export interface AgentManagerObserver {
   onAgentStarted(record: Agent): void;
   onAgentCompleted(record: Agent): void;
   onAgentCompacted(record: Agent, info: CompactionInfo): void;
-  /** Fires synchronously after a background agent record is created (before startAgent). */
+  /** Fires synchronously after a background agent record is created (before run). */
   onAgentCreated(record: Agent): void;
 }
 
@@ -43,22 +39,6 @@ export interface AgentManagerOptions {
   observer?: AgentManagerObserver;
 }
 
-interface SpawnArgs {
-  snapshot: ParentSnapshot;
-  type: SubagentType;
-  prompt: string;
-  options: AgentSpawnConfig;
-}
-
-export interface ParentSessionInfo {
-  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
-  parentSessionFile?: string;
-  /** Session ID of the parent agent (stored in the child session's parentSession header). */
-  parentSessionId?: string;
-  /** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
-  toolCallId?: string;
-}
-
 export interface AgentSpawnConfig {
   description: string;
   model?: Model<any>;
@@ -79,8 +59,8 @@ export interface AgentSpawnConfig {
   invocation?: AgentInvocation;
   /** Parent abort signal - when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
-  /** Called when the agent session is created - receives the session and the agent's record. */
-  onSessionCreated?: (session: AgentSession, record: Agent) => void;
+  /** Per-agent lifecycle observer — replaces onSessionCreated callback. */
+  observer?: AgentLifecycleObserver;
   /** Parent session identity - grouped fields that travel together from the tool boundary. */
   parentSession?: ParentSessionInfo;
 }
@@ -94,8 +74,8 @@ export class AgentManager {
   private readonly _getMaxConcurrent: () => number;
   private getRunConfig?: () => RunConfig;
 
-  /** Queue of background agents waiting to start. */
-  private queue: { id: string; args: SpawnArgs }[] = [];
+  /** Queue of background agent IDs waiting to start. */
+  private queue: string[] = [];
   /** Number of currently running background agents. */
   private runningBackground = 0;
   constructor(options: AgentManagerOptions) {
@@ -117,6 +97,25 @@ export class AgentManager {
     this.drainQueue();
   }
 
+  /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
+  private buildObserver(options: AgentSpawnConfig): AgentLifecycleObserver {
+    return {
+      onStarted: (agent) => {
+        if (options.isBackground) this.runningBackground++;
+        this.observer?.onAgentStarted(agent);
+      },
+      onSessionCreated: options.observer?.onSessionCreated
+        ? (agent, session) => options.observer!.onSessionCreated!(agent, session)
+        : undefined,
+      onRunFinished: (agent) => {
+        if (options.isBackground) this.finalizeBackgroundRun(agent);
+      },
+      onCompacted: (agent, info) => {
+        this.observer?.onAgentCompacted(agent, info);
+      },
+    };
+  }
+
   /**
    * Spawn an agent and return its ID immediately (for background use).
    * If the concurrency limit is reached, the agent is queued.
@@ -128,90 +127,45 @@ export class AgentManager {
     options: AgentSpawnConfig,
   ): string {
     const id = randomUUID().slice(0, 17);
-    const abortController = new AbortController();
     const record = new Agent({
       id,
       type,
       description: options.description,
       status: options.isBackground ? "queued" : "running",
       startedAt: Date.now(),
-      abortController,
       invocation: options.invocation,
+      // Run config
+      snapshot,
+      prompt,
+      model: options.model,
+      maxTurns: options.maxTurns,
+      isolated: options.isolated,
+      thinkingLevel: options.thinkingLevel,
+      isolation: options.isolation,
+      parentSession: options.parentSession,
+      signal: options.signal,
+      // Shared deps
+      runner: this.runner,
+      worktrees: this.worktrees,
+      observer: this.buildObserver(options),
+      getRunConfig: this.getRunConfig,
     });
     this.agents.set(id, record);
 
-    if (options.parentSession?.toolCallId) {
-      record.notification = new NotificationState(options.parentSession.toolCallId);
-    }
-
     if (options.isBackground) {
       this.observer?.onAgentCreated(record);
     }
 
-    const args: SpawnArgs = { snapshot, type, prompt, options };
-
     if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
       // Queue it - will be started when a running agent completes
-      this.queue.push({ id, args });
+      this.queue.push(id);
       return id;
     }
 
-    // setupWorktree can throw (e.g. strict worktree-isolation failure) - clean
-    // up the record so callers don't see an orphan in `listAgents()`.
-    try {
-      record.setupWorktree(this.worktrees, options.isolation);
-      record.promise = this.startAgent(id, record, args);
-    } catch (err) {
-      this.agents.delete(id);
-      throw err;
-    }
+    record.promise = record.run();
     return id;
   }
 
-  /** Actually start an agent (called immediately or from queue drain). */
-  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);
-
-    record.setOnRunFinished(
-      options.isBackground ? () => this.finalizeBackgroundRun(record) : undefined,
-    );
-    record.wireSignal(options.signal, () => this.abort(id));
-
-    const runConfig = this.getRunConfig?.();
-    try {
-      const result = await this.runner.run(snapshot, type, prompt, {
-        context: {
-          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. */
   private finalizeBackgroundRun(record: Agent): void {
     this.runningBackground--;
@@ -222,18 +176,10 @@ export class AgentManager {
   /** Start queued agents up to the concurrency limit. */
   private drainQueue() {
     while (this.queue.length > 0 && this.runningBackground < this._getMaxConcurrent()) {
-      const next = this.queue.shift()!;
-      const record = this.agents.get(next.id);
+      const id = this.queue.shift()!;
+      const record = this.agents.get(id);
       if (record?.status !== "queued") continue;
-      try {
-        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.
-        record.markError(err);
-        this.observer?.onAgentCompleted(record);
-      }
+      record.promise = record.run();
     }
   }
 
@@ -301,7 +247,7 @@ export class AgentManager {
 
     // Remove from queue if queued
     if (record.status === "queued") {
-      this.queue = this.queue.filter(q => q.id !== id);
+      this.queue = this.queue.filter(qid => qid !== id);
       record.markStopped();
       return true;
     }
@@ -349,8 +295,8 @@ export class AgentManager {
   abortAll(): number {
     let count = 0;
     // Clear queued agents first
-    for (const queued of this.queue) {
-      const record = this.agents.get(queued.id);
+    for (const id of this.queue) {
+      const record = this.agents.get(id);
       if (record) {
         record.markStopped();
         count++;

package/src/lifecycle/agent-runner.ts

@@ -9,14 +9,13 @@ import {
   type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import type { ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { registerChildSession, unregisterChildSession } from "#src/lifecycle/permission-bridge";
 import { extractAssistantContent } from "#src/session/content-items";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
 import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
-import type { ShellExec, SubagentType, ThinkingLevel } from "#src/types";
+import type { ParentSessionInfo, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];

package/src/lifecycle/agent.ts

@@ -15,16 +15,32 @@
  * after construction as lifecycle information becomes available.
  */
 
+import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
-import type { RunResult } from "#src/lifecycle/agent-runner";
+import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
 import type { ExecutionState } from "#src/lifecycle/execution-state";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 import { WorktreeState } from "#src/lifecycle/worktree-state";
-import type { NotificationState } from "#src/observation/notification-state";
-import type { AgentInvocation, IsolationMode, SubagentType } from "#src/types";
+import { NotificationState } from "#src/observation/notification-state";
+import { subscribeAgentObserver } from "#src/observation/record-observer";
+import type { RunConfig } from "#src/runtime";
+import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+
+/** Per-agent lifecycle observer — created by AgentManager for each spawn. */
+export interface AgentLifecycleObserver {
+	/** Fires when the agent transitions to running (inside run(), after markRunning). */
+	onStarted?(agent: Agent): void;
+	/** Fires when the runner creates the session — delivers the session to external consumers. */
+	onSessionCreated?(agent: Agent, session: AgentSession): void;
+	/** Fires once when the run completes or fails (for concurrency drain). */
+	onRunFinished?(agent: Agent): void;
+	/** Fires on compaction events during the run. */
+	onCompacted?(agent: Agent, info: CompactionInfo): void;
+}
 
 export type AgentStatus =
 	| "queued"
@@ -36,17 +52,36 @@ export type AgentStatus =
 	| "error";
 
 export interface AgentInit {
+	// Identity
 	id: string;
 	type: SubagentType;
 	description: string;
+	invocation?: AgentInvocation;
+
+	// Status (for tests and restore scenarios)
 	status?: AgentStatus;
 	startedAt?: number;
 	completedAt?: number;
 	result?: string;
 	error?: string;
-	abortController?: AbortController;
-	invocation?: AgentInvocation;
-	promise?: Promise<void>;
+
+	// Shared deps (required for run(), optional for tests)
+	runner?: AgentRunner;
+	worktrees?: WorktreeManager;
+	observer?: AgentLifecycleObserver;
+	getRunConfig?: () => RunConfig;
+
+	// Run config (required for run(), optional for tests)
+	snapshot?: ParentSnapshot;
+	prompt?: string;
+	model?: Model<any>;
+	maxTurns?: number;
+	isolated?: boolean;
+	thinkingLevel?: ThinkingLevel;
+	isolation?: IsolationMode;
+	parentSession?: ParentSessionInfo;
+	isBackground?: boolean;
+	signal?: AbortSignal;
 }
 
 export class Agent {
@@ -82,11 +117,28 @@ export class Agent {
 	private _compactionCount: number;
 	get compactionCount(): number { return this._compactionCount; }
 
-	/** 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. */
+	/** AbortController for cancelling this agent. Created at construction. */
+	readonly abortController: AbortController;
+	/** Promise for the full agent run (including post-processing). Set by run(). */
 	promise?: Promise<void>;
 
+	// Shared deps — optional (required for run())
+	private readonly _runner?: AgentRunner;
+	private readonly _worktrees?: WorktreeManager;
+	readonly observer?: AgentLifecycleObserver;
+	private readonly _getRunConfig?: () => RunConfig;
+
+	// Run config — optional (required for run())
+	private readonly _snapshot?: ParentSnapshot;
+	private readonly _prompt?: string;
+	private readonly _model?: Model<any>;
+	private readonly _maxTurns?: number;
+	private readonly _isolated?: boolean;
+	private readonly _thinkingLevel?: ThinkingLevel;
+	private readonly _isolation?: IsolationMode;
+	private readonly _parentSession?: ParentSessionInfo;
+	private readonly _signal?: AbortSignal;
+
 	// Phase-specific collaborators — each born complete when their info becomes available
 	execution?: ExecutionState;
 	worktreeState?: WorktreeState;
@@ -96,10 +148,14 @@ export class Agent {
 	 * Create a git worktree for isolated execution, set worktreeState, and return the worktree path.
 	 * Returns undefined if isolation is not "worktree".
 	 * Throws if worktree creation fails (strict isolation).
+	 * Uses this._worktrees and this._isolation (set at construction).
 	 */
-	setupWorktree(worktrees: WorktreeManager, isolation: IsolationMode | undefined): string | undefined {
-		if (isolation !== "worktree") return undefined;
-		const wt = worktrees.create(this.id);
+	setupWorktree(): string | undefined {
+		if (this._isolation !== "worktree") return undefined;
+		if (!this._worktrees) {
+			throw new Error("Agent not configured for worktree isolation — missing worktrees dependency");
+		}
+		const wt = this._worktrees.create(this.id);
 		if (!wt) {
 			throw new Error(
 				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
@@ -126,22 +182,107 @@ export class Agent {
 	}
 
 	constructor(init: AgentInit) {
+		// Identity
 		this.id = init.id;
 		this.type = init.type;
 		this.description = init.description;
 		this.invocation = init.invocation;
 
+		// Status
 		this._status = init.status ?? "queued";
 		this._result = init.result;
 		this._error = init.error;
 		this._startedAt = init.startedAt ?? Date.now();
 		this._completedAt = init.completedAt;
 
+		// Stats
 		this._toolUses = 0;
 		this._lifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
 		this._compactionCount = 0;
-		this.abortController = init.abortController;
-		this.promise = init.promise;
+
+		// Abort controller — always created, never injected
+		this.abortController = new AbortController();
+
+		// Shared deps
+		this._runner = init.runner;
+		this._worktrees = init.worktrees;
+		this.observer = init.observer;
+		this._getRunConfig = init.getRunConfig;
+
+		// Run config
+		this._snapshot = init.snapshot;
+		this._prompt = init.prompt;
+		this._model = init.model;
+		this._maxTurns = init.maxTurns;
+		this._isolated = init.isolated;
+		this._thinkingLevel = init.thinkingLevel;
+		this._isolation = init.isolation;
+		this._parentSession = init.parentSession;
+		this._signal = init.signal;
+
+		// Notification state — created from parentSession.toolCallId if present
+		if (init.parentSession?.toolCallId) {
+			this.notification = new NotificationState(init.parentSession.toolCallId);
+		}
+	}
+
+	/**
+	 * Execute the full agent lifecycle: worktree setup, runner invocation,
+	 * session-creation handling, observer wiring, worktree cleanup, and
+	 * status transitions.
+	 *
+	 * Requires runner and snapshot to be set at construction.
+	 * The returned promise always resolves (errors are captured internally).
+	 */
+	async run(): Promise<void> {
+		if (!this._runner) {
+			throw new Error("Agent not configured for execution — missing runner");
+		}
+		if (!this._snapshot || !this._prompt) {
+			throw new Error("Agent not configured for execution — missing snapshot or prompt");
+		}
+
+		this.markRunning(Date.now());
+		this.observer?.onStarted?.(this);
+		this.wireSignal(this._signal, () => this.abort());
+
+		try {
+			this.setupWorktree();
+		} catch (err) {
+			this.markError(err);
+			this.observer?.onRunFinished?.(this);
+			return;
+		}
+
+		const runConfig = this._getRunConfig?.();
+		try {
+			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
+				context: {
+					cwd: this.worktreeState?.path,
+					parentSession: this._parentSession,
+				},
+				model: this._model,
+				maxTurns: this._maxTurns,
+				defaultMaxTurns: runConfig?.defaultMaxTurns,
+				graceTurns: runConfig?.graceTurns,
+				isolated: this._isolated,
+				thinkingLevel: this._thinkingLevel,
+				signal: this.abortController.signal,
+				onSessionCreated: (session) => {
+					// 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;
+					this.execution = { session, outputFile };
+					this.flushPendingSteers(session);
+					this.attachObserver(subscribeAgentObserver(session, this, {
+						onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+					}));
+					this.observer?.onSessionCreated?.(this, session);
+				},
+			});
+			this.completeRun(result);
+		} catch (err) {
+			this.failRun(err);
+		}
 	}
 
 	/** Increment tool use count. Called by record-observer on tool_execution_end. */
@@ -226,7 +367,7 @@ export class Agent {
 	 */
 	abort(): boolean {
 		if (this._status !== "running") return false;
-		this.abortController?.abort();
+		this.abortController.abort();
 		this.markStopped();
 		return true;
 	}
@@ -258,13 +399,11 @@ export class Agent {
 		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 {
@@ -287,25 +426,13 @@ export class Agent {
 		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 {
+	/** Complete a run: release listeners, worktree cleanup, status transition, execution update, notify observer. */
+	completeRun(result: RunResult): void {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
-		if (this.worktreeState) {
-			const wtResult = this.worktreeState.performCleanup(worktrees, this.description);
+		if (this.worktreeState && this._worktrees) {
+			const wtResult = this.worktreeState.performCleanup(this._worktrees, this.description);
 			if (wtResult.hasChanges && wtResult.branch) {
 				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
 			}
@@ -320,20 +447,20 @@ export class Agent {
 			outputFile: result.sessionFile ?? this.execution?.outputFile,
 		};
 
-		this.fireOnRunFinished();
+		this.observer?.onRunFinished?.(this);
 	}
 
-	/** Fail a run: mark error, release listeners, best-effort worktree cleanup, fire onRunFinished. */
-	failRun(err: unknown, worktrees: WorktreeManager): void {
+	/** Fail a run: mark error, release listeners, best-effort worktree cleanup, notify observer. */
+	failRun(err: unknown): void {
 		this.markError(err);
 		this.releaseListeners();
 
-		if (this.worktreeState) {
+		if (this.worktreeState && this._worktrees) {
 			try {
-				this.worktreeState.performCleanup(worktrees, this.description);
+				this.worktreeState.performCleanup(this._worktrees, this.description);
 			} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
 		}
 
-		this.fireOnRunFinished();
+		this.observer?.onRunFinished?.(this);
 	}
 }