Add v3 host-backed container runtime foundations

[groundwater]

Summary

• add an opt-in host-backed container runtime for NAT-based GhostVM guests
• host container VMs in one application-scoped XPC service per helper, isolated from the macOS guest VM process
• share a helper-owned vmnet network across the macOS VM and container VMs with explicit IPAM and serialized network capability handoff
• ship the ghost-container guest CLI with stdin, native PTY allocation, terminal resize, exit propagation, and protocol v1 compatibility
• add read-only guest directory mounts through a loopback bridge and the GhostVMFS FSKit extension
• add backend-neutral runtime, networking, and content-store foundations plus protocol documentation
• update macOS 26 build, signing, packaging, and product requirements

Architecture

The helper owns the macOS VM, shared vmnet network, endpoint allocation, guest filesystem bridge, and vsock container bridge. A single embedded ghostvm-container-runtime.xpc service hosts all container VMs for that helper and reconstructs the vmnet network from its serialized capability. Container runtime failure therefore does not terminate the macOS VM.

Image preparation runs in the short-lived ghostvm-image-fetch helper. Guest bind mounts are exposed read-only through GhostTools, bridged over loopback to the sandboxed GhostVMFS extension, and mounted into the container VM.

Guest CLI

/Volumes/GhostTools/ghost-container run -it \
  registry-1.docker.io/library/ubuntu:24.04 /bin/bash

Supported options in this slice:

• -i, --interactive
• -t, --tty
• -it / -ti
• -v GUEST_PATH:CONTAINER_PATH:ro

TTY mode uses a native Containerization PTY, forwards SIGWINCH, restores local terminal state on exit/signals, and preserves PTY bytes while normalizing host diagnostic newlines.

Requirements

• macOS 26 or later on Apple silicon
• NAT Shared VM networking
• Host-backed Containers enabled for the VM
• GhostVMFS enabled for guest bind mounts

Verification

• xcodebuild test passed: 182 GhostVM tests
• swift test passed: 103 GhostTools tests
• full signed Debug GhostVM app build passed, including GhostVMFS, image-fetch, and runtime XPC targets
• signed/notarized distribution build passed, including stapling and strict signature validation
• embedded runtime XPC self-test passed
• physical Apple silicon validation reached an interactive Ubuntu /bin/bash prompt through ghost-container run -it
• protocol, policy, input framing, terminal resize, newline normalization, filesystem metadata/readlink, IPAM, and content-store tests are included

Remaining Validation

• exercise read-only guest bind mounts, including symbolic links, on a physical macOS 26 host with GhostVMFS enabled
• kill the runtime XPC process during a long-running container and verify the macOS VM survives and a subsequent run relaunches the service
• complete security review of the loopback FSKit capability boundary

Scope

This establishes the v3 runtime foundations and one-shot container execution path. Persistent container lifecycle APIs, port publishing, environment forwarding, image builds, and a broader Docker-compatible adapter remain follow-up work.

Supersedes #262, whose base branch and /usr/local/bin/container architecture are obsolete.