workflow 5.0.0-beta.4 → 5.0.0-beta.6

package/docs/changelog/index.mdx

@@ -12,4 +12,5 @@ Stay up to date with the latest changes to Workflow SDK.
 
 ## 2026
 
-- TBD
+- [Eager processing of steps and incremental event replay](/docs/changelog/eager-processing) - March 2026
+- [Serializable AbortController and AbortSignal](/docs/changelog/serializable-abort-controller) — March 12, 2026

package/docs/cookbook/advanced/child-workflows.mdx

@@ -22,7 +22,7 @@ For simpler cases where steps share a single event log, use [direct await compos
 
 The core pattern has three parts:
 
-1. A **step** that calls `start()` to spawn a child workflow and returns the run ID
+1. A parent workflow that calls `start()` to spawn child workflows and records their run IDs
 2. A **polling loop** in the parent workflow that checks child status with `getRun()`
 3. A **step** that retrieves the child's return value once it completes
 
@@ -67,7 +67,11 @@ export async function processDocumentBatch(documentIds: string[]) {
   "use workflow";
 
   // Spawn a child workflow for each document
-  const runIds = await spawnChildren(documentIds);
+  const runIds: string[] = [];
+  for (const docId of documentIds) {
+    const run = await start(processDocument, [docId]); // [!code highlight]
+    runIds.push(run.runId);
+  }
 
   // Poll until all children complete
   await pollUntilComplete(runIds);
@@ -77,19 +81,6 @@ export async function processDocumentBatch(documentIds: string[]) {
 
   return { processed: results.length, results };
 }
-
-async function spawnChildren(
-  documentIds: string[]
-): Promise<string[]> {
-  "use step"; // [!code highlight]
-
-  const runIds: string[] = [];
-  for (const docId of documentIds) {
-    const run = await start(processDocument, [docId]); // [!code highlight]
-    runIds.push(run.runId);
-  }
-  return runIds;
-}
 ```
 
 ### Polling loop
@@ -163,7 +154,7 @@ async function collectResults(
 
 ## Fan-out pattern: chunked spawning
 
-When spawning hundreds of children, batch the `start()` calls to avoid overwhelming the system. Use multiple spawn steps, each launching a chunk of children.
+When spawning hundreds of children, batch the `start()` calls to avoid overwhelming the system. Start one chunk at a time from the parent workflow.
 
 ```typescript
 import { start } from "workflow/api";
@@ -179,7 +170,7 @@ export async function largeReportBatch(reportConfigs: Array<{ id: string; query:
   const allRunIds: string[] = [];
   for (let i = 0; i < reportConfigs.length; i += CHUNK_SIZE) {
     const chunk = reportConfigs.slice(i, i + CHUNK_SIZE);
-    const runIds = await spawnReportChunk(chunk); // [!code highlight]
+    const runIds = await startReportChunk(chunk); // [!code highlight]
     allRunIds.push(...runIds);
   }
 
@@ -190,14 +181,12 @@ export async function largeReportBatch(reportConfigs: Array<{ id: string; query:
   return { total: results.length, results };
 }
 
-async function spawnReportChunk(
+async function startReportChunk(
   configs: Array<{ id: string; query: string }>
 ): Promise<string[]> {
-  "use step";
-
   const runIds: string[] = [];
   for (const config of configs) {
-    const run = await start(generateReport, [config.id, config.query]);
+    const run = await start(generateReport, [config.id, config.query]); // [!code highlight]
     runIds.push(run.runId);
   }
   return runIds;
@@ -356,12 +345,12 @@ async function pollWithRetries(
 
 ## Tips
 
-- **`start()` must be called from a step**, not directly from a workflow function. Wrap it in a `"use step"` function.
+- **`start()` can be called directly from a workflow function in v5.** It records a step-backed boundary in the parent event log and returns a serializable `Run`.
 - **`getRun()` must also be called from a step.** The polling loop lives in the workflow, but the actual status check is a step.
 - **Set a max iteration count on polling loops** to prevent runaway workflows. Calculate the count from your expected max duration and poll interval.
-- **Use chunked spawning for large batches.** Spawning 500 children in a single step can time out. Break it into chunks of 10-50.
+- **Use chunked spawning for large batches.** Starting 500 children at once can create a large burst of work. Break it into chunks of 10-50.
 - **Each child has its own retry semantics.** Steps inside child workflows retry independently. The parent only sees the child's final status.
-- **Use `deploymentId: "latest"`** if children should run on the most recent deployment. See the [`start()` API reference](/docs/api-reference/workflow-api/start#using-deploymentid-latest) for compatibility considerations.
+- **Use `deploymentId: "latest"`** if children should run on the most recent deployment. See [Versioning](/docs/foundations/versioning) for the full model and the [`start()` API reference](/docs/api-reference/workflow-api/start#using-deploymentid-latest) for compatibility considerations.
 
 ## Key APIs
 

package/docs/cookbook/advanced/meta.json

@@ -1,9 +1,4 @@
 {
   "title": "Advanced",
-  "pages": [
-    "child-workflows",
-    "distributed-abort-controller",
-    "serializable-steps",
-    "publishing-libraries"
-  ]
+  "pages": ["child-workflows", "serializable-steps", "publishing-libraries"]
 }

package/docs/cookbook/agent-patterns/agent-cancellation.mdx

@@ -1,70 +1,15 @@
 ---
 title: Agent Cancellation
-description: Cancel a running agent from the outside — either immediately via run.cancel() or gracefully via a stop signal hook.
+description: Cancel a running agent from the outside using AbortSignal — a hook fires the abort, the agent step bails out of the model stream, and the client gets a clean stop notification.
 type: guide
-summary: Two patterns for cancelling a running agent — Hard Cancellation via getRun(runId).cancel() for forced termination, or Stop Signal via a hook + Promise.race for a clean exit with cleanup and final stream notification.
+summary: Cancel a running agent cooperatively with AbortController. A stop hook fires controller.abort(), the signal propagates into the agent step to cancel the model stream, and a data-stopped part is emitted to streaming clients before the workflow returns.
 ---
 
-Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback. Two patterns are available depending on whether you need the agent to exit cleanly or just need the run to stop: **Hard Cancellation** via `getRun(runId).cancel()` for immediate forced termination, or **Stop Signal** via a hook + `Promise.race` for a graceful exit that runs cleanup and notifies streaming clients before returning.
+Cancel a running agent from the outside — for example, a "Stop" button in a chat UI, an admin cancellation endpoint, or a timeout fallback.
 
-## When to use this
+## Pattern
 
-* **Chat stop buttons** — let users cancel a long-running agent from the browser
-* **Admin cancellation** — stop an agent from a different process or API
-* **Timeout fallback** — combine with `sleep()` to auto-stop after a deadline
-
-## Choosing an approach
-
-Pick the option that matches what your endpoint needs to deliver to the caller:
-
-* **Hard Cancellation** — terminates the run immediately with no opportunity for cleanup or client notification. A single line of code, but the workflow throws `WorkflowRunCancelledError` and any streaming clients see an abrupt connection close.
-* **Stop Signal** — the workflow exits as soon as the hook fires, runs any pending cleanup, emits a final `data-stopped` part to the stream so the client can render cleanly, and returns a real result.
-
-The trade-offs at a glance:
-
-| | Hard Cancellation | Stop Signal |
-| --- | --- | --- |
-| Mechanism | `getRun(runId).cancel()` | Hook + `Promise.race` |
-| Speed to terminate | Immediate | At the next `await` boundary in the workflow |
-| Runs `finally` / cleanup | No | Yes |
-| Final stream notification | No (abrupt close) | Yes (`data-stopped` part) |
-| `run.returnValue` | Throws `WorkflowRunCancelledError` | Returns the workflow's result |
-| Code complexity | One line | Hook + race + signal step |
-| Best for | Stuck or unresponsive runs, forced termination | User-facing stop, admin cancel, timeouts |
-
-## Hard Cancellation
-
-Call `.cancel()` on a run to terminate it immediately:
-
-```typescript lineNumbers
-import { getRun } from "workflow/api";
-
-export async function POST(
-  _request: Request,
-  { params }: { params: Promise<{ runId: string }> }
-) {
-  const { runId } = await params;
-  await getRun(runId).cancel(); // [!code highlight]
-  return Response.json({ success: true });
-}
-```
-
-This is an abrupt termination — the run is stopped mid-step with no opportunity to exit cleanly:
-
-* **No cleanup runs** — `finally` blocks, defer-style step cleanup, and any logic after the current step are all skipped
-* **No final notification to the client** — the writable closes abruptly, so a streaming UI just sees the connection drop with no `data-stopped` part to render a clean ending
-* **`run.returnValue` throws** — anyone awaiting the result receives [`WorkflowRunCancelledError`](/docs/api-reference/workflow-errors/workflow-run-cancelled-error) instead of a meaningful payload
-* **Underlying step keeps running** — same caveat as the Stop Signal pattern below: the model stream or HTTP call inside the current step continues to completion in the background
-
-Hard Cancellation is the appropriate choice when the run is stuck or unresponsive, has exceeded its expected runtime, or you don't need a clean exit. For everything else — chat stop buttons, admin "stop" actions, timeout fallbacks — you typically want the Stop Signal pattern: the agent finishes its current step, emits a final stream part so the client renders a clean ending, and returns a real result.
-
-## Stop Signal
-
-<Callout type="warn">
-**Limitation:** This pattern does not cancel the underlying model stream. The agent step writing to the writable continues running in the background until it completes — tokens generated after the stop signal are still produced (and billed by your model provider). What this pattern *does* is exit the workflow function as soon as the hook fires and emit a `data-stopped` part so the client can stop rendering. For hard cross-process cancellation that signals the inner step to bail out, see [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller).
-</Callout>
-
-### Example
+Create an `AbortController` in the workflow and race the agent (passing its signal) against a stop hook. When the hook fires, `controller.abort()` is called — the signal propagates into the agent step and cancels the underlying model stream. Before returning, a `data-stopped` part is written to the stream so any streaming clients can render a clean end state.
 
 ```typescript lineNumbers
 import { DurableAgent } from "@workflow/ai/agent";
@@ -88,7 +33,7 @@ async function analyzeData({ topic }: { topic: string }) {
   return { summary: `Analysis of ${topic}: significant developments found.`, confidence: 0.85 };
 }
 
-async function emitStopSignal(details: { reason?: string }) { // [!code highlight]
+async function emitStopSignal(details: { reason?: string }) {
   "use step";
   const writer = getWritable<UIMessageChunk>().getWriter();
   try {
@@ -102,7 +47,8 @@ export async function stoppableAgent(messages: ModelMessage[]) {
   "use workflow";
 
   const { workflowRunId } = getWorkflowMetadata();
-  const hook = stopHook.create({ token: `stop:${workflowRunId}` }); // [!code highlight]
+  const controller = new AbortController(); // [!code highlight]
+  const hook = stopHook.create({ token: `stop:${workflowRunId}` });
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
@@ -121,15 +67,23 @@ export async function stoppableAgent(messages: ModelMessage[]) {
     },
   });
 
-  const result = await Promise.race([ // [!code highlight]
+  const result = await Promise.race([
     agent
-      .stream({ messages, writable: getWritable<UIMessageChunk>(), maxSteps: 15 })
+      .stream({
+        messages,
+        writable: getWritable<UIMessageChunk>(),
+        abortSignal: controller.signal, // [!code highlight]
+        maxSteps: 15,
+      })
       .then((r) => ({ type: "complete" as const, messages: r.messages })),
-    hook.then(({ reason }) => ({ type: "stopped" as const, reason })), // [!code highlight]
+    hook.then(({ reason }) => {
+      controller.abort(reason); // [!code highlight]
+      return { type: "stopped" as const, reason };
+    }),
   ]);
 
   if (result.type === "stopped") {
-    await emitStopSignal({ reason: result.reason }); // [!code highlight]
+    await emitStopSignal({ reason: result.reason });
   }
 
   return result;
@@ -148,7 +102,7 @@ export async function POST(
   const { runId } = await params;
   const { reason } = await request.json();
 
-  await stopHook.resume(`stop:${runId}`, { // [!code highlight]
+  await stopHook.resume(`stop:${runId}`, {
     reason: reason || "User requested stop",
   });
 
@@ -180,13 +134,12 @@ export function StopButton({ runId }: { runId: string }) {
 
 ## How it works
 
-1. A hook is created with token `stop:${workflowRunId}` when the workflow starts
-2. `Promise.race` runs the agent stream and the stop hook concurrently
-3. When the stop API resumes the hook, the race resolves immediately — the workflow exits
-4. Before returning, `emitStopSignal` writes a `data-stopped` part to the stream so the client knows the agent was stopped (not just disconnected)
-5. The client detects `data-stopped` and updates the UI accordingly
-
-This is the same pattern used by the [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller) — race a long-running operation against a hook signal.
+1. An `AbortController` is created at the start of the workflow
+2. A hook is created with token `stop:${workflowRunId}`
+3. `Promise.race` runs the agent stream and the stop hook concurrently
+4. The agent receives `controller.signal` — when aborted, the underlying model stream is cancelled
+5. When the stop API resumes the hook, `controller.abort()` is called — the race resolves and the workflow exits
+6. `emitStopSignal` writes a `data-stopped` part to the stream so the client renders a clean stop state
 
 ## Adapting this
 
@@ -194,12 +147,10 @@ This is the same pattern used by the [Distributed Abort Controller](/cookbook/ad
 * **Audit logging** — include a `reason` field in the stop schema to record who stopped and why
 * **Cross-process** — the hook token is deterministic, so any process can call `stopHook.resume()` with the run ID
 * **Step limits** — combine with `maxSteps` on the agent to cap execution even without manual stop
-* **Hard Cancellation as a fallback** — wire your stop endpoint to fall back to `getRun(runId).cancel()` if the hook resume errors with `not found` / `expired` (for example, the hook was already consumed). This guarantees the run is terminated even when the Stop Signal path is unavailable.
 
 ## Key APIs
 
 * [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook for the stop signal
 * [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
-* [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream a stop notification to the client
-* [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — the agent that gets raced against the stop hook
-* [`getRun()`](/docs/api-reference/workflow-api/get-run) — entry point for Hard Cancellation: `getRun(runId).cancel()`
+* [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream output and the stop notification to the client
+* [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — the agent that respects the abort signal via its `signal` option

package/docs/cookbook/agent-patterns/durable-agent.mdx

@@ -14,6 +14,10 @@ Use this pattern to make any AI SDK agent durable. The agent becomes a workflow,
 - Long-running agent sessions where losing progress is unacceptable
 - Agents that need per-step observability in the workflow event log
 
+<Callout type="info">
+A durable agent run stays on the deployment that started it. For multi-turn agents that should pick up newer code between turns, see [Versioning](/docs/foundations/versioning) for patterns that start the next turn or next session run with `deploymentId: "latest"`.
+</Callout>
+
 ## Pattern
 
 Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.

package/docs/cookbook/common-patterns/scheduling.mdx

@@ -7,6 +7,10 @@ summary: Schedule future actions with durable sleep that survives cold starts, a
 
 Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
 
+<Callout type="info">
+Scheduled workflows are still pinned to the deployment that started them. If you are building recurring or indefinitely running schedules that should adopt newer code over time, see [Versioning](/docs/foundations/versioning) for the explicit `deploymentId: "latest"` continuation pattern.
+</Callout>
+
 ## When to use this
 
 - Sending emails on a schedule (drip campaigns, onboarding sequences, reminders)

package/docs/cookbook/common-patterns/timeouts.mdx

@@ -80,7 +80,7 @@ export async function waitForApproval(requestId: string) {
 4. **Throw to fail the workflow** — inside a workflow function, throwing an `Error` exits the run with that error. Use `FatalError` inside steps; throw plain errors inside workflows.
 
 <Callout type="warn">
-**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. For hard cancellation across processes, see [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller).
+**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. Pass an `AbortSignal` into the step to cancel it cooperatively — see the [Cancellation Guide](/docs/foundations/cancellation) for patterns.
 </Callout>
 
 ## Adapting to your use case

package/docs/cookbook/common-patterns/workflow-composition.mdx

@@ -53,7 +53,7 @@ The parent waits for the child to finish before continuing. Both functions share
 
 ### Background spawn via `start()`
 
-To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from a step. This launches the child as a separate workflow run with its own `runId`.
+To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from the parent workflow. This launches the child as a separate workflow run with its own `runId`.
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -62,37 +62,30 @@ declare function generateReport(reportId: string): Promise<void>; // @setup
 declare function fulfillOrder(orderId: string): Promise<{ id: string }>; // @setup
 declare function sendConfirmation(orderId: string): Promise<void>; // @setup
 
-async function triggerReportGeneration(reportId: string) {
-  "use step"; // [!code highlight]
-
-  const run = await start(generateReport, [reportId]); // [!code highlight]
-  return run.runId;
-}
-
 export async function processOrder(orderId: string) {
   "use workflow";
 
   const order = await fulfillOrder(orderId);
 
-  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]
+  const reportRun = await start(generateReport, [orderId]); // [!code highlight]
 
   await sendConfirmation(orderId);
 
-  return { orderId, reportRunId };
+  return { orderId, reportRunId: reportRun.runId };
 }
 ```
 
 The parent continues immediately after `start()` returns. The child runs independently and can be monitored separately using the returned `runId` (e.g., via [`getRun()`](/docs/api-reference/workflow-api/get-run)).
 
 <Callout type="info">
-If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
+If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. See [Versioning](/docs/foundations/versioning) for the full model. This is currently a Vercel-specific feature, and other Worlds may map the concept to their own deployment runtimes. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
 </Callout>
 
 ## How it works
 
 1. **Direct await flattens.** When a workflow function awaits another workflow function, the child's `"use workflow"` directive is treated as inline — the child's steps emit into the parent's event log and share the parent's run ID.
 2. **`start()` mints a new run.** The child gets its own `runId`, its own event log, and its own retry boundary. The parent only sees the `runId` returned by `start()`.
-3. **`start()` must be called from a step.** Calling `start()` directly from a workflow function is not allowed — wrap it in a `"use step"` function. This keeps the spawn deterministic across replays.
+3. **`start()` can run inside workflows.** In v5, `start()` is step-backed, so it can be called directly from a workflow function and still records a deterministic step boundary in the event log.
 
 ## Choosing between the two modes
 
@@ -106,9 +99,9 @@ If you want the child workflow to run on the latest deployment rather than the c
 
 ## Adapting to your use case
 
-- **Spawn many children at once** — call `start()` in a loop inside a step. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
+- **Spawn many children at once** — call `start()` in a loop from the workflow. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
 - **Wait for a background child to finish** — combine `start()` with `getRun()` polling. The [Child Workflows](/cookbook/advanced/child-workflows) page covers the full polling loop.
-- **Pass results back from background children** — the spawn step returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.
+- **Pass results back from background children** — `start()` returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.
 
 ## Key APIs
 

package/docs/cookbook/index.mdx

@@ -33,6 +33,5 @@ A curated collection of workflow patterns with clean, copy-paste code examples f
 ## Advanced
 
 - [**Child Workflows**](/cookbook/advanced/child-workflows) — Spawn and orchestrate child workflows from a parent
-- [**Distributed Abort Controller**](/cookbook/advanced/distributed-abort-controller) — Build a cross-process abort controller using workflow streams and hooks
 - [**Serializable Steps**](/cookbook/advanced/serializable-steps) — Wrap non-serializable third-party objects so they cross the workflow boundary
 - [**Publishing Libraries**](/cookbook/advanced/publishing-libraries) — Ship npm packages that export reusable workflow functions

package/docs/cookbook/integrations/ai-sdk.mdx

@@ -32,6 +32,10 @@ Use [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text)
 
 One workflow run = one full conversation. The workflow suspends between turns on a hook and resumes when the next user message arrives. Conversation state, tool history, and intermediate computation all live inside the run.
 
+<Callout type="info">
+Because the conversation is one workflow run, it stays on the deployment that started it. If each turn should run on the latest deployment while preserving selected state or streams, see [Versioning](/docs/foundations/versioning) for the child-run continuation pattern.
+</Callout>
+
 <Tabs items={['Workflow', 'API Route', 'Client']}>
 
 <Tab value="Workflow">

package/docs/cookbook/integrations/chat-sdk.mdx

@@ -20,6 +20,10 @@ Workflow SDK complements it by making bot **sessions** durable. Each conversatio
 - Survives deploys, cold starts, and crashes — the session picks up from the last step on replay
 - Receives follow-up messages via hooks, so the bot stays responsive while the workflow is still running
 
+<Callout type="info">
+One thread mapped to one workflow run also means the thread stays on the deployment that started it. For channels where each message should use newer code, see [Versioning](/docs/foundations/versioning) for explicit child-run and handoff patterns using `deploymentId: "latest"`.
+</Callout>
+
 The rest of this page covers the integration pattern. For a full Slack + Next.js + Redis walkthrough, see the [Durable chat sessions guide](https://chat-sdk.dev/docs/guides/durable-chat-sessions-nextjs) on chat-sdk.dev.
 
 ## How It Fits Together

package/docs/cookbook/integrations/sandbox.mdx

@@ -21,6 +21,10 @@ A sandbox alone gets you an isolated VM. A workflow around it gets you a **durab
 - **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.
 - **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
 
 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.

package/docs/deploying/building-a-world.mdx

@@ -93,7 +93,7 @@ interface Storage {
 
 **Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
 
-**Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead.
+**Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead and include the active hook owner's run ID as `eventData.conflictingRunId`.
 
 **Automatic Hook Disposal:** When a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`), automatically dispose of all associated hooks to release tokens for reuse.
 

package/docs/deploying/world/postgres-world.mdx

@@ -161,7 +161,9 @@ Prefix for graphile-worker queue job names. Useful when sharing a database betwe
 
 ### `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
 
-Number of concurrent workers polling for jobs. Default: `10`
+Number of concurrent workers polling for jobs. Default: `50`.
+
+This value also bounds how many parent→child workflow polls can be in flight simultaneously. Every `await childRun.returnValue` inside a workflow holds a worker slot until the child run terminates — if you expect recursive or highly-fanned-out parent/child workflows, raise this ceiling above the peak number of concurrent polls. With the default of 50, the included `fibonacciWorkflow` e2e test (fib(6), ~24 concurrent polls at peak) passes; deeper recursion or larger fanouts need a correspondingly larger setting.
 
 ### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
 
@@ -179,8 +181,8 @@ import { createWorld } from "@workflow/world-postgres";
 const world = createWorld({
   connectionString: "postgres://user:password@host:5432/database",
   jobPrefix: "myapp_",
-  queueConcurrency: 20,
-  maxPoolSize: 20, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
+  queueConcurrency: 50,
+  maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
 });
 ```
 

package/docs/deploying/world/vercel-world.mdx

@@ -139,6 +139,8 @@ On Vercel, workflow runs are pegged to the deployment that started them. This me
 
 This ensures long-running workflows complete reliably without being affected by subsequent deployments.
 
+For the full model, including rerunning on latest and explicit upgrade boundaries, see [Versioning](/docs/foundations/versioning).
+
 ## Security
 
 ### Consumer function security

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

@@ -0,0 +1,80 @@
+---
+title: abort-signal-timeout-in-workflow
+description: AbortSignal.timeout() cannot be used inside workflow functions because it relies on real timers which break deterministic replay.
+type: troubleshooting
+summary: Use sleep() with AbortController instead of AbortSignal.timeout() in workflow functions.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/cancellation
+  - /docs/api-reference/workflow/sleep
+  - /docs/errors/timeout-in-workflow
+---
+
+## Error
+
+```
+AbortSignal.timeout() is not supported in workflow functions.
+Use sleep() with an AbortController instead.
+```
+
+## 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.
+
+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
+
+## How to Fix
+
+Use [`sleep()`](/docs/api-reference/workflow/sleep) with an `AbortController` to create a deterministic timeout that cancels in-flight work:
+
+**Before (incorrect):**
+
+{/* @skip-typecheck: intentionally incorrect example */}
+```typescript lineNumbers
+export async function workflow() {
+  "use workflow";
+
+  // This will throw an error
+  const signal = AbortSignal.timeout(10_000); // [!code highlight]
+  const result = await fetchData(signal);
+  return result;
+}
+```
+
+**After (correct):**
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function workflow() {
+  "use workflow";
+
+  const controller = new AbortController(); // [!code highlight]
+  void sleep("10s").then(() => controller.abort()); // [!code highlight]
+
+  return await fetchData(controller.signal);
+}
+
+async function fetchData(signal: AbortSignal) {
+  "use step";
+  const response = await fetch("https://api.example.com/data", { signal });
+  return response.json();
+}
+```
+
+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).
+
+<Callout type="info">
+`AbortSignal.timeout()` works normally inside step functions, since steps have full Node.js runtime access and are not replayed.
+</Callout>
+
+## 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`

package/docs/errors/hook-conflict.mdx

@@ -73,9 +73,9 @@ export async function processPayment() {
 }
 ```
 
-## Handling Hook Conflicts in Your Workflow
+## Handling Hook Conflicts
 
-When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. You can catch this error to handle the conflict gracefully:
+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:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -93,14 +93,64 @@ export async function processPayment(orderId: string) {
     if (HookConflictError.is(error)) { // [!code highlight]
       // Another workflow is already processing this order
       console.log(`Conflicting token: ${error.token}`);
-      return { success: false, reason: "duplicate-processing" };
+      if (error.conflictingRunId) {
+        console.log(`Active run: ${error.conflictingRunId}`);
+      }
+      return {
+        success: false,
+        reason: "duplicate-processing",
+        token: error.token,
+        runId: error.conflictingRunId
+      };
     }
     throw error; // Re-throw other errors
   }
 }
 ```
 
-This pattern is useful when you want to detect and handle duplicate processing attempts instead of letting the workflow fail.
+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
+
+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:
+
+```typescript lineNumbers
+import { getRun, resumeHook, start } from "workflow/api";
+import { processPayment } from "@/workflows/process-payment";
+
+type ProcessPaymentResult =
+  | { success: true; payment: unknown }
+  | {
+      success: false;
+      reason: "duplicate-processing";
+      token: string;
+      runId?: string;
+    };
+
+export async function POST(request: Request) {
+  const { orderId, payment } = await request.json();
+  const run = await start(processPayment, [orderId]);
+  const result = (await run.returnValue) as ProcessPaymentResult;
+
+  if (
+    result.success === false &&
+    result.reason === "duplicate-processing" &&
+    result.runId
+  ) {
+    await resumeHook(result.token, payment); // [!code highlight]
+    const activeRun = getRun(result.runId); // [!code highlight]
+
+    return Response.json({
+      delegatedToRunId: activeRun.runId,
+      result: await activeRun.returnValue
+    });
+  }
+
+  return Response.json(result);
+}
+```
+
+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
 
@@ -122,4 +172,6 @@ After a workflow completes, its hook tokens become available for reuse by other
 ## Related
 
 - [Hooks](/docs/foundations/hooks) - Learn more about using hooks in workflows
+- [getRun](/docs/api-reference/workflow-api/get-run) - Retrieve or control the active run
+- [resumeHook](/docs/api-reference/workflow-api/resume-hook) - Deliver data to the active hook
 - [createWebhook](/docs/api-reference/workflow/create-webhook) - Alternative for fixed webhook URLs