@scelar/nodepod 1.0.0

package/src/polyfills/child_process.ts

@@ -0,0 +1,2288 @@
+// child_process polyfill -- exec, execSync, spawn, fork backed by NodepodShell.
+// Integrates with MemoryVolume directly.
+
+import { NodepodShell } from "../shell/shell-interpreter";
+import type { ShellResult, ShellContext } from "../shell/shell-types";
+import { EventEmitter } from "./events";
+import { Readable, Writable } from "./stream";
+import { Buffer } from "./buffer";
+import type { MemoryVolume } from "../memory-volume";
+import { ScriptEngine } from "../script-engine";
+import type { PackageManifest } from "../types/manifest";
+import { resetActiveInterfaceCount } from "./readline";
+import { ref, unref, getRefCount, resetRefCount, addDrainListener } from "../helpers/event-loop";
+import { getActiveContext, setActiveContext } from "../threading/process-context";
+import type { ProcessContext } from "../threading/process-context";
+import type { PmDeps, PkgManager } from "../shell/commands/pm-types";
+import { createNpmCommand } from "../shell/commands/npm";
+import { createPnpmCommand } from "../shell/commands/pnpm";
+import { createYarnCommand } from "../shell/commands/yarn";
+import { createBunCommand, createBunxCommand } from "../shell/commands/bun";
+import { createNodeCommand, createNpxCommand } from "../shell/commands/node";
+import { createGitCommand } from "../shell/commands/git";
+import { format as utilFormat } from "./util";
+import { VERSIONS, NPM_REGISTRY_URL_SLASH, TIMEOUTS, DEFAULT_ENV, MOCK_PID } from "../constants/config";
+import { closeAllServers, getAllServers } from "./http";
+import type { SyncChannelWorker } from "../threading/sync-channel";
+
+let _shell: NodepodShell | null = null;
+let _vol: MemoryVolume | null = null;
+
+let _syncChannel: SyncChannelWorker | null = null;
+
+let _stdoutSink: ((text: string) => void) | null = null;
+let _stderrSink: ((text: string) => void) | null = null;
+let _haltSignal: AbortSignal | null = null;
+
+let _termCols: (() => number) | null = null;
+let _termRows: (() => number) | null = null;
+
+let _rawModeChangeCb: ((isRaw: boolean) => void) | null = null;
+
+// context-aware state accessors: check ProcessContext first, fall back to module globals
+
+function getStdoutSink(): ((text: string) => void) | null {
+  const ctx = getActiveContext();
+  return ctx?.stdoutSink ?? _stdoutSink;
+}
+
+function getStderrSink(): ((text: string) => void) | null {
+  const ctx = getActiveContext();
+  return ctx?.stderrSink ?? _stderrSink;
+}
+
+function getHaltSignal(): AbortSignal | null {
+  const ctx = getActiveContext();
+  return ctx ? ctx.abortController.signal : _haltSignal;
+}
+
+function getLiveStdin(): { emit: (e: string, ...a: unknown[]) => void } | null {
+  const ctx = getActiveContext();
+  return ctx?.liveStdin ?? _liveStdin;
+}
+
+function getTermCols(): number {
+  const ctx = getActiveContext();
+  return ctx?.termCols?.() ?? _termCols?.() ?? 80;
+}
+
+function getTermRows(): number {
+  const ctx = getActiveContext();
+  return ctx?.termRows?.() ?? _termRows?.() ?? 24;
+}
+
+function formatThrown(e: unknown): string {
+  if (e instanceof Error) {
+    const prefix =
+      e.constructor?.name && e.constructor.name !== "Error"
+        ? `${e.constructor.name}: `
+        : "";
+    let msg = prefix + (e.message || e.name || "Unknown error");
+    if (e.stack) msg += "\n" + e.stack;
+    return msg;
+  }
+  if (e === null || e === undefined) return "Script threw a falsy value";
+  return String(e) || "Unknown error (non-Error object thrown)";
+}
+
+export function setStreamingCallbacks(cfg: {
+  onStdout?: (t: string) => void;
+  onStderr?: (t: string) => void;
+  signal?: AbortSignal;
+  getCols?: () => number;
+  getRows?: () => number;
+  onRawModeChange?: (isRaw: boolean) => void;
+}): void {
+  _stdoutSink = cfg.onStdout ?? null;
+  _stderrSink = cfg.onStderr ?? null;
+  _haltSignal = cfg.signal ?? null;
+  _termCols = cfg.getCols ?? null;
+  _termRows = cfg.getRows ?? null;
+  _rawModeChangeCb = cfg.onRawModeChange ?? null;
+
+  // also update active ProcessContext if present
+  const ctx = getActiveContext();
+  if (ctx) {
+    ctx.stdoutSink = cfg.onStdout ?? null;
+    ctx.stderrSink = cfg.onStderr ?? null;
+    if (cfg.signal) {
+      cfg.signal.addEventListener("abort", () => ctx.abortController.abort(), { once: true });
+    }
+    ctx.termCols = cfg.getCols ?? null;
+    ctx.termRows = cfg.getRows ?? null;
+  }
+}
+
+export function clearStreamingCallbacks(): void {
+  _stdoutSink = null;
+  _stderrSink = null;
+  _haltSignal = null;
+  _termCols = null;
+  _termRows = null;
+  _rawModeChangeCb = null;
+
+  // also clear active ProcessContext if present
+  const ctx = getActiveContext();
+  if (ctx) {
+    ctx.stdoutSink = null;
+    ctx.stderrSink = null;
+    ctx.termCols = null;
+    ctx.termRows = null;
+  }
+}
+
+// set the SyncChannelWorker for true blocking execSync/spawnSync in worker mode
+export function setSyncChannel(channel: SyncChannelWorker): void {
+  _syncChannel = channel;
+}
+
+// onStdout/onStderr fire in real-time as output arrives; promise resolves on child exit
+export type SpawnChildCallback = (
+  command: string,
+  args: string[],
+  opts?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdio?: "pipe" | "inherit";
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+  },
+) => Promise<{ pid: number; exitCode: number; stdout: string; stderr: string }>;
+
+let _spawnChildFn: SpawnChildCallback | null = null;
+
+export function setSpawnChildCallback(fn: SpawnChildCallback): void {
+  _spawnChildFn = fn;
+}
+
+// returns ForkHandle immediately; onExit fires when the child exits
+export type ForkChildCallback = (
+  modulePath: string,
+  args: string[],
+  opts: {
+    cwd: string;
+    env: Record<string, string>;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    onIPC?: (data: unknown) => void;
+    onExit?: (exitCode: number) => void;
+  },
+) => {
+  sendIPC: (data: unknown) => void;
+  disconnect: () => void;
+  requestId: number;
+};
+
+let _forkChildFn: ForkChildCallback | null = null;
+
+export function setForkChildCallback(fn: ForkChildCallback): void {
+  _forkChildFn = fn;
+}
+
+// IPC plumbing for when this worker IS a forked child
+let _ipcSendFn: ((data: unknown) => void) | null = null;
+let _ipcReceiveHandler: ((data: unknown) => void) | null = null;
+// messages that arrive before the handler is wired (parent sends before child's ENB sets up the handler)
+let _ipcQueue: unknown[] = [];
+
+export function setIPCSend(fn: (data: unknown) => void): void {
+  _ipcSendFn = fn;
+}
+
+export function setIPCReceiveHandler(fn: (data: unknown) => void): void {
+  _ipcReceiveHandler = fn;
+  // replay any messages that arrived before the handler was set
+  if (_ipcQueue.length > 0) {
+    const queued = _ipcQueue;
+    _ipcQueue = [];
+    for (const msg of queued) fn(msg);
+  }
+}
+
+// called by process-worker-entry when an IPC message arrives
+export function handleIPCFromParent(data: unknown): void {
+  if (_ipcReceiveHandler) {
+    _ipcReceiveHandler(data);
+  } else {
+    // handler not wired yet, queue for replay
+    _ipcQueue.push(data);
+  }
+}
+
+export function getShellCwd(): string {
+  return _shell?.getCwd() ?? "/";
+}
+
+// called by process.chdir() so subsequent exec/spawn without explicit cwd pick up the new dir
+export function setShellCwd(dir: string): void {
+  if (_shell) _shell.setCwd(dir);
+}
+
+// runs command inline in the current worker via NodepodShell (NOT a child process).
+// child_process.exec() spawns a new worker; shellExec() runs in THIS process.
+export function shellExec(
+  cmd: string,
+  opts: { cwd?: string; env?: Record<string, string> },
+  callback: (error: Error | null, stdout: string, stderr: string) => void,
+): void {
+  if (!_shell) {
+    callback(new Error("[Nodepod] Shell not initialized"), "", "");
+    return;
+  }
+  _shell.exec(cmd, opts).then(
+    (result) => {
+      if (result.exitCode !== 0) {
+        const e = new Error(`Command failed: ${cmd}`);
+        (e as any).code = result.exitCode;
+        callback(e, result.stdout, result.stderr);
+      } else {
+        callback(null, result.stdout, result.stderr);
+      }
+    },
+    (e) => {
+      callback(e instanceof Error ? e : new Error(String(e)), "", "");
+    },
+  );
+}
+
+let _liveStdin: { emit: (e: string, ...a: unknown[]) => void } | null = null;
+
+// check if the live process stdin is in raw mode (library handles its own echo)
+export function isStdinRaw(): boolean {
+  const stdin = getLiveStdin();
+  if (!stdin) return false;
+  return !!(stdin as any).isRaw;
+}
+
+export function sendStdin(text: string): void {
+  const stdin = getLiveStdin();
+  if (!stdin) {
+    return;
+  }
+  // emit 'data' only -- readline.emitKeypressEvents() parses data into 'keypress' events
+  // automatically, matching real Node.js
+  stdin.emit("data", text);
+}
+
+export function initShellExec(volume: MemoryVolume, opts?: { cwd?: string; env?: Record<string, string> }): void {
+  _vol = volume;
+
+  _shell = new NodepodShell(volume, {
+    cwd: opts?.cwd ?? "/",
+    env: {
+      HOME: "/home/user",
+      USER: "user",
+      PATH: "/usr/local/bin:/usr/bin:/bin:/node_modules/.bin",
+      NODE_ENV: "development",
+      TERM: "xterm-256color",
+      COLORTERM: "truecolor",
+      npm_config_user_agent: DEFAULT_ENV.npm_config_user_agent,
+      npm_execpath: DEFAULT_ENV.npm_execpath,
+      npm_node_execpath: DEFAULT_ENV.npm_node_execpath,
+      ...opts?.env,
+    },
+  });
+
+  const pmDeps: PmDeps = {
+    installPackages,
+    uninstallPackages,
+    listPackages,
+    runScript,
+    npmInitOrCreate,
+    npmInfo,
+    npmPack,
+    npmConfig,
+    npxExecute,
+    executeNodeBinary,
+    evalCode: (code, ctx) => evalNodeCode(code, ctx),
+    printCode: (code, ctx) => printNodeCode(code, ctx),
+    removeNodeModules: (cwd) => {
+      const dir = `${cwd}/node_modules`.replace(/\/+/g, "/");
+      if (_vol!.existsSync(dir)) removeDir(_vol!, dir);
+    },
+    formatErr,
+    formatWarn,
+    hasFile: (p) => !!_vol && _vol.existsSync(p),
+    readFile: (p) => _vol!.readFileSync(p, "utf8") as string,
+    writeFile: (p, data) => _vol!.writeFileSync(p, data),
+  };
+
+  _shell.registerCommand(createNodeCommand(pmDeps));
+  _shell.registerCommand(createNpxCommand(pmDeps));
+  _shell.registerCommand(createNpmCommand(pmDeps));
+  _shell.registerCommand(createPnpmCommand(pmDeps));
+  _shell.registerCommand(createYarnCommand(pmDeps));
+  _shell.registerCommand(createBunCommand(pmDeps));
+  _shell.registerCommand(createBunxCommand(pmDeps));
+  _shell.registerCommand(createGitCommand());
+}
+
+// node -e / -p helpers (used by PmDeps)
+
+function evalNodeCode(code: string, ctx: ShellContext): ShellResult {
+  let out = "";
+  let err = "";
+  const sandbox = new ScriptEngine(_vol!, {
+    cwd: ctx.cwd,
+    env: ctx.env,
+    onConsole: (m: string, args: unknown[]) => {
+      const line = utilFormat(args[0], ...args.slice(1)) + "\n";
+      m === "error" ? (err += line) : (out += line);
+    },
+    onStdout: (s: string) => {
+      out += s;
+    },
+    onStderr: (s: string) => {
+      err += s;
+    },
+  });
+  try {
+    sandbox.execute(code, "/<eval>.js");
+  } catch (e) {
+    if (e instanceof Error && e.message.startsWith("Process exited with code"))
+      return { stdout: out, stderr: err, exitCode: 0 };
+    err += `Error: ${e instanceof Error ? e.message : String(e)}\n`;
+    return { stdout: out, stderr: err, exitCode: 1 };
+  }
+  return { stdout: out, stderr: err, exitCode: 0 };
+}
+
+function printNodeCode(code: string, ctx: ShellContext): ShellResult {
+  let out = "";
+  let err = "";
+  const sandbox = new ScriptEngine(_vol!, {
+    cwd: ctx.cwd,
+    env: ctx.env,
+    onConsole: (m: string, args: unknown[]) => {
+      const line = utilFormat(args[0], ...args.slice(1)) + "\n";
+      m === "error" ? (err += line) : (out += line);
+    },
+    onStdout: (s: string) => {
+      out += s;
+    },
+    onStderr: (s: string) => {
+      err += s;
+    },
+  });
+  try {
+    const result = sandbox.execute(code, "/<print>.js");
+    out += String(result.exports) + "\n";
+  } catch (e) {
+    err += `Error: ${e instanceof Error ? e.message : String(e)}\n`;
+    return { stdout: out, stderr: err, exitCode: 1 };
+  }
+  return { stdout: out, stderr: err, exitCode: 0 };
+}
+
+// npm helpers
+
+function removeDir(vol: MemoryVolume, dir: string): void {
+  for (const name of vol.readdirSync(dir)) {
+    const full = `${dir}/${name}`;
+    const st = vol.statSync(full);
+    if (st.isDirectory()) removeDir(vol, full);
+    else vol.unlinkSync(full);
+  }
+  vol.rmdirSync(dir);
+}
+
+function loadManifest(
+  cwd: string,
+): { pkg: PackageManifest } | { fail: ShellResult } {
+  const p = `${cwd}/package.json`.replace(/\/+/g, "/");
+  if (!_vol!.existsSync(p))
+    return {
+      fail: {
+        stdout: "",
+        stderr: formatErr("package.json not found", "npm"),
+        exitCode: 1,
+      },
+    };
+  try {
+    return {
+      pkg: JSON.parse(_vol!.readFileSync(p, "utf8")) as PackageManifest,
+    };
+  } catch {
+    return {
+      fail: {
+        stdout: "",
+        stderr: formatErr("Malformed package.json", "npm"),
+        exitCode: 1,
+      },
+    };
+  }
+}
+
+async function runScript(
+  args: string[],
+  ctx: ShellContext,
+): Promise<ShellResult> {
+  const name = args[0];
+  if (!name) {
+    const r = loadManifest(ctx.cwd);
+    if ("fail" in r) return r.fail;
+    const scripts = r.pkg.scripts ?? {};
+    const keys = Object.keys(scripts);
+    if (keys.length === 0) return { stdout: "", stderr: "", exitCode: 0 };
+    let text = `Scripts in ${r.pkg.name ?? ""}:\n`;
+    for (const k of keys) text += `  ${k}\n    ${scripts[k]}\n`;
+    return { stdout: text, stderr: "", exitCode: 0 };
+  }
+
+  // extra arguments after "--" separator (npm run dev -- --webpack)
+  const dashIdx = args.indexOf("--");
+  const extraArgs = dashIdx >= 0 ? args.slice(dashIdx + 1) : [];
+
+  const r = loadManifest(ctx.cwd);
+  if ("fail" in r) return r.fail;
+  const scripts = r.pkg.scripts ?? {};
+  let cmd = scripts[name];
+  if (!cmd) {
+    let msg = formatErr(`Missing script: "${name}"`, "npm");
+    const avail = Object.keys(scripts);
+    if (avail.length) {
+      msg += "\nAvailable:\n";
+      for (const s of avail)
+        msg += `  ${A_CYAN}${s}${A_RESET}: ${A_DIM}${scripts[s]}${A_RESET}\n`;
+    }
+    return { stdout: "", stderr: msg, exitCode: 1 };
+  }
+
+  // append extra args after "--" to the script command (real npm behavior)
+  if (extraArgs.length > 0) {
+    cmd += " " + extraArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ");
+  }
+
+  // prepend cwd's node_modules/.bin to PATH (matches real npm behavior)
+  const binDir = `${ctx.cwd}/node_modules/.bin`.replace(/\/+/g, "/");
+  const existingPath = ctx.env.PATH || "";
+  const pathWithBin = existingPath.includes(binDir)
+    ? existingPath
+    : `${binDir}:${existingPath}`;
+
+  const env: Record<string, string> = {
+    ...ctx.env,
+    PATH: pathWithBin,
+    npm_lifecycle_event: name,
+  };
+  if (r.pkg.name) env.npm_package_name = r.pkg.name;
+  if (r.pkg.version) env.npm_package_version = r.pkg.version;
+
+  let allOut = "";
+  let allErr = "";
+  const label = `${r.pkg.name ?? ""}@${r.pkg.version ?? ""}`;
+
+  const pre = scripts[`pre${name}`];
+  if (pre) {
+    const hdr = `\n> ${label} pre${name}\n> ${pre}\n\n`;
+    allErr += hdr;
+    if (_stderrSink) _stderrSink(hdr);
+    const pr = await ctx.exec(pre, { cwd: ctx.cwd, env });
+    allOut += pr.stdout;
+    allErr += pr.stderr;
+    if (pr.exitCode !== 0)
+      return { stdout: allOut, stderr: allErr, exitCode: pr.exitCode };
+  }
+
+  const mainHdr = `\n> ${label} ${name}\n> ${cmd}\n\n`;
+  allErr += mainHdr;
+  if (_stderrSink) _stderrSink(mainHdr);
+  const mr = await ctx.exec(cmd, { cwd: ctx.cwd, env });
+  allOut += mr.stdout;
+  allErr += mr.stderr;
+  if (mr.exitCode !== 0)
+    return { stdout: allOut, stderr: allErr, exitCode: mr.exitCode };
+
+  const post = scripts[`post${name}`];
+  if (post) {
+    const hdr = `\n> ${label} post${name}\n> ${post}\n\n`;
+    allErr += hdr;
+    if (_stderrSink) _stderrSink(hdr);
+    const po = await ctx.exec(post, { cwd: ctx.cwd, env });
+    allOut += po.stdout;
+    allErr += po.stderr;
+    if (po.exitCode !== 0)
+      return { stdout: allOut, stderr: allErr, exitCode: po.exitCode };
+  }
+
+  return { stdout: allOut, stderr: allErr, exitCode: 0 };
+}
+
+// ANSI + spinner helpers for npm install output
+
+const A_RESET = "\x1b[0m";
+const A_BOLD = "\x1b[1m";
+const A_DIM = "\x1b[2m";
+const A_RED = "\x1b[31m";
+const A_GREEN = "\x1b[32m";
+const A_YELLOW = "\x1b[33m";
+const A_BLUE = "\x1b[34m";
+const A_MAGENTA = "\x1b[35m";
+const A_CYAN = "\x1b[36m";
+const A_WHITE = "\x1b[37m";
+const ERASE_LINE = "\x1b[2K";
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function createSpinner(text: string, writeFn: (s: string) => void) {
+  let frame = 0;
+  let current = text;
+  const id = setInterval(() => {
+    writeFn(
+      `${ERASE_LINE}\r${A_CYAN}${SPINNER_FRAMES[frame]}${A_RESET} ${current}`,
+    );
+    frame = (frame + 1) % SPINNER_FRAMES.length;
+  }, 80);
+
+  return {
+    update(t: string) {
+      current = t;
+    },
+    succeed(t: string) {
+      clearInterval(id);
+      writeFn(`${ERASE_LINE}\r${A_GREEN}✔${A_RESET} ${t}\n`);
+    },
+    fail(t: string) {
+      clearInterval(id);
+      writeFn(`${ERASE_LINE}\r${A_RED}✖${A_RESET} ${t}\n`);
+    },
+    stop() {
+      clearInterval(id);
+    },
+  };
+}
+
+// per-PM accent colors
+const PM_COLORS: Record<PkgManager, string> = {
+  npm: A_RED,
+  pnpm: A_YELLOW,
+  yarn: A_BLUE,
+  bun: A_WHITE,
+};
+
+function formatProgress(msg: string, pm: PkgManager = "npm"): string {
+  const accent = PM_COLORS[pm];
+
+  const resolving = msg.match(/^Resolving\s+(.+?)\.{3}$/);
+  if (resolving)
+    return `${A_DIM}Resolving${A_RESET} ${accent}${resolving[1]}${A_RESET}${A_DIM}...${A_RESET}`;
+
+  const downloading = msg.match(/^Downloading\s+(\d+)\s+package/);
+  if (downloading)
+    return `${A_DIM}Downloading${A_RESET} ${A_YELLOW}${downloading[1]}${A_RESET} ${A_DIM}packages...${A_RESET}`;
+
+  const fetching = msg.match(/^(?:\s*)?Fetching\s+(.+?)\.{3}$/);
+  if (fetching)
+    return `${A_DIM}Fetching${A_RESET} ${accent}${fetching[1]}${A_RESET}${A_DIM}...${A_RESET}`;
+
+  const transformed = msg.match(/^(?:\s*)?Transformed\s+(\d+)\s+file/);
+  if (transformed) return `${A_DIM}${msg.trim()}${A_RESET}`;
+
+  const installed = msg.match(/^Installed\s+(\d+)/);
+  if (installed) return `${A_GREEN}${msg}${A_RESET}`;
+
+  const skipping = msg.match(/^Skipping\s+(.+?)\s+\(up to date\)$/);
+  if (skipping)
+    return `${A_DIM}Skipping${A_RESET} ${accent}${skipping[1]}${A_RESET} ${A_DIM}(up to date)${A_RESET}`;
+
+  return msg;
+}
+
+function formatInstallSummary(
+  totalAdded: number,
+  elapsed: string,
+  pm: PkgManager,
+): string {
+  const pkgs = `${totalAdded} package${totalAdded !== 1 ? "s" : ""}`;
+  switch (pm) {
+    case "npm":
+      return `${A_BOLD}added ${pkgs}${A_RESET} ${A_DIM}in ${elapsed}s${A_RESET}`;
+    case "pnpm":
+      return `${A_BOLD}packages:${A_RESET} ${A_GREEN}+${totalAdded}${A_RESET}\n${A_DIM}Done in ${elapsed}s${A_RESET}`;
+    case "yarn":
+      return `${A_BOLD}${pkgs} added${A_RESET} ${A_DIM}in ${elapsed}s${A_RESET}`;
+    case "bun":
+      return `${A_BOLD}${pkgs} installed${A_RESET} ${A_DIM}[${elapsed}s]${A_RESET}`;
+  }
+}
+
+function formatErr(msg: string, pm: PkgManager): string {
+  switch (pm) {
+    case "npm":
+      return `${A_RED}npm ERR!${A_RESET} ${msg}\n`;
+    case "pnpm":
+      return `${A_RED} ERR_PNPM${A_RESET}  ${msg}\n`;
+    case "yarn":
+      return `${A_RED}error${A_RESET} ${msg}\n`;
+    case "bun":
+      return `${A_RED}error:${A_RESET} ${msg}\n`;
+  }
+}
+
+function formatWarn(msg: string, pm: PkgManager): string {
+  switch (pm) {
+    case "npm":
+      return `${A_YELLOW}npm WARN${A_RESET} ${msg}\n`;
+    case "pnpm":
+      return `${A_YELLOW} WARN${A_RESET}  ${msg}\n`;
+    case "yarn":
+      return `${A_YELLOW}warning${A_RESET} ${msg}\n`;
+    case "bun":
+      return `${A_YELLOW}warn:${A_RESET} ${msg}\n`;
+  }
+}
+
+async function installPackages(
+  args: string[],
+  ctx: ShellContext,
+  pm: PkgManager = "npm",
+): Promise<ShellResult> {
+  const { DependencyInstaller } = await import("../packages/installer");
+  const installer = new DependencyInstaller(_vol!, { cwd: ctx.cwd });
+  let out = "";
+  const write = _stdoutSink ?? ((_s: string) => {});
+  const startTime = Date.now();
+  const accent = PM_COLORS[pm];
+
+  const spinnerText =
+    pm === "bun"
+      ? `${A_DIM}bun install${A_RESET} ${A_DIM}${VERSIONS.BUN_V}${A_RESET}`
+      : `${A_DIM}Resolving dependencies...${A_RESET}`;
+  const spinner = createSpinner(spinnerText, write);
+
+  try {
+    const names = args.filter((a: string) => !a.startsWith("-"));
+    const onProgress = (m: string) => {
+      const colored = formatProgress(m, pm);
+      out += m + "\n";
+      spinner.update(colored);
+    };
+
+    let totalAdded = 0;
+    if (names.length === 0) {
+      const ir = await installer.installFromManifest(undefined, {
+        withDevDeps: true,
+        onProgress,
+      });
+      totalAdded = ir.newPackages.length;
+    } else {
+      for (const n of names) {
+        const ir = await installer.install(n, undefined, { onProgress });
+        totalAdded += ir.newPackages.length;
+      }
+    }
+
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    const summary = formatInstallSummary(totalAdded, elapsed, pm);
+    spinner.succeed(summary);
+    out += `added ${totalAdded} packages in ${elapsed}s\n`;
+
+    return { stdout: out, stderr: "", exitCode: 0 };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    spinner.fail(`${A_RED}${msg}${A_RESET}`);
+    return {
+      stdout: out,
+      stderr: formatErr(msg, pm),
+      exitCode: 1,
+    };
+  }
+}
+
+async function uninstallPackages(
+  args: string[],
+  ctx: ShellContext,
+  pm: PkgManager = "npm",
+): Promise<ShellResult> {
+  const names = args.filter((a) => !a.startsWith("-"));
+  if (names.length === 0)
+    return {
+      stdout: "",
+      stderr: formatErr("Must specify package to remove", pm),
+      exitCode: 1,
+    };
+
+  const write = _stdoutSink ?? ((_s: string) => {});
+  let out = "";
+  for (const name of names) {
+    const pkgDir = `${ctx.cwd}/node_modules/${name}`.replace(/\/+/g, "/");
+    if (_vol!.existsSync(pkgDir)) {
+      try {
+        removeDir(_vol!, pkgDir);
+        const msg =
+          pm === "bun"
+            ? `${A_DIM}-${A_RESET} ${name}`
+            : pm === "pnpm"
+              ? `${A_RED}-${A_RESET} ${name}`
+              : `removed ${name}`;
+        out += msg + "\n";
+        write(msg + "\n");
+      } catch (e) {
+        return {
+          stdout: out,
+          stderr: formatErr(
+            `Failed to remove ${name}: ${e instanceof Error ? e.message : String(e)}`,
+            pm,
+          ),
+          exitCode: 1,
+        };
+      }
+    } else {
+      out += formatWarn(`${name} not installed`, pm);
+    }
+
+    const r = loadManifest(ctx.cwd);
+    if (!("fail" in r)) {
+      const pkg = r.pkg;
+      let changed = false;
+      if (pkg.dependencies?.[name]) {
+        delete pkg.dependencies[name];
+        changed = true;
+      }
+      if (pkg.devDependencies?.[name]) {
+        delete pkg.devDependencies[name];
+        changed = true;
+      }
+      if (changed) {
+        const p = `${ctx.cwd}/package.json`.replace(/\/+/g, "/");
+        _vol!.writeFileSync(p, JSON.stringify(pkg, null, 2));
+      }
+    }
+  }
+
+  return { stdout: out, stderr: "", exitCode: 0 };
+}
+
+async function listPackages(
+  ctx: ShellContext,
+  pm: PkgManager = "npm",
+): Promise<ShellResult> {
+  const { DependencyInstaller } = await import("../packages/installer");
+  const installer = new DependencyInstaller(_vol!, { cwd: ctx.cwd });
+  const pkgs = installer.listInstalled();
+  const entries = Object.entries(pkgs);
+  if (entries.length === 0)
+    return { stdout: `${A_DIM}(empty)${A_RESET}\n`, stderr: "", exitCode: 0 };
+
+  const r = loadManifest(ctx.cwd);
+  const label = !("fail" in r)
+    ? `${r.pkg.name ?? "project"}@${r.pkg.version ?? "0.0.0"}`
+    : ctx.cwd;
+
+  let text = "";
+  switch (pm) {
+    case "npm":
+      text += `${label} ${ctx.cwd}\n`;
+      for (let i = 0; i < entries.length; i++) {
+        const [n, v] = entries[i];
+        const isLast = i === entries.length - 1;
+        text += `${isLast ? "└──" : "├──"} ${n}@${A_DIM}${v}${A_RESET}\n`;
+      }
+      break;
+    case "pnpm":
+      text += `${A_DIM}Legend: production dependency, optional only, dev only${A_RESET}\n\n`;
+      text += `${label} ${ctx.cwd}\n\n`;
+      text += `${A_BOLD}dependencies:${A_RESET}\n`;
+      for (const [n, v] of entries) text += `${n} ${A_DIM}${v}${A_RESET}\n`;
+      break;
+    case "yarn":
+      text += `${A_BOLD}${label}${A_RESET}\n`;
+      for (let i = 0; i < entries.length; i++) {
+        const [n, v] = entries[i];
+        const isLast = i === entries.length - 1;
+        text += `${isLast ? "└─" : "├─"} ${n}@${A_CYAN}${v}${A_RESET}\n`;
+      }
+      break;
+    case "bun":
+      for (const [n, v] of entries) text += `${n}@${A_DIM}${v}${A_RESET}\n`;
+      text += `\n${A_DIM}${entries.length} packages installed${A_RESET}\n`;
+      break;
+  }
+  return { stdout: text, stderr: "", exitCode: 0 };
+}
+
+async function npmInitOrCreate(
+  args: string[],
+  sub: string,
+  ctx: ShellContext,
+): Promise<ShellResult> {
+  const flags = args.filter((a) => a.startsWith("-"));
+  const positional = args.filter((a) => !a.startsWith("-"));
+
+  // npm create <pkg> / npm init <pkg> → npx create-<pkg>
+  if (sub === "create" || (sub === "init" && positional.length > 0)) {
+    const initializer = positional[0];
+    let pkgSpec: string;
+    if (initializer.startsWith("@")) {
+      // scoped: npm create @scope/pkg → npx @scope/create-pkg
+      pkgSpec = initializer;
+    } else {
+      // vite@latest → create-vite@latest
+      const atIdx = initializer.indexOf("@");
+      if (atIdx > 0) {
+        const name = initializer.slice(0, atIdx);
+        const ver = initializer.slice(atIdx);
+        pkgSpec = `create-${name}${ver}`;
+      } else {
+        pkgSpec = `create-${initializer}`;
+      }
+    }
+    return npxExecute(["-y", pkgSpec, ...positional.slice(1), ...flags], ctx);
+  }
+
+  // plain npm init [-y] → create package.json
+  const p = `${ctx.cwd}/package.json`.replace(/\/+/g, "/");
+  if (_vol!.existsSync(p)) {
+    return {
+      stdout: "",
+      stderr: formatWarn("package.json already exists", "npm"),
+      exitCode: 0,
+    };
+  }
+
+  const isYes = flags.includes("-y") || flags.includes("--yes");
+  const name = ctx.cwd.split("/").filter(Boolean).pop() || "my-project";
+
+  const pkg: PackageManifest = {
+    name,
+    version: "1.0.0",
+    description: "",
+    main: "index.js",
+    scripts: {
+      test: 'echo "Error: no test specified" && exit 1',
+      start: "node index.js",
+    },
+    keywords: [],
+    author: "",
+    license: "ISC",
+  };
+
+  _vol!.writeFileSync(p, JSON.stringify(pkg, null, 2));
+  const out = isYes
+    ? `Wrote to ${p}\n`
+    : `Wrote to ${p}\n\n${JSON.stringify(pkg, null, 2)}\n`;
+  return { stdout: out, stderr: "", exitCode: 0 };
+}
+
+async function npmInfo(
+  args: string[],
+  ctx: ShellContext,
+): Promise<ShellResult> {
+  const name = args[0];
+  if (!name)
+    return {
+      stdout: "",
+      stderr: formatErr("Usage: npm info <package>", "npm"),
+      exitCode: 1,
+    };
+
+  const pkgJsonPath = `/node_modules/${name}/package.json`;
+  if (_vol!.existsSync(pkgJsonPath)) {
+    try {
+      const pkg = JSON.parse(
+        _vol!.readFileSync(pkgJsonPath, "utf8"),
+      ) as PackageManifest;
+      let out = `${pkg.name}@${pkg.version}\n`;
+      if (pkg.description) out += `${pkg.description}\n`;
+      if (pkg.license) out += `license: ${pkg.license}\n`;
+      if (pkg.homepage) out += `homepage: ${pkg.homepage}\n`;
+      if (pkg.dependencies) {
+        out += "\ndependencies:\n";
+        for (const [k, v] of Object.entries(pkg.dependencies))
+          out += `  ${k}: ${v}\n`;
+      }
+      return { stdout: out, stderr: "", exitCode: 0 };
+    } catch {
+      /* fallthrough */
+    }
+  }
+
+  // fall back to registry
+  try {
+    const { RegistryClient } = await import("../packages/registry-client");
+    const client = new RegistryClient();
+    const meta = await client.fetchManifest(name);
+    const latest = meta["dist-tags"]?.latest;
+    let out = `${name}@${latest ?? "unknown"}\n`;
+    if (latest && meta.versions[latest]) {
+      const ver = meta.versions[latest] as unknown as Record<string, unknown>;
+      if (ver.description) out += `${ver.description}\n`;
+      if (ver.license) out += `license: ${ver.license}\n`;
+      if (ver.homepage) out += `homepage: ${ver.homepage}\n`;
+    }
+    return { stdout: out, stderr: "", exitCode: 0 };
+  } catch (e) {
+    return {
+      stdout: "",
+      stderr: formatErr(`Not found: ${name}`, "npm"),
+      exitCode: 1,
+    };
+  }
+}
+
+function npmPack(ctx: ShellContext): ShellResult {
+  const r = loadManifest(ctx.cwd);
+  if ("fail" in r) return r.fail;
+
+  const notice = `${A_DIM}npm notice${A_RESET}`;
+  let out = `${notice}\n`;
+  out += `${notice} ${A_BOLD}package:${A_RESET} ${r.pkg.name}@${r.pkg.version}\n`;
+
+  const files: string[] = [];
+  const walk = (dir: string) => {
+    try {
+      for (const name of _vol!.readdirSync(dir)) {
+        if (name === "node_modules" || name.startsWith(".")) continue;
+        const full = `${dir}/${name}`;
+        const st = _vol!.statSync(full);
+        if (st.isDirectory()) walk(full);
+        else files.push(full);
+      }
+    } catch {
+      /* */
+    }
+  };
+  walk(ctx.cwd);
+
+  for (const f of files) out += `${notice} ${f}\n`;
+  out += `${notice} ${A_BOLD}total files:${A_RESET} ${files.length}\n`;
+  return { stdout: out, stderr: "", exitCode: 0 };
+}
+
+function npmConfig(args: string[], ctx: ShellContext): ShellResult {
+  const sub = args[0];
+  if (!sub || sub === "list") {
+    let out = "; nodepod project config\n";
+    out += `prefix = "${ctx.cwd}"\n`;
+    out += `registry = "${NPM_REGISTRY_URL_SLASH}"\n`;
+    return { stdout: out, stderr: "", exitCode: 0 };
+  }
+  if (sub === "get") {
+    const key = args[1];
+    if (key === "prefix")
+      return { stdout: ctx.cwd + "\n", stderr: "", exitCode: 0 };
+    if (key === "registry")
+      return {
+        stdout: NPM_REGISTRY_URL_SLASH + "\n",
+        stderr: "",
+        exitCode: 0,
+      };
+    return { stdout: "undefined\n", stderr: "", exitCode: 0 };
+  }
+  if (sub === "set") {
+    return {
+      stdout: "",
+      stderr: formatWarn("config set: not supported in nodepod", "npm"),
+      exitCode: 0,
+    };
+  }
+  return {
+    stdout: "",
+    stderr: formatErr(`config: unknown subcommand "${sub}"`, "npm"),
+    exitCode: 1,
+  };
+}
+
+// Direct node binary execution (shared by node command & npx)
+
+export async function executeNodeBinary(
+  filePath: string,
+  args: string[],
+  ctx: ShellContext,
+  opts?: {
+    isFork?: boolean;
+    workerThreadsOverride?: {
+      isMainThread: boolean;
+      parentPort: unknown;
+      workerData: unknown;
+      threadId: number;
+    };
+  },
+): Promise<ShellResult> {
+  if (!_vol) return { stdout: "", stderr: "Volume unavailable\n", exitCode: 1 };
+
+  const rawPath = filePath.startsWith("/")
+    ? filePath
+    : `${ctx.cwd}/${filePath}`.replace(/\/+/g, "/");
+
+  // resolve entry file: exact path, then extensions, then directory index
+  let resolved = "";
+  if (_vol.existsSync(rawPath) && !_vol.statSync(rawPath).isDirectory()) {
+    resolved = rawPath;
+  } else {
+    const exts = [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"];
+    for (const ext of exts) {
+      if (_vol.existsSync(rawPath + ext)) { resolved = rawPath + ext; break; }
+    }
+    if (!resolved) {
+      // try as directory with index file
+      const dirPath = rawPath.endsWith("/") ? rawPath : rawPath + "/";
+      for (const idx of ["index.js", "index.mjs", "index.ts", "index.cjs"]) {
+        if (_vol.existsSync(dirPath + idx)) { resolved = dirPath + idx; break; }
+      }
+    }
+  }
+
+  if (!resolved) {
+    const errMsg = `Cannot locate module '${rawPath}'\n`;
+    const errSink = getStderrSink();
+    if (errSink) errSink(errMsg);
+    return {
+      stdout: "",
+      stderr: errMsg,
+      exitCode: 1,
+    };
+  }
+
+  let out = "";
+  let err = "";
+  let didExit = false;
+  let code = 0;
+
+  const pushOut = (s: string): boolean => {
+    out += s;
+    const sink = getStdoutSink();
+    if (sink) sink(s);
+    return true;
+  };
+  const pushErr = (s: string): boolean => {
+    err += s;
+    const sink = getStderrSink();
+    if (sink) sink(s);
+    return true;
+  };
+
+  // ScriptEngine's module wrapper overwrites globalThis.process -- save and restore
+  const savedProcess = (globalThis as any).process;
+
+  const sandbox = new ScriptEngine(_vol, {
+    cwd: ctx.cwd,
+    env: ctx.env,
+    onConsole: (m: string, cArgs: unknown[]) => {
+      // filter out process.exit sentinel errors logged by library code
+      if (cArgs.length === 1) {
+        const a = cArgs[0];
+        if (a instanceof Error && a.message.startsWith("Process exited with code")) return;
+        if (typeof a === "string" && a.startsWith("Error: Process exited with code")) return;
+      }
+      // error/warn → stderr, everything else → stdout
+      const line = utilFormat(cArgs[0], ...cArgs.slice(1)) + "\n";
+      m === "error" ? pushErr(line) : pushOut(line);
+    },
+    onStdout: pushOut,
+    onStderr: pushErr,
+    workerThreadsOverride: opts?.workerThreadsOverride,
+  });
+
+  const proc = sandbox.getProcess();
+
+  // sync shell cwd when process.chdir() is called (create-next-app etc. depend on this)
+  proc._chdirHook = (dir: string) => {
+    if (_shell) _shell.setCwd(dir);
+  };
+
+  proc.exit = ((c = 0) => {
+    // suppress exit when dev servers are active (SES/error handlers call exit(1) but we want to keep serving)
+    if (getAllServers().size > 0 && c !== 0) {
+      // process.exit suppressed — servers still active
+      return;
+    }
+    if (!didExit) {
+      didExit = true;
+      code = c;
+      proc.emit("exit", c);
+    }
+    // Always throw to halt execution — mirrors real Node.js process.exit()
+    // which terminates immediately. The TLA .catch() and try/catch both
+    // handle "Process exited with code" errors.
+    throw new Error(`Process exited with code ${c}`);
+  }) as (c?: number) => never;
+
+  proc.argv = ["node", resolved, ...args];
+
+  // wire IPC for forked children
+  if (_ipcSendFn) {
+    proc.send = ((msg: unknown, _cb?: (e: Error | null) => void): boolean => {
+      if (_ipcSendFn) {
+        _ipcSendFn(msg);
+        if (typeof _cb === "function") _cb(null);
+        return true;
+      }
+      return false;
+    }) as any;
+    proc.connected = true;
+    proc.disconnect = (() => {
+      proc.connected = false;
+    }) as () => void;
+
+    // incoming IPC from parent → emit on process (also replays queued messages)
+    setIPCReceiveHandler((data: unknown) => {
+      proc.emit("message", data);
+    });
+  }
+
+  const prevLiveStdin = _liveStdin;
+  // capture locally -- the module-level _haltSignal gets cleared by clearStreamingCallbacks()
+  // while this ENB's wait loop may still be running
+  const myHaltSignal = getHaltSignal();
+  if (myHaltSignal) {
+    proc.stdout.isTTY = true;
+    proc.stderr.isTTY = true;
+    proc.stdin.isTTY = true;
+    // sync terminal dimensions for TUI libraries
+    const cols = getTermCols();
+    const rows = getTermRows();
+    proc.stdout.columns = cols;
+    proc.stdout.rows = rows;
+    proc.stderr.columns = cols;
+    proc.stderr.rows = rows;
+    proc.stdin.setRawMode = (flag: boolean) => {
+      proc.stdin.isRaw = flag;
+      // notify terminal so it switches echo mode
+      if (_rawModeChangeCb) _rawModeChangeCb(flag);
+      return proc.stdin;
+    };
+    _liveStdin = proc.stdin;
+    // also update context's liveStdin
+    const ctx = getActiveContext();
+    if (ctx) ctx.liveStdin = proc.stdin;
+  }
+
+  // for forked children: ref() to simulate the IPC channel handle.
+  // real Node.js keeps the IPC channel ref'd until process.disconnect().
+  // we hold a ref for the entire fork lifetime, released on disconnect or exit.
+  const isFork = !!opts?.isFork;
+  if (isFork) {
+    ref();
+    // disconnect → unref (mirrors Node.js IPC channel.unref())
+    const origDisconnect = proc.disconnect;
+    proc.disconnect = (() => {
+      origDisconnect?.call(proc);
+      unref();
+    }) as () => void;
+  }
+
+  let scriptError: Error | null = null;
+  let tlaSettled = false;
+
+  try {
+    const tlaPromise = sandbox.runFileTLA(resolved);
+    tlaPromise
+      .catch((e) => {
+        if (
+          e instanceof Error &&
+          e.message.startsWith("Process exited with code")
+        ) {
+          return;
+        }
+        const msg = formatThrown(e);
+        pushErr(`Error: ${msg}\n`);
+        if (!didExit) {
+          didExit = true;
+          code = 1;
+        }
+      })
+      .finally(() => {
+        tlaSettled = true;
+      });
+  } catch (e) {
+    if (
+      e instanceof Error &&
+      e.message.startsWith("Process exited with code")
+    ) {
+      // process.exit() — handled by didExit flag
+    } else {
+      const msg = formatThrown(e);
+      scriptError = e instanceof Error ? e : new Error(msg);
+    }
+  }
+
+  const cleanup = () => {
+    if (savedProcess) (globalThis as any).process = savedProcess;
+  };
+
+  if (scriptError) {
+    cleanup();
+    const errMsg = scriptError.message || scriptError.name || "Unknown error";
+    const errStack = scriptError.stack || "";
+    const fullMsg =
+      errStack && !errStack.includes(errMsg)
+        ? `${errMsg}\n${errStack}`
+        : errStack || errMsg;
+    return { stdout: out, stderr: err + `Error: ${fullMsg}\n`, exitCode: 1 };
+  }
+
+  // process.exit() called synchronously -- bail
+  if (didExit) {
+    cleanup();
+    return { stdout: out, stderr: err, exitCode: code };
+  }
+
+  // yield one tick so microtasks settle
+  await new Promise((r) => setTimeout(r, 0));
+
+  // keep the process alive while TLA hasn't settled, ref handles exist,
+  // or HTTP servers are registered. process.exit() and Ctrl+C break immediately.
+
+  const shouldStayAlive = (): boolean => {
+    if (!tlaSettled) return true;
+    if (getRefCount() > 0) return true;
+    if (getAllServers().size > 0) return true;
+    return false;
+  };
+
+  // fast path: nothing keeping the process alive
+  if (!myHaltSignal && !shouldStayAlive()) {
+    cleanup();
+    return { stdout: out, stderr: err, exitCode: 0 };
+  }
+
+  // avoid duplicate output when same error fires as both 'error' and 'unhandledrejection'
+  const handledErrors = new WeakSet<object>();
+
+  const rejHandler = (ev: PromiseRejectionEvent) => {
+    ev.preventDefault();
+    const r = ev.reason;
+    if (
+      r instanceof Error &&
+      r.message.startsWith("Process exited with code")
+    ) {
+      return;
+    }
+    // mark as handled to prevent errHandler double-logging
+    if (r != null && typeof r === "object") handledErrors.add(r);
+    // emit 'unhandledRejection' on process -- if a handler exists, it handles it
+    try {
+      const hasHandler = proc.listenerCount
+        ? proc.listenerCount("unhandledRejection") > 0
+        : false;
+      proc.emit("unhandledRejection", r, ev.promise);
+      if (hasHandler) return; // Handler dealt with it — don't log
+    } catch { /* ignore handler errors */ }
+    const rejMsg = r instanceof Error
+      ? `Unhandled rejection: ${r.message}\n${r.stack ?? ""}\n`
+      : `Unhandled rejection: ${String(r)}\n`;
+    pushErr(rejMsg);
+  };
+  const errHandler = (ev: ErrorEvent) => {
+    ev.preventDefault();
+    const e = ev.error ?? new Error(ev.message || "Unknown error");
+    // skip if already handled by rejHandler (same error fires on both global events)
+    if (e != null && typeof e === "object" && handledErrors.has(e)) return;
+    if (e != null && typeof e === "object") handledErrors.add(e);
+    // emit 'uncaughtException' -- frameworks like webpack register handlers for graceful recovery
+    try {
+      const hasUncaught = proc.listenerCount
+        ? proc.listenerCount("uncaughtException") > 0
+        : false;
+      proc.emit("uncaughtException", e);
+      if (hasUncaught) return; // Handler dealt with it — don't log or crash
+    } catch { /* handler threw — fall through to default logging */ }
+    // if there's an unhandledRejection listener, it'll handle this -- don't double-log
+    try {
+      const hasRej = proc.listenerCount
+        ? proc.listenerCount("unhandledRejection") > 0
+        : false;
+      if (hasRej) return;
+    } catch { /* ignore */ }
+    const msg = e instanceof Error
+      ? `${e.stack || e.message}\n`
+      : `Uncaught: ${String(e)}\n`;
+    pushErr(msg);
+  };
+  globalThis.addEventListener("unhandledrejection", rejHandler);
+  globalThis.addEventListener("error", errHandler);
+
+  try {
+    // resolves when Ctrl+C / signal fires
+    const haltPromise = myHaltSignal
+      ? new Promise<void>((r) => {
+          if (myHaltSignal!.aborted) { r(); return; }
+          myHaltSignal!.addEventListener("abort", () => r(), { once: true });
+        })
+      : null;
+
+    // give async startup code time to register handles before deciding the process is done
+    let consecutiveEmpty = 0;
+    let everNonEmpty = false;
+
+    while (!didExit) {
+      if (myHaltSignal?.aborted) {
+        break;
+      }
+
+      // wake on drain notification or periodic tick
+      let wakeResolve!: () => void;
+      const wakePromise = new Promise<void>((r) => { wakeResolve = r; });
+      const removeDrain = addDrainListener(wakeResolve);
+
+      const tickMs = (!everNonEmpty && myHaltSignal && !out && !err)
+        ? TIMEOUTS.WAIT_LOOP_TICK
+        : 50;
+      const racers: Promise<unknown>[] = [
+        wakePromise,
+        new Promise<void>((r) => setTimeout(r, tickMs)),
+      ];
+      if (haltPromise) racers.push(haltPromise);
+
+      await Promise.race(racers);
+      removeDrain();
+
+      if (myHaltSignal?.aborted) {
+        break;
+      }
+      if (didExit) {
+        break;
+      }
+
+      if (!shouldStayAlive()) {
+        // yield one microtask turn for async transitions (e.g. @clack closing/reopening readline)
+        await new Promise<void>((r) => queueMicrotask(r));
+        if (didExit || myHaltSignal?.aborted) break;
+        if (shouldStayAlive()) {
+          everNonEmpty = true;
+          consecutiveEmpty = 0;
+          continue;
+        }
+
+        consecutiveEmpty++;
+
+        if (myHaltSignal) {
+          // terminal mode: tiered timeout -- no output yet (10s), had refs before (5s), output but no refs (2s)
+          if (!everNonEmpty && !out && !err) {
+            if (consecutiveEmpty >= 50) {
+              break;
+            }
+          } else if (!everNonEmpty) {
+            if (consecutiveEmpty >= Math.ceil(2_000 / tickMs)) {
+              break;
+            }
+          } else {
+            if (consecutiveEmpty >= 100) {
+              break;
+            }
+          }
+        } else {
+          break; // Non-terminal: exit immediately when empty.
+        }
+      } else {
+        consecutiveEmpty = 0;
+        everNonEmpty = true;
+      }
+    }
+
+    return { stdout: out, stderr: err, exitCode: didExit ? code : 0 };
+  } finally {
+    cleanup();
+    // defuse proc.exit so floating Promises don't throw unhandled rejections
+    proc.exit = (() => {}) as unknown as (c?: number) => never;
+    globalThis.removeEventListener("unhandledrejection", rejHandler);
+    globalThis.removeEventListener("error", errHandler);
+    // restore _liveStdin for the parent's stdin relay
+    _liveStdin = prevLiveStdin;
+    const ctxRestore = getActiveContext();
+    if (ctxRestore) ctxRestore.liveStdin = prevLiveStdin;
+    // full reset
+    closeAllServers();
+    resetRefCount();
+    resetActiveInterfaceCount();
+  }
+}
+
+async function npxExecute(
+  params: string[],
+  ctx: ShellContext,
+): Promise<ShellResult> {
+  if (!_vol) return { stdout: "", stderr: "Volume unavailable\n", exitCode: 1 };
+
+  // parse npx flags
+  let autoInstall = true;
+  let installPkg: string | null = null;
+  const filteredParams: string[] = [];
+  let separatorSeen = false;
+
+  for (let i = 0; i < params.length; i++) {
+    if (separatorSeen) {
+      filteredParams.push(params[i]);
+      continue;
+    }
+    if (params[i] === "--") {
+      separatorSeen = true;
+      continue;
+    }
+    if (params[i] === "-y" || params[i] === "--yes") {
+      autoInstall = true;
+      continue;
+    }
+    if (params[i] === "-n" || params[i] === "--no") {
+      autoInstall = false;
+      continue;
+    }
+    if (
+      (params[i] === "-p" || params[i] === "--package") &&
+      i + 1 < params.length
+    ) {
+      installPkg = params[++i];
+      continue;
+    }
+    if (params[i] === "--help" || params[i] === "-h") {
+      return {
+        stdout:
+          `${A_BOLD}Usage:${A_RESET} npx [options] <command> [args...]\n\n` +
+          `${A_BOLD}Options:${A_RESET}\n` +
+          `  ${A_CYAN}-y${A_RESET}, ${A_CYAN}--yes${A_RESET}       Auto-confirm install\n` +
+          `  ${A_CYAN}-n${A_RESET}, ${A_CYAN}--no${A_RESET}        Don't install if not found\n` +
+          `  ${A_CYAN}-p${A_RESET}, ${A_CYAN}--package${A_RESET}   Specify package to install\n` +
+          `  ${A_CYAN}--${A_RESET}              Separator for command args\n`,
+        stderr: "",
+        exitCode: 0,
+      };
+    }
+    filteredParams.push(params[i]);
+  }
+
+  let pkgSpec = filteredParams[0];
+  if (!pkgSpec) {
+    return {
+      stdout: "",
+      stderr: formatErr("missing command", "npm"),
+      exitCode: 1,
+    };
+  }
+
+  let cmdName: string;
+  let version: string | undefined;
+  if (pkgSpec.startsWith("@")) {
+    // scoped: @scope/name or @scope/name@version
+    const rest = pkgSpec.slice(1);
+    const atIdx = rest.indexOf("@");
+    if (atIdx > 0 && rest.indexOf("/") < atIdx) {
+      cmdName = "@" + rest.slice(0, atIdx);
+      version = rest.slice(atIdx + 1);
+    } else {
+      cmdName = pkgSpec;
+    }
+  } else {
+    const atIdx = pkgSpec.indexOf("@");
+    if (atIdx > 0) {
+      cmdName = pkgSpec.slice(0, atIdx);
+      version = pkgSpec.slice(atIdx + 1);
+    } else {
+      cmdName = pkgSpec;
+    }
+  }
+
+  // -p overrides the package to install
+  const actualPkg = installPkg || pkgSpec;
+  const actualPkgName = installPkg
+    ? installPkg.replace(/@[^@/]+$/, "").replace(/^@/, "")
+    : cmdName;
+
+  let resolvedBin = findBinary(cmdName, _vol, ctx.cwd);
+
+  // not found locally -- try installing
+  if (!resolvedBin && autoInstall) {
+    const installResult = await installPackages([actualPkg], ctx);
+    if (installResult.exitCode !== 0) return installResult;
+    resolvedBin = findBinary(cmdName, _vol, ctx.cwd);
+  }
+
+  if (!resolvedBin) {
+    return {
+      stdout: "",
+      stderr: `npx: command '${cmdName}' not found\n`,
+      exitCode: 1,
+    };
+  }
+
+  // run directly via node handler to avoid shell re-parsing mangling arguments
+  return executeNodeBinary(resolvedBin, filteredParams.slice(1), ctx);
+}
+
+function findBinary(
+  name: string,
+  vol: MemoryVolume,
+  cwd?: string,
+): string | null {
+  const cleanName = name.startsWith("@") ? name : name;
+  const shortName = cleanName.includes("/")
+    ? cleanName.split("/").pop()!
+    : cleanName;
+
+  // cwd-local first, then root fallback
+  const searchRoots =
+    cwd && cwd !== "/"
+      ? [`${cwd}/node_modules`, `/node_modules`]
+      : [`/node_modules`];
+
+  for (const nmDir of searchRoots) {
+    // check package.json bin field for the real JS entry point
+    const pkgJsonPath = `${nmDir}/${cleanName}/package.json`;
+    if (vol.existsSync(pkgJsonPath)) {
+      try {
+        const pkg = JSON.parse(
+          vol.readFileSync(pkgJsonPath, "utf8") as string,
+        ) as PackageManifest;
+        if (pkg.bin) {
+          if (typeof pkg.bin === "string") {
+            return `${nmDir}/${cleanName}/${pkg.bin}`;
+          }
+          if (typeof pkg.bin === "object") {
+            const binMap = pkg.bin as Record<string, string>;
+            const binEntry =
+              binMap[shortName] ||
+              binMap[cleanName] ||
+              Object.values(binMap)[0];
+            if (binEntry) return `${nmDir}/${cleanName}/${binEntry}`;
+          }
+        }
+        // fallback to main
+        if (pkg.main) return `${nmDir}/${cleanName}/${pkg.main}`;
+      } catch {
+        /* ignore */
+      }
+    }
+
+    // .bin stubs -- resolve through to the actual JS target they reference
+    const binPath = `${nmDir}/.bin/${name}`;
+    if (vol.existsSync(binPath)) {
+      try {
+        const stub = vol.readFileSync(binPath, "utf8");
+        // stubs look like: node "/node_modules/pkg/index.js" "$@"
+        const match = stub.match(/node\s+"([^"]+)"/);
+        if (match && vol.existsSync(match[1])) return match[1];
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  return null;
+}
+
+export interface RunOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  encoding?: BufferEncoding | "buffer";
+  timeout?: number;
+  maxBuffer?: number;
+  shell?: string | boolean;
+}
+
+export type RunCallback = (
+  err: Error | null,
+  stdout: string | Buffer,
+  stderr: string | Buffer,
+) => void;
+
+export interface SpawnConfig {
+  cwd?: string;
+  env?: Record<string, string>;
+  shell?: boolean | string;
+  stdio?: "pipe" | "inherit" | "ignore" | Array<"pipe" | "inherit" | "ignore">;
+}
+
+export function exec(
+  command: string,
+  optsOrCb?: RunOptions | RunCallback,
+  cb?: RunCallback,
+): ShellProcess {
+  let options: RunOptions = {};
+  let done: RunCallback | undefined;
+  if (typeof optsOrCb === "function") {
+    done = optsOrCb;
+  } else if (optsOrCb) {
+    options = optsOrCb;
+    done = cb;
+  }
+
+  const child = new ShellProcess();
+
+  if (!_shell) {
+    const e = new Error("[Nodepod] exec requires shell. Call initShellExec() first.");
+    setTimeout(() => {
+      child.emit("error", e);
+      if (done) done(e, "", "");
+    }, 0);
+    return child;
+  }
+
+  const cwd = options.cwd ?? getShellCwd();
+  const env = (options.env as Record<string, string>) ?? undefined;
+
+  // run inline via NodepodShell -- only fork() gets a dedicated worker
+  _shell.exec(command, { cwd, env }).then(
+    (result) => {
+      const { stdout, stderr, exitCode } = result;
+      if (stdout) child.stdout?.push(Buffer.from(stdout));
+      if (stderr) child.stderr?.push(Buffer.from(stderr));
+      child.stdout?.push(null);
+      child.stderr?.push(null);
+      child.exitCode = exitCode;
+      child.emit("close", exitCode, null);
+      child.emit("exit", exitCode, null);
+      if (done) {
+        if (exitCode !== 0) {
+          const e = new Error(`Command failed: ${command}`);
+          (e as any).code = exitCode;
+          done(e, stdout ?? "", stderr ?? "");
+        } else {
+          done(null, stdout ?? "", stderr ?? "");
+        }
+      }
+    },
+    (e) => {
+      child.emit("error", e instanceof Error ? e : new Error(String(e)));
+      if (done) done(e instanceof Error ? e : new Error(String(e)), "", "");
+    },
+  );
+
+  return child;
+}
+
+export function execSync(cmd: string, opts?: RunOptions): string | Buffer {
+  const trimmed = cmd.trim();
+  const encoding = opts?.encoding;
+
+  // fast path: trivially synchronous commands (version checks, echo, pwd)
+  const result = handleSyncCommand(trimmed, opts);
+  if (result !== null) {
+    if (encoding === "buffer") return Buffer.from(result);
+    return result;
+  }
+
+  // true blocking path via Atomics.wait()
+  if (!_syncChannel) {
+    throw new Error(
+      "[Nodepod] execSync requires SyncChannel (worker mode with SharedArrayBuffer). " +
+      "Ensure Nodepod is running in worker mode with COOP/COEP headers.",
+    );
+  }
+
+  const slot = _syncChannel.allocateSlot();
+  const cwd = opts?.cwd ?? (globalThis as any).process?.cwd?.() ?? "/";
+  const env = (opts?.env as Record<string, string>) ?? {};
+
+  (self as any).postMessage({
+    type: "spawn-sync",
+    requestId: _nextSyncRequestId++,
+    command: trimmed.split(/\s+/)[0],
+    args: trimmed.split(/\s+/).slice(1),
+    cwd,
+    env,
+    syncSlot: slot,
+    shellCommand: trimmed,
+  });
+
+  // blocks until main thread spawns child and child completes
+  const { exitCode, stdout } = _syncChannel.waitForResult(slot, 120_000);
+
+  if (exitCode !== 0) {
+    const err: any = new Error(`Command failed: ${trimmed}\n${stdout}`);
+    err.status = exitCode;
+    err.stderr = Buffer.from("");
+    err.stdout = Buffer.from(stdout);
+    err.output = [null, err.stdout, err.stderr];
+    throw err;
+  }
+
+  if (encoding === "buffer") return Buffer.from(stdout);
+  return stdout;
+}
+
+let _nextSyncRequestId = 1;
+
+const KNOWN_BINS: Record<string, string> = {
+  node: "/usr/local/bin/node",
+  npm: "/usr/local/bin/npm",
+  npx: "/usr/local/bin/npx",
+  pnpm: "/usr/local/bin/pnpm",
+  yarn: "/usr/local/bin/yarn",
+  bun: "/usr/local/bin/bun",
+  bunx: "/usr/local/bin/bunx",
+  git: "/usr/bin/git",
+};
+
+function isBinaryAvailable(name: string): string | null {
+  if (KNOWN_BINS[name]) return KNOWN_BINS[name];
+  if (_vol) {
+    const binPath = `/node_modules/.bin/${name}`;
+    if (_vol.existsSync(binPath)) return binPath;
+  }
+  return null;
+}
+
+// throw an error matching real Node.js execSync behaviour for failed commands
+function throwCommandNotFound(cmd: string): never {
+  const err: any = new Error(
+    `Command failed: ${cmd}\n/bin/sh: 1: ${cmd.split(/\s+/)[0]}: not found\n`,
+  );
+  err.status = 127;
+  err.stderr = Buffer.from(`/bin/sh: 1: ${cmd.split(/\s+/)[0]}: not found\n`);
+  err.stdout = Buffer.from("");
+  throw err;
+}
+
+function _findGitDir(cwd: string): { gitDir: string; workDir: string } | null {
+  if (!_vol) return null;
+  let dir = cwd;
+  while (true) {
+    const gitPath = dir + "/.git";
+    try { if (_vol.existsSync(gitPath)) return { gitDir: gitPath, workDir: dir }; } catch { /* */ }
+    const parent = dir.substring(0, dir.lastIndexOf("/")) || "/";
+    if (parent === dir) break;
+    dir = parent;
+  }
+  try { if (_vol.existsSync("/.git")) return { gitDir: "/.git", workDir: "/" }; } catch { /* */ }
+  return null;
+}
+
+function _readHeadBranch(gitDir: string): string {
+  try {
+    const head = (_vol!.readFileSync(gitDir + "/HEAD", "utf8" as any) as string).trim();
+    if (head.startsWith("ref: refs/heads/")) return head.slice(16);
+    return head.slice(0, 7);
+  } catch { return "main"; }
+}
+
+function _resolveHeadHash(gitDir: string): string | null {
+  try {
+    const head = (_vol!.readFileSync(gitDir + "/HEAD", "utf8" as any) as string).trim();
+    if (head.startsWith("ref: ")) {
+      const refPath = gitDir + "/" + head.slice(5);
+      return (_vol!.readFileSync(refPath, "utf8" as any) as string).trim();
+    }
+    return head;
+  } catch { return null; }
+}
+
+function _readGitConfigKey(gitDir: string, key: string): string | null {
+  try {
+    const config = _vol!.readFileSync(gitDir + "/config", "utf8" as any) as string;
+    const parts = key.split(".");
+    let sectionName: string, subSection: string | null = null, propName: string;
+    if (parts.length === 3) { sectionName = parts[0]; subSection = parts[1]; propName = parts[2]; }
+    else if (parts.length === 2) { sectionName = parts[0]; propName = parts[1]; }
+    else return null;
+    const lines = config.split("\n");
+    let inSection = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("[")) {
+        inSection = subSection
+          ? trimmed === `[${sectionName} "${subSection}"]`
+          : trimmed === `[${sectionName}]`;
+        continue;
+      }
+      if (inSection) {
+        const m = trimmed.match(/^(\w+)\s*=\s*(.*)$/);
+        if (m && m[1] === propName) return m[2].trim();
+      }
+    }
+  } catch { /* */ }
+  return null;
+}
+
+function handleSyncCommand(cmd: string, opts?: RunOptions): string | null {
+  if (/^node\s+(--version|-v)\s*$/.test(cmd)) return VERSIONS.NODE + "\n";
+  if (/^npm\s+(--version|-v)\s*$/.test(cmd)) return VERSIONS.NPM + "\n";
+  if (/^pnpm\s+(--version|-v)\s*$/.test(cmd)) return VERSIONS.PNPM + "\n";
+  if (/^yarn\s+(--version|-v)\s*$/.test(cmd)) return VERSIONS.YARN + "\n";
+  if (/^bun\s+(--version|-v)\s*$/.test(cmd)) return VERSIONS.BUN + "\n";
+
+  // which / command -v
+  const whichMatch = cmd.match(/^(?:which|command\s+-v)\s+(\S+)\s*$/);
+  if (whichMatch) {
+    const binName = whichMatch[1];
+    const binPath = isBinaryAvailable(binName);
+    if (binPath) return binPath + "\n";
+    throwCommandNotFound(cmd);
+  }
+
+  // <binary> --version / -v
+  const versionMatch = cmd.match(/^(\S+)\s+(--version|-v)\s*$/);
+  if (versionMatch) {
+    const binName = versionMatch[1];
+    if (
+      binName === "node" ||
+      binName === "npm" ||
+      binName === "pnpm" ||
+      binName === "yarn" ||
+      binName === "bun"
+    )
+      return null; // handled above
+    if (!isBinaryAvailable(binName)) throwCommandNotFound(cmd);
+    // known binary but no version handler -- fall through to async
+  }
+
+  // registry queries (Next.js uses this to find npm registry)
+  if (/^(?:npm|yarn|pnpm)\s+config\s+get\s+registry\s*$/.test(cmd)) {
+    return NPM_REGISTRY_URL_SLASH.replace(/\/$/, "") + "\n";
+  }
+
+  const echoMatch = cmd.match(/^echo\s+["']?(.*?)["']?\s*$/);
+  if (echoMatch) return echoMatch[1] + "\n";
+  if (/^uname\s+-s\s*$/.test(cmd)) return "Linux\n";
+  if (/^uname\s+-m\s*$/.test(cmd)) return "x86_64\n";
+  if (/^uname\s+-a\s*$/.test(cmd))
+    return "Linux nodepod 5.10.0 #1 SMP x86_64 GNU/Linux\n";
+  // git fast-path for sync commands
+  if (/^git\s+(--version|-v)\s*$/.test(cmd) || cmd === "git --version") {
+    return "git version " + VERSIONS.GIT + "\n";
+  }
+  if (_vol) {
+    const gitRevParseMatch = cmd.match(/^git\s+rev-parse\s+(.+)$/);
+    if (gitRevParseMatch) {
+      const gitArgs = gitRevParseMatch[1].trim();
+      const cwd = opts?.cwd || "/";
+      const gd = _findGitDir(cwd);
+      if (gitArgs === "--show-toplevel") return gd ? gd.workDir + "\n" : "";
+      if (gitArgs === "--is-inside-work-tree") return gd ? "true\n" : "false\n";
+      if (gitArgs === "--git-dir") return gd ? ".git\n" : "";
+      if (gitArgs === "--is-bare-repository") return "false\n";
+      if (gitArgs === "--abbrev-ref HEAD" && gd) return _readHeadBranch(gd.gitDir) + "\n";
+      if ((gitArgs === "HEAD" || gitArgs === "--verify HEAD") && gd) {
+        const h = _resolveHeadHash(gd.gitDir);
+        return h ? h + "\n" : "";
+      }
+      if (gitArgs === "--short HEAD" && gd) {
+        const h = _resolveHeadHash(gd.gitDir);
+        return h ? h.slice(0, 7) + "\n" : "";
+      }
+    }
+    if (/^git\s+branch\s+--show-current\s*$/.test(cmd)) {
+      const cwd = opts?.cwd || "/";
+      const gd = _findGitDir(cwd);
+      if (gd) return _readHeadBranch(gd.gitDir) + "\n";
+    }
+    const gitConfigGetMatch = cmd.match(/^git\s+config\s+(?:--get\s+)?(\S+)\s*$/);
+    if (gitConfigGetMatch) {
+      const cwd = opts?.cwd || "/";
+      const gd = _findGitDir(cwd);
+      if (gd) {
+        const val = _readGitConfigKey(gd.gitDir, gitConfigGetMatch[1]);
+        return val !== null ? val + "\n" : "";
+      }
+      return "";
+    }
+  }
+  // catch-all for git
+  if (/^git\s/.test(cmd)) return "";
+  if (cmd === "true" || cmd === ":") return "";
+  if (cmd === "pwd") return (opts?.cwd || "/") + "\n";
+  if (cmd.startsWith("cat ") && _vol) {
+    const path = cmd.slice(4).trim().replace(/['"]/g, "");
+    try {
+      return _vol.readFileSync(path, "utf8" as any);
+    } catch {
+      return "";
+    }
+  }
+  if ((cmd === "ls" || cmd.startsWith("ls ")) && _vol) {
+    const dir =
+      cmd === "ls"
+        ? opts?.cwd || "/"
+        : cmd.slice(3).trim().replace(/['"]/g, "");
+    try {
+      return _vol.readdirSync(dir).join("\n") + "\n";
+    } catch {
+      return "";
+    }
+  }
+  const testMatch = cmd.match(
+    /^(?:test|\[)\s+(-[fd])\s+["']?(.*?)["']?\s*\]?\s*$/,
+  );
+  if (testMatch && _vol) {
+    const flag = testMatch[1];
+    const path = testMatch[2];
+    try {
+      const st = _vol.statSync(path);
+      if (flag === "-f" && st.isFile()) return "";
+      if (flag === "-d" && st.isDirectory()) return "";
+    } catch {
+      /* */
+    }
+    return "";
+  }
+  return null;
+}
+
+export function spawn(
+  command: string,
+  argsOrOpts?: string[] | SpawnConfig,
+  opts?: SpawnConfig,
+): ShellProcess {
+  let spawnArgs: string[] = [];
+  let cfg: SpawnConfig = {};
+  if (Array.isArray(argsOrOpts)) {
+    spawnArgs = argsOrOpts;
+    cfg = opts ?? {};
+  } else if (argsOrOpts) cfg = argsOrOpts;
+
+  const child = new ShellProcess();
+
+  // spawn() gets a dedicated worker (streaming output, long-lived processes).
+  // exec() runs inline since it collects all output at the end.
+  if (_spawnChildFn) {
+    const cwd = cfg.cwd ?? getShellCwd();
+    const env = (cfg.env as Record<string, string>) ?? {};
+    const fullCmd = spawnArgs.length ? `${command} ${spawnArgs.join(" ")}` : command;
+
+    // keep parent alive while child is running
+    ref();
+
+    _spawnChildFn(command, spawnArgs, {
+      cwd,
+      env,
+      stdio: "pipe",
+      onStdout: (data: string) => {
+        child.stdout?.push(Buffer.from(data));
+        // also route through parent's stdout sink for terminal output
+        const sink = getStdoutSink();
+        if (sink) sink(data);
+      },
+      onStderr: (data: string) => {
+        child.stderr?.push(Buffer.from(data));
+        const sink = getStderrSink();
+        if (sink) sink(data);
+      },
+    }).then(({ exitCode }) => {
+      unref(); // Child done — release event loop hold
+      child.stdout?.push(null);
+      child.stderr?.push(null);
+      child.exitCode = exitCode;
+      child.emit("close", exitCode, null);
+      child.emit("exit", exitCode, null);
+    }).catch((e) => {
+      unref(); // Child done — release event loop hold
+      child.emit("error", e instanceof Error ? e : new Error(String(e)));
+    });
+  } else if (_shell) {
+    // fallback: inline execution (no streaming)
+    const cwd = cfg.cwd ?? getShellCwd();
+    const env = (cfg.env as Record<string, string>) ?? undefined;
+    const fullCmd = spawnArgs.length
+      ? `${command} ${spawnArgs.map((a) => a.includes(" ") ? `"${a}"` : a).join(" ")}`
+      : command;
+
+    _shell.exec(fullCmd, { cwd, env }).then(
+      (result) => {
+        const { stdout, stderr, exitCode } = result;
+        if (stdout) child.stdout?.push(Buffer.from(stdout));
+        if (stderr) child.stderr?.push(Buffer.from(stderr));
+        child.stdout?.push(null);
+        child.stderr?.push(null);
+        child.exitCode = exitCode;
+        child.emit("close", exitCode, null);
+        child.emit("exit", exitCode, null);
+      },
+      (e) => {
+        child.emit("error", e instanceof Error ? e : new Error(String(e)));
+      },
+    );
+  } else {
+    setTimeout(() => {
+      child.emit("error", new Error("[Nodepod] spawn requires shell or worker mode."));
+    }, 0);
+  }
+
+  return child;
+}
+
+export function spawnSync(
+  cmd: string,
+  args?: string[] | SpawnConfig,
+  opts?: SpawnConfig,
+): {
+  stdout: Buffer;
+  stderr: Buffer;
+  status: number;
+  signal: null;
+  pid: number;
+  output: [null, Buffer, Buffer];
+  error?: Error;
+} {
+  let spawnArgs: string[] = [];
+  let cfg: SpawnConfig = {};
+  if (Array.isArray(args)) {
+    spawnArgs = args;
+    cfg = opts ?? {};
+  } else if (args) {
+    cfg = args;
+  }
+
+  const full = spawnArgs.length ? `${cmd} ${spawnArgs.join(" ")}` : cmd;
+  const syncResult = handleSyncCommand(full, { cwd: cfg.cwd, env: cfg.env });
+
+  if (syncResult !== null) {
+    const stdout = Buffer.from(syncResult);
+    const stderr = Buffer.from("");
+    return {
+      stdout,
+      stderr,
+      status: 0,
+      signal: null,
+      pid: MOCK_PID.BASE + Math.floor(Math.random() * MOCK_PID.RANGE),
+      output: [null, stdout, stderr],
+    };
+  }
+
+  // true blocking path via Atomics.wait()
+  if (!_syncChannel) {
+    throw new Error(
+      "[Nodepod] spawnSync requires SyncChannel (worker mode with SharedArrayBuffer). " +
+      "Ensure Nodepod is running in worker mode with COOP/COEP headers.",
+    );
+  }
+
+  const slot = _syncChannel.allocateSlot();
+  const cwd = cfg.cwd ?? (globalThis as any).process?.cwd?.() ?? "/";
+  const env = (cfg.env as Record<string, string>) ?? {};
+
+  (self as any).postMessage({
+    type: "spawn-sync",
+    requestId: _nextSyncRequestId++,
+    command: full.split(/\s+/)[0],
+    args: full.split(/\s+/).slice(1),
+    cwd,
+    env,
+    syncSlot: slot,
+    shellCommand: full,
+  });
+
+  // blocks until main thread spawns child and child completes
+  try {
+    const { exitCode, stdout: stdoutStr } = _syncChannel.waitForResult(slot, 120_000);
+    const stdout = Buffer.from(stdoutStr);
+    const stderr = Buffer.from("");
+    return {
+      stdout,
+      stderr,
+      status: exitCode,
+      signal: null,
+      pid: MOCK_PID.BASE + Math.floor(Math.random() * MOCK_PID.RANGE),
+      output: [null, stdout, stderr],
+    };
+  } catch (e: any) {
+    const stdout = Buffer.from(e?.stdout ?? "");
+    const stderr = Buffer.from(e?.message ?? "");
+    return {
+      stdout,
+      stderr,
+      status: e?.status ?? 1,
+      signal: null,
+      pid: MOCK_PID.BASE + Math.floor(Math.random() * MOCK_PID.RANGE),
+      output: [null, stdout, stderr],
+      error: e instanceof Error ? e : new Error(String(e)),
+    };
+  }
+}
+
+export function execFileSync(
+  file: string,
+  args?: string[],
+  opts?: RunOptions,
+): string | Buffer {
+  const cmd = args?.length ? `${file} ${args.join(" ")}` : file;
+  return execSync(cmd, opts);
+}
+
+export function execFile(
+  file: string,
+  argsOrOpts?: string[] | RunOptions | RunCallback,
+  optsOrCb?: RunOptions | RunCallback,
+  cb?: RunCallback,
+): ShellProcess {
+  let fileArgs: string[] = [];
+  let options: RunOptions = {};
+  let done: RunCallback | undefined;
+
+  if (Array.isArray(argsOrOpts)) {
+    fileArgs = argsOrOpts;
+    if (typeof optsOrCb === "function") done = optsOrCb;
+    else if (optsOrCb) {
+      options = optsOrCb;
+      done = cb;
+    }
+  } else if (typeof argsOrOpts === "function") {
+    done = argsOrOpts;
+  } else if (argsOrOpts) {
+    options = argsOrOpts;
+    done = optsOrCb as RunCallback;
+  }
+
+  const cmd = fileArgs.length ? `${file} ${fileArgs.join(" ")}` : file;
+  return exec(cmd, options, done);
+}
+
+export function fork(
+  modulePath: string,
+  argsOrOpts?: string[] | Record<string, unknown>,
+  opts?: Record<string, unknown>,
+): ShellProcess {
+  let args: string[] = [];
+  let cfg: Record<string, unknown> = {};
+  if (Array.isArray(argsOrOpts)) {
+    args = argsOrOpts;
+    cfg = opts ?? {};
+  } else if (argsOrOpts) cfg = argsOrOpts;
+
+  const cwd = (cfg.cwd as string) || getShellCwd();
+  const env = (cfg.env as Record<string, string>) ||
+    (_shell?.getEnv() ?? {});
+
+  const resolved = modulePath.startsWith("/")
+    ? modulePath
+    : `${cwd}/${modulePath}`.replace(/\/+/g, "/");
+
+  const child = new ShellProcess();
+  child.connected = true;
+  child.spawnargs = ["node", resolved, ...args];
+  child.spawnfile = "node";
+
+  if (!_forkChildFn) {
+    setTimeout(() => {
+      child.emit("error", new Error("[Nodepod] fork requires worker mode. No forkChild callback set."));
+    }, 0);
+    return child;
+  }
+
+  // keep parent alive while forked child is running
+  ref();
+  const handle = _forkChildFn(resolved, args, {
+    cwd,
+    env,
+    onStdout: (data: string) => {
+      child.stdout?.emit("data", data);
+      // also route through parent's stdout sink (fork inherits stdio by default)
+      const sink = getStdoutSink();
+      if (sink) sink(data);
+    },
+    onStderr: (data: string) => {
+      child.stderr?.emit("data", data);
+      const sink = getStderrSink();
+      if (sink) sink(data);
+    },
+    onIPC: (data: unknown) => {
+      child.emit("message", data);
+    },
+    onExit: (exitCode: number) => {
+      unref(); // Child done — release event loop hold
+      child.exitCode = exitCode;
+      child.connected = false;
+      child.emit("exit", exitCode, null);
+      child.emit("close", exitCode, null);
+    },
+  });
+
+  // parent→child IPC
+  child.send = (msg: unknown, _cb?: (e: Error | null) => void): boolean => {
+    if (!child.connected) return false;
+    handle.sendIPC(msg);
+    return true;
+  };
+
+  child.kill = (sig?: string): boolean => {
+    child.killed = true;
+    child.connected = false;
+    handle.disconnect();
+    child.emit("exit", null, sig ?? "SIGTERM");
+    child.emit("close", null, sig ?? "SIGTERM");
+    return true;
+  };
+
+  child.disconnect = (): void => {
+    child.connected = false;
+    handle.disconnect();
+    child.emit("disconnect");
+  };
+
+  return child;
+}
+
+export interface ShellProcess extends EventEmitter {
+  pid: number;
+  connected: boolean;
+  killed: boolean;
+  exitCode: number | null;
+  signalCode: string | null;
+  spawnargs: string[];
+  spawnfile: string;
+  stdin: Writable | null;
+  stdout: Readable | null;
+  stderr: Readable | null;
+  kill(sig?: string): boolean;
+  disconnect(): void;
+  send(msg: unknown, cb?: (e: Error | null) => void): boolean;
+  ref(): this;
+  unref(): this;
+}
+
+interface ShellProcessConstructor {
+  new (): ShellProcess;
+  (this: any): void;
+  prototype: any;
+}
+
+export const ShellProcess = function ShellProcess(this: any) {
+  if (!this) return;
+  EventEmitter.call(this);
+  this.pid = MOCK_PID.BASE + Math.floor(Math.random() * MOCK_PID.RANGE);
+  this.connected = false;
+  this.killed = false;
+  this.exitCode = null;
+  this.signalCode = null;
+  this.spawnargs = [];
+  this.spawnfile = "";
+  this.stdin = new Writable();
+  this.stdout = new Readable();
+  this.stderr = new Readable();
+} as unknown as ShellProcessConstructor;
+
+Object.setPrototypeOf(ShellProcess.prototype, EventEmitter.prototype);
+
+ShellProcess.prototype.kill = function kill(this: any, sig?: string): boolean {
+  this.killed = true;
+  this.emit("exit", null, sig ?? "SIGTERM");
+  return true;
+};
+
+ShellProcess.prototype.disconnect = function disconnect(this: any): void {
+  this.connected = false;
+};
+
+ShellProcess.prototype.send = function send(this: any, msg: unknown, cb?: (e: Error | null) => void): boolean {
+  if (cb) cb(new Error("IPC unavailable"));
+  return false;
+};
+
+ShellProcess.prototype.ref = function ref(this: any): any {
+  return this;
+};
+
+ShellProcess.prototype.unref = function unref(this: any): any {
+  return this;
+};
+
+export default {
+  exec,
+  execSync,
+  execFile,
+  execFileSync,
+  spawn,
+  spawnSync,
+  fork,
+  ShellProcess,
+  initShellExec,
+  shellExec,
+  setStreamingCallbacks,
+  clearStreamingCallbacks,
+  sendStdin,
+  setSyncChannel,
+  setSpawnChildCallback,
+  setForkChildCallback,
+  setIPCSend,
+  setIPCReceiveHandler,
+  handleIPCFromParent,
+  executeNodeBinary,
+};