@ferris1225/pi-subagents 0.29.0 → 0.32.2

package/src/dispatch.ts

@@ -1,26 +1,27 @@
 /**
  * The `subagent` tool: dispatches explore/worker/reviewer agents as isolated pi
- * child processes, single or parallel. Owns the dispatch pipeline: config load
- * + unavailable-model repair, per-run widget tracking, the auto-fix chain
+ * child processes, single or parallel. Owns the dispatch pipeline: config load,
+ * per-agent model-pool resolution, per-run widget tracking, the auto-fix chain
  * (REVIEW_FAIL → worker → re-review), and completion delivery.
  *
- * Vision: a task flagged `vision: true` runs on the configured vision-capable
- * model (config.visionModel); when none is configured it falls back to the main
- * session's current model. If the configured vision model is no longer
- * available, the user is asked (TUI picker) to pick a replacement, which is
- * persisted; outside the TUI it degrades to the main-session model with a
- * warning.
+ * Vision: a task flagged `vision: true` uses the configured vision model as an
+ * explicit primary, then the agent's configured backup and the current
+ * main-window model. Stale refs remain in the pool and fail normally at runtime.
  */
 
+import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } 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 { resolve } from "node:path";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import {
 	completionTriggersTurn,
 	type CompletionMessageItem,
 } from "./completion.ts";
