@ferris1225/pi-subagents 2.0.3 → 2.2.0

package/src/dispatch.ts

@@ -1,33 +1,22 @@
 /**
  * The `subagent` tool: dispatches explore/worker/cleaner/reviewer agents as isolated pi
- * child processes, single or parallel. Owns the dispatch pipeline: config load,
- * per-agent selected→main model routing, per-run status tracking, the auto-fix chain
- * (REVIEW_FAIL → worker → re-review), and completion delivery.
+ * child processes, single or parallel. Owns the public dispatch contract,
+ * per-run status tracking, the auto-fix chain (REVIEW_FAIL → worker → re-review),
+ * and completion delivery. Stable thread generations live in thread-lifecycle.ts.
  *
  * Vision: a task flagged `vision: true` uses the configured vision model, then
  * hands directly to the current main-window model on model/provider failure.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { existsSync } from "node:fs";
-import { realpath, rm } from "node:fs/promises";
+import { realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { Type } from "typebox";
-import { discoverAgents, type AgentConfig } from "./agents.ts";
+import { discoverAgents } from "./agents.ts";
+import { loadConfig } from "./config.ts";
 import {
-	completionTriggersTurn,
-	type CompletionMessageItem,
-} from "./completion.ts";
-import {
-	DEFAULT_THINKING_LEVEL,
-	loadConfig,
-	type SubagentsConfig,
-	type ThinkingLevel,
-} from "./config.ts";
-import {
-	dispatchFailedResult,
 	failedStartResult,
 	formatCompletionBlock,
 	formatUsage,
@@ -38,30 +27,18 @@ import {
 	buildFixTaskBrief,
 	buildReReviewBrief,
 	formatChainSummary,
-	shouldTriggerFixLoop,
 	type ChainStep,
 } from "./fixloop.ts";
-import {
-	availableModelsInScope,
-	currentModelRef,
-	findModelByRef,
-	modelRef,
-	resolveAgentModelRoute,
-	resolveThinkingLevel,
-} from "./models.ts";
 import {
 	formatTaskSummary,
 	formatToolActivity,
 	monitor,
 	statusIcon,
+	sumUsage,
 	type RunChainMeta,
 } from "./monitor.ts";
-import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
-import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
-import { forkRetainedSession } from "./session-fork.ts";
+import type { SubagentRuntime } from "./runtime.ts";
 import {
-	buildResumePrompt,
-	RpcRunControl,
 	getResultOutput,
 	isFailedResult,
 	isModelLevelFailure,
@@ -72,31 +49,14 @@ import {
 	type SubagentLiveEvent,
 } from "./spawn.ts";
 import {
-	createWorktreeIsolation,
-	resolveWorktreeTarget,
-	type IsolationMode,
-	type WorktreeFinalization,
-	type WorktreeIsolation,
-} from "./worktree.ts";
+	createBackgroundDispatcher,
+	resolveDispatchModelRoute,
+} from "./thread-lifecycle.ts";
+import { resolveWorktreeTarget, type IsolationMode } from "./worktree.ts";
 
-const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
-export const FORK_CONTINUATION_PROMPT =
-	"Continue from the retained context above. Review the prior work, then take the most useful next step toward completing the existing objective without repeating completed work.";
-const WORKTREE_ISOLATION_INSTRUCTIONS =
-	"You are running in a temporary detached Git worktree. Work only in the current cwd; do not create another worktree or manually copy/apply changes to the original checkout. The parent dispatcher will integrate your tracked, deleted, and untracked changes when this thread finally settles.";
+export { FORK_CONTINUATION_PROMPT, isWorktreeCapableAgent } from "./thread-lifecycle.ts";
 
-function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
-	return {
-		...agent,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\n${WORKTREE_ISOLATION_INSTRUCTIONS}`.trim(),
-	};
-}
-
-interface DispatchEnvironment {
-	ctx: ExtensionContext;
-	config: SubagentsConfig;
-	agents: AgentConfig[];
-}
+const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 
 const VISION_DESCRIPTION =
 	"Set true when the task may require viewing images (screenshots, mockups, designs) — the configured vision model is used first, then model-level failures hand directly to the current main-window model";
@@ -135,13 +95,6 @@ export function defaultIsolationMode(mode: "single" | "parallel", agentName: str
 	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
 }
 
-export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
-	if (agent.name === "explore" || agent.name === "reviewer") return false;
-	if (agent.name === "worker") return true;
-	if (!agent.tools) return true;
-	return agent.tools.includes("edit") || agent.tools.includes("write");
-}
-
 const autoFixRootTails = new Map<string, Promise<void>>();
 
 async function canonicalAutoFixRoot(cwd: string): Promise<string> {
@@ -184,42 +137,6 @@ function serializeAutoFixChain(
 	};
 }
 
-interface DispatchModelRoute {
-	agent: AgentConfig;
-	mainFallbackRef?: string;
-	thinkingLevel: ThinkingLevel;
-	thinkingLevelForModel: (ref?: string) => ThinkingLevel;
-}
-
-function resolveDispatchModelRoute(
-	agent: AgentConfig,
-	config: SubagentsConfig,
-	ctx: ExtensionContext,
-	vision: boolean,
-): DispatchModelRoute {
-	const availableModels = availableModelsInScope(ctx);
-	const mainRef = currentModelRef(ctx);
-	const route = resolveAgentModelRoute({
-		selectedRef: vision ? config.visionModel : config.agentModels[agent.name],
-		mainRef,
-		declaredDefaultRef: agent.model,
-		availableRefs: availableModels.map(modelRef),
-	});
-	const preferred = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? DEFAULT_THINKING_LEVEL;
-	const thinkingLevelForModel = (ref?: string): ThinkingLevel => {
-		const model = ref === mainRef && ctx.model
-			? ctx.model
-			: findModelByRef(availableModels, ref);
-		return resolveThinkingLevel(model, preferred);
-	};
-	return {
-		agent: { ...agent, model: route.primaryRef },
-		mainFallbackRef: route.mainFallbackRef,
-		thinkingLevel: thinkingLevelForModel(route.primaryRef),
-		thinkingLevelForModel,
-	};
-}
-
 export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	pi.registerTool({
 		name: "subagent",
@@ -507,6 +424,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							const workerStep = await launchInLoop("worker", fixBrief, executionCwd, signal, {
 								groupId: parentGroupId,
 								relationLabel: `fix round ${round}`,
+								parentRunId,
 							}, vision);
 							// Preserve the newest sub-step before checking chain ownership. A
 							// destructive stop invalidates ownsParent() while this child is
@@ -526,10 +444,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							if (!ownsParent()) return;
 							chain.push({ ...workerStep, relation: `fix round ${round}` });
 							if (!runtime.sessionActive || isFailedResult(workerStep.result)) break;
-							const reReviewBrief = buildReReviewBrief(lastReviewer, round);
+							const reReviewBrief = buildReReviewBrief(lastReviewer, round, workerStep.result);
 							const reviewStep = await launchInLoop("reviewer", reReviewBrief, executionCwd, signal, {
 								groupId: parentGroupId,
 								relationLabel: `re-review round ${round}`,
+								parentRunId,
 							}, vision);
 							if (
 								runtime.threads.get(parentRunId) === parentThreadAtStart &&
@@ -611,6 +530,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								agent: `auto-fix chain (${last.result.agent})`,
 								block,
 								triggerTurn: true,
+								usage: sumUsage(chain.map((step) => step.result.usage)),
 							},
 						]);
 						runtime.completionBatcher.flush();
@@ -654,6 +574,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 									agent: initialReviewerResult.agent,
 									block: `${formatCompletionBlock(initialReviewerResult, config.maxResultLines, executionCwd)}\n\nAuto-fix chain crashed before completion: ${errorMessage}. The planned fix rounds did not run; the review above is the triggering reviewer's full output.`,
 									triggerTurn: true,
+									usage: initialReviewerResult.usage,
 								},
 							]);
 							runtime.completionBatcher.flush();
@@ -673,904 +594,16 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				]).then(() => undefined);
 			};
 
-			interface SessionSeed {
-				sessionId?: string;
-				sessionDir?: string;
-				prompt?: string;
-				worktree?: WorktreeIsolation;
-				forkedFromRunId?: number;
-				forkObjective?: string;
-			}
-
-			interface ResumeReservation {
-				version: number;
-				generation: number;
-				sessionId?: string;
-				sessionDir?: string;
-			}
-
-			const ownsResumeReservation = (
-				thread: SubagentThread,
-				reservation: ResumeReservation,
-			): boolean =>
-				runtime.sessionActive &&
-				runtime.threads.get(thread.id) === thread &&
-				!thread.retired &&
-				thread.lifecycleOperation === "resume" &&
-				thread.lifecycleVersion === reservation.version &&
-				thread.generation === reservation.generation &&
-				thread.sessionId === reservation.sessionId &&
-				thread.sessionDir === reservation.sessionDir;
-
-			const beginPreflight = (): (() => void) => {
-				let resolvePreflight!: () => void;
-				const preflight = new Promise<void>((resolve) => {
-					resolvePreflight = resolve;
-				});
-				runtime.preflightOperations.add(preflight);
-				return () => {
-					runtime.preflightOperations.delete(preflight);
-					resolvePreflight();
-				};
-			};
-
-			const startBackground = async (
-				agentName: string,
-				task: string,
-				cwd: string | undefined,
-				vision = false,
-				isolation: IsolationMode = "shared",
-				existingThread?: SubagentThread,
-				newObjectiveOnResume = false,
-				environment?: DispatchEnvironment,
-				seed?: SessionSeed,
-				resumeReservation?: ResumeReservation,
-			): Promise<SingleResult> => {
-				if (!runtime.sessionActive) {
-					return failedStartResult(agentName, task, "Parent session shut down before this subagent generation could start.");
-				}
-				if (existingThread && (!resumeReservation || !ownsResumeReservation(existingThread, resumeReservation))) {
-					return failedStartResult(agentName, task, `Run #${existingThread.id} changed while resume was preparing; no new generation was started.`);
-				}
-				const runCtx = environment?.ctx ?? ctx;
-				const runConfig = environment?.config ?? config;
-				const runAgents = environment?.agents ?? agents;
-				const agent = runAgents.find((candidate) => candidate.name === agentName);
-				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
-				if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
-					return {
-						...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as worker or cleaner.`),
-						isolation,
-					};
-				}
-
-				const originalCwd = resolve(cwd ?? runCtx.cwd);
-				const previousWorktree = existingThread?.worktree;
-				let worktree = seed?.worktree ?? previousWorktree;
-				if (isolation === "worktree") {
-					if (worktree && worktree.state !== "active") {
-						return {
-							...failedStartResult(agentName, task, `Run #${existingThread?.id ?? "?"} has no active continuation worktree.`),
-							isolation,
-							integrationStatus: worktree.state === "finalizing" ? "pending" : worktree.state,
-						};
-					}
-					if (!worktree) {
-						try {
-							worktree = await createWorktreeIsolation(originalCwd);
-						} catch (error) {
-							return {
-								...failedStartResult(agentName, task, error instanceof Error ? error.message : String(error)),
-								isolation,
-							};
-						}
-					}
-				}
-				const executionCwd = worktree?.cwd ?? originalCwd;
-				const resolvedRoute = resolveDispatchModelRoute(agent, runConfig, runCtx, vision);
-				// Isolation is a persistent system-level invariant, not a one-shot task
-				// prefix: queued retargets, live retargets, resumes, and main-model
-				// handoffs all keep the same worktree boundary.
-				const route = isolation === "worktree"
-					? { ...resolvedRoute, agent: withWorktreeSystemPrompt(resolvedRoute.agent) }
-					: resolvedRoute;
-				const thinkingLevel = route.thinkingLevel;
-				const priorTask = existingThread?.task;
-				const priorSessionId = seed?.sessionId ?? existingThread?.sessionId;
-				const priorSessionDir = seed?.sessionDir ?? existingThread?.sessionDir;
-				if (existingThread && resumeReservation && !ownsResumeReservation(existingThread, resumeReservation)) {
-					return failedStartResult(agentName, task, `Run #${existingThread.id} changed while resume was preparing; no new generation was started.`);
-				}
-				const runId = existingThread?.id ?? monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, {
-					isolation,
-					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
-				});
-				const generation = (existingThread?.generation ?? 0) + 1;
-				const pending: SingleResult = {
-					...queuedResult(route.agent, task, thinkingLevel),
-					runId,
-					projectCwd: originalCwd,
-					isolation,
-					...(isolation === "worktree" ? { integrationStatus: "pending" as const } : {}),
-					...(seed?.sessionId && seed.sessionDir
-						? { sessionId: seed.sessionId, sessionDir: seed.sessionDir }
-						: {}),
-					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
-				};
-				if (existingThread) {
-					monitor.restartRun(runId, agent.name, task, route.agent.model, thinkingLevel, isolation);
-					runtime.settledRuns.delete(runId);
-				}
-
-				let thread!: SubagentThread;
-				const control = new RpcRunControl(task, generation, (phase) => {
-					if (runtime.threads.get(runId)?.generation !== generation || phase === "settled") return;
-					const state: ThreadState =
-						phase === "queued" || phase === "starting"
-							? "queued"
-							: phase === "steering"
-								? "steering"
-								: phase === "interrupting"
-									? "interrupting"
-									: phase === "parked"
-										? "parked"
-										: phase === "stopped"
-											? "stopped"
-											: "running";
-					thread.state = state;
-					if (state === "queued") monitor.setStatus(runId, "queued");
-					else if (state === "steering") monitor.setStatus(runId, "steering");
-					else if (state === "interrupting") monitor.setStatus(runId, "interrupting");
-					else if (state === "parked") monitor.setStatus(runId, "parked");
-					else if (state === "running") monitor.setStatus(runId, "running");
-				});
-
-
-				if (existingThread) {
-					thread = existingThread;
-					thread.generation = generation;
-					thread.agentName = agent.name;
-					thread.task = task;
-					thread.cwd = originalCwd;
-					thread.executionCwd = executionCwd;
-					thread.vision = vision;
-					thread.thinkingLevel = thinkingLevel;
-					thread.isolation = isolation;
-					thread.worktree = worktree;
-					thread.state = "queued";
-					thread.control = control;
-					// A newly admitted generation owns no output yet. Keeping the prior
-					// generation here would make a queued stop publish stale task,
-					// session metadata as this generation's partial.
-					thread.lastResult = undefined;
-					if (seed?.sessionId && seed.sessionDir) {
-						thread.sessionId = seed.sessionId;
-						thread.sessionDir = seed.sessionDir;
-					}
-					thread.retireOnSettle = false;
-					thread.isolationFailureNotified = false;
-				} else {
-					thread = {
-						id: runId,
-						generation,
-						agentName: agent.name,
-						task,
-						cwd: originalCwd,
-						executionCwd,
-						vision,
-						thinkingLevel,
-						isolation,
-						worktree,
-						state: "queued",
-						control,
-						generationCompletion: Promise.resolve(),
-						lifecycleVersion: 0,
-						sessionId: seed?.sessionId,
-						sessionDir: seed?.sessionDir,
-						forkedFromRunId: seed?.forkedFromRunId,
-						forkChildRunIds: [],
-						park: async () => {
-							throw new Error("Thread park was not initialized.");
-						},
-						resume: async () => failedStartResult(agent.name, task, "Thread resume was not initialized."),
-						fork: async () => failedStartResult(agent.name, task, "Thread fork was not initialized."),
-						finalizeIsolation: async () => undefined,
-					};
-					runtime.threads.set(runId, thread);
-				}
-				thread.notifyIsolationFailure = (finalization) => {
-					const paths = [finalization.worktreePath, finalization.patchPath].filter(Boolean).join(" · ");
-					runCtx.ui.notify(
-						`✗ ${agent.name} worktree ${finalization.integrated ? "cleanup" : "integration"} failed${paths ? ` · retained ${paths}` : ""}: ${finalization.error ?? "unknown Git integration error"}`,
-						"error",
-					);
-				};
-				thread.finalizeIsolation = async (
-					expectedGeneration: number,
-					result?: SingleResult,
-				): Promise<WorktreeFinalization | undefined> => {
-					if (thread.isolation !== "worktree" || !thread.worktree) return undefined;
-					if (thread.generation !== expectedGeneration) return undefined;
-					const finalization = await thread.worktree.finalize();
-					monitor.setIsolation(runId, "worktree", finalization.status);
-					if (result) {
-						result.runId = runId;
-						result.isolation = "worktree";
-						result.integrationStatus = finalization.status;
-						result.integrationApplied = finalization.integrated;
-						result.integrationError = finalization.error;
-						result.integrationWorktreePath = finalization.worktreePath;
-						result.integrationPatchPath = finalization.patchPath;
-						result.forkedFromRunId = thread.forkedFromRunId;
-						result.forkChildRunIds = [...thread.forkChildRunIds];
-						if (finalization.status === "retained") {
-							const retained = [
-								finalization.worktreePath ? `worktree ${finalization.worktreePath}` : undefined,
-								finalization.patchPath ? `patch ${finalization.patchPath}` : undefined,
-							].filter(Boolean).join(", ");
-							const integrationMessage = finalization.integrated
-								? `Worktree changes were applied, but cleanup failed${retained ? `; retained ${retained}` : ""}: ${finalization.error ?? "unknown Git cleanup error"}`
-								: `Worktree integration failed${retained ? `; retained ${retained}` : ""}: ${finalization.error ?? "unknown Git integration error"}`;
-							result.exitCode = 1;
-							result.stopReason = "error";
-							result.errorMessage = result.errorMessage
-								? `${result.errorMessage}\n${integrationMessage}`
-								: integrationMessage;
-							result.stderr = result.stderr ? `${result.stderr.trimEnd()}\n${integrationMessage}` : integrationMessage;
-						}
-					}
-					if (finalization.status === "retained") {
-						if (!thread.isolationFailureNotified) {
-							thread.isolationFailureNotified = true;
-							try {
-								thread.notifyIsolationFailure?.(finalization);
-							} catch {
-								/* notification failures do not hide retained artifacts */
-							}
-						}
-					}
-					return finalization;
-				};
-
-				const cleanupTrackedSessionDir = async (sessionDir: string, action: string): Promise<void> => {
-					try {
-						await rm(sessionDir, { recursive: true, force: true });
-						runtime.sessionDirs.delete(sessionDir);
-					} catch (error) {
-						// Keep ownership so shutdown can retry; losing the path here leaks a
-						// cloned session containing retained model context on Windows locks.
-						try {
-							runCtx.ui.notify(
-								`✗ ${action}; retained ${sessionDir} for shutdown cleanup: ${error instanceof Error ? error.message : String(error)}`,
-								"error",
-							);
-						} catch {
-							/* cleanup ownership remains tracked even if the UI is unavailable */
-						}
-					}
-				};
-
-				const discardUnusedWorktree = async (candidate: WorktreeIsolation | undefined): Promise<void> => {
-					if (!candidate) return;
-					try {
-						await candidate.discard();
-					} catch (error) {
-						const retainedPath = existsSync(candidate.worktreePath)
-							? candidate.worktreePath
-							: existsSync(candidate.tempDir)
-								? candidate.tempDir
-								: undefined;
-						const finalization: WorktreeFinalization = {
-							status: "retained",
-							integrated: false,
-							hadChanges: false,
-							...(retainedPath ? { worktreePath: retainedPath } : {}),
-							...(existsSync(candidate.patchPath) ? { patchPath: candidate.patchPath } : {}),
-							error: `Discarding unused continuation failed: ${error instanceof Error ? error.message : String(error)}`,
-						};
-						await persistRecoveryRecords(runtime.configPath, [
-							recoveryRecordFromFinalization(runId, finalization),
-						]).catch(() => undefined);
-						try {
-							thread.notifyIsolationFailure?.(finalization);
-						} catch {
-							/* parent UI may already be shutting down */
-						}
-					}
-				};
-
-				const createContinuationWorktree = async (
-					source: WorktreeIsolation,
-					seedIsIntegrated: boolean,
-				): Promise<WorktreeIsolation> => {
-					if (source.state === "finalizing") {
-						throw new Error(`Run #${runId}'s worktree is still finalizing.`);
-					}
-					const seedCheckpoint = await source.snapshotCheckpoint();
-					return createWorktreeIsolation(thread.cwd, {
-						seedCheckpoint,
-						seedIsIntegrated,
-					});
-				};
-
-				thread.park = async (): Promise<"queued" | "active"> => {
-					if (thread.retired) throw new Error(`Run #${runId} was retired by subagent_stop.`);
-					if (thread.lifecycleOperation) throw new Error(`Run #${runId} is already handling ${thread.lifecycleOperation}.`);
-					if (thread.state === "parked") return "active";
-					const phase = thread.control.getPhase();
-					const queued = thread.state === "queued" && phase === "queued";
-					if (
-						!queued &&
-						((phase === "settled" && thread.state !== "running") ||
-							!["starting", "running", "steering", "interrupting", "retrying", "settled"].includes(phase))
-					) {
-						throw new Error(`Run #${runId} is ${thread.state}; only active work can be parked.`);
-					}
-
-					const version = ++thread.lifecycleVersion;
-					const generation = thread.generation;
-					const completion = thread.generationCompletion;
-					const controller = thread.queueController;
-					thread.lifecycleOperation = "park";
-					try {
-						if (queued) {
-							thread.control.parkPending();
-							runtime.backgroundQueue.cancel(controller);
-						} else {
-							await thread.control.park();
-							// Auto-fix orchestration has no live RPC attempt once its parent
-							// review settled, so cancel its queue owner explicitly.
-							if (phase === "settled") runtime.backgroundQueue.cancel(controller);
-						}
-						await completion;
-						if (
-							thread.generation !== generation ||
-							thread.lifecycleVersion !== version ||
-							thread.lifecycleOperation !== "park"
-						) {
-							throw new Error(`Run #${runId} changed while parking.`);
-						}
-						thread.state = "parked";
-						thread.queueController = undefined;
-						runtime.runControllers.delete(runId);
-						monitor.setStatus(runId, "parked");
-						return queued ? "queued" : "active";
-					} finally {
-						if (thread.lifecycleVersion === version && thread.lifecycleOperation === "park") {
-							thread.lifecycleOperation = undefined;
-						}
-					}
-				};
-
-				thread.resume = async (objective?: string, resumeCtx?: ExtensionContext): Promise<SingleResult> => {
-					const requestedObjective = objective?.trim();
-					if (!runtime.sessionActive || runtime.threads.get(runId) !== thread) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} belongs to a parent session that has shut down.`);
-					}
-					if (objective !== undefined && !requestedObjective) {
-						return failedStartResult(thread.agentName, thread.task, "resume objective must be non-blank when provided.");
-					}
-					if (thread.retired) return failedStartResult(thread.agentName, thread.task, `Run #${runId} was retired by subagent_stop.`);
-					if (thread.lifecycleOperation) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is already ${thread.lifecycleOperation === "resume" ? "resuming" : "being forked"}.`);
-					}
-					if (!["parked", "completed", "failed"].includes(thread.state)) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is ${thread.state}; it must be parked or settled before resume.`);
-					}
-
-					// Lifecycle CAS: claim synchronously before the first await, then cancel
-					// and fully quiesce any superseded queue/process before cloning or
-					// reusing its session. A second resume/fork sees this claim immediately.
-					const previousState = thread.state;
-					const previousSessionId = thread.sessionId;
-					const previousSessionDir = thread.sessionDir;
-					const previousExecutionCwd = thread.executionCwd;
-					const reservation: ResumeReservation = {
-						version: ++thread.lifecycleVersion,
-						generation: thread.generation,
-						sessionId: previousSessionId,
-						sessionDir: previousSessionDir,
-					};
-					thread.lifecycleOperation = "resume";
-					thread.state = "resuming";
-					const finishPreflight = beginPreflight();
-					const supersededController = thread.queueController;
-					runtime.backgroundQueue.cancel(supersededController);
-					runtime.runControllers.delete(runId);
-
-					let continuationWorktree: WorktreeIsolation | undefined;
-					let clonedSession: Awaited<ReturnType<typeof forkRetainedSession>> | undefined;
-					try {
-						await thread.generationCompletion;
-						if (!ownsResumeReservation(thread, reservation)) {
-							return failedStartResult(
-								thread.agentName,
-								thread.task,
-								thread.retired
-									? `Run #${runId} was retired by subagent_stop; no new generation was started.`
-									: `Run #${runId} changed while resume was preparing; no new generation was started.`,
-							);
-						}
-						thread.state = "resuming";
-						const currentCtx = resumeCtx ?? runCtx;
-						let seed: SessionSeed | undefined;
-						if (thread.isolation === "worktree" && thread.worktree?.state !== "active") {
-							if (!thread.worktree) throw new Error(`Run #${runId} has no isolated worktree checkpoint.`);
-							const seedAlreadyIntegrated =
-								thread.worktree.state === "integrated" ||
-								thread.worktree.state === "no_changes" ||
-								thread.lastResult?.integrationApplied === true;
-							continuationWorktree = await createContinuationWorktree(thread.worktree, seedAlreadyIntegrated);
-							if (!ownsResumeReservation(thread, reservation)) {
-								throw new Error(`Run #${runId} changed while its continuation worktree was being created.`);
-							}
-							seed = { worktree: continuationWorktree };
-							if (previousSessionId && previousSessionDir) {
-								clonedSession = await forkRetainedSession({
-									cwd: previousExecutionCwd,
-									targetCwd: continuationWorktree.cwd,
-									sessionDir: previousSessionDir,
-									sessionId: previousSessionId,
-								});
-								runtime.sessionDirs.add(clonedSession.sessionDir);
-								if (!ownsResumeReservation(thread, reservation)) {
-									throw new Error(`Run #${runId} changed while its retained session was being cloned.`);
-								}
-								seed.sessionId = clonedSession.sessionId;
-								seed.sessionDir = clonedSession.sessionDir;
-							}
-						}
-
-						const currentConfig = await loadConfig(runtime.configPath);
-						if (!ownsResumeReservation(thread, reservation)) {
-							throw new Error(`Run #${runId} changed while resume configuration was loading.`);
-						}
-						runtime.backgroundQueue.setConcurrency(currentConfig.maxConcurrency);
-						const currentAgents = discoverAgents(currentCtx.cwd, {
-							scope: currentConfig.agentScope,
-							enabledNames: currentConfig.enabledAgents,
-							projectTrusted: currentCtx.isProjectTrusted?.() === true,
-						}).agents;
-						const nextTask = requestedObjective ?? thread.task;
-						const pending = await startBackground(
-							thread.agentName,
-							nextTask,
-							thread.cwd,
-							thread.vision,
-							thread.isolation,
-							thread,
-							objective !== undefined,
-							{
-								ctx: currentCtx,
-								config: currentConfig,
-								agents: currentAgents,
-							},
-							seed,
-							reservation,
-						);
-						if (pending.exitCode !== -1) {
-							if (clonedSession) {
-								await cleanupTrackedSessionDir(
-									clonedSession.sessionDir,
-									`Could not discard failed resume session clone for run #${runId}`,
-								);
-							}
-							await discardUnusedWorktree(continuationWorktree);
-							if (ownsResumeReservation(thread, reservation)) thread.state = previousState;
-							return pending;
-						}
-
-						// The cloned branch replaces the removed-worktree session for this
-						// logical id. Keep an undeletable old dir in runtime cleanup if needed.
-						if (clonedSession && previousSessionDir && previousSessionDir !== clonedSession.sessionDir) {
-							try {
-								await rm(previousSessionDir, { recursive: true, force: true });
-								runtime.sessionDirs.delete(previousSessionDir);
-							} catch {
-								/* shutdown retries cleanup of the old retained branch */
-							}
-						}
-						return pending;
-					} catch (error) {
-						if (clonedSession) {
-							await cleanupTrackedSessionDir(
-								clonedSession.sessionDir,
-								`Could not discard interrupted resume session clone for run #${runId}`,
-							);
-						}
-						await discardUnusedWorktree(continuationWorktree);
-						if (ownsResumeReservation(thread, reservation)) {
-							thread.state = previousState;
-							thread.sessionId = previousSessionId;
-							thread.sessionDir = previousSessionDir;
-							thread.executionCwd = previousExecutionCwd;
-						}
-						return failedStartResult(
-							thread.agentName,
-							requestedObjective ?? thread.task,
-							`Could not resume run #${runId}: ${error instanceof Error ? error.message : String(error)}`,
-						);
-					} finally {
-						finishPreflight();
-						if (
-							thread.lifecycleOperation === "resume" &&
-							thread.lifecycleVersion === reservation.version
-						) {
-							thread.lifecycleOperation = undefined;
-						}
-					}
-				};
-
-				thread.fork = async (objective?: string, forkCtx?: ExtensionContext): Promise<SingleResult> => {
-					const forkObjective = objective?.trim();
-					if (!runtime.sessionActive || runtime.threads.get(runId) !== thread) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} belongs to a parent session that has shut down.`);
-					}
-					if (objective !== undefined && !forkObjective) {
-						return failedStartResult(thread.agentName, thread.task, "fork objective must be non-blank when provided.");
-					}
-					if (thread.retired || thread.state === "stopped") {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} was retired by subagent_stop and cannot be forked.`);
-					}
-					if (thread.lifecycleOperation) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is already ${thread.lifecycleOperation === "resume" ? "resuming" : "being forked"}.`);
-					}
-					if (thread.state === "queued" && !thread.sessionId) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is queued and has no retained session to fork.`);
-					}
-					if (["queued", "running", "steering", "interrupting"].includes(thread.state)) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is active; park it first with subagent_control { action: "park", id: ${runId} }, then fork the stable session.`);
-					}
-					if (!["parked", "completed", "failed"].includes(thread.state)) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is ${thread.state} and has no forkable retained checkpoint.`);
-					}
-					if (!thread.sessionId || !thread.sessionDir) {
-						return failedStartResult(thread.agentName, thread.task, `Run #${runId} has no retained session to fork (it may have been parked before starting).`);
-					}
-					if (thread.isolation === "worktree") {
-						const worktreeState = thread.worktree?.state;
-						const seedIntegrated =
-							worktreeState === "integrated" ||
-							worktreeState === "no_changes" ||
-							thread.lastResult?.integrationApplied === true;
-						if (!seedIntegrated) {
-							return failedStartResult(
-								thread.agentName,
-								thread.task,
-								`Run #${runId}'s isolated checkpoint has not been integrated. Resume and settle it before forking so its seed is applied exactly once.`,
-							);
-						}
-					}
-
-					// Same lifecycle CAS as resume: a concurrent resume/fork cannot consume
-					// or clone this session while the branch copy is in progress.
-					const forkVersion = ++thread.lifecycleVersion;
-					const forkGeneration = thread.generation;
-					const forkSessionId = thread.sessionId;
-					const forkSessionDir = thread.sessionDir;
-					const ownsFork = (): boolean =>
-						runtime.sessionActive &&
-						runtime.threads.get(runId) === thread &&
-						!thread.retired &&
-						thread.lifecycleOperation === "fork" &&
-						thread.lifecycleVersion === forkVersion &&
-						thread.generation === forkGeneration &&
-						thread.sessionId === forkSessionId &&
-						thread.sessionDir === forkSessionDir;
-					thread.lifecycleOperation = "fork";
-					const finishPreflight = beginPreflight();
-					let childWorktree: WorktreeIsolation | undefined;
-					let forkedSession: Awaited<ReturnType<typeof forkRetainedSession>> | undefined;
-					try {
-						await thread.generationCompletion;
-						if (!ownsFork()) {
-							return failedStartResult(thread.agentName, thread.task, `Run #${runId} changed while fork was preparing; no child was started.`);
-						}
-						const currentCtx = forkCtx ?? runCtx;
-						if (thread.isolation === "worktree") {
-							if (!thread.worktree) throw new Error(`Run #${runId} has no isolated worktree checkpoint.`);
-							const seedAlreadyIntegrated =
-								thread.worktree.state === "integrated" ||
-								thread.worktree.state === "no_changes" ||
-								thread.lastResult?.integrationApplied === true;
-							childWorktree = await createContinuationWorktree(thread.worktree, seedAlreadyIntegrated);
-							if (!ownsFork()) throw new Error(`Run #${runId} changed while its fork worktree was being created.`);
-						}
-						forkedSession = await forkRetainedSession({
-							cwd: thread.executionCwd,
-							targetCwd: childWorktree?.cwd ?? thread.cwd,
-							sessionDir: thread.sessionDir,
-							sessionId: thread.sessionId,
-						});
-						runtime.sessionDirs.add(forkedSession.sessionDir);
-						if (!ownsFork()) throw new Error(`Run #${runId} changed while its retained session was being forked.`);
-						const currentConfig = await loadConfig(runtime.configPath);
-						if (!ownsFork()) throw new Error(`Run #${runId} changed while fork configuration was loading.`);
-						runtime.backgroundQueue.setConcurrency(currentConfig.maxConcurrency);
-						const currentAgents = discoverAgents(currentCtx.cwd, {
-							scope: currentConfig.agentScope,
-							enabledNames: currentConfig.enabledAgents,
-							projectTrusted: currentCtx.isProjectTrusted?.() === true,
-						}).agents;
-						if (!ownsFork()) throw new Error(`Run #${runId} changed while fork was preparing; no child was started.`);
-						const childTask = forkObjective ?? thread.task;
-						const child = await startBackground(
-							thread.agentName,
-							childTask,
-							thread.cwd,
-							thread.vision,
-							thread.isolation,
-							undefined,
-							false,
-							{
-								ctx: currentCtx,
-								config: currentConfig,
-								agents: currentAgents,
-							},
-							{
-								sessionId: forkedSession.sessionId,
-								sessionDir: forkedSession.sessionDir,
-								prompt: forkObjective ?? FORK_CONTINUATION_PROMPT,
-								worktree: childWorktree,
-								forkedFromRunId: runId,
-								forkObjective,
-							},
-						);
-						if (child.exitCode !== -1 || child.runId === undefined) {
-							await cleanupTrackedSessionDir(
-								forkedSession.sessionDir,
-								`Could not discard failed fork session clone for run #${runId}`,
-							);
-							await discardUnusedWorktree(childWorktree);
-							return child;
-						}
-
-						// Once the independent child is enqueued it remains valid even if the
-						// source is retired; just skip source-side relationship mutation.
-						if (!ownsFork()) return child;
-						const childRunId = child.runId;
-						if (!thread.forkChildRunIds.includes(childRunId)) thread.forkChildRunIds.push(childRunId);
-						const childThread = runtime.threads.get(childRunId);
-						if (childThread) childThread.forkedFromRunId = runId;
-						monitor.setForkRelation(runId, childRunId);
-						const sourceResult = runtime.settledRuns.get(runId) ?? thread.lastResult;
-						if (sourceResult) sourceResult.forkChildRunIds = [...thread.forkChildRunIds];
-						return child;
-					} catch (error) {
-						if (forkedSession) {
-							await cleanupTrackedSessionDir(
-								forkedSession.sessionDir,
-								`Could not discard interrupted fork session clone for run #${runId}`,
-							);
-						}
-						await discardUnusedWorktree(childWorktree);
-						return failedStartResult(
-							thread.agentName,
-							forkObjective ?? thread.task,
-							`Could not fork retained session for run #${runId}: ${error instanceof Error ? error.message : String(error)}`,
-						);
-					} finally {
-						finishPreflight();
-						if (thread.lifecycleVersion === forkVersion && thread.lifecycleOperation === "fork") {
-							thread.lifecycleOperation = undefined;
-						}
-					}
-				};
-
-				const onLive = makeLiveHandler(runId, generation);
-				const queueController = runtime.backgroundQueue.enqueue(
-					async (backgroundSignal) => {
-						if (runtime.threads.get(runId)?.generation !== generation) return;
-						let result: SingleResult;
-						try {
-							result = await runSingleAgentWithMainFallback(
-								{
-									defaultCwd: executionCwd,
-									agent: route.agent,
-									agentName,
-									task,
-									cwd: executionCwd,
-									thinkingLevel,
-									thinkingLevelForModel: route.thinkingLevelForModel,
-									signal: backgroundSignal,
-									onLive,
-									control,
-									makeDetails: makeDetails("single", true),
-									idleTimeoutMs: runConfig.idleTimeoutSec * 1000,
-									...(priorSessionId && priorSessionDir
-										? {
-											sessionId: priorSessionId,
-											sessionDir: priorSessionDir,
-											stdinText: seed?.prompt ?? (newObjectiveOnResume
-												? task
-												: buildResumePrompt(priorTask ?? task, "the retained thread was resumed")),
-										}
-										: {}),
-								},
-								route.mainFallbackRef,
-							);
-						} catch (error) {
-							const errorMessage = error instanceof Error ? error.message : String(error);
-							result = {
-								...pending,
-								task: control.getObjective(),
-								exitCode: 1,
-								stderr: errorMessage,
-								stopReason: backgroundSignal.aborted ? "aborted" : "error",
-								errorMessage,
-								dispatchFailed: true,
-							};
-						}
-
-						// A stale process/generation may finish after a park/resume race. It owns
-						// no monitor mutation, result registration, or completion delivery.
-						if (runtime.threads.get(runId)?.generation !== generation) return;
-						result.runId = runId;
-						result.projectCwd = originalCwd;
-						result.isolation = isolation;
-						result.forkedFromRunId = thread.forkedFromRunId;
-						result.forkChildRunIds = [...thread.forkChildRunIds];
-						thread.queueController = undefined;
-						runtime.runControllers.delete(runId);
-						thread.task = result.task;
-						thread.sessionId = result.sessionId;
-						thread.sessionDir = result.sessionDir;
-						thread.lastResult = result;
-						runtime.retainSession(result);
-						monitor.setModel(runId, result.model, result.modelFallbackFrom);
-						monitor.setThinking(runId, result.thinking);
-
-						// Destructive stop owns publication once it has synchronously claimed
-						// the lifecycle. Leave the partial result/session on the thread; the
-						// stop path waits for this queue task, finalizes isolation, and emits
-						// exactly one aborted result.
-						if (thread.lifecycleOperation === "stop") return;
-
-						if (result.parked) {
-							thread.state = "parked";
-							monitor.setStatus(runId, "parked");
-							runtime.settledRuns.delete(runId);
-							return;
-						}
-
-						if (thread.retireOnSettle) runtime.retireThreadSession(thread);
-						const wantsFixLoop = shouldTriggerFixLoop(result, runConfig);
-						if (wantsFixLoop && isolation === "shared" && runtime.sessionActive) {
-							thread.state = "running";
-							// The review being done does not mean the logical run is over:
-							// the same row now represents the chain until it resolves.
-							monitor.setStatus(runId, "running");
-							monitor.setActivity(runId, "auto-fix chain running");
-							startFixLoop(result, `fix-${runId}`, runId, thread.executionCwd, vision);
-							return;
-						}
-						// Claim terminal settlement synchronously before the first slow await.
-						// Park therefore either wins while RPC is still active, or is rejected
-						// once settlement owns the generation. Destructive stop may supersede
-						// this reservation; publication is revalidated after Git finalization.
-						const settlementVersion = ++thread.lifecycleVersion;
-						thread.lifecycleOperation = "settle";
-						const ownsSettlement = (): boolean =>
-							runtime.threads.get(runId) === thread &&
-							thread.generation === generation &&
-							thread.lifecycleVersion === settlementVersion &&
-							thread.lifecycleOperation === "settle" &&
-							!thread.retired;
-						try {
-							// Worktree isolation is rejected for reviewers, the only role that can
-							// trigger auto-fix. Keep that invariant explicit: an isolated result is
-							// finalized once here and can never start a chain that would integrate
-							// the same worktree early.
-							await thread.finalizeIsolation(generation, result);
-							if (!ownsSettlement()) return;
-
-							const failed = isFailedResult(result);
-							thread.state = failed ? "failed" : "completed";
-							// Stamp the terminal monitor state before projecting it. This gives every
-							// path a fixed endedAt even when the row is removed immediately.
-							monitor.setStatus(runId, failed ? "failed" : "done");
-							if (!runtime.sessionActive || !ownsSettlement()) return;
-
-							const modelLevel = failed && isModelLevelFailure(result);
-							const dispatchFailed = result.dispatchFailed === true;
-							finishRun(runId, failed ? "failed" : "done", modelLevel || dispatchFailed ? { silent: true } : undefined);
-							runtime.registerRunResult(runId, result);
-							const completion: CompletionMessageItem = {
-								agent: result.agent,
-								block: modelLevel
-									? `${formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
-									: formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd),
-								triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
-							};
-							if (modelLevel) {
-								const detail = result.errorMessage?.trim() || "model unavailable or broken";
-								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${detail} — task handed to the main window`, "error");
-							} else if (dispatchFailed) {
-								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${result.errorMessage ?? "dispatch crashed"}`, "error");
-							}
-							if (failed) {
-								runtime.sendCompletionGroup([completion]);
-								runtime.completionBatcher.flush();
-							} else {
-								runtime.completionBatcher.push(completion);
-							}
-						} finally {
-							if (ownsSettlement()) thread.lifecycleOperation = undefined;
-						}
-					},
-					() => {
-						if (runtime.threads.get(runId)?.generation !== generation) return;
-						// Queued park/stop owns publication and may still be finalizing an
-						// isolated worktree. Do not expose a terminal monitor state before
-						// that owner records the checkpoint or aborted result.
-						if (thread.lifecycleOperation === "park" || thread.lifecycleOperation === "stop") return;
-						runtime.runControllers.delete(runId);
-						thread.queueController = undefined;
-						if (thread.state === "parked") {
-							monitor.setStatus(runId, "parked");
-							return;
-						}
-						thread.state = "stopped";
-						monitor.setStatus(runId, "failed");
-						if (!runtime.sessionActive) {
-							monitor.removeRun(runId);
-							return;
-						}
-						finishRun(runId, "failed");
-					},
-					async (error) => {
-						if (runtime.threads.get(runId)?.generation !== generation) return;
-						// Queue-level crashes use the same settlement reservation as ordinary
-						// results. A concurrent destructive stop may supersede it while slow
-						// worktree finalization is running, in which case stop publishes once.
-						if (thread.lifecycleOperation === "stop") return;
-						const settlementVersion = ++thread.lifecycleVersion;
-						thread.lifecycleOperation = "settle";
-						const ownsSettlement = (): boolean =>
-							runtime.threads.get(runId) === thread &&
-							thread.generation === generation &&
-							thread.lifecycleVersion === settlementVersion &&
-							thread.lifecycleOperation === "settle" &&
-							!thread.retired;
-						try {
-							const crashed: SingleResult = {
-								...dispatchFailedResult(route.agent, control.getObjective(), error, thinkingLevel),
-								runId,
-								isolation,
-								forkedFromRunId: thread.forkedFromRunId,
-							};
-							await thread.finalizeIsolation(generation, crashed);
-							if (!ownsSettlement()) return;
-							thread.state = "failed";
-							monitor.setStatus(runId, "failed");
-							finishRun(runId, "failed", { silent: true });
-							runtime.registerRunResult(runId, crashed);
-							runtime.runControllers.delete(runId);
-							thread.queueController = undefined;
-							if (!runtime.sessionActive || !ownsSettlement()) return;
-							try {
-								runCtx.ui.notify(`✗ ${agent.name} dispatch failed: ${crashed.errorMessage}`, "error");
-								runtime.sendCompletionGroup([
-									{
-										agent: agent.name,
-										block: formatCompletionBlock(crashed, runConfig.maxResultLines, crashed.projectCwd ?? originalCwd),
-										triggerTurn: true,
-									},
-								]);
-								runtime.completionBatcher.flush();
-							} catch {
-								/* a second delivery failure must not throw through the queue */
-							}
-						} finally {
-							if (ownsSettlement()) thread.lifecycleOperation = undefined;
-						}
-					},
-				);
-				thread.queueController = queueController;
-				thread.generationCompletion = runtime.backgroundQueue.waitForTask(queueController);
-				runtime.runControllers.set(runId, queueController);
-				return pending;
-			};
+			const startBackground = createBackgroundDispatcher({
+				runtime,
+				ctx,
+				config,
+				agents,
+				finishRun,
+				makeLiveHandler,
+				makeDetails,
+				startFixLoop,
+			});
 
 			// Sub-agents intentionally detach from the foreground turn. This makes the
 			// editor available immediately; completion messages later wake the main agent.