@ferris1225/pi-subagents 4.1.8 → 4.1.9

package/src/prompt.ts

@@ -61,21 +61,21 @@ export function buildDelegationDirective(
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only as the separate evidence-first entry for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance; never substitute it for \`worker\`. It applies every safe proven in-scope cut without item-by-item approval. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only for user-authorized cleanup, removal, simplification, or duplicate-code consolidation; it applies every safe proven in-scope cut without item-by-item approval. Read-only audits and code-health reviews go to ${hasReviewer ? "`reviewer`" : "the main context because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
 			]
 			: []),
 		...(hasDocumenter
 			? [
-				`Use \`documenter\` directly only for explicit whole-codebase maintenance or standalone documentation/comment work; a top-level documenter delivers directly without an automatic reviewer.${codeWriterNames.length > 0 ? ` ${codeWriterNames.join("/")} must sync existing docs they directly affect; runtime runs documenter only after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback—never dispatch a duplicate.` : ""} It never changes runtime behavior, versions, or release state.`,
+				`Use \`documenter\` directly only for explicit whole-codebase or standalone documentation/comment work; a top-level documenter delivers without an automatic reviewer.${codeWriterNames.length > 0 ? ` ${codeWriterNames.join("/")} must sync existing docs they directly affect; runtime runs documenter only after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback—never dispatch a duplicate.` : ""} It never changes runtime behavior, versions, or release state.`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for read-only assessments or a gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get one fresh read-only reviewer gate, independent of the writer.` : ""} Advisory output has no VERDICT and cannot authorize follow-up edits${hasDocumenter ? "; gates classify docs separately for the enabled documenter." : "."}`,
+				`Use \`reviewer\` for read-only assessments or a gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get one fresh read-only reviewer gate, independent of the writer.` : ""} Advisory output has no VERDICT and cannot authorize follow-up edits${hasDocumenter ? "; gates classify docs separately for the enabled documenter." : "."} Re-verifying your own fixes? Dispatch with \`advisory: true\`: the report returns to you and never starts the auto-fix chain.`,
 			]
 			: []),
 		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory.",
