@bastani/atomic 0.9.8 → 0.9.9-alpha.1

package/dist/builtin/workflows/src/durable/file-lock.ts

@@ -0,0 +1,153 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+import type { FileDurableState } from "./file-state.js";
+
+interface LockOwner {
+  readonly pid: number;
+  readonly host: string;
+  readonly token: string;
+  readonly acquiredAt: number;
+}
+
+const LOCK_OWNER_FILE = "owner.json";
+const STALE_LOCK_MS = 30_000;
+
+export function writeDurableFileState(filePath: string, state: FileDurableState): void {
+  const dir = dirname(filePath);
+  ensureSecureDir(dir);
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state), { encoding: "utf-8", mode: 0o600 });
+  chmodBestEffort(tmp, 0o600);
+  renameSync(tmp, filePath);
+  chmodBestEffort(filePath, 0o600);
+}
+
+export function withDurableFileLock<T>(filePath: string, fn: () => T): T {
+  const dir = dirname(filePath);
+  ensureSecureDir(dir);
+  const lockDir = `${filePath}.lock`;
+  const deadline = Date.now() + 5000;
+  while (true) {
+    try {
+      mkdirSync(lockDir, { mode: 0o700 });
+      try {
+        chmodBestEffort(lockDir, 0o700);
+        writeLockOwner(lockDir);
+      } catch (ownerErr) {
+        rmSync(lockDir, { recursive: true, force: true });
+        throw ownerErr;
+      }
+      break;
+    } catch (err) {
+      if (errorCode(err) !== "EEXIST") throw err;
+      if (tryReclaimStaleLock(lockDir, STALE_LOCK_MS)) continue;
+      if (Date.now() > deadline) throw new Error(`Timed out acquiring durable workflow state lock: ${lockDir}`);
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+function tryReclaimStaleLock(lockDir: string, staleMs: number): boolean {
+  if (!isStaleLock(lockDir, staleMs)) return false;
+  const owner = readLockOwner(lockDir);
+  if (owner === undefined || !isLockOwnerAbandoned(owner)) return false;
+  const quarantine = `${lockDir}.stale.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+  try {
+    renameSync(lockDir, quarantine);
+  } catch {
+    return false;
+  }
+  const quarantinedOwner = readLockOwner(quarantine);
+  if (!sameLockOwner(owner, quarantinedOwner)) {
+    restoreQuarantinedLock(lockDir, quarantine);
+    return false;
+  }
+  try {
+    rmSync(quarantine, { recursive: true, force: true });
+  } catch {
+    // The stale lock has already been moved away from the active lock path.
+  }
+  return true;
+}
+
+function isStaleLock(lockDir: string, staleMs: number): boolean {
+  try {
+    return Date.now() - statSync(lockDir).mtimeMs > staleMs;
+  } catch {
+    return false;
+  }
+}
+
+function writeLockOwner(lockDir: string): void {
+  const owner: LockOwner = {
+    pid: process.pid,
+    host: hostname(),
+    token: `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+    acquiredAt: Date.now(),
+  };
+  const ownerPath = `${lockDir}/${LOCK_OWNER_FILE}`;
+  writeFileSync(ownerPath, JSON.stringify(owner), { encoding: "utf-8", mode: 0o600 });
+  chmodBestEffort(ownerPath, 0o600);
+}
+
+function readLockOwner(lockDir: string): LockOwner | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(`${lockDir}/${LOCK_OWNER_FILE}`, "utf-8"));
+    return isLockOwner(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isLockOwner(value: unknown): value is LockOwner {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const record = value as Partial<LockOwner>;
+  return typeof record.pid === "number" && typeof record.host === "string"
+    && typeof record.token === "string" && typeof record.acquiredAt === "number";
+}
+
+function isLockOwnerAbandoned(owner: LockOwner): boolean {
+  if (owner.host !== hostname() || !Number.isInteger(owner.pid) || owner.pid <= 0) return false;
+  try {
+    process.kill(owner.pid, 0);
+    return false;
+  } catch (err) {
+    return errorCode(err) === "ESRCH";
+  }
+}
+
+function sameLockOwner(a: LockOwner, b: LockOwner | undefined): boolean {
+  return b !== undefined && a.pid === b.pid && a.host === b.host && a.token === b.token;
+}
+
+function restoreQuarantinedLock(lockDir: string, quarantine: string): void {
+  try {
+    if (!existsSync(lockDir)) renameSync(quarantine, lockDir);
+    else rmSync(quarantine, { recursive: true, force: true });
+  } catch {
+    // Best-effort: never delete the active lock path after a failed compare.
+  }
+}
+
+function errorCode(err: unknown): string | undefined {
+  return typeof err === "object" && err !== null && "code" in err ? String(err.code) : undefined;
+}
+
+function ensureSecureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodBestEffort(dir, 0o700);
+}
+
+function chmodBestEffort(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    // chmod is unavailable or unsupported on some filesystems/platforms.
+  }
+}

