agentroam 0.2.0-preview.15 → 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.15.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.15.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.15.tgz \
-  ./agentroam-0.2.0-preview.15.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.15.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.15.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.15.tgz `
-  ./agentroam-0.2.0-preview.15.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.15";
+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/args.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 export function parseArgs(argv) {
     const values = [...argv];
     let command = "start";
-    if (values[0] && ["start", "doctor", "version", "service"].includes(values[0])) {
+    if (values[0] && ["start", "doctor", "version", "service", "update", "update-worker"].includes(values[0])) {
         command = values.shift();
     }
     let serviceAction = null;
@@ -17,6 +17,16 @@ export function parseArgs(argv) {
             throw cliError(`service ${serviceAction} does not accept options`);
         }
     }
+    let updateVersion = null;
+    let updateStateFile = null;
+    if (command === "update" && values[0] && !values[0].startsWith("--"))
+        updateVersion = values.shift();
+    if (command === "update-worker") {
+        const stateFile = values.shift();
+        if (!stateFile || values.length > 0)
+            throw cliError("update-worker requires one state file");
+        updateStateFile = resolve(stateFile);
+    }
     const options = {
         command,
         serviceAction,
@@ -27,8 +37,10 @@ export function parseArgs(argv) {
         localOnly: false,
         qr: true,
         dataDir: resolve(homedir(), ".agentroam"),
+        updateVersion,
+        updateStateFile,
     };
-    for (let index = 0; index < values.length; index++) {
+    for (let index = 0; index < values.length && command !== "update-worker"; index++) {
         const arg = values[index];
         const next = () => {
             const value = values[++index];
@@ -64,6 +76,9 @@ export function parseArgs(argv) {
         else
             throw cliError(`unknown argument: ${arg}`);
     }
+    if (command === "update" && updateVersion && !/^\d+\.\d+\.\d+$/.test(updateVersion)) {
+        throw cliError("update version must be an exact stable X.Y.Z version");
+    }
     if (!options.roots.length)
         options.roots = [process.cwd()];
     if (options.relay === "custom" && !options.tunnelCommand)

package/dist/args.test.js

@@ -51,4 +51,9 @@ describe("parseArgs", () => {
         expect(() => parseArgs(["service", "start", "--port", "3000"])).toThrow("does not accept options");
         expect(() => parseArgs(["service", "stop", "--local-only"])).toThrow("does not accept options");
     });
+    it("parses update with an optional exact stable version", () => {
+        expect(parseArgs(["update"]).updateVersion).toBeNull();
+        expect(parseArgs(["update", "1.2.3", "--data-dir", "./data"])).toMatchObject({ command: "update", updateVersion: "1.2.3" });
+        expect(() => parseArgs(["update", "1.2.3-preview.1"])).toThrow("exact stable");
+    });
 });

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";
@@ -15,9 +15,15 @@ import { ServiceRuntimeReporter } from "./service/runtime-state.js";
 import { runServiceCommand } from "./service/service-command.js";
 import { resolveServicePaths } from "./service/service-files.js";
 import { selectRelay } from "./tunnel/relay-orchestrator.js";
+import { currentCliPath, startUpdate } from "./update/update-command.js";
+import { runUpdateWorker } from "./update/update-worker.js";
 const VERSION = AGENTROAM_VERSION;
 export async function main(argv) {
     const options = parseArgs(argv);
+    if (options.command === "update-worker") {
+        await runUpdateWorker(options.updateStateFile);
+        return;
+    }
     if (options.command === "service") {
         await runServiceCommand(options, {
             nodePath: process.execPath,
@@ -27,6 +33,13 @@ export async function main(argv) {
         return;
     }
     const target = detectPlatform();
+    if (options.command === "update") {
+        if (target !== "darwin-arm64" && target !== "windows-amd64")
+            throw new Error(`updates are unavailable for ${target}`);
+        const state = await startUpdate({ currentVersion: VERSION, requestedVersion: options.updateVersion ?? null, dataDir: options.dataDir, target, cliPath: currentCliPath() });
+        console.log(`AgentRoam ${state.targetVersion} update started in the background.`);
+        return;
+    }
     if (options.command === "version") {
         console.log(`agentroam ${VERSION}`);
         return;
@@ -125,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`);
@@ -136,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,
         });