feat: US-062 - Make Pi headless mode pass end-to-end with real-provider tokens

Author: NathanFlurry

.agent/contracts/node-bridge.md

@@ -79,6 +79,11 @@ This hardening policy MUST NOT force Node stdlib globals to non-writable/non-con
 - **WHEN** bridge setup exposes a Node stdlib global surface (for example `process`, timers, `Buffer`, `URL`, `fetch`, or `console`)
 - **THEN** the bridge MUST preserve Node-compatible behavior and MUST NOT require non-writable/non-configurable descriptors for that stdlib global due to this policy alone
 
+#### Scenario: Bridge exposes Node global alias
+- **WHEN** sandboxed code or bridged dependencies access `global`
+- **THEN** the bridge/runtime bootstrap MUST expose `global` as an alias of `globalThis`
+- **AND** Node globals such as `process` and `Buffer` MUST remain reachable through that alias
+
 ### Requirement: WHATWG URL Bridge Preserves Node Validation And Scalar-Value Semantics
 Bridge-provided `URL` and `URLSearchParams` globals SHALL preserve the Node-observable validation, coercion, and inspection behavior that vendored conformance tests assert.
 

.agent/contracts/node-permissions.md

@@ -89,6 +89,11 @@ When driver-managed node_modules overlay/projection is active (including always-
 - **THEN** those read operations MUST succeed when the canonical path still resolves inside the configured projected `node_modules` closure
 - **AND** the same host-absolute projected paths MUST remain read-only for write, rename, mkdir, unlink, and rmdir operations
 
+#### Scenario: Pnpm virtual-store dependency targets stay inside the projected closure
+- **WHEN** a projected package resolves a transitive dependency through pnpm virtual-store symlinks (for example package-internal `imports` such as Chalk resolving `#ansi-styles` to another package directory under `.pnpm/.../node_modules/...`)
+- **THEN** the module overlay MUST treat those canonical dependency paths as part of the same read-only projected closure
+- **AND** sandboxed reads of those host-absolute dependency files MUST succeed without granting access to unrelated host filesystem paths outside the reachable package closure
+
 #### Scenario: Sandboxed write targets projected module file
 - **WHEN** sandboxed code attempts `writeFile`, `unlink`, or `rename` for a path under projected `/app/node_modules`
 - **THEN** the operation MUST be denied with `EACCES` regardless of broader filesystem allow rules

.agent/contracts/node-stdlib.md

@@ -184,6 +184,11 @@ Builtin module resolution through helper APIs MUST return builtin identifiers di
 - **WHEN** sandboxed code calls `createRequire("/app/entry.js").resolve("path")`
 - **THEN** the call MUST succeed and return a builtin identifier for `path` (for example `"path"` or `"node:path"`)
 
+#### Scenario: CommonJS builtin fallback stays CommonJS-safe
+- **WHEN** CommonJS package code loads a built-in such as `v8` through a fallback file-loading path instead of a pre-populated cache hit
+- **THEN** the runtime MUST still provide CommonJS-compatible source or exports for that builtin
+- **AND** the loader MUST NOT hand a CommonJS `require()` path an ESM wrapper that fails on `export` syntax
+
 ### Requirement: Bridged Builtins Support ESM Default and Named Imports
 For bridged built-in modules exposed to ESM, the runtime MUST provide both default export access and named-import access for supported APIs.
 

CLAUDE.md

@@ -19,6 +19,7 @@
 - tests that validate sandbox behavior MUST run code through the secure-exec sandbox (NodeRuntime/proc.exec()), never directly on the host
 - CLI tool tests (Pi, Claude Code, OpenCode) must execute inside the sandbox: Pi runs as JS in the VM, Claude Code and OpenCode spawn their binaries via the sandbox's child_process.spawn bridge
 - real-provider CLI/SDK tool-integration tests must stay opt-in via an explicit env flag and load credentials at runtime from exported env vars or `~/misc/env.txt`; never commit secrets or replace the live provider path with a mock redirect when the story requires real traffic
+- real-provider NodeRuntime CLI/tool tests that need a mutable temp worktree must pair `moduleAccess` with a real host-backed base filesystem such as `new NodeFileSystem()`; `moduleAccess` alone makes projected packages readable but leaves sandbox tools unable to touch `/tmp` working files
 - e2e-docker fixtures connect to real Docker containers (Postgres, MySQL, Redis, SSH/SFTP) — skip gracefully via `skipUnlessDocker()` when Docker is unavailable
 - interactive/PTY tests must use `kernel.openShell()` with `@xterm/headless`, not host PTY via `script -qefc`
 - kernel blocking-I/O regressions should be proven through `packages/core/test/kernel/kernel-integration.test.ts` using real process-owned FDs via `KernelInterface` (`fdWrite`, `flock`, `fdPollWait`) rather than only manager-level unit tests
@@ -131,6 +132,8 @@
 - keep it up to date when adding, removing, or significantly changing components
 - keep host bootstrap polyfills in `packages/nodejs/src/execution-driver.ts` aligned with isolate bootstrap polyfills in `packages/core/isolate-runtime/src/inject/require-setup.ts`; drift in shared globals like `AbortController` causes sandbox-only behavior gaps that source-level tests can miss
 - 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
 - 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
@@ -148,6 +151,7 @@
 - `/proc/sys/kernel/hostname` conformance hits both kernel-backed and standalone NodeRuntime paths; a procfs fix that only lands in the kernel layer still leaves `createTestNodeRuntime()` fs/FileHandle coverage red
 - require-transformed ESM must not rely on the CommonJS wrapper's `__filename` / `__dirname` parameter names; keep wrapper internals on private names, synthesize local CJS bindings only for plain CommonJS sources, and compute transformed `import.meta.url` from `pathToFileURL(__secureExecFilename).href`
 - `ModuleAccessFileSystem` must treat host-absolute package asset paths derived from `import.meta.url`, `__filename`, or `realpath()` as part of the same read-only projected `node_modules` closure when they canonicalize inside the configured overlay; Pi and similar SDKs walk to sibling `package.json`/README/theme assets that way
+- `ModuleAccessFileSystem` also has to include pnpm virtual-store dependency symlink targets reachable from projected packages; package-internal `imports` like Chalk's `#ansi-styles` resolve into those sibling `.pnpm/*/node_modules/*` targets rather than staying under the top-level package root
 
 ## Virtual Kernel Architecture
 

native/v8-runtime/src/execution.rs

@@ -564,7 +564,7 @@ struct ModuleResolveState {
     bridge_ctx: *const BridgeCallContext,
     /// identity_hash → resource_name for referrer lookup
     module_names: HashMap<NonZeroI32, String>,
-    /// resolved_path → Global<Module> cache
+    /// resolved_path and referrer-qualified request keys → Global<Module> cache
     module_cache: HashMap<String, v8::Global<v8::Module>>,
 }
 
@@ -594,6 +594,10 @@ thread_local! {
     static PENDING_MODULE_EVALUATION: RefCell<Option<PendingModuleEvaluation>> = const { RefCell::new(None) };
 }
 
+fn module_request_cache_key(specifier: &str, referrer_name: &str) -> String {
+    format!("{}\0{}", referrer_name, specifier)
+}
+
 #[cfg_attr(test, allow(dead_code))]
 pub fn clear_module_state() {
     MODULE_RESOLVE_STATE.with(|cell| {
@@ -936,12 +940,13 @@ fn extract_uncached_imports(
         let data = requests.get(scope, i).unwrap();
         let request: v8::Local<v8::ModuleRequest> = data.cast();
         let specifier = request.get_specifier().to_rust_string_lossy(scope);
+        let cache_key = module_request_cache_key(&specifier, referrer_name);
 
-        // Skip if already cached (by specifier or resolved path)
+        // Skip if already cached for this referrer-qualified request.
         let already_cached = MODULE_RESOLVE_STATE.with(|cell| {
             let borrow = cell.borrow();
             let state = borrow.as_ref().unwrap();
-            state.module_cache.contains_key(&specifier)
+            state.module_cache.contains_key(&cache_key)
         });
         if !already_cached {
             uncached.push((specifier, referrer_name.to_string()));
@@ -973,8 +978,8 @@ fn prefetch_module_imports(
             let local_mod = v8::Local::new(scope, global_mod);
             let imports = extract_uncached_imports(scope, local_mod, referrer);
             for (spec, ref_name) in imports {
-                // Deduplicate within this batch
-                if !batch.iter().any(|(s, _)| s == &spec) {
+                // Deduplicate within this batch by the full request identity.
+                if !batch.iter().any(|(s, r)| s == &spec && r == &ref_name) {
                     batch.push((spec, ref_name));
                 }
             }
@@ -1048,7 +1053,10 @@ fn prefetch_module_imports(
                             .insert(resolved_path.clone(), global.clone());
                         state
                             .module_cache
-                            .insert(batch[i].0.clone(), global.clone());
+                            .insert(
+                                module_request_cache_key(&batch[i].0, &batch[i].1),
+                                global.clone(),
+                            );
                     }
                 });
 
@@ -1065,11 +1073,13 @@ fn resolve_or_compile_module<'s>(
     specifier_str: &str,
     referrer_name: &str,
 ) -> Option<v8::Local<'s, v8::Module>> {
-    // Phase 1: Check cache by specifier.
+    let request_cache_key = module_request_cache_key(specifier_str, referrer_name);
+
+    // Phase 1: Check cache by referrer-qualified request.
     let cached_global = MODULE_RESOLVE_STATE.with(|cell| {
         let borrow = cell.borrow();
         let state = borrow.as_ref()?;
-        state.module_cache.get(specifier_str).cloned()
+        state.module_cache.get(&request_cache_key).cloned()
     });
     if let Some(cached) = cached_global {
         return Some(v8::Local::new(scope, &cached));
@@ -1130,7 +1140,7 @@ fn resolve_or_compile_module<'s>(
             let global = v8::Global::new(scope, module);
             state
                 .module_cache
-                .insert(specifier_str.to_string(), global.clone());
+                .insert(request_cache_key.clone(), global.clone());
             state.module_cache.insert(resolved_path, global);
         }
     });

packages/core/isolate-runtime/src/inject/require-setup.ts

@@ -13,6 +13,60 @@
               });
             };
 
