@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

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

@@ -11,6 +11,9 @@ 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 { withPromptCallerStack } from "../../shared/prompt-callsite-context.js";
+import type { DurableUiReplayRequest } from "../../durable/ui-primitive.js";
+import type { DurableStageTopology } from "../../durable/types.js";
 import {
   customPromptDescriptor,
   fallbackForPromptDescriptor,
@@ -22,6 +25,10 @@ import {
   type PromptDescriptor,
 } from "./executor-hil.js";
 
+export interface PromptNodeUiAdapter extends WorkflowUIContext {
+  replayDurable(request: DurableUiReplayRequest): Promise<void>;
+}
+
 export function buildPromptNodeUiAdapter(input: {
   readonly runId: string;
   readonly activeStore: Store;
@@ -35,8 +42,14 @@ export function buildPromptNodeUiAdapter(input: {
   readonly workflowExitSkippedReason: (reason?: string) => string;
   readonly preserveWorkflowExitSkippedReason: (stage: StageSnapshot, fallback: string) => void;
   readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
-}): WorkflowUIContext {
-  const ask = async <T>(descriptor: PromptDescriptor<T>): Promise<unknown> => {
+  readonly durableTopologyForReplayKey?: (replayKey: string) => DurableStageTopology | undefined;
+  /** Durably publish an unanswered prompt node before exposing its live wait. */
+  readonly onPendingStage?: (runId: string, snapshot: StageSnapshot) => Promise<void>;
+}): PromptNodeUiAdapter {
+  const ask = async <T>(
+    descriptor: PromptDescriptor<T>,
+    durableReplay?: DurableUiReplayRequest,
+  ): Promise<unknown> => {
     input.throwIfWorkflowExitSelected();
     const isCustom = isCustomPromptDescriptor(descriptor);
     if (input.signal.aborted) {
@@ -46,9 +59,10 @@ export function buildPromptNodeUiAdapter(input: {
     if (isCustom && descriptor.options?.signal?.aborted) throw hilAbortError(descriptor.options.signal);
 
     const prompt = makePrompt(descriptor);
-    const stageId = crypto.randomUUID();
-    const provisionalParentIds = input.tracker.onSpawn(stageId, descriptor.kind);
     const replayKey = promptReplayKey(descriptor);
+    const durableTopology = input.durableTopologyForReplayKey?.(replayKey);
+    const stageId = durableTopology?.stageId ?? crypto.randomUUID();
+    const provisionalParentIds = input.tracker.onSpawn(stageId, descriptor.kind);
     const replayDecision = input.replayIndex.decide({
       displayName: descriptor.kind,
       replayKey,
@@ -56,16 +70,21 @@ export function buildPromptNodeUiAdapter(input: {
       stageId,
       kind: "prompt",
     });
-    const parentIds = replayDecision.parentIds;
+    const parentIds = durableTopology?.parentIds ?? replayDecision.parentIds;
     if (!sameStringSet(parentIds, provisionalParentIds)) input.tracker.replaceParents(stageId, parentIds);
     const replaySource = replayDecision.source;
-    const replayAnswer = replayDecision.kind === "replay"
+    const continuationAnswer = replayDecision.kind === "replay"
       ? input.activeStore.getStagePromptAnswer(input.opts.continuation!.source.id, replayDecision.source.id)
       : undefined;
+    const replayAnswer = durableReplay === undefined
+      ? continuationAnswer
+      : { value: durableReplay.response };
     const shouldReplay = replayAnswer !== undefined;
-    if (shouldReplay) input.replayIndex.markPromptAnswerReplayed(stageId);
+    if (shouldReplay && durableReplay === undefined) input.replayIndex.markPromptAnswerReplayed(stageId);
     const replaySourceId = replaySource?.id;
-    const promptAnswerStatus = getPromptAnswerState(shouldReplay, replaySourceId, replayDecision.answerReplay);
+    const promptAnswerStatus = durableReplay === undefined
+      ? getPromptAnswerState(shouldReplay, replaySourceId, replayDecision.answerReplay)
+      : "available";
     const stageSnapshot: StageSnapshot = {
       id: stageId,
       name: descriptor.kind,
@@ -89,44 +108,48 @@ export function buildPromptNodeUiAdapter(input: {
       } : {}),
     };
     let finalized = false;
+    let finalization: Promise<void> | undefined;
     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);
-      input.activeStore.recordStageAttachable(input.runId, stageId, false);
-      input.activeStore.recordStageEnd(input.runId, stageSnapshot);
-      input.opts.onStageEnd?.(input.runId, stageSnapshot);
-      if (input.opts.persistence) {
-        appendStageEnd(input.opts.persistence, {
-          runId: input.runId,
-          stageId,
-          status: stageSnapshot.status,
-          durationMs: stageSnapshot.durationMs,
-          ...(stageSnapshot.error !== undefined ? { error: stageSnapshot.error } : {}),
-          ...(stageSnapshot.failureKind !== undefined ? { failureKind: stageSnapshot.failureKind } : {}),
-          ...(stageSnapshot.failureCode !== undefined ? { failureCode: stageSnapshot.failureCode } : {}),
-          ...(stageSnapshot.failureRecoverability !== undefined ? { failureRecoverability: stageSnapshot.failureRecoverability } : {}),
-          ...(stageSnapshot.failureDisposition !== undefined ? { failureDisposition: stageSnapshot.failureDisposition } : {}),
-          ...(stageSnapshot.failureMessage !== undefined ? { failureMessage: stageSnapshot.failureMessage } : {}),
-          ...(stageSnapshot.retryAfterMs !== undefined ? { retryAfterMs: stageSnapshot.retryAfterMs } : {}),
-          ...(stageSnapshot.skippedReason !== undefined ? { skippedReason: stageSnapshot.skippedReason } : {}),
-          ...stageReplayFields(stageSnapshot),
-        });
-      }
-      input.tracker.onSettle(stageId);
+    const finalizePromptStage = async (status: "completed" | "failed" | "skipped"): Promise<void> => {
+      if (finalization !== undefined) return finalization;
+      finalization = (async (): Promise<void> => {
+        finalized = true;
+        unregisterWorkflowExitCleanup();
+        unregisterStageControl();
+        const currentPauseGate = pauseGate;
+        pauseGate = undefined;
+        currentPauseGate?.resolve();
+        stageSnapshot.status = status;
+        stageSnapshot.endedAt = Date.now();
+        stageSnapshot.durationMs = elapsedStageMs(stageSnapshot, stageSnapshot.endedAt);
+        input.activeStore.recordStageAttachable(input.runId, stageId, false);
+        input.activeStore.recordStageEnd(input.runId, stageSnapshot);
+        await input.opts.onStageEnd?.(input.runId, stageSnapshot);
+        if (input.opts.persistence) {
+          appendStageEnd(input.opts.persistence, {
+            runId: input.runId,
+            stageId,
+            status: stageSnapshot.status,
+            durationMs: stageSnapshot.durationMs,
+            ...(stageSnapshot.error !== undefined ? { error: stageSnapshot.error } : {}),
+            ...(stageSnapshot.failureKind !== undefined ? { failureKind: stageSnapshot.failureKind } : {}),
+            ...(stageSnapshot.failureCode !== undefined ? { failureCode: stageSnapshot.failureCode } : {}),
+            ...(stageSnapshot.failureRecoverability !== undefined ? { failureRecoverability: stageSnapshot.failureRecoverability } : {}),
+            ...(stageSnapshot.failureDisposition !== undefined ? { failureDisposition: stageSnapshot.failureDisposition } : {}),
+            ...(stageSnapshot.failureMessage !== undefined ? { failureMessage: stageSnapshot.failureMessage } : {}),
+            ...(stageSnapshot.retryAfterMs !== undefined ? { retryAfterMs: stageSnapshot.retryAfterMs } : {}),
+            ...(stageSnapshot.skippedReason !== undefined ? { skippedReason: stageSnapshot.skippedReason } : {}),
+            ...stageReplayFields(stageSnapshot),
+          });
+        }
+        input.tracker.onSettle(stageId);
+      })();
+      return finalization;
     };
 
     input.activeStore.recordStageStart(input.runId, stageSnapshot);
@@ -158,8 +181,11 @@ export function buildPromptNodeUiAdapter(input: {
       subscribe: () => () => {},
     });
     unregisterWorkflowExitCleanup = input.registerWorkflowExitCleanup(stageId, {
-      skipForWorkflowExit(reason?: string): void {
-        if (finalized) return;
+      async skipForWorkflowExit(reason?: string): Promise<void> {
+        if (finalized) {
+          await finalization;
+          return;
+        }
         stageSnapshot.skippedReason = input.workflowExitSkippedReason(reason);
         if (!shouldReplay) {
           stageUiBroker.cancelStagePrompt(
@@ -168,7 +194,7 @@ export function buildPromptNodeUiAdapter(input: {
             new Error(`atomic-workflows: prompt ${stageId} skipped by workflow exit`),
           );
         }
-        finalizePromptStage("skipped");
+        await finalizePromptStage("skipped");
       },
     });
     if (input.opts.persistence) {
@@ -184,15 +210,23 @@ export function buildPromptNodeUiAdapter(input: {
     if (shouldReplay) {
       await Promise.resolve();
       input.throwIfWorkflowExitSelected();
-      finalizePromptStage("completed");
+      await finalizePromptStage("completed");
       return replayAnswer.value;
     }
 
+    try {
+      await input.onPendingStage?.(input.runId, stageSnapshot);
+    } catch (err) {
+      applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(err));
+      await finalizePromptStage("failed");
+      throw err;
+    }
+
     if (isCustom) {
       if (descriptor.options?.overlay === true) {
         const error = new Error("atomic-workflows: ctx.ui.custom overlay mode is unavailable in the workflow graph viewer");
         applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(error));
-        finalizePromptStage("failed");
+        await finalizePromptStage("failed");
         throw error;
       }
 
@@ -203,7 +237,7 @@ export function buildPromptNodeUiAdapter(input: {
         if (!accepted) {
           const error = new Error("atomic-workflows: ctx.ui.custom prompt node is unavailable");
           stageSnapshot.skippedReason = "prompt-unavailable";
-          finalizePromptStage("skipped");
+          await finalizePromptStage("skipped");
           throw error;
         }
         const response = await stageUiBroker.requestCustomUi(
@@ -215,19 +249,19 @@ export function buildPromptNodeUiAdapter(input: {
         );
         await waitForExplicitResume();
         input.activeStore.recordStagePromptAnswer(input.runId, stageId, prompt, response, { answerSource: "workflow_ui" });
-        finalizePromptStage("completed");
+        await finalizePromptStage("completed");
         return response;
       } catch (err) {
         input.activeStore.recordStageAwaitingInput(input.runId, stageId, false);
         stageUiBroker.cancelStagePrompt(input.runId, stageId, err);
         if (mergedSignal.signal.aborted) {
           input.preserveWorkflowExitSkippedReason(stageSnapshot, input.signal.aborted ? "run-aborted" : "prompt-aborted");
-          finalizePromptStage("skipped");
+          await finalizePromptStage("skipped");
           throw hilAbortError(mergedSignal.signal);
         }
         if (!finalized) {
           applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(err));
-          finalizePromptStage("failed");
+          await finalizePromptStage("failed");
         }
         throw err;
       } finally {
@@ -238,7 +272,7 @@ export function buildPromptNodeUiAdapter(input: {
     const accepted = input.activeStore.recordStagePendingPrompt(input.runId, stageId, prompt);
     if (!accepted) {
       stageSnapshot.skippedReason = "prompt-unavailable";
-      finalizePromptStage("skipped");
+      await finalizePromptStage("skipped");
       return fallbackForPromptDescriptor(descriptor);
     }
 
@@ -272,21 +306,36 @@ export function buildPromptNodeUiAdapter(input: {
         );
       });
       await waitForExplicitResume();
-      finalizePromptStage("completed");
+      await finalizePromptStage("completed");
       return response;
     } catch (err) {
       if (input.signal.aborted) {
         input.preserveWorkflowExitSkippedReason(stageSnapshot, "run-aborted");
-        finalizePromptStage("skipped");
+        await finalizePromptStage("skipped");
       } else {
         applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(err));
-        finalizePromptStage("failed");
+        await finalizePromptStage("failed");
       }
       throw err;
     }
   };
 
   return {
+    async replayDurable(request: DurableUiReplayRequest): Promise<void> {
+      await withPromptCallerStack(request.callerStack, async () => {
+        if (request.kind === "input") {
+          await ask({ kind: "input", message: request.promptText }, request);
+        } else if (request.kind === "confirm") {
+          await ask({ kind: "confirm", message: request.message }, request);
+        } else if (request.kind === "select") {
+          await ask({ kind: "select", message: request.message, choices: request.options }, request);
+        } else if (request.kind === "editor") {
+          await ask({ kind: "editor", message: "Edit and save to continue.", initial: request.initial }, request);
+        } else {
+          await ask(customPromptDescriptor(request.factory, request.options), request);
+        }
+      });
+    },
     async input(promptText: string): Promise<string> {
       const response = await ask({ kind: "input", message: promptText });
       return typeof response === "string" ? response : String(response ?? "");

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

@@ -84,11 +84,14 @@ export function createTrackedStageCaller(input: {
         reason,
         gateEnabled: readinessGateEnabled,
         aborted: runtime.signal.aborted,
-      })) {
-        continue;
+      }) || skipResumeContinuationInjection()) continue;
+      const suppressQueuedContinuation = reason === "paused-queued-user-message";
+      if (suppressQueuedContinuation) runtime.state.suppressQueuedUserMessageContinuation = true;
+      try {
+        result = await raceAbort(runtime.innerCtx.prompt(RESUME_CONTINUATION_PROMPT), runtime.signal) as T;
+      } finally {
+        if (suppressQueuedContinuation) runtime.state.suppressQueuedUserMessageContinuation = false;
       }
-      if (skipResumeContinuationInjection()) continue;
-      result = await raceAbort(runtime.innerCtx.prompt(RESUME_CONTINUATION_PROMPT), runtime.signal) as T;
       captureChatAnswer();
     }
     captureChatAnswer();
@@ -186,8 +189,12 @@ export function createTrackedStageCaller(input: {
               runtime.state.chatAnswerObservedThisTurn = false;
               runtime.state.waitingForStageChatTurn = true;
               try {
-                await raceAbort(new Promise<void>((resolve) => { resolveNextTurnEnd = resolve; }), runtime.signal);
+                await raceAbort(new Promise<void>((resolve) => {
+                  resolveNextTurnEnd = resolve;
+                  runtime.state.wakeWaitingForStageChatTurn = resolve;
+                }), runtime.signal);
               } finally {
+                runtime.state.wakeWaitingForStageChatTurn = undefined;
                 runtime.state.waitingForStageChatTurn = false;
               }
               if (runtime.signal.aborted) break;
@@ -198,6 +205,7 @@ export function createTrackedStageCaller(input: {
               if (runtime.innerCtx.__structuredOutputFinalized()) break;
             }
           } finally {
+            runtime.state.wakeWaitingForStageChatTurn = undefined;
             resolveNextTurnEnd = null;
             unsubscribeTurnWatcher();
           }

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

@@ -1,21 +1,31 @@
 import type { StageControlHandle, AgentSessionEventListener } from "./stage-control-registry.js";
 import type { LiveStageRuntime } from "./executor-stage-types.js";
-import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
+import type { StageUserMessageDeliveryAction, StageUserMessagePreparation } from "./stage-runner-types.js";
 import { isTerminalStage } from "./executor-scheduler.js";
 import { StageToolExecutionBuffer } from "./stage-tool-execution-buffer.js";
 
 export function createStageControlHandle(runtime: LiveStageRuntime): StageControlHandle {
-  const ensureMessagingSession = async (): Promise<void> => {
+  const messagePreparation = (): StageUserMessagePreparation => {
     const meta = runtime.innerCtx.__sessionMeta();
-    if (meta.sessionId !== undefined || meta.sessionFile !== undefined) return;
+    if (meta.sessionId !== undefined || meta.sessionFile !== undefined) {
+      return { beforePreparation: runtime.throwIfStageMutationBlocked };
+    }
     if (runtime.stageSnapshot.sessionFile !== undefined) {
-      await runtime.innerCtx.__ensureSessionFromFile(runtime.stageSnapshot.sessionFile);
-      runtime.captureStageSessionMeta();
-      return;
+      return {
+        sessionFile: runtime.stageSnapshot.sessionFile,
+        beforePreparation: runtime.throwIfStageMutationBlocked,
+      };
     }
     if (isTerminalStage(runtime.stageSnapshot)) {
       throw new Error(`atomic-workflows: cannot message stage "${runtime.name}" because no retained session metadata is available.`);
     }
+    return { beforePreparation: runtime.throwIfStageMutationBlocked };
+  };
+  const ensureMessagingSession = async (): Promise<void> => {
+    const sessionFile = messagePreparation().sessionFile;
+    if (sessionFile === undefined) return;
+    await runtime.innerCtx.__ensureSessionFromFile(sessionFile);
+    runtime.captureStageSessionMeta();
   };
   const toolExecutions = new StageToolExecutionBuffer();
   const unsubscribeToolExecutions = runtime.innerCtx.subscribe((event) => toolExecutions.record(event));
@@ -55,15 +65,19 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
       runtime.throwIfStageMutationBlocked();
       runtime.captureStageSessionMeta();
     },
-    async sendUserMessage(text, options) {
-      runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
+    async sendUserMessage(text, options, beforeDelivery) {
       runtime.throwIfStageMutationBlocked();
+      const preparation = messagePreparation();
+      const admitDelivery = (): void => {
+        runtime.throwIfStageMutationBlocked();
+        beforeDelivery?.();
+      };
       try {
         const action = await runtime.innerCtx.__sendUserMessage(
           text,
           options,
-          runtime.throwIfStageMutationBlocked,
+          admitDelivery,
+          preparation,
         );
         if (action === "steer" || action === "followUp") {
           runtime.state.resumeContinuationPending = "queued-user-message";
@@ -75,13 +89,14 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     },
     async prompt(text: string) {
       runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
+      const preparation = messagePreparation();
       let action: StageUserMessageDeliveryAction | undefined;
       try {
         action = await runtime.innerCtx.__sendUserMessage(
           text,
           undefined,
           runtime.throwIfStageMutationBlocked,
+          preparation,
         );
       } finally {
         runtime.captureStageSessionMeta();
@@ -138,7 +153,7 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
       // pause-adjusted stage elapsed time even inside the normal 30s bucket.
       await runtime.captureStageSessionMeta({ forceDurable: true });
     },
-    async resume(message?: string) {
+    async resume(message?: string, beforeResume?: () => void) {
       runtime.throwIfStageMutationBlocked();
       await ensureMessagingSession();
       runtime.throwIfStageMutationBlocked();
@@ -147,10 +162,23 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
       const hasMessage = typeof message === "string" && message.trim().length > 0;
       const resumeMessage = hasMessage ? message : undefined;
       const queuedResumeContinuation = wasPausedBeforeResume && !resumesIdleStageChat;
-      const addedResumeContinuation = queuedResumeContinuation && runtime.state.resumeContinuationPending === false;
-      if (addedResumeContinuation) runtime.state.resumeContinuationPending = "resume";
+      const previousResumeContinuation = runtime.state.resumeContinuationPending;
+      let resumeContinuationChanged = false;
+      let wakeReleasedIdleStageChat = false;
       try {
-        await runtime.innerCtx.__resume(resumesIdleStageChat ? undefined : resumeMessage);
+        await runtime.innerCtx.__resume(
+          resumesIdleStageChat ? undefined : resumeMessage,
+          ({ releasedQueuedMessages, runnerOwnedDeliveryPending }) => {
+            if (runnerOwnedDeliveryPending) return;
+            if (!releasedQueuedMessages && !queuedResumeContinuation) return;
+            resumeContinuationChanged = true;
+            runtime.state.resumeContinuationPending = releasedQueuedMessages
+              ? "paused-queued-user-message"
+              : previousResumeContinuation === false ? "resume" : previousResumeContinuation;
+            wakeReleasedIdleStageChat = resumesIdleStageChat && releasedQueuedMessages;
+          },
+          beforeResume,
+        );
         const changed = runtime.activeStore.recordStageResumed(runtime.runId, runtime.stageId);
         if (changed) {
           runtime.scheduler.releaseStageBarrier(runtime.stageId);
@@ -159,6 +187,7 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
           // resume succeeds, the run is active even if sibling stages remain paused.
           runtime.activeStore.recordRunResumed(runtime.runId);
         }
+        if (wakeReleasedIdleStageChat) runtime.state.wakeWaitingForStageChatTurn?.();
         if (resumesIdleStageChat && hasMessage) {
           runtime.throwIfStageMutationBlocked();
           return await runtime.innerCtx.__sendUserMessage(
@@ -168,8 +197,8 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
           );
         }
       } catch (err) {
-        if (addedResumeContinuation && runtime.state.resumeContinuationPending === "resume") {
-          runtime.state.resumeContinuationPending = false;
+        if (resumeContinuationChanged) {
+          runtime.state.resumeContinuationPending = previousResumeContinuation;
         }
         throw err;
       } finally {
@@ -179,6 +208,9 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     subscribe(listener: AgentSessionEventListener) {
       return runtime.innerCtx.subscribe(listener);
     },
+    subscribeDeliveryActivity(listener) {
+      return runtime.innerCtx.__subscribeDeliveryActivity(listener);
+    },
     async dispose() {
       unsubscribeToolExecutions();
       toolExecutions.clear();

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

@@ -30,6 +30,7 @@ import { createQueuedUserMessageConsumptionWatcher } from "./executor-queued-use
 
 export function createWorkflowStageFactory(input: {
   readonly runId: string;
+  readonly workflowIntercomGroup: string;
   readonly activeStore: Store;
   readonly opts: EngineStageRuntimeOptions;
   readonly adapters: StageAdapters;
@@ -49,9 +50,10 @@ export function createWorkflowStageFactory(input: {
   return (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope): StageContextWithMeta => {
     input.exit.throwIfWorkflowExitSelected();
     options = stageOptionsWithGitWorktree(stageOptionsWithInputDefaults(options, input.inputRuntimeDefaults), input.workflowInvocationCwd, input.gitWorktreeSetupCache);
-    const stageId = crypto.randomUUID();
+    const stageId = options?.durableStageId ?? crypto.randomUUID();
     const provisionalParentIds = input.tracker.onSpawn(stageId, name);
-    const scopedParentIds = input.opts.continuation === undefined ? stageFailFastScope?.parentIds : undefined;
+    const scopedParentIds = options?.durableParentIds
+      ?? (input.opts.continuation === undefined ? stageFailFastScope?.parentIds : undefined);
     const initialParentIds = scopedParentIds === undefined ? provisionalParentIds : [...scopedParentIds];
     if (scopedParentIds !== undefined && !sameStringSet(scopedParentIds, provisionalParentIds)) {
       input.tracker.replaceParents(stageId, scopedParentIds);
@@ -65,7 +67,7 @@ export function createWorkflowStageFactory(input: {
       stageId,
       kind: "stage",
     });
-    const parentIds = replayDecision.parentIds;
+    const parentIds = options?.durableParentIds ?? replayDecision.parentIds;
     if (!sameStringSet(parentIds, provisionalParentIds)) input.tracker.replaceParents(stageId, parentIds);
     const replaySource = replayDecision.kind === "replay" ? replayDecision.source : undefined;
     const executeReplaySource = replayDecision.kind === "execute" ? replayDecision.source : undefined;
@@ -131,6 +133,7 @@ export function createWorkflowStageFactory(input: {
       stageName: name,
       adapters: input.adapters,
       runId: input.runId,
+      workflowIntercomGroup: input.workflowIntercomGroup,
       signal: input.signal,
       stageOptions: stageOptionsForContext,
       models: input.opts.models,
@@ -147,7 +150,9 @@ export function createWorkflowStageFactory(input: {
       askUserQuestionObservedThisTurn: false,
       chatAnswerObservedThisTurn: false,
       resumeContinuationPending: false,
+      suppressQueuedUserMessageContinuation: false,
       waitingForStageChatTurn: false,
+      wakeWaitingForStageChatTurn: undefined,
       liveHandleReleased: false,
       stageClosedByWorkflowExit: false,
       stageFinalized: false,
@@ -183,7 +188,9 @@ export function createWorkflowStageFactory(input: {
     });
     const unsubscribeQueuedUserMessageWatcher = innerCtx.subscribe(
       createQueuedUserMessageConsumptionWatcher(() => {
-        state.resumeContinuationPending = "queued-user-message";
+        if (!state.suppressQueuedUserMessageContinuation) {
+          state.resumeContinuationPending = "queued-user-message";
+        }
       }),
     );
 

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

@@ -100,6 +100,7 @@ export function createReplayStageContext(input: {
     steer: async () => rejectReplayMutation("steer"),
     followUp: async () => rejectReplayMutation("follow up"),
     subscribe: () => () => {},
+    __subscribeDeliveryActivity: () => () => {},
     get sessionFile() { return replaySource.sessionFile; },
     get sessionId() { return replaySource.sessionId ?? ""; },
     setModel: async () => rejectReplayMutation("set model"),

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

@@ -14,14 +14,17 @@ export interface StageMcpScope {
   clear(): void;
 }
 
-export type ResumeContinuationReason = "resume" | "queued-user-message";
+export type ResumeContinuationReason = "resume" | "queued-user-message" | "paused-queued-user-message";
 
 export interface LiveStageMutableState {
   activeAskUserQuestionAnonymousCalls: number;
   askUserQuestionObservedThisTurn: boolean;
   chatAnswerObservedThisTurn: boolean;
   resumeContinuationPending: false | ResumeContinuationReason;
+  suppressQueuedUserMessageContinuation: boolean;
   waitingForStageChatTurn: boolean;
+  /** Wakes the executor so a paused idle stage-chat can drain released work. */
+  wakeWaitingForStageChatTurn: (() => void) | undefined;
   liveHandleReleased: boolean;
   stageClosedByWorkflowExit: boolean;
   stageFinalized: boolean;

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

@@ -9,7 +9,7 @@ import type {
   WorkflowMcpPort,
   WorkflowModelCatalogPort,
 } from "../../shared/types.js";
-import type { RunStatus, RunSnapshot, StageSnapshot, WorkflowOverlayAdapter } from "../../shared/store-types.js";
+import type { RunStatus, RunSnapshot, StageSnapshot, ToolNodeSnapshot, WorkflowOverlayAdapter } from "../../shared/store-types.js";
 import type { Store } from "../../shared/store.js";
 import type { WorkflowRegistry } from "../../workflows/registry.js";
 import type { CancellationRegistry } from "../background/cancellation-registry.js";
@@ -89,6 +89,8 @@ export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "s
    * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
    */
   durableBackend?: import("../../durable/backend.js").DurableWorkflowBackend;
+  /** Internal physical backend used to reconstruct full nested topology through stacked scopes. */
+  durableRootBackend?: import("../../durable/backend.js").DurableWorkflowBackend;
   /**
    * Durable scope for a child workflow run. When set, the child's internal
    * `ctx.tool`/`ctx.ui`/`ctx.stage` checkpoints are routed under the root
@@ -116,10 +118,14 @@ export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutpu
   readonly status: RunStatus;
   readonly result?: Partial<TOutputs>;
   readonly error?: string;
+  /** Tool node whose rejection supplied the selected terminal failure. */
+  readonly failedToolNodeId?: string;
   /** True when the run reached its terminal status through ctx.exit(). */
   readonly exited?: boolean;
   readonly exitReason?: string;
   readonly stages: StageSnapshot[];
+  /** Always populated by the runtime; optional for legacy structural literals. */
+  readonly toolNodes?: ToolNodeSnapshot[];
 }
 
 export interface ParallelFailFastStage {