pi-subagents 0.46.0 → 0.47.0

package/src/missions/workflow-state.ts

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writePrivateAtomicJson } from "../shared/atomic-json.ts";
-import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, waitForFileSystemRetry } from "../shared/file-system-retry.ts";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, isRetryableFileSystemError, waitForFileSystemRetry } from "../shared/file-system-retry.ts";
 import { assertWorkflowJsonValue } from "../workflows/scripted-workflow.ts";
 import type { MissionStoreLocation } from "./types.ts";
 import { validateMissionId } from "./store.ts";
@@ -162,24 +162,30 @@ function withStateFileLock<T>(filePath: string, operation: () => T): T {
 			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
 			continue;
 		}
+		let acquired = false;
 		try {
-			fs.mkdirSync(lockPath, { mode: 0o700 });
-			owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
-			try {
-				fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
-			} catch (error) {
-				removeOwnedStateLock(lockPath, owner);
-				owner = undefined;
-				throw error;
-			}
-			break;
+			acquired = tryMakeDirectory(lockPath, 0o700);
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-				throw new Error(`Failed to acquire mission state lock '${lockPath}': ${error instanceof Error ? error.message : String(error)}`);
+			if (isRetryableFileSystemError(error)) {
+				waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+				continue;
 			}
+			throw new Error(`Failed to acquire mission state lock '${lockPath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (!acquired) {
 			if (reclaimStaleStateLock(lockPath, reclaimPath)) continue;
 			waitForStateLock(DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS[attempt], lockPath);
+			continue;
+		}
+		owner = { pid: process.pid, token: randomUUID(), createdAt: Date.now(), ...(CURRENT_PROCESS_KEY ? { processKey: CURRENT_PROCESS_KEY } : {}) };
+		try {
+			fs.writeFileSync(path.join(lockPath, "owner.json"), JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
+		} catch (error) {
+			fs.rmSync(lockPath, { recursive: true, force: true });
+			owner = undefined;
+			throw error;
 		}
+		break;
 	}
 	try {
 		return operation();

package/src/runs/background/async-execution.ts

@@ -15,7 +15,7 @@ import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts"
 import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
 import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
 import { injectOutputPathSystemPrompt, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
-import { buildChainInstructions, isCheckpointStep, isDynamicParallelStep, isParallelStep, resolveChainPath, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
+import { buildChainInstructions, isCheckpointStep, isDynamicParallelStep, isParallelStep, resolveChainPath, resolveExistingReadPaths, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import type { ContextMode } from "../shared/context-mode.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
@@ -128,6 +128,8 @@ interface AsyncExecutionContext {
 	interactive?: boolean;
 }
 
+export const DEFAULT_ASYNC_TIMEOUT_MS = 30 * 60 * 1000;
+
 interface AsyncChainParams {
 	chain: ChainStep[];
 	task?: string;
@@ -668,6 +670,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		if (resolvedToolBudget.error) throw new AsyncStartValidationError(resolvedToolBudget.error);
 		const stepCwd = resolveChildCwd(runnerCwd, s.cwd);
 		const instructionCwd = behaviorCwd ?? stepCwd;
+		const readExistenceCwd = behaviorCwd ? stepCwd : instructionCwd;
 		let behavior = suppressProgressForReadOnlyTask(resolvedBehavior ?? resolveStepBehavior(a, buildStepOverrides(s), chainSkills), s.task, originalTask);
 		const inheritedRelativeParallelOutput = parallelOutputNamespace && s.output === undefined && typeof behavior.output === "string" && !path.isAbsolute(behavior.output);
 		if (inheritedRelativeParallelOutput && parallelOutputNamespace.taskIndex !== undefined) {
@@ -698,7 +701,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		}
 		systemPrompt = appendAgentRefinementOverlay(systemPrompt, { cwd: stepCwd, agentName: a.name });
 
-		const readInstructions = buildChainInstructions({ ...behavior, output: false, progress: false }, instructionCwd, false);
+		const readInstructions = buildChainInstructions({ ...behavior, output: false, progress: false }, instructionCwd, false, undefined, readExistenceCwd);
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
 		if (behavior.progress) progressInstructionCreated = true;
 		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, progressDir, isFirstProgressAgent);
@@ -776,6 +779,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 			outputMode: behavior.outputMode,
 			sessionFile,
 			maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
+			timeoutMs: a.defaultTimeoutMs ?? DEFAULT_ASYNC_TIMEOUT_MS,
 			waitToolEnabled: params.waitToolEnabled,
 			effectiveAcceptance: resolveEffectiveAcceptance({
 				explicit: s.acceptance,
@@ -1296,8 +1300,9 @@ export function executeAsyncSingle(
 	// Reads: caller override > agent defaultReads > none. `~`/`~/` expand to home;
 	// absolute paths pass through; relative paths resolve against the child cwd.
 	const reads = params.reads !== undefined ? params.reads : agentConfig.defaultReads ?? false;
-	const readsInstruction = Array.isArray(reads) && reads.length > 0
-		? `[Read from: ${reads.map((f) => resolveChainPath(f, runnerCwd)).join(", ")}]\n\n`
+	const readPaths = Array.isArray(reads) ? resolveExistingReadPaths(reads, runnerCwd) : [];
+	const readsInstruction = readPaths.length > 0
+		? `[Read from: ${readPaths.join(", ")}]\n\n`
 		: "";
 	const taskText = readsInstruction + taskWithOutputInstruction;
 	const primaryModel = externalRunner ? undefined : resolveSubagentModelOverride(
@@ -1399,7 +1404,7 @@ export function executeAsyncSingle(
 		...(params.acceptance !== undefined ? { acceptance: params.acceptance } : {}),
 		...(controlConfig ? { controlConfig } : {}),
 		...(deadlineAt !== undefined ? { absoluteDeadlineAt: deadlineAt } : {}),
-		...(initialTurnBudget ? { initialTurnBudget } : {}),
+		...(initialTurnBudget ? { initialTurnBudget: { maxTurns: initialTurnBudget.maxTurns, graceTurns: initialTurnBudget.graceTurns } } : {}),
 		...(resolvedToolBudget.budget ? { initialToolBudget: resolvedToolBudget.budget } : {}),
 		maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
 		...(maxOutput ? { maxOutput } : {}),

package/src/runs/background/async-job-tracker.ts

@@ -57,6 +57,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	const resultsDir = options.resultsDir ?? DIRS.results;
 	const steeringNoticeSeen = new Map<string, number>();
 	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
+		if (state.widgetsSuspended) return;
 		renderWidget(ctx, options.widgetEnabled === false ? [] : jobs);
 		(ctx.ui as { requestRender?: () => void }).requestRender?.();
 	};
@@ -73,6 +74,19 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			throw error;
 		}
 	};
+	const requestLastWidgetRender = () => {
+		const ctx = state.lastUiContext;
+		if (!ctx || state.widgetsSuspended || options.widgetEnabled === false) return;
+		try {
+			if (ctx.hasUI) (ctx.ui as { requestRender?: () => void }).requestRender?.();
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("extension ctx is stale")) {
+				state.lastUiContext = null;
+				return;
+			}
+			throw error;
+		}
+	};
 	const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
 	const restoredControlEventCursor = (asyncDir: string) => {
 		try {
@@ -400,6 +414,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			}
 
 			if (widgetChanged) rerenderLastWidget();
+			else if (Array.from(state.asyncJobs.values()).some((job) => job.status === "running")) requestLastWidgetRender();
 		}, pollIntervalMs);
 		state.poller.unref?.();
 	};

package/src/runs/background/async-resume.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DIRS, type AcceptanceInput, type AsyncStatus, type SteeringRecoveryDescriptor } from "../../shared/types.ts";
+import { DIRS, type AcceptanceInput, type AsyncStatus, type ResolvedTurnBudget, type SteeringRecoveryDescriptor } from "../../shared/types.ts";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { validateAcceptanceInput } from "../shared/acceptance.ts";
 import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
@@ -273,6 +273,23 @@ function normalizeRecoveryAcceptance(value: unknown, descriptorPath: string): Ac
 	return value as AcceptanceInput;
 }
 
+function normalizeRecoveryTurnBudget(value: unknown, descriptorPath: string): ResolvedTurnBudget {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const {
+			outcome: _outcome,
+			turnCount: _turnCount,
+			wrapUpRequestedAtTurn: _wrapUpRequestedAtTurn,
+			terminationDeferredAtTurn: _terminationDeferredAtTurn,
+			exceededAtTurn: _exceededAtTurn,
+			...publicTurnBudget
+		} = value as Record<string, unknown>;
+		value = publicTurnBudget;
+	}
+	const result = resolveTurnBudgetConfig(value, "recoveryDescriptor.initialTurnBudget");
+	if (result.error || !result.turnBudget) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error ?? "recoveryDescriptor.initialTurnBudget is invalid."}`);
+	return result.turnBudget;
+}
+
 export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): SteeringRecoveryDescriptor | undefined {
 	if (!asyncDir) return undefined;
 	const descriptorPath = path.join(asyncDir, "recovery-descriptor.json");
@@ -329,8 +346,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	}
 	if (parsed.absoluteDeadlineAt !== undefined && (!Number.isFinite(parsed.absoluteDeadlineAt) || (parsed.absoluteDeadlineAt as number) <= 0)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': absoluteDeadlineAt must be a positive timestamp.`);
 	if (parsed.initialTurnBudget !== undefined) {
-		const result = resolveTurnBudgetConfig(parsed.initialTurnBudget, "recoveryDescriptor.initialTurnBudget");
-		if (result.error) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error}`);
+		parsed.initialTurnBudget = normalizeRecoveryTurnBudget(parsed.initialTurnBudget, descriptorPath);
 	}
 	if (parsed.initialToolBudget !== undefined) {
 		const result = validateToolBudgetConfig(parsed.initialToolBudget, "recoveryDescriptor.initialToolBudget");

package/src/runs/background/async-status.ts

@@ -4,7 +4,7 @@ import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "
 import { formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.ts";
 import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type Details, type LaunchResolvedChildExtensionsV1, type RuntimeAcknowledgedChildExtensionsV1, type NestedRunSummary, type SteeringStatus, type SubagentRunMode, type TokenUsage, type TurnBudgetState, type UsageBudgetState, type ChainCheckpointState } from "../../shared/types.ts";
 import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../shared/capability-ceiling.ts";
-import { readStatus } from "../../shared/utils.ts";
+import { pruneStatusCacheForAsyncRoot, readStatus } from "../../shared/utils.ts";
 import { attachRootChildrenToSteps, buildNestedRouteIndex, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
@@ -370,6 +370,7 @@ function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
 
 export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions = {}): AsyncRunSummary[] {
 	let entries: string[];
+	let scannedCompleteRoot = false;
 	try {
 		if (options.runId !== undefined) {
 			const resolution = resolveTargetedAsyncRun(asyncDirRoot, options.runId, options.sessionId);
@@ -383,6 +384,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 					: [];
 		} else {
 			entries = fs.readdirSync(asyncDirRoot).filter((entry) => isAsyncRunDir(asyncDirRoot, entry));
+			scannedCompleteRoot = true;
 		}
 	} catch (error) {
 		if (isNotFoundError(error)) return [];
@@ -392,6 +394,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 	}
 
 	if (options.entryLimit !== undefined) {
+		scannedCompleteRoot = false;
 		const limit = Math.max(0, Math.floor(options.entryLimit));
 		entries = entries
 			.map((entry) => {
@@ -410,6 +413,8 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 			.map((candidate) => candidate.entry);
 	}
 
+	if (scannedCompleteRoot) pruneStatusCacheForAsyncRoot(asyncDirRoot, entries);
+
 	const allowedStates = options.states ? new Set(options.states) : undefined;
 	const runs: AsyncRunSummary[] = [];
 	// Route resolution for every run shares a single index built from the

package/src/runs/background/control-channel.ts

@@ -21,6 +21,16 @@ import { POLL_INTERVAL_MS } from "../../shared/types.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
 
 export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch" | "readdirSync" | "readFileSync" | "realpathSync">;
+
+function writeJsonToExistingDir(filePath: string, payload: object): void {
+	const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
+	try {
+		fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), { encoding: "utf-8", flag: "wx" });
+		fs.renameSync(tempPath, filePath);
+	} finally {
+		fs.rmSync(tempPath, { force: true });
+	}
+}
 export type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };
 type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
 
@@ -205,6 +215,13 @@ export function writeSteerRequestToDir(dir: string, request: SteerRequest): stri
 	return requestPath;
 }
 
+export function writeSteerRequestToExistingDir(dir: string, request: SteerRequest): string {
+	if (!validSteerRequest(request)) throw new Error("steer request is malformed or exceeds transport limits.");
+	const requestPath = path.join(dir, steerRequestFileName(request));
+	writeJsonToExistingDir(requestPath, request);
+	return requestPath;
+}
+
 export function writeSteerCapabilityAt(filePath: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
 	assertChildIndex(capability.index);
 	if (!Number.isInteger(capability.pid) || capability.pid <= 0) throw new Error("steer capability pid must be a positive integer.");
@@ -385,6 +402,25 @@ export function consumeSteerCapabilities(asyncDir: string, fsImpl: Pick<typeof f
 	return capabilities;
 }
 
+export function consumeSteerAckFromDir(
+	dir: string,
+	requestId: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs,
+): SteerAck | undefined {
+	if (!fsImpl.existsSync(dir)) return undefined;
+	let entries: string[];
+	try { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); } catch { return undefined; }
+	for (const entry of entries) {
+		const target = path.join(dir, entry);
+		let ack: SteerAck | undefined;
+		try { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, "utf-8"))); } catch { ack = undefined; }
+		if (ack?.requestId !== requestId) continue;
+		try { fsImpl.rmSync(target, { force: true }); } catch { return undefined; }
+		return ack;
+	}
+	return undefined;
+}
+
 export function consumeSteerAcks(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs): SteerAck[] {
 	const root = path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR);
 	if (!fsImpl.existsSync(root)) return [];

package/src/runs/background/result-watcher.ts

@@ -126,6 +126,7 @@ export function createResultWatcher(
 	const processing = new Set<string>();
 	let deliveryActive = true;
 	let deliveryEpoch = 0;
+	let resultScanTimer: ReturnType<typeof setInterval> | null = null;
 	// The sole in-memory ownership lease. It is acquired for one active session
 	// and revoked before the watcher, queues, or callbacks are torn down.
 	let activeSessionId: string | null = null;
@@ -343,9 +344,15 @@ export function createResultWatcher(
 		}
 	};
 
+	const clearResultScan = () => {
+		if (resultScanTimer) timers.clearInterval(resultScanTimer);
+		resultScanTimer = null;
+	};
+
 	const startPolling = (reason: unknown) => {
 		state.watcher?.close();
 		state.watcher = null;
+		clearResultScan();
 		if (state.watcherRestartTimer) return;
 		console.error(`Subagent result watcher for '${resultsDir}' fell back to polling because native fs.watch is unavailable (${errorCode(reason) ?? "unknown error"}).`);
 		primeExistingResults();
@@ -354,6 +361,7 @@ export function createResultWatcher(
 	};
 
 	const scheduleRestart = () => {
+		clearResultScan();
 		if (state.watcherRestartTimer) return;
 		state.watcherRestartTimer = timers.setTimeout(() => {
 			state.watcherRestartTimer = null;
@@ -381,8 +389,11 @@ export function createResultWatcher(
 		}
 		try {
 			const watchDir = resolveWatchPath(resultsDir, fsApi.realpathSync.native);
-			state.watcher = fsApi.watch(watchDir, (event, file) => {
-				if (event !== "rename" || !file) return;
+			state.watcher = fsApi.watch(watchDir, (_event, file) => {
+				if (!file) {
+					primeExistingResults();
+					return;
+				}
 				const fileName = file.toString();
 				if (fileName.endsWith(".json")) scheduleResult(fileName, true);
 			});
@@ -394,6 +405,8 @@ export function createResultWatcher(
 				scheduleRestart();
 			});
 			state.watcher.unref?.();
+			resultScanTimer = timers.setInterval(primeExistingResults, POLL_INTERVAL_MS);
+			resultScanTimer.unref?.();
 		} catch (error) {
 			if (shouldPoll(error)) return startPolling(error);
 			console.error(`Failed to start subagent result watcher for '${resultsDir}':`, error);
@@ -413,6 +426,7 @@ export function createResultWatcher(
 			timers.clearInterval(state.watcherRestartTimer);
 		}
 		state.watcherRestartTimer = null;
+		clearResultScan();
 		state.resultFileCoalescer.clear();
 		pendingTriggerTurn.clear();
 		processing.clear();

package/src/runs/background/scheduled-runs.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getProjectSubagentsDir } from "../../shared/artifacts.ts";
 import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
 import { shortenPath } from "../../shared/formatters.ts";
 import type { AsyncStatus, Details, ExtensionConfig } from "../../shared/types.ts";
@@ -87,7 +88,7 @@ export function scheduledRunsEnabled(config: ExtensionConfig): boolean {
 }
 
 export function scheduledRunStorePath(cwd: string, _sessionId?: string, root?: string): string {
-	if (!root) return path.join(path.resolve(cwd), ".pi-subagents", "schedules");
+	if (!root) return path.join(getProjectSubagentsDir(path.resolve(cwd)), "schedules");
 	const projectKey = createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 20);
 	return path.join(root, projectKey);
 }

package/src/runs/background/stale-run-reconciler.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { readStatus } from "../../shared/utils.ts";
 import { DIRS, type AsyncParallelGroupStatus, type AsyncStatus, type NestedRunSummary, type SubagentRunMode } from "../../shared/types.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { normalizeParallelGroups } from "./parallel-groups.ts";
@@ -84,26 +85,6 @@ function appendJsonlBestEffort(filePath: string, payload: object): void {
 	}
 }
 
-function readStatusFile(asyncDir: string): AsyncStatus | null {
-	const statusPath = path.join(asyncDir, "status.json");
-	let content: string;
-	try {
-		content = fs.readFileSync(statusPath, "utf-8");
-	} catch (error) {
-		if (isNotFoundError(error)) return null;
-		throw new Error(`Failed to read async status file '${statusPath}': ${getErrorMessage(error)}`, {
-			cause: error instanceof Error ? error : undefined,
-		});
-	}
-	try {
-		return JSON.parse(content) as AsyncStatus;
-	} catch (error) {
-		throw new Error(`Failed to parse async status file '${statusPath}': ${getErrorMessage(error)}`, {
-			cause: error instanceof Error ? error : undefined,
-		});
-	}
-}
-
 interface ResultChildOutcome {
 	agent?: string;
 	success?: boolean;
@@ -348,7 +329,7 @@ export function checkPidLiveness(pid: number, kill: KillFn = process.kill): PidL
 
 export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOptions = {}): ReconcileAsyncRunResult {
 	const now = options.now?.() ?? Date.now();
-	const status = readStatusFile(asyncDir);
+	const status = readStatus(asyncDir);
 	const startedStatus = !status && options.startedRun ? buildStartedStatus(asyncDir, options.startedRun, now) : undefined;
 	const effectiveStatus = status ?? startedStatus;
 	if (!effectiveStatus) return { status: null, repaired: false };

package/src/runs/background/subagent-runner.ts

@@ -1955,6 +1955,47 @@ function combinedAbortSignal(signals: Array<AbortSignal | undefined>): AbortSign
 	return controller.signal;
 }
 
+async function runSingleStepWithTimeout(
+	step: SubagentStep,
+	ctx: SingleStepContext,
+	parentDeadlineAt?: number,
+): Promise<SingleStepResult> {
+	if (step.timeoutMs === undefined) return runSingleStep(step, ctx);
+
+	const parentRemainingMs = parentDeadlineAt === undefined ? undefined : Math.max(0, parentDeadlineAt - Date.now());
+	const timeoutMs = parentRemainingMs === undefined ? step.timeoutMs : Math.min(step.timeoutMs, parentRemainingMs);
+	const timeoutMessage = parentRemainingMs !== undefined && parentRemainingMs <= step.timeoutMs
+		? ctx.timeoutMessage
+		: `Subagent timed out after ${step.timeoutMs}ms.`;
+	const timeoutController = new AbortController();
+	let timeoutAction: (() => void) | undefined;
+	let timeoutTriggered = false;
+	const triggerTimeout = (): void => {
+		if (timeoutTriggered) return;
+		timeoutTriggered = true;
+		timeoutController.abort();
+		timeoutAction?.();
+	};
+	const registerTimeout = (action: (() => void) | undefined): void => {
+		timeoutAction = action;
+		ctx.registerTimeout?.(action ? triggerTimeout : undefined);
+		if (action && timeoutTriggered) action();
+	};
+	const timer = setTimeout(triggerTimeout, timeoutMs);
+	timer.unref?.();
+	try {
+		return await runSingleStep(step, {
+			...ctx,
+			registerTimeout,
+			timeoutSignal: combinedAbortSignal([ctx.timeoutSignal, timeoutController.signal]),
+			timeoutMessage,
+		});
+	} finally {
+		clearTimeout(timer);
+		ctx.registerTimeout?.(undefined);
+	}
+}
+
 async function runSubagent(
 	config: SubagentRunConfig,
 	onWriterProcess?: (writer: { state: "none" | "spawning" } | { state: "running"; pid: number }) => void,
@@ -3449,7 +3490,7 @@ async function runSubagent(
 				writeStatusPayload();
 				appendJsonl(eventsPath, JSON.stringify({ type: "subagent.step.started", ts: taskStartTime, runId: id, stepIndex: fi, agent: task.agent }));
 				flushPendingStepSteers(fi);
-				const singleResult = await runSingleStep(task, compactOptional<SingleStepContext>({
+				const singleResult = await runSingleStepWithTimeout(task, compactOptional<SingleStepContext>({
 					previousOutput, placeholder, cwd, sessionEnabled,
 					outputs,
 					sessionDir: config.sessionDir ? path.join(config.sessionDir, `dynamic-${stepIndex}-${taskIdx}`) : undefined,
@@ -3479,7 +3520,7 @@ async function runSubagent(
 					onWriterProcess,
 					onExternalProcess: (process) => updateExternalProcess(fi, process),
 					skipAcceptance: () => timedOut || stopped,
-				}));
+				}), config.deadlineAt);
 				const taskEndTime = Date.now();
 				const childInterrupted = singleResult.interrupted === true;
 				const childStopped = singleResult.stopped === true;
@@ -3831,7 +3872,7 @@ async function runSubagent(
 						const { taskForRun, taskCwd } = prepareParallelTaskRun(task, cwd, worktreeSetup, taskIdx);
 						flushPendingStepSteers(fi);
 
-						const singleResult = await runSingleStep(taskForRun, compactOptional<SingleStepContext>({
+						const singleResult = await runSingleStepWithTimeout(taskForRun, compactOptional<SingleStepContext>({
 							previousOutput, placeholder, cwd: taskCwd, sessionEnabled,
 							outputs,
 							sessionDir: taskSessionDir,
@@ -3861,7 +3902,7 @@ async function runSubagent(
 							onWriterProcess,
 							onExternalProcess: (process) => updateExternalProcess(fi, process),
 							skipAcceptance: () => timedOut || stopped,
-						}));
+						}), config.deadlineAt);
 						if (task.sessionFile) {
 							latestSessionFile = task.sessionFile;
 						}
@@ -4120,7 +4161,7 @@ async function runSubagent(
 			}));
 
 			flushPendingStepSteers(flatIndex);
-			const singleResult = await runSingleStep(seqStep, compactOptional<SingleStepContext>({
+			const singleResult = await runSingleStepWithTimeout(seqStep, compactOptional<SingleStepContext>({
 				previousOutput, placeholder, cwd, sessionEnabled,
 				outputs: statusPayload.mode === "single" ? undefined : outputs,
 				sessionDir: config.sessionDir,
@@ -4150,7 +4191,7 @@ async function runSubagent(
 				onWriterProcess,
 				onExternalProcess: (process) => updateExternalProcess(flatIndex, process),
 				skipAcceptance: () => timedOut || stopped,
-			}));
+			}), config.deadlineAt);
 			if (seqStep.sessionFile) {
 				latestSessionFile = seqStep.sessionFile;
 			}

package/src/runs/foreground/async-steering-action.ts

@@ -220,7 +220,7 @@ export async function steerAsyncRun(input: {
 			const revived = await input.recover(limits);
 			if (revived.isError || !revived.details.asyncId) throw new Error(revived.content[0]?.type === "text" ? revived.content[0].text : "Replacement launch failed; source run remains paused.");
 			const sourceStatus = readStatus(asyncDir);
-			const targetIndex = input.index ?? status.steps?.findIndex((step) => step.status === "running") ?? -1;
+			const targetIndex = input.index ?? sourceStatus?.steering?.recent.find((request) => request.id === requestId)?.targets[0]?.index ?? status.steps?.findIndex((step) => step.status === "running") ?? -1;
 			if (sourceStatus?.state === "paused" && sourceStatus.steering && targetIndex >= 0) {
 				updateSteeringTarget(sourceStatus.steering, requestId, targetIndex, "recovered", Date.now(), { replacementRunId: revived.details.asyncId });
 				const stepSteering = sourceStatus.steps?.[targetIndex]?.steering;

package/src/runs/foreground/chain-execution.ts

@@ -34,6 +34,7 @@ import {
 import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
 import { INTERCOM_BRIDGE_MARKER } from "../../intercom/intercom-bridge.ts";
 import { runSync } from "./execution.ts";
+import { workflowForegroundSteeringLaunchOptions } from "./workflow-foreground-steering.ts";
 import {
 	beginForegroundChild,
 	finishForegroundChild,
@@ -387,6 +388,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
 				permissions: input.permissions,
 				parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
+				...workflowForegroundSteeringLaunchOptions(input.foregroundControl, childIndex),
 				capabilityCeiling: input.capabilityCeiling,
 				context: input.contextForAgent?.(task.agent),
 				cwd: taskCwd,
@@ -1367,6 +1369,7 @@ ${step.message}` : ""}` }],
 				r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
 				permissions: params.permissions,
 				parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
+				...workflowForegroundSteeringLaunchOptions(params.foregroundControl, childIndex),
 				capabilityCeiling: params.capabilityCeiling,
 				context: params.contextForAgent?.(seqStep.agent),
 				cwd: resolveChildCwd(cwd ?? ctx.cwd, seqStep.cwd),

package/src/runs/foreground/execution.ts

@@ -338,6 +338,9 @@ async function runSingleAttempt(
 		parentRootRunId: options.nestedRoute?.rootRunId,
 		parentCapabilityToken: options.nestedRoute?.capabilityToken,
 		parentSessionId: options.parentSessionId,
+		steerInboxDir: options.steerInboxDir,
+		steerCapabilityPath: options.steerCapabilityPath,
+		steerAckDir: options.steerAckDir,
 		structuredOutput: options.structuredOutput,
 		toolBudget: options.toolBudget,
 		allowZeroToolBudget: options.allowZeroToolBudget,