pi-subagents 0.38.0 → 0.40.0

package/src/runs/foreground/execution.ts

@@ -55,10 +55,12 @@ import { evaluateCompletionMutationGuard } from "../shared/completion-guard.ts";
 import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
-import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
-import { decodeSubagentCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV } from "../shared/capability-ceiling.ts";
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
+import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
+import { assertAgentAllowedByCapabilityCeiling, decodeSubagentCapabilityCeiling, intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV } from "../shared/capability-ceiling.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { 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 { captureSingleOutputSnapshot, extractChildWrittenOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
@@ -121,6 +123,47 @@ function sumUsage(target: Usage, source: Usage): void {
 	target.turns += source.turns;
 }
 
+function persistSingleResultMetadata(input: {
+	metadataPath?: string;
+	enabled: boolean;
+	runId?: string;
+	agent: string;
+	task: string;
+	result: SingleResult;
+}): void {
+	if (!input.enabled || !input.metadataPath) return;
+	const target = input.result;
+	writeMetadata(input.metadataPath, {
+		runId: input.runId,
+		agent: input.agent,
+		task: input.task,
+		exitCode: target.exitCode,
+		processSignal: target.processSignal,
+		usage: target.usage,
+		model: target.model,
+		attemptedModels: target.attemptedModels,
+		modelAttempts: target.modelAttempts,
+		durationMs: target.progressSummary?.durationMs,
+		toolCount: target.progressSummary?.toolCount,
+		error: target.error,
+		agentContract: target.agentContract,
+		launchContractDigest: target.launchContractDigest,
+		launchResolvedExtensions: target.launchResolvedExtensions,
+		runtimeAcknowledgedExtensions: target.runtimeAcknowledgedExtensions,
+		execution: target.execution,
+		acceptance: target.acceptance,
+		capabilityCeiling: target.capabilityCeiling,
+		capabilityAudit: target.capabilityAudit,
+		review: target.review,
+		effects: target.effects,
+		transcriptPath: target.transcriptPath,
+		transcriptError: target.transcriptError,
+		skills: target.skills,
+		skillsWarning: target.skillsWarning,
+		timestamp: Date.now(),
+	});
+}
+
 function formatTimeoutMessage(timeoutMs: number): string {
 	return `Subagent timed out after ${timeoutMs}ms.`;
 }
@@ -148,6 +191,21 @@ function buildPendingAcceptanceLedger(acceptance: ResolvedAcceptanceConfig): Acc
 	};
 }
 
