pi-subagents 0.27.0 → 0.28.0

package/src/runs/foreground/subagent-executor.ts

@@ -121,6 +121,8 @@ export interface SubagentParamsLike {
 	chain?: ChainStep[];
 	tasks?: TaskParam[];
 	concurrency?: number;
+	timeoutMs?: number;
+	maxRuntimeMs?: number;
 	worktree?: boolean;
 	context?: "fresh" | "fork";
 	async?: boolean;
@@ -169,6 +171,7 @@ interface ExecutionContextData {
 	artifactsDir: string;
 	backgroundRequestedWhileClarifying: boolean;
 	effectiveAsync: boolean;
+	foregroundTimeoutMs?: number;
 	controlConfig: ResolvedControlConfig;
 	intercomBridge: IntercomBridgeState;
 	nestedRoute?: NestedRouteInfo;
@@ -250,7 +253,7 @@ function rememberForegroundRun(state: SubagentState, input: { runId: string; mod
 		children: input.results.map((result, index) => ({
 			agent: result.agent,
 			index,
-			status: resolveSubagentResultStatus({ exitCode: result.exitCode, interrupted: result.interrupted, detached: result.detached }),
+			status: resolveSubagentResultStatus({ exitCode: result.exitCode, interrupted: result.interrupted, detached: result.detached, timedOut: result.timedOut }),
 			...(result.sessionFile ? { sessionFile: result.sessionFile } : {}),
 		})),
 	});
@@ -716,6 +719,7 @@ async function emitForegroundResultIntercom(input: {
 			exitCode: result.exitCode,
 			interrupted: result.interrupted,
 			detached: result.detached,
+			timedOut: result.timedOut,
 		}),
 		summary: resultSummaryForIntercom(result),
 		index,
@@ -765,6 +769,21 @@ function validationErrorResult(mode: Details["mode"], text: string): AgentToolRe
 	return { content: [{ type: "text", text }], isError: true, details: { mode, results: [] } };
 }
 
+function resolveForegroundTimeoutMs(params: SubagentParamsLike): { timeoutMs?: number; error?: string } {
+	const rawTimeout = (params as { timeoutMs?: unknown }).timeoutMs;
+	const rawMaxRuntime = (params as { maxRuntimeMs?: unknown }).maxRuntimeMs;
+	for (const [name, value] of [["timeoutMs", rawTimeout], ["maxRuntimeMs", rawMaxRuntime]] as const) {
+		if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 1)) {
+			return { error: `${name} must be a positive integer.` };
+		}
+	}
+	if (rawTimeout !== undefined && rawMaxRuntime !== undefined && rawTimeout !== rawMaxRuntime) {
+		return { error: "timeoutMs and maxRuntimeMs are aliases; provide only one or use identical values." };
+	}
+	const timeoutMs = rawTimeout ?? rawMaxRuntime;
+	return timeoutMs === undefined ? {} : { timeoutMs };
+}
+
 function validateAcceptanceForExecution(params: SubagentParamsLike): AgentToolResult<Details> | null {
 	const topLevelErrors = validateAcceptanceInput(params.acceptance);
 	if (topLevelErrors.length > 0) return validationErrorResult("single", topLevelErrors.join(" "));
@@ -815,6 +834,9 @@ function validateExecutionInput(
 		};
 	}
 
