agentroam 0.2.0-preview.16 → 0.2.0-preview.18

package/README.md

@@ -4,7 +4,7 @@ Zero-install mobile remote terminal and file console. **No desktop app, no VPN**
 
 ## Requirements
 
-- **Node.js 22** (required)
+- **Node.js >=22.22.0** (no upper version bound)
 - macOS arm64 or Windows 10/11 x64
 
 The release is assembled on macOS arm64. Windows does not need Bun, Python,
@@ -20,20 +20,20 @@ npx agentroam@preview
 Or install from tarball:
 
 ```bash
-npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.16.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.16.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.16.tgz \
-  ./agentroam-0.2.0-preview.16.tgz
+npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.18.tgz \
+  ./agentroam-runtime-darwin-arm64-0.2.0-preview.18.tgz \
+  ./agentroam-tui-darwin-arm64-0.2.0-preview.18.tgz \
+  ./agentroam-0.2.0-preview.18.tgz
 npx agentroam
 ```
 
 Windows PowerShell:
 
 ```powershell
-npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.16.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.16.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.16.tgz `
-  ./agentroam-0.2.0-preview.16.tgz
+npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.18.tgz `
+  ./agentroam-runtime-win32-x64-0.2.0-preview.18.tgz `
+  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.18.tgz `
+  ./agentroam-0.2.0-preview.18.tgz
 npx agentroam
 ```
 
@@ -57,16 +57,16 @@ agent-tui                 # start the bundled terminal Agent UI
 
 Run the versioned Shell installer on macOS or PowerShell installer on Windows
 from the project directory AgentRoam should expose. The installer verifies or
-installs Node 22 and the matching CLI, registers the current-user service, starts
+installs a compatible Node and the matching CLI, registers the current-user service, starts
 it, checks readiness, and prints the access URL. Set `AGENTROAM_ROOT` to select a
-different root explicitly. An implicit root equal to the home directory is
-rejected.
+different root explicitly. The current directory, including the home directory, is accepted.
 
-If the active Node is not 22, the installer checks nvm-sh on macOS and
-nvm-windows on Windows, validates every installed candidate, and uses the
-highest installed Node 22. It pins that executable for AgentRoam without
+The installer reuses the active Node when it meets the minimum version. Otherwise
+it checks nvm-sh on macOS and nvm-windows on Windows and uses the highest
+compatible installed version. The service records that executable without
 changing the user's global or active NVM version. A private Node 22.22.0 is
-downloaded only when no installed Node 22 is available.
+downloaded only when no compatible installed Node is available. Higher Node
+versions are never rejected or downgraded solely because of their major version.
 
 The service keeps running after the terminal closes, restarts after failure, and
 starts again when the user logs in. macOS uses a user LaunchAgent; Windows uses a
@@ -117,7 +117,7 @@ The platform cloudflared binary is installed from npm after size and SHA-256 ver
 - Next.js **standalone** web gateway + WebSocket PTY server
 - `@agent/core` bundled runtime
 - Optional platform **cloudflared** package (verified size + SHA-256 before execution)
-- Optional platform **agent-tui** package (Node 22 bundle; Bun is not required)
+- Optional platform **agent-tui** package (Node >=22.22.0 bundle; Bun is not required)
 - **Pairing token** + secure cookies behind HTTPS tunnel
 
 Not included: Electron desktop app, SDK, dev `.env`, session caches.

