macOS guests 4/6: snapshots, schedules and stopped forks

[chruffins]

Summary

PR 4 of 6. Snapshots, standby and stopped clones for macOS guests. Base: #500.

• Stopped snapshots and cold clones: these require a confirmed graceful stop. A clone gets a fresh machine identifier, a MAC assigned under the fork admission lock, and an SSH host key rekey on first start. A failed rekey stops the clone and is retried on the next start.
• Memory snapshots of Running or Standby instances: the exact VZ configuration is validated before pausing, and disk, auxiliary storage and machine state are captured while the VM is down. A formerly Running source resumes afterwards, even if the request is cancelled.
• Same-instance restore and standby: the payload is validated before anything is replaced, then metadata and storage are swapped in together, with crash recovery.
• Interrupted restore: if the API dies mid-restore, the leftover VM comes up Paused; POST /restore resumes it and finishes the restore (records the shim, deletes the consumed checkpoint).
• Snapshot schedules and retention use the existing controller.
• Boot admission: start and restore check machine identity and MAC uniqueness under one boot lock.
• Warm memory forks are rejected. VZ restores saved state only into an identical configuration (MAC, machine identifier, NIC and auxiliary storage), and Apple documents concurrent VMs sharing an identifier as undefined. Repeated same-instance restore is the warm start.

Linux code touched

• lib/instances: snapshot, standby, restore, fork, start and stop gain macOS hooks; manager.go resumes Paused instances through a macOS completion hook and recovers interrupted restore staging at startup.
• lib/hypervisor/vz/client.go: save/restore support probing; tracing.go forwards it.
• lib/network/allocate.go: NewUniqueMAC, so macOS clones share the allocator's uniqueness rule.

Not supported

Memory-snapshot compression, warm memory forks, and snapshots carried to another host or user account (VZ saved state is tied to both). Clones change machine identifier, MAC and SSH host keys only; hostname and accounts are copied.

Testing

• Filesystem and mock tests cover capture, restore, isolation, manifest checks, crash-swap recovery, cancellation, schedules and retention. HTTP fixtures cover VZ pause and configuration probing.
• Native QA ran on Apple silicon (macOS 27.0.1 host and guests) across six runs plus a VZ restore spike. The simplification pass after run 6 has not been re-run natively yet. This PR's paths covered there: memory checkpoint, change and restore (same PID and boot session), repeated restore, Standby/Stopped targets, cancellation after pause, API crash mid-restore, schedules with retention, cold forks with distinct identities, and the VZ restore-compatibility spike behind the warm-fork decision.

Review focus

• lib/instances/snapshot_macos.go (staged swap, recovery, finishMacOSResume).
• lib/instances/macos_identity.go (clone identity, MAC assignment, rekey teardown).

Stack

Each PR is one commit on the one below it. macOS logic lives in its own files (macos*.go, *_darwin.go, exec_lifecycle.go, port_forward.go); shared Linux files get small hooks such as if stored.MacOS != nil.

1. macOS guests 1/6: VZ runtime, machine images and instance lifecycle #498 VZ runtime, machine images and instance lifecycle
2. macOS guests 2/6: OCI machine-image integration #499 OCI machine images
3. macOS guests 3/6: Darwin guest service, readiness and exec #500 Darwin guest agent, readiness and exec
4. macOS guests 4/6: snapshots, schedules and stopped forks #506 snapshots, standby and stopped clones
5. macOS guests 5/6: guest-port forwarding #514 guest-port forwarding
6. macOS guests 6/6: experimental machine-image builds #503 machine-image builds (not needed for v0; can land later)

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

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

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8a79efe. Configure here.}