workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/cookbook/integrations/sandbox.mdx

@@ -1,8 +1,8 @@
 ---
 title: Sandbox
-description: Model one Vercel Sandbox per workflow run — durable, idle-efficient, and not bound by the 5-hour sandbox hard cap.
+description: Model one Vercel Sandbox per workflow run, durable, idle-efficient, and not bound by the 5-hour sandbox hard cap.
 type: guide
-summary: Own a sandbox for the lifetime of a workflow run. Hibernate on idle via snapshot(), proactively refresh before the sandbox hard cap, and reconnect by runId — so one logical session can run effectively forever.
+summary: Own a sandbox for the lifetime of a workflow run. Hibernate on idle via snapshot(), proactively refresh before the sandbox hard cap, and reconnect by `runId`, so one logical session can run effectively forever.
 related:
   - /docs/ai/defining-tools
   - /docs/foundations/errors-and-retries
@@ -10,30 +10,38 @@ related:
   - /docs/cookbook/agent-patterns/durable-agent
 ---
 
-[Vercel Sandbox](https://vercel.com/docs/sandbox) provides isolated code execution environments. The `@vercel/sandbox` package has first-class support for the Workflow SDK — the `Sandbox` class is serializable, and its methods (`create`, `runCommand`, `stop`, `snapshot`) implicitly run as steps. You can use `Sandbox` directly inside a workflow function without wrapping each call in a separate `"use step"` function.
+<CopyPrompt
+  text="Implement a durable Vercel Sandbox-backed coding-agent workflow. Install the Sandbox package used by this project and `workflow`. Create an exported workflow function with &quot;use workflow&quot; that owns the agent session. Put sandbox creation, command execution, snapshot, refresh, and cleanup into helper functions with &quot;use step&quot;. Persist the sandbox ID, snapshot ID, and workflow run ID in the project data store so clients can reconnect. Use `getWritable()` from `workflow` to stream agent progress and command output. Use `sleep()` to hibernate, refresh, or enforce idle timeouts. Add API routes to start a session, reconnect by run ID, and stop/cleanup. Verify first run, reconnect after reload, snapshot restore, timeout, and cleanup behavior."
+/>
+
+[Vercel Sandbox](https://vercel.com/docs/sandbox) provides isolated code execution environments. The `@vercel/sandbox` package has first-class support for the Workflow SDK: the `Sandbox` class is serializable, and its methods (`create`, `runCommand`, `stop`, `snapshot`) implicitly run as steps. You can use `Sandbox` directly inside a workflow function without wrapping each call in a separate `"use step"` function.
 
 ## Why Workflow + Sandbox
 
-A sandbox alone gets you an isolated VM. A workflow around it gets you a **durable controller** for that VM's entire lifetime:
+A sandbox alone provides an isolated virtual machine (VM). A workflow provides a **durable controller** for that VM's entire lifetime:
 
 - **One workflow run = one sandbox session.** The `runId` is the only state you need to persist on the client. Close the tab, come back a week later, POST the same `runId` and you're back in the same session.
-- **Efficient resource use.** Active sandboxes cost money; hibernated workflows cost nothing. The workflow races a command hook against a `sleep()` timer — when idle, it calls `sandbox.snapshot()` (which also stops the VM) and waits indefinitely. Next command → spin a new sandbox from the snapshot with filesystem, installed packages, and git history intact.
-- **Beyond the 5-hour hard cap.** Every Vercel Sandbox has a maximum lifetime. The workflow tracks that deadline and proactively snapshots + recreates *before* the cap, so the logical session outlives any one VM. Effectively unbounded session duration on top of time-bounded infrastructure.
+- **Efficient resource use.** Active sandboxes cost money; hibernated workflows cost nothing. The workflow races a command hook against a `sleep()` timer. When idle, it calls `sandbox.snapshot()` (which also stops the VM) and waits indefinitely. When the next command arrives, the workflow starts a new sandbox from the snapshot with the filesystem, installed packages, and git history intact.
+- **Beyond the 5-hour hard cap.** Every Vercel Sandbox has a maximum lifetime. The workflow tracks that deadline and proactively creates a snapshot and replacement before the cap, so the logical session outlives any one VM. This provides an effectively unbounded session on time-bounded infrastructure.
 - **Automatic cleanup.** `try/finally` in the workflow guarantees the VM is stopped on failure or destroy.
 
-## Use Case: Coding Agents
+<Callout type="info">
+An effectively unbounded sandbox session is still one workflow run, so it stays on the deployment that started it. If the controller or agent code should upgrade over time, use an explicit version boundary and pass the serialized state or stream handles forward. See [Versioning](/docs/foundations/versioning).
+</Callout>
+
+## Use case: coding agents
 
-This is the pattern [Open Agents](https://open-agents.dev/) uses to spawn coding agents that run "infinitely in the cloud." Each agent session gets its own sandbox — full filesystem, network, and runtime access — and the durable workflow keeps the agent loop resumable across restarts, auto-hibernates when the user walks away, and reconnects instantly when they return.
+This is the pattern [Open Agents](https://open-agents.dev/) uses to spawn coding agents that run "infinitely in the cloud." Each agent session gets its own sandbox (full filesystem, network, and runtime access), and the durable workflow keeps the agent loop resumable across restarts, auto-hibernates when the user walks away, and reconnects instantly when they return.
 
 Most coding-agent workloads look like this:
 
-- User sends a task → agent plans, reads files, runs shell commands, commits.
-- User walks away mid-run → agent keeps going, eventually goes idle waiting for input.
-- User comes back days later → same branch, same filesystem, same conversation history.
+- The user sends a task, and the agent plans, reads files, runs shell commands, and commits.
+- If the user leaves mid-run, the agent continues and eventually waits for input.
+- When the user returns, the same branch, filesystem, and conversation history remain available.
 
-Without durable workflows you'd need a separate state store for the agent loop, a separate job queue for retries, a separate scheduler for idle cleanup, and bespoke reconnection logic. With the pattern below, all of it is one file.
+Without durable workflows, you'd need a separate state store for the agent loop, a job queue for retries, a scheduler for idle cleanup, and custom reconnection logic. The pattern below keeps the workflow controller in one file.
 
-## Quickstart: One-shot Pipeline
+## Quickstart: one-shot pipeline
 
 Before the full session pattern, the simplest shape. Each sandbox method is an implicit step, so the event log records every command and the workflow replays from the last completed call on restart.
 
@@ -66,17 +74,17 @@ export async function sandboxPipeline(input: { commands: string[] }) {
 }
 ```
 
-## Session Pattern: Persistent Sandbox Beyond the Hard Cap
+## Session pattern: persistent sandbox beyond the hard cap
 
 One workflow run owns a sandbox for its whole lifetime. The workflow's loop does two jobs simultaneously:
 
-1. **Command pipeline** — await a hook, run the next user command, stream output, loop.
-2. **Sandbox lifecycle** — race the hook against a `sleep()` timer armed for whichever comes first: the idle deadline or the sandbox's refresh deadline (a safety margin before its hard cap).
+1. **Command pipeline**: await a hook, run the next user command, stream output, loop.
+2. **Sandbox lifecycle**: race the hook against a `sleep()` timer armed for whichever comes first: the idle deadline or the sandbox's refresh deadline (a safety margin before its hard cap).
 
 When the timer wins:
 
-- **Idle** → `sandbox.snapshot()` and wait indefinitely for the next command. No compute while asleep.
-- **Near sandbox hard cap** → `sandbox.snapshot()` and immediately create a new sandbox from the snapshot. The session appears continuous; the underlying VM just rotated.
+- **Idle**: Call `sandbox.snapshot()` and wait indefinitely for the next command. The workflow uses no compute while suspended.
+- **Near the sandbox hard cap**: Call `sandbox.snapshot()` and immediately create a new sandbox from the snapshot. The session remains continuous while the underlying VM rotates.
 
 The only way out is an explicit `/destroy` command.
 
@@ -162,7 +170,7 @@ export async function sandboxSessionWorkflow() {
   "use workflow";
 
   const { workflowRunId } = getWorkflowMetadata();
-  // Create the hook once, outside the loop — reusing the same token from inside // [!code highlight]
+  // Create the hook once, outside the loop: reusing the same token from inside // [!code highlight]
   // the loop would throw HookConflictError. // [!code highlight]
   const hook = commandHook.create({ token: workflowRunId });
 
@@ -197,8 +205,8 @@ export async function sandboxSessionWorkflow() {
   try {
     while (!destroyed) {
       if (hibernated && snapshot) {
-        // While hibernated, the VM is already stopped. Just wait for the next
-        // command — no idle timer, no compute cost.
+        // While hibernated, the VM is already stopped. Wait for the next
+        // command: no idle timer, no compute cost.
         const payload = await hook;
         if (payload.command === "/destroy") { destroyed = true; break; }
 
@@ -223,7 +231,7 @@ export async function sandboxSessionWorkflow() {
         continue;
       }
 
-      // Active — wake at whichever comes first: idle-deadline or refresh-deadline.
+      // Active. Wake at whichever comes first: idle-deadline or refresh-deadline.
       const idleDeadline = lastActivityAt + HIBERNATE_AFTER_MS;
       const refreshDeadline = sandboxExpiresAt - REFRESH_SAFETY_MS;
       const wakeAt = Math.min(idleDeadline, refreshDeadline);
@@ -238,7 +246,7 @@ export async function sandboxSessionWorkflow() {
         const nearExpiry = Date.now() >= refreshDeadline;
 
         if (nearExpiry) {
-          // Proactive refresh — snapshot and immediately recreate so the
+          // Proactive refresh: snapshot and immediately recreate so the
           // session outlives the sandbox hard cap.
           await emit({ type: "status", state: "refreshing", at: Date.now() });
           const snap = await sandbox.snapshot(); // [!code highlight]
@@ -255,7 +263,7 @@ export async function sandboxSessionWorkflow() {
           });
           lastActivityAt = Date.now();
         } else {
-          // Idle — snapshot and hibernate indefinitely.
+          // Idle: snapshot and hibernate indefinitely.
           await emit({ type: "status", state: "hibernating", at: Date.now() });
           snapshot = await sandbox.snapshot(); // [!code highlight]
           hibernated = true;
@@ -294,7 +302,11 @@ export async function sandboxSessionWorkflow() {
 
 <Tab value="API Routes">
 
-Two endpoints. `/start` accepts an optional `{ runId }` — if the run still exists, it replays the event log from index 0 so a returning client fully rehydrates. `/command` resumes the hook and returns immediately; command output lands on the `/start` stream.
+Two endpoints manage the session. `/start` accepts an optional `{ runId }`: if the run still exists, it replays the event log from index 0 so a returning client fully rehydrates. `/command` resumes the hook and returns immediately; command output lands on the `/start` stream.
+
+<Callout type="info">
+This example starts a fresh sandbox session when no `runId` is provided. If your product needs one sandbox session per user, project, or task, use a deterministic hook token derived from that session key and route retries through the active hook. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
 
 ```typescript title="app/api/sandbox/start/route.ts" lineNumbers
 import { start, getRun } from "workflow/api";
@@ -322,7 +334,7 @@ export async function POST(req: Request) {
         },
       });
     }
-    // Stale runId — fall through to start fresh.
+    // Stale runId: fall through to start fresh.
   }
 
   const run = await start(sandboxSessionWorkflow, []);
