agentroam 0.2.0-preview.19 → 0.2.0-preview.20

package/README.md

@@ -20,20 +20,20 @@ npx agentroam@preview
 Or install from tarball:
 
 ```bash
-npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.18.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.18.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.18.tgz \
-  ./agentroam-0.2.0-preview.18.tgz
+npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.20.tgz \
+  ./agentroam-runtime-darwin-arm64-0.2.0-preview.20.tgz \
+  ./agentroam-tui-darwin-arm64-0.2.0-preview.20.tgz \
+  ./agentroam-0.2.0-preview.20.tgz
 npx agentroam
 ```
 
 Windows PowerShell:
 
 ```powershell
-npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.18.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.18.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.18.tgz `
-  ./agentroam-0.2.0-preview.18.tgz
+npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.20.tgz `
+  ./agentroam-runtime-win32-x64-0.2.0-preview.20.tgz `
+  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.20.tgz `
+  ./agentroam-0.2.0-preview.20.tgz
 npx agentroam
 ```
 

package/bin/desktop-download.mjs

@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
 import { createHash } from 'node:crypto';
 import { createWriteStream } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
@@ -24,8 +24,8 @@ export function desktopAsset(manifest, version, platform, arch) {
 }
 
 export async function downloadDesktop(version, { platform = process.platform, arch = process.arch, directory = join(homedir(), 'Downloads'), fetchImpl = fetch } = {}) {
-  const launcher = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-  if (version === launcher.version) version = launcher.optionalDependencies["agentroam-runtime-darwin-arm64"];
+  const launcher = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  if (version === launcher.version) version = launcher.optionalDependencies['agentroam-runtime-darwin-arm64'];
   // Validate coordinates before making any request.
   if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-preview\.(0|[1-9]\d*))?$/.test(version)) throw new Error('Invalid AgentRoam version');
   const response = await fetchImpl(`${RELEASE_BASE}/v${version}/release-manifest.json`, { signal: AbortSignal.timeout(30_000) });

package/dist/cli.js

