@bastani/atomic 0.9.9 → 0.9.10

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

@@ -1,41 +1,25 @@
-/**
- * Durable workflow backend seam.
- *
- * This interface abstracts durable checkpoint storage so the workflow engine
- * can persist `ctx.*` operation results without coupling to a specific storage
- * backend. The default implementation is the zero-infrastructure
- * per-workflow file backend, rooted under `~/.atomic/workflow-durable`, so
- * cross-session resume works without user setup. {@link InMemoryDurableBackend}
- * remains available for isolated tests and explicit custom overrides. The
- * {@link DbosDurableBackend} adapter (in dbos-backend.ts) wraps the real
- * `@dbos-inc/dbos-sdk` when configured.
- *
- * Design:
- * - Only `ctx.*` blocks write checkpoints (tool, ui, stage).
- * - Checkpoints are keyed by (workflowId, kind, checkpointId) for uniqueness.
- * - Tool/ui checkpoints also key on a content hash so identical calls are
- *   idempotent (completed side effects are not repeated on resume).
- * - The backend is the checkpoint source of truth; session JSONL entries are
- *   a discovery cache.
- *
- * cross-ref: issue #1498 — DBOS integration behind a backend seam.
- */
+/** Durable workflow backend seam for DBOS and explicit in-memory tests. */
 
 import type { WorkflowSerializableValue } from "../shared/types.js";
-import { createHash } from "node:crypto";
 import { isDurableWorkflowResumable } from "./resume-eligibility.js";
-import { DURABLE_FORMAT_VERSION } from "./format-version.js";
+import { inactivePromptReservationToken, PromptReservationState, type PromptReservationToken } from "./prompt-reservation-state.js";
+import { withCurrentStageTopology } from "./dbos-envelope.js";
 import type {
   DurableCheckpoint,
-  DurableCheckpointEntry,
+  DurableWorkflowMetadata,
   DurableToolCheckpoint,
   DurableUiCheckpoint,
   DurableStageCheckpoint,
   DurableWorkflowHandle,
   DurableWorkflowStatus,
   ResumableWorkflowEntry,
-  WorkflowSerializableObject,
 } from "./types.js";
+export interface DurableWorkflowCatalogEntries {
+  readonly resumable: readonly ResumableWorkflowEntry[];
+  readonly completed: readonly ResumableWorkflowEntry[];
+  readonly completedAll?: readonly ResumableWorkflowEntry[];
+}
+export { durableHash } from "./durable-hash.js";
 
 // ---------------------------------------------------------------------------
 // Backend interface
@@ -49,19 +33,13 @@ export type WorkflowRegistrationInput =
   Omit<DurableWorkflowHandle, "completedCheckpoints" | "pendingPrompts" | "updatedAt">
   & Partial<Pick<DurableWorkflowHandle, "completedCheckpoints" | "pendingPrompts" | "updatedAt">>;
 
