Detect missing microVM host tools before sandbox creation

[shiju-nv]

User Story

As an operator setting up OpenShell's microVM backend on a Mac, I want to check its required host tools before starting the gateway, so I can fix the installation before anyone tries to create a sandbox.

Problem Statement

The VM driver needs host filesystem tools to prepare and recover sandbox disks: mke2fs or mkfs.ext4, debugfs, and e2fsck. openshell-gateway config preflight validates gateway configuration but does not currently check whether these tools are available and usable.

Impact / Why This Matters

An operator can pass configuration validation and still discover a missing dependency during sandbox creation or recovery. Checking tools in an interactive terminal is insufficient when the gateway service uses a different account or PATH. Operators must diagnose those differences during provisioning and reproduce the fixes across managed Macs.

Proposed Design

The operator runs preflight with the gateway's intended configuration, account and environment. It uses the VM driver's tool lookup rules, reports selected executable paths, and checks that tools start and report supported versions. A failure identifies the tool, preserves its error, and explains what to install or fix. The operator corrects the dependency and reruns preflight before launching the gateway.

OpenShell documents the required tools; the operator installs and manages them. Preflight runs without downloading images, creating disks, starting a VM, or initializing gateway state. Its result applies to the host and environment where it ran.

Acceptance Criteria

• Preflight for a local VM configuration checks a formatter (mke2fs or mkfs.ext4), debugfs, and e2fsck, and reports their selected paths.
• Missing, non-executable or unsupported tools produce a nonzero exit and specific corrective guidance. A selected tool's execution error is retained.
• Tool checks finish within a bounded time and create no gateway or sandbox state.
• Documentation shows operator installation and running preflight in the gateway's intended environment, including a service with a restricted PATH.
• Other drivers do not require VM filesystem tools. Preflight identifies checks it cannot perform locally, such as tools on a remote driver host.

Alternatives Considered

Documentation alone leaves the dependency unchecked. PR #3477 already proposes the discovery change.

Agent Investigation

Source review found existing configuration validation and VM tool lookup code. The change should share lookup rules with image operations and preserve preflight's ability to run without starting a driver. #3400 and #3477 cover related discovery work.

Checklist

• I've reviewed existing issues and the published docs
• This is a design proposal, not a "please build this" request

[purp]

We've considered this issue before (#2308) and declined to supply this host system dependency. What's a reasonable alternative to help an installer/operator make sure they've got what they need installed?

[shiju-nv]

The problem I want to avoid is someone getting OpenShell running, then finding out during sandbox creation that the VM driver can't find or run the filesystem tools. A preflight using the same tool lookup and service environment as image preparation would help: check mke2fs or mkfs.ext4, plus debugfs, show the paths it found, and explain what to install or fix before image preparation starts.

OpenShell can use the existing create-validation hook to run each tool with -V and check that it starts and reports a supported version.

[purp]

Makes sense. This feels like something openshell-gateway config preflight should catch and call out. Would accept an issue/PR that added it. (so if you want to revise this issue to propose that ... =)