agentroam 0.2.0-preview.16 → 0.2.0-preview.18

package/dist/device-pairing.js

@@ -0,0 +1,146 @@
+import { createInterface } from "node:readline/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { renderQr } from "./qr.js";
+/** Resolve a private local descriptor; never send the administrative token to a tunnel URL. */
+export async function pairingAdmin(dataDir, action, body, options = {}) {
+    const request = options.request ?? fetch;
+    const directory = options.registry ?? process.env.AGENTROAM_DISCOVERY_DIR ?? join(homedir(), ".agentroam", "services");
+    const names = await readdir(directory).catch((error) => { if (error.code === "ENOENT")
+        return []; throw error; });
+    const candidates = [];
+    for (const name of names.filter((name) => name.endsWith(".json"))) {
+        try {
+            const d = JSON.parse(await readFile(join(directory, name), "utf8"));
+            const url = new URL(d.url);
+            if (d.protocol !== 1 || typeof d.instanceId !== "string" || !Number.isSafeInteger(d.pid) || d.pid <= 0 || ![resolve(dataDir), resolve(dataDir, "data")].includes(d.dataDir) || !/^[a-f0-9]{64}$/.test(d.token))
+                continue;
+            if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/" || url.username || url.password || url.search || url.hash)
+                continue;
+            const response = await request(new URL("/api/desktop/identity", url), { headers: { "x-agentroam-desktop-token": d.token }, redirect: "error", signal: AbortSignal.timeout(1500) });
+            if (!response.ok)
+                continue;
+            const identity = await response.json();
+            if (identity.protocol === 1 && identity.instanceId === d.instanceId && identity.dataDir === d.dataDir)
+                candidates.push(d);
+        }
+        catch { /* Stale descriptors are expected after a process crash. */ }
+    }
+    if (candidates.length !== 1)
+        throw new Error(candidates.length ? "多个服务使用此数据目录，请先停止多余实例" : "未找到运行中的 AgentRoam 服务，请先启动服务或指定 --data-dir");
+    const d = candidates[0];
+    const readOnly = ["devices", "requests", "audit"].includes(action);
+    const response = await request(new URL(`/api/pairing/admin/${action}`, d.url), {
+        method: readOnly ? "GET" : "POST",
+        headers: { "x-agentroam-desktop-token": d.token, "content-type": "application/json" },
+        ...(readOnly ? {} : { body: JSON.stringify(body ?? {}) }),
+        redirect: "error", signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) {
+        const message = response.status === 423 ? "远程访问已锁定，请先执行 agentroam unlock" : response.status === 410 ? "请求已过期或已处理" : response.status === 409 ? "核对短语不匹配" : `设备授权操作失败 (HTTP ${response.status})`;
+        throw new Error(message);
+    }
+    return response.json();
+}
+export function terminalText(value) { return value.replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ""); }
+export function pairingQrPayload(accessUrl, grant) {
+    const url = new URL(accessUrl);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || !/^[A-Za-z0-9_-]{43}$/.test(grant))
+        throw new Error("无效的配对地址或授权凭据");
+    return `${url.origin}/pair#pair=${grant}`;
+}
+export async function printPairingCode(dataDir, log = console.log, options = {}) {
+    const result = await pairingAdmin(dataDir, "code");
+    log(`配对码：${result.code.slice(0, 4)} ${result.code.slice(4)}`);
+    log("5 分钟内有效，仅可使用一次。手机输入后仍需在电脑上确认核对短语。");
+    if ((options.qr ?? true) && (options.interactive ?? process.stdout.isTTY)) {
+        const accessUrl = options.accessUrl ?? await readFile(join(dataDir, "tunnel.url"), "utf8").then((value) => value.trim(), () => null);
+        if (accessUrl) {
+            // Validate the public address before minting an invitation. Never persist the grant.
+            pairingQrPayload(accessUrl, "a".repeat(43));
+            const { grant } = await pairingAdmin(dataDir, "qr");
+            log("手机扫码直接连接（5 分钟、一次有效，请勿分享截图）：");
+            log(await renderQr(pairingQrPayload(accessUrl, grant)));
+        }
+        else
+            log("生成 App 授权二维码：agentroam pair --url <手机可访问的服务器地址>");
+    }
+    if (options.interactive ?? (process.stdin.isTTY && process.stdout.isTTY)) {
+        await watchPairingApproval(dataDir, result.expiresAt, { log, signal: options.signal });
+    }
+    else
+        log("查看请求：agentroam approvals；批准：agentroam approve <请求ID> --phrase <手机核对短语>");
+}
+/** Watch only while the printed code is usable; approval gets the request's own deadline. */
+export async function watchPairingApproval(dataDir, codeExpiresAt, options = {}) {
+    const admin = options.admin ?? pairingAdmin;
+    const log = options.log ?? console.log;
+    log("等待手机发起连接…");
+    while (Date.now() < codeExpiresAt && !options.signal?.aborted) {
+        const result = await admin(dataDir, "requests");
+        if (result.locked) {
+            log("远程访问已锁定");
+            return;
+        }
+        if (result.qrClaimed) {
+            log("App 已扫码连接。");
+            return;
+        }
+        const request = result.requests.find((r) => r.created >= codeExpiresAt - 300_000);
+        if (request) {
+            log(`新设备请求连接：${terminalText(request.name)}`);
+            log(`请求 ID：${request.id}`);
+            log(`核对短语：${request.phrase}`);
+            const approved = await (options.confirm ?? confirmOnTerminal)(request, options.signal);
+            if (options.signal?.aborted)
+                return;
+            if (Date.now() >= request.expires) {
+                log("授权请求已过期，请重新配对。");
+                return;
+            }
+            await admin(dataDir, approved ? "approve" : "deny", { id: request.id, ...(approved ? { phrase: request.phrase } : {}) });
+            log(approved ? "已批准，手机将自动进入。" : "已拒绝此设备。");
+            return;
+        }
+        try {
+            await delay(800, undefined, { signal: options.signal });
+        }
+        catch {
+            return;
+        }
+    }
+    if (!options.signal?.aborted)
+        log("配对码已过期，执行 agentroam pair 生成新码。");
+}
+async function confirmOnTerminal(request, signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(0, request.expires - Date.now()));
+    const input = createInterface({ input: process.stdin, output: process.stdout });
+    input.once("SIGINT", () => controller.abort());
+    try {
+        const answer = await input.question("确认手机显示相同短语？输入 yes 批准，其他输入拒绝：", { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal });
+        return answer.trim().toLowerCase() === "yes";
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+        input.close();
+    }
+}
+export async function installedDataDir(fallback) {
+    if (resolve(fallback) !== resolve(homedir(), ".agentroam"))
+        return fallback;
+    try {
+        const config = JSON.parse(await readFile(join(homedir(), ".agentroam", "service", "config.json"), "utf8"));
+        return typeof config.dataDir === "string" ? resolve(config.dataDir) : fallback;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return fallback;
+        throw error;
+    }
+}

