fix(exec): 同步 3.0.x 生产就绪加固——非零退出保留真实 exitCode 与输出；参数原样传递修复字面引号注入 argv

Author: loong10k

README.md

@@ -228,6 +228,13 @@ There is no configuration file of its own. Key fields:
 
 ### 7.1 `CodexAppServerConfig` (app-server WebSocket route)
 
+> **Upgrade notes (3.0.x.x.20260630+)**: CLI-route arguments are now passed
+> to the child process raw — multi-word prompts no longer arrive at `codex`
+> wrapped in embedded literal quotes. Non-zero CLI exits now preserve the real
+> exit code and both captured streams instead of collapsing to `exitCode=-1`
+> with empty output. A bearer token over a plaintext `ws://` connection logs a
+> warning; prefer `wss://`.
+
 Plain POJO (Spring `@ConfigurationProperties`-bindable). Field names mirror the
 commonly used `CodexEndpoint` binding:
 
@@ -238,6 +245,8 @@ commonly used `CodexEndpoint` binding:
 | `connectTimeoutMillis` | int | `5000` | TCP/TLS + WebSocket handshake timeout |
 | `readTimeoutMillis` | int | `120000` | Upper bound for a whole turn (connect → `turn/completed`) |
 | `maxSessionMappings` | int | `1000` | Bound of the `sessionKey → threadId` LRU; evicted sessions start fresh threads |
+| `maxFrameChars` | int | `1048576` | Frame accumulation hard cap; oversized server frames fail the turn (`<= 0` = unbounded) |
+| `maxContentChars` | int | `1048576` | Per-turn agent-message content cap; excess is truncated with a warning (`<= 0` = unbounded) |
 
 ## 8. Core Usage / API
 

README.zh-CN.md

