agentroam 0.2.0-preview.36 → 0.2.0-preview.38

package/dist/device-pairing.js

@@ -1,49 +1,26 @@
 import { createInterface } from "node:readline/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import { createReadStream, openSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { renderQr } from "./qr.js";
+import { localServiceRequest, LocalServiceHttpError } from "./local-service-request.js";
+import { withCliProgress, withoutCliProgress } from "../bin/cli-progress.mjs";
 /** Resolve a private local descriptor; never send the administrative token to a tunnel URL. */
 export async function pairingAdmin(dataDir, action, body, options = {}) {
-    const request = options.request ?? fetch;
-    const directory = options.registry ?? process.env.AGENTROAM_DISCOVERY_DIR ?? join(homedir(), ".agentroam", "services");
-    const names = await readdir(directory).catch((error) => { if (error.code === "ENOENT")
-        return []; throw error; });
-    const candidates = [];
-    for (const name of names.filter((name) => name.endsWith(".json"))) {
-        try {
-            const d = JSON.parse(await readFile(join(directory, name), "utf8"));
-            const url = new URL(d.url);
-            if (d.protocol !== 1 || typeof d.instanceId !== "string" || !Number.isSafeInteger(d.pid) || d.pid <= 0 || ![resolve(dataDir), resolve(dataDir, "data")].includes(d.dataDir) || !/^[a-f0-9]{64}$/.test(d.token))
-                continue;
-            if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/" || url.username || url.password || url.search || url.hash)
-                continue;
-            const response = await request(new URL("/api/desktop/identity", url), { headers: { "x-agentroam-desktop-token": d.token }, redirect: "error", signal: AbortSignal.timeout(1500) });
-            if (!response.ok)
-                continue;
-            const identity = await response.json();
-            if (identity.protocol === 1 && identity.instanceId === d.instanceId && identity.dataDir === d.dataDir)
-                candidates.push(d);
-        }
-        catch { /* Stale descriptors are expected after a process crash. */ }
-    }
-    if (candidates.length !== 1)
-        throw new Error(candidates.length ? "多个服务使用此数据目录，请先停止多余实例" : "未找到运行中的 AgentRoam 服务，请先启动服务或指定 --data-dir");
-    const d = candidates[0];
     const readOnly = ["devices", "requests", "audit"].includes(action);
-    const response = await request(new URL(`/api/pairing/admin/${action}`, d.url), {
-        method: readOnly ? "GET" : "POST",
-        headers: { "x-agentroam-desktop-token": d.token, "content-type": "application/json" },
-        ...(readOnly ? {} : { body: JSON.stringify(body ?? {}) }),
-        redirect: "error", signal: AbortSignal.timeout(5000),
-    });
-    if (!response.ok) {
-        const message = response.status === 423 ? "远程访问已锁定，请先执行 agentroam unlock" : response.status === 410 ? "请求已过期或已处理" : response.status === 409 ? "核对短语不匹配" : `设备授权操作失败 (HTTP ${response.status})`;
+    try {
+        return await localServiceRequest(dataDir, `/api/pairing/admin/${action}`, {
+            ...options, method: readOnly ? "GET" : "POST", ...(readOnly ? {} : { body: body ?? {} }),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof LocalServiceHttpError))
+            throw error;
+        const message = error.status === 423 ? "远程访问已锁定，请先执行 agentroam unlock" : error.status === 410 ? "请求已过期或已处理" : error.status === 409 ? "核对短语不匹配" : `设备授权操作失败 (HTTP ${error.status})`;
         throw new Error(message);
     }
-    return response.json();
 }
 export function terminalText(value) { return value.replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ""); }
 export function pairingQrPayload(accessUrl, grant) {
@@ -53,7 +30,7 @@ export function pairingQrPayload(accessUrl, grant) {
     return `${url.origin}/pair#pair=${grant}`;
 }
 export async function printPairingCode(dataDir, log = console.log, options = {}) {
-    const result = await pairingAdmin(dataDir, "code");
+    const result = await withCliProgress("正在生成设备配对码", () => pairingAdmin(dataDir, "code"));
     log(`配对码：${result.code.slice(0, 4)} ${result.code.slice(4)}`);
     log("5 分钟内有效，仅可使用一次。手机输入后仍需在电脑上确认核对短语。");
     if ((options.qr ?? true) && (options.interactive ?? process.stdout.isTTY)) {
@@ -61,16 +38,19 @@ export async function printPairingCode(dataDir, log = console.log, options = {})
         if (accessUrl) {
             // Validate the public address before minting an invitation. Never persist the grant.
             pairingQrPayload(accessUrl, "a".repeat(43));
-            const { grant } = await pairingAdmin(dataDir, "qr");
+            const qr = await withCliProgress("正在生成手机连接二维码", async () => {
+                const { grant } = await pairingAdmin(dataDir, "qr");
+                return renderQr(pairingQrPayload(accessUrl, grant));
+            });
             log("手机扫码直接连接（5 分钟、一次有效，请勿分享截图）：");
-            log(await renderQr(pairingQrPayload(accessUrl, grant)));
+            log(qr);
         }
         else
             log("生成 App 授权二维码：agentroam pair --url <手机可访问的服务器地址>");
     }
     const approvalInput = resolveApprovalInput(options);
     if (approvalInput) {
-        await watchPairingApproval(dataDir, result.expiresAt, { log, signal: options.signal, input: approvalInput });
+        await withCliProgress("正在等待手机扫码或输入配对码", () => watchPairingApproval(dataDir, result.expiresAt, { log, signal: options.signal, input: approvalInput }));
     }
     else
         log("查看请求：agentroam approvals；批准：agentroam approve <请求ID> --phrase <手机核对短语>");
@@ -127,7 +107,7 @@ export async function watchPairingApproval(dataDir, codeExpiresAt, options = {})
             log(`请求 ID：${request.id}`);
             log(`核对短语：${request.phrase}`);
             const confirm = options.confirm ?? ((request, signal) => confirmOnTerminal(request, signal, options.input));
-            const approved = await confirm(request, options.signal);
+            const approved = await withoutCliProgress(() => confirm(request, options.signal));
             if (options.signal?.aborted)
                 return;
             if (Date.now() >= request.expires) {

package/dist/instance-takeover.js

@@ -1,4 +1,5 @@
-import { readdir, readFile, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { readdir, readFile, mkdir, writeFile, rm, realpath, rename } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -68,8 +69,11 @@ export async function stopPreviousInstances(dataDir, log, dependencies = {}) {
         return []; throw error; });
     for (const name of names.filter(name => name.endsWith(".json"))) {
         let d;
+        let source;
+        const recordPath = join(registry, name);
         try {
-            d = JSON.parse(await readFile(join(registry, name), "utf8"));
+            source = await readFile(recordPath, "utf8");
+            d = JSON.parse(source);
             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);
@@ -90,8 +94,25 @@ export async function stopPreviousInstances(dataDir, log, dependencies = {}) {
             identity = await response.json();
         }
         catch {
-            if ((dependencies.alive ?? alive)(d.pid))
-                throw new Error("同一数据目录的旧实例无法核验，请先停止旧实例再重试");
+            if ((dependencies.alive ?? alive)(d.pid)) {
+                const processes = dependencies.processes ?? processList;
+                const owner = (await processes()).find(p => p.pid === d.pid);
+                // An unavailable gateway may still own live sessions. Only quarantine
+                // when the PID demonstrably belongs to a different kind of process.
+                if (!owner?.command.trim() || /[\\/]ws-server\.mjs(?:["\s]|$)|[\\/]agentroam[\\/]bin[\\/]agentroam\.mjs(?:["\s]|$)/.test(owner.command)) {
+                    throw new Error("同一数据目录的旧实例无法核验，请先停止旧实例再重试");
+                }
+                const current = (await processes()).find(p => p.pid === d.pid);
+                if (!current || current.ppid !== owner.ppid || current.command !== owner.command) {
+                    throw new Error("旧实例身份已变化，请重试");
+                }
+                if (await readFile(recordPath, "utf8") !== source)
+                    throw new Error("旧实例记录已变化，请重试");
+                const backupDir = join(registry, "stale");
+                await mkdir(backupDir, { recursive: true, mode: 0o700 });
+                await rename(recordPath, join(backupDir, `${randomUUID()}-${name}`));
+                log("检测到旧服务记录的 PID 已被其他进程复用，已备份失效记录，继续启动。");
+            }
             continue;
         }
         if (identity.protocol !== 1 || identity.instanceId !== d.instanceId || identity.dataDir !== d.dataDir)

package/dist/local-desktop-url.js

@@ -1,6 +1,6 @@
 export function printLocalDesktopUrl(localUrl, log = console.log, platform = process.platform) {
     log(`远程桌面授权地址：${localUrl.replace(/\/$/, '')}/web`);
-    log('请在运行 CLI 的这台电脑上用浏览器打开此地址，配对后点击“远程授权”（盾牌图标）。');
+    log('重新授权：agentroam desktop authorize；浏览器备用入口：在这台电脑打开上述地址，配对后点击“远程授权”（盾牌图标）。');
     if (platform === 'win32')
         log('点击“开启共享”。请保持 Windows 已登录且未锁屏；暂不支持 UAC 安全桌面和管理员窗口控制。');
     else

package/dist/local-service-request.js

@@ -0,0 +1,52 @@
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export class LocalServiceHttpError extends Error {
+    status;
+    constructor(status) {
+        super(`本机服务请求失败 (HTTP ${status})`);
+        this.status = status;
+    }
+}
+/** Resolve an identity-checked loopback service; never send its token to a tunnel. */
+export async function localServiceRequest(dataDir, path, options = {}) {
+    if (!path.startsWith("/api/"))
+        throw new Error("无效的本机服务路径");
+    const request = options.request ?? fetch;
+    const directory = options.registry ?? process.env.AGENTROAM_DISCOVERY_DIR ?? join(homedir(), ".agentroam", "services");
+    const names = await readdir(directory).catch((error) => { if (error.code === "ENOENT")
+        return []; throw error; });
+    const candidates = [];
+    for (const name of names.filter((name) => name.endsWith(".json"))) {
+        try {
+            const d = JSON.parse(await readFile(join(directory, name), "utf8"));
+            const url = new URL(d.url);
+            if (d.protocol !== 1 || typeof d.instanceId !== "string" || !Number.isSafeInteger(d.pid) || d.pid <= 0 || ![resolve(dataDir), resolve(dataDir, "data")].includes(d.dataDir) || !/^[a-f0-9]{64}$/.test(d.token))
+                continue;
+            if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/" || url.username || url.password || url.search || url.hash)
+                continue;
+            const response = await request(new URL("/api/desktop/identity", url), { headers: { "x-agentroam-desktop-token": d.token }, redirect: "error", signal: AbortSignal.timeout(1500) });
+            if (!response.ok)
+                continue;
+            const identity = await response.json();
+            if (identity.protocol === 1 && identity.instanceId === d.instanceId && identity.dataDir === d.dataDir)
+                candidates.push(d);
+        }
+        catch { /* Stale descriptors are expected after a process crash. */ }
+    }
+    if (candidates.length !== 1)
+        throw new Error(candidates.length ? "多个服务使用此数据目录，请先停止多余实例" : "未找到运行中的 AgentRoam 服务，请先启动服务或指定 --data-dir");
+    const d = candidates[0];
+    const url = new URL(path, d.url);
+    if (url.origin !== new URL(d.url).origin)
+        throw new Error("无效的本机服务路径");
+    const response = await request(url, {
+        method: options.method ?? "GET",
+        headers: { "x-agentroam-desktop-token": d.token, "content-type": "application/json", origin: new URL(d.url).origin },
+        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        redirect: "error", signal: AbortSignal.timeout(options.timeoutMs ?? 5000),
+    });
+    if (!response.ok)
+        throw new LocalServiceHttpError(response.status);
+    return response.json();
+}

package/dist/runtime-manager.js

@@ -7,6 +7,7 @@ import { resolveOpenCodeRuntime, } from "./opencode-runtime-manager.js";
 import { resolvePlatformRuntime } from "./platform-packages.js";
 import { findAvailablePort } from "./port.js";
 import { ProcessSupervisor } from "./process-supervisor.js";
+import { withCliProgress } from "../bin/cli-progress.mjs";
 export class RuntimeManager {
     supervisor;
     codexResolver;
@@ -22,8 +23,8 @@ export class RuntimeManager {
         const port = await findAvailablePort(options.port);
         const dataDir = resolve(options.dataDir);
         await Promise.all(["data", "bin", "cache", "logs"].map((name) => mkdir(resolve(dataDir, name), { recursive: true })));
-        const codexEnvironment = await prepareCodexRuntimeEnvironment(process.env, { dataDir, target }, this.codexResolver, this.report);
-        const childEnvironment = await prepareOpenCodeRuntimeEnvironment(codexEnvironment, { dataDir, target }, this.opencodeResolver, this.report);
+        const codexEnvironment = await withCliProgress("正在准备 Codex 组件", () => prepareCodexRuntimeEnvironment(process.env, { dataDir, target }, this.codexResolver, this.report));
+        const childEnvironment = await withCliProgress("正在准备 OpenCode 组件", () => prepareOpenCodeRuntimeEnvironment(codexEnvironment, { dataDir, target }, this.opencodeResolver, this.report));
         const { runtimeRoot } = resolvePlatformRuntime(target);
         await repairNativeRuntimePermissions(runtimeRoot);
         const gateway = resolve(runtimeRoot, "ws-server.mjs");
@@ -53,7 +54,7 @@ export class RuntimeManager {
             child.once("exit", (code, signal) => resolveExit({ code, signal }));
         });
         const localUrl = `http://127.0.0.1:${port}`;
-        const status = await waitForHealth(`${localUrl}/api/web-auth/status`, child, 20_000);
+        const status = await withCliProgress("正在等待本机服务就绪", () => waitForHealth(`${localUrl}/api/web-auth/status`, child, 20_000));
         return {
             port,
             localUrl,

package/dist/service/launcher-cleanup.js

@@ -1,5 +1,18 @@
 import { lstat, readFile, readdir, realpath, rm } from "node:fs/promises";
 import { relative, resolve, sep } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function processPathsInUse() {
+    // Windows has no reliable cwd inventory here: retain old installs instead.
+    if (process.platform === "win32")
+        throw new Error("Process paths unavailable");
+    const { stdout } = await execFileAsync(process.platform === "darwin" ? "/usr/sbin/lsof" : "lsof", ["-nP", "-d", "cwd,txt", "-Fn"], { timeout: 5_000, maxBuffer: 16 * 1024 * 1024 });
+    const paths = stdout.split("\n").filter(line => line.startsWith("n/")).map(line => line.slice(1));
+    if (!paths.length)
+        throw new Error("Incomplete process paths");
+    return [process.cwd(), ...paths];
+}
 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;
@@ -18,7 +31,7 @@ function contains(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) {
+export async function cleanupOldLaunchers(config, log, context = {}) {
     try {
         const dataDir = await realpath(config.dataDir);
         const launcherDir = resolve(dataDir, "launcher");
@@ -47,6 +60,11 @@ export async function cleanupOldLaunchers(config, log) {
                 const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
                 if (manifest.name !== "agentroam" || manifest.version !== entry.name)
                     continue;
+                const usedPaths = await (context.pathsInUse ?? processPathsInUse)();
+                if (usedPaths.some(path => contains(candidate, path))) {
+                    log(`旧版 CLI ${entry.name} 仍被进程使用，已保留。`);
+                    continue;
+                }
                 await rm(candidate, { recursive: true });
                 log(`✓ 已清理旧版 CLI ${entry.name}，配置和数据已保留`);
             }

package/dist/service/macos-launch-agent.js

@@ -60,13 +60,13 @@ export class MacLaunchAgent {
         const status = await this.status();
         if (!status.installed)
             throw new Error("AgentRoam service is not installed");
+        const paths = resolveServicePaths(this.homeDir, status.config?.dataDir);
         if (status.running)
-            return status.state;
+            return this.waitForReady(paths);
         if (status.loaded)
             await this.runRequired("launchctl", ["kickstart", this.serviceTarget]);
         else
             await this.bootstrap(status.definition);
-        const paths = resolveServicePaths(this.homeDir, status.config?.dataDir);
         return this.waitForReady(paths, status.state?.pid);
     }
     async stop() {
@@ -84,13 +84,14 @@ export class MacLaunchAgent {
         const config = await readServiceConfig(basePaths);
         const paths = resolveServicePaths(this.homeDir, config?.dataDir);
         const installed = await pathExists(paths.plistPath);
-        const job = installed ? await this.inspectJob() : { loaded: false, running: false };
+        const job = installed ? await this.inspectJob() : { loaded: false, running: false, pid: undefined };
+        const state = await readServiceState(paths);
         return {
             installed,
             loaded: job.loaded,
             running: job.running,
             config,
-            state: await readServiceState(paths),
+            state: job.running && state?.pid !== job.pid ? null : state,
             definition: paths.plistPath,
         };
     }
@@ -157,9 +158,11 @@ export class MacLaunchAgent {
     }
     async inspectJob() {
         const result = await this.runner("launchctl", ["print", this.serviceTarget]);
+        const pid = /\bpid\s*=\s*(\d+)\b/.exec(result.stdout);
         return {
             loaded: result.code === 0,
             running: result.code === 0 && /\bstate\s*=\s*running\b/.test(result.stdout),
+            pid: pid ? Number(pid[1]) : undefined,
         };
     }
     async bootstrap(definition) {
@@ -195,10 +198,13 @@ export class MacLaunchAgent {
         const deadline = Date.now() + this.readyTimeoutMs;
         do {
             const state = await readServiceState(paths);
-            if (state?.status === "ready" && (!previousPid || state.pid !== previousPid))
-                return state;
+            if (state?.status === "ready" && state.accessUrl && (!previousPid || state.pid !== previousPid)) {
+                const job = await this.inspectJob();
+                if (job.running && job.pid === state.pid)
+                    return state;
+            }
             if (Date.now() >= deadline)
-                return state;
+                return state?.status === "ready" ? null : state;
             await delay(this.pollIntervalMs);
         } while (true);
     }

package/dist/service/service-command.js

@@ -9,6 +9,8 @@ import { WindowsTaskService } from "./windows-task-service.js";
 import { assertSupportedNodeVersion } from "../../bin/runtime-policy.mjs";
 import { cleanupOldLaunchers } from "./launcher-cleanup.js";
 import { setupCodexDesktop } from "../codex-desktop-setup.js";
+import { authorizeRemoteDesktop } from "../desktop-authorization.js";
+import { withCliProgress } from "../../bin/cli-progress.mjs";
 export async function runServiceCommand(options, context) {
     const platform = context.platform ?? process.platform;
     const log = context.log ?? console.log;
@@ -30,14 +32,14 @@ export async function runServiceCommand(options, context) {
             const environmentPath = buildServiceEnvironmentPath(context.nodePath, environment.PATH ?? environment.Path, platform);
             let codexPath;
             try {
-                const codex = await (context.codexResolver ?? resolveCodexRuntime)({
+                const codex = await withCliProgress("正在检查和安装 Codex 组件", () => (context.codexResolver ?? resolveCodexRuntime)({
                     dataDir: options.dataDir,
                     target: detectPlatform(platform, context.arch ?? process.arch, nodeVersion),
                     environment: { ...environment, PATH: environmentPath },
                     platform,
                     nodeExecutable: context.nodePath,
                     onProgress: (message) => log(`… ${message}`),
-                });
+                }));
                 codexPath = codex.executable;
             }
             catch (error) {
@@ -58,36 +60,47 @@ export async function runServiceCommand(options, context) {
                 dataDir: options.dataDir,
                 installedAt: now.toISOString(),
             };
-            const { definition, state } = await controller.install(config);
+            const { definition, state } = await withCliProgress("正在安装后台服务，等待服务和手机访问连接就绪", () => controller.install(config));
             log(`✓ AgentRoam service installed: ${definition}`);
+            if (state?.localUrl && state.status !== "stopped")
+                printLocalDesktopUrl(state.localUrl, log, platform);
+            requireReadyService(state);
+            if (state?.localUrl && state.status !== "stopped" && (platform === "darwin" || platform === "win32")) {
+                if (environment.AGENTROAM_INSTALL_REMOTE_DESKTOP === "skip") {
+                    log("已跳过安装时远程桌面授权，可稍后执行 agentroam desktop authorize。");
+                }
+                else {
+                    try {
+                        await (context.desktopAuthorization ?? authorizeRemoteDesktop)(options.dataDir, { platform, isTTY: stdoutIsTTY, log });
+                    }
+                    catch (error) {
+                        log(`远程桌面授权未完成：${error instanceof Error ? error.message : error}`);
+                        log("AgentRoam 安装继续；可稍后执行 agentroam desktop authorize，或在本机浏览器的“远程授权”面板中重试。");
+                    }
+                }
+            }
             if (platform === "darwin" && !options.desktopSetup)
                 log("官方 Codex 桌面共享后端：agentroam codex-desktop --setup；预演：agentroam codex-desktop --dry-run。");
-            if (state?.status === "ready" && state.version === config.version)
+            if (state.version === config.version)
                 await cleanupOldLaunchers(config, log);
-            if (state?.localUrl && state.status !== "stopped")
-                printLocalDesktopUrl(state.localUrl, log, platform);
             if (options.desktopSetup && platform === "darwin") {
-                await (context.desktopSetup ?? setupCodexDesktop)(options, { platform, environment, service: config, log });
-            }
-            if (state?.status === "ready" && state.accessUrl) {
-                log(`Open: ${state.accessUrl}`);
-                await (context.pairingPrinter ?? printPairingCode)(options.dataDir, log, { accessUrl: state.accessUrl, qr: options.qr, interactive: stdoutIsTTY });
+                await withCliProgress("正在配置官方 Codex 桌面共享连接", () => (context.desktopSetup ?? setupCodexDesktop)(options, { platform, environment, service: config, log }));
             }
-            else
-                log("Service is starting. Run `agentroam service url` and `agentroam pair` shortly.");
+            log(`Open: ${state.accessUrl}`);
+            await (context.pairingPrinter ?? printPairingCode)(options.dataDir, log, { accessUrl: state.accessUrl, qr: options.qr, interactive: stdoutIsTTY });
             return;
         }
         case "start": {
-            const state = await controller.start();
-            log("✓ AgentRoam service started");
-            if (state?.status === "ready" && state.accessUrl)
-                await logAccessUrl(state.accessUrl);
+            const state = await withCliProgress("正在启动后台服务，等待服务和手机访问连接就绪", () => controller.start());
             if (state?.localUrl && state.status !== "stopped")
                 printLocalDesktopUrl(state.localUrl, log, platform);
+            requireReadyService(state);
+            log("✓ AgentRoam service started");
+            await logAccessUrl(state.accessUrl);
             return;
         }
         case "stop":
-            await controller.stop();
+            await withCliProgress("正在停止后台服务", () => controller.stop());
             log("✓ AgentRoam service stopped");
             return;
         case "status": {
@@ -122,12 +135,12 @@ export async function runServiceCommand(options, context) {
             return;
         }
         case "restart": {
-            const state = await controller.restart();
-            log("✓ AgentRoam service restarted");
-            if (state?.status === "ready" && state.accessUrl)
-                await logAccessUrl(state.accessUrl);
+            const state = await withCliProgress("正在重启后台服务，等待服务和手机访问连接就绪", () => controller.restart());
             if (state?.localUrl && state.status !== "stopped")
                 printLocalDesktopUrl(state.localUrl, log, platform);
+            requireReadyService(state);
+            log("✓ AgentRoam service restarted");
+            await logAccessUrl(state.accessUrl);
             return;
         }
         case "uninstall": {
@@ -140,6 +153,11 @@ export async function runServiceCommand(options, context) {
             throw cliError("service action is required");
     }
 }
+function requireReadyService(state) {
+    if (state?.status !== "ready" || !state.accessUrl) {
+        throw Object.assign(new Error(`AgentRoam 后台服务未就绪（${state?.status ?? "未取得状态"}）。请运行 agentroam service logs 查看原因，修复后运行 agentroam service start，再执行 agentroam pair。`), { exitCode: 1 });
+    }
+}
 export function buildServiceEnvironmentPath(nodePath, pathValue, platform) {
     const separator = platform === "win32" ? ";" : delimiter;
     const nodeDirectory = platform === "win32" ? win32.dirname(nodePath) : dirname(nodePath);

package/dist/service/windows-task-service.js

@@ -55,9 +55,9 @@ export class WindowsTaskService {
         const status = await this.status();
         if (!status.installed)
             throw new Error("AgentRoam service is not installed");
-        if (status.running)
-            return status.state;
         const paths = resolveServicePaths(this.homeDir, status.config?.dataDir);
+        if (status.running)
+            return this.waitForReady(paths);
         await Promise.all([removeIfExists(paths.statePath), removeIfExists(paths.urlPath)]);
         await this.runRequired(buildStartTaskScript());
         return this.waitForReady(paths, status.state?.pid);
@@ -88,12 +88,13 @@ export class WindowsTaskService {
         const config = await readServiceConfig(basePaths);
         const paths = resolveServicePaths(this.homeDir, config?.dataDir);
         const task = await this.inspectTask();
+        const state = await readServiceState(paths);
         return {
             installed: task.installed,
             loaded: task.installed,
             running: task.running,
             config,
-            state: await readServiceState(paths),
+            state: task.running && state && !this.processExists(state.pid) ? null : state,
             definition: WINDOWS_SERVICE_NAME,
         };
     }
@@ -185,10 +186,13 @@ export class WindowsTaskService {
         const deadline = Date.now() + this.readyTimeoutMs;
         do {
             const state = await readServiceState(paths);
-            if (state?.status === "ready" && (!previousPid || state.pid !== previousPid))
-                return state;
+            if (state?.status === "ready" && state.accessUrl && (!previousPid || state.pid !== previousPid)) {
+                const task = await this.inspectTask();
+                if (task.running && this.processExists(state.pid))
+                    return state;
+            }
             if (Date.now() >= deadline)
-                return state;
+                return state?.status === "ready" ? null : state;
             await delay(this.pollIntervalMs);
         } while (true);
     }

package/dist/unlock-service.js

@@ -1,7 +1,15 @@
-import { spawnSync } from "node:child_process";
+import { execFile } from "node:child_process";
 import { resolve } from "node:path";
 const SERVICE_NAME = "AgentRoamUnlock";
 const DISPLAY_NAME = "AgentRoam Remote Unlock";
+// Keep the event loop free while PowerShell waits for UAC or service control.
+const runFile = (file, args, options) => new Promise((resolveResult) => {
+    execFile(file, [...args], options, (error, stdout, stderr) => {
+        resolveResult({ stdout, stderr, status: error ? 1 : 0,
+            ...(error && typeof error.code !== "number" ? { error } : {}),
+        });
+    });
+});
 function psQuote(value) {
     return `'${value.replaceAll("'", "''")}'`;
 }
@@ -59,36 +67,36 @@ function runPowerShell(script, runner) {
         "-EncodedCommand", encodePowerShell(script),
     ], { encoding: "utf8", windowsHide: true });
 }
-export function queryUnlockServiceStatus(runner = spawnSync) {
+export async function queryUnlockServiceStatus(runner = runFile) {
     const script = `$service = Get-Service -Name '${SERVICE_NAME}' -ErrorAction SilentlyContinue
 if (-not $service) { Write-Output 'missing' } elseif ($service.Status -eq 'Running') { Write-Output 'running' } else { Write-Output 'stopped' }
 `;
-    const result = runPowerShell(script, runner);
+    const result = await runPowerShell(script, runner);
     if (result.error)
         throw result.error;
     if (result.status !== 0)
         throw new Error((result.stderr || "远程解锁服务状态查询失败").trim());
     return parseUnlockServiceStatus(result.stdout || "");
 }
-export function runUnlockServiceCommand(action, runtimeRoot, options = {}) {
+export async function runUnlockServiceCommand(action, runtimeRoot, options = {}) {
     const platform = options.platform ?? process.platform;
-    const runner = options.runner ?? spawnSync;
+    const runner = options.runner ?? runFile;
     const log = options.log ?? console.log;
     if (platform !== "win32")
         throw new Error("远程解锁服务仅支持 Windows 10/11 x64");
     if (action === "status") {
-        const status = queryUnlockServiceStatus(runner);
+        const status = await queryUnlockServiceStatus(runner);
         log(status === "running" ? "远程解锁服务正在运行" : status === "stopped" ? "远程解锁服务已安装但未运行" : "远程解锁服务未安装");
         return;
     }
     const executable = unlockServiceExecutable(runtimeRoot);
-    const result = runPowerShell(buildElevatedPowerShell(buildUnlockServiceAdminScript(action, executable)), runner);
+    const result = await runPowerShell(buildElevatedPowerShell(buildUnlockServiceAdminScript(action, executable)), runner);
     if (result.error)
         throw result.error;
     if (result.status !== 0) {
         throw new Error((result.stderr || (action === "install" ? "远程解锁服务安装失败或已取消管理员授权" : "远程解锁服务卸载失败或已取消管理员授权")).trim());
     }
-    const status = queryUnlockServiceStatus(runner);
+    const status = await queryUnlockServiceStatus(runner);
     if (action === "install" && status !== "running")
         throw new Error("远程解锁服务安装后未能启动");
     if (action === "uninstall" && status !== "missing")

package/install/install-agentroam.ps1

@@ -232,7 +232,7 @@ if ($env:AGENTROAM_INSTALL_SKIP_SERVICE -eq "1") {
   Write-Host "AgentRoam service registration skipped for isolated verification."
 } else {
   & $NodeBin $Entry service install --root $ServiceRoot --data-dir $DataDir
-  if ($LASTEXITCODE -ne 0) { throw "AgentRoam service installation failed with exit code $LASTEXITCODE" }
+  if ($LASTEXITCODE -ne 0) { throw "CLI 已安装，但后台服务安装或启动失败（exit $LASTEXITCODE），尚不能扫码连接。请运行 agentroam service logs 查看原因，修复后运行 agentroam service start，再执行 agentroam pair。" }
 }
 Write-Host "`nAgentRoam $AgentRoamVersion installed: $WrapperPath"
 Write-Host "Open a new terminal, then run: agentroam service status"