@ferris1225/pi-subagents 4.3.9 → 4.3.11

package/src/execution/rpc-run.ts

@@ -3,8 +3,8 @@
  *
  * A child stays alive across prompt/abort operations and speaks
  * strict LF-delimited JSONL. The process is terminated only after the logical
- * run settles, is parked/stopped, or fails. Session files remain owned by the
- * parent runtime so a later generation can resume the same thread.
+ * run settles, is stopped, or fails. Session files remain owned by the parent
+ * runtime for in-run model fallback and manual recovery.
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
@@ -13,6 +13,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import type { Message } from "@earendil-works/pi-ai";
+import type { RpcCommand, RpcExtensionUIResponse, RpcResponse } from "@earendil-works/pi-coding-agent";
 import { SUBAGENT_TOOL_NAMES, type AgentConfig } from "../delegation/agents.ts";
 import type { ThinkingLevel } from "../configuration/config.ts";
 import { writeTempOwnerMarker } from "../isolation/temp-hygiene.ts";
@@ -36,8 +37,6 @@ export const RPC_COMMAND_TIMEOUT_MS = 30_000;
 /** clear_queue is stop-path hygiene ahead of the abort: give it its own short
  * budget so a hung response cannot eat into the abort-settle window. */
 const RPC_CLEAR_QUEUE_TIMEOUT_MS = 2_000;
-/** Keep logical stop responsive when a steering ACK is lost. */
-const RPC_STEER_ACK_TIMEOUT_MS = 2_000;
 /** Time allowed for the child to boot and answer get_state. */
 export const RPC_READY_TIMEOUT_MS = 60_000;
 export const RPC_ABORT_SETTLE_TIMEOUT_MS = 5_000;
@@ -197,15 +196,6 @@ async function writePromptToTempFile(
 	}
 }
 
-interface RpcResponse {
-	id?: string;
-	type: "response";
-	command: string;
-	success: boolean;
-	error?: string;
-	data?: unknown;
-}
-
 interface RpcSessionUsage {
 	input: number;
 	output: number;
@@ -435,7 +425,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	const readyTimeoutMs = options.rpcReadyTimeoutMs ?? RPC_READY_TIMEOUT_MS;
 	const commandTimeoutMs = options.rpcCommandTimeoutMs ?? RPC_COMMAND_TIMEOUT_MS;
 
-	const writeLine = (value: object): Promise<void> =>
+	const writeLine = (value: RpcCommand | RpcExtensionUIResponse): Promise<void> =>
 		new Promise((resolve, reject) => {
 			if (!proc.stdin || proc.stdin.destroyed || !proc.stdin.writable) {
 				reject(new Error("Subagent RPC stdin is not writable."));
@@ -449,7 +439,10 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			});
 		});
 
-	const send = async <T extends { type: string }>(command: T, timeoutMs = commandTimeoutMs): Promise<RpcResponse> => {
+	const send = async <T extends RpcCommand>(
+		command: T,
+		timeoutMs = commandTimeoutMs,
+	): Promise<Extract<RpcResponse, { command: T["type"]; success: true }>> => {
 		if (finished || closed) throw new Error("Subagent RPC process is no longer active.");
 		const id = `req_${++requestId}`;
 		const payload = { ...command, id };
@@ -471,7 +464,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			if (!response.success) {
 				throw new RpcCommandRejectedError(response.error || `RPC ${response.command} failed.`);
 			}
-			return response;
+			return response as Extract<RpcResponse, { command: T["type"]; success: true }>;
 		});
 	};
 
