feat(compute): revive apple-container driver (rebased, review-clean, e2e on container 1.5)

[potable-anarchy]

Summary

Revives the apple-container compute driver originally proposed as #1888 by @shiju-nv, rebased onto current main and hardened in response to three adversarial reviews (codex-astra, claude-code, GLM-5.3-flash) and e2e testing on macOS 27 with Apple Container 1.5.0.

Marked Draft deliberately: the launch model predates main's supervisor/workload split (see B1 limitation below). The driver compiles, the gateway registers it, sandboxes boot and fail deterministically in the expected place — establishing a tested, review-clean base from which the supervisor/workload port can be done as a follow-up. Opening now for upstream direction.

Related Issues / PRs

• Revives feat(compute): add apple-container driver #1888 (closed stale 2026-06-15)
• Closes Add Apple Container as an OpenShell compute backend #1887

What this PR does

Adds an opt-in apple-container compute driver for local macOS gateways. The driver shells out to Apple's container CLI, wires the OpenShell supervisor into Apple Container guests, and keeps the runtime explicit-only so existing kubernetes / podman / docker auto-detection behavior is unchanged.

Porting work to current main since #1888

• Rebased onto main's ComputeDriverRegistry / factory composition model (refactor(compute): decouple gateway driver composition #2823 and successors). AppleContainerFactory in openshell-gateway/src/lib.rs registers "apple-container" (priority 400, no auto-detection, with_local_singleplayer(), telemetry category apple-container).
• Re-uses main's centralized guest-TLS resolution (require_guest_tls_for_local_driver + apply_guest_tls + context.guest_tls_paths()) rather than the original's per-driver gateway-TLS inheritance.
• Adopts the TOML driver table contract ([openshell.drivers.apple-container]) introduced with schema v2.
• Implements the four RPCs main's compute proto gained (refactor(compute): decouple gateway driver composition #2823-era): start_sandbox, ensure_workspace, delete_workspace, authenticate_sandbox (unimplemented — supports_sandbox_authentication = false).
• Returns runtime_identity and fence fields per the current CreateSandboxResponse / StartSandboxResponse protos.
• Reads GPU requirements from spec.resource_requirements.gpu.is_some() (the spec.gpu bool was removed on main).

Review-driven hardening