package/dist/builtin/workflows/src/durable/file-state.ts

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DurableCheckpoint, DurableWorkflowHandle } from "./types.js";
+import { classifyDurableFormatVersion, DURABLE_FORMAT_VERSION } from "./format-version.js";
+
+export interface FileDurableRecord {
+  readonly handle: DurableWorkflowHandle;
+  readonly checkpoints: readonly DurableCheckpoint[];
+}
+
+export interface FileDurableState {
+  readonly version: number;
+  readonly workflows: readonly FileDurableRecord[];
+  readonly deletedWorkflowIds: readonly string[];
+}
+
+export type FileStateReadResult =
+  | { readonly kind: "missing" }
+  | { readonly kind: "current"; readonly state: FileDurableState }
+  | { readonly kind: "legacy"; readonly workflowIds: readonly string[] }
+  | { readonly kind: "unknown" };
+
+export function readDurableFileState(filePath: string): FileStateReadResult {
+  if (!existsSync(filePath)) return { kind: "missing" };
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8")) as Partial<FileDurableState> | null;
+    if (parsed === null || !Array.isArray(parsed.workflows)) return { kind: "unknown" };
+    const compatibility = classifyDurableFormatVersion(parsed.version);
+    if (compatibility === "legacy") {
+      const validRecords = parsed.workflows.filter(isFileDurableRecord);
+      return {
+        kind: "legacy",
+        workflowIds: validRecords.length === parsed.workflows.length
+          ? validRecords.map((record) => record.handle.workflowId)
+          : [],
+      };
+    }
+    const deleted = parsed.deletedWorkflowIds ?? [];
+    if (compatibility === "unknown" || !isStringArray(deleted) || !parsed.workflows.every(isFileDurableRecord)) return { kind: "unknown" };
+    return { kind: "current", state: { version: DURABLE_FORMAT_VERSION, workflows: parsed.workflows, deletedWorkflowIds: deleted } };
+  } catch {
+    return { kind: "unknown" };
+  }
+}
+
+function isFileDurableRecord(value: unknown): value is FileDurableRecord {
+  if (!isObject(value)) return false;
+  const handle = value["handle"];
+  const checkpoints = value["checkpoints"];
+  if (!isHandle(handle) || !Array.isArray(checkpoints)) return false;
+  return checkpoints.every((checkpoint) => isCheckpoint(checkpoint) && checkpoint.workflowId === handle.workflowId);
+}
+
+function isHandle(value: unknown): value is DurableWorkflowHandle {
+  if (!isObject(value) || typeof value["workflowId"] !== "string" || typeof value["name"] !== "string"
+    || !isSerializableObject(value["inputs"]) || typeof value["createdAt"] !== "number"
+    || typeof value["updatedAt"] !== "number" || !isStatus(value["status"])
+    || typeof value["completedCheckpoints"] !== "number" || typeof value["pendingPrompts"] !== "number") return false;
+  return optionalString(value, "invocationCwd") && optionalString(value, "workflowCwd")
+    && optionalString(value, "repositoryRoot") && optionalString(value, "gitWorktreeRoot")
+    && optionalString(value, "sessionFile") && optionalString(value, "label")
+    && optionalString(value, "rootWorkflowId") && optionalBoolean(value, "resumable");
+}
+
+function isCheckpoint(value: unknown): value is DurableCheckpoint {
+  if (!isObject(value) || typeof value["workflowId"] !== "string" || typeof value["checkpointId"] !== "string"
+    || typeof value["completedAt"] !== "number") return false;
+  if (value["kind"] === "tool") return typeof value["name"] === "string" && typeof value["argsHash"] === "string" && isSerializable(value["output"]);
+  if (value["kind"] === "ui") return typeof value["promptKind"] === "string" && typeof value["message"] === "string"
+    && typeof value["promptHash"] === "string" && isSerializable(value["response"]);
+  return value["kind"] === "stage" && typeof value["name"] === "string" && typeof value["replayKey"] === "string"
+    && (!("output" in value) || isSerializable(value["output"]));
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isStatus(value: unknown): boolean {
+  return value === "running" || value === "paused" || value === "completed"
+    || value === "failed" || value === "cancelled" || value === "blocked";
+}
+
+function isSerializableObject(value: unknown): value is Readonly<Record<string, WorkflowSerializableValue>> {
+  return isObject(value) && Object.values(value).every(isSerializable);
+}
+
+function isSerializable(value: unknown): value is WorkflowSerializableValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isSerializable);
+  return isSerializableObject(value);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function optionalString(value: Record<string, unknown>, key: string): boolean {
+  return value[key] === undefined || typeof value[key] === "string";
+}
+
+function optionalBoolean(value: Record<string, unknown>, key: string): boolean {
+  return value[key] === undefined || typeof value[key] === "boolean";
+}

