feat: CLI tool sandbox tests, e2e Docker fixtures, Node.js test suite spec

- E2E Docker fixtures: pg (connect, pool, types, errors, prepared, SSL),
  mysql2, ioredis, ssh2 (connect, key-auth, tunnel, SFTP dirs/large/errors)
- CLI tool tests: Pi (SDK, headless, interactive, tool-use, multi-turn),
  Claude Code (SDK, headless, interactive, tool-use),
  OpenCode (headless, interactive)
- Agentic workflow tests: npm install, npx exec, dev server lifecycle
- Net/TLS socket bridge, crypto.subtle deriveBits/deriveKey (SCRAM-SHA-256)
- VFS examples: S3 (MinIO) and SQLite filesystem drivers
- Node.js test suite integration spec and backlog expansion
- Ralph agent test verification and code quality rules

Author: NathanFlurry

docs-internal/specs/cli-tool-e2e.md

@@ -54,6 +54,37 @@ Priority order is:
 
 ## Priority 1: Compatibility and API Coverage
 
+- [ ] Add Node.js test suite and get it passing.
+  - Spec: `docs-internal/specs/nodejs-test-suite.md`
+  - Run a curated subset of the official Node.js `test/parallel/` tests against secure-exec to systematically find compatibility gaps.
+  - Vendor tests, provide a `common` shim (mustCall, mustSucceed, tmpdir, fixtures), run each through `proc.exec()` in a fresh `NodeRuntime`, report per-module pass/fail/skip/error.
+  - Ratchet rule: once a test passes, it cannot regress without justification.
+  - **Phase 1 — Harness + path module:**
+    - [ ] Build `common` shim module (mustCall, mustSucceed, mustNotCall, expectsError, tmpdir, fixtures, platform checks) as injectable CJS string for sandbox require() interception.
+    - [ ] Build test runner engine (`runner.ts`) + Vitest driver (`nodejs-suite.test.ts`) + manifest format (`manifest.json`). Runner creates fresh NodeRuntime per test, prepends common shim, captures exit code/stdio. Driver reads manifest, generates one Vitest test per entry, enforces ratchet.
+    - [ ] Vendor `test-path-*.js` from Node.js v22.14.0. Validate harness works. Target 100% pass rate (path is a pure polyfill via path-browserify, ~15 test files).
+  - **Phase 2 — Pure-JS polyfill modules:**
+    - [ ] Vendor + run `buffer` tests (~60 files). Expected 80-95% pass rate.
+    - [ ] Vendor + run `events` tests (~30 files). Expected 80-95% pass rate.
+    - [ ] Vendor + run `url` + `querystring` + `string_decoder` tests (~35 files combined).
+    - [ ] Vendor + run `util` + `assert` tests (~60 files combined). Expect util.inspect() divergences.
+  - **Phase 3 — Bridge modules:**
+    - [ ] Vendor + run `fs` tests (~150 files, largest surface). Skip deferred APIs (chmod, chown, symlink, watch). Target 50%+ on compatible tests.
+    - [ ] Vendor + run `process` + `os` + `timers` tests. Skip exit/abort/signal tests for process.
+    - [ ] Vendor + run `child_process` tests (~50 files). Skip fork (not bridged). Target spawn/exec basics.
+    - [ ] Vendor + run `http` + `dns` tests. Skip Agent pooling, upgrade, trailers for http.
+  - **Phase 4 — Stubs + automation + dashboard:**
+    - [ ] Vendor + run `stream` + `zlib` tests. Expect moderate pass rate.
+    - [ ] Vendor + run `crypto` tests. Expect very low pass rate (~5%) — purpose is gap documentation.
+    - [ ] Build automated curation script: clone nodejs/node at pinned tag, filter test/parallel/ by module, static analysis for skip patterns, copy to vendored/, generate manifest.
+    - [ ] Build CI compatibility report + ratchet enforcement. Per-module pass/fail/skip/error counts and percentages. Publish scores to `docs/nodejs-compatibility.mdx`.
+
+- [ ] Add support for forking and snapshotting.
+  - Enable isolate snapshots so a warm VM state (loaded modules, initialized globals) can be captured and restored without re-executing boot code.
+  - Investigate V8 snapshot support in isolated-vm and/or custom serialization of module cache + global state.
+  - Fork support: create a new execution context from an existing snapshot with copy-on-write semantics for the module cache.
+  - Key use cases: fast cold-start for serverless, checkpoint/restore for long-running agent sessions, parallel execution from a shared base state.
+
 - [ ] Fix `v8.serialize` and `v8.deserialize` to use V8 structured serialization semantics.
   - The current JSON-based behavior is observably wrong for `Map`, `Set`, `RegExp`, circular references, and other structured-clone cases.
   - Files: `packages/secure-exec/isolate-runtime/src/inject/bridge-initial-globals.ts`
