macOS guests 3/6: Darwin guest service, readiness and exec

[chruffins]

Summary

PR 3 of 6: Darwin shared GuestService, readiness, exec, and file copy for macOS guests. Base: #499.

• The shared GuestService listens on host-CID vsock 2222 on Darwin. The Linux transport is unchanged.
• A root system agent (LaunchDaemon) with an explicit shutdown policy. Readiness is probed and persisted. Boot markers are committed only for the boot they were probed for, and a stopped boot never gains readiness.
• A lost shutdown reply during a stop still waits for power-off, so a macOS guest is not force-killed while it is powering off. A strict stop (used by build export) requires an acknowledged shutdown and owned VMM exit. A normal stop falls back to forced hypervisor shutdown after its timeout.
• Exec and file copy are gated on the agent declared by the image. Exec TTY and non-TTY modes share one lifecycle. Cancellation kills the process group, and output drains are bounded.
• Linux behavior: exec still does not cancel on client disconnect. A TTY command whose output stays open after the shell exits now reports its status after a bounded drain instead of waiting indefinitely.
• Stat is served by the same agent.
• Readiness probes for macOS guests no longer evict the shared guest connection on a retryable error. Concurrent callers (for example a restore readiness wait) were losing in-flight RPCs to Canceled.

Validation

• Live, in an isolated QA guest with a root agent installed by hand: UID 0 exec in TTY and non-TTY modes, root file round-trip with exact bytes, timeout with descendant cleanup, readiness persisted, normal stop with acknowledged shutdown and no forced fallback.
• Race-tested unit suites for the guest agent, exec, boot markers, and shutdown policy.
• Cross-compiles for Linux and Windows for the agent package. Windows is not functional yet (see PR 3 limitations).

Limitations

• The root agent is installed manually. There is no image-level installer or automatic provisioning.
• Windows support is a compile check only. Process-tree kill, the vsock listener, and the ready path are stubs that return explicit errors.
• Vsock accept polls at 10 ms.

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

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

[cursor]

Read wraps EOF as OpError

Low Severity

vmConn.Read wraps every os.File.Read failure, including bare io.EOF, in net.OpError. Standard net.Conn implementations leave io.EOF unwrapped, and gRPC/HTTP2 compare with == io.EOF for a clean close. Guest disconnects can be treated as transport errors instead of orderly EOF.

 

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

[chruffins]

Real native Darwin GuestService2222 QA passed in an isolated cold-booted OCI guest using the current shared binary, user-launched at UID501 only. Host shared client verified id -u=501, synthetic file copy-to/from exact bytes, and client deadline cancellation of shell + sleep descendant (child PID no longer existed). Three repeated race runs passed. Shutdown correctly returned PermissionDenied for nonroot; guest remained running. Fixed two QA harness assumptions before the passing run: CopyFromInstance's destination is a directory, and deadline may surface as gRPC DeadlineExceeded rather than errors.Is(context.DeadlineExceeded).

Root daemon was not installed: guest noninteractive sudo is unavailable and no privileged provisioning was performed. System image capability remained false. These results prove native transport/user-level exec/files/cancellation and shutdown admission, not normal API system-agent installation/readiness or successful graceful root shutdown. Those remain gates. Original guest/API/storage untouched; isolated QA VM ended stopped.

[chruffins]

Simplification update at 243ce9a: common command setup/process-group cancellation and bounded wait/drain/final-status handling for both TTY modes. Permanent tests cover pre-cancelled starts and failed output sends cancelling/reaping commands. Full agent/client race suites passed 3 runs; combined post-restack focused suites also passed 3 runs. Base changed to feat/macos-oci-images so the image rollback fix and bundle consolidation are inherited once rather than duplicated. Root provisioning remains undone.

All PRs remain draft. This is source-level/synthetic validation, not a new live boot or production build proof. Default Codex independent review was attempted but is still blocked by authentication (HTTP401). Published atomically after checking reviewer heads with explicit per-ref force-with-lease; prior heads preserved locally.

[chruffins]

Root QA follow-up pushed as ae3685d; desktop restacked atomically with explicit leases. Manually installed shared system-role agent survived isolated normal-API cold boots. Repeated race-instrumented authenticated API tests verified UID0 exec (both TTY modes), root-owned0600 file copy round trips, and descendant cancellation. Live testing reproduced and fixed Darwin readiness using the nonexistent /bin/true; /usr/bin/true now probes successfully and normal GET persists GuestAgentReadyAt without a Linux workload marker. Fixed premature shutdown fallback after a lost Darwin RPC reply: configured grace period is retained while still requiring owned VMM exit; Linux policy is unchanged. Final normal API stop accepted the RPC and confirmed VMM exit/storage closure without forced fallback. Corrected stale opt-in test calls left after runtime simplification. Focused instances/API/agent/client tests pass race,count3; default independent autoreview remains401-blocked. Manual QA provisioning is not automatic image installation or end-to-end build/publication proof. PR remains draft.