package/dist/builtin/workflows/src/durable/format-version.ts

@@ -0,0 +1,12 @@
+/** Shared schema version for durable workflow state and discovery metadata. */
+export const DURABLE_FORMAT_VERSION = 2 as const;
+export const LEGACY_DURABLE_FORMAT_VERSION = 1 as const;
+
+export type DurableFormatCompatibility = "current" | "legacy" | "unknown";
+
+/** Classify an explicit durable format version without guessing about malformed data. */
+export function classifyDurableFormatVersion(value: unknown): DurableFormatCompatibility {
+  if (value === DURABLE_FORMAT_VERSION) return "current";
+  if (value === LEGACY_DURABLE_FORMAT_VERSION) return "legacy";
+  return "unknown";
+}

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

@@ -49,6 +49,18 @@ export {
   persistDurableCacheEntry,
   formatResumableWorkflowList,
 } from "./resume-catalog.js";
+export {
+  completedWorkflowSnapshot,
+  listCompletedFromBackend,
+  listOpenableCompletedWorkflows,
+  resolveCompletedWorkflow,
+  type CompletedWorkflowResolution,
+} from "./completed-catalog.js";
+export {
+  openCompletedDurableWorkflow,
+  type OpenCompletedDurableDeps,
+  type OpenCompletedDurableResult,
+} from "./completed-inspection.js";
 export {
   createToolPrimitive,
   createCheckpointIdGenerator,

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

@@ -20,6 +20,8 @@ import { join } from "node:path";
 import type { DurableCheckpointEntry, DurableWorkflowStatus, ResumableWorkflowEntry } from "./types.js";
 import type { DurableWorkflowBackend } from "./backend.js";
 import type { WorkflowSerializableValue } from "../shared/types.js";
+import { isDurableWorkflowResumable } from "./resume-eligibility.js";
+import { DURABLE_FORMAT_VERSION } from "./format-version.js";
 
 // ---------------------------------------------------------------------------
 // Session file scanning
@@ -52,7 +54,7 @@ export function scanResumableWorkflows(sessionDir: string): readonly ResumableWo
       }
     }
   }
