@bastani/atomic 0.9.3-alpha.1 → 0.9.3-alpha.3

package/dist/builtin/workflows/src/extension/extension-runtime-state.ts

@@ -141,6 +141,9 @@ export function createWorkflowExtensionRuntimeState(
     dispatch(args, options) { return runtimeRef.current.dispatch(args, options); },
     runDirect(args, options) { return runtimeRef.current.runDirect(args, options); },
     resumeFailedRun(sourceRunId, stageId, options) { return runtimeRef.current.resumeFailedRun(sourceRunId, stageId, options); },
+    resumeDurableWorkflow(workflowIdOrPrefix, options) { return runtimeRef.current.resumeDurableWorkflow(workflowIdOrPrefix, options); },
+    listDurableResumable(sessionDir) { return runtimeRef.current.listDurableResumable(sessionDir); },
+    prepareDurableResumable(workflowIdOrPrefix, sessionDir) { return runtimeRef.current.prepareDurableResumable(workflowIdOrPrefix, sessionDir); },
   };
 
   function workflowModelCatalogFromContext(ctx?: PiModelContext): WorkflowModelCatalogPort | undefined {

package/dist/builtin/workflows/src/extension/runtime.ts

@@ -43,6 +43,10 @@ import { runDetached } from "../runs/background/runner.js";
 import type { JobTracker } from "../runs/background/job-tracker.js";
 import { appendRunEnd } from "../shared/persistence-session-entries.js";
 import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
+import { resumeDurableWorkflow as resumeDurableWorkflowAdapter, prepareRuntimeDurableResumable, isBackendTerminal, type ResumeDurableDeps, type ResumeDurableResult } from "../durable/resume-runtime.js";
+import { getDurableBackend, initializeDbosDurableBackendFromEnv } from "../durable/factory.js";
+import { scanResumableWorkflows } from "../durable/resume-catalog.js";
+import type { ResumableWorkflowEntry } from "../durable/types.js";
 import { directMode, directModelRequests, directOptions, directProgressTotal } from "./runtime-direct.js";
 
 // ---------------------------------------------------------------------------
@@ -87,11 +91,9 @@ export interface ExtensionRuntimeOpts {
   /** Resolve the host's non-default session directory for workflow stage transcripts. */
   resolveDefaultStageSessionDir?: () => string | undefined;
 }
-
 // ---------------------------------------------------------------------------
 // Public interface
 // ---------------------------------------------------------------------------
-
 export type ResumeFailedRunResult =
   | { ok: true; runId: string; sourceRunId: string; resumeFromStageId: string; message: string }
   | { ok: false; reason: "run_not_found" | "not_resumable" | "workflow_not_found" | "insufficient_state"; message: string };
@@ -114,12 +116,21 @@ export interface ExtensionRuntime {
 
   /** Start a linked continuation for a failed resumable named workflow run. */
   resumeFailedRun(sourceRunId: string, stageId?: string, options?: RuntimeDispatchOptions): ResumeFailedRunResult;
-}
 
+  /**
+   * Resume a durable workflow by top-level workflow id when no live run exists.
+   * Re-dispatches the workflow with the cached inputs and original workflow id
+   * so durable checkpoints replay (skipping completed side effects).
+   *
+   * cross-ref: issue #1498 — cross-session /workflow resume selector.
+   */
+  resumeDurableWorkflow(workflowIdOrPrefix: string, options?: RuntimeDispatchOptions): import("../durable/resume-runtime.js").ResumeDurableResult;
+  listDurableResumable(sessionDir?: string): readonly import("../durable/types.js").ResumableWorkflowEntry[];
+  prepareDurableResumable(workflowIdOrPrefix?: string, sessionDir?: string): Promise<readonly import("../durable/types.js").ResumableWorkflowEntry[]>;
+}
 export interface RuntimeDispatchOptions {
   readonly policy?: WorkflowExecutionPolicy;
 }
-
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -150,6 +161,9 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
   const jobs = opts.jobs;
   const runtimeCwd = opts.cwd ?? process.cwd();
   const resolveDefaultStageSessionDir = opts.resolveDefaultStageSessionDir;
