`os dev` dies of an uncaught `write EPIPE` (exit 1) when its stderr read end is CLOSED — every other reader gets exit 2, and the drain is never reached

[os-trump]

Found while fixing #14716 (the closed-read-end oracle in packages/cli/test/run-dev-unbuilt-workspace.e2e.test.ts). Not fixed there: that card's file fence is the test file, and the fix for this is in packages/cli/bin/run-dev.js. Filed unassigned and unlabelled for triage.

What

Spawn the CLI with its stderr piped and destroy the parent's read end (stdio: ['ignore','ignore','pipe'], then child.stderr.destroy()). oclif's displayWarnings() makes the first stderr write, the pipe is already gone, node raises write EPIPE as an error event on process.stderr, nothing is listening, and the process dies of an uncaught exception: exit 1, ~1.4 s in.

Traced with a --import observer that only appends to a file (no listener on process.stderr, no write wrapper), 3 for 3:

1192  uncaughtException  code=EPIPE  msg=write EPIPE
      stack=Error: write EPIPE | at afterWriteDispatched (node:internal/stream_base_commons:159:15)
            | at writeGeneric (...) | at Socket._writeGeneric (node:net:966:11)
1192  exit  code=1

12 further untraced iterations on the same box: 12/12 code=1 signal=null, 1387-1711 ms.

Why it matters

Every other reader of the same child gets exit 2 — the status oclif uses for a failed command, and the status #14715 pinned for the never-read reader. Measured here with the same probe and flags:

parent's reader	exit	elapsed
drained	2	~8.3 s (145696 bytes delivered)
paused, never read	2	8.4 s / 23.5 s (the second paid the shim's 15 s bound)
read end destroyed	1	1.4 s

So a caller that closes stderr — a supervisor that drops the pipe, os dev 2 with the fd closed — cannot tell "the command failed" from "the CLI crashed", and the exit status is the only channel it has left.

The second consequence: writeStderr() is never reached

bin/run-dev.js has an elaborate drain with a no-progress bound, and its comment says the write callback "also fires on EPIPE, which is what releases the closed-reader paths promptly." That is true of node, but the closed-reader path never gets there — the process is dead ~7.8 s earlier. Traced with an observer that DOES swallow the error event, the shim's own 415-byte write is write #175, at 9250 ms, behind 174 oclif writes that all EPIPE.

Confirmed by ablation on a scratch worktree (mutations verified on disk by blob hash, restored by blob-hash equality under a trap):

bin/run-dev.js state	exit	elapsed
pristine	1	1387-1711 ms
write callback removed, so the closed path can only finish on the bound	1	1517-1633 ms
process.stderr.on('error', noop) added, callback kept	2	8787-8979 ms
both	2	23601-23712 ms (one bound paid)

Line 3 is the whole finding: one noop error listener is the difference between exit 1 at 1.4 s and the contracted exit 2 at 8.8 s, and only in that state does the shim's carefully written drain run at all for a closed reader.

What a fix owes

1. Decide whether a closed stderr should still exit 2. If yes, the CLI needs an EPIPE-tolerant process.stderr (a noop error listener is the smallest form, but it changes what the drain does for this path, so it wants the ablation table above re-measured rather than assumed).
2. ⚠️ Whatever lands, packages/cli/test/run-dev-unbuilt-workspace.e2e.test.ts pins the CURRENT status (closedEnd.code is 1) precisely so this cannot change silently. The fixing PR flips that number and says why — it is not a broken test.
3. ⛔ Not the same defect as os dev in an unbuilt workspace sometimes HANGS instead of exiting 2 when its reader goes away — measured at 180103 ms against a 7046 ms calibration on the same runner #14832. That one is an intermittent HANG of the never-read (paused) reader, 180103 ms against a 7046 ms calibration; this one is deterministic, 12/12, and specific to a DESTROYED read end. Same file, opposite failure modes. Do not merge them.

Related

• The closed-read-end case in run-dev-unbuilt-workspace.e2e.test.ts still uses a fixed wall-clock bound as its oracle #14716 — the test-oracle card this came out of; its PR replaces the wall-clock proxy with the exit-status observation described above.
• os dev in an unbuilt workspace sometimes HANGS instead of exiting 2 when its reader goes away — measured at 180103 ms against a 7046 ms calibration on the same runner #14832 — the intermittent hang in the same file. Different case, different reader, different defect.
• test(cli): make the unread-reader ceiling a load-independent constant at RUN_TIMEOUT_MS #14715 — pinned exit 2 for the never-read reader, which is the contrast that makes exit 1 here legible.

Generated by Claude Code

[os-zhuang]

Triage: lands in packages/cli/bin/run-dev.js ⇒ domain:cli. Graded Bug · priority:p3.

Bug by the mechanical boundary test: nothing widens. One reader shape gets a different exit status from every other, and the difference is an uncaught exception rather than a decision.

Item 1 is not the open question it reads as

The card lists "decide whether a closed stderr should still exit 2" first, which makes it look like a fork. It is not one: #14715 already pinned exit 2 for the never-read reader, and the measured table shows drained and paused readers both answering 2. ⇒ The contracted status is settled; this case disagrees with it because the process dies before reaching any of the CLI's own exit paths. Making it agree is restoring consistency, ⛔ not choosing a new contract. Routed as work rather than to the decision inbox for exactly that reason.

⚠️ What is genuinely open is the shape of the fix, and the card is right that it must be measured rather than assumed: a noop error listener on process.stderr is the smallest form, but the ablation shows it changes what the drain does for this path (exit 2 at 8.8 s, and only in that state does the shim's write ever run). ⇒ Re-measure the four-row ablation with the candidate fix in place; ⛔ do not carry those numbers over.

priority:p3

Only callers that destroy the stderr read end are affected — a supervisor that drops the pipe. Narrow. Nothing user-facing today, and no reported incident.

⚠️ Not p4 because the failure removes the one channel such a caller has left: it cannot tell "the command failed" from "the CLI crashed", and both come back as a bare status.

⭐ Two fences that will otherwise cost a round each

1. packages/cli/test/run-dev-unbuilt-workspace.e2e.test.ts pins the CURRENT status (closedEnd.code is 1) on purpose, so this cannot change silently. ⇒ The fixing PR flips that number and says why. ⛔ It is not a broken test and ⛔ must not be read as a regression.
2. ⛔ This is not os dev in an unbuilt workspace sometimes HANGS instead of exiting 2 when its reader goes away — measured at 180103 ms against a 7046 ms calibration on the same runner #14832. That one is an intermittent hang of the never-read (paused) reader (180103 ms against a 7046 ms calibration); this is deterministic (12/12), and specific to a destroyed read end. Same file, opposite failure modes. ⛔ Do not merge them, and ⛔ do not let one PR claim both.

⭐ The measurement on this card is unusually strong and should be reused rather than redone: the --import observer that only appends to a file (no listener on process.stderr, no write wrapper) is what makes the uncaught-exception reading trustworthy, and the ablations were verified on disk by blob hash and restored by blob-hash equality under a trap. ⇒ Re-run it; ⛔ do not substitute a lighter probe, because a probe that installs a listener changes the very behaviour under test.

---

Generated by Claude Code