A PTY exit can be lost inside bun-pty's constructor and is then never reported

[Edo771977]

Split out of #11, where this sat since 2026-09-24 as "a PTY exit goes unobserved (Linux)". Rewritten: the first version of this issue blamed the call site and was wrong. What follows is what survived measurement.

The symptom

On the CI for #10:

(fail) v2 pty HttpApi > serves location-wrapped PTY routes and retains exited sessions [21256.87ms]
-   "status": "exited",  "exitCode": 4
+   "status": "running", "pid": 6907, …

A sh -c "exit 4" polled every 50ms for 20 seconds and never left running. It did not reproduce on a re-run and passes locally. Since only the onExit event ever sets that status, the exit was not reported at all.

What it is not

Not a race between the spawn and the listener attach in Pty.create. That was the original reading here and it does not survive measurement: over 4901 trials, including pads walking the fiber's op budget across the boundary (maxOpsBeforeYield is 2048), there were 0 microtask and 0 macrotask crossings between yield* Effect.sync(...) and the statements after it. Effect.sync invokes its continuation inline, so the spawn and both push(proc.onData(…), proc.onExit(…)) calls already run in one JS turn, and nothing can fire in between. Two independent reviews reached the same conclusion, one of them also unable to reproduce any loss on dev over repeated runs.

What it is, as far as the evidence goes

bun-pty can lose the exit before any listener could exist. _startReadLoop() is the last statement of the Terminal constructor (bun-pty/src/terminal.ts:175), it is async but has no await before its first bun_pty_read, and its emitter keeps nothing for latecomers (interfaces.ts: fire walks the listeners registered at that instant). So the first read, and any event it triggers, happens inside the constructor, before spawn returns:

• n === -2 (CHILD_EXITED) → _onExit.fire(...) to zero listeners, then break. The loop is over, so nothing reports it again and the session stays running for its whole life.
• n > 0 → the first output chunk is fired to zero listeners and dropped.
• n < 0 (read error) → the loop breaks without firing onExit at all. Even a correctly attached listener gets nothing. Same stranded session.
• kill() fires _onExit synchronously with a fabricated exitCode: 0.

Honest about reachability: I could not make the constructor window fire in 1500 clean sequential /bin/true spawns with listeners attached synchronously (0 lost). A first probe that did show ~350 losses in 1500 was invalid — it never released the PTY handles, so it was exhausting them and hitting the n < 0 branch instead. A review reported 6 of 4000 first reads returning -2 at the FFI level and 1 lost exit in 2500 end to end; neither reproduced here, and the sequential shape of that probe is the one that leaks handles, so I am not treating those numbers as established.

The n < 0 branch is the more promising lead for the CI symptom, because that is exactly what resource pressure produces, and a loaded runner with many PTYs open across a suite is where this appeared. That is consistent with the invalid probe above: under handle exhaustion, exits stopped being delivered entirely.

What would fix it

Nothing at the call site, and nothing in packages/core/src/pty/pty.bun.ts either: Terminal exposes neither the read-loop state nor bun_pty_get_exit_code, so the shim cannot ask afterwards whether an exit was missed. The options are

1. a vendored or upstream bun-pty change — defer _startReadLoop() past a microtask, or give its EventEmitter replay until the first subscriber, and make the n < 0 branch report an exit instead of going silent (packages/core/script/fix-node-pty.ts is a precedent for a post-install fixup), or
2. reconciliation in Pty: notice that a process recorded as running is gone and settle its status without an event.

Both are design decisions rather than small fixes, which is why this stays open. #30 does not close it — it fixes the separate ordering defect in #32 that the investigation turned up.

[Edo771977]

The lost exit reproduces under CPU contention, and now has a rate

This issue said the n < 0 branch was "the more promising lead" and that I could not make the loss happen — 1500 clean sequential /bin/true spawns with the handles released gave 0. That probe was wrong in one respect: it was idle. Under load the loss is easy.

Measured while getting #35's cap tests to behave. Twenty-six short-lived sessions per run, three while :; do :; done hogs on a four-core box:

• spawned all at once: 6 runs in 10 left a session that never reported its exit;
• spawned strictly one at a time, each exit awaited before the next: 6 runs in 10 again.