• Removed SupervisorReadiness trait and its sole AlwaysReadySupervisor impl. Main's ComposedPhase already gates Ready on supervisor-session presence driver-side; the additional trait was unreachable dead code.
• Removed openshell-server's dependency on the driver crate, restoring the backend-agnostic layering documented in openshell-gateway.
• Did not re-introduce ComputeDriverKind (removed upstream in refactor(compute): decouple gateway driver composition #2823); first-party drivers register telemetry categories via TelemetryComputeDriver::anonymous_category, as does this one.
• Scoped the new host.container.internal SAN to #[cfg(target_os = "macos")]. Without this guard, certgen::missing_required_server_sans would trigger a one-time local-CA rotation on every existing install on every OS (Linux/Podman included) the first time the upgraded package boots. This is the largest blast-radius fix in the PR.
• Unified feature-gating to cfg(all(target_os = "macos", feature = "compute-driver-apple-container")) on every reference (decl, factory, registration, tests).
• Gateway registry tests updated to be macOS-aware (assertions now correctly include apple-container in the allowed set on macOS only). Previously broken by the merge.
• Cargo.lock deltas are limited to the new crate and its direct path deps (no incidental aws/tokio/landlock churn).
• Partial-launch cleanup on container run --detach failure now deletes the container before deleting its volume and staged credentials.
• Watch polling loop checks tx.is_closed() each tick so a dropped watcher terminates the spawned task.
• MAX_CONTAINER_NAME_LEN corrected from 64 → 63. Apple's container ID cap is 63; at 64 the gateway emitted container names that the runtime rejected (found in e2e).

B1 limitation (known, intentional, and not hidden)

This driver cannot fully start a working sandbox on current main. The entrypoint it mounts (openshell-sandbox) no longer accepts the legacy sleep infinity argv model that #1888 was written against. Today's openshell-sandbox expects BoundaryArgs { --bootstrap <path> } and runs capability-probe subcommands next to a separately launched trusted /openshell-supervisor, with the workload in network=none. That model is what openshell-driver-podman/src/container.rs:1515-1640 implements.

E2E evidence (macOS 27, container CLI 1.5.0, gateway 0.0.1-dev.1564+g<sha>):

1. openshell-gateway --compute-driver apple-container boots clean, logs Compute driver connected configured_driver=apple-container advertised_driver=apple-container.
2. openshell gateway add + openshell status establish mTLS transport successfully.
3. openshell sandbox create --name a is accepted, the gateway stages volume/JWT/guest-TLS, mounts supervisor_bin_dir, and invokes container run --detach … --entrypoint /opt/openshell/bin/openshell-sandbox … debian:bookworm-slim sleep infinity. The Apple Container guest launches.
4. Inside the guest, openshell-sandbox exits via clap with error: unexpected argument 'sleep' found — visible by running the same entrypoint locally on macOS.
5. The driver maps the stopped container to phase=Error (ContainerStopped: Apple container is stopped) and openshell sandbox list reports it as such. Not silent, credential-inconsistent, or restart-churning.

So the failure surface is exactly what reviewers predicted for the June model being revived onto the post-split supervisor/workload architecture: compile-clean, integration-clean, runtime-blocked.

Why open it anyway

• The scaffolding around the launch path (registry wiring, driver crate, guest-TLS integration, gateway registration, TOML contract, tests) is real and independent of which launch model the final driver uses.
• Two reviewers note that the right frame for the launch-port is "follow podman/container.rs", which is a focused piece of work in one file once the rest of the plumbing is upstreamed.
• The PR title on feat(compute): add apple-container driver #1888 (feat(compute): add apple-container driver) matches what we want the merged end-state to be; a Draft PR is the honest way to mark intermediate progress.

How to test on a Mac (today)

# Build a Linux aarch64 supervisor binary
rustup target add aarch64-unknown-linux-musl
brew install filosottile/musl-cross/musl-cross
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=aarch64-linux-musl-gcc \
  cargo build --release -p openshell-sandbox --target aarch64-unknown-linux-musl
install -m 0755 target/aarch64-unknown-linux-musl/release/openshell-sandbox \
  /tmp/supervisor-bin/openshell-sandbox

# Gateway configuration (~/.config/openshell/gateway.toml)
[openshell]
version = 2
[openshell.gateway]
name = "trybox-test"
compute_driver = "apple-container"
guest_tls_ca = "/path/to/ca.crt"
guest_tls_cert = "/path/to/client/tls.crt"
guest_tls_key = "/path/to/client/tls.key"
[openshell.gateway.gateway_jwt]
signing_key_path = "/path/to/jwt/signing.pem"
public_key_path = "/path/to/jwt/public.pem"
kid_path = "/path/to/jwt/kid"
[openshell.drivers.apple-container]
default_image = "debian:bookworm-slim"
supervisor_bin_dir = "/tmp/supervisor-bin"

cargo run --release -p openshell-gateway -- --config <path> --db-url sqlite:////tmp/test.db
openshell gateway add https://127.0.0.1:17670 --local
openshell sandbox create --name a -- echo hello
openshell sandbox list   # shows Error / ContainerStopped as expected per B1

Follow-up work (post-merge or follow-on PRs)

• Port the launch path to main's supervisor/workload split (workload launches with network=none, the supervisor runs as a separate trusted process with networking, bootstrap via --bootstrap <path>). Reference: openshell-driver-podman/src/container.rs:1515-1640.
• Bounded subprocess execution in cli.rs (each container invocation has no timeout and no kill_on_drop).
• Workspace identifiers in container/volume names and labels (DriverSandbox.workspace).
• docs/how-it-works/gateways/configuration.mdx section for [openshell.drivers.apple-container] and a runtimes entry under docs/how-it-works/sandboxes/runtimes.
• Optional: plumb SupervisorSessionRegistry through ComputeDriverBuildContext so driver-reported conditions can reflect supervisor-readiness honestly. (Currently the driver reports a constant "running" condition and lets the gateway's ComposedPhase do the gating, which is consistent with docker's behavior.)

Verification done by the author

• cargo check --locked clean on macOS arm64 (aarch64-apple-darwin).
• cargo test --lib green across openshell-{core, bootstrap, gateway, server, driver-apple-container} (≥2,534 tests passing, including new registry tests).
• cargo fmt --check clean on all touched crates.
• Live e2e against Apple Container 1.5.0 — see B1 evidence section above.
• Adversarial reviews by three independent LLMs (codex-astra, claude-code, GLM-5.3-flash); all findings except the supervisor/workload architectural issue either resolved or explicitly deferred to follow-ups above.

Co-authored-by: Shiju shiju@nvidia.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

Thank you for your interest in contributing to OpenShell, @potable-anarchy.

This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer.

To get vouched:

1. Open a Vouch Request discussion.
2. Describe what you want to change and why.
3. Write in your own words — do not have an AI generate the request.
4. A maintainer will comment /vouch if approved.
5. Once vouched, open a new PR (preferred) or reopen this one after a few minutes.

See CONTRIBUTING.md for details.

[github-actions]

Thank you for your submission! We ask that you sign our Developer Certificate of Origin before we can accept your contribution. You can sign the DCO by adding a comment below using this text:

---

I have read the DCO document and I hereby sign the DCO.

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the DCO Assistant Lite bot.}