agentroam 0.2.0-preview.37 → 0.2.0-preview.39

package/bin/cli-progress.d.mts

@@ -0,0 +1,9 @@
+export interface CliProgressOptions {
+  enabled?: boolean;
+  environment?: NodeJS.ProcessEnv;
+  log?: (line: string) => void;
+  delayMs?: number;
+  intervalMs?: number;
+}
+export function withCliProgress<T>(label: string, operation: () => T | Promise<T>, options?: CliProgressOptions): Promise<T>;
+export function withoutCliProgress<T>(operation: () => T | Promise<T>): Promise<T>;

package/bin/cli-progress.mjs

@@ -0,0 +1,65 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const context = new AsyncLocalStorage();
+
+// Append complete lines to stderr so stdout (URLs, QR codes, JSON) stays usable.
+class ProgressReporter {
+  constructor(options) {
+    const environment = options.environment ?? process.env;
+    this.enabled = options.enabled ?? (environment.AGENTROAM_SERVICE !== '1' && environment.AGENTROAM_NO_PROGRESS !== '1');
+    this.log = options.log ?? ((line) => process.stderr.write(`${line}\n`));
+    this.delayMs = options.delayMs ?? 800;
+    this.intervalMs = options.intervalMs ?? 5000;
+    this.steps = [];
+    this.pauses = 0;
+  }
+
+  begin(label) {
+    const step = { label, started: Date.now() };
+    this.steps.push(step);
+    this.schedule(this.delayMs);
+    return () => {
+      const wasActive = this.steps.at(-1) === step;
+      this.steps.splice(this.steps.indexOf(step), 1);
+      if (wasActive) this.schedule(this.delayMs);
+    };
+  }
+
+  schedule(milliseconds) {
+    clearTimeout(this.timer);
+    if (!this.enabled || this.pauses || !this.steps.length) return;
+    this.timer = setTimeout(() => {
+      const step = this.steps.at(-1);
+      const seconds = Math.floor((Date.now() - step.started) / 1000);
+      this.log(`… ${step.label}（已等待 ${seconds} 秒）`);
+      this.schedule(this.intervalMs);
+    }, milliseconds);
+    this.timer.unref?.();
+  }
+
+  pause() {
+    this.pauses++;
+    clearTimeout(this.timer);
+    return () => {
+      this.pauses--;
+      this.schedule(this.delayMs);
+    };
+  }
+}
+
+/** Nested stages share one heartbeat. Timers always stop, including on failure. */
+export async function withCliProgress(label, operation, options = {}) {
+  const reporter = context.getStore() ?? new ProgressReporter(options);
+  return context.run(reporter, async () => {
+    const finish = reporter.begin(label);
+    try { return await operation(); }
+    finally { finish(); }
+  });
+}
+
+/** Suspend every nested heartbeat while a terminal prompt owns the cursor. */
+export async function withoutCliProgress(operation) {
+  const resume = context.getStore()?.pause();
+  try { return await operation(); }
+  finally { resume?.(); }
+}

