@ferris1225/pi-subagents 4.1.8 → 4.1.9

package/src/tools.ts

@@ -1,6 +1,6 @@
 /**
  * Thread controls and lookup tools around the subagent runtime:
- * subagent_control (steer/retarget/park/resume/fork), subagent_wait (in-turn
+ * subagent_control (resume), subagent_wait (in-turn
  * result lookup), subagent_status, and destructive subagent_stop.
  */
 
@@ -10,6 +10,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { existsSync } from "node:fs";
 import { Type } from "typebox";
 import { DEFAULT_MAX_RESULT_LINES, loadConfig } from "./config.ts";
+import { removeThreadRecord } from "./durable.ts";
 import { formatCompletionBlock, formatUsage, matchRunIds } from "./format.ts";
 import { emptyUsage } from "./rpc-run.ts";
 import {
@@ -46,15 +47,12 @@ function renderFirstLine(result: { content?: unknown }, label: string, theme: an
 
 export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	const SubagentControlParams = Type.Object({
-		action: StringEnum(["steer", "retarget", "park", "resume", "fork"] as const, {
+		action: StringEnum(["resume"] as const, {
 			description: "Control operation for the logical sub-agent thread.",
 		}),
 		id: Type.Integer({ minimum: 1, description: "Stable run id shown by subagent dispatch/status output." }),
-		instruction: Type.Optional(
-			Type.String({ description: "Instruction queued by steer after the current child tool batch." }),
-		),
 		objective: Type.Optional(
-			Type.String({ description: "Replacement objective for retarget; optional appended objective for resume/fork. Omit on resume/fork to continue the current retained objective." }),
+			Type.String({ description: "Optional appended objective for resume. Omit to continue the current retained objective." }),
 		),
 	});
 
@@ -62,21 +60,14 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 		name: "subagent_control",
 		label: "Subagent Control",
 		description: [
-			"Control an existing sub-agent thread by stable run id.",
-			"steer queues an instruction after the current tool batch while the top-level RPC child is active.",
-			"retarget replaces the objective in that same active top-level child.",
-			"Managed downstream documenter/reviewer/fix stages are controlled by the parent queue rather than its settled RPC control: use park or stop there, then resume with an objective to redirect retained context.",
-			"park aborts to a stable checkpoint, terminates the child, preserves context, and releases its concurrency slot.",
+			"Resume an existing sub-agent thread by stable run id.",
 			"resume restarts a parked, completed, or failed retained thread with the same run id and cumulative active time; omit objective to continue the current goal, or provide one to append it to retained context and make it the displayed current goal.",
-			"fork copies a parked/completed/failed retained session branch into a new logical thread and run id; an isolated checkpoint must be settled and integrated first; omit objective to continue the current goal, or provide one to append a new branch goal.",
+			"Threads parked or interrupted by a shutdown/reload are restorable; use subagent_stop for destructive cancellation.",
 		].join(" "),
-		promptSnippet: "Control a subagent thread: steer/retarget an active top-level child; park/stop a managed downstream stage; resume or fork retained context.",
+		promptSnippet: "Resume a parked or settled subagent thread with its retained context.",
 		promptGuidelines: [
-			"Use subagent_control steer to refine an active top-level RPC child without restarting it; the instruction is delivered after its current tool batch.",
-			"Use subagent_control retarget only while that top-level child is active. During a managed downstream stage, park it and resume with a replacement objective instead.",
-			"Use subagent_control park to checkpoint useful context while releasing the process/concurrency slot, and resume to continue the same run id later. Resume without objective keeps the current goal; resume with objective appends that goal to retained context.",
-			"Use subagent_control fork only on a parked or settled retained thread; isolated work must settle and integrate before it can fork. Fork creates a new run id while leaving the source untouched.",
-			"Use subagent_stop only for destructive cancellation; it retires that thread's retained session without retiring independent forks.",
+			"Use subagent_control resume to continue a parked/settled thread on the same run id. Resume without objective keeps the current goal; resume with objective appends that goal to retained context.",
+			"Use subagent_stop only for destructive cancellation; it retires that thread's retained session.",
 		],
 		parameters: SubagentControlParams,
 
@@ -92,54 +83,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 
 			try {
 				switch (params.action) {
-					case "steer": {
-						const instruction = nonBlank(params.instruction);
-						if (!instruction) {
-							return { content: [{ type: "text", text: "steer requires a non-blank instruction." }], details: {} };
-						}
-						if (!(["running", "steering"] as const).includes(thread.control.getPhase() as any)) {
-							return { content: [{ type: "text", text: `Run #${thread.id} is ${thread.control.getPhase()}; only a running thread can be steered.` }], details: {} };
-						}
-						await thread.control.steer(instruction);
-						return { content: [{ type: "text", text: `Queued steering instruction for run #${thread.id} after its current tool batch.` }], details: {} };
-					}
-					case "retarget": {
-						const objective = nonBlank(params.objective);
-						if (!objective) {
-							return { content: [{ type: "text", text: "retarget requires a non-blank objective." }], details: {} };
-						}
-						const phase = thread.control.getPhase();
-						if (thread.state === "queued" && phase === "queued") {
-							thread.task = objective;
-							thread.control.retargetPending(objective);
-							monitor.setTask(thread.id, objective);
-							monitor.setContinuationKind(thread.id, "retarget");
-							return { content: [{ type: "text", text: `Updated queued run #${thread.id} to the replacement objective; no child was spawned by this control action.` }], details: {} };
-						}
-						if (!(["starting", "running", "steering", "interrupting", "retrying"] as const).includes(phase as any)) {
-							return { content: [{ type: "text", text: `Run #${thread.id} is ${thread.state}; use resume with objective to restart retained context.` }], details: {} };
-						}
-						thread.task = objective;
-						monitor.setTask(thread.id, objective);
-						monitor.setContinuationKind(thread.id, "retarget");
-						await thread.control.retarget(objective);
-						return { content: [{ type: "text", text: `Retargeted run #${thread.id} in the same session; the aborted objective will not be delivered as a completion.` }], details: {} };
-					}
-					case "park": {
-						if (thread.state === "parked") {
-							return { content: [{ type: "text", text: `Run #${thread.id} is already parked.` }], details: {} };
-						}
-						const disposition = await thread.park();
-						return disposition === "queued"
-							? {
-								content: [{ type: "text", text: `Parked queued run #${thread.id}; it never spawned a child or empty session.` }],
-								details: {},
-							}
-							: {
-								content: [{ type: "text", text: `Parked run #${thread.id} at a stable checkpoint; its session is retained and concurrency slot released.` }],
-								details: {},
-							};
-					}
 					case "resume": {
 						if (thread.retired) {
 							return { content: [{ type: "text", text: `Run #${thread.id} was retired by subagent_stop and has no resumable session.` }], details: {} };
@@ -165,24 +108,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 							: "no prior child session existed, so only the logical run and objective are continued";
 						return { content: [{ type: "text", text: `Resumed run #${thread.id}, ${mode}; ${context}, and cumulative active time is preserved. Completion will arrive automatically.` }], details: {}, terminate: true };
 					}
-					case "fork": {
-						const objective = params.objective === undefined ? undefined : nonBlank(params.objective);
-						if (params.objective !== undefined && !objective) {
-							return { content: [{ type: "text", text: "fork objective must be non-blank when provided." }], details: {} };
-						}
-						const pending = await thread.fork(objective, ctx);
-						if (pending.exitCode !== -1 || pending.runId === undefined) {
-							return { content: [{ type: "text", text: getResultOutput(pending) }], details: {} };
-						}
-						return {
-							content: [{
-								type: "text",
-								text: `Forked run #${thread.id} into new run #${pending.runId}; ${objective ? `appended branch objective: ${formatTaskSummary(objective, 80, false)}` : `continuing current objective: ${formatTaskSummary(thread.task, 80, false)}`}. Retained context is copied, the source is unchanged, and child completion will arrive automatically.`,
-							}],
-							details: { sourceRunId: thread.id, childRunId: pending.runId, result: pending },
-							terminate: true,
-						};
-					}
 				}
 			} catch (error) {
 				throw new Error(`Could not ${params.action} run #${thread.id}: ${error instanceof Error ? error.message : String(error)}`);
@@ -431,8 +356,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 						: undefined;
 					const metadata = [
 						activeThread?.isolation === "worktree" ? `worktree ${active.integrationStatus ?? activeThread.worktree?.state ?? "active"}` : undefined,
-						activeThread?.forkedFromRunId !== undefined ? `forked from #${activeThread.forkedFromRunId}` : undefined,
-						(activeThread?.forkChildRunIds.length ?? 0) > 0 ? `forks ${activeThread!.forkChildRunIds.map((id) => `#${id}`).join(",")}` : undefined,
 					].filter(Boolean).join(" · ");
 					const stageStatus = activeChild
 						? monitor.summarize(activeChild)
@@ -444,8 +367,8 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 								text: parked
 									? `Run #${active.id} ${owner} is parked with retained${retainedStage ? ` ${retainedStage} stage` : ""} context${metadata ? ` (${metadata})` : ""}. Use subagent_control resume to restart it, or subagent_stop to retire it.`
 									: managedDownstream
-										? `Run #${active.id} ${owner} is in a managed downstream stage (${stageStatus}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait for its result, subagent_control park to checkpoint it, or subagent_stop to cancel it. Steer/retarget are unavailable until you park and resume the retained stage.`
-										: `Run #${active.id} ${owner} is still active (${active.activity ?? statusLabel(active.status)}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait to block for its result, subagent_control to steer/park it, or subagent_stop to cancel it.`,
+										? `Run #${active.id} ${owner} is in a managed downstream stage (${stageStatus}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait for its result or subagent_stop to cancel it.`
+										: `Run #${active.id} ${owner} is still active (${active.activity ?? statusLabel(active.status)}${metadata ? ` · ${metadata}` : ""}). Use subagent_wait to block for its result or subagent_stop to cancel it.`,
 							},
 						],
 						details: {},
@@ -462,8 +385,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				const parts = [
 					`#${run.id} ${monitor.summarize(run)}`,
 					run.label,
-					thread?.forkedFromRunId !== undefined ? `forked from #${thread.forkedFromRunId}` : undefined,
-					(thread?.forkChildRunIds.length ?? 0) > 0 ? `forks ${thread!.forkChildRunIds.map((id) => `#${id}`).join(",")}` : undefined,
 					run.activity ?? statusLabel(run.status),
 				].filter(Boolean);
 				return `- ${parts.join(" · ")}`;
@@ -475,13 +396,8 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				const retainedStage = run?.managedWorkflow && thread.agentName !== run.agent
 					? ` · retained stage ${thread.agentName}`
 					: "";
-				const relations = [
-					thread.forkedFromRunId !== undefined ? `forked from #${thread.forkedFromRunId}` : undefined,
-					thread.forkChildRunIds.length > 0 ? `forks ${thread.forkChildRunIds.map((id) => `#${id}`).join(",")}` : undefined,
-				].filter(Boolean);
-				const relation = relations.length > 0 ? ` · ${relations.join(" · ")}` : "";
 				const isolation = thread.isolation === "worktree" ? ` · worktree ${thread.worktree?.state ?? "active"}` : "";
-				return `- #${thread.id} ${owner} · ${run?.label ?? runLabel(thread.task)} · parked${thread.sessionDir ? " · context retained" : " · not started"}${retainedStage}${isolation}${relation}`;
+				return `- #${thread.id} ${owner} · ${run?.label ?? runLabel(thread.task)} · parked${thread.sessionDir ? " · context retained" : " · not started"}${retainedStage}${isolation}`;
 			});
 			const completed = [...runtime.settledRuns.entries()].slice(-5);
 			const completedLines = completed.map(([id, result]) => {
@@ -491,12 +407,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					? `${result.model ?? "?"} (main after ${result.modelFallbackFrom} failed)`
 					: (result.model ?? "?");
 				const isolation = result.isolation === "worktree" ? ` · worktree ${result.integrationStatus ?? "unknown"}` : "";
-				const relations = [
-					result.forkedFromRunId !== undefined ? `forked from #${result.forkedFromRunId}` : undefined,
-					(result.forkChildRunIds?.length ?? 0) > 0 ? `forks ${result.forkChildRunIds!.map((childId) => `#${childId}`).join(",")}` : undefined,
-				].filter(Boolean);
-				const relation = relations.length > 0 ? ` · ${relations.join(" · ")}` : "";
-				return `- #${id} ${result.agent}${label ? ` · ${label}` : ""} · ${isFailedResult(result) ? "failed" : "completed"} · ${model}${isolation}${relation}${usage ? ` · ${usage}` : ""}`;
+				return `- #${id} ${result.agent}${label ? ` · ${label}` : ""} · ${isFailedResult(result) ? "failed" : "completed"} · ${model}${isolation}${usage ? ` · ${usage}` : ""}`;
 			});
 
 			const sections: string[] = [];
@@ -506,7 +417,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 			sections.push(parkedLines.length > 0 ? parkedLines.join("\n") : "(none)");
 			sections.push(`### Finished this session (${runtime.settledRuns.size})`);
 			sections.push(completedLines.length > 0 ? completedLines.join("\n") : "(none)");
-			sections.push("Pass a run id to subagent_status for the full result, use subagent_control to steer/park/resume/fork, or subagent_wait for active work.");
+			sections.push("Pass a run id to subagent_status for the full result, use subagent_control to resume a settled thread, or subagent_wait for active work.");
 			return { content: [{ type: "text", text: sections.join("\n\n") }], details: {} };
 		},
 
@@ -551,7 +462,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			// Start config I/O without yielding: every target below must be claimed
-			// synchronously before a resume/fork preflight can cross its next await.
+			// synchronously before a resume preflight can cross its next await.
 			const configPromise = loadConfig(runtime.configPath).catch(() => undefined);
 			const completionResults: SingleResult[] = [];
 			const candidateIds = params.all === true
@@ -560,7 +471,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					...[...runtime.threads.values()]
 						.filter((thread) =>
 							thread.lifecycleOperation !== undefined ||
-							["queued", "resuming", "running", "steering", "interrupting"].includes(thread.state),
+							["queued", "resuming", "running", "interrupting"].includes(thread.state),
 						)
 						.map((thread) => thread.id),
 				])]