@@ -501,9 +494,8 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	const abortAcceptedPrompt = async (): Promise<boolean> => {
 		const acceptance = await initialPrompt.promise;
 		if (!acceptance.accepted) return false;
-		// Pi continues queued steering/follow-up messages after an abort. Drop
-		// them first so a stopped run — or a later resume of its retained
-		// thread — cannot be revived by stale queue entries. Best-effort: an
+		// Pi continues queued messages after an abort. Drop them first so stale
+		// queue entries cannot revive a stopped run. Best-effort: an
 		// older child rejects the command and a hung child falls through to
 		// the bounded abort below.
 		try {
@@ -529,9 +521,6 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	};
 
 	const attemptControl: AttemptControl = {
-		async steer(command): Promise<void> {
-			await send(command, RPC_STEER_ACK_TIMEOUT_MS);
-		},
 		async stop(reason = "Subagent was aborted"): Promise<void> {
 			if (finished) {
 				if (!closed) await processClosed.promise;
@@ -693,8 +682,8 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 					result.usage.contextTokens = usage.totalTokens || 0;
 				}
 				if (!result.model && (message as any).model) result.model = (message as any).model;
-				if ((message as any).stopReason) result.stopReason = (message as any).stopReason;
-				if ((message as any).errorMessage) result.errorMessage = (message as any).errorMessage;
+				result.stopReason = message.stopReason;
+				result.errorMessage = message.errorMessage;
 			}
 			emit({ kind: "usage", usage: { ...result.usage }, model: result.model });
 		}
@@ -747,25 +736,35 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 		finish();
 	});
 
