feat: US-071 - Fix sandbox child_process bridge for mounted host-binary commands

Author: NathanFlurry

CLAUDE.md

@@ -135,6 +135,7 @@
 - WHATWG globals that sandbox code touches before any bridge module loads (`TextDecoder`, `TextEncoder`, `Event`, `CustomEvent`, `EventTarget`) must be fixed in both bootstrap layers and `packages/nodejs/src/bridge/polyfills.ts`; bridge-only fixes do not change the globals seen by direct `runtime.run()` / `runtime.exec()` code
 - bridged `fetch()` request serialization must normalize `Headers` instances before crossing the JSON bridge; passing the host a raw `Headers` object silently drops auth and SDK-specific headers because it stringifies to `{}`
 - sandbox stdout/stderr write bridges must preserve Node's callback semantics even for empty writes like `process.stdout.write('', cb)`; headless CLI tools use that zero-byte callback as a flush barrier before clean exit
+- exec-mode scripts that depend on bridge-delivered child-process/stdio callbacks must keep the same `Execute` alive on `_waitForActiveHandles()`; once the native V8 session returns from `Execute`, later `StreamEvent` messages sent to that idle session thread are ignored
 - When a builtin or `internal/*` module needs sandbox-specific behavior but still has to work through CommonJS `require()`, add it under `packages/nodejs/src/polyfills/` and register it in `packages/nodejs/src/polyfills.ts` `CUSTOM_POLYFILL_ENTRY_POINTS`; that keeps esbuild bundling it to CJS instead of letting the isolate loader choke on raw ESM `export` syntax
 - vendored fs abort tests deep-freeze option bags via `common.mustNotMutateObjectDeep()`, so sandbox `AbortSignal` state must live outside writable instance properties; freezing `{ signal }` must not break later `controller.abort()`
 - vendored `common.mustNotMutateObjectDeep()` helpers must skip populated typed-array/DataView instances; `Object.freeze(new Uint8Array([1]))` throws before the runtime under test executes, which turns option-bag immutability coverage into a harness failure

native/v8-runtime/src/execution.rs

@@ -376,11 +376,17 @@ pub fn execute_script(
         // return a Promise (for example an async IIFE ending in await import()).
         if completion.is_promise() {
             let promise = v8::Local::<v8::Promise>::try_from(completion).unwrap();
-
-            if promise.state() == v8::PromiseState::Rejected {
-                let rejection = promise.result(tc);
-                let (c, err) = exception_to_result(tc, rejection);
-                return (c, Some(err));
+            match promise.state() {
+                v8::PromiseState::Pending => {
+                    set_pending_script_evaluation(tc, promise);
+                    return (0, None);
+                }
+                v8::PromiseState::Rejected => {
+                    let rejection = promise.result(tc);
+                    let (c, err) = exception_to_result(tc, rejection);
+                    return (c, Some(err));
+                }
+                v8::PromiseState::Fulfilled => {}
             }
         }
     }
@@ -593,9 +599,16 @@ struct PendingModuleEvaluation {
 // (single-threaded per session).
 unsafe impl Send for PendingModuleEvaluation {}
 
+struct PendingScriptEvaluation {
+    promise: v8::Global<v8::Promise>,
+}
+
+unsafe impl Send for PendingScriptEvaluation {}
+
 thread_local! {
     static MODULE_RESOLVE_STATE: RefCell<Option<ModuleResolveState>> = const { RefCell::new(None) };
     static PENDING_MODULE_EVALUATION: RefCell<Option<PendingModuleEvaluation>> = const { RefCell::new(None) };
+    static PENDING_SCRIPT_EVALUATION: RefCell<Option<PendingScriptEvaluation>> = const { RefCell::new(None) };
 }
 
 fn module_request_cache_key(specifier: &str, referrer_name: &str) -> String {
@@ -615,11 +628,21 @@ pub fn clear_pending_module_evaluation() {
     });
 }
 
+pub fn clear_pending_script_evaluation() {
+    PENDING_SCRIPT_EVALUATION.with(|cell| {
+        *cell.borrow_mut() = None;
+    });
+}
+
 #[cfg_attr(test, allow(dead_code))]
 pub fn has_pending_module_evaluation() -> bool {
     PENDING_MODULE_EVALUATION.with(|cell| cell.borrow().is_some())
 }
 
+pub fn has_pending_script_evaluation() -> bool {
+    PENDING_SCRIPT_EVALUATION.with(|cell| cell.borrow().is_some())
+}
+
 pub fn pending_module_evaluation_needs_wait(scope: &mut v8::HandleScope) -> bool {
     PENDING_MODULE_EVALUATION.with(|cell| {
         let borrow = cell.borrow();
@@ -631,6 +654,17 @@ pub fn pending_module_evaluation_needs_wait(scope: &mut v8::HandleScope) -> bool
     })
 }
 
+pub fn pending_script_evaluation_needs_wait(scope: &mut v8::HandleScope) -> bool {
+    PENDING_SCRIPT_EVALUATION.with(|cell| {
+        let borrow = cell.borrow();
+        let Some(pending) = borrow.as_ref() else {
+            return false;
+        };
+        let promise = v8::Local::new(scope, &pending.promise);
+        promise.state() == v8::PromiseState::Pending
+    })
+}
+
 fn set_pending_module_evaluation(
     scope: &mut v8::HandleScope,
     module: v8::Local<v8::Module>,
@@ -644,6 +678,17 @@ fn set_pending_module_evaluation(
     });
 }
 
