agentroam 0.2.0-preview.17 → 0.2.0-preview.18

package/README.md

@@ -20,20 +20,20 @@ npx agentroam@preview
 Or install from tarball:
 
 ```bash
-npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.17.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.17.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.17.tgz \
-  ./agentroam-0.2.0-preview.17.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.17.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.17.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.17.tgz `
-  ./agentroam-0.2.0-preview.17.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
 ```
 
@@ -59,8 +59,7 @@ Run the versioned Shell installer on macOS or PowerShell installer on Windows
 from the project directory AgentRoam should expose. The installer verifies or
 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.
 
 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

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

@@ -7,7 +7,7 @@ import { promisify } from "node:util";
 import { MINIMUM_NODE_VERSION, compareNodeVersions, isSupportedNodeVersion, parseNodeVersion } from "./runtime-policy.mjs";
 
 const execFileAsync = promisify(execFile);
-const RELEASE_VERSION = "0.2.0-preview.17";
+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"];
 

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

@@ -5,11 +5,10 @@ import { ensureCloudflared } from "./cloudflared/installer.js";
 import { resolveCodexRuntime } from "./codex-runtime-manager.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([

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 });
+        }
+    });
+});

package/dist/device-pairing.js

@@ -0,0 +1,146 @@
+import { createInterface } from "node:readline/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { renderQr } from "./qr.js";
+/** 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})`;
+        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) {
+    const url = new URL(accessUrl);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || !/^[A-Za-z0-9_-]{43}$/.test(grant))
+        throw new Error("无效的配对地址或授权凭据");
+    return `${url.origin}/pair#pair=${grant}`;
+}
+export async function printPairingCode(dataDir, log = console.log, options = {}) {
+    const result = await pairingAdmin(dataDir, "code");
+    log(`配对码：${result.code.slice(0, 4)} ${result.code.slice(4)}`);
+    log("5 分钟内有效，仅可使用一次。手机输入后仍需在电脑上确认核对短语。");
+    if ((options.qr ?? true) && (options.interactive ?? process.stdout.isTTY)) {
+        const accessUrl = options.accessUrl ?? await readFile(join(dataDir, "tunnel.url"), "utf8").then((value) => value.trim(), () => null);
+        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");
+            log("手机扫码直接连接（5 分钟、一次有效，请勿分享截图）：");
+            log(await renderQr(pairingQrPayload(accessUrl, grant)));
+        }
+        else
+            log("生成 App 授权二维码：agentroam pair --url <手机可访问的服务器地址>");
+    }
+    if (options.interactive ?? (process.stdin.isTTY && process.stdout.isTTY)) {
+        await watchPairingApproval(dataDir, result.expiresAt, { log, signal: options.signal });
+    }
+    else
+        log("查看请求：agentroam approvals；批准：agentroam approve <请求ID> --phrase <手机核对短语>");
+}
+/** Watch only while the printed code is usable; approval gets the request's own deadline. */
+export async function watchPairingApproval(dataDir, codeExpiresAt, options = {}) {
+    const admin = options.admin ?? pairingAdmin;
+    const log = options.log ?? console.log;
+    log("等待手机发起连接…");
+    while (Date.now() < codeExpiresAt && !options.signal?.aborted) {
+        const result = await admin(dataDir, "requests");
+        if (result.locked) {
+            log("远程访问已锁定");
+            return;
+        }
+        if (result.qrClaimed) {
+            log("App 已扫码连接。");
+            return;
+        }
+        const request = result.requests.find((r) => r.created >= codeExpiresAt - 300_000);
+        if (request) {
+            log(`新设备请求连接：${terminalText(request.name)}`);
+            log(`请求 ID：${request.id}`);
+            log(`核对短语：${request.phrase}`);
+            const approved = await (options.confirm ?? confirmOnTerminal)(request, options.signal);
+            if (options.signal?.aborted)
+                return;
+            if (Date.now() >= request.expires) {
+                log("授权请求已过期，请重新配对。");
+                return;
+            }
+            await admin(dataDir, approved ? "approve" : "deny", { id: request.id, ...(approved ? { phrase: request.phrase } : {}) });
+            log(approved ? "已批准，手机将自动进入。" : "已拒绝此设备。");
+            return;
+        }
+        try {
+            await delay(800, undefined, { signal: options.signal });
+        }
+        catch {
+            return;
+        }
+    }
+    if (!options.signal?.aborted)
+        log("配对码已过期，执行 agentroam pair 生成新码。");
+}
+async function confirmOnTerminal(request, signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(0, request.expires - Date.now()));
+    const input = createInterface({ input: process.stdin, output: process.stdout });
+    input.once("SIGINT", () => controller.abort());
+    try {
+        const answer = await input.question("确认手机显示相同短语？输入 yes 批准，其他输入拒绝：", { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal });
+        return answer.trim().toLowerCase() === "yes";
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+        input.close();
+    }
+}
+export async function installedDataDir(fallback) {
+    if (resolve(fallback) !== resolve(homedir(), ".agentroam"))
+        return fallback;
+    try {
+        const config = JSON.parse(await readFile(join(homedir(), ".agentroam", "service", "config.json"), "utf8"));
+        return typeof config.dataDir === "string" ? resolve(config.dataDir) : fallback;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return fallback;
+        throw error;
+    }
+}

