agentroam 0.2.0-preview.8 → 0.2.0-preview.9

package/dist/codex-runtime-manager.js

@@ -0,0 +1,293 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, chmod, mkdir, mkdtemp, open, rename, rm, stat, } from "node:fs/promises";
+import { delimiter, isAbsolute, relative, resolve, win32 } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const CODEX_RUNTIME_VERSION = "0.153.0";
+const CODEX_PACKAGE = `@openai/codex@${CODEX_RUNTIME_VERSION}`;
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const DEFAULT_LOCK_WAIT_MS = 190_000;
+const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
+const defaultDependencies = {
+    async run(command, args, timeoutMs) {
+        try {
+            const { stdout, stderr } = await execFileAsync(command, args, {
+                encoding: "utf8",
+                timeout: timeoutMs,
+                maxBuffer: 4 * 1024 * 1024,
+                windowsHide: true,
+            });
+            return { stdout, stderr };
+        }
+        catch (error) {
+            const value = error;
+            const details = [value.message, value.stderr?.trim(), value.stdout?.trim()]
+                .filter(Boolean)
+                .join(": ");
+            throw new Error(details || "process failed", { cause: error });
+        }
+    },
+    sleep: (delayMs) => new Promise((resolveDelay) => setTimeout(resolveDelay, delayMs)),
+    now: () => Date.now(),
+};
+export async function resolveCodexRuntime(options) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const dependencies = { ...defaultDependencies, ...options.dependencies };
+    const explicit = environment.AGENT_CODEX_BIN?.trim();
+    if (explicit) {
+        const absolute = platform === "win32" ? win32.isAbsolute(explicit) : isAbsolute(explicit);
+        if (!absolute) {
+            throw new Error("AGENT_CODEX_BIN must be an absolute path");
+        }
+        return validateCodex(explicit, "explicit", platform, dependencies);
+    }
+    const global = await findCompatibleGlobalCodex(environment.PATH, platform, dependencies);
+    if (global)
+        return global;
+    const managedRoot = resolve(options.dataDir, "runtimes", "codex", CODEX_RUNTIME_VERSION);
+    const managed = await validateManagedRuntime(managedRoot, options.target, platform, dependencies);
+    if (managed)
+        return managed;
+    options.onProgress?.(`Installing managed Codex ${CODEX_RUNTIME_VERSION}...`);
+    return installManagedCodex({
+        ...options,
+        environment,
+        platform,
+        dependencies,
+        managedRoot,
+    });
+}
+export async function resolveNpmExecutor(options = {}) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const canAccess = options.canAccess ?? pathAccessible;
+    const npmExecPath = environment.npm_execpath?.trim();
+    const npmExecPathIsAbsolute = npmExecPath
+        && (platform === "win32" ? win32.isAbsolute(npmExecPath) : isAbsolute(npmExecPath));
+    if (npmExecPath && npmExecPathIsAbsolute && await canAccess(npmExecPath)) {
+        return {
+            command: options.nodeExecutable ?? process.execPath,
+            argsPrefix: [npmExecPath],
+        };
+    }
+    const names = platform === "win32" ? ["npm.cmd", "npm.exe", "npm"] : ["npm"];
+    const pathDelimiter = platform === "win32" ? ";" : delimiter;
+    for (const directory of (environment.PATH ?? "").split(pathDelimiter).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = platform === "win32" ? win32.resolve(directory, name) : resolve(directory, name);
+            if (!(await canAccess(candidate)))
+                continue;
+            if (platform === "win32" && name === "npm.cmd") {
+                const npmCliCandidates = [
+                    win32.resolve(directory, "node_modules", "npm", "bin", "npm-cli.js"),
+                    win32.resolve(directory, "..", "node_modules", "npm", "bin", "npm-cli.js"),
+                ];
+                for (const npmCliPath of npmCliCandidates) {
+                    if (await canAccess(npmCliPath)) {
+                        return {
+                            command: options.nodeExecutable ?? process.execPath,
+                            argsPrefix: [npmCliPath],
+                        };
+                    }
+                }
+                continue;
+            }
+            return { command: candidate, argsPrefix: [] };
+        }
+    }
+    throw new Error("Codex runtime installer unavailable: npm was not found");
+}
+export function managedCodexBinaryCandidates(runtimeRoot, target) {
+    const platformInfo = codexPlatformInfo(target);
+    const vendorRoot = resolve(runtimeRoot, "node_modules", "@openai", platformInfo.packageName, "vendor", platformInfo.vendorTarget);
+    return [
+        resolve(vendorRoot, "bin", platformInfo.executable),
+        resolve(vendorRoot, "codex", platformInfo.executable),
+        resolve(vendorRoot, platformInfo.executable),
+    ];
+}
+export function parseCodexVersion(output) {
+    const match = output.match(/(?:^|\s)(\d+\.\d+\.\d+)(?:\s|$)/);
+    return match?.[1] ?? null;
+}
+async function findCompatibleGlobalCodex(pathValue, platform, dependencies) {
+    const names = platform === "win32" ? ["codex.exe", "codex"] : ["codex"];
+    const pathDelimiter = platform === "win32" ? ";" : delimiter;
+    for (const directory of (pathValue ?? "").split(pathDelimiter).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = platform === "win32" ? win32.resolve(directory, name) : resolve(directory, name);
+            if (!(await pathAccessible(candidate, platform !== "win32")))
+                continue;
+            try {
+                return await validateCodex(candidate, "global", platform, dependencies);
+            }
+            catch {
+                // An incompatible user installation is left untouched; try managed Codex.
+            }
+        }
+    }
+    return null;
+}
+async function installManagedCodex(options) {
+    const parent = resolve(options.dataDir, "runtimes", "codex");
+    const lockPath = `${options.managedRoot}.lock`;
+    const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
+    const staleLockMs = options.staleLockMs ?? DEFAULT_STALE_LOCK_MS;
+    await mkdir(parent, { recursive: true });
+    const lock = await acquireInstallLock(lockPath, options.managedRoot, options.target, options.platform, options.dependencies, lockWaitMs, staleLockMs);
+    if (lock.completed)
+        return lock.completed;
+    let temporaryRoot = null;
+    try {
+        const existing = await validateManagedRuntime(options.managedRoot, options.target, options.platform, options.dependencies);
+        if (existing)
+            return existing;
+        temporaryRoot = await mkdtemp(resolve(parent, `.${CODEX_RUNTIME_VERSION}-${process.pid}-`));
+        const npm = await resolveNpmExecutor({
+            environment: options.environment,
+            platform: options.platform,
+            nodeExecutable: options.nodeExecutable,
+        });
+        await options.dependencies.run(npm.command, [
+            ...npm.argsPrefix,
+            "install",
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+            `--registry=${NPM_REGISTRY}`,
+            "--prefix",
+            temporaryRoot,
+            CODEX_PACKAGE,
+        ], 180_000);
+        const temporary = await validateManagedRuntime(temporaryRoot, options.target, options.platform, options.dependencies);
+        if (!temporary) {
+            throw new Error(`Codex runtime validation failed after installing ${CODEX_PACKAGE}`);
+        }
+        await rename(temporaryRoot, options.managedRoot);
+        temporaryRoot = null;
+        const installed = await validateManagedRuntime(options.managedRoot, options.target, options.platform, options.dependencies);
+        if (!installed)
+            throw new Error("Codex runtime validation failed after activation");
+        return installed;
+    }
+    catch (error) {
+        const concurrent = await validateManagedRuntime(options.managedRoot, options.target, options.platform, options.dependencies);
+        if (concurrent)
+            return concurrent;
+        throw new Error(`Unable to install managed Codex ${CODEX_RUNTIME_VERSION}: ${describeError(error)}`, {
+            cause: error,
+        });
+    }
+    finally {
+        if (temporaryRoot)
+            await rm(temporaryRoot, { recursive: true, force: true });
+        await lock.handle.close().catch(() => undefined);
+        await rm(lockPath, { force: true });
+    }
+}
+async function acquireInstallLock(lockPath, managedRoot, target, platform, dependencies, waitMs, staleMs) {
+    const deadline = dependencies.now() + waitMs;
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx", 0o600);
+            await handle.writeFile(`${process.pid}\n${dependencies.now()}\n`);
+            return { handle };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const completed = await validateManagedRuntime(managedRoot, target, platform, dependencies);
+            if (completed)
+                return { completed };
+            try {
+                const lockStat = await stat(lockPath);
+                if (dependencies.now() - lockStat.mtimeMs > staleMs) {
+                    await rm(lockPath, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (dependencies.now() >= deadline) {
+                throw new Error(`Timed out waiting for Codex runtime install lock: ${lockPath}`);
+            }
+            await dependencies.sleep(Math.min(250, Math.max(1, deadline - dependencies.now())));
+        }
+    }
+}
+async function validateManagedRuntime(runtimeRoot, target, platform, dependencies) {
+    for (const candidate of managedCodexBinaryCandidates(runtimeRoot, target)) {
+        if (!isWithin(runtimeRoot, candidate) || !(await pathAccessible(candidate)))
+            continue;
+        try {
+            if (platform !== "win32")
+                await chmod(candidate, 0o755);
+            return await validateCodex(candidate, "managed", platform, dependencies);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+async function validateCodex(executable, source, _platform, dependencies) {
+    if (!(await pathAccessible(executable))) {
+        throw new Error(`Codex executable not found: ${executable}`);
+    }
+    const versionResult = await dependencies.run(executable, ["--version"], 5_000);
+    const version = parseCodexVersion(`${versionResult.stdout}\n${versionResult.stderr}`);
+    if (!version)
+        throw new Error(`Unable to parse Codex version from ${executable}`);
+    if (version !== CODEX_RUNTIME_VERSION) {
+        throw new Error(`Codex ${version} at ${executable} is incompatible; AgentRoam requires ${CODEX_RUNTIME_VERSION}`);
+    }
+    try {
+        await dependencies.run(executable, ["app-server", "--help"], 5_000);
+    }
+    catch (error) {
+        throw new Error(`Codex app-server validation failed at ${executable}: ${describeError(error)}`, {
+            cause: error,
+        });
+    }
+    return { executable, version, source };
+}
+function codexPlatformInfo(target) {
+    if (target === "darwin-arm64") {
+        return {
+            packageName: "codex-darwin-arm64",
+            vendorTarget: "aarch64-apple-darwin",
+            executable: "codex",
+        };
+    }
+    if (target === "darwin-amd64") {
+        return {
+            packageName: "codex-darwin-x64",
+            vendorTarget: "x86_64-apple-darwin",
+            executable: "codex",
+        };
+    }
+    return {
+        packageName: "codex-win32-x64",
+        vendorTarget: "x86_64-pc-windows-msvc",
+        executable: "codex.exe",
+    };
+}
+async function pathAccessible(path, executable = false) {
+    try {
+        await access(path, executable ? constants.X_OK : constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isWithin(root, candidate) {
+    const fromRoot = relative(resolve(root), resolve(candidate));
+    return fromRoot !== "" && !fromRoot.startsWith("..") && !isAbsolute(fromRoot);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/codex-runtime-manager.test.js

@@ -0,0 +1,192 @@
+import { chmod, mkdtemp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, resolve, win32 } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CODEX_RUNTIME_VERSION, managedCodexBinaryCandidates, parseCodexVersion, resolveCodexRuntime, resolveNpmExecutor, } from "./codex-runtime-manager.js";
+const temporaryDirectories = [];
+afterEach(async () => {
+    await Promise.all(temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+describe("managed Codex runtime", () => {
+    it("parses the official version output", () => {
+        expect(parseCodexVersion("codex-cli 0.153.0")).toBe("0.153.0");
+        expect(parseCodexVersion("codex-cli next")).toBeNull();
+    });
+    it("uses a compatible explicit absolute executable first", async () => {
+        const root = await temporaryRoot();
+        const executable = await fakeExecutable(resolve(root, "codex"));
+        const run = vi.fn(async (_command, args) => ({
+            stdout: args[0] === "--version" ? "codex-cli 0.153.0\n" : "app-server help\n",
+            stderr: "",
+        }));
+        await expect(resolveCodexRuntime({
+            dataDir: resolve(root, "data"),
+            target: "darwin-arm64",
+            environment: { AGENT_CODEX_BIN: executable, PATH: "" },
+            platform: "darwin",
+            dependencies: { run },
+        })).resolves.toEqual({
+            executable,
+            version: CODEX_RUNTIME_VERSION,
+            source: "explicit",
+        });
+        expect(run.mock.calls.map((call) => call[1])).toEqual([["--version"], ["app-server", "--help"]]);
+    });
+    it("rejects an incompatible explicit executable instead of silently replacing it", async () => {
+        const root = await temporaryRoot();
+        const executable = await fakeExecutable(resolve(root, "codex"));
+        await expect(resolveCodexRuntime({
+            dataDir: resolve(root, "data"),
+            target: "darwin-arm64",
+            environment: { AGENT_CODEX_BIN: executable, PATH: "" },
+            platform: "darwin",
+            dependencies: {
+                run: async () => ({ stdout: "codex-cli 0.154.0\n", stderr: "" }),
+            },
+        })).rejects.toThrow("requires 0.153.0");
+    });
+    it("skips an incompatible PATH executable and reuses the managed runtime", async () => {
+        const root = await temporaryRoot();
+        const global = await fakeExecutable(resolve(root, "bin", "codex"));
+        const managedRoot = resolve(root, "data", "runtimes", "codex", CODEX_RUNTIME_VERSION);
+        const managed = await fakeExecutable(managedCodexBinaryCandidates(managedRoot, "darwin-arm64")[0]);
+        const run = vi.fn(async (command, args) => ({
+            stdout: args[0] === "--version"
+                ? command === global ? "codex-cli 0.152.0\n" : "codex-cli 0.153.0\n"
+                : "help\n",
+            stderr: "",
+        }));
+        await expect(resolveCodexRuntime({
+            dataDir: resolve(root, "data"),
+            target: "darwin-arm64",
+            environment: { PATH: resolve(root, "bin") },
+            platform: "darwin",
+            dependencies: { run },
+        })).resolves.toEqual({ executable: managed, version: CODEX_RUNTIME_VERSION, source: "managed" });
+        expect(run.mock.calls.some((call) => call[1].includes("install"))).toBe(false);
+    });
+    it("installs the locked official package into a versioned runtime directory", async () => {
+        const root = await temporaryRoot();
+        const npmExecPath = await fakeExecutable(resolve(root, "npm-cli.js"));
+        let installs = 0;
+        const run = vi.fn(async (command, args) => {
+            if (command === "/test/node" && args.includes("install")) {
+                installs += 1;
+                const prefix = args[args.indexOf("--prefix") + 1];
+                await fakeExecutable(managedCodexBinaryCandidates(prefix, "darwin-arm64")[0]);
+                expect(args).toContain("@openai/codex@0.153.0");
+                expect(args).toContain("--registry=https://registry.npmjs.org");
+                return { stdout: "installed", stderr: "" };
+            }
+            return {
+                stdout: args[0] === "--version" ? "codex-cli 0.153.0\n" : "help\n",
+                stderr: "",
+            };
+        });
+        const resolution = await resolveCodexRuntime({
+            dataDir: resolve(root, "data"),
+            target: "darwin-arm64",
+            environment: { PATH: "", npm_execpath: npmExecPath },
+            platform: "darwin",
+            nodeExecutable: "/test/node",
+            dependencies: { run },
+        });
+        expect(installs).toBe(1);
+        expect(resolution.executable).toContain(`/runtimes/codex/${CODEX_RUNTIME_VERSION}/`);
+        expect(resolution.source).toBe("managed");
+    });
+    it("serializes concurrent first-start installs", async () => {
+        const root = await temporaryRoot();
+        const npmExecPath = await fakeExecutable(resolve(root, "npm-cli.js"));
+        let installs = 0;
+        const run = async (command, args) => {
+            if (command === "/test/node" && args.includes("install")) {
+                installs += 1;
+                await new Promise((resolveDelay) => setTimeout(resolveDelay, 30));
+                const prefix = args[args.indexOf("--prefix") + 1];
+                await fakeExecutable(managedCodexBinaryCandidates(prefix, "darwin-arm64")[0]);
+                return { stdout: "installed", stderr: "" };
+            }
+            return {
+                stdout: args[0] === "--version" ? "codex-cli 0.153.0\n" : "help\n",
+                stderr: "",
+            };
+        };
+        const options = {
+            dataDir: resolve(root, "data"),
+            target: "darwin-arm64",
+            environment: { PATH: "", npm_execpath: npmExecPath },
+            platform: "darwin",
+            nodeExecutable: "/test/node",
+            dependencies: { run },
+        };
+        const [first, second] = await Promise.all([
+            resolveCodexRuntime(options),
+            resolveCodexRuntime(options),
+        ]);
+        expect(installs).toBe(1);
+        expect(second.executable).toBe(first.executable);
+    });
+    it("cleans temporary installs and the lock after npm failure", async () => {
+        const root = await temporaryRoot();
+        const npmExecPath = await fakeExecutable(resolve(root, "npm-cli.js"));
+        await expect(resolveCodexRuntime({
+            dataDir: resolve(root, "data"),
+            target: "darwin-arm64",
+            environment: { PATH: "", npm_execpath: npmExecPath },
+            platform: "darwin",
+            nodeExecutable: "/test/node",
+            dependencies: {
+                run: async () => { throw new Error("network unavailable"); },
+            },
+        })).rejects.toThrow("network unavailable");
+        expect(await readdir(resolve(root, "data", "runtimes", "codex"))).toEqual([]);
+    });
+});
+describe("Codex npm executor", () => {
+    it("runs npm_execpath through the current Node executable", async () => {
+        await expect(resolveNpmExecutor({
+            environment: { npm_execpath: "/tools/npm-cli.js", PATH: "" },
+            nodeExecutable: "/runtime/node",
+            canAccess: async (path) => path === "/tools/npm-cli.js",
+        })).resolves.toEqual({ command: "/runtime/node", argsPrefix: ["/tools/npm-cli.js"] });
+    });
+    it("finds a directly executable npm.exe on Windows PATH", async () => {
+        const expected = win32.resolve("C:\\tools", "npm.exe");
+        await expect(resolveNpmExecutor({
+            environment: { PATH: ["C:\\missing", "C:\\tools"].join(";") },
+            platform: "win32",
+            canAccess: async (path) => path === expected,
+        })).resolves.toEqual({ command: expected, argsPrefix: [] });
+    });
+    it("runs a standard Windows npm.cmd installation through npm-cli.js", async () => {
+        const npmCmd = win32.resolve("C:\\Program Files\\nodejs", "npm.cmd");
+        const npmCli = win32.resolve("C:\\Program Files\\nodejs", "node_modules", "npm", "bin", "npm-cli.js");
+        await expect(resolveNpmExecutor({
+            environment: { PATH: "C:\\Program Files\\nodejs" },
+            platform: "win32",
+            nodeExecutable: "C:\\Program Files\\nodejs\\node.exe",
+            canAccess: async (path) => path === npmCmd || path === npmCli,
+        })).resolves.toEqual({
+            command: "C:\\Program Files\\nodejs\\node.exe",
+            argsPrefix: [npmCli],
+        });
+    });
+    it("maps official macOS and Windows optional-package binaries", () => {
+        expect(managedCodexBinaryCandidates("/runtime", "darwin-arm64")[0])
+            .toContain("codex-darwin-arm64/vendor/aarch64-apple-darwin/bin/codex");
+        expect(managedCodexBinaryCandidates("/runtime", "windows-amd64")[0])
+            .toContain("codex-win32-x64/vendor/x86_64-pc-windows-msvc/bin/codex.exe");
+    });
+});
+async function temporaryRoot() {
+    const root = await mkdtemp(resolve(tmpdir(), "agentroam-codex-runtime-"));
+    temporaryDirectories.push(root);
+    return root;
+}
+async function fakeExecutable(path) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, "fake\n");
+    await chmod(path, 0o755);
+    return path;
+}

package/dist/install-script-contract.test.js

@@ -0,0 +1,41 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { describe, expect, it } from "vitest";
+import { MANAGED_NODE_VERSION, NODE_RUNTIME_ASSETS } from "./node-runtime-manager.js";
+import { AGENTROAM_VERSION } from "./platform-packages.js";
+const installRoot = resolve(import.meta.dirname, "../install");
+describe("standalone installer contracts", () => {
+    it("keeps the macOS installer aligned with the runtime manifest", async () => {
+        const scriptPath = resolve(installRoot, "install-agentroam.sh");
+        const script = await readFile(scriptPath, "utf8");
+        expect(script).toContain(`NODE_VERSION="${MANAGED_NODE_VERSION}"`);
+        expect(script).toContain(`AGENTROAM_VERSION="${AGENTROAM_VERSION}"`);
+        expect(script).toContain(NODE_RUNTIME_ASSETS["darwin-arm64"].archive);
+        expect(script).toContain(NODE_RUNTIME_ASSETS["darwin-arm64"].sha256);
+        expect(script).toContain("https://registry.npmjs.org");
+        expect(script).toContain("$HOME/.agentroam");
+        expect(script).toContain("$HOME/.local/bin");
+        expect(script).toContain('AGENTROAM_ROOT');
+        expect(script).toContain('AGENTROAM_INSTALL_SKIP_SERVICE');
+        expect(script).toContain('service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR"');
+        expect(script).toContain("refusing to expose the entire home directory implicitly");
+        expect(script).not.toMatch(/\b(?:brew|sudo|nvm|fnm|volta)\b/);
+        execFileSync("sh", ["-n", scriptPath]);
+    });
+    it("keeps the Windows installer aligned with the runtime manifest", async () => {
+        const script = await readFile(resolve(installRoot, "install-agentroam.ps1"), "utf8");
+        expect(script).toContain(`$NodeVersion = "${MANAGED_NODE_VERSION}"`);
+        expect(script).toContain(`$AgentRoamVersion = "${AGENTROAM_VERSION}"`);
+        expect(script).toContain(NODE_RUNTIME_ASSETS["windows-amd64"].archive);
+        expect(script).toContain(NODE_RUNTIME_ASSETS["windows-amd64"].sha256);
+        expect(script).toContain("https://registry.npmjs.org");
+        expect(script).toContain(".agentroam\\bin");
+        expect(script).toContain('[Environment]::SetEnvironmentVariable("Path", $UpdatedPath, "User")');
+        expect(script).toContain("$env:AGENTROAM_ROOT");
+        expect(script).toContain("$env:AGENTROAM_INSTALL_SKIP_SERVICE");
+        expect(script).toContain("service install --root $ServiceRoot --data-dir $DataDir");
+        expect(script).toContain("Refusing to expose the entire home directory implicitly");
+        expect(script).not.toMatch(/\b(?:winget|choco|scoop|Start-Process\s+.*RunAs)\b/i);
+    });
+});

package/dist/node-preflight.test.js

@@ -0,0 +1,109 @@
+import { EventEmitter } from "node:events";
+import { resolve } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+// @ts-expect-error The preflight intentionally remains plain ESM for Node 18 bootstrap.
+import { parsePreflightDataDir, runNodePreflight } from "../bin/node-preflight.mjs";
+describe("Node launcher preflight", () => {
+    it("passes through any Node 22 patch without installing", async () => {
+        const ensureNode = vi.fn();
+        await expect(runNodePreflight({ nodeVersion: "22.1.0", ensureNode })).resolves.toEqual({ handled: false });
+        expect(ensureNode).not.toHaveBeenCalled();
+    });
+    it.each(["18.20.0", "20.18.0", "24.0.0", "25.1.0"])("re-executes Node %s through the managed runtime", async (nodeVersion) => {
+        const child = fakeChild(0, null);
+        const ensureNode = vi.fn(async () => ({ executable: "/managed/node", version: "22.22.0" }));
+        const spawnChild = vi.fn((_executable, _args, _options) => child);
+        const result = await runNodePreflight({
+            argv: ["doctor", "--data-dir", "./custom"],
+            nodeVersion,
+            platform: "darwin",
+            arch: "arm64",
+            launcherPath: "/launcher/agentroam.mjs",
+            environment: { PATH: "" },
+            ensureNode,
+            findSystemNode22: async () => null,
+            spawnChild,
+            processHost: fakeProcessHost(),
+        });
+        expect(result).toEqual({ handled: true, exitCode: 0, signal: null });
+        expect(ensureNode).toHaveBeenCalledWith(expect.objectContaining({
+            dataDir: resolve("./custom"),
+            target: "darwin-arm64",
+        }));
+        expect(spawnChild).toHaveBeenCalledWith("/managed/node", ["/launcher/agentroam.mjs", "doctor", "--data-dir", "./custom"], expect.objectContaining({
+            stdio: "inherit",
+            env: expect.objectContaining({ AGENTROAM_MANAGED_NODE: "22.22.0" }),
+        }));
+    });
+    it("reuses another visible system Node 22", async () => {
+        const ensureNode = vi.fn();
+        const spawnChild = vi.fn((_executable, _args, _options) => fakeChild(7, null));
+        await expect(runNodePreflight({
+            argv: ["version"],
+            nodeVersion: "25.0.0",
+            platform: "win32",
+            arch: "x64",
+            environment: { PATH: "" },
+            findSystemNode22: async () => "C:\\Node22\\node.exe",
+            ensureNode,
+            spawnChild,
+            processHost: fakeProcessHost(),
+        })).resolves.toMatchObject({ handled: true, exitCode: 7 });
+        expect(ensureNode).not.toHaveBeenCalled();
+        expect(spawnChild.mock.calls[0][0]).toBe("C:\\Node22\\node.exe");
+    });
+    it("rejects a failed managed re-entry instead of looping", async () => {
+        await expect(runNodePreflight({
+            nodeVersion: "25.0.0",
+            environment: { AGENTROAM_MANAGED_NODE: "22.22.0" },
+        })).rejects.toMatchObject({ message: expect.stringContaining("re-entry failed"), exitCode: 2 });
+    });
+    it("directs old Node versions to the standalone installer", async () => {
+        await expect(runNodePreflight({
+            nodeVersion: "16.20.0",
+            platform: "darwin",
+            environment: {},
+        })).rejects.toThrow("install-agentroam.sh");
+        await expect(runNodePreflight({
+            nodeVersion: "12.0.0",
+            platform: "win32",
+            environment: {},
+        })).rejects.toThrow("install-agentroam.ps1");
+    });
+    it("forwards termination signals and propagates a child signal", async () => {
+        const processHost = fakeProcessHost();
+        const child = new EventEmitter();
+        child.kill = vi.fn();
+        const running = runNodePreflight({
+            nodeVersion: "20.0.0",
+            platform: "darwin",
+            arch: "arm64",
+            environment: { PATH: "" },
+            findSystemNode22: async () => "/node22",
+            spawnChild: () => child,
+            processHost,
+        });
+        await new Promise((resolveTurn) => setImmediate(resolveTurn));
+        processHost.emit("SIGTERM");
+        expect(child.kill).toHaveBeenCalledWith("SIGTERM");
+        child.emit("exit", null, "SIGTERM");
+        await expect(running).resolves.toEqual({ handled: true, exitCode: null, signal: "SIGTERM" });
+    });
+    it("parses data directory overrides before the CLI import", () => {
+        expect(parsePreflightDataDir(["start", "--data-dir", "./data"], {}, "/home/me")).toBe(resolve("./data"));
+        expect(parsePreflightDataDir([], { AGENTROAM_DATA_DIR: "/custom" }, "/home/me")).toBe("/custom");
+        expect(parsePreflightDataDir([], {}, "/home/me")).toBe(resolve("/home/me", ".agentroam"));
+        expect(() => parsePreflightDataDir(["--data-dir"], {}, "/home/me")).toThrow("missing value");
+    });
+});
+function fakeChild(exitCode, signal) {
+    const child = new EventEmitter();
+    child.kill = vi.fn();
+    setImmediate(() => child.emit("exit", exitCode, signal));
+    return child;
+}
+function fakeProcessHost() {
+    const host = new EventEmitter();
+    host.stderr = { write: vi.fn() };
+    return host;
+}