+fn set_pending_script_evaluation(
+    scope: &mut v8::HandleScope,
+    promise: v8::Local<v8::Promise>,
+) {
+    PENDING_SCRIPT_EVALUATION.with(|cell| {
+        *cell.borrow_mut() = Some(PendingScriptEvaluation {
+            promise: v8::Global::new(scope, promise),
+        });
+    });
+}
+
 pub(crate) fn take_unhandled_promise_rejection(
     scope: &mut v8::HandleScope,
 ) -> Option<ExecutionError> {
@@ -652,6 +697,40 @@ pub(crate) fn take_unhandled_promise_rejection(
         .and_then(|state| state.unhandled.drain().next().map(|(_, err)| err))
 }
 
+pub fn finalize_pending_script_evaluation(
+    scope: &mut v8::HandleScope,
+) -> Option<(i32, Option<ExecutionError>)> {
+    let pending = PENDING_SCRIPT_EVALUATION.with(|cell| cell.borrow_mut().take())?;
+    let tc = &mut v8::TryCatch::new(scope);
+    let promise = v8::Local::new(tc, &pending.promise);
+
+    tc.perform_microtask_checkpoint();
+
+    if let Some(exception) = tc.exception() {
+        let (code, err) = exception_to_result(tc, exception);
+        return Some((code, Some(err)));
+    }
+
+    if let Some(err) = take_unhandled_promise_rejection(tc) {
+        return Some((1, Some(err)));
+    }
+
+    match promise.state() {
+        v8::PromiseState::Pending => {
+            PENDING_SCRIPT_EVALUATION.with(|cell| {
+                *cell.borrow_mut() = Some(pending);
+            });
+            None
+        }
+        v8::PromiseState::Rejected => {
+            let rejection = promise.result(tc);
+            let (code, err) = exception_to_result(tc, rejection);
+            Some((code, Some(err)))
+        }
+        v8::PromiseState::Fulfilled => Some((0, None)),
+    }
+}
+
 fn serialize_module_exports(
     scope: &mut v8::HandleScope,
     module: v8::Local<v8::Module>,

native/v8-runtime/src/session.rs

@@ -535,6 +535,7 @@ fn session_thread(
                         let event_loop_status =
                             if pending.len() > 0
                                 || execution::has_pending_module_evaluation()
+                                || execution::has_pending_script_evaluation()
                                 || !deferred_queue.lock().unwrap().is_empty()
                             {
                                 let scope = &mut v8::HandleScope::new(iso);
@@ -572,6 +573,18 @@ fn session_thread(
                             }
                         }
 
+                        if !terminated && mode == 0 && error.is_none() {
+                            let scope = &mut v8::HandleScope::new(iso);
+                            let ctx = v8::Local::new(scope, &exec_context);
+                            let scope = &mut v8::ContextScope::new(scope, ctx);
+                            if let Some((next_code, next_error)) =
+                                execution::finalize_pending_script_evaluation(scope)
+                            {
+                                code = next_code;
+                                error = next_error;
+                            }
+                        }
+
                         // Check if timeout fired
                         let timed_out = timeout_guard.as_ref().is_some_and(|g| g.timed_out());
 
@@ -621,6 +634,7 @@ fn session_thread(
                         };
 
                         execution::clear_pending_module_evaluation();
+                        execution::clear_pending_script_evaluation();
                         execution::clear_module_state();
 
                         send_message(&ipc_tx, &result_frame, &mut msg_frame_buf);
@@ -736,6 +750,7 @@ pub(crate) fn run_event_loop(
 ) -> EventLoopStatus {
     while pending.len() > 0
         || execution::pending_module_evaluation_needs_wait(scope)
+        || execution::pending_script_evaluation_needs_wait(scope)
         || deferred
             .map(|dq| !dq.lock().unwrap().is_empty())
             .unwrap_or(false)
@@ -749,7 +764,10 @@ pub(crate) fn run_event_loop(
                     return status;
                 }
             }
-            if pending.len() == 0 && !execution::pending_module_evaluation_needs_wait(scope) {
+            if pending.len() == 0
+                && !execution::pending_module_evaluation_needs_wait(scope)
+                && !execution::pending_script_evaluation_needs_wait(scope)
+            {
                 break;
             }
         }

packages/nodejs/src/bridge-handlers.ts

@@ -3736,11 +3736,29 @@ export function buildChildProcessBridgeHandlers(deps: ChildProcessBridgeDeps): B
 		};
 	}
 
+	type ChildProcessStreamPayload =
+		| { sessionId: number; dataBase64: string }
+		| { sessionId: number; code: number };
+
 	// Serialize a child process event and push it into the V8 isolate
-	const dispatchEvent = (sessionId: number, type: string, data?: Uint8Array | number) => {
+	const dispatchEvent = (sessionId: number, type: "stdout" | "stderr" | "exit", data?: Uint8Array | number) => {
 		try {
-			const payload = JSON.stringify({ sessionId, type, data: data instanceof Uint8Array ? Buffer.from(data).toString("base64") : data });
-			deps.sendStreamEvent("childProcess", Buffer.from(payload));
+			let eventType: "child_stdout" | "child_stderr" | "child_exit";
+			let payload: ChildProcessStreamPayload;
+			if (type === "stdout" || type === "stderr") {
+				eventType = type === "stdout" ? "child_stdout" : "child_stderr";
+				payload = {
+					sessionId,
+					dataBase64: Buffer.from(data as Uint8Array).toString("base64"),
+				};
+			} else {
+				eventType = "child_exit";
+				payload = {
+					sessionId,
+					code: Number(data ?? 1),
+				};
+			}
+			deps.sendStreamEvent(eventType, Buffer.from(JSON.stringify(payload)));
 		} catch {
 			// Context may be disposed
 		}

packages/nodejs/src/bridge/child-process.ts

@@ -53,11 +53,11 @@ const childProcessInstances = new Map<number, ChildProcess>();
  * Routes stdout/stderr chunks and exit codes to the corresponding ChildProcess
  * instance by session ID, and unregisters the active handle on exit.
  */
-const childProcessDispatch = (
+function routeChildProcessEvent(
   sessionId: number,
   type: "stdout" | "stderr" | "exit",
-  data: Uint8Array | number
-): void => {
+  data: Uint8Array | number,
+): void {
   const child = childProcessInstances.get(sessionId);
   if (!child) return;
 
@@ -82,6 +82,81 @@ const childProcessDispatch = (
       _unregisterHandle(`child:${sessionId}`);
     }
   }
+}
+
+const childProcessDispatch = (
+  eventTypeOrSessionId: string | number,
+  payloadOrType: unknown,
+  data?: Uint8Array | number
+): void => {
+  if (typeof eventTypeOrSessionId === "number") {
+    routeChildProcessEvent(
+      eventTypeOrSessionId,
+      payloadOrType as "stdout" | "stderr" | "exit",
+      data as Uint8Array | number,
+    );
+    return;
+  }
+
+  const payload = (() => {
+    if (payloadOrType && typeof payloadOrType === "object") {
+      return payloadOrType as {
+        sessionId?: unknown;
+        dataBase64?: unknown;
+        data?: unknown;
+        code?: unknown;
+      };
+    }
+    if (typeof payloadOrType === "string") {
+      try {
+        return JSON.parse(payloadOrType) as {
+          sessionId?: unknown;
+          dataBase64?: unknown;
+          data?: unknown;
+          code?: unknown;
+        };
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  })();
+  const sessionId = typeof payload?.sessionId === "number"
+    ? payload.sessionId
+    : Number(payload?.sessionId);
+  if (!Number.isFinite(sessionId)) {
+    return;
+  }
+
+  if (eventTypeOrSessionId === "child_stdout" || eventTypeOrSessionId === "child_stderr") {
+    const encoded =
+      typeof payload?.dataBase64 === "string"
+        ? payload.dataBase64
+        : typeof payload?.data === "string"
+          ? payload.data
+          : "";
+    const bytes =
+      typeof Buffer !== "undefined"
+        ? Buffer.from(encoded, "base64")
+        : new Uint8Array(
+            atob(encoded)
+              .split("")
+              .map((char) => char.charCodeAt(0)),
+          );
+    routeChildProcessEvent(
+      sessionId,
+      eventTypeOrSessionId === "child_stdout" ? "stdout" : "stderr",
+      bytes,
+    );
+    return;
+  }
+
+  if (eventTypeOrSessionId === "child_exit") {
+    const code = typeof payload?.code === "number"
+      ? payload.code
+      : Number(payload?.code ?? 1);
+    routeChildProcessEvent(sessionId, "exit", code);
+  }
 };
 exposeCustomGlobal("_childProcessDispatch", childProcessDispatch);
 

packages/nodejs/src/execution-driver.ts

@@ -1036,10 +1036,16 @@ export class NodeExecutionDriver implements RuntimeDriver {
 		const sessionMode = options.mode === "run" || entryIsEsm ? "run" : "exec";
 		const userCode = entryIsEsm
 			? options.code
-			: transformSourceForRequireSync(
-					options.code,
-					options.filePath ?? "/entry.js",
-				);
+			: (() => {
+					const transformed = transformSourceForRequireSync(
+						options.code,
+						options.filePath ?? "/entry.js",
+					);
+					if (options.mode !== "exec") {
+						return transformed;
+					}
+					return `${transformed}\n;typeof _waitForActiveHandles === "function" ? _waitForActiveHandles() : undefined;`;
+				})();
 
 		// Get or create V8 runtime
 		const v8Runtime = await getSharedV8Runtime();