bug(vm): per-sandbox Unix socket paths exceed macOS sun_path limit

[benoitf]

User Story

As a developer running the VM compute driver on macOS, I want per-sandbox Unix socket paths to fit within the OS sun_path limit so that sandbox creation does not fail with a socket bind error.

Problem Statement

The VM driver constructs per-sandbox Unix socket paths by joining {state_dir}/sandboxes/{sandbox_id}/{socket_name}. Sandbox IDs are UUID v4 strings (36 chars), and state_dir depends on the user's home directory. On macOS, struct sockaddr_un.sun_path is 104 bytes (103 usable). With the default state_dir (~/.local/state/openshell/vm-driver), the resulting socket path reaches 107 bytes — 3 bytes over the limit — and bind() fails.

/Users/benoitf/.local/state/openshell/vm-driver/sandboxes/3eb2ad45-bead-4c2e-bd10-1a4a7f3a2721/control.sock
└─────────────────────────────────── 107 bytes ──────────────────────────────────────┘

Path length breakdown:

/Users/benoitf/.local/state/openshell/vm-driver   (47)
/sandboxes/                                        (11)
3eb2ad45-bead-4c2e-bd10-1a4a7f3a2721               (36)
/control.sock                                      (13)
                                            total = 107 bytes
                                     macOS limit = 104 bytes
                                       over by 3 bytes

Impact / Why This Matters

When this happens, VM sandbox creation fails at the control socket bind step. The error surfaces as a low-level socket error, not as a clear path-length diagnostic.

The current workaround is to manually configure a short state_dir (e.g. /tmp/os-vm). or rename control.sock for ctl.sock for my case (as I reduced 3 extra chars)
This is non-obvious, fragile, and breaks persistence expectations. Any user whose home directory path is longer than /Users/benoitf (15 chars) would be even further over the limit.

Linux is less affected (108-byte limit) but not immune with deep state directories or longer usernames.

Acceptance Criteria

• Per-sandbox Unix socket paths fit within 103 usable bytes on macOS for any reasonable state_dir
• The fix does not break sandbox state directory layout or persistence/restore
• Existing sandbox directories remain discoverable (sandbox ID must still be recoverable from the filesystem)
• The gateway compute-driver socket path (run/compute-driver.sock) remains unaffected

Reproduction Steps

1. On macOS, start the gateway with --compute-driver vm using the default state_dir (~/.local/state/openshell/vm-driver)
2. Run openshell sandbox create --name test --from ubuntu:24.04
3. Observe the sandbox creation fails at the control socket bind

Environment

• OpenShell: development build (current main branch)
• OS: macOS (Apple Silicon) — sun_path is 104 bytes
• Runtime: VM compute driver (libkrun)

Logs

Error: bind() failed for /Users/benoitf/.local/state/openshell/vm-driver/sandboxes/3eb2ad45-bead-4c2e-bd10-1a4a7f3a2721/control.sock

[benoitf]

let me know which approach you want to take to have higher chances to use a sun_path <= 104 bytes
looks like 3eb2ad45-bead-4c2e-bd10-1a4a7f3a2721 is what we could cut easily

[krishicks]

📋 triage-agent

Triage Assessment

Classification: validated-bug

Summary

The issue is technically valid. The VM/libkrun path currently derives the per-sandbox host control socket as <state_dir>/sandboxes/<sandbox_id>/control.sock, and the reported default macOS-style path is 107 bytes. That exceeds the 103-byte usable sun_path budget on macOS, so sandbox creation can fail before the VM control path is established.

Investigation

• The default VM driver state directory is openshell_core::paths::openshell_state_dir()/vm-driver, which resolves to $HOME/.local/state/openshell/vm-driver when XDG_STATE_HOME is unset.
• crates/openshell-driver-vm/src/driver.rs constructs sandbox state with sandboxes_root_dir(root).join(sandbox_id) and then state_dir.join("control.sock") for the libkrun control socket.
• For libkrun launches, the driver passes that path through --vm-vsock-control-socket; crates/openshell-driver-vm/src/runtime.rs then passes it to krun_add_vsock_port2 via path_to_cstring without enforcing or shortening the AF_UNIX path length.
• The reported path length calculation is correct: /Users/benoitf/.local/state/openshell/vm-driver/sandboxes/<uuid>/control.sock is 107 bytes.
• I found no existing duplicate issue or merged PR/release note that addresses this specific VM per-sandbox control socket path length problem. The VM README documents that the mise run gateway:vm development task uses a short /tmp/openshell-vm-driver-$USER-vm-dev/ state path to stay under macOS SUN_LEN, which further supports that this is a known platform constraint, but the default configured driver path remains affected.

Impact Signals

• Affected users/scope: macOS VM-driver users with default or longer state paths; Linux can also be affected with sufficiently deep state directories, though its typical AF_UNIX path budget is slightly larger.
• Regression: unknown.
• Workaround: configure a shorter VM state_dir; this is non-obvious and may change persistence location.
• Evidence quality: high. The issue includes concrete reproduction steps and logs, and the current code path matches the reported path construction.

Human Decision Required

Decide whether OpenShell should address this issue. If yes, apply
state:accepted, associate it with a roadmap item, or do both, and decide
whether the work remains human-owned. Either action records acceptance;
roadmap placement additionally records sequencing.
To queue investigation or planning for an unattended agent, also apply
agent:plan-requested. You can instead directly ask an agent to use
create-spike or build-from-issue on this issue; the agent will warn about
missing expected workflow labels and continue without changing them. If no,
close it as not planned and record the rationale.