@@ -16,6 +16,7 @@ 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";
+import { lockInstanceStartup, stopPreviousInstances } from "./instance-takeover.js";
 const VERSION = AGENTROAM_VERSION;
 export async function main(argv) {
     if (argv.includes("--help") || argv.includes("-h")) {
@@ -102,23 +103,38 @@ export async function main(argv) {
     let runtime = null;
     let relay = null;
     let closing = false;
+    let releaseStartup;
+    let closePromise;
+    let reportedStarting = false;
     const serviceReporter = process.env.AGENTROAM_SERVICE === "1"
         ? new ServiceRuntimeReporter(resolveServicePaths(undefined, options.dataDir), VERSION)
         : null;
-    const close = async () => {
-        if (closing)
-            return;
+    const close = () => {
+        if (closePromise)
+            return closePromise;
         closing = true;
         controller.abort();
-        await relay?.tunnel?.close().catch(() => { });
-        await runtime?.close().catch(() => { });
+        closePromise = (async () => {
+            await relay?.tunnel?.close().catch(() => { });
+            await runtime?.close().catch(() => { });
+        })();
+        return closePromise;
     };
     const requestClose = () => void close();
     process.once("SIGINT", requestClose);
     process.once("SIGTERM", requestClose);
     try {
+        releaseStartup = await lockInstanceStartup(options.dataDir);
+        await stopPreviousInstances(options.dataDir, console.log);
+        if (controller.signal.aborted)
+            return;
         await serviceReporter?.starting();
+        reportedStarting = Boolean(serviceReporter);
         runtime = await new RuntimeManager().start(options, target);
+        if (controller.signal.aborted) {
+            await runtime.close();
+            return;
+        }
         void runtime.exited.then(() => controller.abort());
         console.log(`✓ Local server: ${runtime.localUrl}/web`);
         const lanUrl = options.localOnly ? findLanUrl(runtime.port) ?? runtime.localUrl : runtime.localUrl;
@@ -134,8 +150,10 @@ export async function main(argv) {
             onFailure: (provider, message) => console.error(`⚠ ${providerDisplayName(provider)} unavailable: ${message}`),
             allowLanFallback: options.localOnly,
         });
-        if (controller.signal.aborted)
+        if (controller.signal.aborted) {
+            await relay.tunnel?.close();
             return;
+        }
         if (relay.provider === "lan") {
             if (relay.failures.length > 0)
                 console.error(`  Continuing with local network access: ${relay.publicUrl}/web`);
@@ -156,6 +174,7 @@ export async function main(argv) {
             accessUrl,
             provider: relay.provider,
         });
+        await releaseStartup();
         if (serviceReporter) {
             console.log("✓ Background service URL written to the private state file.");
         }
@@ -179,7 +198,9 @@ export async function main(argv) {
         process.removeListener("SIGINT", requestClose);
         process.removeListener("SIGTERM", requestClose);
         await close();
-        await serviceReporter?.stopped().catch(() => { });
+        await releaseStartup?.();
+        if (reportedStarting)
+            await serviceReporter?.stopped().catch(() => { });
         await sleepInhibitor.release();
     }
 }

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

@@ -1,11 +1,44 @@
 import { chmod, copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { describe, expect, it } from "vitest";
 import { MANAGED_NODE_VERSION, NODE_RUNTIME_ASSETS } from "./node-runtime-manager.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 === "win32")("continues after failed diagnostics but stops when service registration fails", async () => {
+        const root = await mkdtemp(resolve(process.env.TMPDIR || "/tmp", "agentroam-install-diagnostics-"));
+        try {
+            const script = await readFile(resolve(installRoot, "install-agentroam.sh"), "utf8");
+            // Execute the actual post-install flow with a fake CLI, without touching launchd.
+            const start = script.indexOf('if ! "$NODE_BIN" "$entry" doctor');
+            expect(start).toBeGreaterThan(0);
+            const node = resolve(root, "node");
+            const calls = resolve(root, "calls");
+            await writeFile(node, `#!/bin/sh\nprintf '%s\\n' "$2" >> "$TEST_CALLS"\ncase "$2" in\n doctor) exit 1 ;;\n service) exit "$TEST_SERVICE_EXIT" ;;\nesac\n`);
+            await chmod(node, 0o755);
+            for (const serviceExit of [0, 1]) {
+                await writeFile(calls, "");
+                const result = spawnSync("/bin/sh", ["-c", `set -eu\n${script.slice(start)}`], {
+                    encoding: "utf8",
+                    env: { ...process.env, NODE_BIN: node, entry: "fake-cli", DATA_DIR: root, SERVICE_ROOT: root,
+                        WRAPPER_PATH: "agentroam", WRAPPER_DIR: root, AGENTROAM_VERSION: "test",
+                        AGENTROAM_INSTALL_SKIP_SERVICE: "0", AGENTROAM_INSTALL_DESKTOP: "no",
+                        TEST_CALLS: calls, TEST_SERVICE_EXIT: String(serviceExit) },
+                });
+                expect(await readFile(calls, "utf8")).toBe("doctor\nservice\n");
+                expect(result.stderr).toContain("some component checks failed");
+                expect(result.status).toBe(serviceExit);
+                if (serviceExit === 0)
+                    expect(result.stdout).toContain("installed:");
+                else
+                    expect(result.stdout).not.toContain("installed:");
+            }
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+        }
+    });
     it.skipIf(process.platform !== "darwin" || process.arch !== "arm64")("allows installation from home and keeps a compatible active Node", async () => {
         const root = await mkdtemp(resolve(process.env.TMPDIR || "/tmp", "agentroam-active-node-"));
         try {

package/dist/instance-takeover.js

@@ -0,0 +1,146 @@
+import { readdir, readFile, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { runCommand } from "./service/service-controller.js";
+import { MacLaunchAgent } from "./service/macos-launch-agent.js";
+import { WindowsTaskService } from "./service/windows-task-service.js";
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+async function processList() {
+    if (process.platform === "win32") {
+        const result = await runCommand("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CommandLine | ConvertTo-Json -Compress"]);
+        if (result.code !== 0)
+            throw new Error("无法核验旧 CLI 进程");
+        return JSON.parse(result.stdout).map((p) => ({ pid: p.ProcessId, ppid: p.ParentProcessId, command: p.CommandLine ?? "" }));
+    }
+    const result = await runCommand("ps", ["-axo", "pid=,ppid=,command="]);
+    if (result.code !== 0)
+        throw new Error("无法核验旧 CLI 进程");
+    return result.stdout.split("\n").flatMap(line => {
+        const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+        return match ? [{ pid: Number(match[1]), ppid: Number(match[2]), command: match[3] }] : [];
+    });
+}
+async function stopCli(pid) {
+    const service = process.platform === "win32" ? new WindowsTaskService() : new MacLaunchAgent();
+    const status = await service.status();
+    if (status.running && status.state?.pid === pid) {
+        await service.stop();
+        return;
+    }
+    if (process.platform === "win32") {
+        const result = await runCommand("taskkill", ["/PID", String(pid), "/T", "/F"]);
+        if (result.code !== 0)
+            throw new Error("旧 CLI 进程树停止失败");
+    }
+    else
+        process.kill(pid, "SIGTERM");
+}
+async function isPackagedRuntime(command) {
+    const match = /(?:^|\s)(?:"([^"]+[\\/]ws-server\.mjs)"|(\S+[\\/]ws-server\.mjs))(?=\s|$)/.exec(command);
+    const gateway = match?.[1] ?? match?.[2];
+    if (!gateway)
+        return false;
+    try {
+        const path = await realpath(gateway);
+        if (!/[\\/]node_modules[\\/]agentroam-runtime-(?:darwin-arm64|win32-x64)[\\/]runtime[\\/]ws-server\.mjs$/.test(path))
+            return false;
+        const manifest = JSON.parse(await readFile(join(dirname(dirname(path)), "package.json"), "utf8"));
+        return ["agentroam-runtime-darwin-arm64", "agentroam-runtime-win32-x64"].includes(manifest.name);
+    }
+    catch {
+        return false;
+    }
+}
+/** Authenticate the local server, then verify its CLI parent before sending any signal. */
+export async function stopPreviousInstances(dataDir, log, dependencies = {}) {
+    const canonical = await realpath(dataDir);
+    const registry = dependencies.registry ?? process.env.AGENTROAM_DISCOVERY_DIR ?? join(homedir(), ".agentroam/services");
+    const names = await readdir(registry).catch((error) => { if (error.code === "ENOENT")
+        return []; throw error; });
+    for (const name of names.filter(name => name.endsWith(".json"))) {
+        let d;
+        try {
+            d = JSON.parse(await readFile(join(registry, name), "utf8"));
+            if (d.protocol !== 1 || !Number.isSafeInteger(d.pid) || d.pid <= 1 || typeof d.instanceId !== "string" || !/^[a-f0-9]{64}$/.test(d.token))
+                continue;
+            const actual = await realpath(d.dataDir);
+            if (actual !== canonical && actual !== join(canonical, "data"))
+                continue;
+            const url = new URL(d.url);
+            if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/" || url.username || url.password || url.search || url.hash)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let identity;
+        try {
+            const response = await (dependencies.request ?? fetch)(new URL("/api/desktop/identity", d.url), { headers: { "x-agentroam-desktop-token": d.token }, redirect: "error", signal: AbortSignal.timeout(1500) });
+            if (!response.ok)
+                throw new Error("实例认证失败");
+            identity = await response.json();
+        }
+        catch {
+            if ((dependencies.alive ?? alive)(d.pid))
+                throw new Error("同一数据目录的旧实例无法核验，请先停止旧实例再重试");
+            continue;
+        }
+        if (identity.protocol !== 1 || identity.instanceId !== d.instanceId || identity.dataDir !== d.dataDir)
+            throw new Error("旧实例身份不匹配，已取消启动");
+        const processes = await (dependencies.processes ?? processList)();
+        const server = processes.find(p => p.pid === d.pid);
+        const parent = processes.find(p => p.pid === server?.ppid);
+        const orphan = server && (server.ppid === 1 || !parent) && await isPackagedRuntime(server.command);
+        if (!server || server.pid === process.pid || (!orphan && (!parent || parent.pid === process.pid || !/[\\/]ws-server\.mjs(?:["\s]|$)/.test(server.command) || !/[\\/]agentroam[\\/]bin[\\/]agentroam\.mjs(?:["\s]|$)/.test(parent.command)))) {
+            throw new Error("同一数据目录已有服务，但无法确认它是可接管的 CLI 实例，请先停止该服务");
+        }
+        // Re-read the process relationship immediately before stopping, to reject stale PID records.
+        const current = await (dependencies.processes ?? processList)();
+        if (!current.some(p => p.pid === server.pid && p.ppid === server.ppid && p.command === server.command) || (!orphan && !current.some(p => p.pid === parent.pid && p.command === parent.command)))
+            throw new Error("旧实例身份已变化，请重试");
+        const targetPid = orphan ? server.pid : parent.pid;
+        log(orphan ? "检测到旧 CLI 遗留的服务进程，正在停止…" : "检测到同一数据目录的旧 CLI，正在停止…");
+        await (dependencies.stop ?? stopCli)(targetPid);
+        const deadline = Date.now() + (dependencies.timeoutMs ?? 15_000);
+        while ((dependencies.alive ?? alive)(targetPid) || (dependencies.alive ?? alive)(server.pid)) {
+            if (Date.now() >= deadline)
+                throw new Error("旧 CLI 尚未退出，已取消新实例启动，请稍后重试");
+            await delay(100);
+        }
+        log("✓ 旧 CLI 已停止，继续启动新实例");
+    }
+}
+/** Serialize startup within a data directory; never remove a live owner's lock. */
+export async function lockInstanceStartup(dataDir) {
+    await mkdir(dataDir, { recursive: true });
+    const path = resolve(await realpath(dataDir), ".cli-start.lock");
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        throw new Error("此数据目录已有 CLI 正在启动；请等它完成后重试。若上次异常退出，请确认无启动进程后移除 .cli-start.lock。");
+    }
+    try {
+        await writeFile(join(path, "pid"), String(process.pid), { mode: 0o600 });
+    }
+    catch (error) {
+        await rm(path, { recursive: true, force: true });
+        throw error;
+    }
+    let released = false;
+    return async () => { if (!released) {
+        released = true;
+        await rm(path, { recursive: true, force: true });
+    } };
+}

package/dist/instance-takeover.test.js

@@ -0,0 +1,121 @@
+import { once } from "node:events";
+import { afterEach, expect, it, vi } from "vitest";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { lockInstanceStartup, stopPreviousInstances } from "./instance-takeover.js";
+const temporary = [];
+afterEach(async () => { await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true }))); });
+async function fixture() {
+    const root = await realpath(await mkdtemp(join(tmpdir(), "cli-takeover-")));
+    temporary.push(root);
+    const registry = join(root, "registry");
+    const dataDir = join(root, "data-dir");
+    await mkdir(registry);
+    await mkdir(join(dataDir, "data"), { recursive: true });
+    const descriptor = { protocol: 1, instanceId: "test-instance", pid: 200, url: "http://127.0.0.1:12345", dataDir: join(dataDir, "data"), token: "a".repeat(64) };
+    const save = () => writeFile(join(registry, "test.json"), JSON.stringify(descriptor));
+    await save();
+    const rows = [{ pid: 200, ppid: 100, command: "/node /runtime/ws-server.mjs" }, { pid: 100, ppid: 1, command: "/node /cache/node_modules/agentroam/bin/agentroam.mjs" }];
+    const stop = vi.fn(async () => { });
+    const deps = { registry, request: vi.fn(async () => Response.json(descriptor)), processes: vi.fn(async () => rows), stop, alive: () => false, timeoutMs: 1 };
+    return { descriptor, save, deps, stop, dataDir, rows };
+}
+it("authenticates the same data directory and stops the CLI parent before proceeding", async () => {
+    const f = await fixture();
+    await stopPreviousInstances(f.dataDir, () => { }, f.deps);
+    expect(f.stop).toHaveBeenCalledTimes(1);
+    expect(f.stop).toHaveBeenCalledWith(100);
+    expect(f.deps.processes).toHaveBeenCalledTimes(2);
+});
+it("leaves a different data directory untouched without making an authenticated request", async () => {
+    const f = await fixture();
+    f.descriptor.dataDir = tmpdir();
+    await f.save();
+    await stopPreviousInstances(f.dataDir, () => { }, f.deps);
+    expect(f.deps.request).not.toHaveBeenCalled();
+    expect(f.stop).not.toHaveBeenCalled();
+});
+it("does not send the private token to non-loopback addresses", async () => {
+    const f = await fixture();
+    f.descriptor.url = "https://example.com";
+    await f.save();
+    await stopPreviousInstances(f.dataDir, () => { }, f.deps);
+    expect(f.deps.request).not.toHaveBeenCalled();
+    expect(f.stop).not.toHaveBeenCalled();
+});
+it("rejects a matching live server with a non-CLI parent", async () => {
+    const f = await fixture();
+    f.rows[1].command = "/Applications/Other.app/server";
+    await expect(stopPreviousInstances(f.dataDir, () => { }, f.deps)).rejects.toThrow("无法确认");
+    expect(f.stop).not.toHaveBeenCalled();
+});
+it("does not signal a reused PID", async () => {
+    const f = await fixture();
+    f.deps.processes.mockResolvedValueOnce(f.rows).mockResolvedValueOnce([{ ...f.rows[0], ppid: 300 }, f.rows[1]]);
+    await expect(stopPreviousInstances(f.dataDir, () => { }, f.deps)).rejects.toThrow("身份已变化");
+    expect(f.stop).not.toHaveBeenCalled();
+});
+it("refuses to launch while the previous process still runs", async () => {
+    const f = await fixture();
+    f.deps.alive = () => true;
+    await expect(stopPreviousInstances(f.dataDir, () => { }, f.deps)).rejects.toThrow("尚未退出");
+});
+it("ignores stale dead descriptors but blocks unreachable live instances", async () => {
+    const f = await fixture();
+    f.deps.request = vi.fn(async () => { throw new Error("offline"); });
+    await stopPreviousInstances(f.dataDir, () => { }, f.deps);
+    expect(f.stop).not.toHaveBeenCalled();
+    f.deps.alive = () => true;
+    await expect(stopPreviousInstances(f.dataDir, () => { }, f.deps)).rejects.toThrow("无法核验");
+});
+it("serializes startup and releases the lock for the next launch", async () => {
+    const f = await fixture();
+    const release = await lockInstanceStartup(f.dataDir);
+    await expect(lockInstanceStartup(f.dataDir)).rejects.toThrow("正在启动");
+    await release();
+    await release();
+    await (await lockInstanceStartup(f.dataDir))();
+});
+it.skipIf(process.platform === "win32")("stops an authenticated real CLI parent and waits for its server child to exit", async () => {
+    const { spawn } = await import("node:child_process");
+    const f = await fixture();
+    const cli = join(f.dataDir, "node_modules/agentroam/bin/agentroam.mjs");
+    const server = join(f.dataDir, "runtime/ws-server.mjs");
+    await mkdir(join(f.dataDir, "node_modules/agentroam/bin"), { recursive: true });
+    await mkdir(join(f.dataDir, "runtime"));
+    await writeFile(server, `import http from 'node:http';\nimport {writeFileSync} from 'node:fs';\nconst d=JSON.parse(process.env.DESCRIPTOR);d.pid=process.pid;\nconst s=http.createServer((req,res)=>{if(req.headers['x-agentroam-desktop-token']!==d.token){res.writeHead(401).end();return;}res.setHeader('content-type','application/json');res.end(JSON.stringify(d));});\ns.listen(0,'127.0.0.1',()=>{d.url='http://127.0.0.1:'+s.address().port;writeFileSync(process.env.RECORD,JSON.stringify(d));console.log('ready');});`);
+    await writeFile(cli, `import {spawn} from 'node:child_process';\nimport {writeFileSync} from 'node:fs';\nconst child=spawn(process.execPath,[process.env.SERVER],{stdio:['ignore','inherit','inherit']});\nprocess.on('SIGTERM',()=>{writeFileSync(process.env.MARKER,'graceful');child.kill('SIGTERM');});\nchild.on('exit',()=>process.exit(0));`);
+    const marker = join(f.dataDir, "stopped");
+    const child = spawn(process.execPath, [cli], { env: { ...process.env, SERVER: server, RECORD: join(f.deps.registry, "test.json"), DESCRIPTOR: JSON.stringify(f.descriptor), MARKER: marker }, stdio: ["ignore", "pipe", "pipe"] });
+    const exited = once(child, "exit");
+    try {
+        await once(child.stdout, "data");
+        await stopPreviousInstances(f.dataDir, () => { }, { registry: f.deps.registry, stop: async (pid) => { expect(pid).toBe(child.pid); process.kill(pid, "SIGTERM"); } });
+        await exited;
+        const { readFile } = await import("node:fs/promises");
+        expect(await readFile(marker, "utf8")).toBe("graceful");
+    }
+    finally {
+        if (child.exitCode === null) {
+            child.kill("SIGTERM");
+            await exited;
+        }
+    }
+});
+it("stops an authenticated orphan only when its executable belongs to a runtime package", async () => {
+    const f = await fixture();
+    const pkg = join(f.dataDir, "launcher/0.2.0-preview.18/node_modules/agentroam-runtime-darwin-arm64");
+    await mkdir(join(pkg, "runtime"), { recursive: true });
+    await writeFile(join(pkg, "package.json"), JSON.stringify({ name: "agentroam-runtime-darwin-arm64" }));
+    await writeFile(join(pkg, "runtime/ws-server.mjs"), "// fixture");
+    f.rows.splice(0, f.rows.length, { pid: 200, ppid: 1, command: `/node ${join(pkg, "runtime/ws-server.mjs")}` });
+    await stopPreviousInstances(f.dataDir, () => { }, f.deps);
+    expect(f.stop).toHaveBeenCalledWith(200);
+});
+it("does not stop an orphan merely because its script is named ws-server.mjs", async () => {
+    const f = await fixture();
+    f.rows.splice(0, f.rows.length, { pid: 200, ppid: 1, command: "/node /unrelated/ws-server.mjs" });
+    await expect(stopPreviousInstances(f.dataDir, () => { }, f.deps)).rejects.toThrow("无法确认");
+    expect(f.stop).not.toHaveBeenCalled();
+});