package/dist/device-pairing.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from "vitest";
+import { parseArgs } from "./args.js";
+import { pairingQrPayload, watchPairingApproval } from "./device-pairing.js";
+describe("local approval commands", () => {
+    it("encodes a separate QR invitation and validates the server URL", () => {
+        expect(parseArgs(["pair", "--url", "https://phone.example/web"]).pairingUrl).toBe("https://phone.example/web");
+        const link = new URL(pairingQrPayload("https://phone.example/web", "a".repeat(43)));
+        expect(link.origin + link.pathname).toBe("https://phone.example/pair");
+        expect(link.search).toBe("");
+        expect(link.hash).toBe(`#pair=${"a".repeat(43)}`);
+        expect(() => pairingQrPayload("https://user:password@phone.example", "a".repeat(43))).toThrow();
+    });
+    const id = "12345678-1234-1234-1234-123456789abc";
+    it("requires a request ID and matching phrase for explicit approval", () => {
+        expect(() => parseArgs(["approve", id])).toThrow(/phrase/);
+        expect(parseArgs(["approve", id, "--phrase", "松林·月光·1234"])).toMatchObject({ approvalRequestId: id, approvalPhrase: "松林·月光·1234" });
+        for (const command of ["lock", "unlock", "audit", "approvals"])
+            expect(parseArgs([command]).command).toBe(command);
+        expect(parseArgs(["deny", id]).approvalRequestId).toBe(id);
+    });
+    it.each([true, false])("displays the phrase and sends only the local user's %s decision", async (approve) => {
+        const now = Date.now();
+        const request = { id, name: "Phone\u001b[31m", phrase: "松林·月光·1234", created: now, expires: now + 300_000, status: "waiting" };
+        const admin = vi.fn().mockResolvedValueOnce({ requests: [request], locked: false }).mockResolvedValueOnce({ status: approve ? "approved" : "denied" });
+        const log = vi.fn();
+        const confirm = vi.fn(async () => approve);
+        await watchPairingApproval("/tmp/unused", now + 300_000, { admin: admin, log, confirm });
+        expect(log).toHaveBeenCalledWith(`核对短语：${request.phrase}`);
+        expect(confirm).toHaveBeenCalledWith(request, undefined);
+        expect(admin).toHaveBeenLastCalledWith("/tmp/unused", approve ? "approve" : "deny", { id, ...(approve ? { phrase: request.phrase } : {}) });
+        expect(log.mock.calls.flat().join("\n")).not.toContain("\u001b");
+    });
+});

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

