feat(codex-discovery): let callers scope install candidate paths

[Harold Hunt (huntharo)]

Problem

Four tests in packages/codex-discovery/test/codex-discovery.test.ts fail on any dev machine with a real Codex CLI installed at a well-known path:

• parses and exposes a selected 0.139.0 version with trailing punctuation
• surfaces a too-old binary as a candidate with failureReason codex_too_old (not dropped)
• throws CodexCliNotInstalledError (not a raw ENOENT) when nothing is found
• throws a too-old error (not CodexCliNotInstalledError) when only an old binary exists

Those tests call discovery with platform: "linux", and getCodexInstallCandidatePaths("linux") hardcodes /usr/local/bin/codex among the auto-candidates — a path shared with the macOS list. On a host with a real install there (reproduced against codex-cli 0.146.1 on macOS), the real binary is discovered and, since auto candidates sort newest-first, outranks the temp-dir shim each test just wrote. The two "nothing is installed" cases resolve instead of throwing.

This is not a regression — the tests fail identically on a pristine checkout of main. There was simply no way for a caller to control the auto-candidate set.

Change

Adds an optional CodexInstallCandidateOptions seam, accepted by both discoverCodexCommands and resolveCodexCommand:

• installCandidatePaths — replaces the platform list (spread getCodexInstallCandidatePaths into your own list to extend instead); defaults to getCodexInstallCandidatePaths(platform, homeDir)
• homeDir — expands the user-local entries of the default list; defaults to os.homedir()

Both are optional and default to today's behavior, so existing callers (codex-oneshot-client.ts, codex-thread-client.ts) are unchanged. getCodexInstallCandidatePaths and the new type are now exported so hosts can extend the default list.

While making the helper public, three latent problems in it were fixed:

• A blank homeDir (a host writing process.env.HOME ?? "", or os.homedir() itself when HOME is set but empty) produced relative entries like .local/bin/codex, which discovery resolved — and executed — against process.cwd(). Reproduced selecting a repo-local script over the real install. Now falls back to the real home.
• The helper joined user-local paths with the host's path, so its platform argument was only honoured when it matched process.platform. Now joins with the target platform's rules.
• Its doc claimed list order decides which install wins; selection is by version, with order only breaking ties. Corrected, along with CodexCliNotInstalledError's doc and default message, which claimed a search that a narrowed installCandidatePaths scoped out.

resolveCodexCommand now forwards options by spread rather than field-by-field, so env, platform, the probe budget/signal from #31 and the install-candidate options all reach discovery without being re-listed — and anything added later does too.

Note for reviewers

One test change goes beyond the fix. returns auto candidates newest-first and honors env > config > auto priority wrote two application shims but never passed them to discovery, so its only assertion ran against an undefined candidate and could not fail. It now feeds both shims in oldest-first and asserts the whole snapshot's order.

Verification

pnpm typecheck, pnpm build, pnpm test, and all three lint targets pass. Verified by mutation — each of these is now caught, where three previously slipped through green:

Mutation	Before	After
default list dropped (?? [])	survived	killed
homeDir forward dropped	survived	killed
[] falls through to the defaults	survived	killed
blank-homeDir guard removed	n/a	killed
platform-aware join reverted	n/a	killed

Rebased onto #31. Its probe-budget rework (DEFAULT_COMMAND_VERSION_TIMEOUT_MS 2s → 10s) also resolves the slow-spawn flakiness an earlier revision of this description flagged: the full suite now passes under parallel load on the machine where it previously failed.

🤖 Generated with Claude Code