That second number is the informative one. Serialising made no difference, so this is not twenty-six poll loops starving each other — a single session with nothing else running loses its exit just as readily. From six failures in ten over twenty-six sessions, the per-session rate is about one in thirty under that load.

A separate probe (from a review of #35) caught the state directly: the stuck session reported processAlive=false — the child was dead and onExit had never fired — and the waiting loop sat at total=26 exited=25 running=1 unchanged until it gave up. Not slow convergence, a permanent stall: raising the wait to 90 seconds only moved the failure to the test-level ceiling.

Why this matters more than a flaky test

It is the product defect this issue describes, at a rate worth taking seriously: under a loaded machine roughly one short-lived terminal in thirty is recorded as running for the life of the process. Nothing reconciles it, attach will still accept writes for it, it is never added to exitOrder so it is never trimmed and keeps its buffer, and the app only drops a terminal on pty.exited, so it shows a dead terminal as live indefinitely. A developer's machine running a build is exactly the loaded case.

It also explains the CI symptom this issue was filed for without needing the constructor window: sh -c "exit 4" still running after twenty seconds on a busy runner is one draw from that one-in-thirty.

What #35 does and does not do about it

Nothing — it cannot, from pty.ts. Its cap tests need one more exit than the cap retains, which is twenty-six draws, and they failed six runs in ten because of this. They now remove and respawn a session that goes quiet, on a budget of six, and name this issue when the budget runs out. That keeps the cap measured on real exits without the tests carrying this defect's failure rate: 0 failures in 10 under the same load.

The fix remains the two options above — vendored or upstream bun-pty, or reconciliation in Pty — and the second now looks more attractive than it did, because a one-in-thirty product defect is not something to leave waiting on a dependency.

---

Generated by Claude Code

[Edo771977]

Reopened. This was closed automatically when #30 merged — GitHub lists it under that PR's closed issues, with closed_at at 13:45:46, the minute of the merge — and nothing in it was fixed.

The cause is mine: the first version of #30's description said Closes #29, before the investigation showed the call-site race was not the defect. I rewrote it to Refs #29 and rewrote the commit to say "#29 stays open with the corrected cause", but the link GitHub had already made from the original body survived the edit and fired on merge.

Nothing about the issue has changed, so nothing above is retracted: the loss is still bun-pty's, still unfixed, and now has a rate — roughly one short-lived session in thirty under CPU contention, measured in the comment above. If anything the accounting error is the argument for the second fix option: a product defect at that rate sitting closed by accident is worse than one sitting open.

Worth noting for the next time, since it cost nothing to catch but would have cost a lot to miss: a closing keyword that is later edited out of a pull request body can still close its issue on merge. Refs from the start, or check the issue's state after the merge.

---

Generated by Claude Code

[Edo771977]

This is now breaking CI, which raises what it costs to leave open.

unit (windows) is red on dev itself (7f1b836b23, run 36349524088) with exactly one failure, and it is this bug:

error: the shell never exited
(fail) loop waits while shell runs and starts after shell exits [16459.64ms]

So the lost exit is not only a rare event under CPU contention (the ~1-in-30 figure measured on Linux above) — on the Windows runner it is frequent enough to fail a single run of the suite, and it has been failing every push to dev since.

Two consequences worth recording:

The severity depends on who is waiting. Where the wait carries a timeout, as this test's does, the bug surfaces as a 16-second failure. Where it does not, the wait never ends. On PR #37 the same unit (windows) job hit its 50-minute step limit with opencode#test still running and 48 minutes of no output at all — no test reported a failure, the suite simply stopped making progress. That PR's diff touches neither the PTY nor the shell, and costs nothing on Linux (Run unit tests: 9m46s there against 10m16s on dev), so the stall is very probably this bug landing on an unguarded wait rather than anything in that change.

It makes the Windows job unusable as a signal. While dev is red here, a genuine Windows regression in any pull request is indistinguishable from this. That is the real cost: not the one failing test, but that nobody can tell what else is broken.

This does not change the diagnosis, only the priority, and it does not pick between the two routes still open (reconciling the missing exit inside Pty, or fixing bun_pty_read's negative-return path upstream/in a vendored copy). It does argue for whichever of the two can ship soonest.

---

Generated by Claude Code

[Edo771977]

Fixed, and the cause in this issue was wrong twice — the second time was mine

The fix is patches/bun-pty@0.4.8.patch on #37. What follows is what measurement said, including where it contradicts what I wrote above.

It is the constructor window, and it is not rare

This issue's first version blamed the call site; the comment above then blamed CPU contention and gave a rate of "roughly one short-lived session in thirty". Both are wrong about the cause. Thirty runs each of sh -c "echo hello; exit 7" through the real shim, on four cores:

	exit lost	output lost
exits immediately, three busy cores	7/30	17/30
exits immediately, idle	7/30	8/30
50ms of life before exiting, three busy cores	0/30	13/30
50ms of life before exiting, idle	0/30	8/30

Load is not the variable. Giving the child 50ms of life takes the exit loss from 7 in 30 to zero, under load and idle alike. The variable is whether the child finishes inside the window this issue named at the start: _startReadLoop() is the last statement of the Terminal constructor, it is async with nothing to await before its first bun_pty_read, so that read happens before spawn returns, and the emitter delivers only to the listeners registered at that instant.

So the reachability question this issue left open — "I could not make the constructor window fire in 1500 clean sequential /bin/true spawns" — had the wrong probe. /bin/true through the rust spawn path is slower to die than the shell builtin exit, and the loss needs a child that finishes inside the constructor.

The same window loses output, which nothing here had noticed

Look at the right-hand column. Output is lost whether or not the exit is: 8 to 17 runs in 30, including every row where the exit was delivered intact. echo hello is written immediately, the constructor's first read collects it, and _onData.fire hands it to an empty listener list. Every terminal in this product has had a one-in-three chance of dropping its shell's first output — the prompt — and that is a worse defect than the one this issue was filed for, sitting in the same three lines.

And a leak that makes the n < 0 branch reachable

The read loop closes nothing. kill() was the only path that called bun_pty_close, so a terminal left to exit by itself leaks its pty: 20 sequential sh -c "exit 7" sessions took the process from 12 open file descriptors to 92, four per session, with nothing left able to close them — Pty.teardown only kills a session whose status is still running. A process that opens terminals for long enough therefore runs into its descriptor limit, reads start failing, and a failing read is the n < 0 branch this issue flagged: it breaks without firing onExit at all. That is the invalid first probe from the issue body, explained: it was exhausting handles, which is a state this leak reaches on its own given enough terminals.

The fix, and what it measures

Three lines in the patch: defer that first read to a microtask so a caller subscribing in the spawning turn is early enough; and close the handle where the loop ends, guarded against the double close kill() would otherwise cause. After it: 0 exits and 0 outputs lost in all four conditions above, and 20 sessions move the descriptor count by 1 instead of 80.

Tests, both mutation-checked against the unpatched dependency:

• packages/core/test/pty/pty-spawn.test.ts — 30 short-lived sessions must each report their exit and their output, and 20 must not leak descriptors. Unpatched: both fail.
• packages/core/test/pty/pty-session.test.ts — the cap tests' respawn workaround (fix: record a PTY exit before telling its subscribers, and order typecheck after dependencies #35, RESPAWN_BUDGET) is removed, because it existed only to survive this bug. Unpatched they pass idle and fail 3 runs in 3 under three busy cores; patched, 3 in 3 green.

What is not fixed, and one correction

The n < 0 branch still goes silent, and kill() still fabricates exitCode: 0. Neither is reproducible here now that the leak is gone, and reporting an exit for a child that may still be alive is the more dangerous direction to guess at, so both are recorded in a separate issue rather than patched blind.

The correction. My comment above says this bug is why unit (windows) is red on dev. It is not, and I should have checked the path before writing that. The failing test is loop waits while shell runs and starts after shell exits in packages/opencode/test/session/prompt.test.ts, and SessionPrompt.shell spawns through ChildProcess.make and CrossSpawnSpawner — there is no pty anywhere in it. the shell never exited is a different defect of the same shape, filed separately. The argument I built on #37 from that attribution does not hold, and that comment is corrected there too.

---

Generated by Claude Code