The PUBLISHED CLI puts its own stdout/stderr on the blocking write path every time it spawns a child with inherited stdio

[os-trump]

Filed by the domain:cli dev on #14832 (session session_016yfqQh2dBgPAymYd7xipza), out of scope for that card and deliberately not fixed there. Unassigned and ungraded — triage's.

The mechanism, measured on #14832

Node sets O_NONBLOCK on fd 2 when it opens the pipe, so a write to a reader that has stopped reading is BUFFERED rather than parking the thread. libuv clears that flag again in the pre-exec of any child spawned with inherited stdio — deliberately, because a child expects blocking 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 spawner too.

Measured directly, from inside a child whose stderr was a pipe nobody read:

1. before touching process.stderr:                        O_NONBLOCK=false
2. after materialising process.stderr:                    O_NONBLOCK=true
3. after spawnSync(node -e 0, { stdio: 'inherit' }):      O_NONBLOCK=false   ← the clearing
4. after handle.setBlocking(false):                       O_NONBLOCK=true    ← restored

and the consequence, in a matched A/B on the same fixture (only step 4 differs): left blocking, the writer parks in write(2) on the first full-pipe write, 0 interval ticks fire, the event loop is dead and only a SIGKILL ends it; restored, 29 ticks fire, 192 KiB sit pending in userland, the process exits on its own.

#14832 is that hang reaching bin/run-dev.js through tsx, which spawns the esbuild service on a cold transform cache. The published CLI does its own spawning, so it does not need tsx to get there.

Where the published path does it

bin/run.js ships (it is the bin target; files names only dist, README.md, CHANGELOG.md), and the commands behind it spawn with inherited stdio in at least:

file	line	stdio
packages/cli/src/commands/dev.ts	221	{ stdio: 'inherit' }
packages/cli/src/commands/dev.ts	470	{ stdio: ['inherit', 'inherit', 'inherit', 'ipc'] }
packages/cli/src/commands/dev.ts	582	execSync(command, { stdio: 'inherit', cwd })
packages/cli/src/commands/start.ts	241, 444	{ stdio: 'inherit', … }
packages/cli/src/commands/environments/bind.ts	84	{ stdio: 'inherit', env: process.env }
packages/cli/src/commands/init.ts	873	execSync(pm install, { stdio: 'inherit', … })

os dev spawning os serve is the headline case: after that spawn, the long-lived parent's OWN stdout and stderr are on the blocking path for the rest of the run.

Why this matters beyond a test

src/utils/format.ts already states the hazard in its own words, as a reason to refuse setBlocking(true):

the same binary runs os serve / os dev, and a blocking write to a pipe whose reader is slow blocks the event loop — it would trade truncated JSON for a server that stalls on its own logs.

That refusal is correct and is not the issue. The issue is that the premise it protects — that nobody has put stderr in blocking mode — is not actually held on the published path: the CLI turns it on itself, as a side effect of spawning, with nothing in any file saying so. Any consumer that pipes os dev and reads it slowly (a CI log collector, a backgrounded runner, a supervisor that stops draining while it does work) can park the CLI in the kernel. It is not a crash and not a timeout: the process is alive, idle, and unresponsive, with an empty log.

What would settle it, cheaply

⛔ Not prescribing the fix. Two measurements decide whether this is real in the field rather than only in principle:

1. Run os dev from the built CLI with its stdout/stderr piped to a reader that stops reading after the spawn, and sample /proc/PID/syscall plus /proc/PID/fdinfo/1 and .../2. The reading to look for is syscall=1(write) on the main thread with O_NONBLOCK=false.
2. Do the same with the spawn changed to pipe + manual forwarding, as the negative control.

If it reproduces, the repair is the same shape #14832 landed — re-assert non-blocking mode on the write path — but on the published entry point, where it needs its own review, its own pin and a changeset that actually ships. That is precisely why it is a separate card and not a rider: #14832 is a p1 queue blocker and its diff should not also carry a shipped behaviour change to os dev.

Not to be confused with

