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

package/dist/builtin/workflows/src/durable/ui-primitive.ts

@@ -0,0 +1,96 @@
+/** Durable `ctx.ui` wrapper with collision-resistant prompt identities. */
+
+import type {
+  WorkflowCustomUiFactory,
+  WorkflowCustomUiOptions,
+  WorkflowUIContext,
+} from "../shared/authoring-contract-ui.js";
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import { durableHash } from "./backend.js";
+import type { DurableUiCheckpoint, UiPromptKind } from "./types.js";
+import { recordCheckpointDurably } from "./tool-primitive.js";
+
+export interface DurableUiDeps {
+  readonly workflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  readonly nextCheckpointId: () => string;
+}
+
+export function wrapUiWithDurable(base: WorkflowUIContext, deps: DurableUiDeps): WorkflowUIContext {
+  const ordinals = new Map<string, number>();
+
+  const nextIdentity = (kind: UiPromptKind, message: string, details?: WorkflowSerializableValue): { key: string; hash: string } => {
+    const baseKey = durableHash({ kind, message, details: details ?? null });
+    const ordinal = (ordinals.get(baseKey) ?? 0) + 1;
+    ordinals.set(baseKey, ordinal);
+    const identity = { kind, message, details: details ?? null, ordinal };
+    return { key: JSON.stringify(identity), hash: durableHash(identity) };
+  };
+
+  const record = async (kind: UiPromptKind, identity: { key: string; hash: string }, response: WorkflowSerializableValue): Promise<void> => {
+    const checkpoint: DurableUiCheckpoint = {
+      kind: "ui",
+      workflowId: deps.workflowId,
+      checkpointId: `ui:${identity.hash}`,
+      promptKind: kind,
+      message: identity.key,
+      promptHash: identity.hash,
+      response,
+      completedAt: Date.now(),
+    };
+    await recordCheckpointDurably(deps.backend, checkpoint);
+  };
+
+  const cached = (identity: { readonly hash: string }): WorkflowSerializableValue | undefined => deps.backend.getUiResponse(deps.workflowId, identity.hash);
+
+  const cachedCustom = (identity: { readonly hash: string }): { readonly found: boolean; readonly response?: WorkflowSerializableValue } => {
+    const hit = deps.backend.listCheckpoints(deps.workflowId)
+      .find((checkpoint) => checkpoint.kind === "ui" && checkpoint.promptHash === identity.hash);
+    return hit?.kind === "ui" ? { found: true, response: hit.response } : { found: false };
+  };
+
+  return {
+    async input(promptText: string): Promise<string> {
+      const identity = nextIdentity("input", promptText);
+      const hit = cached(identity);
+      if (typeof hit === "string") return hit;
+      const response = await base.input(promptText);
+      await record("input", identity, response);
+      return response;
+    },
+    async confirm(message: string): Promise<boolean> {
+      const identity = nextIdentity("confirm", message);
+      const hit = cached(identity);
+      if (typeof hit === "boolean") return hit;
+      const response = await base.confirm(message);
+      await record("confirm", identity, response);
+      return response;
+    },
+    async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
+      const identity = nextIdentity("select", message, [...options]);
+      const hit = cached(identity);
+      if (typeof hit === "string") return hit as T;
+      const response = await base.select<T>(message, options);
+      await record("select", identity, response);
+      return response;
+    },
+    async editor(initial?: string): Promise<string> {
+      const identity = nextIdentity("editor", initial ?? "", initial ?? null);
+      const hit = cached(identity);
+      if (typeof hit === "string") return hit;
+      const response = await base.editor(initial);
+      await record("editor", identity, response);
+      return response;
+    },
+    async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
+      const replayIdentity = options?.replayIdentity ?? factory?.name ?? "custom";
+      const identity = nextIdentity("custom", replayIdentity, { replayIdentity });
+      const hit = cachedCustom(identity);
+      if (hit.found) return hit.response as T;
+      const response = await base.custom<T>(factory, options);
+      await record("custom", identity, response as WorkflowSerializableValue);
+      return response;
+    },
+  };
+}

