@bastani/atomic 0.8.21 → 0.8.22-0

package/dist/builtin/workflows/src/runs/foreground/stage-control-registry.ts

@@ -276,7 +276,7 @@ export function createStageControlRegistry(): StageControlRegistry {
       _byRun.clear();
       for (const handle of handles) {
         void Promise.resolve(handle.dispose?.()).catch((err: unknown) => {
-          console.warn("pi-workflows: stage handle dispose failed", err);
+          console.warn("atomic-workflows: stage handle dispose failed", err);
         });
       }
     },

package/dist/builtin/workflows/src/runs/foreground/stage-runner.ts

@@ -9,7 +9,13 @@
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
-import { SessionManager, type AgentSession, type CreateAgentSessionOptions, type PromptOptions } from "@bastani/atomic";
+import {
+  shouldApplyCodexFastModeForScope,
+  SessionManager,
+  type AgentSession,
+  type CreateAgentSessionOptions,
+  type PromptOptions,
+} from "@bastani/atomic";
 import type {
   CompleteStageOpts,
   StageContext,
@@ -19,6 +25,7 @@ import type {
   StagePromptOptions,
   WorkflowMaxOutput,
   WorkflowModelAttempt,
+  WorkflowExecutionMode,
   WorkflowModelCatalogPort,
 } from "../../shared/types.js";
 import {
@@ -47,6 +54,8 @@ export interface StageSessionRuntime {
   readonly isStreaming: AgentSession["isStreaming"];
   /** Number of SDK-level queued steering/follow-up messages, when supported. */
   readonly pendingMessageCount?: number;
+  /** Settings manager supplied by the Atomic SDK when the adapter did not pre-create one. */
+  readonly settingsManager?: WorkflowFastModeSettingsManager;
   navigateTree: AgentSession["navigateTree"];
   compact: AgentSession["compact"];
   abortCompaction(): void;
@@ -57,12 +66,27 @@ export interface StageSessionRuntime {
 
 export type StageSessionCreateOptions = CreateAgentSessionOptions & Pick<StageOptions, "mcp" | "fallbackModels">;
 
+type WorkflowFastModeSettings = {
+  readonly chat: boolean;
+  readonly workflow: boolean;
+};
+
+type WorkflowFastModeSettingsManager = {
+  getCodexFastModeSettings(): WorkflowFastModeSettings;
+};
+
+export interface StageSessionCreateResult {
+  readonly session: StageSessionRuntime;
+  readonly settingsManager?: WorkflowFastModeSettingsManager;
+}
+
 export interface AgentSessionAdapter {
-  create(options: StageSessionCreateOptions, meta?: StageExecutionMeta): Promise<StageSessionRuntime>;
+  create(options: StageSessionCreateOptions, meta?: StageExecutionMeta): Promise<StageSessionRuntime | StageSessionCreateResult>;
 }
 
 export interface StageModelFallbackMeta {
   readonly model?: string;
+  readonly fastMode?: boolean;
   readonly attemptedModels?: readonly string[];
   readonly modelAttempts?: readonly WorkflowModelAttempt[];
   readonly warnings?: readonly string[];
@@ -94,6 +118,10 @@ export interface StageRunnerOpts {
   signal?: AbortSignal;
   /** Optional model catalog used for fallback validation/resolution. */
   models?: WorkflowModelCatalogPort;
+  /** Runtime execution mode forwarded to stage session adapters. */
+  executionMode?: WorkflowExecutionMode;
+  /** Internal: notifies the executor when an in-flight fallback changes model/fast metadata. */
+  onModelFallbackMetaChange?: (meta: StageModelFallbackMeta) => void;
 }
 
 export interface InternalStageContext extends StageContext {
@@ -164,17 +192,17 @@ type AgentSessionConsumer = "prompt" | "complete";
 function missingAdapter(consumer: AgentSessionConsumer): never {
   if (consumer === "complete") {
     throw new Error(
-      "pi-workflows: ctx.complete requires either RunOpts.adapters.complete or RunOpts.adapters.agentSession",
+      "atomic-workflows: ctx.complete requires either RunOpts.adapters.complete or RunOpts.adapters.agentSession",
     );
   }
   throw new Error(
-    "pi-workflows: prompt adapter not configured — provide an AgentSessionAdapter via RunOpts.adapters.agentSession",
+    "atomic-workflows: prompt adapter not configured — provide an AgentSessionAdapter via RunOpts.adapters.agentSession",
   );
 }
 
 function unavailableSync(property: string): never {
   throw new Error(
-    `pi-workflows: stage AgentSession property "${property}" is unavailable until the SDK session has been created`,
+    `atomic-workflows: stage AgentSession property "${property}" is unavailable until the SDK session has been created`,
   );
 }
 
@@ -400,7 +428,7 @@ function splitPromptOptions(options: StagePromptOptions | undefined): {
 function validatePromptOutputOptions(outputOptions: StageOutputOptions): void {
   if (outputOptions.outputMode === "file-only" && (typeof outputOptions.output !== "string" || outputOptions.output.length === 0)) {
     throw new Error(
-      "pi-workflows: prompt sets outputMode: \"file-only\" but does not configure an output file. Set output to a path or use outputMode: \"inline\".",
+      "atomic-workflows: prompt sets outputMode: \"file-only\" but does not configure an output file. Set output to a path or use outputMode: \"inline\".",
     );
   }
 }
@@ -430,8 +458,8 @@ async function finalizePromptOutput(
 }
 
 export function createStageContext(opts: StageRunnerOpts): InternalStageContext {
-  const { stageId, stageName, adapters, runId, signal, stageOptions } = opts;
-  const meta: StageExecutionMeta = { runId, stageId, stageName, signal, stageOptions };
+  const { stageId, stageName, adapters, runId, signal, stageOptions, executionMode } = opts;
+  const meta: StageExecutionMeta = { runId, stageId, stageName, signal, stageOptions, executionMode };
   let session: StageSessionRuntime | undefined;
   let sessionPromise: Promise<StageSessionRuntime> | undefined;
   let lastAssistantText: string | undefined;
@@ -532,19 +560,52 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     return { ...(stageOptions ?? {}), model: candidate.value, fallbackModels: undefined };
   }
 
-  function attachSession(created: StageSessionRuntime): StageSessionRuntime {
-    session = created;
+  let sessionSettingsManager: WorkflowFastModeSettingsManager | undefined;
+
+  function isWorkflowFastModeEnabled(): boolean | undefined {
+    const model = session?.model;
+    const settingsManager = sessionSettingsManager ?? stageOptions?.settingsManager;
+    if (model === undefined || settingsManager === undefined) return undefined;
+    return shouldApplyCodexFastModeForScope(model, settingsManager.getCodexFastModeSettings(), "workflow");
+  }
+
+  function currentModelFallbackMeta(): StageModelFallbackMeta {
+    const attemptedModels = modelAttempts.map((attempt) => attempt.model);
+    const model = selectedModel ?? workflowModelId(session?.model);
+    const fastMode = isWorkflowFastModeEnabled();
+    return {
+      ...(model !== undefined ? { model } : {}),
+      ...(fastMode !== undefined ? { fastMode } : {}),
+      ...(attemptedModels.length > 0 ? { attemptedModels } : {}),
+      ...(modelAttempts.length > 0 ? { modelAttempts: [...modelAttempts] } : {}),
+      ...(modelWarnings.length > 0 ? { warnings: [...modelWarnings] } : {}),
+    };
+  }
+
+  function notifyModelFallbackMetaChange(): void {
+    opts.onModelFallbackMetaChange?.(currentModelFallbackMeta());
+  }
+
+  function normalizeSessionCreateResult(created: StageSessionRuntime | StageSessionCreateResult): StageSessionCreateResult {
+    if ("session" in created) return created;
+    return { session: created };
+  }
+
+  function attachSession(created: StageSessionRuntime | StageSessionCreateResult): StageSessionRuntime {
+    const result = normalizeSessionCreateResult(created);
+    session = result.session;
+    sessionSettingsManager = result.settingsManager ?? result.session.settingsManager;
     if (pendingThinkingLevel !== undefined) {
-      created.setThinkingLevel(pendingThinkingLevel);
+      result.session.setThinkingLevel(pendingThinkingLevel);
     }
     for (const listener of pendingListeners) {
-      listenerUnsubscribes.set(listener, created.subscribe(listener));
+      listenerUnsubscribes.set(listener, result.session.subscribe(listener));
     }
     // Track terminating tool calls for this session so the stage result text is
     // derived deterministically from a tool that actually ended the turn.
     unsubscribeTerminateWatcher?.();
-    unsubscribeTerminateWatcher = created.subscribe((event) => recordTerminatingToolCall(event));
-    return created;
+    unsubscribeTerminateWatcher = result.session.subscribe((event) => recordTerminatingToolCall(event));
+    return result.session;
   }
 
   async function createSession(
@@ -561,7 +622,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
   }
 
   async function ensureSession(consumer: AgentSessionConsumer = "prompt"): Promise<StageSessionRuntime> {
-    if (disposed) throw new Error(`pi-workflows: stage "${stageName}" session has been disposed`);
+    if (disposed) throw new Error(`atomic-workflows: stage "${stageName}" session has been disposed`);
     if (!sessionPromise) {
       sessionPromise = (async () => {
         if (!hasExplicitModelFallbackConfig) return createSession(undefined, consumer);
@@ -580,6 +641,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     const current = session;
     session = undefined;
     sessionPromise = undefined;
+    sessionSettingsManager = undefined;
     for (const unsubscribe of listenerUnsubscribes.values()) unsubscribe();
     listenerUnsubscribes.clear();
     unsubscribeTerminateWatcher?.();
@@ -651,6 +713,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
         : await createSession(candidate, consumer);
       activeCandidateIndex = index;
       selectedModel = candidate.id;
+      notifyModelFallbackMetaChange();
       try {
         await promptWithPauseResume(activeSession, text, sdkOptions);
         modelAttempts.push({ model: candidate.id, success: true });
@@ -705,7 +768,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
         completeOpts?.fallbackModels !== undefined
       ) {
         throw new Error(
-          "pi-workflows: complete options require a CompleteAdapter via RunOpts.adapters.complete",
+          "atomic-workflows: complete options require a CompleteAdapter via RunOpts.adapters.complete",
         );
       }
       // Intentional fallback: when a CompleteAdapter is not configured,
@@ -835,14 +898,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     },
 
     __modelFallbackMeta() {
-      const attemptedModels = modelAttempts.map((attempt) => attempt.model);
-      const model = selectedModel ?? workflowModelId(session?.model);
-      return {
-        ...(model !== undefined ? { model } : {}),
-        ...(attemptedModels.length > 0 ? { attemptedModels } : {}),
-        ...(modelAttempts.length > 0 ? { modelAttempts: [...modelAttempts] } : {}),
-        ...(modelWarnings.length > 0 ? { warnings: [...modelWarnings] } : {}),
-      };
+      return currentModelFallbackMeta();
     },
 
     async __requestPause() {

package/dist/builtin/workflows/src/runs/shared/validate-inputs.ts

@@ -1,20 +1,35 @@
 /**
  * validateInputs — check a parsed input bag against a workflow's declared
- * input schema. Used by slash-command and programmatic SDK dispatch paths to
- * reject malformed input payloads before dispatch.
+ * TypeBox input schema. Used by slash-command and programmatic SDK dispatch
+ * paths to reject malformed input payloads before dispatch.
  *
  * Reports:
  *   - unknown input keys (catches typos like "propmt")
- *   - wrong-typed values (number/boolean/string/text/select)
- *   - select values not in the declared choices
+ *   - wrong-typed values (number/boolean/string/select-union/integer)
+ *   - select values not in the declared literal union
  *   - missing required inputs
+ *   - non-JSON-serializable values
  *
  * Does NOT coerce: "true" is not a boolean, "3" is not a number. JSON parsing
  * upstream already preserves types — string-typed values reaching this point
  * are user mistakes worth surfacing.
+ *
+ * The legacy `{ type }` descriptor is gone; the field kind, choices, and
+ * required-ness are derived from the TypeBox schema via schema-introspection,
+ * keeping the historical error wording byte-for-byte stable.
  */
 
-import type { WorkflowInputSchema } from "../../shared/types.js";
+import { Value } from "typebox/value";
+import {
+  workflowSerializableValidationError,
+  workflowSerializableTypeName,
+} from "../../shared/serializable.js";
+import {
+  schemaChoices,
+  schemaFieldKind,
+  schemaIsRequired,
+} from "../../shared/schema-introspection.js";
+import type { TSchema, WorkflowInputValues } from "../../shared/types.js";
 
 export interface ValidationError {
   key: string;
@@ -22,8 +37,8 @@ export interface ValidationError {
 }
 
 export function validateInputs(
-  schema: Readonly<Record<string, WorkflowInputSchema>>,
-  inputs: Record<string, unknown>,
+  schema: Readonly<Record<string, TSchema>>,
+  inputs: WorkflowInputValues,
 ): ValidationError[] {
   const errors: ValidationError[] = [];
 
@@ -35,49 +50,71 @@ export function validateInputs(
 
   for (const [key, def] of Object.entries(schema)) {
     const value = inputs[key];
+    let hasTypeError = false;
 
     if (value === undefined) {
-      if (def.required === true) {
+      if (schemaIsRequired(def)) {
         errors.push({ key, reason: "required input is missing" });
       }
       continue;
     }
 
-    switch (def.type) {
+    const kind = schemaFieldKind(def);
+    switch (kind) {
       case "text":
-      case "string":
         if (typeof value !== "string") {
-          errors.push({ key, reason: `expected string, got ${typeName(value)}` });
+          errors.push({ key, reason: `expected string, got ${workflowSerializableTypeName(value)}` });
+          hasTypeError = true;
         }
         break;
       case "number":
-        if (typeof value !== "number" || Number.isNaN(value)) {
-          errors.push({ key, reason: `expected number, got ${typeName(value)}` });
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+          errors.push({ key, reason: `expected finite number, got ${workflowSerializableTypeName(value)}` });
+          hasTypeError = true;
+        }
+        break;
+      case "integer":
+        if (typeof value !== "number" || !Number.isInteger(value)) {
+          errors.push({ key, reason: `expected integer, got ${workflowSerializableTypeName(value)}` });
+          hasTypeError = true;
         }
         break;
       case "boolean":
         if (typeof value !== "boolean") {
-          errors.push({ key, reason: `expected boolean, got ${typeName(value)}` });
+          errors.push({ key, reason: `expected boolean, got ${workflowSerializableTypeName(value)}` });
+          hasTypeError = true;
         }
         break;
       case "select": {
-        const allowed = def.choices.join(", ");
+        const choices = schemaChoices(def) ?? [];
+        const allowed = choices.join(", ");
         if (typeof value !== "string") {
-          errors.push({ key, reason: `expected one of [${allowed}], got ${typeName(value)}` });
-        } else if (!def.choices.includes(value)) {
+          errors.push({ key, reason: `expected one of [${allowed}], got ${workflowSerializableTypeName(value)}` });
+          hasTypeError = true;
+        } else if (!choices.includes(value)) {
           errors.push({ key, reason: `must be one of [${allowed}]` });
         }
         break;
       }
+      default:
+        // object / array / unknown: defer to the schema's own checker so a
+        // precise declared shape (Type.Object({ ... }), Type.Array(...)) is
+        // still enforced, while loose schemas accept any serializable value.
+        if (!Value.Check(def, value)) {
+          const first = [...Value.Errors(def, value)][0];
+          errors.push({ key, reason: first === undefined ? `does not match ${kind} schema` : first.message });
+          hasTypeError = true;
+        }
+        break;
+    }
+
+    const serializableError = hasTypeError
+      ? undefined
+      : workflowSerializableValidationError(value, `input "${key}"`);
+    if (serializableError !== undefined) {
+      errors.push({ key, reason: serializableError.replace(/^input "[^"]+" /, "") });
     }
   }
 
   return errors;
 }
-
-function typeName(value: unknown): string {
-  if (value === null) return "null";
-  if (Array.isArray(value)) return "array";
-  if (typeof value === "number" && Number.isNaN(value)) return "NaN";
-  return typeof value;
-}

package/dist/builtin/workflows/src/runs/shared/workflow-runner.ts

@@ -11,6 +11,7 @@ import { buildRuntimeAdapters, type RuntimeAdapterBuildOptions, type RuntimeWiri
 import { discoverWorkflows } from "../../extension/discovery.js";
 import { createStore } from "../../shared/store.js";
 import { renderInputsSchema } from "../../shared/render-inputs-schema.js";
+import { deriveInputFields } from "../../shared/schema-introspection.js";
 import { validateInputs, type ValidationError } from "./validate-inputs.js";
 import type { CreateAgentSessionOptions } from "@bastani/atomic";
 import type { StageSessionRuntime } from "../foreground/stage-runner.js";
@@ -22,6 +23,7 @@ import type {
   WorkflowDirectOptions,
   WorkflowDirectTaskItem,
   WorkflowInputSchema,
+  WorkflowInputValues,
   WorkflowMaxOutput,
   WorkflowOutputMode,
 } from "../../shared/types.js";
@@ -29,7 +31,7 @@ import type {
 export interface WorkflowDefinition extends StageOptions {
   mode?: "workflow" | "named" | "single" | "parallel" | "chain";
   workflow?: string;
-  inputs?: Record<string, unknown>;
+  inputs?: WorkflowInputValues;
   /** Direct single-task mode, or root task text for direct chain/parallel execution. */
   task?: WorkflowDirectTaskItem | string;
   /** Direct top-level parallel mode. */
@@ -221,12 +223,21 @@ async function runNamedWorkflow(
     const available = discovery.registry.names();
     throw new Error(`Workflow not found: "${workflowName}". Available: ${available.length > 0 ? available.join(", ") : "(none)"}`);
   }
-  const inputs = definition.inputs ?? {};
+  // Apply schema defaults before validating so an input declared with both
+  // `required: true` and a `default` is not rejected as "missing" when omitted,
+  // mirroring the resolve-then-validate order every other dispatch path uses.
+  // validateInputs (rather than resolveInputs) still surfaces the full set of
+  // input problems through formatWorkflowValidationFailure; run() re-resolves
+  // internally, which is idempotent on already-defaulted inputs.
+  const inputs = withResolvedDefaults(workflow.inputs, definition.inputs ?? {});
   const errors = validateInputs(workflow.inputs, inputs);
   if (errors.length > 0) {
     throw new Error(formatWorkflowValidationFailure(workflow.name, workflow.inputs, errors));
   }
-  const result = await run(workflow, inputs, runOptions);
+  const result = await run(workflow, inputs, {
+    ...runOptions,
+    registry: discovery.registry,
+  });
   return {
     action: "run",
     mode: "named",
@@ -241,18 +252,29 @@ async function runNamedWorkflow(
   };
 }
 
+function withResolvedDefaults(
+  schema: Readonly<Record<string, WorkflowInputSchema>>,
+  provided: WorkflowInputValues,
+): WorkflowInputValues {
+  const resolved: Record<string, WorkflowInputValues[string]> = {};
+  for (const [key, value] of Object.entries(provided)) {
+    if (value !== undefined) resolved[key] = value;
+  }
+  for (const [key, def] of Object.entries(schema)) {
+    const declaredDefault = (def as { default?: unknown }).default;
+    if (resolved[key] === undefined && declaredDefault !== undefined) {
+      resolved[key] = declaredDefault as WorkflowInputValues[string];
+    }
+  }
+  return resolved;
+}
+
 function formatWorkflowValidationFailure(
   workflowName: string,
   schema: Readonly<Record<string, WorkflowInputSchema>>,
   errors: ValidationError[],
 ): string {
-  const entries = Object.entries(schema).map(([name, definition]) => ({
-    name,
-    type: definition.type,
-    description: definition.description,
-    required: definition.required,
-    default: "default" in definition ? definition.default : undefined,
-  }));
+  const entries = deriveInputFields(schema);
   const lines = errors.map((error) => `  - ${error.key}: ${error.reason}`);
   return `Invalid inputs for "${workflowName}":\n${lines.join("\n")}\n\n${renderInputsSchema(workflowName, entries)}`;
 }

package/dist/builtin/workflows/src/sdk-surface.ts

@@ -7,9 +7,15 @@
  */
 
 export { defineWorkflow } from "./workflows/define-workflow.js";
+
+// TypeBox authoring surface so jiti-loaded workflows can `import { Type } from
+// "@bastani/workflows"` (the virtual module is built from this file).
+export { Type } from "typebox";
+export type { Static, TSchema } from "typebox";
 export { createRegistry } from "./workflows/registry.js";
 export { normalizeWorkflowName, workflowNamesEqual } from "./workflows/identity.js";
 export type * from "./shared/types.js";
+export { INTERACTIVE_WORKFLOW_POLICY, NON_INTERACTIVE_WORKFLOW_POLICY } from "./shared/types.js";
 export type { WorkflowBuilder, CompletedWorkflowBuilder } from "./workflows/define-workflow.js";
 export type { WorkflowRegistry } from "./workflows/registry.js";
 

package/dist/builtin/workflows/src/shared/expanded-workflow-graph.ts

@@ -0,0 +1,178 @@
+import type {
+  RunSnapshot,
+  StageSnapshot,
+  StoreSnapshot,
+} from "./store-types.js";
+
+export interface ExpandedWorkflowStageTarget {
+  readonly runId: string;
+  readonly stageId: string;
+  readonly runName: string;
+  readonly depth: number;
+}
+
+export interface ExpandedWorkflowStage extends StageSnapshot {
+  readonly workflowGraphTarget: ExpandedWorkflowStageTarget;
+}
+
+export interface ExpandedWorkflowGraph {
+  readonly stages: readonly ExpandedWorkflowStage[];
+  readonly targets: ReadonlyMap<string, ExpandedWorkflowStageTarget>;
+}
+
+interface ExpandedRunResult {
+  readonly stages: ExpandedWorkflowStage[];
+  readonly terminalIds: readonly string[];
+}
+
+function virtualStageId(runId: string, stageId: string, isRootRun: boolean): string {
+  return isRootRun ? stageId : `${runId}:${stageId}`;
+}
+
+function childRunIdFor(stage: StageSnapshot): string | undefined {
+  return stage.workflowChildRun?.runId ?? stage.workflowChild?.runId;
+}
+
+function childAliasFor(stage: StageSnapshot): string | undefined {
+  return stage.workflowChildRun?.alias ?? stage.workflowChild?.alias;
+}
+
+function localTerminalStageIds(stages: readonly StageSnapshot[]): readonly string[] {
+  const parentIds = new Set<string>();
+  for (const stage of stages) {
+    for (const parentId of stage.parentIds) parentIds.add(parentId);
+  }
+  const terminals = stages
+    .filter((stage) => !parentIds.has(stage.id))
+    .map((stage) => stage.id);
+  return terminals.length > 0 ? terminals : stages.map((stage) => stage.id);
+}
+
+/**
+ * Build a view-only expanded graph for a run and any nested child workflow
+ * runs it references. Child stages are cloned with virtual ids so their local
+ * parent ids do not collide with parent-run stage ids; each virtual node keeps
+ * a target mapping back to the actual `{ runId, stageId }` for attach/control.
+ *
+ * Imported workflows are flattened: a boundary stage that wraps a child run
+ * with its own stages is NOT emitted as its own node. Instead the child's
+ * stages stand in for it, so a nested workflow reads as a flat layout with no
+ * extra "information" node marking the import boundary. The boundary's incoming
+ * parents become the child roots' parents, and stages downstream of the
+ * boundary rewire to the child's terminal stages. A boundary whose child run
+ * produced no stages of its own is kept as a single node so the import stays
+ * visible. Boundary stages are non-attachable, so dropping them loses no
+ * interactive capability.
+ */
+export function expandWorkflowGraph(
+  snapshot: StoreSnapshot,
+  rootRunId: string,
+): ExpandedWorkflowGraph {
+  const runById = new Map(snapshot.runs.map((run) => [run.id, run]));
+  const root = runById.get(rootRunId);
+  if (!root) return { stages: [], targets: new Map() };
+
+  const targets = new Map<string, ExpandedWorkflowStageTarget>();
+  // Cycle guard only. This relies on the store invariant that each child run is
+  // referenced by exactly one parent stage (runIds are unique and a child run
+  // has a single boundary stage), so removing a run from `visiting` on exit
+  // cannot double-expand a shared child into duplicate virtual stage ids. If
+  // that invariant is ever relaxed, dedupe expanded stages by virtual id here.
+  const visiting = new Set<string>();
+
+  const expandRun = (
+    run: RunSnapshot,
+    depth: number,
+    incomingParentIds: readonly string[],
+  ): ExpandedRunResult => {
+    if (visiting.has(run.id)) return { stages: [], terminalIds: [] };
+    visiting.add(run.id);
+
+    const isRootRun = run.id === rootRunId;
+    const expandedStages: ExpandedWorkflowStage[] = [];
+    const replacementTerminals = new Map<string, readonly string[]>();
+
+    for (const stage of run.stages) {
+      const id = virtualStageId(run.id, stage.id, isRootRun);
+      const resolvedParentIds = stage.parentIds.length === 0
+        ? [...incomingParentIds]
+        : stage.parentIds.flatMap((parentId) =>
+            replacementTerminals.get(parentId) ?? [virtualStageId(run.id, parentId, isRootRun)],
+          );
+
+      const childRunId = childRunIdFor(stage);
+      const childRun = childRunId === undefined ? undefined : runById.get(childRunId);
+
+      // Flatten the imported workflow in place: when the boundary wraps a child
+      // run that has its own stages, splice those stages in instead of emitting
+      // the boundary node. Child roots inherit the boundary's incoming parents,
+      // and downstream stages rewire to the child's terminals below.
+      if (childRun !== undefined && childRun.stages.length > 0) {
+        const childExpanded = expandRun(childRun, depth + 1, resolvedParentIds);
+        expandedStages.push(...childExpanded.stages);
+        replacementTerminals.set(
+          stage.id,
+          childExpanded.terminalIds.length > 0 ? childExpanded.terminalIds : resolvedParentIds,
+        );
+        continue;
+      }
+
+      // Regular stage, or a boundary whose child produced no stages of its own:
+      // emit it so the import still appears as exactly one node.
+      const target: ExpandedWorkflowStageTarget = {
+        runId: run.id,
+        stageId: stage.id,
+        runName: run.name,
+        depth,
+      };
+      targets.set(id, target);
+      expandedStages.push({
+        ...stage,
+        id,
+        parentIds: Object.freeze(resolvedParentIds),
+        workflowGraphTarget: target,
+      });
+    }
+
+    const terminalIds = localTerminalStageIds(run.stages).flatMap((stageId) =>
+      replacementTerminals.get(stageId) ?? [virtualStageId(run.id, stageId, isRootRun)],
+    );
+
+    visiting.delete(run.id);
+    return { stages: expandedStages, terminalIds };
+  };
+
+  const expanded = expandRun(root, 0, []);
+  return { stages: expanded.stages, targets };
+}
+
+export function expandedStageTarget(
+  graph: ExpandedWorkflowGraph,
+  virtualStageIdValue: string,
+): ExpandedWorkflowStageTarget | undefined {
+  return graph.targets.get(virtualStageIdValue);
+}
+
+export function stageMatchesExpandedIdentifier(
+  stage: ExpandedWorkflowStage,
+  target: string,
+): boolean {
+  return (
+    stage.id === target ||
+    stage.name === target ||
+    stage.id.startsWith(target) ||
+    stage.workflowGraphTarget.stageId === target ||
+    stage.workflowGraphTarget.stageId.startsWith(target) ||
+    stage.workflowGraphTarget.runId === target ||
+    stage.workflowGraphTarget.runId.startsWith(target)
+  );
+}
+
+export function expandedStageLabel(stage: ExpandedWorkflowStage): string {
+  const runPrefix = stage.workflowGraphTarget.runId.slice(0, 8);
+  const stagePrefix = stage.workflowGraphTarget.stageId.slice(0, 8);
+  const depthPrefix = stage.workflowGraphTarget.depth > 0
+    ? `${childAliasFor(stage) ?? stage.workflowGraphTarget.runName}:`
+    : "";
+  return `${depthPrefix}${stage.name} (${runPrefix}/${stagePrefix})`;
+}