[robobun]

Stacked on #46687 (the base branch). Merge #46307 first.

Problem

• A builtin's echo x > ${Bun.file(fd)} or > ${Bun.stdout} exits 0 and writes nothing. The docs list Bun.file(fd) as an output target.
• Builtin::init_redirections stores it as BuiltinIO::Blob, whose write arm only returns Ok(buf.len()) (src/runtime/shell/Builtin.rs:370).
• The Response check at :684 is inverted. A new Blob body is lost. A Bun.file(fd) body throws Cannot redirect stdout/stderr to an immutable blob. Expected a file.

Fix

• Interpreter::redirect_target classifies a Bun.file(fd), bare or as a Response body, as the new RedirectTarget::Fd. Both redirect setups use a duplicate of it.
• BuiltinIO::Blob is removed. A builtin refuses any other Blob or body as an output, unread.
• Verified: test/js/bun/shell/file-io.test.ts (42 new tests, 30 fail on the base) and 24 other shell suites.
• Self-reviewed: 21 concerns raised, 19 addressed. Notes names the other two.

Background

• A command is a builtin (code inside bun) or a spawned process. Each has its own redirect setup. shell: open a Response over Bun.file(path) as a file redirect #46687 gives both one classifier.
• ${Bun.file(path)} is path text since template time. Only Bun.file(fd) arrives as an object.
• Considered a classifier in the builtin setup only (shell: fix inverted file-blob check for builtin > ${Response(...)} redirect #35318): the two setups stay different.

Downsides

• Without shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307, a builtin write larger than the free room of a blocking pipe waits in write(2) on the JS thread (Linux). Before: nothing written.
• A builtin's > ${new Response(blob)} now throws. A descriptor that is not open gives exit 1.
• A command that worked before runs at most 37 more instructions. A spawned Bun.file(fd) adds dup and close. .text grows 256 bytes.

Notes

How to land it

• The diff is on cd5cbee, the head of shell: open a Response over Bun.file(path) as a file redirect #46687. It needs Interpreter::redirect_target, which only that PR has.
• Merge this PR into that branch, or retarget it to main after shell: open a Response over Bun.file(path) as a file redirect #46687 merges.
• Merge shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307 before this stack. It bounds the blocking write that the first Downsides line names. The two conflict in one import line of file-io.test.ts.
• No issue exists for this defect. A read of the code found it. The repro below is the report.

Repro (bun 1.4.2, main 6292c65, and the head of #46687):

import { $ } from "bun";
import { closeSync, openSync, readFileSync } from "node:fs";

const fd = openSync("out.txt", "w");
const builtin = await $`echo from-builtin > ${Bun.file(fd)}`;
const spawned = await $`sh -c 'echo from-spawned' > ${Bun.file(fd)}`;
closeSync(fd);
console.log(builtin.exitCode, spawned.exitCode, JSON.stringify(readFileSync("out.txt", "utf8")));
// before: 0 0 "from-spawned\n"
// after:  0 0 "from-builtin\nfrom-spawned\n"

• docs/runtime/shell.mdx:159 lists Bun.file(path), Bun.file(fd) as output targets ("writes to the file"). Bun.stdout and Bun.stderr are such files. The docs are correct after this PR, so there is no docs change.
• The docs list Response as an input only. shell: open a Response over Bun.file(path) as a file redirect #46687 asks if a Response over a file is also an output target. This PR gives the Bun.file(fd) form the answer that shell: open a Response over Bun.file(path) as a file redirect #46687 gives the Bun.file(path) form: the Response is the file, on both routes.
• The write arm that stores nothing is in the first shell commit (feat: Bun shell #7748). Its comment there says "in the case of blob, we write to the file descriptor".
• shell: fix inverted file-blob check for builtin > ${Response(...)} redirect #35318 fixed the builtin setup. The stale sweep closed it on 2026-10-23 with no maintainer comment. This PR keeps its result, and the classification moves into the classifier of shell: open a Response over Bun.file(path) as a file redirect #46687.

Behaviour, before and after (Linux x64, release builds of cd5cbee and of this PR)

Redirect	Route	Before	After
>, >>, 2>, &> to ${Bun.file(fd)}	builtin	nothing written, exit code unchanged	written
the same to ${new Response(Bun.file(fd))}	builtin	throws the "immutable blob" error	written, bodyUsed is true
the same to ${new Response(new Blob(["x"]))}	builtin	exit 0, output lost, bodyUsed is true	throws the "immutable blob" error, body unread
< ${Bun.file(fd)}, the descriptor is a pipe	builtin cat	reads nothing	reads the pipe
< ${Bun.file(fd)}, the descriptor is a regular file	builtin cat on POSIX (experimental flag)	exit 0, reads nothing	exit 1, as cat < file and cat file there (#35337)
&> ${Bun.file(fd)}	spawned	stderr is lost	both streams
&> ${new Response(Bun.file(fd))}	spawned	throws Blobs are immutable, and cannot be used for stdout/stderr	both streams
> or < to ${Bun.file(fd)}, the descriptor is not open	builtin	exit 0	bun: Bad file descriptor: <fd>, exit 1
the same, bare or in a Response	spawned	bun: Bad file descriptor: /usr/bin/sh, exit 1, body used	bun: Bad file descriptor: <fd>, exit 1, body unread

Every other cell of a spawned command is the same before and after. The bare > ${new Blob(["x"])} threw before and throws now.

What the shell does with the descriptor

• The shell does not close it. A redirect reads or writes a duplicate (dup) and closes the duplicate when the command ends. The type JsFd gives out a duplicate and the number, not the descriptor.
• The duplicate shares the file offset. > does not truncate and >> does not seek. A spawned command did the same before.
• A builtin does not change the status flags. open_for_writing_impl would set O_NONBLOCK, and a duplicate shares that flag with the descriptor of the caller and with each process that holds it. A spawned command clears O_NONBLOCK on the descriptor, as each child stdio does since process.stdout/stderr: clear O_NONBLOCK for spawned children, don't drop console output on EAGAIN #43868. That is not new.
• The duplicate comes first. A descriptor that is not open fails the command before the Response body is taken.
• The writer has the settings of the stdout writer of the shell (setup_io_before_run, interpreter.rs:1262): shell_dup, then is_pollable. So > ${Bun.stdout} writes as a command with no redirect does.

Blocking pipe, in full

The target is the blocking write end of a FIFO, passed as Bun.file(wfd). The only reader is on the JS thread. The FIFO holds 65,536 bytes. Linux 6.1. The last column is a debug build of this branch merged with #46307.

Command	Before	After	After, with #46307
builtin echo, 65,536 bytes	exit 0, 0 bytes arrive	exit 0, all bytes arrive	exit 0, all bytes arrive
builtin echo, 65,537 bytes	exit 0, 0 bytes arrive	does not return	exit 0, all bytes arrive
builtin echo, 200,001 bytes	exit 0, 0 bytes arrive	does not return	exit 0, all bytes arrive
builtin echo, 1,000,001 bytes	exit 0, 0 bytes arrive	does not return	exit 0, all bytes arrive
builtin echo, 200,001 bytes, write end opened with O_NONBLOCK	exit 0, 0 bytes arrive	exit 0, all bytes arrive	exit 0, all bytes arrive
the same, after a spawned command got that descriptor	exit 0, 0 bytes arrive	does not return	exit 0, all bytes arrive
spawned sh, 200,001 bytes	exit 0, all bytes arrive	exit 0, all bytes arrive	not run

• The limit is the free room of the pipe, not its size. The writer waits for POLLOUT first, so a full pipe alone does not block (test "a write to a full pipe waits for the reader").
• With a reader in another process, the JS thread waits until that reader makes room. The stdout writer of the shell does the same on main for a bare echo.
• The frame is write_to_blocking_pipe (src/io/PipeWriter.rs:252): one write(2) of the whole chunk after POLLOUT.
• shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307 changes PosixPipeWriter::try_write: a blocking pipe or FIFO gets one pipe slot per POLLOUT, and it reads O_NONBLOCK before each write. This PR has no copy of that change. The writer is shared with the stdout and stderr writers of the shell, and a copy here would conflict with shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307.
• By the notes of shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307, the limit applies to a FIFO on each kernel, to a pipe(2) pipe before Linux 6.4, and to a socket before Linux 6.5. pwritev2(RWF_NOWAIT) from process.stdout/stderr: clear O_NONBLOCK for spawned children, don't drop console output on EAGAIN #43868 covers the rest. macOS was not run.
• Without shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307: redirect to the path of the FIFO. A descriptor with O_NONBLOCK also works, until a spawned command gets the same descriptor, because spawn clears the flag.

Left out on purpose, with the owner

• A Response over a stream of a Bun.file(fd) (.stream(), a read .body, .clone()) stays a JS object. The Blob caches that stream, and taking the body spends it (process.stdin.resume() throws "ReadableStream is locked" after Bun.spawn takes Bun.stdin.stream() (regression in 1.4.3) #45068). Handing Bun.stdin.stream() to a child process leaves it readable #45431 fixes that in the object arm, and its shell test keeps its path.
• Stdin from a stream or from a used Response: shell: reject a stream, used, failed or S3-backed Response body as stdin #42786. An S3 file: Refuse an S3-backed Blob at spawn stdin, in the shell, in Bun.build files and in redis #46673.
• The buffer arm: shell: reject >> to a Buffer/ArrayBuffer instead of silently overwriting from offset 0 #36480, shell: keep both streams when &> redirects to a buffer or a Bun.file(fd) #43131, shell: fail a command whose > ${buf} redirect overflows the target buffer #43196, shell: stop an external command when its > ${buf} target is full #43225.
• The builtin cat cannot read a regular file on POSIX: cat < file and cat file exit 1 there. It is a builtin on POSIX only with BUN_ENABLE_EXPERIMENTAL_SHELL_BUILTINS. cat < ${Bun.file(fd)} now fails the same way. Before, it exited 0 and read nothing. shell(cat): read regular files synchronously in the builtin on POSIX #35337 fixes the reader in cat.rs for each form. Two test.todoIf(isPosix) rows wait for it.
• A spawned > ${new Response(blob)} takes the body and then throws a TypeError with another text. A test.todo row records the difference.
• A sliced Bun.file(fd) is the whole file, as on main. spawn: send a sliced Bun.file() at stdin in chunks of its window #44301 (draft) fixes the slice in Stdio::extract_blob, which a RedirectTarget::Fd does not reach.

Other open PRs on the same lines

• shell: keep both streams when &> redirects to a buffer or a Bun.file(fd) #43131 gives both streams the descriptor for a spawned &> ${Bun.file(fd)}, in the Blob branch of the object arm. The two merge with no conflict in src/, and the results agree. After both, a Bun.file(fd) does not reach that branch.
• spawn: one open-flags table for Bun.file(path) stdio, stdout and stderr replace the file #46665 has its own classifier for new Response(Bun.file(path)) on the spawned route. It conflicts with shell: open a Response over Bun.file(path) as a file redirect #46687 already (shell_body.rs, Cmd.rs). This commit adds no conflict there.
• This commit adds a text conflict with shell: reject a stream, used, failed or S3-backed Response body as stdin #42786 (Builtin.rs) and with shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307 (the import line). Handing Bun.stdin.stream() to a child process leaves it readable #45431 merges clean.
• The self-review asked for edits to shell: keep both streams when &> redirects to a buffer or a Bun.file(fd) #43131, spawn: one open-flags table for Bun.file(path) stdio, stdout and stderr replace the file #46665, Handing Bun.stdin.stream() to a child process leaves it readable #45431 and spawn: send a sliced Bun.file() at stdin in chunks of its window #44301. This PR does not make them. Each of the four has its own review, and this list is the notice.

Weighed and not done

• open_for_writing_impl on the descriptor: see the flags rule above.
• Open /proc/self/fd/N again: Linux only. It gives a new offset, blocks on a FIFO with no reader, fails with ENXIO on a socket, and makes a read-only descriptor writable.
• A classifier in the builtin setup only, the first draft of this change: it repeated the rules of shell: open a Response over Bun.file(path) as a file redirect #46687 and gave the spawned route nothing.
• A trailing newline on bun: Bad file descriptor: <fd>: the path errors of the same function have none, and the tests of shell: open a Response over Bun.file(path) as a file redirect #46687 pin that.

Cost (release builds of cd5cbee and of this PR, Linux x64)

• .text: 82,258,761 to 82,259,017 bytes (+256).
• Type sizes are the same: BuiltinIO 64, BuiltinInput 56, Builtin 280, Cmd 176, RedirectTarget 40.
• Instructions on the JS thread from the entry to the return of Cmd::transition_to_exec, callees included (gdb single-step, warm), for a builtin:

Command	Before	After
echo hi	1,101	1,100
echo hi > path	2,069	2,065
echo hi < path	1,418	1,416
echo hi > ${u8}	1,560	1,573
echo hi < ${blob}	1,446	1,483
echo hi < ${new Response("x")}	1,813	1,756
echo hi < ${Bun.file(fd)}	1,446	1,417
echo hi > ${Bun.file(fd)}	1,294 (writes nothing)	1,813

• For a spawned command the count covers transition_to_exec, redirect_target and ShellSubprocess::ref only, because a single-step across vfork does not end. /bin/true 1,002 to 1,006. > path 1,107 to 1,116. > ${u8} 1,092 to 1,113. < ${blob} 1,155 to 1,188. > ${Bun.file(fd)} 1,140 to 1,148. < ${Bun.file(fd)} 1,113 to 1,123.
• mimalloc calls per builtin command (malloc/free) are the same for the first seven rows: 6/7, 9/11, 8/9, 5/7, 7/8, 9/10, 7/8. > ${Bun.file(fd)} goes from 6/8 to 8/10.
• Syscalls on the JS thread per builtin command are the same for each command that has no Bun.file(fd). < ${Bun.file(fd)} goes from 5 to 7 (dup, close). > ${Bun.file(fd)} goes from 5 to 10 (dup, fstat, ioctl, write, close, no F_SETFL).
• For a spawned command the script counts descriptor syscalls only. They are the same for each command that has no Bun.file(fd). > goes from 11 to 13 and < from 14 to 16 (dup, close).
• perf, valgrind and strace are not in the container. gdb scripts made the counts.

Tests

• file-io.test.ts, block "redirect to a Bun.file(fd)": 42 tests and 4 todo rows. The debug build (ASAN) gives 69 pass, 4 todo, 0 fail for the file. On a release build of cd5cbee 30 of the 42 fail.
• The 12 that pass on the base are controls: the spawned cells that worked before, cat < on POSIX, and the builtin refusal of a Response whose .body was read.
• Each output cell runs for a builtin (echo, basename) and for a spawned twin that writes the same bytes, for >, >>, 2> and both streams of &>, with the bare file and with the Response.
• One fixture counts /dev/fd entries over 20 rounds of nine redirects and compares the status flags of three descriptors with the flags at open (Linux). One fixture fills a FIFO and reads it on the JS thread.
• One fixture writes 200,001 bytes to a FIFO write end with O_NONBLOCK and reads them on the JS thread. The same fixture with a blocking write end is a test.todo row that names shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307. With shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307 merged in, that row passes.
• The rows for a descriptor that is not open are POSIX only. The Windows text was not measured.
• Other suites, debug build: bunshell.test.ts (510 pass), yield, bunshell-instance, exec, throw, shell-worker-terminate-leak, bunshell-file, lazy, shelloutput, epipe, pipeline_stack, assignments-in-pipeline, shell-pipe-read-fault, shell-write-fault, shell-blocking-pipe, and the command suites cat, echo, basename, rm, mv, which, seq, yes, ls. One test in exec and one in ls go over their 5 s limit in a full debug run and pass alone.
• BUN_JSC_validateExceptionChecks=1 passes on the new block. cargo clippy and rustfmt are clean. cargo check -p bun_runtime passes for x86_64-pc-windows-msvc and aarch64-apple-darwin.
• Windows and macOS were not run locally.

Self-review

• Round one: the first draft had its own classifier against main. It repeated shell: open a Response over Bun.file(path) as a file redirect #46687 and disagreed with it. The change was rebuilt on redirect_target. A path case, an S3 case and a docs edit went out.
• Round two: the diff held. Changes from it: the spawned setup duplicates the descriptor and names it before the body is taken, the JsFd type, the stream forms stay objects (Handing Bun.stdin.stream() to a child process leaves it readable #45431), both routes in each test, the flags test reads the flags at open.
• Not done: the edits to the four PRs above, and the trailing newline.
• After the first review on this PR: the test of a write larger than the pipe, its test.todo row for a blocking descriptor, the build with shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307, and the cat row in the table above.

---

no test proof · iteration 0 · platform-specific test(s) that do not run on this machine, deferring to CI, which covers all platforms: test/js/bun/shell/file-io.test.ts

[robobun]

^{Updated 2:49 PM PT - Oct 24th, 2026}

✅ @robobun, your commit 57b5968ca927d9ae327d6196ae653ac90d76285a passed in Build #132199! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 46796

That installs a local version of the PR into your bun-46796 executable, so you can run:

bun-46796 --bun

[robobun]

Status: the fix is in this PR, #46796. It is stacked on #46687. Merge #46307 first (see Downsides in the PR body).

How it was reproduced (Linux x64, on bun 1.4.2, on main 6292c65 and on the head of #46687):

import { $ } from "bun";
import { closeSync, openSync, readFileSync } from "node:fs";

const fd = openSync("out.txt", "w");
await $`echo from-builtin > ${Bun.file(fd)}`;
await $`sh -c 'echo from-spawned' > ${Bun.file(fd)}`;
closeSync(fd);
console.log(JSON.stringify(readFileSync("out.txt", "utf8")));
// before: "from-spawned\n"
// after:  "from-builtin\nfrom-spawned\n"

Both commands exit 0. In test/js/bun/shell/file-io.test.ts, 30 of the 42 new tests fail on a build of the base branch. All 42 pass on this branch.

CI on 57b5968: no job failed. file-io.test.ts has no failure on any lane that ran: Linux, Windows x64 and aarch64, macOS aarch64. The annotated failures are seven other test files, and each passed when CI ran it again. Two macOS x64 test jobs wait for an agent.

[claude]

Beyond the inline findings, I also checked ownership of the dup'd descriptor on every path in both redirect setups: the Fd arm dups before consume_body, and the dup is handed straight to CowFd (closed in deref) or to IOReader/IOWriter (which own and close it), with the only early returns coming before the dup, so no descriptor leaks on the EBADF or ambiguous-redirect paths. The ruled-out wrong-direction Bun.stdin/Bun.stdout case and the dup-lands-on-a-closed-stdio-number case were examined too and are pre-existing behaviour of the spawned path, not introduced here.

Extended reasoning...

The change touches the shell interpreter's redirect classifier (src/runtime/shell/interpreter.rs), the builtin redirect setup (src/runtime/shell/Builtin.rs), and the spawned-command redirect setup (src/runtime/shell/states/Cmd.rs), adding a RedirectTarget::Fd variant that dups a JS-owned descriptor, removing the no-op BuiltinIO::Blob output arm, and adding a 41-case test matrix. It touches no auth, crypto or injection surface; the sensitive surface is fd ownership and blocking I/O on the JS thread. Two confirmed findings (a JS-thread hang on a blocking pipe with more than the free room, and a builtin cat < Bun.file(fd) on a regular file now exiting 1) already mark this for human review, so this note only records the fd-ownership audit that came back clean.

Findings marked 🟡 are optional suggestions and need no follow-up push.

[robobun]

Replies are on the two review threads. In short:

• Blocking pipe (Builtin.rs:605): confirmed. The bound is shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307, in PosixPipeWriter::try_write, and this arm gets it with no change here. A build of this branch merged with shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307 passes the probes with 65,537, 200,001 and 1,000,001 bytes, also after a spawned command cleared O_NONBLOCK on the descriptor. 57b5968 adds a test for a nonblocking descriptor and a test.todo row for the blocking descriptor. The PR body now says to merge shell: write one pipe slot per POLLOUT to a blocking stdout or stderr (Linux) #46307 first.
• Builtin cat on a regular file (Builtin.rs:682): kept. With the experimental builtins flag on POSIX, cat < file and cat file exit 1 too. shell(cat): read regular files synchronously in the builtin on POSIX #35337 fixes each form in cat.rs.

[claude]

Code review found no new issues

No new issues were found in this update; 1 finding from earlier reviews is still open above.

Still open from earlier reviews (1):

• 🔴 src/runtime/shell/Builtin.rs:605 — A builtin writing more than a blocking pipe's free room to a Bun.file(fd) can hang the JS thread for good when the only…

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.

[robobun]

I resolved the thread at src/runtime/shell/Builtin.rs:605, so that the review does not count it again. The finding is correct, and this PR does not fix it: the bound on a write to a blocking pipe is #46307, in PosixPipeWriter::try_write. This branch merged with #46307 passes the probes, and the thread has the numbers. The PR body names the limit in its first Downsides line and says to merge #46307 first.