package/dist/builtin/workflows/src/engine/options.ts

@@ -9,6 +9,7 @@ export type EngineStageRuntimeOptions = Pick<
   | "persistence"
   | "onStageStart"
   | "onStageEnd"
+  | "onStageSession"
   | "confirmStageReadiness"
   | "usePromptNodesForUi"
 >;
@@ -37,4 +38,6 @@ export type EngineChildRunOptions = Pick<
   | "stageControlRegistry"
   | "onStageStart"
   | "onStageEnd"
+  | "onStageSession"
+  | "durableBackend"
 >;

package/dist/builtin/workflows/src/engine/primitives/parallel.ts

@@ -33,11 +33,11 @@ export function createParallelPrimitive(input: {
         taskWithSharedDefaults(taskOptionsFromStep(step, prompt, taskPrevious(step)), options),
         parallelScope,
       );
-    }, (error) => {
+    }, async (error) => {
       if (!failFastEnabled) return;
       parallelScope.failed = true;
       parallelScope.firstFailure = error;
-      for (const stage of parallelScope.activeStages.values()) stage.skip();
+      await Promise.all([...parallelScope.activeStages.values()].map((stage) => stage.skip()));
     }, {
       beforeDequeue: input.runtime.exit.throwIfWorkflowExitSelected,
       beforeMap: input.runtime.exit.throwIfWorkflowExitSelected,

package/dist/builtin/workflows/src/engine/primitives/task.ts

@@ -49,10 +49,10 @@ function createTaskPrimitive(runtime: EngineRuntime): WorkflowTaskPrimitive {
         ...(stageFailFastScope !== undefined ? { failFastScope: stageFailFastScope } : {}),
       });
       const stage = stageHandle.context;
