agentroam 0.2.0-preview.25 → 0.2.0-preview.27

package/README.md

@@ -17,23 +17,24 @@ on a real Windows runner before release.
 npx agentroam@preview
 ```
 
-Or install from tarball:
+Or install from the release tarballs. `<version>` is per-file: platform packages
+may each reuse an older version, so use the actual file names from `dist/cli-release`.
 
 ```bash
-npm install ./agentroam-cloudflared-darwin-arm64-0.2.0-preview.20.tgz \
-  ./agentroam-runtime-darwin-arm64-0.2.0-preview.21.tgz \
-  ./agentroam-tui-darwin-arm64-0.2.0-preview.20.tgz \
-  ./agentroam-0.2.0-preview.21.tgz
+npm install ./agentroam-cloudflared-darwin-arm64-<version>.tgz \
+  ./agentroam-runtime-darwin-arm64-<version>.tgz \
+  ./agentroam-tui-darwin-arm64-<version>.tgz \
+  ./agentroam-<version>.tgz
 npx agentroam
 ```
 
 Windows PowerShell:
 
 ```powershell
-npm install ./agentroam-cloudflared-win32-x64-0.2.0-preview.20.tgz `
-  ./agentroam-runtime-win32-x64-0.2.0-preview.21.tgz `
-  ./caoqu-agentroam-tui-win32-x64-0.2.0-preview.20.tgz `
-  ./agentroam-0.2.0-preview.21.tgz
+npm install ./agentroam-cloudflared-win32-x64-<version>.tgz `
+  ./agentroam-runtime-win32-x64-<version>.tgz `
+  ./caoqu-agentroam-tui-win32-x64-<version>.tgz `
+  ./agentroam-<version>.tgz
 npx agentroam
 ```
 
@@ -55,7 +56,7 @@ agent-tui                 # start the bundled terminal Agent UI
 
 ## Install and run in the background
 
-Run the versioned Shell installer on macOS or PowerShell installer on Windows
+Run the Shell installer on macOS or the 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
@@ -71,7 +72,7 @@ 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
 current-user Task Scheduler task. Neither requires administrator privileges.
-Running a newer versioned installer automatically stops and replaces an existing
+Re-running the installer automatically stops and replaces an existing
 AgentRoam user service before starting the new version. Session data, pairing
 state, managed runtimes, and service logs are preserved during the upgrade.
 
@@ -88,7 +89,7 @@ agentroam service uninstall
 The current phone URL is stored privately at `~/.agentroam/tunnel.url`.
 Cloudflared keeps the same Quick Tunnel hostname while its process reconnects;
 a full service or computer restart creates a new random hostname. Re-run the
-versioned installer after moving or replacing Node/npm so the service receives
+installer after moving or replacing Node/npm so the service receives
 the new absolute executable paths.
 
 Both foreground `agentroam start` and the background service prevent idle system

package/bin/desktop-download.mjs

@@ -9,7 +9,10 @@ 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';
+// 桌面端安装包是构建产物（dmg / exe），进不了只放源码的仓库，只能走 Releases 资产。
+// 资产由 `node scripts/publish-agentroam-release.mjs sync-github --commit <sha>` 上传；
+// 仓库还没有对应版本的 release 时这里必然取不到包（CLI 本体不受影响，它走 raw 安装脚本）。
+const RELEASE_BASE = 'https://github.com/tclxqu-cao/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');

package/bin/node-preflight.mjs

@@ -7,8 +7,9 @@ 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.25";
-const RELEASE_BASE_URL = `https://gitee.com/caoqu/team-agent/releases/download/v${RELEASE_VERSION}`;
+// 安装引导地址：指向仓库主分支上的安装脚本（raw 路径）。
+// 不走 release 产物 —— 避免依赖「发布流程是否产出 asset」，用户拿到的始终是最新安装器。
+const INSTALL_BASE_URL = "https://github.com/tclxqu-cao/team-agent/raw/main/packages/cli/install";
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 
 export async function runNodePreflight(options = {}) {
@@ -160,9 +161,9 @@ function waitForChild(childPromise, processHost) {
 
 function standaloneInstallerMessage(platform) {
   if (platform === "win32") {
-    return `Node.js 18+ is required for automatic bootstrap. Run: irm ${RELEASE_BASE_URL}/install-agentroam.ps1 | iex`;
+    return `Node.js 18+ is required for automatic bootstrap. Run: irm ${INSTALL_BASE_URL}/install-agentroam.ps1 | iex`;
   }
-  return `Node.js 18+ is required for automatic bootstrap. Run: curl -fsSL ${RELEASE_BASE_URL}/install-agentroam.sh | sh`;
+  return `Node.js 18+ is required for automatic bootstrap. Run: curl -fsSL ${INSTALL_BASE_URL}/install-agentroam.sh | sh`;
 }
 
 function cliError(message) {

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { printLocalDesktopUrl } from './local-desktop-url.js';
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import { parseArgs } from "./args.js";
 import { ensureCloudflared } from "./cloudflared/installer.js";
 import { resolveCodexRuntime } from "./codex-runtime-manager.js";
@@ -19,6 +20,7 @@ import { currentCliPath, startUpdate } from "./update/update-command.js";
 import { runUpdateWorker } from "./update/update-worker.js";
 import { lockInstanceStartup, stopPreviousInstances } from "./instance-takeover.js";
 import { runUnlockServiceCommand } from "./unlock-service.js";
+import { createCliErrorLog } from "./error-log.js";
 const VERSION = AGENTROAM_VERSION;
 export async function main(argv) {
     if (argv.includes("--help") || argv.includes("-h")) {
@@ -41,6 +43,11 @@ export async function main(argv) {
         return;
     }
     const options = parseArgs(argv);
+    // CLI 进程自身的按天错误日志:<dataDir>/logs/YYYY-MM-DD.log(NDJSON,与
+    // server/desktop 的 core logger 同格式)。uncaughtException 记录后按默认
+    // 语义退出(1),unhandledRejection 只记录。
+    const cliErrorLog = createCliErrorLog(join(options.dataDir, "logs"));
+    cliErrorLog.installGlobalErrorHandlers();
     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")

package/dist/device-pairing.js

@@ -1,5 +1,6 @@
 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 { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -67,12 +68,44 @@ export async function printPairingCode(dataDir, log = console.log, options = {})
         else
             log("生成 App 授权二维码：agentroam pair --url <手机可访问的服务器地址>");
     }
-    if (options.interactive ?? (process.stdin.isTTY && process.stdout.isTTY)) {
-        await watchPairingApproval(dataDir, result.expiresAt, { log, signal: options.signal });
+    const approvalInput = resolveApprovalInput(options);
+    if (approvalInput) {
+        await watchPairingApproval(dataDir, result.expiresAt, { log, signal: options.signal, input: approvalInput });
     }
     else
         log("查看请求：agentroam approvals；批准：agentroam approve <请求ID> --phrase <手机核对短语>");
 }
+/** Open the controlling terminal (`/dev/tty`) — the same source install-agentroam.sh reads from. */
+function openControllingTerminal() {
+    if (process.platform === "win32")
+        return undefined;
+    let fd;
+    try {
+        fd = openSync("/dev/tty", "r");
+    }
+    catch {
+        return undefined;
+    }
+    return createReadStream("/dev/tty", { fd, autoClose: true });
+}
+/**
+ * Pick the stream the approval phrase is read from.
+ *
+ * Never fall back to `process.stdin` when it is not a TTY: the installer runs as
+ * `curl … | sh`, so stdin is *the install script itself*. Reading it consumes
+ * the rest of the install, echoes it back to the terminal, and answers the
+ * prompt with the next script line instead of the user's "yes" — which silently
+ * rejects the device and swallows the remaining install steps.
+ */
+export function resolveApprovalInput(context = {}) {
+    const stdinIsTTY = context.stdinIsTTY ?? process.stdin.isTTY === true;
+    const stdoutIsTTY = context.stdoutIsTTY ?? process.stdout.isTTY === true;
+    if (!(context.interactive ?? (stdinIsTTY && stdoutIsTTY)))
+        return undefined;
+    if (stdinIsTTY)
+        return process.stdin;
+    return (context.openTerminal ?? openControllingTerminal)();
+}
 /** 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;
@@ -93,7 +126,8 @@ export async function watchPairingApproval(dataDir, codeExpiresAt, options = {})
             log(`新设备请求连接：${terminalText(request.name)}`);
             log(`请求 ID：${request.id}`);
             log(`核对短语：${request.phrase}`);
-            const approved = await (options.confirm ?? confirmOnTerminal)(request, options.signal);
+            const confirm = options.confirm ?? ((request, signal) => confirmOnTerminal(request, signal, options.input));
+            const approved = await confirm(request, options.signal);
             if (options.signal?.aborted)
                 return;
             if (Date.now() >= request.expires) {
@@ -114,10 +148,17 @@ export async function watchPairingApproval(dataDir, codeExpiresAt, options = {})
     if (!options.signal?.aborted)
         log("配对码已过期，执行 agentroam pair 生成新码。");
 }
-async function confirmOnTerminal(request, signal) {
+async function confirmOnTerminal(request, signal, terminal = resolveApprovalInput()) {
+    // A piped stdin is the install script, and a closed one can never answer.
+    if (!terminal || (terminal === process.stdin && process.stdin.isTTY !== true))
+        return false;
     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 });
+    // Read the terminal in canonical mode: the tty echoes the keystrokes itself,
+    // so letting readline echo them again would double every character.
+    const input = createInterface(terminal === process.stdin
+        ? { input: terminal, output: process.stdout }
+        : { input: terminal, output: process.stdout, terminal: false });
     input.once("SIGINT", () => controller.abort());
     try {
         const answer = await input.question("确认手机显示相同短语？输入 yes 批准，其他输入拒绝：", { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal });

package/dist/error-log.js

@@ -0,0 +1,113 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+// Self-contained daily error log for the CLI process. The CLI cannot depend
+// on @agent/core (it ships as a thin launcher), so this mirrors the exact
+// NDJSON entry format of core's DailyFileLogger
+// (`{ts, level, source, message, error?, data?}`) into `<dataDir>/logs/`.
+// It records uncaughtException / unhandledRejection so launcher failures are
+// strictly persisted, matching the server/desktop log series.
+const LEVELS = new Set(["debug", "info", "warn", "error", "fatal"]);
+function localDateString(date) {
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, "0");
+    const d = String(date.getDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+}
+function serializeError(err) {
+    if (err === undefined || err === null)
+        return undefined;
+    if (err instanceof Error) {
+        const out = { name: err.name, message: err.message };
+        if (err.stack)
+            out.stack = err.stack;
+        return out;
+    }
+    if (typeof err === "object") {
+        const anyErr = err;
+        const out = {
+            name: typeof anyErr.name === "string" ? anyErr.name : "NonError",
+            message: typeof anyErr.message === "string" ? anyErr.message : String(err),
+        };
+        if (typeof anyErr.stack === "string")
+            out.stack = anyErr.stack;
+        return out;
+    }
+    return { name: "NonError", message: String(err) };
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? "null";
+    }
+    catch {
+        return '"[unserializable]"';
+    }
+}
+export function createCliErrorLog(logsDir) {
+    let reportedWriteFailure = false;
+    const write = (line) => {
+        try {
+            if (!existsSync(logsDir))
+                mkdirSync(logsDir, { recursive: true });
+            appendFileSync(join(logsDir, `${localDateString(new Date())}.log`), line, "utf8");
+        }
+        catch {
+            if (!reportedWriteFailure) {
+                reportedWriteFailure = true;
+                try {
+                    process.stderr.write(`[agentroam] failed to write error log to ${logsDir}; further failures are silent\n`);
+                }
+                catch { /* stderr gone */ }
+            }
+        }
+    };
+    const cleanupOldFiles = () => {
+        // 30-day retention, aligned with the core logger default. Best effort.
+        try {
+            if (!existsSync(logsDir))
+                return;
+            const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
+            for (const name of readdirSync(logsDir)) {
+                if (!/^\d{4}-\d{2}-\d{2}\.log$/.test(name))
+                    continue;
+                const full = join(logsDir, name);
+                try {
+                    if (statSync(full).mtimeMs < cutoff)
+                        unlinkSync(full);
+                }
+                catch { /* concurrent removal */ }
+            }
+        }
+        catch { /* best effort */ }
+    };
+    const log = (level, message, error, data) => {
+        if (!LEVELS.has(level))
+            level = "error";
+        const entry = {
+            ts: new Date().toISOString(),
+            level,
+            source: "cli",
+            message: typeof message === "string" ? message.slice(0, 4000) : String(message),
+        };
+        const serialized = serializeError(error);
+        if (serialized)
+            entry.error = serialized;
+        if (data !== undefined)
+            entry.data = data;
+        write(`${safeStringify(entry)}\n`);
+    };
+    return {
+        log,
+        installGlobalErrorHandlers: (options = {}) => {
+            const exitOnUncaughtException = options.exitOnUncaughtException ?? true;
+            process.on("uncaughtException", (err) => {
+                log("fatal", "uncaughtException", err);
+                if (exitOnUncaughtException)
+                    process.exit(1);
+            });
+            process.on("unhandledRejection", (reason) => {
+                log("error", "unhandledRejection", reason);
+            });
+            cleanupOldFiles();
+        },
+    };
+}