@@ -607,10 +518,10 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				const wasResuming = previousState === "resuming";
 				const wasActive =
 					thread.lifecycleOperation !== undefined ||
-					["queued", "resuming", "running", "steering", "interrupting"].includes(previousState);
+					["queued", "resuming", "running", "interrupting"].includes(previousState);
 				const stopVersion = ++thread.lifecycleVersion;
 				// Stop-all claims every target before the first await. This invalidates
-				// all concurrent resume/fork preflights as one synchronous operation.
+				// all concurrent resume preflights as one synchronous operation.
 				thread.lifecycleOperation = "stop";
 				thread.retired = true;
 				thread.retireOnSettle = true;
@@ -692,7 +603,6 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					stoppedResult = prior
 						? {
 							...prior,
-							parked: undefined,
 							exitCode: 1,
 							stopReason: "aborted",
 							errorMessage: stopMessage,
@@ -756,6 +666,9 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				if (stoppedResult) completionResults.push(stoppedResult);
 				monitor.removeRun(runId);
 				runtime.retireThreadSession(thread);
+				// The destructive retire removes the durable record with the session;
+				// an id never resurrects after subagent_stop.
+				await removeThreadRecord(runtime.configPath, runId).catch(() => undefined);
 				if (thread.lifecycleVersion === stopVersion && thread.lifecycleOperation === "stop") {
 					thread.lifecycleOperation = undefined;
 				}

package/src/widget.ts

@@ -98,7 +98,7 @@ function runPrimaryLine(
 	// A chain child shows its role in the chain plus a task-derived label; the
 	// templated fix brief itself would only repeat the parent review's content.
 	const continuation = run.parentRunId === undefined
-		? continuationLabel(run.continuationKind, run.forkedFromRunId)
+		? continuationLabel(run.continuationKind)
 		: undefined;
 	const taskSource = run.parentRunId !== undefined
 		? [run.relationLabel, run.label].filter((part): part is string => Boolean(part)).join(" · ")
@@ -215,8 +215,8 @@ function runActivityLine(run: RunView, theme: Theme, width: number, indent: stri
 
 /** Render active runs as compact workflow-aware trees. Stable managed parents
  * retain their stage timeline while the current internal child supplies exact
- * model/thinking/activity telemetry. Fork labels include their source id; other
- * control ids remain available through status. */
+ * model/thinking/activity telemetry. Control ids remain available through
+ * status. */
 export function formatActiveRunLines(
 	runs: readonly RunView[],
 	theme: Theme,

package/src/worktree.ts

@@ -2,7 +2,7 @@
  * Detached Git worktree isolation for write-capable sub-agents.
  *
  * A handle is created before a child is queued and stays owned by the logical
- * thread across retries, model candidates, retargets, and park/resume. Finalize
+ * thread across retries, model candidates, and resumes. Finalize
  * is idempotent: it records a binary patch, applies it to the original working
  * tree without touching its index, then removes/prunes the temporary worktree.
  * Failed integration deliberately retains both the worktree and patch.
@@ -19,7 +19,7 @@ export type IsolationMode = "shared" | "worktree";
 const WORKTREE_TEMP_DIR_PREFIX = "pi-subagent-worktree-";
 
 /** Short stable identity of one isolated worktree group (the mkdtemp suffix).
- * Continuation/fork generations create a fresh worktree, so the identity
+ * Continuation generations create a fresh worktree, so the identity
  * visibly changes when the group's filesystem boundary changes. */
 export function worktreeGroupId(worktree: Pick<WorktreeIsolation, "tempDir">): string {
 	const base = worktree.tempDir.split(/[\\/]/).filter(Boolean).pop() ?? worktree.tempDir;
@@ -213,6 +213,28 @@ export interface WorktreeCheckpoint {
 	patch: Buffer;
 }
 
+export interface WorktreeCheckpointRef {
+	baseHead: string;
+	commit: string;
+}
+
+/** Persistable projection of one worktree handle: enough to rebuild the
+ * handle after a reload or restart. Patch bytes are deliberately omitted —
+ * only the checkpoint commit, which lives in the shared repository object
+ * store, is needed to seed a continuation. */
+export interface WorktreeSnapshot {
+	originalCwd: string;
+	originalRoot: string;
+	cwd: string;
+	worktreePath: string;
+	tempDir: string;
+	patchPath: string;
+	head: string;
+	integrationBaseHead: string;
+	state: "active" | "retained" | "integrated" | "no_changes";
+	checkpoint?: WorktreeCheckpointRef;
+}
+
 export interface WorktreeCreateOptions {
 	runner?: CommandRunner;
 	/** Test hook; production uses the OS temp directory. */
@@ -244,7 +266,12 @@ export interface WorktreeIsolation {
 	readonly tempDir: string;
 	readonly patchPath: string;
 	readonly head: string;
+	/** Diff base for final integration; a continuation baseline commit when
+	 * the generation was seeded with already-integrated work. */
+	readonly integrationBaseHead: string;
 	readonly state: "active" | "finalizing" | WorktreeFinalizationStatus;
+	/** Checkpoint retained after finalization for continuation resumes. */
+	getContinuationCheckpoint(): WorktreeCheckpoint | undefined;
 	/** Capture the complete isolated filesystem state for a fresh continuation.
 	 * The synthetic commit lets Git merge an already-committed seed without
 	 * attempting to apply the same patch twice. */
@@ -410,13 +437,26 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 		private readonly runner: CommandRunner,
 		/** May be a synthetic tree commit representing a seed that the parent
 		 * checkout already contains. Finalization then integrates only new edits. */
-		private readonly integrationBaseHead: string = head,
-	) {}
+		readonly integrationBaseHead: string = head,
+		restored?: {
+			state: WorktreeIsolation["state"];
+			checkpoint?: WorktreeCheckpoint;
+		},
+	) {
+		if (restored) {
+			this.currentState = restored.state;
+			if (restored.checkpoint) this.continuationCheckpoint = cloneCheckpoint(restored.checkpoint);
+		}
+	}
 
 	get state(): WorktreeIsolation["state"] {
 		return this.currentState;
 	}
 
+	getContinuationCheckpoint(): WorktreeCheckpoint | undefined {
+		return this.continuationCheckpoint ? cloneCheckpoint(this.continuationCheckpoint) : undefined;
+	}
+
 	async snapshotCheckpoint(): Promise<WorktreeCheckpoint> {
 		if (this.continuationCheckpoint) return cloneCheckpoint(this.continuationCheckpoint);
 		if (this.currentState === "no_changes") {
@@ -720,3 +760,103 @@ export async function createWorktreeIsolation(
 		);
 	}
 }
+
+/** Snapshot only states whose filesystem or repository objects still exist.
+ * Transient (`finalizing`) and discarded handles are not persistable. */
+export function worktreeSnapshot(worktree: WorktreeIsolation): WorktreeSnapshot | undefined {
+	const state = worktree.state;
+	if (state !== "active" && state !== "retained" && state !== "integrated" && state !== "no_changes") {
+		return undefined;
+	}
+	const checkpoint = worktree.getContinuationCheckpoint();
+	return {
+		originalCwd: worktree.originalCwd,
+		originalRoot: worktree.originalRoot,
+		cwd: worktree.cwd,
+		worktreePath: worktree.worktreePath,
+		tempDir: worktree.tempDir,
+		patchPath: worktree.patchPath,
+		head: worktree.head,
+		integrationBaseHead: worktree.integrationBaseHead,
+		state,
+		...(checkpoint && checkpoint.patch.length > 0
+			? { checkpoint: { baseHead: checkpoint.baseHead, commit: checkpoint.commit } }
+			: {}),
+	};
+}
+
+/** Validate an untrusted persisted snapshot; null when it is unusable. */
+export function normalizeWorktreeSnapshot(value: unknown): WorktreeSnapshot | null {
+	if (!value || typeof value !== "object") return null;
+	const raw = value as Record<string, unknown>;
+	const fields: Record<string, string> = {};
+	for (const key of [
+		"originalCwd",
+		"originalRoot",
+		"cwd",
+		"worktreePath",
+		"tempDir",
+		"patchPath",
+		"head",
+		"integrationBaseHead",
+	] as const) {
+		if (typeof raw[key] !== "string" || !raw[key]) return null;
+		fields[key] = raw[key] as string;
+	}
+	if (raw.state !== "active" && raw.state !== "retained" && raw.state !== "integrated" && raw.state !== "no_changes") {
+		return null;
+	}
+	let checkpoint: WorktreeCheckpointRef | undefined;
+	if (raw.checkpoint && typeof raw.checkpoint === "object") {
+		const rawCheckpoint = raw.checkpoint as Record<string, unknown>;
+		if (typeof rawCheckpoint.baseHead !== "string" || !rawCheckpoint.baseHead) return null;
+		if (typeof rawCheckpoint.commit !== "string" || !rawCheckpoint.commit) return null;
+		checkpoint = { baseHead: rawCheckpoint.baseHead, commit: rawCheckpoint.commit };
+	}
+	return {
+		originalCwd: fields.originalCwd!,
+		originalRoot: fields.originalRoot!,
+		cwd: fields.cwd!,
+		worktreePath: fields.worktreePath!,
+		tempDir: fields.tempDir!,
+		patchPath: fields.patchPath!,
+		head: fields.head!,
+		integrationBaseHead: fields.integrationBaseHead!,
+		state: raw.state,
+		...(checkpoint ? { checkpoint } : {}),
+	};
+}
+
+/** Rebuild a handle from a persisted snapshot. Returns undefined when the
+ * on-disk worktree that an active/retained snapshot promises is gone; settled
+ * states (integrated/no_changes) intentionally need no filesystem. The
+ * restored checkpoint carries no patch bytes — only its commit is consumed by
+ * continuation seeds. */
+export async function restoreWorktreeIsolation(
+	snapshot: WorktreeSnapshot,
+	options: { runner?: CommandRunner } = {},
+): Promise<WorktreeIsolation | undefined> {
+	if (
+		(snapshot.state === "active" || snapshot.state === "retained") &&
+		!existsSync(snapshot.worktreePath)
+	) {
+		return undefined;
+	}
+	return new GitWorktreeIsolation(
+		snapshot.originalCwd,
+		snapshot.originalRoot,
+		snapshot.cwd,
+		snapshot.worktreePath,
+		snapshot.tempDir,
+		snapshot.patchPath,
+		snapshot.head,
+		options.runner ?? runCommand,
+		snapshot.integrationBaseHead,
+		{
+			state: snapshot.state,
+			...(snapshot.checkpoint
+				? { checkpoint: { ...snapshot.checkpoint, patch: Buffer.alloc(0) } }
+				: {}),
+		},
+	);
+}