workflow 5.0.0-beta.1 → 5.0.0-beta.11

package/docs/cookbook/integrations/sandbox.mdx

@@ -0,0 +1,520 @@
+---
+title: Sandbox
+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.
+related:
+  - /docs/ai/defining-tools
+  - /docs/foundations/errors-and-retries
+  - /docs/cookbook/common-patterns/scheduling
+  - /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.
+
+## 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:
+
+- **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.
+- **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.
+
+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.
+
+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.
+
+## 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.
+
+```typescript title="workflows/sandbox-pipeline.ts" lineNumbers
+import { Sandbox } from "@vercel/sandbox";
+
+export async function sandboxPipeline(input: { commands: string[] }) {
+  "use workflow";
+
+  const sandbox = await Sandbox.create({ runtime: "node22" }); // [!code highlight]
+
+  try {
+    const results = [];
+    for (const command of input.commands) {
+      const result = await sandbox.runCommand({ // [!code highlight]
+        cmd: "bash",
+        args: ["-c", command],
+      });
+      results.push({
+        command,
+        exitCode: result.exitCode,
+        stdout: await result.stdout(),
+        stderr: await result.stderr(),
+      });
+    }
+    return { status: "completed", results };
+  } finally {
+    await sandbox.stop(); // [!code highlight]
+  }
+}
+```
+
+## 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).
+
+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.
+
+The only way out is an explicit `/destroy` command.
+
+<Tabs items={['Workflow', 'API Routes', 'Client']}>
+
+<Tab value="Workflow">
+
+```typescript title="workflows/sandbox-session.ts" lineNumbers
+import { defineHook, sleep, getWritable, getWorkflowMetadata } from "workflow";
+import { Sandbox, type Snapshot } from "@vercel/sandbox";
+import { z } from "zod";
+
+export const commandHook = defineHook({ // [!code highlight]
+  schema: z.object({ command: z.string() }),
+});
+
+const RUNTIME = "node22";
+const HIBERNATE_AFTER_MS = 30 * 60_000; // 30 min idle → hibernate
+const SANDBOX_TIMEOUT_MS = 5 * 60 * 60_000; // sandbox hard cap (5h)
+const REFRESH_SAFETY_MS = 5 * 60_000; // refresh 5 min before the cap
+
+export type SandboxEvent =
+  | {
+      type: "created";
+      sandboxId: string;
+      runtime: string;
+      startedAt: number;
+      sandboxExpiresAt: number;
+      hibernateAfterMs: number;
+    }
+  | {
+      type: "status";
+      state:
+        | "active"
+        | "hibernating"
+        | "hibernated"
+        | "resuming"
+        | "refreshing"
+        | "destroyed";
+      at: number;
+      sandboxId?: string;
+      sandboxExpiresAt?: number;
+      snapshotId?: string;
+    }
+  | { type: "activity"; at: number }
+  | { type: "command_start"; id: string; command: string; at: number }
+  | { type: "command_output"; id: string; stream: "stdout" | "stderr"; data: string }
+  | { type: "command_end"; id: string; exitCode: number | null; durationMs: number }
+  | { type: "result"; status: "destroyed"; durationMs: number };
+
+async function emit(event: SandboxEvent) {
+  "use step";
+  const writer = getWritable<SandboxEvent>().getWriter();
+  try {
+    await writer.write(event);
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+async function runCommandAndStream(sandbox: Sandbox, id: string, command: string) {
+  "use step";
+  const writer = getWritable<SandboxEvent>().getWriter();
+  const startedAt = Date.now();
+  try {
+    await writer.write({ type: "command_start", id, command, at: startedAt });
+    const result = await sandbox.runCommand({ cmd: "bash", args: ["-c", command] });
+    const stdout = await result.stdout();
+    if (stdout) await writer.write({ type: "command_output", id, stream: "stdout", data: stdout });
+    const stderr = await result.stderr();
+    if (stderr) await writer.write({ type: "command_output", id, stream: "stderr", data: stderr });
+    await writer.write({
+      type: "command_end", id,
+      exitCode: result.exitCode,
+      durationMs: Date.now() - startedAt,
+    });
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+export async function sandboxSessionWorkflow() {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+  // 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 });
+
+  const startedAt = Date.now();
+
+  let sandbox: Sandbox = await Sandbox.create({
+    runtime: RUNTIME,
+    timeout: SANDBOX_TIMEOUT_MS,
+  });
+  let sandboxCreatedAt = Date.now();
+  let sandboxExpiresAt = sandboxCreatedAt + SANDBOX_TIMEOUT_MS;
+
+  await emit({
+    type: "created",
+    sandboxId: sandbox.sandboxId,
+    runtime: RUNTIME,
+    startedAt,
+    sandboxExpiresAt,
+    hibernateAfterMs: HIBERNATE_AFTER_MS,
+  });
+  await emit({
+    type: "status", state: "active", at: Date.now(),
+    sandboxId: sandbox.sandboxId, sandboxExpiresAt,
+  });
+
+  let snapshot: Snapshot | null = null;
+  let hibernated = false;
+  let lastActivityAt = startedAt;
+  let counter = 0;
+  let destroyed = false;
+
+  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.
+        const payload = await hook;
+        if (payload.command === "/destroy") { destroyed = true; break; }
+
+        await emit({ type: "status", state: "resuming", at: Date.now() });
+        sandbox = await Sandbox.create({ // [!code highlight]
+          source: { type: "snapshot", snapshotId: snapshot.snapshotId }, // [!code highlight]
+          timeout: SANDBOX_TIMEOUT_MS, // [!code highlight]
+        });
+        sandboxCreatedAt = Date.now();
+        sandboxExpiresAt = sandboxCreatedAt + SANDBOX_TIMEOUT_MS;
+        hibernated = false;
+        snapshot = null;
+        await emit({
+          type: "status", state: "active", at: Date.now(),
+          sandboxId: sandbox.sandboxId, sandboxExpiresAt,
+        });
+
+        counter += 1;
+        await runCommandAndStream(sandbox, `cmd-${counter}`, payload.command);
+        lastActivityAt = Date.now();
+        await emit({ type: "activity", at: lastActivityAt });
+        continue;
+      }
+
+      // 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);
+      const sleepMs = Math.max(0, wakeAt - Date.now());
+
+      const outcome = await Promise.race([ // [!code highlight]
+        hook.then((p) => ({ type: "command" as const, command: p.command })),
+        sleep(`${sleepMs}ms`).then(() => ({ type: "timer" as const })),
+      ]);
+
+      if (outcome.type === "timer") {
+        const nearExpiry = Date.now() >= refreshDeadline;
+
+        if (nearExpiry) {
+          // 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]
+          sandbox = await Sandbox.create({ // [!code highlight]
+            source: { type: "snapshot", snapshotId: snap.snapshotId }, // [!code highlight]
+            timeout: SANDBOX_TIMEOUT_MS, // [!code highlight]
+          });
+          sandboxCreatedAt = Date.now();
+          sandboxExpiresAt = sandboxCreatedAt + SANDBOX_TIMEOUT_MS;
+          await emit({
+            type: "status", state: "active", at: Date.now(),
+            sandboxId: sandbox.sandboxId, sandboxExpiresAt,
+            snapshotId: snap.snapshotId,
+          });
+          lastActivityAt = Date.now();
+        } else {
+          // Idle — snapshot and hibernate indefinitely.
+          await emit({ type: "status", state: "hibernating", at: Date.now() });
+          snapshot = await sandbox.snapshot(); // [!code highlight]
+          hibernated = true;
+          await emit({
+            type: "status", state: "hibernated", at: Date.now(),
+            snapshotId: snapshot.snapshotId,
+          });
+        }
+        continue;
+      }
+
+      if (outcome.command === "/destroy") { destroyed = true; break; }
+
+      counter += 1;
+      await runCommandAndStream(sandbox, `cmd-${counter}`, outcome.command);
+      lastActivityAt = Date.now();
+      await emit({ type: "activity", at: lastActivityAt });
+    }
+  } finally {
+    if (!hibernated) {
+      try {
+        if (sandbox.status === "running") await sandbox.stop();
+      } catch { /* best-effort */ }
+    }
+    await emit({ type: "status", state: "destroyed", at: Date.now() });
+    await emit({
+      type: "result",
+      status: "destroyed",
+      durationMs: Date.now() - startedAt,
+    });
+  }
+}
+```
+
+</Tab>
+
+<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.
+
+```typescript title="app/api/sandbox/start/route.ts" lineNumbers
+import { start, getRun } from "workflow/api";
+import { sandboxSessionWorkflow } from "@/workflows/sandbox-session";
+
+export async function POST(req: Request) {
+  let body: { runId?: string } = {};
+  try {
+    const text = await req.text();
+    if (text) body = JSON.parse(text);
+  } catch { /* ignore malformed body */ }
+
+  // Reconnect path: if the client sends a known runId, stream the durable
+  // event log from the beginning so the UI can rehydrate.
+  if (body.runId) {
+    const run = getRun(body.runId);
+    if (await run.exists) { // [!code highlight]
+      const readable = run.getReadable({ startIndex: 0 }); // [!code highlight]
+      return new Response(readable.pipeThrough(ndjson()), {
+        headers: {
+          "Content-Type": "application/x-ndjson",
+          "x-workflow-run-id": body.runId,
+          "x-workflow-reconnected": "true",
+          "Cache-Control": "no-cache, no-transform",
+        },
+      });
+    }
+    // Stale runId — fall through to start fresh.
+  }
+
+  const run = await start(sandboxSessionWorkflow, []);
+  return new Response(run.readable.pipeThrough(ndjson()), {
+    headers: {
+      "Content-Type": "application/x-ndjson",
+      "x-workflow-run-id": run.runId,
+      "Cache-Control": "no-cache, no-transform",
+    },
+  });
+}
+
+function ndjson<T>() {
+  return new TransformStream<T, string>({
+    transform(chunk, controller) {
+      controller.enqueue(JSON.stringify(chunk) + "\n");
+    },
+  });
+}
+```
+
+```typescript title="app/api/sandbox/command/route.ts" lineNumbers
+import { commandHook } from "@/workflows/sandbox-session";
+
+export async function POST(req: Request) {
+  const { runId, command } = (await req.json()) as { runId?: string; command?: string };
+
+  if (!runId || typeof command !== "string") {
+    return Response.json({ error: "runId and command are required" }, { status: 400 });
+  }
+
+  try {
+    await commandHook.resume(runId, { command }); // [!code highlight]
+    return Response.json({ ok: true });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message.toLowerCase() : "";
+    if (msg.includes("not found") || msg.includes("expired")) {
+      return Response.json({ ok: false, note: "session expired" }, { status: 410 });
+    }
+    throw error;
+  }
+}
+```
+
+</Tab>
+
+<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.
+
+```tsx title="components/sandbox-runner.tsx" lineNumbers
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { SandboxEvent } from "@/workflows/sandbox-session";
+
+const RUN_ID_KEY = "sandbox.runId";
+
+export function SandboxRunner() {
+  const [events, setEvents] = useState<SandboxEvent[]>([]);
+  const runIdRef = useRef<string | null>(null);
+  const didReconnectRef = useRef(false);
+
+  const consume = useCallback(async (res: Response) => {
+    if (!res.ok || !res.body) return;
+    runIdRef.current = res.headers.get("x-workflow-run-id");
+    if (runIdRef.current) {
+      localStorage.setItem(RUN_ID_KEY, runIdRef.current); // [!code highlight]
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          setEvents((prev) => [...prev, JSON.parse(line) as SandboxEvent]);
+        } catch { /* malformed line */ }
+      }
+    }
+  }, []);
+
+  const openStream = useCallback(
+    async (runId?: string) => {
+      setEvents([]);
+      const res = await fetch("/api/sandbox/start", {
+        method: "POST",
+        headers: runId ? { "Content-Type": "application/json" } : undefined,
+        body: runId ? JSON.stringify({ runId }) : undefined,
+      });
+      await consume(res);
+    },
+    [consume]
+  );
+
+  // Auto-reconnect on mount if a runId is stashed.
+  useEffect(() => {
+    if (didReconnectRef.current) return;
+    didReconnectRef.current = true;
+    const stored = localStorage.getItem(RUN_ID_KEY);
+    if (stored) openStream(stored); // [!code highlight]
+  }, [openStream]);
+
+  const start = useCallback(() => {
+    localStorage.removeItem(RUN_ID_KEY);
+    runIdRef.current = null;
+    openStream();
+  }, [openStream]);
+
+  const sendCommand = useCallback(async (command: string) => {
+    if (!runIdRef.current) return;
+    const res = await fetch("/api/sandbox/command", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ runId: runIdRef.current, command }),
+    });
+    if (res.status === 410) localStorage.removeItem(RUN_ID_KEY);
+  }, []);
+
+  const destroy = useCallback(async () => {
+    await sendCommand("/destroy");
+    localStorage.removeItem(RUN_ID_KEY);
+  }, [sendCommand]);
+
+  // Render events as a terminal-style log. Drive UI state from `status` events
+  // (active / hibernating / hibernated / resuming / refreshing / destroyed).
+  return null;
+}
+```
+
+</Tab>
+
+</Tabs>
+
+## 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.
+
+## 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.
+
+### `snapshot()` already stops the VM
+
+Calling `stop()` after `snapshot()` either errors or is a no-op depending on timing. Snapshot takes care of it.
+
+### New `sandboxId` after resume and refresh
+
+Both `resuming` (idle → command) and `refreshing` (near-hard-cap rotation) create a new sandbox with a new `sandboxId`. Emit it on the subsequent `status: "active"` event and have the UI read from there, not from the initial `created` event.
+
+### 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.
+
+### Don't call `writable.close()` inside a workflow function
+
+Stream closure must happen inside a `"use step"` function. Calling `writable.close()` directly in the workflow body throws `Not supported in workflow functions`. The runtime closes the underlying writable when the workflow returns.
+
+### Handle stale `runId` gracefully
+
+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.
+
+### 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

package/docs/cookbook/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Cookbook",
+  "defaultOpen": true,
+  "pages": ["agent-patterns", "common-patterns", "integrations", "advanced"]
+}

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/local-world.mdx

@@ -32,7 +32,7 @@ npx workflow web
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />
 

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

@@ -141,7 +141,7 @@ If `WORKFLOW_POSTGRES_URL` is not set, the CLI defaults to `postgres://world:wor
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />
 
@@ -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

@@ -83,7 +83,7 @@ npx workflow inspect runs \
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />
 
@@ -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`