Document Bun's piped console output truncation and workarounds #1007

Bun can silently truncate large console.log() output after an application imports @optique/run. This affects JSON output piped to another process, even when parsing succeeds and the application exits naturally. Ward encountered it and shipped a workaround in crumley/ward#104.

The underlying Bun bug is already reported in oven-sh/bun#36419. Accessing process.stdout makes the pipe nonblocking, and Bun's native console writer drops the unwritten remainder when the pipe is full. In local tests, importing node:process alone was enough to trigger it. @optique/run imports that module and also reads stdout's terminal capabilities.

Reproduction

No Optique dependency is needed for this minimal reproduction:

// repro.ts
await import("node:process");
console.log("x".repeat(200000));

bun repro.ts | { sleep 0.5; wc -c; }

On macOS arm64 with Bun 1.3.14, this delivers 65,536 bytes instead of 200,001, with exit code 0. Removing the import delivers the whole output. Waiting after console.log() does not recover the lost bytes. Node 26.5.0 and Deno 2.9.7 deliver the whole output. The same truncation occurs after importing Optique 1.2.4 and the current development code.

Documentation to add

Document the affected Bun behavior, link the upstream issue, and explain how applications can avoid it:

• Write application data through process.stdout.write() rather than console.log(), then let the process exit naturally.
• If explicit termination is necessary, wait for the completion callbacks of pending stdout/stderr writes before calling process.exit(). An arbitrary delay is not a flush guarantee.
• Explain that skipping TTY detection alone is insufficient: the node:process import also triggers the problem in the tested Bun version.

The upstream fix, oven-sh/bun#43868, was merged on September 29, 2026. As of October 5, the latest stable release listed by GitHub is Bun 1.4.2, whose tag does not contain the fix; the upstream issue also has a report of reproduction on 1.4.2. Verify the first release containing the fix before documenting a minimum fixed version.

This issue covers documentation of Bun's behavior and application workarounds. Optique's own output being cut off by an immediate process.exit() needs a separate fix.