feat(preflight): add an opt-in Bash version probe

[coygeek]

Summary

Add bash as an opt-in name accepted by --preflight-tools and run.preflightTools on POSIX and WSL2 targets. Report the resolved Bash version in Crabbox's normalized pre-command capability snapshot without installing Bash or changing the workload.

Problem to solve

Crabbox can report Go, Cargo, Make, CMake, Python, and JavaScript tool versions, but it cannot report the Bash version used by shell tests and build scripts. Exact current main rejects the conventional command name before provider work:

$ crabbox run --provider local-container --no-sync \
    --preflight --preflight-tools bash -- true
unknown preflight tool "bash"
$ echo $?
2

The provider inventory remains empty after the rejection.

This matters when a project depends on Bash behavior rather than generic POSIX shell syntax. During a clean mvdan/sh v3.14.0 verification, host-confirmation tests disagreed between macOS and Linux builds of Bash 5.3.9. The clean runner had to print bash --version from an uploaded script because the requested preflight probe was unavailable. A version result would not replace behavioral tests, but it would bind their outcome to the actual shell runtime instead of leaving that runtime implicit.

Crabbox's POSIX capability snapshot itself currently invokes bash -lc. A host without Bash therefore produces a generic preflight failure before any per-tool result can identify the missing prerequisite.

Proposed behavior

• Accept bash as an opt-in built-in preflight name on Linux, macOS, and WSL2.
• Probe the literal bash --version command and report its first bounded output line when present.
• Report a stable Bash-unavailable result when the command is missing, without converting the diagnostic probe into a workload failure.
• Keep bash out of the default probe list.
• Preserve exit 2 before acquisition for names that are not in the registry.
• Skip native Windows unless the project adopts a separate literal Bash command contract there.

The missing-command behavior must account for the current Bash-dependent POSIX preflight wrapper. A requested Bash probe should not collapse into an unclassified remote preflight failed message.

Acceptance criteria

• --preflight-tools bash validates on Linux, macOS, and WSL2.
• run.preflightTools: [bash] accepts the same probe from repository and user configuration.
• A target with Bash reports the first bounded line from bash --version before the user command starts.
• A target without Bash reports a stable unavailable state and still runs a user command that does not require Bash.
• default,bash,bash emits the ordinary default probes plus one Bash result.
• Native Windows skips the probe unless a separate supported command contract is defined.
• Bash remains opt-in and Crabbox never installs, upgrades, or selects a shell.
• Unknown names still exit 2 before a lease or provider resource is acquired.
• Tests cover name validation, configuration, deduplication, target filtering, present and missing Bash, the Bash-dependent POSIX wrapper, and the unchanged unknown-name guard.
• Run, observability, and configuration documentation lists the probe and its target support.

Affected area

• Preflight registration, validation, target filtering, and POSIX command generation in internal/cli/run_observability.go.
• Preflight behavior and configuration coverage in internal/cli/run_test.go.
• docs/commands/run.md and docs/observability.md.

Non-goals

• Adding Bash to the default preflight list.
• Installing Bash or changing the target's default shell.
• Treating a version string as proof that a script behaves correctly.
• Probing Zsh, Dash, mksh, BusyBox, Fish, or PowerShell in this request.
• Running a project script as part of the probe.
• Defining a native-Windows Git Bash or MSYS2 discovery policy.

Alternatives considered

Print the version in every workload

An uploaded script can run bash --version, but each workflow must recreate the check and parse its output. The result is absent from Crabbox's normalized preflight snapshot and cannot be selected through run.preflightTools.

Probe sh

The sh command may resolve to Dash, Bash in a compatibility mode, BusyBox, or another implementation. It does not establish the Bash runtime used by a Bash test suite.

Add Bash to the default set

Many workloads do not depend on Bash identity. An opt-in probe keeps the default output stable and follows the existing language and build-tool pattern.

Supporting context

• Latest release baseline: v0.47.0 at 0a55378990265271f5830a465aa643605d7d41f3.
• Exact current main: 905553ffd3999a1ccfc4ac9e1528169055cb3229.
• Current-main binary SHA-256: db3c2709501209966e1ad1c5beedfe41176978a66ea8d70e0831aafeb090a999.
• Build toolchain: go1.26.5 darwin/arm64.

The complete seven-commit range from the release baseline through exact current main, the complete live open-issue and open-pull-request corpora, every open issue authored by coygeek, and relevant closed issues and merged pull requests were checked. No current item adds or requests a Bash version preflight probe.