-      const rawOutput = await stage.prompt(
-        applyTaskContext(`${taskReadInstruction(resolvedTaskOptions)}${taskPrompt(resolvedTaskOptions)}`, taskPrevious(resolvedTaskOptions)),
-        taskPromptOptions(resolvedTaskOptions),
-      );
+      const promptText = resolvedTaskOptions.resumeFromSessionFile !== undefined
+        ? "Continue"
+        : applyTaskContext(`${taskReadInstruction(resolvedTaskOptions)}${taskPrompt(resolvedTaskOptions)}`, taskPrevious(resolvedTaskOptions));
+      const rawOutput = await stage.prompt(promptText, taskPromptOptions(resolvedTaskOptions));
       const structured = typeof rawOutput === "string" ? undefined : rawOutput;
       const text = truncateTaskOutput(structuredTaskOutputText(rawOutput), resolvedTaskOptions.maxOutput);
       const sessionId = (() => {

package/dist/builtin/workflows/src/engine/primitives/ui.ts

@@ -5,37 +5,51 @@ import type {
 } from "../../shared/types.js";
 import type { RunOpts } from "../../runs/foreground/executor-types.js";
 import { makeHeadlessUnavailableUIContext, normalizeUIContext } from "../../runs/foreground/executor-hil.js";
+import type { WorkflowUIContext as AuthoringWorkflowUIContext } from "../../shared/authoring-contract-ui.js";
+import { wrapUiWithDurable, type DurableUiDeps } from "../../durable/ui-primitive.js";
 
-export function buildExitGatedUiContext(input: {
+export interface BuildExitGatedUiContextInput {
   readonly opts: RunOpts;
-  readonly baseFromPromptNodes: () => WorkflowUIContext;
+  readonly baseFromPromptNodes: () => AuthoringWorkflowUIContext;
   readonly throwIfWorkflowExitSelected: () => void;
-}): WorkflowUIContext {
+  /**
+   * Optional durable UI deps. When provided, completed ctx.ui responses are
+   * cached durably and replayed on resume instead of re-asking the user.
+   *
+   * cross-ref: issue #1498 — durable ctx.ui response/pending prompt state.
+   */
+  readonly durableUi?: DurableUiDeps;
+}
+
+export function buildExitGatedUiContext(input: BuildExitGatedUiContextInput): WorkflowUIContext {
   const base = input.opts.usePromptNodesForUi === true
     ? input.baseFromPromptNodes()
     : input.opts.executionMode === "non_interactive" && input.opts.ui === undefined
       ? makeHeadlessUnavailableUIContext()
       : normalizeUIContext(input.opts.ui);
+  // Wrap the resolved base UI with durable caching when deps are supplied.
+  // The durable wrapper is transparent when no cached response exists.
+  const durableBase = input.durableUi !== undefined ? wrapUiWithDurable(base, input.durableUi) : base;
   return {
     async input(promptText: string): Promise<string> {
       input.throwIfWorkflowExitSelected();
-      return await base.input(promptText);
+      return await durableBase.input(promptText);
     },
     async confirm(message: string): Promise<boolean> {
       input.throwIfWorkflowExitSelected();
-      return await base.confirm(message);
+      return await durableBase.confirm(message);
     },
     async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
       input.throwIfWorkflowExitSelected();
-      return await base.select(message, options);
+      return await durableBase.select(message, options);
     },
     async editor(initial?: string): Promise<string> {
       input.throwIfWorkflowExitSelected();
-      return await base.editor(initial);
+      return await durableBase.editor(initial);
     },
     async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
       input.throwIfWorkflowExitSelected();
-      return await base.custom(factory, options);
+      return await durableBase.custom(factory, options);
     },
   };
 }

package/dist/builtin/workflows/src/engine/primitives/workflow.ts

@@ -17,11 +17,18 @@ import {
   workflowChildReplaySnapshot,
   workflowDefinitionRequirementMessage,
 } from "../../runs/foreground/executor-child-helpers.js";
+import type { DurableScope } from "../../durable/scoped-backend.js";
 
 export function createChildWorkflowRunner(input: {
   readonly runtime: EngineRuntime;
   readonly resolveWorkflowCwd: () => string;
   readonly nextWorkflowBoundaryReplayKey: (name: string) => string;
+  /**
+   * Consume the durable scope published by the durable child primitive for the
+   * current invocation, if any. Routes child internal side-effect checkpoints
+   * under the root workflow.
+   */
+  readonly consumeDurableScope?: () => DurableScope | undefined;
   readonly runWorkflow: <
     TInputs extends WorkflowInputValues,
     TRunInputs extends WorkflowInputValues = TInputs,
@@ -100,6 +107,7 @@ export function createChildWorkflowRunner(input: {
         },
         signal: childController.signal,
         deferWorkflowStart: false,
+        ...(input.consumeDurableScope !== undefined ? { durableScope: input.consumeDurableScope() } : {}),
       });
       boundary.observeChildRun(childRunPromise);
       const childRun = await childRunPromise;

package/dist/builtin/workflows/src/engine/run-durable-finalize.ts

@@ -0,0 +1,69 @@
+/**
+ * Durable terminal-status finalization for workflow runs.
+ *
+ * Extracted from `run()` to keep the engine entrypoint under the file-length
+ * gate. Persists the final durable status (cancelled/blocked/skipped/failed/
+ * killed) for cross-session resume discovery when the run did not complete
+ * normally (normal completion is handled in the run try-block).
+ *
+ * cross-ref: issue #1498.
+ */
+
+import type { RunSnapshot } from "../shared/store-types.js";
+import type { WorkflowPersistencePort } from "../shared/types.js";
+import type { DurableWorkflowBackend } from "../durable/backend.js";
+import { persistDurableCacheEntry } from "../durable/resume-catalog.js";
+import type { DurableWorkflowStatus } from "../durable/types.js";
+
+export interface DurableTerminalFinalizeInput {
+  readonly runId: string;
+  readonly runSnapshot: RunSnapshot;
+  readonly isRoot: boolean;
+  readonly durableBackend: DurableWorkflowBackend;
+  readonly persistence?: WorkflowPersistencePort;
+}
+
+/**
+ * Map and persist the terminal durable status for a root workflow run when the
+ * run did not complete normally. Safe to call from a `finally` block: flush
+ * failures are logged but never rethrown so they do not mask the original
+ * failure/exit status.
+ */
+export async function finalizeDurableTerminalStatus(input: DurableTerminalFinalizeInput): Promise<void> {
+  if (!input.isRoot) return;
+  const status = input.runSnapshot.status;
+  const isExitTerminal = input.runSnapshot.exited === true && status !== "running";
+  if (status !== "failed" && status !== "killed" && !isExitTerminal) return;
+
+  const durableStatus = toDurableStatus(status);
+  if (durableStatus !== undefined) {
+    input.durableBackend.setWorkflowStatus(input.runId, durableStatus, undefined, input.runSnapshot.resumable);
+  }
+  try {
+    await input.durableBackend.flush?.();
+  } catch (flushErr) {
+    const msg = flushErr instanceof Error ? flushErr.message : String(flushErr);
+    console.warn(`atomic-workflows: durable terminal status flush failed: ${msg}`);
+  }
+  if (input.persistence !== undefined && input.durableBackend.persistent) {
+    const cacheEntry = input.durableBackend.toCacheEntry(input.runId);
+    if (cacheEntry) persistDurableCacheEntry(input.persistence, cacheEntry);
+  }
+}
+
+function toDurableStatus(status: RunSnapshot["status"]): DurableWorkflowStatus | undefined {
+  switch (status) {
+    case "completed":
+    case "skipped":
+      return "completed";
+    case "cancelled":
+    case "killed":
+      return "cancelled";
+    case "failed":
+      return "failed";
+    case "blocked":
+      return "blocked";
+    default:
+      return undefined;
+  }
+}

package/dist/builtin/workflows/src/engine/run-durable-stage-session.ts

@@ -0,0 +1,31 @@
+import type { StageSnapshot } from "../shared/store-types.js";
+import type { WorkflowPersistencePort } from "../shared/types.js";
+import type { DurableWorkflowBackend } from "../durable/backend.js";
+import { persistDurableCacheEntry } from "../durable/resume-catalog.js";
+import { recordStageSessionCheckpoint, type DurableStageDeps } from "../durable/stage-primitive.js";
+
+export interface DurableStageSessionRecorderInput {
+  readonly runId: string;
+  readonly deps: DurableStageDeps;
+  readonly backend: DurableWorkflowBackend;
+  readonly persistence?: WorkflowPersistencePort;
+  readonly onStageSession?: (runId: string, snapshot: StageSnapshot) => unknown;
+}
+
+export function createDurableStageSessionRecorder(
+  input: DurableStageSessionRecorderInput,
+): (stageRunId: string, snapshot: StageSnapshot) => void {
+  return (stageRunId, snapshot) => {
+    if (stageRunId === input.runId) {
+      void recordStageSessionCheckpoint(input.deps, snapshot).then((recorded) => {
+        if (!recorded || !input.persistence || !input.backend.persistent) return;
+        const cacheEntry = input.backend.toCacheEntry(input.runId);
+        if (cacheEntry) persistDurableCacheEntry(input.persistence, cacheEntry);
+      }).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`atomic-workflows: durable stage session checkpoint failed: ${message}`);
+      });
+    }
+    void input.onStageSession?.(stageRunId, snapshot);
+  };
+}

