@tencent-ai/agent-harness 0.1.0 → 0.1.1

package/lib/integration/executor-supervisor.js

@@ -15,6 +15,7 @@ const trace_context_1 = require("#agent-harness-executor/trace-context");
 const process_runtime_context_js_1 = require("../effect-runtime/process-runtime-context.js");
 const errors_js_1 = require("../internal/errors.js");
 const bounded_json_js_1 = require("../protocol/bounded-json.js");
+const node_runtime_js_1 = require("../runtime/node-runtime.js");
 const process_containment_js_1 = require("../runtime/process-containment.js");
 const process_tree_js_1 = require("../runtime/process-tree.js");
 const windows_job_js_1 = require("../runtime/windows-job.js");
@@ -103,7 +104,7 @@ const CHILD_ENV_ALLOWLIST = Object.freeze([
     'https_proxy',
     'no_proxy',
 ]);
-function createExecutorChildEnvironment(source = process.env) {
+function createExecutorChildEnvironment(source = process.env, nodeRuntime = (0, node_runtime_js_1.resolveNodeRuntimeLaunch)()) {
     const environment = {
         AGENT_HARNESS_PRIVATE_EXECUTOR: '1',
     };
@@ -113,7 +114,7 @@ function createExecutorChildEnvironment(source = process.env) {
             environment[name] = value;
         }
     }
-    return environment;
+    return (0, node_runtime_js_1.applyNodeRuntimeEnvironment)(environment, nodeRuntime);
 }
 function createExecutorWindowsJobSpawnSpec(entryPath, forkOptions, launcherOptions = {}) {
     const { execArgv = process.execArgv, execPath = process.execPath, silent: _silent, ...spawnOptions } = forkOptions;
@@ -163,19 +164,21 @@ function resolveOptions(options) {
         requested: options.allowStdio ?? true,
         windowsJobObjectAttached: options.windowsJobObjectAttached,
     });
