[cli] warn when forking a running sandbox

[erulkey]

Context: Gauntlet story Fork a prepared sandbox into multiple work sandboxes. The agent created a source, wrote /workspace/prepared/state.txt, ran sandbox fork twice, and both children came up without the file. It recovered only after finding sandbox snapshot --stop on its own and forking again: 12 of 22 steps adapted.

The server forks from the source's latest snapshot, or from a fresh copy of its runtime when there is none. It never reads a running session's filesystem. The SDK JSDoc and the vercel.com CLI reference say so; the CLI did not. fork --help only mentioned copied config, and forking a running source printed the normal success summary and exited 0.

Reproduced with sandbox 4.3.0 against elisabethrulke/sandbox-demo:

$ sandbox exec fork-warn-src -- sh -c 'mkdir -p /workspace/prepared && echo ready > /workspace/prepared/state.txt'
$ sandbox fork fork-warn-src --name fork-warn-src-a
✅ Sandbox fork-warn-src-a forked from fork-warn-src.
$ sandbox exec fork-warn-src-a -- cat /workspace/prepared/state.txt
cat: /workspace/prepared/state.txt: No such file or directory
exit=1

This:

• looks the source up before forking (one extra GET, resume: false so a stopped source stays stopped) and, when its session is running, prints a warning to stderr with the snapshot-first workaround. The fork still proceeds.
• states the snapshot semantics in fork --help; docs/index.md regenerated.

Same sequence with this branch:

$ sandbox fork fork-warn-src --name fork-warn-src-b
warn: fork-warn-src is running. The fork starts from its runtime image (it has no snapshot yet), not from its live filesystem.
╰▶ hint: run `sandbox snapshot --stop fork-warn-src` first to fork the current filesystem.
- Forking sandbox fork-warn-src...
✅ Sandbox fork-warn-src-b forked from fork-warn-src.

After sandbox snapshot --stop fork-warn-src, the next fork printed no warning and cat /workspace/prepared/state.txt in the child returned ready.

Not done here: the warning fires on running only; stopping and snapshotting sources are left alone. I did not add a snapshot-and-fork flag, since it would stop the source as a side effect and deserves its own discussion. Server behavior is unchanged.

Verification: pnpm vitest run test/commands 22 passed (3 new in fork.test.ts), pnpm typecheck clean, live run above, all 4 test sandboxes removed afterwards.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sandbox	Ready	Preview, v0	Sep 18, 2026 6:43pm UTC
sandbox-sdk-ai-example	Ready	Preview	Sep 18, 2026 6:43pm UTC
workflow-code-runner	Ready	Preview	Sep 18, 2026 6:43pm UTC