package/dist/builtin/workflows/src/engine/run.ts

@@ -4,6 +4,7 @@ import type {
   WorkflowInputValues,
   WorkflowOutputValues,
   WorkflowRunContext,
+  WorkflowSerializableValue,
 } from "../shared/types.js";
 import type { WorkflowFailure } from "../shared/workflow-failures.js";
 import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
@@ -17,6 +18,8 @@ import { buildExitGatedUiContext } from "./primitives/ui.js";
 import { createWorkflowExitManager } from "./primitives/exit.js";
 import { createWorkflowTaskRunners } from "./primitives/task.js";
 import { createChildWorkflowRunner } from "./primitives/workflow.js";
+import { createChainPrimitive } from "./primitives/chain.js";
+import { createParallelPrimitive } from "./primitives/parallel.js";
 import { createRunLimiter } from "../runs/shared/concurrency.js";
 import { stageControlRegistry as defaultStageControlRegistry } from "../runs/foreground/stage-control-registry.js";
 import type { RunOpts, RunResult } from "../runs/foreground/executor-types.js";
@@ -37,6 +40,16 @@ import {
 } from "../runs/foreground/executor-lifecycle.js";
 import { assertWorkflowRunOutputs, normalizeWorkflowRunOutput } from "../runs/foreground/executor-outputs.js";
 import { isWorkflowDefinition, workflowDefinitionRequirementMessage } from "../runs/foreground/executor-child-helpers.js";
