fix: close the background-path gap where missing bash silently ran commands with no shell

[Salil Das (sadlilas)]

Problem

PR #15 fixed the FOREGROUND no-bash case on Windows, but missed the BACKGROUND path entirely.

When run_in_background=True and no bash was found on Windows, the code fell back to:

args = shlex.split(command)
process = subprocess.Popen(args, ...)

This created two failure modes:

1. Bare OS error (first token NOT a real exe): For commands like echo hello or dir, Popen raised FileNotFoundError. Caught by execute()'s generic except handler, this became a bare [WinError 2] The system cannot find the file specified — no cause, no remedy.

2. Misleading success (first token IS a real exe): For commands like python --version or git status, the first token happens to be a real executable on Windows. Popen succeeded, returned a PID, and execute() reported success=True. But bash never ran the command — pipes, &&, ~, and $VAR were silently passed as literal argv. This is worse than an error: a false positive that corrupts downstream logic.

Solution

Part 1: Extracted the foreground's actionable error message into a shared _WINDOWS_NO_BASH_ERROR constant. The user-visible text is byte-for-byte unchanged (existing foreground tests still pass). This makes it structurally impossible for the two paths to drift again.

Part 2: _run_command_background now raises RuntimeError(_WINDOWS_NO_BASH_ERROR) when no bash is found, launching nothing.

Raising rather than returning an error sentinel keeps the return contract of _run_command_background a plain {"pid": ...} with no optional keys callers must remember to check. execute() already wraps this call in a generic except Exception that produces ToolResult(success=False, output=str(e), error={"message": str(e)}) — exactly the shape the foreground path returns. No dedicated unwrapping branch is needed in execute().

Part 3: Removed the now-unused import shlex.

Test Coverage

Three new tests added (following the style of test_gap_bash_missing_actionable_error.py):

• test_background_real_exe_command_does_not_launch_when_bash_missing — Verifies the misleading-success regression is fixed: subprocess.Popen is NEVER called when bash is missing, and the result is success=False.

• test_background_plain_command_gets_actionable_error_when_bash_missing — Verifies non-exe commands get the actionable error, not a bare WinError.

• test_background_launches_normally_when_bash_is_found — No regression: when bash exists, background path launches normally via Popen.

All three patch the Windows-only subprocess.DETACHED_PROCESS / CREATE_NEW_PROCESS_GROUP constants (which do not exist on Linux/macOS, where most of the CI matrix runs) and spy on the synchronous subprocess.Popen with MagicMock. Both details are load-bearing: without the constant patches, the pre-fix code raises AttributeError while evaluating creationflags= before Popen is reached, so assert not popen_spy.called would pass against the broken code for the wrong reason; and an async spy on a synchronous Popen makes the pre-fix path die on process.pid rather than producing the misleading success=True the test exists to catch.

Verified RED against the pre-fix source: the two regression tests fail on assert not popen_spy.called — Popen was called — which is the actual regression signature, with no AttributeError and no never-awaited warnings.

Verification

uv run pytest -q
114 passed, 12 skipped

Baseline was 111 passed, 12 skipped. The +3 is exactly these new tests. Zero regressions.

ruff check clean. ruff format --diff shows only a pre-existing hunk untouched by this PR. pyright output is identical to the base commit (no new type errors).

Scope

This fix deliberately does NOT touch:

• WSL routing or path translation
• The arbitration logic or _resolve_windows_bash

It closes only the background no-bash gap, leaving architecture and WSL integration for separate work.

---

Fixes the background-path case that PR #15 addressed for the foreground.