agentroam 0.2.0-preview.16 → 0.2.0-preview.17

package/README.md

@@ -4,7 +4,7 @@ Zero-install mobile remote terminal and file console. **No desktop app, no VPN**
 
 ## Requirements
 
-- **Node.js 22** (required)
+- **Node.js >=22.22.0** (no upper version bound)
 - macOS arm64 or Windows 10/11 x64
 
 The release is assembled on macOS arm64. Windows does not need Bun, Python,
@@ -20,20 +20,20 @@ npx agentroam@preview
 Or install from tarball:
 
 ```bash
-npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.16.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.16.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.16.tgz \
-  ./agentroam-0.2.0-preview.16.tgz
+npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.17.tgz \
+  ./agentroam-runtime-darwin-arm64-0.2.0-preview.17.tgz \
+  ./agentroam-tui-darwin-arm64-0.2.0-preview.17.tgz \
+  ./agentroam-0.2.0-preview.17.tgz
 npx agentroam
 ```
 
 Windows PowerShell:
 
 ```powershell
-npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.16.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.16.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.16.tgz `
-  ./agentroam-0.2.0-preview.16.tgz
+npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.17.tgz `
+  ./agentroam-runtime-win32-x64-0.2.0-preview.17.tgz `
+  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.17.tgz `
+  ./agentroam-0.2.0-preview.17.tgz
 npx agentroam
 ```
 
@@ -57,16 +57,17 @@ agent-tui                 # start the bundled terminal Agent UI
 
 Run the versioned Shell installer on macOS or PowerShell installer on Windows
 from the project directory AgentRoam should expose. The installer verifies or
-installs Node 22 and the matching CLI, registers the current-user service, starts
+installs a compatible Node and the matching CLI, registers the current-user service, starts
 it, checks readiness, and prints the access URL. Set `AGENTROAM_ROOT` to select a
 different root explicitly. An implicit root equal to the home directory is
 rejected.
 
-If the active Node is not 22, the installer checks nvm-sh on macOS and
-nvm-windows on Windows, validates every installed candidate, and uses the
-highest installed Node 22. It pins that executable for AgentRoam without
+The installer reuses the active Node when it meets the minimum version. Otherwise
+it checks nvm-sh on macOS and nvm-windows on Windows and uses the highest
+compatible installed version. The service records that executable without
 changing the user's global or active NVM version. A private Node 22.22.0 is
-downloaded only when no installed Node 22 is available.
+downloaded only when no compatible installed Node is available. Higher Node
+versions are never rejected or downgraded solely because of their major version.
 
 The service keeps running after the terminal closes, restarts after failure, and
 starts again when the user logs in. macOS uses a user LaunchAgent; Windows uses a
@@ -117,7 +118,7 @@ The platform cloudflared binary is installed from npm after size and SHA-256 ver
 - Next.js **standalone** web gateway + WebSocket PTY server
 - `@agent/core` bundled runtime
 - Optional platform **cloudflared** package (verified size + SHA-256 before execution)
-- Optional platform **agent-tui** package (Node 22 bundle; Bun is not required)
+- Optional platform **agent-tui** package (Node >=22.22.0 bundle; Bun is not required)
 - **Pairing token** + secure cookies behind HTTPS tunnel
 
 Not included: Electron desktop app, SDK, dev `.env`, session caches.

package/bin/node-preflight.mjs