+import { getDurableBackend } from "../durable/factory.js";
+import { createToolPrimitive, createCheckpointIdGenerator } from "../durable/tool-primitive.js";
+import { persistDurableCacheEntry } from "../durable/resume-catalog.js";
+import { createDurableStagePrimitive, createDurableTaskPrimitive, recordStageCheckpoint, createStageReplayKeyGenerator, recordCachedStageWithTracker } from "../durable/stage-primitive.js";
+import { createDurableChildWorkflowPrimitive } from "../durable/child-primitive.js";
+import { ScopedDurableBackend, type DurableScope } from "../durable/scoped-backend.js";
+import { finalizeDurableTerminalStatus } from "./run-durable-finalize.js";
+import { createDurableStageSessionRecorder } from "./run-durable-stage-session.js";
+import type { DurableWorkflowBackend } from "../durable/backend.js";
+import type { StageSnapshot } from "../shared/store-types.js";
 
 function nextEventLoopTurn(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));
@@ -176,6 +189,38 @@ export async function run<
     classifyExecutorFailure,
     drainWorkflowExitCleanups: exit.drainWorkflowExitCleanups,
   });
+  // Durable workflow backend — registers this run and wires ctx.tool/ui/stage.
+  // Declared early so the stage-end recorder can attach to stageOptions.
+  // cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+  // Child runs with a durable scope route their internal side-effect
+  // checkpoints under the root workflow so interrupted children do not
+  // re-execute completed side effects on parent resume.
+  const rootBackend: DurableWorkflowBackend = opts.durableBackend ?? getDurableBackend();
+  const durableBackend: DurableWorkflowBackend = opts.durableScope !== undefined
+    ? new ScopedDurableBackend(rootBackend, opts.durableScope)
+    : rootBackend;
+  const checkpointIdGenerator = createCheckpointIdGenerator();
+  const stageReplayKeyGenerator = createStageReplayKeyGenerator(runId);
+  const completedStageReplayKeys = new Map<string, string>();
+  const durableStageDeps = {
+    workflowId: runId,
+    backend: durableBackend,
+    nextCheckpointId: checkpointIdGenerator,
+    nextReplayKey: stageReplayKeyGenerator,
+    replayKeyForCompletedStage: (stage: StageSnapshot) => completedStageReplayKeys.get(stage.id),
+  };
+  const userOnStageEnd = opts.onStageEnd;
+  const durableOnStageEnd = async (stageRunId: string, snapshot: StageSnapshot): Promise<void> => {
+    if (stageRunId === runId && snapshot.status === "completed") {
+      await recordStageCheckpoint(durableStageDeps, snapshot);
+      if (opts.persistence && durableBackend.persistent) {
+        const cacheEntry = durableBackend.toCacheEntry(runId);
+        if (cacheEntry) persistDurableCacheEntry(opts.persistence, cacheEntry);
+      }
+    }
+    await userOnStageEnd?.(stageRunId, snapshot);
+  };
+  const durableOnStageSession = createDurableStageSessionRecorder({ runId, deps: durableStageDeps, backend: durableBackend, persistence: opts.persistence, onStageSession: opts.onStageSession });
   const stageOptions: EngineStageRuntimeOptions = {
     continuation: opts.continuation,
     models: opts.models,
@@ -183,7 +228,8 @@ export async function run<
     defaultSessionDir: opts.defaultSessionDir,
     persistence: opts.persistence,
     onStageStart: opts.onStageStart,
-    onStageEnd: opts.onStageEnd,
+    onStageEnd: durableOnStageEnd,
+    onStageSession: durableOnStageSession,
     confirmStageReadiness: opts.confirmStageReadiness,
     usePromptNodesForUi: opts.usePromptNodesForUi,
   };
