@bastani/atomic 0.9.0-alpha.1 → 0.9.0-alpha.2

package/dist/builtin/workflows/src/runs/foreground/executor-child-workflow.ts

@@ -1,158 +1 @@
-import type {
-  WorkflowChildResult,
-  WorkflowDefinition,
-  WorkflowInputValues,
-  WorkflowOutputValues,
-  WorkflowRunChildOptions,
-} from "../../shared/types.js";
-import type { WorkflowChildRunRef } from "../../shared/store-types.js";
-import type { RunOpts, RunResult } from "./executor-types.js";
-import type { WorkflowExitManager } from "./executor-exit-manager.js";
-import type { WorkflowBoundaryStage } from "./executor-child-boundary.js";
-import { findWorkflowExitSignal, isWorkflowExitStatus, makeParentWorkflowExitAbortReason } from "./executor-abort.js";
-import { selectWorkflowOutputs } from "./executor-outputs.js";
-import { resolveAndValidateInputs } from "./executor-inputs.js";
-import {
-  isWorkflowDefinition,
-  workflowChildReplaySnapshot,
-  workflowDefinitionRequirementMessage,
-} from "./executor-child-helpers.js";
-
-export function createChildWorkflowRunner(input: {
-  readonly runId: string;
-  readonly depth: number;
-  readonly opts: RunOpts;
-  readonly exit: WorkflowExitManager;
-  readonly ownController: AbortController;
-  readonly resolveWorkflowCwd: () => string;
-  readonly nextWorkflowBoundaryReplayKey: (name: string) => string;
-  readonly startWorkflowBoundaryStage: (name: string, replayKey: string) => WorkflowBoundaryStage;
-  readonly runWorkflow: <TInputs extends WorkflowInputValues>(
-    def: WorkflowDefinition<TInputs>,
-    inputs: Readonly<Record<string, unknown>>,
-    opts?: RunOpts,
-  ) => Promise<RunResult>;
-}): <TChildInputs extends WorkflowInputValues, TChildOutputs extends WorkflowOutputValues>(
-  child: WorkflowDefinition<TChildInputs, TChildOutputs>,
-  options?: WorkflowRunChildOptions<TChildInputs>,
-) => Promise<WorkflowChildResult<TChildOutputs>> {
-  return async <TChildInputs extends WorkflowInputValues, TChildOutputs extends WorkflowOutputValues>(
-    child: WorkflowDefinition<TChildInputs, TChildOutputs>,
-    options: WorkflowRunChildOptions<TChildInputs> = {},
-  ): Promise<WorkflowChildResult<TChildOutputs>> => {
-    input.exit.throwIfWorkflowExitSelected();
-    if (!isWorkflowDefinition(child)) throw new Error(workflowDefinitionRequirementMessage("ctx.workflow(definition)", child));
-    const childName = child.normalizedName;
-    const boundaryName = options.stageName ?? `workflow:${childName}`;
-    const boundaryReplayKey = input.nextWorkflowBoundaryReplayKey(boundaryName);
-    const boundary = input.startWorkflowBoundaryStage(boundaryName, boundaryReplayKey);
-    let childRunId: string | undefined;
-    let detachParentAbort: (() => void) | undefined;
-    try {
-      if (boundary.replayedChild !== undefined) {
-        await Promise.resolve();
-        input.exit.throwIfWorkflowExitSelected();
-        boundary.finalizeReplay();
-        return boundary.replayedChild as WorkflowChildResult<TChildOutputs>;
-      }
-
-      const childInputs = resolveAndValidateInputs(child.inputs, options.inputs ?? {}, `child workflow "${childName}" (${child.name})`);
-      input.exit.throwIfWorkflowExitSelected();
-
-      childRunId = crypto.randomUUID();
-      const childController = new AbortController();
-      const childRef: WorkflowChildRunRef = { alias: childName, workflow: child.normalizedName, runId: childRunId };
-      boundary.linkChildRun(childRef, childController);
-
-      const abortChildFromParent = (): void => {
-        const parentExit = findWorkflowExitSignal(input.ownController.signal.reason, input.exit.exitScope);
-        childController.abort(parentExit !== undefined ? makeParentWorkflowExitAbortReason(parentExit.reason) : input.ownController.signal.reason);
-      };
-      if (input.ownController.signal.aborted) abortChildFromParent();
-      else {
-        input.ownController.signal.addEventListener("abort", abortChildFromParent, { once: true });
-        detachParentAbort = () => input.ownController.signal.removeEventListener("abort", abortChildFromParent);
-      }
-      input.exit.throwIfWorkflowExitSelected();
-      input.opts.cancellation?.register(childRunId, childController);
-      input.exit.throwIfWorkflowExitSelected();
-
-      const {
-        runId: _parentRunId,
-        continuation: _parentContinuation,
-        deferWorkflowStart: _parentDeferWorkflowStart,
-        parentRun: _parentRun,
-        onRunStart: _parentOnRunStart,
-        onRunEnd: _parentOnRunEnd,
-        ...childBaseOpts
-      } = input.opts;
-      const childRunPromise = input.runWorkflow(child, childInputs, {
-        ...childBaseOpts,
-        runId: childRunId,
-        cwd: input.resolveWorkflowCwd(),
-        depth: input.depth + 1,
-        ...(input.opts.registry !== undefined ? { registry: input.opts.registry } : {}),
-        parentRun: {
-          runId: input.runId,
-          stageId: boundary.id,
-          rootRunId: input.opts.parentRun?.rootRunId ?? input.runId,
-        },
-        signal: childController.signal,
-        deferWorkflowStart: false,
-      });
-      boundary.observeChildRun(childRunPromise);
-      const childRun = await childRunPromise;
-      input.exit.throwIfWorkflowExitSelected();
-
-      if (!isWorkflowExitStatus(childRun.status)) {
-        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 childExited = childRun.exited === true || childRun.status !== "completed";
-      const childResult: WorkflowChildResult<TChildOutputs> = childExited
-        ? {
-            workflow: child.normalizedName,
-            runId: childRun.runId,
-            status: childRun.status,
-            exited: true,
-            outputs: outputs as Partial<TChildOutputs>,
-            ...(childRun.exitReason !== undefined ? { exitReason: childRun.exitReason } : {}),
-          }
-        : {
-            workflow: child.normalizedName,
-            runId: childRun.runId,
-            status: "completed",
-            exited: false,
-            outputs: outputs as TChildOutputs,
-          };
-      const workflowChild = workflowChildReplaySnapshot(childName, childResult);
-      const outputKeys = Object.keys(outputs);
-      boundary.complete(
-        `Workflow "${child.name}" ${childRun.status} (runId: ${childRun.runId}; outputs: ${outputKeys.length > 0 ? outputKeys.join(", ") : "(none)"})`,
-        workflowChild,
-      );
-      return childResult;
-    } catch (err) {
-      const exit = findWorkflowExitSignal(err, input.exit.exitScope) ?? findWorkflowExitSignal(input.ownController.signal.reason, input.exit.exitScope);
-      if (exit !== undefined) {
-        await boundary.skipForWorkflowExit(exit.reason);
-        throw exit;
-      }
-      boundary.fail(err);
-      throw err;
-    } finally {
-      detachParentAbort?.();
-      if (childRunId !== undefined) input.opts.cancellation?.unregister(childRunId);
-    }
-  };
-}
+export { createChildWorkflowRunner } from "../../engine/primitives/workflow.js";

package/dist/builtin/workflows/src/runs/foreground/executor-direct-helpers.ts

@@ -15,7 +15,7 @@ import type {
   WorkflowTaskResult,
   WorkflowTaskStep,
 } from "../../shared/types.js";
-import { stampWorkflowDefinition } from "../../workflows/define-workflow.js";
+import { stampWorkflowDefinition } from "../../authoring/workflow.js";
 import { classifyWorkflowFailure } from "../../shared/workflow-failures.js";
 import { buildModelCandidatesFromCatalog, validateWorkflowModels, workflowModelId } from "../shared/model-fallback.js";
 import {

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

@@ -31,7 +31,7 @@ function assertWorkflowOutputsExplicit(
   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`,
+        `atomic-workflows: ${scope} returned undeclared output "${key}"; declare it in outputs: { "${key}": Type.... } or remove it from the .run() return`,
       );
     }
   }
@@ -119,7 +119,7 @@ export function assertWorkflowExitOutputs(
   for (const key of Object.keys(sourceOutput)) {
     if (!hasOwnWorkflowOutput(declarations, key)) {
       throw new Error(
-        `atomic-workflows: ${scope} provided undeclared output "${key}"; declare it with .output("${key}", Type....) or remove it from ctx.exit({ outputs })`,
+        `atomic-workflows: ${scope} provided undeclared output "${key}"; declare it in outputs: { "${key}": Type.... } or remove it from ctx.exit({ outputs })`,
       );
     }
   }

package/dist/builtin/workflows/src/runs/foreground/executor-prompt-nodes.ts

@@ -5,7 +5,7 @@ import { stageUiBroker } from "../../shared/stage-ui-broker.js";
 import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
 import { elapsedStageMs } from "../../shared/timing.js";
 import type { WorkflowFailure } from "../../shared/workflow-failures.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
 import type { RunOpts, WorkflowExitCleanup } from "./executor-types.js";
 import type { ContinuationReplayIndex } from "./executor-continuation.js";
 import { getPromptAnswerState, sameStringSet } from "./executor-continuation.js";

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

@@ -1,359 +1 @@
-import type { RunSnapshot } from "../../shared/store-types.js";
-import type {
-  WorkflowDefinition,
-  WorkflowInputValues,
-  WorkflowCustomUiFactory,
-  WorkflowCustomUiOptions,
-  WorkflowRunContext,
-  WorkflowUIContext,
-} from "../../shared/types.js";
-import type { WorkflowFailure } from "../../shared/workflow-failures.js";
-import { classifyWorkflowFailure } from "../../shared/workflow-failures.js";
-import { store as defaultStore } from "../../shared/store.js";
-import { appendRunStart } from "../../shared/persistence-session-entries.js";
-import { GraphFrontierTracker } from "../shared/graph-inference.js";
-import { createRunLimiter } from "../shared/concurrency.js";
-import { stageControlRegistry as defaultStageControlRegistry } from "./stage-control-registry.js";
-import type { RunOpts, RunResult } from "./executor-types.js";
-import { unknownErrorMessage, findWorkflowExitSignal, parentWorkflowExitAbortReason } from "./executor-abort.js";
-import { createWorkflowExitManager } from "./executor-exit-manager.js";
-import { resolveAndValidateInputs, resolveInputConcurrency, resolveInputRuntimeDefaults } from "./executor-inputs.js";
-import { workflowCwdWithInputWorktree } from "./executor-direct-helpers.js";
-import { createStageScheduler } from "./executor-scheduler.js";
-import { createRunFinalizers } from "./executor-run-finalizers.js";
-import { createWorkflowBoundaryFactory } from "./executor-child-boundary.js";
-import { createWorkflowStageFactory } from "./executor-stage-factory.js";
-import { createWorkflowTaskRunners } from "./executor-task-context.js";
-import { createChildWorkflowRunner } from "./executor-child-workflow.js";
-import { createContinuationReplayIndex } from "./executor-continuation.js";
-import { buildPromptNodeUiAdapter } from "./executor-prompt-nodes.js";
-import { makeHeadlessUnavailableUIContext, normalizeUIContext } from "./executor-hil.js";
-import {
-  appendRunEndWhenRecorded,
-  assertWorkflowCreatedStage,
-  finalizeKilled,
-  finalizeKilledByFailure,
-  recordActiveBlockedFailure,
-  reconcileTerminalRunResult,
-  selectRunFailureDisposition,
-} from "./executor-lifecycle.js";
-import { assertWorkflowRunOutputs, normalizeWorkflowRunOutput } from "./executor-outputs.js";
-import { isWorkflowDefinition, workflowDefinitionRequirementMessage } from "./executor-child-helpers.js";
-
-function nextEventLoopTurn(): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, 0));
-}
-
-function buildExitGatedUiContext(input: {
-  readonly opts: RunOpts;
-  readonly baseFromPromptNodes: () => WorkflowUIContext;
-  readonly throwIfWorkflowExitSelected: () => void;
-}): WorkflowUIContext {
-  const base = input.opts.usePromptNodesForUi === true
-    ? input.baseFromPromptNodes()
-    : input.opts.executionMode === "non_interactive" && input.opts.ui === undefined
-      ? makeHeadlessUnavailableUIContext()
-      : normalizeUIContext(input.opts.ui);
-  return {
-    async input(promptText: string): Promise<string> {
-      input.throwIfWorkflowExitSelected();
-      return await base.input(promptText);
-    },
-    async confirm(message: string): Promise<boolean> {
-      input.throwIfWorkflowExitSelected();
-      return await base.confirm(message);
-    },
-    async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
-      input.throwIfWorkflowExitSelected();
-      return await base.select(message, options);
-    },
-    async editor(initial?: string): Promise<string> {
-      input.throwIfWorkflowExitSelected();
-      return await base.editor(initial);
-    },
-    async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
-      input.throwIfWorkflowExitSelected();
-      return await base.custom(factory, options);
-    },
-  };
-}
-
-export async function run<TInputs extends WorkflowInputValues>(
-  def: WorkflowDefinition<TInputs>,
-  inputs: Readonly<Record<string, unknown>>,
-  opts: RunOpts = {},
-): Promise<RunResult> {
-  if (!isWorkflowDefinition(def)) throw new Error(workflowDefinitionRequirementMessage("run(definition, inputs)", def));
-
-  const activeStore = opts.store ?? defaultStore;
-  const adapters = opts.adapters ?? {};
-  if (opts.usePromptNodesForUi === true && opts.ui !== undefined) {
-    console.warn("atomic-workflows: usePromptNodesForUi ignores the provided RunOpts.ui adapter");
-  }
-
-  const depth = opts.depth ?? 0;
-  const maxDepth = opts.config?.maxDepth ?? 4;
-  if (depth >= maxDepth) {
-    return {
-      runId: opts.runId ?? crypto.randomUUID(),
-      status: "failed",
-      error: `atomic-workflows: maxDepth exceeded (max ${maxDepth})`,
-      stages: [],
-    };
-  }
-
-  const resolvedInputs = resolveAndValidateInputs(def.inputs, inputs, `workflow "${def.name}"`);
-  const runId = opts.runId ?? crypto.randomUUID();
-  const exitScope = Symbol(`workflow-exit:${runId}`);
-  const ownController = new AbortController();
-  const callerSignal = opts.signal;
-  if (callerSignal) {
-    if (callerSignal.aborted) ownController.abort(callerSignal.reason);
-    else callerSignal.addEventListener("abort", () => { ownController.abort(callerSignal.reason); }, { once: true });
-  }
-  const exit = createWorkflowExitManager({ runId, exitScope, controller: ownController });
-
-  const runSnapshot: RunSnapshot = {
-    id: runId,
-    name: def.name,
-    inputs: Object.freeze(resolvedInputs),
-    status: "running" as const,
-    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,
-    } : {}),
-  };
-
-  const classifiedFailures = new Map<unknown, WorkflowFailure>();
-  const classifyExecutorFailure = (error: unknown): WorkflowFailure => {
-    const cached = classifiedFailures.get(error);
-    if (cached !== undefined) return cached;
-    let classified: WorkflowFailure;
-    try {
-      classified = classifyWorkflowFailure(error);
-    } catch {
-      classified = classifyWorkflowFailure(new Error(unknownErrorMessage(error)));
-    }
-    classifiedFailures.set(error, classified);
-    return classified;
-  };
-
-  activeStore.recordRunStart(runSnapshot);
-  if (!opts.signal) opts.cancellation?.register(runId, ownController);
-  opts.onRunStart?.(runSnapshot);
-  if (opts.persistence) {
-    appendRunStart(opts.persistence, {
-      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,
-    });
-  }
-
-  const tracker = new GraphFrontierTracker();
-  const inputConcurrency = resolveInputConcurrency(def.inputs, resolvedInputs);
-  const inputRuntimeDefaults = resolveInputRuntimeDefaults(def, resolvedInputs);
-  const workflowInvocationCwd = opts.cwd ?? process.cwd();
-  let workflowCwd: string | undefined;
-  const resolveWorkflowCwd = (): string => {
-    workflowCwd ??= workflowCwdWithInputWorktree(inputRuntimeDefaults, workflowInvocationCwd);
-    return workflowCwd;
-  };
-  const limiter = createRunLimiter(inputConcurrency ?? opts.config?.defaultConcurrency);
-  const stageRegistry = opts.stageControlRegistry ?? defaultStageControlRegistry;
-  const replayIndex = createContinuationReplayIndex(opts.continuation);
-  const scheduler = createStageScheduler({
-    runId,
-    runSnapshot,
-    activeStore,
-    tracker,
-    stageRegistry: () => stageRegistry,
-  });
-  ownController.signal.addEventListener(
-    "abort",
-    () => scheduler.rejectReleaseBarriers(ownController.signal.reason ?? new Error("atomic-workflows: run aborted")),
-    { once: true },
-  );
-
-  const finalizers = createRunFinalizers({
-    def,
-    runId,
-    runSnapshot,
-    activeStore,
-    opts,
-    classifyExecutorFailure,
-    drainWorkflowExitCleanups: exit.drainWorkflowExitCleanups,
-  });
-  const startWorkflowBoundaryStage = createWorkflowBoundaryFactory({
-    runId,
-    runSnapshot,
-    activeStore,
-    opts,
-    tracker,
-    replayIndex,
-    registerWorkflowExitCleanup: exit.registerWorkflowExitCleanup,
-    workflowExitSkippedReason: exit.workflowExitSkippedReason,
-    classifyExecutorFailure,
-  });
-  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 stage = createWorkflowStageFactory({
-    runId,
-    activeStore,
-    opts,
-    adapters,
-    signal: ownController.signal,
-    tracker,
-    scheduler,
-    replayIndex,
-    limiter,
-    inputRuntimeDefaults,
-    workflowInvocationCwd,
-    stageRegistry,
-    exit,
-    classifyExecutorFailure,
-  });
-  const taskRunners = createWorkflowTaskRunners({
-    runId,
-    exit,
-    tracker,
-    inputRuntimeDefaults,
-    workflowInvocationCwd,
-    stage,
-  });
-  const workflow = createChildWorkflowRunner({
-    runId,
-    depth,
-    opts,
-    exit,
-    ownController,
-    resolveWorkflowCwd,
-    nextWorkflowBoundaryReplayKey,
-    startWorkflowBoundaryStage,
-    runWorkflow: run,
-  });
-
-  const ctx: WorkflowRunContext<TInputs> = {
-    inputs: resolvedInputs as TInputs,
-    get cwd() { return resolveWorkflowCwd(); },
-    exit: exit.exit,
-    ui: buildExitGatedUiContext({
-      opts,
-      throwIfWorkflowExitSelected: exit.throwIfWorkflowExitSelected,
-      baseFromPromptNodes: () => buildPromptNodeUiAdapter({
-        runId,
-        activeStore,
-        opts,
-        tracker,
-        replayIndex,
-        signal: ownController.signal,
-        throwIfWorkflowExitSelected: exit.throwIfWorkflowExitSelected,
-        registerWorkflowExitCleanup: exit.registerWorkflowExitCleanup,
-        workflowExitSkippedReason: exit.workflowExitSkippedReason,
-        preserveWorkflowExitSkippedReason: exit.preserveWorkflowExitSkippedReason,
-        classifyExecutorFailure,
-      }),
-    }),
-    stage,
-    task: taskRunners.task,
-    chain: taskRunners.chain,
-    parallel: taskRunners.parallel,
-    workflow,
-  };
-
-  try {
-    if (opts.deferWorkflowStart === true) {
-      await nextEventLoopTurn();
-      if (ownController.signal.aborted) {
-        const selectedExit = findWorkflowExitSignal(ownController.signal.reason, exitScope);
-        if (selectedExit !== undefined) return await finalizers.finalizeWorkflowExit(selectedExit);
-        const parentExit = parentWorkflowExitAbortReason(ownController.signal.reason);
-        if (parentExit !== undefined) return await finalizers.finalizeParentWorkflowExitCancellation(parentExit);
-        return finalizeKilled(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd);
-      }
-    }
-
-    const rawResult = await def.run(ctx);
-    if (ownController.signal.aborted) {
-      const selectedExit = findWorkflowExitSignal(ownController.signal.reason, exitScope);
-      if (selectedExit !== undefined) return await finalizers.finalizeWorkflowExit(selectedExit);
-      const parentExit = parentWorkflowExitAbortReason(ownController.signal.reason);
-      if (parentExit !== undefined) return await finalizers.finalizeParentWorkflowExitCancellation(parentExit);
-      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);
-    appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: "completed", result, ts: Date.now() });
-    return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "completed", result }, opts.onRunEnd);
-  } catch (err) {
-    const selectedExit = findWorkflowExitSignal(err, exitScope) ?? findWorkflowExitSignal(ownController.signal.reason, exitScope);
-    if (selectedExit !== undefined) return await finalizers.finalizeWorkflowExit(selectedExit);
-
-    if (ownController.signal.aborted) {
-      const parentExit = parentWorkflowExitAbortReason(ownController.signal.reason);
-      if (parentExit !== undefined) return await finalizers.finalizeParentWorkflowExitCancellation(parentExit);
-      return finalizeKilled(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd);
-    }
-
-    const failure = classifyExecutorFailure(err);
-    const metadata = selectRunFailureDisposition({
-      outerFailure: failure,
-      thrownError: err,
-      stages: runSnapshot.stages,
-      classifyFailure: classifyExecutorFailure,
-    });
-
-    if (metadata.failureDisposition === "terminal_killed") {
-      for (const failedStageId of metadata.failedStageIds) scheduler.blockKnownNonTerminalDescendants(failedStageId);
-      return finalizeKilledByFailure(runId, runSnapshot, activeStore, opts.persistence, opts.onRunEnd, { ...metadata, resumable: false });
-    }
-
-    if (metadata.failureDisposition === "active_blocked" && metadata.failedStageId !== undefined && metadata.failureRecoverability === "recoverable") {
-      for (const failedStageId of metadata.failedStageIds) scheduler.blockKnownNonTerminalDescendants(failedStageId);
-      return recordActiveBlockedFailure(runId, runSnapshot, activeStore, opts.persistence, {
-        ...metadata,
-        failureRecoverability: "recoverable",
-        failedStageId: metadata.failedStageId,
-        resumable: true,
-      });
-    }
-
-    const recorded = activeStore.recordRunEnd(runId, "failed", undefined, metadata.errorMessage, metadata);
-    appendRunEndWhenRecorded(opts.persistence, recorded, {
-      runId,
-      status: "failed",
-      error: metadata.errorMessage,
-      failureKind: metadata.failureKind,
-      ...(metadata.failureCode !== undefined ? { failureCode: metadata.failureCode } : {}),
-      ...(metadata.failureRecoverability !== undefined ? { failureRecoverability: metadata.failureRecoverability } : {}),
-      ...(metadata.failureDisposition !== undefined ? { failureDisposition: metadata.failureDisposition } : {}),
-      failureMessage: metadata.failureMessage,
-      ...(metadata.failedStageId !== undefined ? { failedStageId: metadata.failedStageId } : {}),
-      resumable: metadata.resumable,
-      ...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
-      ts: Date.now(),
-    });
-    return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "failed", error: metadata.errorMessage }, opts.onRunEnd);
-  } finally {
-    opts.cancellation?.unregister(runId);
-  }
-}
+export { run } from "../../engine/run.js";

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

@@ -1,6 +1,6 @@
 import type { RunSnapshot, StageSnapshot } from "../../shared/store-types.js";
 import type { Store } from "../../shared/store.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
 import type { StageControlRegistry } from "./stage-control-registry.js";
 
 interface ReleaseBarrier {

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

@@ -112,10 +112,7 @@ export function createTrackedStageCaller(input: {
     runtime.activeStore.recordStageStart(runtime.runId, runtime.stageSnapshot);
     runtime.appendStageStartOnce();
 
-    const mcpAllow = input.options?.mcp?.allow ?? null;
-    const mcpDeny = input.options?.mcp?.deny ?? null;
-    const hasMcpScope = mcpAllow !== null || mcpDeny !== null;
-    if (runtime.opts.mcp && hasMcpScope) runtime.opts.mcp.setScope(runtime.stageId, mcpAllow, mcpDeny);
+    runtime.mcpScope.apply();
 
     try {
       const abortSession = (): void => {
@@ -183,7 +180,7 @@ export function createTrackedStageCaller(input: {
       }
       throw err;
     } finally {
-      if (runtime.opts.mcp && hasMcpScope) runtime.opts.mcp.clearScope(runtime.stageId);
+      runtime.mcpScope.clear();
       runtime.captureStageSessionMeta();
       runtime.finalizeStageSnapshot();
       if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {

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

@@ -7,10 +7,11 @@ import { appendStageEnd, appendStageStart } from "../../shared/persistence-sessi
 import { elapsedStageMs } from "../../shared/timing.js";
 import type { WorkflowFailure } from "../../shared/workflow-failures.js";
 import type { ConcurrencyLimiter } from "../shared/concurrency.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
+import type { EngineStageRuntimeOptions } from "../../engine/options.js";
 import { createStageContext as createInnerStageContext, type InternalStageContext, type StageAdapters } from "./stage-runner.js";
 import type { StageControlRegistry } from "./stage-control-registry.js";
-import type { RunOpts, ParallelFailFastScope } from "./executor-types.js";
+import type { ParallelFailFastScope } from "./executor-types.js";
 import type { WorkflowExitManager } from "./executor-exit-manager.js";
 import type { ContinuationReplayIndex } from "./executor-continuation.js";
 import { sameStringSet } from "./executor-continuation.js";
@@ -19,7 +20,7 @@ import { isTerminalStage } from "./executor-scheduler.js";
 import { stageReplayFields } from "./executor-lifecycle.js";
 import { askUserQuestionToolEvent, toolResultHasChatAnswer } from "./executor-hil.js";
 import { createReplayStageContext } from "./executor-stage-replay.js";
-import type { LiveStageMutableState, LiveStageRuntime, StageContextWithMeta } from "./executor-stage-types.js";
+import type { LiveStageMutableState, LiveStageRuntime, StageContextWithMeta, StageMcpScope } from "./executor-stage-types.js";
 import { createStageControlHandle } from "./executor-stage-control.js";
 import { createTrackedStageCaller } from "./executor-stage-call.js";
 import { createStageContext } from "./executor-stage-context.js";
@@ -28,7 +29,7 @@ import { stageOptionsWithGitWorktree, stageOptionsWithInputDefaults } from "./ex
 export function createWorkflowStageFactory(input: {
   readonly runId: string;
   readonly activeStore: Store;
-  readonly opts: RunOpts;
+  readonly opts: EngineStageRuntimeOptions;
   readonly adapters: StageAdapters;
   readonly signal: AbortSignal;
   readonly tracker: GraphFrontierTracker;
@@ -40,6 +41,7 @@ export function createWorkflowStageFactory(input: {
   readonly stageRegistry: StageControlRegistry;
   readonly exit: WorkflowExitManager;
   readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
+  readonly createMcpScope: (stageId: string, options: StageOptions | undefined) => StageMcpScope;
 }): (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope) => StageContextWithMeta {
   return (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope): StageContextWithMeta => {
     input.exit.throwIfWorkflowExitSelected();
@@ -287,6 +289,7 @@ export function createWorkflowStageFactory(input: {
       signal: input.signal,
       exit: input.exit,
       classifyExecutorFailure: input.classifyExecutorFailure,
+      mcpScope: input.createMcpScope(stageId, options),
       ...(stageFailFastScope !== undefined ? { stageFailFastScope } : {}),
       state,
       unregisterStageHandle: () => {},
@@ -317,6 +320,11 @@ export function createWorkflowStageFactory(input: {
     const blockedBy = input.scheduler.blockingAncestorFor(stageSnapshot);
     if (blockedBy !== undefined) input.scheduler.blockStageUntilCascadeRelease(stageSnapshot, blockedBy);
 
+    // Parallel fail-fast and workflow-exit cleanup can both target a live stage.
+    // The first terminal path owns the snapshot: finalization unregisters
+    // workflow-exit cleanup and removes the stage from the fail-fast active set.
+    // Later paths must not overwrite the terminal skippedReason; they only abort
+    // and release idempotent live handles.
     const skipForParallelFailFast = (): void => {
       if (isTerminalStage(stageSnapshot)) return;
       markSkippedForParallelFailFast();

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

@@ -2,9 +2,10 @@ import type { StageSnapshot } from "../../shared/store-types.js";
 import type { Store } from "../../shared/store.js";
 import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
 import { elapsedStageMs } from "../../shared/timing.js";
-import type { GraphFrontierTracker } from "../shared/graph-inference.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
+import type { EngineStageRuntimeOptions } from "../../engine/options.js";
 import type { InternalStageContext } from "./stage-runner.js";
-import type { RunOpts, WorkflowExitCleanup } from "./executor-types.js";
+import type { WorkflowExitCleanup } from "./executor-types.js";
 import { stageReplayFields } from "./executor-lifecycle.js";
 
 export function createReplayStageContext(input: {
@@ -14,7 +15,7 @@ export function createReplayStageContext(input: {
   readonly stageSnapshot: StageSnapshot;
   readonly replaySource: StageSnapshot;
   readonly activeStore: Store;
-  readonly opts: RunOpts;
+  readonly opts: EngineStageRuntimeOptions;
   readonly tracker: GraphFrontierTracker;
   readonly registerWorkflowExitCleanup: (stageId: string, cleanup: WorkflowExitCleanup) => () => void;
   readonly workflowExitSkippedReason: (reason?: string) => string;