CRITICAL: Uncaught `write EPIPE` on macOS kills the session after a large built-in read_file result (no MCP involved)

从将工具结果渲染回 TUI 的 output/stream 写入路径入手，并以相关的 EPIPE/EOF issue 作为上下文。使用大型内置 read_file 结果进行复现，并将输出通过管道传给会提前关闭的读取方，例如 cmd … | head -c 1000。完成标准是结果被截断或溢出，故障得到处理，并且会话不会因未捕获的 EPIPE 退出。

Summary

On macOS, Command Code dies with an uncaught Error: write EPIPE (WriteWrap.onWriteComplete, node:internal/stream_base_commons:87:19) immediately after a built-in read_file tool result is large. No MCP server is involved, and this is not Windows.

The existing EPIPE/EOF issues are all pinned to either Windows or MCP responses (#716, #725, #859, #793). This is the first report of the same crash class on macOS, triggered by a built-in tool (multi-file read_file) rather than MCP. The result is fatally unrecoverable: the TUI closes and the session is gone.

Expected Behavior

A tool result that is too large to write back to the terminal should be truncated/spilled to disk and surfaced as a handled, recoverable condition (or a controlled error) — the same way tool output is normally capped. A failed write on the output stream should never become an uncaught exception that kills the process. The transcript already contains the tool result, so the session should survive.

Actual Behavior

A single read_file call that requested several large files returned ~97.7 KB (the tool's own output cap — it reported Read 3/3 files, capped at 97.7 KB, and skipped the 4th file), and immediately after, while the loop rendered/wrote the result, the CLI printed:

✖ CRITICAL: Uncaught Exception!
This is an unexpected error. Please file a bug report at https://github.com/CommandCodeAI/command-code/issues/new
✖ ERROR → Error
ℹ REASON → write EPIPE
ℹ ERROR STACK ↓
 Error: write EPIPE
    at WriteWrap.onWriteComplete [as oncomplete] (node:internal/stream_base_commons:87:19)

ℹ Trace ID: 9221bc3418843be38a38a601e32fdce3
 READ[3]  [Skill(command-code-knowledge/reference/byok.md), Skill(command-code-knowledge/reference/mcp.md) (+2 more)]

The trailing READ[3] … (+2 more) line shows the failing tool call: a read_file whose result carried the four command-code-knowledge/reference/*.md skill files. The process exited; the session was unrecoverable.

Notes on the trigger:

• No MCP server was configured or called in this session (~/.commandcode/mcp.json and .mcp.json do not exist).
• The read was a plain built-in read_file, not an MCP tool result.
• The result was large enough to hit the tool's truncation cap (97.7 KB) and it had already been persisted before the crash — the payload was successfully produced; only the write-back to the stream failed.

Trace ID: 9221bc3418843be38a38a601e32fdce3

Steps to reproduce the issue

1. macOS, Command Code v1.56.0, Node v24.21.0, Apple Terminal, zsh.
2. In a single tool call, ask read_file for several large files whose combined result is at or above the tool's ~97.7 KB output cap (in my case: byok.md, mcp.md, hooks.md, skills.md from the bundled command-code-knowledge skill reference — each tens of KB).
3. The tool returns Read 3/3 files, notes capped at 97.7 KB, and skips one file.
4. Immediately after the result is produced, the CLI throws uncaught write EPIPE and exits.

The crash appears to be timing-dependent on how fast the large payload is written to the output stream — hence not 100% reproducible per call, but reliably reachable by making a single tool result large.

Command Code Version

1.56.0

Operating System

macOS

Terminal/IDE

Apple_Terminal (488)

Shell

zsh

Session file (optional)

Not attached (the session died at the crash; the transcript is available locally if useful). Trace ID 9221bc3418843be38a38a601e32fdce3 should locate it server-side.

Fix prompt (optional)

Command Code v1.56.0 on macOS throws an uncaught Error: write EPIPE at WriteWrap.onWriteComplete (node:internal/stream_base_commons:87:19) right after a large built-in read_file result (~97.7 KB, multi-file) is produced, and the process exits. No MCP is involved.

Where: the output/stream write path that renders tool results back to the TUI — the same path implicated by the write EOF reports in #725/#793/#859, but here reached via a built-in tool on macOS rather than an MCP response on Windows.

What's correct: EPIPE/EOF on the output stream must not be an uncaught exception. Route the tool-result write through a handler that (a) tolerates a closed/backpressured pipe, (b) truncates or spills oversized results to disk (the existing toolout spill directory pattern) before writing, and (c) on write failure surfaces a recoverable error and keeps the session alive — the result is already persisted, so nothing should be lost.

How to check: reproduce by issuing a single read_file for several large files (combined result ≥ the ~97.7 KB cap) and confirm the CLI truncates/spills the result and continues, rather than exiting with EPIPE. Regression-test with output streamed into a pipe whose reader closes early (cmd … | head -c 1000) to exercise the same broken-pipe path.

Additional context

• This is the macOS (non-MCP) instance of the crash family tracked by #716, #725, #793, #859; those are all Windows and/or MCP-response-triggered. Filing separately because the trigger (built-in read_file, darwin) is distinct, which may point at the shared write path rather than MCP-specific handling.
• Related: #783 (OOM resuming long session) and #767 (uncaught exception on a large write_file) both show large payloads reaching the same fragile write path.
• Environment: Command Code installed as a global npm package under mise; node --version v24.21.0; sw_vers reports macOS 27.0 (build 26A428), arm64.
• The command-code-knowledge skill instructs the agent to read multiple large reference files, so this trigger is reproducible by design for anyone using that skill.