package/dist/platform-packages.js

@@ -2,9 +2,8 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
 import { MINIMUM_NODE_VERSION, assertSupportedNodeVersion } from "../bin/runtime-policy.mjs";
-const launcherManifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-export const AGENTROAM_VERSION = launcherManifest.version;
-export const PLATFORM_DEPENDENCY_VERSIONS = launcherManifest.optionalDependencies;
+export const AGENTROAM_VERSION = "0.2.0-preview.20";
+export const PLATFORM_DEPENDENCY_VERSIONS = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).optionalDependencies;
 export const PLATFORM_PACKAGES = {
     "darwin-arm64": {
         runtime: "agentroam-runtime-darwin-arm64",

package/dist/service/launcher-cleanup.js

@@ -0,0 +1,61 @@
+import { lstat, readFile, readdir, realpath, rm } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+function versionParts(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-preview\.(0|[1-9]\d*))?$/.exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3]), match[4] === undefined ? Infinity : Number(match[4])] : null;
+}
+function older(candidate, current) {
+    const left = versionParts(candidate), right = versionParts(current);
+    if (!left || !right)
+        return false;
+    for (let i = 0; i < left.length; i++)
+        if (left[i] !== right[i])
+            return left[i] < right[i];
+    return false;
+}
+function contains(parent, child) {
+    const path = relative(parent, child);
+    return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !path.startsWith(sep));
+}
+/** Remove only recognized managed launcher versions after the replacement service is ready. */
+export async function cleanupOldLaunchers(config, log) {
+    try {
+        const dataDir = await realpath(config.dataDir);
+        const launcherDir = resolve(dataDir, "launcher");
+        if (!(await lstat(launcherDir)).isDirectory() || (await lstat(launcherDir)).isSymbolicLink())
+            return;
+        const currentDir = resolve(launcherDir, config.version);
+        const expectedEntry = resolve(currentDir, "node_modules/agentroam/bin/agentroam.mjs");
+        if (await realpath(config.cliPath) !== expectedEntry)
+            return;
+        const roots = await Promise.all(config.roots.map(async (root) => realpath(root).catch(() => resolve(root))));
+        for (const entry of await readdir(launcherDir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !older(entry.name, config.version))
+                continue;
+            const candidate = resolve(launcherDir, entry.name);
+            try {
+                if (await lstat(`${candidate}.lock`).then(() => true, () => false))
+                    continue;
+                if (roots.some(root => contains(candidate, root)))
+                    continue;
+                const files = await readdir(candidate);
+                if (files.some(file => !["node_modules", "package.json", "package-lock.json"].includes(file)))
+                    continue;
+                const manifestPath = resolve(candidate, "node_modules/agentroam/package.json");
+                if (await realpath(manifestPath) !== manifestPath)
+                    continue;
+                const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+                if (manifest.name !== "agentroam" || manifest.version !== entry.name)
+                    continue;
+                await rm(candidate, { recursive: true });
+                log(`✓ 已清理旧版 CLI ${entry.name}，配置和数据已保留`);
+            }
+            catch {
+                log(`旧版 CLI ${entry.name} 暂未清理，将在下次安装时重试。`);
+            }
+        }
+    }
+    catch {
+        log("旧版 CLI 清理已跳过，新版服务不受影响。");
+    }
+}