-import { loadConfig, saveConfig, type SubagentsConfig } from "./config.ts";
+import { loadConfig, type SubagentsConfig } from "./config.ts";
 import {
 	dispatchFailedResult,
 	failedStartResult,
@@ -37,7 +38,7 @@ import {
 	summarizeChainResult,
 	type ChainStep,
 } from "./fixloop.ts";
-import { availableModelRefs, repairUnavailableModelOverrides, resolveVisionModelRef } from "./models.ts";
+import { currentModelRef, resolveAgentModelPool } from "./models.ts";
 import {
 	formatTaskSummary,
 	formatToolActivity,
@@ -45,8 +46,13 @@ import {
 	statusIcon,
 	type RunChainMeta,
 } from "./monitor.ts";
-import type { SubagentRuntime } from "./runtime.ts";
+import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
+import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
+import { forkRetainedSession } from "./session-fork.ts";
 import {
+	buildFallbackResumeReason,
+	buildResumePrompt,
+	RpcRunControl,
 	getResultOutput,
 	isFailedResult,
 	isModelLevelFailure,
@@ -55,13 +61,50 @@ import {
 	type SingleResult,
 	type SubagentDetails,
 	type SubagentLiveEvent,
+	type SubagentRecordEvent,
 } from "./spawn.ts";
-import { promptSelectOne } from "./ui.ts";
+import { inspectorStore, summarizeToolArgs } from "./trajectory.ts";
+import {
+	createWorktreeIsolation,
+	resolveWorktreeTarget,
+	type IsolationMode,
+	type WorktreeFinalization,
+	type WorktreeIsolation,
+} 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.";
+export 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 function buildWorktreeTaskPrompt(task: string): string {
+	return `${WORKTREE_ISOLATION_INSTRUCTIONS}\n\nTask: ${task}`;
+}
+
+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[];
+	sessionRef?: string;
+}
 
 const VISION_DESCRIPTION =
-	"Set true when the task may require viewing images (screenshots, mockups, designs) — the sub-agent then runs on the configured vision-capable model, or the main session's current model when none is configured";
+	"Set true when the task may require viewing images (screenshots, mockups, designs) — the configured vision model becomes primary, followed by the agent backup and current main-window model";
+
+const ISOLATION_DESCRIPTION =
+	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents only)";
+
+const IsolationSchema = Type.Optional(
+	StringEnum(["shared", "worktree"] as const, { description: ISOLATION_DESCRIPTION }),
+);
 
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
@@ -71,6 +114,7 @@ const TaskItem = Type.Object({
 	}),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
+	isolation: IsolationSchema,
 });
 
 const SubagentParams = Type.Object({
@@ -81,57 +125,79 @@ const SubagentParams = Type.Object({
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
+	isolation: IsolationSchema,
 });
 
-/** True when any dispatched task carries the vision flag. */
-function hasVisionTask(params: { vision?: boolean; tasks?: Array<{ vision?: boolean }> }): boolean {
-	return params.vision === true || (params.tasks ?? []).some((t) => t.vision === true);
+export function defaultIsolationMode(mode: "single" | "parallel", agentName: string, requested?: IsolationMode): IsolationMode {
+	if (requested) return requested;
+	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
 }
 
-/**
- * When the configured vision model is unavailable, ask the user to pick a
- * replacement (TUI) and persist it; outside the TUI, warn and fall back to the
- * main session's model. Returns the repaired vision model (undefined = use the
- * main-session fallback).
- */
-async function repairVisionModelForDispatch(
-	ctx: ExtensionContext,
-	config: SubagentsConfig,
-	configPath: string,
-): Promise<string | undefined> {
-	const configured = config.visionModel?.trim();
-	if (!configured) return undefined;
-	const refs = availableModelRefs(ctx);
-	if (refs.includes(configured)) return configured;
-
-	if (ctx.mode === "tui" && refs.length > 0) {
+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> {
+	try {
+		return (await resolveWorktreeTarget(cwd)).originalRoot;
+	} catch {
 		try {
-			const picked = await promptSelectOne(
-				ctx,
-				`Vision model "${configured}" is unavailable. Pick a replacement?`,
-				"Type to filter • ↑/↓ • Enter selects • Esc falls back to the main session's model",
-				refs.map((ref) => ({ value: ref, label: ref })),
-			);
-			if (picked !== undefined) {
-				try {
-					await saveConfig({ ...config, visionModel: picked }, configPath);
-					ctx.ui.notify(`Vision model switched to ${picked}.`, "info");
-				} catch {
-					/* persistence failure is non-fatal; the pick still applies this dispatch */
-				}
-				return picked;
-			}
+			return await realpath(resolve(cwd));
 		} catch {
-			/* a failed picker must never break the dispatch */
+			return resolve(cwd);
 		}
-		ctx.ui.notify(`Vision model left as "${configured}"; this dispatch runs without the vision override.`, "warning");
-		return undefined;
 	}
-	ctx.ui.notify(
-		`Configured vision model "${configured}" is unavailable; this dispatch uses the main session's model.`,
-		"warning",
-	);
-	return undefined;
+}
+
+/** Keep the complete worker→review loop exclusive for one canonical repository.
+ * Child processes have independent file-mutation queues, so queue concurrency
+ * alone cannot make shared-checkout edits safe. */
+function serializeAutoFixChain(
+	cwd: string,
+	task: (signal: AbortSignal) => Promise<void>,
+): (signal: AbortSignal) => Promise<void> {
+	return async (signal) => {
+		if (signal.aborted) return;
+		const root = await canonicalAutoFixRoot(cwd);
+		const key = process.platform === "win32" ? root.toLowerCase() : root;
+		const previous = autoFixRootTails.get(key) ?? Promise.resolve();
+		let release!: () => void;
+		const gate = new Promise<void>((resolveGate) => {
+			release = resolveGate;
+		});
+		const tail = previous.catch(() => undefined).then(() => gate);
+		autoFixRootTails.set(key, tail);
+		await previous.catch(() => undefined);
+		try {
+			if (!signal.aborted) await task(signal);
+		} finally {
+			release();
+			if (autoFixRootTails.get(key) === tail) autoFixRootTails.delete(key);
+		}
+	};
+}
+
+function resolveDispatchModelPool(
+	agent: AgentConfig,
+	config: SubagentsConfig,
+	mainRef: string | undefined,
+	vision: boolean,
+): { agent: AgentConfig; fallbackModelRefs: string[] } {
+	const pool = resolveAgentModelPool({
+		primaryRef: vision ? config.visionModel : config.agentModels[agent.name],
+		backupRef: config.agentBackupModels[agent.name],
+		mainRef,
+		declaredDefaultRef: agent.model,
+	});
+	return {
+		agent: { ...agent, model: pool.primaryRef },
+		fallbackModelRefs: pool.fallbackModelRefs,
+	};
 }
 
 export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
@@ -142,10 +208,12 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
 			"Agents: explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
 			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
+			"Isolation: single tasks default to shared; parallel worker tasks default to detached Git worktrees unless isolation: shared is explicit. explore/reviewer cannot use worktree isolation.",
+			"Use subagent_control to steer, retarget, park, resume, or fork a thread by its stable run id.",
 			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
 			"Results arrive as wake-up messages automatically — you do NOT need to wait. If you must get a result in-turn, subagent_wait is a non-blocking lookup by default (pass timeoutMs to block).",
-			"Vision: set vision: true when the task may require viewing images (screenshots, mockups, design files — e.g. frontend work) — the sub-agent then runs on the vision-capable model configured in /subagents-setup, or the main session's current model when none is configured.",
+			"Vision: set vision: true when the task may require viewing images (screenshots, mockups, design files — e.g. frontend work) — the configured vision model is primary, followed by that agent's backup and the current main-window model.",
 		].join(" "),
 		promptSnippet:
 			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
@@ -155,36 +223,20 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			"Use subagent with agent 'worker' for a self-contained implementation task worth a separate context; it plans internally.",
 			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
 			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
-			"Run independent tasks in parallel by passing a tasks array to subagent; let the automatically resumed main agent start dependent work after results arrive.",
+			"Run independent tasks in parallel by passing a tasks array to subagent; parallel worker items default to isolation: worktree so their edits are integrated independently. Pass isolation: shared only when workers intentionally need the caller's live uncommitted tree.",
+			"Use isolation: worktree only for worker/write-capable agents and only inside a Git repository with a committed HEAD; setup or integration failures never silently fall back to shared.",
 			"NEVER sleep or poll, and do NOT call subagent_wait to hold the turn — subagent ends the turn immediately and the result arrives as a message that wakes you automatically (even mid-turn). Ending your turn is the default and the only correct way to wait.",
 			"If you must keep the turn for a result, call subagent_wait with an explicit timeoutMs (non-blocking by default) — never bash sleep/timeout to wait for a sub-agent.",
-			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The sub-agent then runs on the configured vision-capable model, or the main session's current model when none is configured.",
+			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The configured vision model becomes primary; model-level failures continue through the agent's backup pool and current main-window model.",
+			"When a sub-agent result arrives it is already shown to the user — do NOT restate, paraphrase, or summarize it; reply with only your own conclusion or next action (often just one line), since duplicating the result wastes tokens for nothing.",
 		],
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			monitor.beginTurn();
-			let config = await loadConfig(runtime.configPath);
+			const config = await loadConfig(runtime.configPath);
 			// Pick up concurrency changes from /subagents-setup without a restart.
 			runtime.backgroundQueue.setConcurrency(config.maxConcurrency);
-			const repairedModels = repairUnavailableModelOverrides(ctx, config.agentModels);
-			if (repairedModels.changed) {
-				config = { ...config, agentModels: repairedModels.agentModels };
-				try {
-					await saveConfig(config, runtime.configPath);
-					ctx.ui.notify(
-						repairedModels.fallbackRef
-							? `Unavailable sub-agent models switched to ${repairedModels.fallbackRef} and saved to config.`
-							: "Unavailable sub-agent model overrides removed; no main-window model is available.",
-						"warning",
-					);
-				} catch (error) {
-					ctx.ui.notify(
-						`Could not persist repaired sub-agent model config: ${error instanceof Error ? error.message : String(error)}`,
-						"warning",
-					);
-				}
-			}
 
 			// Finished runs leave the widget immediately. Their final findings are sent
 			// back as a custom message that automatically starts a follow-up turn.
@@ -203,51 +255,92 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			};
 
 			// Live sub-agent activity → concise one-line status ("thinking",
-			// "read src/index.ts", ...), never a raw args blob. The live handler only
-			// updates widget status; finishing (removeRun + notify) is owned by the
-			// queue task / launchInLoop. That keeps a startup retry — which fires a
-			// transient "failed" status before relaunching — from ripping the row out
-			// early, and lets the queue task decide between delivering a reviewer's
-			// result and starting an auto-fix chain (a triggered chain keeps the
-			// parent row annotated until it completes).
-			const makeLiveHandler = (runId: number) => (e: SubagentLiveEvent): void => {
-				switch (e.kind) {
-					case "status":
-						// Only update the widget status here. Finishing (removeRun + notify) is
-						// owned by the queue task / launchInLoop so that a startup retry — which
-						// fires a transient "failed" status before relaunching the child — never
-						// rips the row out from under the retry or emits a premature "✗" toast.
-						monitor.setStatus(runId, e.status);
-						break;
-					case "usage":
-						monitor.setUsage(runId, e.usage, e.model);
-						break;
-					case "tool_start":
-						monitor.recordToolStart(runId, e.toolName, formatToolActivity(e.toolName, e.args));
-						break;
-					case "tool_end":
-						monitor.recordToolEnd(runId, e.toolName, e.isError);
-						break;
-					case "thinking":
-						monitor.setActivity(runId, "thinking");
-						break;
-					case "text":
-						// A text delta is model output, not a filesystem write.
-						monitor.setActivity(runId, "responding");
-						break;
-				}
-			};
+			// "read src/index.ts", ...), never a raw args blob. In parallel, every
+			// live event is appended to the thread's append-only trajectory (status,
+			// model-candidate changes, usage, tool starts/ends with a redacted
+			// args summary) so /subagents-inspect can replay what happened. The live
+			// handler only updates widget status; finishing (removeRun + notify) is
+			// owned by the queue task / launchInLoop. That keeps a startup retry —
+			// which fires a transient "failed" status before relaunching — from
+			// ripping the row out early, and lets the queue task decide between
+			// delivering a reviewer's result and starting an auto-fix chain.
+			const makeLiveHandler =
+				(runId: number, threadId?: number, generation?: number) =>
+				(e: SubagentLiveEvent): void => {
+					if (generation !== undefined && runtime.threads.get(runId)?.generation !== generation) return;
+					switch (e.kind) {
+						case "status":
+							// Only update the widget status here. Finishing (removeRun + notify) is
+							// owned by the queue task / launchInLoop so that a startup retry — which
+							// fires a transient "failed" status before relaunching the child — never
+							// rips the row out from under the retry or emits a premature "✗" toast.
+							monitor.setStatus(runId, e.status);
+							break;
+						case "model":
+							monitor.setModel(runId, e.model, e.fallbackFrom);
+							break;
+						case "usage":
+							monitor.setUsage(runId, e.usage, e.model);
+							break;
+						case "tool_start":
+							monitor.recordToolStart(runId, e.toolName, formatToolActivity(e.toolName, e.args));
+							break;
+						case "tool_end":
+							monitor.recordToolEnd(runId, e.toolName, e.isError);
+							break;
+						case "thinking":
+							monitor.setActivity(runId, "thinking");
+							break;
+						case "text":
+							// A text delta is model output, not a filesystem write.
+							monitor.setActivity(runId, "responding");
+							break;
+					}
+					if (threadId !== undefined) {
+						const trajectory = inspectorStore.get(threadId).trajectory;
+						switch (e.kind) {
+								case "status":
+									trajectory.append({ kind: "status", status: e.status });
+									break;
+								case "model":
+									trajectory.append({ kind: "candidate", model: e.model, fallbackFrom: e.fallbackFrom });
+									break;
+								case "usage":
+									trajectory.append({ kind: "usage", usage: { ...e.usage }, model: e.model });
+									break;
+								case "tool_start":
+									trajectory.append({
+										kind: "tool_start",
+										tool: e.toolName,
+										toolCallId: e.toolCallId,
+										summary: summarizeToolArgs(e.args),
+									});
+									break;
+								case "tool_end":
+									trajectory.append({ kind: "tool_end", tool: e.toolName, toolCallId: e.toolCallId, isError: e.isError });
+									break;
+								// Text/thinking deltas arrive via onRecord below.
+							}
+					}
+				};
+
+			/** Raw streamed output (text/thinking deltas) → the thread's bounded
+			 * transcript buffer; dropped on restart, never carried across generations. */
+			const makeRecordHandler =
+				(threadId: number, generation?: number) =>
+				(e: SubagentRecordEvent): void => {
+					if (generation !== undefined && runtime.threads.get(threadId)?.generation !== generation) return;
+					const transcript = inspectorStore.get(threadId).transcript;
+					if (e.kind === "thinking") transcript.appendThinking(e.delta);
+					else transcript.appendText(e.delta);
+				};
 			const discovery = discoverAgents(ctx.cwd, {
 				scope: config.agentScope,
 				enabledNames: config.enabledAgents,
+				projectTrusted: ctx.isProjectTrusted?.() === true,
 			});
-
-			// Effective model precedence: setup override > current session model > frontmatter default.
-			const sessionRef = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
-			const agents: AgentConfig[] = discovery.agents.map((agent) => ({
-				...agent,
-				model: config.agentModels[agent.name] ?? sessionRef ?? agent.model,
-			}));
+			const sessionRef = currentModelRef(ctx);
+			const agents = discovery.agents;
 
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
 			const hasSingle = Boolean(params.agent) && params.task !== undefined;
@@ -295,21 +388,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				};
 			}
 
