pi-subagents 0.31.0 → 0.32.0

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

@@ -2,9 +2,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
 import { formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.ts";
-import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type NestedRunSummary, type SubagentRunMode, type TokenUsage } from "../../shared/types.ts";
+import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type NestedRunSummary, type SubagentRunMode, type TokenUsage } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
-import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot } from "../shared/nested-events.ts";
+import { attachRootChildrenToSteps, buildNestedRouteIndex, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
 import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
@@ -29,11 +29,13 @@ interface AsyncRunStepSummary {
 	toolCount?: number;
 	durationMs?: number;
 	tokens?: TokenUsage;
+	totalCost?: CostSummary;
 	skills?: string[];
 	model?: string;
 	thinking?: string;
 	attemptedModels?: string[];
 	error?: string;
+	timedOut?: boolean;
 	children?: NestedRunSummary[];
 }
 
@@ -42,6 +44,7 @@ export interface AsyncRunSummary {
 	asyncDir: string;
 	sessionId?: string;
 	state: "queued" | "running" | "complete" | "failed" | "paused";
+	error?: string;
 	activityState?: ActivityState;
 	lastActivityAt?: number;
 	currentTool?: string;
@@ -54,6 +57,9 @@ export interface AsyncRunSummary {
 	startedAt: number;
 	lastUpdate?: number;
 	endedAt?: number;
+	timeoutMs?: number;
+	deadlineAt?: number;
+	timedOut?: boolean;
 	currentStep?: number;
 	chainStepCount?: number;
 	pendingAppends?: number;
@@ -62,6 +68,7 @@ export interface AsyncRunSummary {
 	sessionDir?: string;
 	outputFile?: string;
 	totalTokens?: TokenUsage;
+	totalCost?: CostSummary;
 	sessionFile?: string;
 	nestedChildren?: NestedRunSummary[];
 	nestedWarnings?: string[];
@@ -122,7 +129,7 @@ function deriveAsyncActivityState(asyncDir: string, status: AsyncStatus): { acti
 	};
 }
 
-function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string }, nestedWarnings: string[] = []): AsyncRunSummary {
+function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string }, nestedWarnings: string[] = [], nestedRoute?: NestedRoute): AsyncRunSummary {
 	if (status.sessionId !== undefined && typeof status.sessionId !== "string") {
 		throw new Error(`Invalid async status '${path.join(asyncDir, "status.json")}': sessionId must be a string.`);
 	}
@@ -131,9 +138,11 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	const chainStepCount = status.chainStepCount ?? steps.length;
 	const parallelGroups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
 	let nestedChildren: NestedRunSummary[] = [];
-	if (nestedWarnings.length === 0) {
+	if (nestedWarnings.length === 0 && nestedRoute) {
 		try {
-			nestedChildren = projectNestedRegistryForRoot(status.runId || path.basename(asyncDir))?.children ?? [];
+			// The route is resolved by the caller via buildNestedRouteIndex, so this
+			// avoids a fresh scan of the nested-events directory per run.
+			nestedChildren = projectNestedEvents(nestedRoute)?.children ?? [];
 		} catch (error) {
 			nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
 		}
@@ -161,11 +170,13 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
 			...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
 			...(step.tokens ? { tokens: step.tokens } : {}),
+			...(step.totalCost ? { totalCost: step.totalCost } : {}),
 			...(step.skills ? { skills: step.skills } : {}),
 			...(step.model ? { model: step.model } : {}),
 			...(step.thinking ? { thinking: step.thinking } : {}),
 			...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
 			...(step.error ? { error: step.error } : {}),
+			...(step.timedOut !== undefined ? { timedOut: step.timedOut } : {}),
 			...(step.children?.length ? { children: step.children } : {}),
 		};
 	});
@@ -175,6 +186,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		asyncDir,
 		...(status.sessionId ? { sessionId: status.sessionId } : {}),
 		state: status.state,
+		...(status.error ? { error: status.error } : {}),
 		activityState,
 		lastActivityAt,
 		currentTool: status.currentTool,
