# Compatibility matrix

ClientVM does not claim generic "Node compatibility". This page is the source of truth for what
works, how it is tested, and the known gaps.

- **Node target:** Node.js **24 LTS** (`process.version` = `v24.11.0`). See [ADR 0001](https://clientvm.joeldsouza.me/docs/decisions/0001-node-24-target.md).
- **Browser:** Chromium only, cross-origin isolated (COOP `same-origin` + COEP `require-corp`).
  Verified on Chromium 156. Instance pages rely on `Document-Isolation-Policy` (host apps need no
  COOP/COEP), `Atomics.waitAsync`, and nested module workers. The exact minimum version is still to
  be pinned by testing older Chromium builds (see open-questions.md).
- **Required frameworks (v1 goal):** Vite + React dev server with HMR, Express. Both work as
  golden fixtures: Express 4 + ws 8, a stock Vite 6 + React 18 project (dev server, React Fast
  Refresh, CSS HMR, error overlay, `vite build`), a stock Vite 8 + React 19 project (rolldown;
  dev server, HMR, `vite build`), and Vite 8 with Tailwind CSS 4 (`@tailwindcss/vite`).
- **Native packages:** native addons and binaries do not run. esbuild, rollup, rolldown,
  lightningcss and Tailwind's oxide are replaced by their official WebAssembly builds of the same version (ADR 0013);
  other native addons fail with `ERR_DLOPEN_FAILED`.

Status legend: **none** = not implemented · **partial** = subset, see gaps · **full** = matches Node for all tested behavior.

## Core modules

| Module | Status | Tested by | Known gaps |
|---|---|---|---|
| `fs` (sync) | partial | e2e fs differential vs real Node, fs differential + seeded random-op fuzz vs `node:fs` | Paths: `readFileSync writeFileSync appendFileSync readdirSync statSync lstatSync existsSync mkdirSync rmdirSync unlinkSync rmSync renameSync linkSync symlinkSync readlinkSync realpathSync(.native) accessSync chmodSync utimesSync truncateSync copyFileSync`. Fds: `openSync closeSync readSync writeSync fstatSync ftruncateSync`. Returns `Buffer`; all Buffer encodings; fds accepted by `readFileSync`/`writeFileSync`; no `opendirSync`, `cpSync`, `watch` (VFS watchers exist, not yet exposed), `fchmod`/`futimes`, `fsync` |
| `fs` (callback / promises) | partial | e2e diffed against real Node | Callback and `fs.promises` APIs for every sync API, `FileHandle`, `Dir`/`opendir`, `mkdtemp`, `cp`, recursive `readdir`, `createReadStream`/`createWriteStream` (ranges, `fd`, events). Operations run synchronously and complete on a later tick. `watch`, `watchFile`, `fs.promises.watch` via kernel VFS watchers. Not yet: `glob`; `statfs` returns fixed values |
| `path` | full | path differential and seeded fuzzing vs `node:path.posix` and `node:path.win32`, Node's own `test-path-*` | Node 24.11's `lib/path.js`, vendored unmodified (`scripts/vendor-node-path.mjs`, checked by SHA-256) and run with a primordials shim, so `posix`, `win32`, `matchesGlob` and the Windows reserved-name rules are Node's code |
| `util` | partial | inspect + events + modules differentials vs `node:util`, e2e | `format`, `inspect` (custom inspect, depth), `types`, `promisify`/`callbackify`, `inherits`, `deprecate`, `isDeepStrictEqual`, `parseArgs` (common cases), `debuglog`, `getCallSites`, legacy `isX`. No `showHidden` (`%o`), colors, Proxy detection, `MIMEType`, `TextEncoder` streaming options |
| `console` | partial | e2e spike | `table` prints like `log`. No `Console` class |
| `process` | partial | e2e | EventEmitter with `exit`, `beforeExit`, `uncaughtException`, `unhandledRejection`, `warning`; `stdin` is a Readable over the kernel pipe or the terminal, `stdout`/`stderr` are Writables; on a pseudo-terminal (ADR 0017) they are TTYs with `columns`/`rows`, `getWindowSize`, `getColorDepth`/`hasColors`, cursor methods, `'resize'`, and `setRawMode`/`isRaw` on stdin. Liveness follows referenced handles (timers, children, stdin while read, watchers, in-flight `fetch`) with `ref`/`unref`. Signals are delivered: listeners (`process.on('SIGINT')`) take them; otherwise the default action applies (exit 128 + n; SIGWINCH and SIGCHLD ignored). `process.kill(process.pid, sig)` signals itself; other pids fail with `ESRCH`. `arch` reports `x64` |
| `timers` | partial | e2e | Node `Timeout` objects with `ref`/`unref`/`refresh`/`hasRef`; `setImmediate` is a macrotask. Promise-only work (other than `fetch`) does not keep the process alive |
| `fs` on fds 0–2 | partial | e2e (esbuild-wasm service) | `fs.read(0)` reads stdin asynchronously; `write`/`writeSync` to 1 and 2 go to stdout/stderr; `fstat` reports pipes. `readSync(0)` fails with `EAGAIN` (a sync read would block the worker) |
| module loading (CommonJS) | full (tested surface) | resolution differential vs `require.resolve` (69 cases), e2e project diffed against real Node | `node_modules` lookup, `main`, `exports`/`imports` (conditions `require`, `node`, `node-addons`), self-reference, symlinks (realpath), JSON, cycles, `require.cache`, `require.extensions`, `createRequire`, `Module._load`/`_resolveFilename`/`_compile` hooks, `NODE_PATH`. `require()` of ES modules (Node 22.12+): the module is rewritten as CommonJS and returns its namespace (or its `"module.exports"` export), with the `module-sync` condition; top-level await throws `ERR_REQUIRE_ASYNC_MODULE` and `--no-experimental-require-module` restores `ERR_REQUIRE_ESM`. A module both required and imported is two instances (Node shares one), and forms the converter does not cover (a destructuring declarator after `export`) throw `ERR_REQUIRE_ESM`. Native addons (`.node`) fail with `ERR_DLOPEN_FAILED`, except rollup's and lightningcss's bindings; a missing `@rolldown/binding-wasm32-wasi` or `@tailwindcss/oxide-wasm32-wasi` resolves to its stand-in (ADR 0013) |
| module loading (ESM) | full (tested surface) | ESM resolution differential vs Node `import()` (34 cases), lexer differential vs es-module-lexer (793 files), e2e project diffed against real Node | Native browser ESM through the instance service worker (ADR 0006): `exports`/`imports` with `import`/`node`/`module-sync`, CommonJS interop with Node's named exports (cjs-module-lexer, ADR 0009), builtins, `import.meta` (`url`, `filename`, `dirname`, `resolve`, `main`), top-level await, cycles, JSON with `with { type: 'json' }`, `import()` from CommonJS and eval, `type`-less `.js` syntax detection. Not supported: `export * from` a builtin, `--input-type=module`, loader hooks (`module.register`), `.wasm` imports. Errors are Node's codes and messages, but a failed static import throws when its module would evaluate, not before the whole graph links |
| `buffer` | full (tested surface) | Buffer differential vs `node:buffer` (thousands of cases: encodings, search, numeric reads/writes, errors), e2e | `Buffer` is a callable function sharing `FastBuffer.prototype`, as in Node. `Blob`/`File` are the browser's. No `transcode` for exotic encodings |
| `events` | full (tested surface) | events differential vs `node:events`, e2e | `EventEmitter` (callable for legacy `EventEmitter.call(this)`), `once`, `on`, captureRejections, errorMonitor, max-listener warnings. `EventTarget` helpers partial |
| `stream` | full (tested surface) | stream differential vs `node:stream`, e2e | Node's own implementation (readable-stream 4.8, Node 18.19 core; ADR 0010): Readable/Writable/Duplex/Transform/PassThrough, `pipeline`/`finished`/`compose`, iterator helpers, `stream/promises`, `stream/consumers`, `stream/web` (browser globals). `Readable.fromWeb`/`toWeb` not yet |
| `crypto` | partial | crypto differential vs `node:crypto` | Synchronous `createHash`/`hash` (md5, sha1, sha224, sha256, sha384, sha512 and OpenSSL aliases), `createHmac`, `pbkdf2(Sync)`, `randomBytes`, `randomFill(Sync)`, `randomInt`, `randomUUID`, `getRandomValues`, `timingSafeEqual`; `webcrypto`/`subtle` are the browser's. Not available (throw `ERR_CLIENTVM_UNSUPPORTED`): ciphers, sign/verify, key pairs, scrypt, ECDH. `Hash` is not a stream |
| `zlib` | partial | zlib differential vs `node:zlib` | pako 2.1 (ADR 0007): sync, callback and stream APIs for deflate/inflate/gzip/gunzip/raw/unzip, `crc32`, Node's error codes, and the `_processChunk`/`_handle` internals minizlib uses. No brotli (absent, so feature detection falls back). `params()` cannot change the level mid-stream |
| `punycode` | full (Node's own) | e2e (`whatwg-url` via the npm smoke run) | Node 24.11's `lib/punycode.js`, vendored unmodified; the DEP0040 warning shows only when code outside `node_modules` loads it |
| `querystring` | full (tested surface) | modules differential vs `node:querystring` | |
| `string_decoder` | full (tested surface) | modules differential | utf16le surrogate pairs split at an odd byte decode correctly (Node emits U+FFFD) |
| `timers/promises` | partial | | `setTimeout`, `setImmediate`, `scheduler` |
| `http` / `https` | partial | e2e: unmodified Express 4 + ws 8 (golden fixture) | Servers listen on virtual ports; previews reach them on their port origin (ADR 0008). Requests and responses stream; `upgrade` gets a raw socket (WebSockets from previews go through an injected shim). `IncomingMessage`/`ServerResponse`/`Server` are Node-shaped (Express extends their prototypes). Request bodies are buffered by the service worker. `https.createServer` serves plain HTTP (TLS is the browser's). Clients use `fetch`: `localhost`/`127.0.0.1` reach this instance's ports; other hosts are cross-origin fetches that need CORS, follow redirects themselves, and drop headers that force preflights (`user-agent`, `npm-*`, ...); compressed responses arrive decoded. Agents are accepted and ignored |
| `net` | partial | e2e | `createServer`/`connect` between processes of one instance on virtual ports (half-close supported); `isIP*`; non-local hosts fail with `ECONNREFUSED`. No Unix sockets |
| `dns` | partial | | `lookup` resolves local names to loopback and other names to `0.0.0.0` (requests go through fetch by name); `resolve*` fail with `ENOTFOUND` |
| `tls` | partial | | Loadable; `connect` fails (the browser does TLS inside fetch); `createServer` is a plain `net` server |
| `os` | partial | e2e | A fixed Linux identity (`hostname` `clientvm`, `x64`); CPU count from the browser. Memory figures are nominal |
| `module` | partial | e2e | `Module` with Node's internal hooks, `createRequire`, `builtinModules`, `isBuiltin`. `register()` (loader hooks) is a no-op |
| `vm` | partial | e2e compared with Node | Runs in the process's own realm; `runInNewContext` uses `with` over the sandbox object, and `globalThis` in the code is the sandbox while it runs (so `globalThis.x = 1` lands on it, as Next.js expects). No separate globals otherwise: top-level `this`, `var` declarations and undeclared assignments reach the process's global |
| `tty`, `perf_hooks`, `sys` | partial | e2e `pty.spec.ts` | `isatty(fd)` is true for stdio streams that are the terminal. `tty.ReadStream`/`WriteStream` constructors are stubs (use `process.stdin`/`stdout`) |
| `child_process` | partial | e2e diffed against real Node, Node's `test-child-process-*` | `spawn`, `exec`, `execFile` (+ promisified), `spawnSync`, `execSync`, `execFileSync`, `fork`; stdio `pipe`/`inherit`/`ignore`/`ipc`, `input`, `cwd`, `env`, `timeout`, `killSignal`, `signal`, `maxBuffer`; Node's `exit`/`close` ordering and spawn errors (`ENOENT`, `EACCES`, `ENOEXEC`). Commands resolve like `execve`: `PATH`, exec bits, shebangs incl. `/usr/bin/env -S`, `node_modules/.bin` symlinks. `shell: true` and `exec` run through `/bin/sh`. IPC (`fork`, `stdio: 'ipc'`): `send`/`message`/`disconnect` both ways with `json` or `advanced` (structured clone) serialization; handles (sockets, servers) cannot be sent. Signals HUP INT QUIT KILL USR1 USR2 PIPE ALRM TERM CHLD XCPU WINCH; `detached` starts a new process group (terminal signals and input skip it) but the child is still killed with its parent. stdin `inherit` is the parent's terminal when it has one, else closed |
| `worker_threads` | partial | e2e, Node's `test-worker-*` | `Worker` (file, `eval: true`, `data:` URLs), `workerData`, `parentPort`, `MessageChannel`/`MessagePort` (ports can be transferred), `SharedArrayBuffer` and `Atomics` across threads, `terminate()` (exit code 1), `error`/`exit`/`online` events, `env` and `SHARE_ENV`, environment data, messages queued until a `'message'` listener attaches (as Node does, so ES module workers miss nothing), `ref`/`unref` on ports. Shared `WebAssembly.Memory` and `WebAssembly.Module` can be posted (WASI threads). A thread is a process in the kernel (one Web Worker) linked to its parent by a `MessagePort`. Not supported: `receiveMessageOnPort` (returns `undefined`), `resourceLimits` enforcement, `getHeapSnapshot`, `BroadcastChannel` across instances |
| `diagnostics_channel` | full (tested surface) | diagnostics-channel differential vs Node | Channels, `subscribe`/`unsubscribe`, `tracingChannel` with `traceSync`/`tracePromise`/`traceCallback`. `bindStore`/`runStores` publish and run, but without store context (see `async_hooks`) |
| `async_hooks` | partial | e2e compared with Node | `AsyncLocalStorage` (`run`, `exit`, `getStore`, `enterWith`, `disable`, `bind`, `snapshot`) and `AsyncResource`. Context follows synchronous calls, timers, `setImmediate`, `process.nextTick` and bound callbacks, **but not promise continuations or `await`** (browsers have no async context hook yet). `createHook` hooks never fire |
| `test` (`node:test`) | partial | e2e | `test`/`it`/`describe`/`suite` with hooks, `skip`/`todo`/`only`, subtests, `t.assert`, `mock.fn`/`mock.method`, TAP output, non-zero exit on failure. No `--test` runner CLI, coverage, snapshot tests or `mock.timers` |
| `readline` / `readline/promises` | partial | readline differential vs `node:readline` (lines, terminal keys, editing, history), e2e (npm, `pty.spec.ts`) | `createInterface` over any readable: `line`/`close` events, `question` (callback and promise), `prompt`, async iteration, `\r\n` handling; cursor helpers write ANSI codes. `emitKeypressEvents`. Terminal mode (`terminal: true`, default when output is a TTY): raw mode, Emacs-style editing, history, `completer`, `SIGINT` event, Ctrl+D closes. Wide characters count as one column |
| `http2` | partial | | `constants` only (header, method and status names). `connect`/`createServer` throw `ERR_CLIENTVM_UNSUPPORTED` |
| `wasi` | partial | differential vs `node:wasi` (same preview1 calls) | WASI preview1 over the instance's `fs`: preopens, files, directories, symlinks, stat, clocks, `poll_oneoff` clock sleeps, random, args/env, `proc_exit` (with `start`/`initialize` and Node's errors), uvwasi's rights checks. Shared guest memory works (WASI threads). No sockets; descriptors other than files are always ready in `poll_oneoff` |
| `inspector`, `inspector/promises` | partial | e2e compared with Node | No debugger can attach: `url()` is undefined, `open()` and `Session.connect()` throw `ERR_INSPECTOR_NOT_AVAILABLE` |
| `v8` | partial | | `getHeapStatistics` from Chromium's `performance.memory`; `serialize`/`deserialize` use JSON, not V8's wire format; no heap snapshots |
| `url` | partial | url differential vs `node:url` | WHATWG `URL` (browser), legacy `parse`/`format`/`resolve`, `fileURLToPath`/`pathToFileURL`, `urlToHttpOptions`. `domainToUnicode` is identity |
| `assert` | partial | assert differential vs `node:assert` | All common assertions, strict mode, `AssertionError` shape. Diff-style messages for objects are simplified |

## CLI

| Command | Status | Notes |
|---|---|---|
| `node -e/-p/--eval/--print <code>` | partial | Runs in global scope with `require`, `module`, `exports` |
| `node <script.js>` | partial | CommonJS and ESM entry points (`.mjs`, `"type": "module"`, detected ESM syntax) |
| `node -v` / options | partial | `-v`/`--version`. Options that only tune V8 or diagnostics (`--no-warnings`, `--max-old-space-size=`, `--experimental-*`, `--enable-source-maps`, `--stack-size=`, ...) are accepted and ignored. Others (`--inspect`, `-r`, `--import`, `--test`) fail with exit code 9 |
| `node --check` / `-c` | partial | Parses without running (CommonJS with `Function`, ESM by linking a copy with its imports blanked). Errors show the file and the message; the source line and caret are not shown |
| `node` (REPL) | none | |
| `sh` / `bash` | partial | See [Shell](#shell) |
| Linux commands | partial | See [Commands](#commands) |
| `npm` / `npx` | partial | npm 11.6.1, unmodified, fetched and integrity-checked on first use (ADR 0012). Tested in e2e: `init`, `pkg`, `install` from the public registry (110-package tree), `ci`, `ls`, `run`, lifecycle scripts, bin links, `npx`. Registry traffic is CORS `fetch` (the registry allows it). Not yet tested: git dependencies, private registries with auth, `npm publish` |
| `pnpm` / `pnpx` | partial | pnpm 10.34.7, unmodified, fetched and integrity-checked on first use (as npm, ADR 0012). Tested in e2e: `init`, `add`, the content-addressed store and `.pnpm` symlink layout, `install --frozen-lockfile`, `run`, `exec`, `pnpx`, workspaces with `workspace:*` and `--filter` |
| npm packages | partial | `test/e2e/smoke.spec.ts` installs 50 popular pure-JavaScript packages with npm and loads each (require or import) with a functional check: React, Express, Fastify, Koa, socket.io, axios, lodash, zod, TypeScript, Sass, Vue, Svelte, three, GraphQL, cheerio and others. Packages with native addons are out of scope for v1 |

## Node's own tests

`test/conformance/node-tests` holds the tests from Node 24.11's `test/parallel` that pass inside
an instance, unmodified, with the real `test/common` (MIT; see that directory's LICENSE).
`test/e2e/node-tests.spec.ts` runs all of them in CI; a test that stops passing fails the build.
A discovery run (`scripts/vendor-node-tests.mjs` documents it) re-runs every test for the
prefixes below and refreshes the set. Tests that skip themselves (`1..0 # Skipped`, for example
because there is no OpenSSL) count as skipped, not passed.

| Prefix | Pass / run | Skipped | Notes |
|---|---|---|---|
| `path` | 13 / 15 | 1 | |
| `stream`, `stream2`, `stream3` | 165 / 199 | 1 | |
| `event`, `events` | 25 / 35 | | |
| `fs` | 105 / 307 | 8 | Many use `fs.watch` timing, permissions or `/proc` |
| `buffer` | 29 / 64 | | |
| `http` | 66 / 365 | 7 | Many need real sockets (`net.Socket` internals, `server.address()` details) |
| `net` | 18 / 143 | 3 | |
| `child-process` | 19 / 105 | 2 | Many spawn `process.execPath` with flags we do not support |
| `worker` | 41 / 128 | 7 | |
| `timers` | 22 / 58 | | |
| `zlib` | 14 / 58 | 1 | No brotli |
| `vm` | 18 / 92 | | Contexts share the process realm |
| `process` | 17 / 88 | 4 | |
| `require`, `module` | 19 / 48 | 3 | `test-require-mjs.js` needs its `--no-experimental-require-module` flag, which Node's harness only adds when crypto is present |
| `url`, `querystring`, `string` | 7 / 21 | | |
| `util`, `assert`, `console` | 8 / 67 | | Mostly exact `inspect` output and assertion message formats |
| `readline`, `tty`, `os`, `dns` | 5 / 59 | | Node's tests open TTYs on fds directly, which ClientVM does not have; `dns` has no resolver |
| `crypto`, `https` | 0 / 0 | 178 | All skip: no OpenSSL |
| **Total** | **591 / 1889** | **215** | Of 2104 tests matched by these prefixes |

## Shell

One interpreter serves `sh`, `bash`, `/bin/sh` and `/bin/bash`. It implements POSIX `sh` plus the
bash extensions agents commonly write. Tested by `test/conformance/shell-differential.test.ts`:
about 175 scripts run under real bash 5.2 and under ClientVM, and stdout, stderr and exit status
must match. Parser fuzzing is in `packages/shell/src/parser.test.ts`; e2e coverage, including
pipes to and from `node`, is in `test/e2e/shell.spec.ts`. Design:
[ADR 0011](https://clientvm.joeldsouza.me/docs/decisions/0011-in-process-shell-commands.md).

| Feature | Status | Notes |
|---|---|---|
| Lists, pipelines, `&&` `\|\|` `;` `&`, `!`, `\|&` | full (tested surface) | `set -o pipefail` |
| Quoting: `'...'`, `"..."`, backslash, `$'...'`, `$"..."` | full (tested surface) | |
| Expansions: parameters, `${x:-}` `:=` `:?` `:+`, `#` `##` `%` `%%`, `/` `//` `/#` `/%`, `:off:len`, `^^` `,,`, `${#x}`, `${!x}` | full (tested surface) | `${@:n:m}` slices positional parameters |
| Command substitution `$(...)` and backquotes, arithmetic `$((...))` | full (tested surface) | 64-bit wrapping integers, bash operators and error messages |
| Field splitting (IFS), pathname expansion (`*` `?` `[...]`, classes), tilde, brace expansion (`{a,b}`, `{1..10..2}`) | full (tested surface) | `shopt -s nullglob dotglob failglob nocasematch`. No `extglob` |
| Redirections: `<` `>` `>>` `>\|` `<>` `n>&m` `n>&-` `&>` `&>>`, heredocs (`<<`, `<<-`, quoted), `<<<` | full (tested surface) | `/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr` |
| `if` `while` `until` `for` (incl. `for ((;;))`) `case` (`;;` `;&` `;;&`) `{ }` `( )` functions (`f()`, `function f`), `[[ ]]` (incl. `=~`), `(( ))` | full (tested surface) | `BASH_REMATCH` holds only the whole match (no arrays) |
| `set -euxfCa`, `set -o pipefail`, `trap ... EXIT` | full (tested surface) | Traps on signals (`trap cmd INT TERM`, `trap '' HUP`) run when the signal is delivered (e2e `pty.spec.ts`) |
| Builtins: `cd pwd echo printf test [ true false : export unset readonly local declare typeset set shift exit return break continue read eval source . exec command type hash wait jobs trap umask let getopts alias unalias shopt pushd popd dirs builtin times` | partial | `printf -v`, `read -r -d -n -p -u`. `alias` stores aliases, but non-interactive bash does not expand them, and neither do we |
| Scripts: `sh file`, `./file` with shebang, `sh -c 'cmd' name args`, script on stdin | full (tested surface) | Run one complete command (line) at a time, like bash. Syntax errors use bash's two-line format |
| Background jobs `&`, `wait`, `$!` | partial | Run in the shell's worker; they end when the shell exits. Spawned programs keep running |
| Process substitution `<(cmd)` | partial | Implemented with a temp file (the command finishes first). `>(cmd)` is not supported |
| Interactive shell (`bash -i`, or no script on a terminal) | partial | e2e `pty.spec.ts`. PS1/PS2 with bash escapes, line editing, history (`~/.bash_history`, ↑/↓, the `history` builtin with `n` and `-c`), Tab completion of commands and paths, continuation lines, Ctrl+C, `[n]+ Done` notices, job control (Ctrl+Z, `fg`, `bg`, `jobs`; ADR 0017). No SIGTTIN, `!` history expansion, aliases, or `~/.bashrc` |
| Arrays (`a=(...)`, `${a[@]}`), `mapfile`, `select`, `coproc`, `time` | none | `declare -a` and `read -a` fail with a clear error |
| `type`/`declare -f` printing function bodies | none | `type -t` works |
| Locale | partial | Text is UTF-8 (`LANG=C.UTF-8`). `LC_ALL=C` byte semantics (e.g. `${#x}` in bytes) are not emulated |

## Commands

Commands run in the shell's own worker when invoked from the shell, and as their own process when
spawned (`child_process.spawn('ls')`). Behavior and messages follow GNU coreutils, grep 3.11,
sed 4.9, findutils 4.9 and diffutils 3.10; the differential suite compares them with the real
tools.

| Command | Notes |
|---|---|
| `ls` | `-aAlRdFphrtSUi1L`. Output is one name per line (no columns, even on a terminal). `-l` shows `user user` as owner |
| `cat cp mv rm mkdir rmdir touch ln chmod stat realpath readlink basename dirname mktemp` | Common GNU options. `chmod` takes octal and symbolic modes, `-R`. `stat -c/--printf` formats |
| `head tail wc sort uniq cut tr tee seq yes rev` | `sort -k -t -n -g -h -V -M -f -r -u -s -c -o`. `tail -f` polls every 250 ms. `tr` is byte-based like GNU's |
| `grep` (`egrep`, `fgrep`) | `-EFGP -ivwxclLnhHoqsr -e -f -A -B -C -m --include --exclude --exclude-dir`. JS regex engine: matching is leftmost-first, not POSIX leftmost-longest, so a few alternations match differently. `-P` is JS regex syntax |
| `sed` | Addresses (`N`, `$`, `/re/`, `first~step`, ranges, `addr,+N`, `0,/re/`, `!`), commands `s y d D p P n N g G h H x a i c = q Q l r w b t T : { } z F`, `-n -e -f -E -r -i[SUF] -s -z`, `\U \L \u \l \E` in replacements. No `e` command or `s///e` |
| `find` | Tests `-name -iname -path -regex -type -size -empty -newer -mtime -mmin -perm -maxdepth -mindepth`; actions `-print -print0 -printf -delete -exec -execdir -prune -quit`; `! -a -o ( ) ,`. Directory entries are visited in sorted order |
| `xargs` | `-n -L -I -0 -d -r -t`. Runs invocations one at a time (`-P` is accepted and ignored) |
| `diff` | Normal and unified (`-u`, `-U N`) output, `-q -r -N -i -w -b -B -s --label`. Timestamps in headers are UTC |
| `env printenv which sleep date uname whoami hostname nproc id true false pwd echo printf test [ clear` | `date` formats in UTC only (`%Z` is `UTC`) |
| `tar` | `-c -x -t -z -v -f -C -O -k -a --strip-components --exclude`, old-style bundles (`tar xzf a.tgz`). Reads ustar, pax and GNU long names; writes ustar with pax headers. gzip is detected on extract. Members containing `..` are skipped, as in GNU tar. Archives are built in memory |
| `gzip gunzip zcat` | `-c -d -k -f -t -q`; levels are accepted and ignored |
| `curl` | Uses the browser's `fetch`: `localhost`/`127.0.0.1` reach virtual ports, other origins need CORS. `-s -S -f -i -I -o -O -X -H -d --data-* --json -G -u -A -e -w -m -T -v`. Redirects are always followed (`-L` is implied). A refused local port exits 7, as curl does |
| `git` | isomorphic-git 1.44.3, fetched and integrity-checked on first use (ADR 0014). Diffed against real git in `test/e2e/git.spec.ts` (stdout and exit codes, fixed dates): commit ids are identical. `init config status add rm mv commit log show diff branch checkout switch restore reset merge stash tag rev-parse ls-files cat-file remote clone fetch pull push`. `log` follows git's date order; `diff`/`show` print unified patches and `--stat`; `merge` fast-forwards or creates merge commits and leaves conflict markers (resolved with `git add` + `git commit`). No editor (`commit` needs `-m`, `-F` or a pending merge message), no rebase, cherry-pick, blame, submodules, hooks, `.gitattributes` or rename detection. Remotes go through `fetch`: most hosts need a CORS proxy (`GIT_CORS_PROXY`); `GIT_TOKEN` authenticates |

## Previews

- HTML documents on port origins get three injected scripts at the top of `<head>`: an inline console capture, the WebSocket shim and the preview agent. A page with a Content-Security-Policy that forbids inline scripts loses console output from before the agent loads; one that forbids same-origin scripts loses the shim and agent.
- Screenshots render the DOM through SVG `foreignObject`: same-origin images are inlined; cross-origin images, canvases, video and iframes are blank.

## Filesystem semantics

- Read-only mounts (`Instance.fs.mount`) fail mutations with `EROFS`; `rm -rf` of a directory containing a mount fails rather than skipping it.
- `/dev/null`, `/dev/zero`, `/dev/random` and `/dev/urandom` are character devices (by path; `ls /dev` lists them). Reading a whole infinite device with `readFile` returns nothing rather than looping.
- Linux semantics are the reference (CI runs the differentials on Linux; a few macOS-divergent cases are skipped locally).
- Symlinks are followed with a 40-hop limit (`ELOOP`); `..` is resolved physically, as the kernel does.
- Hard links, unlinked-but-open files, `O_APPEND`/`O_EXCL`/`O_TRUNC`, and zero-filled holes behave as on Linux.
- No access time updates on reads (`noatime`). Every process runs as root: only execute permission is checked (`access(X_OK)`).
- Per-instance quotas (`quotaBytes`, `maxInodes`) fail with `ENOSPC`; per-process open files are capped at 1024 (`EMFILE`).

- `readdir` returns entries in sorted order (code-unit order). Linux ext4 returns hash order, so
  don't rely on order in tests.
- Paths are case-sensitive.
- Errors carry Linux errno values and Node's `code`, `errno`, `syscall`, and `path`.