fix: explain raw agent spawn ENOENT failures - #511
Conversation
|
🦞👀 Pull request received. I will update this pull request when review starts. |
clawsweeper
Bot
added
P2
|
Codex review: needs maintainer review before merge. Reviewed August 28, 2026, 5:08 PM ET / 21:08 UTC. ClawSweeper reviewWhat this changesThe branch adds an ENOENT-specific spawn-error detail code and actionable remediation text for raw ACP agent launches, with CLI and error-normalization regression coverage. Merge readinessKeep open: current main still emits only the generic spawn failure, and this is a coherent, narrowly scoped candidate fix. The branch needs a rebase to resolve its changelog conflict and maintainer approval for the new permanent machine-readable error convention. Priority: P2 Review scores
Verification
How this fits togetheracpx resolves an agent command and starts its process before ACP session initialization. Process-launch failures are wrapped and normalized into text and JSON CLI errors for people and embedding automation. flowchart LR
A[CLI agent request] --> B[Command resolution]
B --> C[Agent process spawn]
C --> D{Spawn result}
D -->|ENOENT| E[Classified runtime error]
D -->|Other failure| F[Generic runtime error]
E --> G[Text and JSON output]
F --> G
Decision needed
Why: VISION.md and AGENTS.md treat output shapes and naming conventions as long-term API surface; source review can validate the implementation but cannot choose the permanent convention. Before merge
Agent review detailsSecurityNone. Review metrics
Root-cause clusterRelationship: Members:
Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything. Merge-risk optionsMaintainer options:
Technical reviewBest possible solution: Rebase onto current main, then retain the narrow ENOENT classification only if maintainers approve AGENT_SPAWN_ENOENT as a stable additive output contract while leaving RUNTIME and generic non-ENOENT behavior unchanged. Do we have a high-confidence way to reproduce the issue? Yes, with high source confidence: current main still wraps the child-process error as AgentSpawnError without preserving ENOENT, and the supplied clean-release command exercises that raw-command path. This review did not execute target code in the read-only checkout. Is this the best way to solve the issue? Unclear pending product direction: classifying the actual spawn boundary is the narrow implementation, but a new stable detailCode requires explicit approval as public output API. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against ef6b81e71756. LabelsLabel justifications:
EvidenceWhat I checked:
Likely related people:
Rank-up movesOptional improvements that raise the rating; they are not merge blockers.
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
HistoryReview history (1 earlier review cycle)
|
1 participant
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.