pi-subagents 0.50.0 → 0.52.0

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(

package/src/shared/prompt-resources.ts

@@ -1,14 +1,7 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseFrontmatter } from "../agents/frontmatter.ts";
 import { getAgentDir, getProjectConfigDir } from "./utils.ts";
 
-const PROMPT_REF_PATTERN = /^(package|user|project):([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/;
-const PROMPT_VARIABLE_PATTERN = /\{\{(\w+)\}\}/g;
-
-type PromptVariable = string | number | boolean;
-
 export function getPromptDirectories(cwd: string) {
 	return {
 		package: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts"),
@@ -16,36 +9,3 @@ export function getPromptDirectories(cwd: string) {
 		project: path.join(getProjectConfigDir(cwd), "prompts"),
 	};
 }
-
-function promptVariables(vars: unknown): Record<string, PromptVariable> {
-	if (vars === undefined) return {};
-	if (!vars || typeof vars !== "object" || Array.isArray(vars)) throw new Error("prompts.render vars must be a plain object.");
-	const prototype = Object.getPrototypeOf(vars);
-	if (prototype !== null && prototype !== Object.prototype) throw new Error("prompts.render vars must be a plain object.");
-	for (const [name, value] of Object.entries(vars)) {
-		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
-			throw new Error(`prompts.render variable '${name}' must be a string, number, or boolean.`);
-		}
-	}
-	return vars as Record<string, PromptVariable>;
-}
-
-export function renderWorkflowPrompt(ref: string, vars: unknown, cwd: string): string {
-	const match = ref.match(PROMPT_REF_PATTERN);
-	if (!match) throw new Error("prompts.render ref must use package:<name>, user:<name>, or project:<name>.");
-	const scope = match[1] as keyof ReturnType<typeof getPromptDirectories>;
-	const name = match[2]!;
-	const filePath = path.join(getPromptDirectories(cwd)[scope], `${name}.md`);
-	let content: string;
-	try {
-		if (!fs.lstatSync(filePath).isFile()) throw new Error("not a regular file");
-		content = fs.readFileSync(filePath, "utf-8");
-	} catch (error) {
-		const detail = error instanceof Error ? error.message : String(error);
-		throw new Error(`Could not read prompt fragment '${ref}': ${detail}`);
-	}
-	const variables = promptVariables(vars);
-	return parseFrontmatter(content).body.trim().replace(PROMPT_VARIABLE_PATTERN, (placeholder, variable: string) => {
-		return Object.hasOwn(variables, variable) ? String(variables[variable]) : placeholder;
-	});
-}

package/src/shared/settings.ts

@@ -64,6 +64,8 @@ export interface SequentialStep {
 	acceptance?: AcceptanceInput;
 	agentContract?: AgentContract;
 	gateOn?: ChainGateLayer;
+	/** Internal workflow child isolation; public workflowScript supplies this on runs.run. */
+	worktree?: boolean;
 }
 
 /** Parallel task item within a parallel step */
@@ -119,24 +121,6 @@ export interface DynamicParallelStep {
 	gateOn?: ChainGateLayer;
 }
 
-/** Approval checkpoint: pause before later chain steps until parent approval. */
-export interface CheckpointStep {
-	checkpoint: string;
-	message?: string;
-	phase?: string;
-	label?: string;
-	agent?: string;
-	task?: string;
-	as?: string;
-	output?: OutputOverrideInput;
-	outputMode?: OutputMode;
-	reads?: string[] | false;
-	progress?: boolean;
-	skill?: string | string[] | false;
-	skills?: string[] | false;
-	model?: string;
-}
-
 /** Parallel step: multiple agents running concurrently */
 export interface ParallelStep {
 	parallel: ParallelTaskItem[];
@@ -149,16 +133,12 @@ export interface ParallelStep {
 }
 
 /** Union type for chain steps */
-export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep | CheckpointStep;
+export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep;
 
 // =============================================================================
 // Type Guards
 // =============================================================================
 
-export function isCheckpointStep(step: ChainStep): step is CheckpointStep {
-	return "checkpoint" in step;
-}
-
 export function isParallelStep(step: ChainStep): step is ParallelStep {
 	return "parallel" in step && Array.isArray((step as ParallelStep).parallel);
 }
@@ -169,9 +149,6 @@ export function isDynamicParallelStep(step: ChainStep): step is DynamicParallelS
 
 /** Get all agent names in a step (single for sequential, multiple for parallel) */
 export function getStepAgents(step: ChainStep): string[] {
-	if (isCheckpointStep(step)) {
-		return [];
-	}
 	if (isParallelStep(step)) {
 		return step.parallel.map((t) => t.agent);
 	}
@@ -239,7 +216,6 @@ export function resolveChainTemplates(
 	steps: ChainStep[],
 ): ResolvedTemplates {
 	return steps.map((step, i) => {
-		if (isCheckpointStep(step)) return "";
 		if (isParallelStep(step)) {
 			// Parallel step: resolve each task's template
 			return step.parallel.map((task) => {

package/src/shared/types.ts

@@ -41,7 +41,7 @@ export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed"
 
 export interface WorkflowGraphNode {
 	id: string;
-	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent" | "checkpoint";
+	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
 	agent?: string;
 	phase?: string;
 	label: string;
@@ -61,16 +61,6 @@ export interface WorkflowGraphNode {
 	structured?: boolean;
 	acceptanceStatus?: AcceptanceLedgerStatus;
 	error?: string;
-	checkpoint?: ChainCheckpointState;
-}
-
-export interface ChainCheckpointState {
-	name: string;
-	message?: string;
-	status: "pending" | "approved" | "rejected";
-	stepIndex: number;
-	approvedAt?: number;
-	rejectedAt?: number;
 }
 
 export interface WorkflowGraphSnapshot {
@@ -224,6 +214,10 @@ export interface ControlEvent {
 	currentPath?: string;
 	elapsedMs?: number;
 	recentFailureSummary?: string;
+	workflowKey?: string;
+	phase?: string;
+	label?: string;
+	taskPreview?: string;
 }
 
 export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
@@ -282,7 +276,7 @@ export interface ParallelHandoffGroup {
 export interface ParallelHandoffManifest {
 	version: 1;
 	runId: string;
-	mode: "parallel" | "chain";
+	mode: "single" | "parallel" | "chain";
 	source: "foreground" | "async";
 	cwd: string;
 	createdAt: number;
@@ -415,6 +409,12 @@ export type ProcessTerminalV1 =
 		diagnostic?: string;
 	});
 
+/** Identifies the durable schedule that launched a run, so its completion is attributable. */
+export interface ScheduleOrigin {
+	id: string;
+	name?: string;
+}
+
 export type SteeringActionState = "delivered" | "scheduled" | "pending" | "partial" | "recovered" | "failed";
 export type SteeringTargetState = "scheduled" | "pending" | "routed" | "queued" | "delivered" | "late" | "failed" | "recovered";
 
@@ -508,6 +508,7 @@ export interface SteeringRecoveryDescriptor {
 	sessionFile?: string;
 	cwd: string;
 	model?: string;
+	modelOverrideFromParent?: boolean;
 	fallbackModels?: string[];
 	thinking?: string;
 	tools?: string[];
@@ -1057,7 +1058,6 @@ export interface Details {
 	totalSteps?: number;         // Total steps in chain
 	currentStepIndex?: number;   // 0-indexed current step (for running chains)
 	workflowGraph?: WorkflowGraphSnapshot;
-	checkpoint?: ChainCheckpointState;
 	outputs?: ChainOutputMap;
 	// Aggregated child usage across all agents in the run
 	totalChildUsage?: Usage;
@@ -1087,9 +1087,9 @@ export interface Details {
 	workflow?: {
 		value?: unknown;
 		trace: Array<{
-			operation: "run" | "status";
+			operation: "run" | "status" | "steer";
 			key: string;
-			state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused";
+			state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
 			agent?: string;
 			runId?: string;
 			phase?: string;
@@ -1266,6 +1266,7 @@ export interface AsyncStartedEvent {
 	sessionRoot?: string;
 	pid?: number;
 	sessionId?: string;
+	completionOwnerId?: string;
 	mode?: SubagentRunMode;
 	agent?: string;
 	agents?: string[];
@@ -1277,7 +1278,6 @@ export interface AsyncStartedEvent {
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	workflowGraph?: WorkflowGraphSnapshot;
-	checkpoint?: ChainCheckpointState;
 	launchContractDigest?: string;
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1298,6 +1298,11 @@ export type AgentRunnerConfig =
 		command: string;
 		args?: string[];
 		promptDelivery?: "stdin";
+	}
+	| {
+		type: "external-job";
+		provider: string;
+		options?: Record<string, unknown>;
 	};
 
 export interface ExternalCliRunnerStatus {
@@ -1314,6 +1319,35 @@ export interface ExternalCliRunnerStatus {
 	};
 }
 
+export interface ExternalJobRunnerStatus {
+	type: "external-job";
+	provider: string;
+	options: Record<string, unknown>;
+	capabilities: {
+		stop: false;
+		steer: false;
+		resume: false;
+		structuredOutput: false;
+		toolEvents: false;
+	};
+}
+
+export interface ExternalJobStatus {
+	provider: string;
+	providerJobId?: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	handleUrl?: string;
+	conversationUrl?: string;
+	resultArtifactPath?: string;
+	state: "queued" | "running" | "completed" | "failed" | "stopped" | "blocked";
+	failureCode?: string;
+	failureMessage?: string;
+	blockingJobId?: string;
+	startedAt?: number;
+	updatedAt?: number;
+}
+
 export interface ExternalProcessStatus {
 	pid?: number;
 	startedAt: number;
@@ -1328,6 +1362,8 @@ export interface ExternalProcessStatus {
 export interface AsyncStatus {
 	lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
 	runId: string;
+	/** Parent Pi process/window that owns local completion delivery. */
+	completionOwnerId?: string;
 	/** Host tool-call id retained when it differs from the internal run id. */
 	toolCallId?: string;
 	sessionId?: string;
@@ -1361,12 +1397,13 @@ export interface AsyncStatus {
 	usageBudget?: UsageBudgetState;
 	pid?: number;
 	cwd?: string;
+	/** Parent-resolved child session root retained for trusted restored transcript lookup. */
+	sessionRoot?: string;
 	currentStep?: number;
 	chainStepCount?: number;
 	pendingAppends?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	workflowGraph?: WorkflowGraphSnapshot;
-	checkpoint?: ChainCheckpointState;
 	processTerminal?: ProcessTerminalV1;
 	runFanoutBudget?: RunFanoutBudgetSnapshot;
 	runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
@@ -1378,10 +1415,13 @@ export interface AsyncStatus {
 	workflow?: Details["workflow"];
 	parentWorkflowRunId?: string;
 	workflowKey?: string;
+	/** Set when a durable schedule launched this run, so completions can name their origin. */
+	scheduleOrigin?: ScheduleOrigin;
 	steps?: Array<{
 		agent: string;
-		runner?: ExternalCliRunnerStatus;
+		runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
 		externalProcess?: ExternalProcessStatus;
+		externalJob?: ExternalJobStatus;
 		/** Resolved launch context for this child step. */
 		context?: "fresh" | "fork";
 		/** Short caller-facing task/goal shown in fleet surfaces when available. */
@@ -1396,7 +1436,6 @@ export interface AsyncStatus {
 		parentWorkflowRunId?: string;
 		outputName?: string;
 		structured?: boolean;
-		checkpoint?: ChainCheckpointState;
 		status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
 		children?: NestedRunSummary[];
 		sessionFile?: string;
@@ -1476,6 +1515,7 @@ export interface AsyncJobState {
 	description?: string;
 	pid?: number;
 	sessionId?: string;
+	completionOwnerId?: string;
 	activityState?: ActivityState;
 	lastActivityAt?: number;
 	currentTool?: string;
@@ -1492,7 +1532,6 @@ export interface AsyncJobState {
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	steps?: AsyncJobStep[];
-	checkpoint?: ChainCheckpointState;
 	stepsTotal?: number;
 	runningSteps?: number;
 	completedSteps?: number;
@@ -1570,7 +1609,6 @@ export interface ForegroundResumeRun {
 	/** Originating parent session. Detached exits can outlive the active session. */
 	sessionId?: string;
 	updatedAt: number;
-	checkpoint?: ChainCheckpointState;
 	children: ForegroundResumeChild[];
 }
 
@@ -1663,6 +1701,8 @@ export interface ActiveAsyncCapacitySnapshot {
 export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
+	/** Reload-stable identity for this parent Pi process/window. */
+	completionOwnerId?: string;
 	/** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
 	artifactDirPreference?: ArtifactDirPreference;
 	/** Runtime authority snapshot used by optional inspector controls. */
@@ -1811,6 +1851,8 @@ export interface RunSyncOptions {
 	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
+	/** The override came from the running parent session, not configuration. */
+	modelOverrideFromParent?: boolean;
 	/** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
 	llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
 	/** Override the agent's default thinking level for this run */
@@ -1915,6 +1957,8 @@ export interface MainWindowRendererConfig {
 
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
+	/** Set the context for launches that omit an explicit context. */
+	defaultSubagentContext?: "fresh" | "fork";
 	/** Optional shortcut that detaches the active foreground single-subagent run. */
 	foregroundDetachShortcut?: string;
 	/** Show the Claude Code-style navigable fleet. Defaults to true. */
@@ -1925,10 +1969,8 @@ export interface ExtensionConfig {
 	fleetKeybindings?: FleetKeybindingsConfig;
 	/** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
 	asyncWidget?: boolean;
-	/** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
+	/** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
 	toolDescriptionMode?: ToolDescriptionMode;
-	/** Include legacy append-step and checkpoint controls in the registered tool schema. Defaults to false. */
-	legacyChainControls?: boolean;
 	/** Inline chat rendering for the subagent tool. Defaults to rich. */
 	inlineToolDisplay?: InlineToolDisplay;
 	/** Density controls for the main chat subagent call/result renderer. */
@@ -2067,7 +2109,10 @@ export function resolveTempScopeId(options?: {
 
 const MAX_PARALLEL = 8;
 export const MAX_CONCURRENCY = 4;
-export const TEMP_ROOT_DIR = path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
+const configuredTempRoot = process.env.PI_SUBAGENTS_TEMP_ROOT?.trim();
+export const TEMP_ROOT_DIR = configuredTempRoot
+	? path.resolve(configuredTempRoot)
+	: path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
 export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
 export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
 export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
@@ -2090,7 +2135,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
 export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
-export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
+export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
 	"You are a delegated subagent running from a fork of the parent session. " +

package/src/shared/utils.ts

@@ -102,6 +102,7 @@ export function getAgentDir(): string {
 }
 
 const statusCache = new Map<string, { mtime: number; ctime: number; size: number; ino: number; status: AsyncStatus }>();
+const MAX_STATUS_CACHE_ENTRIES = 512;
 
 export function pruneStatusCacheForAsyncRoot(asyncDirRoot: string, runIds: Iterable<string>): number {
 	const root = path.resolve(asyncDirRoot);
@@ -163,6 +164,8 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
 		&& cached.size === stat.size
 		&& cached.ino === stat.ino
 	) {
+		statusCache.delete(statusPath);
+		statusCache.set(statusPath, cached);
 		return cached.status;
 	}
 
@@ -195,6 +198,11 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
 		ino: stat.ino,
 		status,
 	});
+	while (statusCache.size > MAX_STATUS_CACHE_ENTRIES) {
+		const oldest = statusCache.keys().next().value as string | undefined;
+		if (oldest === undefined) break;
+		statusCache.delete(oldest);
+	}
 	return status;
 }
 

package/src/shared/watch-strategy.ts

@@ -0,0 +1,10 @@
+export type FileWatchPurpose =
+	| "result-delivery"
+	| "supervisor-channel"
+	| "async-job-tracker"
+	| "runner-control-inbox"
+	| "child-steering-inbox";
+
+export function shouldUseNativeFsWatch(_purpose: FileWatchPurpose, platform: NodeJS.Platform = process.platform): boolean {
+	return platform !== "darwin";
+}