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

[chruffins]

Summary

PR 4 of 6: stopped snapshots, same-instance standby/restore, and cold forks of stopped instances or snapshots. Base: #500.

• Create stopped disk snapshots only after a confirmed graceful stop. Restore requires the same instance, machine identifier, hardware model and MAC; stage swaps outside the guests directory with rollback and crash recovery.
• Support experimental same-instance memory standby/restore. Memory snapshots and independent memory forks remain unsupported.
• Fork a gracefully stopped instance or stopped snapshot only with an enabled guest agent. Copy disk and auxiliary storage, generate a fresh VZ machine identifier and a fresh MAC when networking is enabled, then rekey SSH host keys on first start. A failed rekey stops the VM and is retried on the next start.
• Snapshot forks default to Stopped; Running cold-boots through the same identity/rekey path. Clear inherited readiness markers and reset macOS clone phase accounting. Reject incompatible target backends before copying files.
• Recheck clone MACs at serialized metadata admission. Use metadata-only name checks for NAT-backed macOS forks; leave Linux network-registry checks unchanged.
• Persistently clear graceful-stop receipts before boot; enforce identity/MAC admission during restore; use uncancelable teardown for failed rekeys.

Validation

• All six layers pass build, targeted vet, relevant instance regression tests and targeted API tests. Relevant tests also pass with -race.
• Darwin/arm64 source and test type-checks pass using a cgo-stub checker; this is not native execution.
• Admission tests cover stopped kind, graceful receipt, enabled agent and incompatible backend rejection before copying. Existing staged-swap tests cover rollback and interrupted-swap recovery.
• Added a Darwin metadata test for two independent snapshot forks: distinct machine IDs/MACs, readiness reset, clean phase accounting, duplicate-name rejection, backend configuration validation, auxiliary-storage copying and disk-write independence. This test has been type-checked, not run natively here; it does not boot a guest.
• The new stopped-snapshot fork path has not been exercised against a live macOS guest here.

Limitations

Saved-state restore is experimental and may fail; failure leaves the instance in Standby. Hostname, account credentials and application-specific identities are outside the SSH-key rekey contract. Memory snapshot forks and cross-host saved-state portability remain unsupported.

Stack

#498 runtime and lifecycle → #499 OCI images → #500 guest service → #506 snapshots and stopped forks → #503 image builds → #501 guest-port forwarding.

[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.}

[cursor]

Stale graceful receipt after start

Medium Severity

StopGraceful is cleared only in memory at the start of startInstance and persisted after the VM is already running. A crash or a failed saveMetadata in that window leaves the prior graceful receipt on disk, so a later stopped snapshot can capture a disk that is no longer consistent.

Additional Locations (1)

• lib/instances/start.go#L206-L210

 

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