workflow 5.0.0-beta.43 → 5.0.0-beta.44

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
@@ -14,34 +14,34 @@ related:
   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 "use workflow" that owns the agent session. Put sandbox creation, command execution, snapshot, refresh, and cleanup into helper functions with "use step". 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.
+[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.
 
 <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
+## 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.
 
@@ -74,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.
 
@@ -170,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 });
 
@@ -205,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; }
 
@@ -231,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);
@@ -246,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]
@@ -263,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;
@@ -302,7 +302,7 @@ 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).
@@ -334,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, []);
@@ -383,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";
@@ -476,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
 
@@ -503,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
 
@@ -523,11 +523,11 @@ Each iteration's `hook.then(...)` attaches a listener to the same hook instance.
 
 ## 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
-- [Idempotency](/docs/foundations/idempotency) — choose when `/start` should reuse an existing run
+- [`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

@@ -10,14 +10,14 @@ related:
   - /worlds/building-a-world
 ---
 
-Workflows are designed to be highly portable. The same workflow code can run locally during development, on Vercel with zero configuration, or on any infrastructure using **Worlds** — pluggable adapters that handle storage, queuing, and communication.
+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
+## Local development
 
-During local development, workflows automatically use the **Local World** — no configuration required. The Local World stores workflow data in a `.workflow-data/` directory and processes steps synchronously, making it perfect for development and testing.
+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
-# Just run your dev server - workflows work out of the box
+# Run your dev server to use workflows locally
 npm run dev
 ```
 
@@ -33,17 +33,17 @@ npx workflow inspect runs
 
 ## Deploying to Vercel
 
-The easiest way to deploy workflows to production is on Vercel. When you deploy to Vercel, workflows automatically use the **Vercel World** — again, with zero configuration.
+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** - Steps are processed reliably with automatic retries
-- **Automatic scaling** - Workflows scale with your application
-- **Built-in observability** - View workflow runs in the Vercel dashboard
-- **Multi-region** - Runs are pinned to the region that creates them, keeping workflow data, queuing, and streaming close to your users (requires `workflow` 5.0.0-beta.33 or later)
+- **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
 
-Simply deploy your application:
+Deploy your application:
 
 ```bash
 vercel deploy
@@ -55,7 +55,7 @@ vercel deploy
   Learn more about the [Vercel World](/worlds/vercel) and its capabilities, including [multi-region](/worlds/vercel#multi-region).
 </Callout>
 
-## Self-Hosting & Other Providers
+## Self-hosting & other providers
 
 For self-hosting or deploying to other cloud providers, you can use community-maintained Worlds or build your own.
 
@@ -68,7 +68,7 @@ For self-hosting or deploying to other cloud providers, you can use community-ma
   </Card>
 </Cards>
 
-### Using a Third-Party World
+### Using a third-party World
 
 To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable:
 
@@ -78,11 +78,11 @@ export WORKFLOW_TARGET_WORLD=@workflow/world-postgres
 export DATABASE_URL=postgres://...
 ```
 
-Each World may have its own configuration requirements — refer to the specific World's documentation for details.
+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 can be configured to inspect remote deployments:
+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

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

@@ -17,21 +17,21 @@ related:
 
 ## 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:
 
@@ -70,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.
@@ -78,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

@@ -13,15 +13,15 @@ This error occurs when the Workflow runtime repeatedly cannot replay events in t
 
 This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. The runtime first retries transient replay divergence automatically; it marks the run as failed with this error only after replay still cannot recover.
 
-## Error Message
+## Error message
 
-```
+```text
 Workflow replay diverged <divergenceCount> times after <maxRecoveryReplays> recovery replays; latest divergent event was <eventId>. Last divergence: <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 (e.g., 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, 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.
 
 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.
 
@@ -29,13 +29,13 @@ Before failing, the runtime retries a divergent replay and surfaces this termina
 
 Common scenarios that produce this error:
 
-1. **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.
-2. **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.
-3. **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 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).
 
-## 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
 
@@ -51,14 +51,14 @@ If this error is displayed, automatic replay recovery has already been exhausted
 
 ### 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`)
 - 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

@@ -15,30 +15,30 @@ Every run is pinned to a single deployment when it starts. When a queued workflo
 
 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
+## 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.
+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
+## 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.
+- 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.
+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.
+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
+## Automatic recovery
 
 A deployment that receives a run it does not own first tries to fix the delivery rather than fail the run:
 
@@ -46,19 +46,19 @@ A deployment that receives a run it does not own first tries to fix the delivery
 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.
+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
+## 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.
+- **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
+## 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:
+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";

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

@@ -10,24 +10,24 @@ related:
 ---
 
 <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 simple 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."
+  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.
 
@@ -72,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:
 
@@ -98,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:
 

package/docs/errors/hook-conflict.mdx

@@ -16,13 +16,13 @@ related:
 
 This error occurs when you try to create a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows in your project.
 
-## Error Message
+## Error message
 
-```
+```text
 Hook token "<token>" is already in use by another workflow
 ```
 
-## Why This Happens
+## Why this happens
 
 Hooks use tokens to identify incoming webhook payloads. When you create a hook with `createHook({ token: "my-token" })`, the Workflow runtime reserves that token for your workflow run. If another workflow run is already using that token, a conflict occurs.
 
@@ -31,9 +31,9 @@ This typically happens when:
 1. **Two workflows start simultaneously** with the same hardcoded token
 2. **A previous workflow run is still waiting** for a hook when a new run tries to use the same token
 
-## Common Causes
+## Common causes
 
-### Hardcoded Token Values
+### Hardcoded token values
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -61,7 +61,7 @@ export async function processPayment(orderId: string) {
 }
 ```
 
-### Omitting the Token (Auto-generated)
+### Omitting the token (auto-generated)
 
 The safest approach is to let the Workflow runtime generate a unique token automatically:
 
@@ -77,7 +77,7 @@ export async function processPayment() {
 }
 ```
 
-## Handling Hook Conflicts
+## Handling hook conflicts
 
 When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. The error exposes the token that conflicted and, for current worlds, the run ID that currently owns it. `conflictingRunId` remains optional for compatibility with older persisted events and world implementations, so guard it before delegating:
 
@@ -114,7 +114,7 @@ export async function processPayment(orderId: string) {
 
 This pattern is useful when you want to detect duplicate processing inside the workflow. Runtime APIs such as `resumeHook()` and `getRun()` must be called outside workflow functions, for example from an API route or in a step.
 
-### Delegate to the Active Run
+### Delegate to the active Run
 
 In idempotency flows, a conflict means another active run already owns the hook token. You can return the duplicate-processing payload from the workflow, resume the active hook to deliver the payload to the existing run, then use `getRun(result.runId)` to wait for, stream, or cancel the active run:
 
@@ -156,17 +156,17 @@ export async function POST(request: Request) {
 
 If the caller needs live output instead of the final result, return `activeRun.getReadable()` from the same branch. If the duplicate request should replace the active work, call `await activeRun.cancel()` after inspecting the run.
 
-## When Hook Tokens Are Released
+## When hook tokens are released
 
 Hook tokens are automatically released when:
 
 - The workflow run **completes** (successfully or with an error)
-- The workflow run is **cancelled**
+- The workflow run is **canceled**
 - The hook is explicitly **disposed**
 
 After a workflow completes, its hook tokens become available for reuse by other workflows.
 
-## Best Practices
+## Best practices
 
 1. **Use auto-generated tokens** when possible - they are guaranteed to be unique
 2. **Include unique identifiers** if you need custom tokens (order ID, user ID, etc.)

package/docs/errors/index.mdx

@@ -11,7 +11,7 @@ Fix common mistakes when creating and executing workflows in the **Workflow SDK*
 
 <AutoCards />
 
-## Learn More
+## Learn more
 
 * [API Reference](/docs/api-reference) - Complete API documentation
 * [Foundations](/docs/foundations) - Architecture and core concepts