[defkode]

--dry-run was gated inside cmd_up only. The bare orbx, orbx shell, and orbx run all parse the flag and then call ensure_up with nothing checking it — so they create and fully provision a machine. orbx down --dry-run deletes one. Only orbx up --dry-run did what --help promises: "Print the orb command that would run, then exit."

I hit this while inspecting behavior the way AGENTS.md recommends — orbx --dry-run --name testname123 — and found a provisioned VM sitting in orb list afterwards. The orb stub shows exactly what happens:

list -q
create -c .../templates/default.yaml --isolated --mount ... ubuntu:26.04 testname123
-m testname123 -u root cat /etc/sandbox-status     ← already polling for ready

This matters most for agents: AGENTS.md tells them --dry-run inspects behavior "without touching OrbStack", so an agent following the documentation silently leaves machines behind.

The fix

The gate moves into orbx::dry_run_plan, called by every path that would mutate OrbStack. It deliberately probes nothing — no orb list, no machine state — so a dry run cannot touch OrbStack even to look. That property is what the existing [ ! -s "$ORB_STUB_LOG" ] assertion in create.bats pins, and the new tests hold the other paths to the same bar. down prints the orb delete -f <name> it would have run.

Verification

Against the real CLI, three dry runs leave orb list empty:

$ orbx --dry-run --name dryrunlive
orb create -c .../templates/default.yaml --isolated --mount ... ubuntu:26.04 dryrunlive
$ orbx run --dry-run --name dryrunlive2 -- true
orb create -c .../templates/default.yaml --isolated --mount ... ubuntu:26.04 dryrunlive2
$ orbx down --dry-run --yes --name dryrunlive3
orb delete -f dryrunlive3
$ orb list | wc -l
0

4 new tests in test/create.bats covering the bare form, run, shell, and down. 77/77 pass, shellcheck clean.

Note on keeping the flag

Worth stating why this is a fix rather than a removal: --dry-run is how test/create.bats asserts the composed orb create line — config layering, mounts, arch, template resolution — without touching OrbStack. It's the introspection seam the create-path tests rest on, and it's a documented flag of a released version.