@@ -210,6 +256,8 @@ export async function run<
     stageControlRegistry: opts.stageControlRegistry,
     onStageStart: opts.onStageStart,
     onStageEnd: opts.onStageEnd,
+    onStageSession: opts.onStageSession,
+    durableBackend,
   };
   const runtime = new EngineRuntime({
     runId,
@@ -238,14 +286,77 @@ export async function run<
     workflowBoundaryReplayCounts.set(name, next);
     return `workflow:${name}:${next}`;
   };
+  // Durable child workflow replay keys use a SEPARATE counter so that cache
+  // hits (which do not invoke the inner workflow runner) do not desync the
+  // ordinal sequence. Without this, repeated ctx.workflow(child) calls would
+  // shift replay keys on resume and re-execute completed children.
+  // cross-ref: issue #1498.
+  const durableChildReplayCounts = new Map<string, number>();
+  const nextDurableChildReplayKey = (name: string): string => {
+    const next = (durableChildReplayCounts.get(name) ?? 0) + 1;
+    durableChildReplayCounts.set(name, next);
+    return `workflow:${name}:${next}`;
+  };
   const taskRunners = createWorkflowTaskRunners({ runtime });
+  // Durable scope holder: the durable child primitive publishes the scope for
+  // the next child invocation; the child runner consumes it when launching the
+  // run. This routes child internal side-effect checkpoints under the root.
+  let pendingChildDurableScope: DurableScope | undefined;
   const workflow = createChildWorkflowRunner({
     runtime,
     resolveWorkflowCwd,
     nextWorkflowBoundaryReplayKey,
+    consumeDurableScope: () => {
+      const scope = pendingChildDurableScope;
+      pendingChildDurableScope = undefined;
+      return scope;
+    },
     runWorkflow: run,
   });
 
+  // Durable workflow registration — register this run for cross-session discovery.
+  if (opts.continuation === undefined && opts.parentRun === undefined) {
+    // New root run: register it durably so a future session can discover it.
+    durableBackend.registerWorkflow({
+      workflowId: runId,
+      name: def.name,
+      inputs: resolvedInputs as Record<string, import("../shared/types.js").WorkflowSerializableValue>,
+      createdAt: runSnapshot.startedAt,
+      status: "running",
+      rootWorkflowId: runId,
+      resumable: true,
+      ...(opts.persistence !== undefined ? { sessionFile: undefined } : {}),
+    });
+  } else if (opts.parentRun === undefined) {
+    // Resuming a root workflow: mark it as running again in the backend.
+    durableBackend.setWorkflowStatus(runId, "running");
+  }
+  const tool = createToolPrimitive({
+    workflowId: runId,
+    backend: durableBackend,
+    nextCheckpointId: checkpointIdGenerator,
+    throwIfCancelled: () => {
+      if (ownController.signal.aborted) {
+        throw new Error("atomic-workflows: workflow cancelled");
+      }
+    },
+    signal: ownController.signal,
+  });
+
+  // Durable ctx.ui wrapper — caches completed user responses so a resumed workflow does not re-ask answered prompts.
+  const durableUiDeps = { workflowId: runId, backend: durableBackend, nextCheckpointId: checkpointIdGenerator };
+  const recordCachedStage = (name: string, replayKey: string, output: WorkflowSerializableValue): void =>
+    recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, output, completedStageReplayKeys);
+  const durableTask = createDurableTaskPrimitive({
+    workflowId: runId, backend: durableBackend,
+    nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName), task: taskRunners.task,
+    recordCachedTask: (name, replayKey, output) => recordCachedStage(name, replayKey, output),
+  });
+  const durableWorkflow = createDurableChildWorkflowPrimitive({
+    workflowId: runId, rootWorkflowId: opts.parentRun?.rootRunId ?? runId, backend: durableBackend,
+    nextReplayKey: nextDurableChildReplayKey, setChildDurableScope: (scope) => { pendingChildDurableScope = scope; },
+    recordCachedStage, workflow,
+  });
   const ctx: WorkflowRunContext<TInputs> = {
     inputs: resolvedInputs as TInputs,
     get cwd() { return resolveWorkflowCwd(); },
@@ -253,6 +364,7 @@ export async function run<
     ui: buildExitGatedUiContext({
       opts,
       throwIfWorkflowExitSelected: exit.throwIfWorkflowExitSelected,
+      durableUi: durableUiDeps,
       baseFromPromptNodes: () => buildPromptNodeUiAdapter({
         runId,
         activeStore,
@@ -267,11 +379,23 @@ export async function run<
         classifyExecutorFailure,
       }),
     }),
-    stage: runtime.stage,
-    task: taskRunners.task,
-    chain: taskRunners.chain,
-    parallel: taskRunners.parallel,
-    workflow,
+    stage: createDurableStagePrimitive({
+      workflowId: runId,
+      backend: durableBackend,
+      nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName),
+      recordCachedStage,
+      stage: (name, options, replayKey) => {
+        const stage = runtime.stage(name, options);
+        const stageId = activeStore.runs().find((r) => r.id === runId)?.stages.at(-1)?.id;
+        if (stageId !== undefined) completedStageReplayKeys.set(stageId, replayKey);
+        return stage;
+      },
+    }),
+    task: durableTask,
+    chain: createChainPrimitive({ runtime, task: durableTask }),
+    parallel: createParallelPrimitive({ runtime, task: durableTask }),
+    workflow: durableWorkflow,
+    tool,
   };
 
   try {
@@ -298,8 +422,15 @@ export async function run<
     const result = normalizeWorkflowRunOutput(def.name, rawResult);
     assertWorkflowRunOutputs(def.name, result, def.outputs);
     assertWorkflowCreatedStage(runSnapshot);
+    await durableBackend.flush?.();
     const recorded = activeStore.recordRunEnd(runId, "completed", result);
     appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: "completed", result, ts: Date.now() });