package/dist/device-pairing.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from "vitest";
+import { parseArgs } from "./args.js";
+import { pairingQrPayload, watchPairingApproval } from "./device-pairing.js";
+describe("local approval commands", () => {
+    it("encodes a separate QR invitation and validates the server URL", () => {
+        expect(parseArgs(["pair", "--url", "https://phone.example/web"]).pairingUrl).toBe("https://phone.example/web");
+        const link = new URL(pairingQrPayload("https://phone.example/web", "a".repeat(43)));
+        expect(link.origin + link.pathname).toBe("https://phone.example/pair");
+        expect(link.search).toBe("");
+        expect(link.hash).toBe(`#pair=${"a".repeat(43)}`);
+        expect(() => pairingQrPayload("https://user:password@phone.example", "a".repeat(43))).toThrow();
+    });
+    const id = "12345678-1234-1234-1234-123456789abc";
+    it("requires a request ID and matching phrase for explicit approval", () => {
+        expect(() => parseArgs(["approve", id])).toThrow(/phrase/);
+        expect(parseArgs(["approve", id, "--phrase", "松林·月光·1234"])).toMatchObject({ approvalRequestId: id, approvalPhrase: "松林·月光·1234" });
+        for (const command of ["lock", "unlock", "audit", "approvals"])
+            expect(parseArgs([command]).command).toBe(command);
+        expect(parseArgs(["deny", id]).approvalRequestId).toBe(id);
+    });
+    it.each([true, false])("displays the phrase and sends only the local user's %s decision", async (approve) => {
+        const now = Date.now();
+        const request = { id, name: "Phone\u001b[31m", phrase: "松林·月光·1234", created: now, expires: now + 300_000, status: "waiting" };
+        const admin = vi.fn().mockResolvedValueOnce({ requests: [request], locked: false }).mockResolvedValueOnce({ status: approve ? "approved" : "denied" });
+        const log = vi.fn();
+        const confirm = vi.fn(async () => approve);
+        await watchPairingApproval("/tmp/unused", now + 300_000, { admin: admin, log, confirm });
+        expect(log).toHaveBeenCalledWith(`核对短语：${request.phrase}`);
+        expect(confirm).toHaveBeenCalledWith(request, undefined);
+        expect(admin).toHaveBeenLastCalledWith("/tmp/unused", approve ? "approve" : "deny", { id, ...(approve ? { phrase: request.phrase } : {}) });
+        expect(log.mock.calls.flat().join("\n")).not.toContain("\u001b");
+    });
+});

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