package/bin/desktop-download.mjs

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Transform, Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { execFile } from 'node:child_process';
+
+const RELEASE_BASE = 'https://gitee.com/caoqu/team-agent/releases/download';
+
+export function desktopAsset(manifest, version, platform, arch) {
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-preview\.(0|[1-9]\d*))?$/.test(version)) throw new Error('Invalid AgentRoam version');
+  const target = platform === 'darwin' && arch === 'arm64' ? 'darwin-arm64' : platform === 'win32' && arch === 'x64' ? 'windows-amd64' : null;
+  if (!target) throw new Error('Desktop download supports macOS Apple Silicon and Windows x64');
+  const asset = manifest?.installers?.desktop?.[target];
+  const expected = platform === 'darwin' ? `AgentRoam-${version}-arm64.dmg` : `AgentRoam-Setup-${version}-x64.exe`;
+  if (manifest?.schemaVersion !== 2 || manifest.version !== version || manifest.channel !== (version.includes('-preview.') ? 'preview' : 'latest') || asset?.fileName !== expected || !/^[a-f0-9]{64}$/.test(asset?.sha256 ?? '') || asset.signed !== false || (asset.size !== undefined && (!Number.isSafeInteger(asset.size) || asset.size <= 0))) {
+    throw new Error('This release has no valid desktop installer for your platform');
+  }
+  return asset;
+}
+
+export async function downloadDesktop(version, { platform = process.platform, arch = process.arch, directory = join(homedir(), 'Downloads'), fetchImpl = fetch } = {}) {
+  // Validate coordinates before making any request.
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-preview\.(0|[1-9]\d*))?$/.test(version)) throw new Error('Invalid AgentRoam version');
+  const response = await fetchImpl(`${RELEASE_BASE}/v${version}/release-manifest.json`, { signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`Desktop release manifest unavailable (${response.status})`);
+  const asset = desktopAsset(await response.json(), version, platform, arch);
+  await mkdir(directory, { recursive: true });
+  // Unique directory prevents overwriting an existing installer, including concurrent downloads.
+  const staging = await mkdtemp(join(directory, 'AgentRoam-'));
+  const partial = join(staging, `${asset.fileName}.download`);
+  try {
+    const binary = await fetchImpl(`${RELEASE_BASE}/v${version}/${encodeURIComponent(asset.fileName)}`, { signal: AbortSignal.timeout(600_000) });
+    if (!binary.ok || !binary.body) throw new Error(`Desktop download failed (${binary.status})`);
+    const hash = createHash('sha256');
+    let size = 0;
+    const verifier = new Transform({ transform(chunk, _encoding, callback) { size += chunk.length; hash.update(chunk); callback(null, chunk); } });
+    await pipeline(Readable.fromWeb(binary.body), verifier, createWriteStream(partial, { flags: 'wx', mode: 0o600 }));
+    if (hash.digest('hex') !== asset.sha256 || (asset.size !== undefined && asset.size !== size)) throw new Error('Desktop installer checksum or size mismatch');
+    const destination = join(staging, asset.fileName);
+    await rename(partial, destination);
+    return destination;
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const destination = await 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);
+  } catch (error) {
+    console.error(`桌面端下载未完成：${error.message}。CLI 已安装，可继续使用。`);
+    process.exitCode = 1;
+  }
+}

package/bin/node-preflight.mjs