@@ -3,11 +3,10 @@ import { resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import { describe, expect, it } from "vitest";
 import { MANAGED_NODE_VERSION, NODE_RUNTIME_ASSETS } from "./node-runtime-manager.js";
-import { AGENTROAM_VERSION } from "./platform-packages.js";
 import { MINIMUM_NODE_VERSION, isSupportedNodeVersion } from "../bin/runtime-policy.mjs";
 const installRoot = resolve(import.meta.dirname, "../install");
 describe("standalone installer contracts", () => {
-    it.skipIf(process.platform !== "darwin" || process.arch !== "arm64")("keeps a compatible active Node instead of selecting a different NVM version", async () => {
+    it.skipIf(process.platform !== "darwin" || process.arch !== "arm64")("allows installation from home and keeps a compatible active Node", async () => {
         const root = await mkdtemp(resolve(process.env.TMPDIR || "/tmp", "agentroam-active-node-"));
         try {
             const homeDir = resolve(root, "home");
@@ -18,7 +17,7 @@ describe("standalone installer contracts", () => {
             const expected = await fakeNode(resolve(activeBin, "node"), "24.13.0");
             await fakeNode(resolve(nvmRoot, "versions/node/v26.0.0/bin/node"), "26.0.0");
             const output = execFileSync("/bin/sh", [resolve(installRoot, "install-agentroam.sh")], {
-                cwd: workspace, encoding: "utf8",
+                cwd: homeDir, encoding: "utf8",
                 env: { ...process.env, HOME: homeDir, NVM_DIR: nvmRoot, PATH: `${activeBin}:/usr/bin:/bin`,
                     AGENTROAM_BOOTSTRAP_TEST: "1", AGENTROAM_BOOTSTRAP_NODE_DISCOVERY_ONLY: "1" },
             });
@@ -33,7 +32,7 @@ describe("standalone installer contracts", () => {
         const script = await readFile(scriptPath, "utf8");
         expect(script).toContain(`NODE_VERSION="${MANAGED_NODE_VERSION}"`);
         expect(script).toContain(`MINIMUM_NODE_VERSION="${MINIMUM_NODE_VERSION}"`);
-        expect(script).toContain(`AGENTROAM_VERSION="${AGENTROAM_VERSION}"`);
+        expect(script).toContain('AGENTROAM_VERSION_REQUEST="${AGENTROAM_VERSION:-preview}"');
         expect(script).toContain(NODE_RUNTIME_ASSETS["darwin-arm64"].archive);
         expect(script).toContain(NODE_RUNTIME_ASSETS["darwin-arm64"].sha256);
         expect(script).toContain("https://registry.npmjs.org");
@@ -42,7 +41,7 @@ describe("standalone installer contracts", () => {
         expect(script).toContain('AGENTROAM_ROOT');
         expect(script).toContain('AGENTROAM_INSTALL_SKIP_SERVICE');
         expect(script).toContain('service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR"');
-        expect(script).toContain("refusing to expose the entire home directory implicitly");
+        expect(script).toContain('SERVICE_ROOT="$PWD"');
         expect(script).toContain("find_nvm_node");
         expect(script).toContain('${NVM_DIR:-}');
         expect(script).not.toMatch(/\b(?:brew|sudo|fnm|volta)\b/);
@@ -52,7 +51,7 @@ describe("standalone installer contracts", () => {
         const script = await readFile(resolve(installRoot, "install-agentroam.ps1"), "utf8");
         expect(script).toContain(`$NodeVersion = "${MANAGED_NODE_VERSION}"`);
         expect(script).toContain(`$MinimumNodeVersion = "${MINIMUM_NODE_VERSION}"`);
-        expect(script).toContain(`$AgentRoamVersion = "${AGENTROAM_VERSION}"`);
+        expect(script).toContain('$AgentRoamVersionRequest = if ($env:AGENTROAM_VERSION) { $env:AGENTROAM_VERSION } else { "preview" }');
         expect(script).toContain(NODE_RUNTIME_ASSETS["windows-amd64"].archive);
         expect(script).toContain(NODE_RUNTIME_ASSETS["windows-amd64"].sha256);
         expect(script).toContain("https://registry.npmjs.org");
@@ -61,7 +60,7 @@ describe("standalone installer contracts", () => {
         expect(script).toContain("$env:AGENTROAM_ROOT");
         expect(script).toContain("$env:AGENTROAM_INSTALL_SKIP_SERVICE");
         expect(script).toContain("service install --root $ServiceRoot --data-dir $DataDir");
-        expect(script).toContain("Refusing to expose the entire home directory implicitly");
+        expect(script).toContain("(Get-Location).Path");
         expect(script).toContain("Find-NvmNode");
         expect(script).toContain("$env:NVM_HOME");
         expect(script).not.toMatch(/\b(?:winget|choco|scoop|Start-Process\s+.*RunAs)\b/i);

package/dist/platform-packages.js

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
 import { MINIMUM_NODE_VERSION, assertSupportedNodeVersion } from "../bin/runtime-policy.mjs";
-export const AGENTROAM_VERSION = "0.2.0-preview.17";
+export const AGENTROAM_VERSION = "0.2.0-preview.18";
 export const PLATFORM_PACKAGES = {
     "darwin-arm64": {
         runtime: "agentroam-runtime-darwin-arm64",

package/dist/runtime-manager.js

@@ -18,7 +18,7 @@ export class RuntimeManager {
         this.report = report;
         this.opencodeResolver = opencodeResolver;
     }
-    async start(options, pairing, target) {
+    async start(options, target) {
         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 })));
@@ -27,19 +27,17 @@ export class RuntimeManager {
         const { runtimeRoot } = resolvePlatformRuntime(target);
         await repairNativeRuntimePermissions(runtimeRoot);
         const gateway = resolve(runtimeRoot, "ws-server.mjs");
-        const child = this.supervisor.spawn(process.execPath, [gateway], {
+        const child = this.supervisor.spawn(process.execPath, [gateway, ...(options.testNoPairing ? ["--test-no-pairing"] : [])], {
             cwd: runtimeRoot,
             env: {
                 ...childEnvironment,
                 NODE_ENV: "production",
                 NEXT_DIST_DIR: ".next",
                 PORT: String(port),
-                HOST: "127.0.0.1",
+                HOST: options.localOnly ? "0.0.0.0" : "127.0.0.1",
                 AGENT_DATA_DIR: resolve(dataDir, "data"),
                 AGENT_WEB_ROOTS: options.roots.join(delimiter),
                 AGENT_TRUST_TUNNEL_PROXY: "1",
-                AGENT_PAIRING_HASH: pairing?.hashHex || "",
-                AGENT_PAIRING_EXPIRES_AT: pairing?.expiresAt || "",
                 AGENTROAM_VERSION: resolvePlatformRuntime(target).manifest.packageVersion,
                 AGENTROAM_DATA_DIR: dataDir,
                 AGENTROAM_CLI_PATH: fileURLToPath(new URL("../bin/agentroam.mjs", import.meta.url)),

package/dist/service/service-command.js

@@ -1,6 +1,7 @@
 import { delimiter, dirname, isAbsolute, resolve, win32 } from "node:path";
 import { resolveCodexRuntime } from "../codex-runtime-manager.js";
 import { detectPlatform } from "../platform.js";
+import { printPairingCode } from "../device-pairing.js";
 import { renderQr } from "../qr.js";
 import { MacLaunchAgent } from "./macos-launch-agent.js";
 import { WindowsTaskService } from "./windows-task-service.js";
@@ -56,10 +57,14 @@ export async function runServiceCommand(options, context) {
             };
             const { definition, state } = await controller.install(config);
             log(`✓ AgentRoam service installed: ${definition}`);
-            if (state?.status === "ready" && state.accessUrl)
-                await logAccessUrl(state.accessUrl);
+            if (state?.status === "ready" && state.accessUrl) {
+                log(`Open: ${state.accessUrl}`);
+                if (state.localUrl)
+                    log(`电脑本机：${state.localUrl.replace(/\/$/, "")}/web（配对后可进行远程授权）`);
+                await (context.pairingPrinter ?? printPairingCode)(options.dataDir, log, { accessUrl: state.accessUrl, qr: options.qr, interactive: stdoutIsTTY });
+            }
             else
-                log("Service is starting. Run `agentroam service url` shortly.");
+                log("Service is starting. Run `agentroam service url` and `agentroam pair` shortly.");
             return;
         }
         case "start": {

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

@@ -40,6 +40,7 @@ describe("runServiceCommand", () => {
             now: () => new Date("2026-09-03T00:00:00.000Z"),
             log,
             controller: controller({ install }),
+            pairingPrinter: vi.fn(async () => { }),
         });
         expect(install).toHaveBeenCalledWith(expect.objectContaining({
             nodePath: "/node",

package/dist/tunnel/public-readiness.js

@@ -22,7 +22,7 @@ export async function waitForPublicReadiness(publicUrl, options = {}) {
             try {
                 const response = await fetchImpl(endpoint, {
                     cache: "no-store",
-                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.17" },
+                    headers: { "user-agent": "agentroam-readiness/0.2.0-preview.18" },
                     signal: options.signal,
                 });
                 if (response.ok) {

package/install/README.md

@@ -5,7 +5,7 @@ These versioned installers support macOS Apple Silicon and Windows x64. They reu
 ## macOS Apple Silicon
 
 ```sh
-curl -fsSL https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.17/install-agentroam.sh | sh
+curl -fsSL https://gitee.com/caoqu/team-agent/raw/master/packages/cli/install/install-agentroam.sh | sh
 ```
 
 The command installs the wrapper at `~/.local/bin/agentroam`. If that directory is not already in `PATH`, the installer prints the required shell setting without editing shell profiles.
@@ -13,14 +13,14 @@ The command installs the wrapper at `~/.local/bin/agentroam`. If that directory
 ## Windows x64
 
 ```powershell
-irm https://gitee.com/caoqu/team-agent/releases/download/v0.2.0-preview.17/install-agentroam.ps1 | iex
+irm https://gitee.com/caoqu/team-agent/raw/master/packages/cli/install/install-agentroam.ps1 | iex
 ```
 
 The command installs `%USERPROFILE%\.agentroam\bin\agentroam.cmd` and adds only that user directory to the user-level `PATH`. It does not require administrator access or change the machine-level `PATH`.
 
 ## Service behavior
 
-Run the installer from the project directory AgentRoam should expose, or set `AGENTROAM_ROOT` explicitly. An installer launched from the home directory without an explicit root stops before service registration so it cannot expose the entire home directory accidentally.
+Run the installer from the project directory AgentRoam should expose, or set `AGENTROAM_ROOT` explicitly. The current directory is accepted even when it is the home directory.
 
 The installer registers and starts the service after Node, CLI, and `doctor` validation. When a previous AgentRoam user service is installed, the new CLI stops it, waits for its process and platform registration to exit, removes only the old service registration, and then registers the replacement. Session data, pairing state, managed runtimes, and logs remain in the data directory. While foreground AgentRoam or the service is running, it prevents idle system sleep but still allows the display to dim and turn off. Lid close, explicit sleep, hibernation, shutdown, and low-battery forced sleep remain controlled by the operating system.
 
@@ -40,8 +40,16 @@ agentroam service uninstall
 
 ## Data and updates
 
-Set `AGENTROAM_DATA_DIR` before running either installer to override the default `~/.agentroam` data directory. Node is stored at `<data-dir>/runtimes/node/22.22.0`, and the launcher is stored at `<data-dir>/launcher/0.2.0-preview.17`.
+Set `AGENTROAM_DATA_DIR` before running either installer to override the default `~/.agentroam` data directory. Node is stored at `<data-dir>/runtimes/node/22.22.0`, and the launcher is stored at `<data-dir>/launcher/0.2.0-preview.18`.
 
 Each AgentRoam release pins its own Node patch and installer assets. Updates happen only by running a newer versioned installer or installing a newer AgentRoam release; startup never follows a moving Node.js release channel.
 
 To uninstall the wrapper, remove `~/.local/bin/agentroam` on macOS or `%USERPROFILE%\.agentroam\bin\agentroam.cmd` on Windows. The private runtime, launcher, session data, and configuration under the data directory are preserved until explicitly removed by the user.
+
+## Optional desktop app
+
+After CLI setup succeeds, interactive installers ask whether to download the desktop app. Answer `y` to download the matching macOS DMG or Windows installer into a unique folder under Downloads, verify its release-manifest SHA-256, and show the file. Open it to complete installation. Answer `n` or press Enter to keep using CLI only. Noninteractive runs skip the prompt.
+
+Set `AGENTROAM_INSTALL_DESKTOP=yes` or `no` explicitly for automation. The Shell installer reads `/dev/tty`, so `curl ... | sh` remains interactive. A missing desktop artifact or failed download does not undo CLI installation. This requires a published CLI that includes `bin/desktop-download.mjs` and matching desktop release assets.
+
+On macOS, the desktop app opens its own permission guide on first launch, even before connecting to a service. Screen Recording enables phone viewing; Accessibility enables keyboard and mouse control. Returning from System Settings rechecks permissions and resumes an enabled session. Restart the desktop app if macOS requires it. Desktop live publishing follows the selected CLI service, including its actual port. Windows desktop download is supported, but the current screen/input helper is macOS-only.

package/install/install-agentroam.ps1

@@ -3,7 +3,9 @@ $ProgressPreference = "SilentlyContinue"
 
 $NodeVersion = "22.22.0"
 $MinimumNodeVersion = "22.22.0"
-$AgentRoamVersion = "0.2.0-preview.17"
+# 默认跟随 npm preview 最新标签；可用 $env:AGENTROAM_VERSION 钉精确版本
+$AgentRoamVersionRequest = if ($env:AGENTROAM_VERSION) { $env:AGENTROAM_VERSION } else { "preview" }
+$AgentRoamVersion = "pending-version"
 $NodeArchive = "node-v22.22.0-win-x64.zip"
 $NodeSha256 = "c97fa376d2becdc8863fcd3ca2dd9a83a9f3468ee7ccf7a6d076ec66a645c77a"
 $NodeUrl = "https://nodejs.org/dist/v22.22.0/$NodeArchive"
@@ -21,11 +23,6 @@ $ServiceRootExplicit = -not [string]::IsNullOrWhiteSpace($env:AGENTROAM_ROOT)
 $ServiceRoot = if ($ServiceRootExplicit) { $env:AGENTROAM_ROOT } else { (Get-Location).Path }
 if (-not (Test-Path -LiteralPath $ServiceRoot -PathType Container)) { throw "AgentRoam root is not a directory: $ServiceRoot" }
 $ServiceRoot = [System.IO.Path]::GetFullPath($ServiceRoot).TrimEnd([System.IO.Path]::DirectorySeparatorChar)
-$HomeRoot = [System.IO.Path]::GetFullPath($HOME).TrimEnd([System.IO.Path]::DirectorySeparatorChar)
-if (-not $ServiceRootExplicit -and $ServiceRoot -eq $HomeRoot) {
-  throw "Refusing to expose the entire home directory implicitly; run from a project directory or set AGENTROAM_ROOT explicitly"
-}
-
 New-Item -ItemType Directory -Force -Path $NodeParent, $LauncherParent, $WrapperDir | Out-Null
 
 function Test-NodeVersion([string]$VersionText) {
@@ -164,6 +161,17 @@ $NpmCandidates = @(
 $NpmCli = $NpmCandidates | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1
 if (-not $NpmCli) { throw "npm CLI was not found beside $NodeBin" }
 
+# 解析 dist-tag → 精确版本（安装最总是最新发布）
+if ($AgentRoamVersionRequest -notmatch '\d$') {
+    $Resolved = (& $NodeBin $NpmCli view "agentroam@$AgentRoamVersionRequest" version --registry $NpmRegistry 2>$null | Select-Object -Last 1)
+    if (-not $Resolved) { throw "could not resolve agentroam@$AgentRoamVersionRequest from $NpmRegistry" }
+    $AgentRoamVersion = ([string]$Resolved).Trim()
+    Write-Host "Installing AgentRoam $AgentRoamVersion (resolved from $AgentRoamVersionRequest)"
+} else {
+    $AgentRoamVersion = $AgentRoamVersionRequest
+}
+$LauncherRoot = Join-Path $LauncherParent $AgentRoamVersion
+$LauncherLock = Join-Path $LauncherRoot ".lock"
 $PackageSpec = "agentroam@$AgentRoamVersion"
 $ExtraPackageSpecs = @()
 if ($env:AGENTROAM_BOOTSTRAP_TEST -eq "1" -and $env:AGENTROAM_PACKAGE_SPEC) {
@@ -227,3 +235,21 @@ if ($env:AGENTROAM_INSTALL_SKIP_SERVICE -eq "1") {
 }
 Write-Host "`nAgentRoam $AgentRoamVersion installed: $WrapperPath"
 Write-Host "Open a new terminal, then run: agentroam service status"
+
+$DesktopChoice = if ($env:AGENTROAM_INSTALL_DESKTOP) { $env:AGENTROAM_INSTALL_DESKTOP } else { "ask" }
+if ($env:AGENTROAM_INSTALL_SKIP_SERVICE -eq "1" -and $DesktopChoice -eq "ask") { $DesktopChoice = "no" }
+if ($DesktopChoice -eq "ask") {
+  $DesktopChoice = "no"
+  if ([Environment]::UserInteractive -and -not [Console]::IsInputRedirected) {
+    try { $DesktopChoice = Read-Host "是否下载桌面端？用于手机查看和控制电脑桌面 [y/N]" } catch { $DesktopChoice = "no" }
+  }
+}
+if ($DesktopChoice -match '^(y|yes|是)$') {
+  $DesktopHelper = Join-Path $LauncherRoot "node_modules\agentroam\bin\desktop-download.mjs"
+  if (Test-Path -LiteralPath $DesktopHelper -PathType Leaf) {
+    & $NodeBin $DesktopHelper $AgentRoamVersion
+    if ($LASTEXITCODE -ne 0) { Write-Warning "CLI 安装已完成，桌面端可稍后重新下载。" }
+  } else {
+    Write-Warning "当前发布的 CLI 尚未包含桌面下载功能，请在新版发布后重试。CLI 安装已完成。"
+  }
+} else { Write-Host "已跳过桌面端下载，CLI 可正常使用。" }

package/install/install-agentroam.sh

@@ -3,7 +3,10 @@ set -eu
 
 NODE_VERSION="22.22.0"
 MINIMUM_NODE_VERSION="22.22.0"
-AGENTROAM_VERSION="0.2.0-preview.17"
+# Default to the newest published preview; pin an exact version via
+# AGENTROAM_VERSION=0.2.0-preview.18 sh install-agentroam.sh
+AGENTROAM_VERSION_REQUEST="${AGENTROAM_VERSION:-preview}"
+AGENTROAM_VERSION=""
 NODE_ARCHIVE="node-v22.22.0-darwin-arm64.tar.xz"
 NODE_SHA256="2bd596bbfc4a275ceb8721a5954ee97daea5ebe673e96a185ebd732f6fb023ac"
 NODE_URL="https://nodejs.org/dist/v22.22.0/$NODE_ARCHIVE"
@@ -13,14 +16,12 @@ NODE_PARENT="$DATA_DIR/runtimes/node"
 NODE_ROOT="$NODE_PARENT/$NODE_VERSION"
 NODE_LOCK="$NODE_ROOT.lock"
 LAUNCHER_PARENT="$DATA_DIR/launcher"
-LAUNCHER_ROOT="$LAUNCHER_PARENT/$AGENTROAM_VERSION"
+LAUNCHER_ROOT="$LAUNCHER_PARENT/pending-version"
 LAUNCHER_LOCK="$LAUNCHER_ROOT.lock"
 WRAPPER_DIR="$HOME/.local/bin"
 WRAPPER_PATH="$WRAPPER_DIR/agentroam"
-SERVICE_ROOT_EXPLICIT=0
 if [ "${AGENTROAM_ROOT+x}" = "x" ]; then
   SERVICE_ROOT="$AGENTROAM_ROOT"
-  SERVICE_ROOT_EXPLICIT=1
 else
   SERVICE_ROOT="$PWD"
 fi
@@ -49,10 +50,6 @@ command -v shasum >/dev/null 2>&1 || fail "shasum is required"
 [ -x /usr/bin/tar ] || fail "/usr/bin/tar is required"
 [ -d "$SERVICE_ROOT" ] || fail "AgentRoam root is not a directory: $SERVICE_ROOT"
 service_root_physical=$(cd "$SERVICE_ROOT" && pwd -P)
-home_physical=$(cd "$HOME" && pwd -P)
-if [ "$SERVICE_ROOT_EXPLICIT" -eq 0 ] && [ "$service_root_physical" = "$home_physical" ]; then
-  fail "refusing to expose the entire home directory implicitly; run from a project directory or set AGENTROAM_ROOT explicitly"
-fi
 SERVICE_ROOT="$service_root_physical"
 
 mkdir -p "$NODE_PARENT" "$LAUNCHER_PARENT" "$WRAPPER_DIR"
@@ -200,7 +197,23 @@ find_npm_cli() {
 }
 
 NPM_CLI=$(find_npm_cli)
+case "$AGENTROAM_VERSION_REQUEST" in
+  *[0-9])
+    # Looks like an exact version — honor the pin as-is.
+    AGENTROAM_VERSION="$AGENTROAM_VERSION_REQUEST"
+    ;;
+  *)
+    # A dist-tag (default "preview") — resolve to the newest published version
+    # so installs always pick up the latest release without touching this file.
+    resolved_version="$("$NODE_BIN" "$NPM_CLI" view "agentroam@$AGENTROAM_VERSION_REQUEST" version --registry "$NPM_REGISTRY" 2>/dev/null | tail -1 | tr -d '[:space:]')"
+    [ -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"
+    ;;
+esac
 PACKAGE_SPEC="agentroam@$AGENTROAM_VERSION"
+LAUNCHER_ROOT="$LAUNCHER_PARENT/$AGENTROAM_VERSION"
+LAUNCHER_LOCK="$LAUNCHER_ROOT.lock"
 EXTRA_PACKAGE_SPECS=""
 if [ "${AGENTROAM_BOOTSTRAP_TEST:-}" = "1" ] && [ -n "${AGENTROAM_PACKAGE_SPEC:-}" ]; then
   PACKAGE_SPEC="$AGENTROAM_PACKAGE_SPEC"
@@ -251,3 +264,26 @@ case ":${PATH:-}:" in
   *":$WRAPPER_DIR:"*) ;;
   *) printf 'Add this directory to PATH: export PATH="%s:$PATH"\n' "$WRAPPER_DIR" ;;
 esac
+
+# stdin is the script itself when launched with curl | sh. Read the choice
+# from the controlling terminal instead; unattended installs never block.
+desktop_choice="${AGENTROAM_INSTALL_DESKTOP:-ask}"
+if [ "${AGENTROAM_INSTALL_SKIP_SERVICE:-}" = "1" ] && [ "$desktop_choice" = "ask" ]; then desktop_choice=no; fi
+if [ "$desktop_choice" = "ask" ]; then
+  desktop_choice=no
+  if ( : </dev/tty ) 2>/dev/null; then
+    printf '\n是否下载桌面端？用于手机查看和控制电脑桌面 [y/N]：' >/dev/tty
+    IFS= read -r desktop_choice </dev/tty || desktop_choice=no
+  fi
+fi
+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'
+    else
+      printf '当前发布的 CLI 尚未包含桌面下载功能，请在新版发布后重试。CLI 安装已完成。\n'
+    fi
+    ;;
+  *) printf '已跳过桌面端下载，CLI 可正常使用。\n' ;;
+esac

package/package.json

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

package/dist/pairing.js

@@ -1,2 +0,0 @@
-import { createHash, randomBytes } from "node:crypto";
-export function createPairingSecret(now = Date.now()) { const token = randomBytes(32).toString("base64url"); return { token, hashHex: createHash("sha256").update(token).digest("hex"), expiresAt: new Date(now + 5 * 60 * 1000).toISOString() }; }