@bastani/atomic 0.9.9 → 0.9.10-alpha.1

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

@@ -9,7 +9,7 @@ import { durableHash } from "./backend.js";
 import { recordCheckpointDurably } from "./tool-primitive.js";
 import { elapsedStageMs } from "../shared/timing.js";
 import { RESUME_CONTINUATION_PROMPT } from "../shared/resume-continuation.js";
-import type { DurableStageCheckpoint } from "./types.js";
+import { DURABLE_STAGE_TOPOLOGY_VERSION, type DurableStageCheckpoint } from "./types.js";
 export type DurableCompletedStageCheckpoint = DurableStageCheckpoint & { readonly output: WorkflowSerializableValue };
 
 export interface DurableStageDeps {
@@ -50,6 +50,18 @@ export async function recordStageCheckpoint(deps: DurableStageDeps, stage: Stage
   return true;
 }
 
+/**
+ * Debounce granularity for stage-session duration updates. `durationMs`
+ * differs on virtually every prompt/steer event, so comparing it exactly
+ * forced a full durable read-merge-rewrite per event; identity fields
+ * (session id/file/start) still force an immediate write when they change.
+ */
+const STAGE_SESSION_DURATION_BUCKET_MS = 30_000;
+
+function stageSessionDurationBucket(durationMs: number | undefined): number {
+  return Math.floor((durationMs ?? 0) / STAGE_SESSION_DURATION_BUCKET_MS);
+}
+
 export async function recordStageSessionCheckpoint(deps: DurableStageDeps, stage: StageSnapshot): Promise<boolean> {
   const replayKey = deps.replayKeyForCompletedStage?.(stage) ?? stage.replayKey ?? deps.nextReplayKey(stage.name);
   if (stage.sessionFile === undefined) return false;
@@ -60,7 +72,7 @@ export async function recordStageSessionCheckpoint(deps: DurableStageDeps, stage
     && current.sessionId === stage.sessionId
     && current.sessionFile === stage.sessionFile
     && current.startedAt === stage.startedAt
-    && current.durationMs === durationMs) return false;
+    && stageSessionDurationBucket(current.durationMs) === stageSessionDurationBucket(durationMs)) return false;
   const checkpoint: DurableStageCheckpoint = {
     kind: "stage",
     workflowId: deps.workflowId,
@@ -246,6 +258,7 @@ function stageOutput(stage: StageSnapshot): WorkflowSerializableValue {
 
 function checkpointMetadata(stage: StageSnapshot): Partial<DurableStageCheckpoint> {
   return {
+    topology: { version: DURABLE_STAGE_TOPOLOGY_VERSION, stageId: stage.id, parentIds: [...stage.parentIds] },
     ...(stage.startedAt !== undefined ? { startedAt: stage.startedAt } : {}),
     ...(stage.endedAt !== undefined ? { endedAt: stage.endedAt } : {}),
     ...(stage.durationMs !== undefined ? { durationMs: stage.durationMs } : {}),

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

@@ -15,6 +15,7 @@
  * typescript code and cache the result for DBOS."
  */
 
+import { runCallback } from "@bastani/atomic";
 import type { WorkflowSerializableValue } from "../shared/types.js";
 import type { DurableWorkflowBackend } from "./backend.js";
 import { durableHash } from "./backend.js";
@@ -85,7 +86,15 @@ export function createToolPrimitive(input: CreateToolPrimitiveInput): WorkflowTo
     if (cached !== undefined) return cached as T;
 
     // Execute (with optional retries).
-    const result = await executeWithRetries(fn, options, input.throwIfCancelled, input.signal);
+    const result = await executeWithRetries(
+      () => runCallback(
+        { kind: "workflow.ctx_tool", name, runId: input.workflowId },
+        fn,
+      ),
+      options,
+      input.throwIfCancelled,
+      input.signal,
+    );
 
     // Re-check cancellation after the tool function resolves but BEFORE the
     // side-effect result is durably checkpointed/returned. A side effect that
@@ -110,12 +119,7 @@ export function createToolPrimitive(input: CreateToolPrimitiveInput): WorkflowTo
 }
 
 export async function recordCheckpointDurably(backend: DurableWorkflowBackend, checkpoint: DurableCheckpoint): Promise<void> {
-  if (backend.recordCheckpointAsync !== undefined) {
-    await backend.recordCheckpointAsync(checkpoint);
-    return;
-  }
-  backend.recordCheckpoint(checkpoint);
-  await backend.flush?.();
+  await backend.recordCheckpointAsync(checkpoint);
 }
 
 async function executeWithRetries<T>(

package/dist/builtin/workflows/src/durable/types.ts

@@ -10,7 +10,6 @@
  */
 
 import type { WorkflowModelAttempt, WorkflowSerializableValue } from "../shared/types.js";
-import type { DURABLE_FORMAT_VERSION } from "./format-version.js";
 
 // ---------------------------------------------------------------------------
 // Top-level workflow identity
@@ -53,6 +52,8 @@ export interface DurableWorkflowHandle {
   readonly rootWorkflowId?: string;
   /** Explicit resumability flag for failed/blocked runs. */
   readonly resumable?: boolean;
+  /** Executor id of the Atomic process that last wrote this workflow's metadata. */
+  readonly ownerExecutorId?: string;
 }
 
 export type DurableWorkflowStatus =
@@ -107,6 +108,15 @@ export interface DurableUiCheckpoint {
   readonly completedAt: number;
 }
 
+export const DURABLE_STAGE_TOPOLOGY_VERSION = 1 as const;
+
+/** Versioned source-stage lineage used to reconstruct completed DAGs after restart. */
+export interface DurableStageTopology {
+  readonly version: typeof DURABLE_STAGE_TOPOLOGY_VERSION;
+  readonly stageId: string;
+  readonly parentIds: readonly string[];
+}
+
 /** A `ctx.stage(...)` / `ctx.task(...)` durable checkpoint or resumable session marker. */
 export interface DurableStageCheckpoint {
   readonly kind: "stage";
@@ -116,6 +126,8 @@ export interface DurableStageCheckpoint {
   readonly name: string;
   /** Stable replay key (matches existing continuation replay semantics). */
   readonly replayKey: string;
+  /** Source stage identity and parents for fresh-process completed-run inspection. */
+  readonly topology?: DurableStageTopology;
   /** Stage output text or structured result when the stage completed. */
   readonly output?: WorkflowSerializableValue;
   /** Resumable Atomic/Pi session metadata for in-progress LM stages. */
@@ -146,26 +158,24 @@ export type UiPromptKind = "input" | "confirm" | "select" | "editor" | "custom";
 export type WorkflowSerializableObject = Readonly<Record<string, WorkflowSerializableValue>>;
 
 // ---------------------------------------------------------------------------
-// Resume catalog entry (cached on session JSONL)
+// DBOS metadata and resume catalog
 // ---------------------------------------------------------------------------
 
-/**
- * Durable workflow metadata cached as a `workflow.durable.checkpoint` session
- * entry. This is the session-file cache described by the issue — it lets a new
- * session discover resumable workflows without scanning the full DBOS system
- * database. DBOS remains the checkpoint source of truth; this cache mirrors
- * the minimal top-level metadata needed for `/workflow resume` discovery.
- */
-export interface DurableCheckpointEntry {
-  /** Durable metadata schema version used to reject incompatible discovery rows. */
-  readonly formatVersion: typeof DURABLE_FORMAT_VERSION;
-  readonly type: "workflow.durable.checkpoint";
+/** Current workflow metadata persisted in DBOS. */
+export interface DurableWorkflowMetadata {
   readonly workflowId: string;
   readonly name: string;
   readonly inputs: WorkflowSerializableObject;
   readonly status: DurableWorkflowStatus;
   readonly completedCheckpoints: number;
   readonly pendingPrompts: number;
+  readonly createdAt: number;
+  readonly promptReservationEpoch: string;
+  /** Executor id of the Atomic process that wrote this metadata generation. */
+  readonly ownerExecutorId?: string;
+  /** Unique winner token for a first-writer-wins status-transition generation. */
+  readonly transitionClaimId?: string;
+  readonly sessionFile?: string;
   readonly label?: string;
   readonly rootWorkflowId?: string;
   readonly resumable?: boolean;
@@ -173,13 +183,10 @@ export interface DurableCheckpointEntry {
   readonly workflowCwd?: string;
   readonly repositoryRoot?: string;
   readonly gitWorktreeRoot?: string;
-  readonly ts: number;
+  readonly updatedAt: number;
 }
 
-/**
- * Resume catalog entry for the cross-session `/workflow resume` selector.
- * Built from durable checkpoint entries found across session files.
- */
+/** Resume catalog entry loaded directly from DBOS metadata. */
 export interface ResumableWorkflowEntry {
   readonly workflowId: string;
   readonly name: string;

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

@@ -6,10 +6,13 @@ import type {
   WorkflowUIContext,
 } from "../shared/authoring-contract-ui.js";
 import type { WorkflowSerializableValue } from "../shared/types.js";
+import { withPromptCallerStack } from "../shared/prompt-callsite-context.js";
+import { selectPromptCallsiteFrame } from "../runs/shared/prompt-callsite.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";
+import { claimDurablePromptToken, durablePromptScope, releaseDurablePrompt, reserveDurablePrompt, type PromptReservationToken } from "./prompt-reservations.js";
 
 export interface DurableUiDeps {
   readonly workflowId: string;
@@ -20,11 +23,25 @@ export interface DurableUiDeps {
 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 scope = durablePromptScope(deps.backend, deps.workflowId);
+  const nextIdentity = (
+    kind: UiPromptKind,
+    message: string,
+    callerStack: string | undefined,
+    details?: WorkflowSerializableValue,
+  ): { key: string; hash: string } => {
+    const authorCallsite = selectPromptCallsiteFrame(callerStack ?? "") ?? "unknown";
+    const descriptor = { kind, message, details: details ?? null };
+    const baseIdentity = {
+      rootWorkflowId: scope.rootWorkflowId,
+      scope: scope.scope,
+      authorCallsite: durableHash({ authorCallsite }),
+      descriptor,
+    };
+    const baseKey = durableHash(baseIdentity);
     const ordinal = (ordinals.get(baseKey) ?? 0) + 1;
     ordinals.set(baseKey, ordinal);
-    const identity = { kind, message, details: details ?? null, ordinal };
+    const identity = ordinal === 1 ? baseIdentity : { ...baseIdentity, ordinal };
     return { key: JSON.stringify(identity), hash: durableHash(identity) };
   };
 
@@ -46,51 +63,122 @@ export function wrapUiWithDurable(base: WorkflowUIContext, deps: DurableUiDeps):
 
   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);
+      .find((checkpoint) => checkpoint.kind === "ui"
+        && (checkpoint.promptHash === identity.hash || checkpoint.promptHash.endsWith(`:${identity.hash}`)));
     return hit?.kind === "ui" ? { found: true, response: hit.response } : { found: false };
   };
 
+  const releasePending = async (identity: { readonly hash: string }, token: PromptReservationToken): Promise<void> => {
+    releaseDurablePrompt(deps.backend, deps.workflowId, identity.hash, token);
+    await deps.backend.flush();
+  };
+  const beginPending = (identity: { readonly hash: string }): {
+    readonly token: PromptReservationToken;
+    readonly write?: Promise<void>;
+  } => {
+    const token = reserveDurablePrompt(deps.backend, deps.workflowId, identity.hash);
+    const write = deps.backend.flush();
+    return { token, write };
+  };
+  const waitForPendingWrite = async (
+    identity: { readonly hash: string },
+    pending: { readonly token: PromptReservationToken; readonly write?: Promise<void> },
+  ): Promise<void> => {
+    if (pending.write === undefined) return;
+    try {
+      await pending.write;
+    } catch (error) {
+      releaseDurablePrompt(deps.backend, deps.workflowId, identity.hash, pending.token);
+      try { await deps.backend.flush(); } catch { /* Preserve the opening-write failure. */ }
+      throw error;
+    }
+  };
+  const releaseCached = async (identity: { readonly hash: string }): Promise<void> => {
+    const token = claimDurablePromptToken(deps.backend, deps.workflowId, identity.hash);
+    if (token !== undefined) await releasePending(identity, token);
+  };
+
   return {
     async input(promptText: string): Promise<string> {
-      const identity = nextIdentity("input", promptText);
+      const callerStack = new Error().stack;
+      const identity = nextIdentity("input", promptText, callerStack);
       const hit = cached(identity);
-      if (typeof hit === "string") return hit;
-      const response = await base.input(promptText);
-      await record("input", identity, response);
-      return response;
+      if (typeof hit === "string") {
+        await releaseCached(identity);
+        return hit;
+      }
+      const pending = beginPending(identity);
+      await waitForPendingWrite(identity, pending);
+      try {
+        const response = await withPromptCallerStack(callerStack, () => base.input(promptText));
+        await record("input", identity, response);
+        return response;
+      } finally { await releasePending(identity, pending.token); }
     },
     async confirm(message: string): Promise<boolean> {
-      const identity = nextIdentity("confirm", message);
+      const callerStack = new Error().stack;
+      const identity = nextIdentity("confirm", message, callerStack);
       const hit = cached(identity);
-      if (typeof hit === "boolean") return hit;
-      const response = await base.confirm(message);
-      await record("confirm", identity, response);
-      return response;
+      if (typeof hit === "boolean") {
+        await releaseCached(identity);
+        return hit;
+      }
+      const pending = beginPending(identity);
+      await waitForPendingWrite(identity, pending);
+      try {
+        const response = await withPromptCallerStack(callerStack, () => base.confirm(message));
+        await record("confirm", identity, response);
+        return response;
+      } finally { await releasePending(identity, pending.token); }
     },
     async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
-      const identity = nextIdentity("select", message, [...options]);
+      const callerStack = new Error().stack;
+      const identity = nextIdentity("select", message, callerStack, [...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;
+      if (typeof hit === "string") {
+        await releaseCached(identity);
+        return hit as T;
+      }
+      const pending = beginPending(identity);
+      await waitForPendingWrite(identity, pending);
+      try {
+        const response = await withPromptCallerStack(callerStack, () => base.select<T>(message, options));
+        await record("select", identity, response);
+        return response;
+      } finally { await releasePending(identity, pending.token); }
     },
     async editor(initial?: string): Promise<string> {
-      const identity = nextIdentity("editor", initial ?? "", initial ?? null);
+      const callerStack = new Error().stack;
+      const identity = nextIdentity("editor", initial ?? "", callerStack, 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;
+      if (typeof hit === "string") {
+        await releaseCached(identity);
+        return hit;
+      }
+      const pending = beginPending(identity);
+      await waitForPendingWrite(identity, pending);
+      try {
+        const response = await withPromptCallerStack(callerStack, () => base.editor(initial));
+        await record("editor", identity, response);
+        return response;
+      } finally { await releasePending(identity, pending.token); }
     },
     async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
+      const callerStack = new Error().stack;
       const replayIdentity = options?.replayIdentity ?? factory?.name ?? "custom";
-      const identity = nextIdentity("custom", replayIdentity, { replayIdentity });
+      const identity = nextIdentity("custom", replayIdentity, callerStack, { 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;
+      if (hit.found) {
+        await releaseCached(identity);
+        return hit.response as T;
+      }
+      const pending = beginPending(identity);
+      await waitForPendingWrite(identity, pending);
+      try {
+        const response = await withPromptCallerStack(callerStack, () => base.custom<T>(factory, options));
+        await record("custom", identity, response as WorkflowSerializableValue);
+        return response;
+      } finally { await releasePending(identity, pending.token); }
     },
   };
 }

package/dist/builtin/workflows/src/durable/workflow-status-transition.ts

@@ -0,0 +1,30 @@
+import type { DurableWorkflowHandle, DurableWorkflowStatus } from "./types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+
+/** Read one loadable handle without combining objects from different generations. */
+export function getLoadableDurableWorkflow(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+): DurableWorkflowHandle | undefined {
+  return backend.getLoadableWorkflow(workflowId);
+}
+
+/** Terminal durable generations cannot be reopened by stale nonterminal writers. */
+export function isAbsorbingDurableStatus(status: DurableWorkflowStatus, resumable?: boolean): boolean {
+  return status === "completed" || status === "cancelled"
+    || ((status === "failed" || status === "blocked") && resumable === false);
+}
+
+/** Perform a required conditional status transition. */
+export async function transitionDurableWorkflowStatus(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+  expectedStatuses: readonly DurableWorkflowStatus[],
+  status: DurableWorkflowStatus,
+  pendingPrompts?: number,
+  resumable?: boolean,
+): Promise<boolean> {
+  return await backend.transitionWorkflowStatus(
+    workflowId, expectedStatuses, status, pendingPrompts, resumable,
+  );
+}

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

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import type { WorkflowParallelOptions, WorkflowTaskResult, WorkflowTaskStep } from "../../shared/types.js";
 import type { EngineRuntime } from "../runtime.js";
 import type { WorkflowTaskPrimitive } from "./task.js";
@@ -11,6 +12,7 @@ import {
   taskPrevious,
   taskWithSharedDefaults,
 } from "../../runs/foreground/executor-task-prompts.js";
+import { normalizeAutoGroupSentinel } from "../../shared/intercom-group.js";
 
 export function createParallelPrimitive(input: {
   readonly runtime: EngineRuntime;
@@ -18,19 +20,32 @@ export function createParallelPrimitive(input: {
 }): (steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions) => Promise<WorkflowTaskResult[]> {
   return async (steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions = {}): Promise<WorkflowTaskResult[]> => {
     input.runtime.exit.throwIfWorkflowExitSelected();
-    const fallback = parallelFallbackTask(steps, options);
-    const failFastEnabled = options.failFast !== false;
+    // Normalize both authored and agent-serialized sentinels before deciding
+    // whether this invocation needs one shared auto-group UUID.
+    const normalizeGroup = <T extends { group?: string | true }>(value: T): T =>
+      value.group === undefined ? value : { ...value, group: normalizeAutoGroupSentinel(value.group) };
+    const normalizedOptions = normalizeGroup(options);
+    const normalizedSteps = steps.map(normalizeGroup);
+    const needsAutoGroup = normalizedOptions.group === true
+      || normalizedSteps.some((step) => step.group === true);
+    const autoGroup = needsAutoGroup ? randomUUID() : undefined;
+    const resolveAutoGroup = <T extends { group?: string | true }>(value: T): T =>
+      value.group === true && autoGroup ? { ...value, group: autoGroup } : value;
+    const resolvedOptions = resolveAutoGroup(normalizedOptions);
+    const resolvedSteps = normalizedSteps.map(resolveAutoGroup);
+    const fallback = parallelFallbackTask(resolvedSteps, resolvedOptions);
+    const failFastEnabled = resolvedOptions.failFast !== false;
     const parallelScope: ParallelFailFastScope = {
       failed: false,
       activeStages: new Map<string, ParallelFailFastStage>(),
       parentIds: Object.freeze(input.runtime.tracker.currentParents()),
     };
-    return mapParallelSteps(steps, options.concurrency, options.failFast, async (step) => {
+    return mapParallelSteps(resolvedSteps, resolvedOptions.concurrency, resolvedOptions.failFast, async (step) => {
       input.runtime.exit.throwIfWorkflowExitSelected();
-      const prompt = replaceTaskPlaceholder(step.prompt ?? step.task ?? fallback, options.task ?? fallback);
+      const prompt = replaceTaskPlaceholder(step.prompt ?? step.task ?? fallback, resolvedOptions.task ?? fallback);
       return await input.task(
         step.name,
-        taskWithSharedDefaults(taskOptionsFromStep(step, prompt, taskPrevious(step)), options),
+        taskWithSharedDefaults(taskOptionsFromStep(step, prompt, taskPrevious(step)), resolvedOptions),
         parallelScope,
       );
     }, async (error) => {

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

@@ -15,7 +15,7 @@ import {
 import {
   cleanupPreparedWorktrees,
   collectWorktreeDiffs,
-  prepareDirectWorktrees,
+  prepareTaskWorktrees,
   stageOptionsWithGitWorktree,
   stageOptionsWithInputDefaults,
 } from "../../runs/foreground/executor-direct-helpers.js";
@@ -81,12 +81,13 @@ function createTaskPrimitive(runtime: EngineRuntime): WorkflowTaskPrimitive {
     };
 
     if (options.worktree !== true) return runTaskOnce(options);
-    const prepared = prepareDirectWorktrees(
+    const prepared = prepareTaskWorktrees(
       [{ ...options, name }],
       { ...options, worktree: true },
       `${runtime.runId}-${name}-${crypto.randomUUID()}`,
       name,
       runtime.workflowInvocationCwd,
+      runtime.worktreeSymlinkDirectories,
     );
     const preparedTask = prepared.tasks[0]!;
     try {

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

@@ -27,9 +27,12 @@ export function buildExitGatedUiContext(input: BuildExitGatedUiContextInput): Wo
     : 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;
+  // Prompt-node continuation owns replay so its stage remains observable;
+  // durable response replay is for non-node UI and fresh redispatches.
+  const promptNodeReplay = input.opts.usePromptNodesForUi === true && input.opts.continuation !== undefined;
+  const durableBase = input.durableUi !== undefined && !promptNodeReplay
+    ? wrapUiWithDurable(base, input.durableUi)
+    : base;
   return {
     async input(promptText: string): Promise<string> {
       input.throwIfWorkflowExitSelected();

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

@@ -10,46 +10,38 @@
  */
 
 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";
+import { recordRunTimingCheckpoint } from "../durable/run-timing.js";
+import { effectiveRunStatus } from "../shared/returned-run-status.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.
- */
+/** Persist the terminal durable status and surface DBOS write failures. */
 export async function finalizeDurableTerminalStatus(input: DurableTerminalFinalizeInput): Promise<void> {
   if (!input.isRoot) return;
-  const status = input.runSnapshot.status;
+  const status = effectiveRunStatus(input.runSnapshot);
   const isExitTerminal = input.runSnapshot.exited === true && status !== "running";
-  const isReturnedBlockedTerminal = status === "blocked" && input.runSnapshot.endedAt !== undefined;
-  if (status !== "failed" && status !== "killed" && !isExitTerminal && !isReturnedBlockedTerminal) return;
+  const isBlocked = status === "blocked"
+    && (input.runSnapshot.endedAt !== undefined || input.runSnapshot.blockedAt !== undefined);
+  if (status !== "failed" && status !== "killed" && !isExitTerminal && !isBlocked) return;
 
   const durableStatus = toDurableStatus(status);
   if (durableStatus !== undefined) {
+    // Failed/blocked runs may be resumed cross-session by workflow id; persist
+    // the exact accumulated elapsed so the resumed dashboard total continues
+    // from the prior sessions instead of restarting at zero.
+    if (durableStatus === "failed" || durableStatus === "blocked") {
+      recordRunTimingCheckpoint(input.durableBackend, input.runSnapshot);
+    }
     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);
-  }
+  await input.durableBackend.flush();
 }
 
 function toDurableStatus(status: RunSnapshot["status"]): DurableWorkflowStatus | undefined {

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

@@ -1,15 +1,18 @@
-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 type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
 import { recordStageSessionCheckpoint, type DurableStageDeps } from "../durable/stage-primitive.js";
+import { recordRunTimingCheckpoint } from "../durable/run-timing.js";
 
 export interface DurableStageSessionRecorderInput {
   readonly runId: string;
   readonly deps: DurableStageDeps;
-  readonly backend: DurableWorkflowBackend;
-  readonly persistence?: WorkflowPersistencePort;
   readonly onStageSession?: (runId: string, snapshot: StageSnapshot) => unknown;
+  /**
+   * Live root-run snapshot. When present, stage-session checkpoints also
+   * refresh the debounced run-level elapsed record so a durable resume can
+   * seed the total workflow duration. Omitted for child runs — run timing is
+   * only tracked for the root workflow.
+   */
+  readonly runSnapshot?: RunSnapshot;
 }
 
 export function createDurableStageSessionRecorder(
@@ -17,14 +20,11 @@ export function createDurableStageSessionRecorder(
 ): (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 recordStageSessionCheckpoint(input.deps, snapshot).then(() => {
+        if (input.runSnapshot !== undefined) {
+          recordRunTimingCheckpoint(input.deps.backend, input.runSnapshot, { debounce: true });
+        }
+      }).catch(() => {});
     }
     void input.onStageSession?.(stageRunId, snapshot);
   };