+      if (typeof globalThis.global === 'undefined') {
+        globalThis.global = globalThis;
+      }
+
+      if (typeof globalThis.RegExp === 'function' && !globalThis.RegExp.__secureExecRgiEmojiCompat) {
+        const NativeRegExp = globalThis.RegExp;
+        const RGI_EMOJI_PATTERN = '^\\p{RGI_Emoji}$';
+        const RGI_EMOJI_BASE_CLASS = '[\\u{00A9}\\u{00AE}\\u{203C}\\u{2049}\\u{2122}\\u{2139}\\u{2194}-\\u{21AA}\\u{231A}-\\u{23FF}\\u{24C2}\\u{25AA}-\\u{27BF}\\u{2934}-\\u{2935}\\u{2B05}-\\u{2B55}\\u{3030}\\u{303D}\\u{3297}\\u{3299}\\u{1F000}-\\u{1FAFF}]';
+        const RGI_EMOJI_KEYCAP = '[#*0-9]\\uFE0F?\\u20E3';
+        const RGI_EMOJI_FALLBACK_SOURCE =
+          '^(?:' +
+          RGI_EMOJI_KEYCAP +
+          '|\\p{Regional_Indicator}{2}|' +
+          RGI_EMOJI_BASE_CLASS +
+          '(?:\\uFE0F|\\u200D(?:' +
+          RGI_EMOJI_KEYCAP +
+          '|' +
+          RGI_EMOJI_BASE_CLASS +
+          ')|[\\u{1F3FB}-\\u{1F3FF}])*)$';
+        try {
+          new NativeRegExp(RGI_EMOJI_PATTERN, 'v');
+        } catch (error) {
+          if (String(error && error.message || error).includes('RGI_Emoji')) {
+            function CompatRegExp(pattern, flags) {
+              const normalizedPattern =
+                pattern instanceof NativeRegExp && flags === undefined
+                  ? pattern.source
+                  : String(pattern);
+              const normalizedFlags =
+                flags === undefined
+                  ? (pattern instanceof NativeRegExp ? pattern.flags : '')
+                  : String(flags);
+              try {
+                return new NativeRegExp(pattern, flags);
+              } catch (innerError) {
+                if (normalizedPattern === RGI_EMOJI_PATTERN && normalizedFlags === 'v') {
+                  return new NativeRegExp(RGI_EMOJI_FALLBACK_SOURCE, 'u');
+                }
+                throw innerError;
+              }
+            }
+            Object.setPrototypeOf(CompatRegExp, NativeRegExp);
+            CompatRegExp.prototype = NativeRegExp.prototype;
+            Object.defineProperty(CompatRegExp.prototype, 'constructor', {
+              value: CompatRegExp,
+              writable: true,
+              configurable: true,
+            });
+            CompatRegExp.__secureExecRgiEmojiCompat = true;
+            globalThis.RegExp = CompatRegExp;
+          }
+        }
+      }
+
       if (
         typeof globalThis.AbortController === 'undefined' ||
         typeof globalThis.AbortSignal === 'undefined' ||
@@ -1603,6 +1657,31 @@
             };
           }
 
