Windows CLI resolution
Windows CLI resolution
Only the two CLI providers are affected: Codex and Gemini spawn a child process, while Grok and
OpenRouter are HTTP bridges that never touch child_process.
npm install -g on Windows does not install an executable. It writes a codex.cmd / codex.ps1
shim, and since the CVE-2024-27980 hardening in Node 18.20 / 20.12, child_process.spawn with
shell: false refuses to execute one - the process never starts. That was
issue #170 (external): every GPT call failed with a
bare spawn error, and the Gemini bridge failed the same way in three more places, including a
startup gate that exits the process.
core/resolve-bin.js resolves the command name once, before spawning:
| Input | Result |
|---|---|
| Anything containing a path separator | passed through untouched - an explicit path is the caller's business |
| Any non-win32 platform | passed through untouched - zero behaviour change off Windows |
win32, a .exe/.com found on PATH (PATHEXT order) |
that absolute path, spawned directly |
win32, only a .cmd/.bat/.ps1 shim, npm entry point present |
process.execPath + the package's own JS entry, bypassing the shim (all three extensions are treated identically) |
win32, a PATHEXT match that is neither of the above (.vbs, .py, a custom entry) |
skipped entirely, so the scan can never return a target Node cannot launch |
| win32, only a shim and no usable entry point | reported as a shim: the call fails with a message naming the shim and the override env var |
| win32, nothing found | passed through untouched, preserving the existing ENOENT |
A hand-written .cmd wrapper is not supported on Windows, and cannot be: Node refuses to
execute any .cmd, which is the whole bug. If one is found first on PATH with no npm package
beside it, the resolver treats it as an unusable shim and looks for something spawnable further
down - so a later npm install runs, and the wrapper's own flags or env do NOT apply. Set
CODEX_BIN / AGY_BIN to a real executable if you need a specific target.
The npm bypass applies to Codex only (@openai/codex declares bin: {"codex": "bin/codex.js"});
no npm package publishes an agy bin, so a shim-only Antigravity install gets the explicit error
instead. CODEX_BIN and AGY_BIN override the name being resolved; a value containing a path
separator is spawned exactly as given, so point them at an executable rather than at a shim or a
.js entry point.
PATH is walked first-match-wins, in PATH order then PATHEXT order - the precedence libuv and
where apply - so a resolvable first match is always the one taken, never a "better" one further
down. The scan continues past the first match only when it is a shim with no package behind it (a
partial install): whatever turns up next and is usable wins, whether that is a real .exe or
another npm shim that does have its package. That is deliberately out of shell order, on the
grounds that failing while a working install sits on PATH is the worse outcome. If nothing usable
turns up, the FIRST shim is the one reported, since that is the one the user believes they run.
shell: true was rejected, and not for argument injection - the prompt travels on stdin and the
argv is a fixed constant. The problem is lifecycle: with a shell interposed, the shell becomes the
child, so the provider's child.kill("SIGKILL") would kill the shell and leave the CLI running past
its timeout. Those timeouts feed the consensus circuit breaker, so trading them for shim
compatibility is a bad deal.
A failed launch is now errorKind: "not-found" (non-retryable) for Codex, and missing-cli for
Gemini, rather than unknown. This is the one part of the change that applies on every
platform, not just Windows: a missing CLI on macOS or Linux now reports the same way, and the error
text names what was tried.
The signal is a structural spawnFailed flag on the run result, never a pattern matched against the
child's stderr - mirroring the existing timedOut flag, and for the same reason. A coding agent
legitimately prints ENOENT about files in the user's repo; classifying the launch from the child's
own output would answer that with advice to go fix CODEX_BIN.
Not verified on Windows by CI. Every workflow is runs-on: ubuntu-latest, so the win32 branch
is asserted through injected platform / env / exists (test/core-resolve-bin.test.js,
buildSpawnPlan in test/core-codex.test.js), the same technique core/paths.js uses. The Gemini
bridge resolves at module load from the real platform, so only its guard LOGIC is asserted
(agyShimError, test S5c) - the wiring from that guard to a genuinely shim-only AGY_TARGET is
not. A real Windows CI lane is blocked on the bash test fixtures and is tracked separately.