[iperev]

fix(test): give spawned CLI children their input as a file, not a socket

Part of the UI-DESIGN-01 chain. Base branch: chain/v1b-media-emulation (#231, the media-emulation assertion). This PR is one commit on that branch's head, and it goes into the chain before the design-token PR. The next change in this chain is stacked on this one and fixes the shipped TypeScript adapter's hang (see Non-claims). Merge after #231.

Why

The Node test suites run the Proofkit CLI with spawnSync(binary, argv, {input, timeout}). On a macOS host, a small share of these calls never ended on their own. They failed with ETIMEDOUT, a different test each time, and this failed full local gates.

For the input option, Node's spawnSync gives the child one end of a Unix-domain socket pair. It writes the input, calls shutdown(SHUT_WR) on its end and keeps that end open until the child exits or the timeout kills it. On macOS, a child blocked in read(2) on that socket is sometimes not woken by the shutdown. The socket already holds end of file, but the read returns only when the parent closes its end, which spawnSync does at its timeout.

Evidence, darwin/arm64:

• Stalled children. Each of the 94 instrumented stalls at 440,000 bytes had received all of its input within 1 ms of its start. A watchdog thread in the child saw recv(MSG_PEEK|MSG_DONTWAIT) return 0 (end of file) every 500 ms until the timeout, while its read(2) stayed blocked: 66 stalls, 330 probes, all 0.
• Parent trace. An interposer in the Node parent recorded every stalled call: the write of all bytes, then shutdown(fd, SHUT_WR) = 0 2 to 3 ms after the spawn, and the close about 3000 ms later, at the timeout.
• Without Node or libuv. The same syscall sequence written in C (socket pair, non-blocking write, shutdown, descriptor kept open) stalled 8 times in 3000 calls. With a close instead of the shutdown, with a pipe(2) or with a regular file, it stalled 0 times in 3000 calls each.
• Node versions. Node 22.23.2, 24.22.0, 26.11.1 and 26.12.0 all stall. With 440,000 bytes of input to a Go child that reads stdin with io.ReadAll or its read loop, 8 to 52 of 3,000 calls stalled per run.
• Linux. In the pinned Playwright arm64 image (Node 24.20.0), and with the official Node 26.11.1 tarball (checksum and signature verified), there were 0 stalls in 24,000 calls.
• Python and async spawn. Python subprocess uses pipes, and a separate run on the same host saw 0 stalls in 472 runs with it. Node's asynchronous spawn with stdin.end() also shuts the socket down, but it closes it within 16 ms, and it stalled 0 times in 3,000 calls.

So the defect is in the macOS kernel's wake-up of a reader blocked on a Unix-domain socket, not in the CLI and not in Node's or libuv's logic. Node's spawnSync exposes it because it keeps its end open after the shutdown. No upstream report naming this mechanism was found.

What changes

One transport helper. spawnWithInputFile(file, args, options) in scripts/cli-process.mjs:

• It is spawnSync(file, args, options), except that options.input is written to a temporary file that the child gets as its standard input. A regular file ends at its size, so the child always reads end of file.
• The file has mode 0600, in a fresh temporary directory of mode 0700. The directory is removed as soon as the file is open, before the child starts; the open descriptor keeps the file. So while the child runs, no input remains on disk, and a signal that ends the parent then leaves none behind. A throw while the file is written or opened removes the directory too. The removal uses path calls only (rmSync of the file, then rmdirSync of the directory), so it needs no descriptor of its own; if it fails, the input descriptor is closed and the call throws.
• status, signal, error, stdout, stderr, timeout, maxBuffer, encoding, env, cwd and killSignal keep spawnSync's meaning. Writing the input can no longer fail with EPIPE.
• A string input is encoded with options.encoding, and a falsy input is no input, as in spawnSync.
• Only the options the caller set are passed. An explicit maxBuffer: undefined would have lifted spawnSync's 1 MiB default bound, and a test pins that.
• Any other option, and any stdio except ["ignore", "pipe", "pipe"], is refused. So is any args that is not an array, including the two-argument form spawnWithInputFile(file, options): spawnSync would read the options from the args position and drop the third argument, so the input would go through the socket again.
• The result also carries stdinUnreadBytes: the input bytes past the file offset that the child shares with the parent when it exits. read(2) and lseek(2) on the inherited descriptor move it; pread(2), mmap(2) and, on Linux, reopening /dev/stdin do not.

Every site. All 42 spawnSync calls with input, in 29 test files under scripts/, now call the helper. Each change is the call name and the import. Apart from the early-refusal test below, no timeout, argument, expected value or assertion changed. The other spawnSync and execFileSync calls under scripts/ and tests/ pass no input, for example Go builds, go version -m, --help, file inputs, the integration-structure invocations, the git and tsc calls, the visual environment probes and argv-only rows with an ignored stdin.

The EPIPE oracle, kept. assertCLITransport keeps its EPIPE rule, which the asynchronous pipe transport of scripts/schema-completeness.test.mjs still needs. It applies the same rule to a non-zero stdinUnreadBytes: it is accepted only from a child that exited normally with a non-zero status and no signal. With status 0 it fails.

The pipe could report EPIPE only when an exiting child left more input than the pipe buffer held. The shared file offset leaves every byte that the child did not read with read(2) past it. So the early-refusal test in scripts/browser-server-structure.test.mjs now asserts that stdinUnreadBytes equals the size of its input (over 8 MiB), that is, the refusal read none of it, instead of asserting EPIPE.

Tests. scripts/cli-process.test.mjs:

• covers the early refusal, status-0 and signal cases through both transports (file and pipe);
• checks that the child's stdin is a regular file that it reads to the end, for string, Buffer, Uint8Array, empty and absent input;
• checks the null-device path, the encoding, the default maxBuffer bound and the refused options, including the two-argument form and a non-array args;
• checks that the child reads an unlinked 0600 file while no input remains in its temporary root, that the directory and the file are 0700 and 0600 up to the open, and that nothing remains after a call, after spawnSync throws, after the open throws and after the write throws; and that a failed removal closes the input descriptor (the process holds as many descriptors after the call as before it);
• adds a source check: a lexical scan of the .js, .cjs, .mjs, .ts, .cts and .mts files under scripts/ and tests/ refuses an input member in the arguments of a direct spawnSync, execFileSync or execSync call, also when the function is called as a member (cp.spawnSync(…)). That covers plain, quoted, string-literal computed and shorthand keys, methods with a plain or quoted name, and object literals spread or nested in the arguments. The scan skips comments, strings, template text and regular expressions, and it has its own positive and negative cases.

Declared inputs. In proofkit/witness-plan.json, the proofkit.boundary-contract-check policy now declares scripts and tests, which the source check reads. witness-scheduler-plan admits the plan (passed). Any change under scripts/ or tests/ now selects this policy in a selective run; its 37 listed scripts/ entries are now redundant. No CI workflow selects from this plan.

Requirements

No requirement text changes. No requirement or binding names the test transport. The REQ-PROOFKIT-QUALITY rows cover coverage metrics, sanitizers and the visual reference gate. The bindings name the witness files, which keep their tests and names. Each touched suite asserts the same CLI behavior, and its transport check is stricter. No clause was false before this change or becomes false with it.

Compatibility

Not breaking. CLI behavior, JSON contracts, exit codes and Go code are unchanged.

The one shipped byte change is proofkit/witness-plan.json, which gains two input selectors of the boundary-contract-check policy. That changes its proof node digest, which no record pins.

The test helper is Node-only and adds no dependency.

Proof

Proof: A local npm run check sequence on darwin/arm64 passed (exit 0) on tree 600c4bf80032 with Node 26.11.1, npm 12.2.0, CPython 3.15.0 and Go 1.27.3, with no Go test verdict replayed from the test cache: 561/561 runtime browser cases in Chromium, Firefox and WebKit with zero retries. One recorded deviation: the host firewall blocks Go-built binaries from the network, so go:vulncheck ran against a vulnerability-database snapshot fetched with curl (modified 2026-10-21T00:27:29Z): no vulnerabilities.

Narrow evidence on the darwin/arm64 host, Node 26.11.1 (CI's version):

• Falsifier, minimal child. Go io.ReadAll child, 440,000 bytes, 3 s timeout. spawnSync with input: 52 stalls in 3,000 calls in one run, 44 in 3,000 in another, and 21 in 1,000 in the same window as the helper run below. spawnWithInputFile: 0 stalls in 3,000 calls, and 0 in 30,000 with two variants of the helper that differ from it only in when and how the input file is removed.
• Falsifier, the CLI. spec-proof-bundle-admission on the 59 captured ~430 KB inputs, 5 s timeout. spawnSync with input: 9 stalls in 590 calls. spawnWithInputFile: 0 in 590, and 0 in 5,900 with those two variants.
• Formerly flaky files. admission-records-structure, report-admission-structure and impact-structure: 0 failures in 3 runs each, and in 15 runs each with those two variants. In interleaved runs, a copy of the base tree failed admission-records-structure once and report-admission-structure once, each on one test with an ETIMEDOUT diagnostic.
• Gates. On this tree, scripts/cli-process.test.mjs and the three formerly flaky files passed 3 times each, and command-contract:check, source-hygiene, text-policy and the Go tests that read the witness plan passed. With one of those two variants, the file lists of compact-contract:check, receipt-contract:check, spec-tree-contract:check and boundary-contract:check passed 5 times each (run with --test-concurrency=3 on the shared host).
• Descriptor limit. Under a hard limit of 256 descriptors, with 1, 2 or 3 left free at the call, the helper returned spawnSync's EMFILE result with no descriptor leaked and no input left on disk, on this host and in the pinned Playwright arm64 image (Node 24.20.0, as root and as uid 1000). A variant that removed the directory with a recursive rmSync threw instead, leaked the input descriptor and left the input file, with 1 free descriptor on both systems and with 2 on macOS.
• Mutants. Each of these fails cli-process.test.mjs:
  • one site reverted to spawnSync({input}), as a shorthand and as an input: key;
  • an execFileSync with a quoted "input" key added under tests/;
  • the helper fed through spawnSync's input;
  • the unread-input rule removed;
  • maxBuffer: undefined passed;
  • the input removed only after the child ran, never removed, or removed only after a successful open, or its directory left in place after the file is removed;
  • the input file created with mode 0644, or in a predictable directory of mode 0755;
  • the write moved before the try that removes the input when it throws;
  • a failed removal that leaves the input descriptor open, alone or as a recursive rmSync of the directory;
  • the args check removed, or narrowed to the two-argument object form;
  • the scanner blind to method members.
• One mutant passes cli-process.test.mjs: a recursive rmSync of the directory that still closes the descriptor when it fails. The suite does not exhaust descriptors. The descriptor-limit probe refuses this mutant, because it leaves the input file at 1 and 2 free descriptors on macOS.
• Signals. SIGTERM, SIGINT and SIGHUP to a parent inside the helper left no input file; the same probe left one per signal with a variant that removes the directory only after the child exits.
• git diff --check over the range: clean.

Non-claims

• The kernel code path that loses the wake-up is not identified. The claim is the observed behavior on this host: macOS 15.8.1 (Darwin 24.6.0) on an Apple M1, under the recorded loads. Other macOS versions and Intel Macs were not tested.
• Linux was tested in the Docker Desktop VM (linuxkit kernel), not on a CI runner.
• A signal that ends the parent between the creation of the temporary directory and its removal, which precedes the child's start, still leaves that directory and, once written, its 0600 file. A removal that itself fails leaves them too; the call then throws.
• stdinUnreadBytes reads falsely for a child that reads its input only with pread(2) or mmap(2), or by reopening /dev/stdin on Linux (it reports bytes it read as unread), and for a child that seeks past input it did not read (it reports that input as read). On macOS, reopening /dev/stdin shares the offset and reads correctly. No current caller depends on these cases: its children are Proofkit CLI builds and the Node probes of cli-process.test.mjs, which read their standard input with read(2) or not at all.
• The source check is lexical. It does not see options assembled outside the call, and it does not see a synchronous spawn function called under another name: scripts/write-browser-proof.mjs and scripts/write-browser-visual-proof.mjs pass spawnSync and execFileSync as values, and their callee passes no input. Nor does it see calls through .call, .apply, Reflect.apply or an optional call (spawnSync?.(…)), a bracketed callee (cp["spawnSync"](…)), a TypeScript type-argument call (spawnSync<T>(…)), getter, setter, async or generator members, methods with a computed key ({["input"]() {…}}), computed keys other than string literals, or escaped key names. Its lexer chooses between a division and a regular expression from the previous token alone, so it misreads some code: for example a / after ++, --, a template literal, an object literal, a property named like a keyword that a regular expression can follow (x.in / y) or a name with a non-ASCII letter (π / 2), a regular expression after ) or export default (export default /'/), and a hashbang line with an unbalanced quote. A misreading can hide the code after it. On this tree every spawnSync, execFileSync and execSync name outside cli-process.* is lexed as a name, and no regular-expression token lies inside any call's arguments.
• Asynchronous spawns that write stdin (schema-completeness, two browser-server session tests) are unchanged. Node's asynchronous transport closes the socket right after the shutdown, and it stalled 0 times in 3,000 reproducer calls. That is evidence, not proof that a lost wake-up can never delay these sites.
• The generated TypeScript adapter of json-report-cli-adapter-source, a shipped product surface, still passes its input through spawnSync's input on this tree. It sets no timeout, and ProofkitCommandRunOptions offers none, so on macOS the same lost wake-up can block a consumer's call, and with it the consumer's event loop, until the CLI child is killed. TestGeneratedTypeScriptAdapterExecutesCoreSemantics (internal/command/jsonreportcliadaptersource/json_report_cli_adapter_source_test.go) runs that adapter under go test with small inputs and no timeout of its own. This PR does not change product output; the adapter hang is fixed by the next change in this chain.