fix(pi-shell): unblock bash heredocs >4 KiB on Windows and >64 KiB on macOS

[oldschoola]

Symptom

The bash tool times out after 305 s when the agent sends a heredoc-style command such as:

mkdir -p .agent-context
cat > .agent-context/merge-context.md << 'CONTEXT'
... ~4 KB of literal body ...
CONTEXT
ls -la .agent-context/

The hard timeout text is the one emitted by bash_executor.ts:214: Command exceeded hard timeout after <N> seconds. Nothing about the user's command is malformed — the brush interpreter deadlocks before cat/ls ever runs.

Root cause

brush_core::interp::setup_open_file_with_contents wires heredocs and here-strings to a process by:

1. creating an anonymous pipe via std::io::pipe(),
2. synchronously writing the whole body into the writer half on the calling thread,
3. handing the reader half to the next command as its stdin.

The reader is not consumed until after the function returns and the command spawns, so step (2) is bounded by the OS pipe buffer:

Platform	Pipe buffer	Workaround in current code
Linux	64 KiB default, growable via F_SETPIPE_SZ up to /proc/sys/fs/pipe-max-size (1 MiB)	F_SETPIPE_SZ(len) before the write
macOS	16–64 KiB, no F_SETPIPE_SZ equivalent	none
Windows	CreatePipe(0) ≈ 4 KiB	none

Any heredoc bigger than the platform buffer (~4 KiB on Windows, 16–64 KiB on macOS) fills the buffer mid-write, writer.write_all blocks forever, and the 305 s hard-timeout in pi-shell finally trips. Confirmed present in upstream reubeno/brush@main.

Fix

In the vendored setup_open_file_with_contents, keep the Linux F_SETPIPE_SZ fast path for the common in-process case, but fall through to a detached writer thread on every other platform (and on Linux when the kernel rejects the requested size — body > pipe-max-size). The thread owns the writer and terminates naturally on drain or BrokenPipe. No JoinHandle is kept — it's fire-and-forget, same shape dash uses for large heredocs.

A LOCAL DIVERGENCE (vs upstream reubeno/brush@main) comment block documents the fork.

Tests

• New cross-platform regression large_heredoc_does_not_deadlock in pi-shell::shell::tests writes a 256 KiB body through the : builtin (never drains stdin) and asserts execute_shell finishes in ≤10 s with exit code 0. Pre-fix, the test panics with execute_shell hung past 10 s — heredoc writer deadlocked (verified locally by stashing the fix).
• Full cargo test -p pi-shell (184 tests) green.
• End-to-end smoke through the rebuilt napi binding: the user's exact heredoc shape (mkdir + cat > .agent-context/merge-context.md << 'CONTEXT' … CONTEXT + ls) with a 12,889-byte body completes in 178 ms, exit 0, file written intact. Pre-fix the same command hangs to 305 s.
• cargo clippy -p brush-core --lib / cargo clippy -p pi-shell --all-targets — no new warnings (5 pre-existing in process.rs).

Files

• crates/brush-core-vendored/src/interp.rs — rewrite setup_open_file_with_contents; document the divergence.
• crates/pi-shell/src/shell.rs — add large_heredoc_does_not_deadlock.
• packages/natives/CHANGELOG.md — [Unreleased] → Fixed entry.
• packages/coding-agent/CHANGELOG.md — [Unreleased] → Fixed entry pointing at the natives release.

Plan artifact: local://fix-heredoc-deadlock-windows-macos.md (surfaced from a session report; no issue tracked).

[oldschoola]

Superseded by upstream PR can1357#1325.