pi-subagents 0.58.0 → 0.60.0

package/src/runs/shared/pi-args.ts

@@ -48,7 +48,7 @@ import {
 	encodeChildWatchdogConfig,
 	type ChildWatchdogConfig,
 } from "../../watchdog/child-status.ts";
-import { WAIT_TOOL_ENABLED_ENV } from "../background/wait-config.ts";
+import { WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV, WAIT_TOOL_ENABLED_ENV } from "../background/wait-config.ts";
 import {
 	PI_CODING_AGENT_PACKAGE_ROOT_ENV,
 	getAgentDir,
@@ -117,6 +117,7 @@ const FAST_MODE_ALLOWED_MODELS = new Set([
 	"openai-codex/gpt-5.6-luna",
 	"openai-codex/gpt-5.6-sol",
 ]);
+const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
 export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 export const SUBAGENT_ORCHESTRATOR_TARGET_ENV =
 	"PI_SUBAGENT_ORCHESTRATOR_TARGET";
@@ -139,6 +140,7 @@ export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
 export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV =
 	"PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
 export const SUBAGENT_PARENT_SESSION_ENV = "PI_SUBAGENT_PARENT_SESSION";
+export const SUBAGENT_FORK_CACHE_KEY_ENV = "PI_SUBAGENT_FORK_CACHE_KEY";
 export const SUBAGENT_STEER_INBOX_ENV = "PI_SUBAGENT_STEER_INBOX";
 export const SUBAGENT_STEER_CAPABILITY_ENV = "PI_SUBAGENT_STEER_CAPABILITY";
 export const SUBAGENT_STEER_ACK_DIR_ENV = "PI_SUBAGENT_STEER_ACK_DIR";
@@ -146,8 +148,16 @@ export const PI_INTERCOM_STABLE_ID_ENV = "PI_INTERCOM_STABLE_ID";
 export const PI_INTERCOM_SESSION_ID_ENV = "PI_INTERCOM_SESSION_ID";
 export const SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_GLOBAL_CONTEXT";
 
+export function deriveForkPromptCacheKey(parentSessionId: string | undefined): string | undefined {
+	const parent = parentSessionId?.trim();
+	if (!parent) return undefined;
+	const digest = createHash("sha256").update(parent).digest("hex").slice(0, OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH - "pi-fork:".length);
+	return `pi-fork:${digest}`;
+}
+
 export interface BuildPiArgsInput {
 	parentSessionId?: string;
+	forkCacheKey?: string;
 	baseArgs: string[];
 	task: string;
 	sessionEnabled: boolean;
@@ -170,6 +180,11 @@ export interface BuildPiArgsInput {
 	cwd?: string;
 	promptFileStem?: string;
 	intercomSessionName?: string;
+	/** Human-readable display name for the child session (agent + task excerpt,
+	 *  derived by the caller). Passed to the child as PI_SUBAGENT_SESSION_NAME;
+	 *  the prompt runtime applies it via pi.setSessionName unless an intercom
+	 *  target takes precedence. */
+	sessionName?: string;
 	orchestratorIntercomTarget?: string;
 	runId?: string;
 	childAgentName?: string;
@@ -206,6 +221,8 @@ export interface BuildPiArgsInput {
 	 */
 	taskDelivery?: SubagentTaskDelivery;
 	waitToolEnabled?: boolean;
+	waitToolDefaultTimeoutMs?: number;
+	allowNestedSubagents?: boolean;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
 	extensionBindings?: ExtensionBindings;
@@ -283,6 +300,7 @@ function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fas
 
 export interface ResolvePiLaunchToolPlanInput {
 	tools?: string[];
+	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
 	mcpDirectTools?: string[];
@@ -481,7 +499,10 @@ export function resolvePiLaunchToolPlan(
 					? ["read", ...requestedBuiltinTools]
 					: requestedBuiltinTools
 				).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
-	const fanoutAuthorized = declaredBuiltinTools.includes("subagent");
+	const fanoutAuthorized = declaredBuiltinTools.includes("subagent") || (
+		input.allowNestedSubagents === true &&
+		(!allowedToolSet || allowedToolSet.has("subagent"))
+	);
 	const toolExtensionPaths: string[] = capabilityCeiling?.denyExtensions
 		? []
 		: (input.tools ?? []).filter(
@@ -496,8 +517,13 @@ export function resolvePiLaunchToolPlan(
 		throw new Error(formatUnresolvedMcpDirectToolSelectors(mcpResolution.unresolvedSelectors));
 	}
 	const resolvedMcpSelections = mcpResolution.selections;
+	const resolvedMcpNames = new Set(resolvedMcpSelections.map((selection) => selection.name));
+	const legacyMcpNameCounts = countLegacyUnderscoreMcpToolNames(resolvedMcpSelections);
 	const effectiveMcpSelections = resolvedMcpSelections.filter(
-		(selection) => !allowedToolSet || allowedToolSet.has(selection.name),
+		(selection) =>
+			!allowedToolSet ||
+			allowedToolSet.has(selection.name) ||
+			isLegacyUnderscoreMcpToolAllowed(selection, allowedToolSet, resolvedMcpNames, legacyMcpNameCounts),
 	);
 	const effectiveMcpTools = effectiveMcpSelections.map(
 		(selection) => selection.name,
@@ -652,6 +678,36 @@ export function resolvePiLaunchToolPlan(
 	};
 }
 
+// Capability ceilings persisted before #1685 may still name hyphenated MCP server prefixes with underscores.
+function countLegacyUnderscoreMcpToolNames(selections: readonly ResolvedMcpDirectToolSelection[]): Map<string, number> {
+	const counts = new Map<string, number>();
+	for (const selection of selections) {
+		const legacyName = legacyUnderscoreMcpToolName(selection);
+		if (legacyName !== selection.name) counts.set(legacyName, (counts.get(legacyName) ?? 0) + 1);
+	}
+	return counts;
+}
+
+function isLegacyUnderscoreMcpToolAllowed(
+	selection: ResolvedMcpDirectToolSelection,
+	allowedToolSet: ReadonlySet<string>,
+	resolvedMcpNames: ReadonlySet<string>,
+	legacyMcpNameCounts: ReadonlyMap<string, number>,
+): boolean {
+	const legacyName = legacyUnderscoreMcpToolName(selection);
+	return legacyMcpNameCounts.get(legacyName) === 1 && !resolvedMcpNames.has(legacyName) && allowedToolSet.has(legacyName);
+}
+
+function legacyUnderscoreMcpToolName(selection: ResolvedMcpDirectToolSelection): string {
+	const slash = selection.selector.indexOf("/");
+	if (slash < 1) return selection.name;
+	const toolName = selection.selector.slice(slash + 1);
+	const suffix = `_${toolName}`;
+	if (!selection.name.endsWith(suffix)) return selection.name;
+	const prefix = selection.name.slice(0, -suffix.length);
+	return `${prefix.replace(/-/g, "_")}${suffix}`;
+}
+
 /** Escape XML-significant characters in a string for safe attribute interpolation. */
 function escapeXmlAttr(value: string): string {
 	return value
@@ -684,6 +740,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 
 	const toolPlan = resolvePiLaunchToolPlan({
 		tools: input.tools,
+		allowNestedSubagents: input.allowNestedSubagents,
 		extensions: input.extensions,
 		subagentOnlyExtensions: input.subagentOnlyExtensions,
 		mcpDirectTools: input.mcpDirectTools,
@@ -795,6 +852,9 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.waitToolEnabled !== undefined) {
 		env[WAIT_TOOL_ENABLED_ENV] = input.waitToolEnabled ? "true" : "false";
 	}
+	if (input.waitToolDefaultTimeoutMs !== undefined) {
+		env[WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV] = String(input.waitToolDefaultTimeoutMs);
+	}
 	const inheritedNestedRoute = Boolean(
 		process.env[SUBAGENT_PARENT_EVENT_SINK_ENV] &&
 			process.env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV] &&
@@ -878,6 +938,9 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.intercomSessionName) {
 		env.PI_SUBAGENT_INTERCOM_SESSION_NAME = input.intercomSessionName;
 	}
+	if (input.sessionName?.trim()) {
+		env.PI_SUBAGENT_SESSION_NAME = input.sessionName.trim();
+	}
 	if (input.orchestratorIntercomTarget) {
 		env[SUBAGENT_ORCHESTRATOR_TARGET_ENV] = input.orchestratorIntercomTarget;
 	}
@@ -956,6 +1019,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 
 	env[SUBAGENT_PARENT_SESSION_ENV] =
 		input.parentSessionId ?? process.env[SUBAGENT_PARENT_SESSION_ENV] ?? "";
+	env[SUBAGENT_FORK_CACHE_KEY_ENV] = input.forkCacheKey?.trim() || undefined;
 
 	return {
 		args,

package/src/runs/shared/single-output.ts

@@ -8,6 +8,17 @@ export interface SingleOutputSnapshot {
 	exists: boolean;
 	mtimeMs?: number;
 	size?: number;
+	error?: string;
+}
+
+function missingFileStatError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+function snapshotFromStatError(error: unknown): SingleOutputSnapshot {
+	if (missingFileStatError(error)) return { exists: false };
+	return { exists: false, error: error instanceof Error ? error.message : String(error) };
 }
 
 /**
@@ -161,23 +172,67 @@ export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, o
 	return undefined;
 }
 
+export function resolveSingleOutputClaimPath(outputPath: string): string {
+	let existing = path.resolve(outputPath);
+	const missingSegments: string[] = [];
+	while (!fs.existsSync(existing)) {
+		missingSegments.unshift(path.basename(existing));
+		const parent = path.dirname(existing);
+		if (parent === existing) break;
+		existing = parent;
+	}
+	return path.join(fs.realpathSync(existing), ...missingSegments);
+}
+
+function outputClaimError(outputPath: string, expectedClaimPath: string | undefined): string | undefined {
+	if (expectedClaimPath && resolveSingleOutputClaimPath(outputPath) !== expectedClaimPath) return "Output path changed after it was claimed.";
+	return undefined;
+}
+
 export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
 	if (!outputPath) return undefined;
 	try {
 		const stat = fs.statSync(outputPath);
 		return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
-	} catch {
-		// The snapshot is advisory; resolveSingleOutput reports concrete read/write failures.
-		return { exists: false };
+	} catch (error) {
+		return snapshotFromStatError(error);
+	}
+}
+
+function inspectSingleOutputChange(
+	outputPath: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { changed: boolean; error?: string } {
+	if (beforeRun?.error) return { changed: false, error: beforeRun.error };
+	try {
+		const stat = fs.statSync(outputPath);
+		return {
+			changed: !beforeRun?.exists || stat.mtimeMs !== beforeRun.mtimeMs || stat.size !== beforeRun.size,
+		};
+	} catch (error) {
+		if (missingFileStatError(error)) return { changed: false };
+		return { changed: false, error: error instanceof Error ? error.message : String(error) };
 	}
 }
 
+export function hasSingleOutputChangedSinceSnapshot(
+	outputPath: string | undefined,
+	beforeRun: SingleOutputSnapshot | undefined,
+): boolean | undefined {
+	if (!outputPath) return undefined;
+	const inspected = inspectSingleOutputChange(outputPath, beforeRun);
+	return inspected.error ? undefined : inspected.changed;
+}
+
 function persistSingleOutput(
 	outputPath: string | undefined,
 	fullOutput: string,
-): { savedPath?: string; error?: string } {
+	expectedClaimPath?: string,
+): { savedPath?: string; error?: string; fatalError?: boolean } {
 	if (!outputPath) return {};
 	try {
+		const claimError = outputClaimError(outputPath, expectedClaimPath);
+		if (claimError) return { error: claimError, fatalError: true };
 		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
 		fs.writeFileSync(outputPath, fullOutput, "utf-8");
 		return { savedPath: outputPath };
@@ -190,26 +245,21 @@ export function resolveSingleOutput(
 	outputPath: string | undefined,
 	fallbackOutput: string,
 	beforeRun: SingleOutputSnapshot | undefined,
-): { fullOutput: string; savedPath?: string; saveError?: string } {
+	expectedClaimPath?: string,
+): { fullOutput: string; savedPath?: string; saveError?: string; fatalError?: boolean } {
 	if (!outputPath) return { fullOutput: fallbackOutput };
+	const claimError = outputClaimError(outputPath, expectedClaimPath);
+	if (claimError) return { fullOutput: fallbackOutput, saveError: claimError, fatalError: true };
 
-	let changedSinceStart = false;
-	try {
-		const stat = fs.statSync(outputPath);
-		changedSinceStart = !beforeRun?.exists
-			|| stat.mtimeMs !== beforeRun.mtimeMs
-			|| stat.size !== beforeRun.size;
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
-		if (code !== "ENOENT" && code !== "ENOTDIR") {
-			return {
-				fullOutput: fallbackOutput,
-				saveError: `Failed to inspect output file: ${error instanceof Error ? error.message : String(error)}`,
-			};
-		}
+	const changedSinceStart = inspectSingleOutputChange(outputPath, beforeRun);
+	if (changedSinceStart.error) {
+		return {
+			fullOutput: fallbackOutput,
+			saveError: `Failed to inspect output file: ${changedSinceStart.error}`,
+		};
 	}
 
-	if (changedSinceStart) {
+	if (changedSinceStart.changed) {
 		try {
 			return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
 		} catch (error) {
@@ -220,9 +270,9 @@ export function resolveSingleOutput(
 		}
 	}
 
-	const save = persistSingleOutput(outputPath, fallbackOutput);
+	const save = persistSingleOutput(outputPath, fallbackOutput, expectedClaimPath);
 	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath };
-	return { fullOutput: fallbackOutput, saveError: save.error };
+	return { fullOutput: fallbackOutput, saveError: save.error, ...(save.fatalError ? { fatalError: true } : {}) };
 }
 
 export function finalizeSingleOutput(params: {

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BeforeProviderRequestEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
 import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.ts";
 import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, PERMISSION_POLICY_ENV } from "./permissions.ts";
 import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerDeliveryStatus, type SteerRequest } from "../background/control-channel.ts";
-import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
+import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_FORK_CACHE_KEY_ENV, SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV, isRuntimeAcknowledgedExtensionId, writeRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
 import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
 import {
@@ -32,6 +32,9 @@ import { drainOutstandingWork } from "../background/auto-drain.ts";
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
 export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
+/** Human-readable child display name (agent + task excerpt) set by the parent
+ *  at launch; applied via pi.setSessionName when no intercom target exists. */
+export const SUBAGENT_SESSION_NAME_ENV = "PI_SUBAGENT_SESSION_NAME";
 const STEERING_LEGACY_SETTLE_FALLBACK_MS = 1000;
 const STEERING_SAFETY_POLL_INTERVAL_MS = 5000;
 
@@ -288,10 +291,27 @@ const PORTABLE_TOOL_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
 const MAX_PORTABLE_TOOL_ID_LENGTH = 64;
 const COMPOSITE_TOOL_ID_APIS = new Set([
 	"azure-openai-responses",
+	"cursor-native",
+	"openai-completions",
+	"openai-responses",
+]);
+const PROMPT_CACHE_KEY_APIS = new Set([
+	"azure-openai-responses",
+	"openai-codex-responses",
 	"openai-completions",
 	"openai-responses",
 ]);
 
+export function rewriteForkCacheProviderRequest(event: BeforeProviderRequestEvent, ctx?: Pick<ExtensionContext, "model">): unknown {
+	const forkCacheKey = process.env[SUBAGENT_FORK_CACHE_KEY_ENV]?.trim();
+	if (!forkCacheKey || !PROMPT_CACHE_KEY_APIS.has(ctx?.model?.api ?? "")) return undefined;
+	if (!event || typeof event !== "object") return undefined;
+	const payload = event.payload;
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+	if (typeof (payload as { prompt_cache_key?: unknown }).prompt_cache_key !== "string") return undefined;
+	return { ...payload, prompt_cache_key: forkCacheKey };
+}
+
 function portableToolId(id: string): string {
 	if (PORTABLE_TOOL_ID_PATTERN.test(id) && id.length <= MAX_PORTABLE_TOOL_ID_LENGTH) return id;
 	const encoded = `tool_${Buffer.from(id).toString("base64url") || "empty"}`;
@@ -671,7 +691,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	registerPermissionGate(pi);
 	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV], { allowZero: process.env[TOOL_BUDGET_ZERO_AUTH_ENV] === "1" }));
 	registerChildWatchdog(pi);
-	const waitToolEnabled = resolveWaitToolConfig().enabled;
+	const waitToolConfig = resolveWaitToolConfig();
 	const waitState = {
 		baseCwd: "",
 		currentSessionId: null,
@@ -686,7 +706,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		watcherRestartTimer: null,
 		resultFileCoalescer: { schedule: () => false, clear: () => {} },
 	} as unknown as SubagentState;
-	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, waitToolEnabled);
+	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, waitToolConfig.enabled, undefined, waitToolConfig.defaultTimeoutMs);
 	let nativeSupervisorClientRegistered = false;
 	const registerNativeSupervisorClientOnce = (): void => {
 		if (nativeSupervisorClientRegistered) return;
@@ -744,6 +764,8 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		});
 	}
 
+	onRuntimeEvent("before_provider_request", (event: unknown, ctx?: ExtensionContext) => rewriteForkCacheProviderRequest(event as BeforeProviderRequestEvent, ctx));
+
 	onRuntimeEvent("context", (event: unknown, ctx?: ExtensionContext) => {
 		if (!event || typeof event !== "object" || !("messages" in event) || !Array.isArray(event.messages)) return undefined;
 		const messages = stripParentOnlySubagentMessages(event.messages, {
@@ -756,9 +778,14 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	onRuntimeEvent("before_agent_start", async (event: unknown) => {
 		if (!event || typeof event !== "object" || !("systemPrompt" in event) || typeof event.systemPrompt !== "string") return undefined;
 		registerNativeSupervisorClientOnce();
+		// The intercom target is a routing address and always wins; the display
+		// name (agent + task excerpt, computed by the parent at launch) only
+		// applies when the bridge is not addressing this child.
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
-		if (intercomSessionName && typeof pi.setSessionName === "function") {
-			pi.setSessionName(intercomSessionName);
+		const displaySessionName = process.env[SUBAGENT_SESSION_NAME_ENV]?.trim();
+		const childSessionName = intercomSessionName || displaySessionName;
+		if (childSessionName && typeof pi.setSessionName === "function") {
+			pi.setSessionName(childSessionName);
 		}
 
 		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);

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

@@ -13,6 +13,21 @@ export interface WorkflowGraphBuildInput {
 	dynamicGroupStatuses?: Record<number, { status: WorkflowNodeStatus; error?: string; acceptance?: SingleResult["acceptance"] }>;
 }
 
+/** Return displayable workflow stages while hiding structural parallel groups and host monitors. */
+export function workflowGraphStageNodes(graph: WorkflowGraphSnapshot | undefined): WorkflowGraphNode[] {
+	if (!graph?.nodes?.length) return [];
+	const stages: WorkflowGraphNode[] = [];
+	const visit = (node: WorkflowGraphNode): void => {
+		if (node.kind === "parallel-group" || node.kind === "dynamic-parallel-group") {
+			for (const child of node.children ?? []) visit(child);
+			return;
+		}
+		if (node.kind !== "host-step") stages.push(node);
+	};
+	for (const node of graph.nodes) visit(node);
+	return stages;
+}
+
 function normalizeStatus(status: string | undefined): WorkflowNodeStatus | undefined {
 	switch (status) {
 		case "complete":