@bastani/atomic 0.9.9 → 0.9.10-alpha.1

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

@@ -1,22 +1,13 @@
 import { tmpdir } from "node:os";
-import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { APP_NAME, CONFIG_DIR_NAME, isCodexFastModeCandidateModelId } from "@bastani/atomic";
-import { Type } from "typebox";
 import type {
   StageOptions,
   WorkflowArtifact,
-  WorkflowChainStep,
-  WorkflowDefinition,
-  WorkflowDetails,
-  WorkflowDirectOptions,
-  WorkflowDirectTaskItem,
-  WorkflowOutputSchema,
-  WorkflowTaskResult,
+  WorkflowTaskOptions,
   WorkflowTaskStep,
 } from "../../shared/types.js";
-import { stampWorkflowDefinition } from "../../authoring/workflow.js";
-import { classifyWorkflowFailure } from "../../shared/workflow-failures.js";
-import { buildModelCandidatesFromCatalog, validateWorkflowModels, workflowModelId } from "../shared/model-fallback.js";
+import { buildModelCandidatesFromCatalog, workflowModelId } from "../shared/model-fallback.js";
 import {
   cleanupWorktrees,
   createWorktrees,
@@ -30,37 +21,12 @@ import {
   type WorktreeSetup,
 } from "../shared/worktree.js";
 import { resolveWorktreeStageCwd } from "../shared/worktree-cwd.js";
-import type { RunOpts, RunResult } from "./executor-types.js";
-import { isWorkflowExitStatus } from "./executor-abort.js";
-import { directTaskWithDefaults, withoutUndefinedProperties } from "./executor-task-prompts.js";
+import type { RunOpts } from "./executor-types.js";
+import { withoutUndefinedProperties } from "./executor-task-prompts.js";
+
 export { createGitWorktreeSetupCache, createGitWorktreeSetupCacheOwner } from "../shared/worktree.js";
 export type { GitWorktreeSetupCache } from "../shared/worktree.js";
 
-export function directModelRequestsFromChain(
-  chain: readonly WorkflowChainStep[],
-  options: WorkflowDirectOptions,
-): Array<{ readonly model?: WorkflowDirectTaskItem["model"]; readonly fallbackModels?: readonly string[] }> {
-  const requests: Array<{ readonly model?: WorkflowDirectTaskItem["model"]; readonly fallbackModels?: readonly string[] }> = [];
-  for (const step of chain) {
-    if ("parallel" in step) {
-      requests.push(...step.parallel.map((item) => directTaskWithDefaults(item, options)));
-    } else {
-      requests.push(directTaskWithDefaults(step, options));
-    }
-  }
-  return requests;
-}
-
-export async function validateDirectModels(
-  tasks: readonly WorkflowDirectTaskItem[],
-  runOptions: RunOpts,
-): Promise<readonly string[]> {
-  return validateWorkflowModels({
-    requests: tasks.map((task) => ({ model: task.model, fallbackModels: task.fallbackModels })),
-    catalog: runOptions.models,
-  });
-}
-
 export function positiveConcurrency(value: number | undefined): number | undefined {
   if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return undefined;
   return Math.floor(value);
@@ -107,16 +73,12 @@ export async function mapParallelSteps<T>(
 
   async function worker(): Promise<void> {
     while (true) {
-      if (controlSignal !== undefined) return;
-      if (failFastEnabled && firstFailure !== undefined) return;
+      if (controlSignal !== undefined || (failFastEnabled && firstFailure !== undefined)) return;
       try {
         control?.beforeDequeue?.();
-      } catch (err) {
-        if (isControlSignal(err)) {
-          selectControlSignal(err);
-          return;
-        }
-        await recordFailure(nextIndex, err);
+      } catch (error) {
+        if (isControlSignal(error)) selectControlSignal(error);
+        else await recordFailure(nextIndex, error);
         return;
       }
       if (controlSignal !== undefined) return;
@@ -127,104 +89,38 @@ export async function mapParallelSteps<T>(
       try {
         control?.beforeMap?.();
         results[index] = await mapper(step);
-      } catch (err) {
-        if (isControlSignal(err)) {
-          selectControlSignal(err);
+      } catch (error) {
+        if (isControlSignal(error)) {
+          selectControlSignal(error);
           return;
         }
-        await recordFailure(index, err);
+        await recordFailure(index, error);
         if (failFastEnabled) return;
       }
     }
   }
 
-  const workers = Array.from({ length: Math.min(limit, steps.length) }, () => worker());
-  const allWorkers = Promise.all(workers);
-
-  if (!failFastEnabled) {
-    await allWorkers;
-  } else {
+  const allWorkers = Promise.all(Array.from({ length: Math.min(limit, steps.length) }, () => worker()));
+  if (!failFastEnabled) await allWorkers;
+  else {
     try {
       await Promise.race([allWorkers, firstFailurePromise]);
-    } catch (err) {
+    } catch (error) {
       void allWorkers.catch(() => {});
-      throw err;
+      throw error;
     }
   }
 
   if (controlSignal !== undefined) throw controlSignal;
-
   if (failures.length > 0) {
     throw new AggregateError(
       failures.map((failure) => failure.error),
       `atomic-workflows: ${failures.length} parallel ${failures.length === 1 ? "step" : "steps"} failed`,
     );
   }
-
   return results;
 }
 
-export function expandedParallelTasks(tasks: readonly WorkflowDirectTaskItem[]): WorkflowDirectTaskItem[] {
-  const expanded: WorkflowDirectTaskItem[] = [];
-  for (const task of tasks) {
-    const count = task.count ?? 1;
-    if (!Number.isInteger(count) || count < 1) {
-      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 : {
-        ...task,
-        name: `${task.name}-${index + 1}`,
-        count: undefined,
-        output: namespaceRepeatedOutput(task.output, index),
-      });
-    }
-  }
-  return expanded;
-}
-
-function namespaceRepeatedOutput(output: WorkflowDirectTaskItem["output"], index: number): WorkflowDirectTaskItem["output"] {
-  if (typeof output !== "string") return output;
-  const ext = extname(output);
-  const base = basename(output, ext);
-  return join(dirname(output), `${base}-${index + 1}${ext}`);
-}
-
-export interface DirectOutputIsolation {
-  readonly baseDir: string;
-  readonly trustedRoot: string;
-}
-
-export interface PreparedDirectWorktrees {
-  readonly tasks: WorkflowDirectTaskItem[];
-  readonly setup?: WorktreeSetup;
-  readonly agents: string[];
-  readonly diffsDir?: string;
-  readonly outputIsolations?: readonly DirectOutputIsolation[];
-}
-
-export function directRunId(runOptions: RunOpts): string {
-  return runOptions.runId ?? crypto.randomUUID();
-}
-
-function hasDirectWorktreeIsolation(tasks: readonly WorkflowDirectTaskItem[], options: WorkflowDirectOptions): boolean {
-  return options.worktree === true || tasks.some((task) => task.worktree === true);
-}
-
-function resolveSharedDirectWorktreeCwd(
-  tasks: readonly WorkflowDirectTaskItem[],
-  workflowInvocationCwd: string,
-): string {
-  const explicitCwd = tasks.find((task) => typeof task.cwd === "string")?.cwd;
-  if (explicitCwd === undefined) return workflowInvocationCwd;
-  return isAbsolute(explicitCwd) ? explicitCwd : resolve(workflowInvocationCwd, explicitCwd);
-}
-
-function normalizeDirectTaskCwd(cwd: string | undefined, workflowInvocationCwd: string): string | undefined {
-  if (cwd === undefined) return undefined;
-  return isAbsolute(cwd) ? cwd : resolve(workflowInvocationCwd, cwd);
-}
-
 export function stageOptionsWithInputDefaults<T extends StageOptions>(options: T | undefined, inputDefaults: Partial<StageOptions>): T | undefined {
   const defaults = withoutUndefinedProperties(inputDefaults);
   if (Object.keys(defaults).length === 0) return options;
@@ -247,9 +143,7 @@ export function stageOptionsWithGitWorktree<T extends StageOptions>(options: T |
 }
 
 export function setupWorkflowInputGitWorktree(inputDefaults: Partial<StageOptions>, workflowInvocationCwd: string, cache?: GitWorktreeSetupCache): GitWorktreeSetupResult | undefined {
-  if (typeof inputDefaults.gitWorktreeDir !== "string" || inputDefaults.gitWorktreeDir.trim().length === 0) {
-    return undefined;
-  }
+  if (typeof inputDefaults.gitWorktreeDir !== "string" || inputDefaults.gitWorktreeDir.trim().length === 0) return undefined;
   return setupGitWorktreeCached({
     gitWorktreeDir: inputDefaults.gitWorktreeDir,
     baseBranch: inputDefaults.baseBranch,
@@ -274,74 +168,73 @@ export function workflowInvocationMetadata(inputDefaults: Partial<StageOptions>,
   };
 }
 
-function nonBlankChainDir(chainDir: string | undefined): string | undefined {
-  return typeof chainDir === "string" && chainDir.trim().length > 0 ? chainDir : undefined;
+export interface TaskOutputIsolation {
+  readonly baseDir: string;
+  readonly trustedRoot: string;
 }
 
-function directWorktreeArtifactBase(options: WorkflowDirectOptions, setup: WorktreeSetup): string {
-  return nonBlankChainDir(options.chainDir) ?? join(setup.cwd, CONFIG_DIR_NAME, "workflows");
+export interface PreparedTaskWorktrees {
+  readonly tasks: WorkflowTaskStep[];
+  readonly setup?: WorktreeSetup;
+  readonly agents: string[];
+  readonly diffsDir?: string;
+  readonly outputIsolations?: readonly TaskOutputIsolation[];
 }
 
-function directWorktreeDiffsDir(options: WorkflowDirectOptions, setup: WorktreeSetup, runId: string, scope: string): string {
-  return join(directWorktreeArtifactBase(options, setup), "worktree-diffs", runId, scope);
+function resolvedTaskCwd(cwd: string | undefined, workflowInvocationCwd: string): string | undefined {
+  if (cwd === undefined) return undefined;
+  return isAbsolute(cwd) ? cwd : resolve(workflowInvocationCwd, cwd);
 }
 
-function directWorktreeOutputsRoot(): string {
+function taskWorktreeOutputsRoot(): string {
   return join(tmpdir(), `${APP_NAME}-workflow-outputs`);
 }
 
-function directWorktreeOutputsDir(runId: string, scope: string, index: number): string {
-  return join(directWorktreeOutputsRoot(), runId, scope, String(index));
-}
-
-export function prepareDirectWorktrees(
-  tasks: readonly WorkflowDirectTaskItem[],
-  options: WorkflowDirectOptions,
+export function prepareTaskWorktrees(
+  tasks: readonly WorkflowTaskStep[],
+  options: WorkflowTaskOptions,
   runId: string,
   scope: string,
   workflowInvocationCwd: string = process.cwd(),
-): PreparedDirectWorktrees {
-  if (!hasDirectWorktreeIsolation(tasks, options)) {
-    return {
-      tasks: [...tasks],
-      agents: tasks.map((task) => task.name),
-    };
+  symlinkDirectories?: readonly string[],
+): PreparedTaskWorktrees {
+  if (options.worktree !== true && !tasks.some((task) => task.worktree === true)) {
+    return { tasks: [...tasks], agents: tasks.map((task) => task.name) };
   }
-
   if (typeof options.gitWorktreeDir === "string" || tasks.some((task) => typeof task.gitWorktreeDir === "string")) {
     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, workflowInvocationCwd);
+  const explicitCwd = tasks.find((task) => typeof task.cwd === "string")?.cwd;
+  const sharedCwd = explicitCwd === undefined
+    ? workflowInvocationCwd
+    : isAbsolute(explicitCwd) ? explicitCwd : resolve(workflowInvocationCwd, explicitCwd);
   const conflict = findWorktreeTaskCwdConflict(
-    tasks.map((task) => ({ agent: task.name, cwd: normalizeDirectTaskCwd(task.cwd, workflowInvocationCwd) })),
+    tasks.map((task) => ({ agent: task.name, cwd: resolvedTaskCwd(task.cwd, workflowInvocationCwd) })),
     sharedCwd,
   );
   if (conflict !== undefined) throw new Error(formatWorktreeTaskCwdConflict(conflict, sharedCwd));
 
   const agents = tasks.map((task) => task.name);
-  const setup = createWorktrees(sharedCwd, runId, tasks.length, { agents });
+  const setup = createWorktrees(sharedCwd, runId, tasks.length, {
+    agents,
+    baseBranch: options.baseBranch,
+    symlinkDirectories,
+  });
+  const trustedRoot = taskWorktreeOutputsRoot();
   return {
-    tasks: tasks.map((task, index) => ({
-      ...task,
-      cwd: setup.worktrees[index]!.agentCwd,
-    })),
+    tasks: tasks.map((task, index) => ({ ...task, cwd: setup.worktrees[index]!.agentCwd })),
     setup,
     agents,
-    diffsDir: directWorktreeDiffsDir(options, setup, runId, scope),
-    outputIsolations: tasks.map((_, index) => ({
-      baseDir: directWorktreeOutputsDir(runId, scope, index),
-      trustedRoot: directWorktreeOutputsRoot(),
-    })),
+    diffsDir: join(setup.cwd, CONFIG_DIR_NAME, "workflows", "worktree-diffs", runId, scope),
+    outputIsolations: tasks.map((_, index) => ({ baseDir: join(trustedRoot, runId, scope, String(index)), trustedRoot })),
   };
 }
 
-export function collectWorktreeDiffs(prepared: PreparedDirectWorktrees, enabled = true): {
+export function collectWorktreeDiffs(prepared: PreparedTaskWorktrees, enabled = true): {
   artifacts: WorkflowArtifact[];
   summary?: string;
 } {
   if (!enabled || prepared.setup === undefined || prepared.diffsDir === undefined) return { artifacts: [] };
-
   const diffs = diffWorktrees(prepared.setup, prepared.agents, prepared.diffsDir);
   const artifacts = diffs.map((diff) => ({
     kind: "diff" as const,
@@ -354,105 +247,13 @@ export function collectWorktreeDiffs(prepared: PreparedDirectWorktrees, enabled
     deletions: diff.deletions,
   }));
   const summary = formatWorktreeDiffSummary(diffs);
-  return {
-    artifacts,
-    ...(summary.length > 0 ? { summary } : {}),
-  };
+  return { artifacts, ...(summary.length > 0 ? { summary } : {}) };
 }
 
-export function cleanupPreparedWorktrees(prepared: PreparedDirectWorktrees): void {
+export function cleanupPreparedWorktrees(prepared: PreparedTaskWorktrees): void {
   if (prepared.setup !== undefined) cleanupWorktrees(prepared.setup);
 }
 
-export function isRunOpts(value: WorkflowDirectOptions | RunOpts | undefined): value is RunOpts {
-  if (value === undefined) return false;
-  return (
-    "adapters" in value || "ui" in value || "store" in value || "persistence" in value ||
-    "mcp" in value || "cancellation" in value || "overlay" in value || "signal" in value ||
-    "config" in value || "depth" in value || "stageControlRegistry" in value || "runId" in value ||
-    "gitWorktreeSetupCache" in value || "onRunStart" in value || "onStageStart" in value ||
-    "onStageEnd" in value || "onRunEnd" in value || "models" in value
-  );
-}
-
-
-function directFailureMessage(error: unknown): string {
-  return classifyWorkflowFailure(error).userMessage;
-}
-
-export function failedDirectDetails(
-  mode: WorkflowDetails["mode"],
-  runId: string,
-  total: number,
-  error: unknown,
-  options: WorkflowDirectOptions = {},
-): WorkflowDetails {
-  return {
-    mode,
-    action: "run",
-    runId,
-    status: "failed",
-    ...(options.context !== undefined ? { context: options.context } : {}),
-    results: [],
-    progress: { completed: 0, total },
-    error: directFailureMessage(error),
-  };
-}
-
-export function workflowDetailsFromRun(
-  mode: WorkflowDetails["mode"],
-  runResult: RunResult,
-  results: readonly WorkflowTaskResult[],
-  options: WorkflowDirectOptions = {},
-  warnings: readonly string[] = [],
-): WorkflowDetails {
-  const sessionArtifacts = options.artifacts === false ? [] : results.flatMap((result) =>
-    result.sessionFile === undefined ? [] : [{ kind: "session" as const, path: result.sessionFile, taskName: result.name }],
-  );
-  const outputArtifacts = Array.isArray(runResult.result?.["artifacts"])
-    ? runResult.result["artifacts"] as WorkflowArtifact[]
-    : [];
-  const artifacts = [...outputArtifacts, ...sessionArtifacts];
-  const allWarnings = [...warnings, ...results.flatMap((result) => result.warnings ?? [])];
-  return {
-    mode,
-    action: "run",
-    runId: runResult.runId,
-    status: isWorkflowExitStatus(runResult.status) ? runResult.status : runResult.status === "failed" ? "failed" : runResult.status === "killed" ? "killed" : "running",
-    ...(options.context !== undefined ? { context: options.context } : {}),
-    results: [...results],
-    output: runResult.result,
-    progress: { completed: results.length, total: results.length },
-    ...(artifacts.length > 0 ? { artifacts } : {}),
-    ...(allWarnings.length > 0 ? { warnings: allWarnings } : {}),
-    ...(runResult.error !== undefined ? { error: runResult.error } : {}),
-    ...(runResult.exited !== undefined ? { exited: runResult.exited } : {}),
-    ...(runResult.exitReason !== undefined ? { exitReason: runResult.exitReason } : {}),
-  };
-}
-
-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()),
-});
-
-export function defineDirectWorkflow(name: string, runFn: WorkflowDefinition["run"]): WorkflowDefinition {
-  const definition = {
-    __piWorkflow: true,
-    name,
-    normalizedName: name,
-    description: "Direct workflow execution",
-    inputs: Object.freeze({}),
-    outputs: DIRECT_WORKFLOW_OUTPUTS,
-    run: runFn,
-  } as WorkflowDefinition;
-  stampWorkflowDefinition(definition);
-  return Object.freeze(definition);
-}
-
 export async function hasExplicitFastModeCandidate(input: {
   readonly model?: StageOptions["model"];
   readonly fallbackModels?: readonly string[];

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

@@ -10,6 +10,8 @@ import type {
 } from "../../shared/types.js";
 import type { PendingPrompt, CustomPromptIdentitySource } from "../../shared/store-types.js";
 import { selectPromptCallsiteFrame } from "../shared/prompt-callsite.js";
+import { currentPromptCallerStack } from "../../shared/prompt-callsite-context.js";
+import type { ResumeContinuationReason } from "./executor-stage-types.js";
 
 export type PrimitivePromptDescriptor =
   | { readonly kind: "input"; readonly message: string; readonly initial?: string }
@@ -83,7 +85,7 @@ export function promptReplayKey(descriptor: PromptDescriptor): string {
 }
 
 function promptCallsiteHash(): string {
-  const frame = selectPromptCallsiteFrame(new Error().stack ?? "") ?? "unknown";
+  const frame = selectPromptCallsiteFrame(currentPromptCallerStack() ?? new Error().stack ?? "") ?? "unknown";
   return stableHash(frame);
 }
 
@@ -263,7 +265,7 @@ const READINESS_GATE_ADVANCE_NORMALIZED = READINESS_GATE_ADVANCE_LABEL.trim().to
 export const READINESS_GATE_QUESTION_PARAMS = {
   questions: [
     {
-      question: "Any additional points to explore before moving on?",
+      question: "Are you ready to move on to the next stage?",
       header: "Continue?",
       options: [
         {
@@ -313,11 +315,12 @@ export function toolResultHasChatAnswer(result: unknown): boolean {
 export { RESUME_CONTINUATION_PROMPT } from "../../shared/resume-continuation.js";
 
 export function shouldInjectResumeContinuation(state: {
-  readonly resumeOccurred: boolean;
+  readonly reason: ResumeContinuationReason | false;
   readonly gateEnabled: boolean;
   readonly aborted: boolean;
 }): boolean {
-  return state.resumeOccurred && state.gateEnabled && !state.aborted;
+  if (state.reason === false || state.aborted) return false;
+  return state.reason === "queued-user-message" || state.gateEnabled;
 }
 
 let cachedReadinessGateTool: ReturnType<typeof createAskUserQuestionToolDefinition> | undefined;

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

@@ -135,7 +135,7 @@ export function runFailureMetadata(
   };
 }
 
-interface SelectedRunFailureMetadata extends RunFailureMetadata {
+export interface SelectedRunFailureMetadata extends RunFailureMetadata {
   readonly failedStageIds: readonly string[];
 }
 
@@ -337,6 +337,17 @@ export function selectRunFailureDisposition(input: {
   return selectedMetadata(runFailureMetadata(input.outerFailure, input.stages), failedStageIds);
 }
 
+/** Stage-less non-cancellation errors are startup failures, not killed runs. */
+export function normalizeStageLessFailureMetadata(
+  metadata: SelectedRunFailureMetadata,
+  stageCount: number,
+): SelectedRunFailureMetadata {
+  if (metadata.failureDisposition !== "terminal_killed" || metadata.failureKind === "cancelled" || stageCount > 0) {
+    return metadata;
+  }
+  return { ...metadata, failureDisposition: "terminal_failed" };
+}
+
 export function stageReplayFields(stage: StageSnapshot): Partial<Pick<StageSnapshot, "replayKey" | "replayedFromStageId" | "replayed">> {
   return {
     ...(stage.replayKey !== undefined ? { replayKey: stage.replayKey } : {}),

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

@@ -8,6 +8,7 @@ import type { WorkflowFailure } from "../../shared/workflow-failures.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 type { StageControlRegistry } from "./stage-control-registry.js";
 import { getPromptAnswerState, sameStringSet } from "./executor-continuation.js";
 import { applyFailureToStage, stageReplayFields } from "./executor-lifecycle.js";
 import {
@@ -25,6 +26,7 @@ export function buildPromptNodeUiAdapter(input: {
   readonly runId: string;
   readonly activeStore: Store;
   readonly opts: RunOpts;
+  readonly stageControlRegistry: StageControlRegistry;
   readonly tracker: GraphFrontierTracker;
   readonly replayIndex: ContinuationReplayIndex;
   readonly signal: AbortSignal;
@@ -88,10 +90,19 @@ export function buildPromptNodeUiAdapter(input: {
     };
     let finalized = false;
     let unregisterWorkflowExitCleanup = (): void => {};
+    let unregisterStageControl = (): void => {};
+    let pauseGate: PromiseWithResolvers<void> | undefined;
+    const waitForExplicitResume = async (): Promise<void> => {
+      if (pauseGate !== undefined) await pauseGate.promise;
+    };
     const finalizePromptStage = (status: "completed" | "failed" | "skipped"): void => {
       if (finalized) return;
       finalized = true;
       unregisterWorkflowExitCleanup();
+      unregisterStageControl();
+      const currentPauseGate = pauseGate;
+      pauseGate = undefined;
+      currentPauseGate?.resolve();
       stageSnapshot.status = status;
       stageSnapshot.endedAt = Date.now();
       stageSnapshot.durationMs = elapsedStageMs(stageSnapshot, stageSnapshot.endedAt);
@@ -120,6 +131,32 @@ export function buildPromptNodeUiAdapter(input: {
 
     input.activeStore.recordStageStart(input.runId, stageSnapshot);
     input.opts.onStageStart?.(input.runId, stageSnapshot);
+    unregisterStageControl = input.stageControlRegistry.register({
+      runId: input.runId,
+      stageId,
+      stageName: descriptor.kind,
+      get status() { return stageSnapshot.status; },
+      sessionId: undefined,
+      sessionFile: undefined,
+      isStreaming: false,
+      messages: [],
+      async ensureAttached() {},
+      async prompt() {},
+      async steer() {},
+      async followUp() {},
+      async pause() {
+        if (pauseGate === undefined) pauseGate = Promise.withResolvers<void>();
+        input.activeStore.recordStagePaused(input.runId, stageId);
+      },
+      async resume() {
+        input.activeStore.recordStageResumed(input.runId, stageId);
+        input.activeStore.recordRunResumed(input.runId);
+        const currentPauseGate = pauseGate;
+        pauseGate = undefined;
+        currentPauseGate?.resolve();
+      },
+      subscribe: () => () => {},
+    });
     unregisterWorkflowExitCleanup = input.registerWorkflowExitCleanup(stageId, {
       skipForWorkflowExit(reason?: string): void {
         if (finalized) return;
@@ -176,6 +213,7 @@ export function buildPromptNodeUiAdapter(input: {
           descriptor.options as Parameters<typeof stageUiBroker.requestCustomUi>[3],
           mergedSignal.signal,
         );
+        await waitForExplicitResume();
         input.activeStore.recordStagePromptAnswer(input.runId, stageId, prompt, response, { answerSource: "workflow_ui" });
         finalizePromptStage("completed");
         return response;
@@ -233,6 +271,7 @@ export function buildPromptNodeUiAdapter(input: {
           },
         );
       });
+      await waitForExplicitResume();
       finalizePromptStage("completed");
       return response;
     } catch (err) {

package/dist/builtin/workflows/src/runs/foreground/executor-queued-user-message.ts

@@ -0,0 +1,75 @@
+import type { StageSessionEvent } from "./stage-runner-types.js";
+
+interface QueueSnapshot {
+  readonly steering: readonly string[];
+  readonly followUp: readonly string[];
+}
+
+function removedMessages(before: readonly string[], after: readonly string[]): string[] {
+  const remaining = [...after];
+  const removed: string[] = [];
+  for (const message of before) {
+    const index = remaining.indexOf(message);
+    if (index === -1) removed.push(message);
+    else remaining.splice(index, 1);
+  }
+  return removed;
+}
+
+function userMessageText(event: StageSessionEvent): string | undefined {
+  if (event.type !== "message_start" || event.message.role !== "user") return undefined;
+  const { content } = event.message;
+  if (typeof content === "string") return content;
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text)
+    .join("");
+}
+
+/**
+ * Arms only when a user message is consumed inside an SDK agent run. The
+ * prompt that starts a run is its first user message; later user messages are
+ * steering/follow-up deliveries. Queue-removal correlation also recognizes a
+ * queued message consumed as the first user message of a follow-on
+ * `agent.continue()` run.
+ *
+ * Queue additions and clears never arm by themselves. Candidate removals are
+ * retained across intervening events but discarded at run boundaries, which
+ * avoids both extension-event ordering races and stale matches in later idle
+ * prompts.
+ */
+export function createQueuedUserMessageConsumptionWatcher(
+  armContinuation: () => void,
+): (event: StageSessionEvent) => void {
+  let snapshot: QueueSnapshot = { steering: [], followUp: [] };
+  let consumptionCandidates: string[] = [];
+  let userMessageSeenInAgentRun = false;
+
+  return (event): void => {
+    if (event.type === "queue_update") {
+      consumptionCandidates.push(
+        ...removedMessages(snapshot.steering, event.steering),
+        ...removedMessages(snapshot.followUp, event.followUp),
+      );
+      snapshot = { steering: [...event.steering], followUp: [...event.followUp] };
+      return;
+    }
+    if (event.type === "agent_start") {
+      consumptionCandidates = [];
+      userMessageSeenInAgentRun = false;
+      return;
+    }
+    if (event.type === "agent_end") {
+      consumptionCandidates = [];
+      userMessageSeenInAgentRun = false;
+      return;
+    }
+
+    const text = userMessageText(event);
+    if (text === undefined) return;
+    const candidateIndex = consumptionCandidates.indexOf(text);
+    if (userMessageSeenInAgentRun || candidateIndex !== -1) armContinuation();
+    if (candidateIndex !== -1) consumptionCandidates.splice(candidateIndex, 1);
+    userMessageSeenInAgentRun = true;
+  };
+}