@@ -222,6 +222,11 @@ public class CodexDemo {
 
 ### 7.1 `CodexAppServerConfig`（app-server WebSocket 路线）
 
+> **升级注意（3.0.x.x.20260630+）**：CLI 路线的参数改为原样传给子进程——
+> 含空格的多词 prompt 不再被塞进字面双引号后发给 `codex`。CLI 非零退出现在
+> 保留真实退出码与两路输出，不再折叠为 `exitCode=-1` 加空输出。通过明文
+> `ws://` 携带 Bearer token 会打告警日志，生产环境请优先 `wss://`。
+
 纯 POJO（可绑定 Spring `@ConfigurationProperties`）。字段名与常用的
 `CodexEndpoint` 绑定保持一致：
 
@@ -232,6 +237,8 @@ public class CodexDemo {
 | `connectTimeoutMillis` | int | `5000` | TCP/TLS + WebSocket 握手超时 |
 | `readTimeoutMillis` | int | `120000` | 单个 turn 全程上限（建连 → `turn/completed`） |
 | `maxSessionMappings` | int | `1000` | `sessionKey → threadId` LRU 上限；被淘汰的会话退化为新建线程 |
+| `maxFrameChars` | int | `1048576` | 帧累积硬上限；超限的服务器帧使 turn 失败（`<= 0` = 不限） |
+| `maxContentChars` | int | `1048576` | 单 turn agent 消息内容上限；超出部分截断并告警（`<= 0` = 不限） |
 
 ## 8. 核心用法 / API
 

src/main/java/io/github/easy4j/codex/cli/CodexCliExecutor.java

@@ -18,6 +18,7 @@
 import io.github.easy4j.codex.CodexClientConfig;
 import org.apache.commons.exec.CommandLine;
 import org.apache.commons.exec.DefaultExecutor;
+import org.apache.commons.exec.ExecuteException;
 import org.apache.commons.exec.ExecuteWatchdog;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -79,6 +80,10 @@ public CodexCliExecutor(CodexClientConfig config) {
      *   <li>Process timeout &mdash; {@link CodexCliResult#isTimeout()} returns
      *       {@code true}; exit code is {@code -1}; stderr contains the timeout
      *       notice.</li>
+     *   <li>Non-zero process exit &mdash; the real exit code is preserved in
+     *       {@link CodexCliResult#getExitCode()}, and both captured streams are
+     *       returned as-is ({@link CodexCliResult#isSuccess()} is simply
+     *       {@code exitCode == 0}).</li>
      *   <li>IOException (missing executable, permission denied, etc.) &mdash;
      *       the {@link IOException#getMessage()} is captured in
      *       {@link CodexCliResult#getStderr()} and the exit code is {@code -1}.</li>
@@ -113,7 +118,11 @@ private CodexCliResult runProcess(String stdin, String... args) {
         CommandLine cmd = CommandLine.parse(config.getLocalExecutable());
         for (String arg : args) {
             if (arg != null) {
-                cmd.addArgument(arg);
+                // handleQuoting=false: the child is spawned via exec(argv), not
+                // a shell — commons-exec's default quoting would embed literal
+                // double quotes inside arguments containing spaces (prompts,
+                // config overrides, paths), corrupting them on arrival.
+                cmd.addArgument(arg, false);
             }
         }
 
@@ -131,6 +140,7 @@ private CodexCliResult runProcess(String stdin, String... args) {
         ExecuteWatchdog watchdog = new ExecuteWatchdog(timeoutMs);
         executor.setWatchdog(watchdog);
 
+        long startNanos = System.nanoTime();
         try {
             int exitCode = executor.execute(cmd);
             String out = stdout.toString().trim();
@@ -140,6 +150,23 @@ private CodexCliResult runProcess(String stdin, String... args) {
                 return new CodexCliResult(-1, out, "codex CLI timed out after " + timeoutMs + " ms\n" + err);
             }
             return new CodexCliResult(exitCode, out, err);
+        } catch (ExecuteException e) {
+            // commons-exec throws ExecuteException for EVERY non-zero exit
+            // (and for watchdog kills). The stream pumps are joined before it
+            // is thrown, so both buffers are complete — surface them together
+            // with the real exit code instead of discarding the output. The
+            // deadline check makes the timeout verdict race-free even when
+            // {@code watchdog.killedProcess()} has not observed the kill yet.
+            String out = stdout.toString().trim();
+            String err = stderr.toString().trim();
+            boolean timedOut = watchdog.killedProcess()
+                    || System.nanoTime() - startNanos >= timeoutMs * 1_000_000L;
+            if (timedOut) {
+                return new CodexCliResult(-1, out, "codex CLI timed out after " + timeoutMs + " ms\n" + err);
+            }
+            log.debug("codex CLI failed: exitCode={}, stdout.len={}, stderr.len={}",
+                    e.getExitValue(), out.length(), err.length());
+            return new CodexCliResult(e.getExitValue(), out, err);
         } catch (IOException e) {
             return new CodexCliResult(-1, "", e.getMessage());
         }

src/test/java/io/github/easy4j/codex/cli/CodexCliExecutorTest.java

@@ -64,10 +64,21 @@ void shouldCaptureExitCodeFromFailingProcess() {
 
         CodexCliResult result = executor.execute("-c", "exit 7");
 
-        assertEquals(-1, result.getExitCode());
         assertFalse(result.isSuccess());
     }
 
+    @Test
+    void shouldPreserveRealExitCodeAndStreamsOnNonZeroExit() {
+        CodexCliExecutor executor = new CodexCliExecutor(configFor("/bin/sh"));
+
+        CodexCliResult result = executor.execute("-c", "echo out-marker; echo err-marker 1>&2; exit 7");
+
+        assertEquals(7, result.getExitCode());
+        assertFalse(result.isSuccess());
+        assertTrue(result.getStdout().contains("out-marker"), "stdout must survive a non-zero exit");
+        assertTrue(result.getStderr().contains("err-marker"), "stderr must survive a non-zero exit");
+    }
+
     @Test
     void shouldReturnIoExceptionMessageWhenExecutableMissing() {
         CodexCliExecutor executor = new CodexCliExecutor(configFor("/nonexistent/path/to/codex"));
@@ -80,6 +91,16 @@ void shouldReturnIoExceptionMessageWhenExecutableMissing() {
         assertFalse(result.getStderr().isEmpty());
     }
 
+    @Test
+    void shouldPassArgumentsRawWithoutEmbeddedQuotes() {
+        CodexCliExecutor executor = new CodexCliExecutor(configFor("/bin/echo"));
+
+        CodexCliResult result = executor.execute("Write a failing test", "-c", "key=some value");
+
+        assertEquals("Write a failing test -c key=some value", result.getStdout(),
+                "multi-word arguments must arrive without embedded literal quotes");
+    }
+
     @Test
     void shouldIgnoreNullArguments() {
         CodexCliExecutor executor = new CodexCliExecutor(configFor("/bin/echo"));