-/**
- * Abstract durable checkpoint store. Implementations:
- * - per-workflow file backend — JSON-file-backed; default cross-process resume.
- * - {@link DbosDurableBackend} — wraps `@dbos-inc/dbos-sdk` + Postgres.
- * - {@link InMemoryDurableBackend} — process-local; explicit test/custom use.
- */
+export type DurableInactiveDeleteResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: "not_found" | "running" };
+
+/** DBOS is the sole persistent implementation. In-memory is an explicit test seam. */
 export interface DurableWorkflowBackend {
-  /**
-   * True when the backend persists across processes (file/DBOS). When false
-   * (in-memory), the engine skips session-cache persistence since there is no
-   * cross-session state to discover. This keeps in-process test runs from
-   * polluting session JSONL with discovery cache entries.
-   */
+  /** Whether state survives the current process. */
   readonly persistent: boolean;
   /** Register or update a workflow's top-level metadata. */
   registerWorkflow(handle: WorkflowRegistrationInput): void;
@@ -69,15 +47,11 @@ export interface DurableWorkflowBackend {
   /** Record a completed checkpoint. Idempotent: same (kind, checkpointId) is a no-op. */
   recordCheckpoint(checkpoint: DurableCheckpoint): void;
 
-  /**
-   * Optional async checkpoint persistence. DBOS-backed implementations use this
-   * so ctx.tool/ctx.ui can await durable writes before returning side-effect
-   * results to workflow code.
-   */
-  recordCheckpointAsync?(checkpoint: DurableCheckpoint): Promise<void>;
+  /** Persist a checkpoint before exposing its side effect. */
+  recordCheckpointAsync(checkpoint: DurableCheckpoint): Promise<void>;
 
-  /** Optional: wait for serialized durable writes to settle. */
-  flush?(): Promise<void>;
+  /** Wait for all serialized writes to settle. */
+  flush(): Promise<void>;
 
   /**
    * Look up a cached tool output by content hash. Returns `undefined` if the
@@ -109,9 +83,24 @@ export interface DurableWorkflowBackend {
 
   /** Get the top-level workflow handle, or `undefined` if not registered. */
   getWorkflow(workflowId: string): DurableWorkflowHandle | undefined;
+  /**
+   * Return one authoritative loadable handle snapshot. Persistent backends use
+   * this narrow seam to refresh once and classify from that same generation.
+   */
+  getLoadableWorkflow(workflowId: string): DurableWorkflowHandle | undefined;
 
   /** Update workflow status (running/paused/completed/failed/cancelled/blocked). */
   setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean): void;
+  /** Atomically update status only when the authoritative status is expected. */
+  transitionWorkflowStatus(
+    workflowId: string,
+    expectedStatuses: readonly DurableWorkflowStatus[],
+    status: DurableWorkflowStatus,
+    pendingPrompts?: number,
+    resumable?: boolean,
+  ): Promise<boolean>;
+  /** Atomically adjust unresolved UI prompt count, clamped at zero. */
+  adjustPendingPrompts(workflowId: string, delta: number): void;
 
   /**
    * List resumable root workflows: running/paused runs with progress and
@@ -120,12 +109,16 @@ export interface DurableWorkflowBackend {
   listResumableWorkflows(): readonly ResumableWorkflowEntry[];
   /** List successful completed root workflows with durable checkpoint progress. */
   listCompletedWorkflows(): readonly ResumableWorkflowEntry[];
+  /** Current DBOS-backed resumable and completed catalog. */
+  prepareWorkflowCatalog(): Promise<DurableWorkflowCatalogEntries>;
 
-  /** Export a session-cache entry for the given workflow (for JSONL persistence). */
-  toCacheEntry(workflowId: string): DurableCheckpointEntry | undefined;
+  /** Shape the current DBOS metadata payload. */
+  toMetadata(workflowId: string): Omit<DurableWorkflowMetadata, "promptReservationEpoch"> | undefined;
 
   /** Permanently remove one root workflow and its durable checkpoints. */
   deleteWorkflow(workflowId: string): Promise<void>;
+  /** Atomically delete only when authoritative state is not currently running. */
+  deleteWorkflowIfInactive(workflowId: string): Promise<DurableInactiveDeleteResult>;
 
   /** Whether a workflow id may be exposed or resumed from live/restored metadata. */
   isWorkflowLoadable(workflowId: string): boolean;
@@ -133,47 +126,18 @@ export interface DurableWorkflowBackend {
   /** Clear all state (for tests). */
   reset(): void;
 
-  /**
-   * Optional: hydrate a single workflow's checkpoints from the persistent
-   * store (DBOS) into the in-memory mirror. Implementations that do not need
-   * async hydration (in-memory, file) omit this method.
-   */
-  hydrateWorkflow?(workflowId: string): Promise<void>;
-
-  /**
-   * Optional: hydrate all resumable workflows from the persistent store (DBOS)
-   * into the in-memory mirror. Called before listing/resuming in a fresh
-   * process. Implementations that do not need async hydration omit this.
-   */
-  hydrateResumableWorkflows?(): Promise<void>;
+  /** Hydrate one workflow from persistent storage. */
+  hydrateWorkflow(workflowId: string): Promise<void>;
+  /** Hydrate all catalog candidates from persistent storage. */
+  hydrateResumableWorkflows(): Promise<void>;
+  promptReservationScope(workflowId: string): { readonly rootWorkflowId: string; readonly scope: string };
+  pendingPromptToken(workflowId: string, reservationId: string): PromptReservationToken | undefined;
+  reservePendingPrompt(workflowId: string, reservationId: string): PromptReservationToken;
+  releasePendingPrompt(workflowId: string, reservationId: string, token: PromptReservationToken): void;
 }
 
-// ---------------------------------------------------------------------------
-// Hashing helpers
-// ---------------------------------------------------------------------------
 
-/**
- * Compute a deterministic content digest for a JSON-serializable value.
- * Uses canonical JSON stringification (sorted keys) for stability and SHA-256
- * for collision resistance. The earlier 32-bit DJB2 hash demonstrably
- * collided across distinct tool/stage identities and could cause completed
- * side effects to be skipped (or merged) incorrectly on resume.
- *
- * cross-ref: issue #1498 — collision-resistant durable replay identities.
- */
-export function durableHash(value: WorkflowSerializableValue | WorkflowSerializableObject): string {
-  const canonical = canonicalJsonString(value);
-  const digest = createHash("sha256").update(canonical).digest("hex");
-  return `h${digest.slice(0, 32)}`;
-}
 
-function canonicalJsonString(value: unknown): string {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(canonicalJsonString).join(",")}]`;
-  const obj = value as Record<string, unknown>;
-  const keys = Object.keys(obj).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJsonString(obj[k])}`).join(",")}}`;
-}
 
 // ---------------------------------------------------------------------------
 // In-memory backend
@@ -192,14 +156,11 @@ function checkpointKey(c: DurableCheckpoint): string {
   return `${c.kind}:${c.checkpointId}`;
 }
 
-/**
- * Process-local durable backend for tests and explicit custom overrides.
- * Checkpoints live in memory for the lifetime of the process; the production
- * default is the cross-process per-workflow file backend.
- */
+/** Process-local current-interface backend for explicit test injection. */
 export class InMemoryDurableBackend implements DurableWorkflowBackend {
-  public readonly persistent = false;
+  public readonly persistent: boolean = false;
   private readonly workflows = new Map<string, InMemoryWorkflowRecord>();
+  private readonly promptReservations = new Map<string, PromptReservationState>();
   private readonly deletedWorkflowIds = new Set<string>();
 
   registerWorkflow(handle: WorkflowRegistrationInput): void {
@@ -225,31 +186,39 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
       ...(handle.label !== undefined ? { label: handle.label } : {}),
       ...(handle.rootWorkflowId !== undefined ? { rootWorkflowId: handle.rootWorkflowId } : {}),
       ...(handle.resumable !== undefined ? { resumable: handle.resumable } : {}),
+      ...(handle.ownerExecutorId !== undefined ? { ownerExecutorId: handle.ownerExecutorId } : existing?.handle.ownerExecutorId !== undefined ? { ownerExecutorId: existing.handle.ownerExecutorId } : {}),
     };
     if (existing) existing.handle = full;
     else this.workflows.set(handle.workflowId, { handle: full, checkpoints: new Map(), toolByHash: new Map(), uiByHash: new Map(), stageOutputByReplayKey: new Map(), stageSessionByReplayKey: new Map() });
+    if (handle.pendingPrompts !== undefined) this.promptReservations.delete(handle.workflowId);
   }
-
   recordCheckpoint(checkpoint: DurableCheckpoint): void {
-    const rec = this.workflows.get(checkpoint.workflowId);
+    const currentCheckpoint = withCurrentStageTopology(checkpoint);
+    const rec = this.workflows.get(currentCheckpoint.workflowId);
     if (!rec) return;
-    const key = checkpointKey(checkpoint);
-    if (rec.checkpoints.has(key)) return; // idempotent
-    rec.checkpoints.set(key, checkpoint);
-    if (checkpoint.kind === "tool") rec.toolByHash.set(checkpoint.argsHash, checkpoint);
-    else if (checkpoint.kind === "ui") rec.uiByHash.set(checkpoint.promptHash, checkpoint);
+    const key = checkpointKey(currentCheckpoint);
+    if (rec.checkpoints.has(key)) return;
+    rec.checkpoints.set(key, currentCheckpoint);
+    if (currentCheckpoint.kind === "tool") rec.toolByHash.set(currentCheckpoint.argsHash, currentCheckpoint);
+    else if (currentCheckpoint.kind === "ui") rec.uiByHash.set(currentCheckpoint.promptHash, currentCheckpoint);
     else {
-      if ("output" in checkpoint) rec.stageOutputByReplayKey.set(checkpoint.replayKey, checkpoint);
-      if (checkpoint.sessionId !== undefined || checkpoint.sessionFile !== undefined) {
-        const existing = rec.stageSessionByReplayKey.get(checkpoint.replayKey);
-        if (existing === undefined || checkpoint.completedAt >= existing.completedAt) {
-          rec.stageSessionByReplayKey.set(checkpoint.replayKey, checkpoint);
+      if ("output" in currentCheckpoint) rec.stageOutputByReplayKey.set(currentCheckpoint.replayKey, currentCheckpoint);
+      if (currentCheckpoint.sessionId !== undefined || currentCheckpoint.sessionFile !== undefined) {
+        const existing = rec.stageSessionByReplayKey.get(currentCheckpoint.replayKey);
+        if (existing === undefined || currentCheckpoint.completedAt >= existing.completedAt) {
+          rec.stageSessionByReplayKey.set(currentCheckpoint.replayKey, currentCheckpoint);
         }
       }
     }
-    rec.handle = { ...rec.handle, completedCheckpoints: rec.checkpoints.size, updatedAt: checkpoint.completedAt };
+    rec.handle = { ...rec.handle, completedCheckpoints: rec.checkpoints.size, updatedAt: currentCheckpoint.completedAt };
+  }
+
+  async recordCheckpointAsync(checkpoint: DurableCheckpoint): Promise<void> {
+    this.recordCheckpoint(checkpoint);
   }
 
+  async flush(): Promise<void> {}
+
   getToolOutput(workflowId: string, argsHash: string): WorkflowSerializableValue | undefined {
     return this.workflows.get(workflowId)?.toolByHash.get(argsHash)?.output;
   }
@@ -288,11 +257,79 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
   getWorkflow(workflowId: string): DurableWorkflowHandle | undefined {
     return this.workflows.get(workflowId)?.handle;
   }
+  getLoadableWorkflow(workflowId: string): DurableWorkflowHandle | undefined {
+    return this.getWorkflow(workflowId);
+  }
+
+  async hydrateWorkflow(_workflowId: string): Promise<void> {}
+
+  async hydrateResumableWorkflows(): Promise<void> {}
+
+  async prepareWorkflowCatalog(): Promise<DurableWorkflowCatalogEntries> {
+    return { resumable: this.listResumableWorkflows(), completed: this.listCompletedWorkflows() };
+  }
 
   setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean): void {
     const rec = this.workflows.get(workflowId);
     if (!rec) return;
     rec.handle = { ...rec.handle, status, updatedAt: Date.now(), ...(pendingPrompts !== undefined ? { pendingPrompts } : {}), ...(resumable !== undefined ? { resumable } : {}) };
+    if (pendingPrompts !== undefined) this.promptReservations.delete(workflowId);
+  }
+
+  async transitionWorkflowStatus(workflowId: string, expected: readonly DurableWorkflowStatus[], status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean): Promise<boolean> {
+    const current = this.workflows.get(workflowId)?.handle.status;
+    if (current === undefined || !expected.includes(current)) return false;
+    this.setWorkflowStatus(workflowId, status, pendingPrompts, resumable);
+    return true;
+  }
+
+  adjustPendingPrompts(workflowId: string, delta: number): void {
+    const state = this.promptState(workflowId);
+    if (state === undefined) return;
+    state.adjust(delta);
+    this.setPromptCount(workflowId, state.pendingPrompts);
+  }
+
+  promptReservationScope(workflowId: string): { readonly rootWorkflowId: string; readonly scope: string } {
+    return { rootWorkflowId: workflowId, scope: "root" };
+  }
+
+  pendingPromptToken(workflowId: string, reservationId: string): PromptReservationToken | undefined {
+    const state = this.promptState(workflowId);
+    const token = state?.claim(reservationId);
+    if (state !== undefined && token !== undefined) this.setPromptCount(workflowId, state.pendingPrompts);
+    return token;
+  }
+
+  reservePendingPrompt(workflowId: string, reservationId: string): PromptReservationToken {
+    const state = this.promptState(workflowId);
+    if (state === undefined) return inactivePromptReservationToken(reservationId);
+    const token = state.reserve(reservationId);
+    this.setPromptCount(workflowId, state.pendingPrompts);
+    return token;
+  }
+
+  releasePendingPrompt(workflowId: string, reservationId: string, token: PromptReservationToken): void {
+    const state = this.promptState(workflowId);
+    if (state === undefined) return;
+    state.release(reservationId, token);
+    this.setPromptCount(workflowId, state.pendingPrompts);
+  }
+
+  private promptState(workflowId: string): PromptReservationState | undefined {
+    const rec = this.workflows.get(workflowId);
+    if (rec === undefined) return undefined;
+    let state = this.promptReservations.get(workflowId);
+    if (state === undefined) {
+      state = new PromptReservationState(rec.handle.pendingPrompts);
+      this.promptReservations.set(workflowId, state);
+    }
+    return state;
+  }
+
+  private setPromptCount(workflowId: string, pendingPrompts: number): void {
+    const rec = this.workflows.get(workflowId);
+    if (rec !== undefined) rec.handle = { ...rec.handle, pendingPrompts, updatedAt: Date.now() };
   }
 
   listResumableWorkflows(): readonly ResumableWorkflowEntry[] {
@@ -307,19 +344,22 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
       .map((rec) => toResumableEntry(rec.handle));
   }
 
-  toCacheEntry(workflowId: string): DurableCheckpointEntry | undefined {
+
+  /** Shape the current DBOS metadata payload. */
+  toMetadata(workflowId: string): Omit<DurableWorkflowMetadata, "promptReservationEpoch"> | undefined {
     const rec = this.workflows.get(workflowId);
     if (!rec) return undefined;
     const h = rec.handle;
     return {
-      formatVersion: DURABLE_FORMAT_VERSION,
-      type: "workflow.durable.checkpoint",
       workflowId: h.workflowId,
       name: h.name,
       inputs: h.inputs,
       status: h.status,
+      createdAt: h.createdAt,
       completedCheckpoints: h.completedCheckpoints,
       pendingPrompts: h.pendingPrompts,
+      ...(h.ownerExecutorId !== undefined ? { ownerExecutorId: h.ownerExecutorId } : {}),
+      ...(h.sessionFile !== undefined ? { sessionFile: h.sessionFile } : {}),
       ...(h.label !== undefined ? { label: h.label } : {}),
       ...(h.rootWorkflowId !== undefined ? { rootWorkflowId: h.rootWorkflowId } : {}),
       ...(h.resumable !== undefined ? { resumable: h.resumable } : {}),
@@ -327,36 +367,34 @@ export class InMemoryDurableBackend implements DurableWorkflowBackend {
       ...(h.workflowCwd !== undefined ? { workflowCwd: h.workflowCwd } : {}),
       ...(h.repositoryRoot !== undefined ? { repositoryRoot: h.repositoryRoot } : {}),
       ...(h.gitWorktreeRoot !== undefined ? { gitWorktreeRoot: h.gitWorktreeRoot } : {}),
-      ts: h.updatedAt,
+      updatedAt: h.updatedAt,
     };
   }
 
   async deleteWorkflow(workflowId: string): Promise<void> {
     this.workflows.delete(workflowId);
+    this.promptReservations.delete(workflowId);
     this.deletedWorkflowIds.add(workflowId);
   }
 
+  async deleteWorkflowIfInactive(workflowId: string): Promise<DurableInactiveDeleteResult> {
+    const handle = this.workflows.get(workflowId)?.handle;
+    if (handle === undefined) return { ok: false, reason: "not_found" };
+    if (handle.status === "running") return { ok: false, reason: "running" };
+    await this.deleteWorkflow(workflowId);
+    return { ok: true };
+  }
+
   isWorkflowLoadable(workflowId: string): boolean {
     return !this.deletedWorkflowIds.has(workflowId);
   }
 
   reset(): void {
     this.workflows.clear();
+    this.promptReservations.clear();
     this.deletedWorkflowIds.clear();
   }
 
-  /** Export all records (for FileDurableBackend serialization or debugging). */
-  exportAll(): readonly { readonly handle: DurableWorkflowHandle; readonly checkpoints: readonly DurableCheckpoint[] }[] {
-    return [...this.workflows.values()].map((rec) => ({ handle: rec.handle, checkpoints: [...rec.checkpoints.values()] }));
-  }
-
-  /** Import records (for FileDurableBackend deserialization). */
-  importAll(records: readonly { readonly handle: DurableWorkflowHandle; readonly checkpoints: readonly DurableCheckpoint[] }[]): void {
-    for (const rec of records) {
-      this.registerWorkflow(rec.handle);
-      for (const cp of rec.checkpoints) this.recordCheckpoint(cp);
-    }
-  }
 }
 
 function isRootWorkflow(handle: DurableWorkflowHandle): boolean {
@@ -371,6 +409,11 @@ function isCompletedHandle(handle: DurableWorkflowHandle): boolean {
   return handle.status === "completed" && hasResumeProgress(handle);
 }
 
+/** Convert a durable workflow handle into a resume-catalog entry. */
+export function resumableEntryFromHandle(handle: DurableWorkflowHandle): ResumableWorkflowEntry {
+  return toResumableEntry(handle);
+}
+
 function toResumableEntry(handle: DurableWorkflowHandle): ResumableWorkflowEntry {
   return {
     workflowId: handle.workflowId,

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

@@ -1,11 +1,12 @@
-import { readFileSync, statSync } from "node:fs";
 import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
 import type { WorkflowInputValues } from "../shared/types.js";
+import { isReopenableSessionTranscript } from "../shared/session-transcript.js";
 import type { DurableWorkflowBackend } from "./backend.js";
-import type {
-  DurableCheckpoint,
-  DurableStageCheckpoint,
-  ResumableWorkflowEntry,
+import {
+  DURABLE_STAGE_TOPOLOGY_VERSION,
+  type DurableCheckpoint,
+  type DurableStageCheckpoint,
+  type ResumableWorkflowEntry,
 } from "./types.js";
 import { resolveDurableEntry } from "./resume-runtime.js";
 
@@ -15,15 +16,6 @@ export type CompletedWorkflowResolution =
   | { readonly kind: "not_found" }
   | { readonly kind: "stale"; readonly entry: ResumableWorkflowEntry };
 
-interface SessionTranscriptEntry {
-  readonly type?: string;
-  readonly id?: string;
-  readonly timestamp?: string;
-  readonly message?: {
-    readonly role?: string;
-    readonly content?: string | object;
-  };
-}
 
 interface StageDraft {
   readonly replayKey: string;
@@ -40,6 +32,7 @@ interface StageDraft {
   readonly fastMode?: boolean;
   readonly attemptedModels?: readonly string[];
   readonly modelAttempts?: DurableStageCheckpoint["modelAttempts"];
+  readonly topology?: DurableStageCheckpoint["topology"];
 }
 
 /** Authoritative completed rows. This path is deliberately separate from resumability. */
@@ -67,9 +60,10 @@ export function resolveCompletedWorkflow(
   if (resolved !== undefined) {
     if ("kind" in resolved) return { kind: "ambiguous", matches: resolved.matches };
     const snapshot = completedWorkflowSnapshot(backend, resolved);
-    return snapshot === undefined
-      ? { kind: "stale", entry: resolved }
-      : { kind: "found", entry: resolved, snapshot };
+    if (snapshot === undefined) {
+      return { kind: "stale", entry: resolved };
+    }
+    return { kind: "found", entry: resolved, snapshot };
   }
 
   const authoritative = resolveDurableEntry(workflowIdOrPrefix, listCompletedFromBackend(backend));
@@ -109,49 +103,6 @@ function validatedStageTranscript(stage: StageSnapshot): StageSnapshot {
   return withoutSessionFile;
 }
 
-function isReopenableSessionTranscript(path: string): boolean {
-  try {
-    const stats = statSync(path);
-    if (!stats.isFile() || stats.size === 0) return false;
-    const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim().length > 0);
-    if (lines.length < 2) return false;
-    const entries: SessionTranscriptEntry[] = [];
-    for (const line of lines) {
-      const parsed = JSON.parse(line) as object;
-      if (typeof parsed !== "object" || parsed === null) return false;
-      entries.push(parsed as SessionTranscriptEntry);
-    }
-    const header = entries[0];
-    return header?.type === "session" && typeof header.id === "string" && entries.some(isUsableContextMessage);
-  } catch {
-    return false;
-  }
-}
-
-function isUsableContextMessage(entry: SessionTranscriptEntry): boolean {
-  return entry.type === "message"
-    && typeof entry.id === "string"
-    && typeof entry.timestamp === "string"
-    && typeof entry.message?.role === "string"
-    && hasUsableMessageContent(entry.message.content);
-}
-
-function hasUsableMessageContent(content: string | object | undefined): boolean {
-  if (typeof content === "string") return content.trim().length > 0;
-  return Array.isArray(content) && content.some(hasUsableContentBlock);
-}
-
-function hasUsableContentBlock(block: object): boolean {
-  if (typeof block !== "object" || block === null) return false;
-  const contentBlock = block as {
-    readonly text?: string;
-    readonly thinking?: string;
-    readonly data?: string;
-    readonly name?: string;
-  };
-  return [contentBlock.text, contentBlock.thinking, contentBlock.data, contentBlock.name]
-    .some((value) => typeof value === "string" && value.trim().length > 0);
-}
 
 function stageSnapshotsFromCheckpoints(
   checkpoints: readonly DurableCheckpoint[],
@@ -165,7 +116,7 @@ function stageSnapshotsFromCheckpoints(
   }
   const ordered = [...drafts.values()].sort((a, b) => a.firstCompletedAt - b.firstCompletedAt);
   if (ordered.length === 0) return [syntheticCheckpointStage(checkpoints.length, fallbackCompletedAt)];
-  return ordered.map(stageSnapshotFromDraft);
+  return stageSnapshotsFromDrafts(ordered);
 }
 
 function mergeStageDraft(
@@ -187,6 +138,7 @@ function mergeStageDraft(
     ...valueOrExisting("fastMode", checkpoint, existing),
     ...valueOrExisting("attemptedModels", checkpoint, existing),
     ...valueOrExisting("modelAttempts", checkpoint, existing),
+    ...valueOrExisting("topology", checkpoint, existing),
   };
 }
 
@@ -199,14 +151,35 @@ function valueOrExisting<
   return existingValue === undefined ? {} : { [key]: existingValue } as Pick<StageDraft, K>;
 }
 
-function stageSnapshotFromDraft(draft: StageDraft, index: number): StageSnapshot {
+function stageSnapshotsFromDrafts(drafts: readonly StageDraft[]): StageSnapshot[] {
+  const reconstructedIds = drafts.map((_, index) => `completed-stage-${index + 1}`);
+  const sourceToReconstructed = new Map<string, string>();
+  for (let index = 0; index < drafts.length; index += 1) {
+    const topology = drafts[index]!.topology;
+    if (topology?.version !== DURABLE_STAGE_TOPOLOGY_VERSION
+      || sourceToReconstructed.has(topology.stageId)) return [];
+    sourceToReconstructed.set(topology.stageId, reconstructedIds[index]!);
+  }
+  if (drafts.some((draft) => draft.topology!.parentIds.some((parentId) => !sourceToReconstructed.has(parentId)))) return [];
+  return drafts.map((draft, index) => stageSnapshotFromDraft(
+    draft,
+    reconstructedIds[index]!,
+    draft.topology!.parentIds.map((parentId) => sourceToReconstructed.get(parentId)!),
+  ));
+}
+
+function stageSnapshotFromDraft(
+  draft: StageDraft,
+  id: string,
+  parentIds: readonly string[],
+): StageSnapshot {
   const startedAt = draft.startedAt ?? draft.firstCompletedAt;
   const endedAt = draft.endedAt ?? draft.firstCompletedAt;
   return {
-    id: `completed-stage-${index + 1}`,
+    id,
     name: draft.name,
     status: "completed",
-    parentIds: [],
+    parentIds,
     startedAt,
     endedAt,
     durationMs: draft.durationMs ?? Math.max(0, endedAt - startedAt),