feat(discovery): report probe timeouts instead of "not installed"

[Harold Hunt (huntharo)]

The problem

command-discovery.ts probed <command> --version with a hardcoded timeout: 2_000 — no way for a caller to change, extend, or cancel it.

2s is generous for a native binary and marginal for a shim. Measured against a real Codex 0.146.0 install on a Windows VM:

launch path	time
native codex.exe	~0.3s
npm codex.cmd (cmd.exe → node → shim)	~1.5s warm

A loaded machine goes straight past 2s.

Worse than a slow path: an overrun was not reported as slow — it was indistinguishable from "this tool is not installed". The candidate came back with no version, a version-gating consumer demoted it (a version is required for protocol-compatibility gating), no candidate was selected, and resolve() threw CodexCliNotInstalledError. Nothing retried. One slow moment stranded the caller with Codex reported missing. discoverCommands is generic, so the same path serves git and gh lookups.

What changed

1. The budget is configurable. versionTimeoutMs on DiscoverCommandOptions, discoverCodexCommands, and resolveCodexCommand, with a named DEFAULT_COMMAND_VERSION_TIMEOUT_MS export. Shape follows the siblings that already got this right (DEFAULT_SHELL_PATH_TIMEOUT_MS, requestTimeoutMs, warmTimeoutMs).

2. The default is raised to 10s, sized for the shim chain rather than the native binary — configurability alone doesn't help a caller who doesn't know to tune it, and the symptom points away from the cause.

3. A timeout is distinguishable in the result shape — the load-bearing item. readCommandVersion is now exported and returns a CommandVersionProbeOutcome:

type CommandVersionProbeOutcome =
  | "ok" | "version_not_reported"
  | "not_found" | "not_executable"   // verdicts about the command
  | "timed_out" | "aborted"          // no evidence either way
  | "failed";

That outcome rides on every discovery candidate and on ResolvedCommandCandidate, so a consumer can tell an unfinished measurement from a missing CLI and re-probe on its own budget or surface an honest message. isUnprovenVersionProbe() names the "no evidence" set.

Two places were still swallowing the signal and are fixed here:

• a timed-out candidate was filtered out of the snapshot entirely unless includeFailedAutoCandidates was set — the evidence vanished one level up;
• it was labelled failureReason: "not_executable" when the access check had proven nothing. Now version_probe_timed_out.

CodexCliNotInstalledError keeps its type (existing catch sites still work) but carries timedOutCommands / probeTimedOut when a timeout — not a missing binary — is why nothing resolved.

4. Cancellation. AbortSignal on every entry point, for a renderer stampede or a quit mid-probe. An aborted run returns a snapshot with error: COMMAND_DISCOVERY_ABORTED; resolveCodexCommand throws CodexDiscoveryAbortedError, deliberately not a CodexCliNotInstalledError — a run that stopped looking is not evidence about what is installed.

Three latent hangs of the same class, also fixed

• Neither probe could be trusted to settle. Killing the cmd.exe wrapper of a .cmd shim leaves the node grandchild holding the stdio pipes open, so execFile's close never fires and no timeout value would have helped. Both probes now race their own budget and resolve regardless.
• collectCodexStatus had no budget at all — a wedged codex login status hung the caller forever. Now DEFAULT_CODEX_STATUS_TIMEOUT_MS (10s) with outcome / timedOut, so a slow check isn't read as a signed-out profile.
• AcpConnection.request accepted timeoutMs and ignored it (_timeoutMs), making the 30s initialize and 1h session/prompt budgets AcpAgentClient passes dead code. Now enforced. This is the only behavior change that can turn a previously-infinite wait into a rejection.

agent-acp local discovery gains probeTimeoutMs + AbortSignal. Its default stays 5s: discoverStrategyInstances walks candidates serially, so the worst case is candidates × budget, not one budget — raising it there is a knowing choice, not a default.

Reviewer notes

• Backward compatible throughout — every addition is optional; the only semantic changes are the raised default, the newly-enforced ACP request timeout, and a timed-out candidate reporting version_probe_timed_out instead of not_executable. PwrAgent can adopt this and delete its desktop-owned 10s re-probe workaround.
• Bonus: discoverCommands now runs fixed and auto candidates in one parallel wave. They were awaited in sequence, so a fully-hung machine cost two full budgets — which matters much more at 10s than at 2s.
• Pre-existing test failures, not from this PR: 4 tests in codex-discovery.test.ts fail on any machine with a real Codex CLI at a well-known path (they pass platform: "linux", whose auto-candidates include /usr/local/bin/codex, and the host binary beats the temp shim). They fail identically on a pristine b7cd7bc; there's no seam to override the well-known paths, so fixing it is filed separately rather than widening this change.
• Deliberately untouched: agent-client's CodexThreadClient / CodexOneShotClient call resolveCodexCommand internally with no options seam. They inherit the raised default but can't tune it — easy to thread through if wanted.

Testing

• pnpm typecheck — clean across all 7 packages.
• pnpm test — 271 pass (24 new: 19 in command-discovery-timeout.test.ts, 4 in codex-login.test.ts, plus ACP connection and discovery cases), alongside the 4 pre-existing failures above.
• lint:boundaries, lint:deps, lint:licenses — all pass.
• New tests pin the distinction end to end: probe outcome, discovery candidate, and resolved-command shape; that the budget is authoritative against a sleeping shim; and that abort never masquerades as "not installed".

🤖 Generated with Claude Code