+    durableBackend.setWorkflowStatus(runId, "completed");
+    await durableBackend.flush?.();
+    if (opts.persistence && durableBackend.persistent) {
+      const cacheEntry = durableBackend.toCacheEntry(runId);
+      if (cacheEntry) persistDurableCacheEntry(opts.persistence, cacheEntry);
+    }
     return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "completed", result }, opts.onRunEnd);
   } catch (err) {
     const selectedExit = findWorkflowExitSignal(err, exitScope) ?? findWorkflowExitSignal(ownController.signal.reason, exitScope);
@@ -351,6 +482,17 @@ export async function run<
     });
     return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "failed", error: metadata.errorMessage }, opts.onRunEnd);
   } finally {
+    // Persist final durable status for cross-session resume discovery.
+    // Covers ctx.exit terminal states and failure/kill paths; normal
+    // completion is handled in the try block.
+    // cross-ref: issue #1498
+    await finalizeDurableTerminalStatus({
+      runId,
+      runSnapshot,
+      isRoot: opts.parentRun === undefined,
+      durableBackend,
+      persistence: opts.persistence,
+    });
     opts.cancellation?.unregister(runId);
   }
 }

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

@@ -148,12 +148,18 @@ export class EngineRuntime {
     const allow = options?.mcp?.allow ?? null;
     const deny = options?.mcp?.deny ?? null;
     const hasScope = allow !== null || deny !== null;
+    let depth = 0;
     return {
       apply: () => {
-        if (this.childRunOptions.mcp && hasScope) this.childRunOptions.mcp.setScope(stageId, allow, deny);
+        if (!this.childRunOptions.mcp || !hasScope) return;
+        if (depth === 0) this.childRunOptions.mcp.setScope(stageId, allow, deny);
+        depth += 1;
       },
       clear: () => {
-        if (this.childRunOptions.mcp && hasScope) this.childRunOptions.mcp.clearScope(stageId);
+        if (!this.childRunOptions.mcp || !hasScope) return;
+        if (depth === 0) return;
+        depth -= 1;
+        if (depth === 0) this.childRunOptions.mcp.clearScope(stageId);
       },
     };
   }

