Beagle SCM

JS-020 LOW: process spawn + output-as-Buf — bind FILESpawn/FILESpawnFds/FILEReap

A JABC script cannot run a child process: the C leaves exist but aren't bound. Bind them, plus an "output as a Buf" convenience via a file + mmap sink — the deadlock-free, zero-copy path. Method: Issues.

Input

Context

• io.spawn/reap are shown in js/API.md but NOT bound (grep js/ for

  spawn/Spawn → none). The leaves exist: abc/FILE.h:537 FILESpawn (pipes for stdin/stdout, *stderr inherited*), :545 FILESpawnFds (caller fds, -1=inherit), :552 FILEReap (FILESIGNAL on signal death).

• Surfaced by the spawn/Buf design chat: scripts/extensions need to run a

  child and read its output. Naive pipe-drain *deadlocks* at the 64 KB pipe buffer, and a fixed-cap Buf overflows — the binding must dodge both.

• No anonymous-fd leaf today (memfd/O_TMPFILE absent from FILE.h); the

  zero-copy sink uses a named temp file via FILECreate + FILEMapRO.

Goals

• io.spawn(path, argv) → {pid, stdin, stdout} (fds); `io.spawnFds(path,

  argv, inFd, outFd) → pid (-1 inherits); io.reap(pid) → {code, signal}`.

• "Output as a Buf": spawn with a file sink, reap, mmap → the child's

  stdout as a zero-copy Buf (no pipe, no deadlock, no drain loop).

Constraints

• Pure marshalling over the three leaves (no new abc): argv = a JS string

  array → u8css; fds + pid cross as numbers; no held JS refs (rule #4).

• The Buf-sink convenience composes EXISTING leaves (io.open/spawnFds/

  reap/mmap) — a JS-side helper, no C format logic.

• Reap contract: clean exit → {code}; FILESIGNAL → {signal} (exactly

  one set). Caller owns + closes every fd; the binding never reaps on GC.

WIP

Design decisions

• (open) Landing scope = the 3 leaf bindings + a JS io.exec/io.capture

  (file-sink → mmap) returning {out: Buf, code}, optional {stdin: Buf}.

• (open) Deferred refinements: io.memfd() anon sink (needs a new

  FILEMemFd abc leaf); *stderr capture* (FILESpawn inherits it — needs a stderr-fd spawn variant or a self-made pipe); an async streaming child module over pol (mirror net.cpp): two-pipe poll-drain (no deadlock) + SIGCHLD/waitpid reaping + .on('data'|'exit').

TODOs

• Repro-first: io.spawn("/bin/echo",["echo","hi"]) → read stdout == "hi\n",

  io.reap → {code:0}; a non-zero exit and a signal death both surface correctly; the file-sink io.exec returns the output Buf.

• Bind the 3 leaves; add the file-sink→mmap convenience.
• Document the surface + the deadlock/stderr caveats in js/API.md; update

  js/INDEX.md (io.cpp section).

Blockers

• None for the core. stderr capture + memfd are flagged follow-ups that may

  need small new abc leaves; the async child module is a larger follow-up.

Outcome

• LANDED 0155ee76 (2026-06-21): io.spawn(path,argv) → {pid,stdin,stdout},

  io.spawnFds(path,argv,inFd,outFd) → pid (-1=inherit), io.reap(pid) → {code}|{signal} — pure marshalling over FILESpawn/FILESpawnFds/ FILEReap; plus io.unlink (FILEUnLink). argv→u8css idiom from WIRECLI.c. Tests red→green (echo, stdin round-trip, exit-code, signal, spawnFds-inherit, argv-throws); ctest -R JABC 18/18, ASAN/LSan clean.

• io.exec (file-sink→mmap) was built then CUT on review: the name

  mismatches POSIX/Node exec and it was sugar over spawn. Capture-stdout recipes (pipe-drain + zero-copy file+mmap) stay in API.md over the leaves.

• Deferred: stderr capture, a memfd anon sink, an async pol-driven child

  module, {stdin:Buf} — and a Buf.close() doc/impl gap spotted in API.md.