pi-subagents 0.47.1 → 0.48.0

package/src/runs/background/owned-process-tree.ts

@@ -0,0 +1,104 @@
+import { spawnSync } from "node:child_process";
+import type { ProcessTreeTerminalV1 } from "../../shared/types.ts";
+
+const DEFAULT_TERM_GRACE_MS = 3000;
+const DEFAULT_KILL_VERIFY_MS = 1000;
+const VERIFY_INTERVAL_MS = 25;
+
+type SignalResult = "sent" | "absent" | { diagnostic: string };
+
+function diagnostic(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function signalProcess(id: number, signal: NodeJS.Signals): SignalResult {
+	try {
+		process.kill(id, signal);
+		return "sent";
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ESRCH") return "absent";
+		return { diagnostic: diagnostic(error) };
+	}
+}
+
+function activeProcessGroupMembers(processGroupId: number): number[] | { diagnostic: string } {
+	const result = spawnSync("ps", ["-axo", "pid=,pgid=,stat="], { encoding: "utf-8" });
+	if (result.error || result.status !== 0) {
+		return { diagnostic: result.error ? diagnostic(result.error) : (result.stderr.trim() || `ps exited with ${result.status}`) };
+	}
+	const members: number[] = [];
+	for (const line of result.stdout.split("\n")) {
+		const match = /^\s*(\d+)\s+(\d+)\s+(\S+)/.exec(line);
+		if (!match || Number(match[2]) !== processGroupId || match[3]!.startsWith("Z")) continue;
+		members.push(Number(match[1]));
+	}
+	return members;
+}
+
+async function waitUntilGroupTerminal(
+	processGroupId: number,
+	timeoutMs: number,
+): Promise<false | { state: "enumeration-failed" | "still-active"; diagnostic: string }> {
+	const deadline = Date.now() + timeoutMs;
+	while (true) {
+		const members = activeProcessGroupMembers(processGroupId);
+		if (Array.isArray(members) && members.length === 0) return false;
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) {
+			if (!Array.isArray(members)) return { state: "enumeration-failed", diagnostic: members.diagnostic };
+			return { state: "still-active", diagnostic: `Process group ${processGroupId} still has active members: ${members.join(", ")}.` };
+		}
+		await new Promise<void>((resolve) => setTimeout(resolve, Math.min(VERIFY_INTERVAL_MS, remaining)));
+	}
+}
+
+function observed(processGroupId: number): ProcessTreeTerminalV1 {
+	return { state: "observed", mechanism: "posix-process-group", processGroupId, verifiedAt: Date.now() };
+}
+
+/** Owns one writer process group and arbitrates its cleanup exactly once. */
+export interface OwnedProcessTreeController {
+	terminate(): Promise<ProcessTreeTerminalV1>;
+	finishAfterWriterClose(): Promise<ProcessTreeTerminalV1>;
+}
+
+export function createOwnedProcessTreeController(
+	pid: number,
+	options: { termGraceMs?: number; killVerifyMs?: number } = {},
+): OwnedProcessTreeController {
+	let termination: Promise<ProcessTreeTerminalV1> | undefined;
+	const posixGroupOwned = process.platform !== "win32";
+	const target = posixGroupOwned ? -pid : pid;
+
+	const terminate = (): Promise<ProcessTreeTerminalV1> => {
+		if (termination) return termination;
+		termination = (async () => {
+			if (!posixGroupOwned) {
+				signalProcess(target, "SIGTERM");
+				return { state: "unknown", reason: "unsupported-platform" };
+			}
+			const term = signalProcess(target, "SIGTERM");
+			if (term !== "sent" && term !== "absent") {
+				return { state: "unknown", reason: "signal-failed", diagnostic: term.diagnostic };
+			}
+			const termExit = await waitUntilGroupTerminal(pid, options.termGraceMs ?? DEFAULT_TERM_GRACE_MS);
+			if (termExit === false) return observed(pid);
+
+			const kill = signalProcess(target, "SIGKILL");
+			if (kill !== "sent" && kill !== "absent") {
+				const members = activeProcessGroupMembers(pid);
+				if (!Array.isArray(members) || members.length > 0) {
+					return { state: "unknown", reason: "signal-failed", diagnostic: kill.diagnostic };
+				}
+			}
+			const killExit = await waitUntilGroupTerminal(pid, options.killVerifyMs ?? DEFAULT_KILL_VERIFY_MS);
+			if (killExit !== false) {
+				return { state: "unknown", reason: "verification-failed", diagnostic: killExit.diagnostic };
+			}
+			return observed(pid);
+		})();
+		return termination;
+	};
+
+	return { terminate, finishAfterWriterClose: terminate };
+}