-		"Children are leaf processes without delegation tools; use `subagent_control fork` on a parked/settled thread for an independent continuation.",
+		"Children are leaf processes without delegation tools; use `subagent_control resume` on a parked/settled thread to continue its retained context.",
 		...(hasMultiple
 			? [
 				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",

package/src/rpc-run.ts

@@ -1,7 +1,7 @@
 /*
  * Persistent pi RPC child transport for one logical sub-agent generation.
  *
- * A child stays alive across prompt/steer/abort/retarget operations and speaks
+ * 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.
@@ -16,6 +16,7 @@ import { StringDecoder } from "node:string_decoder";
 import type { Message } from "@earendil-works/pi-ai";
 import { SUBAGENT_TOOL_NAMES, type AgentConfig } from "./agents.ts";
 import type { ThinkingLevel } from "./config.ts";
+import { writeTempOwnerMarker } from "./temp-hygiene.ts";
 import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
@@ -82,8 +83,6 @@ export interface RpcSingleResult {
 	sessionDir?: string;
 	/** Original task/project cwd used for result-artifact retention buckets. */
 	projectCwd?: string;
-	/** Internal disposition: dispatch suppresses completion delivery for parks. */
-	parked?: boolean;
 	/** Stable logical run id assigned by dispatch (also present on queued results). */
 	runId?: number;
 	/** Filesystem isolation selected for this logical thread. */
@@ -95,15 +94,13 @@ export interface RpcSingleResult {
 	/** Retained only when integration/cleanup failed; never contains patch data. */
 	integrationWorktreePath?: string;
 	integrationPatchPath?: string;
-	/** Session-fork relationships between stable logical run ids. */
-	forkedFromRunId?: number;
-	forkChildRunIds?: number[];
 }
 
 export type SubagentLiveEvent =
-	| { kind: "status"; status: "queued" | "running" | "steering" | "interrupting" | "parked" | "done" | "failed" }
+	| { kind: "status"; status: "queued" | "running" | "interrupting" | "done" | "failed" }
 	| { kind: "model"; model?: string; thinking?: ThinkingLevel; fallbackFrom?: string }
 	| { kind: "usage"; usage: UsageStats; model?: string }
+	| { kind: "session"; sessionId: string; sessionDir: string }
 	| { kind: "tool_start"; toolCallId?: string; toolName: string; args: unknown }
 	| { kind: "tool_end"; toolCallId?: string; toolName: string; isError: boolean }
 	| { kind: "thinking" }
@@ -113,17 +110,12 @@ export type RpcControlPhase =
 	| "queued"
 	| "starting"
 	| "running"
-	| "steering"
 	| "interrupting"
 	| "retrying"
-	| "parked"
 	| "settled"
 	| "stopped";
 
 interface AttemptControl {
-	steer(instruction: string): Promise<void>;
-	retarget(objective: string): Promise<void>;
-	park(): Promise<void>;
 	stop(reason?: string): Promise<void>;
 }
 
@@ -138,9 +130,9 @@ export class RpcRunControl {
 	private attempt?: { token: number; control: AttemptControl };
 	private nextToken = 1;
 	private serial: Promise<void> = Promise.resolve();
-	private parkRequested = false;
 	private stopRequested = false;
 	private stopMessage = "Subagent was aborted";
+	private childPids = new Set<number>();
 
 	constructor(
 		objective: string,
@@ -158,10 +150,6 @@ export class RpcRunControl {
 		return this.phase;
 	}
 
-	isParkRequested(): boolean {
-		return this.parkRequested;
-	}
-
 	isStopRequested(): boolean {
 		return this.stopRequested;
 	}
@@ -170,15 +158,15 @@ export class RpcRunControl {
 		return this.stopMessage;
 	}
 
-	/** Update a not-yet-started/retrying objective without launching a process. */
-	retargetPending(objective: string): void {
-		this.objective = objective;
+	/** Pids of every child process this generation spawned. Persisted with the
+	 * thread record so a later load can kill orphans that still hold the
+	 * retained session. */
+	noteChildPid(pid: number): void {
+		if (Number.isInteger(pid) && pid > 0) this.childPids.add(pid);
 	}
 
-	/** Mark queued/starting work for park without waiting on an RPC abort event. */
-	parkPending(): void {
-		this.parkRequested = true;
-		this.setPhase("parked");
+	getChildPids(): number[] {
+		return [...this.childPids];
 	}
 
 	markStarting(): void {
@@ -186,12 +174,12 @@ export class RpcRunControl {
 	}
 
 	markRetrying(): void {
-		if (!this.parkRequested && !this.stopRequested) this.setPhase("retrying");
+		if (!this.stopRequested) this.setPhase("retrying");
 	}
 
 	markSettled(): void {
 		this.attempt = undefined;
-		if (!this.parkRequested && !this.stopRequested) this.setPhase("settled");
+		if (!this.stopRequested) this.setPhase("settled");
 	}
 
 	/** Allocate an attempt token used to reject state updates from old children. */
@@ -212,32 +200,6 @@ export class RpcRunControl {
 		this.setPhase(phase);
 	}
 
-	async steer(instruction: string): Promise<void> {
-		return this.serialize(async () => {
-			const attempt = this.attempt?.control;
-			if (!attempt) throw new Error(`Thread is ${this.phase}; steering requires a running child.`);
-			await attempt.steer(instruction);
-		});
-	}
-
-	async retarget(objective: string): Promise<void> {
-		return this.serialize(async () => {
-			this.objective = objective;
-			const attempt = this.attempt?.control;
-			if (!attempt) return;
-			await attempt.retarget(objective);
-		});
-	}
-
-	async park(): Promise<void> {
-		return this.serialize(async () => {
-			this.parkRequested = true;
-			const attempt = this.attempt?.control;
-			if (attempt) await attempt.park();
-			this.setPhase("parked");
-		});
-	}
-
 	async stop(reason = "Subagent was aborted"): Promise<void> {
 		return this.serialize(async () => {
 			this.stopRequested = true;
@@ -369,6 +331,7 @@ export async function writeChildRetryPolicyExtension(
 	modelRef?: string,
 ): Promise<ChildRetryPolicyExtension> {
 	const dir = await mkdtemp(join(tmpdir(), "pi-subagents-policy-"));
+	writeTempOwnerMarker(dir);
 	const filePath = join(dir, "no-provider-retries.mjs");
 	const slash = modelRef?.indexOf("/") ?? -1;
 	const selectedProvider = slash > 0 ? modelRef!.slice(0, slash) : undefined;
@@ -398,6 +361,7 @@ export async function writeChildRetryPolicyExtension(
 
 async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
 	const dir = await mkdtemp(join(tmpdir(), "pi-subagents-"));
+	writeTempOwnerMarker(dir);
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
 	const filePath = join(dir, `prompt-${safeName}.md`);
 	try {
@@ -541,11 +505,6 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	let abortSettlement: Deferred<void> | undefined;
 	let initialPromptResolved = false;
 	const initialPrompt = deferred<{ accepted: boolean; error?: Error }>();
-	let continuationCommandInFlight = false;
-	let continuationAccepted = false;
-	let continuationTurnStarted = false;
-	let continuationTurnCompleted = false;
-	let deferredAgentSettlement = false;
 	const pendingRequests = new Map<string, PendingRequest>();
 	const outcome = deferred<void>();
 	const processClosed = deferred<void>();
@@ -562,13 +521,8 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 
 	const setAttemptPhase = (phase: RpcControlPhase): void => {
 		if (attemptToken !== undefined) control?.updateAttemptPhase(attemptToken, phase);
-		switch (phase) {
-			case "running":
-			case "steering":
-			case "interrupting":
-			case "parked":
-				emit({ kind: "status", status: phase });
-				break;
+		if (phase === "running" || phase === "interrupting") {
+			emit({ kind: "status", status: phase });
 		}
 	};
 
@@ -685,142 +639,6 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	};
 
 	const attemptControl: AttemptControl = {
-		async steer(instruction: string): Promise<void> {
-			if (finished) throw new Error("Thread already settled before it could be steered.");
-			const acceptance = await initialPrompt.promise;
-			if (!acceptance.accepted) throw acceptance.error ?? new Error("The initial prompt was rejected.");
-			setAttemptPhase("steering");
-			// Prompt+streamingBehavior performs the active→steer / idle→new-prompt
-			// choice atomically inside Pi. Hold any old agent_settled event until this
-			// command is accepted so an extension-handler race cannot drop the steer.
-			continuationCommandInFlight = true;
-			continuationAccepted = false;
-			continuationTurnStarted = false;
-			continuationTurnCompleted = false;
-			deferredAgentSettlement = false;
-			try {
-				await send({ type: "prompt", message: asPlainTextRpcPrompt(instruction), streamingBehavior: "steer" });
-				continuationAccepted = true;
-				if (deferredAgentSettlement && !continuationTurnStarted) {
-					// A handled input can succeed without starting a turn. Confirm the
-					// server is idle before consuming the delayed settlement.
-					const state = await send({ type: "get_state" }).catch(() => undefined);
-					if ((state?.data as { isStreaming?: unknown } | undefined)?.isStreaming === false) {
-						continuationAccepted = false;
-						deferredAgentSettlement = false;
-						settleRun();
-					}
-				}
-			} catch (error) {
-				continuationAccepted = false;
-				if (deferredAgentSettlement) {
-					deferredAgentSettlement = false;
-					settleRun();
-				}
-				throw error;
-			} finally {
-				continuationCommandInFlight = false;
-			}
-			// Remain visibly steering until the next turn starts.
-		},
-		async retarget(objective: string): Promise<void> {
-			if (finished) throw new Error("Thread already settled before it could be retargeted.");
-			setAttemptPhase("interrupting");
-			result.task = objective;
-			const accepted = await abortAcceptedPrompt();
-			if (!accepted) {
-				if (!closed) await processClosed.promise;
-				return;
-			}
-			if (finished || closed) throw new Error("Thread exited while retargeting.");
-			// The aborted assistant message remains in the retained session/history,
-			// but it must not classify the replacement objective as aborted.
-			result.stopReason = undefined;
-			result.errorMessage = undefined;
-			result.exitCode = 0;
-			// Tool failures belong to the abandoned objective. Keep them in session
-			// history, but do not classify a successful replacement as failed.
-			result.failedTools = undefined;
-			try {
-				await send({ type: "prompt", message: asPlainTextRpcPrompt(objective) });
-				setAttemptPhase("running");
-			} catch (error) {
-				const promptError = error instanceof Error ? error : new Error(String(error));
-				result.exitCode = 1;
-				result.stopReason = "error";
-				result.errorMessage = `Replacement prompt was rejected: ${promptError.message}`;
-				if (promptError instanceof RpcCommandRejectedError) result.rpcPromptRejected = true;
-				finish();
-				terminate();
-				if (!closed) await processClosed.promise;
-				throw promptError;
-			}
-		},
-		async park(): Promise<void> {
-			const markParked = (): void => {
-				result.parked = true;
-				result.exitCode = 0;
-				result.stopReason = undefined;
-				result.errorMessage = undefined;
-				result.rpcStartupFailed = undefined;
-				result.rpcPromptRejected = undefined;
-			};
-			if (finished) {
-				if (!closed) await processClosed.promise;
-				if (result.parked) return;
-				// Handshake/startup already tore the child down. Convert a pre-prompt
-				// settlement into a park instead of throwing past the control tool.
-				if (!result.rpcPromptAccepted) {
-					markParked();
-					return;
-				}
-				throw new Error("Thread already settled before it could be parked.");
-			}
-			setAttemptPhase("interrupting");
-			if (!initialPromptResolved) {
-				const parked = new Error("Run was parked before its initial prompt.");
-				resolveInitialPrompt(false, parked);
-				rejectPending(parked);
-				markParked();
-				setAttemptPhase("parked");
-				finish();
-				terminate();
-				if (!closed) await processClosed.promise;
-				return;
-			}
-			// Bound the abort settlement exactly like stop: a child that never
-			// settles after abort must not hold the control operation forever.
-			let parkTimer: ReturnType<typeof setTimeout> | undefined;
-			let parkTimedOut = false;
-			const parkDeadline = new Promise<boolean>((resolve) => {
-				parkTimer = setTimeout(() => {
-					parkTimedOut = true;
-					resolve(false);
-				}, RPC_ABORT_SETTLE_TIMEOUT_MS);
-				if (typeof parkTimer.unref === "function") parkTimer.unref();
-			});
-			let accepted: boolean;
-			try {
-				accepted = await Promise.race([abortAcceptedPrompt(), parkDeadline]);
-			} catch {
-				/* a rejected abort still parks; termination below is the bounded fallback */
-				accepted = false;
-			} finally {
-				if (parkTimer) clearTimeout(parkTimer);
-			}
-			if (abortSettlement) {
-				const stable = abortSettlement;
-				abortSettlement = undefined;
-				stable.resolve();
-			}
-			if (!accepted && !parkTimedOut && !closed) await processClosed.promise;
-			if (finished && accepted) throw new Error("Thread exited while parking.");
-			markParked();
-			setAttemptPhase("parked");
-			finish();
-			terminate();
-			if (!closed) await processClosed.promise;
-		},
 		async stop(reason = "Subagent was aborted"): Promise<void> {
 			if (finished) {
 				if (!closed) await processClosed.promise;
@@ -862,6 +680,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	};
 
 	if (attemptToken !== undefined) control?.attach(attemptToken, attemptControl);
+	if (proc.pid !== undefined) control?.noteChildPid(proc.pid);
 	control?.markStarting();
 
 	const processLine = (rawLine: string): void => {
@@ -929,15 +748,8 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			emit({ kind: "status", status: "running" });
 		}
 		if (event.type === "turn_start") {
-			if (continuationCommandInFlight || continuationAccepted) {
-				continuationTurnStarted = true;
-			}
 			setAttemptPhase("running");
 		}
-		if (event.type === "turn_end" && continuationTurnStarted) {
-			continuationTurnCompleted = true;
-			deferredAgentSettlement = false;
-		}
 
 		if (event.type === "message_update") {
 			const type = event.assistantMessageEvent?.type;
@@ -998,18 +810,6 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				stable.resolve();
 				return;
 			}
-			if ((continuationCommandInFlight || continuationAccepted) && !continuationTurnCompleted) {
-				// Pi may emit an old settlement while an extension handler is yielding
-				// and the atomic prompt command starts the continuation. Its successful
-				// response guarantees a new/queued turn, so defer this stale event until
-				// that continuation has completed a turn.
-				deferredAgentSettlement = true;
-				return;
-			}
-			continuationAccepted = false;
-			continuationTurnStarted = false;
-			continuationTurnCompleted = false;
-			deferredAgentSettlement = false;
 			settleRun();
 		}
 	};
@@ -1098,13 +898,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	}
 
 	try {
-		if (control?.isParkRequested()) {
-			resolveInitialPrompt(false, new Error("Run was parked before its initial prompt."));
-			result.parked = true;
-			result.exitCode = 0;
-			finish();
-			terminate();
-		} else if (control?.isStopRequested()) {
+		if (control?.isStopRequested()) {
 			resolveInitialPrompt(false, new Error("Run was stopped before its initial prompt."));
 			await attemptControl.stop();
 		} else {
@@ -1123,13 +917,13 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				await send({ type: "get_state" }, readyTimeoutMs);
 			} catch (error) {
 				const handshakeError = error instanceof Error ? error : new Error(String(error));
-				if (!control?.isParkRequested() && !control?.isStopRequested()) {
+				if (!control?.isStopRequested()) {
 					failBeforePrompt(handshakeError, true);
 				} else {
 					resolveInitialPrompt(false, handshakeError);
 				}
 			}
-			if (!finished && !initialPromptResolved && !control?.isParkRequested() && !control?.isStopRequested()) {
+			if (!finished && !initialPromptResolved && !control?.isStopRequested()) {
 				// Pi starts the agent immediately after prompt preflight, before its
 				// success response necessarily reaches stdout. From this point on, a
 				// missing ACK is ambiguous and must never be recovered by replay.

package/src/runtime.ts

@@ -20,28 +20,24 @@ import {
 	type CompletionMessageItem,
 } from "./completion.ts";
 import { type ThinkingLevel } from "./config.ts";
+import { threadRecordFromThread, upsertThreadRecord, type ThreadRecord } from "./durable.ts";
 import { isRunActiveStatus, monitor } from "./monitor.ts";
-import {
-	persistRecoveryRecords,
-	recoveryRecordFromFinalization,
-	type RecoveryRecord,
-} from "./recovery.ts";
 import type { RpcRunControl } from "./rpc-run.ts";
-import type { SingleResult } from "./spawn.ts";
+import type { StartBackgroundInternal } from "./thread-lifecycle.ts";
+import { isFailedResult, type SingleResult } from "./spawn.ts";
 import type { IsolationMode, WorktreeFinalization, WorktreeIsolation } from "./worktree.ts";
 
 export type ThreadState =
 	| "queued"
 	| "resuming"
 	| "running"
-	| "steering"
 	| "interrupting"
 	| "parked"
 	| "completed"
 	| "failed"
 	| "stopped";
 
-export type ThreadLifecycleOperation = "park" | "resume" | "fork" | "stop" | "settle";
+export type ThreadLifecycleOperation = "park" | "resume" | "stop" | "settle";
 
 export interface SubagentThread {
 	id: number;
@@ -54,6 +50,8 @@ export interface SubagentThread {
 	executionCwd: string;
 	thinkingLevel?: ThinkingLevel;
 	isolation: IsolationMode;
+	/** Report-only reviewer dispatch: verdicts never chain into auto-fix. */
+	advisoryReview: boolean;
 	worktree?: WorktreeIsolation;
 	state: ThreadState;
 	control: RpcRunControl;
@@ -74,15 +72,8 @@ export interface SubagentThread {
 	/** A destructive stop retires context even if the active child settles later. */
 	retireOnSettle?: boolean;
 	retired?: boolean;
-	/** Abort the active generation to a stable checkpoint and wait until its
-	 * queue work has published that checkpoint and released its slot. */
-	park: () => Promise<"queued" | "active">;
 	/** Installed by dispatch so the control tool can restart the same logical id. */
 	resume: (objective?: string, ctx?: ExtensionContext) => Promise<SingleResult>;
-	/** Create a new logical thread from this thread's retained Pi session branch. */
-	fork: (objective?: string, ctx?: ExtensionContext) => Promise<SingleResult>;
-	forkedFromRunId?: number;
-	forkChildRunIds: number[];
 	/** Dispatch-owned, generation-guarded worktree settlement hook. Its apply
 	 * runs under the canonical original-repository lane. */
 	finalizeIsolation: (generation: number, result?: SingleResult) => Promise<WorktreeFinalization | undefined>;
@@ -98,6 +89,13 @@ export interface SubagentRuntime {
 	getActiveTools: () => string[];
 	/** False after session_shutdown; guards delivery and queue work. */
 	sessionActive: boolean;
+	/** The process-wide background dispatcher. Set at tool registration so
+	 * threads restored from the durable manifest can resume before any dispatch. */
+	dispatcher?: StartBackgroundInternal;
+	/** Run ids restored from the durable manifest at load; consumed by the
+	 * one-time session-start notice. */
+	restoredRunIds: number[];
+	restoredNotified: boolean;
 	/** Deliver a batch of completion messages to the main window, waking it only
 	 * when the batch needs a turn. */
 	sendCompletionGroup: (items: CompletionMessageItem[]) => void;
@@ -111,7 +109,7 @@ export interface SubagentRuntime {
 	registerRunResult: (runId: number, result: SingleResult) => void;
 	/** Logical threads outlive process attempts and completed generations. */
 	threads: Map<number, SubagentThread>;
-	/** Resume/fork setup that has claimed a thread but has not yet enqueued its
+	/** Resume setup that has claimed a thread but has not yet enqueued its
 	 * next generation. Shutdown invalidates these claims and waits for cleanup. */
 	preflightOperations: Set<Promise<void>>;
 	/** Every session directory retained for this parent session, including
@@ -131,6 +129,8 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 		backgroundQueue,
 		getActiveTools: () => pi.getActiveTools(),
 		sessionActive: true,
+		restoredRunIds: [],
+		restoredNotified: false,
 		sendCompletionGroup: (items) => {
 			if (!runtime.sessionActive || items.length === 0) return;
 			// A result arriving for one run does not mean sibling runs are done.
@@ -203,61 +203,86 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			if (!runtime.sessionActive) return;
 			runtime.sessionActive = false;
 			const shutdownThreads = [...runtime.threads.values()];
+			const liveStates = new Set(["queued", "resuming", "running", "interrupting"]);
+			const previousStates = new Map(shutdownThreads.map((thread) => [thread.id, thread.state] as const));
 			// Invalidate every lifecycle claim synchronously before the first await.
-			// Resume/fork preflight checks both this version and sessionActive, then
+			// Resume preflight checks both this version and sessionActive, then
 			// cleans any worktree/session it created before resolving its tracker.
+			// A generation already inside its settlement keeps its own claim: it
+			// finalizes its worktree and persists its terminal record itself.
+			const interrupting = shutdownThreads.filter((thread) =>
+				!thread.retired &&
+				thread.lifecycleOperation !== "settle" &&
+				liveStates.has(thread.state),
+			);
 			for (const thread of shutdownThreads) {
 				thread.lifecycleVersion++;
+				if (thread.retired) {
+					thread.lifecycleOperation = "stop";
+					continue;
+				}
+				if (thread.lifecycleOperation === "settle") continue;
 				thread.lifecycleOperation = "stop";
-				thread.retired = true;
-				thread.retireOnSettle = true;
-				thread.state = "stopped";
+				// Deliberately NOT retireOnSettle: shutdown interrupts to the last
+				// checkpoint but keeps the session/worktree resumable across reload.
+				thread.retireOnSettle = false;
+				if (liveStates.has(thread.state)) thread.state = "stopped";
 			}
 			const preflights = [...runtime.preflightOperations];
 			runtime.completionBatcher.dispose();
 			runtime.backgroundQueue.cancelAll();
 			// Await live RPC process-tree cleanup and continuation preflight rollback
-			// before removing sessions/worktrees or clearing ownership maps.
+			// before persisting records or releasing ownership maps.
 			await Promise.all([
 				Promise.all(
-					shutdownThreads.map((thread) =>
+					interrupting.map((thread) =>
 						thread.control.stop("Parent session shut down").catch(() => undefined),
 					),
 				),
 				Promise.allSettled(preflights),
 				runtime.backgroundQueue.waitForIdle(),
 			]);
-			// Parked work owns no queue task, so shutdown is its final settlement.
-			// Active/stopped tasks may already have finalized; the handle and callback
-			// are idempotent and generation-guarded.
-			const recoveryRecords: RecoveryRecord[] = [];
+			// Persist one record per non-retired thread, then keep exactly the
+			// artifacts those records reference. A thread whose settlement finished
+			// during the wait above already wrote its own terminal record; the
+			// lastResult-derived state below matches it.
+			const records: ThreadRecord[] = [];
 			for (const thread of runtime.threads.values()) {
-				const finalization = await thread.finalizeIsolation(thread.generation).catch(() => undefined);
-				if (finalization?.status === "retained") {
-					recoveryRecords.push(recoveryRecordFromFinalization(thread.id, finalization));
-					if (!thread.isolationFailureNotified) {
-						thread.isolationFailureNotified = true;
-						try {
-							thread.notifyIsolationFailure?.(finalization);
-						} catch {
-							/* the parent UI may already be shutting down */
-						}
-					}
+				if (thread.retired) continue;
+				const previous = previousStates.get(thread.id) ?? thread.state;
+				let state: "parked" | "completed" | "failed";
+				if (previous === "completed" || previous === "failed") {
+					state = previous;
+				} else if (thread.lifecycleOperation === "settle" && thread.lastResult) {
+					state = isFailedResult(thread.lastResult) ? "failed" : "completed";
+				} else {
+					state = "parked";
 				}
+				records.push(threadRecordFromThread(thread, state));
 			}
-			// Persist before tearing down the old runtime. A /new, /resume, or quit
-			// must not make the only recovery paths unreachable.
-			await persistRecoveryRecords(runtime.configPath, recoveryRecords).catch(() => undefined);
-			runtime.settledRuns.clear();
-			runtime.settledListeners.clear();
-			runtime.runControllers.clear();
+			await Promise.all(
+				records.map((record) => upsertThreadRecord(runtime.configPath, record).catch(() => undefined)),
+			);
+			// Retained-failure recovery records are persisted by the finalization
+			// itself; shutdown only drops sessions no record claims anymore.
+			const referenced = new Set(
+				records.flatMap((record) =>
+					[record.sessionDir, record.worktree?.tempDir].filter(Boolean) as string[],
+				),
+			);
 			for (const sessionDir of runtime.sessionDirs) {
+				if (referenced.has(sessionDir)) continue;
 				try {
 					rmSync(sessionDir, { recursive: true, force: true });
 				} catch {
-					/* best-effort */
+					/* best-effort; the state-root sweep catches leftovers later */
 				}
 			}
+			runtime.settledRuns.clear();
+			runtime.settledListeners.clear();
+			runtime.runControllers.clear();
+			// sessionDirs entries still referenced by records stay owned by the
+			// manifest; the next process re-registers them at restore.
 			runtime.sessionDirs.clear();
 			runtime.preflightOperations.clear();
 			runtime.threads.clear();

package/src/session-fork.ts

@@ -2,7 +2,7 @@
 
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -43,12 +43,17 @@ export async function forkRetainedSession(options: {
 	targetCwd?: string;
 	sessionDir: string;
 	sessionId: string;
+	/** Parent directory for the cloned branch. Defaults to the OS temp dir;
+	 * dispatch passes the durable state root. */
+	targetRoot?: string;
 }): Promise<ForkedSession> {
 	const sourceSessionFile = await findRetainedSessionFile(
 		options.sessionDir,
 		options.sessionId,
 	);
-	const sessionDir = await mkdtemp(join(tmpdir(), "pi-subagent-session-fork-"));
+	const root = options.targetRoot ?? tmpdir();
+	await mkdir(root, { recursive: true });
+	const sessionDir = await mkdtemp(join(root, "pi-subagent-session-fork-"));
 	try {
 		// Supplying the new directory makes createBranchedSession write there.
 		// cwdOverride rewrites the cloned header so a settled isolated session can