package/dist/platform-packages.js

@@ -2,8 +2,15 @@ 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.25";
-export const PLATFORM_DEPENDENCY_VERSIONS = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).optionalDependencies;
+const CLI_PACKAGE_JSON = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+/**
+ * CLI 自身版本。
+ *
+ * **唯一源头是 packages/cli/package.json 的 version** —— 发版时只改那一处，
+ * 本文件、bin/node-preflight.mjs、tunnel/public-readiness.ts 全部自动跟随。
+ */
+export const AGENTROAM_VERSION = CLI_PACKAGE_JSON.version;
+export const PLATFORM_DEPENDENCY_VERSIONS = CLI_PACKAGE_JSON.optionalDependencies;
 export const PLATFORM_PACKAGES = {
     "darwin-arm64": {
         runtime: "agentroam-runtime-darwin-arm64",

package/dist/runtime-manager.js

@@ -36,6 +36,9 @@ export class RuntimeManager {
                 PORT: String(port),
                 HOST: options.localOnly ? "0.0.0.0" : "127.0.0.1",
                 AGENT_DATA_DIR: resolve(dataDir, "data"),
+                // 应用日志收口到 <dataDir>/logs,与 launchd 的 service.stdout/stderr.log
+                // 及 CLI 自身的错误日志同一个目录,用户排障时只需打包这一处。
+                AGENT_LOG_DIR: resolve(dataDir, "logs"),
                 AGENT_WEB_ROOTS: options.roots.join(delimiter),
                 AGENT_TRUST_TUNNEL_PROXY: "1",
                 AGENTROAM_VERSION: resolvePlatformRuntime(target).manifest.packageVersion,

package/dist/tunnel/public-readiness.js

@@ -1,5 +1,6 @@
 import { fetch as undiciFetch, ProxyAgent } from "undici";
 import { resolveProxyForUrl } from "./proxy-settings.js";
+import { AGENTROAM_VERSION } from "../platform-packages.js";
 export async function waitForPublicReadiness(publicUrl, options = {}) {
     const timeoutMs = options.timeoutMs ?? 30_000;
     const intervalMs = options.intervalMs ?? 750;
@@ -22,7 +23,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.25" },
+                    headers: { "user-agent": `agentroam-readiness/${AGENTROAM_VERSION}` },
                     signal: options.signal,
                 });
                 if (response.ok) {

package/dist/update/update-command.js

@@ -4,10 +4,9 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
 import { updatePaths, writeUpdateState } from "./update-state.js";
-import { parseChannelVersion, registryUrlsForChannel, resolveReleaseChannel, resolveUpdateChannel, } from "./update-channel.js";
+import { parseChannelVersion, registryUrlsForChannel, resolveUpdateChannel, } from "./update-channel.js";
+import { buildCliInstallManifestUrl, validateCliInstallManifest } from "./update-install.js";
 const REGISTRY_BASE = "https://registry.npmjs.org/agentroam";
-const RELEASE_BASE = "https://gitee.com/caoqu/team-agent/releases/download";
-const SHA = /^[a-f0-9]{64}$/;
 export async function resolveUpdate(options, fetchImpl = fetch) {
     const channel = resolveUpdateChannel(options.currentVersion);
     const target = await readRegistryCandidate(fetchImpl, channel);
@@ -17,16 +16,11 @@ export async function resolveUpdate(options, fetchImpl = fetch) {
         throw new Error("requested version is not the current npm candidate");
     if (compare(target, options.currentVersion) <= 0)
         throw new Error("AgentRoam is already up to date");
-    const response = await fetchWithTimeout(fetchImpl, `${RELEASE_BASE}/v${target}/release-manifest.json`);
+    const response = await fetchWithTimeout(fetchImpl, buildCliInstallManifestUrl());
     if (!response.ok)
-        throw new Error("release manifest is unavailable");
-    const manifest = await response.json();
-    const asset = manifest?.installers?.cli?.[options.target];
-    const fileName = options.target === "darwin-arm64" ? "install-agentroam.sh" : "install-agentroam.ps1";
-    if (manifest?.schemaVersion !== 2 || manifest.version !== target || manifest.channel !== resolveReleaseChannel(target) || asset?.fileName !== fileName || !SHA.test(asset?.sha256 ?? "")) {
-        throw new Error("release manifest is invalid for this platform");
-    }
-    return { targetVersion: target, fileName, sha256: asset.sha256 };
+        throw new Error("CLI install manifest is unavailable");
+    const asset = validateCliInstallManifest(await response.json(), options.target);
+    return { targetVersion: target, fileName: asset.fileName, sha256: asset.sha256 };
 }
 // Preview installations follow the higher of the preview and latest npm
 // dist-tags so a newer stable release can move them onto the stable track.

package/dist/update/update-install.js

@@ -0,0 +1,34 @@
+const REPOSITORY_BASE = "https://github.com/tclxqu-cao/team-agent";
+const REPOSITORY_BRANCH = "main";
+const INSTALL_BASE = `${REPOSITORY_BASE}/raw/${REPOSITORY_BRANCH}/packages/cli/install`;
+export const CLI_INSTALL_FILE_NAMES = {
+    "darwin-arm64": "install-agentroam.sh",
+    "windows-amd64": "install-agentroam.ps1",
+};
+export function buildCliInstallManifestUrl() {
+    return `${INSTALL_BASE}/install-manifest.json`;
+}
+export function buildCliInstallScriptUrl(fileName) {
+    if (!Object.values(CLI_INSTALL_FILE_NAMES).includes(fileName))
+        throw new Error("invalid CLI installer file name");
+    return `${INSTALL_BASE}/${fileName}`;
+}
+export function validateCliInstallManifest(value, platform) {
+    const expected = CLI_INSTALL_FILE_NAMES[platform];
+    if (!expected)
+        throw new Error("CLI install manifest does not support this platform");
+    if (typeof value !== "object" || value === null)
+        throw new Error("invalid CLI install manifest identity");
+    const manifest = value;
+    if (manifest.schemaVersion !== 1 || typeof manifest.installers !== "object" || manifest.installers === null) {
+        throw new Error("invalid CLI install manifest identity");
+    }
+    const asset = manifest.installers[platform];
+    if (!asset || asset.fileName !== expected || typeof asset.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(asset.sha256)) {
+        throw new Error("invalid CLI installer metadata");
+    }
+    if (asset.size !== undefined && (!Number.isSafeInteger(asset.size) || asset.size <= 0)) {
+        throw new Error("invalid CLI installer size");
+    }
+    return { fileName: expected, sha256: asset.sha256, ...(asset.size === undefined ? {} : { size: asset.size }) };
+}

package/dist/update/update-worker.js

@@ -6,7 +6,7 @@ import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { spawn } from "node:child_process";
 import { acquireUpdateLock, readUpdateState, sanitizeUpdateError, updatePaths, writeUpdateState } from "./update-state.js";
-const RELEASE_BASE = "https://gitee.com/caoqu/team-agent/releases/download";
+import { buildCliInstallScriptUrl } from "./update-install.js";
 export async function runUpdateWorker(stateFile, fetchImpl = fetch) {
     const initial = await readUpdateState(stateFile);
     if (!initial)
@@ -22,7 +22,7 @@ export async function runUpdateWorker(stateFile, fetchImpl = fetch) {
         await writeUpdateState(stateFile, state);
     };
     try {
-        const response = await fetchImpl(`${RELEASE_BASE}/v${state.targetVersion}/${encodeURIComponent(state.fileName)}`);
+        const response = await fetchImpl(buildCliInstallScriptUrl(state.fileName));
         if (!response.ok || !response.body)
             throw new Error("installer download failed");
         await pipeline(Readable.fromWeb(response.body), createWriteStream(partial, { mode: 0o700 }));
@@ -33,7 +33,16 @@ export async function runUpdateWorker(stateFile, fetchImpl = fetch) {
         await update({ phase: "installing" });
         const command = process.platform === "win32" ? "powershell.exe" : "/bin/sh";
         const args = process.platform === "win32" ? ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", partial] : [partial];
-        const code = await run(command, args, { ...process.env, AGENTROAM_DATA_DIR: state.dataDir, AGENTROAM_ROOT: state.roots[0], AGENTROAM_INSTALL_SKIP_SERVICE: "1" });
+        // 用 AGENTROAM_VERSION 钉住版本，而不是让安装脚本自己解析 dist-tag：
+        // 一是装的必须正是检查阶段向用户承诺的那一版，二是下一步要按
+        // launcher/<targetVersion> 定位入口，版本漂了就找不到。
+        const code = await run(command, args, {
+            ...process.env,
+            AGENTROAM_VERSION: state.targetVersion,
+            AGENTROAM_DATA_DIR: state.dataDir,
+            AGENTROAM_ROOT: state.roots[0],
+            AGENTROAM_INSTALL_SKIP_SERVICE: "1",
+        });
         if (code !== 0)
             throw new Error(`installer exited with code ${code}`);
         const nextEntry = resolve(state.dataDir, "launcher", state.targetVersion, "node_modules", "agentroam", "bin", "agentroam.mjs");

package/install/README.md

@@ -1,11 +1,11 @@
 # AgentRoam bootstrap installers
 
-These versioned installers support macOS Apple Silicon and Windows x64. They reuse the active Node.js installation when it meets `>=22.22.0`, with no upper version bound. Otherwise they search NVM for the highest compatible version, then fall back to the verified private Node.js `22.22.0` runtime under the AgentRoam data directory. They then register and start the current-user AgentRoam background service. They never modify, replace, or uninstall system Node.js or global power settings.
+These installers support macOS Apple Silicon and Windows x64. They install the newest published `preview` release by default (resolved from the npm dist-tag); pin an exact release with `AGENTROAM_VERSION=<x.y.z-preview.N>`. They reuse the active Node.js installation when it meets `>=22.22.0`, with no upper version bound. Otherwise they search NVM for the highest compatible version, then fall back to the verified private Node.js `22.22.0` runtime under the AgentRoam data directory. They then register and start the current-user AgentRoam background service. They never modify, replace, or uninstall system Node.js or global power settings.
 
 ## macOS Apple Silicon
 
 ```sh
-curl -fsSL https://gitee.com/caoqu/team-agent/raw/master/packages/cli/install/install-agentroam.sh | sh
+curl -fsSL https://github.com/tclxqu-cao/team-agent/raw/main/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,7 +13,7 @@ The command installs the wrapper at `~/.local/bin/agentroam`. If that directory
 ## Windows x64
 
 ```powershell
-irm https://gitee.com/caoqu/team-agent/raw/master/packages/cli/install/install-agentroam.ps1 | iex
+irm https://github.com/tclxqu-cao/team-agent/raw/main/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`.
@@ -40,9 +40,9 @@ 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.21`.
+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/<version>`.
 
-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.
+Each AgentRoam release pins its own Node patch. Updates happen by running the installer again (it resolves the newest published `preview`) or by 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.
 

package/install/install-agentroam.ps1

@@ -4,7 +4,7 @@ $ProgressPreference = "SilentlyContinue"
 $NodeVersion = "22.22.0"
 $MinimumNodeVersion = "22.22.0"
 # 默认跟随 npm preview 最新标签；可用 $env:AGENTROAM_VERSION 钉精确版本
-# 例如：$env:AGENTROAM_VERSION = "0.2.0-preview.25"; ./install-agentroam.ps1
+# 例如：$env:AGENTROAM_VERSION = "<x.y.z-preview.N>"; ./install-agentroam.ps1
 $AgentRoamVersionRequest = if ($env:AGENTROAM_VERSION) { $env:AGENTROAM_VERSION } else { "preview" }
 $AgentRoamVersion = "pending-version"
 $NodeArchive = "node-v22.22.0-win-x64.zip"

package/install/install-agentroam.sh

@@ -3,8 +3,8 @@ set -eu
 
 NODE_VERSION="22.22.0"
 MINIMUM_NODE_VERSION="22.22.0"
-# Default to the newest published preview; pin an exact version via
-# AGENTROAM_VERSION=0.2.0-preview.25 sh install-agentroam.sh
+# Default to the newest published preview (npm dist-tag); pin an exact version via
+# AGENTROAM_VERSION=<x.y.z-preview.N> sh install-agentroam.sh
 AGENTROAM_VERSION_REQUEST="${AGENTROAM_VERSION:-preview}"
 AGENTROAM_VERSION=""
 NODE_ARCHIVE="node-v22.22.0-darwin-arm64.tar.xz"

package/install/install-manifest.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "installers": {
+    "darwin-arm64": {
+      "fileName": "install-agentroam.sh",
+      "sha256": "db22342cd22272c739f6633deff65c4b54b9dc919778141b7d8d55c37be221a3",
+      "size": 11625
+    },
+    "windows-amd64": {
+      "fileName": "install-agentroam.ps1",
+      "sha256": "4a3683a3e6027e15356dab7a5c7d02a81ad1be3f4bad61a6119328ed2ab89298",
+      "size": 13155
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentroam",
-  "version": "0.2.0-preview.25",
+  "version": "0.2.0-preview.27",
   "description": "Zero-install mobile remote terminal and file console",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run --root ../.. packages/cli/src",
     "prepack": "npm run build"
   },
@@ -26,12 +26,12 @@
     "undici": "^6.25.0"
   },
   "optionalDependencies": {
-    "agentroam-runtime-darwin-arm64": "0.2.0-preview.25",
-    "agentroam-runtime-win32-x64": "0.2.0-preview.25",
-    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.25",
-    "agentroam-cloudflared-win32-x64": "0.2.0-preview.25",
-    "agentroam-tui-darwin-arm64": "0.2.0-preview.25",
-    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.25"
+    "agentroam-runtime-darwin-arm64": "0.2.0-preview.27",
+    "agentroam-runtime-win32-x64": "0.2.0-preview.27",
+    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.27",
+    "agentroam-cloudflared-win32-x64": "0.2.0-preview.27",
+    "agentroam-tui-darwin-arm64": "0.2.0-preview.27",
+    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.27"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",