Document the devbox VM dev-loop and its single-bundle (one-at-a-time) constraint

[obj-p]

Gap

The devbox/ VM tooling (vzy, make -C devbox, dev.swift) is new and undocumented — AGENTS.md has no devbox section. A dev who wants a disposable macOS VM with their worktree mounted has nothing to read. Worse, the per-worktree concurrency limit is invisible: you cannot run a devbox VM from worktree A and worktree B at the same time today, and nothing says so.

What to document (AGENTS.md or devbox/README.md)

• Build the bundle: make -C devbox bundle → snapshots base → post-sa → post-ssh → post-toolchain → post-ios (built from the cached IPSW + Xcode 26.2 XIP; first build is long).
• Dev loop: make -C devbox dev WORKTREE=<path> [CMD=...] runs dev.swift (restore post-toolchain, boot, virtio-fs mount the worktree via --dir/--mount-at, drop a shell, stop on exit).
• Toolchain is Brewfile-driven (brew bundle) + Xcode pinned at boot via the com.devbox.xcode-select LaunchDaemon; VM is 12 vCPU / 24GB, display 110ppi.
• Constraint: one devbox VM at a time per bundle. Guest.session (the vzy run path) does not check the pidfile (only vzy boot does), and bundle disk/snapshots are shared, so a second concurrent run clobbers the first.

Concurrency (the real ask): per-worktree devbox VMs

Running an isolated devbox VM per worktree concurrently needs the same primitive as #294: clonefile the base bundle per run, give the clone a fresh MAC + machine-identifier.bin, boot it (mounting that worktree), and delete it on exit. #294 frames this for merge-queue test sandboxes; the devbox dev loop is the same mechanism and arguably the more common need. Either broaden #294 to cover dev.swift, or build Guest.sandbox(cloneOf:) once and use it for both.

Found while landing chunk D (the Bazel bar). Related: #294 (sandbox primitive).

[obj-p]

Closing as moot: devbox/ was removed from main (#364, PR #369). The dev-loop it documented no longer exists in this repo; vzy usage docs belong to https://github.com/obj-p/vzy.