From 706814653e87d42362263bdd14fd218bb44a1c0e Mon Sep 17 00:00:00 2001
From: weishu <twsxtd@gmail.com>
Date: Tue, 23 Dec 2025 20:20:51 +0800
Subject: [PATCH] fix: add friendly error messages for failed binary spawning

Added helpful error messages with cause preservation when spawning codex, gemini, or other CLI tools fails because the binary is not found in PATH. This follows the existing error handling pattern from claudeLocal.ts.
---
 cli/src/agent/backends/acp/AcpStdioTransport.ts | 6 +++++-
 cli/src/codex/codexLocal.ts                     | 3 ++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/cli/src/agent/backends/acp/AcpStdioTransport.ts b/cli/src/agent/backends/acp/AcpStdioTransport.ts
index 9f93b876..e74f7681 100644
--- a/cli/src/agent/backends/acp/AcpStdioTransport.ts
+++ b/cli/src/agent/backends/acp/AcpStdioTransport.ts
@@ -65,7 +65,11 @@ export class AcpStdioTransport {
 
         this.process.on('error', (error) => {
             logger.debug('[ACP] Process error', error);
-            this.rejectAllPending(error instanceof Error ? error : new Error(String(error)));
+            const message = error instanceof Error ? error.message : String(error);
+            this.rejectAllPending(new Error(
+                `Failed to spawn ${options.command}: ${message}. Is it installed and on PATH?`,
+                { cause: error }
+            ));
         });
     }
 
diff --git a/cli/src/codex/codexLocal.ts b/cli/src/codex/codexLocal.ts
index 24a51039..33fe8aa7 100644
--- a/cli/src/codex/codexLocal.ts
+++ b/cli/src/codex/codexLocal.ts
@@ -95,7 +95,8 @@ export async function codexLocal(opts: {
 
             child.on('error', (error) => {
                 cleanupAbortHandler();
-                reject(error);
+                const message = error instanceof Error ? error.message : String(error);
+                reject(new Error(`Failed to spawn codex: ${message}. Is Codex CLI installed and on PATH?`, { cause: error }));
             });
 
             child.on('exit', (code, signal) => {