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

package/dist/builtin/web-access/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.3-alpha.3] - 2026-06-27
+
+### Changed
+
+- Published a synchronized Atomic 0.9.3-alpha.3 prerelease for the web-access extension; no web-access extension changes were made after 0.9.2.
+
 ## [0.9.2] - 2026-06-23
 
 ### Changed

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.3-alpha.1",
+  "version": "0.9.3-alpha.3",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,10 +6,59 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.3-alpha.3] - 2026-06-27
+
+### Changed
+
+- Published the Atomic 0.9.3-alpha.3 prerelease for the workflows extension from the same code as 0.9.3-alpha.2; no workflow changes were made after the previous prerelease.
+
+## [0.9.3-alpha.2] - 2026-06-27
+
+### Breaking Changes
+
+- Workflow durability is now enabled by default with the zero-infrastructure per-workflow file backend rooted under `~/.atomic/workflow-durable`; the previous process-local in-memory default and `ATOMIC_WORKFLOW_DURABLE_DIR` opt-in path were removed. In-memory durability remains available for explicit test/custom backend overrides and for the privacy opt-out `ATOMIC_WORKFLOW_DURABLE=0`/`false`/`off`/`memory`. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+
+### Added
+
+- Added `StageContext.sendUserMessage(content, { deliverAs? })` so workflow authors can inject a normal follow-on user turn into a stage session after `prompt()` resolves. Idle sessions start immediately, streaming sessions queue as follow-up by default (or steering with `deliverAs: "steer"`), schema-backed stages can continue after their one allowed structured `prompt()` without tripping the one-shot prompt guard, follow-on turns preserve the stage MCP allow/deny scope, and native stage sessions accept the same string or text/image block content as `AgentSession.sendUserMessage()`. Durable replayed cached stages now reject this live-session operation instead of silently ignoring it. ([#1520](https://github.com/bastani-inc/atomic/issues/1520))
+- Added cross-session workflow resumability via a durable workflow backend seam (`packages/workflows/src/durable/`). Workflows now persist `ctx.*` operation checkpoints (tool, ui, stage) to a durable backend so a new Atomic session can resume a workflow started in a prior session from the last completed checkpoint, without re-running completed work. Cross-session persistence is enabled by default through a lock-protected per-workflow file backend at `~/.atomic/workflow-durable`; no environment variable is required. When `DBOS_SYSTEM_DATABASE_URL` is set, Atomic lazily initializes DBOS with Postgres-backed workflow/control records and falls back to the file backend if DBOS is unavailable. Top-level workflow metadata is mirrored as `workflow.durable.checkpoint` session entries for `/workflow resume` discovery. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Introduced `ctx.tool(name, args, fn, options?)` — a durable cached tool execution primitive that runs arbitrary TypeScript code and caches the result so completed side effects are not repeated on resume. Supports optional retry with exponential backoff via `retriesAllowed`, `maxAttempts`, `intervalMs`, and `backoffRate` options. Only `ctx.*` blocks produce durable checkpoints. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Added durable `ctx.ui` checkpointing: completed `ctx.ui.input` / `confirm` / `select` / `editor` / `custom` responses are cached by prompt identity that includes method, label/message, options, and call order, so repeated prompts do not collide and a resumed workflow does not re-ask already-answered prompts. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Added durable `ctx.stage` / `ctx.task` / `ctx.chain` / `ctx.parallel` / child `ctx.workflow` checkpointing: completed stage-like outputs are recorded with stable ordinal replay keys and replayed on resume, skipping re-execution while avoiding checkpoint id collisions after redispatch. Chain and parallel items reuse durable task checkpoints, and child workflow calls checkpoint the completed child result at the parent boundary. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Wired `/workflow resume` into the TUI command surface to fall back to the cross-session durable resume catalog when a target id is not a live run, and to surface durable root workflow history in fresh sessions. It lists resumable workflows by top-level id and resumes via DBOS-style replay (re-dispatch with the original workflow id so completed checkpoints are skipped), mirroring `/resume` ergonomics. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Added `@dbos-inc/dbos-sdk` as an optional dependency of `@bastani/atomic` so DBOS-backed durable execution is available without a separate install when the SDK resolves. The workflows package remains dependency-free at runtime; the DBOS adapter is loaded lazily only when `DBOS_SYSTEM_DATABASE_URL` is set. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Added a cross-session resume catalog (`scanResumableWorkflows`) that scans session JSONL files for durable checkpoint entries to build the `/workflow resume` selector list, displaying root workflow name, status, completed checkpoint count, and pending prompts. The scanner understands Atomic's actual extension custom-entry JSONL shape (`type: "custom"`, `customType: "workflow.durable.checkpoint"`) as well as legacy direct checkpoint rows.
+- Added cancellation, failure, and retry semantics for durable workflows: killed/cancelled workflows are marked `cancelled` and excluded from automatic resume; recoverable failures remain in the resumable list; non-recoverable failures are filtered out; `ctx.tool` retries with exponential backoff; pending `ctx.ui` prompts leave off on resume for the user to answer.
+- Added DBOS read-side hydration: when `DBOS_SYSTEM_DATABASE_URL` is set, a fresh Atomic process now hydrates its in-memory checkpoint mirror from DBOS on `/workflow resume` so workflows persisted by a prior session can be discovered and replayed without prior in-process state. Checkpoint records are stored as structured envelopes (including kind, checkpoint id, args hash, prompt hash, and replay key) in DBOS so hydration fully reconstructs the original checkpoint metadata. Root workflow metadata is mirrored separately, so DBOS helper-workflow completion does not make Atomic roots appear completed; `ctx.tool`/`ctx.ui`/`ctx.task` await async DBOS checkpoint persistence before returning side-effect results. Legacy/simple DBOS step outputs without the envelope are handled gracefully as generic stage checkpoints. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+
+### Fixed
+
+- Added direct mouse-click activation for visible workflow graph nodes: clicking a node now focuses it and opens/attaches it through the same path as pressing Enter, with hit-testing based on the rendered node rectangles so overlay chrome/scroll geometry stays in sync while wheel scrolling and empty-space/chrome clicks remain safe no-ops. ([#1521](https://github.com/bastani-inc/atomic/issues/1521))
+- Fixed attached workflow stage chats to capture mouse/trackpad wheel events by default and enable button-event SGR terminal reporting, keeping scroll gestures inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback; `ctrl+t` now toggles true copy mode by disabling workflow-chat mouse reporting so terminal/tmux text selection works normally. ([#1519](https://github.com/bastani-inc/atomic/issues/1519))
+- Routed idle `StageContext.sendUserMessage()` turns through the workflow stage guard so first-call injected turns record normal stage lifecycle and all idle injected turns observe abort/kill wiring, MCP scope, readiness handling, and the concurrency limiter. ([#1520](https://github.com/bastani-inc/atomic/issues/1520))
+- Fixed attached workflow stage chats so stale terminal, paused, blocked, skipped, or otherwise no-longer-running live stage handles, terminal run/stage transitions before `agent_end`, reopened terminal chats, late post-terminal subagent tool updates, and partial subagent workflow-graph progress no longer keep the `Working...` spinner, animation tick, subagent renderer interval, renderer animation registry entry, or subagent progress spinner active, while genuine follow-up/prompt/resume `agent_start` work still shows progress on retained terminal stage chats. ([#1518](https://github.com/bastani-inc/atomic/issues/1518))
+- Fixed `/workflow resume`'s interactive picker to reuse the same Atomic `/resume` session-selector tree chrome for live, paused, failed-resumable, and cross-session durable workflows, replacing the hand-rolled durable/combined picker so the selector is cosmetically consistent across resume flows. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Matched `/resume` empty-state behavior for interactive `/workflow resume` by opening the shared empty selector when no resumable workflow rows remain after filtering instead of printing an error. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Hid `/workflow resume` selector entries that only exist as stale session-cache metadata with no matching durable backend handle and hid durable `running`/`failed`/`blocked` rows whose workflow definition is no longer registered, filtering old pre-checkpoint-engine/test workflow runs instead of surfacing rows that can only fail as stale or missing-definition. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Persisted terminal non-resumable durable metadata during finalization so non-recoverable failed/blocked workflows do not remain visible in `/workflow resume` as resumable entries after they are completely finished. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Delayed durable `/workflow resume` discovery for `running`/`paused` workflows until the first durable checkpoint or pending checkpointable prompt exists, records resumable LM-stage session metadata as soon as a stage opens, and reopens that exact Atomic/Pi session file on durable resume so eligible stages continue mid-session while completed tool/UI/stage checkpoints still replay all-or-nothing. CLI/orchestrator quit now leaves durable-progress workflows resumable instead of treating panel close as an authoritative kill; `/workflow kill` remains the explicit non-resumable disposal path, and successful completion still marks the root workflow terminal and removes the row once the whole workflow terminates to the end. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed repeated quit/resume durable LM-stage cycles by keeping in-progress stage-session metadata separate from completed stage-output checkpoints, persisting DBOS checkpoint records by checkpoint id rather than replay key, removing stale quit snapshots before reusing the original durable workflow id, and sending a single `Continue` continuation message to the recorded LM session instead of replaying the original workflow prompt. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Made `/workflow resume` list only inactive workflows: actively-running durable runs are hidden from the selector and refused on resume (in-session or cross-session) with an intuitive error pointing at `/workflow connect`/`/workflow kill`, while quitting the CLI/panel flips the durable handle from `running` to `paused` so it re-enters the resumable set. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed DBOS durable metadata updates to use versioned metadata records with latest-timestamp hydration, removed invalid DBOS `duplicationPolicy` parameters, awaited completed stage checkpoint writes before returning to workflow code where practical, awaited DBOS initialization before first dispatch/list/resume in DBOS-configured runtimes, opened an interactive durable picker for no-arg `/workflow resume` when only durable entries exist (including sessions with only completed local runs), distinguished repeated same-name/same-args `ctx.tool` calls by stable ordinal identity, and made retry backoff observe cancellation before later attempts run. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed durable stage lifecycle persistence so workflow completion waits for pending backend checkpoint writes (including DBOS async writes) and reports a failed run when those writes fail instead of acknowledging success before checkpoints are durable. Terminal durable status metadata is flushed before completed/failed/cancelled root runs return. Cached `ctx.task`, `ctx.chain`/`ctx.parallel` items, and child `ctx.workflow` replay now record completed replay nodes in the workflow graph/store, matching cached `ctx.stage` visibility. DBOS `recordCheckpointAsync()` updates the replay mirror only after DBOS accepts the checkpoint, so failed durable writes do not make the current process believe a side effect is safely replayable. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed repeated `ctx.workflow(child)` calls to use a dedicated durable replay-key counter so cache-hit calls do not desync ordinal sequencing across resume; direct completed stages now checkpoint under the durable replay key used for lookup instead of the executor snapshot key; `ctx.exit` terminal states (`cancelled`, `blocked`, `skipped`) are now persisted to durable metadata and flushed; no-arg `/workflow resume` surfaces durable workflow history even when live local runs exist; and `durableBackend` is propagated into child workflow run options so custom backends are shared across parent and child instead of split-braining. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed durable resume edge cases where workflows discovered only from session JSONL could be dropped before actual resume, schema-backed stage replay returned raw JSON text instead of structured values, parallel fail-fast skipped stages before async finalizers completed, retry backoff left abort listeners behind after normal sleeps, and durable stage checkpointing could ignore an explicit stage replay key. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed durable replay robustness: child workflow internal `ctx.tool`/`ctx.ui`/`ctx.stage` side effects are now checkpointed under the parent/root durable workflow via a scoped backend keyed by the child boundary, so an interrupted child does not re-execute completed side effects on parent resume (previously child checkpoints were written under a fresh per-run UUID that was never recovered). `/workflow resume` now refuses cache-only entries as `stale` when a workflow has session-JSONL metadata but no durable checkpoint state in the backend, instead of silently re-running from scratch. Durable replay identities (`durableHash`) now use a SHA-256 digest instead of a 32-bit DJB2 hash that could collide across distinct tool/stage identities. `ctx.tool` re-checks cancellation after the tool function resolves and before recording/returning the side-effect result, so a side effect that completes concurrently with cancellation is not persisted as a replayable checkpoint. File-backed durability recovers from a stale lock directory left by a crashed process (backdated beyond a threshold) instead of wedging until the acquire timeout. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed terminal durable cache suppression so stale session-JSONL entries cannot resurrect workflows the backend knows are completed/cancelled/non-resumable: the backend terminal state now takes precedence over older JSONL cache entries during listing and resume. Successful durable `/workflow resume <id>` now connects/opens the overlay to the resumed run, matching live resume ergonomics. No-arg `/workflow resume` now shows a combined selector (live runs + cross-session durable workflows) so durable workflows are directly selectable even when live runs exist, instead of only being printed as hints. Fixed `ScopedDurableBackend.listCheckpoints` to exclude sibling child scopes that shared a common id prefix (previously re-prefixing caused sibling checkpoints to leak into the wrong scope). Cleaned up a cosmetic merged import line in `run.ts`. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed empty string stage outputs to be preserved durably as empty strings instead of being collapsed into status objects, so a stage completing with empty assistant text replays as empty rather than appearing to have no checkpoint. Schema-backed stage prompts with empty string results are now also checkpointed. Stage finalization failures (including durable checkpoint write errors) no longer leak the concurrency limiter/semaphore because each cleanup step is independently guarded. Mixed live+durable `/workflow resume` now uses async DBOS-hydrated durable listing (`prepareDurableResumable`) instead of a synchronous in-memory listing so cross-session entries discovered from Postgres are included in the combined selector. Replayed durable stages now register in the graph frontier tracker so parent/lineage topology is preserved for subsequent stages. Dismissing the combined resume picker returns to chat without opening a second live-only picker. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed Ralph review regressions in durable resume: durable and combined pickers now settle selections before synchronous custom-UI disposal can dismiss them; headless no-arg durable resume prints the catalog instead of awaiting unavailable/no-op picker UI; failed live runs selected from the combined picker resume through the continuation path; durable resume dispatch forwards the interactive/non-interactive command policy; `ctx.ui.custom` replays cached void/`undefined` responses instead of treating them as cache misses; stage finalization errors are rethrown after releasing handles/limiters; and resume integration tests isolate the durable singleton so full integration runs remain deterministic. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+- Fixed default file-backed durability to write one JSON state file per root workflow instead of rewriting a shared `state.json` on every checkpoint, avoid all-files scans on point checkpoint lookups, prune completed/cancelled/non-resumable terminal workflow files while retaining running/paused/recoverable-failed files for crash recovery until resumed or killed, use restrictive `0700` durable directories and `0600` state/lock-owner files, fail closed to in-memory durability when no home directory is available, and reclaim stale locks only when their owner marker belongs to a dead process. Added `ATOMIC_WORKFLOW_DURABLE=0`/`false`/`off`/`memory` as a documented privacy opt-out for plaintext cross-session checkpoint persistence. ([#1498](https://github.com/bastani-inc/atomic/issues/1498))
+
 ## [0.9.3-alpha.1] - 2026-06-25
 
 ### Changed
 
+- Workflow stage sessions are now marked as internal and excluded from the standard Atomic `/resume`, `atomic -r`, and `--continue` history, while remaining fully resumable/inspectable through `/workflow resume`, `/workflow attach`, and the `workflow` tool's `status`/`stages`/`stage`/`resume` actions via the run/stage store and its `sessionFile` links ([#1504](https://github.com/bastani-inc/atomic/issues/1504)).
 - Revised the builtin `goal` worker/continuation prompts and the builtin `ralph` orchestrator prompts to emphasize implementing the requested task through full completion ("do not stop until the objective is complete") instead of preparing a partial implementation for incremental review.
 - Removed model-visible current-iteration/turn/loop information from the builtin `goal`, `ralph`, and `open-claude-design` workflows so models are not biased by which iteration they are on. This drops the worker `Turn: N/M` banner, `Implement iteration N/M` / `Research iteration N/M` framing, "first iteration/worker turn" phrasing, and the live-preview `iteration N/M` label; switches model-relayed artifacts to stable non-ordinal names (`worker-receipt.md`, `review-<reviewer>.json`, `review-round-latest.json`, `orchestrator-report.md`); and strips turn fields from the model-facing goal ledger artifact. Internal UI stage names (e.g. `work-turn-2`, `orchestrator-2`) are unchanged, and the `max_turns`/`max_loops` inputs and `turns_completed`/`iterations_completed` outputs are retained.
 - Raised workflow-stage subagent recursion to the shared five-level nesting budget so workflow stages match main-chat delegation depth.

package/dist/builtin/workflows/README.md

@@ -540,7 +540,7 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 
 Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`). Runtime validation is strict: unknown input keys, missing required values, type mismatches, and invalid `select` choices fail before a named workflow run starts.
 
-Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on the node to answer locally, never as a modal dialog over the chat. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
+Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on a focused node, or click a visible graph node directly, to open that stage and answer locally, never as a modal dialog over the chat. Attached stage chats capture mouse/trackpad wheel events by default so scrolling stays inside the active stage transcript or prompt instead of falling through to terminal/main-chat scrollback. Press `ctrl+t` to toggle **copy mode**: copy mode disables workflow-chat mouse reporting so normal terminal/tmux text selection can work; press `ctrl+t` again to leave copy mode and restore workflow-chat scrolling. While copy mode is on, wheel/trackpad gestures are handled by the terminal/tmux and may scroll terminal scrollback, so leave copy mode before using the wheel again. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
 
 Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. The `workflow` tool's `stages`, `stage`, `transcript`, `send`, `pause`, `interrupt`, and `resume` actions can still target visible child stage ids, prefixes, or names from the expanded graph; Atomic routes the control action to the owning nested run internally. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `kill`, `resume`, `reload`, and `inputs`.)
 

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.3-alpha.1",
+  "version": "0.9.3-alpha.3",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/authoring.d.ts

@@ -1,6 +1,6 @@
 import type { TSchema } from "typebox";
 export type { Static, TSchema } from "typebox";
-export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
+export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSendUserMessageOptions, StageUserMessageContent, StageUserMessageDelivery, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
 import type * as AuthoringContract from "./shared/authoring-contract.js";
 import type { AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./shared/workflow-authoring-types.js";
 export type { WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas, } from "./shared/workflow-authoring-types.js";

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

@@ -0,0 +1,343 @@
+/**
+ * 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.
+ */
+
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import { createHash } from "node:crypto";
+import type {
+  DurableCheckpoint,
+  DurableCheckpointEntry,
+  DurableToolCheckpoint,
+  DurableUiCheckpoint,
+  DurableStageCheckpoint,
+  DurableWorkflowHandle,
+  DurableWorkflowStatus,
+  ResumableWorkflowEntry,
+  WorkflowSerializableObject,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Backend interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Input for registering/updating a workflow in the durable backend.
+ * Optional fields default to existing values or zero.
+ */
+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 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.
+   */
+  readonly persistent: boolean;
+  /** Register or update a workflow's top-level metadata. */
+  registerWorkflow(handle: WorkflowRegistrationInput): void;
+
+  /** 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>;
+
+  /** Optional: wait for serialized durable writes to settle. */
+  flush?(): Promise<void>;
+
+  /**
+   * Look up a cached tool output by content hash. Returns `undefined` if the
+   * tool has not completed. This is how `ctx.tool` avoids re-executing side
+   * effects on resume.
+   */
+  getToolOutput(workflowId: string, argsHash: string): WorkflowSerializableValue | undefined;
+
+  /**
+   * Look up a cached UI response by prompt hash. Returns `undefined` if the
+   * prompt has not been answered. This is how `ctx.ui.*` resumes at pending
+   * prompts instead of re-asking completed ones.
+   */
+  getUiResponse(workflowId: string, promptHash: string): WorkflowSerializableValue | undefined;
+
+  /** Look up a cached stage output by replay key. */
+  getStageOutput(workflowId: string, replayKey: string): WorkflowSerializableValue | undefined;
+
+  /** Look up resumable stage session metadata by replay key, when available. */
+  getStageSession(workflowId: string, replayKey: string): { sessionId?: string; sessionFile?: string } | undefined;
+
+  /** List all checkpoints for a workflow (in completion order). */
+  listCheckpoints(workflowId: string): readonly DurableCheckpoint[];
+
+  /** Get the top-level workflow handle, or `undefined` if not registered. */
+  getWorkflow(workflowId: string): DurableWorkflowHandle | undefined;
+
+  /** Update workflow status (running/paused/completed/failed/cancelled/blocked). */
+  setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean): void;
+
+  /**
+   * List resumable workflows (not completed/cancelled, or explicitly marked
+   * resumable after failure). Used by the `/workflow resume` selector.
+   */
+  listResumableWorkflows(): readonly ResumableWorkflowEntry[];
+
+  /** Export a session-cache entry for the given workflow (for JSONL persistence). */
+  toCacheEntry(workflowId: string): DurableCheckpointEntry | undefined;
+
+  /** 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>;
+}
+
+// ---------------------------------------------------------------------------
+// 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
+// ---------------------------------------------------------------------------
+
+interface InMemoryWorkflowRecord {
+  handle: DurableWorkflowHandle;
+  checkpoints: Map<string, DurableCheckpoint>;
+  toolByHash: Map<string, DurableToolCheckpoint>;
+  uiByHash: Map<string, DurableUiCheckpoint>;
+  stageOutputByReplayKey: Map<string, DurableStageCheckpoint>;
+  stageSessionByReplayKey: Map<string, DurableStageCheckpoint>;
+}
+
+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.
+ */
+export class InMemoryDurableBackend implements DurableWorkflowBackend {
+  public readonly persistent = false;
+  private readonly workflows = new Map<string, InMemoryWorkflowRecord>();
+
+  registerWorkflow(handle: WorkflowRegistrationInput): void {
+    const existing = this.workflows.get(handle.workflowId);
+    const completedCheckpoints = handle.completedCheckpoints ?? existing?.handle.completedCheckpoints ?? 0;
+    const pendingPrompts = handle.pendingPrompts ?? existing?.handle.pendingPrompts ?? 0;
+    const updatedAt = handle.updatedAt ?? Date.now();
+    const full: DurableWorkflowHandle = {
+      workflowId: handle.workflowId,
+      name: handle.name,
+      inputs: handle.inputs,
+      createdAt: handle.createdAt,
+      status: handle.status,
+      ...(handle.sessionFile !== undefined ? { sessionFile: handle.sessionFile } : {}),
+      completedCheckpoints,
+      pendingPrompts,
+      updatedAt,
+      ...(handle.label !== undefined ? { label: handle.label } : {}),
+      ...(handle.rootWorkflowId !== undefined ? { rootWorkflowId: handle.rootWorkflowId } : {}),
+      ...(handle.resumable !== undefined ? { resumable: handle.resumable } : {}),
+    };
+    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() });
+  }
+
+  recordCheckpoint(checkpoint: DurableCheckpoint): void {
+    const rec = this.workflows.get(checkpoint.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);
+    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);
+        }
+      }
+    }
+    rec.handle = { ...rec.handle, completedCheckpoints: rec.checkpoints.size, updatedAt: checkpoint.completedAt };
+  }
+
+  getToolOutput(workflowId: string, argsHash: string): WorkflowSerializableValue | undefined {
+    return this.workflows.get(workflowId)?.toolByHash.get(argsHash)?.output;
+  }
+
+  getUiResponse(workflowId: string, promptHash: string): WorkflowSerializableValue | undefined {
+    return this.workflows.get(workflowId)?.uiByHash.get(promptHash)?.response;
+  }
+
+  getStageOutput(workflowId: string, replayKey: string): WorkflowSerializableValue | undefined {
+    const checkpoint = this.workflows.get(workflowId)?.stageOutputByReplayKey.get(replayKey);
+    return checkpoint !== undefined && "output" in checkpoint ? checkpoint.output : undefined;
+  }
+
+  getStageSession(workflowId: string, replayKey: string): { sessionId?: string; sessionFile?: string } | undefined {
+    const checkpoint = this.workflows.get(workflowId)?.stageSessionByReplayKey.get(replayKey);
+    if (checkpoint?.sessionId === undefined && checkpoint?.sessionFile === undefined) return undefined;
+    return { ...(checkpoint.sessionId !== undefined ? { sessionId: checkpoint.sessionId } : {}), ...(checkpoint.sessionFile !== undefined ? { sessionFile: checkpoint.sessionFile } : {}) };
+  }
+
+  listCheckpoints(workflowId: string): readonly DurableCheckpoint[] {
+    const rec = this.workflows.get(workflowId);
+    if (!rec) return [];
+    return [...rec.checkpoints.values()].sort((a, b) => a.completedAt - b.completedAt);
+  }
+
+  getWorkflow(workflowId: string): DurableWorkflowHandle | undefined {
+    return this.workflows.get(workflowId)?.handle;
+  }
+
+  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 } : {}) };
+  }
+
+  listResumableWorkflows(): readonly ResumableWorkflowEntry[] {
+    return [...this.workflows.values()]
+      .filter((rec) => isRootWorkflow(rec.handle) && isResumableHandle(rec.handle))
+      .map((rec) => toResumableEntry(rec.handle));
+  }
+
+  toCacheEntry(workflowId: string): DurableCheckpointEntry | undefined {
+    const rec = this.workflows.get(workflowId);
+    if (!rec) return undefined;
+    const h = rec.handle;
+    return {
+      type: "workflow.durable.checkpoint",
+      workflowId: h.workflowId,
+      name: h.name,
+      inputs: h.inputs,
+      status: h.status,
+      completedCheckpoints: h.completedCheckpoints,
+      pendingPrompts: h.pendingPrompts,
+      ...(h.label !== undefined ? { label: h.label } : {}),
+      ...(h.rootWorkflowId !== undefined ? { rootWorkflowId: h.rootWorkflowId } : {}),
+      ...(h.resumable !== undefined ? { resumable: h.resumable } : {}),
+      ts: h.updatedAt,
+    };
+  }
+
+  reset(): void {
+    this.workflows.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 {
+  return handle.rootWorkflowId === undefined || handle.rootWorkflowId === handle.workflowId;
+}
+
+function hasResumeProgress(handle: DurableWorkflowHandle): boolean {
+  return handle.completedCheckpoints > 0 || handle.pendingPrompts > 0;
+}
+
+function isResumableHandle(handle: DurableWorkflowHandle): boolean {
+  if (handle.status === "failed" || handle.status === "blocked") return handle.resumable !== false;
+  // `running`/`paused` are both resumable at the backend level: a `running`
+  // durable handle may belong to a crashed process (no live executor), which
+  // is exactly the cross-session crash-recovery case. Same-session
+  // double-resume is prevented by the command layer, which hides durable
+  // entries that match an active live run.
+  return (handle.status === "running" || handle.status === "paused") && hasResumeProgress(handle);
+}
+
+function toResumableEntry(handle: DurableWorkflowHandle): ResumableWorkflowEntry {
+  return {
+    workflowId: handle.workflowId,
+    name: handle.name,
+    inputs: handle.inputs,
+    status: handle.status,
+    completedCheckpoints: handle.completedCheckpoints,
+    pendingPrompts: handle.pendingPrompts,
+    ...(handle.sessionFile !== undefined ? { sessionFile: handle.sessionFile } : {}),
+    ...(handle.label !== undefined ? { label: handle.label } : {}),
+    ...(handle.rootWorkflowId !== undefined ? { rootWorkflowId: handle.rootWorkflowId } : {}),
+    ...(handle.resumable !== undefined ? { resumable: handle.resumable } : {}),
+    createdAt: handle.createdAt,
+    updatedAt: handle.updatedAt,
+  };
+}

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

@@ -0,0 +1,79 @@
+import type {
+  WorkflowChildResult,
+  WorkflowDefinition,
+  WorkflowInputValues,
+  WorkflowOutputValues,
+  WorkflowRunChildArgs,
+  WorkflowSerializableValue,
+} from "../shared/types.js";
+import { isWorkflowDefinition, workflowDefinitionRequirementMessage } from "../runs/foreground/executor-child-helpers.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import type { DurableScope } from "./scoped-backend.js";
+import { recordCheckpointDurably } from "./tool-primitive.js";
+
+export function createDurableChildWorkflowPrimitive(input: {
+  readonly workflowId: string;
+  readonly rootWorkflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  readonly nextReplayKey: (name: string) => string;
+  readonly recordCachedStage: (name: string, replayKey: string, output: WorkflowSerializableValue) => void;
+  /**
+   * Publish the durable scope computed for the next child invocation so the
+   * child runner can consume it and route its internal side-effect checkpoints
+   * under the root workflow. Avoids re-deriving the ordinal independently.
+   */
+  readonly setChildDurableScope: (scope: DurableScope) => void;
+  readonly workflow: <
+    TChildInputs extends WorkflowInputValues,
+    TChildOutputs extends WorkflowOutputValues,
+    TChildRunInputs extends WorkflowInputValues = TChildInputs,
+  >(
+    child: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
+    ...args: WorkflowRunChildArgs<TChildRunInputs>
+  ) => Promise<WorkflowChildResult<TChildOutputs>>;
+}) {
+  return async <
+    TChildInputs extends WorkflowInputValues,
+    TChildOutputs extends WorkflowOutputValues,
+    TChildRunInputs extends WorkflowInputValues = TChildInputs,
+  >(
+    child: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
+    ...args: WorkflowRunChildArgs<TChildRunInputs>
+  ): Promise<WorkflowChildResult<TChildOutputs>> => {
+    if (!isWorkflowDefinition(child)) throw new Error(workflowDefinitionRequirementMessage("ctx.workflow(definition)", child));
+    const options = args[0] as { readonly stageName?: string } | undefined;
+    const boundaryName = options?.stageName ?? `workflow:${child.normalizedName}`;
+    const replayKey = input.nextReplayKey(boundaryName);
+    // Route this child's internal side-effect checkpoints under the root
+    // workflow with a stable boundary key, so an interrupted child does not
+    // re-execute completed side effects on parent resume.
+    // cross-ref: issue #1498.
+    input.setChildDurableScope({ rootWorkflowId: input.rootWorkflowId, scopePrefix: replayKey });
+    const cached = input.backend.getStageOutput(input.workflowId, replayKey);
+    if (cached !== undefined && isWorkflowChildResult(cached)) {
+      input.recordCachedStage(boundaryName, replayKey, cached);
+      return cached as WorkflowChildResult<TChildOutputs>;
+    }
+    const result = await input.workflow(child, ...args);
+    await recordCheckpointDurably(input.backend, {
+      kind: "stage",
+      workflowId: input.workflowId,
+      checkpointId: `workflow:${replayKey}`,
+      name: boundaryName,
+      replayKey,
+      output: result as WorkflowSerializableValue,
+      completedAt: Date.now(),
+    });
+    return result as WorkflowChildResult<TChildOutputs>;
+  };
+}
+
+function isWorkflowChildResult(value: WorkflowSerializableValue): value is WorkflowChildResult<WorkflowOutputValues> {
+  return typeof value === "object"
+    && value !== null
+    && !Array.isArray(value)
+    && typeof (value as { readonly workflow?: WorkflowSerializableValue }).workflow === "string"
+    && typeof (value as { readonly runId?: WorkflowSerializableValue }).runId === "string"
+    && typeof (value as { readonly status?: WorkflowSerializableValue }).status === "string"
+    && typeof (value as { readonly outputs?: WorkflowSerializableValue }).outputs === "object";
+}