@bastani/atomic 0.9.10 → 0.9.11-alpha.2

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

@@ -1,4 +1,4 @@
-/** DBOS-only durable backend factory and internal test injection seam. */
+/** DBOS-first durable backend factory with a non-durable last-resort fallback. */
 
 import { InMemoryDurableBackend, type DurableWorkflowBackend } from "./backend.js";
 import {
@@ -9,8 +9,9 @@ import {
 
 let injectedBackend: DurableWorkflowBackend | undefined;
 let initializedBackend: DurableWorkflowBackend | undefined;
+let initializing: Promise<DurableWorkflowBackend> | undefined;
 
-/** Return the injected test backend or the process-wide ready DBOS backend. */
+/** Return the injected test backend or the process-wide initialized backend. */
 export function getDurableBackend(): DurableWorkflowBackend {
   const backend = injectedBackend ?? initializedBackend ?? getReadyDbosBackendSync();
   if (backend === undefined) throw new DbosNotReadyError();
@@ -20,7 +21,10 @@ export function getDurableBackend(): DurableWorkflowBackend {
 /** Internal injection seam. Production initialization uses DBOS. */
 export function setDurableBackend(backend: DurableWorkflowBackend | undefined): void {
   injectedBackend = backend;
-  if (backend === undefined) initializedBackend = undefined;
+  if (backend === undefined) {
+    initializedBackend = undefined;
+    initializing = undefined;
+  }
 }
 
 /** Create an isolated current-interface backend for tests only. */
@@ -28,9 +32,34 @@ export function createInMemoryTestBackend(): InMemoryDurableBackend {
   return new InMemoryDurableBackend();
 }
 
-/** Configure, register, launch, and install the mandatory DBOS backend. */
+/**
+ * Configure, register, launch, and install the DBOS backend.
+ *
+ * When no durable backend can be provisioned (no `DBOS_SYSTEM_DATABASE_URL`,
+ * embedded Postgres unavailable — e.g. running as root without an
+ * unprivileged account — and no Docker), workflows degrade to a process-local
+ * in-memory backend with a loud warning instead of refusing to run at all.
+ * Non-durable runs execute normally but do not survive the process:
+ * `/workflow resume` after exit has nothing to restore.
+ */
 export async function initializeDurableBackend(): Promise<DurableWorkflowBackend> {
   if (injectedBackend !== undefined) return injectedBackend;
-  initializedBackend ??= await getReadyDbosBackend();
-  return initializedBackend;
+  if (initializedBackend !== undefined) return initializedBackend;
+  initializing ??= getReadyDbosBackend()
+    .catch((error: unknown) => degradeToNonDurableBackend(error))
+    .then((backend) => {
+      initializedBackend = backend;
+      return backend;
+    });
+  return await initializing;
+}
+
+function degradeToNonDurableBackend(error: unknown): DurableWorkflowBackend {
+  const detail = error instanceof Error ? error.message : String(error);
+  console.error(
+    "atomic-workflows: durable backend unavailable — continuing NON-DURABLY with an in-memory backend. "
+    + "Workflow runs will execute, but their state will not survive this process and `/workflow resume` "
+    + `after exit will not work. Restore durability by fixing Postgres provisioning: ${detail}`,
+  );
+  return new InMemoryDurableBackend();
 }

package/dist/builtin/workflows/src/durable/local-command.ts

@@ -11,16 +11,25 @@ export interface LocalCommandResult {
 
 const OUTPUT_LIMIT_BYTES = 16_384;
 
+export interface LocalCommandOptions {
+  readonly env?: Readonly<Record<string, string>>;
+  /** POSIX drop-privilege identity for the spawned process (root only). */
+  readonly uid?: number;
+  readonly gid?: number;
+}
+
 export function runLocalCommand(
   command: string,
   args: readonly string[],
-  env?: Readonly<Record<string, string>>,
+  options?: LocalCommandOptions,
 ): Promise<LocalCommandResult> {
   return new Promise((resolve, reject) => {
     const child = spawn(command, [...args], {
       stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true,
-      ...(env !== undefined ? { env: { ...process.env, ...env } } : {}),
+      ...(options?.env !== undefined ? { env: { ...process.env, ...options.env } } : {}),
+      ...(options?.uid !== undefined ? { uid: options.uid } : {}),
+      ...(options?.gid !== undefined ? { gid: options.gid } : {}),
     });
     let stdout = "";
     let stderr = "";

package/dist/builtin/workflows/src/durable/resume-runtime.ts

@@ -18,7 +18,7 @@
  * top-level workflow id."
  */
 
-import type { WorkflowInputValues } from "../shared/types.js";
+import type { WorkflowDefinition, WorkflowInputValues } from "../shared/types.js";
 import type { WorkflowRegistry } from "../workflows/registry.js";
 import type { RunOpts } from "../runs/foreground/executor-types.js";
 import { launchDetachedUntilStartup, workflowStartupFailureMessage } from "../runs/background/startup-admission.js";
@@ -44,6 +44,8 @@ export interface ResumeDurableDeps {
   readonly baseRunOpts: RunOpts;
   /** Durable backend override (defaults to the global singleton). */
   readonly durableBackend?: DurableWorkflowBackend;
+  /** Resolve a definition from its original invocation directory after restart. */
+  readonly resolveDefinition?: (name: string, cwd: string | undefined) => Promise<WorkflowDefinition | undefined>;
   /** Job tracker used by the detached resume launch. */
   readonly jobs?: JobTracker;
 }
@@ -146,7 +148,9 @@ export async function resumeDurableWorkflow(
     return { ok: false, reason: "not_resumable", message: `Workflow ${resolved.workflowId.slice(0, 8)} is ${handle.status}, not resumable.` };
   }
 
-  const def = deps.registry.get(handle.name);
+  const def = handle.invocationCwd === undefined
+    ? deps.registry.get(handle.name)
+    : await deps.resolveDefinition?.(handle.name, handle.invocationCwd) ?? deps.registry.get(handle.name);
   if (def === undefined) {
     return { ok: false, reason: "workflow_not_found", message: `Workflow definition not found: ${handle.name}` };
   }

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 { DURABLE_STAGE_TOPOLOGY_VERSION, type DurableStageCheckpoint } from "./types.js";
+import { DURABLE_STAGE_TOPOLOGY_VERSION, type DurableStageCheckpoint, type DurableStageRunTopology } from "./types.js";
 export type DurableCompletedStageCheckpoint = DurableStageCheckpoint & { readonly output: WorkflowSerializableValue };
 
 export interface DurableStageDeps {
@@ -18,13 +18,14 @@ export interface DurableStageDeps {
   readonly nextCheckpointId: () => string;
   readonly nextReplayKey: (stageName: string) => string;
   readonly replayKeyForCompletedStage?: (stage: StageSnapshot) => string | undefined;
+  readonly runTopology?: DurableStageRunTopology;
   readonly now?: () => number;
 }
 
 export async function recordStageCheckpoint(deps: DurableStageDeps, stage: StageSnapshot): Promise<boolean> {
   if (stage.status !== "completed") return false;
   const replayKey = deps.replayKeyForCompletedStage?.(stage) ?? stage.replayKey ?? deps.nextReplayKey(stage.name);
-  const metadata = checkpointMetadata(stage);
+  const metadata = durableStageCheckpointMetadata(stage, deps.runTopology);
   const hasExistingOutput = deps.backend.getStageOutput(deps.workflowId, replayKey) !== undefined;
   const checkpoint: DurableStageCheckpoint = hasExistingOutput
     ? {
@@ -62,13 +63,17 @@ 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> {
+export async function recordStageSessionCheckpoint(
+  deps: DurableStageDeps,
+  stage: StageSnapshot,
+  options?: { readonly force?: boolean },
+): Promise<boolean> {
   const replayKey = deps.replayKeyForCompletedStage?.(stage) ?? stage.replayKey ?? deps.nextReplayKey(stage.name);
   if (stage.sessionFile === undefined) return false;
   const checkpointNow = deps.now?.() ?? Date.now();
   const durationMs = elapsedStageMs(stage, checkpointNow) ?? 0;
   const current = deps.backend.getStageSession(deps.workflowId, replayKey);
-  if (current !== undefined
+  if (options?.force !== true && current !== undefined
     && current.sessionId === stage.sessionId
     && current.sessionFile === stage.sessionFile
     && current.startedAt === stage.startedAt
@@ -79,6 +84,7 @@ export async function recordStageSessionCheckpoint(deps: DurableStageDeps, stage
     checkpointId: stageSessionCheckpointId(replayKey, stage, durationMs),
     name: stage.name,
     replayKey,
+    ...durableStageCheckpointMetadata(stage, deps.runTopology),
     ...(stage.sessionId !== undefined ? { sessionId: stage.sessionId } : {}),
     sessionFile: stage.sessionFile,
     ...(stage.startedAt !== undefined ? { startedAt: stage.startedAt } : {}),
@@ -256,9 +262,17 @@ function stageOutput(stage: StageSnapshot): WorkflowSerializableValue {
   return { status: stage.status, stageId: stage.id };
 }
 
-function checkpointMetadata(stage: StageSnapshot): Partial<DurableStageCheckpoint> {
+export function durableStageCheckpointMetadata(
+  stage: StageSnapshot,
+  run?: DurableStageRunTopology,
+): Partial<DurableStageCheckpoint> {
   return {
-    topology: { version: DURABLE_STAGE_TOPOLOGY_VERSION, stageId: stage.id, parentIds: [...stage.parentIds] },
+    topology: {
+      version: DURABLE_STAGE_TOPOLOGY_VERSION,
+      stageId: stage.id,
+      parentIds: [...stage.parentIds],
+      ...(run !== undefined ? { run: { ...run } } : {}),
+    },
     ...(stage.startedAt !== undefined ? { startedAt: stage.startedAt } : {}),
     ...(stage.endedAt !== undefined ? { endedAt: stage.endedAt } : {}),
     ...(stage.durationMs !== undefined ? { durationMs: stage.durationMs } : {}),
@@ -311,6 +325,7 @@ function mergeCheckpointHydrationMetadata(
   if (checkpoints.length === 0) return replayValueCheckpoint;
   return {
     ...replayValueCheckpoint,
+    ...preferredHydrationTopology(replayValueCheckpoint, checkpoints),
     ...(replayValueCheckpoint.startedAt === undefined ? metadataValue(checkpoints, "startedAt") : {}),
     ...(replayValueCheckpoint.endedAt === undefined ? metadataValue(checkpoints, "endedAt") : {}),
     ...(replayValueCheckpoint.durationMs === undefined ? metadataValue(checkpoints, "durationMs") : {}),
@@ -323,6 +338,19 @@ function mergeCheckpointHydrationMetadata(
     ...(replayValueCheckpoint.modelAttempts === undefined ? metadataValue(checkpoints, "modelAttempts") : {}),
   };
 }
+function preferredHydrationTopology(
+  replayValueCheckpoint: DurableCompletedStageCheckpoint,
+  checkpoints: readonly DurableStageCheckpoint[],
+): Pick<DurableStageCheckpoint, "topology"> | Record<string, never> {
+  for (let index = checkpoints.length - 1; index >= 0; index -= 1) {
+    const topology = checkpoints[index]?.topology;
+    if (topology?.run !== undefined) return { topology };
+  }
+  return replayValueCheckpoint.topology === undefined
+    ? metadataValue(checkpoints, "topology")
+    : {};
+}
+
 
 function metadataValue<K extends keyof DurableStageCheckpoint>(
   checkpoints: readonly DurableStageCheckpoint[],
@@ -390,6 +418,7 @@ export function recordCachedStageIntoStore(
     id: stageId, name, status: "completed", parentIds: parentIds !== undefined ? Object.freeze([...parentIds]) : [],
     startedAt: checkpoint?.startedAt ?? endedAt, endedAt, durationMs: checkpoint?.durationMs ?? 0, result,
     replayKey, replayed: true, skippedReason: "durable checkpoint replay", toolEvents: [], attachable: false,
+    ...(checkpoint?.topology !== undefined ? { replayedFromStageId: checkpoint.topology.stageId } : {}),
     ...(workflowChild !== undefined ? { workflowChild } : {}),
     ...(checkpoint?.sessionId !== undefined ? { sessionId: checkpoint.sessionId } : {}),
     ...(checkpoint?.sessionFile !== undefined ? { sessionFile: checkpoint.sessionFile } : {}),
@@ -420,10 +449,19 @@ export function recordCachedStageWithTracker(
 ): void {
   const stageId = cachedStageId(runId, replayKey);
   let parentIds = tracker.onSpawn(stageId, name);
-  const scopeParentIds = stageFailFastScope?.parentIds ?? [];
-  if (stageFailFastScope !== undefined) {
-    tracker.replaceParents(stageId, scopeParentIds);
-    parentIds = [...scopeParentIds];
+  const sourceParents = checkpoint.topology?.run?.runId === runId
+    ? checkpoint.topology.parentIds
+    : undefined;
+  const run = store.runs().find((candidate) => candidate.id === runId);
+  const restored = sourceParents?.map((sourceId) =>
+    run?.stages.find((stage) => stage.replayedFromStageId === sourceId)?.id
+  );
+  if (restored !== undefined && restored.every((id): id is string => id !== undefined)) {
+    parentIds = restored;
+    tracker.replaceParents(stageId, parentIds);
+  } else if (stageFailFastScope !== undefined) {
+    parentIds = [...(stageFailFastScope.parentIds ?? [])];
+    tracker.replaceParents(stageId, parentIds);
   }
   recordCachedStageIntoStore(store, runId, name, replayKey, checkpoint.output, completedStageReplayKeys, parentIds, checkpoint);
   tracker.onSettle(stageId);

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

@@ -110,11 +110,22 @@ export interface DurableUiCheckpoint {
 
 export const DURABLE_STAGE_TOPOLOGY_VERSION = 1 as const;
 
+/** Durable ownership metadata needed to rebuild nested workflow runs. */
+export interface DurableStageRunTopology {
+  readonly runId: string;
+  readonly runName: string;
+  readonly parentRunId?: string;
+  readonly parentStageId?: string;
+  readonly rootRunId?: string;
+}
+
 /** 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[];
+  /** Owning run and boundary linkage for nested workflow graph reconstruction. */
+  readonly run?: DurableStageRunTopology;
 }
 
 /** A `ctx.stage(...)` / `ctx.task(...)` durable checkpoint or resumable session marker. */

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

@@ -1,11 +1,12 @@
 import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
 import { recordStageSessionCheckpoint, type DurableStageDeps } from "../durable/stage-primitive.js";
+import type { StageSessionCheckpointOptions } from "../runs/foreground/executor-types.js";
 import { recordRunTimingCheckpoint } from "../durable/run-timing.js";
 
 export interface DurableStageSessionRecorderInput {
   readonly runId: string;
   readonly deps: DurableStageDeps;
-  readonly onStageSession?: (runId: string, snapshot: StageSnapshot) => unknown;
+  readonly onStageSession?: (runId: string, snapshot: StageSnapshot, options?: StageSessionCheckpointOptions) => unknown;
   /**
    * Live root-run snapshot. When present, stage-session checkpoints also
    * refresh the debounced run-level elapsed record so a durable resume can
@@ -17,15 +18,14 @@ export interface DurableStageSessionRecorderInput {
 
 export function createDurableStageSessionRecorder(
   input: DurableStageSessionRecorderInput,
-): (stageRunId: string, snapshot: StageSnapshot) => void {
-  return (stageRunId, snapshot) => {
+): (stageRunId: string, snapshot: StageSnapshot, options?: StageSessionCheckpointOptions) => Promise<void> {
+  return async (stageRunId, snapshot, options) => {
     if (stageRunId === input.runId) {
-      void recordStageSessionCheckpoint(input.deps, snapshot).then(() => {
-        if (input.runSnapshot !== undefined) {
-          recordRunTimingCheckpoint(input.deps.backend, input.runSnapshot, { debounce: true });
-        }
-      }).catch(() => {});
+      await recordStageSessionCheckpoint(input.deps, snapshot, { force: options?.forceDurable === true });
+      if (input.runSnapshot !== undefined) {
+        recordRunTimingCheckpoint(input.deps.backend, input.runSnapshot, { debounce: options?.forceDurable !== true });
+      }
     }
-    void input.onStageSession?.(stageRunId, snapshot);
+    await input.onStageSession?.(stageRunId, snapshot, options);
   };
 }

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

@@ -0,0 +1,89 @@
+import { durableHash, type DurableWorkflowBackend } from "../durable/backend.js";
+import { durableNestedRunSnapshots } from "../durable/completed-catalog.js";
+import {
+  durableStageCheckpointMetadata,
+  recordCachedStageWithTracker,
+  type DurableCompletedStageCheckpoint,
+  type DurableStageDeps,
+} from "../durable/stage-primitive.js";
+import type { DurableStageRunTopology } from "../durable/types.js";
+import type { GraphFrontierTracker } from "./graph-inference.js";
+import type { RunSnapshot } from "../shared/store-types.js";
+import type { Store } from "../shared/store.js";
+import type { ParallelFailFastScope } from "../runs/foreground/executor-types.js";
+
+export function durableRunTopology(run: RunSnapshot): DurableStageRunTopology {
+  return {
+    runId: run.id,
+    runName: run.name,
+    ...(run.parentRunId !== undefined ? { parentRunId: run.parentRunId } : {}),
+    ...(run.parentStageId !== undefined ? { parentStageId: run.parentStageId } : {}),
+    ...(run.rootRunId !== undefined ? { rootRunId: run.rootRunId } : {}),
+  };
+}
+
+export function createDurableStageDeps(input: {
+  readonly backend: DurableWorkflowBackend;
+  readonly run: RunSnapshot;
+  readonly nextCheckpointId: () => string;
+  readonly nextReplayKey: (stageName: string) => string;
+  readonly completedReplayKeys: Map<string, string>;
+}): DurableStageDeps {
+  return {
+    workflowId: input.run.id,
+    backend: input.backend,
+    nextCheckpointId: input.nextCheckpointId,
+    nextReplayKey: input.nextReplayKey,
+    replayKeyForCompletedStage: (stage) => input.completedReplayKeys.get(stage.id),
+    runTopology: durableRunTopology(input.run),
+  };
+}
+
+export function createDurableCachedStageRecorder(input: {
+  readonly store: Store;
+  readonly tracker: GraphFrontierTracker;
+  readonly run: RunSnapshot;
+  readonly backend: DurableWorkflowBackend;
+  readonly rootBackend: DurableWorkflowBackend;
+  readonly completedStageReplayKeys: Map<string, string>;
+}): {
+  readonly record: (name: string, replayKey: string, checkpoint: DurableCompletedStageCheckpoint, scope?: ParallelFailFastScope) => void;
+  readonly metadata: (replayKey: string) => Partial<DurableCompletedStageCheckpoint>;
+} {
+  return {
+    record(name, replayKey, checkpoint, scope): void {
+      recordCachedStageWithTracker(
+        input.store, input.tracker, input.run.id, name, replayKey, checkpoint,
+        input.completedStageReplayKeys, scope,
+      );
+      const stage = input.store.runs().find((run) => run.id === input.run.id)?.stages
+        .find((candidate) => candidate.replayKey === replayKey);
+      if (stage !== undefined) {
+        input.backend.recordCheckpoint({
+          kind: "stage", workflowId: input.run.id,
+          checkpointId: `stage-replay-meta:${durableHash({ replayKey, stageId: stage.id, parentIds: stage.parentIds })}`,
+          name, replayKey, completedAt: Date.now(),
+          ...durableStageCheckpointMetadata(stage, durableRunTopology(input.run)),
+        });
+      }
+      if (workflowChildRunId(checkpoint) === undefined) return;
+      const durableRootId = input.run.rootRunId ?? input.run.id;
+      for (const childRun of durableNestedRunSnapshots(input.rootBackend, durableRootId)) {
+        if (!input.store.runs().some((candidate) => candidate.id === childRun.id)) input.store.recordRunStart(childRun);
+      }
+    },
+    metadata(replayKey) {
+      const stage = input.run.stages.find((candidate) => candidate.replayKey === replayKey);
+      return stage === undefined ? {} : durableStageCheckpointMetadata(stage, durableRunTopology(input.run));
+    },
+  };
+}
+
+function workflowChildRunId(checkpoint: DurableCompletedStageCheckpoint): string | undefined {
+  const output = checkpoint.output;
+  if (typeof output !== "object" || output === null || Array.isArray(output)) return undefined;
+  const record = output as Record<string, import("../shared/types.js").WorkflowSerializableValue>;
+  const runId = record["runId"];
+  const workflow = record["workflow"];
+  return typeof runId === "string" && typeof workflow === "string" ? runId : undefined;
+}

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

@@ -39,14 +39,14 @@ import { isWorkflowDefinition, workflowDefinitionRequirementMessage } from "../r
 import { getDurableBackend } from "../durable/factory.js";
 import { classifyReturnedRunStatus } from "./run-returned-status.js";
 import { createToolPrimitive, createCheckpointIdGenerator } from "../durable/tool-primitive.js";
-import { createDurableStagePrimitive, createDurableTaskPrimitive, recordStageCheckpoint, createStageReplayKeyGenerator, recordCachedStageWithTracker } from "../durable/stage-primitive.js";
-import { inheritedRunElapsedMs } from "../durable/run-timing.js";
-import type { DurableCompletedStageCheckpoint } from "../durable/stage-primitive.js";
+import { createDurableStagePrimitive, createDurableTaskPrimitive, recordStageCheckpoint, createStageReplayKeyGenerator } from "../durable/stage-primitive.js";
+import { inheritedRunElapsedMs, recordRunTimingCheckpoint } from "../durable/run-timing.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 { createDurableCachedStageRecorder, createDurableStageDeps } from "./run-durable-topology.js";
 
 type WorkflowRunInputArgument = Parameters<typeof resolveAndValidateInputs>[1];
 
@@ -201,13 +201,11 @@ export async function run<
   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 durableStageDeps = createDurableStageDeps({
+    backend: durableBackend, run: runSnapshot,
+    nextCheckpointId: checkpointIdGenerator, nextReplayKey: stageReplayKeyGenerator,
+    completedReplayKeys: completedStageReplayKeys,
+  });
   const userOnStageEnd = opts.onStageEnd;
   const durableOnStageEnd = async (stageRunId: string, snapshot: StageSnapshot): Promise<void> => {
     if (stageRunId === runId && snapshot.status === "completed") {
@@ -340,18 +338,21 @@ export async function run<
 
   // 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, checkpoint: DurableCompletedStageCheckpoint): void =>
-    recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, checkpoint, completedStageReplayKeys);
+  const cachedStage = createDurableCachedStageRecorder({
+    store: activeStore, tracker, run: runSnapshot, backend: durableBackend,
+    rootBackend, completedStageReplayKeys,
+  });
   const durableTask = createDurableTaskPrimitive({
     workflowId: runId, backend: durableBackend,
     nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName), task: taskRunners.task,
-    recordCachedTask: (name, replayKey, checkpoint, scope) =>
-      recordCachedStageWithTracker(activeStore, tracker, runId, name, replayKey, checkpoint, completedStageReplayKeys, scope),
+    recordCachedTask: cachedStage.record,
   });
   const durableWorkflow = createDurableChildWorkflowPrimitive({
     workflowId: runId, rootWorkflowId: opts.parentRun?.rootRunId ?? runId, backend: durableBackend,
     nextReplayKey: nextDurableChildReplayKey, setChildDurableScope: (scope) => { pendingChildDurableScope = scope; },
-    recordCachedStage, workflow,
+    recordCachedStage: cachedStage.record,
+    checkpointMetadata: cachedStage.metadata,
+    workflow,
   });
   const ctx: WorkflowRunContext<TInputs> = {
     inputs: resolvedInputs as TInputs,
@@ -380,7 +381,7 @@ export async function run<
       workflowId: runId,
       backend: durableBackend,
       nextReplayKey: (stageName) => stageReplayKeyGenerator(stageName),
-      recordCachedStage,
+      recordCachedStage: cachedStage.record,
       stage: (name, options, replayKey) => {
         const stage = runtime.stage(name, options);
         const stageId = activeStore.runs().find((r) => r.id === runId)?.stages.at(-1)?.id;
@@ -429,6 +430,7 @@ export async function run<
     const returned = classifyReturnedRunStatus(result, runSnapshot);
     const recorded = activeStore.recordRunEnd(runId, returned.status, result, returned.error, returned.metadata);
     appendRunEndWhenRecorded(opts.persistence, recorded, { runId, status: returned.status, result, ...(returned.error !== undefined ? { error: returned.error } : {}), ...(returned.metadata ?? {}), ...(runSnapshot.endedAt !== undefined ? { endedAt: runSnapshot.endedAt } : {}), ...(runSnapshot.durationMs !== undefined ? { durationMs: runSnapshot.durationMs } : {}), ts: Date.now() });
+    if (opts.parentRun === undefined) recordRunTimingCheckpoint(durableBackend, runSnapshot);
     durableBackend.setWorkflowStatus(runId, returned.status, undefined, returned.metadata?.resumable);
     await durableBackend.flush();
     return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: returned.status, result, error: returned.error }, opts.onRunEnd);

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

@@ -16,10 +16,22 @@ import { shutdownDbos } from "../durable/dbos-lifecycle.js";
 
 let processShutdownInstalled = false;
 
+/**
+ * Session dispose and process exit must never crash on durability teardown:
+ * a genuine flush/stop failure is diagnostic, not fatal, and an unhandled
+ * rejection here turns an otherwise-successful run into a nonzero exit.
+ */
+function shutdownDbosQuietly(): Promise<void> {
+  return shutdownDbos().catch((error: unknown) => {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.error(`atomic-workflows: DBOS durability shutdown failed: ${detail}`);
+  });
+}
+
 function installDbosProcessShutdown(): void {
   if (processShutdownInstalled) return;
   processShutdownInstalled = true;
-  process.once("beforeExit", () => shutdownDbos());
+  process.once("beforeExit", () => void shutdownDbosQuietly());
 }
 
 export interface WorkflowLifecycleRegistrationDeps {
@@ -123,6 +135,6 @@ export function registerWorkflowLifecycleHandlers(
     deps.storeWidgetRef.current = null;
     runtimeState.resetWorkflowDiscoveryForSession();
     runtimeState.setNotificationsActive(false);
-    await shutdownDbos();
+    await shutdownDbosQuietly();
   });
 }

package/dist/builtin/workflows/src/extension/public-types.ts

@@ -2,6 +2,7 @@ import type {
   CreateAgentSessionOptions,
   DefaultResourceLoaderInheritanceSnapshot,
 } from "@bastani/atomic";
+import type { Api, Model } from "@earendil-works/pi-ai/compat";
 import type { SessionManager } from "../shared/persistence-restore.js";
 import type { StageSessionRuntime } from "../runs/foreground/stage-runner.js";
 import type { RunStatus, StageStatus } from "../shared/store-types.js";
@@ -58,10 +59,7 @@ export interface PiCommandOptions {
   getArgumentCompletions?: (partial: string) => PiArgumentCompletionResult | Promise<PiArgumentCompletionResult>;
 }
 
-export interface PiRuntimeModel {
-  readonly provider: string;
-  readonly id: string;
-}
+export type PiRuntimeModel = Model<Api>;
 
 export interface PiRuntimeModelRegistry {
   getAvailable(): PiRuntimeModel[];
@@ -222,6 +220,7 @@ export interface WorkflowToolArgs {
   workflow?: string;
   inputs?: WorkflowInputValues;
   action?:
+    | "models"
     | "run"
     | "list"
     | "get"

package/dist/builtin/workflows/src/extension/render-call.ts

@@ -11,6 +11,7 @@ export interface WorkflowToolArgs {
   workflow?: string;
   inputs?: WorkflowInputValues;
   action?:
+    | "models"
     | "run"
     | "list"
     | "get"
@@ -106,6 +107,9 @@ export function renderCall(args: WorkflowToolArgs, opts: RenderCallOpts = {}): s
     case "get":
       line = name === undefined ? "workflow: get" : `workflow: get ${quoted(name)}`;
       break;
+    case "models":
+      line = "workflow: list configured models";
+      break;
     default:
       line = name === undefined ? `workflow: ${action}` : `workflow: ${action} ${quoted(name)}`;
       break;

package/dist/builtin/workflows/src/extension/render-result.ts

@@ -149,6 +149,14 @@ type ReloadResult = WorkflowReloadReport & { action: "reload"; status: "ok" | "n
 type InterruptResult = { action: "interrupt"; runId: string; status: string; message: string };
 type QuitResult = { action: "quit"; runId: string; status: string; message: string };
 type ResumeResult = { action: "resume"; runId: string; status: string; message: string };
+export interface ModelCatalogEntry {
+  provider: string;
+  id: string;
+  fullId: string;
+  isCurrent: boolean;
+  availableThinkingLevels?: readonly string[];
+}
+type ModelsResult = { action: "models"; models: ModelCatalogEntry[] };
 
 export type WorkflowToolResult =
   | ListResult
@@ -165,7 +173,8 @@ export type WorkflowToolResult =
   | ReloadResult
   | InterruptResult
   | QuitResult
-  | ResumeResult;
+  | ResumeResult
+  | ModelsResult;
 
 export interface RenderResultOpts {
   isPartial?: boolean;
@@ -432,6 +441,27 @@ export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts
       return renderNotice("WORKFLOW RESUME", `${r.runId}: ${r.message}`, opts, themed);
     }
 
+    case "models": {
+      const r = result as ModelsResult;
+      if (r.models.length === 0) {
+        return renderNotice("WORKFLOW MODELS", "no models in configured catalog — configured-auth snapshot, not proof of credentials, entitlements, OAuth freshness, or live provider access.", opts, themed);
+      }
+      const currentLine = r.models.find((model) => model.isCurrent);
+      const lines = r.models.map((model) => {
+        const levels = model.availableThinkingLevels?.length
+          ? ` [levels: ${model.availableThinkingLevels.join(", ")}]`
+          : "";
+        return `${model.provider}/${model.id}${model.isCurrent ? " (current)" : ""}${levels}`;
+      }).join("; ");
+      const suffix = currentLine !== undefined ? "" : " (no current model)";
+      return renderNotice(
+        "WORKFLOW MODELS",
+        `${lines}${suffix} — configured-auth catalog snapshot, not proof of credentials, entitlements, OAuth freshness, or live provider access.`,
+        opts,
+        themed,
+      );
+    }
+
     default: {
       // Runtime guard — handles values coerced from external sources.
       const fallback = result as { action: string; message?: string };

package/dist/builtin/workflows/src/extension/runtime-durable-resume.ts

@@ -20,6 +20,7 @@ import {
 } from "../durable/completed-inspection.js";
 import type { ResumableWorkflowEntry } from "../durable/types.js";
 import type { DurableWorkflowCatalogEntries } from "../durable/backend.js";
+import { discoverWorkflows } from "./discovery.js";
 
 export interface DurableResumeRuntime {
   resumeDurableWorkflow(
@@ -76,6 +77,8 @@ export function createDurableResumeRuntime(
         registry: deps.registry,
         baseRunOpts: deps.baseRunOpts(options?.policy),
         durableBackend: backend,
+        resolveDefinition: async (name, cwd) =>
+          (await discoverWorkflows({ cwd: cwd ?? deps.runtimeCwd })).registry.get(name),
         ...(deps.jobs !== undefined ? { jobs: deps.jobs } : {}),
       };
       return await resumeDurableWorkflowAdapter(workflowIdOrPrefix, adapterDeps, preparedCatalog);