-	proc.once("close", (code) => {
+	proc.once("close", (code, exitSignal) => {
 		closed = true;
-		resolveInitialPrompt(false, new Error(`Subagent RPC process exited before the initial prompt was accepted (code=${code ?? "signal"}).`));
+		const disposition = exitSignal ? `signal=${exitSignal}` : `code=${code}`;
+		resolveInitialPrompt(false, new Error(`Subagent RPC process exited before the initial prompt was accepted (${disposition}).`));
 		if (forceKillTimer) clearTimeout(forceKillTimer);
 		stdoutBuffer += stdoutDecoder.end();
 		result.stderr += stderrDecoder.end();
 		if (stdoutBuffer.length > 0) processLine(stdoutBuffer);
 		const exitError = new Error(
-			`Subagent RPC process exited before settling (code=${code ?? "signal"}).${result.stderr ? ` ${result.stderr.trim()}` : ""}`,
+			`Subagent RPC process exited before settling (${disposition}).${result.stderr ? ` ${result.stderr.trim()}` : ""}`,
 		);
 		rejectPending(exitError);
 		if (abortSettlement) {
 			abortSettlement.reject(exitError);
 			abortSettlement = undefined;
 		}
-		if (!finished) {
+		if (!finished && !usageSettlementStarted) {
+			const silentStartupExit = !result.rpcPromptDispatched && !result.rpcActivity
+				&& result.messages.length === 0 && !result.stderr.trim() && !result.errorMessage?.trim();
 			result.exitCode = code === 0 ? 1 : (code ?? 1);
-			result.stopReason ??= signal?.aborted ? "aborted" : "error";
-			if (signal?.aborted) result.errorMessage ??= "Subagent was aborted";
+			result.stopReason = signal?.aborted ? "aborted" : "error";
+			if (signal?.aborted) {
+				result.errorMessage ||= "Subagent was aborted";
+			} else {
+				result.errorMessage = result.errorMessage?.trim()
+					? `${result.errorMessage}\n${exitError.message}` : exitError.message;
+				if (silentStartupExit) result.rpcStartupFailed = true;
+				else result.dispatchFailed = true;
+			}
 			finish();
 		}
 		processClosed.resolve();

package/src/execution/spawn.ts

@@ -290,7 +290,7 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 }
 
 export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
-	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or dispatch fewer sub-agents at once.`;
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. Main handles this phase; inspect launch diagnostics instead of redispatching it.`;
 }
 
 export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
@@ -334,20 +334,26 @@ async function waitForControlledRetry(
 	return !signal?.aborted && !control?.isStopRequested();
 }
 
+/** Runtime/assistant diagnostics, never an inference from individual failed tools. */
+export function getResultError(result: SingleResult): string | undefined {
+	if (result.exitCode === -1 || !isFailedResult(result)) return undefined;
+	return result.errorMessage?.trim()
+		|| lastAssistantMessage(result.messages)?.errorMessage?.trim()
+		|| result.stderr.trim()
+		|| (result.stopReason === "aborted"
+			? "Subagent was aborted."
+			: `Subagent failed (exit code ${result.exitCode}${result.stopReason ? `, stop reason ${result.stopReason}` : ""}); no failure reason was recorded.`);
+}
+
 export function getResultOutput(result: SingleResult): string {
-	if (isFailedResult(result)) {
-		const error = result.errorMessage || result.stderr;
-		const partial = getFinalOutput(result.messages);
-		if (error && partial) return `${error}\n\n--- Partial output ---\n${partial}`;
-		return error || partial || "(no output)";
-	}
-	return getFinalOutput(result.messages) || "(no output)";
+	const error = getResultError(result);
+	const output = getFinalOutput(result.messages);
+	if (error && output) return `${error}\n\n--- Partial output ---\n${output}`;
+	return error || output || "(no output)";
 }
 
-/** Continuation rules shared by every resume flavor. The workspace clause is
- * what keeps a retained context from becoming a liability: a parked or settled
- * thread may return after main integrated sibling worktrees or edited the tree
- * itself, so a file read in an earlier generation is not proof of its content. */
+/** Model handoff preserves useful history, but main or siblings may have edited
+ * the workspace since the selected model last read it. */
 const RESUME_CONTINUATION_RULES =
 	"Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Do not redo searches, reads, or edits that already succeeded. The workspace may have changed while this thread was inactive: before editing a file, re-read it unless you read it during this continuation. Finish with the result-only handoff your role requires.";
 
@@ -355,12 +361,6 @@ export function buildResumePrompt(task: string, reason: string): string {
 	return `You are resuming an earlier sub-agent session after ${reason}. ${RESUME_CONTINUATION_RULES} Current objective: ${task}. Pick up exactly where you left off and finish it. Continue now.`;
 }
 
-/** A resume with an appended objective continues the same thread: the new
- * objective is guidance layered on retained context, not a restart. */
-export function buildAppendedObjectivePrompt(previousTask: string, objective: string): string {
-	return `You are continuing an earlier sub-agent session with an appended objective from the parent. ${RESUME_CONTINUATION_RULES} Previous objective: ${previousTask}. Appended objective: ${objective}. Complete the appended objective on top of the work already done, without restarting from scratch. Continue now.`;
-}
-
 /** Create a fresh private session directory under the given root. The owner
  * marker is what lets a later load tell a session this process still owns from
  * one a crash abandoned. */
@@ -553,10 +553,11 @@ export async function runSingleAgentWithMainFallback(
 			}
 			const delay = startupDelays[attempt];
 			if (delay === undefined) {
-				lastResult.errorMessage = formatStartupRetryExhaustedError(
+				const reason = getResultError(lastResult);
+				lastResult.errorMessage = [formatStartupRetryExhaustedError(
 					lastResult.model ?? opts.agent.model ?? "default",
 					attempt + 1,
-				);
+				), reason].filter(Boolean).join("\n");
 				lastResult.stopReason ??= "error";
 				lastResult.dispatchFailed = true;
 				return lastResult;

package/src/isolation/temp-hygiene.ts

@@ -5,17 +5,15 @@
  * Two classes live there and both are swept the same way. Transient per-run
  * files (child prompt copies, the no-retry policy extension) sit in `tmp/`;
  * retained child sessions and isolated worktrees sit in `sessions/` and
- * `worktrees/`, where they must outlive the process that made them so a reload
- * can resume from them. Every mkdtemp directory gets an owner marker with the
+ * `worktrees/`, where they must outlive the process that made them for manual
+ * recovery after reload. Every mkdtemp directory gets an owner marker with the
  * creating pid. At extension load, directories whose owner is dead are removed;
  * unmarked leftovers fall back to an age cap.
  *
- * Ownership is what makes this safe for the durable class. A retained session
- * that no manifest record claims — a settled thread still resumable in the
- * session that produced it — belongs to a live owner and survives; the same
- * directory left behind by a crash does not. Callers sweeping durable roots
- * additionally pass the paths their thread and recovery manifests still reference,
- * so parked and retained work is never removed even if its owner is long gone.
+ * Ownership keeps a live parent's retained sessions and worktrees intact even
+ * when no manifest record claims them. Callers sweeping durable roots additionally
+ * pass the paths their thread and recovery manifests still reference, so interrupted
+ * and retained work survives even when its owner is gone.
  *
  * A live sibling pi instance never loses its directories: `kill(pid, 0)` only
  * reports "no such process" when the pid genuinely does not exist, so a live
@@ -36,7 +34,7 @@ export const TEMP_OWNER_FILE_NAME = "owner.json";
 const TEMP_DIR_PREFIXES = ["pi-subagents-"] as const;
 
 /** Durable directories created under `<project>/sessions` and
- * `<project>/worktrees`: retained child sessions (including resume forks) and
+ * `<project>/worktrees`: retained child sessions and
  * isolated worktree groups. */
 const DURABLE_DIR_PREFIXES = ["pi-subagent-session-", "pi-subagent-worktree-"] as const;
 

package/src/isolation/worktree.ts

@@ -1,8 +1,8 @@
 /**
  * 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, and resumes. Finalize
+ * A handle is created in the bounded queue and stays owned by the logical run
+ * across startup retries and model candidates. 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.
@@ -17,7 +17,6 @@ import {
 	runCommand,
 	type CommandResult,
 	type CommandRunner,
-	WORKTREE_PATCH_MAX_BYTES,
 } from "./git-command.ts";
 import { writeTempOwnerMarker } from "./temp-hygiene.ts";
 
@@ -25,9 +24,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 generations create a fresh worktree, so the identity
- * visibly changes when the group's filesystem boundary changes. */
+/** Short stable identity of one isolated worktree group (the mkdtemp suffix). */
 export function worktreeGroupId(worktree: Pick<WorktreeIsolation, "tempDir">): string {
 	const base = worktree.tempDir.split(/[\\/]/).filter(Boolean).pop() ?? worktree.tempDir;
 	return base.startsWith(WORKTREE_TEMP_DIR_PREFIX)
@@ -60,9 +57,8 @@ export interface WorktreeCheckpointRef {
 }
 
 /** 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. */
+ * handle after a reload or restart. Patch bytes are deliberately omitted;
+ * the checkpoint commit remains in the shared repository as recovery evidence. */
 export interface WorktreeSnapshot {
 	originalCwd: string;
 	originalRoot: string;
@@ -81,11 +77,6 @@ export interface WorktreeCreateOptions {
 	/** Parent directory for the worktree group: the project-scoped durable
 	 * worktrees root, so isolation never lands in the OS temp directory. */
 	tempBaseDir: string;
-	/** Complete source generation checkpoint merged onto the current HEAD. */
-	seedCheckpoint?: WorktreeCheckpoint;
-	/** The seed is already present in the parent checkout, so only later edits
-	 * should be integrated when this continuation settles. */
-	seedIsIntegrated?: boolean;
 }
 
 export type WorktreeFinalizationStatus = "integrated" | "no_changes" | "retained";
@@ -110,17 +101,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. */
+	/** Diff base retained in snapshots so recovery never reapplies integrated work. */
 	readonly integrationBaseHead: string;
 	readonly state: "active" | "finalizing" | WorktreeFinalizationStatus;
-	/** Checkpoint retained after finalization for continuation resumes. */
+	/** Checkpoint retained after finalization for recovery evidence. */
 	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. */
-	snapshotCheckpoint(): Promise<WorktreeCheckpoint>;
-	/** Remove a newly-created continuation that failed before it was dispatched. */
+	/** Remove an unused worktree whose dispatch was cancelled. */
 	discard(): Promise<void>;
 	/** Whether anything is pending against the integration base — the same
 	 * question finalization answers as `hadChanges`, asked before settlement so
@@ -319,8 +305,7 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 	private currentState: WorktreeIsolation["state"] = "active";
 	private finalization?: Promise<WorktreeFinalization>;
 	private discardPromise?: Promise<void>;
-	/** Full workspace checkpoint relative to the generation's starting HEAD,
-	 * retained after cleanup so settled threads can continue safely. */
+	/** Full workspace checkpoint retained for manual recovery. */
 	private continuationCheckpoint?: WorktreeCheckpoint;
 
 	constructor(
@@ -332,8 +317,7 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 		readonly patchPath: string,
 		readonly head: string,
 		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. */
+		/** A restored base may represent work already integrated into the parent. */
 		readonly integrationBaseHead: string = head,
 		restored?: {
 			state: WorktreeIsolation["state"];
@@ -354,19 +338,6 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 		return this.continuationCheckpoint ? cloneCheckpoint(this.continuationCheckpoint) : undefined;
 	}
 
-	async snapshotCheckpoint(): Promise<WorktreeCheckpoint> {
-		if (this.continuationCheckpoint) return cloneCheckpoint(this.continuationCheckpoint);
-		if (this.currentState === "no_changes") {
-			return { baseHead: this.head, commit: this.head, patch: Buffer.alloc(0) };
-		}
-		if (!existsSync(this.worktreePath)) {
-			throw new Error(`Cannot snapshot isolated worktree after it was removed: ${this.worktreePath}`);
-		}
-		const snapshot = await this.collectChanges(this.head);
-		this.continuationCheckpoint = await this.createCheckpoint(snapshot.stdout);
-		return cloneCheckpoint(this.continuationCheckpoint);
-	}
-
 	discard(): Promise<void> {
 		if (this.discardPromise) return this.discardPromise;
 		if (this.finalization) {
@@ -385,8 +356,8 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 
 	async hasPendingChanges(): Promise<boolean> {
 		// A settled worktree already recorded the answer; asking Git again after
-		// removal would fail. Diffing the integration base (not HEAD) keeps a
-		// continuation honest: only this generation's own work counts.
+		// removal would fail. Diffing the integration base (not HEAD) excludes
+		// previously integrated work from the recovered run's pending changes.
 		if (this.currentState === "no_changes") return false;
 		if (this.currentState !== "active" || !existsSync(this.worktreePath)) return true;
 		const diff = await this.collectChanges(this.integrationBaseHead);
@@ -633,50 +604,6 @@ export async function createWorktreeIsolation(
 		await mkdir(isolatedCwd, { recursive: true });
 		await linkNodeModules(runner, target.originalRoot, worktreePath);
 
-		let integrationBaseHead = target.head;
-		const checkpoint = options.seedCheckpoint;
-		if (checkpoint && checkpoint.patch.length > WORKTREE_PATCH_MAX_BYTES) {
-			throw new Error(
-				`Isolated checkpoint exceeds the ${WORKTREE_PATCH_MAX_BYTES}-byte patch limit (${checkpoint.patch.length} bytes).`,
-			);
-		}
-		if (checkpoint && checkpoint.patch.length > 0) {
-			// Merge the checkpoint commit with today's HEAD instead of blindly
-			// applying its old patch. If the parent committed generation one after
-			// integration, Git recognizes the equivalent tree and produces HEAD
-			// unchanged; unrelated newer commits are preserved by the three-way merge.
-			const merged = await runGit(
-				runner,
-				worktreePath,
-				["merge-tree", "--write-tree", "--messages", target.head, checkpoint.commit],
-				`Merging isolated checkpoint into continuation ${worktreePath}`,
-			);
-			const mergedTree = merged.stdout.toString("utf8").split(/\r?\n/, 1)[0]?.trim();
-			if (!mergedTree) throw new Error("Git returned no merged continuation tree id.");
-			await runGit(
-				runner,
-				worktreePath,
-				["read-tree", "--reset", "-u", mergedTree],
-				`Materializing isolated checkpoint in ${worktreePath}`,
-			);
-			if (options.seedIsIntegrated) {
-				const commit = await runGit(
-					runner,
-					worktreePath,
-					[
-						"-c", "user.name=pi-subagents",
-						"-c", "user.email=pi-subagents@example.invalid",
-						"commit-tree", mergedTree,
-						"-p", target.head,
-						"-m", "pi-subagents continuation baseline",
-					],
-					`Creating continuation baseline commit in ${worktreePath}`,
-				);
-				integrationBaseHead = commit.stdout.toString("utf8").trim();
-				if (!integrationBaseHead) throw new Error("Git returned no continuation baseline commit id.");
-			}
-		}
-
 		return new GitWorktreeIsolation(
 			target.originalCwd,
 			target.originalRoot,
@@ -686,7 +613,6 @@ export async function createWorktreeIsolation(
 			patchPath,
 			target.head,
 			runner,
-			integrationBaseHead,
 		);
 	} catch (error) {
 		const rollbackErrors: string[] = [];
@@ -795,8 +721,7 @@ export function normalizeWorktreeSnapshot(value: unknown): WorktreeSnapshot | nu
 /** 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. */
+ * restored checkpoint retains its commit identity without duplicating patch bytes. */
 export async function restoreWorktreeIsolation(
 	snapshot: WorktreeSnapshot,
 	options: { runner?: CommandRunner } = {},

package/src/lifecycle/durable.ts

@@ -43,9 +43,8 @@ const THREADS_MANIFEST_VERSION = 1;
  * win over the age rule. */
 export const PROJECT_ROOT_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1_000;
 
-/** Fixed retention: parked work (which may hold unintegrated changes) stops
- * being resumable after a month. Older manifests may still carry settled
- * records from previous versions; restore discards them on sight. */
+/** Interrupted work retains its recovery record for a month. Older manifests
+ * may still carry settled records; restore discards those on sight. */
 export const PARKED_RECORD_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
 
 /** Result excerpts are for status display after restore, not full transcripts. */
@@ -84,7 +83,7 @@ export interface ThreadRecord {
 	executionCwd: string;
 	/** Resolved (clamped) level of the last generation. */
 	thinkingLevel?: string;
-	/** Level the dispatch requested; a resume after a restart re-runs at it. */
+	/** Originally requested level, retained with the recovery metadata. */
 	requestedThinkingLevel?: string;
 	isolation: IsolationMode;
 	state: "parked" | "completed" | "failed";
@@ -106,9 +105,8 @@ export function currentBootId(now = Date.now()): number {
 /** Whether a record's `childPids` can still name processes of this boot. Pids
  * are only unique within a boot: after a restart the same number belongs to
  * whatever claimed it, so restore must not signal them. Records written before
- * this field existed carry no boot id and count as unverifiable — leaving a
- * stray child alive costs a resumable session nothing, while killing an
- * unrelated process tree is not recoverable. */
+ * this field existed carry no boot id and count as unverifiable; leaving a
+ * stray child alive is safer than killing an unrelated process tree. */
 export function isCurrentBoot(record: ThreadRecord, now = Date.now()): boolean {
 	if (record.bootId === undefined) return false;
 	return Math.abs(record.bootId - currentBootId(now)) <= BOOT_ID_TOLERANCE_MS;
@@ -375,7 +373,7 @@ function summarizeResult(result: SingleResult): ThreadResultSummary | undefined
 
 /** Project a live thread into its durable record. Only handles whose
  * filesystem is still meaningful are persisted; finalized-and-removed
- * worktrees keep just their checkpoint commit for continuation resumes. */
+ * worktrees keep their checkpoint commit as recovery evidence. */
 export function threadRecordFromThread(
 	thread: SubagentThread,
 	state: "parked" | "completed" | "failed",