@volter/tabnode 0.4.1 → 0.5.0

package/src/shims/child_process.ts

@@ -33,6 +33,7 @@ if (typeof globalThis.process === 'undefined') {
 }
 
 import { forGuestRealm, heldWork } from '../host-globals';
+import { promiseOwner } from '../promise-ownership';
 import { Bash, defineCommand } from 'just-bash';
 import type { CommandContext, ExecResult as JustBashExecResult } from 'just-bash';
 import { EventEmitter } from '../node-lib/events-module';
@@ -43,12 +44,18 @@ import { VirtualFSAdapter } from './vfs-adapter';
 import { __releaseOwnedServers, __ownedServerPorts } from '../node-lib/net-module';
 import { __ownedHandleCount, __releaseOwnedHandles } from '../node-lib/net-module';
 import { setProcessRunner, type RunRequest, type StartedRun } from '../node-lib/binding/process_wrap';
+import { registerRunFd, releaseRunFds, inheritedRunFds } from '../node-lib/binding/fds';
+import { nodeProcessHostFor, nodeProcessHostInstalled, nodeProcessRealmToken, nodeProcessInput, type NodeProcessHost, type NodeProcessLaunch } from '../node-process-host';
+import { nativeStreamDescriptor } from '../native-stream-binding';
 import { Pipe, constants as pipeConstants } from '../node-lib/binding/pipe_wrap';
-import { registerRunFd, releaseRunFds } from '../node-lib/binding/fds';
+import {
+  WriteWrap, ShutdownWrap, streamBaseState, kReadBytesOrError, kArrayBufferOffset,
+  type LibuvStreamWrap,
+} from '../node-lib/binding/stream_wrap';
 import { UV_ESRCH } from '../node-lib/binding/uv';
-import { setupChannel } from '../node-lib/child-process-module';
+import { loadNodeLibFor } from '../node-lib/load';
+import type { ChildProcessModule } from '../node-lib/child-process-module';
 import { getCommandNames } from 'just-bash';
-import { diagnosticsChannelModule } from '../node-lib/small-modules';
 import { __substrateExecPath, __substrateProgramName, __substrateLineFor, __substrateShellLine, setProgramResolver } from './command-line';
 
 import { __substrateChildren, __onUncaughtException, __reportUncaughtException } from './process';
@@ -65,6 +72,34 @@ import { resolve as __resolvePath } from './path';
 import { setSyncChildVfs, warmSyncChild } from './sync-child';
 import type { PackageJson } from '../types/package-json';
 
+// Capture host capabilities before the guest's authority is restricted. These
+// endpoints are private, carry no guest bytes, and close at each checkpoint.
+const HostBroadcastChannel = globalThis.BroadcastChannel;
+const hostChannelName = globalThis.crypto?.randomUUID.bind(globalThis.crypto);
+const isWorkerRealm = typeof (globalThis as Record<string, unknown>).WorkerGlobalScope !== 'undefined';
+
+async function settlePrintedEntry(): Promise<void> {
+  await new Promise<void>(resolve => (globalThis.__browserRuntimeNativeSetTimeout ?? setTimeout).call(globalThis, resolve, 0));
+  if (!isWorkerRealm || nodeProcessRealmToken() === null) return;
+  if (!HostBroadcastChannel || !hostChannelName) throw new Error('Native process rejection checkpoint is unavailable.');
+  // HTML queues rejection reporting after the microtask checkpoint on the
+  // DOM manipulation task source. A timer alone can overtake that report.
+  // BroadcastChannel uses the same source, ordering this acknowledgment
+  // behind reports already queued before the timer turn above.
+  const name = hostChannelName();
+  const receiver = new HostBroadcastChannel(name);
+  try {
+    const sender = new HostBroadcastChannel(name);
+    try {
+      await new Promise<void>((resolve, reject) => {
+        receiver.onmessage = () => resolve();
+        receiver.onmessageerror = () => reject(new Error('Native process rejection checkpoint failed.'));
+        sender.postMessage(null);
+      });
+    } finally { sender.close(); }
+  } finally { receiver.close(); }
+}
+
 // Singleton bash instance - uses VFS adapter for two-way file sync
 let bashInstance: Bash | null = null;
 let vfsAdapter: VirtualFSAdapter | null = null;