@@ -4,10 +4,10 @@ import { homedir } from "node:os";
 import { delimiter, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { MINIMUM_NODE_VERSION, compareNodeVersions, isSupportedNodeVersion, parseNodeVersion } from "./runtime-policy.mjs";
 
 const execFileAsync = promisify(execFile);
-const MANAGED_NODE_VERSION = "22.22.0";
-const RELEASE_VERSION = "0.2.0-preview.16";
+const RELEASE_VERSION = "0.2.0-preview.18";
 const RELEASE_BASE_URL = `https://gitee.com/caoqu/team-agent/releases/download/v${RELEASE_VERSION}`;
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 
@@ -21,10 +21,10 @@ export async function runNodePreflight(options = {}) {
   const processHost = options.processHost ?? process;
   const major = Number(nodeVersion.split(".")[0]);
 
-  if (major === 22) return { handled: false };
+  if (isSupportedNodeVersion(nodeVersion)) return { handled: false };
   if (environment.AGENTROAM_MANAGED_NODE) {
     throw cliError(
-      `managed Node.js re-entry failed: expected 22, got ${nodeVersion} (${environment.AGENTROAM_MANAGED_NODE})`,
+      `managed Node.js re-entry failed: expected >=${MINIMUM_NODE_VERSION}, got ${nodeVersion} (${environment.AGENTROAM_MANAGED_NODE})`,
     );
   }
   if (!Number.isFinite(major) || major < 18) {
@@ -33,8 +33,8 @@ export async function runNodePreflight(options = {}) {
 
   const target = detectManagedTarget(platform, arch);
   const dataDir = parsePreflightDataDir(argv, environment, options.homeDir ?? homedir());
-  const findSystemNode22 = options.findSystemNode22 ?? defaultFindSystemNode22;
-  const systemNode = await findSystemNode22(environment, platform, options.currentExecutable ?? process.execPath);
+  const findSystemNode = options.findSystemNode ?? defaultFindSystemNode;
+  const systemNode = await findSystemNode(environment, platform, options.currentExecutable ?? process.execPath);
   let executable = systemNode;
 
   if (!executable) {
@@ -55,7 +55,7 @@ export async function runNodePreflight(options = {}) {
   const spawnChild = options.spawnChild ?? defaultSpawnChild;
   const child = spawnChild(executable, [launcherPath, ...argv], {
     stdio: "inherit",
-    env: { ...environment, AGENTROAM_MANAGED_NODE: MANAGED_NODE_VERSION },
+    env: { ...environment, AGENTROAM_MANAGED_NODE: executable },
   });
   const result = await waitForChild(child, processHost);
   return { handled: true, ...result };
@@ -77,7 +77,7 @@ function detectManagedTarget(platform, arch) {
   throw cliError(`managed Node.js is unsupported on ${platform}-${arch}`);
 }
 
-async function defaultFindSystemNode22(environment, platform, currentExecutable) {
+async function defaultFindSystemNode(environment, platform, currentExecutable) {
   const executableName = platform === "win32" ? "node.exe" : "node";
   const pathDelimiter = platform === "win32" ? ";" : delimiter;
   const currentDirectory = dirname(currentExecutable);
@@ -85,12 +85,12 @@ async function defaultFindSystemNode22(environment, platform, currentExecutable)
     if (resolve(directory) === resolve(currentDirectory)) continue;
     const candidate = resolve(directory, executableName);
     const version = await inspectNodeVersion(candidate);
-    if (version?.[0] === 22) return candidate;
+    if (isSupportedNodeVersion(version)) return candidate;
   }
-  return findNvmNode22(environment, platform);
+  return findNvmNode(environment, platform);
 }
 
-export async function findNvmNode22(environment = process.env, platform = process.platform) {
+export async function findNvmNode(environment = process.env, platform = process.platform) {
   const windows = platform === "win32";
   const homeDir = environment.HOME || environment.USERPROFILE || homedir();
   const roots = windows
@@ -109,10 +109,10 @@ export async function findNvmNode22(environment = process.env, platform = proces
       if (!entry.isDirectory()) continue;
       const candidate = resolve(versionsRoot, entry.name, windows ? "node.exe" : "bin/node");
       const version = await inspectNodeVersion(candidate);
-      if (version?.[0] === 22) candidates.push({ candidate, version });
+      if (isSupportedNodeVersion(version)) candidates.push({ candidate, version });
     }
   }
-  candidates.sort((left, right) => compareVersions(right.version, left.version));
+  candidates.sort((left, right) => compareNodeVersions(right.version, left.version));
   return candidates[0]?.candidate ?? null;
 }
 
@@ -124,20 +124,13 @@ async function inspectNodeVersion(candidate) {
       timeout: 5_000,
       windowsHide: true,
     });
-    const parts = stdout.trim().split(".").map((part) => Number(part));
-    return parts.length >= 3 && parts.every(Number.isInteger) ? parts.slice(0, 3) : null;
+    const version = stdout.trim();
+    return parseNodeVersion(version) ? version : null;
   } catch {
     return null;
   }
 }
 
-function compareVersions(left, right) {
-  for (let index = 0; index < 3; index++) {
-    if (left[index] !== right[index]) return left[index] - right[index];
-  }
-  return 0;
-}
-
 async function defaultSpawnChild(executable, args, options) {
   const { spawn } = await import("node:child_process");
   return spawn(executable, args, options);

package/bin/node-runtime-policy.json

@@ -0,0 +1,4 @@
+{
+  "schemaVersion": 1,
+  "minimumNodeVersion": "22.22.0"
+}

package/bin/runtime-policy.d.mts

@@ -0,0 +1,5 @@
+export const MINIMUM_NODE_VERSION: string;
+export function parseNodeVersion(version: unknown): number[] | null;
+export function compareNodeVersions(left: string, right: string): number;
+export function isSupportedNodeVersion(version: unknown, minimum?: string): boolean;
+export function assertSupportedNodeVersion(version?: string): void;

package/bin/runtime-policy.mjs

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+
+const policy = JSON.parse(readFileSync(new URL("./node-runtime-policy.json", import.meta.url), "utf8"));
+
+export const MINIMUM_NODE_VERSION = policy.minimumNodeVersion;
+
+export function parseNodeVersion(version) {
+  if (typeof version !== "string") return null;
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+  if (!match) return null;
+  const parts = match.slice(1, 4).map(Number);
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+export function compareNodeVersions(left, right) {
+  const leftParts = parseNodeVersion(left);
+  const rightParts = parseNodeVersion(right);
+  if (!leftParts || !rightParts) throw new Error("invalid Node.js version");
+  for (let index = 0; index < 3; index++) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+export function isSupportedNodeVersion(version, minimum = MINIMUM_NODE_VERSION) {
+  return parseNodeVersion(version) !== null && compareNodeVersions(version, minimum) >= 0;
+}
+
+export function assertSupportedNodeVersion(version = process.versions.node) {
+  if (!isSupportedNodeVersion(version)) {
+    throw Object.assign(new Error(`Node.js >=${MINIMUM_NODE_VERSION} required (current ${version})`), { exitCode: 2 });
+  }
+}
+
+if (policy.schemaVersion !== 1 || !parseNodeVersion(MINIMUM_NODE_VERSION)) {
+  throw new Error("invalid AgentRoam Node.js runtime policy");
+}

package/dist/args.js

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 export function parseArgs(argv) {
     const values = [...argv];
     let command = "start";
-    if (values[0] && ["start", "doctor", "version", "service", "update", "update-worker"].includes(values[0])) {
+    if (values[0] && ["start", "doctor", "version", "service", "update", "update-worker", "pair", "devices", "revoke", "approvals", "approve", "deny", "lock", "unlock", "audit"].includes(values[0])) {
         command = values.shift();
     }
     let serviceAction = null;
@@ -17,6 +17,23 @@ export function parseArgs(argv) {
             throw cliError(`service ${serviceAction} does not accept options`);
         }
     }
+    let revokeDeviceId = null;
+    let revokeAll = false;
+    if (command === "revoke") {
+        const device = values.shift();
+        if (device === "--all")
+            revokeAll = true;
+        else if (device && /^[a-f0-9-]{36}$/.test(device))
+            revokeDeviceId = device;
+        else
+            throw cliError("revoke requires a device ID or --all");
+    }
+    let approvalRequestId;
+    if (command === "approve" || command === "deny") {
+        approvalRequestId = values.shift();
+        if (!approvalRequestId || !/^[a-f0-9-]{36}$/.test(approvalRequestId))
+            throw cliError(`${command} requires a request ID`);
+    }
     let updateVersion = null;
     let updateStateFile = null;
     if (command === "update" && values[0] && !values[0].startsWith("--"))
@@ -37,6 +54,8 @@ export function parseArgs(argv) {
         localOnly: false,
         qr: true,
         dataDir: resolve(homedir(), ".agentroam"),
+        ...(command === "revoke" ? { revokeDeviceId, revokeAll } : {}),
+        ...(approvalRequestId ? { approvalRequestId } : {}),
         updateVersion,
         updateStateFile,
     };
@@ -48,7 +67,9 @@ export function parseArgs(argv) {
                 throw cliError(`missing value for ${arg}`);
             return value;
         };
-        if (arg === "--root")
+        if (arg === "--url" && command === "pair")
+            options.pairingUrl = next();
+        else if (arg === "--root")
             options.roots.push(resolve(next()));
         else if (arg === "--port") {
             const port = Number(next());
@@ -67,8 +88,12 @@ export function parseArgs(argv) {
             options.tunnelCommand = next();
         else if (arg === "--data-dir")
             options.dataDir = resolve(next());
+        else if (arg === "--phrase" && command === "approve")
+            options.approvalPhrase = next();
         else if (arg === "--local-only")
             options.localOnly = true;
+        else if (arg === "--test-no-pairing")
+            options.testNoPairing = true;
         else if (arg === "--no-qr")
             options.qr = false;
         else if (arg === "--help" || arg === "-h")
@@ -76,9 +101,13 @@ export function parseArgs(argv) {
         else
             throw cliError(`unknown argument: ${arg}`);
     }
+    if (command === "approve" && !options.approvalPhrase)
+        throw cliError("approve requires --phrase matching the phone");
     if (command === "update" && updateVersion && !/^\d+\.\d+\.\d+$/.test(updateVersion)) {
         throw cliError("update version must be an exact stable X.Y.Z version");
     }
+    if (options.testNoPairing && (command !== "start" || !options.localOnly || options.tunnelCommand || options.relay !== "auto"))
+        throw cliError("--test-no-pairing requires start --local-only and cannot use a tunnel or background service");
     if (!options.roots.length)
         options.roots = [process.cwd()];
     if (options.relay === "custom" && !options.tunnelCommand)

package/dist/args.test.js

@@ -57,3 +57,19 @@ describe("parseArgs", () => {
         expect(() => parseArgs(["update", "1.2.3-preview.1"])).toThrow("exact stable");
     });
 });
+describe("device authorization commands", () => {
+    it("parses pairing, listing and individual/all revocation", () => {
+        expect(parseArgs(["pair"]).command).toBe("pair");
+        expect(parseArgs(["devices"]).command).toBe("devices");
+        expect(parseArgs(["revoke", "--all"]).revokeAll).toBe(true);
+        expect(parseArgs(["revoke", "12345678-1234-1234-1234-123456789abc"]).revokeDeviceId).toBe("12345678-1234-1234-1234-123456789abc");
+        expect(() => parseArgs(["revoke"])).toThrow();
+        expect(parseArgs(["pair", "--data-dir", "/tmp/device-test"]).dataDir).toBe("/tmp/device-test");
+    });
+});
+it("restricts no-pairing test mode to explicit local foreground starts", () => {
+    expect(parseArgs(["start", "--local-only", "--test-no-pairing"]).testNoPairing).toBe(true);
+    expect(parseArgs([]).testNoPairing).toBeUndefined();
+    for (const args of [["--test-no-pairing"], ["service", "install", "--local-only", "--test-no-pairing"], ["start", "--local-only", "--test-no-pairing", "--relay", "pinggy"]])
+        expect(() => parseArgs(args)).toThrow();
+});

package/dist/cli.js

@@ -3,13 +3,12 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "./args.js";
 import { ensureCloudflared } from "./cloudflared/installer.js";
 import { resolveCodexRuntime } from "./codex-runtime-manager.js";
-import { repairNativeRuntimePermissions } from "./native-runtime.js";
+import { probeSQLiteRuntime, probeTerminalRuntime, repairNativeRuntimePermissions } from "./native-runtime.js";
 import { findLanUrl } from "./network.js";
-import { createPairingSecret } from "./pairing.js";
+import { installedDataDir, pairingAdmin, printPairingCode, terminalText } from "./device-pairing.js";
 import { detectPlatform } from "./platform.js";
 import { AGENTROAM_VERSION, resolvePlatformRuntime, resolvePlatformTui } from "./platform-packages.js";
 import { acquireSleepInhibitor } from "./power/sleep-inhibitor.js";
-import { renderQr } from "./qr.js";
 import { RuntimeManager } from "./runtime-manager.js";
 import { ServiceRuntimeReporter } from "./service/runtime-state.js";
 import { runServiceCommand } from "./service/service-command.js";
@@ -19,7 +18,56 @@ import { currentCliPath, startUpdate } from "./update/update-command.js";
 import { runUpdateWorker } from "./update/update-worker.js";
 const VERSION = AGENTROAM_VERSION;
 export async function main(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`AgentRoam
+  agentroam [start] [--local-only] [--test-no-pairing] [--data-dir PATH]
+  agentroam pair                    生成一次性设备配对码
+  agentroam pair --url <服务器地址>   生成 App 扫码直连授权（终端显示）
+  agentroam approvals               查看待批准请求和核对短语
+  agentroam approve <请求ID> --phrase <核对短语>
+  agentroam deny <请求ID>             拒绝请求
+  agentroam lock                    紧急锁定全部远程访问
+  agentroam unlock                  本机解锁（需要重新配对）
+  agentroam audit                   查看安全审计记录
+  agentroam devices                 查看已授权设备
+  agentroam revoke <设备ID>          移除一台设备
+  agentroam revoke --all            全部退出并取消待用配对码
+  agentroam service install|start|stop|restart|status|url|logs|uninstall
+设备命令支持 --data-dir PATH；配对码有效期 5 分钟，设备授权有效期 30 天。`);
+        return;
+    }
     const options = parseArgs(argv);
+    if (["pair", "devices", "revoke", "approvals", "approve", "deny", "lock", "unlock", "audit"].includes(options.command)) {
+        const dataDir = argv.includes("--data-dir") ? options.dataDir : await installedDataDir(options.dataDir);
+        if (options.command === "pair")
+            await printPairingCode(dataDir, console.log, { accessUrl: options.pairingUrl, qr: options.qr });
+        else if (options.command === "approvals") {
+            const { requests, locked } = await pairingAdmin(dataDir, "requests");
+            console.log(locked ? "远程访问已锁定" : requests.length ? requests.map((r) => `${r.id}  ${terminalText(r.name)}  核对短语：${r.phrase}  到期 ${new Date(r.expires).toLocaleString()}`).join("\n") : "暂无待授权请求");
+        }
+        else if (options.command === "approve" || options.command === "deny") {
+            await pairingAdmin(dataDir, options.command, { id: options.approvalRequestId, phrase: options.approvalPhrase });
+            console.log(options.command === "approve" ? "已批准，手机将自动进入。" : "已拒绝此设备。");
+        }
+        else if (options.command === "lock" || options.command === "unlock") {
+            await pairingAdmin(dataDir, options.command);
+            console.log(options.command === "lock" ? "远程访问已锁定，设备授权和待用配对已取消。已提交的本机任务不会自动终止。" : "远程访问已解锁。旧设备不会恢复授权，请执行 agentroam pair 重新配对。");
+        }
+        else if (options.command === "audit") {
+            const { events } = await pairingAdmin(dataDir, "audit");
+            console.log(events.length ? events.map((e) => `${new Date(e.at).toISOString()} ${e.action} ${e.outcome} actor=${e.actor ?? "-"} target=${e.target ?? "-"} count=${e.count}`).join("\n") : "暂无审计记录");
+        }
+        else if (options.command === "devices") {
+            const { devices } = await pairingAdmin(dataDir, "devices");
+            console.log(devices.length ? devices.map((d) => `${d.id}  ${d.name.replace(/[\x00-\x1f\x7f-\x9f]/g, "")}  最近使用 ${new Date(d.seen).toLocaleString()}  到期 ${new Date(d.expires).toLocaleString()}`).join("\n") : "暂无已授权设备");
+            console.log("移除设备：agentroam revoke <设备ID>；全部退出：agentroam revoke --all");
+        }
+        else {
+            const result = await pairingAdmin(dataDir, "revoke", options.revokeAll ? { all: true } : { id: options.revokeDeviceId });
+            console.log(`已撤销 ${result.revoked} 台设备的授权`);
+        }
+        return;
+    }
     if (options.command === "update-worker") {
         await runUpdateWorker(options.updateStateFile);
         return;
@@ -50,7 +98,6 @@ export async function main(argv) {
     }
     console.log(`AgentRoam ${VERSION}\n✓ Node ${process.versions.node} · ${target}`);
     const sleepInhibitor = await acquireSleepInhibitor();
-    const pairing = createPairingSecret();
     const controller = new AbortController();
     let runtime = null;
     let relay = null;
@@ -71,9 +118,10 @@ export async function main(argv) {
     process.once("SIGTERM", requestClose);
     try {
         await serviceReporter?.starting();
-        runtime = await new RuntimeManager().start(options, pairing, target);
+        runtime = await new RuntimeManager().start(options, target);
+        void runtime.exited.then(() => controller.abort());
         console.log(`✓ Local server: ${runtime.localUrl}/web`);
-        const lanUrl = findLanUrl(runtime.port) ?? runtime.localUrl;
+        const lanUrl = options.localOnly ? findLanUrl(runtime.port) ?? runtime.localUrl : runtime.localUrl;
         relay = await selectRelay({
             cli: options,
             target,
@@ -84,7 +132,7 @@ export async function main(argv) {
             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: serviceReporter === null,
+            allowLanFallback: options.localOnly,
         });
         if (controller.signal.aborted)
             return;
@@ -101,7 +149,7 @@ export async function main(argv) {
             console.log("  Pinggy free tunnels expire after 60 minutes and use a new hostname each session.");
             console.log("  The phone browser may show a one-time Pinggy security confirmation before pairing.");
         }
-        const accessUrl = `${relay.publicUrl}/web${runtime.needsSetup ? `?pair=${encodeURIComponent(pairing.token)}` : ""}`;
+        const accessUrl = `${relay.publicUrl}/web`;
         await serviceReporter?.ready({
             localUrl: runtime.localUrl,
             publicUrl: relay.publicUrl,
@@ -113,10 +161,8 @@ export async function main(argv) {
         }
         else {
             console.log(`\nOpen: ${accessUrl}`);
-            if (options.qr)
-                console.log(`\n${await renderQr(accessUrl)}`);
-            if (runtime.needsSetup)
-                console.log("First pairing link expires in 5 minutes.");
+            if (!options.testNoPairing)
+                await printPairingCode(options.dataDir, console.log, { signal: controller.signal, accessUrl, qr: options.qr });
             console.log("Ctrl+C stops the tunnel and local server.");
         }
         await Promise.race([
@@ -138,7 +184,7 @@ export async function main(argv) {
     }
 }
 async function doctor(target, dataDir) {
-    console.log(`✓ Node ${process.versions.node}`);
+    console.log(`✓ Node ${process.versions.node} · Node-API ${process.versions.napi}`);
     console.log(`✓ Platform ${target}`);
     const { runtimeRoot } = resolvePlatformRuntime(target);
     const runtimeRequire = createRequire(`${runtimeRoot}/package.json`);
@@ -149,9 +195,12 @@ async function doctor(target, dataDir) {
     catch (error) {
         reportDoctorFailure(error);
     }
-    for (const module of ["node-pty", "better-sqlite3"]) {
+    for (const [module, probe] of [
+        ["node-pty", probeTerminalRuntime],
+        ["better-sqlite3", probeSQLiteRuntime],
+    ]) {
         try {
-            runtimeRequire(module);
+            await probe(runtimeRequire);
             console.log(`✓ ${module}`);
         }
         catch (error) {

package/dist/desktop-download.test.js

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+// @ts-expect-error Standalone bootstrap helper ships as JavaScript.
+import { desktopAsset, downloadDesktop } from '../bin/desktop-download.mjs';
+const version = '0.2.0-preview.17';
+const body = Buffer.from('desktop test artifact');
+function manifest() {
+    return { schemaVersion: 2, version, channel: 'preview', installers: { desktop: {
+                'darwin-arm64': { fileName: `AgentRoam-${version}-arm64.dmg`, sha256: createHash('sha256').update(body).digest('hex'), size: body.length, signed: false },
+                'windows-amd64': { fileName: `AgentRoam-Setup-${version}-x64.exe`, sha256: createHash('sha256').update(body).digest('hex'), signed: false },
+            } } };
+}
+describe('optional desktop installer download', () => {
+    it('selects the versioned Windows asset and rejects wrong versions and filenames', () => {
+        expect(desktopAsset(manifest(), version, 'win32', 'x64').fileName).toMatch(/\.exe$/);
+        expect(() => desktopAsset(manifest(), '0.2.0-preview.18', 'darwin', 'arm64')).toThrow();
+        const invalid = manifest();
+        invalid.installers.desktop['darwin-arm64'].fileName = '../unsafe.dmg';
+        expect(() => desktopAsset(invalid, version, 'darwin', 'arm64')).toThrow();
+    });
+    it('downloads and verifies into unique directories without overwriting previous installs', async () => {
+        const directory = await mkdtemp(join(tmpdir(), 'desktop-download-'));
+        const fetchImpl = vi.fn(async (url) => url.endsWith('.json') ? Response.json(manifest()) : new Response(body));
+        try {
+            const first = await downloadDesktop(version, { directory, platform: 'darwin', arch: 'arm64', fetchImpl });
+            const second = await downloadDesktop(version, { directory, platform: 'darwin', arch: 'arm64', fetchImpl });
+            expect(await readFile(first)).toEqual(body);
+            expect(second).not.toBe(first);
+            expect(fetchImpl.mock.calls[1][0]).toContain(`/v${version}/AgentRoam-${version}-arm64.dmg`);
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    });
+    it('cleans up partial files on checksum mismatch', async () => {
+        const directory = await mkdtemp(join(tmpdir(), 'desktop-download-'));
+        const fetchImpl = vi.fn(async (url) => url.endsWith('.json') ? Response.json(manifest()) : new Response('corrupted'));
+        try {
+            await expect(downloadDesktop(version, { directory, platform: 'darwin', arch: 'arm64', fetchImpl })).rejects.toThrow('checksum');
+            expect(await readdir(directory)).toEqual([]);
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    });
+    it('rejects missing platform artifacts before downloading binaries', async () => {
+        const fetchImpl = vi.fn(async () => Response.json({ ...manifest(), installers: {} }));
+        await expect(downloadDesktop(version, { platform: 'darwin', arch: 'arm64', fetchImpl })).rejects.toThrow('no valid');
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+    });
+});
+// Exercise the actual installer tail with an isolated launcher. Nothing installs
+// on the machine; the helper records whether the optional branch ran.
+describe.skipIf(process.platform === 'win32')('Shell desktop choice after CLI installation', () => {
+    it.each(['no', 'yes', undefined])('handles choice %s without reading piped script input', async (choice) => {
+        const { execFileSync } = await import('node:child_process');
+        const { mkdir, writeFile } = await import('node:fs/promises');
+        const root = await mkdtemp(join(tmpdir(), 'desktop-choice-'));
+        try {
+            const bin = join(root, 'node_modules/agentroam/bin');
+            await mkdir(bin, { recursive: true });
+            const marker = join(root, 'selected');
+            await writeFile(join(bin, 'desktop-download.mjs'), `import { writeFileSync } from 'node:fs'; writeFileSync(process.env.CHOICE_MARKER, process.argv[2]);`);
+            const installer = await readFile(new URL('../install/install-agentroam.sh', import.meta.url), 'utf8');
+            const section = installer.slice(installer.indexOf('# stdin is the script itself'));
+            const env = { ...process.env, LAUNCHER_ROOT: root, NODE_BIN: process.execPath, AGENTROAM_VERSION: version, CHOICE_MARKER: marker };
+            delete env.AGENTROAM_INSTALL_DESKTOP;
+            if (choice)
+                Object.assign(env, { AGENTROAM_INSTALL_DESKTOP: choice });
+            execFileSync('/bin/sh', ['-c', section], { env, input: 'yes\n' });
+            if (choice === 'yes')
+                expect(await readFile(marker, 'utf8')).toBe(version);
+            else
+                expect(await readdir(root)).not.toContain('selected');
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+        }
+    });
+});