package/bin/desktop-download.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { Transform, Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { execFile } from 'node:child_process';
+import { withCliProgress } from './cli-progress.mjs';
 
 // 桌面端安装包是构建产物（dmg / exe），进不了只放源码的仓库，只能走 Releases 资产。
 // 资产由 `node scripts/publish-agentroam-release.mjs sync-github --commit <sha>` 上传；
@@ -57,7 +58,7 @@ export async function downloadDesktop(version, { platform = process.platform, ar
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
-    const destination = await downloadDesktop(process.argv[2]);
+    const destination = await withCliProgress('正在下载并校验桌面端安装包', () => downloadDesktop(process.argv[2]));
     console.log(`桌面端安装包已下载：${destination}\n请打开安装包完成安装。首次打开 AgentRoam 后，按提示授权远程桌面。`);
     if (process.platform === 'darwin') execFile('/usr/bin/open', ['-R', destination], () => undefined);
     else if (process.platform === 'win32') execFile('explorer.exe', [`/select,${destination}`], () => undefined);

package/bin/node-preflight.mjs

@@ -5,6 +5,7 @@ import { delimiter, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { MINIMUM_NODE_VERSION, compareNodeVersions, isSupportedNodeVersion, parseNodeVersion } from "./runtime-policy.mjs";
+import { withCliProgress } from "./cli-progress.mjs";
 
 const execFileAsync = promisify(execFile);
 // 安装引导地址：指向仓库主分支上的安装脚本（raw 路径）。
@@ -35,10 +36,9 @@ export async function runNodePreflight(options = {}) {
   const target = detectManagedTarget(platform, arch);
   const dataDir = parsePreflightDataDir(argv, environment, options.homeDir ?? homedir());
   const findSystemNode = options.findSystemNode ?? defaultFindSystemNode;
-  const systemNode = await findSystemNode(environment, platform, options.currentExecutable ?? process.execPath);
-  let executable = systemNode;
-
-  if (!executable) {
+  const executable = await withCliProgress("正在查找或安装兼容的 Node.js", async () => {
+    const systemNode = await findSystemNode(environment, platform, options.currentExecutable ?? process.execPath);
+    if (systemNode) return systemNode;
     const ensureNode = options.ensureNode ?? (async (installOptions) => {
       const { ensureManagedNode } = await import("../dist/node-runtime-manager.js");
       return ensureManagedNode(installOptions);
@@ -50,8 +50,8 @@ export async function runNodePreflight(options = {}) {
       arch,
       onProgress: options.onProgress ?? ((message) => processHost.stderr.write(`${message}\n`)),
     });
-    executable = resolution.executable;
-  }
+    return resolution.executable;
+  }, { environment, log: (line) => processHost.stderr.write(`${line}\n`) });
 
   const spawnChild = options.spawnChild ?? defaultSpawnChild;
   const child = spawnChild(executable, [launcherPath, ...argv], {

package/dist/args.js

@@ -3,11 +3,18 @@ import { resolve } from "node:path";
 export function parseArgs(argv) {
     const values = [...argv];
     let command = "start";
-    if (values[0] && ["start", "doctor", "version", "service", "unlock-service", "update", "update-worker", "pair", "devices", "revoke", "approvals", "approve", "deny", "lock", "unlock", "audit", "codex-desktop"].includes(values[0])) {
+    if (values[0] && ["start", "doctor", "version", "service", "unlock-service", "update", "update-worker", "pair", "devices", "revoke", "approvals", "approve", "deny", "lock", "unlock", "audit", "codex-desktop", "desktop"].includes(values[0])) {
         command = values.shift();
     }
     let serviceAction = null;
     let unlockServiceAction = null;
+    let desktopAction;
+    if (command === "desktop") {
+        const action = values.shift();
+        if (!action || !["authorize", "status", "disable"].includes(action))
+            throw cliError("desktop requires authorize, status, or disable");
+        desktopAction = action;
+    }
     if (command === "service") {
         const action = values.shift();
         if (!action || !["install", "start", "stop", "status", "url", "logs", "restart", "uninstall"].includes(action)) {
@@ -67,9 +74,13 @@ export function parseArgs(argv) {
         ...(approvalRequestId ? { approvalRequestId } : {}),
         updateVersion,
         updateStateFile,
+        ...(desktopAction ? { desktopAction } : {}),
     };
     for (let index = 0; index < values.length && command !== "update-worker"; index++) {
         const arg = values[index];
+        if (command === "desktop" && !["--data-dir", "--help", "-h"].includes(arg)) {
+            throw cliError("desktop accepts only --data-dir");
+        }
         if (command === "codex-desktop" && !["--restart", "--dry-run", "--setup", "--data-dir", "--help", "-h"].includes(arg)) {
             throw cliError("codex-desktop accepts only --setup, --restart, --dry-run and --data-dir");
         }

package/dist/cli.js

@@ -23,6 +23,8 @@ import { runUnlockServiceCommand } from "./unlock-service.js";
 import { createCliErrorLog } from "./error-log.js";
 import { runCodexDesktopCommand } from "./codex-desktop-command.js";
 import { setupCodexDesktop } from "./codex-desktop-setup.js";
+import { runDesktopCommand } from "./desktop-authorization.js";
+import { withCliProgress } from "../bin/cli-progress.mjs";
 const VERSION = AGENTROAM_VERSION;
 export async function main(argv) {
     if (argv.includes("--help") || argv.includes("-h")) {
@@ -40,6 +42,9 @@ export async function main(argv) {
   agentroam revoke <设备ID>          移除一台设备
   agentroam revoke --all            全部退出并取消待用配对码
   agentroam service install|start|stop|restart|status|url|logs|uninstall
+  agentroam desktop authorize       本机弹窗授权远程桌面，无需浏览器；可重复执行
+  agentroam desktop status          重新检查远程桌面权限和共享状态
+  agentroam desktop disable         关闭远程桌面共享，保留系统权限
   agentroam unlock-service install|uninstall|status  管理 Windows 远程解锁服务（安装时弹出 UAC）
   agentroam codex-desktop [--dry-run]  通过共享后端启动官方 Codex 桌面端（macOS）
   agentroam codex-desktop --restart   退出并重新连接官方桌面端，会中断它的全部运行会话
@@ -49,6 +54,19 @@ export async function main(argv) {
         return;
     }
     const options = parseArgs(argv);
+    // Foreground start remains alive after readiness; only its startup stages load.
+    if (options.command === "start" || options.command === "update-worker")
+        return executeCommand(options, argv);
+    const label = options.command === "service" ? `正在处理后台服务：${options.serviceAction}`
+        : options.command === "desktop" ? "正在检查远程桌面授权"
+            : options.command === "codex-desktop" ? "正在配置官方 Codex 桌面连接"
+                : options.command === "doctor" ? "正在检查运行组件"
+                    : options.command === "update" ? "正在检查并准备更新"
+                        : options.command === "unlock-service" ? "正在处理 Windows 解锁服务，请留意管理员授权弹窗"
+                            : "正在处理设备授权命令";
+    await withCliProgress(label, () => executeCommand(options, argv));
+}
+async function executeCommand(options, argv) {
     // CLI 进程自身的按天错误日志:<dataDir>/logs/YYYY-MM-DD.log(NDJSON,与
     // server/desktop 的 core logger 同格式)。uncaughtException 记录后按默认
     // 语义退出(1),unhandledRejection 只记录。
@@ -98,6 +116,12 @@ export async function main(argv) {
         return;
     }
     const target = detectPlatform();
+    if (options.command === "desktop") {
+        if (!argv.includes("--data-dir"))
+            options.dataDir = await installedDataDir(options.dataDir);
+        await runDesktopCommand(options);
+        return;
+    }
     if (options.command === "codex-desktop") {
         if (!argv.includes("--data-dir"))
             options.dataDir = await installedDataDir(options.dataDir);
@@ -110,7 +134,7 @@ export async function main(argv) {
     if (options.command === "unlock-service") {
         if (target !== "windows-amd64")
             throw new Error("远程解锁服务仅支持 Windows 10/11 x64");
-        runUnlockServiceCommand(options.unlockServiceAction, resolvePlatformRuntime(target).runtimeRoot);
+        await runUnlockServiceCommand(options.unlockServiceAction, resolvePlatformRuntime(target).runtimeRoot);
         return;
     }
     if (options.command === "update") {
@@ -129,7 +153,7 @@ export async function main(argv) {
         return;
     }
     console.log(`AgentRoam ${VERSION}\n✓ Node ${process.versions.node} · ${target}`);
-    const sleepInhibitor = await acquireSleepInhibitor();
+    const sleepInhibitor = await withCliProgress("正在准备启动环境", () => acquireSleepInhibitor());
     const controller = new AbortController();
     let runtime = null;
     let relay = null;
@@ -145,23 +169,23 @@ export async function main(argv) {
             return closePromise;
         closing = true;
         controller.abort();
-        closePromise = (async () => {
+        closePromise = withCliProgress("正在停止本机服务和访问连接", 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);
+        releaseStartup = await withCliProgress("正在等待启动锁", () => lockInstanceStartup(options.dataDir));
+        await withCliProgress("正在接管旧实例", () => stopPreviousInstances(options.dataDir, console.log));
         if (controller.signal.aborted)
             return;
         await serviceReporter?.starting();
         reportedStarting = Boolean(serviceReporter);
-        runtime = await new RuntimeManager().start(options, target);
+        runtime = await withCliProgress("正在启动本机服务", () => new RuntimeManager().start(options, target));
         if (controller.signal.aborted) {
             await runtime.close();
             return;
@@ -172,18 +196,19 @@ export async function main(argv) {
         if (!serviceReporter)
             printLocalDesktopUrl(runtime.localUrl);
         const lanUrl = options.localOnly ? findLanUrl(runtime.port) ?? runtime.localUrl : runtime.localUrl;
-        relay = await selectRelay({
+        const relayRuntime = runtime;
+        relay = await withCliProgress("正在建立手机访问连接", () => selectRelay({
             cli: options,
             target,
-            localUrl: runtime.localUrl,
+            localUrl: relayRuntime.localUrl,
             lanUrl,
-            port: runtime.port,
+            port: relayRuntime.port,
             signal: controller.signal,
             log: (line) => process.stderr.write(`${line}\n`),
             onAttempt: (provider) => console.log(`▲ Trying ${providerDisplayName(provider)} relay...`),
             onFailure: (provider, message) => console.error(`⚠ ${providerDisplayName(provider)} unavailable: ${message}`),
             allowLanFallback: options.localOnly,
-        });
+        }));
         if (controller.signal.aborted) {
             await relay.tunnel?.close();
             return;
@@ -255,7 +280,7 @@ async function doctor(target, dataDir) {
         ["better-sqlite3", probeSQLiteRuntime],
     ]) {
         try {
-            await probe(runtimeRequire);
+            await withCliProgress(`正在检查 ${module}`, () => probe(runtimeRequire));
             console.log(`✓ ${module}`);
         }
         catch (error) {
@@ -270,18 +295,18 @@ async function doctor(target, dataDir) {
         reportDoctorFailure(error, "agent-tui: ");
     }
     try {
-        const codex = await resolveCodexRuntime({
+        const codex = await withCliProgress("正在检查和准备 Codex", () => resolveCodexRuntime({
             dataDir,
             target,
             onProgress: (message) => console.log(`… ${message}`),
-        });
+        }));
         console.log(`✓ Codex ${codex.version} (${codex.source}) ${codex.executable}`);
     }
     catch (error) {
         reportDoctorFailure(error, "Codex: ");
     }
     try {
-        const executable = await ensureCloudflared(target, dataDir);
+        const executable = await withCliProgress("正在检查和准备 Cloudflare 组件", () => ensureCloudflared(target, dataDir));
         console.log(`✓ cloudflared ${executable}`);
     }
     catch (error) {

package/dist/codex-desktop-setup.js

@@ -4,6 +4,7 @@ import { ReadStream, WriteStream } from "node:tty";
 import { fileURLToPath } from "node:url";
 import { runCodexDesktopCommand } from "./codex-desktop-command.js";
 import { inspectCodexDesktop } from "./codex-desktop-status.js";
+import { withoutCliProgress } from "../bin/cli-progress.mjs";
 export async function setupCodexDesktop(options, context = {}) {
     if ((context.platform ?? process.platform) !== "darwin")
         return;
@@ -39,7 +40,7 @@ export async function setupCodexDesktop(options, context = {}) {
                 ? `官方 Codex 桌面端当前有 ${snapshot.activity.activeCount} 个运行中的会话。`
                 : "无法可靠确认官方 Codex 桌面端的全部任务已结束。";
             log(reason);
-            const answer = await (context.confirm ?? confirmDesktopRestart)("现在重启桌面端以共享会话？重启可能中断桌面端的所有运行任务；选择保留则暂不能共享原桌面会话 [y/N]：");
+            const answer = await withoutCliProgress(() => (context.confirm ?? confirmDesktopRestart)("现在重启桌面端以共享会话？重启可能中断桌面端的所有运行任务；选择保留则暂不能共享原桌面会话 [y/N]："));
             if (!answer || !/^(?:y|yes)$/i.test(answer.trim())) {
                 deferred();
                 return;

package/dist/desktop-authorization.js

@@ -0,0 +1,148 @@
+import { execFile } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { Readable } from "node:stream";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import { resolveApprovalInput, terminalText } from "./device-pairing.js";
+import { localServiceRequest } from "./local-service-request.js";
+import { withCliProgress, withoutCliProgress } from "../bin/cli-progress.mjs";
+const runFile = promisify(execFile);
+const endpoint = "/api/remote-authorization";
+async function requestAuthorization(dataDir, body) {
+    const status = await localServiceRequest(dataDir, endpoint, {
+        method: body ? "POST" : "GET", body, timeoutMs: body?.action === "request-permission" ? 135_000 : 30_000,
+    });
+    if (status.local !== true || typeof status.supported !== "boolean" || typeof status.installed !== "boolean"
+        || typeof status.enabled !== "boolean" || typeof status.screen !== "boolean" || typeof status.accessibility !== "boolean"
+        || typeof status.online !== "boolean" || typeof status.platform !== "string"
+        || (status.error !== null && typeof status.error !== "string")) {
+        throw new Error("本机远程授权状态无效，请升级 CLI 后重试");
+    }
+    return status;
+}
+/** A native macOS dialog; no browser, shell interpolation, or piped stdin. */
+export async function confirmDesktopAuthorization(platform) {
+    if (platform === "darwin") {
+        const script = 'display dialog "是否启用 AgentRoam 远程桌面？\n接下来将请求屏幕录制和辅助功能权限。授权后，已配对的设备可以查看和控制这台电脑。" with title "AgentRoam 远程桌面授权" buttons {"稍后", "开始授权"} default button "开始授权" cancel button "稍后" giving up after 120';
+        try {
+            const { stdout } = await runFile("/usr/bin/osascript", ["-e", script], { timeout: 125_000, maxBuffer: 4096 });
+            return stdout.includes("button returned:开始授权") && !stdout.includes("gave up:true");
+        }
+        catch {
+            return false;
+        }
+    }
+    const input = resolveApprovalInput({ interactive: true });
+    if (!input)
+        return false;
+    const reader = createInterface({ input, output: process.stdout });
+    try {
+        const answer = await withoutCliProgress(() => reader.question("启用远程桌面，允许已配对设备查看和控制这台电脑？[y/N]："));
+        return /^(y|yes)$/i.test(answer.trim());
+    }
+    finally {
+        reader.close();
+        if (input !== process.stdin && input instanceof Readable)
+            input.destroy();
+    }
+}
+function recoveryHint(log) {
+    log("稍后重新授权：agentroam desktop authorize；也可在本机浏览器的“远程授权”面板中操作。");
+}
+function complete(status) {
+    return status.enabled && status.screen && status.accessibility && !status.error;
+}
+/** Request permissions without enabling sharing, then verify before activation. */
+export async function authorizeRemoteDesktop(dataDir, context = {}) {
+    const log = context.log ?? console.log;
+    if (!(context.isTTY ?? process.stdout.isTTY === true)) {
+        log("未检测到交互终端，已跳过远程桌面授权。");
+        recoveryHint(log);
+        return false;
+    }
+    const request = context.request ?? requestAuthorization;
+    let status = await withCliProgress("正在检查本机远程桌面权限", () => request(dataDir));
+    if (!status.supported)
+        throw new Error("远程桌面支持 macOS 14 及以上的 Apple Silicon 电脑和 Windows 10/11 x64");
+    if (!status.installed)
+        throw new Error("当前 CLI 未包含远程授权组件，请升级 CLI");
+    if (status.enabled) {
+        status = await request(dataDir, { action: "recheck" });
+        if (complete(status)) {
+            log("✓ 远程桌面已授权并开启共享。");
+            return true;
+        }
+    }
+    const platform = context.platform ?? process.platform;
+    const confirm = context.confirm ?? (() => confirmDesktopAuthorization(platform));
+    const confirmed = await (platform === "darwin"
+        ? withCliProgress("正在等待本机授权弹窗确认", confirm)
+        : withoutCliProgress(confirm));
+    if (!confirmed) {
+        log("已跳过远程桌面授权。");
+        recoveryHint(log);
+        return false;
+    }
+    status = await request(dataDir, { action: "recheck" });
+    const wait = context.wait ?? delay;
+    if (platform === "darwin") {
+        for (const permission of ["screen", "accessibility"]) {
+            if (status[permission])
+                continue;
+            const name = permission === "screen" ? "屏幕录制" : "辅助功能";
+            log(`正在请求${name}权限，请在系统设置中允许 AgentRoam Remote Desktop…`);
+            status = await withCliProgress(`正在等待${name}权限，请在系统弹窗或设置中允许`, async () => {
+                let current = await request(dataDir, { action: "request-permission", permission });
+                for (let attempt = 0; !current[permission] && attempt < (context.pollAttempts ?? 60); attempt++) {
+                    await wait(2000);
+                    current = await request(dataDir, { action: "recheck" });
+                }
+                return current;
+            });
+            if (!status[permission]) {
+                log(`${name}权限尚未授予，本次未开启共享。`);
+                recoveryHint(log);
+                return false;
+            }
+        }
+    }
+    if (!status.screen || !status.accessibility) {
+        log("远程桌面尚不可用，请确认系统权限及当前桌面状态，本次未开启共享。");
+        recoveryHint(log);
+        return false;
+    }
+    status = await withCliProgress("正在开启并检查远程桌面共享", () => request(dataDir, { action: "enable" }));
+    if (!complete(status))
+        throw new Error(status.error ? terminalText(status.error) : "远程桌面共享未就绪，请重新检查系统权限");
+    log("✓ 远程桌面授权完成，已开启共享。手机首次连接仍需设备配对。");
+    return true;
+}
+export async function runDesktopCommand(options, context = {}) {
+    const log = context.log ?? console.log;
+    const request = context.request ?? requestAuthorization;
+    if (options.desktopAction === "authorize") {
+        try {
+            if (!await authorizeRemoteDesktop(options.dataDir, context))
+                process.exitCode = 1;
+        }
+        catch (error) {
+            recoveryHint(log);
+            throw error;
+        }
+        return;
+    }
+    let status = await request(options.dataDir);
+    if (options.desktopAction === "disable") {
+        status = await request(options.dataDir, { action: "disable" });
+        if (status.enabled)
+            throw new Error("远程桌面共享尚未关闭，请重试");
+        log("✓ 已关闭远程桌面共享，系统权限保留。重新开启：agentroam desktop authorize");
+        return;
+    }
+    if (status.supported && status.installed)
+        status = await request(options.dataDir, { action: "recheck" });
+    log(`远程桌面：${status.supported ? "支持" : "不支持"}；共享：${status.enabled ? "已开启" : "未开启"}；屏幕录制：${status.screen ? "已授权" : "未授权或桌面不可用"}；辅助功能：${status.accessibility ? "已授权" : "未授权"}`);
+    if (status.error)
+        log(`状态提示：${terminalText(status.error)}`);
+    recoveryHint(log);
+}

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/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"

package/install/install-agentroam.sh

@@ -28,6 +28,47 @@ fi
 TEMP_ROOT=""
 OWN_NODE_LOCK=0
 OWN_LAUNCHER_LOCK=0
+PROGRESS_PID=""
+
+# Works before Node exists and never reads stdin (curl | sh owns it).
+stop_progress() {
+  if [ -n "$PROGRESS_PID" ]; then
+    kill "$PROGRESS_PID" 2>/dev/null || true
+    wait "$PROGRESS_PID" 2>/dev/null || true
+    PROGRESS_PID=""
+  fi
+}
+
+start_progress() {
+  stop_progress
+  [ "${AGENTROAM_NO_PROGRESS:-}" != "1" ] || return 0
+  printf '… %s（已等待 0 秒）\n' "$1" >&2
+  (
+    progress_label=$1
+    progress_started=$(date +%s)
+    progress_sleep_pid=""
+    trap 'if [ -n "$progress_sleep_pid" ]; then kill "$progress_sleep_pid" 2>/dev/null || true; wait "$progress_sleep_pid" 2>/dev/null || true; fi' EXIT
+    trap 'exit 0' HUP INT TERM
+    while :; do
+      sleep 5 &
+      progress_sleep_pid=$!
+      wait "$progress_sleep_pid" || exit 0
+      progress_sleep_pid=""
+      progress_now=$(date +%s)
+      printf '… %s（已等待 %s 秒）\n' "$progress_label" "$((progress_now - progress_started))" >&2
+    done
+  ) </dev/null &
+  PROGRESS_PID=$!
+}
+
+run_with_progress() {
+  progress_command_label=$1
+  shift
+  start_progress "$progress_command_label"
+  if "$@"; then progress_command_status=0; else progress_command_status=$?; fi
+  stop_progress
+  return "$progress_command_status"
+}
 
 fail() {
   printf 'agentroam installer: %s\n' "$*" >&2
@@ -35,6 +76,7 @@ fail() {
 }
 
 cleanup() {
+  stop_progress
   if [ -n "$TEMP_ROOT" ] && [ -d "$TEMP_ROOT" ]; then
     rm -rf "$TEMP_ROOT"
   fi
@@ -121,6 +163,7 @@ acquire_directory_lock() {
   done
 }
 
+start_progress "正在检查可用的 Node.js"
 SYSTEM_NODE=$(command -v node 2>/dev/null || true)
 if [ "${AGENTROAM_BOOTSTRAP_TEST:-}" = "1" ] && [ "${AGENTROAM_FORCE_PRIVATE_NODE:-}" = "1" ]; then
   SYSTEM_NODE=""
@@ -138,7 +181,9 @@ else
     printf 'Using Node.js %s from NVM: %s\n' "$("$NODE_BIN" --version)" "$NODE_BIN"
   else
     if ! runtime_is_valid; then
+      start_progress "正在等待 Node.js 安装锁"
       acquire_directory_lock "$NODE_LOCK"
+      stop_progress
       OWN_NODE_LOCK=1
       if ! runtime_is_valid; then
         TEMP_ROOT=$(mktemp -d "$NODE_PARENT/.node-$NODE_VERSION.XXXXXX")
@@ -146,6 +191,7 @@ else
         extract_path="$TEMP_ROOT/extract"
         mkdir "$extract_path"
         printf 'Downloading Node.js %s...\n' "$NODE_VERSION"
+        start_progress "正在下载 Node.js $NODE_VERSION"
         if [ -n "${AGENTROAM_NODE_ARCHIVE_FILE:-}" ]; then
           cp "$AGENTROAM_NODE_ARCHIVE_FILE" "$archive_path"
         else
@@ -156,8 +202,10 @@ else
             sleep "$download_attempt"
           done
         fi
+        start_progress "正在校验 Node.js 安装包"
         actual_sha=$(shasum -a 256 "$archive_path" | awk '{print $1}')
         [ "$actual_sha" = "$NODE_SHA256" ] || fail "Node.js archive checksum mismatch"
+        start_progress "正在解压并验证 Node.js"
         /usr/bin/tar -xJf "$archive_path" -C "$extract_path"
         entry_count=$(find "$extract_path" -mindepth 1 -maxdepth 1 | wc -l | tr -d ' ')
         [ "$entry_count" = "1" ] || fail "unexpected Node.js archive layout"
@@ -177,6 +225,7 @@ else
     NODE_BIN="$NODE_ROOT/bin/node"
   fi
 fi
+stop_progress
 
 if [ "${AGENTROAM_BOOTSTRAP_TEST:-}" = "1" ] && [ "${AGENTROAM_BOOTSTRAP_NODE_DISCOVERY_ONLY:-}" = "1" ]; then
   printf '%s\n' "$NODE_BIN"
@@ -205,7 +254,9 @@ case "$AGENTROAM_VERSION_REQUEST" in
   *)
     # A dist-tag (default "preview") — resolve to the newest published version
     # so installs always pick up the latest release without touching this file.
+    start_progress "正在查询 AgentRoam $AGENTROAM_VERSION_REQUEST 最新版本"
     resolved_version="$("$NODE_BIN" "$NPM_CLI" view "agentroam@$AGENTROAM_VERSION_REQUEST" version --registry "$NPM_REGISTRY" 2>/dev/null | tail -1 | tr -d '[:space:]')"
+    stop_progress
     [ -n "$resolved_version" ] || fail "could not resolve agentroam@$AGENTROAM_VERSION_REQUEST from $NPM_REGISTRY"
     AGENTROAM_VERSION="$resolved_version"
     printf 'Installing AgentRoam %s (resolved from %s)\n' "$AGENTROAM_VERSION" "$AGENTROAM_VERSION_REQUEST"
@@ -225,14 +276,18 @@ launcher_is_valid() {
     && [ "$("$NODE_BIN" "$LAUNCHER_ROOT/node_modules/agentroam/bin/agentroam.mjs" version 2>/dev/null | awk '{print $2}' || true)" = "$AGENTROAM_VERSION" ]
 }
 
+start_progress "正在检查已安装的 CLI"
 if ! launcher_is_valid; then
+  start_progress "正在等待 CLI 安装锁"
   acquire_directory_lock "$LAUNCHER_LOCK"
+  stop_progress
   OWN_LAUNCHER_LOCK=1
   if ! launcher_is_valid; then
     TEMP_ROOT=$(mktemp -d "$LAUNCHER_PARENT/.launcher-$AGENTROAM_VERSION.XXXXXX")
     # Test-only extra specs are whitespace-delimited artifact paths in isolated CI directories.
     # shellcheck disable=SC2086
-    "$NODE_BIN" "$NPM_CLI" install --no-audit --no-fund --registry "$NPM_REGISTRY" --prefix "$TEMP_ROOT" $EXTRA_PACKAGE_SPECS "$PACKAGE_SPEC"
+    run_with_progress "正在下载和安装 CLI 及平台组件" "$NODE_BIN" "$NPM_CLI" install --no-audit --no-fund --registry "$NPM_REGISTRY" --prefix "$TEMP_ROOT" $EXTRA_PACKAGE_SPECS "$PACKAGE_SPEC"
+    start_progress "正在验证并启用 CLI"
     entry="$TEMP_ROOT/node_modules/agentroam/bin/agentroam.mjs"
     [ -f "$entry" ] || fail "AgentRoam launcher is missing after npm install"
     [ "$("$NODE_BIN" "$entry" version | awk '{print $2}')" = "$AGENTROAM_VERSION" ] || fail "AgentRoam version validation failed"
@@ -243,6 +298,7 @@ if ! launcher_is_valid; then
   rmdir "$LAUNCHER_LOCK" 2>/dev/null || true
   OWN_LAUNCHER_LOCK=0
 fi
+stop_progress
 
 entry="$LAUNCHER_ROOT/node_modules/agentroam/bin/agentroam.mjs"
 wrapper_temp=$(mktemp "$WRAPPER_DIR/.agentroam.XXXXXX")
@@ -253,18 +309,26 @@ wrapper_temp=$(mktemp "$WRAPPER_DIR/.agentroam.XXXXXX")
 chmod 755 "$wrapper_temp"
 mv "$wrapper_temp" "$WRAPPER_PATH"
 
-if ! "$NODE_BIN" "$entry" doctor --data-dir "$DATA_DIR"; then
+if ! run_with_progress "正在检查运行组件" env AGENTROAM_NO_PROGRESS=1 "$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
+  # The CLI owns progress here so it can pause for confirmations and print QR intact.
+  printf '… 正在安装后台服务；随后检查远程桌面授权并生成手机连接二维码\n' >&2
   codex_setup_module="$(dirname "$entry")/../dist/codex-desktop-setup.js"
-  if [ -f "$codex_setup_module" ]; then
-    "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR" --setup-codex-desktop
-  else
-    printf '当前发布的 CLI 尚未包含官方 Codex 桌面共享配置；扫码可连接 AgentRoam，原桌面会话暂未共享，请升级 CLI 后重试。\n'
-    "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR"
+  install_background_service() {
+    if [ -f "$codex_setup_module" ]; then
+      "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR" --setup-codex-desktop
+    else
+      printf '当前发布的 CLI 尚未包含官方 Codex 桌面共享配置；扫码可连接 AgentRoam，原桌面会话暂未共享，请升级 CLI 后重试。\n'
+      "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR"
+    fi
+  }
+  if ! install_background_service; then
+    printf 'CLI 已安装，但后台服务安装或启动失败，尚不能扫码连接。请运行 agentroam service logs 查看原因，修复后运行 agentroam service start，再执行 agentroam pair。\n' >&2
+    exit 1
   fi
 fi
 printf '\nAgentRoam %s installed: %s\n' "$AGENTROAM_VERSION" "$WRAPPER_PATH"
@@ -288,7 +352,7 @@ case "$desktop_choice" in
   y|Y|yes|YES|是)
     desktop_helper="$LAUNCHER_ROOT/node_modules/agentroam/bin/desktop-download.mjs"
     if [ -f "$desktop_helper" ]; then
-      "$NODE_BIN" "$desktop_helper" "$AGENTROAM_VERSION" || printf 'CLI 安装已完成，桌面端可稍后重新下载。\n'
+      run_with_progress "正在下载并校验桌面端安装包" env AGENTROAM_NO_PROGRESS=1 "$NODE_BIN" "$desktop_helper" "$AGENTROAM_VERSION" || printf 'CLI 安装已完成，桌面端可稍后重新下载。\n'
     else
       printf '当前发布的 CLI 尚未包含桌面下载功能，请在新版发布后重试。CLI 安装已完成。\n'
     fi

package/install/install-manifest.json

@@ -3,13 +3,13 @@
   "installers": {
     "darwin-arm64": {
       "fileName": "install-agentroam.sh",
-      "sha256": "8ae51c123a05aa32f1483baf6d80ff7c5dbe0cc638578402e2a65c5e314f90de",
-      "size": 12028
+      "sha256": "9fad4cb6528e0b71224c40c4eece94881a67191b165ccb673b980498b8646487",
+      "size": 14575
     },
     "windows-amd64": {
       "fileName": "install-agentroam.ps1",
-      "sha256": "4a3683a3e6027e15356dab7a5c7d02a81ad1be3f4bad61a6119328ed2ab89298",
-      "size": 13155
+      "sha256": "5df75c9a139997cfee382ef824216b92bf4a68eba679fbc5be01102019ce1652",
+      "size": 13309
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentroam",
-  "version": "0.2.0-preview.37",
+  "version": "0.2.0-preview.39",
   "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.37",
-    "agentroam-runtime-win32-x64": "0.2.0-preview.37",
-    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.36",
-    "agentroam-cloudflared-win32-x64": "0.2.0-preview.36",
-    "agentroam-tui-darwin-arm64": "0.2.0-preview.36",
-    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.36"
+    "agentroam-runtime-darwin-arm64": "0.2.0-preview.39",
+    "agentroam-runtime-win32-x64": "0.2.0-preview.39",
+    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.39",
+    "agentroam-cloudflared-win32-x64": "0.2.0-preview.39",
+    "agentroam-tui-darwin-arm64": "0.2.0-preview.39",
+    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.39"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",