pi-subagents 0.49.0 → 0.51.0

package/src/runs/shared/subagent-control.ts

@@ -6,6 +6,9 @@ import {
 	type ControlNotificationChannel,
 	type ResolvedControlConfig,
 } from "../../shared/types.ts";
+import { isToolTimeoutExempt } from "./tool-timeout.ts";
+import { createHash } from "node:crypto";
+import { previewDisplayText } from "../../shared/display-text.ts";
 
 const CONTROL_EVENT_TYPES: ControlEventType[] = ["active_long_running", "needs_attention"];
 const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
@@ -84,6 +87,18 @@ export function deriveActivityState(input: {
 	return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
 }
 
+export function shouldEmitOpenToolAttention(input: {
+	config: ResolvedControlConfig;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	now?: number;
+}): boolean {
+	if (!input.config.enabled || !input.currentTool || input.currentToolStartedAt === undefined) return false;
+	if (isToolTimeoutExempt(input.currentTool)) return false;
+	const now = input.now ?? Date.now();
+	return Math.max(0, now - input.currentToolStartedAt) >= input.config.activeNoticeAfterMs;
+}
+
 export function buildControlEvent(input: {
 	type?: ControlEventType;
 	from?: ActivityState;
@@ -103,6 +118,10 @@ export function buildControlEvent(input: {
 	currentPath?: string;
 	elapsedMs?: number;
 	recentFailureSummary?: string;
+	workflowKey?: string;
+	phase?: string;
+	label?: string;
+	taskPreview?: string;
 }): ControlEvent {
 	const ts = input.ts ?? Date.now();
 	const type = input.type ?? (input.to === "active_long_running" ? "active_long_running" : "needs_attention");
@@ -131,6 +150,10 @@ export function buildControlEvent(input: {
 		...(input.currentPath ? { currentPath: input.currentPath } : {}),
 		...(elapsedMs !== undefined ? { elapsedMs } : {}),
 		...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
+		...(input.workflowKey ? { workflowKey: input.workflowKey } : {}),
+		...(input.phase ? { phase: input.phase } : {}),
+		...(input.label ? { label: input.label } : {}),
+		...(input.taskPreview ? { taskPreview: previewDisplayText(input.taskPreview, 160) } : {}),
 	};
 }
 
@@ -140,7 +163,8 @@ export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: C
 
 export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
 	const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
-	return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
+	const contextHash = createHash("sha256").update(formatControlNudge(event)).digest("hex").slice(0, 8);
+	return `${childKey}:${event.type}:${event.reason ?? "idle"}:${contextHash}`;
 }
 
 export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
@@ -162,6 +186,17 @@ function formatLongRunningFacts(event: ControlEvent): string | undefined {
 	return facts.length > 0 ? facts.join(" | ") : undefined;
 }
 
+export function formatControlNudge(event: ControlEvent): string {
+	const scope = event.label ?? event.phase ?? event.workflowKey ?? event.taskPreview;
+	if (event.recentFailureSummary) return previewDisplayText(`Resolve the recent failure${scope ? ` for ${scope}` : ""}: ${event.recentFailureSummary}. Report the smallest next step or ask for a decision.`, 160);
+	if (event.currentTool || event.currentPath) {
+		const current = [event.currentTool ? `tool ${event.currentTool}` : undefined, event.currentPath ? `path ${event.currentPath}` : undefined].filter(Boolean).join(" at ");
+		return previewDisplayText(`Check ${current}${scope ? ` for ${scope}` : ""}. Report the smallest next step or ask for a decision.`, 160);
+	}
+	if (scope) return previewDisplayText(`Continue ${scope}. Report the smallest next step or ask for a decision.`, 160);
+	return "What are you blocked on? Reply with the smallest next step or ask for a decision.";
+}
+
 export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
 	const runTarget = event.runId;
 	if (event.reason === "completion_guard") {
@@ -174,9 +209,9 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 		].filter((line): line is string => Boolean(line)).join("\n");
 	}
 
-	const nudgeMessage = "What are you blocked on? Reply with the smallest next step or ask for a decision.";
-	const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: "${nudgeMessage}" })`;
-	const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: "${nudgeMessage}" })`;
+	const nudgeMessage = formatControlNudge(event);
+	const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: ${JSON.stringify(nudgeMessage)} })`;
+	const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: ${JSON.stringify(nudgeMessage)} })`;
 	if (event.type === "active_long_running") {
 		const facts = formatLongRunningFacts(event);
 		return [
@@ -196,10 +231,12 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 	const supervisorHint = event.reason === "supervisor_request"
 		? "Supervisor request: reply to the pending request. If subagent_supervisor pending is empty, check intercom pending because an external intercom tool may own the request."
 		: undefined;
+	const facts = formatLongRunningFacts(event);
 	return [
 		`Subagent needs attention: ${event.agent}`,
 		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
 		`Signal: ${event.message}`,
+		facts ? `Facts: ${facts}` : undefined,
 		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
 		supervisorHint,
 		"Hint: Inspect status first unless the run is clearly blocked. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
+import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.ts";
 import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, PERMISSION_POLICY_ENV } from "./permissions.ts";
 import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerDeliveryStatus, type SteerRequest } from "../background/control-channel.ts";
 import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
@@ -337,6 +338,7 @@ export function registerSteeringInbox(
 		nativeRealpath?: (filePath: string) => string;
 		legacySettleFallbackMs?: number;
 		safetyPollIntervalMs?: number;
+		platform?: NodeJS.Platform;
 		timers?: Pick<typeof globalThis, "setInterval" | "clearInterval">;
 	} = {},
 ): void {
@@ -449,13 +451,17 @@ export function registerSteeringInbox(
 			safetyInterval = (deps.timers?.setInterval ?? setInterval)(flush, deps.safetyPollIntervalMs ?? STEERING_SAFETY_POLL_INTERVAL_MS) as NodeJS.Timeout;
 			safetyInterval.unref?.();
 		};
-		try {
-			watcher = (deps.watch ?? fs.watch)(resolveWatchPath(steerInbox, deps.nativeRealpath), () => flush());
-			watcher.on("error", startPolling);
-			startSafetyPolling();
-		} catch {
-			watcher = undefined;
+		if (!shouldUseNativeFsWatch("child-steering-inbox", deps.platform)) {
 			startPolling();
+		} else {
+			try {
+				watcher = (deps.watch ?? fs.watch)(resolveWatchPath(steerInbox, deps.nativeRealpath), () => flush());
+				watcher.on("error", startPolling);
+				startSafetyPolling();
+			} catch {
+				watcher = undefined;
+				startPolling();
+			}
 		}
 	};
 	const activate = (): undefined => {
@@ -580,16 +586,9 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	} as unknown as SubagentState;
 	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, waitToolEnabled);
 	let nativeSupervisorClientRegistered = false;
