@nklisch/pi-enhanced 0.2.7 → 0.3.1

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/lifecycle/subagent.ts

@@ -1,25 +1,25 @@
 /**
- * subagent.ts — Subagent class: identity, lifecycle status, and per-subagent behavior.
+ * The authoritative subagent record and its run leases.
  *
- * Status/stats are delegated to the SubagentState value object; listener
- * lifecycle to RunListeners; workspace prepare/dispose to WorkspaceBracket.
- * Behavior (abort, steer buffering) lives here rather than on SubagentManager.
+ * A record remains active until the current lease's settlement promise resolves.
+ * In particular, requesting a stop never fabricates terminal state while child
+ * code, teardown, or an admission callback can still mutate the workspace.
  */
 
-import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSessionEvent, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { debugLog, runDetached, runSafely } from "#src/debug";
+import type { AdmissionHandle } from "#src/lifecycle/concurrency-limiter";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
-import {
-  type LifecycleInterceptorRegistry,
-  type SubagentLifecycleExecutionPath,
-  type SubagentTurnLifecycle,
+import type {
+  LifecycleInterceptorRegistry,
+  SubagentLifecycleExecutionPath,
+  SubagentTurnLifecycle,
 } from "#src/lifecycle/lifecycle-interceptor";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { RunListeners } from "#src/lifecycle/run-listeners";
 import type { SubagentSession, TurnLoopResult } from "#src/lifecycle/subagent-session";
-import { SubagentState, type SubagentStatus } from "#src/lifecycle/subagent-state";
+import { SubagentState, type SubagentStatus, type SubagentStopReason, type SubagentTerminalReason } from "#src/lifecycle/subagent-state";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import { WorkspaceBracket } from "#src/lifecycle/workspace-bracket";
@@ -27,712 +27,581 @@ import { subscribeSubagentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
 import { formatModelLabel } from "#src/session/model-label";
 import { resolveEffectiveThinkingLevel } from "#src/session/thinking-level";
-import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SessionMessage, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SessionMessage, SubagentMode, SubagentType, ThinkingLevel } from "#src/types";
 
-/** Per-subagent lifecycle observer — created by SubagentManager for each spawn. */
 export interface SubagentLifecycleObserver {
-	/** Fires when the subagent transitions to running (inside run(), after markRunning). */
-	onStarted?(agent: Subagent): void;
-	/** Fires once the session is created — the subagent's subagentSession is now available. */
-	onSessionCreated?(agent: Subagent): void;
-	/** Fires once when the initial run completes or fails (for concurrency drain). */
-	onRunFinished?(agent: Subagent): void;
-	/** Fires once when a resumed turn reaches a terminal state. */
-	onResumedFinished?(agent: Subagent): void;
-	/** Fires on compaction events during the run. */
-	onCompacted?(agent: Subagent, info: CompactionInfo): void;
+  onStarted?(agent: Subagent): void;
+  onSessionCreated?(agent: Subagent): void;
+  onRunFinished?(agent: Subagent): void;
+  onResumedStarted?(agent: Subagent): void;
+  onResumedFinished?(agent: Subagent): void;
+  onCompacted?(agent: Subagent, info: CompactionInfo): void;
 }
 
-export type { SubagentStatus } from "#src/lifecycle/subagent-state";
-
-/**
- * The result of a steer attempt. `Subagent.steer` owns the non-running
- * rejection rule and reports it here, so coordinators switch on the outcome
- * instead of pre-checking status (tell by id, with outcomes).
- */
 export type SteerOutcome =
-	| { kind: "delivered" }
-	| { kind: "buffered" }
-	| { kind: "rejected"; status: SubagentStatus };
-
-/** A second prompt was requested while this record already owned an execution. */
-export class SubagentBusyError extends Error {
-	constructor(agentId: string) {
-		super(`Subagent "${agentId}" is still processing a turn. Wait for it to settle before resuming.`);
-		this.name = "SubagentBusyError";
-	}
-}
+  | { kind: "delivered"; runId: number }
+  | { kind: "buffered"; runId: number }
+  | { kind: "rejected"; runId: number; status: SubagentStatus };
 
-/**
- * The execution machinery a Subagent needs to run. A single mandatory
- * collaborator: production (SubagentManager.spawn) always supplies it, so run()
- * needs no "not configured" guards. The genuinely-optional behavior knobs stay
- * optional; the four inputs run() cannot proceed without are required.
- */
 export interface SubagentExecution {
-	/** Assembly factory that produces a born-complete SubagentSession. */
-	createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
-	/** Immutable spawn-time parent snapshot handed to the session factory. */
-	snapshot: ParentSnapshot;
-	/** Initial prompt for the turn loop. */
-	prompt: string;
-	/** Parent working directory handed to a workspace provider's prepare(). */
-	baseCwd: string;
-	observer?: SubagentLifecycleObserver;
-	getRunConfig?: () => RunConfig;
-	/** Resolves the registered workspace provider (if any) at run-start. */
-	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
-	model?: Model<any>;
-	maxTurns?: number;
-	thinkingLevel?: ThinkingLevel;
-	parentSession?: ParentSessionInfo;
-	/** Service-origin identity for lifecycle callbacks; never changes child setup. */
-	lifecycleParentSession?: ParentSessionInfo;
-	signal?: AbortSignal;
-	/** Owned by the manager; only a callback bridge reaches the child session. */
-	lifecycleInterceptors?: LifecycleInterceptorRegistry;
-	/** Spawn-path facts remain stable when the same child session resumes. */
-	executionPath?: SubagentLifecycleExecutionPath;
+  createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+  snapshot: ParentSnapshot;
+  prompt: string;
+  baseCwd: string;
+  mode: SubagentMode;
+  timeoutSeconds?: number;
+  observer?: SubagentLifecycleObserver;
+  getRunConfig?: () => RunConfig;
+  getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+  model?: Model<any>;
+  maxTurns?: number;
+  thinkingLevel?: ThinkingLevel;
+  parentSession?: ParentSessionInfo;
+  lifecycleParentSession?: ParentSessionInfo;
+  signal?: AbortSignal;
+  lifecycleInterceptors?: LifecycleInterceptorRegistry;
+  executionPath?: Omit<SubagentLifecycleExecutionPath, "phase" | "mode"> & { admission?: "immediate" | "queued" };
 }
 
 export interface SubagentInit {
-	// Identity
-	id: string;
-	type: SubagentType;
-	description: string;
-	invocation?: AgentInvocation;
+  id: string;
+  type: SubagentType;
+  description: string;
+  invocation?: AgentInvocation;
+  execution: SubagentExecution;
+  state?: SubagentState;
+}
 
-	/** Execution machinery — always supplied; construct-complete, no test fallbacks. */
-	execution: SubagentExecution;
+interface RunLease {
+  readonly runId: number;
+  readonly phase: "initial" | "resume";
+  readonly mode: SubagentMode;
+  readonly prompt: string;
+  readonly timeoutSeconds?: number;
+  readonly executionController: AbortController;
+  readonly settlement: Promise<void>;
+  readonly resolveSettlement: () => void;
+  admission?: AdmissionHandle;
+  admitted: boolean;
+  settled: boolean;
+  admissionPath: "immediate" | "queued";
+  startedAt?: number;
+  runtimeTimer?: ReturnType<typeof setTimeout>;
+  parentSignalCleanup?: () => void;
+  stopRequest?: SubagentStopReason;
+}
 
-	/** Lifecycle status and metrics. Defaults to a fresh queued state. */
-	state?: SubagentState;
+function deferred(): { promise: Promise<void>; resolve: () => void } {
+  let resolve!: () => void;
+  const promise = new Promise<void>((res) => { resolve = res; });
+  return { promise, resolve };
 }
 
 export class Subagent {
-	// Identity — set once at construction
-	readonly id: string;
-	readonly type: SubagentType;
-	readonly description: string;
-	readonly invocation?: AgentInvocation;
-
-	// Lifecycle status and metrics — owned by a private value object; getters and
-	// mutation methods below delegate to it one line.
-	private readonly state: SubagentState;
-	get status(): SubagentStatus { return this.state.status; }
-	get result(): string | undefined { return this.state.result; }
-	get error(): string | undefined { return this.state.error; }
-	get startedAt(): number { return this.state.startedAt; }
-	get completedAt(): number | undefined { return this.state.completedAt; }
-	get stoppedWhileQueued(): boolean { return this.state.stoppedWhileQueued; }
-	get consumedAt(): number | undefined { return this.state.consumedAt; }
-	get consumed(): boolean { return this.state.consumed; }
-	/** A blocking get-result call will deliver the next terminal outcome directly. */
-	get hasPendingResultWait(): boolean { return this.state.hasPendingResultWait; }
-	get toolUses(): number { return this.state.toolUses; }
-	get lifetimeUsage(): Readonly<LifetimeUsage> { return this.state.lifetimeUsage; }
-	get compactionCount(): number { return this.state.compactionCount; }
-	get turnCount(): number { return this.state.turnCount; }
-	get activeTools(): ReadonlyMap<string, string> { return this.state.activeTools; }
-	get responseText(): string { return this.state.responseText; }
-	get maxTurns(): number | undefined { return this.execution.maxTurns; }
-	/** Exact effective model label used by every operator-facing status surface. */
-	get modelLabel(): string { return this._modelLabel; }
-	/** Exact effective thinking level used by every operator-facing status surface. */
-	get effectiveThinkingLevel(): ThinkingLevel { return this._effectiveThinkingLevel; }
-
-	abortController: AbortController;
-	private _promise?: Promise<void>;
-	get promise(): Promise<void> | undefined { return this._promise; }
-
-	private readonly execution: SubagentExecution;
-	private _modelLabel: string;
-	private _effectiveThinkingLevel: ThinkingLevel;
-	private readonly listeners = new RunListeners();
-	private readonly workspaceBracket: WorkspaceBracket;
-	/** True while run()/runResume() owns the child prompt boundary. */
-	private executionInFlight = false;
-	/** Synchronous admission lease spanning wind-down, Pi idle, and resume. */
-	private resumeReserved = false;
-	private pendingResumeAbort?: AbortController;
-
-	subagentSession?: SubagentSession;
-	private releasedOutputFile?: string;
-	private _sessionReleased = false;
-	get sessionReleased(): boolean { return this._sessionReleased; }
-
-	// Steer buffer — messages queued before the session is ready
-	private _pendingSteers: string[] = [];
-	/** Number of steer messages waiting to be delivered. */
-	get pendingSteerCount(): number { return this._pendingSteers.length; }
-
-	/** Path to the agent's session JSONL file, or undefined if not yet available. */
-	get outputFile(): string | undefined {
-		return this.subagentSession?.outputFile ?? this.releasedOutputFile;
-	}
-
-	/** The tool call ID that spawned this background agent, if any. */
-	get toolCallId(): string | undefined {
-		return this.execution.parentSession?.toolCallId;
-	}
-
-	/** Returns true when a SubagentSession is available (session is ready). */
-	isSessionReady(): boolean {
-		return this.subagentSession != null;
-	}
-
-	isActive(): boolean {
-		return this.status === "queued" || this.status === "running" || this.resumeReserved;
-	}
-
-	isRunning(): boolean {
-		return this.status === "running";
-	}
-
-	/**
-	 * Steer a running agent, owning the non-running rejection rule.
-	 * Returns a `rejected` outcome (with the observed status) when the agent is
-	 * not running, a `buffered` outcome when the session is not yet ready, or a
-	 * `delivered` outcome once the message reaches the session.
-	 */
-	async steer(message: string): Promise<SteerOutcome> {
-		if (this.status !== "running") {
-			return { kind: "rejected", status: this.status };
-		}
-		if (!this.subagentSession) {
-			this.queueSteer(message);
-			return { kind: "buffered" };
-		}
-		await this.subagentSession.steer(message);
-		return { kind: "delivered" };
-	}
-
-	/** Return the session conversation as formatted text, or undefined if no session. */
-	getConversation(): string | undefined {
-		return this.subagentSession?.getConversation();
-	}
-
-	/** Return the session context window utilization (0-100), or null if unavailable. */
-	getContextPercent(): number | null {
-		return this.subagentSession?.getContextPercent() ?? null;
-	}
-
-	/**
-	 * Subscribe to session events for live updates (e.g., conversation viewer).
-	 * Returns an unsubscribe function, or undefined if no session is available.
-	 */
-	subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined {
-		return this.subagentSession?.subscribe(fn);
-	}
-
-	/** The session's message history, or an empty array if no session. */
-	get messages(): readonly unknown[] {
-		return this.subagentSession?.messages ?? [];
-	}
-
-	/** The session's message history typed for Pi's session-rendering machinery, or empty if no session. */
-	get agentMessages(): readonly SessionMessage[] {
-		return this.subagentSession?.agentMessages ?? [];
-	}
-
-	/** Resolve a registered tool definition by name, or undefined if no session. */
-	getToolDefinition(name: string): ToolDefinition | undefined {
-		return this.subagentSession?.getToolDefinition(name);
-	}
-
-	constructor(init: SubagentInit) {
-		// Identity
-		this.id = init.id;
-		this.type = init.type;
-		this.description = init.description;
-		this.invocation = init.invocation;
-
-		// Lifecycle status and metrics — fresh queued state unless one is supplied
-		this.state = init.state ?? new SubagentState();
-
-		// Abort controller — always created, never injected
-		this.abortController = new AbortController();
-
-		// Execution machinery — a single mandatory collaborator
-		this.execution = init.execution;
-		this._modelLabel = formatModelLabel(this.execution.model ?? this.execution.snapshot.model);
-		this._effectiveThinkingLevel = resolveEffectiveThinkingLevel(
-			this.execution.model ?? this.execution.snapshot.model,
-			this.execution.thinkingLevel,
-			this.execution.snapshot.thinkingLevel,
-		);
-
-		// Per-run lifecycle collaborators
-		this.workspaceBracket = new WorkspaceBracket(
-			this.execution.getWorkspaceProvider ?? (() => undefined),
-		);
-	}
-
-	/**
-	 * Execute the full agent lifecycle: workspace preparation, session creation
-	 * via the factory, observer wiring, the turn loop, workspace disposal, and
-	 * status transitions.
-	 *
-	 * Execution is supplied at construction (mandatory), so run() needs no
-	 * "not configured" guards. The returned promise always resolves (errors are
-	 * captured internally).
-	 */
-	async run(): Promise<void> {
-		this.executionInFlight = true;
-		this.markRunning(Date.now());
-		try {
-			// Observer callbacks are extension-owned sinks, not part of the agent's
-			// work. A stale UI/context callback must not leave a background record
-			// running with a slot held and no terminal notification.
-			runSafely("subagent onStarted observer", () => this.execution.observer?.onStarted?.(this));
-			this.listeners.wireSignal(this.execution.signal, () => this.abort());
-
-			// Guard the await so the no-provider path stays synchronous, preserving
-			// the original run() timing: the factory is called in the same turn as
-			// spawn() when no workspace provider is registered.
-			let cwd: string | undefined;
-			if (this.workspaceBracket.hasProvider()) {
-				cwd = await this.workspaceBracket.prepare({
-					agentId: this.id,
-					agentType: this.type,
-					baseCwd: this.execution.baseCwd,
-					invocation: this.invocation,
-				});
-			}
-
-			this.subagentSession = await this.execution.createSubagentSession({
-				snapshot: this.execution.snapshot,
-				type: this.type,
-				cwd,
-				parentSession: this.execution.parentSession,
-				model: this.execution.model,
-				thinkingLevel: this.execution.thinkingLevel,
-			});
-
-			// The SDK session is authoritative after creation: it has applied its
-			// defaults and model-capability clamp. Keep the record as the one source
-			// consumed by every operator-facing status surface.
-			this._modelLabel = formatModelLabel(this.subagentSession.model ?? this.execution.model ?? this.execution.snapshot.model);
-			this._effectiveThinkingLevel = this.subagentSession.thinkingLevel ?? this._effectiveThinkingLevel;
-
-			this.flushPendingSteers();
-			this.listeners.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
-				onCompact: (info) => runSafely(
-					"subagent onCompacted observer",
-					() => this.execution.observer?.onCompacted?.(this, info),
-				),
-			}));
-			runSafely("subagent onSessionCreated observer", () => this.execution.observer?.onSessionCreated?.(this));
-
-			const runConfig = this.execution.getRunConfig?.();
-			const lifecycle = this.createTurnLifecycle("initial");
-			const result = await this.subagentSession.runTurnLoop(this.execution.prompt, {
-				maxTurns: this.execution.maxTurns,
-				defaultMaxTurns: runConfig?.defaultMaxTurns,
-				graceTurns: runConfig?.graceTurns,
-				signal: lifecycle?.signal ?? this.abortController.signal,
-				...(lifecycle ? { lifecycle } : {}),
-			});
-			this.completeRun(result);
-		} catch (err) {
-			// One outer failure path guarantees terminal state, listener release,
-			// workspace cleanup, and the manager's completion funnel.
-			this.failRun(err);
-		} finally {
-			this.executionInFlight = false;
-		}
-	}
-
-	/**
-	 * Start execution immediately (foreground / bypassQueue paths).
-	 * Stores the run promise so it is awaitable via the `promise` getter.
-	 */
-	start(): void {
-		this._promise = this.guardedRun();
-	}
-
-	/**
-	 * Schedule execution through an external concurrency scheduler (the limiter).
-	 * Captures the scheduler's promise eagerly, so a still-queued agent is
-	 * awaitable via the `promise` getter from spawn — not only once its slot opens.
-	 * The guard in guardedRun() makes an abort-while-queued run a no-op when the
-	 * slot finally frees.
-	 */
-	scheduleVia(schedule: (thunk: () => Promise<void>) => Promise<void>): void {
-		this._promise = schedule(() => this.guardedRun());
-	}
-
-	/**
-	 * Run unless the agent left the active set before its slot opened
-	 * (e.g. abort-while-queued): a non-queued, non-running status resolves
-	 * immediately without running.
-	 */
-	private guardedRun(): Promise<void> {
-		if (this.status !== "queued" && this.status !== "running") return Promise.resolve();
-		return this.run();
-	}
-
-	/**
-	 * Resume an existing session with a new prompt, managing the observer
-	 * subscription lifecycle internally (same wiring as run()).
-	 *
-	 * Requires an existing SubagentSession (set when the original run created it).
-	 * The returned promise always resolves (errors are captured internally).
-	 * Parent cancellation and manager abort both stop the resumed turn.
-	 */
-	resume(prompt: string, signal?: AbortSignal): Promise<void> {
-		const subagentSession = this.subagentSession;
-		if (!subagentSession) {
-			return Promise.reject(new Error(
-				this.sessionReleased
-					? "Subagent session was released and can no longer be resumed"
-					: "Subagent not configured for resume — missing session",
-			));
-		}
-		if (this.status === "queued" || this.status === "running" || this.resumeReserved) {
-			return Promise.reject(new SubagentBusyError(this.id));
-		}
-
-		// Reserve synchronously before the first await. This closes both the
-		// concurrent-resume race and retention's release-while-waiting race.
-		this.resumeReserved = true;
-		const previousExecution = this.executionInFlight ? this._promise : undefined;
-		const resumeAbort = new AbortController();
-		this.pendingResumeAbort = resumeAbort;
-		const resumed = this.resumeWhenReady(
-			subagentSession,
-			previousExecution,
-			prompt,
-			resumeAbort,
-			signal,
-		);
-		this._promise = resumed;
-		return resumed;
-	}
-
-	private async resumeWhenReady(
-		subagentSession: SubagentSession,
-		previousExecution: Promise<void> | undefined,
-		prompt: string,
-		resumeAbort: AbortController,
-		signal?: AbortSignal,
-	): Promise<void> {
-		const waitSignal = signal
-			? AbortSignal.any([resumeAbort.signal, signal])
-			: resumeAbort.signal;
-		let started = false;
-		try {
-			// abort() marks a record stopped before AgentSession.prompt() necessarily
-			// settles. Wait for both the record-owned invocation and Pi's stronger
-			// idle boundary instead of racing a new prompt into the old one.
-			if (previousExecution) await previousExecution;
-			waitSignal.throwIfAborted();
-			await subagentSession.waitUntilIdle(waitSignal);
-			waitSignal.throwIfAborted();
-			if (this.subagentSession !== subagentSession) {
-				throw new Error("Subagent session was released while waiting to resume");
-			}
-
-			started = true;
-			this.executionInFlight = true;
-			this.resetForResume(Date.now(), resumeAbort);
-			await this.runResume(subagentSession, prompt, signal);
-		} catch (error) {
-			if (waitSignal.aborted) this.markStopped();
-			else this.markError(error);
-			if (!started) {
-				runSafely("subagent onResumedFinished observer", () => this.execution.observer?.onResumedFinished?.(this));
-			}
-		} finally {
-			if (started) this.executionInFlight = false;
-			if (this.pendingResumeAbort === resumeAbort) this.pendingResumeAbort = undefined;
-			this.resumeReserved = false;
-		}
-	}
-
-	private async runResume(
-		subagentSession: SubagentSession,
-		prompt: string,
-		signal?: AbortSignal,
-	): Promise<void> {
-		const executionSignal = signal
-			? AbortSignal.any([this.abortController.signal, signal])
-			: this.abortController.signal;
-		try {
-			this.listeners.attachObserver(subscribeSubagentObserver(subagentSession, this.state, {
-				onCompact: (info) => runSafely(
-					"subagent onCompacted observer",
-					() => this.execution.observer?.onCompacted?.(this, info),
-				),
-			}));
-
-			const lifecycle = this.createTurnLifecycle("resume", executionSignal);
-			if (lifecycle) {
-				const result = await subagentSession.resumeLifecycleTurnLoop(
-					prompt,
-					lifecycle.signal,
-					lifecycle,
-				);
-				if (result.failure) this.markFailed(result.failure, result.responseText);
-				else if (result.aborted) this.markAborted(result.responseText);
-				else if (result.steered) this.markSteered(result.responseText);
-				else this.markCompleted(result.responseText);
-			} else {
-				const resumed = await subagentSession.resumeTurnLoop(prompt, executionSignal);
-				const outcome = typeof resumed === "string" ? { text: resumed } : resumed;
-				if (outcome.failure) this.markFailed(outcome.failure, outcome.text);
-				else this.markCompleted(outcome.text);
-			}
-		} catch (err) {
-			this.markError(err);
-		} finally {
-			this.listeners.release();
-			runSafely("subagent onResumedFinished observer", () => this.execution.observer?.onResumedFinished?.(this));
-		}
-	}
-
-	/** Wait for the current queued, running, or resumed execution without cancelling it. */
-	async waitUntilSettled(signal: AbortSignal): Promise<void> {
-		const run = this._promise;
-		if (!run || (!this.executionInFlight && !this.resumeReserved) || signal.aborted) return;
-		await settleOrAbort(run, signal);
-	}
-
-	/**
-	 * Wait for a terminal result that the caller will return directly to the
-	 * parent. The claim begins synchronously, before the first await, so a child
-	 * that settles while the tool is blocked cannot also queue a follow-up nudge.
-	 */
-	async waitForResult(signal: AbortSignal): Promise<void> {
-		if (!this.isActive()) return;
-		this.state.beginResultWait();
-		try {
-			await this.waitUntilSettled(signal);
-		} finally {
-			this.state.endResultWait();
-		}
-	}
-
-	/** Build a callback-only lifecycle bridge after the immutable child session exists. */
-	private createTurnLifecycle(
-		phase: "initial" | "resume",
-		executionSignal: AbortSignal | undefined = this.abortController.signal,
-	): SubagentTurnLifecycle | undefined {
-		const registry = this.execution.lifecycleInterceptors;
-		const session = this.subagentSession;
-		if (!registry?.hasInterceptors() || !session) return undefined;
-		const initialPath = this.execution.executionPath ?? {
-			phase: "initial" as const,
-			origin: "service" as const,
-			mode: "foreground" as const,
-			admission: "immediate" as const,
-		};
-		const lifecycleParent = this.execution.lifecycleParentSession ?? this.execution.parentSession;
-		return registry.createTurnLifecycle({
-			identity: {
-				agentId: this.id,
-				sessionId: session.sessionId,
-				runId: randomUUID(),
-				agentType: this.type,
-				...(lifecycleParent?.parentSessionId
-					? { parentSessionId: lifecycleParent.parentSessionId }
-					: {}),
-			},
-			execution: { ...initialPath, phase },
-			signal: executionSignal === this.abortController.signal
-				? executionSignal
-				: AbortSignal.any([this.abortController.signal, executionSignal]),
-		});
-	}
-
-	/** Increment tool use count. Called by record-observer on tool_execution_end. */
-	incrementToolUses(): void {
-		this.state.incrementToolUses();
-	}
-
-	/** Accumulate a usage delta into lifetimeUsage. Called by record-observer on message_end. */
-	addUsage(delta: { input: number; output: number; cacheWrite: number }): void {
-		this.state.addUsage(delta);
-	}
-
-	/** Increment compaction count. Called by record-observer on compaction_end. */
-	incrementCompactions(): void {
-		this.state.incrementCompactions();
-	}
-
-	/** Transition to running state. Sets status and startedAt. */
-	markRunning(startedAt: number): void {
-		this.state.markRunning(startedAt);
-	}
-
-	/**
-	 * Transition to completed state.
-	 * Always sets result and completedAt (??=). Only changes status if not stopped.
-	 */
-	markCompleted(result: string, completedAt?: number): void {
-		this.state.markCompleted(result, completedAt);
-	}
-
-	/**
-	 * Transition to aborted state.
-	 * Always sets result and completedAt (??=). Only changes status if not stopped.
-	 */
-	markAborted(result: string, completedAt?: number): void {
-		this.state.markAborted(result, completedAt);
-	}
-
-	/**
-	 * Transition to steered state.
-	 * Always sets result and completedAt (??=). Only changes status if not stopped.
-	 */
-	markSteered(result: string, completedAt?: number): void {
-		this.state.markSteered(result, completedAt);
-	}
-
-	/**
-	 * Transition to error state.
-	 * Always sets error (formatted) and completedAt (??=). Only changes status if not stopped.
-	 */
-	markError(error: unknown, completedAt?: number): void {
-		this.state.markError(error, completedAt);
-	}
-
-	/** Record a provider failure and preserve any partial output. */
-	markFailed(error: unknown, partialResult?: string, completedAt?: number): void {
-		this.state.markFailed(error, partialResult, completedAt);
-	}
-
-	/** Transition to stopped state. Always valid — no guard. */
-	markStopped(completedAt?: number): void {
-		this.state.markStopped(completedAt);
-	}
-
-	markConsumed(at?: number): void {
-		this.state.markConsumed(at);
-	}
-
-	/** Stop a queued agent through the same terminal observer funnel as a run. */
-	stopQueued(): void {
-		this.state.stopQueued();
-		runSafely("subagent onRunFinished observer", () => this.execution.observer?.onRunFinished?.(this));
-	}
-
-	/**
-	 * Abort a running agent: fire AbortController and transition to stopped.
-	 * Returns false if the agent is not running.
-	 * A still-queued agent is stopped by SubagentManager; its scheduled thunk
-	 * then no-ops on the queued-status guard.
-	 */
-	abort(): boolean {
-		if (this.status !== "running" && !this.resumeReserved) return false;
-		this.abortController.abort();
-		this.pendingResumeAbort?.abort();
-		this.markStopped();
-		return true;
-	}
-
-	/**
-	 * Buffer a steer message for delivery once the session is ready.
-	 * Called internally from steer() before the session is ready.
-	 */
-	private queueSteer(message: string): void {
-		this._pendingSteers.push(message);
-	}
-
-	/**
-	 * Flush all buffered steer messages to the session and clear the buffer.
-	 * Called once the session is available (inside run()).
-	 */
-	private flushPendingSteers(): void {
-		for (const msg of this._pendingSteers) {
-			runDetached("subagent buffered steer", () => this.subagentSession?.steer(msg));
-		}
-		this._pendingSteers = [];
-	}
-
-	/** Reset for resume: running status, new startedAt, clear completedAt/result/error/listeners. */
-	resetForResume(startedAt: number, controller = new AbortController()): void {
-		this.abortController = controller;
-		this.state.resetForResume(startedAt);
-		this.listeners.release();
-	}
-
-	/** Complete a run: release listeners, dispose the workspace, status transition, notify observer. */
-	completeRun(result: TurnLoopResult): void {
-		this.listeners.release();
-
-		const finalStatus: SubagentStatus = result.failure
-			? "error"
-			: result.aborted
-				? "aborted"
-				: result.steered
-					? "steered"
-					: "completed";
-		let finalResult = result.responseText;
-		try {
-			finalResult += this.workspaceBracket.dispose({ status: finalStatus, description: this.description });
-		} catch (error) {
-			// Workspace teardown belongs to the run's terminal boundary. If it
-			// fails, report an error once rather than re-entering disposal from the
-			// outer catch path.
-			this.failRun(error);
-			return;
-		}
-
-		if (result.failure) this.markFailed(result.failure, finalResult);
-		else if (result.aborted) this.markAborted(finalResult);
-		else if (result.steered) this.markSteered(finalResult);
-		else this.markCompleted(finalResult);
-
-		runSafely("subagent onRunFinished observer", () => this.execution.observer?.onRunFinished?.(this));
-	}
-
-	/** Dispose the wrapped session, firing the `disposed` lifecycle event. */
-	async disposeSession(): Promise<void> {
-		const session = this.subagentSession;
-		if (!session) return;
-		// Detach first: callers must not admit a resume while asynchronous
-		// extension shutdown is in progress.
-		this.subagentSession = undefined;
-		await session.dispose();
-	}
-
-	/** Release heavy session state while preserving the transcript pointer and record. */
-	async releaseSession(): Promise<void> {
-		const session = this.subagentSession;
-		if (!session) return;
-		this.releasedOutputFile = session.outputFile;
-		// The record becomes non-resumable atomically at release admission, not
-		// after extension shutdown finishes.
-		this.subagentSession = undefined;
-		this._sessionReleased = true;
-		await session.dispose();
-	}
-
-	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
-	failRun(err: unknown): void {
-		this.markError(err);
-		this.listeners.release();
-
-		try {
-			this.workspaceBracket.dispose({ status: "error", description: this.description });
-		} catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
-
-		runSafely("subagent onRunFinished observer", () => this.execution.observer?.onRunFinished?.(this));
-	}
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly invocation?: AgentInvocation;
+
+  private readonly state: SubagentState;
+  private readonly execution: SubagentExecution;
+  private readonly listeners = new RunListeners();
+  private readonly workspaceBracket: WorkspaceBracket;
+  private currentLease: RunLease;
+  private nextRunId = 1;
+  private _modelLabel: string;
+  private _effectiveThinkingLevel: ThinkingLevel;
+  private _sessionReleased = false;
+  private releasedOutputFile?: string;
+  private pendingResumeAbort?: AbortController;
+  private pendingSteers: string[] = [];
+  private readonly recordUpdateListeners = new Set<() => void>();
+  private runtimeMs = 0;
+
+  subagentSession?: SubagentSession;
+
+  get status(): SubagentStatus { return this.state.status; }
+  get result(): string | undefined { return this.state.result; }
+  get error(): string | undefined { return this.state.error; }
+  get startedAt(): number { return this.state.startedAt; }
+  get completedAt(): number | undefined { return this.state.completedAt; }
+  get consumedAt(): number | undefined { return this.state.consumedAt; }
+  get consumed(): boolean { return this.state.consumed; }
+  get toolUses(): number { return this.state.toolUses; }
+  get lifetimeUsage(): Readonly<LifetimeUsage> { return this.state.lifetimeUsage; }
+  get compactionCount(): number { return this.state.compactionCount; }
+  get turnCount(): number { return this.state.turnCount; }
+  get activeTools(): ReadonlyMap<string, string> { return this.state.activeTools; }
+  get responseText(): string { return this.state.responseText; }
+  get maxTurns(): number | undefined { return this.execution.maxTurns; }
+  get modelLabel(): string { return this._modelLabel; }
+  get effectiveThinkingLevel(): ThinkingLevel { return this._effectiveThinkingLevel; }
+  get runId(): number { return this.currentLease.runId; }
+  get mode(): SubagentMode { return this.currentLease.mode; }
+  get stopRequested(): boolean { return this.currentLease.stopRequest !== undefined; }
+  get stopReason(): SubagentStopReason | undefined { return this.currentLease.stopRequest; }
+  get stateTerminalReason(): SubagentTerminalReason | undefined { return this.state.terminalReason; }
+  get activeRuntimeMs(): number {
+    if (this.currentLease.admitted && !this.currentLease.settled && this.currentLease.startedAt != null) {
+      return Date.now() - this.currentLease.startedAt;
+    }
+    return this.currentLease.settled ? this.runtimeMs : 0;
+  }
+  get sessionReleased(): boolean { return this._sessionReleased; }
+  get pendingSteerCount(): number { return this.pendingSteers.length; }
+  get outputFile(): string | undefined { return this.subagentSession?.outputFile ?? this.releasedOutputFile; }
+  get toolCallId(): string | undefined { return this.execution.parentSession?.toolCallId; }
+  get settlement(): Promise<void> { return this.currentLease.settlement; }
+  get isSettled(): boolean { return this.currentLease.settled; }
+
+  constructor(init: SubagentInit) {
+    this.id = init.id;
+    this.type = init.type;
+    this.description = init.description;
+    this.invocation = init.invocation;
+    this.state = init.state ?? new SubagentState();
+    this.execution = init.execution;
+    this._modelLabel = formatModelLabel(this.execution.model ?? this.execution.snapshot.model);
+    this._effectiveThinkingLevel = resolveEffectiveThinkingLevel(
+      this.execution.model ?? this.execution.snapshot.model,
+      this.execution.thinkingLevel,
+      this.execution.snapshot.thinkingLevel,
+    );
+    this.workspaceBracket = new WorkspaceBracket(this.execution.getWorkspaceProvider ?? (() => undefined));
+    this.currentLease = this.createLease(1, "initial", this.execution.mode, this.execution.prompt, this.execution.timeoutSeconds);
+    // A terminal state can be supplied when a record is reconstructed for a
+    // read-only projection (for example, a service or renderer test). Keep
+    // the lease invariant aligned with that state instead of claiming that a
+    // terminal record still has work in flight. Manager-created records start
+    // queued and take the normal admission path below.
+    if (this.state.status === "completed" || this.state.status === "stopped" || this.state.status === "error") {
+      this.currentLease.settled = true;
+      this.currentLease.resolveSettlement();
+    } else if (this.state.status === "running") {
+      this.currentLease.admitted = true;
+      this.currentLease.startedAt = this.state.startedAt;
+    }
+  }
+
+  isSessionReady(): boolean { return this.subagentSession != null; }
+  isActive(): boolean { return !this.currentLease.settled; }
+  isRunning(): boolean { return this.currentLease.admitted && !this.currentLease.settled; }
+
+  /** Schedule this lease through the one shared FIFO limiter. */
+  scheduleVia(schedule: (task: () => Promise<void>) => AdmissionHandle): AdmissionHandle {
+    const lease = this.currentLease;
+    const handle = schedule(() => this.admitAndRun(lease));
+    lease.admission = handle;
+    if (lease.stopRequest && !handle.admitted) handle.cancel();
+    return handle;
+  }
+
+  /** Arm cancellation before admission; detached callers intentionally pass no signal. */
+  armParentSignal(signal: AbortSignal | undefined): void {
+    if (!signal) return;
+    const lease = this.currentLease;
+    const onAbort = (): void => { this.requestStop("parent_cancelled"); };
+    signal.addEventListener("abort", onAbort, { once: true });
+    lease.parentSignalCleanup = () => signal.removeEventListener("abort", onAbort);
+    if (signal.aborted) onAbort();
+  }
+
+  async steer(message: string): Promise<SteerOutcome> {
+    const lease = this.currentLease;
+    if (!this.isRunning() || lease.stopRequest) return { kind: "rejected", runId: lease.runId, status: this.status };
+    if (!this.subagentSession) {
+      this.pendingSteers.push(message);
+      return { kind: "buffered", runId: lease.runId };
+    }
+    await this.subagentSession.steer(message);
+    return { kind: "delivered", runId: lease.runId };
+  }
+
+  getConversation(): string | undefined { return this.subagentSession?.getConversation(); }
+  getContextPercent(): number | null { return this.subagentSession?.getContextPercent() ?? null; }
+  subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined { return this.subagentSession?.subscribe(fn); }
+  /** Read-only lifecycle notification for adapters that bridge retention release. */
+  subscribeToRecordUpdates(fn: () => void): () => void {
+    this.recordUpdateListeners.add(fn);
+    return () => { this.recordUpdateListeners.delete(fn); };
+  }
+  get messages(): readonly unknown[] { return this.subagentSession?.messages ?? []; }
+  get agentMessages(): readonly SessionMessage[] { return this.subagentSession?.agentMessages ?? []; }
+  getToolDefinition(name: string): ToolDefinition | undefined { return this.subagentSession?.getToolDefinition(name); }
+
+  /** Request cooperative cancellation. The first reason owns this lease. */
+  requestStop(reason: SubagentStopReason): boolean {
+    const lease = this.currentLease;
+    if (lease.settled) return false;
+    lease.stopRequest ??= reason;
+    lease.executionController.abort(lease.stopRequest);
+    this.pendingResumeAbort?.abort(lease.stopRequest);
+    lease.admission?.cancel();
+    if (!lease.admitted) void this.finalizePendingStop(lease);
+    return true;
+  }
+
+  /** Reserve a retained session for resume before any asynchronous wait. */
+  reserveResume(
+    prompt: string,
+    mode: SubagentMode,
+    timeoutSeconds: number | undefined,
+    schedule: (task: () => Promise<void>) => AdmissionHandle,
+    signal?: AbortSignal,
+    admissionPath: "immediate" | "queued" = "immediate",
+  ): { accepted: true; runId: number } | { accepted: false; kind: "not_found" | "wrong_state"; status?: SubagentStatus } {
+    if (!this.subagentSession || this._sessionReleased) return { accepted: false, kind: "wrong_state", status: this.status };
+    if (this.isActive()) return { accepted: false, kind: "wrong_state", status: this.status };
+
+    const previous = this.currentLease;
+    const runId = ++this.nextRunId;
+    const lease = this.createLease(runId, "resume", mode, prompt, timeoutSeconds, admissionPath);
+    this.currentLease = lease;
+    this.state.resetForResume();
+    const resumeAbort = new AbortController();
+    this.pendingResumeAbort = resumeAbort;
+    // A detached resume is independent of the caller even while waiting for
+    // the prior turn to become idle. The private controller remains available
+    // for an explicit stop request.
+    const waitSignal = mode === "joined" && signal
+      ? AbortSignal.any([resumeAbort.signal, signal])
+      : resumeAbort.signal;
+    if (mode === "joined") this.armParentSignal(signal);
+
+    void this.waitAndScheduleResume(lease, previous, waitSignal, schedule);
+    return { accepted: true, runId };
+  }
+
+  private async waitAndScheduleResume(
+    lease: RunLease,
+    previous: RunLease,
+    signal: AbortSignal,
+    schedule: (task: () => Promise<void>) => AdmissionHandle,
+  ): Promise<void> {
+    try {
+      await previous.settlement;
+      await this.subagentSession?.waitUntilIdle(signal);
+      signal.throwIfAborted();
+      if (this.currentLease !== lease || lease.settled) return;
+      // Resume only enters the limiter after Pi's idle boundary. Queue time is
+      // therefore excluded from both the deadline and the active runtime.
+      lease.admission = schedule(() => this.admitAndRun(lease));
+      if (lease.stopRequest && !lease.admission.admitted) lease.admission.cancel();
+    } catch (error) {
+      if (this.currentLease !== lease || lease.settled) return;
+      if (lease.stopRequest || signal.aborted) {
+        lease.stopRequest ??= "parent_cancelled";
+        await this.finalizePendingStop(lease);
+      } else {
+        await this.finalizeError(lease, error, "execution_failure");
+      }
+    } finally {
+      if (this.currentLease === lease) this.pendingResumeAbort = undefined;
+    }
+  }
+
+  private async admitAndRun(lease: RunLease): Promise<void> {
+    if (this.currentLease !== lease || lease.settled) return;
+    if (lease.stopRequest) {
+      await this.finalizePendingStop(lease);
+      return;
+    }
+    lease.admitted = true;
+    lease.startedAt = Date.now();
+    this.runtimeMs = 0;
+    this.state.markRunning(lease.startedAt);
+    if (lease.timeoutSeconds != null) {
+      lease.runtimeTimer = setTimeout(() => this.requestStop("runtime_timeout"), lease.timeoutSeconds * 1000);
+    }
+    if (lease.phase === "resume") {
+      runSafely("subagent onResumedStarted observer", () => this.execution.observer?.onResumedStarted?.(this));
+    } else {
+      runSafely("subagent onStarted observer", () => this.execution.observer?.onStarted?.(this));
+    }
+    await this.executeLease(lease);
+  }
+
+  private async executeLease(lease: RunLease): Promise<void> {
+    try {
+      if (lease.phase === "resume") {
+        await this.executeResume(lease);
+      } else {
+        await this.executeInitial(lease);
+      }
+    } catch (error) {
+      // A stop request aborts both provider work and lifecycle callbacks. Those
+      // callbacks reject through the same cooperative signal, so this is a
+      // normal stopped run rather than an execution failure. Keep genuine
+      // failures classified below when no stop owns the lease.
+      if (lease.stopRequest && isCooperativeAbort(error, lease.executionController.signal)) {
+        await this.finalizeResult(lease, { responseText: "" }, lease.phase === "initial");
+      } else {
+        await this.finalizeError(lease, error, "execution_failure");
+      }
+    }
+  }
+
+  private async executeInitial(lease: RunLease): Promise<void> {
+    let cwd: string | undefined;
+    if (this.workspaceBracket.hasProvider()) {
+      cwd = await this.workspaceBracket.prepare({
+        agentId: this.id,
+        agentType: this.type,
+        baseCwd: this.execution.baseCwd,
+        invocation: this.invocation,
+      });
+    }
+    if (lease.stopRequest) {
+      // Admission has already happened, so finalize through the full run
+      // boundary. In particular, a stop arriving while workspace preparation
+      // is pending must dispose the prepared workspace exactly once rather
+      // than taking the queued-only fast path.
+      await this.finalizeResult(lease, { responseText: "" }, true);
+      return;
+    }
+
+    const session = await this.execution.createSubagentSession({
+      snapshot: this.execution.snapshot,
+      type: this.type,
+      cwd,
+      parentSession: this.execution.parentSession,
+      model: this.execution.model,
+      thinkingLevel: this.execution.thinkingLevel,
+    });
+    this.subagentSession = session;
+    this._modelLabel = formatModelLabel(session.model ?? this.execution.model ?? this.execution.snapshot.model);
+    this._effectiveThinkingLevel = session.thinkingLevel ?? this._effectiveThinkingLevel;
+
+    if (lease.stopRequest) {
+      this.releasedOutputFile = session.outputFile;
+      this.subagentSession = undefined;
+      await session.dispose();
+      return this.finalizeResult(lease, { responseText: "" }, true);
+    }
+
+    this.flushPendingSteers();
+    this.listeners.attachObserver(subscribeSubagentObserver(session, this.state, {
+      onCompact: (info) => runSafely("subagent onCompacted observer", () => this.execution.observer?.onCompacted?.(this, info)),
+    }));
+    runSafely("subagent onSessionCreated observer", () => this.execution.observer?.onSessionCreated?.(this));
+
+    const runConfig = this.execution.getRunConfig?.();
+    const lifecycle = this.createTurnLifecycle(lease);
+    const result = await session.runTurnLoop(lease.prompt, {
+      maxTurns: this.execution.maxTurns,
+      defaultMaxTurns: runConfig?.defaultMaxTurns,
+      graceTurns: runConfig?.graceTurns,
+      signal: lease.executionController.signal,
+      ...(lifecycle ? { lifecycle } : {}),
+    });
+    await this.finalizeResult(lease, result, true);
+  }
+
+  private async executeResume(lease: RunLease): Promise<void> {
+    const session = this.subagentSession;
+    if (!session) return this.finalizeError(lease, new Error("Subagent session was released while resuming"), "execution_failure");
+    this.listeners.attachObserver(subscribeSubagentObserver(session, this.state, {
+      onCompact: (info) => runSafely("subagent onCompacted observer", () => this.execution.observer?.onCompacted?.(this, info)),
+    }));
+    const lifecycle = this.createTurnLifecycle(lease);
+    if (lifecycle) {
+      const result = await session.resumeLifecycleTurnLoop(lease.prompt, lease.executionController.signal, lifecycle);
+      await this.finalizeResult(lease, result, false);
+    } else {
+      const result = await session.resumeTurnLoop(lease.prompt, lease.executionController.signal);
+      await this.finalizeResult(lease, {
+        responseText: result.text,
+        ...(result.failure ? { failure: result.failure } : {}),
+        ...(result.terminalReason ? { terminalReason: result.terminalReason } : {}),
+      }, false);
+    }
+  }
+
+  private createTurnLifecycle(lease: RunLease): SubagentTurnLifecycle | undefined {
+    const registry = this.execution.lifecycleInterceptors;
+    const session = this.subagentSession;
+    if (!registry?.hasInterceptors() || !session) return undefined;
+    const basePath = this.execution.executionPath ?? { origin: "service" as const, admission: "immediate" as const };
+    const execution: SubagentLifecycleExecutionPath = {
+      phase: lease.phase,
+      origin: basePath.origin,
+      mode: lease.mode,
+      admission: lease.admissionPath,
+    };
+    const lifecycleParent = this.execution.lifecycleParentSession ?? this.execution.parentSession;
+    return registry.createTurnLifecycle({
+      identity: {
+        agentId: this.id,
+        sessionId: session.sessionId,
+        runId: lease.runId,
+        agentType: this.type,
+        ...(lifecycleParent?.parentSessionId ? { parentSessionId: lifecycleParent.parentSessionId } : {}),
+      },
+      execution,
+      signal: lease.executionController.signal,
+    });
+  }
+
+  private async finalizeResult(lease: RunLease, result: TurnLoopResult, disposeWorkspace: boolean): Promise<void> {
+    if (this.currentLease !== lease || lease.settled) return;
+    this.listeners.release();
+    let finalResult = result.responseText;
+    if (disposeWorkspace) {
+      const terminalStatus: "completed" | "stopped" | "error" = result.failure
+        ? "error"
+        : lease.stopRequest || result.terminalReason === "turn_limit_hard" || result.terminalReason === "lifecycle_abort"
+          ? "stopped"
+          : "completed";
+      try {
+        finalResult += this.workspaceBracket.dispose({ status: terminalStatus, description: this.description });
+      } catch (error) {
+        return this.finalizeError(lease, error, "workspace_teardown_failure", finalResult);
+      }
+    }
+
+    if (result.failure) {
+      await this.finalizeTerminal(lease, "error", "provider_failure", finalResult, result.failure);
+    } else if (lease.stopRequest) {
+      await this.finalizeTerminal(lease, "stopped", lease.stopRequest, finalResult);
+    } else if (result.terminalReason === "lifecycle_abort") {
+      await this.finalizeTerminal(lease, "stopped", "lifecycle_abort", finalResult);
+    } else if (result.terminalReason === "turn_limit_hard") {
+      await this.finalizeTerminal(lease, "stopped", "turn_limit_hard", finalResult);
+    } else {
+      await this.finalizeTerminal(lease, "completed", result.terminalReason ?? "completed", finalResult);
+    }
+  }
+
+  private async finalizeError(
+    lease: RunLease,
+    error: unknown,
+    reason: "provider_failure" | "execution_failure" | "workspace_teardown_failure",
+    partialResult?: string,
+  ): Promise<void> {
+    if (this.currentLease !== lease || lease.settled) return;
+    this.listeners.release();
+    let finalResult = partialResult;
+    if (reason !== "workspace_teardown_failure") {
+      try {
+        finalResult = (finalResult ?? "") + this.workspaceBracket.dispose({ status: lease.stopRequest ? "stopped" : "error", description: this.description });
+      } catch (cleanupError) {
+        debugLog("workspace dispose on agent error", cleanupError);
+        reason = "workspace_teardown_failure";
+        error = cleanupError;
+      }
+    }
+    // An actual execution failure outranks a cancellation request. A normal
+    // cooperative abort resolves through finalizeResult and therefore still
+    // reports the lease's first stop reason; this branch is reserved for a
+    // genuine thrown failure while running or tearing down the child.
+    await this.finalizeTerminal(lease, "error", reason, finalResult, error);
+  }
+
+  private async finalizePendingStop(lease: RunLease): Promise<void> {
+    if (this.currentLease !== lease || lease.settled || lease.admitted) return;
+    await this.finalizeTerminal(lease, "stopped", lease.stopRequest ?? "explicit_stop");
+  }
+
+  private async finalizeTerminal(
+    lease: RunLease,
+    status: SubagentStatus,
+    reason: SubagentTerminalReason,
+    result?: string,
+    error?: unknown,
+  ): Promise<void> {
+    if (this.currentLease !== lease || lease.settled) return;
+    lease.settled = true;
+    lease.parentSignalCleanup?.();
+    lease.parentSignalCleanup = undefined;
+    if (lease.runtimeTimer) clearTimeout(lease.runtimeTimer);
+    this.runtimeMs = lease.admitted && lease.startedAt != null ? Math.max(0, Date.now() - lease.startedAt) : 0;
+
+    if (status === "completed") this.state.markCompleted(result ?? "", reason as "completed" | "turn_limit_graceful");
+    else if (status === "stopped") this.state.markStopped(result, reason as SubagentStopReason | "turn_limit_hard" | "lifecycle_abort");
+    else this.state.markError(error ?? result ?? "subagent execution failed", reason as "provider_failure" | "execution_failure" | "workspace_teardown_failure", result);
+
+    if (lease.phase === "resume") {
+      runSafely("subagent onResumedFinished observer", () => this.execution.observer?.onResumedFinished?.(this));
+    } else {
+      runSafely("subagent onRunFinished observer", () => this.execution.observer?.onRunFinished?.(this));
+    }
+    lease.resolveSettlement();
+  }
+
+  private createLease(
+    runId: number,
+    phase: "initial" | "resume",
+    mode: SubagentMode,
+    prompt: string,
+    timeoutSeconds?: number,
+    admissionPath: "immediate" | "queued" = "immediate",
+  ): RunLease {
+    const d = deferred();
+    return {
+      runId,
+      phase,
+      mode,
+      prompt,
+      timeoutSeconds,
+      executionController: new AbortController(),
+      settlement: d.promise,
+      resolveSettlement: d.resolve,
+      admitted: false,
+      settled: false,
+      admissionPath,
+    };
+  }
+
+  private flushPendingSteers(): void {
+    for (const message of this.pendingSteers) runDetached("subagent buffered steer", () => this.subagentSession?.steer(message));
+    this.pendingSteers = [];
+  }
+
+  incrementToolUses(): void { this.state.incrementToolUses(); }
+  addUsage(delta: { input: number; output: number; cacheWrite: number }): void { this.state.addUsage(delta); }
+  incrementCompactions(): void { this.state.incrementCompactions(); }
+  markConsumed(at?: number): void { this.state.markConsumed(at); }
+
+  async waitForSettlement(signal?: AbortSignal): Promise<void> {
+    if (!signal) return this.currentLease.settlement;
+    await settleOrAbort(this.currentLease.settlement, signal);
+  }
+
+  async disposeSession(): Promise<void> {
+    const session = this.subagentSession;
+    if (!session) return;
+    this.subagentSession = undefined;
+    await session.dispose();
+  }
+
+  async releaseSession(): Promise<void> {
+    const session = this.subagentSession;
+    if (!session) return;
+    this.releasedOutputFile = session.outputFile;
+    this.subagentSession = undefined;
+    this._sessionReleased = true;
+    for (const listener of this.recordUpdateListeners) runSafely("subagent release update", listener);
+    await session.dispose();
+  }
+}
+
+function isCooperativeAbort(error: unknown, signal: AbortSignal): boolean {
+  if (!signal.aborted) return false;
+  if (error === signal.reason) return true;
+  return error instanceof Error && /abort|cancel/i.test(error.message);
 }
 
-/** Resolve when either the run settles or the caller's wait is interrupted. */
 async function settleOrAbort(run: Promise<void>, signal: AbortSignal): Promise<void> {
-	await new Promise<void>((resolve) => {
-		let done = false;
-		const finish = (): void => {
-			if (done) return;
-			done = true;
-			signal.removeEventListener("abort", finish);
-			resolve();
-		};
-		signal.addEventListener("abort", finish, { once: true });
-		void run.then(finish, finish);
-	});
+  if (signal.aborted) return;
+  await new Promise<void>((resolve) => {
+    let done = false;
+    const finish = (): void => {
+      if (done) return;
+      done = true;
+      signal.removeEventListener("abort", finish);
+      resolve();
+    };
+    signal.addEventListener("abort", finish, { once: true });
+    void run.then(finish, finish);
+  });
 }