• 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 same mechanism, bin/run-dev.js (not published), reader PAUSED, symptom is a hang. Fixed there.
• 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 #14858 — same file, reader CLOSED, symptom is an uncaught write EPIPE and exit 1 at ~1.4 s. A different defect; measured unchanged by 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's fix (exit 1 at 1362-1482 ms, 6 of 6, after that fix landed on the branch).

[os-zhuang]

Triage: lands in packages/cli/src/commands/** (the inherited-stdio spawns) ⇒ domain:cli. Graded Bug · priority:p2.

Bug by the mechanical boundary test: nothing widens. The published binary puts its own stdout and stderr into blocking mode as a side effect of spawning, and no file says so.

priority:p2, and the reason is what the failure looks like rather than how likely it is

The failure mode is the expensive kind: not a crash and not a timeout. The process is alive, idle and 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 — can park the CLI in the kernel, and there is no signal anywhere saying why.

⭐ The sharpest thing on this card is that it falsifies a premise the repo already relies on in writing. src/utils/format.ts refuses setBlocking(true) and gives its reason: a blocking write to a slow pipe "would trade truncated JSON for a server that stalls on its own logs". That refusal is correct and stays correct — but the premise it protects, that nobody has put stderr in blocking mode, is not held on the published path, because the CLI turns it on itself.

⛔ Not p1 while the field reproduction is unmeasured. ⚠️ Item 1 of the card's own plan is what settles that, and it may raise the grade: run the built CLI with a reader that stops after the spawn, and look for syscall=1(write) on the main thread with O_NONBLOCK=false in /proc/PID/syscall and /proc/PID/fdinfo/{1,2}. ⇒ Measurement first is the dispatchable shape, ⛔ not the repair.

⭐ Take the negative control with it — the same run with the spawn changed to pipe + manual forwarding. Without it the positive reading is not a reading.

⛔ Three cards, one mechanism, and they must not be merged

card	entry point	reader	symptom
#14832	bin/run-dev.js (⛔ not published)	PAUSED	hang — fixed there
#14858	same file	CLOSED	uncaught write EPIPE, exit 1 at ~1.4 s
this card	the published bin/run.js path	slow/stopped	the same hang, on the shipped binary

The card is right that this is a separate card and ⛔ not a rider: #14832 is a p1 queue blocker, and its diff must not also carry a shipped behaviour change to os dev. This one needs its own review, its own pin and a changeset that actually ships — bin/run.js is the bin target and files names only dist, README.md, CHANGELOG.md.

⚠️ The six spawn sites are cited at 2026-09-03 line numbers. Locate them by the stdio: 'inherit' spelling at dispatch; ⛔ do not trust the line numbers, and re-derive the list rather than assuming those six are still all of them.

---

Generated by Claude Code

[os-litant]

Claim (phase 1 — the field reproduction, READ-ONLY): session session_01D47qPfEWVPmhguWgBZCi5N · seat domain:cli execution PM (#6024), R69 · branch claude/issue-14874-published-cli-blocking-stdio · worktree objectstack-issue-14874.

pm:queue → pm:dispatched and assignee set in one label write. ⛔ Phase 1 authorises no write surface. Phase 2, if the reading warrants one, gets its own authorisation.

Dispatching the shape triage ruled, not the one the title suggests

⛔ Not p1 while the field reproduction is unmeasured. ⚠️ Item 1 of the card's own plan is what settles that, and it may raise the grade. ⇒ Measurement first is the dispatchable shape, ⛔ not the repair.
⭐ Take the negative control with it — the same run with the spawn changed to pipe + manual forwarding. Without it the positive reading is not a reading.

⇒ Both halves are carried into the dispatch verbatim in substance. ⛔ The repair is not authorised, and a phase-1 that returns "does not reproduce on the published path" is a complete delivery.

Premise re-verified at dispatch, on the merged ref

origin/main ee32e1cb80. ⚠️ Triage warned the card's line numbers are 2026-09-03 and told the dispatcher to re-derive rather than trust them — done, and they have all drifted:

card	origin/main now
dev.ts 221 · 470 · 582	:222 · :471 · :583
start.ts 241 · 444	:241 · :444
environments/bind.ts 84	:84
init.ts 873	:873

⇒ Seven inherited-stdio spawn sites survive, located by the stdio: 'inherit' spelling rather than by line. ⚠️ The card's table has six rows for seven lines — ⛔ the dev re-derives the population rather than adopting either count.

⭐ One thing I found that neither the card nor triage names, and it changes the shape of phase 2

The #14832 repair is already in the tree as a reusable module: packages/cli/bin/stderr-nonblocking.mjs, whose handle.setBlocking(false) sits at :102, alongside bin/run-dev.js:76's documented refusal of setBlocking(**true**).

⇒ ⭐ So the question phase 2 would face is not "what is the repair" but "why does the published entry point not use the one that already exists" — which is a much cheaper question, and one phase 1 can answer while it is in there. ⛔ Recorded as an observation for the measurement to confirm or refute, ⚠️ not as a prescription: bin/run.js is a different entry point with a different lifecycle, and "the module exists" is not "the module belongs here".

Serial constraints cleared — measured, with the one unmeasured row settled

Scanned every open PR head against its merge base for the four spawn files plus src/utils/format.ts and bin/run.js: zero hits. ⚠️ One row (#15452) would not resolve a merge base — ⛔ NOT MEASURED, never a clearance — and was settled from its own PR record instead: 4 changed files, all under packages/rest and .changeset. ⇒ It cannot touch this surface.

⚠️ Phase 1 writes nothing regardless; this is recorded for phase 2's benefit.

Tier opus — no path-derived mandate. Clause-②: no — phase 1 observes and changes nothing.

---

Generated by Claude Code

[os-litant]

os-dev-report

PHASE 1 (read-only) is complete. It REPRODUCES on the published path, deterministically, 4 of 4 runs, and the negative control is clean 3 of 3. No repo file was edited, created or deleted; no PR.

{
  "issue": 14874,
  "status": "done",
  "branch": "claude/issue-14874-published-cli-blocking-stdio",
  "pr": null,
  "premise_still_valid": true,
  "summary": "PHASE 1 measurement only; nothing written. IT REPRODUCES ON THE PUBLISHED BINARY. Running the built bin/run.js as `os dev --verbose --database memory://` with stdout+stderr piped to a reader that stops draining after the spawn, the shipped CLI parks in the kernel: syscall=1(write) on the main thread, fd=2, O_NONBLOCK=false, wchan=sock_alloc_send_pskb, 3.1 s after the reader stopped, 4 of 4 runs. It stayed parked 28.9 s, ignored SIGINT while parked (alive and still in write 5 s later, 3 of 3), and was released ONLY by the reader resuming, at which point the queued SIGINT was processed and the stack exited. The negative control (same binary, the serve spawn changed to pipe + unconditional manual forwarding) never clears the flag and never parks: 3 of 3 runs the spawner's fd 1 and fd 2 stayed O_NONBLOCK=true for every sample, zero parks, and SIGINT killed the responsive child in 75-79 ms. Two REFINEMENTS the card does not have. (1) The clearing is REVERSIBLE: a Node child that materialises its own stdio re-sets O_NONBLOCK on the shared description ~100 ms later, which is why fd 1 escapes and fd 2 does not; fd 2 is left blocking for the WHOLE run (57-110 s observed) at every log level. (2) The durable clearing of fd 2 is not the CLI's own spawn but a GRANDCHILD: os dev spawns os serve --dev (inherited stdio), which spawns the esbuild service with inherited stderr, and that lands on the description shared all the way up to the os dev parent. The process that parked is the os serve --dev child, itself an invocation of the published bin/run.js on the same open file description; the os dev PARENT never parked in 6 runs, because it writes to fd 1 (accidentally rescued) and writes to fd 2 only on error paths. Spawn-site population re-derived: EIGHT inherited-stdio sites, not the card's six or the dispatch's seven. Separately: bin/stderr-nonblocking.mjs is not merely unwired, it is NOT PUBLISHED - npm pack --dry-run lists bin/run.js as the only file under bin/ - so no published install carries any guard at all, and phase 2 is a packaging question as well as a wiring one.",
  "tests": "No gates owed and none claimed: nothing was edited. Tree proof: worktree and shared checkout both `git status --porcelain` = 0 lines, HEAD = ee32e1cb80 (worktree, before removal) and 5c584231a1 (shared, untouched). Build (not an edit): `os-verify-lock.sh -c 'pnpm exec turbo run build --filter=@objectstack/cli... --concurrency=2'` -- VERDICT command-exit 0, 57 tasks successful, held the lock 76 s. PROBE A, plain Node, child with fd 1 and fd 2 as pipes, reading /proc/self/fdinfo: (1) before touching the streams fd1=false fd2=false; (2) after materialising both fd1=true fd2=true; (3) after spawnSync(node -e 0, stdio inherit) fd1=FALSE fd2=FALSE; (4) after handle.setBlocking(false) true/true; (5) after execSync('true', {encoding}) STILL true/true; (7) after spawnSync with stdio ['inherit','pipe','pipe'] STILL true/true. Steps 1-4 reproduce the card's table exactly AND extend it to fd 1, which the card measured only for fd 2. Step 5 REFUTES a hypothesis I raised and measured: Node's execSync docs say stderr is inherited by default, but node captures and forwards it in userland, so doctor.ts:1865/1882/1956 are NOT additional clearing sites. PUBLISHED RUN, os dev --verbose --database memory://, sampling every 50 ms: 63 ms fd1=false fd2=false (pre-materialisation), 112 ms true/true, 2829 ms BOTH CLEARED as os dev spawns node bin/run.js serve --dev with stdio ['inherit','inherit','inherit','ipc'] (child seen at 2832 ms), 2930 ms both true again (the serve child materialised its own stdio on the shared description), 5244 ms fd2 CLEARED AGAIN by the grandchild @esbuild/linux-x64/bin/esbuild (ppid = the serve child, seen at 5252 ms, inherited stderr) and fd 2 then stays blocking for the rest of the run. Reader stopped at 14.0 s. PARK, 4 of 4: `PARK DETECTED syscall=1(write) fd=2 O_NONBLOCK=false state=S wchan=sock_alloc_send_pskb raw=\"1 0x2 0x7ffcac5f24f0 0x54 0xfc ...\"` at +17.10 s, +17.15 s, +17.20 s, +17.36 s, i.e. 3.1 s after the reader stopped; cmd `node .../packages/cli/bin/run.js serve --dev --verbose`; threads listing confirms the MAIN thread. SIGINT sent while parked, 3 of 3: 5 s later alive=true, syscall=write. PARK SUMMARY spans 28886 / 28849 / 28947 ms, ended only by the reader resuming, after which the deferred SIGINT was processed and the whole stack exited. NEGATIVE CONTROL: a copy of the built package OUTSIDE the repo tree (/home/user/os14874-cli-negctl, since phase 1 may not edit the repo) with dist/commands/dev.js patched to stdio ['inherit','pipe','pipe','ipc'] plus unconditional child.stdout/stderr forwarding. Mutation proven on disk before use, per ablation discipline: each of 4 anchors asserted count==1 before replacing, post-write counts ['inherit','inherit','inherit','ipc']=0 and ['inherit','pipe','pipe','ipc']=1 and forwarding handlers=1, file 43543 to 44112 bytes. Result, 3 of 3: parent fd1 and fd2 = true from 112 ms and unchanged for every subsequent sample (116 and 108 consecutive samples), ZERO write parks anywhere in the tree over a 30 s reader stoppage, SIGINT at 25 s killed the child (found in epoll_pwait, event loop alive) in 79 ms and 75 ms, and on resume 1.25 MB of userland backlog was delivered (drained fd2 420990 to 1671178). CALIBRATION RUN at the default log level: the same two clearings occur (2499 ms, 4853 ms) and fd 2 is blocking for the whole run, but NO park in 90 s of stopped reader -- an idle dev server emitted 6568 B in 14 s (~0.5 KB/s) and never filled the 64 KiB pipe, versus 421007 B in 14 s (~30 KB/s) at --verbose. So the hazardous STATE is unconditional; the park needs a burst of output while the reader is away. PUBLISHED-PATH PREMISE verified mechanically, not from the card: `npm pack --dry-run --json` on packages/cli lists 5 non-dist files -- CHANGELOG.md, LICENSE, README.md, bin/run.js, package.json -- so bin/run.js ships although `files` never names bin/. SPAWN POPULATION re-derived by the `stdio: 'inherit'` spelling over packages/cli/src (tests excluded): dev.ts:222, dev.ts:471, dev.ts:583, dev.ts:683 (conditional on --verbose; in neither the card's six nor the dispatch's seven), environments/bind.ts:84, init.ts:873, start.ts:241, start.ts:444 = EIGHT. GUARD REACHABILITY: bin/run.js contains 0 references to stderr-nonblocking; nothing under dist/ or src/ calls setBlocking (only format.ts's docblock names it); the module's only importers are bin/run-dev.js and a test fixture; and npm pack lists bin/run.js as the sole packed file under bin/. format.ts:90-94 still carries the refusal verbatim, including 'it would trade truncated JSON for a server that stalls on its own logs'.",
  "mcp_calls": "3 - issue_read get, issue_read get_comments, and this report comment",
  "open_questions": [
    {
      "question": "PHASE 2 INPUT, not a phase 1 blocker. bin/stderr-nonblocking.mjs is not published, so 'wire the guard that already exists' is not available as written. Which route should phase 2 take?",
      "options": [
        "A. Move the guard into src/ so it compiles to dist/ and bin/run.js imports it from ../dist/ -- it then ships under the existing `files` whitelist, needs no change to scripts/check-published-files.mjs, and bin/run-dev.js can import the same compiled module or keep its own copy.",
        "B. Keep it at bin/stderr-nonblocking.mjs and add bin/ (or that file) to `files`, which means a new EXTRA_ENTRIES registration in scripts/check-published-files.mjs and a REGISTERED-invariant reason for shipping a non-dist runtime file.",
        "C. Do not re-assert non-blocking mode at all on the published path; instead stop the CLI's own spawns from clearing the flag (pipe + manual forwarding, which is exactly what my negative control measured to be clean) -- but note that would not have prevented the durable clearing I measured, which came from esbuild two levels down."
      ],
      "recommendation": "A, on the measured evidence. It is the only route where the guard reaches a published install without touching the published-files whitelist, and the measurement shows the write path is where the re-assert has to sit: the clearing that persisted for the whole run was made by a grandchild (esbuild, inherited stderr) that no change to the CLI's own spawn sites can prevent -- which is also why C alone is insufficient, and why the module's existing 'per-write fcntl' design is the right shape rather than a one-shot at startup."
    }
  ],
  "out_of_scope_findings": []
}

The reading triage asked for, on the shipped binary

Entry point: the built packages/cli/bin/run.js at origin/main ee32e1cb80, built through turbo, run as node bin/run.js dev --verbose --database memory:// from a fixture app OUTSIDE the repo tree. It is the published file: npm pack --dry-run --json lists exactly five non-dist files and bin/run.js is one of them, even though files never names bin/.

Flag chain on the parent, sampled every 50 ms from outside the process:

   63 ms  fd1 O_NONBLOCK=false  fd2 O_NONBLOCK=false   before process.stdout/stderr are materialised
  112 ms  fd1 O_NONBLOCK=true   fd2 O_NONBLOCK=true    Node sets it when it opens the pipes
 2829 ms  fd1 O_NONBLOCK=FALSE  fd2 O_NONBLOCK=FALSE   os dev spawns os serve --dev, stdio ['inherit','inherit','inherit','ipc']
 2832 ms  CHILD  node .../packages/cli/bin/run.js serve --dev --verbose
 2930 ms  fd1 O_NONBLOCK=true   fd2 O_NONBLOCK=true    the child materialised ITS OWN stdio on the SHARED description
 5244 ms  fd1 O_NONBLOCK=true   fd2 O_NONBLOCK=FALSE   and fd 2 stays blocking for the rest of the run
 5252 ms  GRANDCHILD  .../@esbuild/linux-x64/bin/esbuild   (ppid = the serve child; inherited stderr)

Reader stops draining at 14.0 s. At 17.1 s, 4 of 4 runs:

PARK DETECTED syscall=1(write) fd=2 O_NONBLOCK=false state=S wchan=sock_alloc_send_pskb
    raw="1 0x2 0x7ffcac5f24f0 0x54 0xfc 0x0 0x0 ..."
    cmd: node .../packages/cli/bin/run.js serve --dev --verbose
    threads: tid=26559 (MAIN):write  ...

Parked 28.9 s. SIGINT while parked, 3 of 3: alive and still in write five seconds later. Released only when the reader resumed -- and the instant it drained, the deferred SIGINT was processed and the stack exited. Alive, idle, unresponsive, empty log: exactly the failure the card describes.

The negative control, which is what makes the above a reading

Same binary, copied outside the repo tree (phase 1 may not edit the repo) with the serve spawn changed to stdio: ['inherit','pipe','pipe','ipc'] plus unconditional manual forwarding. The mutation was proven on disk before use -- every anchor asserted unique, post-write counts checked, 43543 to 44112 bytes -- because an edit that silently matched nothing would have produced a clean-looking control that measured nothing.

3 of 3 runs: the spawner's fd 1 and fd 2 reach O_NONBLOCK=true at 112 ms and never leave it (116 and 108 consecutive samples). Zero parks anywhere in the tree across a 30 s stoppage. At 25 s the child was in epoll_pwait -- event loop alive -- and SIGINT killed it in 79 ms. On resume it delivered 1.25 MB of userland backlog. That is the same run, the same reader, the same stoppage: only the spawn's stdio differs.

Three things the card and the dispatch do not have

1. The population is EIGHT, not six and not seven. By the stdio: 'inherit' spelling over packages/cli/src, tests excluded: dev.ts:222, dev.ts:471, dev.ts:583, dev.ts:683 (conditional on --verbose, and in neither count), environments/bind.ts:84, init.ts:873, start.ts:241, start.ts:444. I also raised and then refuted a ninth candidate: doctor.ts:1865/1882/1956 call execSync with no stdio, and Node's docs say stderr is inherited by default -- measured, it is not; Node captures it and forwards it in userland, so the flag survives. Measurement over docs-reading.

2. The clearing is reversible, and that is why fd 1 escapes and fd 2 does not. Any Node child that materialises its own process.stdout re-sets O_NONBLOCK on the shared description ~100 ms later. The os dev parent's fd 1 is rescued that way every time; its fd 2 is not, because the durable clearing comes from esbuild -- a non-Node process spawned two levels down with only stderr inherited. So re-deriving the CLI's own spawn sites is necessary but not sufficient: the clearing that actually persisted was made by a dependency.

3. The guard that already exists cannot be reached from a published install. bin/stderr-nonblocking.mjs is not merely unwired by bin/run.js (0 references) -- npm pack lists bin/run.js as the only packed file under bin/, nothing in dist/ or src/ calls setBlocking, and its only importers are bin/run-dev.js and a test fixture. Phase 2 is a packaging question as well as a wiring one; the fork is in open_questions above.

Grade implication -- stated plainly, and triage's to act on

The reading supports raising the grade, and here is the whole basis, both directions, so triage can weigh it rather than take my word.

For: it reproduces on the shipped binary, deterministically (4 of 4), within 3.1 s of a reader stopping; the parked process ignores SIGINT; it is released only by the consumer that stopped; the hazardous state is established within 5 s of start at every log level and holds for the whole run; and no published install carries any guard, because the guard is not published.

Against, and this is real calibration rather than hedging: the process that parked is the os serve --dev child, not the os dev parent -- the parent's own exposure (fd 2 blocking) is present in every run but was never triggered, because in a healthy run the parent writes to fd 1, which gets accidentally rescued, and writes to fd 2 only on error paths. And at the default log level nothing parked in 90 s of stopped reader: an idle dev server emits ~0.5 KB/s and never fills the 64 KiB pipe. The park needs a stopped or slow reader and a burst of output while it is away -- a rebuild, a request log, an error dump, or --verbose, which is what CI usually runs.

So the card's title, "every time it spawns a child with inherited stdio", is right about the state and overstates the parent's demonstrated exposure. The failure that is real, measured and shipped is: a consumer that stops draining hangs the dev server in the kernel, silently, unkillable by SIGINT, for as long as it stays away.

---

Generated by Claude Code