-  return [...entries.values()].filter(isResumableEntry).sort((a, b) => b.updatedAt - a.updatedAt);
+  return [...entries.values()].filter(isDurableWorkflowResumable).sort((a, b) => b.updatedAt - a.updatedAt);
 }
 
 function readDurableEntriesFromFile(filePath: string): readonly DurableCheckpointEntry[] {
@@ -89,6 +91,8 @@ function durablePayloadFromJsonlEntry(parsed: Record<string, unknown>): Record<s
 }
 
 function parseDurableEntry(raw: Record<string, unknown>): DurableCheckpointEntry | undefined {
+  if (raw["formatVersion"] !== DURABLE_FORMAT_VERSION) return undefined;
+
   const workflowId = raw["workflowId"];
   const name = raw["name"];
   const inputs = raw["inputs"];
@@ -97,6 +101,7 @@ function parseDurableEntry(raw: Record<string, unknown>): DurableCheckpointEntry
   if (typeof workflowId !== "string" || typeof name !== "string" || typeof status !== "string" || typeof ts !== "number") return undefined;
   if (!isWorkflowSerializableObject(inputs)) return undefined;
   return {
+    formatVersion: DURABLE_FORMAT_VERSION,
     type: "workflow.durable.checkpoint",
     workflowId,
     name,
@@ -155,24 +160,6 @@ function entryToResumable(entry: DurableCheckpointEntry, sessionFile: string): R
   };
 }
 
-function isResumableStatus(status: DurableWorkflowStatus): boolean {
-  // `running`/`paused` are both resumable at the catalog level. A `running`
-  // durable handle may be a crashed process (cross-session crash recovery);
-  // same-session double-resume is filtered out by the command layer.
-  return status === "running" || status === "paused";
-}
-function hasResumeProgress(entry: ResumableWorkflowEntry): boolean {
-  return entry.completedCheckpoints > 0 || entry.pendingPrompts > 0;
-}
-
-
-function isResumableEntry(entry: ResumableWorkflowEntry): boolean {
-  const isRoot = entry.rootWorkflowId === undefined || entry.rootWorkflowId === entry.workflowId;
-  if (!isRoot) return false;
-  if (entry.status === "failed" || entry.status === "blocked") return entry.resumable !== false;
-  return isResumableStatus(entry.status) && hasResumeProgress(entry);
-}
-
 // ---------------------------------------------------------------------------
 // Backend-backed catalog
 // ---------------------------------------------------------------------------