@@ -125,9 +156,11 @@ Priority order is:
 - [ ] CLI tool E2E validation: Pi, Claude Code, and OpenCode inside sandbox.
   - Prove that real-world AI coding agents boot and produce output in secure-exec.
   - Spec: `docs-internal/specs/cli-tool-e2e.md`
-  - Phases: Pi headless → Pi interactive/PTY → OpenCode headless (binary spawn + SDK) → OpenCode interactive/PTY → Claude Code headless → Claude Code interactive/PTY
-  - OpenCode is a Bun binary (hardest) — tests the child_process spawn path and SDK HTTP/SSE client path (not in-VM execution); done before Claude Code to front-load risk
-  - Prerequisite bridge gaps: controllable `isTTY`, `setRawMode()` under PTY, HTTPS client verification, Stream Transform/PassThrough, SSE/EventSource client
+  - SDK, headless binary, and tool-use modes are passing for all three tools. Agentic workflow tests (multi-turn, npm install, npx, dev server lifecycle) also passing.
+  - Remaining work — full TTY / interactive mode for all three tools:
+    - [ ] Pi full TTY mode — BLOCKED: all 5 PTY tests skip. Pi CLI can't fully load in sandbox — undici requires `util/types` which is not yet bridged. Test infrastructure in place (TerminalHarness + kernel.openShell + HostBinaryDriver). Blocker: implement `util/types` bridge or workaround for undici dependency.
+    - [ ] Claude Code full TTY mode — BLOCKED: all 6 PTY tests skip. HostBinaryDriver + TerminalHarness infrastructure is in place, but boot probe fails — Claude Code's interactive startup requires handling workspace trust dialog and API validation that the mock server doesn't fully support. Blocker: mock server needs to handle Claude's full startup handshake.
+    - [ ] OpenCode full TTY mode — PARTIALLY WORKING: 4 of 5 PTY tests pass (TUI renders, input works, ^C works, exit works), but 'submit prompt and see response' test FAILS with waitFor timeout. Mock LLM response doesn't render on screen after submit. Also: HostBinaryDriver is copy-pasted across 3 interactive test files — needs extraction to shared module. Blocker: fix submit+response rendering through kernel PTY.
 
 - [x] Review the Node driver against the intended long-term runtime contract. *(done — `.agent/contracts/node-runtime.md` and `node-bridge.md` exist)*
 

docs-internal/specs/nodejs-test-suite.md