-	let nativeSupervisorFallbackRegistered = false;
 	const registerNativeSupervisorClientOnce = (): void => {
 		if (nativeSupervisorClientRegistered) return;
 		nativeSupervisorClientRegistered = true;
-		registerNativeSupervisorClient(pi, { includeIntercomFallback: false });
-	};
-	const registerNativeSupervisorFallbackOnce = (): void => {
-		registerNativeSupervisorClientOnce();
-		if (nativeSupervisorFallbackRegistered) return;
-		nativeSupervisorFallbackRegistered = true;
 		registerNativeSupervisorClient(pi);
 	};
 	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown, ctx?: ExtensionContext) => unknown) => void;
@@ -597,7 +596,6 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		const sessionManager = (ctx as { sessionManager?: Parameters<typeof resolveCurrentSessionId>[0] } | undefined)?.sessionManager;
 		waitState.currentSessionId = sessionManager ? resolveCurrentSessionId(sessionManager) : null;
 		registerNativeSupervisorClientOnce();
-		if (readRequiredChildTools()?.includes("intercom")) registerNativeSupervisorFallbackOnce();
 	});
 	onRuntimeEvent("agent_start", () => {
 		refreshChildToolDiagnostic(pi);
@@ -650,7 +648,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 
 	onRuntimeEvent("before_agent_start", async (event: unknown) => {
 		if (!event || typeof event !== "object" || !("systemPrompt" in event) || typeof event.systemPrompt !== "string") return undefined;
-		registerNativeSupervisorFallbackOnce();
+		registerNativeSupervisorClientOnce();
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(intercomSessionName);

package/src/runs/shared/subagent-startup-retry.ts

@@ -12,6 +12,7 @@ export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
 export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
 
 const SIGKILL_PROCESS_SIGNAL_ERROR = formatProcessSignalError("SIGKILL");
+const EXTENSION_REGISTRATION_CONFLICT_PATTERN = /Failed to load extension\b[^\n]*:\s*(?:Tool|Flag)\s+"[^"]+"\s+conflicts with\b/i;
 
 export interface SubagentStartupFailureEvidence {
 	exitCode: number | null | undefined;
@@ -31,6 +32,17 @@ export interface SubagentStartupFailureEvidence {
 	turnBudgetExceeded?: boolean;
 }
 
+export function formatSubagentExtensionConflictError(
+	error: string | undefined,
+	input: { agent: string; ambientExtensionsEnabled: boolean },
+): string | undefined {
+	if (!error || !input.ambientExtensionsEnabled || !EXTENSION_REGISTRATION_CONFLICT_PATTERN.test(error)) return error;
+	const settings = JSON.stringify({
+		subagents: { agentOverrides: { [input.agent]: { extensions: [] } } },
+	});
+	return `${error}\n\nSubagent startup loaded conflicting ambient Pi extensions. Retry this run after disabling ambient extension discovery for agent ${JSON.stringify(input.agent)} in project .pi/settings.json: ${settings}. Replace the empty array with only the required extension entry paths when this agent needs extension tools.`;
+}
+
 function hasUsage(usage: Usage): boolean {
 	return usage.input !== 0
 		|| usage.output !== 0

package/src/runs/shared/tool-timeout.ts

@@ -0,0 +1,93 @@
+export const TOOL_TIMEOUT_ENV = "PI_SUBAGENT_TOOL_TIMEOUT_MS";
+
+/** Maximum delay a Node.js timer accepts without overflow. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+export const DEFAULT_FAST_TOOL_TIMEOUT_MS = 300_000;
+
+export const DEFAULT_FAST_TOOL_TIMEOUT_TOOLS = new Set([
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"edit",
+	"write",
+	"structured_output",
+]);
+
+/** Tools whose normal job can be to wait for a person or another run. */
+export const TOOL_TIMEOUT_EXEMPT_TOOLS = new Set(["contact_supervisor", "intercom", "subagent_wait"]);
+
+// Backward-compatible export name for existing callers/tests.
+export const TOOL_TIMEOUT_ALLOWLIST = TOOL_TIMEOUT_EXEMPT_TOOLS;
+
+export function isToolTimeoutExempt(toolName: string | undefined): boolean {
+	return toolName !== undefined && TOOL_TIMEOUT_EXEMPT_TOOLS.has(toolName);
+}
+
+export function defaultToolTimeoutMs(toolName: string | undefined): number | undefined {
+	return toolName !== undefined && DEFAULT_FAST_TOOL_TIMEOUT_TOOLS.has(toolName)
+		? DEFAULT_FAST_TOOL_TIMEOUT_MS
+		: undefined;
+}
+
+export function effectiveToolTimeoutMs(toolName: string | undefined, configuredToolTimeoutMs: number | undefined): number | undefined {
+	if (isToolTimeoutExempt(toolName)) return undefined;
+	return configuredToolTimeoutMs ?? defaultToolTimeoutMs(toolName);
+}
+
+export function formatToolTimeoutMessage(toolName: string, timeoutMs: number): string {
+	return `Tool '${toolName}' exceeded its timeout of ${timeoutMs}ms.`;
+}
+
+export function toolTimeoutCallKey(event: { toolCallId?: unknown; toolName?: unknown }, fallbackId: number): string {
+	return typeof event.toolCallId === "string" && event.toolCallId.length > 0
+		? `id:${event.toolCallId}`
+		: `anon:${String(event.toolName ?? "tool")}:${fallbackId}`;
+}
+
+export interface ToolTimeoutResolutionInput {
+	/** Per-call value from the subagent tool params (highest precedence). */
+	callValue?: unknown;
+	/** Agent frontmatter default (second precedence). */
+	agentValue?: number;
+	/** Global extension config.toolTimeoutMs (third precedence). */
+	configValue?: unknown;
+	/** PI_SUBAGENT_TOOL_TIMEOUT_MS environment override (lowest precedence). */
+	envValue?: string | undefined;
+}
+
+/** Resolve the configured hard timeout. Default fast-tool timeouts apply later per tool name. */
+export function resolveToolTimeoutMs(input: ToolTimeoutResolutionInput): { toolTimeoutMs?: number; error?: string } {
+	const candidates: Array<{ label: string; value: unknown }> = [
+		{ label: "toolTimeoutMs", value: input.callValue },
+		{ label: "agent.toolTimeoutMs", value: input.agentValue },
+		{ label: "config.toolTimeoutMs", value: input.configValue },
+	];
+	let winner: { label: string; value: unknown } | undefined;
+	for (const candidate of candidates) {
+		if (candidate.value === undefined) continue;
+		winner = candidate;
+		break;
+	}
+	if (winner === undefined && input.envValue !== undefined && input.envValue.trim() !== "") {
+		winner = { label: TOOL_TIMEOUT_ENV, value: input.envValue };
+	}
+	if (winner === undefined) return {};
+
+	let raw: unknown = winner.value;
+	let parsed: number;
+	if (winner.label === TOOL_TIMEOUT_ENV && typeof raw === "string") {
+		parsed = Number(raw);
+		if (raw.trim() !== "" && !Number.isNaN(parsed)) raw = parsed;
+	}
+	if (typeof raw !== "number" || !Number.isInteger(raw) || raw <= 0 || raw > MAX_TIMER_DELAY_MS) {
+		return { error: `${winner.label} must be a positive integer no larger than ${MAX_TIMER_DELAY_MS}.` };
+	}
+	return { toolTimeoutMs: raw };
+}
+
+/** Read the environment override without requiring callers to know the name. */
+export function toolTimeoutFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	return env[TOOL_TIMEOUT_ENV];
+}

package/src/runs/shared/workflow-graph.ts

@@ -1,4 +1,4 @@
-import { isCheckpointStep, isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
+import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
 import type { SingleResult, SubagentRunMode, WorkflowGraphNode, WorkflowGraphSnapshot, WorkflowNodeStatus } from "../../shared/types.ts";
 
 export interface WorkflowGraphBuildInput {
@@ -81,28 +81,6 @@ export function buildWorkflowGraphSnapshot(input: WorkflowGraphBuildInput): Work
 
 	for (let stepIndex = 0; stepIndex < input.steps.length; stepIndex++) {
 		const step = input.steps[stepIndex]!;
-		if (isCheckpointStep(step)) {
-			const status = normalizeStatus(input.stepStatuses?.[flatIndex]?.status)
-				?? (input.currentStepIndex === stepIndex ? "paused" : "pending");
-			const checkpoint = { name: step.checkpoint, ...(step.message ? { message: step.message } : {}), status: status === "rejected" ? "rejected" as const : status === "completed" ? "approved" as const : "pending" as const, stepIndex };
-			const id = `step-${stepIndex}`;
-			nodes.push({
-				id,
-				kind: "checkpoint",
-				phase: step.phase,
-				label: step.label?.trim() || step.checkpoint,
-				status,
-				flatIndex,
-				stepIndex,
-				checkpoint,
-				error: input.stepStatuses?.[flatIndex]?.error,
-			});
-			pushPhase(phases, step.phase, id);
-			if (status === "paused" || input.currentStepIndex === stepIndex) currentNodeId = id;
-			flatIndex++;
-			continue;
-		}
-
 		if (isParallelStep(step)) {
 			const groupId = `step-${stepIndex}`;
 			const children: WorkflowGraphNode[] = [];

package/src/runs/shared/worktree.ts

@@ -46,7 +46,7 @@ export interface WorktreeCleanupTask {
 }
 
 export type WorktreeCleanupIntent =
-	| { kind: "preserve"; capturedDiffs?: WorktreeDiff[]; handoffManifestPath?: string }
+	| { kind: "preserve"; capturedDiffs?: WorktreeDiff[]; handoffManifestPath?: string; cleanupBlocker?: string }
 	| {
 		kind: "discard";
 		authorization:
@@ -571,6 +571,17 @@ function cleanupSingleWorktree(
 	const errors: string[] = [];
 	let worktreeRemoved = false;
 	let branchRemoved = false;
+	if (intent.kind === "preserve" && intent.cleanupBlocker) {
+		return {
+			index: worktree.index,
+			path: worktree.path,
+			branch: worktree.branch,
+			worktreeRemoved: false,
+			branchRemoved: false,
+			preserved: true,
+			reason: intent.cleanupBlocker,
+		};
+	}
 	if (intent.kind !== "setup-rollback") {
 		try {
 			removeSyntheticPathsBeforeDiff(worktree);

package/src/shared/atomic-json.ts

@@ -1,9 +1,12 @@
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, runFileSystemOperationWithRetry, waitForFileSystemRetry } from "./file-system-retry.ts";
 
 type AtomicJsonFs = Pick<typeof fs, "mkdirSync" | "writeFileSync" | "renameSync" | "rmSync">;
 
+const MAX_PATH_COMPONENT_BYTES = 255;
+
 type AtomicJsonWriterOptions = {
 	fs?: AtomicJsonFs;
 	now?: () => number;
@@ -28,6 +31,13 @@ function renameWithRetry(
 	}, { retryDelaysMs, wait });
 }
 
+function tempBaseName(filePath: string, pid: number, nowMs: number, randomId: string): string {
+	const suffix = `.${pid}.${nowMs}.${randomId}.tmp`;
+	const preferred = `.${path.basename(filePath)}${suffix}`;
+	if (Buffer.byteLength(preferred, "utf-8") <= MAX_PATH_COMPONENT_BYTES) return preferred;
+	return `.${createHash("sha256").update(path.basename(filePath)).digest("hex")}${suffix}`;
+}
+
 export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (filePath: string, payload: object) => void {
 	const fsImpl = options.fs ?? fs;
 	const now = options.now ?? Date.now;
@@ -46,13 +56,23 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 		}, { retryDelaysMs: directoryRetryDelaysMs, wait });
 		const tempPath = path.join(
 			path.dirname(filePath),
-			`.${path.basename(filePath)}.${pid}.${now()}.${random().toString(36).slice(2)}.tmp`,
+			tempBaseName(filePath, pid, now(), random().toString(36).slice(2)),
 		);
+		let writeError: unknown;
 		try {
 			fsImpl.writeFileSync(tempPath, JSON.stringify(payload, null, 2), mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
 			renameWithRetry(fsImpl, tempPath, filePath, renameRetryDelaysMs, wait);
+		} catch (error) {
+			writeError = error;
+			throw error;
 		} finally {
-			fsImpl.rmSync(tempPath, { force: true });
+			try {
+				fsImpl.rmSync(tempPath, { force: true });
+			} catch (cleanupError) {
+				// Preserve the write/rename failure: cleanup is best effort and must
+				// not hide the error callers need to classify or report.
+				if (writeError === undefined) throw cleanupError;
+			}
 		}
 	};
 }

package/src/shared/capacity-resilient-json.ts

@@ -0,0 +1,102 @@
+import { isStorageCapacityError } from "./file-system-retry.ts";
+import { writeAtomicJson } from "./atomic-json.ts";
+
+type TimerApi = {
+	setTimeout(handler: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+};
+
+const defaultTimerApi: TimerApi = {
+	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export type CapacityResilientJsonWriterOptions = {
+	/** The underlying write operation. It must be atomic for each target path. */
+	write?: (filePath: string, payload: object) => void;
+	/** Keep retry timers referenced by the event loop (needed by child runners). */
+	keepAlive?: boolean;
+	retryDelayMs?: number;
+	timerApi?: TimerApi;
+	onError?: (error: unknown, filePath: string) => void;
+	onSuccess?: (filePath: string, payload: object) => void;
+};
+
+export type CapacityResilientJsonWriter = {
+	write(filePath: string, payload: object, writeOperation?: (filePath: string, payload: object) => void): void;
+	pendingCount(): number;
+	dispose(): void;
+};
+
+/**
+ * Defers only storage-capacity failures, retaining the newest payload per path.
+ * Initial/ordinary writes remain synchronous and preserve their throwing contract;
+ * only ENOSPC-like failures enter the guarded retry loop.
+ */
+export function createCapacityResilientJsonWriter(options: CapacityResilientJsonWriterOptions = {}): CapacityResilientJsonWriter {
+	const defaultWrite = options.write ?? writeAtomicJson;
+	const keepAlive = options.keepAlive ?? false;
+	const retryDelayMs = options.retryDelayMs ?? 1_000;
+	const timerApi = options.timerApi ?? defaultTimerApi;
+	const onError = options.onError ?? ((error, filePath) => console.error(`Failed to persist JSON '${filePath}':`, error));
+	const onSuccess = options.onSuccess;
+	const reportError = (error: unknown, filePath: string): void => {
+		try {
+			onError(error, filePath);
+		} catch (callbackError) {
+			console.error(`Failed to report JSON persistence error for '${filePath}':`, callbackError);
+		}
+	};
+	const notifySuccess = (filePath: string, payload: object): void => {
+		if (!onSuccess) return;
+		try {
+			onSuccess(filePath, payload);
+		} catch (error) {
+			reportError(error, filePath);
+		}
+	};
+	const pending = new Map<string, { payload: object; write: (filePath: string, payload: object) => void }>();
+	let retryTimer: unknown;
+
+	const scheduleRetry = (): void => {
+		if (retryTimer !== undefined) return;
+		retryTimer = timerApi.setTimeout(() => {
+			retryTimer = undefined;
+			for (const [filePath, entry] of pending) {
+				try {
+					entry.write(filePath, entry.payload);
+					pending.delete(filePath);
+					notifySuccess(filePath, entry.payload);
+				} catch (error) {
+					if (isStorageCapacityError(error)) continue;
+					pending.delete(filePath);
+					reportError(error, filePath);
+				}
+			}
+			if (pending.size > 0) scheduleRetry();
+		}, retryDelayMs);
+		if (!keepAlive && typeof retryTimer === "object" && retryTimer !== null && "unref" in retryTimer && typeof retryTimer.unref === "function") {
+			retryTimer.unref();
+		}
+	};
+
+	return {
+		write(filePath, payload, writeOperation = defaultWrite): void {
+			try {
+				writeOperation(filePath, payload);
+				pending.delete(filePath);
+				notifySuccess(filePath, payload);
+			} catch (error) {
+				if (!isStorageCapacityError(error)) throw error;
+				pending.set(filePath, { payload, write: writeOperation });
+				scheduleRetry();
+			}
+		},
+		pendingCount: () => pending.size,
+		dispose: (): void => {
+			if (retryTimer !== undefined) timerApi.clearTimeout(retryTimer);
+			retryTimer = undefined;
+			pending.clear();
+		},
+	};
+}

package/src/shared/completion-owner.ts

@@ -0,0 +1,14 @@
+import { randomUUID } from "node:crypto";
+
+const COMPLETION_OWNER_KEY = Symbol.for("pi-subagents.completion-owner-id");
+
+type CompletionOwnerGlobal = typeof globalThis & {
+	[COMPLETION_OWNER_KEY]?: string;
+};
+
+/** Stable for one parent Pi process across extension reloads. */
+export function currentCompletionOwnerId(): string {
+	const runtime = globalThis as CompletionOwnerGlobal;
+	runtime[COMPLETION_OWNER_KEY] ??= randomUUID();
+	return runtime[COMPLETION_OWNER_KEY];
+}

package/src/shared/file-system-retry.ts

@@ -1,8 +1,51 @@
 const WAIT_BUFFER = typeof SharedArrayBuffer !== "undefined" ? new SharedArrayBuffer(4) : undefined;
 const WAIT_VIEW = WAIT_BUFFER ? new Int32Array(WAIT_BUFFER) : undefined;
 const RETRYABLE_FILE_SYSTEM_ERROR_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
+const STORAGE_CAPACITY_ERROR_CODES = new Set(["EDQUOT", "EMFILE", "ENFILE", "ENOSPC"]);
 
-export const DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
+export const FS_RETRY_MAX_TOTAL_MS_ENV = "PI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS";
+
+const BASE_FILE_SYSTEM_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
+
+/**
+ * Clamp the retry ladder to a total sleep budget, preserving its length.
+ *
+ * waitForFileSystemRetry blocks the calling thread, so the ladder above is also
+ * a ceiling on how long a single contended rename can stall that thread: about
+ * 7.9s. That is fine for a short-lived CLI. A long-lived host that loads this
+ * extension in-process runs the same writers on its event loop, where an 8s
+ * stall stops it serving anything at all -- and because Atomics.wait parks
+ * rather than spins, it presents as an unresponsive process at 0% CPU.
+ *
+ * The length is preserved deliberately: run-fanout-budget.ts and
+ * workflow-state.ts index this array by attempt number and treat running off
+ * the end as "timed out acquiring lock". Shortening it would quietly shrink
+ * those attempt budgets too, so only the sleeps shrink here.
+ *
+ * Unset by default, so behaviour is unchanged unless a host opts in. Opting in
+ * trades lock-wait tolerance for responsiveness: entries clamped to 0 return
+ * immediately, so contention that would previously have been waited out is
+ * surfaced as an error sooner.
+ */
+export function resolveFileSystemRetryDelays(
+	env: NodeJS.ProcessEnv = process.env,
+	base: readonly number[] = BASE_FILE_SYSTEM_RETRY_DELAYS_MS,
+): readonly number[] {
+	const raw = env[FS_RETRY_MAX_TOTAL_MS_ENV];
+	if (raw === undefined || raw.trim() === "") return base;
+	const budget = Number(raw);
+	if (!Number.isInteger(budget) || budget < 0) {
+		throw new Error(`${FS_RETRY_MAX_TOTAL_MS_ENV} must be a non-negative integer number of milliseconds.`);
+	}
+	let spent = 0;
+	return base.map((delayMs) => {
+		const allowed = Math.max(0, Math.min(delayMs, budget - spent));
+		spent += allowed;
+		return allowed;
+	});
+}
+
+export const DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS = resolveFileSystemRetryDelays();
 
 export type FileSystemRetryOptions = {
 	retryDelaysMs?: readonly number[];
@@ -32,6 +75,11 @@ export function isRetryableFileSystemError(error: unknown): boolean {
 	return typeof code === "string" && RETRYABLE_FILE_SYSTEM_ERROR_CODES.has(code);
 }
 
+export function isStorageCapacityError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return typeof code === "string" && STORAGE_CAPACITY_ERROR_CODES.has(code);
+}
+
 export function runFileSystemOperationWithRetry<T>(operation: () => T, options: FileSystemRetryOptions = {}): T {
 	const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS;
 	const wait = options.wait ?? waitForFileSystemRetry;

package/src/shared/fork-context.ts

@@ -56,6 +56,48 @@ export function resolveSubagentContext(value: unknown): SubagentExecutionContext
 	return value === "fork" ? "fork" : "fresh";
 }
 
+export interface PreferredForkAvailability {
+	getSessionFile(): string | undefined;
+	getLeafId?: () => string | null;
+}
+
+export interface PreferredForkSnapshot {
+	parentSessionFile?: string | null;
+	leafId?: string | null;
+}
+
+export interface SubagentLaunchContextInput {
+	explicitContext?: SubagentExecutionContext;
+	agentDefaultContext?: SubagentExecutionContext;
+	defaultSubagentContext?: SubagentExecutionContext;
+	canUseImplicitFork: boolean;
+}
+
+/** Resolve the actual launch context from explicit, global, and agent preferences. */
+export function resolveSubagentLaunchContext(input: SubagentLaunchContextInput): SubagentExecutionContext {
+	if (input.explicitContext !== undefined) return input.explicitContext;
+	const preferredContext = input.defaultSubagentContext ?? input.agentDefaultContext ?? "fresh";
+	return preferredContext === "fork" && input.canUseImplicitFork ? "fork" : "fresh";
+}
+
+/** True when an implicit `defaultContext: fork` can create a real branch now.
+ * Explicit `context: "fork"` stays strict and does not use this preference. */
+export function canPreferFork(sessionManager: PreferredForkAvailability): boolean {
+	return canPreferForkFromSnapshot({
+		parentSessionFile: sessionManager.getSessionFile(),
+		leafId: sessionManager.getLeafId?.() ?? null,
+	});
+}
+
+export function canPreferForkFromSnapshot(input: PreferredForkSnapshot): boolean {
+	if (!input.parentSessionFile || !input.leafId) return false;
+	try {
+		return fs.existsSync(input.parentSessionFile);
+	} catch {
+		return false;
+	}
+}
+
 /** Decide whether a resolved child model uses Anthropic's provider or message API, which
  * requires the sanitized fork to disable thinking. Unknown models stay conservative. */
 export function forkedChildRequiresThinkingOff(