Summary

• Problem: When the codex-acp subprocess terminates abruptly (e.g. misconfigured binary, interactive prompt on stdout, deprecated config error), CodexAppServerClient.writeMessage() at extensions/codex/src/app-server/client.ts:215 writes a JSON-RPC payload to the dead subprocess's stdin. Node.js emits an asynchronous write EPIPE error on the stream, and because no error event handler is registered on child.stdin, the error propagates as an unhandled exception that crashes the entire OpenClaw gateway daemon — taking down all connected channels.

• Root Cause: Three compounding defects in CodexAppServerClient:

  1. No error handler on child.stdin (constructor, line 57–77): the constructor registers error/exit handlers on the transport (child) itself, but never on child.stdin. When the pipe breaks, the stdin stream emits an error event that has no listener, causing Node.js to throw it as an uncaught exception.
  2. writeMessage() does not check this.closed (line 214–216): even after the client is marked closed by closeWithError(), async code paths like handleServerRequest() can still resume and call writeMessage(), triggering writes to a dead pipe.
  3. closeWithError() performs incomplete cleanup (line 298–304): unlike close() which closes the readline interface and shuts down the transport, closeWithError() only sets closed = true and rejects pending requests — leaving the readline active (processing more lines → more writes) and the transport open.

• Fix: Three targeted changes that address each root cause:

  1. Attach an error event handler on child.stdin in the constructor that routes errors through closeWithError(), preventing unhandled exceptions.
  2. Guard writeMessage() with a this.closed check, preventing writes to dead pipes from async continuations.
  3. Align closeWithError() cleanup with close(): close the readline interface and shut down the transport.

• What changed:

  • extensions/codex/src/app-server/transport.ts: added optional on method to the stdin type to support error event registration across stdio, websocket, and test transports.
  • extensions/codex/src/app-server/client.ts: added stdin error handler in constructor; added closed guard in writeMessage(); added lines.close() and closeCodexAppServerTransport() to closeWithError().
  • extensions/codex/src/app-server/client.test.ts: added two tests — one verifying stdin EPIPE is caught and pending requests are rejected gracefully; one verifying notify() after child exit does not attempt writes.

• What did NOT change (scope boundary):

  • close() behavior is unchanged — it already performed full cleanup.
  • request() call-site error handling is unchanged — its existing try/catch around writeMessage() continues to work.
  • WebSocket transport (transport-websocket.ts) is unchanged — its custom Writable stdin already buffers writes safely.
  • No changes to handleLine(), handleResponse(), handleNotification(), or any RPC protocol logic.
  • No changes to the transport lifecycle in closeCodexAppServerTransport().

Reproduction

1. Configure OpenClaw with a codex-acp binary that fails during initialization (e.g. a binary that writes an interactive prompt or error text to stdout, then exits immediately).
2. Start the gateway: openclaw gateway
3. The gateway attempts to send a JSON-RPC initialize payload to the dead subprocess's stdin.
4. Before fix: the gateway crashes with Error: write EPIPE as an unhandled exception.
5. After fix: the client closes gracefully, rejects the pending initialize request, and the gateway continues running.

Risk / Mitigation

• Risk: closeWithError() now calls closeCodexAppServerTransport() which sends SIGTERM/SIGKILL to the child process. If the child has already exited (the common case), the signal is silently ignored. If the child is still running after a stdin error, terminating it is the correct behavior.
• Mitigation: Both close() and closeWithError() are guarded by if (this.closed) return, so only one can execute — no double-cleanup risk. The closeCodexAppServerTransport() force-kill timer is unref()'d, so it cannot keep the process alive. Two new tests validate the exact crash scenario and the post-exit write guard.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway
• Codex extension
• Plugin SDK (transport type)

Linked Issue/PR

Fixes #67886