@@ -108,6 +108,27 @@ The [project-matrix test suite](https://github.com/rivet-dev/secure-exec/tree/ma
 
 To request a new package be added to the test suite, [open an issue](https://github.com/rivet-dev/secure-exec/issues/new?labels=package-request&title=Package+request:+%5Bpackage-name%5D).
 
+## Known Unsupported npm Packages (Native Extensions)
+
+These popular packages ship native binaries or platform-specific `.node` addons and cannot run inside a secure-exec V8 isolate. Native addons require Node's native module loader (`dlopen`), which is not available in the sandbox. The overlay module loader explicitly rejects `.node` files.
+
+| Package | Weekly Downloads | Why It Fails | Pure-JS Alternative |
+| --- | --- | --- | --- |
+| [esbuild](https://npmjs.com/package/esbuild) | 116M | Spawns a platform-specific Go binary; JS API is a thin IPC wrapper | [`esbuild-wasm`](https://npmjs.com/package/esbuild-wasm) (same API, ~3x slower) |
+| [rollup](https://npmjs.com/package/rollup) (v4+) | 78M | Rust parser via napi-rs (`@rollup/rollup-linux-x64-gnu`, etc.) | [`@rollup/wasm-node`](https://npmjs.com/package/@rollup/wasm-node) (WASM fallback) |
+| [vite](https://npmjs.com/package/vite) | 65M | Hard dependency on esbuild (dep optimization) and rollup (bundling) | [webpack](https://npmjs.com/package/webpack) (pure JS) |
+| [tailwindcss](https://npmjs.com/package/tailwindcss) (v4) | 51M | Rust Oxide engine via napi-rs (`@tailwindcss/oxide-*`) | [`tailwindcss@3`](https://npmjs.com/package/tailwindcss) (pure JS PostCSS plugin) |
+| [next](https://npmjs.com/package/next) | 27M | Rust SWC compiler (`@next/swc-*`); also depends on esbuild | No pure-JS equivalent |
+| [sass-embedded](https://npmjs.com/package/sass-embedded) | — | Wraps a native Dart executable | [`sass`](https://npmjs.com/package/sass) (dart2js compiled, pure JS) |
+| [node-sass](https://npmjs.com/package/node-sass) | — | C++ LibSass binding via node-gyp (deprecated) | [`sass`](https://npmjs.com/package/sass) |
+| [bcrypt](https://npmjs.com/package/bcrypt) | — | C++ binding via node-gyp | [`bcryptjs`](https://npmjs.com/package/bcryptjs) (pure JS) |
+| [@swc/core](https://npmjs.com/package/@swc/core) | — | Rust/napi-rs transpiler | [typescript](https://npmjs.com/package/typescript) `transpileModule()` or [babel](https://npmjs.com/package/@babel/core) |
+| [sharp](https://npmjs.com/package/sharp) | — | C++ libvips binding via prebuild | [jimp](https://npmjs.com/package/jimp) (pure JS, slower) |
+| [better-sqlite3](https://npmjs.com/package/better-sqlite3) | — | C++ SQLite binding via node-gyp | [sql.js](https://npmjs.com/package/sql.js) (WASM-based SQLite) |
+| [canvas](https://npmjs.com/package/canvas) | — | C++ Cairo/Pango binding via node-gyp | [@napi-rs/canvas](https://npmjs.com/package/@napi-rs/canvas) is also native; no pure-JS equivalent |
+
+Packages in the [Tested Packages](#tested-packages) table that overlap with this list (e.g. `next`, `vite`) have fixtures that test module resolution and limited API surface, not the full native build pipeline.
+
 ## Logging Behavior
 
 - `console.log`/`warn`/`error` are supported and serialize arguments with circular-safe bounded formatting.

docs-internal/todo.md

@@ -458,13 +458,23 @@ class KernelImpl implements Kernel {
 			if (!stderrCb) stderrCb = (data) => stderrBuf.push(data);
 		}
 
+		// Detect TTY attachment — check if each stdio FD is a PTY slave
+		const stdinEntry = table.get(0);
+		const stdoutEntry = table.get(1);
+		const stderrEntry = table.get(2);
+
 		// Build process context with pre-wired callbacks
 		const ctx: ProcessContext = {
 			pid,
 			ppid: callerPid ?? 0,
 			env: { ...this.env, ...options?.env },
 			cwd: options?.cwd ?? this.cwd,
 			fds: { stdin: 0, stdout: 1, stderr: 2 },
+			isTTY: {
+				stdin: !!stdinEntry && this.ptyManager.isSlave(stdinEntry.description.id),
+				stdout: !!stdoutEntry && this.ptyManager.isSlave(stdoutEntry.description.id),
+				stderr: !!stderrEntry && this.ptyManager.isSlave(stderrEntry.description.id),
+			},
 			onStdout: stdoutCb,
 			onStderr: stderrCb,
 		};

docs/nodejs-compatibility.mdx

@@ -188,6 +188,8 @@ export interface ProcessContext {
 	env: Record<string, string>;
 	cwd: string;
 	fds: { stdin: number; stdout: number; stderr: number };
+	/** Whether stdin/stdout/stderr are connected to a PTY (terminal). */
+	isTTY: { stdin: boolean; stdout: boolean; stderr: boolean };
 	/** Kernel-provided callback for stdout data emitted during spawn. */
 	onStdout?: (data: Uint8Array) => void;
 	/** Kernel-provided callback for stderr data emitted during spawn. */

packages/kernel/src/kernel.ts

@@ -35,6 +35,7 @@ function createCtx(overrides?: Partial<ProcessContext>): ProcessContext {
 		env: {},
 		cwd: "/",
 		fds: { stdin: 0, stdout: 1, stderr: 2 },
+		isTTY: { stdin: false, stdout: false, stderr: false },
 		...overrides,
 	};
 }

packages/kernel/src/types.ts

@@ -20,12 +20,14 @@ import type {
 import {
   NodeExecutionDriver,
   createNodeDriver,
+  createDefaultNetworkAdapter,
 } from '@secure-exec/node';
 import {
   allowAllChildProcess,
 } from '@secure-exec/core';
 import type {
   CommandExecutor,
+  NetworkAdapter,
   Permissions,
   VirtualFileSystem,
 } from '@secure-exec/core';
@@ -44,6 +46,10 @@ export interface NodeRuntimeOptions {
    * (fs/network/env deny-by-default). Use allowAll for full sandbox access.
    */
   permissions?: Partial<Permissions>;
+  /** Enable default network adapter for sandbox fetch/http. */
+  useDefaultNetwork?: boolean;
+  /** Custom network adapter for sandbox fetch/http (overrides useDefaultNetwork). */
+  networkAdapter?: NetworkAdapter;
 }
 
 /**
@@ -318,11 +324,16 @@ class NodeRuntimeDriver implements RuntimeDriver {
   private _kernel: KernelInterface | null = null;
   private _memoryLimit: number;
   private _permissions: Partial<Permissions>;
+  private _moduleAccessPaths?: string[];
+  private _networkAdapter?: NetworkAdapter;
   private _activeDrivers = new Map<number, NodeExecutionDriver>();
 
   constructor(options?: NodeRuntimeOptions) {
     this._memoryLimit = options?.memoryLimit ?? 128;
     this._permissions = options?.permissions ?? { ...allowAllChildProcess };
+    this._moduleAccessPaths = options?.moduleAccessPaths;
+    this._networkAdapter = options?.networkAdapter
+      ?? (options?.useDefaultNetwork ? createDefaultNetworkAdapter() : undefined);
   }
 
   async init(kernel: KernelInterface): Promise<void> {
@@ -435,30 +446,59 @@ class NodeRuntimeDriver implements RuntimeDriver {
         filesystem = createHostFallbackVfs(filesystem);
       }
 
+      // Module access: use explicit paths if provided, otherwise default
+      const moduleAccess = this._moduleAccessPaths?.length
+        ? { cwd: this._moduleAccessPaths[0] }
+        : undefined;
+
       const systemDriver = createNodeDriver({
         filesystem,
         commandExecutor,
+        moduleAccess,
+        networkAdapter: this._networkAdapter,
         permissions: { ...this._permissions },
         processConfig: {
-          cwd: ctx.cwd,
+          // Sandbox CWD defaults to /root — the ModuleAccessFileSystem's synthetic
+          // root where /root/node_modules maps to the host's node_modules.
+          // The host-facing CWD (ctx.cwd) is used for command resolution, not for
+          // in-sandbox module resolution.
           env: ctx.env,
           argv: [process.execPath, filePath ?? command, ...args],
+          stdinIsTTY: ctx.isTTY.stdin,
+          stdoutIsTTY: ctx.isTTY.stdout,
+          stderrIsTTY: ctx.isTTY.stderr,
         },
       });
 
+      // Wire PTY setRawMode callback — when sandbox calls process.stdin.setRawMode(),
+      // translate to kernel PTY discipline change
+      let onPtySetRawMode: ((mode: boolean) => void) | undefined;
+      if (ctx.isTTY.stdin && kernel) {
+        onPtySetRawMode = (mode: boolean) => {
+          try {
+            kernel.ptySetDiscipline(ctx.pid, 0, {
+              canonical: !mode,
+              echo: !mode,
+            });
+          } catch { /* PTY may be gone */ }
+        };
+      }
+
       // Create a per-process isolate
       const executionDriver = new NodeExecutionDriver({
         system: systemDriver,
         runtime: systemDriver.runtime,
         memoryLimit: this._memoryLimit,
+        onPtySetRawMode,
       });
       this._activeDrivers.set(ctx.pid, executionDriver);
 
-      // Execute with stdout/stderr capture and stdin data
+      // Execute with stdout/stderr capture and stdin data.
+      // For inline code (-e), use a synthetic filePath under /root/ so that
+      // __dirname is /root/ and module resolution finds /root/node_modules.
       const result = await executionDriver.exec(code, {
-        filePath,
+        filePath: filePath ?? '/root/entry.js',
         env: ctx.env,
-        cwd: ctx.cwd,
         stdin: stdinData,
         onStdio: (event) => {
           const data = new TextEncoder().encode(event.message + '\n');

packages/kernel/test/process-table.test.ts

@@ -202,6 +202,7 @@ describe('Node RuntimeDriver', () => {
       const ctx: ProcessContext = {
         pid: 1, ppid: 0, env: {}, cwd: '/home/user',
         fds: { stdin: 0, stdout: 1, stderr: 2 },
+        isTTY: { stdin: false, stdout: false, stderr: false },
       };
       expect(() => driver.spawn('node', ['-e', 'true'], ctx)).toThrow(/not initialized/);
     });

packages/runtime/node/src/driver.ts

@@ -208,6 +208,7 @@ describe('Python RuntimeDriver', () => {
       const ctx: ProcessContext = {
         pid: 1, ppid: 0, env: {}, cwd: '/home/user',
         fds: { stdin: 0, stdout: 1, stderr: 2 },
+        isTTY: { stdin: false, stdout: false, stderr: false },
       };
       expect(() => driver.spawn('python', ['-c', 'pass'], ctx)).toThrow(/not initialized/);
     });