package/src/runs/background/process-terminal.ts

@@ -10,6 +10,7 @@ import {
 	type ProcessTerminalV1,
 } from "../../shared/types.ts";
 import { canonicalSessionId, inspectSessionLease } from "../shared/session-lease.ts";
+import { releaseActiveRunIndex } from "./active-run-index.ts";
 
 export interface ProcessTerminalCandidate {
 	version: 1;
@@ -40,9 +41,19 @@ function validProcessInstance(value: unknown, kind?: "runner" | "pi-writer"): va
 	if (typeof value.closeObservedAt !== "number" || !Number.isFinite(value.closeObservedAt)) return false;
 	if (typeof value.exitCode !== "number" && value.exitCode !== null) return false;
 	if (typeof value.signal !== "string" && value.signal !== null) return false;
-	return value.kind === "runner"
-		? value.attempt === undefined
-		: typeof value.attempt === "number" && Number.isInteger(value.attempt) && value.attempt >= 0;
+	if (value.kind === "runner") return value.attempt === undefined;
+	if (typeof value.attempt !== "number" || !Number.isInteger(value.attempt) || value.attempt < 0 || !isRecord(value.processTree)) return false;
+	if (value.processTree.state === "observed") {
+		return value.processTree.mechanism === "posix-process-group"
+			&& typeof value.processTree.processGroupId === "number"
+			&& Number.isInteger(value.processTree.processGroupId)
+			&& value.processTree.processGroupId > 0
+			&& typeof value.processTree.verifiedAt === "number"
+			&& Number.isFinite(value.processTree.verifiedAt);
+	}
+	return value.processTree.state === "unknown"
+		&& ["unsupported-platform", "signal-failed", "verification-failed"].includes(String(value.processTree.reason))
+		&& (value.processTree.diagnostic === undefined || typeof value.processTree.diagnostic === "string");
 }
 
 function validInstance(value: unknown): value is ProcessInstanceExitV1 {
@@ -249,6 +260,8 @@ export function finalizeProcessTerminal(
 				proof = unknownProof(runId, runnerClose.processInstanceId, "canonical-session-release-unverified");
 			} else if (inconsistentWriters || (allWriters.length === 0 && expectedEntries.length === 0)) {
 				proof = unknownProof(runId, runnerClose.processInstanceId, "writer-close-unverified");
+			} else if (allWriters.some((writer) => writer.kind === "pi-writer" && writer.processTree.state !== "observed")) {
+				proof = unknownProof(runId, runnerClose.processInstanceId, "process-tree-unverified");
 			} else {
 				const runner: ProcessInstanceExitV1 = { kind: "runner", ...runnerClose };
 				const canonicalSession = session && sessionProjection(candidate, session);
@@ -271,6 +284,7 @@ export function finalizeProcessTerminal(
 	try {
 		writeAtomicJson(processTerminalPath(asyncDir), proof);
 		durable = true;
+		if (proof.state === "observed") releaseActiveRunIndex(asyncDir);
 		overlayStatus(asyncDir, proof, candidateForOverlay);
 		fs.appendFileSync(path.join(asyncDir, "events.jsonl"), `${JSON.stringify({ type: "subagent.run.process_terminal", lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, ts: Date.now(), runId, processTerminal: proof })}\n`, "utf-8");
 	} catch {

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

@@ -19,6 +19,7 @@ import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-
 import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 import { readMissionBinding } from "../../missions/lifecycle.ts";
 import { formatWorkflowJsonPreview } from "../../workflows/scripted-workflow.ts";
+import { formatRunFanoutBudget, getRunFanoutBudgetSnapshot, readRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
 
 interface RunStatusParams {
 	action?: string;
@@ -389,6 +390,8 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			const steeringText = formatSteeringSummary(status);
 			const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId })
 				?? sanitizeProcessTerminal(status.processTerminal, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId }, path.join(asyncDir, "status.json"));
+			const runFanoutBudgetDescriptor = readRunFanoutBudgetDescriptor(asyncDir);
+			const runFanoutBudget = runFanoutBudgetDescriptor ? getRunFanoutBudgetSnapshot(runFanoutBudgetDescriptor) : status.runFanoutBudget;
 			let missionId: string | undefined;
 			try {
 				missionId = readMissionBinding(asyncDir)?.missionId;
@@ -410,6 +413,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				statusActivityText ? `Activity: ${statusActivityText}` : undefined,
 				steeringText ? `Steering: ${steeringText}` : undefined,
 				`Mode: ${status.mode}`,
+				runFanoutBudget ? formatRunFanoutBudget(runFanoutBudget) : undefined,
 				status.parentWorkflowRunId ? `Workflow parent: ${status.parentWorkflowRunId}${status.workflowKey ? ` (${status.workflowKey})` : ""}` : undefined,
 				status.mode === "workflow" && workflowReturnPreview !== undefined ? `Return: ${workflowReturnPreview}` : undefined,
 				status.mode === "workflow" && workflowEmitPreview !== undefined ? `Latest emit: ${workflowEmitPreview}` : undefined,
@@ -466,7 +470,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
 			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
 
-			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [], ...(processTerminal ? { lifecycleStatus: { processTerminal } } : {}) } };
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [], ...(runFanoutBudget ? { runFanoutBudget } : {}), ...(processTerminal ? { lifecycleStatus: { processTerminal } } : {}) } };
 		}
 	}
 

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

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { updateActiveRunIndex } from "./active-run-index.ts";
+import { releaseActiveRunIndex, updateActiveRunIndex } from "./active-run-index.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";
@@ -261,7 +261,7 @@ function writeFailedRepair(asyncDir: string, status: AsyncStatus, resultPath: st
 	const repair = buildFailedRepair(status, asyncDir, now, reason);
 	writeAtomicJson(resultPath, repair.result);
 	writeAtomicJson(path.join(asyncDir, "status.json"), repair.status);
-	updateActiveRunIndex(asyncDir, repair.status.state);
+	if (repair.status.processTerminal?.state === "observed") releaseActiveRunIndex(asyncDir);
 	appendJsonlBestEffort(path.join(asyncDir, "events.jsonl"), {
 		type: "subagent.run.repaired_stale",
 		ts: now,
@@ -351,7 +351,7 @@ export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOp
 			: undefined;
 		if (terminalStatus) {
 			writeAtomicJson(path.join(asyncDir, "status.json"), terminalStatus);
-			updateActiveRunIndex(asyncDir, terminalStatus.state);
+			if (terminalStatus.processTerminal?.state === "observed") releaseActiveRunIndex(asyncDir);
 			return { status: terminalStatus, repaired: true, resultPath, message: "Existing async result file was used to repair stale running status." };
 		}
 		if (effectiveStatus.displayDismissedAt === undefined) return { status: effectiveStatus, repaired: false, resultPath };

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

@@ -25,11 +25,14 @@ import {
 	type LaunchResolvedChildExtensionsV1,
 	type RuntimeAcknowledgedChildExtensionsV1,
 	type ModelAttempt,
+	type PiWriterProcessInstanceExitV1,
+	type ProcessTreeTerminalV1,
 	type NestedRouteInfo,
 	type NestedRunSummary,
 	type ResolvedControlConfig,
 	type ResolvedTurnBudget,
 	type ResolvedToolBudget,
+	type RunFanoutBudgetDescriptor,
 	type SubagentRunMode,
 	type SubagentOutputState,
 	type UsageBudgetConfig,
@@ -68,13 +71,14 @@ import {
 	DEFAULT_GLOBAL_CONCURRENCY_LIMIT,
 	Semaphore,
 } from "../shared/parallel-utils.ts";
-import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan, type SubagentTaskDelivery } from "../shared/pi-args.ts";
 import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
 import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
 import { createStructuredOutputRuntime, MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput } from "../shared/structured-output.ts";
 import { formatProcessSignalError, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
+import { claimRunFanoutBatch, getRunFanoutBudgetSnapshot } from "../shared/run-fanout-budget.ts";
 import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent } from "../shared/nested-events.ts";
 import { formatModelAttemptNote, isRetryableModelFailure } from "../shared/model-fallback.ts";
 import {
@@ -85,9 +89,10 @@ import {
 	waitForSubagentStartupRetry,
 } from "../shared/subagent-startup-retry.ts";
 import { markProcessTerminalCandidateLeaseRelease, writeProcessTerminalCandidate, type ProcessTerminalCandidate } from "./process-terminal.ts";
+import { createOwnedProcessTreeController, type OwnedProcessTreeController } from "./owned-process-tree.ts";
 import { createSteeringStatus, recordSteeringRequest, steeringStatus, terminalSteeringNoticeState, updateSteeringTarget } from "./steering.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
-import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput, hasEmptyTerminalAssistantResponse, readStatus } from "../../shared/utils.ts";
+import { PROMPT_REDACTED, detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput, hasEmptyTerminalAssistantResponse, readStatus } from "../../shared/utils.ts";
 import { evaluateCompletionMutationGuard } from "../shared/completion-guard.ts";
 import {
 	createMutatingFailureState,
@@ -177,6 +182,7 @@ interface SubagentRunConfig {
 	/** Global cap on simultaneously-running subagent tasks within this run. */
 	globalConcurrencyLimit?: number;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	runFanoutBudget?: RunFanoutBudgetDescriptor;
 	launchContractDigest?: string;
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -232,7 +238,7 @@ interface StepResult {
 	structuredOutputSchemaPath?: string;
 	acceptance?: import("../../shared/types.ts").AcceptanceLedger;
 	watchdog?: import("../../shared/types.ts").ChildWatchdogProgress;
-	writerProcesses?: Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }>;
+	writerProcesses?: PiWriterProcessInstanceExitV1[];
 	writerAttemptCount?: number;
 	runner?: ExternalCliRunnerStatus;
 	externalProcess?: ExternalProcessStatus;
@@ -512,6 +518,7 @@ interface RunPiStreamingResult {
 	processInstanceId: string;
 	processCloseObservedAt?: number;
 	processSignal?: string | null;
+	processTree: ProcessTreeTerminalV1;
 }
 
 function runPiStreaming(
@@ -548,7 +555,9 @@ function runPiStreaming(
 			stdio: ["ignore", "pipe", "pipe"],
 			env: spawnEnv,
 			windowsHide: true,
+			detached: process.platform !== "win32",
 		});
+		let processTreeController: OwnedProcessTreeController | undefined;
 		const stderrTail = createBoundedByteTail();
 		const rawStdoutTail = createBoundedByteTail();
 		const messages: Message[] = [];
@@ -556,6 +565,7 @@ function runPiStreaming(
 		let model: string | undefined;
 		let writerRegistrationError: string | undefined;
 		if (typeof child.pid === "number") {
+			processTreeController = createOwnedProcessTreeController(child.pid);
 			try {
 				onWriterProcess?.({ state: "running", pid: child.pid });
 			} catch (writerError) {
@@ -703,7 +713,6 @@ function runPiStreaming(
 		// a lingering stdio holder after `exit`, or a child that never exits.
 		const FINAL_STOP_GRACE_MS = 1000;
 		const HARD_KILL_MS = 3000;
-		const TIMEOUT_HARD_KILL_MS = 3000;
 		let childExited = false;
 		let forcedTerminationSignal = false;
 		let cleanTerminalAssistantStopReceived = false;
@@ -711,7 +720,6 @@ function runPiStreaming(
 		let finalDrainTimer: NodeJS.Timeout | undefined;
 		let finalHardKillTimer: NodeJS.Timeout | undefined;
 		let watchdogTailTimer: NodeJS.Timeout | undefined;
-		let timeoutHardKillTimer: NodeJS.Timeout | undefined;
 		let turnBudgetTerminationTimer: NodeJS.Timeout | undefined;
 		let turnBudgetHardKillTimer: NodeJS.Timeout | undefined;
 		let protocolHardKillTimer: NodeJS.Timeout | undefined;
@@ -776,22 +784,16 @@ function runPiStreaming(
 			timedOut = true;
 			interrupted = false;
 			error = timeoutMessage ?? "Subagent timed out.";
-			trySignalChild(child, "SIGTERM");
-			timeoutHardKillTimer = setTimeout(() => {
-				if (!settled) trySignalChild(child, "SIGKILL");
-			}, TIMEOUT_HARD_KILL_MS);
-			timeoutHardKillTimer.unref?.();
+			if (processTreeController) void processTreeController.terminate();
+			else trySignalChild(child, "SIGTERM");
 		});
 		registerStop?.(() => {
 			if (settled || timedOut || stopped) return;
 			stopped = true;
 			interrupted = false;
 			error = stopMessage ?? "Subagent stopped by user.";
-			trySignalChild(child, "SIGTERM");
-			timeoutHardKillTimer = setTimeout(() => {
-				if (!settled) trySignalChild(child, "SIGKILL");
-			}, TIMEOUT_HARD_KILL_MS);
-			timeoutHardKillTimer.unref?.();
+			if (processTreeController) void processTreeController.terminate();
+			else trySignalChild(child, "SIGTERM");
 		});
 		registerTurnBudgetAbort?.((message, state) => {
 			if (settled || timedOut || stopped || turnBudgetExceeded) return;
@@ -820,10 +822,6 @@ function runPiStreaming(
 				finalHardKillTimer = undefined;
 			}
 			clearWatchdogTailTimer();
-			if (timeoutHardKillTimer) {
-				clearTimeout(timeoutHardKillTimer);
-				timeoutHardKillTimer = undefined;
-			}
 			if (turnBudgetTerminationTimer) {
 				clearTimeout(turnBudgetTerminationTimer);
 				turnBudgetTerminationTimer = undefined;
@@ -885,9 +883,12 @@ function runPiStreaming(
 			childExited = true;
 			clearDrainTimers();
 		});
-		child.on("close", (exitCode, signal) => {
+		child.on("close", async (exitCode, signal) => {
 			settled = true;
 			const processCloseObservedAt = Date.now();
+			const processTree = processTreeController
+				? await processTreeController.finishAfterWriterClose()
+				: { state: "unknown" as const, reason: "verification-failed" as const, diagnostic: "Writer PID was unavailable." };
 			try {
 				onWriterProcess?.({ state: "none" });
 			} catch {
@@ -939,6 +940,7 @@ function runPiStreaming(
 				processInstanceId,
 				processCloseObservedAt,
 				processSignal: signal,
+				processTree,
 			}));
 		});
 
@@ -961,7 +963,7 @@ function runPiStreaming(
 			const stderr = stderrTail.text();
 			const finalOutput = getFinalOutput(messages) || rawStdoutTail.text().trim();
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, structuredOutputToolInvoked, structuredOutputMessageStartIndex, watchdog: childWatchdogState, processInstanceId }));
+			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, structuredOutputToolInvoked, structuredOutputMessageStartIndex, watchdog: childWatchdogState, processInstanceId, processTree: { state: "unknown", reason: "verification-failed", diagnostic: spawnErrorMessage } }));
 		});
 	});
 }
@@ -1105,6 +1107,7 @@ interface SingleStepContext {
 	orchestratorIntercomTarget?: string;
 	nestedRoute?: NestedRouteInfo;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	runFanoutBudget?: RunFanoutBudgetDescriptor;
 	onAttemptStart?: (attempt: { model?: string; thinking?: string }) => void;
 	onChildEvent?: (event: ChildEvent) => void;
 	onWriterProcess?: (writer: { state: "none" | "spawning" } | { state: "running"; pid: number }) => void;
@@ -1206,7 +1209,7 @@ async function runSingleStep(
 		artifactPaths = getArtifactPaths(ctx.artifactsDir, ctx.id, step.agent, index);
 		fs.mkdirSync(ctx.artifactsDir, { recursive: true });
 		if (ctx.artifactConfig?.includeInput !== false) {
-			fs.writeFileSync(artifactPaths.inputPath, `# Task for ${step.agent}\n\n${task}`, "utf-8");
+			fs.writeFileSync(artifactPaths.inputPath, `# Task for ${step.agent}\n\n${PROMPT_REDACTED}; live Prompt Audit only.\n`, "utf-8");
 		}
 		if (ctx.artifactConfig?.includeTranscript !== false) {
 			transcriptWriter = createChildTranscriptWriter({
@@ -1219,7 +1222,7 @@ async function runSingleStep(
 			});
 		}
 	}
-	transcriptWriter?.writeInitialUserMessage(task);
+	transcriptWriter?.writeInitialUserMessage(`${PROMPT_REDACTED}; live Prompt Audit only.`);
 
 	if (step.runner?.type === "external-cli") {
 		const runner: ExternalCliRunnerStatus = {
@@ -1262,7 +1265,7 @@ async function runSingleStep(
 				artifactPaths,
 				artifactConfig: ctx.artifactConfig,
 				output: formatOutputArtifactContent(omitUndefinedProperties({ output: resolvedOutput.fullOutput, error: external.error, metadataPath: ctx.artifactConfig?.includeMetadata === false ? undefined : artifactPaths.metadataPath })),
-				metadata: { runId: ctx.id, agent: step.agent, task, runner, externalProcess: external.externalProcess, exitCode: external.exitCode, error: external.error, timestamp: Date.now() },
+				metadata: { runId: ctx.id, agent: step.agent, task: PROMPT_REDACTED, runner, externalProcess: external.externalProcess, exitCode: external.exitCode, error: external.error, timestamp: Date.now() },
 			})
 			: {};
 		return omitUndefinedProperties({
@@ -1292,7 +1295,7 @@ async function runSingleStep(
 	let capabilityAudit: import("../shared/capability-ceiling.ts").SubagentCapabilityAudit | undefined;
 	let launchResolvedExtensions = step.launchResolvedExtensions;
 	const modelAttempts: ModelAttempt[] = [];
-	const writerProcesses: Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }> = [];
+	const writerProcesses: PiWriterProcessInstanceExitV1[] = [];
 	let writerAttemptCount = 0;
 	const attemptNotes: string[] = [];
 	const eventsPath = path.join(path.dirname(ctx.outputFile), "events.jsonl");
@@ -1306,6 +1309,9 @@ async function runSingleStep(
 
 	let modelIndex = 0;
 	let startupAttemptIndex = 0;
+	// Escalated to "file" after an unexplained zero-activity startup failure so
+	// retries keep the task text out of argv (endpoint pre-exec scans may deny it).
+	let taskDeliveryOverride: SubagentTaskDelivery | undefined;
 	modelAttemptsLoop: while (modelIndex < candidates.length) {
 		if (ctx.timeoutSignal?.aborted || ctx.stopSignal?.aborted || ctx.skipAcceptance?.()) break;
 		const candidate = candidates[modelIndex];
@@ -1331,6 +1337,7 @@ async function runSingleStep(
 			parentSessionId: step.parentSessionId,
 			baseArgs: ["--mode", "json", "-p"],
 			task,
+			taskDelivery: taskDeliveryOverride,
 			sessionEnabled,
 			sessionDir,
 			sessionFile: step.sessionFile,
@@ -1356,6 +1363,10 @@ async function runSingleStep(
 			parentControlInbox: ctx.nestedRoute?.controlInbox,
 			parentRootRunId: ctx.nestedRoute?.rootRunId,
 			parentCapabilityToken: ctx.nestedRoute?.capabilityToken,
+			runFanoutBudget: ctx.runFanoutBudget ? {
+				...ctx.runFanoutBudget,
+				...(step.runFanoutPath ? { parentPath: `${ctx.runFanoutBudget.parentPath ? `${ctx.runFanoutBudget.parentPath}/` : ""}${step.runFanoutPath}` } : {}),
+			} : undefined,
 			steerInboxDir: ctx.steerInboxDir,
 			steerCapabilityPath: ctx.steerCapabilityPath,
 			steerAckDir: ctx.steerAckDir,
@@ -1429,6 +1440,7 @@ async function runSingleStep(
 				closeObservedAt: run.processCloseObservedAt,
 				exitCode: run.exitCode,
 				signal: run.processSignal ?? null,
+				processTree: run.processTree,
 			});
 		}
 		if (run.turnBudget) turnBudget = run.turnBudget;
@@ -1583,6 +1595,10 @@ async function runSingleStep(
 			});
 			const shouldRetry = await waitForSubagentStartupRetry(retryDelayMs, [ctx.timeoutSignal, ctx.stopSignal]);
 			if (!shouldRetry || ctx.skipAcceptance?.()) break modelAttemptsLoop;
+			if (!taskDeliveryOverride && run.processSignal === "SIGKILL") {
+				taskDeliveryOverride = "file";
+				attemptNotes.push("[startup-retry] retrying with file task delivery to keep the task text out of the child process argv.");
+			}
 			attempt.error = retryNote;
 			attemptNotes.push(retryNote);
 			startupAttemptIndex += 1;
@@ -1700,7 +1716,7 @@ async function runSingleStep(
 			metadata: {
 				runId: ctx.id,
 				agent: step.agent,
-				task,
+				task: PROMPT_REDACTED,
 				exitCode: effectiveFinalExitCode,
 				model: finalResult?.model,
 				attemptedModels: attemptedModels.length > 0 ? attemptedModels : undefined,
@@ -2171,6 +2187,7 @@ async function runSubagent(
 		...(config.launchContractDigest ? { launchContractDigest: config.launchContractDigest } : {}),
 		...(config.launchResolvedExtensions ? { launchResolvedExtensions: config.launchResolvedExtensions } : {}),
 		...(config.capabilityCeiling ? { capabilityCeiling: config.capabilityCeiling } : {}),
+		...(config.runFanoutBudget ? { runFanoutBudget: getRunFanoutBudgetSnapshot(config.runFanoutBudget) } : {}),
 		...(config.parentWorkflowRunId ? { parentWorkflowRunId: config.parentWorkflowRunId } : {}),
 		...(config.workflowKey ? { workflowKey: config.workflowKey } : {}),
 		...(config.runnerProcessInstanceId ? { processTerminal: { version: 1 as const, state: "pending" as const, runId: id, runnerProcessInstanceId: config.runnerProcessInstanceId } } : {}),
@@ -2260,10 +2277,10 @@ async function runSubagent(
 		refreshWorkflowGraph();
 		writeAtomicJson(statusPath, statusPayload);
 		const activeState = isActiveAsyncState(statusPayload.state);
-		if (activeState !== lastIndexedActiveState) {
+		if (activeState && activeState !== lastIndexedActiveState) {
 			updateActiveRunIndex(asyncDir, statusPayload.state);
-			lastIndexedActiveState = activeState;
 		}
+		lastIndexedActiveState = activeState;
 		emitNestedSelfEvent(statusPayload.state === "running" || statusPayload.state === "queued" ? "subagent.nested.updated" : "subagent.nested.completed");
 	};
 	const statusWriteCoalescer = createFileCoalescer(writeStatusPayloadNow, 100);
@@ -3035,7 +3052,6 @@ async function runSubagent(
 		if (stopped || timedOut || interrupted || statusPayload.state !== "running") return;
 		stopped = true;
 		const now = Date.now();
-		statusPayload.state = "stopped";
 		statusPayload.stopped = true;
 		statusPayload.error = stopMessage;
 		currentActivityState = undefined;
@@ -3068,7 +3084,6 @@ async function runSubagent(
 		timedOut = true;
 		const now = Date.now();
 		const message = timeoutMessage ?? "Subagent timed out.";
-		statusPayload.state = "failed";
 		statusPayload.timedOut = true;
 		statusPayload.error = message;
 		currentActivityState = undefined;
@@ -3258,6 +3273,9 @@ async function runSubagent(
 					throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} materialized ${materialized.parallel.length} items that resolve output to the same path: ${step.parallel.outputPath}. Remove the explicit output path or use an inherited relative agent output so each item can be isolated.`);
 				}
 				if (materialized.collectedOnEmpty) await validateDynamicCollection(step.collect.outputSchema, materialized.collectedOnEmpty);
+				if (!config.runFanoutBudget) throw new Error("Async runner is missing its run fan-out budget identity.");
+				const runFanoutBudget = claimRunFanoutBatch(config.runFanoutBudget, materialized.parallel.map((_, itemIndex) => `chain[${stepIndex}].expand[${itemIndex}]`));
+				statusPayload.runFanoutBudget = runFanoutBudget;
 			} catch (error) {
 				const now = Date.now();
 				const message = error instanceof DynamicFanoutError ? error.message : error instanceof Error ? error.message : String(error);
@@ -3364,6 +3382,7 @@ async function runSubagent(
 				const materializedTask = step.parallel.namespaceOutputPath ? injectSingleOutputInstruction(taskText, outputPath, step.parallel) : taskText;
 				return omitUndefinedProperties({
 					...step.parallel,
+					runFanoutPath: `chain[${stepIndex}].expand[${itemIndex}]`,
 					task: materializedTask,
 					effectiveAcceptance: resolveEffectiveAcceptance(omitUndefinedProperties({
 						explicit: step.parallel.acceptanceInput,
@@ -3523,6 +3542,7 @@ async function runSubagent(
 					orchestratorIntercomTarget: config.controlIntercomTarget,
 					nestedRoute: config.nestedRoute,
 					capabilityCeiling: config.capabilityCeiling,
+					runFanoutBudget: config.runFanoutBudget,
 					registerInterrupt: (interrupt) => registerStepInterrupt(fi, interrupt),
 					registerTimeout: (interrupt) => registerStepTimeout(fi, interrupt),
 					registerStop: (stop) => registerStepStop(fi, stop),
@@ -3905,6 +3925,7 @@ async function runSubagent(
 							orchestratorIntercomTarget: config.controlIntercomTarget,
 							nestedRoute: config.nestedRoute,
 							capabilityCeiling: config.capabilityCeiling,
+							runFanoutBudget: config.runFanoutBudget,
 							registerInterrupt: (interrupt) => registerStepInterrupt(fi, interrupt),
 							registerTimeout: (interrupt) => registerStepTimeout(fi, interrupt),
 							registerStop: (stop) => registerStepStop(fi, stop),
@@ -4194,6 +4215,7 @@ async function runSubagent(
 				orchestratorIntercomTarget: config.controlIntercomTarget,
 				nestedRoute: config.nestedRoute,
 				capabilityCeiling: config.capabilityCeiling,
+				runFanoutBudget: config.runFanoutBudget,
 				registerInterrupt: (interrupt) => registerStepInterrupt(flatIndex, interrupt),
 				registerTimeout: (interrupt) => registerStepTimeout(flatIndex, interrupt),
 				registerStop: (stop) => registerStepStop(flatIndex, stop),
@@ -4438,6 +4460,9 @@ async function runSubagent(
 		clearTimeout(timeoutTimer);
 		timeoutTimer = undefined;
 	}
+	if (!timedOut && !stopped && !interrupted && config.timeoutMs !== undefined && results.some((result) => result.timedOut === true && result.error === timeoutMessage)) {
+		timedOut = true;
+	}
 	const signalTerminated = !stopped && !timedOut && !turnBudgetExceeded && !interrupted && results.some((result) => result.exitCode !== 0 && isUnexplainedProcessSignal(omitUndefinedProperties({
 		processSignal: result.processSignal,
 		interrupted: result.interrupted,
@@ -4630,7 +4655,7 @@ async function runSubagent(
 		shareError,
 	}));
 	if (config.runnerProcessInstanceId) {
-		const writers: Record<string, Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }>> = {};
+		const writers: Record<string, PiWriterProcessInstanceExitV1[]> = {};
 		const expectedWriters: Record<string, number> = {};
 		for (const [index, result] of results.entries()) {
 			writers[String(index)] = result.writerProcesses ?? [];