fix(cli): keep the published binary's stderr off the blocking write path (#15496)

`bin/run.js` now installs `keepStderrNonBlocking()` before oclif can write a
byte, and the guard compiles from `src/` into `dist/` so a published install
actually carries it.

Measured on the built binary: `os dev --verbose` piped to a reader that stops
draining parks the main thread in `write(2)` 3.1 s later, 4 of 4 runs, fd 2,
`O_NONBLOCK=false`, `wchan=sock_alloc_send_pskb` — parked 28.9 s, ignoring
SIGINT, released only by the reader resuming. The clearing that persisted came
from a grandchild (the esbuild service, inherited stderr), so the re-assert has
to sit on the write path rather than run once at startup.


Claude-Session: https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

.changeset/published-cli-stderr-nonblocking-guard.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/cli": patch
+---
+
+The published `os` binary no longer freezes in the kernel when whatever is reading its output stops draining.
+
+Node puts the CLI's stderr on the non-blocking write path when it opens the pipe, so a write to a reader that has stopped is buffered rather than parking the thread. libuv clears that flag again in the pre-exec of every child spawned with **inherited** stdio — and inheriting is `dup2`, so the flag lives on an open file description the spawner shares. Clearing it for the child clears it for the CLI too.
+
+Measured on the built binary, `os dev --verbose` with its output piped to a reader that stopped draining: `os dev` spawns `os serve --dev` with inherited stdio at 2.8 s, that child spawns the esbuild service with inherited stderr at 5.2 s, and fd 2 stays blocking for the rest of the run. 3.1 s after the reader stopped, the main thread sat in `write(2)` (`wchan=sock_alloc_send_pskb`), 4 of 4 runs — parked 28.9 s, **ignoring SIGINT while parked**, and released only when the consumer resumed. Not a crash and not a timeout: alive, idle, unresponsive, with an empty log. Anything that pipes `os dev` and reads it slowly — a CI log collector, a backgrounded runner, a supervisor that stops draining while it does work — could park the CLI this way.
+
+`bin/run.js` now installs `keepStderrNonBlocking()` before oclif can write a byte. The guard re-asserts `O_NONBLOCK` immediately ahead of each write, which is what the measurement requires: the clearing that persisted was made by a **grandchild** the CLI does not spawn and cannot see, so a one-shot at startup would be undone silently and no change to the CLI's own spawn sites would have prevented it.
+
+The guard itself is not new — it shipped in no published install. It lived at `packages/cli/bin/stderr-nonblocking.mjs`, and `files` names only `dist`, `README.md` and `CHANGELOG.md`; npm packs a `bin` **target** regardless of `files`, which is why `bin/run.js` reached every install and the module beside it reached none. It now compiles from `src/utils/stderr-nonblocking.ts` into `dist/`, under the whitelist that was already there.
+
+Nothing about which arguments the CLI accepts, what it prints, or what it exits with changes. The refusal of `setBlocking(true)` in `src/utils/format.ts` stands and is untouched — this is its inverse, and what keeps its premise true.

packages/cli/bin/run-dev.js

@@ -13,7 +13,7 @@
 // exactly as it did.
 import { flush, handle, run, settings } from '@oclif/core';
 
