agentroam 0.2.0-preview.15 → 0.2.0-preview.17

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.15";
+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/runtime-manager.js

@@ -1,5 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import { delimiter, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveCodexRuntime, } from "./codex-runtime-manager.js";
 import { repairNativeRuntimePermissions } from "./native-runtime.js";
 import { resolveOpenCodeRuntime, } from "./opencode-runtime-manager.js";
@@ -39,6 +40,9 @@ export class RuntimeManager {
                 AGENT_TRUST_TUNNEL_PROXY: "1",
                 AGENT_PAIRING_HASH: pairing?.hashHex || "",
                 AGENT_PAIRING_EXPIRES_AT: pairing?.expiresAt || "",
+                AGENTROAM_VERSION: resolvePlatformRuntime(target).manifest.packageVersion,
+                AGENTROAM_DATA_DIR: dataDir,
+                AGENTROAM_CLI_PATH: fileURLToPath(new URL("../bin/agentroam.mjs", import.meta.url)),
             },
         });
         const log = (stream) => stream?.on("data", (chunk) => process.stderr.write(chunk));

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.15" },
+                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.17" },
                     signal: options.signal,
                 });
                 if (response.ok) {

package/dist/update/update-channel.js

@@ -0,0 +1,38 @@
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-preview\.(0|[1-9]\d*))?$/;
+export function parseAgentRoamVersion(value) {
+    const match = VERSION.exec(value);
+    if (!match)
+        return null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        preview: match[4] === undefined ? null : Number(match[4]),
+    };
+}
+// A prerelease installation follows the preview channel; a stable installation
+// follows latest. Preview users are also offered a newer stable release so they
+// can migrate to the stable track without reinstalling.
+export function resolveUpdateChannel(currentVersion) {
+    const parsed = parseAgentRoamVersion(currentVersion);
+    if (!parsed)
+        throw new Error("invalid AgentRoam version");
+    return parsed.preview === null ? "latest" : "preview";
+}
+export function resolveReleaseChannel(version) {
+    const parsed = parseAgentRoamVersion(version);
+    if (!parsed)
+        throw new Error("invalid AgentRoam version");
+    return parsed.preview === null ? "latest" : "preview";
+}
+export function registryUrlsForChannel(channel, registryBase) {
+    return channel === "preview" ? [`${registryBase}/latest`, `${registryBase}/preview`] : [`${registryBase}/latest`];
+}
+export function parseChannelVersion(value, channel) {
+    if (typeof value !== "string")
+        return null;
+    const parsed = parseAgentRoamVersion(value);
+    if (!parsed)
+        return null;
+    if (parsed.preview === null)
+        return value;
+    return channel === "preview" ? value : null;
+}

package/dist/update/update-command.js

