feat(preflight): add a Python virtual-environment readiness probe #1578

Summary

Add an opt-in python3-venv probe to --preflight-tools and run.preflightTools so a run can distinguish a working python3 executable from a Python installation that cannot create a pip-enabled virtual environment.

Keep the probe diagnostic only. It should not install packages, modify Python, or prevent the workload from running.

Problem to solve

The current python3 preflight probe proves only that the literal interpreter starts and reports a version. A clean runner can pass that probe but still fail before project setup because its distribution splits venv or ensurepip into another package.

This reproduces against exact current main. The candidate probe name is rejected before provider work:

$ ./crabbox-main run --preflight --preflight-tools python3-venv --no-sync -- true
unknown preflight tool "python3-venv"

The command exits 2 without acquiring a lease. On a fresh Ubuntu 26.04 ARM64 local-container lease, the existing probe reports Python as present:

remote preflight python3=Python 3.14.4

The workload then fails when it tests the capability that setup actually needs:

$ python3 -m venv /tmp/crabbox-preflight-venv
The virtual environment was not created successfully because ensurepip is not available.

Crabbox returns the workload's exit 1 and cleans up the one-shot lease. The missing signal is available only after the user has provisioned a machine and started setup.

The distinction matters for Python test and type-check workflows. An interpreter version does not establish that the runner can create an isolated environment, seed pip, and invoke both environment-local Python and pip.

Proposed behavior

• Accept python3-venv anywhere Crabbox accepts built-in preflight tool names.
• On supported POSIX and WSL2 targets, run a bounded functional probe that creates a disposable virtual environment with pip, invokes the environment's Python and pip, and removes the temporary directory on success or failure.
• Report stable diagnostic states that distinguish a missing python3 executable from a present interpreter whose venv or pip seeding is unavailable.
• Keep an unavailable capability diagnostic-only, consistent with existing tool probes. The workload must still run.
• Keep the probe opt-in unless a separate product decision changes the default set.
• Preserve the current literal python and python3 probes unchanged.

The linux-builder readiness profile already defines the relevant functional contract. Its python3-venv capability creates a temporary pip-enabled environment, invokes its Python and pip, and cleans up. The run preflight probe should align with that observable contract without coupling run telemetry to image-manifest state.

Acceptance criteria

• --preflight-tools python3-venv validates, and run.preflightTools: [python3-venv] accepts the same probe through repository and user configuration.
• A target where python3 can create a pip-enabled venv reports the capability as ready.
• A target where python3 exists but venv or ensurepip is unavailable reports a distinct unavailable state rather than reporting Python missing or ready.
• A target without python3 reports the interpreter as missing.
• Missing or unavailable states do not fail or skip the workload.
• The probe leaves no temporary virtual environment after success, ordinary failure, interruption, or timeout.
• default,python3-venv,python3-venv emits the ordinary default probes plus one virtual-environment result.
• Existing python and python3 output, default probe selection, and target filtering remain unchanged.
• Unknown names still exit 2 before a lease or provider resource is created.
• Tests cover validation, configuration round-tripping, deduplication, target filtering, ready, interpreter-missing, venv-unavailable, pip-seeding failure, cleanup, and the unchanged unknown-name guard.
• Run, observability, and configuration documentation describes the probe's functional and diagnostic-only semantics.

Affected area

• The preflight registry, target filtering, and probe generation in internal/cli/run_observability.go.
• Preflight validation, configuration, state, and cleanup coverage in internal/cli/run_test.go.
• docs/commands/run.md, docs/observability.md, and the run.preflightTools configuration documentation.

Non-goals

• Installing python3, python3-venv, ensurepip, pip, or any project dependency.
• Selecting, activating, or reusing a project's existing virtual environment.
• Replacing the literal python or python3 version probes.
• Adding virtual-environment readiness to the default probe list.
• Turning a failed capability probe into a failed workload.
• Changing provider bootstrap, prebaked-image selection, or the Linux readiness-manifest contract.
• Validating Poetry, PDM, Conda, Hatch, tox, nox, uv-managed environments, or application imports.

Alternatives considered

Infer venv readiness from python3 --version

The clean Ubuntu reproduction shows why this is insufficient: Python 3.14.4 starts normally while python3 -m venv fails because pip seeding is unavailable.

Require a custom shell probe

A project can run the functional check itself, but the result arrives after provisioning, uses project-specific output, and cannot be reused through Crabbox's normalized run.preflightTools configuration.

Infer the capability from a Linux readiness manifest

The linux-builder manifest proves the capability for images that carry and pass that exact profile. Raw workspaces, third-party images, static SSH hosts, and other selected targets still need a live probe from the workload environment.

Supporting context

• Latest published release baseline: v0.46.0 at 8ba71f913bbe57285ae29af45ef0d8ec6712477d.
• Exact current main: 7e2d0288ed7f8a22751e844ed93175d1e2457cec.
• Current-main binary SHA-256: c63410e13ae4a1c64c8ef6470c15be3036add8896e3cabdc0d6a0162179b8dcc.
• Build metadata: vcs.revision=7e2d0288ed7f8a22751e844ed93175d1e2457cec, vcs.modified=false.
• Build toolchain: go1.26.5 darwin/arm64.
• Live current-main reproduction: Ubuntu 26.04 ARM64 through local-container, run run_6dac11442a05; the workload exited 1 and lease cleanup reported stopped=true.

The complete 71-commit range from the published release baseline through exact current main, the complete live corpus of 26 open issues, all 18 open issues authored by coygeek, all 19 open pull requests, and relevant closed issues and merged pull requests were checked. No current item adds or requests a Python virtual-environment preflight probe.

Closed issue #1243 and merged pull request #1347 added the literal python and python3 probes while explicitly leaving virtual-environment detection out of scope. Merged pull request #1444 added the functional pip-enabled venv check to the linux-builder readiness profile while explicitly leaving runner telemetry unchanged. This request exposes that existing capability contract through opt-in run preflight without changing either completed feature's boundary.