package/dist/builtin/workflows/src/extension/extension-factory.ts

@@ -1,5 +1,4 @@
-import { killRun } from "../runs/background/status.js";
-import { cancellationRegistry } from "../runs/background/cancellation-registry.js";
+import { quitRun } from "../runs/background/quit.js";
 import { store } from "../shared/store.js";
 import { subscribeIntercomControl } from "../intercom/result-intercom.js";
 import { buildIntercomCallbacks } from "../intercom/intercom-routing.js";
@@ -7,9 +6,8 @@ import { installStoreWidget, installToolExecutionHooks } from "../tui/store-widg
 import { buildGraphOverlayAdapter } from "../tui/overlay-adapter.js";
 import type { GraphOverlayPort } from "../tui/overlay-adapter.js";
 import { registerInlineFormRenderer } from "../tui/inline-form-overlay.js";
-import { registerChatSurfaceRenderer, emitChatSurface } from "../tui/chat-surface-message.js";
+import { registerChatSurfaceRenderer } from "../tui/chat-surface-message.js";
 import { deriveGraphTheme } from "../tui/graph-theme.js";
-import type { WorkflowPersistencePort } from "../shared/types.js";
 import { renderRunBanner, renderRunSummary, type RunEndPayload, type RunStartPayload } from "./renderers.js";
 import { buildRuntimeAdapters } from "./wiring.js";
 import type { ExtensionAPI, PiCommandContext } from "./public-types.js";
@@ -36,15 +34,11 @@ function registerWorkflowMessageRenderers(pi: ExtensionAPI): void {
 
 function buildWorkflowOverlay(
   pi: ExtensionAPI,
-  getPersistence: () => WorkflowPersistencePort | undefined,
 ): GraphOverlayPort {
   return buildGraphOverlayAdapter(pi, store, {
-    onKillRun: (runId) => {
-      const run = store.runs().find((r) => r.id === runId);
-      const result = killRun(runId, { cancellation: cancellationRegistry, persistence: getPersistence() });
-      if (run && result.ok) {
-        emitChatSurface(pi, { kind: "killed", run, previousStatus: result.previousStatus });
-      }
+    onQuitRun: (runId) => {
+      quitRun(runId, { store });
+      pi.ui?.notify?.(`Workflow quit; resume with /workflow resume.`, "info");
     },
   });
 }
@@ -83,7 +77,7 @@ function registerIntercomControl(
 function factory(pi: ExtensionAPI): void {
   const adapters = buildRuntimeAdapters(pi);
   const runtimeState = createWorkflowExtensionRuntimeState(pi, adapters);
-  const overlay = buildWorkflowOverlay(pi, () => runtimeState.persistenceRef.current);
+  const overlay = buildWorkflowOverlay(pi);
   const workflowCommands = new Map<string, WorkflowCommandHandler>();
   const storeWidgetRef: { current: (() => void) | null } = { current: null };
   const intercomControlRef: { current: (() => void) | null } = { current: null };

package/dist/builtin/workflows/src/extension/extension-lifecycle.ts

@@ -1,4 +1,5 @@
 import { killAllRuns } from "../runs/background/status.js";
+import { quitAllRuns } from "../runs/background/quit.js";
 import { cancellationRegistry } from "../runs/background/cancellation-registry.js";
 import { stageControlRegistry } from "../runs/foreground/stage-control-registry.js";
 import { store } from "../shared/store.js";
@@ -99,7 +100,10 @@ export function registerWorkflowLifecycleHandlers(
     deps.intercomControlRef.current?.();
     deps.intercomControlRef.current = null;
     if (reason === "quit") {
-      killAllRuns({ store, cancellation: cancellationRegistry, persistence: runtimeState.persistenceRef.current });
+      // CLI/orchestrator quit is a resumable process boundary, not explicit
+      // `/workflow kill`. Durable-progress workflows stay available through
+      // `/workflow resume`; stage handles are disposed after being paused.
+      quitAllRuns({ store, stageControlRegistry });
       stageControlRegistry.clear();
     }
     deps.storeWidgetRef.current?.();