+          if (typeof _cryptoRandomUUID !== 'undefined' && typeof result.randomUUID !== 'function') {
+            result.randomUUID = function randomUUID(options) {
+              if (options !== undefined) {
+                if (options === null || typeof options !== 'object') {
+                  throw createInvalidArgTypeError('options', 'of type object', options);
+                }
+                if (
+                  Object.prototype.hasOwnProperty.call(options, 'disableEntropyCache') &&
+                  typeof options.disableEntropyCache !== 'boolean'
+                ) {
+                  throw createInvalidArgTypeError(
+                    'options.disableEntropyCache',
+                    'of type boolean',
+                    options.disableEntropyCache,
+                  );
+                }
+              }
+              var uuid = _cryptoRandomUUID.applySync(undefined, []);
+              if (typeof uuid !== 'string') {
+                throw new Error('invalid host uuid');
+              }
+              return uuid;
+            };
+          }
+
           // Overlay host-backed pbkdf2/pbkdf2Sync
           if (typeof _cryptoPbkdf2 !== 'undefined') {
             function createPbkdf2ArgTypeError(name, value) {
@@ -3772,6 +3851,16 @@
           return globalThis.process;
         }
 
+        // Special handling for v8. Some CommonJS dependencies require it
+        // before the mutable module cache has been copied into the local cache.
+        if (name === 'v8') {
+          if (__internalModuleCache['v8']) return __internalModuleCache['v8'];
+          const v8Module = globalThis._moduleCache?.v8 || {};
+          __internalModuleCache['v8'] = v8Module;
+          _debugRequire('loaded', name, 'v8-special');
+          return v8Module;
+        }
+
         // Special handling for async_hooks.
         // This provides the minimum API surface needed by tracing libraries.
         if (name === 'async_hooks') {

packages/core/src/generated/isolate-runtime.ts

@@ -108,8 +108,9 @@
   "dependencies": {
     "@secure-exec/core": "workspace:*",
     "@secure-exec/v8": "workspace:*",
-    "esbuild": "^0.27.1",
+    "cjs-module-lexer": "^2.1.0",
     "es-module-lexer": "^1.7.0",
+    "esbuild": "^0.27.1",
     "node-stdlib-browser": "^1.3.1"
   },
   "devDependencies": {