-			// A vision-flagged dispatch with a stale vision model asks the user for a
-			// replacement before spawning (the persisted pick also fixes future runs).
-			// Runs only after parameter validation, so an invalid call never pops a picker.
-			const visionRequested = hasVisionTask(params);
-			let visionModel = config.visionModel;
-			if (visionRequested && visionModel !== undefined && !availableModelRefs(ctx).includes(visionModel.trim())) {
-				visionModel = await repairVisionModelForDispatch(ctx, config, runtime.configPath);
-			}
-			// Vision-flagged dispatches run on the configured vision model, else the
-			// main session's current model (the documented fallback), else the agent's
-			// own model as the last resort.
-			const visionRef = resolveVisionModelRef(ctx, visionModel);
-			const withVision = (agent: AgentConfig, vision: boolean): AgentConfig =>
-				vision && visionRef ? { ...agent, model: visionRef } : agent;
-
 			/**
 			 * Dispatch one agent inside an auto-fix chain: tracked in the widget with a
 			 * groupId/relationLabel, but NOT delivered through the completion flow — the
@@ -318,45 +396,85 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			const launchInLoop = async (
 				agentName: string,
 				task: string,
+				executionCwd: string,
 				signal: AbortSignal,
 				meta: RunChainMeta,
 				vision = false,
 			): Promise<{ runId?: number; result: SingleResult }> => {
 				const agent = agents.find((candidate) => candidate.name === agentName);
 				if (!agent) return { result: failedStartResult(agentName, task, `Unknown agent: "${agentName}".`) };
-				// A vision-flagged chain (e.g. a review of UI screenshots) keeps its rounds
-				// on the vision model: the fix worker and re-review re-read the same images.
-				const effectiveAgent = withVision(agent, vision);
+				// Vision chains keep the vision override as each round's primary while
+				// retaining that worker/reviewer's own configured backup pool.
+				const pool = resolveDispatchModelPool(agent, config, sessionRef, vision);
 				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
-				const runId = monitor.addRun(agent.name, task, effectiveAgent.model, thinkingLevel, meta);
-				const onLive = makeLiveHandler(runId);
+				const runId = monitor.addRun(agent.name, task, pool.agent.model, thinkingLevel, meta);
+				// Chain rounds are real threads: they get their own trajectory so the
+				// inspector can show each fix/re-review round's full story.
+				const chainState = inspectorStore.get(runId);
+				chainState.retainFrom({ agent: agent.name, task, status: "queued", model: pool.agent.model, thinking: thinkingLevel });
+				chainState.trajectory.append({
+					kind: "dispatch",
+					agent: agent.name,
+					task,
+					model: pool.agent.model,
+					thinking: thinkingLevel,
+					pool: pool.fallbackModelRefs,
+					vision,
+					isolation: "shared",
+					originalCwd: executionCwd,
+					isolationCwd: executionCwd,
+				});
+				const onLive = makeLiveHandler(runId, runId);
+				const onRecord = makeRecordHandler(runId);
 				try {
 					const result = await runSingleAgentWithModelFallback(
 						{
-							defaultCwd: ctx.cwd,
-							agent: effectiveAgent,
+							defaultCwd: executionCwd,
+							cwd: executionCwd,
+							agent: pool.agent,
 							agentName,
 							task,
 							thinkingLevel,
 							signal,
 							onLive,
+							onRecord,
 							makeDetails: makeDetails("single", true),
 							idleTimeoutMs: config.idleTimeoutSec * 1000,
 						},
-						sessionRef,
+						pool.fallbackModelRefs,
 					);
+					result.runId = runId;
+					result.isolation = "shared";
+					result.originalCwd = executionCwd;
+					result.isolationCwd = executionCwd;
+					runtime.retainSession(result);
+					monitor.setModel(runId, result.model, result.modelFallbackFrom);
+					chainState.trajectory.append({
+						kind: "settled",
+						status: isFailedResult(result) ? "failed" : "done",
+						model: result.model,
+					});
 					// Keep the finished round visible in the widget while the chain is
 					// still running, with a one-line summary of what it did; the whole
 					// group is dropped when the chain resolves (see removeChainGroup).
 					monitor.setSummary(runId, summarizeChainResult(result));
 					finishRun(runId, isFailedResult(result) ? "failed" : "done", { retain: true });
+					const retainedRun = monitor.findRun(runId);
+					if (retainedRun) chainState.retainFrom(retainedRun);
 					runtime.registerRunResult(runId, result);
 					return { runId, result };
 				} catch (error) {
 					finishRun(runId, "failed", { retain: true });
+					chainState.trajectory.append({ kind: "settled", status: "failed", model: pool.agent.model });
+					const retainedRun = monitor.findRun(runId);
+					if (retainedRun) chainState.retainFrom(retainedRun);
 					const errorMessage = error instanceof Error ? error.message : String(error);
-					const crashed = {
-						...queuedResult(agent, task, thinkingLevel),
+					const crashed: SingleResult = {
+						...queuedResult(pool.agent, task, thinkingLevel),
+						runId,
+						isolation: "shared",
+						originalCwd: executionCwd,
+						isolationCwd: executionCwd,
 						exitCode: 1,
 						stderr: errorMessage,
 						stopReason: signal.aborted ? "aborted" : "error",
@@ -388,10 +506,35 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				initialReviewerResult: SingleResult,
 				parentGroupId: string,
 				parentRunId: number,
+				executionCwd: string,
 				vision = false,
 			): void => {
-				runtime.runControllers.set(parentRunId, runtime.backgroundQueue.enqueue(
-					async (signal) => {
+				const parentThreadAtStart = runtime.threads.get(parentRunId);
+				if (!parentThreadAtStart) return;
+				const parentGeneration = parentThreadAtStart.generation;
+				const parentControl = parentThreadAtStart.control;
+				let fixController: AbortController | undefined;
+				const ownsParent = (): boolean => {
+					const current = runtime.threads.get(parentRunId);
+					return fixController !== undefined &&
+						current === parentThreadAtStart &&
+						current.generation === parentGeneration &&
+						current.control === parentControl &&
+						current.queueController === fixController &&
+						runtime.runControllers.get(parentRunId) === fixController;
+				};
+				const clearOwnedController = (): void => {
+					if (!fixController) return;
+					if (runtime.runControllers.get(parentRunId) === fixController) {
+						runtime.runControllers.delete(parentRunId);
+					}
+					const current = runtime.threads.get(parentRunId);
+					if (current === parentThreadAtStart && current.queueController === fixController) {
+						current.queueController = undefined;
+					}
+				};
+				fixController = runtime.backgroundQueue.enqueue(
+					serializeAutoFixChain(executionCwd, async (signal) => {
 						const chain: ChainStep[] = [
 							{ runId: parentRunId, result: initialReviewerResult, relation: "initial review" },
 						];
@@ -399,17 +542,45 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						for (let round = 1; round <= config.maxFixRounds; round++) {
 							if (!runtime.sessionActive) break;
 							const fixBrief = buildFixTaskBrief(lastReviewer, round, config.maxFixRounds);
-							const workerStep = await launchInLoop("worker", fixBrief, signal, {
+							const workerStep = await launchInLoop("worker", fixBrief, executionCwd, signal, {
 								groupId: parentGroupId,
 								relationLabel: `fix round ${round}`,
 							}, vision);
+							// Preserve the newest sub-step before checking chain ownership. A
+							// destructive stop invalidates ownsParent() while this child is
+							// aborting, and its partial output must become the parent's stopped
+							// result instead of falling back to the old triggering review.
+							if (
+								runtime.threads.get(parentRunId) === parentThreadAtStart &&
+								parentThreadAtStart.generation === parentGeneration
+							) {
+								parentThreadAtStart.lastResult = workerStep.result;
+								parentThreadAtStart.agentName = workerStep.result.agent;
+								parentThreadAtStart.task = workerStep.result.task;
+								parentThreadAtStart.sessionId = workerStep.result.sessionId;
+								parentThreadAtStart.sessionDir = workerStep.result.sessionDir;
+								runtime.retainSession(workerStep.result);
+							}
+							if (!ownsParent()) return;
 							chain.push({ ...workerStep, relation: `fix round ${round}` });
 							if (!runtime.sessionActive || isFailedResult(workerStep.result)) break;
 							const reReviewBrief = buildReReviewBrief(lastReviewer, round);
-							const reviewStep = await launchInLoop("reviewer", reReviewBrief, signal, {
+							const reviewStep = await launchInLoop("reviewer", reReviewBrief, executionCwd, signal, {
 								groupId: parentGroupId,
 								relationLabel: `re-review round ${round}`,
 							}, vision);
+							if (
+								runtime.threads.get(parentRunId) === parentThreadAtStart &&
+								parentThreadAtStart.generation === parentGeneration
+							) {
+								parentThreadAtStart.lastResult = reviewStep.result;
+								parentThreadAtStart.agentName = reviewStep.result.agent;
+								parentThreadAtStart.task = reviewStep.result.task;
+								parentThreadAtStart.sessionId = reviewStep.result.sessionId;
+								parentThreadAtStart.sessionDir = reviewStep.result.sessionDir;
+								runtime.retainSession(reviewStep.result);
+							}
+							if (!ownsParent()) return;
 							chain.push({ ...reviewStep, relation: `re-review round ${round}` });
 							lastReviewer = reviewStep.result;
 							// A crashed re-review must stop the chain like a crashed worker: its
@@ -418,27 +589,70 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							if (!runtime.sessionActive || isFailedResult(reviewStep.result)) break;
 							if (reviewVerdict(getResultOutput(reviewStep.result)) === "pass") break;
 						}
+						// Every parent mutation is guarded by the exact generation, control, and
+						// queue controller that started this chain. A parked/resumed generation or
+						// destructive stop must make this old orchestration a no-op.
+						if (!ownsParent()) return;
+						const controlledParent = parentThreadAtStart;
+						if (controlledParent.retired || controlledParent.state === "stopped") {
+							clearOwnedController();
+							removeChainGroup(parentGroupId);
+							return;
+						}
+						// Parking an auto-fix chain aborts its in-flight child but preserves the
+						// parent's retained checkpoint and suppresses an aborted chain delivery.
+						if (controlledParent.state === "parked") {
+							clearOwnedController();
+							removeChainGroup(parentGroupId);
+							monitor.setRetained(parentRunId, false);
+							monitor.setStatus(parentRunId, "parked");
+							return;
+						}
 						// The chain is done (success, exhaustion, or abort): drop the retained
 						// parent row and its retained round rows, then deliver one condensed
 						// summary. Register the parent's final state (the last chain result)
 						// before removal so subagent_wait can resolve it.
-						runtime.registerRunResult(parentRunId, chain[chain.length - 1].result);
-						runtime.runControllers.delete(parentRunId);
+						const last = chain[chain.length - 1];
+						runtime.registerRunResult(parentRunId, last.result);
 						removeChainGroup(parentGroupId);
 						monitor.removeRun(parentRunId);
-						if (!runtime.sessionActive) return;
+						runtime.retainSession(last.result);
+						const parentThread = parentThreadAtStart;
+						parentThread.agentName = last.result.agent;
+						parentThread.task = last.result.task;
+						parentThread.sessionId = last.result.sessionId;
+						parentThread.sessionDir = last.result.sessionDir;
+						parentThread.state = isFailedResult(last.result) ? "failed" : "completed";
+						// The chain outcome settles the parent thread's trajectory: the
+						// last chain step is its final state.
+						const parentInspection = inspectorStore.get(parentRunId);
+						parentInspection.trajectory.append({
+							kind: "settled",
+							status: parentThread.state === "failed" ? "failed" : "done",
+							model: last.result.model,
+						});
+						parentInspection.retainFrom({
+							agent: last.result.agent,
+							task: last.result.task,
+							model: last.result.model,
+							status: parentThread.state === "failed" ? "failed" : "done",
+							usage: last.result.usage,
+						});
+						if (!runtime.sessionActive) {
+							clearOwnedController();
+							return;
+						}
 						// One compact message instead of every round's raw output: the summary
 						// lines cover each step (verdict + what changed/found), and the final
 						// step's full report is appended only when its detail is actionable
 						// (a FAIL verdict, a crash, or a model-level failure the main agent
 						// must take over). Everything else stays one `subagent_status #id`
 						// call away.
-						const last = chain[chain.length - 1];
 						let block = formatChainSummary(chain);
 						if (isFailedResult(last.result) && isModelLevelFailure(last.result)) {
-							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(last.result)}`;
+							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, executionCwd)}\n\n${modelLevelTakeoverNote(last.result, { runId: parentRunId })}`;
 						} else if (isFailedResult(last.result) || reviewVerdict(getResultOutput(last.result)) === "fail") {
-							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}`;
+							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, executionCwd)}`;
 						}
 						runtime.sendCompletionGroup([
 							{
@@ -448,25 +662,37 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							},
 						]);
 						runtime.completionBatcher.flush();
-					},
+						clearOwnedController();
+					}),
 					() => {
-						// Cancelled before delivery: clean up the retained parent row and
-						// every retained chain row (each in-flight chain run was already
-						// finished by its launchInLoop path).
-						runtime.runControllers.delete(parentRunId);
+						if (!ownsParent()) return;
+						const controlledParent = parentThreadAtStart;
+						clearOwnedController();
 						removeChainGroup(parentGroupId);
-						monitor.removeRun(parentRunId);
+						if (controlledParent.state === "parked") {
+							monitor.setRetained(parentRunId, false);
+							monitor.setStatus(parentRunId, "parked");
+							return;
+						}
+						if (!controlledParent.retired) monitor.removeRun(parentRunId);
 					},
 					(error) => {
 						// A crash inside the chain orchestration (failed runs are caught by
-						// launchInLoop and delivered as part of the chain) must not vanish:
-						// drop the retained rows, notify, and deliver a failed result
-						// so the main agent knows the chain never completed.
+						// launchInLoop and delivered as part of the chain) must not vanish, but
+						// an obsolete generation/controller must never publish it.
+						if (!ownsParent()) return;
+						if (parentThreadAtStart.retired || parentThreadAtStart.state === "stopped") {
+							clearOwnedController();
+							removeChainGroup(parentGroupId);
+							return;
+						}
 						runtime.registerRunResult(parentRunId, initialReviewerResult);
-						runtime.runControllers.delete(parentRunId);
 						removeChainGroup(parentGroupId);
 						monitor.removeRun(parentRunId);
-						if (!runtime.sessionActive) return;
+						if (!runtime.sessionActive) {
+							clearOwnedController();
+							return;
+						}
 						const errorMessage = error instanceof Error ? error.message : String(error);
 						try {
 							ctx.ui.notify(`✗ auto-fix chain dispatch failed: ${errorMessage}`, "error");
@@ -475,157 +701,1055 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							runtime.sendCompletionGroup([
 								{
 									agent: initialReviewerResult.agent,
-									block: `${formatCompletionBlock(initialReviewerResult, config.maxResultLines, ctx.cwd)}\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.`,
+									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,
 								},
 							]);
 							runtime.completionBatcher.flush();
 						} catch {
 							/* a second delivery failure must not throw through the queue */
