fix: explain raw agent spawn ENOENT failures - #511
Open
anyech wants to merge 1 commit into
Open
Conversation
Contributor
|
🦞👀 Pull request received. I will update this pull request when review starts. |
clawsweeper
Bot
added
P2
Contributor
|
Codex review: needs maintainer review before merge. Reviewed August 21, 2026, 1:04 AM ET / 05:04 UTC. ClawSweeper reviewWhat this changesThis PR classifies raw custom-agent process-spawn ENOENT failures with an additive machine detail code and actionable text, while retaining the existing broad runtime code for all consumers. Merge readiness✅ Ready for maintainer review Keep open: this is a focused, source-backed fix for the linked current bug, and current main/release v0.13.1 still emits only the generic spawn failure. Priority: P2 Review scores
Verification
Live VerificationCommand: Result: PASS (completed) Assertions:
How this fits togetherThe CLI resolves a built-in or custom ACP agent command, starts its child process, and normalizes launch failures for terminal and JSON consumers. This change improves the diagnostic produced at the process-spawn boundary before ACP session initialization begins. flowchart LR
A[CLI custom agent input] --> B[Command resolution]
B --> C[Agent process spawn]
C --> D{Spawn result}
D -->|ENOENT| E[Actionable runtime error]
D -->|Other failure| F[Generic runtime error]
E --> G[Terminal and JSON output]
F --> G
Before mergeNone. Agent review detailsSecurityNone. Review metrics
Technical reviewBest possible solution: Land the narrow diagnostic improvement after ordinary PR checks, keeping the broad RUNTIME classification and generic handling for non-ENOENT failures unchanged. Do we have a high-confidence way to reproduce the issue? Yes. The supported raw-command path, spawn-error wrapper, and current generic output are directly traceable in source, and the PR supplies a focused current-release CLI reproduction. Is this the best way to solve the issue? Yes. Classifying the actual child-process ENOENT at the existing spawn-error boundary is narrower and more reliable than preflighting command paths or changing raw-command resolution. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against 2d735cf18220. LabelsLabel changes:
Label justifications:
EvidenceWhat I checked:
Likely related people:
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #510
What Problem This Solves
Fixes an issue where users launching a raw custom ACP agent would receive only
Failed to spawn agent command: <name>when process creation failed withENOENT. The error discarded the launch classification, so operators and embedding runtimes could not distinguish this missing-path condition from other startup failures or select a useful next step.Why This Change Was Made
AgentSpawnErrornow preserves the existing broadRUNTIMEcode while addingdetailCode=AGENT_SPAWN_ENOENTonly when the actual child-process cause hascode=ENOENT. Its message gives qualified remediation covering the executable, interpreter, effectivePATH, working directory, and configured argv without assuming the command binary is always the missing path.Unknown positional agents remain valid raw commands. Non-
ENOENTspawn failures keep the prior generic message and metadata. The existing machine-error strategy and changelog document the additive contract.User Impact
Operators get a useful explanation at the failure boundary instead of debugging unrelated ACP session, provider, or protocol paths. Embedding runtimes can branch on a stable detail code without breaking consumers that already rely on
acpxCode=RUNTIME.Evidence
Behavior addressed
Raw custom-agent process creation with an underlying
ENOENTlost the cause and remediation in both text and JSON output.Real setup tested
A clean disposable source checkout and a dedicated credential-free temporary HOME were used. The final CLI processes ran under
env -i; no Gateway, production state, provider credentials, or external ACP agent was involved.Exact steps or command run after this patch
Evidence after fix
Failed-first focused tests produced two expected failures before the production edit: the CLI still emitted only the generic message, and normalized JSON had no detail code. After the fix, the same three-test slice passed:
The built JSON output now preserves the broad code and adds narrow detail:
{ "error": { "data": { "acpxCode": "RUNTIME", "detailCode": "AGENT_SPAWN_ENOENT", "origin": "cli" } } }pnpm run checkpassed with 938 tests and the configured coverage gates.pnpm run check:docsalso passed. The automated CLI test now covers both an absent raw-agent path and an invalid working directory. A separate manual built-CLI EACCES control used a present non-executable file and retained the old generic result with no new detail.Observed result after fix
Text output identifies a missing executable, interpreter, working directory, or other required launch path and suggests checking the command, effective
PATH, working directory, or configured argv. JSON consumers receive additiveAGENT_SPAWN_ENOENTdetail while the top-level runtime classification remains unchanged.What was not tested
AI assistance
AI-assisted implementation and review. I inspected the owner path, reproduced the failure on the current release, and verified the final source and tests directly.