@@ -3,14 +3,36 @@ 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";
+import { MINIMUM_NODE_VERSION, isSupportedNodeVersion } from "../bin/runtime-policy.mjs";
 const installRoot = resolve(import.meta.dirname, "../install");
 describe("standalone installer contracts", () => {
+    it.skipIf(process.platform !== "darwin" || process.arch !== "arm64")("allows installation from home and keeps a compatible active Node", async () => {
+        const root = await mkdtemp(resolve(process.env.TMPDIR || "/tmp", "agentroam-active-node-"));
+        try {
+            const homeDir = resolve(root, "home");
+            const workspace = resolve(root, "workspace");
+            const activeBin = resolve(root, "active bin");
+            const nvmRoot = resolve(root, "nvm");
+            await Promise.all([mkdir(homeDir), mkdir(workspace), mkdir(activeBin), mkdir(nvmRoot)]);
+            const expected = await fakeNode(resolve(activeBin, "node"), "24.13.0");
+            await fakeNode(resolve(nvmRoot, "versions/node/v26.0.0/bin/node"), "26.0.0");
+            const output = execFileSync("/bin/sh", [resolve(installRoot, "install-agentroam.sh")], {
+                cwd: homeDir, encoding: "utf8",
+                env: { ...process.env, HOME: homeDir, NVM_DIR: nvmRoot, PATH: `${activeBin}:/usr/bin:/bin`,
+                    AGENTROAM_BOOTSTRAP_TEST: "1", AGENTROAM_BOOTSTRAP_NODE_DISCOVERY_ONLY: "1" },
+            });
+            expect(output.trim()).toBe(expected);
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+        }
+    });
     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(`MINIMUM_NODE_VERSION="${MINIMUM_NODE_VERSION}"`);
+        expect(script).toContain('AGENTROAM_VERSION_REQUEST="${AGENTROAM_VERSION:-preview}"');
         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");
@@ -19,8 +41,8 @@ describe("standalone installer contracts", () => {
         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).toContain("find_nvm_node_22");
+        expect(script).toContain('SERVICE_ROOT="$PWD"');
+        expect(script).toContain("find_nvm_node");
         expect(script).toContain('${NVM_DIR:-}');
         expect(script).not.toMatch(/\b(?:brew|sudo|fnm|volta)\b/);
         execFileSync("sh", ["-n", scriptPath]);
@@ -28,7 +50,8 @@ describe("standalone installer contracts", () => {
     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(`$MinimumNodeVersion = "${MINIMUM_NODE_VERSION}"`);
+        expect(script).toContain('$AgentRoamVersionRequest = if ($env:AGENTROAM_VERSION) { $env:AGENTROAM_VERSION } else { "preview" }');
         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");
@@ -37,12 +60,12 @@ describe("standalone installer contracts", () => {
         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).toContain("Find-NvmNode22");
+        expect(script).toContain("(Get-Location).Path");
+        expect(script).toContain("Find-NvmNode");
         expect(script).toContain("$env:NVM_HOME");
         expect(script).not.toMatch(/\b(?:winget|choco|scoop|Start-Process\s+.*RunAs)\b/i);
     });
-    it.skipIf(process.platform !== "darwin" || process.arch !== "arm64")("selects the highest installed NVM Node 22 without changing the active version", async () => {
+    it.skipIf(process.platform !== "darwin" || process.arch !== "arm64")("selects the highest compatible NVM Node without changing the active version", async () => {
         const root = await mkdtemp(resolve(process.env.TMPDIR || "/tmp", "agentroam-nvm-discovery-"));
         try {
             const home = resolve(root, "home");
@@ -52,7 +75,8 @@ describe("standalone installer contracts", () => {
             await Promise.all([mkdir(home), mkdir(workspace), mkdir(activeBin), mkdir(nvmRoot)]);
             await fakeNode(resolve(activeBin, "node"), "20.19.0");
             await fakeNode(resolve(nvmRoot, "versions/node/v22.3.0/bin/node"), "22.3.0");
-            const expected = await fakeNode(resolve(nvmRoot, "versions/node/v22.22.2/bin/node"), "22.22.2");
+            await fakeNode(resolve(nvmRoot, "versions/node/v22.22.2/bin/node"), "22.22.2");
+            const expected = await fakeNode(resolve(nvmRoot, "versions/node/v25.8.0/bin/node"), "25.8.0");
             await fakeNode(resolve(nvmRoot, "versions/node/v22.99.0/bin/node"), "21.99.0");
             const output = execFileSync("/bin/sh", [resolve(installRoot, "install-agentroam.sh")], {
                 cwd: workspace,
@@ -67,13 +91,13 @@ describe("standalone installer contracts", () => {
                 },
             });
             expect(output.trim().split("\n").at(-1)).toBe(expected);
-            expect(output).toContain("Using Node.js v22.22.2 from NVM");
+            expect(output).toContain("Using Node.js v25.8.0 from NVM");
         }
         finally {
             await rm(root, { recursive: true, force: true });
         }
     });
-    it.skipIf(process.platform !== "win32" || Number(process.versions.node.split(".")[0]) !== 22)("selects an installed nvm-windows Node 22 when the active PATH has no Node", async () => {
+    it.skipIf(process.platform !== "win32" || !isSupportedNodeVersion(process.versions.node))("selects a compatible nvm-windows Node when the active PATH has no Node", async () => {
         const root = await mkdtemp(resolve(process.env.TEMP || process.env.TMP || "C:\\Windows\\Temp", "agentroam-nvm-windows-"));
         try {
             const home = resolve(root, "home");

package/dist/native-runtime.js

@@ -1,5 +1,51 @@
 import { chmod } from "node:fs/promises";
 import { resolve } from "node:path";
+export function probeSQLiteRuntime(runtimeRequire) {
+    const Database = runtimeRequire("better-sqlite3");
+    const database = new Database(":memory:");
+    try {
+        database.exec("CREATE TABLE runtime_probe (value INTEGER NOT NULL)");
+        database.prepare("INSERT INTO runtime_probe VALUES (?)").run(7);
+        if (database.prepare("SELECT value FROM runtime_probe").get()?.value !== 7) {
+            throw new Error("SQLite runtime query failed");
+        }
+    }
+    finally {
+        database.close();
+    }
+}
+export async function probeTerminalRuntime(runtimeRequire, platform = process.platform) {
+    const pty = runtimeRequire("node-pty");
+    const windows = platform === "win32";
+    const marker = "agentroam-runtime-probe";
+    const terminal = pty.spawn(windows ? (process.env.ComSpec || "cmd.exe") : "/bin/sh", windows
+        ? ["/d", "/s", "/c", `echo ${marker}`]
+        : ["-c", `printf ${marker}`], {
+        name: "xterm-256color", cols: 80, rows: 24, cwd: process.cwd(), env: process.env,
+    });
+    await new Promise((resolveProbe, rejectProbe) => {
+        let output = "";
+        const timer = setTimeout(() => {
+            dataListener.dispose();
+            exitListener.dispose();
+            try {
+                terminal.kill();
+            }
+            catch { }
+            rejectProbe(new Error("PTY runtime probe timed out"));
+        }, 5_000);
+        const dataListener = terminal.onData((chunk) => { output = (output + chunk).slice(-4096); });
+        const exitListener = terminal.onExit(({ exitCode }) => {
+            clearTimeout(timer);
+            dataListener.dispose();
+            exitListener.dispose();
+            if (exitCode === 0 && output.includes(marker))
+                resolveProbe();
+            else
+                rejectProbe(new Error(`PTY runtime probe failed (exit ${exitCode})`));
+        });
+    });
+}
 export async function repairNativeRuntimePermissions(runtimeRoot, platform = process.platform, arch = process.arch) {
     if (platform === "win32")
         return;

package/dist/native-runtime.test.js

@@ -1,8 +1,29 @@
 import { mkdtemp, mkdir, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
-import { describe, expect, it } from "vitest";
-import { repairNativeRuntimePermissions } from "./native-runtime.js";
+import { describe, expect, it, vi } from "vitest";
+import { probeSQLiteRuntime, probeTerminalRuntime, repairNativeRuntimePermissions } from "./native-runtime.js";
+describe("native runtime health", () => {
+    it("detects lazy SQLite binding failures after require succeeds", () => {
+        const requireRuntime = (() => class Database {
+            constructor() { throw new Error("native binding unavailable"); }
+        });
+        expect(() => probeSQLiteRuntime(requireRuntime)).toThrow("native binding unavailable");
+    });
+    it("closes SQLite when its query fails", () => {
+        const close = vi.fn();
+        const requireRuntime = (() => class Database {
+            exec() { throw new Error("database failed"); }
+            close = close;
+        });
+        expect(() => probeSQLiteRuntime(requireRuntime)).toThrow("database failed");
+        expect(close).toHaveBeenCalledOnce();
+    });
+    it("detects PTY spawn failures after require succeeds", async () => {
+        const requireRuntime = (() => ({ spawn() { throw new Error("spawn-helper unavailable"); } }));
+        await expect(probeTerminalRuntime(requireRuntime)).rejects.toThrow("spawn-helper unavailable");
+    });
+});
 describe("repairNativeRuntimePermissions", () => {
     it("restores the node-pty helper execute bits stripped by npm pack", async () => {
         const root = await mkdtemp(resolve(tmpdir(), "agentroam-native-"));

package/dist/node-preflight.test.js

@@ -4,18 +4,22 @@ import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 // @ts-expect-error The preflight intentionally remains plain ESM for Node 18 bootstrap.
-import { findNvmNode22, parsePreflightDataDir, runNodePreflight } from "../bin/node-preflight.mjs";
+import { findNvmNode, parsePreflightDataDir, runNodePreflight } from "../bin/node-preflight.mjs";
 const temporaryDirectories = [];
 afterEach(async () => {
     await Promise.all(temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })));
 });
 describe("Node launcher preflight", () => {
-    it("passes through any Node 22 patch without installing", async () => {
+    it.each(["22.22.0", "22.23.0", "24.0.0", "25.8.0", "26.0.0", "100.0.0"])("passes through Node %s without installing or switching", async (nodeVersion) => {
         const ensureNode = vi.fn();
-        await expect(runNodePreflight({ nodeVersion: "22.1.0", ensureNode })).resolves.toEqual({ handled: false });
+        const findSystemNode = vi.fn();
+        const spawnChild = vi.fn();
+        await expect(runNodePreflight({ nodeVersion, ensureNode, findSystemNode, spawnChild, environment: { AGENTROAM_MANAGED_NODE: "/older/node" } })).resolves.toEqual({ handled: false });
         expect(ensureNode).not.toHaveBeenCalled();
+        expect(findSystemNode).not.toHaveBeenCalled();
+        expect(spawnChild).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) => {
+    it.each(["18.20.0", "20.18.0", "22.1.0", "22.21.9"])("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);
@@ -27,7 +31,7 @@ describe("Node launcher preflight", () => {
             launcherPath: "/launcher/agentroam.mjs",
             environment: { PATH: "" },
             ensureNode,
-            findSystemNode22: async () => null,
+            findSystemNode: async () => null,
             spawnChild,
             processHost: fakeProcessHost(),
         });
@@ -38,38 +42,40 @@ describe("Node launcher preflight", () => {
         }));
         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" }),
+            env: expect.objectContaining({ AGENTROAM_MANAGED_NODE: "/managed/node" }),
         }));
     });
-    it("reuses another visible system Node 22", async () => {
+    it("reuses another visible compatible system Node", async () => {
         const ensureNode = vi.fn();
         const spawnChild = vi.fn((_executable, _args, _options) => fakeChild(7, null));
         await expect(runNodePreflight({
             argv: ["version"],
-            nodeVersion: "25.0.0",
+            nodeVersion: "20.0.0",
             platform: "win32",
             arch: "x64",
             environment: { PATH: "" },
-            findSystemNode22: async () => "C:\\Node22\\node.exe",
+            findSystemNode: async () => "C:\\Node25\\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");
+        expect(spawnChild.mock.calls[0][0]).toBe("C:\\Node25\\node.exe");
     });
-    it.skipIf(process.platform === "win32")("selects the highest inactive NVM Node 22", async () => {
+    it.skipIf(process.platform === "win32")("selects the highest compatible inactive NVM Node", async () => {
         const root = await mkdtemp(resolve(tmpdir(), "agentroam-preflight-nvm-"));
         temporaryDirectories.push(root);
         await fakeNodeExecutable(resolve(root, "versions/node/v22.3.0/bin/node"), "22.3.0");
-        const expected = await fakeNodeExecutable(resolve(root, "versions/node/v22.22.2/bin/node"), "22.22.2");
+        await fakeNodeExecutable(resolve(root, "versions/node/v22.22.2/bin/node"), "22.22.2");
         await fakeNodeExecutable(resolve(root, "versions/node/v23.1.0/bin/node"), "23.1.0");
-        await expect(findNvmNode22({ NVM_DIR: root, HOME: resolve(root, "home") }, "darwin"))
+        const expected = await fakeNodeExecutable(resolve(root, "versions/node/v25.8.0/bin/node"), "25.8.0");
+        await fakeNodeExecutable(resolve(root, "versions/node/v26.0.0-rc.1/bin/node"), "26.0.0-rc.1");
+        await expect(findNvmNode({ NVM_DIR: root, HOME: resolve(root, "home") }, "darwin"))
             .resolves.toBe(expected);
     });
     it("rejects a failed managed re-entry instead of looping", async () => {
         await expect(runNodePreflight({
-            nodeVersion: "25.0.0",
+            nodeVersion: "22.21.9",
             environment: { AGENTROAM_MANAGED_NODE: "22.22.0" },
         })).rejects.toMatchObject({ message: expect.stringContaining("re-entry failed"), exitCode: 2 });
     });
@@ -94,7 +100,7 @@ describe("Node launcher preflight", () => {
             platform: "darwin",
             arch: "arm64",
             environment: { PATH: "" },
-            findSystemNode22: async () => "/node22",
+            findSystemNode: async () => "/compatible-node",
             spawnChild: () => child,
             processHost,
         });

package/dist/opencode-runtime-manager.js

@@ -5,7 +5,9 @@ import { delimiter, isAbsolute, relative, resolve, win32 } from "node:path";
 import { promisify } from "node:util";
 import { resolveNpmExecutor } from "./codex-runtime-manager.js";
 const execFileAsync = promisify(execFile);
+// Default managed installation; compatibility has an independent minimum.
 export const OPENCODE_RUNTIME_VERSION = "1.18.27";
+export const OPENCODE_MINIMUM_VERSION = "1.18.27";
 const OPENCODE_PACKAGE = `opencode-ai@${OPENCODE_RUNTIME_VERSION}`;
 const NPM_REGISTRY = "https://registry.npmjs.org";
 const defaults = {
@@ -49,7 +51,7 @@ export async function resolveOpenCodeRuntime(options) {
     return install({ ...options, environment, platform, dependencies, managedRoot });
 }
 export function parseOpenCodeVersion(output) {
-    return output.match(/(?:^|\s)(\d+\.\d+\.\d+)(?:\s|$)/)?.[1] ?? null;
+    return output.match(/(?:^|\s)((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*))(?:\s|$)/)?.[1] ?? null;
 }
 export function managedOpenCodeBinaryCandidates(root, platform) {
     return platform === "win32"
@@ -183,12 +185,22 @@ async function validate(executable, source, _platform, dependencies) {
     const version = parseOpenCodeVersion(`${result.stdout}\n${result.stderr}`);
     if (!version)
         throw new Error(`Unable to parse OpenCode version from ${executable}`);
-    if (version !== OPENCODE_RUNTIME_VERSION) {
-        throw new Error(`OpenCode ${version} at ${executable} is incompatible; AgentRoam requires ${OPENCODE_RUNTIME_VERSION}`);
+    if (!meetsOpenCodeMinimum(version)) {
+        throw new Error(`OpenCode ${version} at ${executable} is incompatible; AgentRoam requires >=${OPENCODE_MINIMUM_VERSION}`);
     }
     await dependencies.run(executable, ["serve", "--help"], 5_000);
     return { executable, version, source };
 }
+// Compare numeric components, so 1.18.100 and 1.19.0 both exceed 1.18.27.
+function meetsOpenCodeMinimum(version) {
+    const actual = version.split(".").map(BigInt);
+    const minimum = OPENCODE_MINIMUM_VERSION.split(".").map(BigInt);
+    for (let index = 0; index < minimum.length; index += 1) {
+        if (actual[index] !== minimum[index])
+            return actual[index] > minimum[index];
+    }
+    return true;
+}
 async function accessible(path, executable = false) {
     try {
         await access(path, executable ? constants.X_OK : constants.F_OK);

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

@@ -2,7 +2,7 @@ import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { OPENCODE_RUNTIME_VERSION, managedOpenCodeBinaryCandidates, parseOpenCodeVersion, resolveOpenCodeRuntime, } from "./opencode-runtime-manager.js";
+import { OPENCODE_RUNTIME_VERSION, OPENCODE_MINIMUM_VERSION, managedOpenCodeBinaryCandidates, parseOpenCodeVersion, resolveOpenCodeRuntime, } from "./opencode-runtime-manager.js";
 const roots = [];
 afterEach(async () => {
     await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
@@ -31,6 +31,38 @@ describe("resolveOpenCodeRuntime", () => {
         })).resolves.toEqual({ executable: binary.path, version: OPENCODE_RUNTIME_VERSION, source: "explicit" });
         expect(run).toHaveBeenCalledWith(binary.path, ["serve", "--help"], 5_000);
     });
+    it.each([OPENCODE_MINIMUM_VERSION, "1.18.30", "1.18.100", "1.19.0", "2.0.0"])("reuses PATH version %s without installation", async (version) => {
+        const binary = await executable();
+        const run = vi.fn(async (_command, args) => ({
+            stdout: args[0] === "--version" ? version : "serve help", stderr: "",
+        }));
+        await expect(resolveOpenCodeRuntime({
+            dataDir: binary.root, target: "darwin-arm64", platform: "darwin",
+            environment: { PATH: binary.root }, dependencies: { run },
+        })).resolves.toEqual({ executable: binary.path, version, source: "global" });
+        expect(run.mock.calls.map(([, args]) => args)).toEqual([["--version"], ["serve", "--help"]]);
+    });
+    it.each(["1.18.26", "1.18.9", "1.17.99", "0.99.99", "dev", "1.19.0-beta.1", "01.19.0"])("rejects unsupported explicit version %s", async (version) => {
+        const binary = await executable();
+        const run = vi.fn(async () => ({ stdout: version, stderr: "" }));
+        await expect(resolveOpenCodeRuntime({
+            dataDir: binary.root, target: "darwin-arm64", platform: "darwin",
+            environment: { AGENT_OPENCODE_BIN: binary.path, PATH: "" }, dependencies: { run },
+        })).rejects.toThrow(/requires >=|Unable to parse OpenCode version/);
+        expect(run).toHaveBeenCalledTimes(1);
+    });
+    it("rejects a newer executable without serve support", async () => {
+        const binary = await executable();
+        await expect(resolveOpenCodeRuntime({
+            dataDir: binary.root, target: "darwin-arm64", platform: "darwin",
+            environment: { AGENT_OPENCODE_BIN: binary.path, PATH: "" },
+            dependencies: { run: async (_command, args) => {
+                    if (args[0] === "serve")
+                        throw new Error("serve unavailable");
+                    return { stdout: "1.18.30", stderr: "" };
+                } },
+        })).rejects.toThrow("serve unavailable");
+    });
     it("rejects relative explicit overrides", async () => {
         await expect(resolveOpenCodeRuntime({
             dataDir: "/data",

package/dist/platform-packages.js

@@ -1,7 +1,8 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
-export const AGENTROAM_VERSION = "0.2.0-preview.16";
+import { MINIMUM_NODE_VERSION, assertSupportedNodeVersion } from "../bin/runtime-policy.mjs";
+export const AGENTROAM_VERSION = "0.2.0-preview.18";
 export const PLATFORM_PACKAGES = {
     "darwin-arm64": {
         runtime: "agentroam-runtime-darwin-arm64",
@@ -37,12 +38,14 @@ export function resolvePlatformRuntime(target, requireFromCli = createRequire(im
     const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
     if (manifest.packageVersion !== AGENTROAM_VERSION
         || manifest.target !== target
-        || manifest.nodeMajor !== 22
-        || manifest.nodeModuleAbi !== 127
+        || manifest.schemaVersion !== 2
+        || manifest.minimumNodeVersion !== MINIMUM_NODE_VERSION
         || !manifest.nativeFiles
-        || typeof manifest.nativeFiles !== "object") {
+        || typeof manifest.nativeFiles !== "object"
+        || Array.isArray(manifest.nativeFiles)) {
         throw new Error(`invalid AgentRoam runtime manifest: ${manifestPath}`);
     }
+    assertSupportedNodeVersion();
     return {
         packageName,
         runtimeRoot: dirname(runtimePackageJson),

package/dist/platform-packages.test.js

@@ -28,8 +28,8 @@ describe("platform packages", () => {
         writeFileSync(manifestPath, JSON.stringify({
             packageVersion: AGENTROAM_VERSION,
             target: "windows-amd64",
-            nodeMajor: 22,
-            nodeModuleAbi: 127,
+            schemaVersion: 2,
+            minimumNodeVersion: "22.22.0",
             nativeFiles: { "node_modules/example.node": "a".repeat(64) },
         }));
         const resolved = resolvePlatformRuntime("windows-amd64", fakeRequire({
@@ -48,8 +48,8 @@ describe("platform packages", () => {
         writeFileSync(manifestPath, JSON.stringify({
             packageVersion: "0.0.0",
             target: "darwin-arm64",
-            nodeMajor: 22,
-            nodeModuleAbi: 127,
+            schemaVersion: 2,
+            minimumNodeVersion: "22.22.0",
             nativeFiles: {},
         }));
         expect(() => resolvePlatformRuntime("windows-amd64", fakeRequire({
@@ -61,6 +61,17 @@ describe("platform packages", () => {
         const entry = resolvePlatformTui("windows-amd64", fakeRequire({ "/entry": "C:\\agentroam\\agent-tui.js" }));
         expect(entry).toBe("C:\\agentroam\\agent-tui.js");
     });
+    it("rejects legacy ABI manifests even when their release version matches", () => {
+        const root = mkdtempSync(resolve(tmpdir(), "agentroam-runtime-legacy-"));
+        const manifestPath = resolve(root, "manifest.json");
+        writeFileSync(manifestPath, JSON.stringify({
+            packageVersion: AGENTROAM_VERSION, target: "darwin-arm64",
+            nodeMajor: 22, nodeModuleAbi: 127, nativeFiles: {},
+        }));
+        expect(() => resolvePlatformRuntime("darwin-arm64", fakeRequire({
+            "/manifest.json": manifestPath, "/runtime": resolve(root, "runtime/package.json"),
+        }))).toThrow("invalid AgentRoam runtime manifest");
+    });
 });
 function fakeRequire(suffixes) {
     return {

package/dist/platform.js

@@ -1,3 +1,4 @@
+import { assertSupportedNodeVersion } from "../bin/runtime-policy.mjs";
 export function detectPlatformTarget(platform = process.platform, arch = process.arch) {
     if (platform === "darwin" && arch === "arm64")
         return "darwin-arm64";
@@ -8,9 +9,6 @@ export function detectPlatformTarget(platform = process.platform, arch = process
     throw Object.assign(new Error(`unsupported platform: ${platform}-${arch}`), { exitCode: 2 });
 }
 export function detectPlatform(platform = process.platform, arch = process.arch, nodeVersion = process.versions.node) {
-    const major = Number(nodeVersion.split(".")[0]);
-    if (major !== 22) {
-        throw Object.assign(new Error(`Node.js 22 required (current ${nodeVersion})`), { exitCode: 2 });
-    }
+    assertSupportedNodeVersion(nodeVersion);
     return detectPlatformTarget(platform, arch);
 }