@@ -371,7 +383,7 @@ export async function POST(req: Request) {
 
 <Tab value="Client">
 
-On mount, if a `runId` is stashed in `localStorage`, reconnect to the existing run. Otherwise start fresh. Commands are POSTed to `/command` — output lands on the `/start` stream.
+On mount, reconnect to the existing run if `localStorage` contains a `runId`. Otherwise, start a new run. Send commands to `/command` with POST requests. Output arrives on the `/start` stream.
 
 ```tsx title="components/sandbox-runner.tsx" lineNumbers
 "use client";
@@ -464,22 +476,22 @@ export function SandboxRunner() {
 
 </Tabs>
 
-## How It Works
+## How it works
 
-1. **One workflow = one session.** The workflow owns a sandbox for its entire lifetime. The `runId` is the only state the client has to remember.
-2. **Hook created once.** `commandHook.create({ token: workflowRunId })` outside the loop. Creating it twice with the same token throws `HookConflictError`.
-3. **Two timer branches.** The active-state race wakes on the earlier of `idleDeadline` and `refreshDeadline`. The hibernated state awaits the hook alone — no timer, no compute.
-4. **Proactive refresh.** `refreshDeadline = sandboxExpiresAt - REFRESH_SAFETY_MS`. Hitting this triggers a snapshot + immediate new sandbox from that snapshot, rolling over the hard cap without user intervention.
-5. **`sandbox.snapshot()` stops the VM.** It's documented as part of the snapshot process — don't call `stop()` separately.
-6. **Resume = new sandbox.** `Sandbox.create({ source: { type: "snapshot", snapshotId } })` creates a fresh VM from the snapshot. The new sandbox has a different `sandboxId`; filesystem, installed packages, and git history are preserved.
-7. **Reconnect by runId.** `getRun(runId).getReadable({ startIndex: 0 })` replays the durable event log to a returning client, who rebuilds UI state from the replay.
-8. **Exit only on `/destroy`.** The workflow loop has no hard deadline of its own. Individual sandboxes time out; the session doesn't.
+1. **One workflow represents one session**: The workflow owns a sandbox for its entire lifetime. The `runId` is the only state the client has to remember.
+2. **Create the hook once**: Call `commandHook.create({ token: workflowRunId })` outside the loop. Creating it twice with the same token throws `HookConflictError`.
+3. **Two timer branches control wake-up**: The active-state race wakes on the earlier of `idleDeadline` and `refreshDeadline`. The hibernated state awaits the hook alone, with no timer or compute.
+4. **Proactive refresh replaces the sandbox**: When `refreshDeadline = sandboxExpiresAt - REFRESH_SAFETY_MS` arrives, the workflow takes a snapshot and immediately creates a new sandbox from it. This rolls over the hard cap without user intervention.
+5. **`sandbox.snapshot()` stops the VM**: The snapshot process stops the VM, so don't call `stop()` separately.
+6. **Resume creates a new sandbox**: `Sandbox.create({ source: { type: "snapshot", snapshotId } })` creates a new VM from the snapshot. The new sandbox has a different `sandboxId`; the filesystem, installed packages, and git history are preserved.
+7. **Reconnect by `runId`**: `getRun(runId).getReadable({ startIndex: 0 })` replays the durable event log to a returning client, which rebuilds UI state from the replay.
+8. **Exit only on `/destroy`**: The workflow loop has no hard deadline of its own. Individual sandboxes time out, but the session doesn't.
 
 ## Pitfalls
 
 ### `sandbox.stop()` is terminal
 
-A stopped sandbox cannot be restarted — you have to create a new one. Hibernation is only possible via `snapshot()` + new-sandbox-from-snapshot. Don't try to "pause" an active sandbox with `stop()` and resume later.
+A stopped sandbox cannot be restarted: you have to create a new one. Hibernation is only possible via `snapshot()` + new-sandbox-from-snapshot. Don't try to "pause" an active sandbox with `stop()` and resume later.
 
 ### `snapshot()` already stops the VM
 
@@ -491,7 +503,7 @@ Both `resuming` (idle → command) and `refreshing` (near-hard-cap rotation) cre
 
 ### Keep the refresh margin generous
 
-`snapshot()` + `Sandbox.create({ source })` takes real time (typically tens of seconds). If `REFRESH_SAFETY_MS` is too small, the old sandbox hits its hard cap mid-snapshot. Leave at least 60–90 seconds; 5 minutes is comfortable.
+`snapshot()` followed by `Sandbox.create({ source })` takes time, typically tens of seconds. If `REFRESH_SAFETY_MS` is too small, the old sandbox hits its hard cap mid-snapshot. Leave at least 60–90 seconds; the example uses 5 minutes.
 
 ### Don't call `writable.close()` inside a workflow function
 
@@ -501,16 +513,21 @@ Stream closure must happen inside a `"use step"` function. Calling `writable.clo
 
 Clients can hold `runId`s from long-gone workflow runs (localStorage, back button, server restart). Gate the reconnect path on `run.exists` and fall through to starting fresh. On `hook.resume`, catch `not found` / `expired` and return 410 so the client clears its state.
 
+### Decide whether `/start` should be idempotent
+
+The sample treats a missing or stale `runId` as a request for a new session. For one-session-per-resource behavior, use a durable resource key, such as `projectId` or `taskId`, to claim or retrieve the run before starting a new one.
+
 ### Keep the hook outside the loop
 
 Each iteration's `hook.then(...)` attaches a listener to the same hook instance. Creating a new hook per iteration with the same token throws `HookConflictError`. One hook, one token (`workflowRunId`), reused every iteration.
 
 ## Key APIs
 
-- [`Sandbox.create`](https://vercel.com/docs/sandbox) — provision a VM (runtime, source, timeout)
-- [`sandbox.runCommand`](https://vercel.com/docs/sandbox) — execute a command; implicit step
-- [`sandbox.snapshot`](https://vercel.com/docs/sandbox) — save state and stop the VM; returns `Snapshot`
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — suspension point for user commands
-- [`sleep()`](/docs/api-reference/workflow/sleep) — durable timer that powers both idle hibernation and proactive refresh
-- [`getRun()`](/docs/api-reference/workflow-api/get-run) — look up a run and replay its event log for reconnection
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — resumable NDJSON event stream
+- [`Sandbox.create`](https://vercel.com/docs/sandbox): provision a VM (runtime, source, timeout)
+- [`sandbox.runCommand`](https://vercel.com/docs/sandbox): execute a command; implicit step
+- [`sandbox.snapshot`](https://vercel.com/docs/sandbox): save state and stop the VM; returns `Snapshot`
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): suspension point for user commands
+- [`sleep()`](/docs/api-reference/workflow/sleep): durable timer that powers both idle hibernation and proactive refresh
+- [`getRun()`](/docs/api-reference/workflow-api/get-run): look up a run and replay its event log for reconnection
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): resumable newline-delimited JSON (NDJSON) event stream
+- [Idempotency](/docs/foundations/idempotency): choose when `/start` should reuse an existing run

package/docs/deploying.mdx

@@ -0,0 +1,95 @@
+---
+title: Deploying
+description: Deploy workflows locally, on Vercel, or anywhere using pluggable World adapters.
+type: overview
+summary: Learn how to deploy workflows to different environments using World adapters.
+related:
+  - /worlds/local
+  - /worlds/postgres
+  - /worlds/vercel
+  - /worlds/building-a-world
+---
+
+The same workflow code can run locally during development, on Vercel with zero configuration, or on any infrastructure using **Worlds**, which are pluggable adapters that handle storage, queuing, and communication.
+
+## Local development
+
+During local development, workflows use the **Local World** without configuration. The Local World stores workflow data in a `.workflow-data/` directory and processes steps synchronously for development and testing.
+
+```bash
+# Run your dev server to use workflows locally
+npm run dev
+```
+
+You can inspect local workflow data using the CLI:
+
+```bash
+npx workflow inspect runs
+```
+
+<Callout>
+  Learn more about the [Local World](/worlds/local) configuration and internals.
+</Callout>
+
+## Deploying to Vercel
+
+Deploy workflows to production on Vercel without configuration. Workflows deployed to Vercel use the **Vercel World**.
+
+The Vercel World provides:
+
+- **Durable storage**: Workflow state persists across function invocations
+- **Managed queuing**: The queue processes steps reliably with automatic retries
+- **Automatic scaling**: Workflows scale with your application
+- **Built-in observability**: View workflow runs in the Vercel dashboard
+- **Multi-region**: The region that creates each run also hosts its workflow data, queue, and streams, keeping them close to your users
+
+Deploy your application:
+
+```bash
+vercel deploy
+```
+
+<FluidComputeCallout />
+
+<Callout>
+  Learn more about the [Vercel World](/worlds/vercel) and its capabilities, including [multi-region](/worlds/vercel#multi-region).
+</Callout>
+
+## Self-hosting & other providers
+
+For self-hosting or deploying to other cloud providers, you can use community-maintained Worlds or build your own.
+
+<Cards>
+  <Card title="Explore Worlds" href="/worlds">
+    Browse official and community World implementations with compatibility status and performance benchmarks.
+  </Card>
+  <Card title="Build Your Own" href="/worlds/building-a-world">
+    Learn how to implement a custom World for your infrastructure.
+  </Card>
+</Cards>
+
+### Using a third-party World
+
+To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable:
+
+```bash
+export WORKFLOW_TARGET_WORLD=@workflow/world-postgres
+# Plus any world-specific configuration
+export DATABASE_URL=postgres://...
+```
+
+Each World may have its own configuration requirements. Refer to that World's documentation for details.
+
+## Observability
+
+The [Observability tools](/docs/observability) work with any World backend. By default, they connect to your local environment, but you can configure them to inspect remote deployments:
+
+```bash
+# Inspect local workflows
+npx workflow inspect runs
+
+# Inspect remote workflows
+npx workflow inspect runs --backend @workflow/world-postgres
+```
+
+Learn more about [Observability](/docs/observability) tools.

package/docs/errors/abort-signal-timeout-in-workflow.mdx

@@ -11,23 +11,27 @@ related:
   - /docs/errors/timeout-in-workflow
 ---
 
+<CopyPrompt
+  text="Replace `AbortSignal.timeout()` inside workflow functions. Find the failing `AbortSignal.timeout(ms)` call in a `&quot;use workflow&quot;` function. Import `sleep` from `workflow`. Create `const controller = new AbortController()`, pass `controller.signal` into the async work that supports cancellation, and start a deterministic timeout with `void sleep(&quot;10s&quot;).then(() => controller.abort())` or a `Promise.race` between the work and `sleep(...)`. Keep actual fetch/SDK side effects inside `&quot;use step&quot;` helpers when they need Node.js APIs. Treat intentional aborts as non-retryable if appropriate by throwing `FatalError`. Verify the operation succeeds before the timeout, aborts after the timeout, and replays without abort-signal-timeout-in-workflow."
+/>
+
 ## Error
 
-```
+```text
 AbortSignal.timeout() is not supported in workflow functions.
 Use sleep() with an AbortController instead.
 ```
 
-## Why This Happens
+## Why this happens
 
-`AbortSignal.timeout()` creates a signal that aborts after a real-time delay using an internal timer. Workflow functions must be [deterministic](/docs/foundations/workflows-and-steps) to support replay — they run the same code multiple times during the workflow's lifecycle, using the [event log](/docs/how-it-works/event-sourcing) to resume execution to the correct point.
+`AbortSignal.timeout()` creates a signal that aborts after a real-time delay using an internal timer. Workflow functions must be [deterministic](/docs/foundations/workflows-and-steps) to support replay: they run the same code multiple times during the workflow's lifecycle, using the [event log](/docs/how-it-works/event-sourcing) to resume execution to the correct point.
 
 Real-time timers break this determinism because:
-- On the first execution, the timer might fire after 10 seconds
-- On replay, the timer would fire again, but the event log may have already advanced past that point
-- The timer's behavior depends on wall-clock time, which varies between executions
+- On the first execution, the timer might fire after 10 seconds.
+- On replay, the timer would fire again, but the event log may have already advanced past that point.
+- The timer's behavior depends on wall-clock time, which varies between executions.
 
-## How to Fix
+## How to fix
 
 Use [`sleep()`](/docs/api-reference/workflow/sleep) with an `AbortController` to create a deterministic timeout that cancels in-flight work:
 
@@ -66,7 +70,7 @@ async function fetchData(signal: AbortSignal) {
 }
 ```
 
-The `sleep()` + `AbortController` pattern is the durable equivalent of `AbortSignal.timeout()`. The sleep is recorded in the event log, so it replays deterministically. If `fetchData` finishes within 10 seconds you get the response; if not, the timer fires `controller.abort()`, `fetch` rejects with an `AbortError`, and the step's failure propagates to the workflow as a `FatalError` (no retries — abort is intentional cancellation).
+The `sleep()` and `AbortController` pattern is the durable equivalent of `AbortSignal.timeout()`. The sleep is recorded in the event log, so it replays deterministically. If `fetchData` finishes within 10 seconds, you get the response. Otherwise, the timer calls `controller.abort()`, `fetch` rejects with an `AbortError`, and the step's failure propagates to the workflow as a `FatalError` (no retries because the abort is intentional cancellation).
 
 <Callout type="info">
 `AbortSignal.timeout()` works normally inside step functions, since steps have full Node.js runtime access and are not replayed.
@@ -74,7 +78,7 @@ The `sleep()` + `AbortController` pattern is the durable equivalent of `AbortSig
 
 ## Related
 
-- [Cancellation](/docs/foundations/cancellation) — Patterns for cancelling in-flight work
-- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) — Durable sleep primitive
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Why workflow functions must be deterministic
-- [`setTimeout` in Workflow](/docs/errors/timeout-in-workflow) — Similar restriction on `setTimeout`
+- [Cancellation](/docs/foundations/cancellation): Patterns for canceling in-flight work
+- [`sleep()` API Reference](/docs/api-reference/workflow/sleep): Durable sleep primitive
+- [Workflows and Steps](/docs/foundations/workflows-and-steps): Why workflow functions must be deterministic
+- [`setTimeout` in Workflow](/docs/errors/timeout-in-workflow): Similar restriction on `setTimeout`

package/docs/errors/corrupted-event-log.mdx

@@ -1,39 +1,50 @@
 ---
 title: corrupted-event-log
-description: The workflow's event log contains an event that no consumer can process, indicating corruption or invalid state.
+description: The workflow's event log contains an event that cannot be processed or a stored payload that cannot be read.
 type: troubleshooting
-summary: Resolve corrupted event log errors caused by duplicate or orphaned events.
+summary: Resolve corrupted event log errors caused by invalid events or unreadable stored payloads.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/foundations/errors-and-retries
 ---
 
-This error occurs when the Workflow runtime encounters an event in the event log that no registered consumer can process. This means the event log is in an invalid state — typically due to duplicate or orphaned events.
+This error occurs when the Workflow runtime cannot safely replay the event log. The log may be in an invalid state, such as an orphaned event or one no consumer can attribute to anything the workflow did, or it may reference a stored payload that the World can no longer read.
 
-This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. A corrupted event log immediately fails the entire run without executing any more user code. The run must be retried from outside the workflow.
+This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. The runtime retries transient replay divergence automatically, but an unreadable stored payload is terminal immediately because replaying cannot restore it.
 
-## Error Message
+## Error message
 
+For replay divergence:
+
+```text
+Workflow replay diverged <divergenceCount> times after <maxRecoveryReplays> recovery replays; latest divergent event was <eventId>. Last divergence: <details>
 ```
-Unconsumed event in event log: eventType=<type>, correlationId=<id>, eventId=<id>. This indicates a corrupted or invalid event log.
+
+For an unreadable stored payload:
+
+```text
+the event log references a payload that no longer exists in storage: <details>
 ```
 
-## Why This Happens
+## Why this happens
+
+Workflows persist their progress as an ordered event log. During replay, the runtime processes each event in sequence. Every event must be consumed by a matching callback, such as a step or sleep waiting for its result. An event no callback ever claims is one the runtime would have to drop to finish the run, so it fails the run instead of returning a result that silently ignored it.
 
-Workflows persist their progress as an ordered event log. During replay, the runtime processes each event in sequence — every event must be consumed by a matching callback (e.g., a step or sleep waiting for its result). When an event has no matching consumer, the runtime cannot advance past it, which would block all subsequent events and hang the workflow indefinitely.
+A delivery written from outside the replay, such as a hook firing or a step completing on another invocation, can land ahead of the events the replay is writing itself. That is ordinary concurrency rather than corruption, so the runtime holds such an event and offers it to each consumer the replay registers afterwards. The failure comes only when the workflow function returns while an event is still held, at which point no consumer can ever appear. A replay that suspends still holding one reports it on the span (`workflow.events.parked.count`, `.event_id`, `.event_type`) and leaves the decision to the replay that follows.
 
-Instead of silently hanging, the runtime raises a `WorkflowRuntimeError` to fail the workflow fast and surface the problem.
+Before failing on divergence, the runtime retries the replay and surfaces this terminal error only if replay still cannot recover. It does not retry a payload that the World reports as permanently missing.
 
 Common scenarios that produce this error:
 
-1. **Duplicate completion events** — Two `wait_completed` events for a single `wait_created`, or two `step_completed` events for the same step. The first is consumed normally, but the second has no consumer.
-2. **Orphaned events** — A `step_completed` or `wait_completed` event whose `correlationId` doesn't match any step or sleep in the workflow code.
-3. **Events after terminal state** — An event that arrives after its corresponding step or wait has already reached a terminal state (e.g., `step_retrying` after `step_completed`).
+- **An unclaimed event that repeats nothing**: A duplicate of a kind the log already records for that entity is read past rather than failing the run, so a second `step_completed` or `wait_completed` is not this error (see [Duplicate Events](/docs/how-it-works/event-sourcing#duplicate-events)). What fails is an unclaimed event with no earlier counterpart to defer to: a `step_started` behind a `step_completed` on a log that never recorded a `step_started`, for instance. No consumer remains for the step, and there is no earlier event of that kind the replay could be reading instead.
+- **Orphaned events**: A `step_completed` or `wait_completed` event whose `correlationId` doesn't match any step or sleep in the workflow code, so the replay reaches its end still holding it.
+- **A hole in the log**: Events are numbered by their position in the run's log, and those positions are dense, so a position below the log's highest that holds no event means the log the replay loaded is incomplete. The runtime cannot tell a position no write ever occupied from one whose event it failed to read, so it refuses to replay rather than produce a result that may be silently wrong. See [`WORKFLOW_SLOT_GAP_CHECK`](/docs/configuration/runtime-tuning#workflow_slot_gap_check).
+- **An unreadable stored payload**: An event row still references a payload object, but the World reports that the object no longer exists in its storage. The same log would fail on every replay, so the run fails immediately instead of retrying forever.
 
-## What To Do
+## What to do
 
-This error indicates a bug in the Workflow SDK or Workflow server — not in your workflow code. Your workflow code does not need to change. Follow these steps to resolve the issue:
+This error indicates a bug in the Workflow SDK or Workflow server, not in your workflow code. Your workflow code does not need to change. Follow these steps to resolve the issue:
 
 ### 1. Upgrade to the latest `workflow` package
 
@@ -45,18 +56,18 @@ npm install workflow@latest
 
 ### 2. Retry the failed run
 
-Since this is a fatal error, the run is automatically marked as `failed`. You can re-run it using the **Re-run** button in the Workflow Dashboard.
+If this error reports replay divergence, automatic replay recovery has already been exhausted. If it reports an unreadable payload, recovery cannot recreate that payload. In either case, the run has been marked as `failed`. You can re-run the workflow using the **Re-run** button in the Workflow Dashboard; a re-run starts a new run with a new event log.
 
 ### 3. Report the issue
 
-If the error persists after upgrading, please [open an issue on GitHub](https://github.com/vercel/workflow/issues/new) so we can investigate and fix the underlying bug. Include the following details to help us diagnose the problem:
+If the error persists after upgrading, [open an issue on GitHub](https://github.com/vercel/workflow/issues/new) so we can investigate and fix the underlying bug. Include the following details to help us diagnose the problem:
 
 - The version of the `workflow` package you are using
 - The run ID(s) of the affected workflow run(s)
-- The error message (including `eventType`, `correlationId`, and `eventId`)
+- The complete error message, including any `eventType`, `correlationId`, `eventId`, or payload details
 - Any details about the event log or the workflow that triggered the error
 
-## This Error Cannot Be Caught
+## This error cannot be caught
 
 Unlike other workflow errors, a corrupted event log error is **not catchable** inside your workflow function. Because the event log itself is invalid, the runtime cannot safely continue executing any user code. The entire run fails immediately and is marked as `failed`.
 

package/docs/errors/deployment-mismatch.mdx

@@ -0,0 +1,71 @@
+---
+title: deployment-mismatch
+description: A workflow run was delivered to a deployment other than the one it is pinned to.
+type: troubleshooting
+summary: Understand how Workflow recovers from a misrouted delivery, and why a run eventually fails with DEPLOYMENT_MISMATCH.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/versioning
+  - /docs/errors/runtime-decryption-failed
+  - /docs/foundations/errors-and-retries
+---
+
+Every run is pinned to a single deployment when it starts. When a queued workflow or step callback is delivered to a **different** deployment, Workflow does not execute it there. Instead it re-routes the message to the deployment the run is pinned to, and only if the run keeps arriving elsewhere does it fail with the `DEPLOYMENT_MISMATCH` classification.
+
+This is an SDK/runtime signal, not an error thrown by your workflow code, and it is not catchable inside a workflow function.
+
+## Error message
+
+```text
+Workflow run "wrun_..." is pinned to deployment "dpl_A", but was received by deployment "dpl_B". The runtime re-routed the message to "dpl_A" 3 times and it kept arriving elsewhere, so the run was stopped to protect against code-skew errors. Verify that the run's deployment is still available and that queue callbacks are routed to it.
+```
+
+When the queue definitively reports that the run's deployment cannot be reached (it was deleted, or aged out of its retention window), no re-route is possible and the message omits the re-routing clause. Transient or unknown publishing failures leave the current delivery unacknowledged so the queue can redeliver it; they do not fail the run or consume this recovery budget.
+
+## Why a run is pinned
+
+A run's deployment is chosen once, at [`start()`](/docs/api-reference/workflow-api/start):
+
+- By default it is the deployment that called `start()`. See [Versioning](/docs/foundations/versioning) for why runs are pinned this way.
+- With `start(workflow, args, { deploymentId })` it is the id you pass, so a run can deliberately target a deployment other than the one that created it.
+- With `deploymentId: "latest"` it is the most recent deployment for the current environment, resolved at start time.
+
+Whichever it is, that `deploymentId` is recorded on the run, and every subsequent workflow replay and step execution must happen on that deployment. Continuing on a different one is unsafe:
+
+1. **Code skew.** The workflow and step bundles on the receiving deployment may not match the code that produced the run's recorded history, so replay could diverge or produce incorrect results.
+2. **Encryption.** Step inputs and other event-log payloads are encrypted with a per-run key derived from the pinned deployment's key material. A different deployment derives the wrong key and cannot decrypt them, previously the source of a confusing [runtime-decryption-failed](/docs/errors/runtime-decryption-failed) that exhausted retries with no clear cause.
+
+So the runtime checks the pinned deployment before it executes anything, and `DEPLOYMENT_MISMATCH` names the result, instead of the mismatch surfacing later as an unrelated decryption failure.
+
+## Automatic recovery
+
+A deployment that receives a run it does not own first tries to fix the delivery rather than fail the run:
+
+1. It re-enqueues the message **explicitly addressed** to the run's own deployment. This is strictly better-addressed than the send that misrouted, which inherited the producing deployment's ambient id.
+2. Delivery is delayed with a short exponential backoff (1s, 2s, 4s).
+3. If the run keeps arriving at the wrong deployment, the run is failed with `DEPLOYMENT_MISMATCH` after `WORKFLOW_DEPLOYMENT_MISMATCH_MAX_RETRIES` attempts (default `3`). Set it to `0` to fail on the first misrouted delivery instead.
+
+Nothing is executed on the wrong deployment during recovery: no workflow code, no step body, no `step_started`, and no hook resume. Whatever the delivery was carrying travels with it, so a pending step keeps its identity and a hook resume keeps its payload: they run on the deployment that can actually decrypt them.
+
+Recovery attempts do not create events on the run, so a run that self-heals looks completely normal. They are reported on the invocation's trace span (`workflow.deployment.pinned_id`, `workflow.deployment_mismatch.retry_count`, `workflow.deployment_mismatch.recovered`) and as a runtime warning in your function logs.
+
+## What to do
+
+- **Re-run from the current deployment.** Trigger the workflow again from your latest deployment (or use the **Re-run** button in the Workflow Dashboard). The new run is pinned to the current deployment.
+- **Keep a run's deployment available** for the lifetime of that run. A run whose deployment has been deleted or has aged out cannot be resumed and must be re-run: recovery cannot help, so these fail on the first misrouted delivery. This applies to runs started with an explicit `deploymentId` too: pinning a run to an older deployment keeps it dependent on that deployment for its whole lifetime.
+- **Report it** if the pinned deployment was still available. Include both deployment IDs and the run ID from the error message, plus the trace span attributes above. A run that failed this way despite a reachable target is a routing fault worth investigating rather than something to work around.
+
+## This error cannot be caught
+
+Like other runtime signals, `DEPLOYMENT_MISMATCH` is **not catchable** inside your workflow function: the run is failed before any workflow or step code executes on the receiving deployment. Check the run status from outside instead:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+const run = getRun("wrun_abc123");
+const status = await run.status;
+if (status === "failed") {
+  console.error("Run failed");
+}
+```

package/docs/errors/fetch-in-workflow.mdx

@@ -9,21 +9,25 @@ related:
   - /docs/api-reference/workflow/fetch
 ---
 
+<CopyPrompt
+  text="Fix `fetch` usage inside workflow functions. Search workflow files for direct global `fetch(...)` calls and libraries such as AI SDK calls that use fetch. For basic HTTP calls inside a `&quot;use workflow&quot;` function, import `{ fetch }` from `workflow` and replace the global call. For SDK/client calls that need normal Node.js or provider behavior, move the call into a helper function with `&quot;use step&quot;` and call that step from the workflow. Keep all step inputs and outputs serializable. Verify the workflow starts and replays without the fetch-in-workflow error."
+/>
+
 This error occurs when you try to use `fetch()` directly in a workflow function, or when a library (like the AI SDK) tries to call `fetch()` under the hood.
 
-## Error Message
+## Error message
 
-```
+```text
 Global "fetch" is unavailable in workflow functions. Use the "fetch" step function from "workflow" to make HTTP requests.
 ```
 
-## Why This Happens
+## Why this happens
 
 Workflow functions run in a sandboxed environment without direct access to `fetch()`.
 
 Many libraries make HTTP requests under the hood. For example, the AI SDK's `generateText()` function calls `fetch()` to make HTTP requests to AI providers. When these libraries run inside a workflow function, they fail because the global `fetch` is not available.
 
-## Quick Fix
+## Quick fix
 
 Import the `fetch` step function from the `workflow` package and assign it to `globalThis.fetch` inside your workflow function. This version of `fetch` is a step function that wraps the standard `fetch` API, automatically handling serialization and providing retry capabilities. This will also make `fetch()` available to all functions and libraries in the current workflow function.
 
@@ -68,9 +72,9 @@ export async function chatWorkflow(prompt: string) {
 }
 ```
 
-## Common Scenarios
+## Common scenarios
 
-### AI SDK Integration
+### AI SDK integration
 
 This is the most common scenario - using AI SDK functions that make HTTP requests:
 
@@ -94,7 +98,7 @@ export async function aiWorkflow(userMessage: string) {
 }
 ```
 
-### Direct API Calls
+### Direct API calls
 
 You can also use the fetch step function directly for your own HTTP requests: