agentroam 0.2.0-preview.48 → 0.2.0-preview.53

package/README.md

@@ -40,7 +40,7 @@ npx agentroam
 
 On first run:
 
-1. AgentRoam tries a bundled **Cloudflare Quick Tunnel**, then a **Pinggy HTTPS tunnel** over SSH port 443.
+1. AgentRoam tries a bundled **Cloudflare Quick Tunnel** for up to 30 seconds, then uses **LAN access** if that attempt fails or times out.
 2. A **QR code** prints in the terminal — scan it on your phone.
 3. Complete **one-time pairing** (5-minute token) and create the admin account.
 4. Use the web terminal + file tree remotely.
@@ -49,7 +49,7 @@ On first run:
 
 ```bash
 agentroam                 # start (default)
-agentroam doctor          # check native modules + platform
+agentroam doctor          # check native modules and install Codex if missing
 agentroam version
 agent-tui                 # start the bundled terminal Agent UI
 ```
@@ -103,7 +103,7 @@ hibernation, shutdown, and low-battery forced sleep remain controlled by the OS.
 |------|-------------|
 | `--root <path>` | Workspace root (repeatable). Default: cwd |
 | `--local-only` | Skip tunnel; LAN/localhost only |
-| `--relay auto` | Cloudflare, then Pinggy, then LAN (default) |
+| `--relay auto` | Cloudflare, then LAN on failure or timeout (default) |
 | `--relay cloudflare` | Cloudflare only, then LAN |
 | `--relay pinggy` | Pinggy only, then LAN |
 | `--relay custom --tunnel-command "<cmd>"` | Your own tunnel command |
@@ -111,7 +111,9 @@ hibernation, shutdown, and low-battery forced sleep remain controlled by the OS.
 | `--port <n>` | Fixed local port |
 | `--data-dir <path>` | State directory (default: `~/.agentroam`) |
 
-The platform cloudflared binary is installed from npm after size and SHA-256 verification, so startup does not download from GitHub. If Cloudflare cannot connect, automatic mode tries Pinggy over outbound SSH port 443. Pinggy free tunnels last up to 60 minutes and may show a one-time security confirmation in the phone browser. If neither public relay works, the QR code uses a LAN address and the phone must be on the same local network.
+The platform cloudflared binary is installed from npm after size and SHA-256 verification, so startup does not download from GitHub. Automatic mode attempts Cloudflare for at most 30 seconds, including connection and public health checks. Any failure falls back directly to LAN, where the phone must be on the same local network. Pinggy is only used when explicitly selected with `--relay pinggy`; a failed explicit relay also falls back to LAN.
+
+Startup reuses a compatible installed Codex CLI. Only when none is found does it install `@openai/codex@latest`; Codex preparation is limited to 180 seconds. Installed OpenCode is reused, and missing OpenCode is skipped without downloading. If Codex installation fails or times out, the local service still starts with an explicit warning that Codex sessions are unavailable. Run `agentroam doctor` to repair Codex, then restart the service. Remote desktop uses the bundled native runtime and still requires system authorization.
 
 ## What's included
 

package/dist/abort.js

