[quickbeard]

Summary

Phase 2 of the desktop sandbox: the macOS backend — a small Swift helper (codev-vmm) driving Virtualization.framework, plus the vz SandboxProvider that manages it. Implements the agreed design: NIC-less guest (the VM has no network device; its only egress is vsock), virtio-fs mounts, hard block below macOS 12, and the same server/broker bridge contract Phase 1 (#197) established for bwrap.

The Swift helper (native/vzhelper)

A ~350-line SwiftPM executable (macOS 12+, compiles clean on Swift 6.3 toolchain in Swift 5 mode):

• Boot: VZLinuxBootLoader with kernel + initrd + virtio block disk; cpu/memory clamped to framework limits; entropy + balloon devices; guest serial console routed to stderr so boot problems land in the provider's captured diagnostics.
• Shares: virtio-fs tags workspace (rw), bundle (ro, the server bundle for automatic version parity), config (ro, per-boot credentials).
• vsock bridging: host-to-guest — a POSIX unix-socket listener per forward, each accepted connection dialed into the guest via VZVirtioSocketDevice.connect(toPort:); guest-to-host — VZVirtioSocketListener dials the host unix socket (where the egress broker listens). Bidirectional fd relays with proper half-close semantics.
• Protocol: argv[1] = VmConfig JSON; newline-delimited {"event":"state"|"error"} JSON on stdout; stop via stdin command, stdin EOF (parent death), or SIGTERM.
• Signing: bun run build:vzhelper builds and ad-hoc signs with the com.apple.security.virtualization entitlement for dev (--universal for arm64+x86_64); release packaging re-signs with the app identity when the desktop wiring lands.

The TS provider (src/vz/)

• protocol.ts — typed wire protocol + a line-buffering event reader (chunks may split/batch events arbitrarily).
• provider.ts — availability() enforces the plan's asymmetric policy: hard block below macOS 12 with the explanatory message (via macosSandboxAvailability, versions read from sw_vers), plus a helper-binary presence check. create() stages + unpacks the vz image tarball (vmlinux/initrd/rootfs.img, validated) and clones the instance disk copy-on-write via COPYFILE_FICLONE (APFS clonefile, plain copy fallback). start() writes the guest boot.json, waits for the helper's running event, then reuses the Phase 1 TCP→unix forwarder + health gate; failures carry the helper's stderr tail (guest serial console included). reset() just re-clones the pristine disk — instant, no re-download.

Verification

• 61 tests pass / 2 skip (the Phase 1 bwrap integration tests, skipped on macOS), 172 assertions. New vz provider tests spawn a fake helper process speaking the real protocol — real spawn, real unix-socket bridge, real HTTP health through the forwarder, stop→exit — plus error-event, timeout, missing-image-file, and availability-gate cases.
• bun typecheck clean.
• The real binary builds via bun run build:vzhelper and its error protocol was smoke-verified (cannot read config, invalid virtual machine configuration events with correct exit codes). Actually booting a VM requires the guest image from the image pipeline (parallel track) — the README documents the guest agent contract the image must implement (mount the three tags, run the bundle per boot.json, bridge vsock 4096/8788).

Notes

• Fork-only files throughout — no upstream edits, no DIVERGENCES.md rows needed this time.
• .build/ and dist/ are gitignored; the helper binary is built, not committed.
• Still no CHANGELOG entry — nothing user-facing until the desktop wiring phase.

🤖 Generated with Claude Code