+	const timeoutResolution = resolveForegroundTimeoutMs(params);
+	if (timeoutResolution.error) return validationErrorResult(getRequestedModeLabel(params), timeoutResolution.error);
+
 	if (hasSingle && params.agent && !agents.find((agent) => agent.name === params.agent)) {
 		return {
 			content: [{ type: "text", text: `Unknown agent: ${params.agent}` }],
@@ -1288,6 +1310,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		onUpdate,
 		onControlEvent,
 		controlConfig,
+		...(data.foregroundTimeoutMs !== undefined ? { timeoutMs: data.foregroundTimeoutMs } : {}),
 		childIntercomTarget: childIntercomTarget ? (agent, index) => childIntercomTarget(runId, agent, index) : undefined,
 		orchestratorIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
 		foregroundControl,
@@ -1344,7 +1367,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 	const chainDetails = chainResult.details ? compactForegroundDetails({ ...chainResult.details, runId }) : undefined;
 	if (foregroundControl) updateForegroundNestedProjection(foregroundControl);
 	if (chainDetails) rememberForegroundRun(deps.state, { runId, mode: "chain", cwd: effectiveCwd, results: chainDetails.results });
-	const intercomReceipt = chainDetails && !chainDetails.results.some((result) => result.interrupted || result.detached)
+	const intercomReceipt = chainDetails && !chainDetails.results.some((result) => result.interrupted || result.detached || result.timedOut)
 		? await maybeBuildForegroundIntercomReceipt({
 			pi: deps.pi,
 			intercomBridge: data.intercomBridge,
@@ -1379,6 +1402,8 @@ interface ForegroundParallelRunInput {
 	artifactConfig: ArtifactConfig;
 	artifactsDir: string;
 	maxOutput?: MaxOutputConfig;
+	timeoutMs?: number;
+	timeoutAt?: number;
 	paramsCwd: string;
 	maxSubagentDepths: number[];
 	availableModels: ModelInfo[];
@@ -1531,6 +1556,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			cwd: taskCwd,
 			signal: input.signal,
 			interruptSignal: interruptController.signal,
+			...(input.timeoutMs !== undefined && input.timeoutAt !== undefined ? { timeoutMs: input.timeoutMs, timeoutAt: input.timeoutAt } : {}),
 			allowIntercomDetach: agentConfig?.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
 			intercomEvents: input.intercomEvents,
 			runId: input.runId,
@@ -1544,6 +1570,8 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			outputPath,
 			outputMode: behavior?.outputMode,
 			maxSubagentDepth: input.maxSubagentDepths[index],
+			maxExecutionTimeMs: agentConfig?.maxExecutionTimeMs,
+			maxTokens: agentConfig?.maxTokens,
 			controlConfig: input.controlConfig,
 			onControlEvent: input.onControlEvent,
 			intercomSessionName: input.childIntercomTarget?.(task.agent, index),
@@ -1811,6 +1839,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			}
 		}
 
+		const timeoutAt = data.foregroundTimeoutMs !== undefined ? Date.now() + data.foregroundTimeoutMs : undefined;
 		const results = await runForegroundParallelTasks({
 			tasks,
 			taskTexts,
@@ -1825,6 +1854,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			artifactConfig,
 			artifactsDir,
 			maxOutput: params.maxOutput,
+			...(data.foregroundTimeoutMs !== undefined && timeoutAt !== undefined ? { timeoutMs: data.foregroundTimeoutMs, timeoutAt } : {}),
 			paramsCwd: effectiveCwd,
 			availableModels,
 			modelOverrides,
@@ -1852,6 +1882,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 		}
 
+		const timedOut = results.find((result) => result.timedOut);
 		const interrupted = results.find((result) => result.interrupted);
 		const details = compactForegroundDetails({
 			mode: "parallel",
@@ -1861,6 +1892,13 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			artifacts: allArtifactPaths.length ? { dir: artifactsDir, files: allArtifactPaths } : undefined,
 		});
 		rememberForegroundRun(deps.state, { runId, mode: "parallel", cwd: effectiveCwd, results: details.results });
+		if (timedOut) {
+			return {
+				content: [{ type: "text", text: `Parallel run timed out (${timedOut.agent}): ${timedOut.error ?? "timeout expired"}` }],
+				details,
+				isError: true,
+			};
+		}
 		if (interrupted) {
 			return {
 				content: [{ type: "text", text: `Parallel run paused after interrupt (${interrupted.agent}). Waiting for explicit next action.` }],
@@ -2091,10 +2129,12 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		}
 		: undefined;
 
+	const timeoutAt = data.foregroundTimeoutMs !== undefined ? Date.now() + data.foregroundTimeoutMs : undefined;
 	const r = await runSync(ctx.cwd, agents, params.agent!, task, {
 		cwd: effectiveCwd,
 		signal,
 		interruptSignal: interruptController.signal,
+		...(data.foregroundTimeoutMs !== undefined && timeoutAt !== undefined ? { timeoutMs: data.foregroundTimeoutMs, timeoutAt } : {}),
 		allowIntercomDetach: agentConfig.systemPrompt?.includes(INTERCOM_BRIDGE_MARKER) === true,
 		intercomEvents: deps.pi.events,
 		runId,
@@ -2107,6 +2147,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		outputPath,
 		outputMode: effectiveOutputMode,
 		maxSubagentDepth,
+		maxExecutionTimeMs: agentConfig.maxExecutionTimeMs,
+		maxTokens: agentConfig.maxTokens,
 		onUpdate: forwardSingleUpdate,
 		controlConfig,
 		onControlEvent,
@@ -2159,7 +2201,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	});
 	rememberForegroundRun(deps.state, { runId, mode: "single", cwd: effectiveCwd, results: details.results });
 
-	if (!r.detached && !r.interrupted) {
+	if (!r.detached && !r.interrupted && !r.timedOut) {
 		if (foregroundControl) updateForegroundNestedProjection(foregroundControl);
 		const intercomReceipt = await maybeBuildForegroundIntercomReceipt({
 			pi: deps.pi,
@@ -2185,6 +2227,14 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		};
 	}
 
+	if (r.timedOut) {
+		return {
+			content: [{ type: "text", text: `Run timed out (${params.agent}): ${r.error ?? "timeout expired"}` }],
+			details,
+			isError: true,
+		};
+	}
+
 	if (r.interrupted) {
 		return {
 			content: [{ type: "text", text: `Run paused after interrupt (${params.agent}). Waiting for explicit next action.` }],
@@ -2412,6 +2462,11 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const requestedAsync = effectiveParams.async ?? deps.asyncByDefault;
 		const backgroundRequestedWhileClarifying = (hasChain || hasTasks) && requestedAsync && effectiveParams.clarify === true;
 		const effectiveAsync = requestedAsync && effectiveParams.clarify !== true;
+		const foregroundTimeout = resolveForegroundTimeoutMs(effectiveParams);
+		if (foregroundTimeout.error) return buildRequestedModeError(effectiveParams, foregroundTimeout.error);
+		if (effectiveAsync && foregroundTimeout.timeoutMs !== undefined) {
+			return buildRequestedModeError(effectiveParams, "timeoutMs/maxRuntimeMs only applies to foreground subagent runs. Omit async:true or use action:'interrupt' for background runs.");
+		}
 		const controlConfig = resolveControlConfig(deps.config.control, effectiveParams.control);
 
 		const artifactConfig: ArtifactConfig = {
@@ -2463,6 +2518,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			artifactsDir,
 			backgroundRequestedWhileClarifying,
 			effectiveAsync,
+			...(foregroundTimeout.timeoutMs !== undefined ? { foregroundTimeoutMs: foregroundTimeout.timeoutMs } : {}),
 			controlConfig,
 			intercomBridge,
 			nestedRoute,

package/src/runs/shared/acceptance-contract.ts

@@ -34,6 +34,22 @@ const ACCEPTANCE_KEYS = new Set([
 
 const REMOVED_ACCEPTANCE_KEYS = new Set(["level", "finalization", "reason"]);
 
+const EVIDENCE_REPORT_FIELDS: Record<AcceptanceEvidenceKind, string> = {
+	"changed-files": "changedFiles: array of changed file paths",
+	"tests-added": "testsAddedOrUpdated: array of test files, suites, or cases added/updated",
+	"commands-run": "commandsRun: array of commands with result passed/failed/not-run and a short summary",
+	"validation-output": "validationOutput: array of relevant validation output summaries",
+	"residual-risks": "residualRisks: array of remaining risks or blockers; use [] when none remain",
+	"no-staged-files": "noStagedFiles: boolean",
+	"diff-summary": "diffSummary: non-empty string summarizing changed behavior and important files",
+	"review-findings": "reviewFindings: array of reviewer findings; use [] when no findings remain",
+	"manual-notes": "manualNotes: string for manual notes or external evidence",
+};
+
+export function formatEvidenceReportFieldMapping(evidence: AcceptanceEvidenceKind[]): string[] {
+	return evidence.map((kind) => `- ${kind} -> ${EVIDENCE_REPORT_FIELDS[kind]}`);
+}
+
 function hasArrayItems(value: unknown): boolean {
 	return Array.isArray(value) && value.length > 0;
 }
@@ -260,6 +276,14 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig): st
 		"",
 		`Required evidence: ${acceptance.evidence.join(", ") || "none explicitly requested"}`,
 	];
+	if (acceptance.evidence.length > 0) {
+		lines.push(
+			"",
+			"Structured evidence must be present in the `acceptance-report` JSON fields. Markdown sections in your visible answer do not satisfy required evidence by themselves. If you already described evidence in prose, copy or summarize it into the matching JSON field.",
+			"Evidence field mapping:",
+			...formatEvidenceReportFieldMapping(acceptance.evidence),
+		);
+	}
 	if (acceptance.verify.length > 0) {
 		lines.push("", "Runtime verification commands configured by parent:");
 		for (const command of acceptance.verify) lines.push(`- ${command.id}: ${command.command}`);
@@ -283,6 +307,9 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig): st
 			validationOutput: [],
 			residualRisks: [],
 			noStagedFiles: true,
+			diffSummary: "concise summary of changed behavior and important files",
+			reviewFindings: [],
+			manualNotes: "manual notes or external evidence, if any",
 			notes: "anything else the parent should know",
 		}, null, 2),
 		"```",

package/src/runs/shared/acceptance-finalization.ts

@@ -4,6 +4,7 @@ import type {
 	ResolvedAcceptanceConfig,
 } from "../../shared/types.ts";
 import { acceptanceFailureMessage } from "./acceptance-evaluation.ts";
+import { formatEvidenceReportFieldMapping } from "./acceptance-contract.ts";
 import { stripAcceptanceReport } from "./acceptance-reports.ts";
 
 const INITIAL_OUTPUT_LIMIT = 8_000;
@@ -42,6 +43,14 @@ export function formatAcceptanceFinalizationPrompt(input: {
 		"",
 		`Required evidence: ${input.acceptance.evidence.join(", ") || "none explicitly requested"}`,
 	];
+	if (input.acceptance.evidence.length > 0) {
+		lines.push(
+			"",
+			"Structured evidence must be present in the final `acceptance-report` JSON fields. Markdown sections in the visible answer do not satisfy required evidence by themselves. If the previous visible output already included the evidence, copy or summarize it into the matching JSON field.",
+			"Evidence field mapping:",
+			...formatEvidenceReportFieldMapping(input.acceptance.evidence),
+		);
+	}
 	if (input.acceptance.verify.length > 0) {
 		lines.push("", "Runtime verification commands that must pass:", ...input.acceptance.verify.map((command) => `- ${command.id}: ${command.command}`));
 	}
@@ -74,6 +83,9 @@ export function formatAcceptanceFinalizationPrompt(input: {
 			validationOutput: [],
 			residualRisks: [],
 			noStagedFiles: true,
+			diffSummary: "concise summary of changed behavior and important files",
+			reviewFindings: [],
+			manualNotes: "manual notes or external evidence, if any",
 			notes: "final self-review summary",
 		}, null, 2),
 		"```",

package/src/runs/shared/parallel-utils.ts

@@ -25,6 +25,8 @@ export interface RunnerSubagentStep {
 	outputMode?: "inline" | "file-only";
 	sessionFile?: string;
 	maxSubagentDepth?: number;
+	maxExecutionTimeMs?: number;
+	maxTokens?: number;
 	structuredOutput?: {
 		schema: JsonSchemaObject;
 		schemaPath: string;

package/src/runs/shared/workflow-graph.ts

@@ -5,7 +5,7 @@ export interface WorkflowGraphBuildInput {
 	runId: string;
 	mode?: SubagentRunMode;
 	steps: ChainStep[];
-	results?: Array<Pick<SingleResult, "exitCode" | "detached" | "interrupted" | "error" | "acceptance">>;
+	results?: Array<Pick<SingleResult, "exitCode" | "detached" | "interrupted" | "timedOut" | "error" | "acceptance">>;
 	currentFlatIndex?: number;
 	currentStepIndex?: number;
 	stepStatuses?: Array<{ status?: string; error?: string }>;
@@ -26,6 +26,8 @@ function normalizeStatus(status: string | undefined): WorkflowNodeStatus | undef
 			return "paused";
 		case "detached":
 			return "detached";
+		case "timed-out":
+			return "timed-out";
 		case "pending":
 			return "pending";
 		default:
@@ -33,9 +35,10 @@ function normalizeStatus(status: string | undefined): WorkflowNodeStatus | undef
 	}
 }
 
-function resultStatus(result: Pick<SingleResult, "exitCode" | "detached" | "interrupted"> | undefined): WorkflowNodeStatus | undefined {
+function resultStatus(result: Pick<SingleResult, "exitCode" | "detached" | "interrupted" | "timedOut"> | undefined): WorkflowNodeStatus | undefined {
 	if (!result) return undefined;
 	if (result.detached) return "detached";
+	if (result.timedOut) return "timed-out";
 	if (result.interrupted) return "paused";
 	return result.exitCode === 0 ? "completed" : "failed";
 }
@@ -63,6 +66,7 @@ function seqLabel(step: SequentialStep, stepIndex: number): string {
 function summarizeParallelStatuses(statuses: WorkflowNodeStatus[]): WorkflowNodeStatus {
 	if (statuses.some((status) => status === "running")) return "running";
 	if (statuses.some((status) => status === "failed")) return "failed";
+	if (statuses.some((status) => status === "timed-out")) return "timed-out";
 	if (statuses.some((status) => status === "paused")) return "paused";
 	if (statuses.some((status) => status === "detached")) return "detached";
 	if (statuses.length > 0 && statuses.every((status) => status === "completed")) return "completed";

package/src/shared/types.ts

@@ -30,7 +30,7 @@ export interface ChainOutputMapEntry {
 
 export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
 
-export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "detached";
+export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "detached" | "timed-out";
 
 export interface WorkflowGraphNode {
 	id: string;
@@ -142,7 +142,7 @@ export interface ControlEvent {
 	recentFailureSummary?: string;
 }
 
-export type SubagentResultStatus = "completed" | "failed" | "paused" | "detached";
+export type SubagentResultStatus = "completed" | "failed" | "paused" | "detached" | "timed-out";
 export type SubagentRunMode = "single" | "parallel" | "chain";
 
 export type PublicNestedStepSummary = Pick<
@@ -408,6 +408,13 @@ export interface AcceptanceLedger {
 	};
 }
 
+export interface ResourceLimitExceeded {
+	kind: "maxExecutionTimeMs" | "maxTokens";
+	limit: number;
+	observed?: number;
+	message: string;
+}
+
 export interface SingleResult {
 	agent: string;
 	task: string;
@@ -415,6 +422,8 @@ export interface SingleResult {
 	detached?: boolean;
 	detachedReason?: string;
 	interrupted?: boolean;
+	timedOut?: boolean;
+	resourceLimitExceeded?: ResourceLimitExceeded;
 	messages?: Message[];
 	usage: Usage;
 	model?: string;
@@ -639,6 +648,7 @@ export interface AsyncStatus {
 		structuredOutputPath?: string;
 		structuredOutputSchemaPath?: string;
 		acceptance?: AcceptanceLedger;
+		resourceLimitExceeded?: ResourceLimitExceeded;
 	}>;
 	sessionDir?: string;
 	outputFile?: string;
@@ -780,6 +790,8 @@ export interface RunSyncOptions {
 	cwd?: string;
 	signal?: AbortSignal;
 	interruptSignal?: AbortSignal;
+	timeoutMs?: number;
+	timeoutAt?: number;
 	allowIntercomDetach?: boolean;
 	intercomEvents?: IntercomEventBus;
 	onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
@@ -798,6 +810,8 @@ export interface RunSyncOptions {
 	outputPath?: string;
 	outputMode?: OutputMode;
 	maxSubagentDepth?: number;
+	maxExecutionTimeMs?: number;
+	maxTokens?: number;
 	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;

package/src/shared/utils.ts

@@ -204,6 +204,13 @@ export function getSingleResultOutput(result: Pick<SingleResult, "finalOutput" |
 	return result.finalOutput ?? getFinalOutput(result.messages ?? []);
 }
 
+export function formatResourceLimitExceeded(input: { agent: string; kind: "maxExecutionTimeMs" | "maxTokens"; limit: number; observed?: number }): string {
+	if (input.kind === "maxExecutionTimeMs") {
+		return `Resource limit exceeded for ${input.agent}: maxExecutionTimeMs ${input.limit}ms.`;
+	}
+	return `Resource limit exceeded for ${input.agent}: maxTokens ${input.limit}${input.observed !== undefined ? ` (observed ${input.observed})` : ""}.`;
+}
+
 /**
  * Extract display items (text and tool calls) from messages
  */

package/src/tui/render.ts

@@ -233,6 +233,7 @@ function formatAcceptanceStatus(result: Details["results"][number]): string | un
 
 function resultStatusLine(result: Details["results"][number], output: string): string {
 	if (result.detached) return result.detachedReason ? `Detached: ${result.detachedReason}` : "Detached";
+	if (result.timedOut) return `Timed out${result.error ? `: ${result.error}` : ""}`;
 	if (result.interrupted) return "Paused";
 	if (result.exitCode !== 0) return `Error: ${result.error ?? (firstOutputLine(output) || `exit ${result.exitCode}`)}`;
 	const acceptance = formatAcceptanceStatus(result);
@@ -244,6 +245,7 @@ function resultStatusLine(result: Details["results"][number], output: string): s
 function resultGlyph(result: Details["results"][number], output: string, theme: Theme, running = result.progress?.status === "running", seed = progressRunningSeed(result.progress ?? result.progressSummary)): string {
 	if (running) return theme.fg("accent", runningGlyph(seed));
 	if (result.detached) return theme.fg("warning", "■");
+	if (result.timedOut) return theme.fg("error", "✗");
 	if (result.interrupted) return theme.fg("warning", "■");
 	if (result.exitCode !== 0) return theme.fg("error", "✗");
 	if (hasEmptyTextOutputWithoutOutputTarget(result.task, output)) return theme.fg("warning", "✓");
@@ -363,18 +365,19 @@ function widgetStatusGlyph(job: AsyncJobState, theme: Theme): string {
 	return theme.fg("error", "✗");
 }
 
-function widgetStepGlyph(status: AsyncJobStep["status"], theme: Theme, seed?: number): string {
+function widgetStepGlyph(status: AsyncJobStep["status"] | WorkflowNodeStatus, theme: Theme, seed?: number): string {
 	if (status === "running") return theme.fg("accent", runningGlyph(seed));
 	if (status === "complete" || status === "completed") return theme.fg("success", "✓");
-	if (status === "failed") return theme.fg("error", "✗");
+	if (status === "failed" || status === "timed-out") return theme.fg("error", "✗");
 	if (status === "paused") return theme.fg("warning", "■");
 	return theme.fg("muted", "◦");
 }
 
-function widgetStepStatus(status: AsyncJobStep["status"], theme: Theme): string {
+function widgetStepStatus(status: AsyncJobStep["status"] | WorkflowNodeStatus, theme: Theme): string {
 	if (status === "running") return theme.fg("accent", "running");
 	if (status === "complete" || status === "completed") return theme.fg("success", "complete");
 	if (status === "failed") return theme.fg("error", "failed");
+	if (status === "timed-out") return theme.fg("error", "timed out");
 	if (status === "paused") return theme.fg("warning", "paused");
 	return theme.fg("dim", status);
 }
@@ -511,7 +514,7 @@ function isDoneResult(result: Details["results"][number]): boolean {
 	const status = result.progress?.status;
 	if (status === "completed") return true;
 	if (status === "running" || status === "pending") return false;
-	if (result.interrupted || result.detached) return false;
+	if (result.interrupted || result.detached || result.timedOut) return false;
 	return result.exitCode === 0;
 }
 
@@ -583,7 +586,7 @@ function buildMultiProgressLabel(details: Pick<Details, "mode" | "results" | "pr
 
 	if (details.mode === "parallel") {
 		const totalCount = details.totalSteps ?? details.results.length;
-		const statuses = new Array(totalCount).fill("pending") as Array<"pending" | "running" | "completed" | "failed" | "detached">;
+		const statuses = new Array(totalCount).fill("pending") as WorkflowNodeStatus[];
 		for (const progress of details.progress ?? []) {
 			if (progress.index >= 0 && progress.index < totalCount) statuses[progress.index] = progress.status;
 		}
@@ -594,11 +597,13 @@ function buildMultiProgressLabel(details: Pick<Details, "mode" | "results" | "pr
 			const index = result.progress?.index ?? progressFromArray?.index ?? i;
 			if (index < 0 || index >= totalCount) continue;
 			const status = result.progress?.status
-				?? (result.interrupted || result.detached
-					? "detached"
-					: result.exitCode === 0
-						? "completed"
-						: "failed");
+				?? (result.timedOut
+					? "timed-out"
+					: result.interrupted || result.detached
+						? "detached"
+						: result.exitCode === 0
+							? "completed"
+							: "failed");
 			statuses[index] = status;
 		}
 		const running = statuses.filter((status) => status === "running").length;
@@ -1060,7 +1065,7 @@ function renderMultiCompact(d: Details, theme: Theme): Component {
 		|| d.results.some((r) => r.progress?.status === "running")
 		|| workflowGraphHasStatus(d, ["running"]);
 	const failed = d.results.some((r) => r.exitCode !== 0 && r.progress?.status !== "running")
-		|| workflowGraphHasStatus(d, ["failed"]);
+		|| workflowGraphHasStatus(d, ["failed", "timed-out"]);
 	const paused = d.results.some((r) => (r.interrupted || r.detached) && r.progress?.status !== "running")
 		|| workflowGraphHasStatus(d, ["paused", "detached"]);
 	let totalSummary = d.progressSummary;
@@ -1136,7 +1141,7 @@ function renderMultiCompact(d: Details, theme: Theme): Component {
 			const activity = compactCurrentActivity(rProg);
 			c.addChild(new Text(truncLine(theme.fg("dim", `    ⎿  ${activity}`), width), 0, 0));
 			c.addChild(new Text(truncLine(theme.fg("accent", "    Press Ctrl+O for live detail"), width), 0, 0));
-		} else if (!rPending && (r.exitCode !== 0 || r.interrupted || r.detached || hasEmptyTextOutputWithoutOutputTarget(r.task, output))) {
+		} else if (!rPending && (r.exitCode !== 0 || r.interrupted || r.detached || r.timedOut || hasEmptyTextOutputWithoutOutputTarget(r.task, output))) {
 			c.addChild(new Text(truncLine(theme.fg(r.exitCode !== 0 ? "error" : "dim", `    ⎿  ${resultStatusLine(r, output)}`), width), 0, 0));
 		}
 		const outputTarget = extractOutputTarget(r.task);
@@ -1273,7 +1278,7 @@ export function renderSubagentResult(
 		&& r.progress?.status !== "running"
 		&& hasEmptyTextOutputWithoutOutputTarget(r.task, getSingleResultOutput(r)),
 	);
-	const hasWorkflowFailure = workflowGraphHasStatus(d, ["failed"]);
+	const hasWorkflowFailure = workflowGraphHasStatus(d, ["failed", "timed-out"]);
 	const hasWorkflowPause = workflowGraphHasStatus(d, ["paused", "detached"]);
 	const icon = hasRunning
 		? theme.fg("warning", "running")