bug(vm-driver): driver startup fails with a bare "path must be shorter than SUN_LEN" and does not name the path

[shiju-nv]

User Story

I use OpenShell with the MicroVM compute driver. I directly encountered a gateway that failed to start after I pointed XDG_STATE_HOME at a long directory. This affects anyone whose OpenShell state directory is deep enough that the driver's socket path does not fit the operating system's Unix socket limit.

Problem Statement

When the VM driver starts, the gateway gives it a control socket at <state_dir>/run/compute-driver.sock. If that path is longer than the operating system's Unix socket path limit, the driver exits with path must be shorter than SUN_LEN. The message does not include the path, its length, the limit, or the setting that controls it. The gateway then reports a second error, vm compute driver exited before becoming ready with status exit status: 1, which does not mention the path either.

The limit comes from the operating system. Per unix(7), a Linux socket path holds 107 bytes plus the terminating NUL; on macOS it holds 103. The code that builds this path is not platform-specific, and the error text matches the message in the socket2 crate, which is also cross-platform. I observed the failure on macOS only and did not run it on Linux.

Per-sandbox sockets already get a clear error. create_sandbox_socket_dir in crates/openshell-driver-vm/src/driver.rs fails with socket path <path> exceeds sun_path limit (103 bytes), so the driver's own socket is the one without that check.

Impact / Why This Matters

The gateway does not start, and the only clue is a socket-library error name. A user has to know that SUN_LEN refers to the Unix socket path limit, work out which path the driver builds, and find that [openshell.drivers.vm] state_dir or XDG_STATE_HOME moves it. A default state directory (~/.local/state/openshell/vm-driver) is short for a typical account name: the full socket path was 69 bytes for an account named usera. Long account names, custom state directories, and deep checkout or workspace paths are the cases that hit this. In my test the path was 140 bytes.

Acceptance Criteria

• When the driver's socket path exceeds the limit of the platform it runs on, the error names the full path, its length in bytes, and the limit.
• The error names the setting or environment variable that moves the path ([openshell.drivers.vm] state_dir, XDG_STATE_HOME).
• The gateway's follow-up error includes that message instead of only the driver's exit status.
• A path at or under the limit still starts normally.

Reproduction Steps

1. Create a gateway config with compute_driver = "vm".
2. Set a long state directory so that <state>/openshell/vm-driver/run/compute-driver.sock is longer than the platform limit. On macOS, for example: export XDG_STATE_HOME=/Users/<you>/some/deeply/nested/project/directory/that/is/more/than/seventy/characters/state.
3. Start the gateway: openshell-gateway --config gateway.toml.
4. Observe the two errors under Logs. Set XDG_STATE_HOME to a short directory such as /tmp/os-state and the gateway starts.

Suggested UX (if applicable)

Error: VM driver control socket path is 140 bytes, over the 103-byte limit on this platform:
  /path/to/openshell/vm-driver/run/compute-driver.sock
Set [openshell.drivers.vm] state_dir or XDG_STATE_HOME to a shorter directory.

Environment

• OpenShell: 0.1.3-dev.82+g8983642e2 (rolling dev pre-release, commit 8983642e2)
• OS: macOS 26.7, Apple Silicon (arm64). Linux was not tested.
• Deployment: local gateway from the release archives, compute_driver = "vm", driver in libexec

Logs

INFO openshell_driver_vm: Starting vm compute driver socket=/path/to/xdg/state/openshell/vm-driver/run/compute-driver.sock
Error:   × path must be shorter than SUN_LEN

Error:   × execution error: vm compute driver exited before becoming ready with
  │ status exit status: 1

[benoitf]

might be related to #3452

[shiju-nv]

Thanks. It is the same limit but a different socket, which is why #3544 did not cover it.

PR #3544 moved the per-sandbox sockets (control.sock, ssh.sock) to a short random directory under /tmp. The socket in this issue is the driver's own control socket, <state_dir>/run/compute-driver.sock.

I reproduced this on the dev pre-release 0.1.3-dev.82.