@@ -196,6 +183,7 @@ export function persistDurableCacheEntry(
 ): void {
   if (typeof persistence.appendEntry !== "function") return;
   persistence.appendEntry("workflow.durable.checkpoint", {
+    formatVersion: entry.formatVersion,
     workflowId: entry.workflowId,
     name: entry.name,
     inputs: entry.inputs as Record<string, unknown>,
@@ -217,13 +205,14 @@ export function persistDurableCacheEntry(
  * Format the resumable workflow list for display in the selector.
  */
 export function formatResumableWorkflowList(entries: readonly ResumableWorkflowEntry[]): string {
-  if (entries.length === 0) return "No resumable workflows found.";
-  const lines = entries.map((e, i) => {
-    const id = e.workflowId.slice(0, 8);
-    const status = e.status.padEnd(8);
-    const checkpoints = `${e.completedCheckpoints} checkpoint${e.completedCheckpoints === 1 ? "" : "s"}`;
-    const label = e.label ? ` "${e.label}"` : "";
-    return `  ${i + 1}. ${id}  ${status}  ${e.name}${label}  (${checkpoints})`;
+  if (entries.length === 0) return "No resumable or completed workflows found.";
+  const hasCompleted = entries.some((entry) => entry.status === "completed");
+  const lines = entries.map((entry, index) => {
+    const id = entry.workflowId.slice(0, 8);
+    const status = entry.status === "completed" ? "✓ completed" : entry.status.padEnd(8);
+    const checkpoints = `${entry.completedCheckpoints} checkpoint${entry.completedCheckpoints === 1 ? "" : "s"}`;
+    const label = entry.label ? ` "${entry.label}"` : "";
+    return `  ${index + 1}. ${id}  ${status}  ${entry.name}${label}  (${checkpoints})`;
   });
-  return `Resumable workflows:\n${lines.join("\n")}`;
+  return `${hasCompleted ? "Workflow resume targets" : "Resumable workflows"}:\n${lines.join("\n")}`;
 }

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

@@ -0,0 +1,20 @@
+import type { DurableWorkflowStatus } from "./types.js";
+
+/** Metadata shared by durable handles and session-cache resume entries. */
+export interface DurableResumeCandidate {
+  readonly workflowId: string;
+  readonly status: DurableWorkflowStatus;
+  readonly completedCheckpoints: number;
+  readonly pendingPrompts: number;
+  readonly rootWorkflowId?: string;
+  readonly resumable?: boolean;
+}
+
+/** Authoritative status/progress rules for durable workflow resume discovery. */
+export function isDurableWorkflowResumable(candidate: DurableResumeCandidate): boolean {
+  const isRoot = candidate.rootWorkflowId === undefined || candidate.rootWorkflowId === candidate.workflowId;
+  if (!isRoot) return false;
+  if (candidate.status === "failed" || candidate.status === "blocked") return candidate.resumable !== false;
+  const hasResumeProgress = candidate.completedCheckpoints > 0 || candidate.pendingPrompts > 0;
+  return (candidate.status === "running" || candidate.status === "paused") && hasResumeProgress;
+}

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

@@ -31,6 +31,7 @@ import { resolveAndValidateInputs } from "../runs/foreground/executor-inputs.js"
 import { getDurableBackend } from "./factory.js";
 import type { DurableWorkflowBackend } from "./backend.js";
 import type { ResumableWorkflowEntry } from "./types.js";
+import { isDurableWorkflowResumable } from "./resume-eligibility.js";
 import { workflowDefinitionRequirementMessage } from "../runs/foreground/executor-child-helpers.js";
 import { isWorkflowDefinition } from "../runs/foreground/executor-child-helpers.js";
 import type { RunSnapshot } from "../shared/store-types.js";
@@ -109,6 +110,9 @@ export function resumeDurableWorkflow(
   const resolvedCatalog = catalog ?? backend.listResumableWorkflows();
   const resolved = resolveDurableEntry(workflowIdOrPrefix, resolvedCatalog);
   if (resolved === undefined) {
+    if (!backend.isWorkflowLoadable(workflowIdOrPrefix)) {
+      return { ok: false, reason: "not_registered", message: `Durable workflow ${workflowIdOrPrefix.slice(0, 8)} uses an incompatible or unavailable persisted format and cannot be resumed.` };
+    }
     // Not in the (filtered) resumable catalog. It may still be a workflow the
     // backend knows about. Only surface "already running" when there is a live,
     // actively-executing run for it in this session; otherwise a `running`
@@ -126,6 +130,9 @@ export function resumeDurableWorkflow(
       message: `Ambiguous workflow prefix "${workflowIdOrPrefix}" matches: ${resolved.matches.map((m) => `${m.name} (${m.workflowId.slice(0, 8)})`).join(", ")}`,
     };
   }
+  if (!backend.isWorkflowLoadable(resolved.workflowId)) {
+    return { ok: false, reason: "not_registered", message: `Durable workflow ${resolved.workflowId.slice(0, 8)} uses an incompatible or unavailable persisted format and cannot be resumed.` };
+  }
   // Authoritative backend-handle check: a cache-only entry (no handle) is
   // "stale" regardless of its cached status. A `running` handle is only
   // refused when there is a live, actively-executing run for it in THIS
@@ -140,15 +147,15 @@ export function resumeDurableWorkflow(
     };
   }
   if (handle.status === "running" && hasActiveLiveRun(deps.baseRunOpts.store, resolved.workflowId)) {
-    return alreadyRunningResult(resolved.name, resolved.workflowId, deps.baseRunOpts.store);
+    return alreadyRunningResult(handle.name, resolved.workflowId, deps.baseRunOpts.store);
   }
-  if (!isResumableEntry(resolved)) {
-    return { ok: false, reason: "not_resumable", message: `Workflow ${resolved.workflowId.slice(0, 8)} is ${resolved.status}, not resumable.` };
+  if (!isDurableWorkflowResumable(handle)) {
+    return { ok: false, reason: "not_resumable", message: `Workflow ${resolved.workflowId.slice(0, 8)} is ${handle.status}, not resumable.` };
   }
 
-  const def = deps.registry.get(resolved.name);
+  const def = deps.registry.get(handle.name);
   if (def === undefined) {
-    return { ok: false, reason: "workflow_not_found", message: `Workflow definition not found: ${resolved.name}` };
+    return { ok: false, reason: "workflow_not_found", message: `Workflow definition not found: ${handle.name}` };
   }
   if (!isWorkflowDefinition(def)) {
     return { ok: false, reason: "workflow_not_found", message: workflowDefinitionRequirementMessage("resumeDurableWorkflow", def) };
@@ -180,8 +187,8 @@ export function resumeDurableWorkflow(
     ok: true,
     runId: accepted.runId,
     workflowId: resolved.workflowId,
-    name: resolved.name,
-    message: `Resuming durable workflow "${resolved.name}" (${resolved.workflowId.slice(0, 8)}) — completed checkpoints will be replayed.`,
+    name: handle.name,
+    message: `Resuming durable workflow "${handle.name}" (${resolved.workflowId.slice(0, 8)}) — completed checkpoints will be replayed.`,
   };
 }
 
@@ -209,20 +216,6 @@ function alreadyRunningResult(name: string, workflowId: string, store: RunOpts["
   };
 }
 
-function hasResumeProgress(entry: ResumableWorkflowEntry): boolean {
-  return entry.completedCheckpoints > 0 || entry.pendingPrompts > 0;
-}
-
-function isResumableEntry(entry: ResumableWorkflowEntry): boolean {
-  const isRoot = entry.rootWorkflowId === undefined || entry.rootWorkflowId === entry.workflowId;
-  if (!isRoot) return false;
-  if (entry.status === "failed" || entry.status === "blocked") return entry.resumable !== false;
-  // `running` is resumable at this layer: a `running` durable handle may be a
-  // crashed process. Same-session double-resume is blocked separately via
-  // `hasActiveLiveRun` before dispatch.
-  return (entry.status === "running" || entry.status === "paused") && hasResumeProgress(entry);
-}
-
 /**
  * True when the live run store has an actively-executing (not ended, not quit)
  * run for `workflowId`. This is the only reliable signal that a durable
@@ -251,9 +244,6 @@ export function isBackendTerminal(backend: DurableWorkflowBackend, workflowId: s
   return false;
 }
 
-function hasBackendResumeState(backend: DurableWorkflowBackend, workflowId: string): boolean {
-  return backend.getWorkflow(workflowId) !== undefined;
-}
 
 /**
  * Runtime-facing async preparation: hydrate the durable backend from DBOS
@@ -266,6 +256,17 @@ function hasBackendResumeState(backend: DurableWorkflowBackend, workflowId: stri
  * terminal (completed/cancelled/non-resumable), stale cache rows for that id
  * are also suppressed. cross-ref: issue #1498.
  */
+/** Remove restored/live snapshots whose authoritative durable format is non-loadable. */
+export function purgeSuppressedWorkflowRuns(backend: DurableWorkflowBackend, store: RunOpts["store"]): readonly string[] {
+  if (store === undefined) return [];
+  const removed: string[] = [];
+  for (const run of store.runs()) {
+    if (backend.isWorkflowLoadable(run.id)) continue;
+    if (store.removeRun(run.id)) removed.push(run.id);
+  }
+  return removed;
+}
+
 export async function prepareRuntimeDurableResumable(
   getBackend: () => DurableWorkflowBackend,
   resolveSessionDir: () => string | undefined,
@@ -293,10 +294,9 @@ export async function prepareRuntimeDurableResumable(
   // durable backend handle/checkpoint state, selecting the row can only fail
   // as stale (or risk re-running from scratch), so it should not clutter the
   // resume selector.
-  const suppressed = scanned.filter((e) =>
-    !liveIds.has(e.workflowId) &&
-    hasBackendResumeState(backend, e.workflowId) &&
-    !isBackendTerminal(backend, e.workflowId)
-  );
+  const suppressed = scanned.filter((entry) => {
+    const handle = backend.getWorkflow(entry.workflowId);
+    return !liveIds.has(entry.workflowId) && handle !== undefined && isDurableWorkflowResumable(handle);
+  });
   return [...live, ...suppressed];
 }

package/dist/builtin/workflows/src/durable/scoped-backend.ts

@@ -13,9 +13,9 @@
  * child boundary key, so the same side effects are recovered on resume.
  *
  * Only checkpoint read/write methods are scoped. Lifecycle methods
- * (`registerWorkflow`, `setWorkflowStatus`, `listResumableWorkflows`,
+ * (`registerWorkflow`, `setWorkflowStatus`, completed/resumable listing,
  * `toCacheEntry`, `getWorkflow`) are no-ops for scoped children because child
- * runs are never independently resumable — only the root workflow is resumed.
+ * runs are never independently addressable — only the root workflow is.
  *
  * cross-ref: issue #1498 — child side effects under the root durable workflow.
  */
@@ -86,7 +86,12 @@ export class ScopedDurableBackend implements DurableWorkflowBackend {
     return this.inner.getStageOutput(this.scope.rootWorkflowId, this.scopeKey(replayKey));
   }
 
-  getStageSession(_workflowId: string, replayKey: string): { sessionId?: string; sessionFile?: string } | undefined {
+  getStageSession(_workflowId: string, replayKey: string): {
+    sessionId?: string;
+    sessionFile?: string;
+    startedAt?: number;
+    durationMs?: number;
+  } | undefined {
     return this.inner.getStageSession(this.scope.rootWorkflowId, this.scopeKey(replayKey));
   }
 
@@ -114,10 +119,22 @@ export class ScopedDurableBackend implements DurableWorkflowBackend {
     return [];
   }
 
+  listCompletedWorkflows(): readonly ResumableWorkflowEntry[] {
+    return [];
+  }
+
   toCacheEntry(_workflowId: string): undefined {
     return undefined;
   }
 
+  async deleteWorkflow(_workflowId: string): Promise<void> {
+    // No-op: scoped children never own or delete root durable state.
+  }
+
+  isWorkflowLoadable(_workflowId: string): boolean {
+    return false;
+  }
+
   reset(): void {
     // No-op: scoped backends never own root state.
   }

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

@@ -7,6 +7,7 @@ import type { DurableWorkflowBackend } from "./backend.js";
 import type { ParallelFailFastScope } from "../runs/foreground/executor-types.js";
 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";
 export type DurableCompletedStageCheckpoint = DurableStageCheckpoint & { readonly output: WorkflowSerializableValue };
@@ -17,6 +18,7 @@ export interface DurableStageDeps {
   readonly nextCheckpointId: () => string;
   readonly nextReplayKey: (stageName: string) => string;
   readonly replayKeyForCompletedStage?: (stage: StageSnapshot) => string | undefined;
+  readonly now?: () => number;
 }
 
 export async function recordStageCheckpoint(deps: DurableStageDeps, stage: StageSnapshot): Promise<boolean> {
@@ -51,17 +53,25 @@ export async function recordStageCheckpoint(deps: DurableStageDeps, stage: Stage
 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;
+  const checkpointNow = deps.now?.() ?? Date.now();
+  const durationMs = elapsedStageMs(stage, checkpointNow) ?? 0;
   const current = deps.backend.getStageSession(deps.workflowId, replayKey);
-  if (current?.sessionFile === stage.sessionFile) return false;
+  if (current !== undefined
+    && current.sessionId === stage.sessionId
+    && current.sessionFile === stage.sessionFile
+    && current.startedAt === stage.startedAt
+    && current.durationMs === durationMs) return false;
   const checkpoint: DurableStageCheckpoint = {
     kind: "stage",
     workflowId: deps.workflowId,
-    checkpointId: stageSessionCheckpointId(replayKey, stage),
+    checkpointId: stageSessionCheckpointId(replayKey, stage, durationMs),
     name: stage.name,
     replayKey,
     ...(stage.sessionId !== undefined ? { sessionId: stage.sessionId } : {}),
     sessionFile: stage.sessionFile,
-    completedAt: Date.now(),
+    ...(stage.startedAt !== undefined ? { startedAt: stage.startedAt } : {}),
+    durationMs,
+    completedAt: checkpointNow,
   };
   await recordCheckpointDurably(deps.backend, checkpoint);
   return true;
@@ -107,7 +117,10 @@ export function createDurableStagePrimitive(input: {
     const liveOptions: StageOptions | undefined = {
       ...(options ?? {}),
       durableReplayKey: replayKey,
-      ...(isMidSessionResume ? { resumeFromSessionFile: session.sessionFile } : {}),
+      ...(isMidSessionResume ? {
+        resumeFromSessionFile: session.sessionFile,
+        durableAccumulatedDurationMs: session.durationMs ?? 0,
+      } : {}),
     };
     const live = withMidSessionResumePrompt(input.stage(name, liveOptions, replayKey), isMidSessionResume);
     if (options?.schema === undefined) return live;
@@ -139,7 +152,10 @@ export function createDurableTaskPrimitive(input: {
     const taskOptions: WorkflowTaskOptions = {
       ...options,
       durableReplayKey: replayKey,
-      ...(session?.sessionFile !== undefined ? { resumeFromSessionFile: session.sessionFile } : {}),
+      ...(session?.sessionFile !== undefined ? {
+        resumeFromSessionFile: session.sessionFile,
+        durableAccumulatedDurationMs: session.durationMs ?? 0,
+      } : {}),
     };
     const result = await input.task(name, taskOptions, stageFailFastScope);
     await recordCheckpointDurably(input.backend, {
@@ -299,8 +315,11 @@ function metadataValue<K extends keyof DurableStageCheckpoint>(
   checkpoints: readonly DurableStageCheckpoint[],
   key: K,
 ): Pick<DurableStageCheckpoint, K> | Record<string, never> {
-  const value = checkpoints.find((checkpoint) => checkpoint[key] !== undefined)?.[key];
-  return value === undefined ? {} : { [key]: value } as Pick<DurableStageCheckpoint, K>;
+  for (let index = checkpoints.length - 1; index >= 0; index -= 1) {
+    const value = checkpoints[index]?.[key];
+    if (value !== undefined) return { [key]: value } as Pick<DurableStageCheckpoint, K>;
+  }
+  return {};
 }
 
 
@@ -317,10 +336,12 @@ export function stableCheckpointId(kind: string, replayKey: string): string {
   return `${kind}:${replayKey}`;
 }
 
-function stageSessionCheckpointId(replayKey: string, stage: StageSnapshot): string {
+function stageSessionCheckpointId(replayKey: string, stage: StageSnapshot, durationMs: number): string {
   return `${stableCheckpointId("stage-session", replayKey)}:${durableHash({
     sessionId: stage.sessionId ?? "",
     sessionFile: stage.sessionFile ?? "",
+    startedAt: stage.startedAt ?? 0,
+    durationMs,
   })}`;
 }