fix(discovery): resolve Windows commands through PATHEXT, not the bare name

[Harold Hunt (huntharo)]

The bug

buildPathCommandNames returned [command, ...extensions] — the bare, extensionless name first — and resolvePathCommand walks that list per PATH directory and returns the first hit.

npm installs three shims side by side: codex (an sh script, for Git Bash), codex.cmd, and codex.ps1. So in any npm or nvm-windows bin directory the scan stopped on the sh script and never reached codex.cmd. The tool is present and working; discovery reported it missing.

Measured on a Windows guest with a working Codex 0.146.0 install at C:\nvm4w\nodejs\:

where codex
C:\nvm4w\nodejs\codex        <- sh script, unusable on Windows, chosen by the scan
C:\nvm4w\nodejs\codex.cmd    <- the real entry point, never reached

.PS1 is not in the default PATHEXT, so the .ps1 was never the problem — the bare name was.

This is not Codex-specific. discoverCommands is generic, so every consumer resolving a tool (git, gh, …) on a Windows npm-shim layout has the same defect.

What changed

Ordering (buildPathCommandNames) — on win32 the bare name is no longer a candidate at all. I dropped it rather than merely demoting it below the extensions: CreateProcess appends .exe to an extensionless name, so that file is unlaunchable from child_process no matter where it sits in the list, and keeping it as a fallback would still reproduce the bug across directories — the scan's outer loop is per-directory, so an extensionless codex in an earlier PATH entry would still beat a codex.cmd in a later one.

One exception: a command carrying a non-PATHEXT extension (tool.ps1) keeps the verbatim name, tried last. The caller named a specific file; dropping it entirely would make it undiscoverable. A name already ending in a PATHEXT extension still resolves to itself.

PATHEXT is now read case-insensitively (it was env.PATHEXT exact, while PATH was already case-insensitive). The sibling agent-acp enumerator (executableCommandNames) already does exactly this — extensions only, no bare name — so this brings the two packages in line.

POSIX is untouched — same single-element [command] return, asserted in tests.

pathIsExecutable — fixed here, not deferred. It used access(X_OK), which on Windows has no execute bit to consult and degrades to F_OK: it answered true for a README, so candidate.executable on win32 was asserting nothing. It now judges by PATHEXT there (the rule CreateProcess and cmd.exe actually apply) and confirms existence separately; POSIX still asks the filesystem. New optional second argument PathIsExecutableOptions { env, platform } defaulting to process.env / process.platform, so existing one-arg calls keep compiling. Discovery still ORs this with "the version probe actually ran", so a candidate proven to execute is unaffected.

Verification

The end-to-end assertion (a directory holding both codex and codex.cmd resolves to the .cmd) can only run on a Windows host — path.win32.join produces backslash paths that never match a POSIX temp file, which is why the pre-existing Windows tests here are already runIf(isWindows). So it's added there and buildPathCommandNames is exported module-locally (not from index.ts, matching the normalizeTimeoutMs precedent) for host-independent ordering coverage.

I confirmed the new tests actually catch the old behavior by temporarily restoring the buggy code: 5 failures (4 ordering + 1 executability). The POSIX assertions passed in both states.

Full suite: agent-core 20, agent-transport 28, agent-chat-react 22, agent-acp 147, codex-discovery 64 passing.

Pre-existing failures, not from this change

4 tests in packages/codex-discovery/test/codex-discovery.test.ts fail on my machine. I verified they fail identically on the clean tree with these changes stashed. They're host contamination: this Mac has a real codex 0.146.1 at /usr/local/bin, which discovery scans beyond the test's PATH, so the "nothing installed" and "only an old binary" tests find it. Worth a separate fix — flagging so it isn't attributed here.

Reviewer notes

• Changeset included, minor. It flags that consumers pinned to ^0.1.6 need to widen the range — the package is already at 0.2.0, so PwrAgent won't pick this up without that bump.
• Backward compatible: no exported name changed meaning off Windows, and nothing was removed.
• Downstream: fix(desktop): launch Windows Codex through its .cmd shim PwrAgent#1734 carries a compensating module plus coordinator special-casing for this. The other half of that compensation — the hardcoded 2s --version probe timeout and timeouts being indistinguishable from "not installed" — already landed upstream in dbc7298 / d589cf7, so with this both halves are covered and most of that downstream module can go away.

🤖 Generated with Claude Code