Closed issue #1243 and merged pull request #1347 added the literal Python probes. Closed issue #1394 and merged pull request #1402 added the analogous CMake probe. Those changes establish the opt-in literal-command pattern while keeping unknown names fail-closed before acquisition, but neither covers Bash.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 28, 2026, 6:06 PM ET / 22:06 UTC.

Summary
Keep open for maintainer product direction: the requested opt-in probe matches existing preflight patterns, but its Bash-missing acceptance criterion conflicts with Crabbox’s current POSIX execution contract, which invokes every remote shell command through Bash.

Reproducibility: yes. source inspection gives a high-confidence reproduction: bash is absent from the registry and unknown preflight names exit 2 before lease acquisition. The Bash-missing continuation scenario is also source-proven incompatible with the current bash -lc execution path.

Maintainer decision needed

Question	Recommendation
Should Crabbox retain Bash as the required POSIX remote-shell contract and add only an opt-in diagnostic, or support Bash-free POSIX targets as requested?	Retain the Bash transport contract: Add a POSIX/WSL2 opt-in Bash version probe but document Bash as a prerequisite for remote POSIX execution.

Why: The requested unavailable result and continued workload execution cannot be achieved by the proposed preflight registry change alone because both preflight and ordinary POSIX remote commands currently require bash -lc.

Next step
A maintainer must choose the POSIX Bash compatibility contract before a focused implementation boundary can be defined.

Review details

Best possible solution:

Decide whether Bash remains a required POSIX transport shell; if it does, add the opt-in version probe only for supported Bash targets and document that prerequisite, otherwise design and prove a compatibility-safe Bash-free transport before adding the missing-Bash guarantee.

Do we have a high-confidence way to reproduce the issue?

Yes, source inspection gives a high-confidence reproduction: bash is absent from the registry and unknown preflight names exit 2 before lease acquisition. The Bash-missing continuation scenario is also source-proven incompatible with the current bash -lc execution path.

Is this the best way to solve the issue?

Unclear. A literal opt-in probe follows the established CMake/Python pattern, but it cannot meet the requested Bash-unavailable behavior until maintainers choose whether to change the POSIX shell contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A registry-only change would still report a generic transport failure when Bash is absent, while a Bash-free fallback changes the established POSIX workload and login-shell compatibility contract.

Codex review notes: model internal, reasoning high; reviewed against f0f2fbde0864.

Label changes

Label justifications:

• P3: This is a bounded observability feature request rather than a broken established behavior or urgent reliability issue.
• impact:other: The request would extend normalized remote capability evidence, which is meaningful but outside the specialized impact taxonomy.

Evidence reviewed

What I checked:

• Current registry rejects Bash: The current preflight registry has opt-in CMake and Python entries but no bash entry; validation rejects every name absent from this registry with exit code 2. (internal/cli/run_observability.go:544, f0f2fbde0864)
• Existing execution contract requires Bash: Both argv and shell-mode POSIX remote commands are wrapped in bash -lc, so a Bash-free target cannot currently run even a Bash-independent workload; a registry-only probe cannot satisfy the proposed missing-Bash continuation criterion. (internal/cli/ssh.go:1785, f0f2fbde0864)
• Established opt-in probe pattern: Current documentation defines CMake and Python as opt-in literal probes whose missing state is diagnostic-only, providing a maintainable pattern for a Bash-present diagnostic if maintainers approve that narrower scope. (docs/commands/run.md:416, f0f2fbde0864)
• Feature history: The current preflight surface was recently extended by the merged Python and CMake probe commits, establishing the relevant area ownership and precedent. (internal/cli/run_observability.go:550, a76807e695de)
• Maturity helper limitation: The required shortlist helper was run, but this checkout has no qa/maturity-scores.yaml; no stable-maturity label is selected.

Likely related people:

• Peter Steinberger: Authored the merged Python and CMake preflight additions that define the current registry, diagnostic, documentation, and test pattern. (role: recent preflight feature owner; confidence: high; commits: add2375124b6, a76807e695de; files: internal/cli/run_observability.go, internal/cli/run_test.go, docs/commands/run.md)
• Vincent Koc: Recent history on the preflight path includes WSL2 and Windows transport fixes, relevant if maintainers choose to alter the Bash-dependent transport contract. (role: adjacent transport contributor; confidence: medium; commits: 3ced7ea7d37f, 0908cc1aba8f; files: internal/cli/run_observability.go, internal/cli/ssh.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.