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

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

@@ -0,0 +1,217 @@
+/**
+ * Cross-session resume catalog.
+ *
+ * Builds the list of resumable workflows for the `/workflow resume` selector by
+ * scanning session JSONL files for `workflow.durable.checkpoint` entries. This
+ * is the session-file cache described by the issue — it lets a new session
+ * discover workflows started in prior sessions without requiring a live DBOS
+ * system database connection.
+ *
+ * The catalog reads session files lazily and caches results per scan. DBOS
+ * remains the checkpoint source of truth; this catalog provides the discovery
+ * index for the selector UI.
+ *
+ * cross-ref: issue #1498 — "/workflow resume should show a selector for
+ * resumable workflow sessions, analogous to the /resume session selector."
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+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";
+
+// ---------------------------------------------------------------------------
+// Session file scanning
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan a session directory for `workflow.durable.checkpoint` entries and build
+ * a list of resumable workflows.
+ *
+ * @param sessionDir Directory containing session JSONL files.
+ * @returns Resumable workflow entries, most recently updated first.
+ */
+export function scanResumableWorkflows(sessionDir: string): readonly ResumableWorkflowEntry[] {
+  if (!existsSync(sessionDir)) return [];
+  const entries = new Map<string, ResumableWorkflowEntry>();
+  let files: string[];
+  try {
+    files = readdirSync(sessionDir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return [];
+  }
+  for (const file of files) {
+    const filePath = join(sessionDir, file);
+    const fileEntries = readDurableEntriesFromFile(filePath);
+    const sessionFile = filePath;
+    for (const entry of fileEntries) {
+      const existing = entries.get(entry.workflowId);
+      if (!existing || entry.ts > existing.updatedAt) {
+        entries.set(entry.workflowId, entryToResumable(entry, sessionFile));
+      }
+    }
+  }
+  return [...entries.values()].filter(isResumableEntry).sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+function readDurableEntriesFromFile(filePath: string): readonly DurableCheckpointEntry[] {
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    return [];
+  }
+  const results: DurableCheckpointEntry[] = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      const rawEntry = durablePayloadFromJsonlEntry(parsed);
+      if (rawEntry !== undefined) {
+        const entry = parseDurableEntry(rawEntry);
+        if (entry) results.push(entry);
+      }
+    } catch {
+      // Skip malformed lines.
+    }
+  }
+  return results;
+}
+
+function durablePayloadFromJsonlEntry(parsed: Record<string, unknown>): Record<string, unknown> | undefined {
+  if (parsed["type"] === "workflow.durable.checkpoint") return parsed;
+  if (parsed["type"] !== "custom" || parsed["customType"] !== "workflow.durable.checkpoint") return undefined;
+  const data = parsed["data"];
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return undefined;
+  return data as Record<string, unknown>;
+}
+
+function parseDurableEntry(raw: Record<string, unknown>): DurableCheckpointEntry | undefined {
+  const workflowId = raw["workflowId"];
+  const name = raw["name"];
+  const inputs = raw["inputs"];
+  const status = raw["status"];
+  const ts = raw["ts"];
+  if (typeof workflowId !== "string" || typeof name !== "string" || typeof status !== "string" || typeof ts !== "number") return undefined;
+  if (!isWorkflowSerializableObject(inputs)) return undefined;
+  return {
+    type: "workflow.durable.checkpoint",
+    workflowId,
+    name,
+    inputs,
+    status: status as DurableWorkflowStatus,
+    completedCheckpoints: typeof raw["completedCheckpoints"] === "number" ? raw["completedCheckpoints"] : 0,
+    pendingPrompts: typeof raw["pendingPrompts"] === "number" ? raw["pendingPrompts"] : 0,
+    ...(typeof raw["label"] === "string" ? { label: raw["label"] } : {}),
+    ...(typeof raw["rootWorkflowId"] === "string" ? { rootWorkflowId: raw["rootWorkflowId"] } : {}),
+    ...(typeof raw["resumable"] === "boolean" ? { resumable: raw["resumable"] } : {}),
+    ts,
+  };
+}
+
+function isWorkflowSerializableObject(value: unknown): value is Readonly<Record<string, WorkflowSerializableValue>> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const obj = value as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    if (!isSerializableValue(obj[key])) return false;
+  }
+  return true;
+}
+
+function isSerializableValue(value: unknown): value is WorkflowSerializableValue {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return true;
+  if (Array.isArray(value)) return value.every(isSerializableValue);
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    return Object.keys(obj).every((k) => isSerializableValue(obj[k]));
+  }
+  return false;
+}
+
+function entryToResumable(entry: DurableCheckpointEntry, sessionFile: string): ResumableWorkflowEntry {
+  return {
+    workflowId: entry.workflowId,
+    name: entry.name,
+    inputs: entry.inputs,
+    status: entry.status,
+    completedCheckpoints: entry.completedCheckpoints,
+    pendingPrompts: entry.pendingPrompts,
+    sessionFile,
+    ...(entry.label !== undefined ? { label: entry.label } : {}),
+    ...(entry.rootWorkflowId !== undefined ? { rootWorkflowId: entry.rootWorkflowId } : {}),
+    ...(entry.resumable !== undefined ? { resumable: entry.resumable } : {}),
+    createdAt: entry.ts,
+    updatedAt: entry.ts,
+  };
+}
+
+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
+// ---------------------------------------------------------------------------
+
+/**
+ * List resumable workflows from a durable backend (in-memory or file-backed).
+ * Used when the session file scan is not available (e.g. same-process resume).
+ */
+export function listResumableFromBackend(backend: DurableWorkflowBackend): readonly ResumableWorkflowEntry[] {
+  return backend.listResumableWorkflows();
+}
+
+/**
+ * Append a durable checkpoint entry to a session JSONL persistence port.
+ * This caches the top-level workflow metadata so a future session can discover
+ * it via {@link scanResumableWorkflows}.
+ */
+export function persistDurableCacheEntry(
+  persistence: { appendEntry?: (type: string, payload: Record<string, unknown>) => string | undefined },
+  entry: DurableCheckpointEntry,
+): void {
+  if (typeof persistence.appendEntry !== "function") return;
+  persistence.appendEntry("workflow.durable.checkpoint", {
+    workflowId: entry.workflowId,
+    name: entry.name,
+    inputs: entry.inputs as Record<string, unknown>,
+    status: entry.status,
+    completedCheckpoints: entry.completedCheckpoints,
+    pendingPrompts: entry.pendingPrompts,
+    ...(entry.label !== undefined ? { label: entry.label } : {}),
+    ...(entry.rootWorkflowId !== undefined ? { rootWorkflowId: entry.rootWorkflowId } : {}),
+    ...(entry.resumable !== undefined ? { resumable: entry.resumable } : {}),
+    ts: entry.ts,
+  });
+}
+
+/**
+ * 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})`;
+  });
+  return `Resumable workflows:\n${lines.join("\n")}`;
+}

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

@@ -0,0 +1,299 @@
+/**
+ * Cross-session durable workflow resume adapter.
+ *
+ * Resumes a workflow whose durable checkpoints live in the durable backend
+ * (and are mirrored to the session JSONL cache) but whose in-process run is no
+ * longer live. This is the production path behind `/workflow resume <id>` when
+ * the id names a durable workflow that is not present in the live run store.
+ *
+ * Resume semantics (DBOS-aligned):
+ *   1. Look up the durable catalog entry (workflow name + cached inputs).
+ *   2. Resolve the workflow definition from the registry.
+ *   3. Re-dispatch the workflow as a new background run, reusing the ORIGINAL
+ *      top-level workflow id as the run id. Because durable checkpoints are
+ *      keyed by workflow id, every `ctx.tool` / `ctx.ui` / `ctx.stage` call
+ *      inside the resumed run returns its cached result instead of re-executing
+ *      — completed side effects are not repeated, exactly like DBOS replay.
+ *
+ * The adapter deliberately re-dispatches through `runDetached` rather than
+ * reconstructing an in-memory snapshot, so it works across processes and
+ * sessions without a live store entry.
+ *
+ * cross-ref: issue #1498 — "/workflow resume connects/attempts resume by
+ * top-level workflow id."
+ */
+
+import type { WorkflowInputValues } from "../shared/types.js";
+import type { WorkflowRegistry } from "../workflows/registry.js";
+import type { RunOpts } from "../runs/foreground/executor-types.js";
+import { runDetached, type DetachedAccepted } from "../runs/background/runner.js";
+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 { 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";
+
+export type ResumeDurableResult =
+  | { ok: true; runId: string; workflowId: string; name: string; message: string }
+  | { ok: false; reason: "workflow_not_found" | "not_resumable" | "invalid_inputs" | "not_registered" | "stale"; message: string };
+
+export interface ResumeDurableDeps {
+  readonly registry: WorkflowRegistry;
+  /** Base run options forwarded to the detached runner (store, persistence, …). */
+  readonly baseRunOpts: RunOpts;
+  /** Durable backend override (defaults to the global singleton). */
+  readonly durableBackend?: DurableWorkflowBackend;
+}
+
+/**
+ * Prepare a durable resume: hydrate the backend's in-memory mirror from the
+ * persistent store (DBOS) so synchronous reads in {@link resumeDurableWorkflow}
+ * find the workflow and its checkpoints. No-op for backends without hydration.
+ *
+ * Must be awaited before calling {@link resumeDurableWorkflow} when the backend
+ * might be a fresh DBOS process.
+ */
+export async function prepareDurableResume(
+  workflowIdOrPrefix: string | undefined,
+  deps: ResumeDurableDeps,
+): Promise<readonly ResumableWorkflowEntry[]> {
+  const backend = deps.durableBackend ?? getDurableBackend();
+  // Hydrate all resumable workflows first so the catalog is complete.
+  if (backend.hydrateResumableWorkflows !== undefined) {
+    await backend.hydrateResumableWorkflows();
+  }
+  const catalog = backend.listResumableWorkflows();
+  // If a specific target was requested, hydrate that workflow too (it might
+  // be resumable but not yet in the resumable filter — e.g. recently failed).
+  if (workflowIdOrPrefix !== undefined) {
+    const resolved = resolveDurableEntry(workflowIdOrPrefix, catalog);
+    if (resolved !== undefined && !("kind" in resolved)) {
+      if (backend.hydrateWorkflow !== undefined) {
+        await backend.hydrateWorkflow(resolved.workflowId);
+      }
+    }
+  }
+  return backend.listResumableWorkflows();
+}
+
+/**
+ * Resolve a durable catalog entry for a workflow id (full or prefix match).
+ * Prefers the durable backend's resumable list; falls back to an explicit
+ * session-scan catalog when provided by the caller.
+ */
+export function resolveDurableEntry(
+  workflowIdOrPrefix: string,
+  catalog: readonly ResumableWorkflowEntry[],
+): ResumableWorkflowEntry | { kind: "ambiguous"; matches: readonly ResumableWorkflowEntry[] } | undefined {
+  const exact = catalog.find((entry) => entry.workflowId === workflowIdOrPrefix);
+  if (exact !== undefined) return exact;
+  const prefixMatches = catalog.filter((entry) => entry.workflowId.startsWith(workflowIdOrPrefix));
+  if (prefixMatches.length === 0) return undefined;
+  if (prefixMatches.length === 1) return prefixMatches[0];
+  return { kind: "ambiguous", matches: prefixMatches };
+}
+
+/**
+ * Resume a durable workflow by top-level workflow id. Re-dispatches the workflow
+ * with the cached inputs and the original workflow id so durable checkpoints
+ * replay (skipping completed side effects).
+ */
+export function resumeDurableWorkflow(
+  workflowIdOrPrefix: string,
+  deps: ResumeDurableDeps,
+  catalog?: readonly ResumableWorkflowEntry[],
+): ResumeDurableResult {
+  const backend = deps.durableBackend ?? getDurableBackend();
+  const resolvedCatalog = catalog ?? backend.listResumableWorkflows();
+  const resolved = resolveDurableEntry(workflowIdOrPrefix, resolvedCatalog);
+  if (resolved === undefined) {
+    // 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`
+    // durable handle is a crashed process and falls through to not-found.
+    const direct = backend.getWorkflow(workflowIdOrPrefix);
+    if (direct !== undefined && direct.status === "running" && hasActiveLiveRun(deps.baseRunOpts.store, direct.workflowId)) {
+      return alreadyRunningResult(direct.name, direct.workflowId, deps.baseRunOpts.store);
+    }
+    return { ok: false, reason: "not_registered", message: `No durable workflow found for id/prefix: ${workflowIdOrPrefix}` };
+  }
+  if ("kind" in resolved) {
+    return {
+      ok: false,
+      reason: "not_registered",
+      message: `Ambiguous workflow prefix "${workflowIdOrPrefix}" matches: ${resolved.matches.map((m) => `${m.name} (${m.workflowId.slice(0, 8)})`).join(", ")}`,
+    };
+  }
+  // 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
+  // session — otherwise it is a crashed process and cross-session crash
+  // recovery should proceed.
+  const handle = backend.getWorkflow(resolved.workflowId);
+  if (handle === undefined) {
+    return {
+      ok: false,
+      reason: "stale",
+      message: `Workflow ${resolved.workflowId.slice(0, 8)} has only session-cache metadata and no durable checkpoint state; resume would re-run from scratch. Re-run the workflow to start fresh.`,
+    };
+  }
+  if (handle.status === "running" && hasActiveLiveRun(deps.baseRunOpts.store, resolved.workflowId)) {
+    return alreadyRunningResult(resolved.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.` };
+  }
+
+  const def = deps.registry.get(resolved.name);
+  if (def === undefined) {
+    return { ok: false, reason: "workflow_not_found", message: `Workflow definition not found: ${resolved.name}` };
+  }
+  if (!isWorkflowDefinition(def)) {
+    return { ok: false, reason: "workflow_not_found", message: workflowDefinitionRequirementMessage("resumeDurableWorkflow", def) };
+  }
+
+  const inputs: Record<string, unknown> = { ...handle.inputs };
+  try {
+    resolveAndValidateInputs(def.inputs, inputs as WorkflowInputValues, `workflow "${def.name}"`);
+  } catch (err) {
+    return { ok: false, reason: "invalid_inputs", message: `invalid_inputs: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  removeDurableResumeShadowRuns(deps.baseRunOpts.store, resolved.workflowId);
+
+
+  // Mark the workflow as resuming in the backend, then re-dispatch with the
+  // ORIGINAL workflow id as the run id so durable checkpoints replay.
+  backend.setWorkflowStatus(resolved.workflowId, "running");
+
+  const accepted: DetachedAccepted = runDetached(def, inputs, {
+    ...deps.baseRunOpts,
+    runId: resolved.workflowId,
+    durableBackend: backend,
+  });
+
+  return {
+    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.`,
+  };
+}
+
+function isDurableResumeShadow(run: RunSnapshot): boolean {
+  return run.endedAt !== undefined || run.exitReason === "quit" || run.status === "paused";
+}
+
+function removeDurableResumeShadowRuns(store: RunOpts["store"], workflowId: string): void {
+  if (store === undefined) return;
+  for (;;) {
+    const existing = store.runs().find((run) => run.id === workflowId);
+    if (existing === undefined || !isDurableResumeShadow(existing)) return;
+    if (!store.removeRun(workflowId)) return;
+  }
+}
+
+function alreadyRunningResult(name: string, workflowId: string, store: RunOpts["store"]): ResumeDurableResult {
+  const here = store?.runs().some((r) => r.id === workflowId && r.endedAt === undefined) === true;
+  return {
+    ok: false,
+    reason: "not_resumable",
+    message: `Workflow "${name}" (${workflowId.slice(0, 8)}) is already running${
+      here ? " in this session" : " in another session"
+    }. Attach with \`/workflow connect ${workflowId.slice(0, 8)}\`, or if that session has ended, clear it with \`/workflow kill ${workflowId.slice(0, 8)}\` and re-run.`,
+  };
+}
+
+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
+ * `running` handle is genuinely live in THIS process — distinguishing a real
+ * double-resume from cross-session crash recovery.
+ */
+function hasActiveLiveRun(store: RunOpts["store"] | undefined, workflowId: string): boolean {
+  if (store === undefined) return false;
+  return store.runs().some((r) => r.id === workflowId && r.endedAt === undefined && r.exitReason !== "quit");
+}
+
+/**
+ * Check whether the durable backend records a TERMINAL (non-resumable) status
+ * for the given workflow id. Terminal status suppresses stale session-cache
+ * entries so a completed/cancelled workflow is not resurrected as resumable.
+ *
+ * Returns true only when the backend has a registered handle whose status is
+ * definitively terminal (completed, cancelled, or failed-and-non-resumable).
+ */
+export function isBackendTerminal(backend: DurableWorkflowBackend, workflowId: string): boolean {
+  const handle = backend.getWorkflow(workflowId);
+  if (handle === undefined) return false;
+  const status = handle.status;
+  if (status === "completed" || status === "cancelled") return true;
+  if (status === "failed" || status === "blocked") return handle.resumable === false;
+  return false;
+}
+
+function hasBackendResumeState(backend: DurableWorkflowBackend, workflowId: string): boolean {
+  return backend.getWorkflow(workflowId) !== undefined;
+}
+
+/**
+ * Runtime-facing async preparation: hydrate the durable backend from DBOS
+ * (when supported) then list resumable workflows with optional session-dir
+ * scan merge. Used by the ExtensionRuntime's `prepareDurableResumable`.
+ *
+ * Stale-cache suppression: when a session JSONL cache entry has no matching
+ * durable backend handle, it came from an older/non-checkpointed workflow
+ * engine and is hidden from selectors. When the backend knows a workflow is
+ * terminal (completed/cancelled/non-resumable), stale cache rows for that id
+ * are also suppressed. cross-ref: issue #1498.
+ */
+export async function prepareRuntimeDurableResumable(
+  getBackend: () => DurableWorkflowBackend,
+  resolveSessionDir: () => string | undefined,
+  workflowIdOrPrefix?: string,
+  sessionDir?: string,
+): Promise<readonly ResumableWorkflowEntry[]> {
+  const backend = getBackend();
+  if (backend.hydrateResumableWorkflows !== undefined) {
+    await backend.hydrateResumableWorkflows();
+  }
+  if (workflowIdOrPrefix !== undefined && backend.hydrateWorkflow !== undefined) {
+    const catalog = backend.listResumableWorkflows();
+    const resolved = resolveDurableEntry(workflowIdOrPrefix, catalog);
+    if (resolved !== undefined && !("kind" in resolved)) {
+      await backend.hydrateWorkflow(resolved.workflowId);
+    }
+  }
+  const live = backend.listResumableWorkflows();
+  const effectiveSessionDir = sessionDir ?? resolveSessionDir();
+  if (effectiveSessionDir === undefined) return live;
+  const { scanResumableWorkflows } = await import("./resume-catalog.js");
+  const scanned = scanResumableWorkflows(effectiveSessionDir);
+  const liveIds = new Set(live.map((e) => e.workflowId));
+  // Suppress cache-only entries from older workflow engines. Without a
+  // 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)
+  );
+  return [...live, ...suppressed];
+}

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

@@ -0,0 +1,171 @@
+/**
+ * Scoped durable backend for child workflow runs.
+ *
+ * A child workflow launched via `ctx.workflow(child)` runs with its own run id,
+ * but its internal `ctx.tool` / `ctx.ui` / `ctx.stage` side effects must be
+ * checkpointed under the PARENT (root) durable workflow so that an interrupted
+ * child does not re-execute completed side effects when the parent is resumed.
+ *
+ * Without scoping, child checkpoints are written under a fresh per-run UUID
+ * that is never recovered on resume, so a re-dispatched child loses all of its
+ * prior checkpoints and re-runs side effects (split-brain). {@link ScopedDurableBackend}
+ * remaps every checkpoint identity to the root workflow id, prefixed by a stable
+ * child boundary key, so the same side effects are recovered on resume.
+ *
+ * Only checkpoint read/write methods are scoped. Lifecycle methods
+ * (`registerWorkflow`, `setWorkflowStatus`, `listResumableWorkflows`,
+ * `toCacheEntry`, `getWorkflow`) are no-ops for scoped children because child
+ * runs are never independently resumable — only the root workflow is resumed.
+ *
+ * cross-ref: issue #1498 — child side effects under the root durable workflow.
+ */
+
+import type { DurableCheckpoint, DurableWorkflowStatus, ResumableWorkflowEntry } from "./types.js";
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DurableWorkflowBackend, WorkflowRegistrationInput } from "./backend.js";
+
+/**
+ * Durable scope for a child workflow run.
+ *
+ * - `rootWorkflowId`: the top-level workflow id under which checkpoints persist.
+ * - `scopePrefix`: a stable boundary key (e.g. `workflow:<name>:<ordinal>`)
+ *   unique within the root so multiple children (and the root itself) do not
+ *   collide.
+ */
+export interface DurableScope {
+  readonly rootWorkflowId: string;
+  readonly scopePrefix: string;
+}
+
+/**
+ * Wrap a durable backend so all checkpoint identities for a child run are
+ * namespaced under the root workflow. The wrapped backend is the source of
+ * truth; this wrapper only translates keys.
+ */
+export class ScopedDurableBackend implements DurableWorkflowBackend {
+  public readonly persistent: boolean;
+  private readonly inner: DurableWorkflowBackend;
+  private readonly scope: DurableScope;
+
+  constructor(inner: DurableWorkflowBackend, scope: DurableScope) {
+    this.inner = inner;
+    this.scope = scope;
+    this.persistent = inner.persistent;
+  }
+
+  registerWorkflow(_handle: WorkflowRegistrationInput): void {
+    // Child runs are not independently resumable; only the root is registered.
+  }
+
+  recordCheckpoint(checkpoint: DurableCheckpoint): void {
+    this.inner.recordCheckpoint(this.remap(checkpoint));
+  }
+
+  async recordCheckpointAsync(checkpoint: DurableCheckpoint): Promise<void> {
+    if (this.inner.recordCheckpointAsync !== undefined) {
+      await this.inner.recordCheckpointAsync(this.remap(checkpoint));
+      return;
+    }
+    this.inner.recordCheckpoint(this.remap(checkpoint));
+    await this.inner.flush?.();
+  }
+
+  flush(): Promise<void> {
+    return this.inner.flush?.() ?? Promise.resolve();
+  }
+
+  getToolOutput(_workflowId: string, argsHash: string): WorkflowSerializableValue | undefined {
+    return this.inner.getToolOutput(this.scope.rootWorkflowId, this.scopeKey(argsHash));
+  }
+
+  getUiResponse(_workflowId: string, promptHash: string): WorkflowSerializableValue | undefined {
+    return this.inner.getUiResponse(this.scope.rootWorkflowId, this.scopeKey(promptHash));
+  }
+
+  getStageOutput(_workflowId: string, replayKey: string): WorkflowSerializableValue | undefined {
+    return this.inner.getStageOutput(this.scope.rootWorkflowId, this.scopeKey(replayKey));
+  }
+
+  getStageSession(_workflowId: string, replayKey: string): { sessionId?: string; sessionFile?: string } | undefined {
+    return this.inner.getStageSession(this.scope.rootWorkflowId, this.scopeKey(replayKey));
+  }
+
+  listCheckpoints(_workflowId: string): readonly DurableCheckpoint[] {
+    const all = this.inner.listCheckpoints(this.scope.rootWorkflowId);
+    const prefix = `${this.scope.scopePrefix}:`;
+    // Checkpoints are stored with their scope prefix already embedded in their
+    // ids (see remap()). Filter by the stored id directly — NOT by re-prefixing
+    // — so sibling scopes (e.g. "workflow:child:1") are excluded when the
+    // current scope is "workflow:child:2". Re-prefixing would prepend the
+    // current scope prefix to every id, causing sibling ids to falsely match.
+    return all.filter((cp) => storedScopeId(cp).startsWith(prefix));
+  }
+
+  getWorkflow(_workflowId: string): undefined {
+    // Child runs have no independent resumable handle.
+    return undefined;
+  }
+
+  setWorkflowStatus(_workflowId: string, _status: DurableWorkflowStatus, _pendingPrompts?: number, _resumable?: boolean): void {
+    // No-op: child status is reflected via the root workflow boundary.
+  }
+
+  listResumableWorkflows(): readonly ResumableWorkflowEntry[] {
+    return [];
+  }
+
+  toCacheEntry(_workflowId: string): undefined {
+    return undefined;
+  }
+
+  reset(): void {
+    // No-op: scoped backends never own root state.
+  }
+
+  hydrateWorkflow(_workflowId: string): Promise<void> {
+    return Promise.resolve();
+  }
+
+  hydrateResumableWorkflows(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  private scopeKey(key: string): string {
+    return `${this.scope.scopePrefix}:${key}`;
+  }
+
+  private remap(checkpoint: DurableCheckpoint): DurableCheckpoint {
+    const workflowId = this.scope.rootWorkflowId;
+    if (checkpoint.kind === "tool") {
+      return {
+        ...checkpoint,
+        workflowId,
+        checkpointId: this.scopeKey(checkpoint.checkpointId),
+        argsHash: this.scopeKey(checkpoint.argsHash),
+      };
+    }
+    if (checkpoint.kind === "ui") {
+      return {
+        ...checkpoint,
+        workflowId,
+        checkpointId: this.scopeKey(checkpoint.checkpointId),
+        promptHash: this.scopeKey(checkpoint.promptHash),
+      };
+    }
+    return {
+      ...checkpoint,
+      workflowId,
+      checkpointId: this.scopeKey(checkpoint.checkpointId),
+      replayKey: this.scopeKey(checkpoint.replayKey),
+    };
+  }
+}
+
+/**
+ * Return the checkpoint's stored scope-qualified id, which includes any scope
+ * prefix embedded by {@link ScopedDurableBackend.remap}. This is the raw stored
+ * value used for prefix filtering in {@link ScopedDurableBackend.listCheckpoints}.
+ */
+function storedScopeId(cp: DurableCheckpoint): string {
+  return cp.kind === "stage" ? cp.replayKey : cp.checkpointId;
+}