fix(cli): flush stdout before exiting on a signal (OX-L8)

[ojassug]

Closes OX-L8, the last open oxaudit item that was a defect rather than a decision. Lifted from the audit/lane-a2 worktree — then rewritten, because the fix it carried does not work.

The item, and why it was left open

process.exit() discards whatever a stream still holds, so tokendamper mcp exiting the instant stop() returned lost any JSON-RPC frame still buffered.

It was recorded rather than fixed for a stated reason: "delivering SIGINT to exercise that is not something the suite can do here", so a change would ship unverified — and the fix contemplated at the time, dropping the forced exit to let the loop drain, risked tokendamper mcp hanging on Ctrl+C instead. Both halves are answered here.

Measured first, because the platform decides whether this bug exists

Node's stdout is synchronous for pipes on Windows and Linux, asynchronous on macOS, and the buffer only overflows on a large frame. A child writing 1 MB and exiting the way this handler does:

Platform	Delivered
Windows	1,000,046 / 1,000,046 — complete
Linux	146,176 / 1,000,046 — truncated

Then end to end through the real product on Linux — a 900 kB MCP response with SIGINT delivered mid-stream:

	Bytes received	Final frame
Without fix	365,696	did not parse
With fix	900,819	complete

lane-a2's fix does not work

The other worktree's change was await server.stop(). stop() is (): void, so the await yields one microtask — and a microtask does not run the I/O loop that drains a pipe. Measured: 146,176 / 1,000,046, byte for byte identical to no fix at all.

Porting it as-is would have shipped something that reads as a fix in the changelog and changes nothing. That is the failure mode this review keeps finding, so it is recorded rather than repeated.

What actually works

Ask the stream. An empty write queues behind everything already pending, so its callback is the stream reporting that its bytes reached the OS.

The 2 s cap answers the hang objection: the exit is still forced, merely deferred, so a consumer that never reads cannot wedge shutdown. unref keeps the timer from holding the loop open.

The test

test/unit/cli/sigint-flush.test.ts pins the ordering deterministically — it holds the write callback rather than waiting on a clock, so it cannot pass by timing accident. Three cases: the flush defers the exit, the cap fires when no flush is reported, and the exit happens exactly once when both occur.

All three fail against the unfixed handler, verified by reverting main.ts and re-running (expected "spy" to not be called at all, but actually been called 1 times). A green from a test that cannot detect the defect would have been worthless here.

Checks

99 test files / 918 tests pass, 2 skipped (POSIX-only). Typecheck and lint clean. CLI-only change, off the optimize route; no corpus run applies.

🤖 Generated with Claude Code