+function buildInterruptedAcceptanceLedger(acceptance: ResolvedAcceptanceConfig): AcceptanceLedger {
+	const pending = buildPendingAcceptanceLedger(acceptance);
+	if (acceptance.level === "none") {
+		pending.status = "not-required";
+		pending.evidenceStatus = "not-required";
+	} else {
+		pending.runtimeChecks = [{
+			id: "interrupted",
+			status: "not-applicable",
+			message: "Acceptance was not evaluated because the subagent was interrupted.",
+		}];
+	}
+	return pending;
+}
+
 function appendRecentOutput(progress: AgentProgress, lines: string[]): void {
 	if (lines.length === 0) return;
 	progress.recentOutput.push(...lines.filter((line) => line.trim()));
@@ -203,7 +261,7 @@ function snapshotResult(result: SingleResult, progress: AgentProgress): SingleRe
  * unbounded `messages` transcript in favour of compact tool-call summaries so a
  * single `tool_execution_update` line stays well under the child-stdout protocol
  * cap (`MAX_CHILD_PENDING_LINE_BYTES`). Non-streaming consumers such as
- * detached-exit recovery call snapshotResult directly and keep the full transcript.
+ * foreground detach receipts and terminal consumers use snapshotResult directly.
  */
 function snapshotStreamResult(result: SingleResult, progress: AgentProgress): SingleResult {
 	const snapshot = snapshotResult(result, progress);
@@ -244,7 +302,7 @@ async function runSingleAttempt(
 			childIndex: options.index ?? 0,
 		})
 		: undefined;
-	const { args, env: sharedEnv, tempDir, toolDiagnosticPath, capabilityAudit } = buildPiArgs({
+	const { args, env: sharedEnv, tempDir, toolDiagnosticPath, runtimeAcknowledgedExtensionsPath, capabilityAudit } = buildPiArgs({
 		baseArgs: ["--mode", "json", "-p"],
 		task,
 		sessionEnabled: shared.sessionEnabled,
@@ -292,7 +350,9 @@ async function runSingleAttempt(
 		structuredOutput: Boolean(options.structuredOutput),
 		capabilityCeiling: options.capabilityCeiling,
 		inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
+		agentName: agent.name,
 	});
+	const launchResolvedExtensions = projectLaunchResolvedChildExtensions(toolPlan);
 	const launchContractDigest = launchBindingDigest({
 		definitionDigest: agentDefinitionDigest(agent),
 		task: shared.originalTask ?? task,
@@ -312,11 +372,14 @@ async function runSingleAttempt(
 		...(options.structuredOutput ? { structuredOutputSchema: options.structuredOutput.schema } : {}),
 	});
 	const result: SingleResult = withRunContext({
+		index: options.index ?? 0,
 		agent: agent.name,
 		task: shared.originalTask ?? task,
 		...(options.agentContract ? { agentContract: options.agentContract } : {}),
 		launchContractDigest,
+		launchResolvedExtensions,
 		exitCode: 0,
+		outputState: "absent",
 		messages: [],
 		usage: emptyUsage(),
 		model: modelArg,
@@ -399,7 +462,7 @@ async function runSingleAttempt(
 		});
 		const jsonlWriter = createJsonlWriter(shared.jsonlPath, proc.stdout);
 		let processClosed = false;
-		let settled = false;
+		let lifecycleFinished = false;
 		let detached = false;
 		let intercomStarted = false;
 		let assistantError: string | undefined;
@@ -438,19 +501,43 @@ async function runSingleAttempt(
 			}
 		};
 
-		const detachForIntercom = () => {
-			detached = true;
-			processClosed = true;
-			result.detached = true;
-			result.detachedReason = "intercom coordination";
-			progress.status = "detached";
-			progress.durationMs = Date.now() - startTime;
-			result.progressSummary = {
-				toolCount: progress.toolCount,
-				tokens: progress.tokens,
-				durationMs: progress.durationMs,
+		const detachForeground = (reason: string): boolean => {
+			if (detached || processClosed || lifecycleFinished || options.signal?.aborted) return false;
+			const receiptProgress = snapshotProgress(progress);
+			receiptProgress.status = "detached";
+			receiptProgress.durationMs = Date.now() - startTime;
+			const receipt = snapshotResult(result, receiptProgress);
+			receipt.exitCode = -2;
+			receipt.detached = true;
+			receipt.detachedReason = reason;
+			receipt.finalOutput = reason === "intercom coordination"
+				? "Detached for intercom coordination before task completion."
+				: reason === "user request"
+					? "Detached at user request before task completion."
+					: `Detached for ${reason} before task completion.`;
+			receipt.outputMode = options.outputMode ?? "inline";
+			if (options.outputPath) {
+				receipt.outputSaveError = reason === "user request"
+					? "Output file was not finalized because the subagent detached at user request."
+					: `Output file was not finalized because the subagent detached for ${reason}.`;
+			}
+			receipt.progressSummary = {
+				toolCount: receiptProgress.toolCount,
+				tokens: receiptProgress.tokens,
+				durationMs: receiptProgress.durationMs,
 			};
-			finish(-2);
+			// The attempt is not detached until the outer coordinator has accepted and
+			// synchronously published the receipt. A persistence/callback failure must
+			// leave this attempt attached and abortable rather than orphaning it.
+			let accepted = false;
+			try {
+				accepted = options.onDetachReceipt?.(receipt) === true;
+			} catch {
+				return false;
+			}
+			if (!accepted) return false;
+			detached = true;
+			return true;
 		};
 
 		// If the child emits a terminal assistant stop but never exits,
@@ -491,9 +578,9 @@ async function runSingleAttempt(
 				armWatchdogTail();
 				return;
 			}
-			if (childExited || finalDrainTimer || settled || processClosed || detached) return;
+			if (childExited || finalDrainTimer || lifecycleFinished || processClosed) return;
 			finalDrainTimer = setTimeout(() => {
-				if (settled || processClosed || detached) return;
+				if (lifecycleFinished || processClosed) return;
 				const termSent = trySignalChild(proc, "SIGTERM");
 				if (!termSent) return;
 				forcedTerminationSignal = true;
@@ -501,7 +588,7 @@ async function runSingleAttempt(
 					result.error = result.error ?? `Subagent process did not exit within ${FINAL_STOP_GRACE_MS}ms after its terminal event. Forcing termination.`;
 				}
 				finalHardKillTimer = setTimeout(() => {
-					if (settled || processClosed || detached) return;
+					if (lifecycleFinished || processClosed) return;
 					forcedTerminationSignal = trySignalChild(proc, "SIGKILL") || forcedTerminationSignal;
 				}, HARD_KILL_MS);
 				finalHardKillTimer.unref?.();
@@ -509,7 +596,7 @@ async function runSingleAttempt(
 			finalDrainTimer.unref?.();
 		};
 		function armWatchdogTail(): void {
-			if ((!cleanTerminalAssistantStopReceived && !agentSettledReceived) || watchdogTailTimer || settled || processClosed || detached) return;
+			if ((!cleanTerminalAssistantStopReceived && !agentSettledReceived) || watchdogTailTimer || lifecycleFinished || processClosed) return;
 			watchdogTailTimer = setTimeout(() => {
 				watchdogTailTimer = undefined;
 				updateChildWatchdogState({
@@ -535,7 +622,7 @@ async function runSingleAttempt(
 		};
 
 		const unsubscribeIntercomDetach = options.intercomEvents?.on?.(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
-			if (!options.allowIntercomDetach || detached || processClosed) return;
+			if (!options.allowIntercomDetach || processClosed) return;
 			if (!payload || typeof payload !== "object") return;
 			const event = payload as { requestId?: unknown; runId?: unknown; agent?: unknown; childIndex?: unknown };
 			const requestId = event.requestId;
@@ -546,13 +633,13 @@ async function runSingleAttempt(
 				if (typeof event.agent === "string" && event.agent !== agent.name) return;
 				if (typeof event.childIndex === "number" && event.childIndex !== (options.index ?? 0)) return;
 			} else if (!intercomStarted) return;
-			options.intercomEvents?.emit(INTERCOM_DETACH_RESPONSE_EVENT, { requestId, accepted: true, runId: options.runId, agent: agent.name, childIndex: options.index ?? 0 });
-			detachForIntercom();
+			const accepted = detachForeground("intercom coordination");
+			options.intercomEvents?.emit(INTERCOM_DETACH_RESPONSE_EVENT, { requestId, accepted, runId: options.runId, agent: agent.name, childIndex: options.index ?? 0 });
 		});
 
 		const finish = (code: number) => {
-			if (settled) return;
-			settled = true;
+			if (lifecycleFinished) return;
+			lifecycleFinished = true;
 			clearFinalDrainTimers();
 			clearWatchdogTailTimer();
 			clearStdioGuard();
@@ -637,7 +724,7 @@ async function runSingleAttempt(
 		};
 		const requestTurnBudgetAbort = (turnCount: number) => {
 			const budget = options.turnBudget;
-			if (!budget || result.timedOut || result.turnBudgetExceeded || interruptedByControl || processClosed || settled || detached) return;
+			if (!budget || result.timedOut || result.turnBudgetExceeded || interruptedByControl || processClosed || lifecycleFinished) return;
 			const message = turnBudgetExceededMessage(budget, turnCount);
 			result.turnBudgetExceeded = true;
 			result.wrapUpRequested = true;
@@ -650,12 +737,12 @@ async function runSingleAttempt(
 			fireUpdate();
 			trySignalChild(proc, "SIGINT");
 			turnBudgetTerminationTimer = setTimeout(() => {
-				if (processClosed || settled || detached || result.timedOut) return;
+				if (processClosed || lifecycleFinished || result.timedOut) return;
 				trySignalChild(proc, "SIGTERM");
 			}, 1000);
 			turnBudgetTerminationTimer.unref?.();
 			turnBudgetHardKillTimer = setTimeout(() => {
-				if (processClosed || settled || detached || result.timedOut) return;
+				if (processClosed || lifecycleFinished || result.timedOut) return;
 				trySignalChild(proc, "SIGKILL");
 			}, 4000);
 			turnBudgetHardKillTimer.unref?.();
@@ -892,7 +979,7 @@ async function runSingleAttempt(
 
 		if (controlConfig.enabled) {
 			activityTimer = setInterval(() => {
-				if (processClosed || settled || detached) return;
+				if (processClosed || lifecycleFinished) return;
 				const now = Date.now();
 				if (updateActivityState(now)) {
 					progress.durationMs = now - startTime;
@@ -904,7 +991,7 @@ async function runSingleAttempt(
 
 		if (attemptTimeout) {
 			timeoutTimer = setTimeout(() => {
-				if (processClosed || settled || detached || interruptedByControl) return;
+				if (processClosed || lifecycleFinished || interruptedByControl) return;
 				result.timedOut = true;
 				result.error = attemptTimeout.message;
 				result.finalOutput = attemptTimeout.message;
@@ -914,12 +1001,12 @@ async function runSingleAttempt(
 				fireUpdate();
 				trySignalChild(proc, "SIGINT");
 				timeoutTerminationTimer = setTimeout(() => {
-					if (processClosed || settled || detached) return;
+					if (processClosed || lifecycleFinished) return;
 					trySignalChild(proc, "SIGTERM");
 				}, 1000);
 				timeoutTerminationTimer.unref?.();
 				timeoutHardKillTimer = setTimeout(() => {
-					if (processClosed || settled || detached) return;
+					if (processClosed || lifecycleFinished) return;
 					trySignalChild(proc, "SIGKILL");
 				}, 4000);
 				timeoutHardKillTimer.unref?.();
@@ -963,19 +1050,33 @@ async function runSingleAttempt(
 			clearFinalDrainTimers();
 		});
 		proc.on("close", (code, signal) => {
+			if (lifecycleFinished) return;
+			processClosed = true;
 			clearFinalDrainTimers();
 			clearStdioGuard();
 			void jsonlWriter.close().catch(() => {
 				// JSONL artifact flush is best effort.
 			});
 			const toolDiagnosticError = readChildToolDiagnosticError(toolDiagnosticPath);
+			result.runtimeAcknowledgedExtensions = readRuntimeAcknowledgedExtensions(runtimeAcknowledgedExtensionsPath);
 			cleanupTempDir(tempDir);
 			stdoutReader.end();
 			stderrReader.end();
 			const stderr = stderrTail.text();
 			const rawStdout = rawStdoutTail.text();
 			let closeError = result.error ?? toolDiagnosticError ?? assistantError;
-			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && (cleanTerminalAssistantStopReceived || agentSettledReceived) && !closeError;
+			const forcedDrainAfterFinalSuccess = Boolean(forcedTerminationSignal || signal) && (cleanTerminalAssistantStopReceived || agentSettledReceived) && !closeError;
+			if (signal) result.processSignal = signal;
+			if (!closeError && isUnexplainedProcessSignal({
+				processSignal: signal,
+				interrupted: result.interrupted,
+				timedOut: result.timedOut,
+				stopped: result.stopped,
+				turnBudgetExceeded: result.turnBudgetExceeded,
+				forcedDrainAfterFinalSuccess,
+			})) {
+				closeError = formatProcessSignalError(signal!);
+			}
 			if (code !== 0 && rawStdout.trim() && !closeError && !forcedDrainAfterFinalSuccess) {
 				closeError = rawStdout.trim();
 			}
@@ -983,61 +1084,12 @@ async function runSingleAttempt(
 				closeError = stderr.trim();
 			}
 			const finalCode = forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (code ?? 1) : (code ?? 0);
-			if (signal) result.processSignal = signal;
-			if (detached) {
-				const recoveredProgress = snapshotProgress(progress);
-				const recoveredResult = snapshotResult(result, recoveredProgress);
-				if (!recoveredResult.error && closeError) recoveredResult.error = closeError;
-				recoveredResult.exitCode = recoveredResult.error && finalCode === 0 ? 1 : finalCode;
-				recoveredProgress.status = recoveredResult.exitCode === 0 ? "completed" : "failed";
-				recoveredProgress.durationMs = Date.now() - startTime;
-				if (recoveredResult.error) recoveredProgress.error = recoveredResult.error;
-				recoveredResult.progressSummary = {
-					toolCount: recoveredProgress.toolCount,
-					tokens: recoveredProgress.tokens,
-					durationMs: recoveredProgress.durationMs,
-				};
-				const acceptanceOutput = getFinalOutput(recoveredResult.messages ?? []).trim()
-					|| recoveredResult.error
-					|| recoveredResult.finalOutput
-					|| "Detached child exited without final output.";
-				acceptanceOutputByResult.set(recoveredResult, acceptanceOutput);
-				let fullOutput = stripAcceptanceReport(acceptanceOutput);
-				fullOutput = fullOutput.trim() || recoveredResult.error || recoveredResult.finalOutput || "Detached child exited without final output.";
-				recoveredResult.outputMode = options.outputMode ?? "inline";
-				if (options.outputPath && recoveredResult.exitCode === 0) {
-					const resolvedOutput = resolveSingleOutput(options.outputPath, fullOutput, shared.outputSnapshot);
-					fullOutput = stripAcceptanceReport(resolvedOutput.fullOutput);
-					recoveredResult.savedOutputPath = resolvedOutput.savedPath;
-					recoveredResult.outputSaveError = resolvedOutput.saveError;
-					if (resolvedOutput.savedPath) {
-						recoveredResult.outputReference = formatSavedOutputReference(resolvedOutput.savedPath, fullOutput);
-					} else {
-						recoveredResult.exitCode = 1;
-						recoveredResult.error = `Output file was not finalized after detached child exit: ${resolvedOutput.saveError ?? options.outputPath}`;
-						recoveredProgress.status = "failed";
-						recoveredProgress.error = recoveredResult.error;
-					}
-				}
-				recoveredResult.finalOutput = options.outputMode === "file-only" && recoveredResult.savedOutputPath && recoveredResult.outputReference
-					? recoveredResult.outputReference.message
-					: fullOutput;
-				if (recoveredResult.artifactPaths && options.artifactConfig?.enabled !== false && options.artifactConfig?.includeOutput !== false) {
-					try {
-						writeArtifact(recoveredResult.artifactPaths.outputPath, fullOutput);
-					} catch {
-						// Detached children may outlive test/temp cleanup; recovered status is best-effort.
-					}
-				}
-				options.onDetachedExit?.(recoveredResult);
-				finish(-2);
-				return;
-			}
 			if (!result.error && closeError) result.error = closeError;
-			processClosed = true;
 			finish(finalCode);
 		});
 		proc.on("error", (error) => {
+			if (lifecycleFinished) return;
+			processClosed = true;
 			clearFinalDrainTimers();
 			clearStdioGuard();
 			void jsonlWriter.close().catch(() => {
@@ -1054,7 +1106,7 @@ async function runSingleAttempt(
 
 		if (options.signal) {
 			const kill = () => {
-				if (processClosed || detached) return;
+				if (processClosed || lifecycleFinished) return;
 				proc.kill("SIGTERM");
 				setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
 			};
@@ -1067,7 +1119,7 @@ async function runSingleAttempt(
 
 		if (options.interruptSignal) {
 			const interrupt = () => {
-				if (processClosed || detached || settled) return;
+				if (processClosed || lifecycleFinished) return;
 				if (result.timedOut) return;
 				interruptedByControl = true;
 				clearTimeoutTimers();
@@ -1079,7 +1131,7 @@ async function runSingleAttempt(
 				fireUpdate();
 				trySignalChild(proc, "SIGINT");
 				setTimeout(() => {
-					if (settled || processClosed || detached) return;
+					if (lifecycleFinished || processClosed) return;
 					trySignalChild(proc, "SIGTERM");
 				}, 1000).unref?.();
 			};
@@ -1089,6 +1141,16 @@ async function runSingleAttempt(
 				removeInterruptListener = () => options.interruptSignal?.removeEventListener("abort", interrupt);
 			}
 		}
+
+		// Publish only after every callback and cleanup guard captured by detach or
+		// later lifecycle events has initialized. Consumers may invoke synchronously.
+		try {
+			options.onDetachReady?.((reason = "user request") => detachForeground(reason));
+		} catch (error) {
+			// A consumer callback is advisory. Keep the child attached and observable
+			// rather than rejecting this attempt and orphaning its live process.
+			appendRecentOutput(progress, [`Foreground detach callback failed: ${error instanceof Error ? error.message : String(error)}`]);
+		}
 	});
 	result.exitCode = exitCode;
 	if (interruptedByControl) {
@@ -1106,16 +1168,6 @@ async function runSingleAttempt(
 		};
 		return result;
 	}
-	if (result.detached) {
-		result.exitCode = -2;
-		result.finalOutput = "Detached for intercom coordination before task completion.";
-		result.outputMode = options.outputMode ?? "inline";
-		if (options.outputPath) {
-			result.outputSaveError = "Output file was not finalized because the subagent detached for intercom coordination.";
-		}
-		return result;
-	}
-
 	if (result.error && result.exitCode === 0) {
 		result.exitCode = 1;
 	}
@@ -1177,6 +1229,7 @@ async function runSingleAttempt(
 
 	const acceptanceOutput = getFinalOutput(result.messages ?? []);
 	let fullOutput = stripAcceptanceReport(acceptanceOutput);
+	result.outputState = fullOutput.trim() || result.structuredOutput !== undefined ? "present" : "absent";
 	if (result.timedOut) {
 		const timeoutMessage = formatTimeoutMessage(options.timeoutMs ?? 0);
 		fullOutput = fullOutput.trim()
@@ -1236,6 +1289,7 @@ async function runSingleAttempt(
 			result.outputSaveError = resolvedOutput.saveError;
 			if (resolvedOutput.savedPath) {
 				result.outputReference = formatSavedOutputReference(resolvedOutput.savedPath, fullOutput);
+				if (result.outputState === "absent") result.outputState = "unknown";
 			}
 	}
 		artifactOutputByResult.set(result, fullOutput);
@@ -1265,7 +1319,7 @@ async function runSingleAttempt(
 /**
  * Run a subagent synchronously (blocking until complete)
  */
-export async function runSync(
+async function runSyncCompletion(
 	runtimeCwd: string,
 	agents: AgentConfig[],
 	agentName: string,
@@ -1274,11 +1328,12 @@ export async function runSync(
 ): Promise<SingleResult> {
 	options = {
 		...options,
-		capabilityCeiling: options.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(options.parentSessionId),
+		capabilityCeiling: intersectSubagentCapabilityCeilings(options.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(options.parentSessionId), decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV])),
 	};
 	const agent = agents.find((a) => a.name === agentName);
 	if (!agent) {
 		return withRunContext({
+			index: options.index ?? 0,
 			agent: agentName,
 			task,
 			exitCode: 1,
@@ -1287,9 +1342,23 @@ export async function runSync(
 			error: `Unknown agent: ${agentName}`,
 		}, options.context);
 	}
+	try {
+		assertAgentAllowedByCapabilityCeiling(agent.name, options.capabilityCeiling);
+	} catch (error) {
+		return withRunContext({
+			agent: agent.name,
+			task,
+			exitCode: 1,
+			messages: [],
+			usage: emptyUsage(),
+			error: error instanceof Error ? error.message : String(error),
+			...(options.capabilityCeiling ? { capabilityCeiling: options.capabilityCeiling } : {}),
+		}, options.context);
+	}
 	const outputModeValidationError = validateFileOnlyOutputMode(options.outputMode, options.outputPath, `Single run (${agentName})`);
 	if (outputModeValidationError) {
 		return withRunContext({
+			index: options.index ?? 0,
 			agent: agentName,
 			task,
 			exitCode: 1,
@@ -1326,6 +1395,7 @@ export async function runSync(
 	);
 	if (skillNames.some((skill) => skill.trim() === "pi-subagents") && missingSkills.includes("pi-subagents")) {
 		return withRunContext({
+			index: options.index ?? 0,
 			agent: agentName,
 			task,
 			exitCode: 1,
@@ -1385,83 +1455,42 @@ export async function runSync(
 	}
 
 	const persistResultMetadata = (target: SingleResult): void => {
-		if (!artifactPathsResult || options.artifactConfig?.enabled === false || options.artifactConfig?.includeMetadata === false) return;
-		writeMetadata(artifactPathsResult.metadataPath, {
+		persistSingleResultMetadata({
+			metadataPath: artifactPathsResult?.metadataPath,
+			enabled: options.artifactConfig?.enabled !== false && options.artifactConfig?.includeMetadata !== false,
 			runId: options.runId,
 			agent: agentName,
 			task,
-			exitCode: target.exitCode,
-			processSignal: target.processSignal,
-			usage: target.usage,
-			model: target.model,
-			attemptedModels: target.attemptedModels,
-			modelAttempts: target.modelAttempts,
-			durationMs: target.progressSummary?.durationMs,
-			toolCount: target.progressSummary?.toolCount,
-			error: target.error,
-			agentContract: target.agentContract,
-			launchContractDigest: target.launchContractDigest,
-			execution: target.execution,
-			acceptance: target.acceptance,
-			capabilityCeiling: target.capabilityCeiling,
-			capabilityAudit: target.capabilityAudit,
-			review: target.review,
-			effects: target.effects,
-			...(transcriptWriter ? { transcriptPath: artifactPathsResult.transcriptPath } : {}),
-			transcriptError: target.transcriptError,
-			skills: target.skills,
-			skillsWarning: target.skillsWarning,
-			timestamp: Date.now(),
+			result: target,
 		});
 	};
 
-	const detachedAwareOptions: RunSyncOptions = options.onDetachedExit
-		? {
-			...options,
-			onDetachedExit: (recoveredResult) => {
-				void (async () => {
-					const childWrittenOutput = options.outputPath
-						? extractChildWrittenOutput(recoveredResult.messages, options.outputPath, options.cwd ?? runtimeCwd)
-						: undefined;
-					recoveredResult.acceptance = await evaluateAcceptance({
-						acceptance: effectiveAcceptance,
-						output: acceptanceOutputByResult.get(recoveredResult) ?? recoveredResult.finalOutput ?? "",
-						fileOutput: childWrittenOutput !== undefined && options.outputPath
-							? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
-							: undefined,
-						cwd: options.cwd ?? runtimeCwd,
-						reportOptional: isAgentContractV1(options.agentContract),
-					});
-					const acceptanceFailure = acceptanceFailureMessage(recoveredResult.acceptance);
-					stripAcceptanceReportsFromMessages(recoveredResult.messages);
-					if (acceptanceFailure && recoveredResult.acceptance.explicit && recoveredResult.exitCode === 0 && !isAgentContractV1(options.agentContract)) {
-						recoveredResult.exitCode = 1;
-						recoveredResult.error = recoveredResult.error ? `${recoveredResult.error}\n${acceptanceFailure}` : acceptanceFailure;
-						if (recoveredResult.progress) {
-							recoveredResult.progress.status = "failed";
-							recoveredResult.progress.error = recoveredResult.error;
-						}
-					}
-					if (isAgentContractV1(options.agentContract)) attachContractProjections(recoveredResult);
-					persistResultMetadata(recoveredResult);
-					options.onDetachedExit?.(recoveredResult);
-				})().catch((error) => {
-					const message = error instanceof Error ? error.message : String(error);
-					recoveredResult.exitCode = 1;
-					recoveredResult.error = recoveredResult.error ? `${recoveredResult.error}\nAcceptance evaluation failed: ${message}` : `Acceptance evaluation failed: ${message}`;
-					options.onDetachedExit?.(recoveredResult);
-				});
-			},
-		}
-		: options;
-
+	let intercomDetached = false;
+	let detachedReason: string | undefined;
+	const attemptOptions: RunSyncOptions = {
+		...options,
+		onDetachReceipt: (receipt) => {
+			receipt.acceptance = buildPendingAcceptanceLedger(effectiveAcceptance);
+			try {
+				persistResultMetadata(receipt);
+			} catch (error) {
+				receipt.metadataSaveError = error instanceof Error ? error.message : String(error);
+			}
+			const accepted = options.onDetachReceipt?.(receipt) === true;
+			if (accepted) {
+				detachedReason = receipt.detachedReason;
+				if (receipt.detachedReason === "intercom coordination") intercomDetached = true;
+			}
+			return accepted;
+		},
+	};
 	let lastResult: SingleResult | undefined;
 	const modelsToTry = candidates.length > 0 ? candidates : [undefined];
 	modelAttemptsLoop: for (let modelIndex = 0; modelIndex < modelsToTry.length; modelIndex++) {
 		const candidate = modelsToTry[modelIndex];
 		for (let startupAttemptIndex = 0; ; startupAttemptIndex++) {
 			const outputSnapshot = captureSingleOutputSnapshot(options.outputPath);
-			const result = await runSingleAttempt(runtimeCwd, agent, taskWithAcceptance, candidate, detachedAwareOptions, {
+			const result = await runSingleAttempt(runtimeCwd, agent, taskWithAcceptance, candidate, attemptOptions, {
 				sessionEnabled,
 				systemPrompt,
 				resolvedSkillNames: resolvedSkills.length > 0 ? resolvedSkills.map((skill) => skill.name) : undefined,
@@ -1493,7 +1522,10 @@ export async function runSync(
 				usage: { ...result.usage },
 			};
 			modelAttempts.push(attempt);
-			if (result.detached || result.timedOut || result.turnBudgetExceeded) break modelAttemptsLoop;
+			// Preserve the legacy intercom handoff contract: once this logical run has
+			// been handed to a supervisor, terminating that attempt must not launch a
+			// startup retry or model fallback. Explicit user detach retains fallback.
+			if (intercomDetached || result.timedOut || result.turnBudgetExceeded) break modelAttemptsLoop;
 			if (attemptSucceeded) break modelAttemptsLoop;
 
 			const startupFailure = isRetryableSubagentStartupFailure({
@@ -1565,6 +1597,7 @@ export async function runSync(
 	}
 
 	const result = withRunContext(lastResult ?? {
+		index: options.index ?? 0,
 		agent: agentName,
 		task,
 		exitCode: 1,
@@ -1584,25 +1617,30 @@ export async function runSync(
 	if (transcriptWriter) result.transcriptPath = artifactPathsResult?.transcriptPath;
 	if (transcriptWriter?.getError()) result.transcriptError = transcriptWriter.getError();
 
-	if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
-		result.artifactPaths = artifactPathsResult;
-		if (options.artifactConfig?.includeOutput !== false) {
-			writeArtifact(artifactPathsResult.outputPath, formatOutputArtifactContent({
-				output: artifactOutputByResult.get(result) ?? result.finalOutput ?? "",
-				error: result.error,
-				transcriptPath: result.transcriptPath,
-				metadataPath: options.artifactConfig?.includeMetadata === false ? undefined : artifactPathsResult.metadataPath,
-			}));
-		}
-		if (options.maxOutput) {
+	try {
+		if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
+			result.artifactPaths = artifactPathsResult;
+			if (options.artifactConfig?.includeOutput !== false) {
+				writeArtifact(artifactPathsResult.outputPath, formatOutputArtifactContent({
+					output: artifactOutputByResult.get(result) ?? result.finalOutput ?? "",
+					error: result.error,
+					transcriptPath: result.transcriptPath,
+					metadataPath: options.artifactConfig?.includeMetadata === false ? undefined : artifactPathsResult.metadataPath,
+				}));
+			}
+			if (options.maxOutput) {
+				const config = { ...DEFAULT_MAX_OUTPUT, ...options.maxOutput };
+				const truncationResult = truncateOutput(result.finalOutput ?? "", config, artifactPathsResult.outputPath);
+				if (truncationResult.truncated) result.truncation = truncationResult;
+			}
+		} else if (options.maxOutput) {
 			const config = { ...DEFAULT_MAX_OUTPUT, ...options.maxOutput };
-			const truncationResult = truncateOutput(result.finalOutput ?? "", config, artifactPathsResult.outputPath);
+			const truncationResult = truncateOutput(result.finalOutput ?? "", config);
 			if (truncationResult.truncated) result.truncation = truncationResult;
 		}
-	} else if (options.maxOutput) {
-		const config = { ...DEFAULT_MAX_OUTPUT, ...options.maxOutput };
-		const truncationResult = truncateOutput(result.finalOutput ?? "", config);
-		if (truncationResult.truncated) result.truncation = truncationResult;
+	} catch (error) {
+		const message = `Artifact output post-processing failed: ${error instanceof Error ? error.message : String(error)}`;
+		result.outputSaveError = result.outputSaveError ? `${result.outputSaveError}\n${message}` : message;
 	}
 
 	if (options.sessionFile && (existsSync(options.sessionFile) || result.messages?.length)) {
@@ -1615,28 +1653,36 @@ export async function runSync(
 	const childWrittenOutput = options.outputPath
 		? extractChildWrittenOutput(result.messages, options.outputPath, options.cwd ?? runtimeCwd)
 		: undefined;
-	if (result.detached) {
-		result.acceptance = buildPendingAcceptanceLedger(effectiveAcceptance);
-	} else if (result.stopped) {
-		result.acceptance = buildSkippedAcceptanceLedger(effectiveAcceptance, { id: "stopped", message: "Acceptance was not evaluated because the subagent was stopped." });
-	} else if (result.timedOut) {
-		result.acceptance = buildSkippedAcceptanceLedger(effectiveAcceptance, { id: "timeout", message: "Acceptance was not evaluated because the subagent timed out." });
-	} else if (result.turnBudgetExceeded) {
-		result.acceptance = buildSkippedAcceptanceLedger(effectiveAcceptance, { id: "turn-budget", message: "Acceptance was not evaluated because the subagent exceeded its turn budget." });
-	} else {
-		result.acceptance = await evaluateAcceptance({
-			acceptance: effectiveAcceptance,
-			output: acceptanceOutputByResult.get(result) ?? result.finalOutput ?? "",
-			fileOutput: childWrittenOutput !== undefined && options.outputPath
-				? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
-				: undefined,
-			cwd: options.cwd ?? runtimeCwd,
-			reportOptional: isAgentContractV1(options.agentContract),
-		});
+	try {
+		if (result.interrupted && detachedReason === "user request") {
+			// Only an accepted user-detach receipt needs a non-rejecting terminal
+			// ledger. Attached and background execution retain their baseline
+			// acceptance behavior.
+			result.acceptance = buildInterruptedAcceptanceLedger(effectiveAcceptance);
+		} else if (result.stopped) {
+			result.acceptance = buildSkippedAcceptanceLedger(effectiveAcceptance, { id: "stopped", message: "Acceptance was not evaluated because the subagent was stopped." });
+		} else if (result.timedOut) {
+			result.acceptance = buildSkippedAcceptanceLedger(effectiveAcceptance, { id: "timeout", message: "Acceptance was not evaluated because the subagent timed out." });
+		} else if (result.turnBudgetExceeded) {
+			result.acceptance = buildSkippedAcceptanceLedger(effectiveAcceptance, { id: "turn-budget", message: "Acceptance was not evaluated because the subagent exceeded its turn budget." });
+		} else {
+			result.acceptance = await evaluateAcceptance({
+				acceptance: effectiveAcceptance,
+				output: acceptanceOutputByResult.get(result) ?? result.finalOutput ?? "",
+				fileOutput: childWrittenOutput !== undefined && options.outputPath
+					? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
+					: undefined,
+				cwd: options.cwd ?? runtimeCwd,
+				reportOptional: isAgentContractV1(options.agentContract),
+			});
+		}
+	} catch (error) {
+		const message = `Acceptance evaluation failed: ${error instanceof Error ? error.message : String(error)}`;
+		result.acceptance = buildSkippedAcceptanceLedger(effectiveAcceptance, { id: "acceptance-evaluation", message });
 	}
 	const acceptanceFailure = acceptanceFailureMessage(result.acceptance);
 	stripAcceptanceReportsFromMessages(result.messages);
-	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted && !result.timedOut && !isAgentContractV1(options.agentContract)) {
+	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.interrupted && !result.timedOut && !isAgentContractV1(options.agentContract)) {
 		result.exitCode = 1;
 		result.error = result.error ? `${result.error}\n${acceptanceFailure}` : acceptanceFailure;
 		if (result.progress) {
@@ -1645,7 +1691,143 @@ export async function runSync(
 		}
 	}
 	if (isAgentContractV1(options.agentContract)) attachContractProjections(result);
-	persistResultMetadata(result);
+	try {
+		persistResultMetadata(result);
+	} catch (error) {
+		result.metadataSaveError = error instanceof Error ? error.message : String(error);
+	}
 
 	return result;
 }
+
+/**
+ * Runs the authoritative completion pipeline independently from the foreground
+ * receipt. Detachment is same-runtime only: it does not adopt or daemonize work.
+ */
+export async function runSync(
+	runtimeCwd: string,
+	agents: AgentConfig[],
+	agentName: string,
+	task: string,
+	options: RunSyncOptions,
+): Promise<SingleResult> {
+	// Capture the strict contract before consumer-owned objects can be mutated
+	// after a detached receipt is published.
+	const strictContract = isAgentContractV1(options.agentContract);
+	let detachedReason: string | undefined;
+	let publishedReceipt: SingleResult | undefined;
+	let activeDetachAttempt: ((reason?: string) => boolean) | undefined;
+	let detachReadyPublished = false;
+	let resolveReceipt!: (result: SingleResult) => void;
+	const receipt = new Promise<SingleResult>((resolve) => { resolveReceipt = resolve; });
+	const originSignal = options.signal;
+	const originController = new AbortController();
+	const forwardOriginAbort = () => {
+		if (!detachedReason) originController.abort(originSignal?.reason);
+	};
+	if (originSignal?.aborted) forwardOriginAbort();
+	else originSignal?.addEventListener("abort", forwardOriginAbort, { once: true });
+
+	const completion = runSyncCompletion(runtimeCwd, agents, agentName, task, {
+		...options,
+		signal: originController.signal,
+		onDetachedExit: undefined,
+		onDetachReceipt: (detachedReceipt) => {
+			if (detachedReason || publishedReceipt) return false;
+			// Keep the authoritative result, fallback snapshot, and caller receipt
+			// separately owned while the completion pipeline remains live.
+			publishedReceipt = structuredClone(detachedReceipt);
+			const callerReceipt = structuredClone(detachedReceipt);
+			// A strict contract was already validated before detach; normalize private
+			// and caller snapshots to the only safely known version.
+			publishedReceipt.agentContract = strictContract ? { version: 1 } : undefined;
+			callerReceipt.agentContract = strictContract ? { version: 1 } : undefined;
+			detachedReason = detachedReceipt.detachedReason ?? "user request";
+			resolveReceipt(callerReceipt);
+			return true;
+		},
+		onDetachReady: (detachAttempt) => {
+			activeDetachAttempt = detachAttempt;
+			if (detachReadyPublished) return;
+			detachReadyPublished = true;
+			options.onDetachReady?.((reason = "user request") => {
+				if (detachedReason || originController.signal.aborted) return false;
+				return activeDetachAttempt?.(reason) ?? false;
+			});
+		},
+	});
+
+	const authoritativeCompletion = completion.catch((error: unknown) => {
+		if (!publishedReceipt || !detachedReason) throw error;
+		const message = error instanceof Error ? error.message : String(error);
+		const failureMessage = `Detached completion pipeline failed after receipt: ${message}`;
+		const failedProgress: AgentProgress = publishedReceipt.progress
+			? { ...publishedReceipt.progress, status: "failed", error: failureMessage }
+			: {
+				index: options.index ?? 0,
+				agent: publishedReceipt.agent,
+				status: "failed",
+				task: publishedReceipt.task,
+				recentTools: [],
+				recentOutput: [],
+				toolCount: publishedReceipt.progressSummary?.toolCount ?? 0,
+				tokens: publishedReceipt.progressSummary?.tokens ?? 0,
+				durationMs: publishedReceipt.progressSummary?.durationMs ?? 0,
+				error: failureMessage,
+			};
+		const failedResult: SingleResult = {
+			...publishedReceipt,
+			detached: undefined,
+			detachedReason,
+			exitCode: 1,
+			error: failureMessage,
+			finalOutput: failureMessage,
+			progress: failedProgress,
+			progressSummary: {
+				toolCount: failedProgress.toolCount,
+				tokens: failedProgress.tokens,
+				durationMs: failedProgress.durationMs,
+			},
+			acceptance: publishedReceipt.acceptance
+				? buildSkippedAcceptanceLedger(publishedReceipt.acceptance.effectiveAcceptance, { id: "completion-pipeline", message: failureMessage })
+				: undefined,
+		};
+		if (strictContract) attachContractProjections(failedResult);
+		try {
+			// Replace the provisional detach receipt metadata with the authoritative
+			// terminal failure. Persistence remains best-effort and cannot orphan work.
+			persistSingleResultMetadata({
+				metadataPath: failedResult.artifactPaths?.metadataPath,
+				enabled: options.artifactConfig?.enabled !== false && options.artifactConfig?.includeMetadata !== false,
+				runId: options.runId,
+				agent: failedResult.agent,
+				task: failedResult.task,
+				result: failedResult,
+			});
+		} catch (metadataError) {
+			failedResult.metadataSaveError = metadataError instanceof Error ? metadataError.message : String(metadataError);
+		}
+		return failedResult;
+	});
+
+	let terminalCallbackInvoked = false;
+	void authoritativeCompletion.then((terminalResult) => {
+		if (!detachedReason || terminalCallbackInvoked) return;
+		terminalCallbackInvoked = true;
+		terminalResult.detached = undefined;
+		terminalResult.detachedReason = detachedReason;
+		try {
+			options.onDetachedExit?.(terminalResult);
+		} catch {
+			// The authoritative result has settled. Consumer callback failures are
+			// contained here; each consumer owns cleanup through its own finally block.
+		}
+	}).catch(() => {
+		// Attached completion rejection remains observable through the returned
+		// promise without becoming an unhandled side-channel rejection.
+	}).finally(() => {
+		originSignal?.removeEventListener("abort", forwardOriginAbort);
+	});
+
+	return Promise.race([authoritativeCompletion, receipt]);
+}