package/dist/service/launcher-cleanup.test.js

@@ -0,0 +1,81 @@
+import { afterEach, expect, it } from "vitest";
+import { mkdtemp, mkdir, writeFile, readFile, rm, symlink, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { cleanupOldLaunchers } from "./launcher-cleanup.js";
+const temporary = [];
+afterEach(async () => { await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true }))); });
+async function fixture() {
+    const dataDir = await realpath(await mkdtemp(resolve(tmpdir(), "launcher-cleanup-")));
+    temporary.push(dataDir);
+    async function install(version) {
+        const root = resolve(dataDir, "launcher", version);
+        const pkg = resolve(root, "node_modules/agentroam");
+        await mkdir(resolve(pkg, "bin"), { recursive: true });
+        await writeFile(resolve(pkg, "package.json"), JSON.stringify({ name: "agentroam", version }));
+        await writeFile(resolve(pkg, "bin/agentroam.mjs"), "// fixture");
+        return root;
+    }
+    const current = await install("0.2.0-preview.19");
+    const config = { dataDir, version: "0.2.0-preview.19", cliPath: resolve(current, "node_modules/agentroam/bin/agentroam.mjs"), roots: [] };
+    return { dataDir, current, config, install };
+}
+it("removes an older managed program while retaining current, newer versions and user data", async () => {
+    const f = await fixture();
+    const old = await f.install("0.2.0-preview.18");
+    const newer = await f.install("0.2.0-preview.20");
+    for (const file of ["config.json", "agent.db", "pairing.db"])
+        await writeFile(resolve(f.dataDir, file), "preserve");
+    await cleanupOldLaunchers(f.config, () => { });
+    await expect(readFile(resolve(old, "node_modules/agentroam/package.json"))).rejects.toMatchObject({ code: "ENOENT" });
+    for (const root of [f.current, newer])
+        expect(await readFile(resolve(root, "node_modules/agentroam/package.json"), "utf8")).toContain("agentroam");
+    for (const file of ["config.json", "agent.db", "pairing.db"])
+        expect(await readFile(resolve(f.dataDir, file), "utf8")).toBe("preserve");
+});
+it("preserves project roots, unexpected data, locked installs, and linked versions", async () => {
+    const f = await fixture();
+    const project = await f.install("0.2.0-preview.15");
+    f.config.roots = [project];
+    const data = await f.install("0.2.0-preview.16");
+    await writeFile(resolve(data, "session.db"), "preserve");
+    const locked = await f.install("0.2.0-preview.17");
+    await mkdir(`${locked}.lock`);
+    await symlink(data, resolve(f.dataDir, "launcher/0.2.0-preview.14"));
+    await cleanupOldLaunchers(f.config, () => { });
+    for (const root of [project, data, locked])
+        expect(await readFile(resolve(root, "node_modules/agentroam/package.json"), "utf8")).toContain("agentroam");
+});
+it("does not clean when the active CLI is outside the managed installation", async () => {
+    const f = await fixture();
+    const old = await f.install("0.2.0-preview.18");
+    f.config.cliPath = resolve(f.dataDir, "npx/agentroam.mjs");
+    await cleanupOldLaunchers(f.config, () => { });
+    expect(await readFile(resolve(old, "node_modules/agentroam/package.json"), "utf8")).toContain("agentroam");
+});
+it.each(["starting", "failed", "ready"])("cleans only after a replacement service is ready (%s)", async (status) => {
+    const { runServiceCommand } = await import("./service-command.js");
+    const { parseArgs } = await import("../args.js");
+    const f = await fixture();
+    const old = await f.install("0.2.0-preview.18");
+    const install = async () => {
+        if (status === "failed")
+            throw new Error("activation failed");
+        return { definition: "test", state: { status, version: f.config.version } };
+    };
+    const action = runServiceCommand(parseArgs(["service", "install", "--data-dir", f.dataDir]), {
+        platform: "darwin", arch: "arm64", nodeVersion: "25.8.0", nodePath: process.execPath,
+        cliPath: f.config.cliPath, version: f.config.version, log: () => { },
+        codexResolver: async () => ({ executable: "/test/codex", version: "test", source: "global" }),
+        controller: { install },
+    });
+    if (status === "failed")
+        await expect(action).rejects.toThrow("activation failed");
+    else
+        await action;
+    const manifest = readFile(resolve(old, "node_modules/agentroam/package.json"), "utf8");
+    if (status === "ready")
+        await expect(manifest).rejects.toMatchObject({ code: "ENOENT" });
+    else
+        expect(await manifest).toContain("agentroam");
+});