+  const dbosReady = initializeDbosDurableBackendFromEnv().catch((err) => process.emitWarning(`Atomic workflow DBOS durability unavailable; using file-backed durability: ${err instanceof Error ? err.message : String(err)}`));
+  const ensureDbosReady = async (): Promise<void> => { await dbosReady; };
+  let preparedDurableCatalog: readonly ResumableWorkflowEntry[] = [];
 
   function runOptions(args: WorkflowToolArgs, policy?: WorkflowExecutionPolicy): RunOpts {
     const argConcurrency =
@@ -182,14 +196,12 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       cwd: runtimeCwd,
     };
   }
-
   function explicitIntercomDelivery(args: WorkflowToolArgs): WorkflowIntercomDelivery | undefined {
     if (args.intercom?.enabled === false) return "off";
     if (args.intercom?.delivery !== undefined) return args.intercom.delivery;
     if (args.intercom?.enabled === true) return "control-and-result";
     return undefined;
   }
-
   function effectiveIntercomDelivery(args: WorkflowToolArgs, mode: WorkflowDetails["mode"]): WorkflowIntercomDelivery {
     const explicit = explicitIntercomDelivery(args);
     if (explicit !== undefined) return explicit;
@@ -202,7 +214,6 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     }
     return "off";
   }
-
   function intercomParentSession(args: WorkflowToolArgs): string | undefined {
     if (args.intercom?.parentSession !== undefined) return args.intercom.parentSession;
     if (typeof intercom?.parentSession === "function") return intercom.parentSession();
@@ -371,6 +382,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
   }
 
   async function runDirectAsync(args: WorkflowToolArgs, policy?: WorkflowExecutionPolicy): Promise<WorkflowDetails> {
+    await ensureDbosReady();
     const runId = crypto.randomUUID();
     const mode = directMode(args);
     const delivery = effectiveIntercomDelivery(args, mode);
@@ -423,7 +435,8 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       return registry;
     },
 