@@ -0,0 +1,25 @@
+/** Bound an asynchronous operation even when its implementation ignores cancellation. */
+export async function withAbortSignal(operation, signal) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            signal.removeEventListener("abort", abort);
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        Promise.resolve().then(() => {
+            signal.throwIfAborted();
+            return operation();
+        }).then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+export async function withTimeout(operation, timeoutMs, message) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(message)), timeoutMs);
+    try {
+        return await withAbortSignal(() => operation(controller.signal), controller.signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/cli.js

@@ -11,7 +11,8 @@ import { installedDataDir, pairingAdmin, printPairingCode, terminalText } from "
 import { detectPlatform } from "./platform.js";
 import { AGENTROAM_VERSION, resolvePlatformRuntime, resolvePlatformTui } from "./platform-packages.js";
 import { acquireSleepInhibitor } from "./power/sleep-inhibitor.js";
-import { RuntimeManager } from "./runtime-manager.js";
+import { CODEX_PREPARATION_TIMEOUT_MS, RuntimeManager } from "./runtime-manager.js";
+import { withTimeout } from "./abort.js";
 import { ServiceRuntimeReporter } from "./service/runtime-state.js";
 import { runServiceCommand } from "./service/service-command.js";
 import { resolveServicePaths } from "./service/service-files.js";
@@ -197,7 +198,7 @@ async function executeCommand(options, argv) {
         await serviceReporter?.localReady(runtime.localUrl);
         if (!serviceReporter)
             printLocalDesktopUrl(runtime.localUrl);
-        const lanUrl = options.localOnly ? findLanUrl(runtime.port) ?? runtime.localUrl : runtime.localUrl;
+        const lanUrl = findLanUrl(runtime.port) ?? runtime.localUrl;
         const relayRuntime = runtime;
         relay = await withCliProgress("正在建立手机访问连接", () => selectRelay({
             cli: options,
@@ -207,9 +208,8 @@ async function executeCommand(options, argv) {
             port: relayRuntime.port,
             signal: controller.signal,
             log: (line) => process.stderr.write(`${line}\n`),
-            onAttempt: (provider) => console.log(`▲ Trying ${providerDisplayName(provider)} relay...`),
-            onFailure: (provider, message) => console.error(`⚠ ${providerDisplayName(provider)} unavailable: ${message}`),
-            allowLanFallback: options.localOnly,
+            onAttempt: (provider) => console.log(`▲ 正在连接 ${providerDisplayName(provider)}（最多 30 秒，失败后使用局域网）…`),
+            onFailure: (provider, message) => console.error(`⚠ ${providerDisplayName(provider)} 不可用：${message}；正在切换到局域网。`),
         }));
         if (controller.signal.aborted) {
             await relay.tunnel?.close();
@@ -220,6 +220,7 @@ async function executeCommand(options, argv) {
                 console.error(`  Continuing with local network access: ${relay.publicUrl}/web`);
             else
                 console.log(`✓ Local network: ${relay.publicUrl}/web`);
+            console.log(lanUrl === runtime.localUrl ? "当前没有可用的局域网地址，可先在本机使用；连接 Wi-Fi 或有线网络后重启服务以生成手机访问地址。" : "手机与电脑连接同一局域网后，即可使用以上地址或二维码连接。");
         }
         else {
             console.log(`✓ ${providerDisplayName(relay.provider)} tunnel ready: ${relay.publicUrl}`);
@@ -297,11 +298,12 @@ async function doctor(target, dataDir) {
         reportDoctorFailure(error, "agent-tui: ");
     }
     try {
-        const codex = await withCliProgress("正在检查和准备 Codex", () => resolveCodexRuntime({
+        const codex = await withCliProgress("正在检查和准备 Codex（最多 180 秒）", () => withTimeout(signal => resolveCodexRuntime({
             dataDir,
             target,
+            signal,
             onProgress: (message) => console.log(`… ${message}`),
-        }));
+        }), CODEX_PREPARATION_TIMEOUT_MS, "Codex 组件准备超时（180 秒）；请检查网络后重试。"));
         console.log(`✓ Codex ${codex.version} (${codex.source}) ${codex.executable}`);
     }
     catch (error) {

package/dist/codex-runtime-manager.js

@@ -3,22 +3,25 @@ import { constants } from "node:fs";
 import { access, chmod, mkdir, mkdtemp, open, readdir, rename, rm, stat, } from "node:fs/promises";
 import { delimiter, dirname, isAbsolute, relative, resolve, win32 } from "node:path";
 import { promisify } from "node:util";
+import { withAbortSignal } from "./abort.js";
 const execFileAsync = promisify(execFile);
 // Fresh installs follow npm's latest stable release; existing installs have an independent floor.
 export const CODEX_RUNTIME_TAG = "latest";
 export const CODEX_MINIMUM_VERSION = "0.153.0";
 const CODEX_PACKAGE = `@openai/codex@${CODEX_RUNTIME_TAG}`;
 const NPM_REGISTRY = "https://registry.npmjs.org";
-export const CODEX_INSTALL_TIMEOUT_MS = 60 * 60_000;
+export const CODEX_INSTALL_TIMEOUT_MS = 180_000;
 const DEFAULT_LOCK_WAIT_MS = 190_000;
 export const CODEX_INSTALL_STALE_LOCK_MS = CODEX_INSTALL_TIMEOUT_MS + 5 * 60_000;
 const DEFAULT_STALE_LOCK_MS = CODEX_INSTALL_STALE_LOCK_MS;
 const defaultDependencies = {
-    async run(command, args, timeoutMs) {
+    async run(command, args, timeoutMs, signal) {
         try {
             const { stdout, stderr } = await execFileAsync(command, args, {
                 encoding: "utf8",
                 timeout: timeoutMs,
+                signal,
+                killSignal: "SIGKILL",
                 maxBuffer: 4 * 1024 * 1024,
                 windowsHide: true,
             });
@@ -36,9 +39,21 @@ const defaultDependencies = {
     now: () => Date.now(),
 };
 export async function resolveCodexRuntime(options) {
+    return options.signal
+        ? withAbortSignal(() => resolveRuntime(options), options.signal)
+        : resolveRuntime(options);
+}
+async function resolveRuntime(options) {
     const environment = options.environment ?? process.env;
     const platform = options.platform ?? process.platform;
     const dependencies = { ...defaultDependencies, ...options.dependencies };
+    const signal = options.signal;
+    if (signal) {
+        const run = dependencies.run;
+        const sleep = dependencies.sleep;
+        dependencies.run = (command, args, timeoutMs) => withAbortSignal(() => run(command, args, timeoutMs, signal), signal);
+        dependencies.sleep = (delayMs) => withAbortSignal(() => sleep(delayMs), signal);
+    }
     const explicit = environment.AGENT_CODEX_BIN?.trim();
     if (explicit) {
         const absolute = platform === "win32" ? win32.isAbsolute(explicit) : isAbsolute(explicit);
@@ -54,6 +69,9 @@ export async function resolveCodexRuntime(options) {
     const managed = await findManagedRuntime(managedParent, options.target, platform, dependencies);
     if (managed)
         return managed;
+    signal?.throwIfAborted();
+    if (options.installIfMissing === false)
+        throw new Error("Codex is not installed; run agentroam doctor to install it.");
     options.onProgress?.(`Installing managed Codex from ${CODEX_PACKAGE}...`);
     return installManagedCodex({
         ...options,
@@ -199,6 +217,7 @@ async function installManagedCodex(options) {
             throw new Error(`Codex runtime validation failed after installing ${CODEX_PACKAGE}`);
         }
         const managedRoot = resolve(parent, temporary.version);
+        options.signal?.throwIfAborted();
         // An invalid cache for this version must not block a validated replacement.
         await rm(managedRoot, { recursive: true, force: true });
         await rename(temporaryRoot, managedRoot);
@@ -209,6 +228,7 @@ async function installManagedCodex(options) {
         return installed;
     }
     catch (error) {
+        options.signal?.throwIfAborted();
         const concurrent = await findManagedRuntime(parent, options.target, options.platform, options.dependencies);
         if (concurrent)
             return concurrent;

package/dist/codex-sharing.js

@@ -47,7 +47,7 @@ export async function configureCodexSharing(options, context = {}) {
     };
     const json = `${paths.root}/job.json`;
     const temporary = `${paths.root}/job.plist`;
-    const commandOptions = { encoding: "utf8", timeout: 20_000, maxBuffer: 1024 * 1024 };
+    const commandOptions = { encoding: "utf8", timeout: 20_000, maxBuffer: 1024 * 1024, signal: context.signal, killSignal: "SIGKILL" };
     // Identical startup calls must not unload/reload an already healthy job.
     let unchanged = false;
     try {

package/dist/native-runtime.js

@@ -1,5 +1,22 @@
 import { chmod } from "node:fs/promises";
 import { resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execute = promisify(execFile);
+const WINDOWS_PTY_PROBE = `
+const pty = require(process.argv[1]);
+const marker = "agentroam-runtime-probe";
+const terminal = pty.spawn(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", "echo " + marker], {
+  name: "xterm-256color", cols: 80, rows: 24, cwd: process.cwd(), env: process.env,
+});
+let output = "";
+const timer = setTimeout(() => process.exit(1), 5000);
+terminal.onData(chunk => { output = (output + chunk).slice(-4096); });
+terminal.onExit(({ exitCode }) => {
+  clearTimeout(timer);
+  process.exit(exitCode === 0 && output.includes(marker) ? 0 : 1);
+});
+`;
 export function probeSQLiteRuntime(runtimeRequire) {
     const Database = runtimeRequire("better-sqlite3");
     const database = new Database(":memory:");
@@ -15,12 +32,17 @@ export function probeSQLiteRuntime(runtimeRequire) {
     }
 }
 export async function probeTerminalRuntime(runtimeRequire, platform = process.platform) {
+    if (platform === "win32") {
+        // ConPTY retains an output worker after shell exit. Keep the probe in an
+        // owned child process so terminating it releases all handles together.
+        await execute(process.execPath, ["--input-type=commonjs", "-e", WINDOWS_PTY_PROBE, runtimeRequire.resolve("node-pty")], {
+            timeout: 10_000, windowsHide: true, maxBuffer: 64 * 1024,
+        });
+        return;
+    }
     const pty = runtimeRequire("node-pty");
-    const windows = platform === "win32";
     const marker = "agentroam-runtime-probe";
-    const terminal = pty.spawn(windows ? (process.env.ComSpec || "cmd.exe") : "/bin/sh", windows
-        ? ["/d", "/s", "/c", `echo ${marker}`]
-        : ["-c", `printf ${marker}`], {
+    const terminal = pty.spawn("/bin/sh", ["-c", `printf ${marker}`], {
         name: "xterm-256color", cols: 80, rows: 24, cwd: process.cwd(), env: process.env,
     });
     await new Promise((resolveProbe, rejectProbe) => {

package/dist/opencode-runtime-manager.js

@@ -4,6 +4,7 @@ import { access, chmod, mkdir, mkdtemp, open, rename, rm, stat } from "node:fs/p
 import { delimiter, isAbsolute, relative, resolve, win32 } from "node:path";
 import { promisify } from "node:util";
 import { resolveNpmExecutor } from "./codex-runtime-manager.js";
+import { withAbortSignal } from "./abort.js";
 const execFileAsync = promisify(execFile);
 // Default managed installation; compatibility has an independent minimum.
 export const OPENCODE_RUNTIME_VERSION = "1.18.27";
@@ -11,11 +12,13 @@ export const OPENCODE_MINIMUM_VERSION = "1.18.27";
 const OPENCODE_PACKAGE = `opencode-ai@${OPENCODE_RUNTIME_VERSION}`;
 const NPM_REGISTRY = "https://registry.npmjs.org";
 const defaults = {
-    async run(command, args, timeoutMs) {
+    async run(command, args, timeoutMs, signal) {
         try {
             const { stdout, stderr } = await execFileAsync(command, args, {
                 encoding: "utf8",
                 timeout: timeoutMs,
+                signal,
+                killSignal: "SIGKILL",
                 maxBuffer: 4 * 1024 * 1024,
                 windowsHide: true,
             });
@@ -30,9 +33,21 @@ const defaults = {
     now: () => Date.now(),
 };
 export async function resolveOpenCodeRuntime(options) {
+    return options.signal
+        ? withAbortSignal(() => resolveRuntime(options), options.signal)
+        : resolveRuntime(options);
+}
+async function resolveRuntime(options) {
     const environment = options.environment ?? process.env;
     const platform = options.platform ?? process.platform;
     const dependencies = { ...defaults, ...options.dependencies };
+    const signal = options.signal;
+    if (signal) {
+        const run = dependencies.run;
+        const sleep = dependencies.sleep;
+        dependencies.run = (command, args, timeoutMs) => withAbortSignal(() => run(command, args, timeoutMs, signal), signal);
+        dependencies.sleep = (delayMs) => withAbortSignal(() => sleep(delayMs), signal);
+    }
     const explicit = environment.AGENT_OPENCODE_BIN?.trim();
     if (explicit) {
         const absolute = platform === "win32" ? win32.isAbsolute(explicit) : isAbsolute(explicit);
@@ -47,6 +62,9 @@ export async function resolveOpenCodeRuntime(options) {
     const managed = await validateManaged(managedRoot, platform, dependencies);
     if (managed)
         return managed;
+    signal?.throwIfAborted();
+    if (options.installIfMissing === false)
+        throw new Error("OpenCode is not installed; optional OpenCode sessions are unavailable.");
     options.onProgress?.(`Installing managed OpenCode ${OPENCODE_RUNTIME_VERSION}...`);
     return install({ ...options, environment, platform, dependencies, managedRoot });
 }
@@ -114,6 +132,7 @@ async function install(options) {
         const validated = await validateManaged(temporary, options.platform, options.dependencies);
         if (!validated)
             throw new Error(`validation failed after installing ${OPENCODE_PACKAGE}`);
+        options.signal?.throwIfAborted();
         await rename(temporary, options.managedRoot);
         temporary = null;
         const activated = await validateManaged(options.managedRoot, options.platform, options.dependencies);
@@ -122,6 +141,7 @@ async function install(options) {
         return activated;
     }
     catch (error) {
+        options.signal?.throwIfAborted();
         const concurrent = await validateManaged(options.managedRoot, options.platform, options.dependencies);
         if (concurrent)
             return concurrent;

package/dist/runtime-manager.js

@@ -9,6 +9,10 @@ import { findAvailablePort } from "./port.js";
 import { ProcessSupervisor } from "./process-supervisor.js";
 import { configureCodexSharing } from "./codex-sharing.js";
 import { withCliProgress } from "../bin/cli-progress.mjs";
+import { withAbortSignal, withTimeout } from "./abort.js";
+export const CODEX_PREPARATION_TIMEOUT_MS = 180_000;
+const OPTIONAL_RUNTIME_CHECK_TIMEOUT_MS = 60_000;
+const CODEX_SHARING_TIMEOUT_MS = 10_000;
 export class RuntimeManager {
     supervisor;
     codexResolver;
@@ -24,16 +28,15 @@ export class RuntimeManager {
         const port = await findAvailablePort(options.port);
         const dataDir = resolve(options.dataDir);
         await Promise.all(["data", "bin", "cache", "logs"].map((name) => mkdir(resolve(dataDir, name), { recursive: true })));
-        const codexEnvironment = await withCliProgress("正在准备 Codex 组件", () => prepareCodexRuntimeEnvironment(process.env, { dataDir, target }, this.codexResolver, this.report));
-        if (process.platform === "darwin" && codexEnvironment.AGENT_CODEX_BIN) {
+        const childEnvironment = await withCliProgress("正在检查 Agent 组件；缺少 Codex 时自动安装最新版，最多等待 180 秒", () => prepareAgentRuntimeEnvironment(process.env, { dataDir, target }, this.codexResolver, this.report, this.opencodeResolver));
+        if (process.platform === "darwin" && childEnvironment.AGENT_CODEX_BIN) {
             try {
-                await configureCodexSharing(options, { environment: codexEnvironment });
+                await withTimeout(signal => configureCodexSharing(options, { environment: childEnvironment, signal }), CODEX_SHARING_TIMEOUT_MS, "Codex 共享后台配置超时（10 秒）");
             }
             catch (error) {
                 this.report(`Codex 共享启动配置未完成，可在电脑菜单中修复：${error instanceof Error ? error.message : error}`);
             }
         }
-        const childEnvironment = await withCliProgress("正在准备 OpenCode 组件", () => prepareOpenCodeRuntimeEnvironment(codexEnvironment, { dataDir, target }, this.opencodeResolver, this.report));
         const { runtimeRoot } = resolvePlatformRuntime(target);
         await repairNativeRuntimePermissions(runtimeRoot);
         const gateway = resolve(runtimeRoot, "ws-server.mjs");
@@ -44,7 +47,7 @@ export class RuntimeManager {
                 NODE_ENV: "production",
                 NEXT_DIST_DIR: ".next",
                 PORT: String(port),
-                HOST: options.localOnly ? "0.0.0.0" : "127.0.0.1",
+                HOST: "0.0.0.0",
                 AGENT_DATA_DIR: resolve(dataDir, "data"),
                 // 应用日志收口到 <dataDir>/logs,与 launchd 的 service.stdout/stderr.log
                 // 及 CLI 自身的错误日志同一个目录,用户排障时只需打包这一处。
@@ -63,7 +66,14 @@ export class RuntimeManager {
             child.once("exit", (code, signal) => resolveExit({ code, signal }));
         });
         const localUrl = `http://127.0.0.1:${port}`;
-        const status = await withCliProgress("正在等待本机服务就绪", () => waitForHealth(`${localUrl}/api/web-auth/status`, child, 20_000));
+        let status;
+        try {
+            status = await withCliProgress("正在等待本机服务就绪", () => waitForHealth(`${localUrl}/api/web-auth/status`, child, 20_000));
+        }
+        catch (error) {
+            await this.supervisor.stopAll();
+            throw error;
+        }
         return {
             port,
             localUrl,
@@ -75,15 +85,29 @@ export class RuntimeManager {
         };
     }
 }
+export async function prepareAgentRuntimeEnvironment(environment, options, codexResolver = resolveCodexRuntime, report = (message) => process.stderr.write(`${message}\n`), opencodeResolver = resolveOpenCodeRuntime) {
+    const [codex, opencode] = await Promise.all([
+        prepareCodexRuntimeEnvironment(environment, options, codexResolver, report),
+        prepareOpenCodeRuntimeEnvironment(environment, options, opencodeResolver, report),
+    ]);
+    return {
+        ...codex,
+        AGENT_OPENCODE_BIN: opencode.AGENT_OPENCODE_BIN,
+        AGENT_OPENCODE_RUNTIME_ERROR: opencode.AGENT_OPENCODE_RUNTIME_ERROR,
+    };
+}
 export async function prepareCodexRuntimeEnvironment(environment, options, resolver = resolveCodexRuntime, report = (message) => process.stderr.write(`${message}\n`)) {
     const childEnvironment = { ...environment };
+    const timeoutMs = options.timeoutMs ?? CODEX_PREPARATION_TIMEOUT_MS;
     report(`Checking Codex ${options.target} runtime...`);
     try {
-        const resolution = await resolver({
-            ...options,
+        const resolution = await withTimeout(signal => resolver({
+            dataDir: options.dataDir,
+            target: options.target,
+            signal,
             environment,
             onProgress: report,
-        });
+        }), timeoutMs, `Codex 组件准备超时（${timeoutMs / 1000} 秒）；请检查网络后运行 agentroam doctor 重试。`);
         childEnvironment.AGENT_CODEX_BIN = resolution.executable;
         delete childEnvironment.AGENT_CODEX_RUNTIME_ERROR;
         report(`Codex ${resolution.version} (${resolution.source}): ${resolution.executable}`);
@@ -92,7 +116,7 @@ export async function prepareCodexRuntimeEnvironment(environment, options, resol
         delete childEnvironment.AGENT_CODEX_BIN;
         const message = error instanceof Error ? error.message : String(error);
         childEnvironment.AGENT_CODEX_RUNTIME_ERROR = message;
-        report(`Codex unavailable; AgentRoam will continue without Codex sessions: ${message}`);
+        report(`⚠ Codex 会话功能未就绪，局域网服务将继续启动；运行 agentroam doctor 修复后重启服务：${message}`);
     }
     return childEnvironment;
 }
@@ -100,7 +124,9 @@ export async function prepareOpenCodeRuntimeEnvironment(environment, options, re
     const childEnvironment = { ...environment };
     report(`Checking OpenCode ${options.target} runtime...`);
     try {
-        const resolution = await resolver({ ...options, environment, onProgress: report });
+        const resolution = await withTimeout(signal => resolver({
+            dataDir: options.dataDir, target: options.target, environment, signal, installIfMissing: false, onProgress: report,
+        }), options.timeoutMs ?? OPTIONAL_RUNTIME_CHECK_TIMEOUT_MS, "OpenCode 组件检查超时；已跳过，不下载安装。");
         childEnvironment.AGENT_OPENCODE_BIN = resolution.executable;
         delete childEnvironment.AGENT_OPENCODE_RUNTIME_ERROR;
         report(`OpenCode ${resolution.version} (${resolution.source}): ${resolution.executable}`);
@@ -109,22 +135,33 @@ export async function prepareOpenCodeRuntimeEnvironment(environment, options, re
         delete childEnvironment.AGENT_OPENCODE_BIN;
         const message = error instanceof Error ? error.message : String(error);
         childEnvironment.AGENT_OPENCODE_RUNTIME_ERROR = message;
-        report(`OpenCode unavailable; AgentRoam will continue without OpenCode sessions: ${message}`);
+        report(`OpenCode 不可用，已跳过（不自动安装）：${message}`);
     }
     return childEnvironment;
 }
 async function waitForHealth(url, child, timeoutMs) {
     const end = Date.now() + timeoutMs;
-    while (Date.now() < end) {
-        if (child.exitCode !== null)
-            throw new Error(`local server exited with ${child.exitCode}`);
-        try {
-            const response = await fetch(url);
-            if (response.ok)
-                return response.json();
-        }
-        catch { }
-        await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("local server health check timed out")), timeoutMs);
+    try {
+        return await withAbortSignal(async () => {
+            while (Date.now() < end) {
+                controller.signal.throwIfAborted();
+                if (child.exitCode !== null)
+                    throw new Error(`local server exited with ${child.exitCode}`);
+                try {
+                    const response = await fetch(url, { signal: controller.signal });
+                    if (response.ok)
+                        return response.json();
+                    void response.body?.cancel().catch(() => { });
+                }
+                catch { }
+                await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+            }
+            throw new Error("local server health check timed out");
+        }, controller.signal);
+    }
+    finally {
+        clearTimeout(timer);
     }
-    throw new Error("local server health check timed out");
 }

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

@@ -19,7 +19,8 @@ export class MacLaunchAgent {
         this.runner = options.runner ?? runCommand;
         this.processExists = options.processExists ?? isProcessRunning;
         this.now = options.now ?? (() => new Date());
-        this.readyTimeoutMs = options.readyTimeoutMs ?? 120_000;
+        // Codex preparation (180s), sharing (10s), local server (20s), relay (30s), plus cleanup.
+        this.readyTimeoutMs = options.readyTimeoutMs ?? 270_000;
         this.stopTimeoutMs = options.stopTimeoutMs ?? 15_000;
         this.pollIntervalMs = options.pollIntervalMs ?? 250;
     }

package/dist/service/service-command.js

@@ -12,6 +12,7 @@ import { configureCodexSharing } from "../codex-sharing.js";
 import { setupCodexDesktop } from "../codex-desktop-setup.js";
 import { authorizeRemoteDesktop } from "../desktop-authorization.js";
 import { withCliProgress } from "../../bin/cli-progress.mjs";
+import { withTimeout } from "../abort.js";
 export async function runServiceCommand(options, context) {
     const platform = context.platform ?? process.platform;
     const log = context.log ?? console.log;
@@ -33,18 +34,20 @@ export async function runServiceCommand(options, context) {
             const environmentPath = buildServiceEnvironmentPath(context.nodePath, environment.PATH ?? environment.Path, platform);
             let codexPath;
             try {
-                const codex = await withCliProgress("正在检查和安装 Codex 组件", () => (context.codexResolver ?? resolveCodexRuntime)({
+                const codex = await withCliProgress("正在检查已有 Codex；缺失时由后台服务限时安装最新版", () => withTimeout(signal => (context.codexResolver ?? resolveCodexRuntime)({
                     dataDir: options.dataDir,
                     target: detectPlatform(platform, context.arch ?? process.arch, nodeVersion),
                     environment: { ...environment, PATH: environmentPath },
                     platform,
                     nodeExecutable: context.nodePath,
+                    installIfMissing: false,
+                    signal,
                     onProgress: (message) => log(`… ${message}`),
-                }));
+                }), 60_000, "检查已有 Codex 超时；后台服务将继续检查。"));
                 codexPath = codex.executable;
             }
             catch (error) {
-                log(`⚠ Codex runtime was not pinned during service install: ${error instanceof Error ? error.message : error}`);
+                log(`Codex 将在后台服务启动时检查并限时补齐：${error instanceof Error ? error.message : error}`);
             }
             const config = {
                 version: context.version,
@@ -63,17 +66,20 @@ export async function runServiceCommand(options, context) {
             };
             if (platform === "darwin" && codexPath) {
                 try {
-                    await (context.configureSharing ?? configureCodexSharing)(options, { homeDir: context.homeDir, environment: { ...environment, PATH: environmentPath, AGENT_CODEX_BIN: codexPath } });
+                    await withTimeout(signal => (context.configureSharing ?? configureCodexSharing)(options, {
+                        homeDir: context.homeDir, environment: { ...environment, PATH: environmentPath, AGENT_CODEX_BIN: codexPath }, signal,
+                    }), 10_000, "Codex 默认共享配置超时（10 秒）");
                 }
                 catch (error) {
                     log(`Codex 默认共享配置未完成，可在电脑菜单中修复：${error instanceof Error ? error.message : error}`);
                 }
             }
-            const { definition, state } = await withCliProgress("正在安装后台服务，等待服务和手机访问连接就绪", () => controller.install(config));
+            const { definition, state } = await withCliProgress("正在启动后台服务；Codex 准备最多 180 秒，公网连接最多等待 30 秒，失败后使用局域网", () => controller.install(config));
             log(`✓ AgentRoam service installed: ${definition}`);
             if (state?.localUrl && state.status !== "stopped")
                 printLocalDesktopUrl(state.localUrl, log, platform);
             requireReadyService(state);
+            printLanFallback(state, log);
             if (state?.localUrl && state.status !== "stopped" && (platform === "darwin" || platform === "win32")) {
                 if (environment.AGENTROAM_INSTALL_REMOTE_DESKTOP === "skip") {
                     log("已跳过安装时远程桌面授权，可稍后执行 agentroam desktop authorize。");
@@ -100,10 +106,11 @@ export async function runServiceCommand(options, context) {
             return;
         }
         case "start": {
-            const state = await withCliProgress("正在启动后台服务，等待服务和手机访问连接就绪", () => controller.start());
+            const state = await withCliProgress("正在启动后台服务；Codex 准备最多 180 秒，公网连接最多等待 30 秒，失败后使用局域网", () => controller.start());
             if (state?.localUrl && state.status !== "stopped")
                 printLocalDesktopUrl(state.localUrl, log, platform);
             requireReadyService(state);
+            printLanFallback(state, log);
             log("✓ AgentRoam service started");
             await logAccessUrl(state.accessUrl);
             return;
@@ -126,6 +133,7 @@ export async function runServiceCommand(options, context) {
             if (status.running && status.state?.localUrl)
                 printLocalDesktopUrl(status.state.localUrl, log, platform);
             if (status.running && status.state?.status === "ready" && status.state.accessUrl) {
+                printLanFallback(status.state, log);
                 await logAccessUrl(status.state.accessUrl);
             }
             return;
@@ -144,10 +152,11 @@ export async function runServiceCommand(options, context) {
             return;
         }
         case "restart": {
-            const state = await withCliProgress("正在重启后台服务，等待服务和手机访问连接就绪", () => controller.restart());
+            const state = await withCliProgress("正在重启后台服务；Codex 准备最多 180 秒，公网连接最多等待 30 秒，失败后使用局域网", () => controller.restart());
             if (state?.localUrl && state.status !== "stopped")
                 printLocalDesktopUrl(state.localUrl, log, platform);
             requireReadyService(state);
+            printLanFallback(state, log);
             log("✓ AgentRoam service restarted");
             await logAccessUrl(state.accessUrl);
             return;
@@ -162,6 +171,15 @@ export async function runServiceCommand(options, context) {
             throw cliError("service action is required");
     }
 }
+function printLanFallback(state, log) {
+    if (state.provider !== "lan")
+        return;
+    if (state.accessUrl && ["127.0.0.1", "localhost", "[::1]"].includes(new URL(state.accessUrl).hostname)) {
+        log("✓ 本机服务已启动；当前没有局域网地址，连接 Wi-Fi 或有线网络后重启服务即可生成手机访问地址。");
+        return;
+    }
+    log("✓ 后台服务已通过局域网启动；手机与电脑连接同一局域网后扫码连接。");
+}
 function requireReadyService(state) {
     if (state?.status !== "ready" || !state.accessUrl) {
         throw Object.assign(new Error(`AgentRoam 后台服务未就绪（${state?.status ?? "未取得状态"}）。请运行 agentroam service logs 查看原因，修复后运行 agentroam service start，再执行 agentroam pair。`), { exitCode: 1 });

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

@@ -17,7 +17,8 @@ export class WindowsTaskService {
         this.runner = options.runner ?? runCommand;
         this.processExists = options.processExists ?? isProcessRunning;
         this.now = options.now ?? (() => new Date());
-        this.readyTimeoutMs = options.readyTimeoutMs ?? 120_000;
+        // Leave room for bounded component preparation, local readiness and relay fallback.
+        this.readyTimeoutMs = options.readyTimeoutMs ?? 270_000;
         this.stopTimeoutMs = options.stopTimeoutMs ?? 15_000;
         this.pollIntervalMs = options.pollIntervalMs ?? 250;
         this.validate = options.validateConfig ?? validateWindowsConfig;
@@ -219,7 +220,7 @@ $user = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
 $action = New-ScheduledTaskAction -Execute ${powerShellLiteral(config.nodePath)} -Argument ${powerShellLiteral(argumentsValue)} -WorkingDirectory ${powerShellLiteral(config.roots[0])}
 $trigger = New-ScheduledTaskTrigger -AtLogOn -User $user
 $principal = New-ScheduledTaskPrincipal -UserId $user -LogonType Interactive -RunLevel Limited
-$settings = New-ScheduledTaskSettingsSet -MultipleInstances IgnoreNew -RestartCount 999 -RestartInterval (New-TimeSpan -Seconds 5) -ExecutionTimeLimit ([TimeSpan]::Zero) -StartWhenAvailable -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
+$settings = New-ScheduledTaskSettingsSet -MultipleInstances IgnoreNew -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit ([TimeSpan]::Zero) -StartWhenAvailable -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
 Register-ScheduledTask -TaskName ${powerShellLiteral(WINDOWS_SERVICE_NAME)} -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null
 `;
 }

package/dist/tunnel/public-readiness.js

@@ -1,64 +1,83 @@
 import { fetch as undiciFetch, ProxyAgent } from "undici";
 import { resolveProxyForUrl } from "./proxy-settings.js";
 import { AGENTROAM_VERSION } from "../platform-packages.js";
+import { withAbortSignal } from "../abort.js";
 export async function waitForPublicReadiness(publicUrl, options = {}) {
     const timeoutMs = options.timeoutMs ?? 30_000;
     const intervalMs = options.intervalMs ?? 750;
     const endpoint = new URL("/api/web-auth/status", `${publicUrl.replace(/\/$/, "")}/`);
-    let proxyFetch = null;
+    const deadline = Date.now() + timeoutMs;
+    const controller = new AbortController();
+    let lastFailure = "no response";
+    const timer = setTimeout(() => {
+        const detail = lastFailure === "no response" ? "request timed out" : `${lastFailure} (request timed out)`;
+        controller.abort(new Error(`public tunnel not ready: ${detail}`));
+    }, timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+    const connection = { proxy: null };
     let fetchImpl = options.fetchImpl;
-    if (!fetchImpl) {
-        const proxyResolver = options.proxyResolver ?? resolveProxyForUrl;
-        const proxyUrl = await proxyResolver(endpoint).catch(() => null);
-        if (proxyUrl)
-            proxyFetch = (options.proxyFetchFactory ?? createProxyFetch)(proxyUrl);
-        fetchImpl = proxyFetch?.fetch ?? fetch;
-    }
     try {
-        const deadline = Date.now() + timeoutMs;
-        let lastFailure = "no response";
-        while (Date.now() <= deadline) {
-            if (options.signal?.aborted)
-                throw new Error("public tunnel readiness aborted");
-            try {
-                const response = await fetchImpl(endpoint, {
-                    cache: "no-store",
-                    headers: { "user-agent": `agentroam-readiness/${AGENTROAM_VERSION}` },
-                    signal: options.signal,
-                });
-                if (response.ok) {
-                    let body;
-                    try {
-                        body = (await response.json());
-                    }
-                    catch {
+        await withAbortSignal(async () => {
+            if (!fetchImpl) {
+                const proxyResolver = options.proxyResolver ?? resolveProxyForUrl;
+                const proxyUrl = await proxyResolver(endpoint).catch(() => null);
+                signal.throwIfAborted();
+                if (proxyUrl)
+                    connection.proxy = (options.proxyFetchFactory ?? createProxyFetch)(proxyUrl);
+                fetchImpl = connection.proxy?.fetch ?? fetch;
+            }
+            while (Date.now() <= deadline) {
+                signal.throwIfAborted();
+                try {
+                    const response = await fetchImpl(endpoint, {
+                        cache: "no-store",
+                        headers: { "user-agent": `agentroam-readiness/${AGENTROAM_VERSION}` },
+                        signal,
+                    });
+                    if (response.ok) {
+                        let body;
+                        try {
+                            body = (await response.json());
+                        }
+                        catch {
+                            throw new FatalReadinessError("HTTP 200 with invalid auth status JSON");
+                        }
+                        signal.throwIfAborted();
+                        if (typeof body.authenticated === "boolean" && typeof body.needsSetup === "boolean")
+                            return;
                         throw new FatalReadinessError("HTTP 200 with invalid auth status JSON");
                     }
-                    if (typeof body.authenticated === "boolean" && typeof body.needsSetup === "boolean")
-                        return;
-                    throw new FatalReadinessError("HTTP 200 with invalid auth status JSON");
+                    else {
+                        lastFailure = `HTTP ${response.status}`;
+                        void response.body?.cancel().catch(() => { });
+                        if (![404, 502, 503, 530].includes(response.status))
+                            throw new FatalReadinessError(lastFailure);
+                    }
                 }
-                else {
-                    lastFailure = `HTTP ${response.status}`;
-                    if (![404, 502, 503, 530].includes(response.status))
-                        throw new FatalReadinessError(lastFailure);
+                catch (error) {
+                    if (options.signal?.aborted)
+                        throw new Error("public tunnel readiness aborted");
+                    signal.throwIfAborted();
+                    if (error instanceof FatalReadinessError)
+                        throw new Error(`public tunnel not ready: ${error.message}`);
+                    lastFailure = error instanceof Error ? error.message : String(error);
                 }
+                if (Date.now() + intervalMs > deadline)
+                    break;
+                await delay(intervalMs, signal);
             }
-            catch (error) {
-                if (options.signal?.aborted)
-                    throw new Error("public tunnel readiness aborted");
-                if (error instanceof FatalReadinessError)
-                    throw new Error(`public tunnel not ready: ${error.message}`);
-                lastFailure = error instanceof Error ? error.message : String(error);
-            }
-            if (Date.now() + intervalMs > deadline)
-                break;
-            await delay(intervalMs, options.signal);
-        }
-        throw new Error(`public tunnel not ready: ${lastFailure}`);
+            throw new Error(`public tunnel not ready: ${lastFailure}`);
+        }, signal);
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw new Error("public tunnel readiness aborted");
+        throw error;
     }
     finally {
-        await proxyFetch?.close().catch(() => { });
+        clearTimeout(timer);
+        if (connection.proxy)
+            await withAbortSignal(() => connection.proxy.close(), AbortSignal.timeout(3_000)).catch(() => { });
     }
 }
 class FatalReadinessError extends Error {
@@ -68,16 +87,22 @@ function createProxyFetch(proxyUrl) {
     return {
         fetch: async (input, init) => (await undiciFetch(input, { ...init, dispatcher })),
         close: async () => {
-            await dispatcher.close();
+            await dispatcher.destroy();
         },
     };
 }
 function delay(milliseconds, signal) {
     return new Promise((resolvePromise, reject) => {
-        const timer = setTimeout(resolvePromise, milliseconds);
-        signal?.addEventListener("abort", () => {
+        const abort = () => {
             clearTimeout(timer);
-            reject(new Error("public tunnel readiness aborted"));
-        }, { once: true });
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolvePromise();
+        }, milliseconds);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
     });
 }

package/dist/tunnel/relay-orchestrator.js

@@ -3,33 +3,49 @@ import { CloudflareTunnelProvider } from "./cloudflare-provider.js";
 import { CustomCommandTunnelProvider } from "./custom-command-provider.js";
 import { PinggyTunnelProvider } from "./pinggy-provider.js";
 import { waitForPublicReadiness } from "./public-readiness.js";
+import { withAbortSignal } from "../abort.js";
+export const RELAY_START_TIMEOUT_MS = 30_000;
 export async function selectRelay(options) {
+    options.signal.throwIfAborted();
     if (options.cli.localOnly)
         return { tunnel: null, publicUrl: options.lanUrl, provider: "lan", failures: [] };
-    const providers = options.cli.relay === "auto" ? ["cloudflare", "pinggy"] : [options.cli.relay];
+    const providers = options.cli.relay === "auto" ? ["cloudflare"] : [options.cli.relay];
     const failures = [];
     const readiness = options.readiness ?? waitForPublicReadiness;
     for (const providerName of providers) {
         options.onAttempt?.(providerName);
-        let tunnel = null;
+        const attempt = { tunnel: null };
+        const deadline = new AbortController();
+        const timeoutMs = options.timeoutMs ?? RELAY_START_TIMEOUT_MS;
+        const timer = setTimeout(() => deadline.abort(new Error(`relay connection timed out after ${timeoutMs}ms`)), timeoutMs);
+        const signal = AbortSignal.any([options.signal, deadline.signal]);
         try {
-            const provider = await createProvider(providerName, options);
-            tunnel = await provider.start({ localUrl: options.localUrl, signal: options.signal, log: options.log });
-            await readiness(tunnel.publicUrl, { signal: options.signal });
-            return { tunnel, publicUrl: tunnel.publicUrl, provider: providerName, failures };
+            return await withAbortSignal(async () => {
+                const provider = await createProvider(providerName, options);
+                signal.throwIfAborted();
+                const handle = await provider.start({ localUrl: options.localUrl, signal, log: options.log });
+                if (signal.aborted) {
+                    void handle.close().catch(() => { });
+                    signal.throwIfAborted();
+                }
+                attempt.tunnel = handle;
+                await readiness(handle.publicUrl, { signal });
+                signal.throwIfAborted();
+                return { tunnel: handle, publicUrl: handle.publicUrl, provider: providerName, failures };
+            }, signal);
         }
         catch (error) {
-            await tunnel?.close().catch(() => { });
+            deadline.abort(error);
+            if (attempt.tunnel)
+                await withAbortSignal(() => attempt.tunnel.close(), AbortSignal.timeout(3_000)).catch(() => { });
+            options.signal.throwIfAborted();
             const message = error instanceof Error ? error.message : String(error);
             failures.push({ provider: providerName, message });
             options.onFailure?.(providerName, message);
-            if (options.signal.aborted)
-                break;
         }
-    }
-    if (options.allowLanFallback === false) {
-        const detail = failures.map(({ provider, message }) => `${provider}: ${message}`).join("; ");
-        throw new Error(`public relay unavailable${detail ? ` (${detail})` : ""}`);
+        finally {
+            clearTimeout(timer);
+        }
     }
     return { tunnel: null, publicUrl: options.lanUrl, provider: "lan", failures };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentroam",
-  "version": "0.2.0-preview.48",
+  "version": "0.2.0-preview.53",
   "description": "Zero-install mobile remote terminal and file console",
   "type": "module",
   "bin": {
@@ -27,12 +27,12 @@
     "ws": "^8.21.3"
   },
   "optionalDependencies": {
-    "agentroam-runtime-darwin-arm64": "0.2.0-preview.48",
-    "agentroam-runtime-win32-x64": "0.2.0-preview.48",
-    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.39",
-    "agentroam-cloudflared-win32-x64": "0.2.0-preview.39",
-    "agentroam-tui-darwin-arm64": "0.2.0-preview.47",
-    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.47"
+    "agentroam-runtime-darwin-arm64": "0.2.0-preview.53",
+    "agentroam-runtime-win32-x64": "0.2.0-preview.53",
+    "agentroam-cloudflared-darwin-arm64": "0.2.0-preview.53",
+    "agentroam-cloudflared-win32-x64": "0.2.0-preview.53",
+    "agentroam-tui-darwin-arm64": "0.2.0-preview.53",
+    "@caoqu/agentroam-tui-win32-x64": "0.2.0-preview.53"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",