@@ -114,7 +149,12 @@ Object.defineProperty = function(target: object, key: PropertyKey, descriptor: P
 } as typeof Object.defineProperty;
 
 /** The stdin of a held run's guest, as the run's own. */
-type RunStdin = { emit: (event: string, ...args: unknown[]) => void; push: (chunk: string | Uint8Array | null) => boolean };
+type RunStdin = {
+  emit: (event: string, ...args: unknown[]) => void;
+  push: (chunk: string | Uint8Array | null) => boolean;
+  /** A hosted sink acknowledges consumption before another pipe read. */
+  writeAsync?: (chunk: string | Uint8Array | null) => Promise<void>;
+};
 
 /**
  * What a host gave one run: where its output goes, the handle that aborts it,
@@ -156,6 +196,29 @@ export interface RunStreams {
  */
 const _runStreams = new Map<ProcessToken, RunStreams>();
 
+/** Submit before returning to a spawning parent; completion remains async. */
+async function runHostedNode(host: NodeProcessHost, launch: Omit<NodeProcessLaunch, 'identity' | 'inherited' | 'stdinStream'>): Promise<CommandOutcome> {
+  const { token, streams } = launch;
+  if (!runPid(token)) setRunPid(token, mintPid(), 0);
+  let input: ReturnType<typeof nodeProcessInput> | undefined;
+  try {
+    streams?.signal?.throwIfAborted();
+    const inherited = inheritedRunFds(token).map(({ fd, handle }) => {
+      const descriptor = nativeStreamDescriptor(handle as LibuvStreamWrap);
+      if (!descriptor) throw new Error(`Node descriptor ${fd} has no native owner for process isolation.`);
+      return { fd, handle: descriptor };
+    });
+    input = nodeProcessInput(streams);
+    return await host.run({ ...launch, identity: { ...runPid(token)! }, inherited,
+      ...(input.stream ? { stdinStream: input.stream } : {}) });
+  } finally {
+    if (streams) streams.stdin = null;
+    input?.dispose();
+    // Adoption moves owner registration; only the source-local lookup remains.
+    forgetRunPid(token);
+  }
+}
+
 /**
  * One line on the host realm's console when a run the tab owns dies and
  * nobody is reading its stderr.
@@ -274,7 +337,7 @@ forGuestRealm(() => {
   if (typeof globalThis.addEventListener !== 'function') return;
   __backstopInstalled = true;
   globalThis.addEventListener('error', (event: Event) => {
-    const token = __currentProcessToken() ?? __lastLaunchedToken;
+    const token = nodeProcessRealmToken() ?? __currentProcessToken() ?? __lastLaunchedToken;
     if (token === null) return;
     const raised = event as ErrorEvent;
     const error = raised.error ?? new Error(raised.message || 'uncaught exception');
@@ -333,16 +396,25 @@ export function initChildProcess(vfs: VirtualFS): void {
    * of the server's became `TypeError: Cannot read properties of undefined
    * (reading 'catch')` inside a timer, 59 of them in one boot.
    */
