@bastani/atomic 0.9.4 → 0.9.5-alpha.10

package/dist/builtin/subagents/src/runs/background/subagent-runner-streaming.ts

@@ -1,11 +1,10 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import type { Message } from "@earendil-works/pi-ai/compat";
-import { appendJsonl } from "../../shared/artifacts.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "../../shared/utils.ts";
 import { getSubagentDepthEnv } from "../../shared/types.ts";
-import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
+import { formatPiSpawnError, getPiSpawnCommand, validatePiSpawnCwd } from "../shared/pi-spawn.ts";
 import {
 	assistantStopReason,
 	isAssistantFailureStopReason,
@@ -14,6 +13,7 @@ import {
 import { modelFailureMessage } from "../shared/model-fallback.ts";
 import { createAttemptWatchdog } from "../shared/attempt-watchdog.ts";
 import type { ChildEvent, ChildEventContext, RunPiStreamingResult } from "./subagent-runner-types.ts";
+import { createChildEventJournal } from "./async-event-journal.ts";
 import { emptyUsage } from "./subagent-runner-utils.ts";
 
 export function runPiStreaming(
@@ -29,6 +29,17 @@ export function runPiStreaming(
 	registerInterrupt?: (interrupt: (() => void) | undefined) => void,
 	onChildEvent?: (event: ChildEvent) => void,
 ): Promise<RunPiStreamingResult> {
+	const cwdValidation = validatePiSpawnCwd(cwd);
+	if (!cwdValidation.ok) {
+		return Promise.resolve({
+			stderr: "",
+			exitCode: 1,
+			messages: [],
+			usage: emptyUsage(),
+			error: cwdValidation.error,
+			finalOutput: "",
+		});
+	}
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
 		const spawnEnv = {
@@ -46,6 +57,11 @@ export function runPiStreaming(
 			env: spawnEnv,
 			windowsHide: true,
 		});
+		const childEventJournal = createChildEventJournal(childEventContext?.eventsPath, child.stdout, {
+			runId: childEventContext?.runId ?? "",
+			stepIndex: childEventContext?.stepIndex,
+			agent: childEventContext?.agent ?? "",
+		});
 		let stderr = "";
 		let stdoutBuf = "";
 		let stderrBuf = "";
@@ -55,6 +71,7 @@ export function runPiStreaming(
 		let error: string | undefined;
 		let assistantError: string | undefined;
 		let assistantFailureSignal: unknown;
+		let spawnErrorText: string | undefined;
 		let interrupted = false;
 		let activeToolExecutions = 0;
 		const rawStdoutLines: string[] = [];
@@ -72,14 +89,7 @@ export function runPiStreaming(
 
 		const appendChildEvent = (event: Record<string, unknown> | ChildEvent) => {
 			if (!childEventContext) return;
-			appendJsonl(childEventContext.eventsPath, JSON.stringify({
-				...event,
-				subagentSource: "child",
-				subagentRunId: childEventContext.runId,
-				subagentStepIndex: childEventContext.stepIndex,
-				subagentAgent: childEventContext.agent,
-				observedAt: Date.now(),
-			}));
+			childEventJournal.append({ ...event });
 		};
 
 		const appendChildLine = (type: "subagent.child.stdout" | "subagent.child.stderr", line: string) => {
@@ -238,7 +248,7 @@ export function runPiStreaming(
 			childExited = true;
 			clearDrainTimers();
 		});
-		child.on("close", (exitCode, signal) => {
+		child.on("close", async (exitCode, signal) => {
 			settled = true;
 			registerInterrupt?.(undefined);
 			clearDrainTimers();
@@ -247,8 +257,9 @@ export function runPiStreaming(
 			if (stdoutBuf.trim()) processStdoutLine(stdoutBuf);
 			if (stderrBuf.trim()) appendChildLine("subagent.child.stderr", stderrBuf);
 			outputStream.end();
+			await childEventJournal.close();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
-			const finalError = error ?? assistantError;
+			const finalError = error ?? assistantError ?? spawnErrorText;
 			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !finalError;
 			resolve({
 				stderr,
@@ -265,16 +276,19 @@ export function runPiStreaming(
 			});
 		});
 
-		child.on("error", (spawnError) => {
+		child.on("error", async (spawnError) => {
+			// Capture the diagnostic before awaiting journal drain: `close` may fire
+			// while this handler is suspended and win Promise settlement.
+			spawnErrorText = formatPiSpawnError(spawnError, spawnSpec, cwd);
 			settled = true;
 			registerInterrupt?.(undefined);
 			clearDrainTimers();
 			clearStdioGuard();
 			attemptWatchdog.clear();
 			outputStream.end();
+			await childEventJournal.close();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
-			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			const finalError = error ?? assistantError ?? spawnErrorMessage;
+			const finalError = error ?? assistantError ?? spawnErrorText;
 			resolve({
 				stderr,
 				exitCode: 1,

package/dist/builtin/subagents/src/runs/background/top-level-async.ts

@@ -1,6 +1,5 @@
 interface AsyncOverrideParams {
 	async?: boolean;
-	clarify?: boolean;
 }
 
 export function applyForceTopLevelAsyncOverride<T extends AsyncOverrideParams>(
@@ -9,5 +8,5 @@ export function applyForceTopLevelAsyncOverride<T extends AsyncOverrideParams>(
 	forceTopLevelAsync: boolean,
 ): T {
 	if (!(depth === 0 && forceTopLevelAsync)) return params;
-	return { ...params, async: true, clarify: false };
+	return { ...params, async: true };
 }

package/dist/builtin/subagents/src/runs/foreground/chain-execution-dynamic-step.ts

@@ -129,6 +129,7 @@ export async function runDynamicParallelChainStep(input: {
 		maxSubagentDepth: context.params.maxSubagentDepth,
 		workflowStageSubagentGuard: context.params.workflowStageSubagentGuard,
 		runSync: context.executeRunSync,
+		onDetachedExit: context.onDetachedExit,
 	});
 	state.globalTaskIndex += dynamicParallelStep.parallel.length;
 	for (const result of parallelResults) {

package/dist/builtin/subagents/src/runs/foreground/chain-execution-parallel-runner.ts

@@ -123,6 +123,7 @@ export async function runParallelChainTasks(input: ParallelChainRunInput): Promi
 			intercomSessionName: input.childIntercomTarget?.(task.agent, input.globalTaskIndex + taskIndex),
 			orchestratorIntercomTarget: input.orchestratorIntercomTarget,
 			nestedRoute: input.nestedRoute,
+			onDetachedExit: (recovered) => input.onDetachedExit?.(input.globalTaskIndex + taskIndex, recovered),
 			modelOverride: effectiveModel,
 			availableModels: input.availableModels,
 			knownModelProviders: input.knownModelProviders,

package/dist/builtin/subagents/src/runs/foreground/chain-execution-parallel-step.ts

@@ -112,6 +112,7 @@ export async function runStaticParallelChainStep(input: {
 			maxSubagentDepth: context.params.maxSubagentDepth,
 			workflowStageSubagentGuard: context.params.workflowStageSubagentGuard,
 			runSync: context.executeRunSync,
+			onDetachedExit: context.onDetachedExit,
 		});
 		state.globalTaskIndex += step.parallel.length;
 		for (const result of parallelResults) {

package/dist/builtin/subagents/src/runs/foreground/chain-execution-sequential-step.ts

@@ -20,7 +20,6 @@ import { validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { createStructuredOutputRuntime } from "../shared/structured-output.ts";
 import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
 import { buildChainExecutionDetails, buildChainExecutionErrorResult } from "./chain-execution-details.ts";
-import type { BehaviorOverride } from "./chain-clarify.ts";
 import type { ChainExecutionMutableState, ChainExecutionResult, ChainRuntimeContext } from "./chain-execution-types.ts";
 
 export async function runSequentialChainStep(input: {
@@ -29,9 +28,8 @@ export async function runSequentialChainStep(input: {
 	seqStep: SequentialStep;
 	stepIndex: number;
 	stepTemplate: string;
-	tuiOverride?: BehaviorOverride;
 }): Promise<ChainExecutionResult | undefined> {
-	const { context, state, seqStep, stepIndex, stepTemplate, tuiOverride } = input;
+	const { context, state, seqStep, stepIndex, stepTemplate } = input;
 	const agentConfig = context.agents.find((agent) => agent.name === seqStep.agent);
 	if (!agentConfig) {
 		removeChainDir(context.chainDir);
@@ -43,11 +41,11 @@ export async function runSequentialChainStep(input: {
 	}
 
 	const stepOverride: StepOverrides = {
-		output: tuiOverride?.output !== undefined ? tuiOverride.output : seqStep.output,
+		output: seqStep.output,
 		outputMode: seqStep.outputMode,
-		reads: tuiOverride?.reads !== undefined ? tuiOverride.reads : seqStep.reads,
-		progress: tuiOverride?.progress !== undefined ? tuiOverride.progress : seqStep.progress,
-		skills: tuiOverride?.skills !== undefined ? tuiOverride.skills : normalizeSkillInput(seqStep.skill),
+		reads: seqStep.reads,
+		progress: seqStep.progress,
+		skills: normalizeSkillInput(seqStep.skill),
 	};
 	const behavior = suppressProgressForReadOnlyTask(
 		resolveStepBehavior(agentConfig, stepOverride, context.chainSkills),
@@ -73,8 +71,7 @@ export async function runSequentialChainStep(input: {
 	stepTask = prefix + stepTask + suffix;
 
 	const effectiveModel =
-		tuiOverride?.model
-		?? (seqStep.model ? resolveModelCandidate(seqStep.model, context.availableModels, context.ctx.model?.provider) : null)
+		(seqStep.model ? resolveModelCandidate(seqStep.model, context.availableModels, context.ctx.model?.provider) : null)
 		?? resolveModelCandidate(agentConfig.model, context.availableModels, context.ctx.model?.provider);
 	const outputPath = typeof behavior.output === "string"
 		? (path.isAbsolute(behavior.output) ? behavior.output : path.join(context.chainDir, behavior.output))
@@ -124,6 +121,7 @@ export async function runSequentialChainStep(input: {
 		intercomSessionName: context.childIntercomTarget?.(seqStep.agent, flatIndex),
 		orchestratorIntercomTarget: context.orchestratorIntercomTarget,
 		nestedRoute: context.params.nestedRoute,
+		onDetachedExit: (recovered) => context.onDetachedExit?.(flatIndex, recovered),
 		modelOverride: effectiveModel,
 		availableModels: context.availableModels,
 		knownModelProviders: context.knownModelProviders,

package/dist/builtin/subagents/src/runs/foreground/chain-execution-types.ts

@@ -6,7 +6,6 @@ import type {
 	ChainStep,
 	ParallelStep,
 	ResolvedStepBehavior,
-	ResolvedTemplates,
 } from "../../shared/settings.ts";
 import type {
 	ActivityState,
@@ -23,7 +22,6 @@ import type {
 import type { ChainOutputMap } from "../../shared/types.ts";
 import type { WorktreeSetup } from "../shared/worktree.ts";
 import type { runSync } from "./execution.ts";
-import type { BehaviorOverride } from "./chain-clarify.ts";
 
 export type RunSyncDependency = typeof runSync;
 
@@ -74,7 +72,6 @@ export interface ChainExecutionParams {
 	artifactsDir: string;
 	artifactConfig: ArtifactConfig;
 	includeProgress?: boolean;
-	clarify?: boolean;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
 	onControlEvent?: (event: ControlEvent) => void;
 	controlConfig: ResolvedControlConfig;
@@ -90,16 +87,13 @@ export interface ChainExecutionParams {
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	runSync?: RunSyncDependency;
+	onDetachedExit?: (index: number, result: SingleResult) => void;
 }
 
 export interface ChainExecutionResult {
 	content: Array<{ type: "text"; text: string }>;
 	details: Details;
 	isError?: boolean;
-	requestedAsync?: {
-		chain: ChainStep[];
-		chainSkills: string[];
-	};
 }
 
 export interface ParallelChainRunInput {
@@ -143,6 +137,7 @@ export interface ParallelChainRunInput {
 	workflowStageSubagentGuard?: boolean;
 	nestedRoute?: NestedRouteInfo;
 	runSync: RunSyncDependency;
+	onDetachedExit?: (index: number, result: SingleResult) => void;
 }
 
 export interface ChainExecutionMutableState {
@@ -187,10 +182,5 @@ export interface ChainRuntimeContext {
 	totalSteps: number;
 	executeRunSync: RunSyncDependency;
 	makeDetailsInput(overrides?: Pick<Partial<ChainExecutionDetailsInput>, "currentStepIndex" | "currentFlatIndex">): ChainExecutionDetailsInput;
+	onDetachedExit?: (index: number, result: SingleResult) => void;
 }
-
-export type ChainClarificationOutcome = {
-	result?: ChainExecutionResult;
-	templates: ResolvedTemplates;
-	tuiBehaviorOverrides?: (BehaviorOverride | undefined)[];
-};

package/dist/builtin/subagents/src/runs/foreground/chain-execution.ts

@@ -14,7 +14,6 @@ import {
 import { buildChainSummary } from "../../shared/formatters.ts";
 import { ChainOutputValidationError, validateChainOutputBindings } from "../shared/chain-outputs.ts";
 import { buildChainExecutionDetails } from "./chain-execution-details.ts";
-import { resolveChainClarification } from "./chain-execution-clarify.ts";
 import { runDynamicParallelChainStep } from "./chain-execution-dynamic-step.ts";
 import { runStaticParallelChainStep } from "./chain-execution-parallel-step.ts";
 import { runSequentialChainStep } from "./chain-execution-sequential-step.ts";
@@ -45,7 +44,6 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		artifactsDir,
 		artifactConfig,
 		includeProgress,
-		clarify,
 		onUpdate,
 		onControlEvent,
 		controlConfig,
@@ -113,9 +111,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 	}
 
 	const chainDir = createChainDir(runId, chainDirBase);
-	const hasParallelSteps = chainSteps.some((step) => isParallelStep(step) || isDynamicParallelStep(step));
-	let templates: ResolvedTemplates = resolveChainTemplates(chainSteps);
-	let tuiBehaviorOverrides: Awaited<ReturnType<typeof resolveChainClarification>>["tuiBehaviorOverrides"];
+	const templates: ResolvedTemplates = resolveChainTemplates(chainSteps);
 	const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map(toModelInfo);
 	const knownModelProviders = collectKnownModelProviders(ctx.modelRegistry);
 	const context: ChainRuntimeContext = {
@@ -148,17 +144,9 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		totalSteps,
 		executeRunSync,
 		makeDetailsInput,
+		onDetachedExit: params.onDetachedExit,
 	};
 
-	const clarification = await resolveChainClarification({
-		context,
-		templates,
-		shouldClarify: clarify !== false && ctx.hasUI && !hasParallelSteps,
-	});
-	if (clarification.result) return clarification.result;
-	templates = clarification.templates;
-	tuiBehaviorOverrides = clarification.tuiBehaviorOverrides;
-
 	for (let stepIndex = 0; stepIndex < chainSteps.length; stepIndex++) {
 		const step = chainSteps[stepIndex]!;
 		const stepTemplates = templates[stepIndex]!;
@@ -180,7 +168,6 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				seqStep: step as SequentialStep,
 				stepIndex,
 				stepTemplate: stepTemplates as string,
-				tuiOverride: tuiBehaviorOverrides?.[stepIndex],
 			});
 		}
 		if (earlyResult) return earlyResult;

package/dist/builtin/subagents/src/runs/foreground/execution-attempt-finalize.ts

@@ -33,8 +33,8 @@ export function finalizeSingleAttempt(input: {
 		return result;
 	}
 	if (result.detached) {
-		result.exitCode = 0;
-		result.finalOutput = "Detached for intercom coordination.";
+		result.exitCode = -2;
+		result.finalOutput = "Detached for intercom coordination; awaiting the child's eventual result.";
 		return result;
 	}
 

package/dist/builtin/subagents/src/runs/foreground/execution-attempt.ts

@@ -3,21 +3,19 @@ import { existsSync, unlinkSync } from "node:fs";
 import type { Message } from "@earendil-works/pi-ai/compat";
 import type { AgentConfig } from "../../agents/agents.ts";
 import {
-	type AgentProgress,
-	type RunSyncOptions,
-	type SingleResult,
-	INTERCOM_DETACH_REQUEST_EVENT,
-	INTERCOM_DETACH_RESPONSE_EVENT,
-	getSubagentDepthEnv,
+	type AgentProgress, type RunSyncOptions, type SingleResult,
+	INTERCOM_DETACH_REQUEST_EVENT, INTERCOM_DETACH_RESPONSE_EVENT, getSubagentDepthEnv,
 } from "../../shared/types.ts";
 import { extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "../../shared/utils.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
-import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
+import { formatPiSpawnError, getPiSpawnCommand, validatePiSpawnCwd } from "../shared/pi-spawn.ts";
 import { assistantStopReason, isAssistantFailureStopReason, shouldStartSubagentFinalDrain } from "../shared/final-drain.ts";
 import { modelFailureMessage } from "../shared/model-fallback.ts";
 import { createAttemptWatchdog } from "../shared/attempt-watchdog.ts";
+import { matchesIntercomDetachRoute, type IntercomDetachRoute } from "./execution-detach-route.ts";
+import { IntercomDetachReservations } from "./execution-detach-reservations.ts";
 import {
 	createMutatingFailureState,
 	didMutatingToolFail,
@@ -33,7 +31,6 @@ import { appendRecentOutput, emptyUsage, modelFailureSignalByResult, snapshotPro
 import { createAttemptControlRuntime } from "./execution-attempt-control.ts";
 import { finalizeSingleAttempt } from "./execution-attempt-finalize.ts";
 import type { RunSingleAttemptShared } from "./execution-attempt-types.ts";
-
 export async function runSingleAttempt(
 	runtimeCwd: string,
 	agent: AgentConfig,
@@ -80,7 +77,6 @@ export async function runSingleAttempt(
 		codexFastModeScope: shared.fastModeScope,
 		structuredOutput: options.structuredOutput,
 	});
-
 	const result: SingleResult = {
 		agent: agent.name,
 		task: shared.originalTask ?? task,
@@ -124,6 +120,14 @@ export async function runSingleAttempt(
 			workflowStageSubagentGuard: options.workflowStageSubagentGuard,
 		}),
 	};
+	const cwdValidation = validatePiSpawnCwd(runCwd);
+	if (!cwdValidation.ok) {
+		cleanupTempDir(tempDir);
+		result.error = cwdValidation.error;
+		return finalizeSingleAttempt({
+			result, progress, exitCode: 1, interruptedByControl, allControlEvents: controlRuntime.allControlEvents, options, shared, startTime,
+		});
+	}
 	const exitCode = await new Promise<number>((resolve) => {
 		const spawnSpec = getPiSpawnCommand(args);
 		const proc = spawn(spawnSpec.command, spawnSpec.args, {
@@ -137,24 +141,21 @@ export async function runSingleAttempt(
 		let processClosed = false;
 		let settled = false;
 		let detached = false;
-		let intercomStarted = false;
 		let assistantError: string | undefined;
 		let assistantFailureSignal: unknown;
 		let removeAbortListener: (() => void) | undefined;
 		let removeInterruptListener: (() => void) | undefined;
 		let activityTimer: NodeJS.Timeout | undefined;
-
 		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 };
-			finish(-2);
+			// Settle the foreground tool call, but retain process lifecycle ownership.
+			finish(-2, true);
 		};
-
 		const FINAL_STOP_GRACE_MS = 1000;
 		const HARD_KILL_MS = 3000;
 		let childExited = false;
@@ -173,9 +174,9 @@ export async function runSingleAttempt(
 			}
 		};
 		const startFinalDrain = () => {
-			if (childExited || finalDrainTimer || settled || processClosed || detached) return;
+			if (childExited || finalDrainTimer || processClosed) return;
 			finalDrainTimer = setTimeout(() => {
-				if (settled || processClosed || detached) return;
+				if (processClosed) return;
 				const termSent = trySignalChild(proc, "SIGTERM");
 				if (!termSent) return;
 				forcedTerminationSignal = true;
@@ -183,39 +184,49 @@ export async function runSingleAttempt(
 					result.error = result.error ?? `Subagent process did not exit within ${FINAL_STOP_GRACE_MS}ms after its final message. Forcing termination.`;
 				}
 				finalHardKillTimer = setTimeout(() => {
-					if (settled || processClosed || detached) return;
+					if (processClosed) return;
 					forcedTerminationSignal = trySignalChild(proc, "SIGKILL") || forcedTerminationSignal;
 				}, HARD_KILL_MS);
 				finalHardKillTimer.unref?.();
 			}, FINAL_STOP_GRACE_MS);
 			finalDrainTimer.unref?.();
 		};
-
+		const detachReservations = new IntercomDetachReservations();
 		const unsubscribeIntercomDetach = options.intercomEvents?.on?.(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
-			if (!options.allowIntercomDetach || detached || processClosed || !intercomStarted) return;
+			if (!options.allowIntercomDetach || processClosed || options.signal?.aborted) return;
 			if (!payload || typeof payload !== "object") return;
-			const requestId = (payload as { requestId?: unknown }).requestId;
-			if (typeof requestId !== "string" || requestId.length === 0) return;
-			options.intercomEvents?.emit(INTERCOM_DETACH_RESPONSE_EVENT, { requestId, accepted: true });
+			const event = payload as IntercomDetachRoute;
+			const reservationKeyValid = typeof event.requestId === "string";
+			if (!reservationKeyValid || !matchesIntercomDetachRoute(event, {
+				childIntercomTarget: options.intercomSessionName,
+			})) return;
+			if (event.phase === "probe") {
+				if (detached || !detachReservations.reserve(event)) return;
+				options.intercomEvents?.emit?.(INTERCOM_DETACH_RESPONSE_EVENT, { ...event, accepted: true });
+				return;
+			}
+			if (event.phase !== "commit" || detached || !detachReservations.commit(event)) return;
 			detachForIntercom();
+			options.intercomEvents?.emit?.(INTERCOM_DETACH_RESPONSE_EVENT, { ...event, accepted: true });
 		});
-
-		const finish = (code: number) => {
+		const finish = (code: number, retainLifecycleOwner = false) => {
 			if (settled) return;
 			settled = true;
-			clearFinalDrainTimers();
-			clearStdioGuard();
-			attemptWatchdog.clear();
+			if (!retainLifecycleOwner) {
+				clearFinalDrainTimers();
+				clearStdioGuard();
+				attemptWatchdog.clear();
+				removeAbortListener?.();
+				detachReservations.clear();
+				unsubscribeIntercomDetach?.();
+			}
 			if (activityTimer) {
 				clearInterval(activityTimer);
 				activityTimer = undefined;
 			}
-			unsubscribeIntercomDetach?.();
-			removeAbortListener?.();
 			removeInterruptListener?.();
 			resolve(code);
 		};
-
 		let pendingToolResult: { tool: string; path?: string; mutates: boolean; startedAt?: number } | undefined;
 		const mutatingFailures = createMutatingFailureState();
 		const mutatingFailureWindowMs = 5 * 60_000;
@@ -238,7 +249,6 @@ export async function runSingleAttempt(
 			progress.durationMs = Date.now() - startTime;
 			emitUpdateSnapshot(getFinalOutput(result.messages ?? []) || "(running...)");
 		};
-
 		const processLine = (line: string) => {
 			if (!line.trim()) return;
 			jsonlWriter.writeLine(line);
@@ -256,7 +266,8 @@ export async function runSingleAttempt(
 
 			if (evt.type === "tool_execution_start") {
 				const toolArgs = evt.args && typeof evt.args === "object" && !Array.isArray(evt.args) ? evt.args as Record<string, unknown> : {};
-				if (options.allowIntercomDetach && (evt.toolName === "intercom" || evt.toolName === "contact_supervisor")) intercomStarted = true;
+				// Broker delivery is the authoritative detach trigger; tool-start observation
+				// is intentionally not required because the broker event may arrive first.
 				progress.toolCount++;
 				progress.currentTool = evt.toolName;
 				progress.currentToolArgs = extractToolArgsPreview(toolArgs);
@@ -362,7 +373,7 @@ export async function runSingleAttempt(
 		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
 		const attemptWatchdog = createAttemptWatchdog({
 			child: proc,
-			isSettled: () => settled || processClosed || detached,
+			isSettled: () => processClosed,
 			// A slow, quiet tool call (long build/test run) must not be mistaken for a
 			// stalled attempt: an in-flight tool execution counts as watchdog activity.
 			// Caveat: `progress.currentTool` is cleared on tool_execution_end, so if a
@@ -395,13 +406,12 @@ export async function runSingleAttempt(
 			clearFinalDrainTimers();
 			clearStdioGuard();
 			attemptWatchdog.clear();
+			removeAbortListener?.(); removeAbortListener = undefined;
+			removeInterruptListener?.(); removeInterruptListener = undefined;
+			detachReservations.clear();
+			unsubscribeIntercomDetach?.();
 			void jsonlWriter.close().catch(() => undefined);
 			cleanupTempDir(tempDir);
-			if (detached) {
-				finish(-2);
-				return;
-			}
-			processClosed = true;
 			if (buf.trim()) processLine(buf);
 			if (!result.error && assistantError) result.error = assistantError;
 			if (assistantFailureSignal !== undefined && result.error === assistantError) {
@@ -410,6 +420,17 @@ export async function runSingleAttempt(
 			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && cleanTerminalAssistantStopReceived && !result.error;
 			if (code !== 0 && stderrBuf.trim() && !result.error && !forcedDrainAfterFinalSuccess) result.error = stderrBuf.trim();
 			const finalCode = forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (code ?? 1) : (code ?? 0);
+			if (detached) {
+				processClosed = true;
+				const recovered: SingleResult = { ...result, detached: undefined, detachedReason: undefined };
+				const recoveredProgress = recovered.progress ? { ...recovered.progress } : progress;
+				options.onDetachedExit?.(finalizeSingleAttempt({
+					result: recovered, progress: recoveredProgress, exitCode: finalCode, interruptedByControl,
+					allControlEvents: controlRuntime.allControlEvents, options: { ...options, onUpdate: undefined }, shared, startTime,
+				}));
+				return;
+			}
+			processClosed = true;
 			finish(finalCode);
 		});
 		proc.on("error", (error) => {
@@ -418,19 +439,15 @@ export async function runSingleAttempt(
 			attemptWatchdog.clear();
 			void jsonlWriter.close().catch(() => undefined);
 			cleanupTempDir(tempDir);
-			if (!result.error) result.error = error instanceof Error ? error.message : String(error);
+			if (!result.error) result.error = formatPiSpawnError(error, spawnSpec, runCwd);
 			finish(1);
 		});
 
 		if (options.signal) {
 			const kill = () => {
-				if (processClosed || detached) return;
-				if (options.allowIntercomDetach && intercomStarted) {
-					detachForIntercom();
-					return;
-				}
-				proc.kill("SIGTERM");
-				setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
+				if (childExited) return;
+				trySignalChild(proc, "SIGTERM");
+				setTimeout(() => { if (!childExited) trySignalChild(proc, "SIGKILL"); }, 3000).unref?.();
 			};
 			if (options.signal.aborted) kill();
 			else {

package/dist/builtin/subagents/src/runs/foreground/execution-detach-reservations.ts

@@ -0,0 +1,48 @@
+import type { IntercomDetachRoute } from "./execution-detach-route.js";
+
+interface Reservation {
+	route: IntercomDetachRoute;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+function identity(event: IntercomDetachRoute): string | undefined {
+	if (typeof event.requestId !== "string" || event.requestId.length === 0
+		|| typeof event.messageId !== "string" || event.messageId.length === 0
+		|| typeof event.senderId !== "string" || event.senderId.length === 0
+		|| typeof event.runtimeGeneration !== "number") return undefined;
+	return `${event.requestId}\0${event.messageId}\0${event.senderId}\0${event.runtimeGeneration}`;
+}
+
+function sameRoute(left: IntercomDetachRoute, right: IntercomDetachRoute): boolean {
+	return left.requestId === right.requestId && left.messageId === right.messageId
+		&& left.senderId === right.senderId && left.runtimeGeneration === right.runtimeGeneration
+		&& left.childIntercomTarget === right.childIntercomTarget;
+}
+
+export class IntercomDetachReservations {
+	private readonly entries = new Map<string, Reservation>();
+
+	reserve(event: IntercomDetachRoute): boolean {
+		const key = identity(event);
+		if (!key || this.entries.has(key)) return false;
+		const timer = setTimeout(() => this.entries.delete(key), 1000);
+		timer.unref?.();
+		this.entries.set(key, { route: event, timer });
+		return true;
+	}
+
+	commit(event: IntercomDetachRoute): boolean {
+		const key = identity(event);
+		if (!key) return false;
+		const reservation = this.entries.get(key);
+		if (!reservation || !sameRoute(event, reservation.route)) return false;
+		clearTimeout(reservation.timer);
+		this.entries.delete(key);
+		return true;
+	}
+
+	clear(): void {
+		for (const reservation of this.entries.values()) clearTimeout(reservation.timer);
+		this.entries.clear();
+	}
+}

package/dist/builtin/subagents/src/runs/foreground/execution-detach-route.ts

@@ -0,0 +1,17 @@
+export interface IntercomDetachRoute {
+	phase?: unknown;
+	requestId?: unknown;
+	messageId?: unknown;
+	senderId?: unknown;
+	childIntercomTarget?: unknown;
+	runtimeGeneration?: unknown;
+}
+
+export function matchesIntercomDetachRoute(
+	event: IntercomDetachRoute,
+	expected: { childIntercomTarget?: string },
+): boolean {
+	return typeof event.childIntercomTarget === "string"
+		&& event.childIntercomTarget.length > 0
+		&& event.childIntercomTarget === expected.childIntercomTarget;
+}