fix(#433): verify amd64 emulation on Apple Silicon + start colima with VZ/Rosetta

[shujaatTracebloc]

#433 — Apple Silicon: amd64 emulation assumed but never verified; colima lacked Rosetta

The client images are amd64-only. On Apple Silicon the installer just printed a note and proceeded, assuming Docker Desktop's emulation works — so with "Use Rosetta for x86_64/amd64 emulation" off (or colima in play), pods crash-loop with an exec-format error minutes later, no preflight/setup catch. The headless colima path was worse: colima start passed no arch/Rosetta flags → an arm64 VM running amd64 images under slow QEMU or not at all.

Fix

1. Post-Docker smoke — assert_amd64_emulation (setup-macos.sh)
Once Docker is confirmed up, force-run a tiny amd64 binary:

docker run --rm --platform linux/amd64 busybox:1.36 true

On failure, hard-fail naming the exact setting (Docker Desktop → Settings → General → "Use Rosetta for x86_64/amd64 emulation") and the colima remedy — so it's caught at setup, never as a crash-looping pod. Wired into install_macos right after Docker readiness. Intel Macs skip it (native amd64); TRACEBLOC_ALLOW_ARM64 is the escape hatch; image overridable via TB_AMD64_SMOKE_IMAGE.

2. colima VZ/Rosetta — _install_docker_colima
On Apple Silicon + macOS 13+ (VZ available), start colima with --vm-type vz --vz-rosetta for Rosetta-accelerated amd64 (matches Docker Desktop's Rosetta). Older macOS keeps colima's QEMU default (amd64 still runs, just slower — and the smoke catches a truly-broken setup either way). New _macos_supports_vz helper (TB_MACOS_VER-overridable). bash-3.2-safe: the colima arg vector is never empty, so "${_colima_args[@]}" is safe under set -u.

3. Preflight message — _pf_arch
The macOS arch note now names the Rosetta setting and says the real check runs once Docker is up, instead of "assume it works".

Acceptance criteria

• ✅ Apple Silicon with emulation disabled is caught at setup with the named setting — never as a crash-looping pod later.

Tests / gates

• New scripts/tests/setup-macos-arch.bats: VZ detection (13+/12/junk/undeterminable), colima flag matrix (Apple Silicon+13 → VZ+Rosetta; macOS 12 → QEMU; Intel → none), and the smoke test (pass/fail-names-setting/Intel-noop/ALLOW_ARM64-skip/image-override).
• preflight.bats assertion that the arch note names the setting + defers to the post-Docker smoke.
• Separate test file from setup-macos.bats to avoid a file-add clash with fix(installer): macOS installs tools via bare brew — version pins inoperative, no checksums, no execute-gate #429/fix(#429): macOS installs pinned kubectl/k3d/helm via the shared verified path (not bare brew) #521.
• shellcheck --severity=error, check-style, check-drift clean; preflight.bats (82) green; manifest.sha256 regenerated (R8).

Closes#433

---

Note

Medium Risk
Changes macOS installer bootstrap and Colima VM creation flags; failures are intentional early exits, but headless/Apple Silicon install paths are directly affected.

Overview
Apple Silicon installs no longer assume amd64 client images will run. Preflight now names Docker Desktop’s “Use Rosetta for x86_64/amd64 emulation” setting and says the real check happens once Docker is up, instead of implying emulation already works.

After Docker is ready, assert_amd64_emulation runs a time-bounded docker run --platform linux/amd64 smoke test and hard-fails with Docker Desktop and Colima remediation steps (or honors TRACEBLOC_ALLOW_ARM64). Intel Macs skip the probe.

On headless Colima paths, fresh Apple Silicon VMs on macOS 13+ start with --vm-type vz --vz-rosetta; existing VMs are left unchanged so Colima doesn’t reject a vmType change. Helpers gate VZ support and instance detection.

New setup-macos-arch.bats and an updated preflight test cover these behaviors; manifest.sha256 is refreshed.

^{Reviewed by Cursor Bugbot for commit 1f172ab. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9bf1513. Configure here.}

[LukasWodka]

/fr-pass