Skip to content

fix(harness): Tell a missing CLI from a dead child - #673

Merged
omesser merged 2 commits into
mainfrom
fix/659-missing-harness-cli
Sep 14, 2026
Merged

omesser merged 2 commits into
mainfrom
fix/659-missing-harness-cli

Conversation

@omesser

@omesser omesser commented Sep 13, 2026

Copy link
Copy Markdown
Owner

Why

Spawning a Harness CLI that is not on PATH failed as a generic start error, so nothing could tell "this machine does not have that CLI" from "the child died".

A Harness is user-supplied and never bundled (ADR-0018), but Settings and Chat offer claude, codex, grok, hermes, opencode and pi regardless. Pick one the machine has not got and three things went wrong:

  • The error was an errno — could not start: No such file or directory (os error 2).
  • The session entered the respawn backoff, 5s climbing to 5 minutes, as if the file might appear.
  • Settings said "set but not running", which describes a child that died, not a binary that was never there.

The cause was that the spawn's std::io::Error was flattened to a String the moment it arrived (acp_wire.rs, both spawn arms) and its kind() was never read, so attach charged charge_loss on any failure alike.

What changed

SpawnError { Missing, Failed(String) } carries the distinction from the spawn to the caller. SpawnError::start branches on std::io::ErrorKind::NotFound — not on the message text, because (os error 2) is the platform's wording in the user's locale.

  • acp_wire.rs — the ready channel and Wire::spawn carry SpawnError. The two platform spawn arms collapsed into one, since both produce an io::Error and the kind is now read in a single place. To make that true, spawn_in_job and spawn_fallback_no_job return Result<Child, io::Error> and the four Job-Object failures wrap in io::Error::other, so a job failure can never be misread as a missing file.
  • harness.rs — attach splits the arm: Missing returns note_missing() and does not call charge_loss; Failed still does. A missing binary is not a child that might come back. A spawn that gets past PATH clears the flag, so installing the CLI is picked up without a relaunch.
  • settings.rs — the not-running row names the command and says ai-buddy does not bundle a Harness, instead of an errno.

Deliberately not done: harness_login in main.rs is untouched. PR #661 deletes that function outright — Chat's Connect names the login command rather than spawning it — so the issue's "Chat Connect login" bullet is handled there, from the other direction. Adding ENOENT handling to a function being deleted would conflict and buy nothing.

Which of the two argvs is missing

Launch::command spawns argv[0], so ENOENT is only ever about that. For claude, codex and pi argv[0] is npx; for grok, hermes, opencode and any Custom line it is the vendor binary. The sentence therefore names argv[0] and never launch.name: a missing launcher for codex reads "npx is not installed", which is true and claims nothing about codex.

The inverse — npx present, codex absent — produces no ENOENT from our spawn at all. npx starts, and the adapter's failure to find codex surfaces as an initialize error, which stays on the backoff ladder because a child genuinely did start. No which codex pre-check was added to guess at it; that is a different failure. a_missing_launcher_is_not_a_missing_vendor_cli pins this.

How to verify

cargo test -p ai-buddy
cargo clippy --workspace --all-targets -- -D warnings
node --test tests/

418 Rust tests pass, clippy clean, 108 node tests pass.

a_missing_binary_backs_off_instead_of_respawning pinned the behavior this issue reverses. It is renamed and rewritten, not deleted — a_missing_binary_says_so_instead_of_backing_off — and its doc comment records what it used to assert and why that was the bug. It keeps the session.backoff(...) reads, since the ladder itself did not change.

Guards were mutation-tested, and the failures observed rather than assumed:

Mutation Result
Missing also calls charge_loss FAILS — "a binary that is not there was charged a respawn wait"
drop the ErrorKind::NotFound arm FAILS — got the raw (os error 2) string
note_missing uses launch.name not argv[0] FAILS — got `codex`, wanted `npx`
settings falls back to the old copy FAILS — no `npx` in the row

A dying child still backs off. That half was verified separately with a real child that starts and exits before initialize: spawn_wait_until is still charged, and the existing death tests pass unchanged. A fix that dropped backoff for all failures would have been a regression.

Notes

  • The Windows windows_job arm was not compiled here — #[cfg(windows)], and this machine is aarch64-apple-darwin only, so cargo check never parses it. The edits are mechanical (two return types, one return Err(why) replacing a format!, a deleted map_err, four io::Error::other wraps) and were read carefully, but CI's Windows job is the first real check. Worth watching.
  • Chat's status line still says not running where Settings now says not-installed. ChatHarness carries no missing field, so closing that gap means touching main.rs — which fix(harness): Name the login rather than spawn it #661 owns. The stale parity claim in src/chat-status.js was corrected to say what is true and name the issue, rather than left asserting something false.
  • No runtime check against a real missing CLI on screen; the evidence is unit-level plus the mutation table.

Closes #659

— Claude Code agent, on @omesser's behalf.

🤖 Generated with Claude Code

omesser and others added 2 commits September 14, 2026 17:55
The spawn's ENOENT now reaches `attach` as its own condition, so a binary
`PATH` has not got skips the respawn ladder and Settings names the file
that was looked for - `argv[0]`, which is `npx` and not `codex` for the
presets whose two argvs disagree. #659.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A spawn that failed for any other reason left `missing` as an earlier wake
recorded it, so the Settings row kept naming a command the user had since
installed and never named the adapter that actually failed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@omesser
omesser force-pushed the fix/659-missing-harness-cli branch from 89f88e6 to 3ed675c Compare September 14, 2026 14:57
@omesser

omesser commented Sep 14, 2026

Copy link
Copy Markdown
Owner Author

Rebased onto 3331af0e (#664). One conflict, in harness.rs, and it was worth resolving carefully rather than mechanically.

Both sides had rewritten the doc comment above login_command, and this branch also adds not_installed next to it. I kept both the new function and main's version of the doc — because #676 inverted the precedence so the login table now outranks the handshake description, and this branch predates that. Its own wording ("in the Harness's own words where it has any") describes the pre-#676 behaviour and would have been false the moment it landed.

acp_wire.rs applied cleanly, which mattered more than it looks: #664 changed turn() to return Err(TurnError::Lost) on Msg::Shutdown, and this branch reshapes the spawn path in the same file. Verified both features coexist rather than assuming it:

  • fix(harness): Reap a dropped Session off-thread #664's fix intact at acp_wire.rs:713-716 (Some(Msg::Shutdown) => … return Err(TurnError::Lost)), and its regression test retarget_does_not_wait_out_a_turn_in_flight still passes.
  • This branch's SpawnError::Missing path intact at harness.rs:859 and :898, with a_missing_launcher_is_not_a_missing_vendor_cli passing.

cargo test -p ai-buddy — 420 passed, 0 failed, 4 ignored. cargo clippy --workspace --all-targets -- -D warnings — clean.

— Claude Code agent, on @omesser's behalf.

@omesser
omesser merged commit 5326289 into main Sep 14, 2026
5 checks passed
@omesser
omesser deleted the fix/659-missing-harness-cli branch September 14, 2026 15:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(harness): A missing Harness CLI is treated as a dead child

1 participant