+						} finally {
+							clearOwnedController();
 						}
 					},
-				));
+				);
+				runtime.runControllers.set(parentRunId, fixController);
+				parentThreadAtStart.queueController = fixController;
+				const priorCompletion = parentThreadAtStart.generationCompletion;
+				parentThreadAtStart.generationCompletion = Promise.all([
+					priorCompletion,
+					runtime.backgroundQueue.waitForTask(fixController),
+				]).then(() => undefined);
 			};
 
-			const startBackground = (agentName: string, task: string, cwd?: string, vision = false): SingleResult => {
-				const agent = agents.find((candidate) => candidate.name === agentName);
+			interface SessionSeed {
+				sessionId?: string;
+				sessionDir?: string;
+				prompt?: string;
+				worktree?: WorktreeIsolation;
+				forkedFromRunId?: number;
+				forkObjective?: string;
+				modelPool?: string[];
+				thinkingLevel?: SubagentThread["thinkingLevel"];
+			}
+
+			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 runSessionRef = environment?.sessionRef ?? sessionRef;
+				const agent = runAgents.find((candidate) => candidate.name === agentName);
 				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
-				// A vision-flagged task runs on the configured vision model (or the main
-				// session's current model), overriding the agent's own model — the
-				// per-agent model may not support images.
-				const effectiveAgent = withVision(agent, vision);
+				if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
+					return {
+						...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to worker/write-capable agents.`),
+						isolation,
+					};
+				}
 
-				// Effective strength: config override > agent frontmatter default > global default.
-				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
-				const pending = queuedResult(effectiveAgent, task, thinkingLevel);
-				const runId = monitor.addRun(agent.name, task, effectiveAgent.model, thinkingLevel);
-				// Only a main-agent-dispatched reviewer can trigger an auto-fix chain, so
-				// only its finish is deferred to the queue task (see startFixLoop).
-				const onLive = makeLiveHandler(runId);
+				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,
+							originalCwd,
+							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,
+								originalCwd,
+							};
+						}
+					}
+				}
+				const executionCwd = worktree?.cwd ?? originalCwd;
+				const resolvedPool = resolveDispatchModelPool(agent, runConfig, runSessionRef, vision);
+				const inheritedPool = seed?.modelPool?.filter((ref) => ref.trim().length > 0) ?? [];
+				const rawPool = inheritedPool.length > 0
+					? {
+						agent: { ...agent, model: inheritedPool[0] },
+						fallbackModelRefs: inheritedPool.slice(1),
+					}
+					: resolvedPool;
+				// Isolation is a persistent system-level invariant, not a one-shot task
+				// prefix: queued retargets, live retargets, resumes, and model fallbacks
+				// all keep the same worktree boundary.
+				const pool = isolation === "worktree"
+					? { ...rawPool, agent: withWorktreeSystemPrompt(rawPool.agent) }
+					: rawPool;
+				const thinkingLevel = seed?.thinkingLevel ?? runConfig.agentThinkingLevels[agent.name] ?? agent.thinking ?? runConfig.thinkingLevel;
+				const modelPool = [pool.agent.model, ...pool.fallbackModelRefs].filter((ref): ref is string => Boolean(ref));
+				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, pool.agent.model, thinkingLevel, {
+					isolation,
+					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
+				});
+				const generation = (existingThread?.generation ?? 0) + 1;
+				const pending: SingleResult = {
+					...queuedResult(pool.agent, task, thinkingLevel),
+					runId,
+					isolation,
+					originalCwd,
+					isolationCwd: executionCwd,
+					...(isolation === "worktree" ? { integrationStatus: "pending" as const } : {}),
+					...(seed?.sessionId && seed.sessionDir
+						? { sessionId: seed.sessionId, sessionDir: seed.sessionDir, resumed: true }
+						: {}),
+					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
+				};
+				if (existingThread) {
+					monitor.restartRun(runId, agent.name, task, pool.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;
+					// Orchestration transitions are part of the trajectory (retrying →
+					// retry event, park/stop → terminal control events).
+					const trajectory = inspectorStore.get(runId).trajectory;
+					if (phase === "retrying") trajectory.append({ kind: "retry", reason: "retrying" });
+					else if (phase === "parked") trajectory.append({ kind: "park" });
+					else if (phase === "stopped") trajectory.append({ kind: "stop", reason: control.getStopMessage() });
+					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");
+				});
+
+				// Inspector projection for this thread id: on restart the append-only
+				// event history is kept (bumped generation), while the bounded
+				// transcript starts fresh for the new generation.
+				const inspectState = inspectorStore.get(runId);
+				if (existingThread) {
+					inspectState.trajectory.restart();
+					inspectState.transcript.clear();
+					inspectState.trajectory.append({
+						kind: "resume",
+						objective: newObjectiveOnResume ? task : undefined,
+					});
+				}
+				inspectState.retainFrom({ agent: agent.name, task, status: "queued", model: pool.agent.model, thinking: thinkingLevel });
+				if (seed?.forkedFromRunId !== undefined) {
+					inspectState.trajectory.append({
+						kind: "fork",
+						sourceRunId: seed.forkedFromRunId,
+						childRunId: runId,
+						objective: seed.forkObjective,
+					});
+				}
+				inspectState.trajectory.append({
+					kind: "dispatch",
+					agent: agent.name,
+					task,
+					model: pool.agent.model,
+					thinking: thinkingLevel,
+					pool: pool.fallbackModelRefs,
+					vision,
+					resumed: existingThread !== undefined || seed !== undefined,
+					isolation,
+					originalCwd,
+					isolationCwd: executionCwd,
+				});
+				if (worktree && worktree !== previousWorktree) {
+					inspectState.trajectory.append({
+						kind: "worktree",
+						status: "created",
+						originalCwd,
+						isolationCwd: executionCwd,
+						worktreePath: worktree.worktreePath,
+					});
+				}
+
+				if (existingThread) {
+					thread = existingThread;
+					thread.generation = generation;
+					thread.agentName = agent.name;
+					thread.task = task;
+					thread.cwd = originalCwd;
+					thread.executionCwd = executionCwd;
+					thread.vision = vision;
+					thread.modelPool = modelPool;
+					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,
+					// transcript, and 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,
+						modelPool,
+						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(
+						`✗ worker 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);
+					inspectState.trajectory.append({
+						kind: "worktree",
+						status: finalization.status,
+						originalCwd: thread.cwd,
+						isolationCwd: thread.executionCwd,
+						worktreePath: finalization.worktreePath,
+						patchPath: finalization.patchPath,
+						integrated: finalization.integrated,
+						error: finalization.error,
+					});
+					if (result) {
+						result.runId = runId;
+						result.isolation = "worktree";
+						result.originalCwd = thread.cwd;
+						result.isolationCwd = thread.executionCwd;
+						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") {
+						runtime.retainWorktreeArtifacts(finalization);
+						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 {
+						if (candidate.discard) {
+							await candidate.discard();
+							return;
+						}
+						// Compatibility for externally supplied/test handles. Production handles
+						// expose discard(), so this fallback never integrates a seeded worktree.
+						if (candidate.state === "active") await candidate.finalize();
+					} 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)}`,
+						};
+						runtime.retainWorktreeArtifacts(finalization);
+						await persistRecoveryRecords(runtime.configPath, [
+							recoveryRecordFromFinalization(runId, finalization),
+						]).catch(() => undefined);
+						try {
+							thread.notifyIsolationFailure?.(finalization);
+						} catch {
+							/* parent UI may already be shutting down */
+						}
+					}
+				};
 
-				runtime.runControllers.set(runId, runtime.backgroundQueue.enqueue(
+				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,
+								sessionRef: currentModelRef(currentCtx),
+							},
+							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,
+								sessionRef: currentModelRef(currentCtx),
+							},
+							{
+								sessionId: forkedSession.sessionId,
+								sessionDir: forkedSession.sessionDir,
+								prompt: forkObjective ?? FORK_CONTINUATION_PROMPT,
+								worktree: childWorktree,
+								forkedFromRunId: runId,
+								forkObjective,
+								modelPool: [...thread.modelPool],
+								thinkingLevel: thread.thinkingLevel,
+							},
+						);
+						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);
+						inspectorStore.get(runId).trajectory.append({
+							kind: "fork",
+							sourceRunId: runId,
+							childRunId,
+							objective: forkObjective,
+						});
+						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, runId, generation);
+				const onRecord = makeRecordHandler(runId, generation);
+				const queueController = runtime.backgroundQueue.enqueue(
 					async (backgroundSignal) => {
+						if (runtime.threads.get(runId)?.generation !== generation) return;
 						let result: SingleResult;
 						try {
 							result = await runSingleAgentWithModelFallback(
 								{
-									defaultCwd: ctx.cwd,
-									agent: effectiveAgent,
+									defaultCwd: executionCwd,
+									agent: pool.agent,
 									agentName,
 									task,
-									cwd,
+									cwd: executionCwd,
 									thinkingLevel,
 									signal: backgroundSignal,
 									onLive,
+									onRecord,
+									control,
 									makeDetails: makeDetails("single", true),
-									idleTimeoutMs: config.idleTimeoutSec * 1000,
+									idleTimeoutMs: runConfig.idleTimeoutSec * 1000,
+									...(priorSessionId && priorSessionDir
+										? {
+											sessionId: priorSessionId,
+											sessionDir: priorSessionDir,
+											stdinText: seed?.prompt ?? (newObjectiveOnResume
+												? task
+												: buildResumePrompt(priorTask ?? task, buildFallbackResumeReason())),
+										}
+										: {}),
 								},
-								sessionRef,
+								pool.fallbackModelRefs,
 							);
 						} 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,
 							};
-							// The dedicated dispatch-failure notification below replaces the generic
-							// failure toast for dispatch crashes, so finish silently here.
-							finishRun(runId, "failed", { silent: true });
-							runtime.registerRunResult(runId, result);
-							runtime.runControllers.delete(runId);
 						}
 
-						if (!runtime.sessionActive) return;
-						// Auto-fix loop: a REVIEW_FAIL from a main-agent-dispatched reviewer
-						// triggers a worker→reviewer chain (up to maxFixRounds) without waking
-						// the main agent. Loop-internal re-reviews never reach here (they are
-						// awaited inside launchInLoop); the initial review is delivered with
-						// the chain at the end. While the chain runs, the triggering review
-						// stays in the widget (annotated) so the chain rows have an obvious
-						// parent; no premature "done" notification is shown.
-						if (shouldTriggerFixLoop(result, config)) {
-							// The session is known active here (checked above), so the chain
-							// always starts: keep the triggering review in the widget
-							// (annotated) without a premature "done" notification, and let
-							// startFixLoop deliver the whole chain and drop the parent row.
+						// 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.isolation = isolation;
+						result.originalCwd = originalCwd;
+						result.isolationCwd = executionCwd;
+						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);
+
+						// 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");
+							const parkedRun = monitor.findRun(runId);
+							if (parkedRun) inspectState.retainFrom({ ...parkedRun, task: result.task, usage: result.usage });
+							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";
 							finishRun(runId, "done", { silent: true, retain: true });
 							monitor.setAnnotation(runId, "auto-fix chain running");
-							startFixLoop(result, `fix-${runId}`, runId, vision);
+							startFixLoop(result, `fix-${runId}`, runId, thread.executionCwd, vision);
 							return;
 						}
-						const failed = isFailedResult(result);
-						// Model-level failures and dispatch crashes get their own dedicated
-						// dispatch-failure notification below, so finishRun's generic failure toast is
-						// silenced for them (computed before finishRun for that reason).
-						const modelLevel = failed && isModelLevelFailure(result);
-						const dispatchFailed = result.dispatchFailed === true;
-						finishRun(runId, failed ? "failed" : "done", modelLevel || dispatchFailed ? { silent: true } : undefined);
-						// Register before delivery so a concurrent subagent_wait resolves with
-						// the result even though the run row is already gone from the monitor.
-						runtime.registerRunResult(runId, result);
-						runtime.runControllers.delete(runId);
-						if (!runtime.sessionActive) return;
-						// Model-level failure: the configured model is unavailable or broke
-						// and the retry with the main-window model (when distinct) also
-						// failed. Instead of leaving a dead failure, hand the task to the
-						// main window — the main agent executes it itself with its own tools.
-						const completion: CompletionMessageItem = {
-							agent: result.agent,
-							block: modelLevel
-								? `${formatCompletionBlock(result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(result)}`
-								: formatCompletionBlock(result, config.maxResultLines, ctx.cwd),
-							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
-						};
-						if (modelLevel) {
-							ctx.ui.notify(`✗ ${result.agent} dispatch failed: model unavailable or broken — task handed to the main window`, "error");
-						} else if (dispatchFailed) {
-							// An exception inside the dispatch layer (spawn infra, temp-file/fs
-							// errors, ...): the main agent must know so it can re-dispatch.
-							ctx.ui.notify(`✗ ${result.agent} dispatch failed: ${result.errorMessage ?? "dispatch crashed"}`, "error");
-						}
-						if (failed) {
-							// Failures never wait and never hide behind a success turn: deliver
-							// first so the wake-up leads with the failure; held successes follow.
-							runtime.sendCompletionGroup([completion]);
-							runtime.completionBatcher.flush();
-						} else {
-							runtime.completionBatcher.push(completion);
+						// 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");
+							inspectState.trajectory.append({
+								kind: "settled",
+								status: failed ? "failed" : "done",
+								model: result.model,
+								isolation,
+								...(result.integrationStatus && result.integrationStatus !== "pending"
+									? { integrationStatus: result.integrationStatus }
+									: {}),
+							});
+							const terminalRun = monitor.findRun(runId);
+							inspectState.retainFrom(terminalRun
+								? { ...terminalRun, task: result.task, model: result.model ?? terminalRun.model, usage: result.usage }
+								: {
+									agent: pool.agent.name,
+									task: result.task,
+									model: result.model,
+									thinking: thinkingLevel,
+									status: failed ? "failed" : "done",
+									endedAt: inspectState.trajectory.summary().endedAt,
+									usage: result.usage,
+								});
+							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, runCtx.cwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
+									: formatCompletionBlock(result, runConfig.maxResultLines, runCtx.cwd),
+								triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
+							};
+							if (modelLevel) {
+								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: model unavailable or broken — 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/trajectory 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");
+						inspectState.trajectory.append({ kind: "settled", status: "stopped", model: monitor.findRun(runId)?.model, isolation });
+						const stoppedRun = monitor.findRun(runId);
+						if (stoppedRun) inspectState.retainFrom(stoppedRun);
+						if (!runtime.sessionActive) {
+							monitor.removeRun(runId);
+							return;
+						}
 						finishRun(runId, "failed");
 					},
-					(error) => {
-						// The task body converts sub-agent failures into delivered results; an
-						// exception escaping it (spawn infra, delivery API, ...) must not
-						// vanish: notify the user and deliver a failed result so the main
-						// agent knows the dispatch failed and can re-dispatch.
-						const crashed = dispatchFailedResult(agent, task, error, thinkingLevel);
-						finishRun(runId, "failed", { silent: true });
-						runtime.registerRunResult(runId, crashed);
-						runtime.runControllers.delete(runId);
-						if (!runtime.sessionActive) return;
+					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 {
-							ctx.ui.notify(`✗ ${agent.name} dispatch failed: ${crashed.errorMessage}`, "error");
-							runtime.sendCompletionGroup([
-								{
-									agent: agent.name,
-									block: formatCompletionBlock(crashed, config.maxResultLines, ctx.cwd),
-									triggerTurn: true,
-								},
-							]);
-							runtime.completionBatcher.flush();
-						} catch {
-							/* a second delivery failure must not throw through the queue */
+							const crashed: SingleResult = {
+								...dispatchFailedResult(pool.agent, control.getObjective(), error, thinkingLevel),
+								runId,
+								isolation,
+								originalCwd,
+								isolationCwd: executionCwd,
+								forkedFromRunId: thread.forkedFromRunId,
+							};
+							await thread.finalizeIsolation(generation, crashed);
+							if (!ownsSettlement()) return;
+							thread.state = "failed";
+							monitor.setStatus(runId, "failed");
+							inspectState.trajectory.append({
+								kind: "settled",
+								status: "failed",
+								model: crashed.model,
+								isolation,
+								...(crashed.integrationStatus && crashed.integrationStatus !== "pending"
+									? { integrationStatus: crashed.integrationStatus }
+									: {}),
+							});
+							const crashedRun = monitor.findRun(runId);
+							if (crashedRun) inspectState.retainFrom({ ...crashedRun, usage: crashed.usage });
+							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, runCtx.cwd),
+										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;
 			};
 
@@ -644,32 +1768,53 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					};
 				}
 
-				const results = params.tasks.map((task) => startBackground(task.agent, task.task, task.cwd, task.vision === true));
+				const results: SingleResult[] = [];
+				// Preserve caller order (and deterministic completion batching) while
+				// preparing each isolated filesystem before its queue entry can start.
+				for (const item of params.tasks) {
+					results.push(await startBackground(
+						item.agent,
+						item.task,
+						item.cwd,
+						item.vision === true,
+						defaultIsolationMode("parallel", item.agent, item.isolation as IsolationMode | undefined),
+					));
+				}
 				const started = results.filter((result) => result.exitCode === -1).length;
-				const failures = results.filter((result) => result.exitCode !== -1);
+				const failureLines = results.flatMap((result, index) => {
+					if (result.exitCode === -1) return [];
+					const reason = getResultOutput(result).trim() || "unknown startup failure";
+					return [
+						`- tasks[${index}] (${params.tasks![index]!.agent}) failed to start: ${reason.replace(/\n/g, "\n  ")}`,
+					];
+				});
+				if (started === 0) {
+					// Pi marks custom-tool failures only when execute throws; returning an
+					// `isError` property is still a successful AgentToolResult.
+					throw new Error(`No background subagents were started.\n${failureLines.join("\n")}`);
+				}
+				const text = [
+					`Started ${started} background subagent${started === 1 ? "" : "s"}. Results will automatically resume the main agent when ready.`,
+					...(failureLines.length > 0
+						? [`${failureLines.length} task${failureLines.length === 1 ? "" : "s"} failed before launch:`, ...failureLines]
+						: []),
+				].join("\n");
 				return {
-					content: [
-						{
-							type: "text",
-							text:
-								started > 0
-									? `Started ${started} background subagent${started === 1 ? "" : "s"}. Results will automatically resume the main agent when ready.`
-									: failures.map((result) => getResultOutput(result)).join("\n"),
-						},
-					],
+					content: [{ type: "text", text }],
 					details: makeDetails("parallel", true)(results),
-					isError: failures.length > 0,
 					terminate: true,
 				};
 			}
 
-			const result = startBackground(params.agent as string, params.task as string, params.cwd, params.vision === true);
+			const result = await startBackground(
+				params.agent as string,
+				params.task as string,
+				params.cwd,
+				params.vision === true,
+				defaultIsolationMode("single", params.agent as string, params.isolation as IsolationMode | undefined),
+			);
 			if (result.exitCode !== -1) {
-				return {
-					content: [{ type: "text", text: getResultOutput(result) }],
-					details: makeDetails("single")([result]),
-					isError: true,
-				};
+				throw new Error(getResultOutput(result));
 			}
 			return {
 				content: [{ type: "text", text: `Started ${result.agent} in the background. Its result will automatically resume the main agent when ready.` }],
@@ -684,15 +1829,17 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				let text = `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${args.tasks.length})`)}`;
 				for (const t of args.tasks.slice(0, 4)) {
 					const preview = formatTaskSummary(t.task, 48);
-					text += `\n  ${theme.fg("accent", t.agent)} ${theme.fg("dim", preview)}`;
+					const isolation = defaultIsolationMode("parallel", t.agent, t.isolation) === "worktree" ? " [worktree]" : "";
+					text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", isolation)} ${theme.fg("dim", preview)}`;
 				}
 				if (args.tasks.length > 4) text += `\n  ${theme.fg("dim", `… +${args.tasks.length - 4} more`)}`;
 				return new Text(text, 0, 0);
 			}
 			const task: string = args.task ?? "";
 			const preview = formatTaskSummary(task, 60);
+			const isolation = args.isolation === "worktree" ? " [worktree]" : "";
 			return new Text(
-				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "?")} ${theme.fg("dim", preview)}`,
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "?")}${theme.fg("dim", isolation)} ${theme.fg("dim", preview)}`,
 				0,
 				0,
 			);
@@ -707,8 +1854,9 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const pending = r.exitCode === -1;
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
-				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (fell back from ${r.modelFallbackFrom})` : ""}`;
-				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (pool fallback from ${r.modelFallbackFrom})` : ""}`;
+				const isolation = r.isolation === "worktree" ? ` · worktree ${r.integrationStatus ?? "active"}` : "";
+				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${isolation}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
 				return new Text(line, 0, 0);
 			}
 
@@ -720,8 +1868,9 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const pending = r.exitCode === -1;
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
-				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (fell back from ${r.modelFallbackFrom})` : ""}`;
-				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (pool fallback from ${r.modelFallbackFrom})` : ""}`;
+				const isolation = r.isolation === "worktree" ? ` · worktree ${r.integrationStatus ?? "active"}` : "";
+				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${isolation}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
 			}
 			return new Text(lines.join("\n"), 0, 0);
 		},