@bastani/atomic 0.8.21-0 → 0.8.22-0

package/dist/builtin/workflows/src/runs/foreground/executor.ts

@@ -5,7 +5,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
-import { CONFIG_DIR_NAME, createAskUserQuestionToolDefinition } from "@bastani/atomic";
+import { CONFIG_DIR_NAME, createAskUserQuestionToolDefinition, isCodexFastModeCandidateModelId } from "@bastani/atomic";
 import { stageUiBroker } from "../../shared/stage-ui-broker.js";
 import { buildStagePromptAdapter } from "../../shared/stage-prompt.js";
 import type {
@@ -34,6 +34,13 @@ import type {
   WorkflowPersistencePort,
   WorkflowRuntimeConfig,
   WorkflowModelCatalogPort,
+  WorkflowExecutionMode,
+  WorkflowRunChildOptions,
+  WorkflowChildResult,
+  WorkflowOutputSchema,
+  WorkflowOutputValues,
+  WorkflowInputValues,
+  WorkflowSerializableValue,
 } from "../../shared/types.js";
 import type { InternalStageContext, StageAdapters } from "./stage-runner.js";
 import type {
@@ -45,9 +52,12 @@ import type {
   WorkflowFailureKind,
   PendingPrompt,
   PromptKind,
+  WorkflowChildReplaySnapshot,
+  WorkflowChildRunRef,
 } from "../../shared/store-types.js";
 import type { StageControlHandle, StageControlRegistry, AgentSessionEventListener } from "./stage-control-registry.js";
 import type { Store } from "../../shared/store.js";
+import type { WorkflowRegistry } from "../../workflows/registry.js";
 import type { CancellationRegistry } from "../background/cancellation-registry.js";
 import { createStageContext } from "./stage-runner.js";
 import { GraphFrontierTracker } from "../shared/graph-inference.js";
@@ -71,12 +81,21 @@ import {
   appendStageEnd,
   appendRunEnd,
 } from "../../shared/persistence-session-entries.js";
-import { validateWorkflowModels } from "../shared/model-fallback.js";
+import { buildModelCandidatesFromCatalog, validateWorkflowModels, workflowModelId } from "../shared/model-fallback.js";
+import { validateInputs, type ValidationError } from "../shared/validate-inputs.js";
+import { Type, type TSchema } from "typebox";
+import { Value } from "typebox/value";
+import { schemaFieldKind, schemaChoices, schemaIsRequired } from "../../shared/schema-introspection.js";
 import type { WorkflowFailure } from "../../shared/workflow-failures.js";
 import { classifyWorkflowFailure } from "../../shared/workflow-failures.js";
 import { selectPromptCallsiteFrame } from "../shared/prompt-callsite.js";
+import {
+  assertWorkflowSerializableObject,
+  workflowSerializableValidationError,
+  workflowSerializableTypeName,
+} from "../../shared/serializable.js";
 
-export interface ResolvedInputs extends Record<string, unknown> {}
+export interface ResolvedInputs extends WorkflowInputValues {}
 
 export interface RunContinuationOpts {
   readonly source: RunSnapshot;
@@ -89,6 +108,8 @@ export interface RunOpts {
   cwd?: string;
   /** HIL adapter injected by the pi runtime or test harness. */
   ui?: WorkflowUIAdapter;
+  /** Runtime execution mode. Controls child session policy metadata. */
+  executionMode?: WorkflowExecutionMode;
   /** Internal detached-run mode: surface ctx.ui.* as node-local workflow prompt stages. */
   usePromptNodesForUi?: boolean;
   /**
@@ -132,6 +153,8 @@ export interface RunOpts {
   config?: WorkflowRuntimeConfig;
   /** Optional model catalog used for fallback validation/resolution. */
   models?: WorkflowModelCatalogPort;
+  /** Registry metadata forwarded to workflow runs launched from discovery/tooling. */
+  registry?: WorkflowRegistry;
   /**
    * Current nesting depth of this workflow run. Starts at 0 for top-level runs.
    * Callers that spawn nested runs must increment this by 1 before passing to
@@ -155,16 +178,22 @@ export interface RunOpts {
   runId?: string;
   /** Replay completed stages from a failed source run, then resume at this stage. */
   continuation?: RunContinuationOpts;
+  /** Internal parent linkage for nested ctx.workflow(...) runs. */
+  parentRun?: {
+    readonly runId: string;
+    readonly stageId: string;
+    readonly rootRunId: string;
+  };
   onRunStart?: (snapshot: RunSnapshot) => void;
   onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
   onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
-  onRunEnd?: (runId: string, status: RunStatus, result?: Record<string, unknown>, error?: string) => void;
+  onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string) => void;
 }
 
 export interface RunResult {
   readonly runId: string;
   readonly status: RunStatus;
-  readonly result?: Record<string, unknown>;
+  readonly result?: WorkflowOutputValues;
   readonly error?: string;
   readonly stages: StageSnapshot[];
 }
@@ -175,19 +204,25 @@ export interface RunResult {
 
 export function resolveInputs(
   schema: Readonly<Record<string, WorkflowInputSchema>>,
-  provided: Record<string, unknown>,
+  provided: Readonly<Record<string, unknown>>,
 ): ResolvedInputs {
-  const resolved: Record<string, unknown> = { ...provided };
+  const resolved: Record<string, WorkflowSerializableValue> = {};
+  for (const [key, value] of Object.entries(provided)) {
+    if (value !== undefined) resolved[key] = value as WorkflowSerializableValue;
+  }
 
-  for (const [key, schemaDef] of Object.entries(schema)) {
-    if (resolved[key] === undefined && "default" in schemaDef && schemaDef.default !== undefined) {
-      resolved[key] = schemaDef.default;
-    }
+  // Apply declared TypeBox defaults (top-level and nested) for absent keys.
+  const withDefaults = Value.Default(
+    Type.Object(schema as Record<string, TSchema>, { additionalProperties: true }),
+    resolved,
+  ) as Record<string, WorkflowSerializableValue>;
+  for (const [key, value] of Object.entries(withDefaults)) {
+    if (value !== undefined) resolved[key] = value;
   }
 
   for (const [key, schemaDef] of Object.entries(schema)) {
-    if (schemaDef.required === true && resolved[key] === undefined) {
-      throw new TypeError(`pi-workflows: required input "${key}" not provided`);
+    if (schemaIsRequired(schemaDef) && resolved[key] === undefined) {
+      throw new TypeError(`atomic-workflows: required input "${key}" not provided`);
     }
   }
 
@@ -198,7 +233,10 @@ function resolveInputConcurrency(
   schema: Readonly<Record<string, WorkflowInputSchema>>,
   resolvedInputs: ResolvedInputs,
 ): number | undefined {
-  if (schema["max_concurrency"]?.type !== "number") return undefined;
+  const concurrencySchema = schema["max_concurrency"];
+  if (concurrencySchema === undefined || schemaFieldKind(concurrencySchema) !== "number") {
+    return undefined;
+  }
 
   const value = resolvedInputs["max_concurrency"];
   if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return undefined;
@@ -287,12 +325,12 @@ function promptCallsiteHash(): string {
 function hilAbortError(signal: AbortSignal): Error {
   return signal.reason instanceof Error
     ? signal.reason
-    : new Error("pi-workflows: HIL aborted");
+    : new Error("atomic-workflows: HIL aborted");
 }
 
 function makeUnavailableUIContext(): WorkflowUIContext {
   const msg = (primitive: string): string =>
-    `pi-workflows: HIL ctx.ui.${primitive} is unavailable because pi runtime did not provide a UI adapter`;
+    `atomic-workflows: HIL ctx.ui.${primitive} is unavailable because Atomic runtime did not provide a UI adapter`;
   return {
     input: () => Promise.reject(new Error(msg("input"))),
     confirm: () => Promise.reject(new Error(msg("confirm"))),
@@ -434,8 +472,9 @@ export async function askReadinessViaStageBroker(
   // Expose a headless-answer adapter for the gate so it can be answered
   // programmatically (e.g. `workflow send`) without a TUI host. The gate
   // question params are known statically here.
+  const gatePromptId = `readiness-gate-${stageId}-${crypto.randomUUID()}`;
   const gateAdapter = buildStagePromptAdapter(
-    `readiness-gate-${stageId}`,
+    gatePromptId,
     "readiness_gate",
     READINESS_GATE_QUESTION_PARAMS,
     Date.now(),
@@ -443,7 +482,7 @@ export async function askReadinessViaStageBroker(
   if (gateAdapter) stageUiBroker.provideStagePrompt(runId, stageId, gateAdapter);
   try {
     const result = await execute(
-      `readiness-gate-${stageId}`,
+      gatePromptId,
       READINESS_GATE_QUESTION_PARAMS as Parameters<typeof execute>[1],
       signal,
       undefined,
@@ -499,7 +538,7 @@ function applyTaskContext(prompt: string, previous: WorkflowTaskOptions["previou
 function taskPrompt(options: WorkflowTaskOptions): string {
   const prompt = options.prompt ?? options.task;
   if (prompt === undefined) {
-    throw new Error("pi-workflows: ctx.task requires options.prompt or options.task");
+    throw new Error("atomic-workflows: ctx.task requires options.prompt or options.task");
   }
   return prompt;
 }
@@ -819,7 +858,7 @@ async function mapParallelSteps<T>(
   if (failures.length > 0) {
     throw new AggregateError(
       failures.map((failure) => failure.error),
-      `pi-workflows: ${failures.length} parallel ${failures.length === 1 ? "step" : "steps"} failed`,
+      `atomic-workflows: ${failures.length} parallel ${failures.length === 1 ? "step" : "steps"} failed`,
     );
   }
 
@@ -831,7 +870,7 @@ function expandedParallelTasks(tasks: readonly WorkflowDirectTaskItem[]): Workfl
   for (const task of tasks) {
     const count = task.count ?? 1;
     if (!Number.isInteger(count) || count < 1) {
-      throw new Error(`pi-workflows: direct task "${task.name}" count must be a positive integer`);
+      throw new Error(`atomic-workflows: direct task "${task.name}" count must be a positive integer`);
     }
     for (let index = 0; index < count; index += 1) {
       expanded.push(count === 1 ? task : {
@@ -933,7 +972,7 @@ function prepareDirectWorktrees(
   }
 
   if (typeof options.gitWorktreeDir === "string" || tasks.some((task) => typeof task.gitWorktreeDir === "string")) {
-    throw new Error("pi-workflows: worktree and gitWorktreeDir are mutually exclusive; use gitWorktreeDir for a reusable worktree or worktree:true for temporary isolated worktrees.");
+    throw new Error("atomic-workflows: worktree and gitWorktreeDir are mutually exclusive; use gitWorktreeDir for a reusable worktree or worktree:true for temporary isolated worktrees.");
   }
 
   const sharedCwd = resolveSharedDirectWorktreeCwd(tasks);
@@ -1088,13 +1127,27 @@ function workflowDetailsFromRun(
   };
 }
 
-const EMPTY_WORKFLOW_GRAPH_ERROR_MESSAGE = "Workflow run completed without creating any workflow stages. Create at least one stage with ctx.stage(), ctx.task(), ctx.chain(), or ctx.parallel().";
+const EMPTY_WORKFLOW_GRAPH_ERROR_MESSAGE = "Workflow run completed without creating any workflow stages. Create at least one stage with ctx.stage(), ctx.task(), ctx.chain(), ctx.parallel(), or ctx.workflow().";
 
 function assertWorkflowCreatedStage(runSnapshot: RunSnapshot): void {
   if (runSnapshot.stages.length > 0) return;
   throw new Error(EMPTY_WORKFLOW_GRAPH_ERROR_MESSAGE);
 }
 
+// Direct (task/parallel/chain) execution synthesizes ephemeral workflows that
+// expose tool-parity outputs. They are declared explicitly like any other
+// workflow so the fully-explicit output contract holds on the direct path too.
+// `unknown` accepts any serializable value, and every key is optional because a
+// given direct mode only returns the subset it produces (e.g. `count` for chain/
+// parallel, `text` for single task, `worktreeSummary` only with worktrees).
+const DIRECT_WORKFLOW_OUTPUTS: Readonly<Record<string, WorkflowOutputSchema>> = Object.freeze({
+  results: Type.Optional(Type.Unknown()),
+  text: Type.Optional(Type.Unknown()),
+  count: Type.Optional(Type.Unknown()),
+  artifacts: Type.Optional(Type.Unknown()),
+  worktreeSummary: Type.Optional(Type.Unknown()),
+});
+
 function defineDirectWorkflow(
   name: string,
   runFn: WorkflowDefinition["run"],
@@ -1105,6 +1158,7 @@ function defineDirectWorkflow(
     normalizedName: name,
     description: "Direct workflow execution",
     inputs: Object.freeze({}),
+    outputs: DIRECT_WORKFLOW_OUTPUTS,
     run: runFn,
   });
 }
@@ -1337,7 +1391,7 @@ function appendRunEndWhenRecorded(
   payload: {
     readonly runId: string;
     readonly status: RunStatus;
-    readonly result?: Record<string, unknown>;
+    readonly result?: WorkflowOutputValues;
     readonly error?: string;
     readonly failureKind?: WorkflowFailureKind;
     readonly failureMessage?: string;
@@ -1419,7 +1473,7 @@ interface ContinuationReplayInput {
   readonly replayKey: string;
   readonly parentIds: readonly string[];
   readonly stageId: string;
-  readonly kind: "stage" | "prompt";
+  readonly kind: "stage" | "prompt" | "workflow";
 }
 
 interface ContinuationReplayIndex {
@@ -1450,7 +1504,7 @@ function createContinuationReplayIndex(continuation: RunContinuationOpts | undef
   }
   const resumeStage = continuation.source.stages.find((stage) => stage.id === continuation.resumeFromStageId);
   if (resumeStage === undefined) {
-    throw new Error(`pi-workflows: insufficient_state: resume stage ${continuation.resumeFromStageId} was not found in source run ${continuation.source.id}`);
+    throw new Error(`atomic-workflows: insufficient_state: resume stage ${continuation.resumeFromStageId} was not found in source run ${continuation.source.id}`);
   }
 
   const stagesByReplayIdentity = new Map<string, StageSnapshot[]>();
@@ -1472,7 +1526,7 @@ function createContinuationReplayIndex(continuation: RunContinuationOpts | undef
   const replayablePromptContinuationStageIds = new Set<string>();
 
   const failTopology = (displayName: string, replayKey: string, reason: "mismatch" | "ambiguous"): never => {
-    throw new Error(`pi-workflows: insufficient_state: replay topology ${reason} for stage "${displayName}" (replayKey "${replayKey}") in source run ${continuation.source.id}`);
+    throw new Error(`atomic-workflows: insufficient_state: replay topology ${reason} for stage "${displayName}" (replayKey "${replayKey}") in source run ${continuation.source.id}`);
   };
 
   const translateSourceParents = (source: StageSnapshot): string[] | undefined => {
@@ -1618,15 +1672,197 @@ function nextEventLoopTurn(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));
 }
 
-export async function run<TInputs extends Record<string, unknown>>(
+function formatValidationErrors(errors: readonly ValidationError[]): string {
+  return errors.map((error) => `  - ${error.key}: ${error.reason}`).join("\n");
+}
+
+export function resolveAndValidateInputs(
+  schema: Readonly<Record<string, WorkflowInputSchema>>,
+  provided: Readonly<Record<string, unknown>>,
+  scope: string,
+): ResolvedInputs {
+  const resolved = resolveInputs(schema, provided);
+  const errors = validateInputs(schema, resolved);
+  if (errors.length > 0) {
+    throw new TypeError(
+      `atomic-workflows: invalid inputs for ${scope}:\n${formatValidationErrors(errors)}`,
+    );
+  }
+  return resolved;
+}
+
+function hasOwnWorkflowOutput(record: WorkflowOutputValues | Readonly<Record<string, WorkflowOutputSchema>>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+// Workflow outputs are fully explicit: a workflow exposes exactly the outputs it
+// declares with `.output(...)`. There is no implicit `result` fallback, and a
+// `.run()` return that contains a key the workflow did not declare is an error,
+// so authors cannot silently leak undeclared values across a workflow boundary.
+function assertWorkflowOutputsExplicit(
+  scope: string,
+  sourceOutput: WorkflowOutputValues,
+  declarations: Readonly<Record<string, WorkflowOutputSchema>>,
+  missingOutputSuffix = "",
+): void {
+  for (const key of Object.keys(sourceOutput)) {
+    if (!hasOwnWorkflowOutput(declarations, key)) {
+      throw new Error(
+        `atomic-workflows: ${scope} returned undeclared output "${key}"; declare it with .output("${key}", Type....) or remove it from the .run() return`,
+      );
+    }
+  }
+  for (const [key, schema] of Object.entries(declarations)) {
+    if (!(key in sourceOutput)) {
+      if (schemaIsRequired(schema)) {
+        throw new Error(
+          `atomic-workflows: ${scope} missing output "${key}"${missingOutputSuffix}`,
+        );
+      }
+      continue;
+    }
+    const value = sourceOutput[key];
+    const kind = schemaFieldKind(schema);
+    if (!Value.Check(schema, value)) {
+      const choices = schemaChoices(schema);
+      if (kind === "select" && choices !== undefined && typeof value === "string") {
+        throw new Error(
+          `atomic-workflows: ${scope} output "${key}" must be one of [${choices.join(", ")}], got ${JSON.stringify(value)}`,
+        );
+      }
+      throw new Error(
+        `atomic-workflows: ${scope} output "${key}" expected ${kind}, got ${workflowSerializableTypeName(value)}`,
+      );
+    }
+    const serializableError = workflowSerializableValidationError(
+      value,
+      `${scope} output "${key}"`,
+    );
+    if (serializableError !== undefined) {
+      throw new Error(`atomic-workflows: ${serializableError}`);
+    }
+  }
+}
+
+function normalizeWorkflowRunOutput(
+  workflowName: string,
+  rawOutput: unknown,
+): WorkflowOutputValues | undefined {
+  if (rawOutput === undefined) return undefined;
+  // Drop top-level keys explicitly set to `undefined` so conditional outputs
+  // (e.g. `{ note: cond ? value : undefined }`) satisfy the JSON-serializable
+  // contract instead of failing validation; selectWorkflowOutputs strips the
+  // same way at the child boundary, keeping both paths consistent.
+  const normalized =
+    rawOutput !== null && typeof rawOutput === "object" && !Array.isArray(rawOutput)
+      ? Object.fromEntries(
+          Object.entries(rawOutput as Record<string, unknown>).filter(([, v]) => v !== undefined),
+        )
+      : rawOutput;
+  assertWorkflowSerializableObject(normalized, `workflow "${workflowName}" .run() return`);
+  return normalized;
+}
+
+function assertWorkflowRunOutputs(
+  workflowName: string,
+  result: WorkflowOutputValues | undefined,
+  declaredOutputs: Readonly<Record<string, WorkflowOutputSchema>> | undefined,
+): void {
+  assertWorkflowOutputsExplicit(
+    `workflow "${workflowName}"`,
+    result ?? {},
+    declaredOutputs ?? {},
+  );
+}
+
+function selectWorkflowOutputs(
+  child: WorkflowDefinition,
+  rawOutput: WorkflowOutputValues | undefined,
+): WorkflowOutputValues {
+  const declarations = child.outputs ?? {};
+  const sourceOutput = rawOutput ?? {};
+  // The child run already validated its return against these declared outputs
+  // (assertWorkflowRunOutputs) before it could complete, so undeclared keys are
+  // impossible here and a second assertWorkflowOutputsExplicit pass could never
+  // fire. Just project the declared outputs the child returned. (An undeclared
+  // key fails the child run itself; the parent surfaces that as a wrapped
+  // "child workflow ... failed" error.)
+  const selected: Record<string, WorkflowSerializableValue> = {};
+  for (const key of Object.keys(declarations)) {
+    const value = sourceOutput[key];
+    if (value !== undefined) selected[key] = value;
+  }
+
+  return selected;
+}
+
+function cloneWorkflowChildValue<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function workflowChildSerializationMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function isWorkflowDefinition(value: unknown): value is WorkflowDefinition {
+  if (value === null || typeof value !== "object") return false;
+  const record = value as Partial<WorkflowDefinition>;
+  return record.__piWorkflow === true &&
+    typeof record.name === "string" && record.name.trim().length > 0 &&
+    typeof record.normalizedName === "string" && record.normalizedName.trim().length > 0 &&
+    typeof record.run === "function" &&
+    // Compiled definitions always set `inputs: {}`; guard it so a handcrafted
+    // object that passes the sentinel still fails here with the clear "requires
+    // a compiled workflow definition" error rather than crashing later inside
+    // resolveAndValidateInputs(child.inputs, ...) on `Object.entries(undefined)`.
+    typeof record.inputs === "object" && record.inputs !== null;
+}
+
+function cloneWorkflowChildReplaySnapshot(snapshot: WorkflowChildReplaySnapshot): WorkflowChildReplaySnapshot {
+  return {
+    alias: snapshot.alias,
+    workflow: snapshot.workflow,
+    runId: snapshot.runId,
+    status: snapshot.status,
+    outputs: cloneWorkflowChildValue(snapshot.outputs),
+  };
+}
+
+function workflowChildReplaySnapshot(
+  alias: string,
+  childResult: WorkflowChildResult,
+): WorkflowChildReplaySnapshot {
+  const outputs: Record<string, WorkflowSerializableValue> = {};
+  for (const [key, value] of Object.entries(childResult.outputs)) {
+    if (value === undefined) continue;
+    try {
+      outputs[key] = cloneWorkflowChildValue(value);
+    } catch (err) {
+      throw new Error(
+        `atomic-workflows: child workflow "${alias}" (${childResult.workflow}) exposed output "${key}" is not serializable for continuation replay: ${workflowChildSerializationMessage(err)}`,
+        { cause: err },
+      );
+    }
+  }
+
+  return {
+    alias,
+    workflow: childResult.workflow,
+    runId: childResult.runId,
+    status: childResult.status,
+    outputs,
+  };
+}
+
+export async function run<TInputs extends WorkflowInputValues>(
   def: WorkflowDefinition<TInputs>,
-  inputs: Record<string, unknown>,
+  inputs: Readonly<Record<string, unknown>>,
   opts: RunOpts = {},
 ): Promise<RunResult> {
   const activeStore = opts.store ?? defaultStore;
   const adapters = opts.adapters ?? {};
   if (opts.usePromptNodesForUi === true && opts.ui !== undefined) {
-    console.warn("pi-workflows: usePromptNodesForUi ignores the provided RunOpts.ui adapter");
+    console.warn("atomic-workflows: usePromptNodesForUi ignores the provided RunOpts.ui adapter");
   }
 
   // 0. maxDepth guard — reject before any store/persistence side effects.
@@ -1637,13 +1873,17 @@ export async function run<TInputs extends Record<string, unknown>>(
     return {
       runId: opts.runId ?? crypto.randomUUID(),
       status: "failed",
-      error: `pi-workflows: maxDepth exceeded (max ${max})`,
+      error: `atomic-workflows: maxDepth exceeded (max ${max})`,
       stages: [],
     };
   }
 
   // 1. Resolve + validate inputs
-  const resolvedInputs = resolveInputs(def.inputs, inputs);
+  const resolvedInputs = resolveAndValidateInputs(
+    def.inputs,
+    inputs,
+    `workflow "${def.name}"`,
+  );
 
   // 2. Generate runId (or use pre-allocated seam from caller)
   const runId = opts.runId ?? crypto.randomUUID();
@@ -1668,6 +1908,11 @@ export async function run<TInputs extends Record<string, unknown>>(
     status: "running",
     stages: [],
     startedAt: Date.now(),
+    ...(opts.parentRun !== undefined ? {
+      parentRunId: opts.parentRun.runId,
+      parentStageId: opts.parentRun.stageId,
+      rootRunId: opts.parentRun.rootRunId,
+    } : {}),
     ...(opts.continuation !== undefined ? {
       resumedFromRunId: opts.continuation.source.id,
       resumeFromStageId: opts.continuation.resumeFromStageId,
@@ -1692,6 +1937,9 @@ export async function run<TInputs extends Record<string, unknown>>(
       runId,
       name: def.name,
       inputs: resolvedInputs,
+      ...(runSnapshot.parentRunId !== undefined ? { parentRunId: runSnapshot.parentRunId } : {}),
+      ...(runSnapshot.parentStageId !== undefined ? { parentStageId: runSnapshot.parentStageId } : {}),
+      ...(runSnapshot.rootRunId !== undefined ? { rootRunId: runSnapshot.rootRunId } : {}),
       ...(runSnapshot.resumedFromRunId !== undefined ? { resumedFromRunId: runSnapshot.resumedFromRunId } : {}),
       ...(runSnapshot.resumeFromStageId !== undefined ? { resumeFromStageId: runSnapshot.resumeFromStageId } : {}),
       ts: runSnapshot.startedAt,
@@ -1858,10 +2106,162 @@ export async function run<TInputs extends Record<string, unknown>>(
 
   ownController.signal.addEventListener(
     "abort",
-    () => rejectReleaseBarriers(ownController.signal.reason ?? new Error("pi-workflows: run aborted")),
+    () => rejectReleaseBarriers(ownController.signal.reason ?? new Error("atomic-workflows: run aborted")),
     { once: true },
   );
 
+  interface WorkflowBoundaryStage {
+    readonly id: string;
+    readonly replayedChild?: WorkflowChildResult;
+    finalizeReplay(): void;
+    linkChildRun(ref: WorkflowChildRunRef): void;
+    complete(summary: string, workflowChild: WorkflowChildReplaySnapshot): void;
+    fail(error: unknown): void;
+  }
+
+  const workflowChildResultFromReplay = (snapshot: WorkflowChildReplaySnapshot): WorkflowChildResult => ({
+    workflow: snapshot.workflow,
+    runId: snapshot.runId,
+    status: snapshot.status,
+    outputs: cloneWorkflowChildValue(snapshot.outputs),
+  });
+
+  const workflowBoundaryReplayCounts = new Map<string, number>();
+  const nextWorkflowBoundaryReplayKey = (name: string): string => {
+    const next = (workflowBoundaryReplayCounts.get(name) ?? 0) + 1;
+    workflowBoundaryReplayCounts.set(name, next);
+    return `workflow:${name}:${next}`;
+  };
+
+  const startWorkflowBoundaryStage = (name: string, replayKey: string): WorkflowBoundaryStage => {
+    const stageId = crypto.randomUUID();
+    const provisionalParentIds = tracker.onSpawn(stageId, name);
+    const replayDecision = replayIndex.decide({
+      displayName: name,
+      replayKey,
+      parentIds: provisionalParentIds,
+      stageId,
+      kind: "workflow",
+    });
+    const parentIds = replayDecision.parentIds;
+    if (!sameStringSet(parentIds, provisionalParentIds)) {
+      tracker.replaceParents(stageId, parentIds);
+    }
+    const replaySource = replayDecision.source;
+    const replayChildSnapshot = replayDecision.kind === "replay" ? replayDecision.source.workflowChild : undefined;
+    const replayedChild = replayChildSnapshot !== undefined
+      ? workflowChildResultFromReplay(replayChildSnapshot)
+      : undefined;
+    const startedAt = Date.now();
+    const stageSnapshot: StageSnapshot = {
+      id: stageId,
+      name,
+      replayKey,
+      status: replayedChild !== undefined ? "completed" : "running",
+      parentIds: Object.freeze([...parentIds]),
+      startedAt,
+      toolEvents: [],
+      attachable: false,
+      ...(replaySource !== undefined ? {
+        replayedFromStageId: replaySource.id,
+        replayed: replayedChild !== undefined,
+      } : {}),
+      ...(replayedChild !== undefined && replayChildSnapshot !== undefined ? {
+        endedAt: startedAt,
+        durationMs: 0,
+        ...(replayDecision.kind === "replay" && replayDecision.source.result !== undefined ? { result: replayDecision.source.result } : {}),
+        workflowChild: cloneWorkflowChildReplaySnapshot(replayChildSnapshot),
+      } : {}),
+    };
+    let finalized = false;
+
+    const appendStageStartOnce = (): void => {
+      if (!opts.persistence) return;
+      appendStageStart(opts.persistence, {
+        runId,
+        stageId,
+        name,
+        parentIds: stageSnapshot.parentIds,
+        ...stageReplayFields(stageSnapshot),
+        ts: startedAt,
+      });
+    };
+
+    const appendStageEndForSnapshot = (): void => {
+      if (!opts.persistence) return;
+      appendStageEnd(opts.persistence, {
+        runId,
+        stageId,
+        status: stageSnapshot.status,
+        durationMs: stageSnapshot.durationMs,
+        ...(stageSnapshot.error !== undefined ? { error: stageSnapshot.error } : {}),
+        ...(stageSnapshot.failureKind !== undefined ? { failureKind: stageSnapshot.failureKind } : {}),
+        ...(stageSnapshot.failureMessage !== undefined ? { failureMessage: stageSnapshot.failureMessage } : {}),
+        ...(stageSnapshot.result !== undefined && stageSnapshot.status === "completed" ? { summary: stageSnapshot.result } : {}),
+        ...stageReplayFields(stageSnapshot),
+        ...(stageSnapshot.workflowChild !== undefined ? { workflowChild: stageSnapshot.workflowChild } : {}),
+      });
+    };
+
+    const finalize = (
+      status: "completed" | "failed",
+      summaryOrError: string,
+      workflowChild?: WorkflowChildReplaySnapshot,
+      failureError?: unknown,
+    ): void => {
+      if (finalized) return;
+      finalized = true;
+      stageSnapshot.status = status;
+      if (status === "completed") {
+        stageSnapshot.result = summaryOrError;
+        if (workflowChild !== undefined) stageSnapshot.workflowChild = workflowChild;
+      } else {
+        const failure = classifyWorkflowFailure(failureError);
+        stageSnapshot.error = failure.userMessage;
+        stageSnapshot.failureKind = failure.kind;
+        stageSnapshot.failureMessage = failure.message;
+      }
+      stageSnapshot.endedAt = Date.now();
+      stageSnapshot.durationMs = elapsedStageMs(stageSnapshot, stageSnapshot.endedAt);
+      activeStore.recordStageEnd(runId, stageSnapshot);
+      opts.onStageEnd?.(runId, stageSnapshot);
+      appendStageEndForSnapshot();
+      tracker.onSettle(stageId);
+    };
+
+    activeStore.recordStageStart(runId, stageSnapshot);
+    opts.onStageStart?.(runId, stageSnapshot);
+    appendStageStartOnce();
+
+    const finalizeReplay = (): void => {
+      if (replayedChild === undefined || finalized) return;
+      finalized = true;
+      activeStore.recordStageEnd(runId, stageSnapshot);
+      opts.onStageEnd?.(runId, stageSnapshot);
+      appendStageEndForSnapshot();
+      tracker.onSettle(stageId);
+    };
+
+    const linkChildRun = (ref: WorkflowChildRunRef): void => {
+      if (finalized) return;
+      stageSnapshot.workflowChildRun = { ...ref };
+      activeStore.recordStageWorkflowChildRun(runId, stageId, ref);
+    };
+
+    return {
+      id: stageId,
+      ...(replayedChild !== undefined ? { replayedChild } : {}),
+      finalizeReplay,
+      linkChildRun,
+      complete(summary: string, workflowChild: WorkflowChildReplaySnapshot): void {
+        finalize("completed", summary, workflowChild);
+      },
+      fail(error: unknown): void {
+        finalize("failed", error instanceof Error ? error.message : String(error), undefined, error);
+      },
+    };
+  };
+
   const buildPromptNodeUiAdapter = (): WorkflowUIAdapter => {
     const ask = async (descriptor: PromptDescriptor): Promise<unknown> => {
       if (ownController.signal.aborted) {
@@ -2020,7 +2420,7 @@ export async function run<TInputs extends Record<string, unknown>>(
       },
       async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
         if (options.length === 0) {
-          throw new Error("pi-workflows: ctx.ui.select requires at least one option");
+          throw new Error("atomic-workflows: ctx.ui.select requires at least one option");
         }
         const response = await ask({ kind: "select", message, choices: options });
         if (typeof response === "string" && (options as readonly string[]).includes(response)) {
@@ -2139,7 +2539,7 @@ export async function run<TInputs extends Record<string, unknown>>(
           return replayResult;
         };
         const rejectReplayMutation = (action: string): never => {
-          throw new Error(`pi-workflows: replayed stage "${name}" cannot ${action}`);
+          throw new Error(`atomic-workflows: replayed stage "${name}" cannot ${action}`);
         };
         const replayContext: InternalStageContext = {
           name,
@@ -2175,6 +2575,7 @@ export async function run<TInputs extends Record<string, unknown>>(
           __pendingMessageCount: () => 0,
           __modelFallbackMeta: () => ({
             ...(replaySource.model !== undefined ? { model: replaySource.model } : {}),
+            ...(replaySource.fastMode === true ? { fastMode: replaySource.fastMode } : {}),
             ...(replaySource.attemptedModels !== undefined ? { attemptedModels: replaySource.attemptedModels } : {}),
             ...(replaySource.modelAttempts !== undefined ? { modelAttempts: replaySource.modelAttempts } : {}),
           }),
@@ -2188,6 +2589,16 @@ export async function run<TInputs extends Record<string, unknown>>(
       // d. Create inner AgentSession-like StageContext (raw, without lifecycle wrapping).
       //    Must come before the registry registration because the handle
       //    delegates to it for every operation.
+      const applyModelFallbackMeta = (meta: ReturnType<InternalStageContext["__modelFallbackMeta"]>): void => {
+        if (meta.model !== undefined) stageSnapshot.model = meta.model;
+        if (meta.fastMode !== undefined) {
+          if (meta.fastMode) stageSnapshot.fastMode = true;
+          else delete stageSnapshot.fastMode;
+        }
+        if (meta.attemptedModels !== undefined) stageSnapshot.attemptedModels = meta.attemptedModels;
+        if (meta.modelAttempts !== undefined) stageSnapshot.modelAttempts = meta.modelAttempts;
+      };
+
       const innerCtx: InternalStageContext = createStageContext({
         stageId,
         stageName: name,
@@ -2196,6 +2607,13 @@ export async function run<TInputs extends Record<string, unknown>>(
         signal: ownController.signal,
         stageOptions: options,
         models: opts.models,
+        executionMode: opts.executionMode,
+        onModelFallbackMetaChange(meta) {
+          applyModelFallbackMeta(meta);
+          if (stageSnapshot.status === "running") {
+            activeStore.recordStageStart(runId, stageSnapshot);
+          }
+        },
       });
       const activeAskUserQuestionCalls = new Set<string>();
       let activeAskUserQuestionAnonymousCalls = 0;
@@ -2213,11 +2631,9 @@ export async function run<TInputs extends Record<string, unknown>>(
           askUserQuestionObservedThisTurn = true;
           if (toolEvent.callId !== undefined) activeAskUserQuestionCalls.add(toolEvent.callId);
           else activeAskUserQuestionAnonymousCalls += 1;
-          activeStore.recordStageAwaitingInput(runId, stageId, true);
-          // Expose a headless-answer adapter so the prompt can be answered
-          // programmatically (e.g. `workflow send`) without a TUI host. The
-          // (runId, stageId) key joins this to the broker request the tool's
-          // ctx.ui.custom() call raises.
+          // Expose a headless-answer adapter before marking the stage awaiting
+          // input so the main-chat steering notice can include the actual
+          // structured question instead of a promptless placeholder.
           const adapter = buildStagePromptAdapter(
             toolEvent.callId ?? `ask-user-question-${stageId}`,
             "ask_user_question",
@@ -2225,6 +2641,7 @@ export async function run<TInputs extends Record<string, unknown>>(
             Date.now(),
           );
           if (adapter) stageUiBroker.provideStagePrompt(runId, stageId, adapter);
+          activeStore.recordStageAwaitingInput(runId, stageId, true);
           return;
         }
 
@@ -2352,12 +2769,14 @@ export async function run<TInputs extends Record<string, unknown>>(
         stageSnapshot.endedAt = Date.now();
         stageSnapshot.durationMs = elapsedStageMs(stageSnapshot, stageSnapshot.endedAt);
 
-        const finalModelMeta = innerCtx.__modelFallbackMeta();
-        if (finalModelMeta.model !== undefined) stageSnapshot.model = finalModelMeta.model;
-        if (finalModelMeta.attemptedModels !== undefined) stageSnapshot.attemptedModels = finalModelMeta.attemptedModels;
-        if (finalModelMeta.modelAttempts !== undefined) stageSnapshot.modelAttempts = finalModelMeta.modelAttempts;
+        applyModelFallbackMeta(innerCtx.__modelFallbackMeta());
 
         activeStore.recordStageEnd(runId, stageSnapshot);
+        stageUiBroker.cancelStagePrompt(
+          runId,
+          stageId,
+          new Error(`atomic-workflows: stage ${stageId} completed with pending custom UI`),
+        );
         opts.onStageEnd?.(runId, stageSnapshot);
 
         if (opts.persistence) {
@@ -2387,7 +2806,7 @@ export async function run<TInputs extends Record<string, unknown>>(
         stageSnapshot.skippedReason = "fail-fast";
       };
       const parallelFailFastError = (): unknown =>
-        stageFailFastScope?.firstFailure ?? new Error("pi-workflows: skipped after parallel fail-fast");
+        stageFailFastScope?.firstFailure ?? new Error("atomic-workflows: skipped after parallel fail-fast");
       const skipForParallelFailFast = (): void => {
         if (isTerminalStage(stageSnapshot)) return;
         markSkippedForParallelFailFast();
@@ -2453,7 +2872,7 @@ export async function run<TInputs extends Record<string, unknown>>(
         }
       };
 
-      const runTrackedStageCall = async (call: () => Promise<string>): Promise<string> => {
+      const runTrackedStageCall = async (call: () => Promise<string>, eagerSession = false): Promise<string> => {
         await waitForStageRelease();
         if (stageFinalized) {
           throw parallelFailFastError();
@@ -2481,6 +2900,33 @@ export async function run<TInputs extends Record<string, unknown>>(
         }
         stageSnapshot.status = "running";
         stageSnapshot.startedAt = Date.now();
+        const hasExplicitFastModeCandidate = async (): Promise<boolean> => {
+          const rawCandidate = isCodexFastModeCandidateModelId(workflowModelId(options?.model))
+            || (Array.isArray(options?.fallbackModels) && options.fallbackModels.some((candidate) => isCodexFastModeCandidateModelId(workflowModelId(candidate))));
+          if (rawCandidate) return true;
+          try {
+            const candidates = await buildModelCandidatesFromCatalog({
+              primaryModel: options?.model,
+              fallbackModels: options?.fallbackModels,
+              catalog: opts.models,
+            });
+            return candidates.some((candidate) => isCodexFastModeCandidateModelId(candidate.id));
+          } catch {
+            return false;
+          }
+        };
+        const hasNoExplicitModelConfig = options?.model === undefined && options?.fallbackModels === undefined;
+        const promptAdapterHandlesInitialPrompt = adapters.prompt !== undefined;
+        if (eagerSession && !promptAdapterHandlesInitialPrompt && (hasNoExplicitModelConfig || await hasExplicitFastModeCandidate())) {
+          try {
+            await innerCtx.__ensureSession();
+          } catch (err) {
+            if (!(err instanceof Error && err.message.includes("prompt adapter not configured"))) {
+              throw err;
+            }
+          }
+        }
+        applyModelFallbackMeta(innerCtx.__modelFallbackMeta());
         activeStore.recordStageStart(runId, stageSnapshot);
 
         // Persistence: append stage.start entry
@@ -2556,10 +3002,7 @@ export async function run<TInputs extends Record<string, unknown>>(
             if (meta.sessionId !== undefined || meta.sessionFile !== undefined) {
               activeStore.recordStageSession(runId, stageId, meta);
             }
-            const modelMeta = innerCtx.__modelFallbackMeta();
-            if (modelMeta.model !== undefined) stageSnapshot.model = modelMeta.model;
-            if (modelMeta.attemptedModels !== undefined) stageSnapshot.attemptedModels = modelMeta.attemptedModels;
-            if (modelMeta.modelAttempts !== undefined) stageSnapshot.modelAttempts = modelMeta.modelAttempts;
+            applyModelFallbackMeta(innerCtx.__modelFallbackMeta());
           }
           if (stageFailFastScope?.failed === true && stageFailFastScope.activeStages.has(stageId)) {
             markSkippedForParallelFailFast();
@@ -2626,7 +3069,7 @@ export async function run<TInputs extends Record<string, unknown>>(
 
       const stageContext: StageContext & Pick<InternalStageContext, "__modelFallbackMeta"> = {
         name: innerCtx.name,
-        prompt: (text, promptOptions) => runTrackedStageCall(() => innerCtx.prompt(text, promptOptions)),
+        prompt: (text, promptOptions) => runTrackedStageCall(() => innerCtx.prompt(text, promptOptions), true),
         complete: (text, completeOptions) => runTrackedStageCall(() => innerCtx.complete(text, completeOptions)),
         steer: (text) => innerCtx.steer(text),
         followUp: (text) => innerCtx.followUp(text),
@@ -2706,6 +3149,7 @@ export async function run<TInputs extends Record<string, unknown>>(
           ...(sessionId !== undefined ? { sessionId } : {}),
           ...(stage.sessionFile !== undefined ? { sessionFile: stage.sessionFile } : {}),
           ...(stageMeta.model !== undefined ? { model: stageMeta.model } : {}),
+          ...(stageMeta.fastMode === true ? { fastMode: stageMeta.fastMode } : {}),
           ...(stageMeta.attemptedModels !== undefined ? { attemptedModels: stageMeta.attemptedModels } : {}),
           ...(stageMeta.modelAttempts !== undefined ? { modelAttempts: stageMeta.modelAttempts } : {}),
           ...(stageMeta.warnings !== undefined ? { warnings: stageMeta.warnings } : {}),
@@ -2768,6 +3212,131 @@ export async function run<TInputs extends Record<string, unknown>>(
         }
       });
     },
+
+    async workflow<TChildInputs extends WorkflowInputValues, TChildOutputs extends WorkflowOutputValues>(
+      child: WorkflowDefinition<TChildInputs, TChildOutputs>,
+      options: WorkflowRunChildOptions<TChildInputs> = {},
+    ): Promise<WorkflowChildResult<TChildOutputs>> {
+      // The executor operates on type-erased definitions at runtime; the child's
+      // declared output contract is validated dynamically by the child run and
+      // selectWorkflowOutputs, so the typed result is reconstructed via casts.
+      if (!isWorkflowDefinition(child)) {
+        throw new Error("atomic-workflows: ctx.workflow(definition) requires a compiled workflow definition");
+      }
+      const childName = child.normalizedName;
+      const boundaryName = options.stageName ?? `workflow:${childName}`;
+      const boundaryReplayKey = nextWorkflowBoundaryReplayKey(boundaryName);
+      const boundary = startWorkflowBoundaryStage(boundaryName, boundaryReplayKey);
+      if (boundary.replayedChild !== undefined) {
+        // Continuation replay returns the persisted child boundary exactly as
+        // written; input validation and output remapping are intentionally not
+        // re-run against edited workflow code for a completed child boundary.
+        // Defer settling by one microtask so concurrent replayed boundaries
+        // spawned in the same turn see the same frontier as the source run.
+        await Promise.resolve();
+        boundary.finalizeReplay();
+        return boundary.replayedChild as WorkflowChildResult<TChildOutputs>;
+      }
+
+      // Tracked so the finally can detach the parent-abort listener and release
+      // the pre-registered child controller on every exit path — including the
+      // maxDepth early return inside run(), which returns before run()'s own
+      // cleanup. Without this, sequential ctx.workflow(...) calls accumulate one
+      // parent-signal listener (and a leaked registry entry) per child.
+      let childRunId: string | undefined;
+      let detachParentAbort: (() => void) | undefined;
+      try {
+        const childInputs = resolveAndValidateInputs(
+          child.inputs,
+          options.inputs ?? {},
+          `child workflow "${childName}" (${child.name})`,
+        );
+
+        childRunId = crypto.randomUUID();
+        boundary.linkChildRun({
+          alias: childName,
+          workflow: child.normalizedName,
+          runId: childRunId,
+        });
+
+        const childController = new AbortController();
+        if (ownController.signal.aborted) {
+          childController.abort(ownController.signal.reason);
+        } else {
+          const onParentAbort = () => childController.abort(ownController.signal.reason);
+          ownController.signal.addEventListener("abort", onParentAbort, { once: true });
+          detachParentAbort = () =>
+            ownController.signal.removeEventListener("abort", onParentAbort);
+        }
+        // Pre-register the child controller under its own runId *before* run()
+        // so a kill targeting the child runId works even before the nested run
+        // would register itself. The nested run() sees opts.signal set and skips
+        // its own cancellation.register (avoiding a double-register on the same
+        // key) while still running its finally{} unregister(runId) cleanup, so
+        // both branches must agree on this key.
+        opts.cancellation?.register(childRunId, childController);
+
+        const {
+          runId: _parentRunId,
+          continuation: _parentContinuation,
+          deferWorkflowStart: _parentDeferWorkflowStart,
+          parentRun: _parentRun,
+          onRunStart: _parentOnRunStart,
+          onRunEnd: _parentOnRunEnd,
+          ...childBaseOpts
+        } = opts;
+        const childRun = await run(child, childInputs, {
+          ...childBaseOpts,
+          runId: childRunId,
+          cwd: resolveWorkflowCwd(),
+          depth: depth + 1,
+          ...(opts.registry !== undefined ? { registry: opts.registry } : {}),
+          parentRun: {
+            runId,
+            stageId: boundary.id,
+            rootRunId: opts.parentRun?.rootRunId ?? runId,
+          },
+          signal: childController.signal,
+          deferWorkflowStart: false,
+        });
+
+        if (childRun.status !== "completed") {
+          const failedChildStage = childRun.stages.find((stage) => stage.failureKind !== undefined);
+          throw new Error(
+            `atomic-workflows: child workflow "${childName}" (${child.name}) failed with status ${childRun.status}${childRun.error !== undefined ? `: ${childRun.error}` : ""}`,
+            {
+              cause: {
+                ...(failedChildStage?.failureKind !== undefined ? { code: failedChildStage.failureKind } : {}),
+                ...(failedChildStage?.failureMessage !== undefined ? { message: failedChildStage.failureMessage } : {}),
+              },
+            },
+          );
+        }
+
+        const outputs = selectWorkflowOutputs(child, childRun.result);
+        const childResult: WorkflowChildResult<TChildOutputs> = {
+          workflow: child.normalizedName,
+          runId: childRun.runId,
+          status: "completed",
+          outputs: outputs as TChildOutputs,
+        };
+        const workflowChild = workflowChildReplaySnapshot(childName, childResult);
+        const outputKeys = Object.keys(outputs);
+        boundary.complete(
+          `Workflow "${child.name}" completed (runId: ${childRun.runId}; outputs: ${outputKeys.length > 0 ? outputKeys.join(", ") : "(none)"})`,
+          workflowChild,
+        );
+        return childResult;
+      } catch (err) {
+        boundary.fail(err);
+        throw err;
+      } finally {
+        detachParentAbort?.();
+        // Idempotent with run()'s own finally on the normal path; required on
+        // the maxDepth early-return path where run() never reaches its cleanup.
+        if (childRunId !== undefined) opts.cancellation?.unregister(childRunId);
+      }
+    },
   };
 
   // 6. Call def.run(ctx)
@@ -2779,7 +3348,7 @@ export async function run<TInputs extends Record<string, unknown>>(
       }
     }
 
-    const result = await def.run(ctx);
+    const rawResult = await def.run(ctx);
 
     // Post-body abort check: if signal was aborted at any point before we record
     // completion, the run must be finalized as "killed", never "completed".
@@ -2787,6 +3356,9 @@ export async function run<TInputs extends Record<string, unknown>>(
       return finalizeKilled(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd);
     }
 
+    const result = normalizeWorkflowRunOutput(def.name, rawResult);
+    assertWorkflowRunOutputs(def.name, result, def.outputs);
+
     assertWorkflowCreatedStage(runSnapshot);
 
     const recorded = activeStore.recordRunEnd(runId, "completed", result);