`unit (windows)` is red on dev: the V1 shell's wait never ends, and it is not the PTY bug

[Edo771977]

Split out of a wrong attribution in #29. That issue's comment and #37's both said this failure was the lost PTY exit; it is not, and nobody had checked the path.

The failure

unit (windows) has been red on every push to dev since 7f1b836b23 (run 36349524088), with exactly one failing test:

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

packages/opencode/test/session/prompt.test.ts:1747. The command is sleep 0.2; the named wait that fails is awaitWithTimeout(Fiber.await(sh), "the shell never exited", "15 seconds"), so the shell fiber is still running fifteen seconds after a 200ms command. Measured on Linux the whole test is 1.8s.

Why it is not #29

There is no pseudoterminal in this path at all. SessionPrompt.shell → shellImpl (packages/opencode/src/session/prompt.ts:458) builds ChildProcess.make(sh, args, …) and spawns it through ChildProcessSpawner, provided by CrossSpawnSpawner.node (packages/opencode/src/tool/registry.ts:449). #pty and bun-pty appear nowhere in it. #29's defect cannot reach this test, and #29's fix will not turn this job green.

It is the same shape as #29 — a process that ends and a wait that is never released — which is presumably why it was misread.

The lead

packages/core/src/cross-spawn-spawner.ts. The exit signal is resolved only on close, never on exit:

proc.on("exit", (...args) => { exit = args })
proc.on("close", (...args) => {
  if (end) return
  end = true
  Deferred.doneUnsafe(signal, Exit.succeed(exit ?? args))
})

and handle.exitCode is Deferred.await(signal). close fires only once every stdio stream is closed, not when the child dies — so anything holding a pipe open holds the wait open, with the child long gone.

On Windows those pipes are opened as overlapped rather than pipe:

const pipe = (x) => (process.platform === "win32" && x === "pipe" ? "overlapped" : x)

stdio: overlapped requires the reader to keep reading for the handle to be released. The test's caller does read (Stream.runForEach(Stream.decodeText(handle.all), …)) and then awaits handle.exitCode, so the plausible readings are that one of stdout/stderr never reaches its end event under overlapped, or that the merge of the two leaves one side unread once the other has ended. Neither is measured yet — this issue is the diagnosis, not the cause.

Worth checking against the same file's release path, which treats win32 specially (if (process.platform === "win32") return yield* Effect.void) and kills through taskkill /T /F.

Why it matters beyond one test

While dev is red on this job, a genuine Windows regression in any pull request is indistinguishable from it. That cost was recorded on #29 and belongs here instead: three consecutive unit (windows) failures on #37 had three different causes and none of them was the change under review.

If the resolution is really about close versus exit, it is not test-only: every V1 shell invocation, every shell tool call and every mcp child process on Windows waits on the same deferred.

[Edo771977]

Two leads closed, two still open, and the instrument fixed

No fix yet. What follows is what a day of reading settled, including one lead of my own that died and one probe that lied to me.

Closed: the merged stream is not abandoning a pipe

shellImpl drains handle.all, which is Stream.merge(stdout, stderr). The obvious mechanism was a halt strategy that ends the merge when the first side ends, leaving the other pipe unread and therefore unclosed — which would keep the child's close from ever firing. Effect 4's own documentation kills it (Stream.ts:4133):

By default, the merged stream ends when both streams end. Use haltStrategy to change the termination behavior.

Both pipes are drained. Not this.

Closed, mostly: close does fire for a plain piped child on Windows

packages/core/test/effect/cross-spawn-spawner.test.ts already awaits handle.exitCode with nobody reading the streams ("returns exit code", "returns non-zero exit code"), on a child whose stdio is piped — which on Windows this spawner opens overlapped. That file runs on Windows and those tests pass. So the exit path is not simply broken there, which is the evidence against my own leading suspicion below. Worth stating plainly rather than leaving it flattering.

Still open: two deviations from the spawner this one was forked from