-  const __listenForUnhandledRejections = (report: (reason: unknown, promise?: Promise<unknown>) => void): (() => void) => {
+  const __listenForUnhandledRejections = (owner: object, report: (reason: unknown, promise?: Promise<unknown>) => void, ownsRealm: boolean): (() => void) => {
     if (typeof globalThis.addEventListener === 'function') {
       const target = globalThis as unknown as EventTarget;
-      const listener = (event: Event) => { event.preventDefault(); report((event as PromiseRejectionEvent).reason, (event as PromiseRejectionEvent).promise); };
+      const listener = (event: Event) => {
+        const rejection = event as PromiseRejectionEvent;
+        // An admitted process worker has exactly one Node owner. Shared
+        // embeddings still require provenance and never broadcast failures.
+        if (!ownsRealm && promiseOwner(rejection.promise) !== owner) return;
+        event.preventDefault();
+        report(rejection.reason, rejection.promise);
+      };
       target.addEventListener('unhandledrejection', listener);
       return () => target.removeEventListener('unhandledrejection', listener);
     }
     const host = __hostProcess;
     if (host) {
-      const listener = (reason: unknown, promise?: Promise<unknown>) => report(reason, promise);
+      const listener = (reason: unknown, promise?: Promise<unknown>) => {
+        if (ownsRealm || promiseOwner(promise) === owner) report(reason, promise);
+      };
       host.on('unhandledRejection', listener);
       return () => host.off('unhandledRejection', listener);
     }
@@ -353,6 +425,18 @@ export function initChildProcess(vfs: VirtualFS): void {
       return { stdout: '', stderr: 'VFS not initialized\n', exitCode: 1 };
     }
 
+    // Capture this run's name, streams and cancellation before another Node
+    // entry can start. Forks and shell entries reach this same dispatch seam.
+    const runToken = runTokenOf(ctx);
+    const streams = runToken === null ? undefined : runStreamsFor(runToken);
+    const processHost = nodeProcessHostFor(runToken);
+    if (processHost && runToken !== null) {
+      return runHostedNode(processHost, {
+        token: runToken, argv: [...args], cwd: ctx.cwd, filesystem: tree, env: guestEnvironmentOf(ctx),
+        ...(typeof ctx.stdin === 'string' ? { stdin: ctx.stdin } : {}), ...(streams ? { streams } : {}),
+      });
+    }
+
     // Node reads its own options before the script: `node --turbo-fast-api-calls
     // file.js a b` runs file.js with `a b`, and the options it were given are
     // its `execArgv`. Node's own suite spawns children that way, and the
@@ -378,8 +462,28 @@ export function initChildProcess(vfs: VirtualFS): void {
     // its first fork.
     const execArgv: string[] = [];
     let first = 0;
+    // `-e`/`--eval` and `-p`/`--print` carry the program itself as their
+    // value: there is no script, and every word after the source is the
+    // program's argument. Taken for an option, the source was read as the
+    // script's path ("Cannot find module '/workspace/console.log(1+1)'").
+    let evaluated: { source: string; print: boolean } | null = null;
     while (first < args.length && args[first]!.startsWith('-') && args[first] !== '-' && args[first] !== '--') {
-      execArgv.push(args[first]!);
+      const option = args[first]!;
+      const inline = /^(--eval|--print)=([\s\S]*)$/.exec(option);
+      if (inline) {
+        evaluated = { source: inline[2]!, print: inline[1] === '--print' };
+        execArgv.push(option);
+        first += 1;
+        break;
+      }
+      if (option === '-e' || option === '--eval' || option === '-p' || option === '--print' || option === '-pe') {
+        if (first + 1 >= args.length) return { stdout: '', stderr: `node: ${option} requires an argument\n`, exitCode: 9 };
+        evaluated = { source: args[first + 1]!, print: option.includes('p') };
+        execArgv.push(option, args[first + 1]!);
+        first += 2;
+        break;
+      }
+      execArgv.push(option);
       first += 1;
     }
     if (args[first] === '--') first += 1;
@@ -392,30 +496,21 @@ export function initChildProcess(vfs: VirtualFS): void {
     };
     let script = first;
     let resolvedPath: string | null = null;
-    for (let index = first; index < args.length; index += 1) {
+    for (let index = first; evaluated === null && index < args.length; index += 1) {
       const found = fileNamed(args[index]!);
       if (found !== null) { script = index; resolvedPath = found; break; }
     }
-    for (let index = first; index < script; index += 1) execArgv.push(args[index]!);
-    if (!args[script]) {
+    if (evaluated === null) for (let index = first; index < script; index += 1) execArgv.push(args[index]!);
+    if (evaluated === null && !args[script]) {
       return { stdout: '', stderr: 'Usage: node <script.js> [args...]\n', exitCode: 1 };
     }
-    if (resolvedPath === null) {
+    if (evaluated === null && resolvedPath === null) {
       return { stdout: '', stderr: `Error: Cannot find module '${__resolvePath(ctx.cwd, args[script]!)}'\n`, exitCode: 1 };
     }
 
     let stdout = '';
     let stderr = '';
 
-    // A run the host named is this guest process, for as long as the run
-    // lasts: `pendingTimers`, `processPorts` and `stopProcess` are answered
-    // from here, and a server the guest opens registers under this name.
-    const runToken = runTokenOf(ctx);
-    // What the host gave THIS run — its streams, its abort handle, whether it
-    // holds the run open. Read once here and nowhere from a module global, so
-    // a child spawned by this guest (a second run) cannot take them.
-    const streams = runToken === null ? undefined : runStreamsFor(runToken);
-
     // Track whether process.exit() was called
     let exitCalled = false;
     let exitCode = 0;
@@ -534,7 +629,11 @@ export function initChildProcess(vfs: VirtualFS): void {
     // Set up process.argv for the script. Node fills argv[0] with the
     // executable's path, the same value `process.execPath` reports; `argv0`
     // keeps the original argv[0], the plain word.
-    proc.argv = [__substrateExecPath, resolvedPath, ...args.slice(script + 1)];
+    // An evaluated program has no script: its argv is the executable and the
+    // words after the source, as Node's is.
+    proc.argv = evaluated !== null
+      ? [__substrateExecPath, ...args.slice(first)]
+      : [__substrateExecPath, resolvedPath!, ...args.slice(script + 1)];
     proc.argv0 = 'node';
     proc.execArgv = execArgv;
 
@@ -599,7 +698,8 @@ export function initChildProcess(vfs: VirtualFS): void {
       syncExecution = false;
       try { proc.exit(1); } finally { syncExecution = wasSync; }
     };
-    const detachRejections = __listenForUnhandledRejections(onUnhandledRejection);
+    const detachRejections = __listenForUnhandledRejections(proc, onUnhandledRejection,
+      runToken !== null && nodeProcessRealmToken() === runToken);
 
     // An exception nobody caught ends the program it was thrown in, as it ends
     // one in Node: a guest listener for `uncaughtException` on its process
@@ -668,7 +768,14 @@ export function initChildProcess(vfs: VirtualFS): void {
       // this program's, not whichever run started last. The engine's storage
       // carries it into the timers, microtasks and `then` callbacks the entry
       // schedules from here, so a child spawned later still names its parent.
-      const runEntry = () => runtime.runFile(resolvedPath);
+      // `-p` prints the completion value of the source, which a direct `eval`
+      // in the module body yields with the body's own `require` in scope.
+      const runEntry = () => evaluated !== null
+        ? runtime.evaluate(
+          evaluated.print ? `console.log(eval(${JSON.stringify(evaluated.source)}));` : evaluated.source,
+          __resolvePath(ctx.cwd, '[eval]'),
+        )
+        : runtime.runFile(resolvedPath!);
       entrySettling = __substratePendingOf(
         (runToken === null ? runEntry() : enterRun(runToken, runEntry)).exports,
       );
@@ -734,7 +841,7 @@ export function initChildProcess(vfs: VirtualFS): void {
     if ((stdout.length > 0 || stderr.length > 0) && !__printedThenWorking()) {
       // Settling the command is host work. Killing guest timers must not
       // cancel this continuation and leave the command's promise unresolved.
-      await new Promise(r => (globalThis.__browserRuntimeNativeSetTimeout ?? setTimeout).call(globalThis, r, 0));
+      await settlePrintedEntry();
       // Work that began during that tick is the program's still: a build
       // reached through a dynamic import's chain, a timer the entry set.
       // vue-pure-admin's mock loader, `import('bundle-import').then(...)`
@@ -950,7 +1057,6 @@ export function initChildProcess(vfs: VirtualFS): void {
     },
     start: startChildRun,
   });
-  watchChildren();
 }
 
 /**
@@ -961,19 +1067,10 @@ export function initChildProcess(vfs: VirtualFS): void {
  * a realm here holds many programs and the channel belongs to one of them.
  */
 function attachChannel(proc: ReturnType<Runtime['getProcess']>, fd: number, serialization: string): void {
-  const channel = new Pipe(pipeConstants.IPC);
-  if (channel.open(fd) !== 0) { channel.close(); return; }
-  // Node unrefs a child's channel: the channel alone does not hold a program
-  // open, and `Control.refCounted` puts it back the moment the program
-  // listens for a message.
-  channel.unref();
-  const control = setupChannel(proc, channel, serialization);
-  proc.on('newListener', (name: unknown) => {
-    if (name === 'message' || name === 'disconnect') control.refCounted();
-  });
-  proc.on('removeListener', (name: unknown) => {
-    if (name === 'message' || name === 'disconnect') control.unrefCounted();
-  });
+  // With a process-bound loader, Node's own bootstrap now owns this too.
+  // The host setupChannel built received sockets from the host net graph;
+  // process.send and every received socket must use the child's graph.
+  (loadNodeLibFor(proc, 'child_process') as ChildProcessModule)._forkChild(fd, serialization);
 }
 
 /** The shell's environment as a record: just-bash hands a command a Map. */
@@ -1251,6 +1348,19 @@ interface ChildProcessHostResult {
   exitCode: number;
 }
 
+/**
+ * One of a child's pipes past fd 2, as the host's program holds it: the
+ * parent's handle for that fd is the other end.
+ */
+interface ChildProcessHostDescriptor {
+  /** Bytes the parent writes to this fd, in order; ends when the parent closes it. */
+  input: AsyncIterable<Uint8Array>;
+  /** Bytes the child writes on this fd; they are reads on the parent's handle. */
+  write(bytes: Uint8Array): void;
+  /** The child closed this fd: EOF on the parent's handle. */
+  end(): void;
+}
+
 /** How a command is handed to that host. */
 interface ChildProcessHostRequest {
   cwd?: string;
@@ -1258,10 +1368,13 @@ interface ChildProcessHostRequest {
   /** Bytes already on fd 0 when the command begins, as Node delivers them. */
   stdin?: string;
   stdinStream: AsyncIterable<Uint8Array>;
+  terminal?: RunStreams['terminal'];
   signal: AbortSignal;
   hold: { value: boolean };
   onStdout: (data: string) => void;
   onStderr: (data: string) => void;
+  /** The child's pipes past fd 2, by number; only where it was started with any. */
+  descriptors?: Record<number, ChildProcessHostDescriptor>;
 }
 
 /** The executor a host publishes on the well-known global symbol. */
@@ -1308,10 +1421,13 @@ interface CommandRun {
   stdin?: string;
   /** Bytes a writer still holds the run's fd 0 open with, as they arrive. */
   stdinStream?: AsyncIterable<Uint8Array>;
+  terminal?: RunStreams['terminal'];
   signal?: AbortSignal;
   onStdout?: (data: string) => void;
   onStderr?: (data: string) => void;
   vfs?: VirtualFS;
+  /** The child's ends of its pipes past fd 2, for a host that runs it. */
+  descriptors?: { fd: number; pipe: Pipe }[];
 }
 
 /**
@@ -1349,16 +1465,29 @@ async function routeCommand(run: CommandRun): Promise<CommandOutcome> {
     let streamedErr = '';
     const onStdout = (data: string): void => { streamedOut += String(data); run.onStdout?.(String(data)); };
     const onStderr = (data: string): void => { streamedErr += String(data); run.onStderr?.(String(data)); };
+    // This token routes the engine's own shell, not a program's environment.
+    // If a host shell inherits it, a later Node launch can override its new
+    // stream identity with the ancestor's and deliver output to both runs.
+    // Host ancestry is already carried by the current process context.
+    const hostEnv = run.env === undefined ? undefined : { ...run.env };
+    if (hostEnv) delete hostEnv[PROCESS_TOKEN_ENV];
+    // The host's program is the one holding the child's pipes past fd 2; the
+    // run's end is its end of them, whatever it did not close itself.
+    const opened = (run.descriptors ?? []).map(({ fd, pipe }) => ({ fd, ...descriptorOver(pipe) }));
     try {
       const result = await bridge.run(run.command, {
         cwd: run.cwd,
-        env: run.env,
+        env: hostEnv,
         ...(typeof run.stdin === 'string' ? { stdin: run.stdin } : {}),
         stdinStream: run.stdinStream ?? emptyStdinStream(),
+        ...(run.terminal ? { terminal: run.terminal } : {}),
         signal: controller.signal,
         hold: { value: true },
         onStdout,
         onStderr,
+        ...(opened.length > 0
+          ? { descriptors: Object.fromEntries(opened.map(({ fd, descriptor }) => [fd, descriptor])) }
+          : {}),
       });
       const stdout = result.stdout || streamedOut;
       const stderr = result.stderr || streamedErr;
@@ -1367,6 +1496,7 @@ async function routeCommand(run: CommandRun): Promise<CommandOutcome> {
       return { stdout, stderr, exitCode: result.exitCode };
     } finally {
       if (bridge.parentSignal) bridge.parentSignal.removeEventListener('abort', abortWithParent);
+      for (const { release } of opened) release();
     }
   }
 
@@ -1379,6 +1509,63 @@ async function routeCommand(run: CommandRun): Promise<CommandOutcome> {
   return { stdout: result.stdout || '', stderr: result.stderr || '', exitCode: result.exitCode };
 }
 
+/**
+ * A child's pipe past fd 2, held by a program the host runs: the parent's
+ * writes on its handle are the program's input, read the way the handle's fd 0
+ * is read, and the program's writes are reads on the parent's handle, as bytes.
+ * `release` is the run's end: reading stops and the input ends.
+ */
+function descriptorOver(pipe: Pipe): { descriptor: ChildProcessHostDescriptor; release(): void } {
+  const queued: Uint8Array[] = [];
+  let waiting: ((result: IteratorResult<Uint8Array>) => void) | null = null;
+  let ended = false;
+  const finish = (): void => {
+    if (ended) return;
+    ended = true;
+    pipe.readStop();
+    pipe.onread = null;
+    if (waiting) { const wake = waiting; waiting = null; wake({ value: undefined, done: true }); }
+  };
+  pipe.onread = (arrayBuffer: ArrayBuffer | null): void => {
+    const length = streamBaseState[kReadBytesOrError];
+    if (length <= 0 || arrayBuffer === null) { finish(); return; }
+    const bytes = new Uint8Array(arrayBuffer, streamBaseState[kArrayBufferOffset], length).slice();
+    if (waiting) { const wake = waiting; waiting = null; wake({ value: bytes, done: false }); }
+    else queued.push(bytes);
+  };
+  pipe.readStart();
+  const input: AsyncIterable<Uint8Array> = {
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array> {
+      return {
+        next(): Promise<IteratorResult<Uint8Array>> {
+          const next = queued.shift();
+          if (next) return Promise.resolve({ value: next, done: false });
+          if (ended) return Promise.resolve({ value: undefined, done: true });
+          return new Promise((resolve) => { waiting = resolve; });
+        },
+        return(): Promise<IteratorResult<Uint8Array>> {
+          finish();
+          return Promise.resolve({ value: undefined, done: true });
+        },
+      };
+    },
+  };
+  return {
+    descriptor: {
+      input,
+      write(bytes: Uint8Array): void {
+        if (pipe.closed) return;
+        pipe.writeBuffer(new WriteWrap(), bytes);
+      },
+      end(): void {
+        finish();
+        if (!pipe.closed) pipe.shutdown(new ShutdownWrap());
+      },
+    },
+    release: finish,
+  };
+}
+
 /** A child whose stdin nobody writes to still needs a stream the host can read. */
 function emptyStdinStream(): AsyncIterable<Uint8Array> {
   return { async *[Symbol.asyncIterator]() { /* nothing is ever written */ } };
@@ -1491,9 +1678,28 @@ function startChildRun(request: RunRequest): StartedRun {
   // number of the run that spawned it. `src/process-tokens.ts` says what
   // reads them.
   const pid = mintPid();
-  setRunPid(token, pid, runPid(__currentProcessToken() ?? __lastLaunchedToken)?.pid ?? 0);
+  // In a process realm the admitted guest is always the spawning parent.
+  // Async bookkeeping for a routed child must not make that child its parent.
+  setRunPid(token, pid, runPid(nodeProcessRealmToken() ?? __currentProcessToken() ?? __lastLaunchedToken)?.pid ?? 0);
   const controller = new AbortController();
   const pendingStdin: Array<Uint8Array | null> = [];
+  // A host terminal consumes input incrementally. The old string-only
+  // route dropped every keystroke that arrived after a child was launched.
+  const admittedNode = nodeProcessHostInstalled() && engineProgramFor(request.file, request.cwd) === 'node';
+  const hostTerminal = request.terminal !== undefined && hostExecutor() !== null && !admittedNode;
+  let wakeInput: (() => void) | undefined;
+  const hostInput: AsyncIterable<Uint8Array> = {
+    async *[Symbol.asyncIterator]() {
+      while (!finished && !controller.signal.aborted) {
+        if (pendingStdin.length) {
+          const bytes = pendingStdin.shift();
+          if (bytes === null) return;
+          if (bytes) yield bytes;
+        } else await new Promise<void>((resolve) => { wakeInput = resolve; });
+      }
+    },
+  };
+  controller.signal.addEventListener('abort', () => { wakeInput?.(); }, { once: true });
   let stdinSink: RunStdin | null = null;
   let finished = false;
   let started = false;
@@ -1501,9 +1707,22 @@ function startChildRun(request: RunRequest): StartedRun {
   /** What the parent wrote to the child's fd 0 before the command began. */
   const initialStdin: Uint8Array[] = [];
 
-  const flushStdin = (): void => {
-    if (!stdinSink) return;
-    while (pendingStdin.length > 0) stdinSink.push(pendingStdin.shift() as Uint8Array | null);
+  let flushingInput: Promise<void> | undefined;
+  const flushStdin = (): void | Promise<void> => {
+    if (flushingInput) return flushingInput;
+    if (!stdinSink || finished) return;
+    while (pendingStdin.length > 0) {
+      const chunk = pendingStdin.shift() as Uint8Array | null;
+      if (stdinSink.writeAsync) {
+        const waiting = stdinSink.writeAsync(chunk);
+        flushingInput = waiting.then(() => {
+          flushingInput = undefined;
+          return flushStdin();
+        }, cause => { flushingInput = undefined; throw cause; });
+        return flushingInput;
+      }
+      stdinSink.push(chunk);
+    }
   };
 
   let streamedOut = 0;
@@ -1515,23 +1734,39 @@ function startChildRun(request: RunRequest): StartedRun {
     held: false,
     stdinOpen: request.stdinIsPipe,
     stderrIsPipe: request.stderrIsPipe,
+    terminal: request.terminal,
     get stdin(): RunStdin | null | undefined { return stdinSink; },
-    set stdin(sink: RunStdin | null | undefined) { stdinSink = sink ?? null; if (stdinSink) flushStdin(); },
+    set stdin(sink: RunStdin | null | undefined) {
+      stdinSink = sink ?? null;
+      if (stdinSink) {
+        const pending = flushStdin();
+        if (pending) void pending.catch(cause => {
+          // Normal child exit detaches the sink before cancelling its writer.
+          // That cancellation must not turn a successful exit into failure.
+          if (!finished && stdinSink === sink) { controller.abort(cause); end(1, null); }
+        });
+      }
+    },
   };
   registerRunStreams(token, streams);
   // The child is started with the descriptors its parent wired: an IPC channel
   // is at the number its `NODE_CHANNEL_FD` will name, under this run's name,
   // because every child is told the same number.
   if (request.channel) registerRunFd(token, request.channel.fd, 'PIPE', request.channel.pipe);
+  // Its pipes past fd 2 are there the same way, at the numbers it was given.
+  for (const { fd, pipe } of request.descriptors) registerRunFd(token, fd, 'PIPE', pipe);
 
   const end = (code: number, signal: string | null): void => {
     if (finished) return;
     finished = true;
+    wakeInput?.();
+    wakeInput = undefined;
     _activeForkedChildren -= 1;
     releaseRunStreams(token);
     releaseRunFds(token);
     // A run that has ended is no longer a process: its number answers ESRCH.
     forgetRunPid(token);
+    __substrateChildren.delete(pid);
     _onForkedChildExit?.();
     request.exit(code, signal);
   };
@@ -1554,16 +1789,24 @@ function startChildRun(request: RunRequest): StartedRun {
     void (async () => {
       let outcome: CommandOutcome;
       try {
-        outcome = await routeCommand({
+        const processHost = admittedNode ? nodeProcessHostFor(token) : undefined;
+        const env = { ...request.env };
+        delete env[PROCESS_TOKEN_ENV];
+        outcome = processHost ? await runHostedNode(processHost, {
+          token, argv: request.args.slice(1), cwd: request.cwd ?? '/',
+          filesystem: currentVfs!, env, streams, ...(stdin !== undefined ? { stdin } : {}),
+        }) : await enterRun(token, () => routeCommand({
           command: __substrateLineFor(request.file, request.args, request.cwd),
-          engineFirst: programExists(request.file, request.cwd, request.env),
+          engineFirst: !hostTerminal && programExists(request.file, request.cwd, request.env),
           cwd: request.cwd,
           env: { ...request.env, [PROCESS_TOKEN_ENV]: token },
           stdin,
+          ...(hostTerminal ? { stdinStream: hostInput, terminal: request.terminal } : {}),
           signal: controller.signal,
           onStdout: streams.onStdout,
           onStderr: streams.onStderr,
-        });
+          descriptors: request.descriptors,
+        }));
       } catch (error) {
         outcome = { stdout: '', stderr: `${error instanceof Error ? error.message : String(error)}\n`, exitCode: 1 };
       }
@@ -1577,10 +1820,10 @@ function startChildRun(request: RunRequest): StartedRun {
   };
 
   _activeForkedChildren += 1;
-  if (request.stdinIsPipe) (globalThis.__browserRuntimeNativeSetTimeout ?? setTimeout).call(globalThis, begin, 0);
+  if (request.stdinIsPipe && !admittedNode) (globalThis.__browserRuntimeNativeSetTimeout ?? setTimeout).call(globalThis, begin, 0);
   else begin();
 
-  return {
+  const control: StartedRun = {
     token,
     pid,
     kill(signal: string): number {
@@ -1593,12 +1836,14 @@ function startChildRun(request: RunRequest): StartedRun {
       end(0, killedBy);
       return 0;
     },
-    writeStdin(bytes: Uint8Array): void {
+    writeStdin(bytes: Uint8Array): void | Promise<void> {
+      if (hostTerminal) { pendingStdin.push(bytes); wakeInput?.(); wakeInput = undefined; return; }
       if (!started) { initialStdin.push(bytes); return; }
       pendingStdin.push(bytes);
-      flushStdin();
+      return flushStdin();
     },
     endStdin(): void {
+      if (hostTerminal) { pendingStdin.push(null); wakeInput?.(); wakeInput = undefined; return; }
       if (!started) {
         // The writer closed before the command began: the run's fd 0 is the
         // string already collected and nothing more, so it is not held open.
@@ -1607,38 +1852,23 @@ function startChildRun(request: RunRequest): StartedRun {
         return;
       }
       pendingStdin.push(null);
-      flushStdin();
+      const sink = stdinSink;
+      const pending = flushStdin();
+      if (pending) void pending.catch(cause => {
+        if (!finished && stdinSink === sink && sink) { controller.abort(cause); end(1, null); }
+      });
     },
   };
-}
-
-/**
- * The guest's children are processes it can see, so `process.kill(pid, 0)`
- * answers about a live child rather than ESRCH for every pid but its own.
- * Node publishes each `ChildProcess` on the `child_process` diagnostics
- * channel as it is constructed, which is the door this reads: the pid is
- * filled by `spawn` a moment later, so the child is recorded on the next tick.
- */
-function watchChildren(): void {
-  // Node's own `diagnostics_channel`, the same module the vendored
-  // `child_process.js` publishes on. A channel is a name in one registry, and
-  // the engine's own imitation of the module was a second registry: a
-  // subscriber there heard nothing a vendored file published.
-  const diagnosticsChannel = diagnosticsChannelModule as unknown as {
-    channel(name: string): { subscribe(listener: (message: unknown) => void): void };
-  };
-  diagnosticsChannel.channel('child_process').subscribe((message: unknown) => {
-    const child = (message as { process?: { pid?: number; exitCode: number | null; signalCode: string | null; kill(signal?: string): boolean; once(event: string, listener: () => void): unknown } }).process;
-    if (!child) return;
-    queueMicrotask(() => {
-      const pid = child.pid;
-      if (typeof pid !== 'number' || pid === 0) return;
-      __substrateChildren.set(pid, child);
-      child.once('exit', () => { __substrateChildren.delete(pid); });
-    });
+  // A pid is signalable before spawn returns, including cancellation in
+  // the same turn. A diagnostics-channel microtask registered it too late.
+  __substrateChildren.set(pid, {
+    exitCode: null, signalCode: null,
+    kill: (signal = 'SIGTERM') => control.kill(signal) === 0,
   });
+  return control;
 }
 
+
 export default {
   initChildProcess,
   registerRunStreams,