package/dist/service/service-command.js

@@ -6,6 +6,7 @@ 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";
+import { cleanupOldLaunchers } from "./launcher-cleanup.js";
 export async function runServiceCommand(options, context) {
     const platform = context.platform ?? process.platform;
     const log = context.log ?? console.log;
@@ -57,10 +58,15 @@ export async function runServiceCommand(options, context) {
             };
             const { definition, state } = await controller.install(config);
             log(`✓ AgentRoam service installed: ${definition}`);
+            if (state?.status === "ready" && state.version === config.version)
+                await cleanupOldLaunchers(config, log);
             if (state?.status === "ready" && state.accessUrl) {
                 log(`Open: ${state.accessUrl}`);
-                if (state.localUrl)
-                    log(`电脑本机：${state.localUrl.replace(/\/$/, "")}/web（配对后可进行远程授权）`);
+                if (state.localUrl) {
+                    log(`远程桌面授权地址：${state.localUrl.replace(/\/$/, "")}/web`);
+                    log('请在运行 CLI 的这台电脑上用浏览器打开此地址，配对后点击“远程授权”（盾牌图标）。');
+                    log('按提示授予“屏幕录制”和“辅助功能”权限，然后点击“开启共享”。');
+                }
                 await (context.pairingPrinter ?? printPairingCode)(options.dataDir, log, { accessUrl: state.accessUrl, qr: options.qr, interactive: stdoutIsTTY });
             }
             else

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

@@ -25,7 +25,7 @@ describe("runServiceCommand", () => {
     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" },
-            state: { status: "ready", accessUrl: "https://ready.example/web" },
+            state: { status: "ready", accessUrl: "https://ready.example/web", localUrl: "http://127.0.0.1:4317/" },
             definition: "/Users/test/Library/LaunchAgents/com.agentroam.service.plist",
         }));
         const log = vi.fn();