packages/core/src/cross-spawn-spawner.ts is a copy of Effect's NodeChildProcessSpawner with cross-spawn swapped in for spawn. It differs from upstream in exactly two Windows-relevant ways, neither of them commented:

1. It resolves the exit on close, not exit (cross-spawn-spawner.ts:276-283): exit only captures the code into a variable, and the deferred every wait hangs off is completed in the close handler. Upstream completes it in exit (NodeChildProcessSpawner.ts:325-326, and again at 497) and installs no close handler at all. close fires only once every stdio stream has closed, so under our version anything holding a pipe open holds handle.exitCode open with the child long dead.
2. It opens Windows pipes overlapped (cross-spawn-spawner.ts:155): process.platform === "win32" && x === "pipe" ? "overlapped" : x. Upstream contains the string zero times. overlapped sets FILE_FLAG_OVERLAPPED and wants the reader to keep reading.

Together they are the shape of this bug: a wait that cannot end, for a fixed duration, only on Windows. Apart, neither is established — see the paragraph above.

Not changed here, deliberately. Every child process in this product goes through that file (git, the LSP, MCP servers, the shell tool, snapshots), it is the one platform that cannot be run locally, and this issue's parent has been burned three times by fixes chosen ahead of evidence.

Still open: the resolved shell

On Windows Shell.preferred() with no configured shell is win()[0] — the first of pwsh, powershell, Git Bash, COMSPEC (shell.ts:98-121) — and Shell.args gives a PowerShell ["-NoProfile", "-Command", command] (shell.ts:198). So the failing test's sleep 0.2 is most likely pwsh -NoProfile -Command "sleep 0.2", where sleep is an alias of Start-Sleep. Nothing recorded which shell it actually was, which is the gap #11 asked about twice and which is now closed by the logging below.

What just landed, and what it will say

Diagnosis only, on claude/relaxed-newton-tk13z8:

• SessionPrompt.shellImpl logs the resolved shell, command and cwd before spawning, and logs again when the spawn block returns, so a stall says which side of the spawn/drain/exit block it is on.
• Three tests in the spawner's own suite, in the shape that call uses (stdin: "ignore", forceKillAfter, the merge of stdout and stderr), each wait bounded with its own message: the merged output ending, the exit code arriving after it, and both for the preferred shell running a command. On Windows one of them either names the step that stops, or all three pass and the spawner is exonerated — which narrows this to shellImpl and the shell itself.

The probe that lied, recorded because it is the same class of error as #12

The bounded waits were written under fx.effect first. That harness runs against a TestClock where virtual time never advances (packages/core/test/lib/effect.ts:71), so every timeout under it is dead — the tests reported the suite ceiling and none of their own messages, and a probe built the same way read as "a drain over a child's output cannot be interrupted", which is false. Switched to fx.live, the bounds fire at 2044ms and 4046ms and the scope still closes cleanly.

That is the same failure mode as #12: an instrument that silently produces nothing, read as information. Worth one line in whatever gets written about diagnosing this next.

One product hazard found on the way

Between shellImpl's Effect.exit of the spawn block and its finish, the fiber is holding a pending interrupt whenever the command was aborted. finish survives that only because it is Effect.uninterruptible; any interruptible effect placed between them silently stops it from running at all — the part stays running and the caller's wait never ends. Found by putting a log line there: cancel interrupts loop queued behind shell hung for its full 30s ceiling. The line moved inside finish and the constraint is now commented, but the invariant is invisible at the call site and nothing enforces it.

---

Generated by Claude Code

[Edo771977]

The diagnosis run came back green, which is itself the most useful thing in it

Workflow test dispatched on claude/relaxed-newton-tk13z8 at e7f27a1a83 (run 36419991075): all four jobs green, unit (windows) included. So this failure did not reproduce, and three things follow.

The failures track runner throughput, monotonically

Three runs of the same 3777 tests in opencode#test on windows-latest:

opencode#test	failures
1341.59s	none
1555.50s	1 — workspace waitForSync, an explicit 7000ms budget
2087.00s	5 — instance bootstrap at its 120s ceiling, two afterEach cascades behind it, and both shell waits

A 56% spread in runner speed for identical work, and the failures appear in order of it. Every one of them is a clock. This is correlation over three points, not a mechanism, but it says where to look: the shell stall lives on the slow tail, and a green run is not evidence that anything is fixed.

Which corrects something #11 and I have both been repeating

#11 argued that the failure's duration being stable — 17138ms and 17085ms, 53ms apart — meant "something stops rather than runs slow", because a slow machine varies. That inference does not hold, and I repeated it. The duration is dominated by the named wait's own 15s bound plus a couple of seconds of setup, so any failure of that wait lands near 17s however far past the bound the real work would have gone. Today's slow run gave 16281ms and 16071ms for the same two tests. The stability is the bound's, not the bug's.

So the open question is sharper than this issue states: is the shell wait a genuine stall, or is a cold pwsh on a starved runner simply taking longer than 15 seconds? Nothing measured so far separates those.

The instrumentation is in place and is silent by design until it is needed

shellImpl now logs the resolved shell before spawning and logs again when the spawn block returns. Neither line appears in this green log, and that is correct rather than broken: packages/opencode/test/lib/effect.ts:60-66 collects the captured console only when the test fails (if (Exit.isSuccess(exit)) return { exit, logs: [] }), which is what #13 built. So the next red run on that job answers both halves at once — which of pwsh, powershell, Git Bash or COMSPEC was resolved, and whether the spawn/drain/exit block returned at all.

What did run, and passed

The three new bounded tests in packages/core/test/effect/cross-spawn-spawner.test.ts passed on Windows: the merged output of a child that wrote to both streams ends, the exit code arrives after that drain, and both hold for the preferred shell running a command through Shell.args. That is a baseline, not an exoneration — the shape works on a healthy Windows runner, so if it stalls on a starved one the cause is starvation or something that only starvation exposes.

Cost: packages/core went from 1136 tests in 145.10s to 1139 in 161.23s on this job, and the three tests are bounded well under their ceilings.

---

Generated by Claude Code

[Edo771977]

Retracting the "one product hazard found on the way"

The comment above claims that between shellImpl's Effect.exit of the spawn block and its finish, an interruptible effect silently stops finish from running, and cites a log line that made cancel interrupts loop queued behind shell hang for its full 30s ceiling. Both halves are wrong.

The mechanism cannot happen. shellImpl runs entirely inside Effect.uninterruptibleMask (packages/opencode/src/session/prompt.ts:459), and the only interruptible part is the restore(...) block holding the spawn, the drain and the wait for the exit code. So a line between that block and finish is already uninterruptible and cannot unwind the fiber. What is true, and testable, is the converse: finish must stay uninterruptible — changed to Effect.interruptible, that test fails in about two seconds.

The observation was a flaky test. My before/after was not a comparison: the "after" ran a 15-test filter and the "before" ran one test. Run properly, cancel interrupts loop queued behind shell fails 1 run in 4 with no log lines at all, on four cores, on an unmodified checkout. That is now #44, along with the measurement and one thing worth knowing for this issue: the layer under shellImpl is not where it is stuck — interrupting a drain of sleep 30 through the resolved preferred shell and releasing the scope is 10/10 clean in 2–7ms, so the close-versus-exit deviation recorded above is not that failure's mechanism either.

Which leaves a thing to notice about this issue: #44 is the same question as this one — a shell that ends and a wait that does not — reproducing on Linux, where this issue's failure has never been seen. Two of the three tests in that file got named, bounded waits from #28 and this one did not, which is why its failure says nothing. That asymmetry is the cheapest lead either issue has.

The code changes from this round stand and are unaffected: the resolved shell is still logged, the second line still sits inside finish (for a plain reason — it is next to the state it reports), and the three bounded spawner tests are unchanged except that the drain bound now names which shell it was draining.

---

Generated by Claude Code