@@ -0,0 +1,102 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { updatePaths, writeUpdateState } from "./update-state.js";
+import { parseChannelVersion, registryUrlsForChannel, resolveReleaseChannel, resolveUpdateChannel, } from "./update-channel.js";
+const REGISTRY_BASE = "https://registry.npmjs.org/agentroam";
+const RELEASE_BASE = "https://gitee.com/caoqu/team-agent/releases/download";
+const SHA = /^[a-f0-9]{64}$/;
+export async function resolveUpdate(options, fetchImpl = fetch) {
+    const channel = resolveUpdateChannel(options.currentVersion);
+    const target = await readRegistryCandidate(fetchImpl, channel);
+    if (!target)
+        throw new Error("unable to check the npm release channel");
+    if (options.requestedVersion && options.requestedVersion !== target)
+        throw new Error("requested version is not the current npm candidate");
+    if (compare(target, options.currentVersion) <= 0)
+        throw new Error("AgentRoam is already up to date");
+    const response = await fetchWithTimeout(fetchImpl, `${RELEASE_BASE}/v${target}/release-manifest.json`);
+    if (!response.ok)
+        throw new Error("release manifest is unavailable");
+    const manifest = await response.json();
+    const asset = manifest?.installers?.cli?.[options.target];
+    const fileName = options.target === "darwin-arm64" ? "install-agentroam.sh" : "install-agentroam.ps1";
+    if (manifest?.schemaVersion !== 2 || manifest.version !== target || manifest.channel !== resolveReleaseChannel(target) || asset?.fileName !== fileName || !SHA.test(asset?.sha256 ?? "")) {
+        throw new Error("release manifest is invalid for this platform");
+    }
+    return { targetVersion: target, fileName, sha256: asset.sha256 };
+}
+// Preview installations follow the higher of the preview and latest npm
+// dist-tags so a newer stable release can move them onto the stable track.
+async function readRegistryCandidate(fetchImpl, channel) {
+    let best = null;
+    for (const url of registryUrlsForChannel(channel, REGISTRY_BASE)) {
+        const response = await fetchWithTimeout(fetchImpl, url).catch(() => null);
+        if (!response?.ok)
+            continue;
+        const candidate = parseChannelVersion((await response.json()).version, channel);
+        if (!candidate)
+            continue;
+        if (!best || compare(candidate, best) > 0)
+            best = candidate;
+    }
+    return best;
+}
+export async function startUpdate(options) {
+    const release = await resolveUpdate(options);
+    const paths = updatePaths(options.dataDir);
+    const service = await readServiceConfig();
+    const state = {
+        schemaVersion: 1,
+        phase: "downloading",
+        currentVersion: options.currentVersion,
+        ...release,
+        dataDir: resolve(options.dataDir),
+        roots: service?.roots?.length ? service.roots : [process.cwd()],
+        port: service?.port ?? null,
+        relay: service?.relay ?? "auto",
+        tunnelCommand: service?.tunnelCommand ?? null,
+        localOnly: service?.localOnly ?? false,
+        cliPath: resolve(options.cliPath),
+        updatedAt: Date.now(),
+    };
+    await writeUpdateState(paths.stateFile, state);
+    const child = spawn(process.execPath, [options.cliPath, "update-worker", paths.stateFile], { detached: true, stdio: "ignore", windowsHide: true });
+    child.unref();
+    return state;
+}
+async function readServiceConfig() {
+    try {
+        return JSON.parse(await readFile(resolve(homedir(), ".agentroam", "service", "config.json"), "utf8"));
+    }
+    catch { }
+    return null;
+}
+async function fetchWithTimeout(fetchImpl, url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 4_000);
+    timer.unref?.();
+    try {
+        return await fetchImpl(url, { headers: { accept: "application/json" }, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function compare(left, right) {
+    const parse = (value) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)(?:-preview\.(\d+))?$/.exec(value);
+        if (!match)
+            throw new Error("invalid AgentRoam version");
+        return [...match.slice(1, 4).map(Number), match[4] === undefined ? Number.MAX_SAFE_INTEGER : Number(match[4])];
+    };
+    const a = parse(left);
+    const b = parse(right);
+    for (let i = 0; i < a.length; i += 1)
+        if (a[i] !== b[i])
+            return a[i] > b[i] ? 1 : -1;
+    return 0;
+}
+export const currentCliPath = () => fileURLToPath(new URL("../../bin/agentroam.mjs", import.meta.url));

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

@@ -0,0 +1,70 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { resolveUpdate } from "./update-command.js";
+import { acquireUpdateLock, readUpdateState, updatePaths, writeUpdateState } from "./update-state.js";
+const sha256 = "c".repeat(64);
+const response = (body) => new Response(JSON.stringify(body), { status: 200 });
+describe("resolveUpdate", () => {
+    it("accepts only npm latest with an audited Gitee installer", async () => {
+        const fetcher = vi.fn()
+            .mockResolvedValueOnce(response({ version: "1.2.3" }))
+            .mockResolvedValueOnce(response({ schemaVersion: 2, version: "1.2.3", channel: "latest", installers: { cli: { "windows-amd64": { fileName: "install-agentroam.ps1", sha256 } } } }));
+        await expect(resolveUpdate({ currentVersion: "1.2.2", requestedVersion: null, dataDir: "data", target: "windows-amd64", cliPath: "cli" }, fetcher))
+            .resolves.toEqual({ targetVersion: "1.2.3", fileName: "install-agentroam.ps1", sha256 });
+    });
+    it("rejects a requested version that is not npm latest", async () => {
+        const fetcher = vi.fn().mockResolvedValue(response({ version: "1.2.3" }));
+        await expect(resolveUpdate({ currentVersion: "1.0.0", requestedVersion: "1.2.2", dataDir: "data", target: "darwin-arm64", cliPath: "cli" }, fetcher)).rejects.toThrow("not the current npm candidate");
+    });
+    it("follows the preview channel and offers a higher preview", async () => {
+        const fetcher = vi.fn((url) => {
+            const u = String(url);
+            if (u.endsWith("/preview"))
+                return Promise.resolve(response({ version: "1.2.3-preview.4" }));
+            if (u.endsWith("/latest"))
+                return Promise.resolve(response({ version: "1.2.2" }));
+            return Promise.resolve(response({ schemaVersion: 2, version: "1.2.3-preview.4", channel: "preview", installers: { cli: { "darwin-arm64": { fileName: "install-agentroam.sh", sha256 } } } }));
+        });
+        await expect(resolveUpdate({ currentVersion: "1.2.3-preview.3", requestedVersion: null, dataDir: "data", target: "darwin-arm64", cliPath: "cli" }, fetcher))
+            .resolves.toEqual({ targetVersion: "1.2.3-preview.4", fileName: "install-agentroam.sh", sha256 });
+    });
+    it("offers a newer stable release to preview users", async () => {
+        const fetcher = vi.fn((url) => {
+            const u = String(url);
+            if (u.endsWith("/preview"))
+                return Promise.resolve(response({ version: "1.2.3-preview.4" }));
+            if (u.endsWith("/latest"))
+                return Promise.resolve(response({ version: "1.2.4" }));
+            return Promise.resolve(response({ schemaVersion: 2, version: "1.2.4", channel: "latest", installers: { cli: { "darwin-arm64": { fileName: "install-agentroam.sh", sha256 } } } }));
+        });
+        await expect(resolveUpdate({ currentVersion: "1.2.3-preview.4", requestedVersion: null, dataDir: "data", target: "darwin-arm64", cliPath: "cli" }, fetcher))
+            .resolves.toEqual({ targetVersion: "1.2.4", fileName: "install-agentroam.sh", sha256 });
+    });
+    it("stable channel never queries the preview tag", async () => {
+        const fetcher = vi.fn((url) => {
+            const u = String(url);
+            expect(u).not.toContain("/preview");
+            if (u.endsWith("/latest"))
+                return Promise.resolve(response({ version: "1.2.4" }));
+            return Promise.resolve(response({ schemaVersion: 2, version: "1.2.4", channel: "latest", installers: { cli: { "darwin-arm64": { fileName: "install-agentroam.sh", sha256 } } } }));
+        });
+        await resolveUpdate({ currentVersion: "1.2.3", requestedVersion: null, dataDir: "data", target: "darwin-arm64", cliPath: "cli" }, fetcher);
+        expect(fetcher.mock.calls.map((call) => String(call[0])).some((url) => url.includes("/preview"))).toBe(false);
+    });
+    it("writes durable state atomically and excludes concurrent workers", async () => {
+        const dataDir = await mkdtemp(resolve(tmpdir(), "agentroam-update-state-"));
+        const paths = updatePaths(dataDir);
+        const state = {
+            schemaVersion: 1, phase: "downloading", currentVersion: "1.0.0", targetVersion: "1.1.0",
+            dataDir, roots: ["D:\\project"], port: 3000, relay: "auto", tunnelCommand: null,
+            localOnly: false, fileName: "install-agentroam.ps1", sha256, cliPath: "C:\\agentroam.mjs", updatedAt: 1,
+        };
+        await writeUpdateState(paths.stateFile, state);
+        await expect(readUpdateState(paths.stateFile)).resolves.toEqual(state);
+        const release = await acquireUpdateLock(paths.lockFile);
+        await expect(acquireUpdateLock(paths.lockFile)).rejects.toThrow("already running");
+        await release();
+    });
+});

package/dist/update/update-state.js

@@ -0,0 +1,43 @@
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+export function updatePaths(dataDir) {
+    const directory = resolve(dataDir, "updates");
+    return { directory, stateFile: resolve(directory, "state.json"), lockFile: resolve(directory, "update.lock") };
+}
+export async function readUpdateState(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        return value?.schemaVersion === 1 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUpdateState(path, state) {
+    await mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    await rename(temp, path);
+}
+export async function acquireUpdateLock(path, now = Date.now()) {
+    await mkdir(dirname(path), { recursive: true });
+    try {
+        const handle = await open(path, "wx", 0o600);
+        await handle.writeFile(`${process.pid}\n${now}\n`);
+        await handle.close();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const age = now - (await stat(path)).mtimeMs;
+        if (age <= 30 * 60 * 1_000)
+            throw new Error("an AgentRoam update is already running");
+        await unlink(path);
+        return acquireUpdateLock(path, now);
+    }
+    return async () => { await unlink(path).catch(() => undefined); };
+}
+export function sanitizeUpdateError(error) {
+    const value = error instanceof Error ? error.message : String(error);
+    return value.replace(/[A-Za-z]:\\[^\s]+|\/(?:Users|home|var|tmp)\/[^\s]+/g, "<path>").slice(0, 300);
+}

package/dist/update/update-worker.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { chmod, readFile, unlink } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { spawn } from "node:child_process";
+import { acquireUpdateLock, readUpdateState, sanitizeUpdateError, updatePaths, writeUpdateState } from "./update-state.js";
+const RELEASE_BASE = "https://gitee.com/caoqu/team-agent/releases/download";
+export async function runUpdateWorker(stateFile, fetchImpl = fetch) {
+    const initial = await readUpdateState(stateFile);
+    if (!initial)
+        throw new Error("update state is missing");
+    const paths = updatePaths(initial.dataDir);
+    if (resolve(stateFile) !== paths.stateFile)
+        throw new Error("update state is outside the data directory");
+    const releaseLock = await acquireUpdateLock(paths.lockFile);
+    const partial = resolve(paths.directory, `${basename(initial.fileName)}.partial`);
+    let state = initial;
+    const update = async (next) => {
+        state = { ...state, ...next, updatedAt: Date.now() };
+        await writeUpdateState(stateFile, state);
+    };
+    try {
+        const response = await fetchImpl(`${RELEASE_BASE}/v${state.targetVersion}/${encodeURIComponent(state.fileName)}`);
+        if (!response.ok || !response.body)
+            throw new Error("installer download failed");
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(partial, { mode: 0o700 }));
+        const actual = createHash("sha256").update(await readFile(partial)).digest("hex");
+        if (actual !== state.sha256)
+            throw new Error("installer checksum mismatch");
+        await chmod(partial, 0o700).catch(() => undefined);
+        await update({ phase: "installing" });
+        const command = process.platform === "win32" ? "powershell.exe" : "/bin/sh";
+        const args = process.platform === "win32" ? ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", partial] : [partial];
+        const code = await run(command, args, { ...process.env, AGENTROAM_DATA_DIR: state.dataDir, AGENTROAM_ROOT: state.roots[0], AGENTROAM_INSTALL_SKIP_SERVICE: "1" });
+        if (code !== 0)
+            throw new Error(`installer exited with code ${code}`);
+        const nextEntry = resolve(state.dataDir, "launcher", state.targetVersion, "node_modules", "agentroam", "bin", "agentroam.mjs");
+        const serviceArgs = [nextEntry, "service", "install"];
+        for (const root of state.roots)
+            serviceArgs.push("--root", root);
+        serviceArgs.push("--data-dir", state.dataDir, "--relay", state.relay, "--no-qr");
+        if (state.port)
+            serviceArgs.push("--port", String(state.port));
+        if (state.tunnelCommand)
+            serviceArgs.push("--tunnel-command", state.tunnelCommand);
+        if (state.localOnly)
+            serviceArgs.push("--local-only");
+        await update({ phase: "reconnecting" });
+        const serviceCode = await run(process.execPath, serviceArgs, process.env);
+        if (serviceCode !== 0)
+            throw new Error(`service activation exited with code ${serviceCode}`);
+        await update({ phase: "complete", message: `AgentRoam ${state.targetVersion} installed` });
+    }
+    catch (error) {
+        await update({ phase: "failed", message: sanitizeUpdateError(error) });
+        throw error;
+    }
+    finally {
+        await unlink(partial).catch(() => undefined);
+        await releaseLock();
+    }
+}
+function run(command, args, env) {
+    return new Promise((resolveRun, reject) => {
+        const child = spawn(command, args, { env, stdio: "ignore", windowsHide: true });
+        child.once("error", reject);
+        child.once("exit", resolveRun);
+    });
+}

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.15/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.15/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.15`.
+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.