-    dispatch(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowToolResult> {
+    async dispatch(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowToolResult> {
+      await ensureDbosReady();
       const defaultSessionDir = resolveDefaultStageSessionDir?.();
       return dispatch(args, {
         registry,
@@ -441,7 +454,8 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       });
     },
 
-    runDirect(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowDetails> {
+    async runDirect(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowDetails> {
+      await ensureDbosReady();
       const policy = options?.policy ?? INTERACTIVE_WORKFLOW_POLICY;
       if (args.async === true && policy.awaitTerminalRun !== true) {
         return runDirectAsync(args, policy);
@@ -457,5 +471,30 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     },
 
     resumeFailedRun,
+
+    resumeDurableWorkflow(workflowIdOrPrefix: string, options?: RuntimeDispatchOptions): ResumeDurableResult {
+      const adapterDeps: ResumeDurableDeps = {
+        registry,
+        baseRunOpts: runOptions({ workflow: "", inputs: {} }, options?.policy),
+        durableBackend: getDurableBackend(),
+      };
+      return resumeDurableWorkflowAdapter(workflowIdOrPrefix, adapterDeps, preparedDurableCatalog);
+    },
+    listDurableResumable(sessionDir?: string): readonly ResumableWorkflowEntry[] {
+      const backend = getDurableBackend();
+      const live = backend.listResumableWorkflows();
+      const dir = sessionDir ?? resolveDefaultStageSessionDir?.();
+      if (dir === undefined) return live;
+      const scanned = scanResumableWorkflows(dir);
+      const liveIds = new Set(live.map((e) => e.workflowId));
+      const compatible = scanned.filter((e) => !liveIds.has(e.workflowId) && backend.getWorkflow(e.workflowId) !== undefined && !isBackendTerminal(backend, e.workflowId));
+      return [...live, ...compatible];
+    },
+
+    async prepareDurableResumable(workflowIdOrPrefix?: string, sessionDir?: string): Promise<readonly ResumableWorkflowEntry[]> {
+      await ensureDbosReady();
+      preparedDurableCatalog = await prepareRuntimeDurableResumable(getDurableBackend, () => resolveDefaultStageSessionDir?.(), workflowIdOrPrefix, sessionDir);
+      return preparedDurableCatalog;
+    },
   };
 }

package/dist/builtin/workflows/src/extension/workflow-run-control-command.ts

@@ -5,6 +5,7 @@ import { store } from "../shared/store.js";
 import { topLevelWorkflowRuns } from "../shared/run-visibility.js";
 import { renderSessionList } from "../tui/session-list.js";
 import { openKillConfirm, openSessionPicker } from "../tui/session-overlays.js";
+import { openWorkflowResumeSelector } from "../tui/workflow-resume-selector.js";
 import { deriveGraphTheme } from "../tui/graph-theme.js";
 import { emitChatSurface } from "../tui/chat-surface-message.js";
 import type { GraphOverlayPort } from "../tui/overlay-adapter.js";
@@ -13,6 +14,8 @@ import type { ExtensionAPI, PiCommandContext } from "./public-types.js";
 import type { WorkflowCommandReporter } from "./workflow-command-utils.js";
 import { stripYesFlag } from "./workflow-command-utils.js";
 import { workflowPolicyFromContext } from "./workflow-policy.js";
+import { formatResumableWorkflowList } from "../durable/resume-catalog.js";
+import type { ResumableWorkflowEntry } from "../durable/types.js";
 import {
   formatAlreadyEndedRetainedMessage,
   overlaySurfaceFromContext,
@@ -37,6 +40,75 @@ function resolveAttachStageId(runId: string, stageTarget: string | undefined): s
   return byName?.id ?? false;
 }
 
+function filterSelectorDurableEntries(
+  runtime: ExtensionRuntime,
+  entries: readonly ResumableWorkflowEntry[],
+): readonly ResumableWorkflowEntry[] {
+  const registry = runtime.registry as { has(name: string): boolean } | undefined;
+  if (registry === undefined) return entries;
+  return entries.filter((entry) => {
+    const requiresCurrentDefinition = entry.status === "running" || entry.status === "failed" || entry.status === "blocked";
+    return !requiresCurrentDefinition || registry.has(entry.name);
+  });
+}
+
+
+async function handleDurableResume(
+  target: string | undefined,
+  ctx: PiCommandContext,
+  reporter: WorkflowCommandReporter,
+  deps: WorkflowRunControlDeps,
+): Promise<boolean> {
+  const print = (msg: string): void => reporter.info(msg);
+  const fail = (msg: string): void => reporter.error(msg);
+  const runtime = deps.runtimeForContext(ctx);
+  const policy = workflowPolicyFromContext(ctx);
+  // Hydrate the durable backend from DBOS (if configured) before listing so a
+  // fresh process discovers workflows persisted by a prior session.
+  const prepared = await runtime.prepareDurableResumable(target);
+  const durable = filterSelectorDurableEntries(runtime, prepared);
+  if (target !== undefined) {
+    // Attempt resume by id/prefix against the durable catalog.
+    const result = runtime.resumeDurableWorkflow(target, { policy });
+    if (result.ok) {
+      print(result.message);
+      // Open/connect the overlay to the resumed run, analogous to live resume.
+      if (policy.allowInputPicker) deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
+      return true;
+    }
+    // Not a durable workflow either — surface the catalog for discovery.
+    if (durable.length > 0) {
+      fail(`${result.message}\n\n${formatResumableWorkflowList(durable)}`);
+    } else {
+      fail(result.message);
+    }
+    return true;
+  }
+  // No target: show the durable selector when interactive, otherwise print.
+  if (durable.length === 0) {
+    fail("No resumable durable workflows found. Usage: /workflow resume <id> (or /resume for Atomic sessions).");
+    return true;
+  }
+  if (!policy.allowInputPicker) {
+    print(`${formatResumableWorkflowList(durable)}\n\nResume with: /workflow resume <id>`);
+    return true;
+  }
+  const picked = await openWorkflowResumeSelector(ctx.ui, [], durable);
+  if (picked.kind === "durable") {
+    const result = runtime.resumeDurableWorkflow(picked.workflowId, { policy });
+    if (result.ok) {
+      print(result.message);
+      if (policy.allowInputPicker) deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
+    } else {
+      fail(result.message);
+    }
+  }
+  if (picked.kind !== "durable") {
+    print(`${formatResumableWorkflowList(durable)}\n\nResume with: /workflow resume <id>`);
+  }
+  return true;
+}
+
 export async function handleRunControlCommand(
   action: "connect" | "interrupt" | "kill" | "attach" | "pause" | "resume",
   rest: string[],
@@ -115,7 +187,7 @@ export async function handleRunControlCommand(
     }
     if (failHeadlessAttachCommand("connect", resolved.runId)) return true;
     if (policy.allowInputPicker) deps.overlay.open(resolved.runId, overlaySurfaceFromContext(ctx));
-    print(`Attached to ${resolved.runId.slice(0, 8)}. h/ctrl+d hide · q kill · esc close.`);
+    print(`Attached to ${resolved.runId.slice(0, 8)}. h/ctrl+d hide · q quit (resumable via /workflow resume) · esc close.`);
     return true;
   }
 
@@ -206,10 +278,64 @@ export async function handleRunControlCommand(
         if (action === "pause") {
           const active = topLevelWorkflowRuns(store.runs()).filter((r) => r.endedAt === undefined);
           fail(active.length === 0 ? "No active runs to pause." : `Picker requires an interactive UI surface. Active runs:\n${active.map((r) => `  ${r.id.slice(0, 8)}  ${r.name}`).join("\n")}\n\nUsage: /workflow pause <runId> [stageId]`);
+        } else if (action === "attach") {
+          fail(`${renderSessionList(store.runs(), { theme, includeAll: true })}\n\nPicker requires an interactive UI surface. Pass a runId: /workflow attach <id> [stageId]`);
         } else {
-          fail(action === "attach"
-            ? `${renderSessionList(store.runs(), { theme, includeAll: true })}\n\nPicker requires an interactive UI surface. Pass a runId: /workflow attach <id> [stageId]`
-            : "Usage: /workflow resume <runId> [stageId] [message…]");
+          // resume: show cross-session durable catalog in headless/print mode.
+          return await handleDurableResume(undefined, ctx, reporter, deps);
+        }
+        return true;
+      }
+      if (action === "resume") {
+        // Only inactive workflows belong in the resume selector. Live runs:
+        // show paused (quit) or recoverably-failed runs; actively-running live
+        // runs are hidden (resuming one that is executing would double-dispatch).
+        const liveRuns = topLevelWorkflowRuns(store.runs()).filter((run) =>
+          run.status === "paused" || (run.status === "failed" && run.resumable !== false),
+        );
+        // Durable entries: a `running` durable handle may be a crashed process
+        // (cross-session crash recovery), so it stays selectable UNLESS it
+        // matches an actively-executing live run in this session.
+        const activeLiveIds = new Set(
+          topLevelWorkflowRuns(store.runs())
+            .filter((run) => run.endedAt === undefined && run.status === "running" && run.exitReason !== "quit")
+            .map((run) => run.id),
+        );
+        const runtime = deps.runtimeForContext(ctx);
+        let durableEntries: readonly ResumableWorkflowEntry[] = [];
+        try {
+          const prepared = await runtime.prepareDurableResumable(undefined);
+          durableEntries = filterSelectorDurableEntries(runtime, prepared)
+            .filter((entry) => !activeLiveIds.has(entry.workflowId));
+        } catch (error) {
+          if (liveRuns.length === 0) {
+            const message = error instanceof Error ? error.message : String(error);
+            fail(`Failed to list resumable workflows: ${message}`);
+            return true;
+          }
+        }
+        const picked = await openWorkflowResumeSelector(ctx.ui, liveRuns, durableEntries);
+        if (picked.kind === "durable") return await handleDurableResume(picked.workflowId, ctx, reporter, deps);
+        if (picked.kind === "live") {
+          const resolved = resolveRunIdPrefix(picked.runId);
+          if (resolved.kind !== "exact") {
+            fail(`Run not found: ${picked.runId}`);
+            return true;
+          }
+          const run = store.runs().find((r) => r.id === resolved.runId);
+          const isPaused = run?.status === "paused" || (run?.stages.some((s) => s.status === "paused") ?? false);
+          const isResumableContinuation = run !== undefined && !isPaused && ((run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) || (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable"));
+          if (isResumableContinuation) {
+            const continuation = deps.runtimeForContext(ctx).resumeFailedRun(resolved.runId, undefined, { policy });
+            continuation.ok ? print(continuation.message) : fail(continuation.message);
+          } else {
+            const result = resumeRun(resolved.runId, {});
+            if (result.ok && result.mode === "snapshot" && run?.exitReason === "quit") {
+              return await handleDurableResume(resolved.runId, ctx, reporter, deps);
+            }
+            if (result.ok && policy.allowInputPicker) deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
+            result.ok ? print(result.message ?? `Resumed ${result.runId.slice(0, 8)}`) : fail(`Run not found: ${picked.runId}`);
+          }
         }
         return true;
       }
@@ -220,6 +346,11 @@ export async function handleRunControlCommand(
     } else {
       const resolved = resolveRunIdPrefix(target);
       if (resolved.kind === "not_found") {
+        // Not a live run — fall back to the cross-session durable resume catalog.
+        // cross-ref: issue #1498 — /workflow resume by top-level workflow id.
+        if (action === "resume") {
+          return await handleDurableResume(target, ctx, reporter, deps);
+        }
         fail(`Run not found: ${target}`);
         return true;
       }
@@ -260,6 +391,11 @@ export async function handleRunControlCommand(
     const run = store.runs().find((r) => r.id === stageRunId);
     const isPaused = run?.status === "paused" || (run?.stages.some((s) => s.status === "paused") ?? false);
     const isResumableContinuation = run !== undefined && !isPaused && ((run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) || (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable"));
+    const isActivelyRunning = run !== undefined && run.endedAt === undefined && run.status === "running" && !isPaused && run.exitReason !== "quit";
+    if (isActivelyRunning && action === "resume") {
+      fail(`Workflow ${stageRunId.slice(0, 8)} is already running in this session. Attach with \`/workflow connect ${stageRunId.slice(0, 8)}\` instead of resuming.`);
+      return true;
+    }
     if (isResumableContinuation) {
       const continuation = deps.runtimeForContext(ctx).resumeFailedRun(stageRunId, stageId, { policy });
       continuation.ok ? print(continuation.message) : fail(continuation.message);
@@ -270,6 +406,9 @@ export async function handleRunControlCommand(
       fail(`Run not found: ${stageRunId.slice(0, 8)}`);
       return true;
     }
+    if (result.mode === "snapshot" && run?.exitReason === "quit" && action === "resume") {
+      return await handleDurableResume(stageRunId, ctx, reporter, deps);
+    }
     if (!isPaused) {
       if (policy.allowInputPicker) deps.overlay.open(result.runId, overlaySurfaceFromContext(ctx));
       print(result.message ?? `Snapshot available: run ${result.runId} (${result.snapshot.name}) — status: ${result.snapshot.status}, stages: ${result.snapshot.stages.length}`);

package/dist/builtin/workflows/src/runs/background/quit.ts

@@ -0,0 +1,61 @@
+import { pauseRun, type PauseResult } from "./status.js";
+import { store as defaultStore } from "../../shared/store.js";
+import type { Store } from "../../shared/store-public-types.js";
+import { topLevelWorkflowRuns } from "../../shared/run-visibility.js";
+import type { StageControlRegistry } from "../foreground/stage-control-registry.js";
+import { getDurableBackend } from "../../durable/factory.js";
+
+export type QuitRunResult = PauseResult;
+
+/**
+ * Quit/detach a workflow UI without authoritatively killing the workflow.
+ *
+ * This is the graph-panel/orchestrator close affordance: it pauses any live
+ * stage handles when possible, annotates the run as resumable via
+ * `/workflow resume`, and deliberately does NOT abort through the cancellation
+ * registry or append a terminal `workflow.run.end` entry. `/workflow kill`
+ * remains the only explicit non-resumable manual kill path.
+ */
+export function quitRun(
+  runId: string,
+  opts?: {
+    store?: Store;
+    stageControlRegistry?: StageControlRegistry;
+  },
+): QuitRunResult {
+  const activeStore = opts?.store ?? defaultStore;
+  const run = activeStore.runs().find((candidate) => candidate.id === runId);
+  if (!run) return { ok: false, runId, reason: "not_found" };
+  if (run.endedAt !== undefined) return { ok: false, runId, reason: "already_ended" };
+
+  const paused = pauseRun(runId, opts);
+  if (!paused.ok && paused.reason !== "no_active_stages") return paused;
+  activeStore.recordRunPaused(runId, undefined, { exitReason: "quit", resumable: true });
+  // Mark the durable handle inactive so `/workflow resume` in this or another
+  // session can discover it again. While the run stays `running` in the store
+  // and (after a fresh dispatch) in the durable backend, it is hidden from the
+  // resume selector and refused on resume; quitting flips durable to `paused`.
+  markDurableQuit(runId);
+  return paused.ok ? paused : { ok: true, runId, paused: [] };
+}
+
+function markDurableQuit(runId: string): void {
+  let backend;
+  try {
+    backend = getDurableBackend();
+  } catch {
+    return;
+  }
+  if (backend.getWorkflow(runId) !== undefined) {
+    backend.setWorkflowStatus(runId, "paused", undefined, true);
+  }
+}
+
+export function quitAllRuns(opts?: {
+  store?: Store;
+  stageControlRegistry?: StageControlRegistry;
+}): QuitRunResult[] {
+  const activeStore = opts?.store ?? defaultStore;
+  const inFlight = topLevelWorkflowRuns(activeStore.runs()).filter((r) => r.endedAt === undefined);
+  return inFlight.map((r) => quitRun(r.id, { store: activeStore, stageControlRegistry: opts?.stageControlRegistry }));
+}

package/dist/builtin/workflows/src/runs/background/status.ts

@@ -405,6 +405,7 @@ export function pauseAllRuns(opts?: {
   );
 }
 
+
 // ---------------------------------------------------------------------------
 // interruptRun
 // ---------------------------------------------------------------------------

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

@@ -67,7 +67,7 @@ export async function mapParallelSteps<T>(
   concurrency: number | undefined,
   failFast: boolean | undefined,
   mapper: (step: WorkflowTaskStep) => Promise<T>,
-  onFirstFailure?: (error: unknown) => void,
+  onFirstFailure?: (error: unknown) => void | Promise<void>,
   control?: {
     readonly beforeDequeue?: () => void;
     readonly beforeMap?: () => void;
@@ -92,11 +92,11 @@ export async function mapParallelSteps<T>(
     controlSignal = error;
     if (failFastEnabled) rejectFirstFailure(error);
   };
-  const recordFailure = (index: number, error: unknown): void => {
+  const recordFailure = async (index: number, error: unknown): Promise<void> => {
     failures.push({ index, error });
     if (firstFailure === undefined) {
       firstFailure = error;
-      onFirstFailure?.(error);
+      await onFirstFailure?.(error);
       if (failFastEnabled) rejectFirstFailure(error);
     }
   };
@@ -112,7 +112,7 @@ export async function mapParallelSteps<T>(
           selectControlSignal(err);
           return;
         }
-        recordFailure(nextIndex, err);
+        await recordFailure(nextIndex, err);
         return;
       }
       if (controlSignal !== undefined) return;
@@ -128,7 +128,7 @@ export async function mapParallelSteps<T>(
           selectControlSignal(err);
           return;
         }
-        recordFailure(index, err);
+        await recordFailure(index, err);
         if (failFastEnabled) return;
       }
     }

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

@@ -8,6 +8,21 @@ import { hasExplicitFastModeCandidate } from "./executor-direct-helpers.js";
 import { applyFailureToStage } from "./executor-lifecycle.js";
 import { isTerminalStage } from "./executor-scheduler.js";
 
+export interface TrackedStageCallOptions {
+  readonly eagerSession?: boolean;
+  readonly allowFinalized?: boolean;
+}
+
+export type TrackedStageCaller = <T>(
+  call: () => Promise<T>,
+  eagerSessionOrOptions?: boolean | TrackedStageCallOptions,
+) => Promise<T>;
+
+function normalizeTrackedStageCallOptions(input: boolean | TrackedStageCallOptions | undefined): Required<TrackedStageCallOptions> {
+  if (typeof input === "boolean") return { eagerSession: input, allowFinalized: false };
+  return { eagerSession: input?.eagerSession === true, allowFinalized: input?.allowFinalized === true };
+}
+
 export function createTrackedStageCaller(input: {
   readonly runtime: LiveStageRuntime;
   readonly limiter: ConcurrencyLimiter;
@@ -15,7 +30,7 @@ export function createTrackedStageCaller(input: {
   readonly adapters: StageAdapters;
   readonly hasContinuation: boolean;
   readonly hasScopedParents: boolean;
-}): <T>(call: () => Promise<T>, eagerSession?: boolean) => Promise<T> {
+}): TrackedStageCaller {
   const { runtime } = input;
   const readinessGateEnabled = runtime.opts.confirmStageReadiness !== undefined || runtime.opts.usePromptNodesForUi === true;
   const confirmReadiness = async (): Promise<"advance" | "stay"> => {
@@ -68,22 +83,24 @@ export function createTrackedStageCaller(input: {
     return result;
   };
 
-  return async <T>(call: () => Promise<T>, eagerSession = false): Promise<T> => {
+  return async <T>(call: () => Promise<T>, eagerSessionOrOptions?: boolean | TrackedStageCallOptions): Promise<T> => {
+    const callOptions = normalizeTrackedStageCallOptions(eagerSessionOrOptions);
     runtime.exit.throwIfWorkflowExitSelected();
     await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
-    if (runtime.state.stageFinalized) throw runtime.parallelFailFastError();
+    if (runtime.state.stageFinalized && !callOptions.allowFinalized) throw runtime.parallelFailFastError();
 
     await input.limiter.acquire();
     try {
       await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
       runtime.exit.throwIfWorkflowExitSelected();
-      if (runtime.state.stageFinalized) throw runtime.parallelFailFastError();
+      if (runtime.state.stageFinalized && !callOptions.allowFinalized) throw runtime.parallelFailFastError();
     } catch (err) {
       input.limiter.release();
       throw err;
     }
 
-    if (!input.hasContinuation && runtime.stageSnapshot.startedAt === undefined && !input.hasScopedParents) {
+    const trackStageLifecycle = !runtime.state.stageFinalized;
+    if (trackStageLifecycle && !input.hasContinuation && runtime.stageSnapshot.startedAt === undefined && !input.hasScopedParents) {
       const actualParentIds = runtime.scheduler.tracker.currentParents();
       const sameParents = actualParentIds.length === runtime.stageSnapshot.parentIds.length &&
         actualParentIds.every((value) => runtime.stageSnapshot.parentIds.includes(value));
@@ -92,25 +109,29 @@ export function createTrackedStageCaller(input: {
         runtime.scheduler.setStageParentIds(runtime.stageSnapshot, actualParentIds);
       }
     }
-    runtime.stageSnapshot.status = "running";
-    runtime.stageSnapshot.startedAt = Date.now();
-    const hasNoExplicitModelConfig = input.options?.model === undefined && input.options?.fallbackModels === undefined;
-    const promptAdapterHandlesInitialPrompt = input.adapters.prompt !== undefined;
-    if (eagerSession && !promptAdapterHandlesInitialPrompt && (hasNoExplicitModelConfig || await hasExplicitFastModeCandidate({
-      model: input.options?.model,
-      fallbackModels: input.options?.fallbackModels,
-      models: runtime.opts.models,
-    }))) {
-      try {
-        await runtime.innerCtx.__ensureSession();
-        runtime.captureStageSessionMeta();
-      } catch (err) {
-        if (!(err instanceof Error && err.message.includes("prompt adapter not configured"))) throw err;
+    if (trackStageLifecycle) {
+      runtime.stageSnapshot.status = "running";
+      runtime.stageSnapshot.startedAt = Date.now();
+      const hasNoExplicitModelConfig = input.options?.model === undefined && input.options?.fallbackModels === undefined;
+      const promptAdapterHandlesInitialPrompt = input.adapters.prompt !== undefined;
+      if (callOptions.eagerSession && !promptAdapterHandlesInitialPrompt && (hasNoExplicitModelConfig || await hasExplicitFastModeCandidate({
+        model: input.options?.model,
+        fallbackModels: input.options?.fallbackModels,
+        models: runtime.opts.models,
+      }))) {
+        try {
+          await runtime.innerCtx.__ensureSession();
+          runtime.captureStageSessionMeta();
+        } catch (err) {
+          if (!(err instanceof Error && err.message.includes("prompt adapter not configured"))) throw err;
+        }
       }
+      runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
+      runtime.activeStore.recordStageStart(runtime.runId, runtime.stageSnapshot);
+      runtime.appendStageStartOnce();
+    } else {
+      runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
     }
-    runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
-    runtime.activeStore.recordStageStart(runtime.runId, runtime.stageSnapshot);
-    runtime.appendStageStartOnce();
 
     runtime.mcpScope.apply();
 
@@ -158,37 +179,57 @@ export function createTrackedStageCaller(input: {
       }
       runtime.captureStageSessionMeta();
       runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
-      if (runtime.stageFailFastScope?.failed === true && runtime.stageFailFastScope.activeStages.has(runtime.stageId)) {
+      if (trackStageLifecycle && runtime.stageFailFastScope?.failed === true && runtime.stageFailFastScope.activeStages.has(runtime.stageId)) {
         runtime.markSkippedForParallelFailFast();
         throw runtime.parallelFailFastError();
       }
-      if (runtime.state.stageFinalized) throw runtime.parallelFailFastError();
-      runtime.stageSnapshot.status = "completed";
-      const assistantText = runtime.innerCtx.__getLastAssistantText();
-      if (assistantText !== undefined) runtime.stageSnapshot.result = assistantText;
+      if (trackStageLifecycle && runtime.state.stageFinalized) throw runtime.parallelFailFastError();
+      if (trackStageLifecycle) {
+        runtime.stageSnapshot.status = "completed";
+        const assistantText = runtime.innerCtx.__getLastAssistantText();
+        if (assistantText !== undefined) runtime.stageSnapshot.result = assistantText;
+      }
       return result;
     } catch (err) {
       const workflowExitAbort = runtime.signal.aborted ? runtime.exit.currentWorkflowExitAbortReason() : undefined;
       if (workflowExitAbort !== undefined && !runtime.state.skippedForParallelFailFast) {
         runtime.state.stageClosedByWorkflowExit = true;
-        if (!isTerminalStage(runtime.stageSnapshot)) {
+        if (trackStageLifecycle && !isTerminalStage(runtime.stageSnapshot)) {
           runtime.stageSnapshot.status = "skipped";
           runtime.stageSnapshot.skippedReason = runtime.exit.workflowExitSkippedReason(workflowExitAbort.reason);
         }
-      } else if (!runtime.signal.aborted && !runtime.state.skippedForParallelFailFast) {
+      } else if (trackStageLifecycle && !runtime.signal.aborted && !runtime.state.skippedForParallelFailFast) {
         applyFailureToStage(runtime.stageSnapshot, runtime.classifyExecutorFailure(err));
       }
       throw err;
     } finally {
+      // Finalization, handle release, and limiter release are each independent.
+      // If finalizeStageSnapshot() throws, the limiter must still be released
+      // so the concurrency semaphore is not leaked.
+      // cross-ref: issue #1498 — durable finalization failures must not leak the stage limiter.
       runtime.mcpScope.clear();
       runtime.captureStageSessionMeta();
-      runtime.finalizeStageSnapshot();
-      if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {
+      let finalizationError: { readonly thrown: true; readonly error: unknown } | undefined;
+      if (trackStageLifecycle) {
+        try {
+          await runtime.finalizeStageSnapshot();
+        } catch (err) {
+          finalizationError = { thrown: true, error: err };
+        }
+        try {
+          if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {
+            await runtime.releaseLiveHandle().catch(() => {});
+          } else {
+            await runtime.dropStageControlForCompletion().catch(() => {});
+          }
+        } catch {
+          // Best-effort: handle release failure must not prevent limiter release.
+        }
+      } else if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {
         await runtime.releaseLiveHandle().catch(() => {});
-      } else {
-        await runtime.dropStageControlForCompletion().catch(() => {});
       }
       input.limiter.release();
+      if (finalizationError !== undefined) throw finalizationError.error;
     }
   };
 }