@@ -53,6 +53,8 @@ describe("runServiceCommand", () => {
             installedAt: "2026-09-03T00:00:00.000Z",
         }));
         expect(log).toHaveBeenCalledWith("Open: https://ready.example/web");
+        expect(log).toHaveBeenCalledWith("远程桌面授权地址：http://127.0.0.1:4317/web");
+        expect(log).toHaveBeenCalledWith(expect.stringContaining("屏幕录制"));
     });
     it("prints a scannable QR code after the URL on interactive terminals", async () => {
         const log = vi.fn();

package/install/README.md

@@ -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.18`.
+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.20`.
 
 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

@@ -226,7 +226,7 @@ if ($PathParts -notcontains $WrapperDir) {
 }
 
 & $NodeBin $Entry doctor --data-dir $DataDir
-if ($LASTEXITCODE -ne 0) { throw "AgentRoam doctor failed with exit code $LASTEXITCODE" }
+if ($LASTEXITCODE -ne 0) { Write-Warning "Some component checks failed; continuing background service installation. Affected features may be unavailable. Run agentroam doctor to retry." }
 if ($env:AGENTROAM_INSTALL_SKIP_SERVICE -eq "1") {
   Write-Host "AgentRoam service registration skipped for isolated verification."
 } else {

package/install/install-agentroam.sh

@@ -4,7 +4,7 @@ set -eu
 NODE_VERSION="22.22.0"
 MINIMUM_NODE_VERSION="22.22.0"
 # Default to the newest published preview; pin an exact version via
-# AGENTROAM_VERSION=0.2.0-preview.18 sh install-agentroam.sh
+# AGENTROAM_VERSION=0.2.0-preview.20 sh install-agentroam.sh
 AGENTROAM_VERSION_REQUEST="${AGENTROAM_VERSION:-preview}"
 AGENTROAM_VERSION=""
 NODE_ARCHIVE="node-v22.22.0-darwin-arm64.tar.xz"
@@ -253,7 +253,9 @@ wrapper_temp=$(mktemp "$WRAPPER_DIR/.agentroam.XXXXXX")
 chmod 755 "$wrapper_temp"
 mv "$wrapper_temp" "$WRAPPER_PATH"
 
-"$NODE_BIN" "$entry" doctor --data-dir "$DATA_DIR"
+if ! "$NODE_BIN" "$entry" doctor --data-dir "$DATA_DIR"; then
+  printf 'Warning: some component checks failed; continuing background service installation. Affected features may be unavailable. Run agentroam doctor to retry.\n' >&2
+fi
 if [ "${AGENTROAM_INSTALL_SKIP_SERVICE:-}" = "1" ]; then
   printf 'AgentRoam service registration skipped for isolated verification.\n'
 else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentroam",
-  "version": "0.2.0-preview.19",
+  "version": "0.2.0-preview.20",
   "description": "Zero-install mobile remote terminal and file console",
   "type": "module",
   "bin": {
@@ -26,12 +26,12 @@
     "undici": "^6.25.0"
   },
   "optionalDependencies": {
-    "agentroam-runtime-darwin-arm64": "0.2.0-preview.18",
-    "agentroam-runtime-win32-x64": "0.2.0-preview.18",
-    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.18",
-    "agentroam-cloudflared-win32-x64": "0.2.0-preview.18",
-    "agentroam-tui-darwin-arm64": "0.2.0-preview.19",
-    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.19"
+    "agentroam-runtime-darwin-arm64": "0.2.0-preview.20",
+    "agentroam-runtime-win32-x64": "0.2.0-preview.20",
+    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.20",
+    "agentroam-cloudflared-win32-x64": "0.2.0-preview.20",
+    "agentroam-tui-darwin-arm64": "0.2.0-preview.20",
+    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.20"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",