+    const nodeRuntime = options.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)();
     return {
         allowStdio: stdioContainment.allowStdio,
         childEntryPath: options.childEntryPath ?? defaultChildEntryPath(),
         closeTimeoutMs: positive(options.closeTimeoutMs, DEFAULT_CLOSE_TIMEOUT_MS, 'closeTimeoutMs'),
         containment: options.containment ?? new process_containment_js_1.CodeBuddyProcessContainment(),
         crashWindowMs: positive(options.crashWindowMs, DEFAULT_CRASH_WINDOW_MS, 'crashWindowMs'),
-        environment: createExecutorChildEnvironment(options.environment),
+        environment: createExecutorChildEnvironment(options.environment, nodeRuntime),
         healthIntervalMs: nonNegative(options.healthIntervalMs, DEFAULT_HEALTH_INTERVAL_MS, 'healthIntervalMs'),
         healthTimeoutMs: positive(options.healthTimeoutMs, DEFAULT_HEALTH_TIMEOUT_MS, 'healthTimeoutMs'),
         instanceId: options.instanceId ?? (0, node_crypto_1.randomUUID)(),
         maxCrashes: positive(options.maxCrashes, DEFAULT_MAX_CRASHES, 'maxCrashes'),
         maxPendingRequestBytes: positive(options.maxPendingRequestBytes, DEFAULT_MAX_PENDING_REQUEST_BYTES, 'maxPendingRequestBytes'),
         maxPendingRequests: positive(options.maxPendingRequests, DEFAULT_MAX_PENDING_REQUESTS, 'maxPendingRequests'),
+        nodeRuntime,
         onElicitation: options.onElicitation,
         ...(options.onFailure === undefined
             ? {}
@@ -650,6 +653,7 @@ class ExecutorProcessSupervisor {
             detached: this.options.platform !== 'win32',
             env: this.options.environment,
             execArgv: [],
+            execPath: this.options.nodeRuntime.executable,
             serialization: 'json',
             stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
         });

package/lib/integration/stdio-guardian-child.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const node_child_process_1 = require("node:child_process");
+const posix_process_snapshot_js_1 = require("../runtime/posix-process-snapshot.js");
 const process_tree_js_1 = require("../runtime/process-tree.js");
 const stdio_guardian_capture_js_1 = require("./stdio-guardian-capture.js");
 const stdio_guardian_protocol_js_1 = require("./stdio-guardian-protocol.js");
@@ -61,28 +61,18 @@ function signalProcessGroup(processGroupId, signal) {
 function delay(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
-function captureOwnedProcessIds(rootPid) {
-    const spec = (0, process_tree_js_1.buildPosixProcessListSpec)(process.platform);
-    return new Promise((resolve, reject) => {
-        (0, node_child_process_1.execFile)(spec.command, [...spec.args], {
-            encoding: 'utf8',
-            maxBuffer: 1024 * 1024,
-            timeout: PROCESS_TREE_CAPTURE_TIMEOUT_MS,
-            windowsHide: true,
-        }, (error, stdout) => {
-            if (error) {
-                reject(error);
-                return;
-            }
-            resolve((0, process_tree_js_1.collectPosixOwnedProcessIds)(typeof stdout === 'string' ? stdout : '', rootPid, process.pid));
-        });
+function captureOwnedProcessIds(rootPid, ownershipId) {
+    return (0, posix_process_snapshot_js_1.capturePosixOwnedProcessIds)(rootPid, process.platform, {
+        excludedPid: process.pid,
+        ownershipId,
+        timeoutMs: PROCESS_TREE_CAPTURE_TIMEOUT_MS,
     });
 }
-async function captureOwnedProcessIdsReliably(rootPid) {
+async function captureOwnedProcessIdsReliably(rootPid, ownershipId) {
     let lastError;
     for (let attempt = 1; attempt <= PROCESS_TREE_CAPTURE_ATTEMPTS; attempt += 1) {
         try {
-            return await captureOwnedProcessIds(rootPid);
+            return await captureOwnedProcessIds(rootPid, ownershipId);
         }
         catch (error) {
             lastError = error;
@@ -138,11 +128,11 @@ async function cleanProcessGroup(options, anchorPid, knownProcessIds) {
         && ((0, process_tree_js_1.processExists)(anchorPid)
             || (0, process_tree_js_1.processGroupExists)(options.targetProcessGroupId))) {
         try {
-            // `ps` can transiently exceed its deadline while the Harness is
+            // A snapshot can transiently exceed its deadline while the Harness is
             // concurrently reaping several process trees. Cleanup still fails
             // closed if every bounded attempt fails, but one busy snapshot no
             // longer trips the process-wide containment fuse.
-            const processIds = await captureOwnedProcessIdsReliably(anchorPid);
+            const processIds = await captureOwnedProcessIdsReliably(anchorPid, options.targetProcessGroupId);
             // Terminal capture must union with periodic observations. A
             // forkpty/setsid descendant can be reparented between the last
             // periodic snapshot and this final owner-rooted snapshot; replacing
@@ -249,7 +239,7 @@ async function runGuardianChild() {
             return true;
         }
         try {
-            const processIds = await captureOwnedProcessIdsReliably(rootPid);
+            const processIds = await captureOwnedProcessIdsReliably(rootPid, options.targetProcessGroupId);
             // Replace rather than accumulate: long-lived guardians must not
             // retain an exited PID after the OS has reused it for an unrelated
             // process.

package/lib/integration/stdio-guardian.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import { type NodeRuntimeLaunch } from '../runtime/node-runtime.js';
 import { CodeBuddyProcessContainment } from '../runtime/process-containment.js';
 import { type StdioMcpGuardianSnapshotMode } from './stdio-guardian-protocol.js';
 export type StdioMcpContainmentDecision = {
@@ -23,7 +24,7 @@ export interface ResolveStdioMcpContainmentOptions {
  * stdio stays disabled unless a real Job Object owner has already attached.
  */
 export declare function resolveStdioMcpContainment(options: ResolveStdioMcpContainmentOptions): StdioMcpContainmentDecision;
-export declare function createStdioMcpGuardianEnvironment(): NodeJS.ProcessEnv;
+export declare function createStdioMcpGuardianEnvironment(nodeRuntime?: NodeRuntimeLaunch): NodeJS.ProcessEnv;
 export interface PosixStdioMcpGuardianOptions {
     readonly childEntryPath?: string;
     readonly containment?: CodeBuddyProcessContainment;

package/lib/integration/stdio-guardian.js

@@ -10,6 +10,7 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const errors_js_1 = require("../internal/errors.js");
+const node_runtime_js_1 = require("../runtime/node-runtime.js");
 const process_containment_js_1 = require("../runtime/process-containment.js");
 const process_tree_js_1 = require("../runtime/process-tree.js");
 const windows_job_js_1 = require("../runtime/windows-job.js");
@@ -54,10 +55,10 @@ function resolveStdioMcpContainment(options) {
         reason: 'windows_job_object_required',
     };
 }
-function createStdioMcpGuardianEnvironment() {
-    return {
+function createStdioMcpGuardianEnvironment(nodeRuntime = (0, node_runtime_js_1.resolveNodeRuntimeLaunch)()) {
+    return (0, node_runtime_js_1.applyNodeRuntimeEnvironment)({
         AGENT_HARNESS_PRIVATE_STDIO_GUARDIAN: '1',
-    };
+    }, nodeRuntime);
 }
 function positiveInteger(value, fallback, name) {
     const resolved = value ?? fallback;
@@ -495,12 +496,13 @@ async function attachPosixStdioMcpGuardian(input) {
         String(options.pollIntervalMs),
         options.containmentMode,
     ];
+    const nodeRuntime = (0, node_runtime_js_1.resolveNodeRuntimeLaunch)();
     let child;
     try {
-        child = options.spawnGuardian(process.execPath, args, {
+        child = options.spawnGuardian(nodeRuntime.executable, args, {
             cwd: node_path_1.default.dirname(options.childEntryPath),
             detached: true,
-            env: createStdioMcpGuardianEnvironment(),
+            env: createStdioMcpGuardianEnvironment(nodeRuntime),
             stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true,
         });

package/lib/runtime/agent-harness.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess, spawn, type StdioOptions } from 'node:child_process';
+import { type NodeRuntimeLaunch } from './node-runtime.js';
 export interface ResolveAgentHarnessBinPathOptions {
     exists?: (candidate: string) => boolean;
     readFile?: (candidate: string) => string;
@@ -11,6 +12,7 @@ export interface CreateAgentHarnessSpawnSpecOptions {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     nodeExecutable?: string;
+    nodeRuntime?: NodeRuntimeLaunch;
     processEnv?: NodeJS.ProcessEnv;
 }
 export interface AgentHarnessSpawnSpec {
@@ -24,5 +26,5 @@ export interface SpawnAgentHarnessOptions extends CreateAgentHarnessSpawnSpecOpt
     stdio?: StdioOptions;
 }
 export declare function resolveAgentHarnessBinPath({ exists, readFile, resolvePackageJson, }?: ResolveAgentHarnessBinPathOptions): string;
-export declare function createAgentHarnessSpawnSpec({ binPath, cliArgs, cwd, env, nodeExecutable, processEnv, }?: CreateAgentHarnessSpawnSpecOptions): AgentHarnessSpawnSpec;
+export declare function createAgentHarnessSpawnSpec({ binPath, cliArgs, cwd, env, nodeExecutable, nodeRuntime, processEnv, }?: CreateAgentHarnessSpawnSpecOptions): AgentHarnessSpawnSpec;
 export declare function spawnAgentHarness({ spawnImpl, stdio, ...options }?: SpawnAgentHarnessOptions): ChildProcess;

package/lib/runtime/agent-harness.js

@@ -40,6 +40,7 @@ const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const codebuddy_code_js_1 = require("./codebuddy-code.js");
+const node_runtime_js_1 = require("./node-runtime.js");
 function resolveAgentHarnessBinPath({ exists = fs.existsSync, readFile = candidate => fs.readFileSync(candidate, 'utf8'), 
 // Resolve relative to this module instead of either the workspace or
 // published package name. pnpm publishConfig.name intentionally makes
@@ -64,15 +65,23 @@ resolvePackageJson = () => path.resolve(__dirname, '../../package.json'), } = {}
     }
     return binPath;
 }
-function createAgentHarnessSpawnSpec({ binPath = resolveAgentHarnessBinPath(), cliArgs = [], cwd, env, nodeExecutable = process.execPath, processEnv, } = {}) {
+function createAgentHarnessSpawnSpec({ binPath = resolveAgentHarnessBinPath(), cliArgs = [], cwd, env, nodeExecutable, nodeRuntime, processEnv, } = {}) {
     if (cliArgs.some(argument => argument.includes('\0'))) {
         throw new Error('Agent Harness CLI arguments must not contain NUL bytes');
     }
+    if (nodeExecutable !== undefined
+        && nodeRuntime !== undefined
+        && nodeExecutable !== nodeRuntime.executable) {
+        throw new Error('Agent Harness Node runtime executable is ambiguous');
+    }
+    const runtime = nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)({
+        ...(nodeExecutable === undefined ? {} : { executable: nodeExecutable }),
+    });
     return {
-        command: nodeExecutable,
+        command: runtime.executable,
         args: [binPath, ...cliArgs],
         cwd,
-        env: (0, codebuddy_code_js_1.buildCodeBuddyCodeEnv)(env, processEnv),
+        env: (0, codebuddy_code_js_1.buildCodeBuddyCodeEnv)(env, processEnv, { nodeRuntime: runtime }),
     };
 }
 function spawnAgentHarness({ spawnImpl = node_child_process_1.spawn, stdio = ['pipe', 'pipe', 'inherit'], ...options } = {}) {

package/lib/runtime/codebuddy-code.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess, spawn, type StdioOptions } from 'node:child_process';
+import { type NodeRuntimeLaunch } from './node-runtime.js';
 import type { ProductLaunchSnapshot } from './product-manager.js';
 export declare const CODEBUDDY_CODE_PACKAGE_NAME = "@tencent-ai/codebuddy-code";
 /** Package manifest for the CodeBuddy runtime embedded in this Harness build. */
@@ -21,6 +22,8 @@ export interface CreateCodeBuddyCodeSpawnSpecOptions {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     nodeExecutable?: string;
+    /** Coherent executable/environment contract for an injected runtime. */
+    nodeRuntime?: NodeRuntimeLaunch;
     processEnv?: NodeJS.ProcessEnv;
     /** Shared Host only: retain process-owned managed login sources. */
     preserveManagedAuthenticationEnvironment?: boolean;
@@ -67,9 +70,10 @@ export declare function buildCodeBuddyCodeArgs(productLaunch?: ProductLaunchSnap
  * explicitly approved overrides are applied.
  */
 export declare function buildCodeBuddyCodeEnv(env?: NodeJS.ProcessEnv, processEnv?: NodeJS.ProcessEnv, options?: {
+    readonly nodeRuntime?: NodeRuntimeLaunch;
     readonly preserveManagedAuthenticationEnvironment?: boolean;
 }): NodeJS.ProcessEnv;
-export declare function createCodeBuddyCodeSpawnSpec({ binPath, cwd, env, nodeExecutable, processEnv, preserveManagedAuthenticationEnvironment, prewarmId, productLaunch, sessionEnabledPlugins, }?: CreateCodeBuddyCodeSpawnSpecOptions): CodeBuddyCodeSpawnSpec;
+export declare function createCodeBuddyCodeSpawnSpec({ binPath, cwd, env, nodeExecutable, nodeRuntime, processEnv, preserveManagedAuthenticationEnvironment, prewarmId, productLaunch, sessionEnabledPlugins, }?: CreateCodeBuddyCodeSpawnSpecOptions): CodeBuddyCodeSpawnSpec;
 /**
  * Starts one private native-ACP-v2 CodeBuddy executor.
  *

package/lib/runtime/codebuddy-code.js

@@ -46,6 +46,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const session_plugin_settings_js_1 = require("../protocol/session-plugin-settings.js");
 const client_identity_js_1 = require("./client-identity.js");
+const node_runtime_js_1 = require("./node-runtime.js");
 const product_launch_js_1 = require("./product-launch.js");
 exports.CODEBUDDY_CODE_PACKAGE_NAME = '@tencent-ai/codebuddy-code';
 /** Package manifest for the CodeBuddy runtime embedded in this Harness build. */
@@ -181,16 +182,24 @@ function buildCodeBuddyCodeEnv(env = {}, processEnv = process.env, options = {})
         // them after this fallback-disable switch.
         result.CODEBUDDY_API_KEY_DISABLED = '1';
     }
-    return result;
+    return (0, node_runtime_js_1.applyNodeRuntimeEnvironment)(result, options.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)());
 }
-function createCodeBuddyCodeSpawnSpec({ binPath = resolveCodeBuddyCodeBinPath(), cwd, env, nodeExecutable = process.execPath, processEnv, preserveManagedAuthenticationEnvironment, prewarmId, productLaunch, sessionEnabledPlugins, } = {}) {
+function createCodeBuddyCodeSpawnSpec({ binPath = resolveCodeBuddyCodeBinPath(), cwd, env, nodeExecutable, nodeRuntime, processEnv, preserveManagedAuthenticationEnvironment, prewarmId, productLaunch, sessionEnabledPlugins, } = {}) {
     if (prewarmId !== undefined
         && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(prewarmId)) {
         throw new Error('Private CodeBuddy prewarm id is invalid');
     }
     const resolvedProductLaunch = resolveProductLaunch(productLaunch);
+    if (nodeExecutable !== undefined
+        && nodeRuntime !== undefined
+        && nodeExecutable !== nodeRuntime.executable) {
+        throw new Error('CodeBuddy Node runtime executable is ambiguous');
+    }
+    const runtime = nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)({
+        ...(nodeExecutable === undefined ? {} : { executable: nodeExecutable }),
+    });
     return {
-        command: nodeExecutable,
+        command: runtime.executable,
         args: [
             binPath,
             ...buildCodeBuddyCodeArgs(resolvedProductLaunch, sessionEnabledPlugins),
@@ -200,6 +209,7 @@ function createCodeBuddyCodeSpawnSpec({ binPath = resolveCodeBuddyCodeBinPath(),
         ],
         cwd,
         env: buildCodeBuddyCodeEnv(env, processEnv, {
+            nodeRuntime: runtime,
             preserveManagedAuthenticationEnvironment,
         }),
     };

package/lib/runtime/codebuddy-prewarm-pool.d.ts

@@ -1,6 +1,7 @@
 import { type SessionEnabledPlugins } from '../protocol/session-plugin-settings.js';
 import type { AgentPrewarmObserver } from './codebuddy-prewarm-observability.js';
 import type { CodeBuddyProcessSupervisor, CodeBuddyProcessSupervisorOptions } from './codebuddy-process.js';
+import { type NodeRuntimeLaunch } from './node-runtime.js';
 import type { CodeBuddyProcessContainment } from './process-containment.js';
 import type { ProductLaunchSnapshot } from './product-manager.js';
 export interface CodeBuddyPrewarmKey {
@@ -19,6 +20,7 @@ export interface CreateCodeBuddyPrewarmKeyOptions {
     readonly cwd: string;
     readonly env?: NodeJS.ProcessEnv;
     readonly nodeExecutablePath?: string;
+    readonly nodeRuntime?: NodeRuntimeLaunch;
     readonly preserveManagedAuthenticationEnvironment?: boolean;
     readonly processEnv?: NodeJS.ProcessEnv;
     readonly productLaunch: ProductLaunchSnapshot;

package/lib/runtime/codebuddy-prewarm-pool.js

@@ -41,6 +41,7 @@ const node_crypto_1 = require("node:crypto");
 const path = __importStar(require("node:path"));
 const session_plugin_settings_js_1 = require("../protocol/session-plugin-settings.js");
 const codebuddy_code_js_1 = require("./codebuddy-code.js");
+const node_runtime_js_1 = require("./node-runtime.js");
 function createCodeBuddyPrewarmKey(options) {
     if (!path.isAbsolute(options.cliArtifactPath)) {
         throw new Error('Private CodeBuddy CLI artifact path must be absolute');
@@ -51,12 +52,18 @@ function createCodeBuddyPrewarmKey(options) {
     if (options.cliVersion.trim().length === 0 || options.cliVersion.length > 256) {
         throw new Error('Private CodeBuddy CLI version is invalid');
     }
+    const nodeRuntime = options.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)({
+        ...(options.nodeExecutablePath === undefined
+            ? {}
+            : { executable: options.nodeExecutablePath }),
+    });
     const key = {
         canonicalCwd: path.resolve(options.cwd),
         cliArtifactPath: path.resolve(options.cliArtifactPath),
         cliVersion: options.cliVersion,
-        nodeExecutablePath: path.resolve(options.nodeExecutablePath ?? process.execPath),
+        nodeExecutablePath: path.resolve(nodeRuntime.executable),
         preImportEnvironmentFingerprint: fingerprintEnvironment((0, codebuddy_code_js_1.buildCodeBuddyCodeEnv)(options.env, options.processEnv, {
+            nodeRuntime,
             preserveManagedAuthenticationEnvironment: options.preserveManagedAuthenticationEnvironment,
         })),
         productBootstrapFile: path.resolve(options.productLaunch.bootstrapFile),
@@ -112,6 +119,7 @@ function assertPrimeMatchesKey(key, options) {
         cwd: options.cwd,
         env: options.env,
         nodeExecutablePath: options.nodeExecutable,
+        nodeRuntime: options.nodeRuntime,
         preserveManagedAuthenticationEnvironment: options.preserveManagedAuthenticationEnvironment,
         processEnv: options.processEnv,
         productLaunch: options.productLaunch,

package/lib/runtime/codebuddy-process.d.ts

@@ -71,7 +71,8 @@ export interface CodeBuddyProcessSupervisorOptions extends Omit<SpawnCodeBuddyCo
      */
     parentDeathGuard?: boolean;
     /**
-     * `process-tree` also tracks forkpty/setsid descendants through `ps`.
+     * `process-tree` also tracks forkpty/setsid descendants through an OS
+     * process snapshot.
      * Use `process-group` only for runtimes that cannot create detached
      * sessions, so cleanup can rely entirely on the detached child group.
      */

package/lib/runtime/codebuddy-process.js

@@ -41,6 +41,7 @@ const stdio_guardian_js_1 = require("../integration/stdio-guardian.js");
 const errors_js_1 = require("../internal/errors.js");
 const codebuddy_code_js_1 = require("./codebuddy-code.js");
 const posix_contained_process_js_1 = require("./posix-contained-process.js");
+const posix_process_snapshot_js_1 = require("./posix-process-snapshot.js");
 const process_containment_js_1 = require("./process-containment.js");
 const process_tree_js_1 = require("./process-tree.js");
 const DEFAULT_STDERR_TAIL_BYTES = 64 * 1024;
@@ -259,25 +260,6 @@ function createCodeBuddyNdJsonStream(output, input, maximumLineBytes, onInputFai
     });
     return { readable, writable };
 }
-function runProcessUtility(command, args, timeoutMs) {
-    if (timeoutMs <= 0) {
-        return Promise.reject(new Error(`${command} process utility deadline expired`));
-    }
-    return new Promise((resolve, reject) => {
-        (0, node_child_process_1.execFile)(command, [...args], {
-            encoding: 'utf8',
-            maxBuffer: 1024 * 1024,
-            timeout: Math.max(1, Math.min(500, timeoutMs)),
-            windowsHide: true,
-        }, (error, stdout) => {
-            if (error) {
-                reject(error);
-                return;
-            }
-            resolve(typeof stdout === 'string' ? stdout : '');
-        });
-    });
-}
 function terminateWindowsProcessTree(rootPid, force, timeoutMs = 2_000) {
     if (process.platform !== 'win32') {
         return Promise.resolve(false);
@@ -303,9 +285,10 @@ async function listOwnedProcessTree(rootPid, platform, timeoutMs = 500) {
     if (platform === 'win32') {
         return [];
     }
-    const spec = (0, process_tree_js_1.buildPosixProcessListSpec)(platform);
-    const output = await runProcessUtility(spec.command, spec.args, timeoutMs);
-    return (0, process_tree_js_1.collectPosixOwnedProcessIds)(output, rootPid, process.pid);
+    return (0, posix_process_snapshot_js_1.capturePosixOwnedProcessIds)(rootPid, platform, {
+        excludedPid: process.pid,
+        timeoutMs,
+    });
 }
 function requirePipe(value, name) {
     if (!value) {

package/lib/runtime/codebuddy-resource-management.d.ts

@@ -12,6 +12,7 @@ import type { RuntimeLifecycleRecorder } from '../telemetry/index.js';
 import type { CodeBuddyProcessTimeouts } from './codebuddy-process.js';
 import { type CodeBuddyResourceProcessDependencies, CodeBuddyResourceProcessSupervisor, type CodeBuddyResourceProcessSupervisorOptions } from './codebuddy-resource-process.js';
 import { type CodeBuddyResourceRecoveryFuseOptions } from './codebuddy-resource-recovery.js';
+import { type NodeRuntimeLaunch } from './node-runtime.js';
 import { CodeBuddyProcessContainment } from './process-containment.js';
 import type { ProductLaunchSnapshot } from './product-manager.js';
 export interface CreateCodeBuddyHostClientOptions {
@@ -22,6 +23,7 @@ export interface CreateCodeBuddyHostClientOptions {
     /** @deprecated Resource management no longer performs HTTP through fetch. */
     fetchImpl?: typeof fetch;
     nodeExecutable?: string;
+    nodeRuntime?: NodeRuntimeLaunch;
     processDependencies?: CodeBuddyResourceProcessDependencies;
     processEntryPath?: string;
     processFactory?: (options: CodeBuddyResourceProcessSupervisorOptions) => CodeBuddyResourceProcessSupervisor;

package/lib/runtime/codebuddy-resource-management.js

@@ -58,6 +58,7 @@ const codebuddy_code_js_1 = require("./codebuddy-code.js");
 const codebuddy_resource_process_js_1 = require("./codebuddy-resource-process.js");
 const codebuddy_resource_process_protocol_js_1 = require("./codebuddy-resource-process-protocol.js");
 const codebuddy_resource_recovery_js_1 = require("./codebuddy-resource-recovery.js");
+const node_runtime_js_1 = require("./node-runtime.js");
 const process_containment_js_1 = require("./process-containment.js");
 const product_launch_js_1 = require("./product-launch.js");
 const DEFAULT_READY_TIMEOUT_MS = 60_000;
@@ -2571,6 +2572,16 @@ class CodeBuddyHostClientImpl {
         const password = (0, node_crypto_1.randomBytes)(24).toString('base64url');
         const runtimeInstanceId = (0, node_crypto_1.randomUUID)();
         const productLaunch = this.resolveProductLaunch();
+        if (this.options.nodeExecutable !== undefined
+            && this.options.nodeRuntime !== undefined
+            && this.options.nodeExecutable !== this.options.nodeRuntime.executable) {
+            throw new Error('CodeBuddy Host Node runtime executable is ambiguous');
+        }
+        const nodeRuntime = this.options.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)({
+            ...(this.options.nodeExecutable === undefined
+                ? {}
+                : { executable: this.options.nodeExecutable }),
+        });
         const socket = await createCodeBuddyResourceSocket(platform);
         const environment = (0, codebuddy_code_js_1.buildCodeBuddyCodeEnv)({
             ...this.options.env,
@@ -2580,6 +2591,7 @@ class CodeBuddyHostClientImpl {
             CODEBUDDY_RUNTIME_INSTANCE_ID: runtimeInstanceId,
             DISABLE_AUTOUPDATER: 'true',
         }, this.options.processEnv, {
+            nodeRuntime,
             preserveManagedAuthenticationEnvironment: true,
         });
         const binPath = this.options.binPath ?? (0, codebuddy_code_js_1.resolveCodeBuddyCodeBinPath)();
@@ -2595,7 +2607,7 @@ class CodeBuddyHostClientImpl {
                 containment: this.containment,
                 cwd: this.cwd,
                 dependencies: this.options.processDependencies,
-                nodeExecutable: this.options.nodeExecutable,
+                nodeRuntime,
                 processEnv: this.options.processEnv,
                 processRuntime: this.processRuntime,
                 recordLifecycle: this.options.recordLifecycle,

package/lib/runtime/codebuddy-resource-process.d.ts

@@ -4,6 +4,7 @@ import type { HarnessProcessRuntimeHandle } from '../effect-runtime/process-runt
 import { type PosixStdioMcpGuardian, type PosixStdioMcpGuardianOptions } from '../integration/stdio-guardian.js';
 import type { RuntimeLifecycleRecorder } from '../telemetry/index.js';
 import { type CodeBuddyResourceProcessBootstrapV1, type CodeBuddyResourceProcessRequest } from './codebuddy-resource-process-protocol.js';
+import { type NodeRuntimeLaunch } from './node-runtime.js';
 import { CodeBuddyProcessContainment } from './process-containment.js';
 import { type ResolveWindowsJobLauncherPathOptions } from './windows-job.js';
 export type CodeBuddyResourceProcessState = 'idle' | 'starting' | 'running' | 'closing' | 'closed' | 'failed';
@@ -29,6 +30,7 @@ export interface CodeBuddyResourceProcessSupervisorOptions {
     readonly cwd: string;
     readonly dependencies?: CodeBuddyResourceProcessDependencies;
     readonly nodeExecutable?: string;
+    readonly nodeRuntime?: NodeRuntimeLaunch;
     /** Ambient system environment used only for the inert pre-containment stub. */
     readonly processEnv?: NodeJS.ProcessEnv;
     /** @internal Process-owned runtime for this child Scope. */
@@ -44,7 +46,7 @@ export interface CodeBuddyResourceWindowsJobSpawnSpec {
     readonly command: string;
     readonly options: SpawnOptions;
 }
-export declare function createCodeBuddyResourceStubEnvironment(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function createCodeBuddyResourceStubEnvironment(source?: NodeJS.ProcessEnv, nodeRuntime?: NodeRuntimeLaunch): NodeJS.ProcessEnv;
 /**
  * Wraps one inert Resource stub in a strict nested Job while retaining Node's
  * inherited IPC descriptor. The returned ChildProcess represents the native
@@ -54,6 +56,7 @@ export declare function createCodeBuddyResourceWindowsJobSpawnSpec(childEntryPat
     readonly cwd: string;
     readonly environment: NodeJS.ProcessEnv;
     readonly nodeExecutable?: string;
+    readonly nodeRuntime?: NodeRuntimeLaunch;
 }, launcherOptions?: ResolveWindowsJobLauncherPathOptions): CodeBuddyResourceWindowsJobSpawnSpec;
 export declare class CodeBuddyResourceProcessSupervisor extends EventEmitter {
     private readonly bootstrap;
@@ -70,7 +73,7 @@ export declare class CodeBuddyResourceProcessSupervisor extends EventEmitter {
     private failure?;
     private guardian?;
     private guardianPromise?;
-    private readonly nodeExecutable;
+    private readonly nodeRuntime;
     private readonly pendingShutdownIds;
     private readonly processEnv;
     private readonly processRuntime;

package/lib/runtime/codebuddy-resource-process.js

@@ -43,6 +43,7 @@ const path = __importStar(require("node:path"));
 const stdio_guardian_js_1 = require("../integration/stdio-guardian.js");
 const errors_js_1 = require("../internal/errors.js");
 const codebuddy_resource_process_protocol_js_1 = require("./codebuddy-resource-process-protocol.js");
+const node_runtime_js_1 = require("./node-runtime.js");
 const process_containment_js_1 = require("./process-containment.js");
 const process_tree_js_1 = require("./process-tree.js");
 const windows_job_js_1 = require("./windows-job.js");
@@ -71,7 +72,7 @@ const STUB_ENVIRONMENT_ALLOWLIST = Object.freeze([
     'https_proxy',
     'no_proxy',
 ]);
-function createCodeBuddyResourceStubEnvironment(source = process.env) {
+function createCodeBuddyResourceStubEnvironment(source = process.env, nodeRuntime = (0, node_runtime_js_1.resolveNodeRuntimeLaunch)()) {
     const environment = {
         [RESOURCE_CHILD_MARKER]: '1',
     };
@@ -81,7 +82,7 @@ function createCodeBuddyResourceStubEnvironment(source = process.env) {
             environment[name] = value;
         }
     }
-    return environment;
+    return (0, node_runtime_js_1.applyNodeRuntimeEnvironment)(environment, nodeRuntime);
 }
 /**
  * Wraps one inert Resource stub in a strict nested Job while retaining Node's
@@ -89,16 +90,26 @@ function createCodeBuddyResourceStubEnvironment(source = process.env) {
  * Job owner; lifecycle messages travel directly between Harness and target.
  */
 function createCodeBuddyResourceWindowsJobSpawnSpec(childEntryPath, options, launcherOptions = {}) {
+    if (options.nodeExecutable !== undefined
+        && options.nodeRuntime !== undefined
+        && options.nodeExecutable !== options.nodeRuntime.executable) {
+        throw new Error('CodeBuddy Resource Node runtime executable is ambiguous');
+    }
+    const nodeRuntime = options.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)({
+        ...(options.nodeExecutable === undefined
+            ? {}
+            : { executable: options.nodeExecutable }),
+    });
     const launch = (0, windows_job_js_1.createWindowsJobChildLaunchSpec)({
         args: [childEntryPath],
-        command: options.nodeExecutable ?? process.execPath,
+        command: nodeRuntime.executable,
         ...launcherOptions,
     });
     return {
         ...launch,
         options: {
             cwd: options.cwd,
-            env: options.environment,
+            env: (0, node_runtime_js_1.applyNodeRuntimeEnvironment)(options.environment, nodeRuntime),
             serialization: 'json',
             stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
             windowsHide: true,
@@ -206,7 +217,16 @@ class CodeBuddyResourceProcessSupervisor extends node_events_1.EventEmitter {
             spawnChild: options.dependencies?.spawnChild
                 ?? ((command, args, spawnOptions) => (0, node_child_process_1.spawn)(command, [...args], spawnOptions)),
         };
-        this.nodeExecutable = options.nodeExecutable ?? process.execPath;
+        if (options.nodeExecutable !== undefined
+            && options.nodeRuntime !== undefined
+            && options.nodeExecutable !== options.nodeRuntime.executable) {
+            throw new Error('CodeBuddy Resource Node runtime executable is ambiguous');
+        }
+        this.nodeRuntime = options.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)({
+            ...(options.nodeExecutable === undefined
+                ? {}
+                : { executable: options.nodeExecutable }),
+        });
         this.processEnv = options.processEnv ?? process.env;
         this.processRuntime = options.processRuntime;
         this.recordLifecycleObserver = options.recordLifecycle;
@@ -300,7 +320,7 @@ class CodeBuddyResourceProcessSupervisor extends node_events_1.EventEmitter {
         }
         const { openResourceProcessChildScope } = await import('../effect-runtime/resource-process-scope.mjs');
         this.assertStartupOpen();
-        const stubEnvironment = createCodeBuddyResourceStubEnvironment(this.processEnv);
+        const stubEnvironment = createCodeBuddyResourceStubEnvironment(this.processEnv, this.nodeRuntime);
         try {
             const child = this.spawnStub(stubEnvironment);
             this.child = child;
@@ -451,11 +471,11 @@ class CodeBuddyResourceProcessSupervisor extends node_events_1.EventEmitter {
             const spec = createCodeBuddyResourceWindowsJobSpawnSpec(this.childEntryPath, {
                 cwd: this.cwd,
                 environment,
-                nodeExecutable: this.nodeExecutable,
+                nodeRuntime: this.nodeRuntime,
             }, this.windowsLauncher);
             return this.dependencies.spawnChild(spec.command, spec.args, spec.options);
         }
-        return this.dependencies.spawnChild(this.nodeExecutable, [this.childEntryPath], {
+        return this.dependencies.spawnChild(this.nodeRuntime.executable, [this.childEntryPath], {
             cwd: this.cwd,
             detached: true,
             env: environment,