@@ -4,10 +4,10 @@ import { homedir } from "node:os";
 import { delimiter, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { MINIMUM_NODE_VERSION, compareNodeVersions, isSupportedNodeVersion, parseNodeVersion } from "./runtime-policy.mjs";
 
 const execFileAsync = promisify(execFile);
-const MANAGED_NODE_VERSION = "22.22.0";
-const RELEASE_VERSION = "0.2.0-preview.16";
+const RELEASE_VERSION = "0.2.0-preview.17";
 const RELEASE_BASE_URL = `https://gitee.com/caoqu/team-agent/releases/download/v${RELEASE_VERSION}`;
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 
@@ -21,10 +21,10 @@ export async function runNodePreflight(options = {}) {
   const processHost = options.processHost ?? process;
   const major = Number(nodeVersion.split(".")[0]);
 
-  if (major === 22) return { handled: false };
+  if (isSupportedNodeVersion(nodeVersion)) return { handled: false };
   if (environment.AGENTROAM_MANAGED_NODE) {
     throw cliError(
-      `managed Node.js re-entry failed: expected 22, got ${nodeVersion} (${environment.AGENTROAM_MANAGED_NODE})`,
+      `managed Node.js re-entry failed: expected >=${MINIMUM_NODE_VERSION}, got ${nodeVersion} (${environment.AGENTROAM_MANAGED_NODE})`,
     );
   }
   if (!Number.isFinite(major) || major < 18) {
@@ -33,8 +33,8 @@ export async function runNodePreflight(options = {}) {
 
   const target = detectManagedTarget(platform, arch);
   const dataDir = parsePreflightDataDir(argv, environment, options.homeDir ?? homedir());
-  const findSystemNode22 = options.findSystemNode22 ?? defaultFindSystemNode22;
-  const systemNode = await findSystemNode22(environment, platform, options.currentExecutable ?? process.execPath);
+  const findSystemNode = options.findSystemNode ?? defaultFindSystemNode;
+  const systemNode = await findSystemNode(environment, platform, options.currentExecutable ?? process.execPath);
   let executable = systemNode;
 
   if (!executable) {
@@ -55,7 +55,7 @@ export async function runNodePreflight(options = {}) {
   const spawnChild = options.spawnChild ?? defaultSpawnChild;
   const child = spawnChild(executable, [launcherPath, ...argv], {
     stdio: "inherit",
-    env: { ...environment, AGENTROAM_MANAGED_NODE: MANAGED_NODE_VERSION },
+    env: { ...environment, AGENTROAM_MANAGED_NODE: executable },
   });
   const result = await waitForChild(child, processHost);
   return { handled: true, ...result };
@@ -77,7 +77,7 @@ function detectManagedTarget(platform, arch) {
   throw cliError(`managed Node.js is unsupported on ${platform}-${arch}`);
 }
 
-async function defaultFindSystemNode22(environment, platform, currentExecutable) {
+async function defaultFindSystemNode(environment, platform, currentExecutable) {
   const executableName = platform === "win32" ? "node.exe" : "node";
   const pathDelimiter = platform === "win32" ? ";" : delimiter;
   const currentDirectory = dirname(currentExecutable);
@@ -85,12 +85,12 @@ async function defaultFindSystemNode22(environment, platform, currentExecutable)
     if (resolve(directory) === resolve(currentDirectory)) continue;
     const candidate = resolve(directory, executableName);
     const version = await inspectNodeVersion(candidate);
-    if (version?.[0] === 22) return candidate;
+    if (isSupportedNodeVersion(version)) return candidate;
   }
-  return findNvmNode22(environment, platform);
+  return findNvmNode(environment, platform);
 }
 
-export async function findNvmNode22(environment = process.env, platform = process.platform) {
+export async function findNvmNode(environment = process.env, platform = process.platform) {
   const windows = platform === "win32";
   const homeDir = environment.HOME || environment.USERPROFILE || homedir();
   const roots = windows
@@ -109,10 +109,10 @@ export async function findNvmNode22(environment = process.env, platform = proces
       if (!entry.isDirectory()) continue;
       const candidate = resolve(versionsRoot, entry.name, windows ? "node.exe" : "bin/node");
       const version = await inspectNodeVersion(candidate);
-      if (version?.[0] === 22) candidates.push({ candidate, version });
+      if (isSupportedNodeVersion(version)) candidates.push({ candidate, version });
     }
   }
-  candidates.sort((left, right) => compareVersions(right.version, left.version));
+  candidates.sort((left, right) => compareNodeVersions(right.version, left.version));
   return candidates[0]?.candidate ?? null;
 }
 
@@ -124,20 +124,13 @@ async function inspectNodeVersion(candidate) {
       timeout: 5_000,
       windowsHide: true,
     });
-    const parts = stdout.trim().split(".").map((part) => Number(part));
-    return parts.length >= 3 && parts.every(Number.isInteger) ? parts.slice(0, 3) : null;
+    const version = stdout.trim();
+    return parseNodeVersion(version) ? version : null;
   } catch {
     return null;
   }
 }
 
-function compareVersions(left, right) {
-  for (let index = 0; index < 3; index++) {
-    if (left[index] !== right[index]) return left[index] - right[index];
-  }
-  return 0;
-}
-
 async function defaultSpawnChild(executable, args, options) {
   const { spawn } = await import("node:child_process");
   return spawn(executable, args, options);

package/bin/node-runtime-policy.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "minimumNodeVersion": "22.22.0"
+}

package/bin/runtime-policy.d.mts

@@ -0,0 +1,5 @@
+export const MINIMUM_NODE_VERSION: string;
+export function parseNodeVersion(version: unknown): number[] | null;
+export function compareNodeVersions(left: string, right: string): number;
+export function isSupportedNodeVersion(version: unknown, minimum?: string): boolean;
+export function assertSupportedNodeVersion(version?: string): void;

package/bin/runtime-policy.mjs

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+
+const policy = JSON.parse(readFileSync(new URL("./node-runtime-policy.json", import.meta.url), "utf8"));
+
+export const MINIMUM_NODE_VERSION = policy.minimumNodeVersion;
+
+export function parseNodeVersion(version) {
+  if (typeof version !== "string") return null;
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+  if (!match) return null;
+  const parts = match.slice(1, 4).map(Number);
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+export function compareNodeVersions(left, right) {
+  const leftParts = parseNodeVersion(left);
+  const rightParts = parseNodeVersion(right);
+  if (!leftParts || !rightParts) throw new Error("invalid Node.js version");
+  for (let index = 0; index < 3; index++) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+export function isSupportedNodeVersion(version, minimum = MINIMUM_NODE_VERSION) {
+  return parseNodeVersion(version) !== null && compareNodeVersions(version, minimum) >= 0;
+}
+
+export function assertSupportedNodeVersion(version = process.versions.node) {
+  if (!isSupportedNodeVersion(version)) {
+    throw Object.assign(new Error(`Node.js >=${MINIMUM_NODE_VERSION} required (current ${version})`), { exitCode: 2 });
+  }
+}
+
+if (policy.schemaVersion !== 1 || !parseNodeVersion(MINIMUM_NODE_VERSION)) {
+  throw new Error("invalid AgentRoam Node.js runtime policy");
+}

package/dist/cli.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "./args.js";
 import { ensureCloudflared } from "./cloudflared/installer.js";
 import { resolveCodexRuntime } from "./codex-runtime-manager.js";
-import { repairNativeRuntimePermissions } from "./native-runtime.js";
+import { probeSQLiteRuntime, probeTerminalRuntime, repairNativeRuntimePermissions } from "./native-runtime.js";
 import { findLanUrl } from "./network.js";
 import { createPairingSecret } from "./pairing.js";
 import { detectPlatform } from "./platform.js";
@@ -138,7 +138,7 @@ export async function main(argv) {
     }
 }
 async function doctor(target, dataDir) {
-    console.log(`✓ Node ${process.versions.node}`);
+    console.log(`✓ Node ${process.versions.node} · Node-API ${process.versions.napi}`);
     console.log(`✓ Platform ${target}`);
     const { runtimeRoot } = resolvePlatformRuntime(target);
     const runtimeRequire = createRequire(`${runtimeRoot}/package.json`);
@@ -149,9 +149,12 @@ async function doctor(target, dataDir) {
     catch (error) {
         reportDoctorFailure(error);
     }
-    for (const module of ["node-pty", "better-sqlite3"]) {
+    for (const [module, probe] of [
+        ["node-pty", probeTerminalRuntime],
+        ["better-sqlite3", probeSQLiteRuntime],
+    ]) {
         try {
-            runtimeRequire(module);
+            await probe(runtimeRequire);
             console.log(`✓ ${module}`);
         }
         catch (error) {

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

@@ -4,12 +4,35 @@ 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")("keeps a compatible active Node instead of selecting a different NVM version", 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: workspace, 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(`MINIMUM_NODE_VERSION="${MINIMUM_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);
@@ -20,7 +43,7 @@ describe("standalone installer contracts", () => {
         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("find_nvm_node");
         expect(script).toContain('${NVM_DIR:-}');
         expect(script).not.toMatch(/\b(?:brew|sudo|fnm|volta)\b/);
         execFileSync("sh", ["-n", scriptPath]);
@@ -28,6 +51,7 @@ 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(`$MinimumNodeVersion = "${MINIMUM_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);
@@ -38,11 +62,11 @@ describe("standalone installer contracts", () => {
         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("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 +76,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 +92,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.17";
 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);
 }

package/dist/platform.test.js

@@ -2,15 +2,15 @@ import { describe, expect, it } from "vitest";
 import { detectPlatform, detectPlatformTarget } from "./platform.js";
 describe("detectPlatform", () => {
     it("maps supported targets", () => {
-        expect(detectPlatform("darwin", "arm64", "22.1.0")).toBe("darwin-arm64");
-        expect(detectPlatform("win32", "x64", "22.1.0")).toBe("windows-amd64");
+        expect(detectPlatform("darwin", "arm64", "22.22.0")).toBe("darwin-arm64");
+        expect(detectPlatform("win32", "x64", "25.8.0")).toBe("windows-amd64");
     });
     it("detects a target before Node version validation", () => {
         expect(detectPlatformTarget("darwin", "arm64")).toBe("darwin-arm64");
         expect(detectPlatformTarget("win32", "x64")).toBe("windows-amd64");
     });
     it("rejects unsupported versions", () => {
-        expect(() => detectPlatform("darwin", "arm64", "23.0.0")).toThrow("Node.js 22");
+        expect(() => detectPlatform("darwin", "arm64", "22.21.9")).toThrow("Node.js >=22.22.0");
     });
     it("rejects unsupported platforms", () => {
         expect(() => detectPlatformTarget("linux", "x64")).toThrow("unsupported platform");

package/dist/service/service-command.js

@@ -4,6 +4,7 @@ import { detectPlatform } from "../platform.js";
 import { renderQr } from "../qr.js";
 import { MacLaunchAgent } from "./macos-launch-agent.js";
 import { WindowsTaskService } from "./windows-task-service.js";
+import { assertSupportedNodeVersion } from "../../bin/runtime-policy.mjs";
 export async function runServiceCommand(options, context) {
     const platform = context.platform ?? process.platform;
     const log = context.log ?? console.log;
@@ -19,9 +20,7 @@ export async function runServiceCommand(options, context) {
     switch (options.serviceAction) {
         case "install": {
             const nodeVersion = context.nodeVersion ?? process.versions.node;
-            if (Number(nodeVersion.split(".")[0]) !== 22) {
-                throw cliError(`Node.js 22 is required to install the service (current ${nodeVersion})`);
-            }
+            assertSupportedNodeVersion(nodeVersion);
             const now = context.now?.() ?? new Date();
             const environment = context.environment ?? process.env;
             const environmentPath = buildServiceEnvironmentPath(context.nodePath, environment.PATH ?? environment.Path, platform);

package/dist/service/service-command.test.js

@@ -2,6 +2,26 @@ import { resolve } from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import { buildServiceEnvironmentPath, runServiceCommand } from "./service-command.js";
 describe("runServiceCommand", () => {
+    it.each(["22.22.0", "24.0.0", "25.8.0", "26.0.0"])("keeps the selected Node %s when installing a service", async (nodeVersion) => {
+        const install = vi.fn(async () => ({ definition: "/test/service.plist" }));
+        const nodePath = `/runtimes/node-${nodeVersion}/bin/node`;
+        const codexResolver = vi.fn(async () => ({ executable: "/tools/codex", version: "test", source: "global" }));
+        await runServiceCommand(options("install"), {
+            platform: "darwin", arch: "arm64", nodeVersion, nodePath,
+            cliPath: "/agentroam.mjs", version: "test", environment: { PATH: "/usr/bin" },
+            codexResolver, controller: controller({ install }), log: vi.fn(),
+        });
+        expect(install).toHaveBeenCalledWith(expect.objectContaining({ nodePath }));
+        expect(codexResolver).toHaveBeenCalledWith(expect.objectContaining({ nodeExecutable: nodePath }));
+    });
+    it("rejects a below-minimum service runtime before installation", async () => {
+        const install = vi.fn();
+        await expect(runServiceCommand(options("install"), {
+            platform: "darwin", nodePath: "/node", nodeVersion: "22.21.9", cliPath: "/agentroam.mjs",
+            version: "test", controller: controller({ install }),
+        })).rejects.toThrow("Node.js >=22.22.0");
+        expect(install).not.toHaveBeenCalled();
+    });
     it("installs the service using absolute runtime context and parsed start options", async () => {
         const install = vi.fn(async (config) => ({
             paths: { plistPath: "/Users/test/Library/LaunchAgents/com.agentroam.service.plist" },

package/dist/tunnel/public-readiness.js

@@ -22,7 +22,7 @@ export async function waitForPublicReadiness(publicUrl, options = {}) {
             try {
                 const response = await fetchImpl(endpoint, {
                     cache: "no-store",
-                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.16" },
+                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.17" },
                     signal: options.signal,
                 });
                 if (response.ok) {

package/install/README.md

@@ -1,11 +1,11 @@
 # AgentRoam bootstrap installers
 
-These versioned installers support macOS Apple Silicon and Windows x64. They reuse a visible Node.js 22 installation when available. Otherwise they install the verified private Node.js `22.22.0` runtime under the AgentRoam data directory. They then register and start the current-user AgentRoam background service. They never modify, replace, or uninstall system Node.js or global power settings.
+These versioned installers support macOS Apple Silicon and Windows x64. They reuse the active Node.js installation when it meets `>=22.22.0`, with no upper version bound. Otherwise they search NVM for the highest compatible version, then fall back to the verified private Node.js `22.22.0` runtime under the AgentRoam data directory. They then register and start the current-user AgentRoam background service. They never modify, replace, or uninstall system Node.js or global power settings.
 
 ## macOS Apple Silicon
 
 ```sh
-curl -fsSL https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.16/install-agentroam.sh | sh
+curl -fsSL https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.17/install-agentroam.sh | sh
 ```
 
 The command installs the wrapper at `~/.local/bin/agentroam`. If that directory is not already in `PATH`, the installer prints the required shell setting without editing shell profiles.
@@ -13,7 +13,7 @@ The command installs the wrapper at `~/.local/bin/agentroam`. If that directory
 ## Windows x64
 
 ```powershell
-irm https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.16/install-agentroam.ps1 | iex
+irm https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.17/install-agentroam.ps1 | iex
 ```
 
 The command installs `%USERPROFILE%\.agentroam\bin\agentroam.cmd` and adds only that user directory to the user-level `PATH`. It does not require administrator access or change the machine-level `PATH`.
@@ -40,7 +40,7 @@ agentroam service uninstall
 
 ## Data and updates
 
-Set `AGENTROAM_DATA_DIR` before running either installer to override the default `~/.agentroam` data directory. Node is stored at `<data-dir>/runtimes/node/22.22.0`, and the launcher is stored at `<data-dir>/launcher/0.2.0-preview.16`.
+Set `AGENTROAM_DATA_DIR` before running either installer to override the default `~/.agentroam` data directory. Node is stored at `<data-dir>/runtimes/node/22.22.0`, and the launcher is stored at `<data-dir>/launcher/0.2.0-preview.17`.
 
 Each AgentRoam release pins its own Node patch and installer assets. Updates happen only by running a newer versioned installer or installing a newer AgentRoam release; startup never follows a moving Node.js release channel.
 

package/install/install-agentroam.ps1

@@ -2,7 +2,8 @@ $ErrorActionPreference = "Stop"
 $ProgressPreference = "SilentlyContinue"
 
 $NodeVersion = "22.22.0"
-$AgentRoamVersion = "0.2.0-preview.16"
+$MinimumNodeVersion = "22.22.0"
+$AgentRoamVersion = "0.2.0-preview.17"
 $NodeArchive = "node-v22.22.0-win-x64.zip"
 $NodeSha256 = "c97fa376d2becdc8863fcd3ca2dd9a83a9f3468ee7ccf7a6d076ec66a645c77a"
 $NodeUrl = "https://nodejs.org/dist/v22.22.0/$NodeArchive"
@@ -27,9 +28,14 @@ if (-not $ServiceRootExplicit -and $ServiceRoot -eq $HomeRoot) {
 
 New-Item -ItemType Directory -Force -Path $NodeParent, $LauncherParent, $WrapperDir | Out-Null
 
-function Test-Node22([string]$NodeBin) {
+function Test-NodeVersion([string]$VersionText) {
+  if ($VersionText -notmatch '^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$') { return $false }
+  try { return [Version]($VersionText.Split('+')[0]) -ge [Version]$MinimumNodeVersion } catch { return $false }
+}
+
+function Test-SupportedNode([string]$NodeBin) {
   if (-not (Test-Path -LiteralPath $NodeBin -PathType Leaf)) { return $false }
-  try { return (& $NodeBin -p 'process.versions.node.split(".")[0]' 2>$null) -eq "22" } catch { return $false }
+  try { return Test-NodeVersion ((& $NodeBin -p 'process.versions.node' 2>$null).Trim()) } catch { return $false }
 }
 
 function Get-NvmRoots {
@@ -50,15 +56,15 @@ function Get-NvmRoots {
   @($Candidates | Where-Object { $_ -and (Test-Path -LiteralPath $_ -PathType Container) } | Select-Object -Unique)
 }
 
-function Find-NvmNode22 {
+function Find-NvmNode {
   $VersionMatches = foreach ($NvmRoot in (Get-NvmRoots)) {
     foreach ($VersionDirectory in Get-ChildItem -LiteralPath $NvmRoot -Directory -ErrorAction SilentlyContinue) {
       $Candidate = Join-Path $VersionDirectory.FullName "node.exe"
       if (-not (Test-Path -LiteralPath $Candidate -PathType Leaf)) { continue }
       try {
         $VersionText = (& $Candidate -p 'process.versions.node' 2>$null).Trim()
-        $Version = [Version]$VersionText
-        if ($Version.Major -eq 22) {
+        if (Test-NodeVersion $VersionText) {
+          $Version = [Version]($VersionText.Split('+')[0])
           [pscustomobject]@{ Path = $Candidate; Version = $Version }
         }
       } catch {}
@@ -97,10 +103,10 @@ function Enter-InstallLock([string]$Path) {
 
 $SystemNode = Get-Command node.exe -ErrorAction SilentlyContinue
 if ($env:AGENTROAM_BOOTSTRAP_TEST -eq "1" -and $env:AGENTROAM_FORCE_PRIVATE_NODE -eq "1") { $SystemNode = $null }
-if ($SystemNode -and (Test-Node22 $SystemNode.Source)) {
+if ($SystemNode -and (Test-SupportedNode $SystemNode.Source)) {
   $NodeBin = $SystemNode.Source
 } else {
-  $NvmNode = if ($env:AGENTROAM_BOOTSTRAP_TEST -eq "1" -and $env:AGENTROAM_FORCE_PRIVATE_NODE -eq "1") { $null } else { Find-NvmNode22 }
+  $NvmNode = if ($env:AGENTROAM_BOOTSTRAP_TEST -eq "1" -and $env:AGENTROAM_FORCE_PRIVATE_NODE -eq "1") { $null } else { Find-NvmNode }
   if ($NvmNode) {
     $NodeBin = $NvmNode
     Write-Host "Using Node.js $(& $NodeBin --version) from NVM: $NodeBin"

package/install/install-agentroam.sh

@@ -2,7 +2,8 @@
 set -eu
 
 NODE_VERSION="22.22.0"
-AGENTROAM_VERSION="0.2.0-preview.16"
+MINIMUM_NODE_VERSION="22.22.0"
+AGENTROAM_VERSION="0.2.0-preview.17"
 NODE_ARCHIVE="node-v22.22.0-darwin-arm64.tar.xz"
 NODE_SHA256="2bd596bbfc4a275ceb8721a5954ee97daea5ebe673e96a185ebd732f6fb023ac"
 NODE_URL="https://nodejs.org/dist/v22.22.0/$NODE_ARCHIVE"
@@ -56,25 +57,40 @@ SERVICE_ROOT="$service_root_physical"
 
 mkdir -p "$NODE_PARENT" "$LAUNCHER_PARENT" "$WRAPPER_DIR"
 
-node_is_22() {
-  [ -x "$1" ] && [ "$("$1" -p 'process.versions.node.split(".")[0]' 2>/dev/null || true)" = "22" ]
+version_is_supported() {
+  awk -v version="$1" -v minimum="$MINIMUM_NODE_VERSION" 'BEGIN {
+    if (version !~ /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/) exit 1;
+    sub(/\+.*/, "", version);
+    split(version, actual, "."); split(minimum, required, ".");
+    for (component = 1; component <= 3; component++) {
+      if (actual[component] + 0 > required[component] + 0) exit 0;
+      if (actual[component] + 0 < required[component] + 0) exit 1;
+    }
+    exit 0;
+  }'
 }
 
-find_nvm_node_22() {
+node_is_supported() {
+  [ -x "$1" ] && version_is_supported "$("$1" -p 'process.versions.node' 2>/dev/null || true)"
+}
+
+find_nvm_node() {
   best_bin=""
+  best_major=-1
   best_minor=-1
   best_patch=-1
   for nvm_root in "${NVM_DIR:-}" "$HOME/.nvm"; do
     [ -n "$nvm_root" ] || continue
-    for candidate in "$nvm_root"/versions/node/v22*/bin/node; do
+    for candidate in "$nvm_root"/versions/node/v*/bin/node; do
       [ -x "$candidate" ] || continue
       version=$("$candidate" -p 'process.versions.node' 2>/dev/null || true)
+      version_is_supported "$version" || continue
       major=$(printf '%s\n' "$version" | awk -F. '{ print $1 + 0 }')
       minor=$(printf '%s\n' "$version" | awk -F. '{ print $2 + 0 }')
       patch=$(printf '%s\n' "$version" | awk -F. '{ sub(/[^0-9].*$/, "", $3); print $3 + 0 }')
-      [ "$major" -eq 22 ] 2>/dev/null || continue
-      if [ "$minor" -gt "$best_minor" ] || { [ "$minor" -eq "$best_minor" ] && [ "$patch" -gt "$best_patch" ]; }; then
+      if [ "$major" -gt "$best_major" ] || { [ "$major" -eq "$best_major" ] && { [ "$minor" -gt "$best_minor" ] || { [ "$minor" -eq "$best_minor" ] && [ "$patch" -gt "$best_patch" ]; }; }; }; then
         best_bin="$candidate"
+        best_major=$major
         best_minor=$minor
         best_patch=$patch
       fi
@@ -112,13 +128,13 @@ SYSTEM_NODE=$(command -v node 2>/dev/null || true)
 if [ "${AGENTROAM_BOOTSTRAP_TEST:-}" = "1" ] && [ "${AGENTROAM_FORCE_PRIVATE_NODE:-}" = "1" ]; then
   SYSTEM_NODE=""
 fi
-if [ -n "$SYSTEM_NODE" ] && node_is_22 "$SYSTEM_NODE"; then
+if [ -n "$SYSTEM_NODE" ] && node_is_supported "$SYSTEM_NODE"; then
   NODE_BIN="$SYSTEM_NODE"
 else
   if [ "${AGENTROAM_BOOTSTRAP_TEST:-}" = "1" ] && [ "${AGENTROAM_FORCE_PRIVATE_NODE:-}" = "1" ]; then
     NVM_NODE=""
   else
-    NVM_NODE=$(find_nvm_node_22 || true)
+    NVM_NODE=$(find_nvm_node || true)
   fi
   if [ -n "$NVM_NODE" ]; then
     NODE_BIN="$NVM_NODE"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentroam",
-  "version": "0.2.0-preview.16",
+  "version": "0.2.0-preview.17",
   "description": "Zero-install mobile remote terminal and file console",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
     "agent-tui": "./bin/agent-tui.mjs"
   },
   "engines": {
-    "node": ">=22 <23"
+    "node": ">=22.22.0"
   },
   "files": [
     "bin",
@@ -26,12 +26,12 @@
     "undici": "^6.25.0"
   },
   "optionalDependencies": {
-    "agentroam-runtime-darwin-arm64": "0.2.0-preview.16",
-    "agentroam-runtime-win32-x64": "0.2.0-preview.16",
-    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.16",
-    "agentroam-cloudflared-win32-x64": "0.2.0-preview.16",
-    "agentroam-tui-darwin-arm64": "0.2.0-preview.16",
-    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.16"
+    "agentroam-runtime-darwin-arm64": "0.2.0-preview.17",
+    "agentroam-runtime-win32-x64": "0.2.0-preview.17",
+    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.17",
+    "agentroam-cloudflared-win32-x64": "0.2.0-preview.17",
+    "agentroam-tui-darwin-arm64": "0.2.0-preview.17",
+    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.17"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",