-import { keepStderrNonBlocking } from './stderr-nonblocking.mjs';
+import { keepStderrNonBlocking } from '../src/utils/stderr-nonblocking.ts';
 
 /**
  * How long stderr may make NO PROGRESS before this shim stops waiting for it.
@@ -189,7 +189,7 @@ settings.debug = true;
 // kernel with the diagnostic still unwritten, and only a reader or a kill ends
 // it. Measured that way on an unbuilt workspace with the reader gone — 27 of 30
 // cold-cache runs, main thread in `write(2)` on fd 2 at `sock_alloc_send_pskb`,
-// still alive at a 90 s ceiling. `stderr-nonblocking.mjs` carries the whole
+// still alive at a 90 s ceiling. `src/utils/stderr-nonblocking.ts` carries the whole
 // derivation, including who clears the flag (a child spawned with inherited
 // stdio — libuv clears `O_NONBLOCK` on the SHARED open file description) and
 // why the re-assert has to sit on the write path rather than run once here.

packages/cli/bin/run.js

@@ -6,7 +6,7 @@
 //
 // It used to be `await execute({ type: 'esm', dir: import.meta.url })`. What is
 // inlined below IS `execute()` from @oclif/core 4.13.3, verbatim apart from the
-// one added line, because `execute` swallows the error into `handle()` and
+// added lines, because `execute` swallows the error into `handle()` and
 // there is no hook between the two. `handle()` writes the parse error and then
 // a full usage dump; #10111 needs one unmistakable line to reach stderr FIRST,
 // so a backgrounded runner that skims its log reads "the command never ran"
@@ -37,6 +37,39 @@ async function announceInvocationFailure(error) {
   }
 }
 
+// ⚠️ BEFORE `run()`, and that order is the whole point rather than tidiness.
+//
+// Node puts fd 2 on the NON-blocking path when it opens the pipe, and libuv
+// clears that flag again in the pre-exec of any child spawned with inherited
+// stdio — on the SHARED open file description, so the spawner loses it too.
+// This binary is the one that spawns: `os dev` starts `os serve --dev` with
+// inherited stdio, and that child starts the esbuild service with inherited
+// stderr. Measured on the built binary with its output piped to a reader that
+// stopped draining: fd 2 was left blocking from 5.2 s onward and the main
+// thread then sat in `write(2)` (`wchan=sock_alloc_send_pskb`) 3.1 s later, 4
+// of 4 runs — alive, idle, ignoring SIGINT, empty log, released only when the
+// consumer resumed. `src/utils/stderr-nonblocking.ts` carries the whole
+// derivation, including why the re-assert has to sit on the write path rather
+// than run once here: the clearing that persisted came from a GRANDCHILD this
+// process does not spawn and cannot see.
+//
+// Everything the CLI writes to stderr is written after this point — oclif's own
+// output starts inside `Config.load()`, i.e. inside `run()` — so a guard
+// installed here has not missed a write.
+//
+// Lazily imported for the reason `announceInvocationFailure` states above: a
+// STATIC `../dist/` import would turn an unbuilt tree's "command not found"
+// into a module-resolution error and break the classification every gate that
+// shells out to this CLI depends on. ⛔ The `catch` therefore degrades to the
+// behaviour this file had before the guard existed; it must never become a
+// report, because the only stream it could report on is the one being repaired.
+try {
+  const { keepStderrNonBlocking } = await import('../dist/utils/stderr-nonblocking.js');
+  keepStderrNonBlocking();
+} catch {
+  // Unbuilt or half-built tree — nothing to install and nothing to say.
+}
+
 await run(process.argv.slice(2), import.meta.url)
   .then(async (result) => {
     flush();

packages/cli/bin/stderr-nonblocking.mjs

@@ -0,0 +1,139 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Keep this process's stderr writes off the BLOCKING path for the whole run.
+ *
+ * Installed by BOTH CLI entry points — `bin/run.js` (the published `bin`
+ * target) and `bin/run-dev.js` (the source shim) — immediately before `run()`.
+ *
+ * ## Why this module lives in `src/` and not beside the shims in `bin/`
+ *
+ * It was written in `bin/`, next to its only caller at the time. That put it
+ * outside everything npm ships: `files` names `dist`, `README.md` and
+ * `CHANGELOG.md`, and npm packs a `bin` TARGET regardless of `files` — which is
+ * why `bin/run.js` reaches a published install and a sibling module beside it
+ * does not. `npm pack --dry-run` listed `bin/run.js` as the only packed file
+ * under `bin/`, so NO published install carried the guard at all while the
+ * defect it prevents was reproducing on the shipped binary. Compiling from
+ * `src/` puts it under the existing whitelist instead of widening it.
+ *
+ * ## The premise, and the measurement that made it false
+ *
+ * Node makes the premise true when it opens the pipe: `uv_pipe_open()` sets
+ * `O_NONBLOCK` on fd 2 the moment `process.stderr` is first touched, so a write
+ * to a reader that has stopped is BUFFERED rather than parking the thread
+ * inside `write(2)`. What is easy to miss is that libuv CLEARS it again in the
+ * pre-exec of every child spawned with inherited stdio
+ * (`uv__process_child_init` does exactly that for fds 0-2, deliberately,
+ * because a child expects blocking stdio) — and since inheriting is `dup2`, the
+ * child shares the parent's OPEN FILE DESCRIPTION. The flag lives on the
+ * description, not on the fd number, so clearing it for the child clears it for
+ * the SPAWNER TOO.
+ *
+ * Measured on the PUBLISHED binary, `node bin/run.js dev --verbose` with its
+ * output piped to a reader that stopped draining, sampling `/proc/PID/fdinfo/2`
+ * from outside the process every 50 ms:
+ *
+ * ```
+ *   112 ms  fd2 O_NONBLOCK=true    process.stderr materialised
+ *  2829 ms  fd2 O_NONBLOCK=false   `os dev` spawns `os serve --dev`, stdio inherit
+ *  2930 ms  fd2 O_NONBLOCK=true    the serve child materialised ITS OWN stdio
+ *  5244 ms  fd2 O_NONBLOCK=false   the esbuild service, a GRANDCHILD, inherits stderr
+ * ```
+ *
+ * and from there the main thread of the `os serve --dev` child never left
+ * `write(2)`, 4 of 4 runs, 3.1 s after the reader stopped:
+ *
+ * ```
+ * syscall=1(write) fd=2 O_NONBLOCK=false state=S wchan=sock_alloc_send_pskb
+ *     tid=… (node) syscall=1(write)      ← the MAIN thread
+ * ```
+ *
+ * Parked 28.9 s; SIGINT was IGNORED while parked (3 of 3, alive and still in
+ * `write` five seconds later); released only when the reader resumed. With the
+ * loop parked in the kernel there is no late timer to catch up and no signal
+ * handler to run: the process is alive, idle, unresponsive, with an empty log.
+ *
+ * ## Why the re-assert is on the WRITE path and not done once at startup
+ *
+ * Because the clearing that PERSISTS is not made by this process. On the
+ * published path it came from esbuild — spawned by the `os serve --dev` child,
+ * two levels below the `os dev` parent, with only stderr inherited — 5.2 s into
+ * the run, and no change to any of this CLI's own spawn sites would have
+ * prevented it. The same holds under `tsx`, where the service is spawned when a
+ * module has to be transformed (measured 27 of 30 on a cold transform cache
+ * against 1 of 90 on a warm one). A one-shot at startup is undone by the next
+ * such spawn — including from a module-hooks worker thread, which shares the
+ * same descriptions — and it fails SILENTLY, back into the hang it was meant to
+ * prevent. Re-asserting immediately before each write costs one `fcntl` and
+ * cannot be outrun by a later spawn, whoever makes it.
+ *
+ * ⚠️ The reverse also happens and must not be mistaken for a fix: any Node
+ * child that materialises its own stdio re-SETS the flag on the shared
+ * description ~100 ms later. That is why fd 1 tends to escape and fd 2 does
+ * not, and why "it was true the last time I looked" is worth nothing here.
+ *
+ * ## ⛔ This is not the prohibited call, it is its inverse
+ *
+ * `bin/run-dev.js` and `src/utils/format.ts` both refuse
+ * `_handle.setBlocking(TRUE)`, and that refusal stands: forcing blocking writes
+ * process-wide is what stalls `os serve` / `os dev` on its own logs. This
+ * function forces the other direction — it is the thing that KEEPS those two
+ * docblocks true when something else has quietly flipped the flag.
+ *
+ * ⛔ It does not touch a TTY. A terminal is written synchronously on POSIX by
+ * design, has no unread-reader failure mode (the reader is a human's terminal),
+ * and prompt-adjacent output would change behaviour for no benefit.
+ */
+
+/** Marks the stream so a second install cannot stack wrappers. */
+const INSTALLED = Symbol.for('objectstack.stderr-nonblocking');
+
+/**
+ * The libuv handle behind a stdio stream. Not in `@types/node` — it is an
+ * internal — so the shape this module actually uses is named here rather than
+ * reached for through `any`.
+ */
+interface BlockingCapableHandle {
+  setBlocking(blocking: boolean): void;
+}
+
+/** `stream.write`, seen as the plain callable this module re-invokes. */
+type StreamWrite = (...args: unknown[]) => boolean;
+
+/**
+ * @param stream The stream to guard; defaults to `process.stderr`.
+ *   Parameterised for the pin, which drives the guard against a manufactured
+ *   blocking pipe rather than waiting for a cold cache.
+ * @returns `true` when this process's writes are now guarded, `false` when
+ *   there was nothing to guard (a TTY, a file, a stream with no libuv handle).
+ *   The boolean is returned rather than logged: a reporter that announces
+ *   itself on the very stream it is repairing is the one thing this file must
+ *   not do.
+ */
+export function keepStderrNonBlocking(stream: NodeJS.WriteStream = process.stderr): boolean {
+  if (!stream || stream.isTTY === true) return false;
+  const handle = (stream as unknown as { _handle?: BlockingCapableHandle | null })._handle;
+  if (!handle || typeof handle.setBlocking !== 'function') return false;
+
+  const marks = stream as unknown as Record<symbol, boolean | undefined>;
+  if (marks[INSTALLED]) return true;
+
+  const target = stream as unknown as { write: StreamWrite };
+  const write = target.write;
+  if (typeof write !== 'function') return false;
+
+  marks[INSTALLED] = true;
+  target.write = function guardedWrite(this: unknown, ...args: unknown[]): boolean {
+    // One `fcntl`, immediately ahead of the syscall that would otherwise park
+    // this thread. Wrapped because a stream that lost its handle mid-run must
+    // still take the write — a repair that throws is worse than the defect.
+    try {
+      handle.setBlocking(false);
+    } catch {
+      // Nothing to say and nowhere safe to say it.
+    }
+    return write.apply(this, args);
+  };
+  return true;
+}