ADR 0011: The shell runs its commands in-process; every command is also a runtime

  • Status: accepted (2026-10-21)
  • Context: Shell scripts run many short commands: ls, grep, sed, mkdir -p, pipelines, $(...), and loops that run a command per file. A ClientVM process is a Web Worker with syscall channels, and a process spawn costs about 9 ms (docs/phase3-plan.md). A worker per command would make for f in *.js; do grep -q x "$f"; done take seconds. Multi-call shells such as busybox avoid this by running applets inside the shell process.
  • Decision:
    • The commands in @clientvm/shell (ls cat grep sed find ...) and the shell builtins run inside the shell’s worker as async functions. Pipelines between them use in-memory pipes with backpressure, and EPIPE becomes exit status 141. Subshells, pipeline stages and $(...) are copies of the shell state, as fork() would give.
    • The choice still goes through PATH lookup, as execve would. The shell resolves argv[0] to a file. If the file is a builtin marker (#!/clientvm/builtin grep) for a command it implements, the command runs in-process. Anything else (node, scripts, node_modules/.bin shims, an earlier file of the same name on PATH) is spawned as a real child process through the kernel. Output that goes to the shell’s own stdout or stderr is inherited (the kernel routes it), not copied through the shell.
    • Every command is also registered as a standalone runtime, so child_process.spawn('ls'), execSync('grep ...') and xargs/find -exec from a spawned program work as on Linux. sh and bash are runtimes too, with marker files at /bin/sh, /bin/bash and /usr/bin/env.
    • One implementation targets both shells: POSIX sh plus the bash extensions agents commonly write. Behavior is checked against real bash and GNU coreutils in CI (test/conformance/shell-differential.test.ts).
  • Consequences:
    • A loop iteration costs microseconds instead of a worker spawn.
    • In-process background jobs (cmd &) live in the shell’s worker and end when the shell exits. Spawned children keep running, as orphans do on Linux.
    • Killing a process kills its descendants, like a signal to a process group. Instance.exec timeouts therefore stop the whole command line.
    • Nothing acknowledges stdin data the shell feeds to a spawned child. The feeding loop yields to the event loop every 64 KiB, so the child’s exit is seen (yes | node ... terminates).
    • A command bug can affect the shell that runs it, but both run in the same sandboxed worker with the same authority. This is not a new boundary.

Edit this page on GitHub ↗Markdown