@@ -187,6 +199,9 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		startedAt: status.startedAt,
 		lastUpdate: status.lastUpdate,
 		endedAt: status.endedAt,
+		...(status.timeoutMs !== undefined ? { timeoutMs: status.timeoutMs } : {}),
+		...(status.deadlineAt !== undefined ? { deadlineAt: status.deadlineAt } : {}),
+		...(status.timedOut !== undefined ? { timedOut: status.timedOut } : {}),
 		currentStep: status.currentStep,
 		...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
 		...(status.pendingAppends !== undefined ? { pendingAppends: status.pendingAppends } : {}),
@@ -197,6 +212,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		...(status.sessionDir ? { sessionDir: status.sessionDir } : {}),
 		...(status.outputFile ? { outputFile: status.outputFile } : {}),
 		...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
+		...(status.totalCost ? { totalCost: status.totalCost } : {}),
 		...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
 	};
 }
@@ -233,6 +249,16 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 
 	const allowedStates = options.states ? new Set(options.states) : undefined;
 	const runs: AsyncRunSummary[] = [];
+	// Route resolution for every run shares a single index built from the
+	// nested-events directory, so the per-run lookup is O(1) instead of scanning
+	// the directory once per run. The index is built lazily on first use, so
+	// load-time restoration (which only wants queued/running runs) skips it
+	// entirely when no active runs match.
+	let nestedRouteIndex: Map<string, NestedRoute> | undefined;
+	const resolveNestedRoute = (rootRunId: string): NestedRoute | undefined => {
+		if (!nestedRouteIndex) nestedRouteIndex = buildNestedRouteIndex();
+		return nestedRouteIndex.get(rootRunId);
+	};
 	for (const entry of entries) {
 		const asyncDir = path.join(asyncDirRoot, entry);
 		const reconciliation = options.reconcile === false
@@ -240,16 +266,21 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 			: reconcileAsyncRun(asyncDir, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
 		const status = (reconciliation?.status ?? readStatus(asyncDir)) as (AsyncStatus & { cwd?: string }) | null;
 		if (!status) continue;
+		// Filter before the nested-route lookup: the lookup builds an index over
+		// the nested-events directory, so deferring it for filtered-out runs keeps
+		// restoration at load from scanning that directory when no active runs
+		// match.
+		if (allowedStates && !allowedStates.has(status.state)) continue;
+		if (options.sessionId && status.sessionId !== options.sessionId) continue;
 		const nestedWarnings: string[] = [];
+		let nestedRoute: NestedRoute | undefined;
 		try {
-			const nestedRoute = findNestedRouteForRootId(status.runId || path.basename(asyncDir));
+			nestedRoute = resolveNestedRoute(status.runId || path.basename(asyncDir));
 			if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
 		} catch (error) {
 			nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
 		}
-		const summary = statusToSummary(asyncDir, status, nestedWarnings);
-		if (allowedStates && !allowedStates.has(summary.state)) continue;
-		if (options.sessionId && summary.sessionId !== options.sessionId) continue;
+		const summary = statusToSummary(asyncDir, status, nestedWarnings, nestedRoute);
 		runs.push(summary);
 	}
 
@@ -328,6 +359,7 @@ export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active as
 		const attached = new Set(run.steps.flatMap((step) => step.children?.map((child) => child.id) ?? []));
 		const unattached = run.nestedChildren?.filter((child) => !attached.has(child.id)) ?? [];
 		lines.push(...formatNestedRunStatusLines(unattached, { indent: "  ", maxLines: 12 }));
+		if (run.error) lines.push(`  Error: ${run.error}`);
 		for (const warning of run.nestedWarnings ?? []) lines.push(`  Warning: ${warning}`);
 		const outputPath = formatAsyncRunOutputPath(run);
 		if (outputPath) lines.push(`  output: ${shortenPath(outputPath)}`);

package/src/runs/background/chain-root-attachment.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { AcceptanceLedger, AsyncStatus, ModelAttempt } from "../../shared/types.ts";
+import type { AcceptanceLedger, AsyncStatus, CostSummary, ModelAttempt } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 
 export interface ImportedAsyncRoot {
@@ -21,26 +21,32 @@ export interface ImportedAsyncRootResult {
 	model?: string;
 	attemptedModels?: string[];
 	modelAttempts?: ModelAttempt[];
+	totalCost?: CostSummary;
 	structuredOutput?: unknown;
 	structuredOutputPath?: string;
 	structuredOutputSchemaPath?: string;
 	acceptance?: AcceptanceLedger;
+	timedOut?: boolean;
 }
 
 interface AsyncResultFile {
 	state?: string;
 	success?: boolean;
 	summary?: string;
+	error?: string;
+	timedOut?: boolean;
 	results?: Array<{
 		agent?: string;
 		output?: string;
 		error?: string;
 		success?: boolean;
+		timedOut?: boolean;
 		sessionFile?: string;
 		intercomTarget?: string;
 		model?: string;
 		attemptedModels?: string[];
 		modelAttempts?: ModelAttempt[];
+		totalCost?: CostSummary;
 		structuredOutput?: unknown;
 		structuredOutputPath?: string;
 		structuredOutputSchemaPath?: string;
@@ -85,6 +91,7 @@ function resultState(result: AsyncResultFile | undefined, child: NonNullable<Asy
 
 function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus, step: NonNullable<AsyncStatus["steps"]>[number] | undefined): ImportedAsyncRootResult {
 	const agent = step?.agent ?? status.steps?.[root.index]?.agent ?? "subagent";
+	const timedOut = step?.timedOut === true || status.timedOut === true;
 	const message = step?.error ?? status.error ?? `Attached async root ${root.runId} ended without a result file at ${root.resultPath}.`;
 	return {
 		agent,
@@ -92,10 +99,12 @@ function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus,
 		success: false,
 		exitCode: 1,
 		error: message,
+		...(timedOut ? { timedOut: true } : {}),
 		...(step?.sessionFile ?? status.sessionFile ? { sessionFile: step?.sessionFile ?? status.sessionFile } : {}),
 		...(step?.model ? { model: step.model } : {}),
 		...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
 		...(step?.modelAttempts ? { modelAttempts: step.modelAttempts } : {}),
+		...(step?.totalCost ? { totalCost: step.totalCost } : {}),
 		...(step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
 		...(step?.structuredOutputPath ? { structuredOutputPath: step.structuredOutputPath } : {}),
 		...(step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: step.structuredOutputSchemaPath } : {}),
@@ -103,25 +112,45 @@ function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus,
 	};
 }
 
+function outputFromTimeout(root: ImportedAsyncRoot, status: AsyncStatus | null, message: string): ImportedAsyncRootResult {
+	const step = selectedStatusStep(status, root.index);
+	return {
+		agent: step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent",
+		output: message,
+		success: false,
+		exitCode: 1,
+		error: message,
+		timedOut: true,
+		...(step?.sessionFile ?? status?.sessionFile ? { sessionFile: step?.sessionFile ?? status?.sessionFile } : {}),
+		...(step?.model ? { model: step.model } : {}),
+		...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
+		...(step?.modelAttempts ? { modelAttempts: step.modelAttempts } : {}),
+		...(step?.totalCost ? { totalCost: step.totalCost } : {}),
+	};
+}
+
 function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null, result: AsyncResultFile): ImportedAsyncRootResult {
 	const child = result.results?.[root.index];
 	const step = selectedStatusStep(status, root.index);
 	const state = resultState(result, child);
 	const agent = child?.agent ?? step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent";
 	const output = child?.output ?? result.summary ?? "";
-	const success = state === "complete";
-	const error = child?.error ?? (success ? undefined : result.summary ?? status?.error ?? `Attached async root ${root.runId} did not complete successfully.`);
+	const timedOut = child?.timedOut === true || step?.timedOut === true || result.timedOut === true || status?.timedOut === true;
+	const success = state === "complete" && !timedOut;
+	const error = child?.error ?? (success ? undefined : result.error ?? result.summary ?? status?.error ?? `Attached async root ${root.runId} did not complete successfully.`);
 	return {
 		agent,
 		output: success ? output : (output || error || ""),
 		success,
 		exitCode: success ? 0 : 1,
 		...(error ? { error } : {}),
+		...(timedOut ? { timedOut: true } : {}),
 		...(child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile ? { sessionFile: child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile } : {}),
 		...(child?.intercomTarget ? { intercomTarget: child.intercomTarget } : {}),
 		...(child?.model ?? step?.model ? { model: child?.model ?? step?.model } : {}),
 		...(child?.attemptedModels ?? step?.attemptedModels ? { attemptedModels: child?.attemptedModels ?? step?.attemptedModels } : {}),
 		...(child?.modelAttempts ?? step?.modelAttempts ? { modelAttempts: child?.modelAttempts ?? step?.modelAttempts } : {}),
+		...(child?.totalCost ?? step?.totalCost ? { totalCost: child?.totalCost ?? step?.totalCost } : {}),
 		...(child?.structuredOutput !== undefined ? { structuredOutput: child.structuredOutput } : step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
 		...(child?.structuredOutputPath ?? step?.structuredOutputPath ? { structuredOutputPath: child?.structuredOutputPath ?? step?.structuredOutputPath } : {}),
 		...(child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath } : {}),
@@ -131,7 +160,7 @@ function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null
 
 export async function waitForImportedAsyncRoot(
 	root: ImportedAsyncRoot,
-	options: { pollIntervalMs?: number; terminalResultGraceMs?: number; now?: () => number } = {},
+	options: { pollIntervalMs?: number; terminalResultGraceMs?: number; now?: () => number; shouldAbort?: () => boolean; timeoutMessage?: string } = {},
 ): Promise<ImportedAsyncRootResult> {
 	const pollIntervalMs = options.pollIntervalMs ?? 500;
 	const terminalResultGraceMs = options.terminalResultGraceMs ?? 1_000;
@@ -139,6 +168,7 @@ export async function waitForImportedAsyncRoot(
 	let terminalSince: number | undefined;
 	for (;;) {
 		const status = readStatus(root.asyncDir);
+		if (options.shouldAbort?.()) return outputFromTimeout(root, status, options.timeoutMessage ?? "Subagent timed out.");
 		const result = readResultFile(root.resultPath);
 		if (result) return buildImportedResult(root, status, result);
 		if (isTerminalStatus(status, root.index)) {

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

@@ -0,0 +1,227 @@
+/**
+ * Cross-OS control channel for async subagent runs.
+ *
+ * Background runs are detached OS processes. The original control path delivered
+ * an interrupt with `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
+ * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,
+ * which left async runs uninterruptible (no stop, no live steer) on Windows.
+ *
+ * This module adds a portable, file-based control inbox inside the run directory.
+ * The parent drops an interrupt request file; the runner watches the inbox and
+ * routes the request into its existing graceful `interruptRunner()` (pause +
+ * resumable), identically on every platform. The OS signal is kept only as an
+ * opportunistic fast-path; its failure is non-fatal because the file inbox is
+ * authoritative.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { POLL_INTERVAL_MS } from "../../shared/types.ts";
+
+/**
+ * Opportunistic fast-path interrupt signal. On Unix `SIGUSR2` is trapped by the
+ * runner; on Windows `process.kill(pid, "SIGBREAK")` is not deliverable
+ * cross-process and throws `ENOSYS`, so the file inbox below is the real channel.
+ */
+export const INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
+
+export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch">;
+export type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };
+type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
+
+export interface InterruptRequest {
+	type: "interrupt";
+	ts?: number;
+	source?: string;
+	reason?: string;
+}
+
+export interface TimeoutRequest {
+	type: "timeout";
+	ts?: number;
+	source?: string;
+	reason?: string;
+}
+
+/** Control inbox directory inside an async run dir. */
+export function controlInboxDir(asyncDir: string): string {
+	return path.join(asyncDir, "control");
+}
+
+/** Path of the portable interrupt request file. */
+export function interruptRequestPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), "interrupt.json");
+}
+
+/** Path of the portable timeout request file. */
+export function timeoutRequestPath(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), "timeout.json");
+}
+
+/**
+ * Parent side: drop a portable interrupt request the runner's inbox watcher will
+ * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.
+ */
+export function requestAsyncInterrupt(
+	asyncDir: string,
+	payload: Omit<InterruptRequest, "type"> = {},
+	deps: { now?: () => number } = {},
+): string {
+	const requestPath = interruptRequestPath(asyncDir);
+	const request: InterruptRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: "interrupt" };
+	writeAtomicJson(requestPath, request);
+	return requestPath;
+}
+
+export function requestAsyncTimeout(
+	asyncDir: string,
+	payload: Omit<TimeoutRequest, "type"> = {},
+	deps: { now?: () => number } = {},
+): string {
+	const requestPath = timeoutRequestPath(asyncDir);
+	const request: TimeoutRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: "timeout" };
+	writeAtomicJson(requestPath, request);
+	return requestPath;
+}
+
+/**
+ * Runner side: consume a pending interrupt request. Idempotent — removes the file
+ * so each distinct request fires exactly once. Returns whether one was pending.
+ */
+export function consumeInterruptRequest(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync"> = fs,
+): boolean {
+	const requestPath = interruptRequestPath(asyncDir);
+	if (!fsImpl.existsSync(requestPath)) return false;
+	try {
+		fsImpl.rmSync(requestPath, { force: true, recursive: true });
+	} catch {
+		// Already removed by a concurrent check — still counts as consumed.
+	}
+	return true;
+}
+
+export function consumeTimeoutRequest(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync"> = fs,
+): boolean {
+	const requestPath = timeoutRequestPath(asyncDir);
+	if (!fsImpl.existsSync(requestPath)) return false;
+	try {
+		fsImpl.rmSync(requestPath, { force: true, recursive: true });
+	} catch {
+		// Already removed by a concurrent check — still counts as consumed.
+	}
+	return true;
+}
+
+/**
+ * Parent side: portable interrupt = authoritative file request + best-effort OS
+ * signal. The signal is only a latency optimization on Unix; ENOSYS on Windows
+ * is swallowed because the file inbox is authoritative there. Other signal
+ * failures are surfaced because they usually mean the runner is not alive to
+ * consume the request.
+ */
+export function deliverInterruptRequest(input: {
+	asyncDir: string;
+	pid?: number;
+	kill?: KillFn;
+	signal?: NodeJS.Signals;
+	now?: () => number;
+	source?: string;
+}): void {
+	const requestPath = requestAsyncInterrupt(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
+	if (typeof input.pid === "number" && input.pid > 0) {
+		try {
+			(input.kill ?? process.kill)(input.pid, input.signal ?? INTERRUPT_SIGNAL);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOSYS") {
+				// File inbox is authoritative when custom cross-process signals are unavailable.
+				return;
+			}
+			try {
+				fs.rmSync(requestPath, { force: true });
+			} catch {
+				// Best effort cleanup; the caller still gets the signal failure.
+			}
+			throw error;
+		}
+	}
+}
+
+export function deliverTimeoutRequest(input: {
+	asyncDir: string;
+	pid?: number;
+	kill?: KillFn;
+	signal?: NodeJS.Signals;
+	now?: () => number;
+	source?: string;
+}): void {
+	requestAsyncTimeout(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
+}
+
+/**
+ * Runner side: watch the control inbox and route interrupt requests into
+ * `onInterrupt`. Uses `fs.watch` when available plus an interval poll as a
+ * portable safety net (covers filesystems/platforms where `fs.watch` is
+ * unreliable). Fires once per distinct request. Returns a disposer.
+ */
+export function watchAsyncControlInbox(
+	asyncDir: string,
+	opts: {
+		onInterrupt: () => void;
+		onTimeout?: () => void;
+		pollIntervalMs?: number;
+		fs?: ControlChannelFs;
+		timers?: ControlChannelTimers;
+	},
+): () => void {
+	const fsImpl = opts.fs ?? fs;
+	const timers = opts.timers ?? { setInterval, clearInterval };
+	const dir = controlInboxDir(asyncDir);
+	try {
+		fsImpl.mkdirSync(dir, { recursive: true });
+	} catch {
+		// Best effort — the poll/watch below tolerates a missing dir.
+	}
+
+	let disposed = false;
+	const check = (): void => {
+		if (disposed) return;
+		try {
+			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
+			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
+		} catch {
+			// Never let inbox errors crash the runner.
+		}
+	};
+
+	// Handle a request that may have arrived before the watcher started.
+	check();
+
+	let watcher: fs.FSWatcher | undefined;
+	try {
+		watcher = fsImpl.watch(dir, () => check());
+		watcher.on?.("error", () => {
+			// fs.watch can emit on transient FS errors; the interval poll keeps us live.
+		});
+	} catch {
+		watcher = undefined;
+	}
+
+	const interval = timers.setInterval(check, opts.pollIntervalMs ?? POLL_INTERVAL_MS);
+	interval.unref?.();
+
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		try {
+			watcher?.close();
+		} catch {
+			// ignore
+		}
+		timers.clearInterval(interval);
+	};
+}

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

@@ -202,6 +202,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			const lines = [
 				`Run: ${status.runId}`,
 				`State: ${status.state}`,
+				status.error ? `Error: ${status.error}` : undefined,
 				statusActivityText ? `Activity: ${statusActivityText}` : undefined,
 				`Mode: ${status.mode}`,
 				`Progress: ${progressLabel}`,

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

@@ -41,6 +41,31 @@ function getErrorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+function readRunnerStartupDiagnostics(asyncDir: string): string | undefined {
+	const stderrPath = path.join(asyncDir, "runner.stderr.log");
+	const maxBytes = 64 * 1024;
+	let content: string;
+	try {
+		const stat = fs.statSync(stderrPath);
+		if (stat.size <= 0) return undefined;
+		const fd = fs.openSync(stderrPath, "r");
+		try {
+			const bytesToRead = Math.min(stat.size, maxBytes);
+			const start = Math.max(0, stat.size - bytesToRead);
+			const buffer = Buffer.alloc(bytesToRead);
+			fs.readSync(fd, buffer, 0, bytesToRead, start);
+			content = buffer.toString("utf-8").trim();
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch {
+		return undefined;
+	}
+	if (!content) return undefined;
+	const lines = content.split(/\r?\n/).slice(-30).join("\n");
+	return lines.length > 4000 ? `${lines.slice(-4000)}\n[stderr tail truncated]` : lines;
+}
+
 function isNotFoundError(error: unknown): boolean {
 	return typeof error === "object"
 		&& error !== null
@@ -172,7 +197,9 @@ function buildStartedStatus(asyncDir: string, startedRun: StartedRunMetadata, no
 function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, reason?: string): { status: AsyncStatus; result: object; message: string } {
 	const runId = status.runId || path.basename(asyncDir);
 	const pid = typeof status.pid === "number" ? status.pid : "unknown";
-	const message = reason ?? `Async runner process ${pid} exited or disappeared before writing a result. Marked run failed by stale-run reconciliation.`;
+	const baseMessage = reason ?? `Async runner process ${pid} exited or disappeared before writing a result. Marked run failed by stale-run reconciliation.`;
+	const diagnostics = readRunnerStartupDiagnostics(asyncDir);
+	const message = diagnostics ? `${baseMessage}\n\nRunner stderr tail:\n${diagnostics}` : baseMessage;
 	const steps = status.steps?.length ? status.steps : [{ agent: "subagent", status: "running" as const }];
 	const repairedSteps = steps.map((step) => step.status === "running" || step.status === "pending"
 		? {