agentroam 0.2.0-preview.35 → 0.2.0-preview.37

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", "unlock-service", "update", "update-worker", "pair", "devices", "revoke", "approvals", "approve", "deny", "lock", "unlock", "audit"].includes(values[0])) {
+    if (values[0] && ["start", "doctor", "version", "service", "unlock-service", "update", "update-worker", "pair", "devices", "revoke", "approvals", "approve", "deny", "lock", "unlock", "audit", "codex-desktop"].includes(values[0])) {
         command = values.shift();
     }
     let serviceAction = null;
@@ -70,13 +70,24 @@ export function parseArgs(argv) {
     };
     for (let index = 0; index < values.length && command !== "update-worker"; index++) {
         const arg = values[index];
+        if (command === "codex-desktop" && !["--restart", "--dry-run", "--setup", "--data-dir", "--help", "-h"].includes(arg)) {
+            throw cliError("codex-desktop accepts only --setup, --restart, --dry-run and --data-dir");
+        }
         const next = () => {
             const value = values[++index];
             if (!value)
                 throw cliError(`missing value for ${arg}`);
             return value;
         };
-        if (arg === "--url" && command === "pair")
+        if (arg === "--restart" && command === "codex-desktop")
+            options.desktopRestart = true;
+        else if (arg === "--dry-run" && command === "codex-desktop")
+            options.desktopDryRun = true;
+        else if (arg === "--setup" && command === "codex-desktop")
+            options.desktopSetup = true;
+        else if (arg === "--setup-codex-desktop" && command === "service" && serviceAction === "install")
+            options.desktopSetup = true;
+        else if (arg === "--url" && command === "pair")
             options.pairingUrl = next();
         else if (arg === "--root")
             options.roots.push(resolve(next()));
@@ -112,6 +123,9 @@ export function parseArgs(argv) {
     }
     if (command === "approve" && !options.approvalPhrase)
         throw cliError("approve requires --phrase matching the phone");
+    if (command === "codex-desktop" && options.desktopSetup && (options.desktopRestart || options.desktopDryRun)) {
+        throw cliError("--setup cannot be combined with --restart or --dry-run");
+    }
     if (command === "update" && updateVersion && !/^\d+\.\d+\.\d+$/.test(updateVersion)) {
         throw cliError("update version must be an exact stable X.Y.Z version");
     }

package/dist/cli.js

@@ -21,6 +21,8 @@ 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";
+import { runCodexDesktopCommand } from "./codex-desktop-command.js";
+import { setupCodexDesktop } from "./codex-desktop-setup.js";
 const VERSION = AGENTROAM_VERSION;
 export async function main(argv) {
     if (argv.includes("--help") || argv.includes("-h")) {
@@ -39,6 +41,10 @@ export async function main(argv) {
   agentroam revoke --all            全部退出并取消待用配对码
   agentroam service install|start|stop|restart|status|url|logs|uninstall
   agentroam unlock-service install|uninstall|status  管理 Windows 远程解锁服务（安装时弹出 UAC）
+  agentroam codex-desktop [--dry-run]  通过共享后端启动官方 Codex 桌面端（macOS）
+  agentroam codex-desktop --restart   退出并重新连接官方桌面端，会中断它的全部运行会话
+  agentroam codex-desktop --setup     空闲桌面自动重新连接；有任务或状态未知时询问是否重启
+  agentroam service install --setup-codex-desktop  扫码前配置官方桌面共享连接（macOS）
 设备命令支持 --data-dir PATH；配对码有效期 5 分钟，设备授权有效期 30 天。`);
         return;
     }
@@ -92,6 +98,15 @@ export async function main(argv) {
         return;
     }
     const target = detectPlatform();
+    if (options.command === "codex-desktop") {
+        if (!argv.includes("--data-dir"))
+            options.dataDir = await installedDataDir(options.dataDir);
+        if (options.desktopSetup)
+            await setupCodexDesktop(options);
+        else
+            await runCodexDesktopCommand(options);
+        return;
+    }
     if (options.command === "unlock-service") {
         if (target !== "windows-amd64")
             throw new Error("远程解锁服务仅支持 Windows 10/11 x64");

package/dist/codex-desktop-command.js

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { resolveCodexRuntime } from "./codex-runtime-manager.js";
+import { readServiceConfig, resolveServicePaths } from "./service/service-files.js";
+import { detectPlatform } from "./platform.js";
+const execFileAsync = promisify(execFile);
+const scriptPath = fileURLToPath(new URL("../install/start-codex-desktop-shared.sh", import.meta.url));
+export async function runCodexDesktopCommand(options, context = {}) {
+    const platform = context.platform ?? process.platform;
+    if (platform !== "darwin")
+        throw new Error("官方 Codex 桌面共享后端入口目前仅支持 macOS");
+    const log = context.log ?? console.log;
+    const environment = { ...(context.environment ?? process.env) };
+    const service = await (context.readConfig ?? (() => readServiceConfig(resolveServicePaths())))();
+    if (service?.dataDir === options.dataDir) {
+        if (!environment.AGENT_CODEX_BIN && service.codexPath)
+            environment.AGENT_CODEX_BIN = service.codexPath;
+        if (!environment.CODEX_HOME && service.codexHome)
+            environment.CODEX_HOME = service.codexHome;
+    }
+    // A dry run reads the installed configuration and never installs a runtime.
+    if (!options.desktopDryRun) {
+        const codex = await (context.codexResolver ?? resolveCodexRuntime)({
+            dataDir: options.dataDir,
+            target: detectPlatform(platform, process.arch, process.versions.node),
+            environment: { ...environment },
+            platform,
+            nodeExecutable: process.execPath,
+            onProgress: (message) => log(`… ${message}`),
+        });
+        environment.AGENT_CODEX_BIN = codex.executable;
+    }
+    const args = [scriptPath];
+    if (!options.desktopDryRun) {
+        environment.AGENTROAM_CODEX_DESKTOP_PREFLIGHT_NODE = process.execPath;
+        environment.AGENTROAM_CODEX_DESKTOP_PREFLIGHT = fileURLToPath(new URL("./codex-desktop-preflight.js", import.meta.url));
+    }
+    if (options.desktopRestart)
+        args.push("--restart");
+    if (options.desktopDryRun)
+        args.push("--dry-run");
+    try {
+        const { stdout, stderr } = await (context.execute ?? execFileAsync)("/bin/bash", args, {
+            env: environment, encoding: "utf8", timeout: 60_000, maxBuffer: 1024 * 1024,
+        });
+        if (stdout.trim())
+            log(stdout.trimEnd());
+        if (stderr.trim())
+            log(stderr.trimEnd());
+    }
+    catch (error) {
+        const detail = error;
+        throw new Error(detail.stderr?.trim() || detail.message, { cause: error });
+    }
+}

package/dist/codex-desktop-idle-guard.js

@@ -0,0 +1,15 @@
+import { inspectCodexDesktop } from "./codex-desktop-status.js";
+// Invoked only by the packaged launcher, after daemon preflight and immediately
+// before graceful quit. Runtime installation may have taken minutes since setup.
+try {
+    const snapshot = await inspectCodexDesktop(process.env);
+    if (snapshot.status !== "running" || String(snapshot.pid) !== process.env.AGENTROAM_CODEX_DESKTOP_EXPECTED_PID
+        || snapshot.activity.state !== "idle") {
+        console.error("Desktop is no longer confirmed idle; no automatic restart attempted. Run agentroam codex-desktop --setup to choose again.");
+        process.exitCode = 1;
+    }
+}
+catch {
+    console.error("Desktop idle check failed; no automatic restart attempted.");
+    process.exitCode = 1;
+}

package/dist/codex-desktop-preflight.js

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+import { DesktopProbeRpcError, readDesktopActivity, withDesktopRpc } from "./codex-desktop-probe.js";
+const execFileAsync = promisify(execFile);
+async function inspectBackend(endpoint) {
+    return withDesktopRpc(endpoint, async (request, becameActive) => {
+        try {
+            await request("config/read", {});
+            try {
+                await request("account/gatewayOAuth/read", {});
+            }
+            catch (error) {
+                // Older servers may not have the Desktop gateway RPC.
+                if (!(error instanceof DesktopProbeRpcError && error.code === -32601))
+                    throw error;
+            }
+            return true;
+        }
+        catch (error) {
+            if (!(error instanceof DesktopProbeRpcError) || !/No such file or directory|os error 2/.test(error.message))
+                throw error;
+            const activity = await readDesktopActivity(request);
+            if (activity.state !== "idle" || becameActive())
+                throw new Error("共享后端配置失效，但任务忙碌或状态无法确认；已保留桌面和共享后端");
+            return false;
+        }
+    });
+}
+/** Repair only a missing-directory backend after two complete idle snapshots. */
+export async function preflightCodexDesktop(endpoint, executable, context = {}) {
+    if (await inspectBackend(endpoint))
+        return;
+    if (await inspectBackend(endpoint))
+        return;
+    (context.log ?? console.log)("共享后端的工作目录已失效，已确认全部任务空闲，正在从稳定目录重建…");
+    await (context.restart ?? (async () => {
+        await execFileAsync(executable, ["app-server", "daemon", "restart"], {
+            cwd: homedir(), env: process.env, timeout: 15_000, maxBuffer: 1024 * 1024,
+        });
+    }))();
+    if (!await inspectBackend(endpoint))
+        throw new Error("共享后端重建后仍无法读取配置；已保留桌面");
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const [endpoint, executable] = process.argv.slice(2);
+    if (!endpoint || !executable) {
+        console.error("Missing shared backend endpoint or Codex executable");
+        process.exitCode = 1;
+    }
+    else
+        preflightCodexDesktop(endpoint, executable).catch(error => {
+            console.error(`共享后端检查失败：${error instanceof Error ? error.message : error}`);
+            process.exitCode = 1;
+        });
+}

package/dist/codex-desktop-probe.js

@@ -0,0 +1,147 @@
+import { Agent, WebSocket } from "undici";
+export class DesktopProbeRpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Read live state only. Never resume, subscribe, interrupt or unload a thread. */
+export async function probeDesktopActivity(endpoint, timeoutMs = 5_000) {
+    try {
+        return await withDesktopRpc(endpoint, async (request, becameActive) => {
+            const activity = await readDesktopActivity(request);
+            return becameActive() && activity.state === "idle" ? { state: "busy", activeCount: 1 } : activity;
+        }, timeoutMs);
+    }
+    catch {
+        return { state: "unknown", reason: "无法完整查询桌面端的实时任务状态" };
+    }
+}
+export async function withDesktopRpc(endpoint, operation, timeoutMs = 5_000) {
+    let dispatcher;
+    let socket;
+    let timer;
+    let rejectPending;
+    try {
+        const address = new URL(endpoint);
+        let url = endpoint;
+        if (address.protocol === "ws+unix:") {
+            const separator = address.pathname.indexOf(":");
+            if (address.hostname !== "localhost" || separator < 1)
+                throw new Error("invalid local socket");
+            dispatcher = new Agent({ connect: { socketPath: decodeURIComponent(address.pathname.slice(0, separator)) } });
+            url = `ws://localhost${address.pathname.slice(separator + 1)}`;
+        }
+        else if (!(["ws:", "wss:"].includes(address.protocol)
+            && ["127.0.0.1", "localhost", "[::1]"].includes(address.hostname))) {
+            throw new Error("not a local Desktop endpoint");
+        }
+        if (address.username || address.password || address.search || address.hash)
+            throw new Error("invalid endpoint");
+        socket = new WebSocket(url, dispatcher ? { dispatcher } : undefined);
+        const connection = socket;
+        let nextId = 0;
+        let changedToActive = false;
+        const pending = new Map();
+        const fail = () => {
+            for (const item of pending.values())
+                item.reject(new Error("Desktop probe disconnected"));
+            pending.clear();
+        };
+        rejectPending = fail;
+        const opened = new Promise((resolve, reject) => {
+            connection.addEventListener("open", () => resolve(), { once: true });
+            connection.addEventListener("error", () => reject(new Error("Desktop probe connection failed")), { once: true });
+            connection.addEventListener("close", () => reject(new Error("Desktop probe disconnected")), { once: true });
+        });
+        connection.addEventListener("error", fail);
+        connection.addEventListener("close", fail);
+        connection.addEventListener("message", (event) => {
+            try {
+                const message = JSON.parse(String(event.data));
+                if (message.method === "thread/status/changed" && message.params?.status?.type === "active")
+                    changedToActive = true;
+                const item = pending.get(message.id);
+                if (!item)
+                    return;
+                pending.delete(message.id);
+                if (message.error)
+                    item.reject(new DesktopProbeRpcError(message.error.code, String(message.error.message ?? "Desktop probe RPC failed")));
+                else
+                    item.resolve(message.result);
+            }
+            catch {
+                fail();
+            }
+        });
+        const request = (method, params) => new Promise((resolve, reject) => {
+            const id = ++nextId;
+            pending.set(id, { resolve, reject });
+            try {
+                connection.send(JSON.stringify({ id, method, params }));
+            }
+            catch (error) {
+                pending.delete(id);
+                reject(error);
+            }
+        });
+        const run = async () => {
+            await opened;
+            await request("initialize", { clientInfo: { name: "agentroam_desktop_setup", version: "1" }, capabilities: { experimentalApi: true } });
+            connection.send(JSON.stringify({ method: "initialized", params: {} }));
+            return operation(request, () => changedToActive);
+        };
+        return await Promise.race([
+            run(),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Desktop probe timed out")), timeoutMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        rejectPending?.();
+        socket?.close();
+        await dispatcher?.destroy();
+    }
+}
+export async function readDesktopActivity(request) {
+    const listLoaded = async () => {
+        const ids = new Set();
+        const cursors = new Set();
+        let cursor = null;
+        for (let pageIndex = 0; pageIndex < 20; pageIndex++) {
+            const page = await request("thread/loaded/list", { cursor, limit: 100 });
+            if (!Array.isArray(page?.data) || page.data.some((id) => typeof id !== "string" || !id))
+                throw new Error("incomplete loaded thread list");
+            for (const id of page.data)
+                ids.add(id);
+            if (page.nextCursor === null || page.nextCursor === undefined)
+                return [...ids].sort();
+            if (typeof page.nextCursor !== "string" || !page.nextCursor || cursors.has(page.nextCursor))
+                throw new Error("invalid cursor");
+            cursors.add(page.nextCursor);
+            cursor = page.nextCursor;
+        }
+        throw new Error("Desktop thread list exceeded probe limit");
+    };
+    const ids = await listLoaded();
+    let activeCount = 0;
+    let hasUnknownStatus = false;
+    for (const threadId of ids) {
+        const result = await request("thread/read", { threadId, includeTurns: false });
+        if (result?.thread?.id !== threadId)
+            throw new Error("Desktop thread identity changed");
+        const status = result.thread.status?.type;
+        if (status === "active")
+            activeCount++;
+        else if (status !== "idle")
+            hasUnknownStatus = true;
+    }
+    if (activeCount)
+        return { state: "busy", activeCount };
+    if (hasUnknownStatus || JSON.stringify(ids) !== JSON.stringify(await listLoaded())) {
+        return { state: "unknown", reason: "桌面任务列表发生变化或包含无法确认的状态" };
+    }
+    return { state: "idle" };
+}

package/dist/codex-desktop-setup.js

@@ -0,0 +1,119 @@
+import { openSync, closeSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { ReadStream, WriteStream } from "node:tty";
+import { fileURLToPath } from "node:url";
+import { runCodexDesktopCommand } from "./codex-desktop-command.js";
+import { inspectCodexDesktop } from "./codex-desktop-status.js";
+export async function setupCodexDesktop(options, context = {}) {
+    if ((context.platform ?? process.platform) !== "darwin")
+        return;
+    const log = context.log ?? console.log;
+    const environment = { ...(context.environment ?? process.env) };
+    if (context.service?.dataDir === options.dataDir) {
+        if (!environment.CODEX_HOME && context.service.codexHome)
+            environment.CODEX_HOME = context.service.codexHome;
+        if (!environment.AGENT_CODEX_BIN && context.service.codexPath)
+            environment.AGENT_CODEX_BIN = context.service.codexPath;
+    }
+    const inspect = context.inspect ?? inspectCodexDesktop;
+    const deferred = () => log("已保留当前 Codex 桌面端。扫码仍可连接 AgentRoam；原桌面会话暂未共享，可稍后执行 agentroam codex-desktop --setup。");
+    try {
+        let snapshot = await inspect(environment);
+        if (snapshot.status === "not-installed") {
+            log("未安装官方 Codex 桌面端，继续生成扫码连接入口。");
+            return;
+        }
+        const original = snapshot;
+        let restartConfirmed = false;
+        if (snapshot.status === "running" && snapshot.activity.state === "idle") {
+            // Read every loaded thread again immediately before choosing automatic restart.
+            snapshot = await inspect(environment);
+            if (!sameDesktop(original, snapshot)) {
+                log("桌面进程已变化，本次保留桌面。");
+                deferred();
+                return;
+            }
+        }
+        if (snapshot.status === "running" && snapshot.activity.state !== "idle") {
+            const reason = snapshot.activity.state === "busy"
+                ? `官方 Codex 桌面端当前有 ${snapshot.activity.activeCount} 个运行中的会话。`
+                : "无法可靠确认官方 Codex 桌面端的全部任务已结束。";
+            log(reason);
+            const answer = await (context.confirm ?? confirmDesktopRestart)("现在重启桌面端以共享会话？重启可能中断桌面端的所有运行任务；选择保留则暂不能共享原桌面会话 [y/N]：");
+            if (!answer || !/^(?:y|yes)$/i.test(answer.trim())) {
+                deferred();
+                return;
+            }
+            restartConfirmed = true;
+            const checked = await inspect(environment);
+            if (!sameDesktop(snapshot, checked)) {
+                log("确认后桌面进程已变化，本次保留桌面。");
+                deferred();
+                return;
+            }
+            snapshot = checked;
+        }
+        if (snapshot.status !== "running" && snapshot.status !== "stopped")
+            return;
+        environment.CODEX_DESKTOP_APP = snapshot.appPath;
+        environment.AGENTROAM_CODEX_DESKTOP_EXPECTED_PID = snapshot.status === "running" ? String(snapshot.pid) : "0";
+        if (snapshot.status === "running" && !restartConfirmed) {
+            environment.AGENTROAM_CODEX_DESKTOP_IDLE_GUARD = fileURLToPath(new URL("./codex-desktop-idle-guard.js", import.meta.url));
+            environment.AGENTROAM_CODEX_DESKTOP_GUARD_NODE = process.execPath;
+        }
+        else {
+            delete environment.AGENTROAM_CODEX_DESKTOP_IDLE_GUARD;
+            delete environment.AGENTROAM_CODEX_DESKTOP_GUARD_NODE;
+        }
+        const launchOptions = { ...options, command: "codex-desktop", desktopSetup: false,
+            desktopDryRun: false, desktopRestart: snapshot.status === "running" };
+        log(snapshot.status === "stopped" ? "正在启动官方 Codex 桌面端并连接共享后端…" : "正在重新连接官方 Codex 桌面端的共享后端…");
+        await (context.launch ?? ((args, env) => runCodexDesktopCommand(args, { environment: env, log })))(launchOptions, environment);
+        log("已尝试桌面连接，随后显示扫码入口。AgentRoam 将根据实际连接结果，依次使用桌面、shared、standalone 后端。");
+    }
+    catch (error) {
+        log(`桌面共享连接未完成：${error instanceof Error ? error.message : error}`);
+        log("AgentRoam 安装继续，扫码可连接；后端按桌面 → shared → standalone 回退。原桌面会话暂未确认共享，可稍后执行 agentroam codex-desktop --setup 重试。");
+    }
+}
+function sameDesktop(previous, current) {
+    return previous.status === "running" && current.status === "running"
+        && previous.pid === current.pid && previous.appPath === current.appPath;
+}
+/** curl | sh owns stdin. Only the controlling terminal can authorize restart. */
+export async function confirmDesktopRestart(question) {
+    let inputFd;
+    let outputFd;
+    let input;
+    let output;
+    let reader;
+    try {
+        inputFd = openSync("/dev/tty", "r");
+        outputFd = openSync("/dev/tty", "w");
+        input = new ReadStream(inputFd);
+        output = new WriteStream(outputFd);
+        reader = createInterface({ input, output, terminal: true });
+        const prompt = reader;
+        return await new Promise((resolve) => {
+            prompt.once("close", () => resolve(null));
+            prompt.once("SIGINT", () => resolve(null));
+            input.once("error", () => resolve(null));
+            output.once("error", () => resolve(null));
+            prompt.question(question, resolve);
+        });
+    }
+    catch {
+        return null;
+    }
+    finally {
+        reader?.close();
+        if (input)
+            input.destroy();
+        else if (inputFd !== undefined)
+            closeSync(inputFd);
+        if (output)
+            output.destroy();
+        else if (outputFd !== undefined)
+            closeSync(outputFd);
+    }
+}

package/dist/codex-desktop-status.js

@@ -0,0 +1,85 @@
+import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { probeDesktopActivity } from "./codex-desktop-probe.js";
+const execFileAsync = promisify(execFile);
+export async function inspectCodexDesktop(environment, context = {}) {
+    const executableExists = context.executableExists ?? (async (path) => {
+        try {
+            await access(path, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    let appPath = environment.CODEX_DESKTOP_APP;
+    if (!appPath)
+        appPath = await executableExists("/Applications/ChatGPT.app") ? "/Applications/ChatGPT.app" : "/Applications/Codex.app";
+    const binary = join(appPath, "Contents/MacOS", basename(appPath, ".app"));
+    if (!await executableExists(binary))
+        return { status: "not-installed" };
+    const execute = context.execute ?? execFileAsync;
+    const commandOptions = { encoding: "utf8", timeout: 1_500, maxBuffer: 2 * 1024 * 1024 };
+    const { stdout } = await execute("/bin/ps", ["-axo", "pid=,ppid=,args="], commandOptions);
+    const processes = String(stdout).split("\n").flatMap((line) => {
+        const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+        return match ? [{ pid: Number(match[1]), parentPid: Number(match[2]), command: match[3] }] : [];
+    });
+    const desktops = processes.filter(({ command }) => command === binary || command.startsWith(`${binary} `));
+    if (!desktops.length)
+        return { status: "stopped", appPath };
+    const pid = desktops[0].pid;
+    const unknown = (reason) => ({ status: "running", appPath, pid, activity: { state: "unknown", reason } });
+    if (desktops.length !== 1)
+        return unknown("检测到多个官方桌面进程，无法完整确认任务状态");
+    const servers = processes.filter((process) => process.parentPid === pid && /^(?:.*\/)?codex\s.*\bapp-server(?:\s|$)/.test(process.command));
+    if (servers.length !== 1)
+        return unknown("桌面端未提供可完整查询的独立后端");
+    const server = servers[0];
+    const listenUrl = /(?:^|\s)--listen(?:=|\s+)(unix:\/\/.*?|ws:\/\/\S+)(?=\s+-|$)/.exec(server.command)?.[1];
+    if (!listenUrl || /\bapp-server\s+(?:proxy|daemon)\b/.test(server.command)) {
+        return unknown("桌面端使用私有后端，无法可靠判断全部会话是否空闲");
+    }
+    let endpoint = null;
+    try {
+        if (listenUrl.startsWith("ws://")) {
+            const address = new URL(listenUrl);
+            if (["0.0.0.0", "[::]"].includes(address.hostname))
+                address.hostname = "localhost";
+            if (!["localhost", "127.0.0.1", "[::1]"].includes(address.hostname) || address.port === "0")
+                throw new Error("not local");
+            const result = await execute("/usr/sbin/lsof", ["-nP", "-a", "-p", String(server.pid), "-iTCP", "-sTCP:LISTEN", "-Ftn"], commandOptions);
+            const port = address.port || "80";
+            if (String(result.stdout).split("\n").some((line) => /^n(?:127\.0\.0\.1|localhost|\[::1\]|\*|0\.0\.0\.0|\[::\]):(\d+)$/.exec(line)?.[1] === port))
+                endpoint = address.href;
+        }
+        else {
+            const result = await execute("/usr/sbin/lsof", ["-nP", "-a", "-p", String(server.pid), "-U", "-Ftn"], commandOptions);
+            const requested = listenUrl.slice("unix://".length);
+            const paths = [];
+            let unix = false;
+            for (const line of String(result.stdout).split("\n")) {
+                if (line.startsWith("t"))
+                    unix = line === "tunix";
+                if (!unix || !line.startsWith("n/"))
+                    continue;
+                const path = line.slice(1).split(" type=")[0];
+                if (path.includes(" -> ") || path.includes(":"))
+                    continue;
+                if (!requested || path === requested)
+                    paths.push(path);
+            }
+            if (paths.length === 1)
+                endpoint = `ws+unix://localhost${encodeURI(paths[0])}:/rpc`;
+        }
+        if (!endpoint)
+            return unknown("未找到归属桌面端的可连接监听地址");
+        return { status: "running", appPath, pid, activity: await (context.probe ?? probeDesktopActivity)(endpoint) };
+    }
+    catch {
+        return unknown("无法完整查询桌面端的实时任务状态");
+    }
+}

package/dist/service/launcher-cleanup.js

@@ -1,5 +1,18 @@
 import { lstat, readFile, readdir, realpath, rm } from "node:fs/promises";
 import { relative, resolve, sep } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function processPathsInUse() {
+    // Windows has no reliable cwd inventory here: retain old installs instead.
+    if (process.platform === "win32")
+        throw new Error("Process paths unavailable");
+    const { stdout } = await execFileAsync(process.platform === "darwin" ? "/usr/sbin/lsof" : "lsof", ["-nP", "-d", "cwd,txt", "-Fn"], { timeout: 5_000, maxBuffer: 16 * 1024 * 1024 });
+    const paths = stdout.split("\n").filter(line => line.startsWith("n/")).map(line => line.slice(1));
+    if (!paths.length)
+        throw new Error("Incomplete process paths");
+    return [process.cwd(), ...paths];
+}
 function versionParts(version) {
     const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-preview\.(0|[1-9]\d*))?$/.exec(version);
     return match ? [Number(match[1]), Number(match[2]), Number(match[3]), match[4] === undefined ? Infinity : Number(match[4])] : null;
@@ -18,7 +31,7 @@ function contains(parent, child) {
     return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !path.startsWith(sep));
 }
 /** Remove only recognized managed launcher versions after the replacement service is ready. */
-export async function cleanupOldLaunchers(config, log) {
+export async function cleanupOldLaunchers(config, log, context = {}) {
     try {
         const dataDir = await realpath(config.dataDir);
         const launcherDir = resolve(dataDir, "launcher");
@@ -47,6 +60,11 @@ export async function cleanupOldLaunchers(config, log) {
                 const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
                 if (manifest.name !== "agentroam" || manifest.version !== entry.name)
                     continue;
+                const usedPaths = await (context.pathsInUse ?? processPathsInUse)();
+                if (usedPaths.some(path => contains(candidate, path))) {
+                    log(`旧版 CLI ${entry.name} 仍被进程使用，已保留。`);
+                    continue;
+                }
                 await rm(candidate, { recursive: true });
                 log(`✓ 已清理旧版 CLI ${entry.name}，配置和数据已保留`);
             }

package/dist/service/service-command.js

@@ -8,6 +8,7 @@ import { MacLaunchAgent } from "./macos-launch-agent.js";
 import { WindowsTaskService } from "./windows-task-service.js";
 import { assertSupportedNodeVersion } from "../../bin/runtime-policy.mjs";
 import { cleanupOldLaunchers } from "./launcher-cleanup.js";
+import { setupCodexDesktop } from "../codex-desktop-setup.js";
 export async function runServiceCommand(options, context) {
     const platform = context.platform ?? process.platform;
     const log = context.log ?? console.log;
@@ -59,10 +60,15 @@ export async function runServiceCommand(options, context) {
             };
             const { definition, state } = await controller.install(config);
             log(`✓ AgentRoam service installed: ${definition}`);
+            if (platform === "darwin" && !options.desktopSetup)
+                log("官方 Codex 桌面共享后端：agentroam codex-desktop --setup；预演：agentroam codex-desktop --dry-run。");
             if (state?.status === "ready" && state.version === config.version)
                 await cleanupOldLaunchers(config, log);
             if (state?.localUrl && state.status !== "stopped")
                 printLocalDesktopUrl(state.localUrl, log, platform);
+            if (options.desktopSetup && platform === "darwin") {
+                await (context.desktopSetup ?? setupCodexDesktop)(options, { platform, environment, service: config, log });
+            }
             if (state?.status === "ready" && state.accessUrl) {
                 log(`Open: ${state.accessUrl}`);
                 await (context.pairingPrinter ?? printPairingCode)(options.dataDir, log, { accessUrl: state.accessUrl, qr: options.qr, interactive: stdoutIsTTY });

package/install/install-agentroam.sh

@@ -259,7 +259,13 @@ fi
 if [ "${AGENTROAM_INSTALL_SKIP_SERVICE:-}" = "1" ]; then
   printf 'AgentRoam service registration skipped for isolated verification.\n'
 else
-  "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR"
+  codex_setup_module="$(dirname "$entry")/../dist/codex-desktop-setup.js"
+  if [ -f "$codex_setup_module" ]; then
+    "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR" --setup-codex-desktop
+  else
+    printf '当前发布的 CLI 尚未包含官方 Codex 桌面共享配置；扫码可连接 AgentRoam，原桌面会话暂未共享，请升级 CLI 后重试。\n'
+    "$NODE_BIN" "$entry" service install --root "$SERVICE_ROOT" --data-dir "$DATA_DIR"
+  fi
 fi
 printf '\nAgentRoam %s installed: %s\n' "$AGENTROAM_VERSION" "$WRAPPER_PATH"
 case ":${PATH:-}:" in

package/install/install-manifest.json

@@ -3,8 +3,8 @@
   "installers": {
     "darwin-arm64": {
       "fileName": "install-agentroam.sh",
-      "sha256": "db22342cd22272c739f6633deff65c4b54b9dc919778141b7d8d55c37be221a3",
-      "size": 11625
+      "sha256": "8ae51c123a05aa32f1483baf6d80ff7c5dbe0cc638578402e2a65c5e314f90de",
+      "size": 12028
     },
     "windows-amd64": {
       "fileName": "install-agentroam.ps1",

package/install/start-codex-desktop-shared.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Launch a stopped official Desktop against the existing shared app-server.
+# Restart is opt-in; a normal start preserves an already running Desktop.
+codex_desktop_dry_run=false
+codex_desktop_restart=false
+for codex_desktop_option in "$@"; do
+  case "$codex_desktop_option" in
+    --dry-run) codex_desktop_dry_run=true ;;
+    --restart) codex_desktop_restart=true ;;
+    *) echo "Usage: agentroam codex-desktop [--dry-run] [--restart]" >&2; exit 2 ;;
+  esac
+done
+
+if [[ "$(uname -s)" != Darwin ]]; then
+  echo "This launcher requires macOS." >&2
+  exit 2
+fi
+
+codex_desktop_app="${CODEX_DESKTOP_APP:-}"
+if [[ -z "$codex_desktop_app" ]]; then
+  if [[ -d /Applications/ChatGPT.app ]]; then
+    codex_desktop_app=/Applications/ChatGPT.app
+  else
+    codex_desktop_app=/Applications/Codex.app
+  fi
+fi
+codex_desktop_name="$(basename "$codex_desktop_app" .app)"
+codex_desktop_binary="$codex_desktop_app/Contents/MacOS/$codex_desktop_name"
+if [[ ! -x "$codex_desktop_binary" ]]; then
+  echo "Official Desktop executable not found: $codex_desktop_binary" >&2
+  exit 2
+fi
+
+# Attempt the connection regardless of Desktop version. A missing marker in
+# app.asar is not proof of incompatibility; the client's actual initialization
+# determines whether Desktop, shared or standalone is selected.
+
+codex_shared_root="${CODEX_HOME:-$HOME/.codex}"
+codex_shared_socket="$codex_shared_root/app-server-control/app-server-control.sock"
+if [[ "$codex_shared_socket" != /* || "$codex_shared_socket" == *[[:space:]%:#?]* ]]; then
+  echo "Shared socket path must be absolute and contain no whitespace or URL delimiters." >&2
+  exit 2
+fi
+codex_shared_url="ws+unix://localhost$codex_shared_socket:/rpc"
+codex_shared_cli="${AGENT_CODEX_BIN:-$HOME/.local/bin/codex}"
+if [[ -n "${AGENT_CODEX_BIN:-}" && ! -x "$codex_shared_cli" ]]; then
+  echo "Configured AGENT_CODEX_BIN is not executable: $codex_shared_cli" >&2
+  exit 2
+fi
+if [[ -z "${AGENT_CODEX_BIN:-}" && ! -x "$codex_shared_cli" ]]; then
+  codex_shared_cli="$(command -v codex || true)"
+fi
+if [[ -z "$codex_shared_cli" ]]; then
+  echo "Codex CLI not found. Set AGENT_CODEX_BIN to its executable." >&2
+  exit 2
+fi
+
+codex_desktop_running_pid=""
+check_desktop_pid() {
+  codex_desktop_running_pid=""
+  local codex_desktop_processes
+  codex_desktop_processes="$(/bin/ps -axo pid=,args=)" || return 1
+  while read -r codex_desktop_pid codex_desktop_command; do
+    if [[ "$codex_desktop_command" == "$codex_desktop_binary" || "$codex_desktop_command" == "$codex_desktop_binary "* ]]; then
+      if [[ -n "$codex_desktop_running_pid" ]]; then
+        echo "Multiple Desktop processes found; no restart attempted." >&2
+        return 1
+      fi
+      codex_desktop_running_pid="$codex_desktop_pid"
+    fi
+  done <<< "$codex_desktop_processes"
+  if [[ -n "${AGENTROAM_CODEX_DESKTOP_EXPECTED_PID:-}" && "${codex_desktop_running_pid:-0}" != "$AGENTROAM_CODEX_DESKTOP_EXPECTED_PID" ]]; then
+    echo "Desktop process changed after setup inspection; no restart attempted." >&2
+    return 1
+  fi
+}
+check_desktop_pid
+
+if [[ "$codex_desktop_dry_run" == true ]]; then
+  echo "Desktop: $codex_desktop_app"
+  echo "CODEX_APP_SERVER_WS_URL=$codex_shared_url"
+  echo "CLI: $codex_shared_cli"
+  if [[ -n "$codex_desktop_running_pid" ]]; then
+    if [[ "$codex_desktop_restart" == true ]]; then
+      echo "Desktop PID $codex_desktop_running_pid would be quit and relaunched; all its running sessions would be interrupted."
+    else
+      echo "Desktop PID $codex_desktop_running_pid is running; launch will refuse until Desktop has exited."
+    fi
+  fi
+  echo "Dry run: no process started or stopped, no environment persisted."
+  exit 0
+fi
+
+if [[ -n "$codex_desktop_running_pid" && "$codex_desktop_restart" != true ]]; then
+  echo "Desktop PID $codex_desktop_running_pid is still running. Exit Desktop after its active sessions finish, then rerun, or explicitly use agentroam codex-desktop --restart (interrupts all Desktop sessions)." >&2
+  exit 1
+fi
+
+# Check daemon availability before asking the existing Desktop to quit.
+(cd "$HOME" && "$codex_shared_cli" app-server daemon start)
+if [[ ! -S "$codex_shared_socket" ]]; then
+  echo "Shared app-server socket not found: $codex_shared_socket" >&2
+  exit 1
+fi
+"$codex_shared_cli" app-server daemon version >/dev/null
+codex_desktop_preflight_node="${AGENTROAM_CODEX_DESKTOP_PREFLIGHT_NODE:-$(command -v node || true)}"
+codex_desktop_preflight="${AGENTROAM_CODEX_DESKTOP_PREFLIGHT:-$(dirname "$0")/../dist/codex-desktop-preflight.js}"
+if [[ -z "$codex_desktop_preflight_node" || ! -f "$codex_desktop_preflight" ]]; then
+  echo "Shared backend configuration check unavailable; Desktop was preserved." >&2
+  exit 1
+fi
+"$codex_desktop_preflight_node" "$codex_desktop_preflight" "$codex_shared_url" "$codex_shared_cli"
+
+# Recheck after daemon preflight; never quit a different Desktop instance.
+codex_desktop_preflight_pid="$codex_desktop_running_pid"
+check_desktop_pid
+if [[ "$codex_desktop_preflight_pid" != "$codex_desktop_running_pid" ]]; then
+  echo "Desktop process changed during daemon preflight; no restart attempted." >&2
+  exit 1
+fi
+
+if [[ -n "$codex_desktop_running_pid" ]]; then
+  if [[ -n "${AGENTROAM_CODEX_DESKTOP_IDLE_GUARD:-}" ]]; then
+    "${AGENTROAM_CODEX_DESKTOP_GUARD_NODE:?}" "$AGENTROAM_CODEX_DESKTOP_IDLE_GUARD"
+    check_desktop_pid
+  fi
+  echo "Restarting official Desktop; all its running sessions will be interrupted."
+  /usr/bin/osascript \
+    -e 'on run argv' \
+    -e 'tell application (item 1 of argv) to quit' \
+    -e 'end run' "$codex_desktop_app"
+  for ((codex_desktop_wait=0; codex_desktop_wait<40; codex_desktop_wait++)); do
+    if ! /bin/kill -0 "$codex_desktop_running_pid" 2>/dev/null; then break; fi
+    sleep 0.25
+  done
+  if /bin/kill -0 "$codex_desktop_running_pid" 2>/dev/null; then
+    echo "Desktop did not exit; no forced kill or second launch was attempted." >&2
+    exit 1
+  fi
+fi
+
+# open --env applies only to the newly launched app, avoiding global launchd
+# environment changes and preserving all Desktop settings and saved windows.
+/usr/bin/open -a "$codex_desktop_app" \
+  --env "CODEX_APP_SERVER_WS_URL=$codex_shared_url" \
+  --env "CODEX_APP_SERVER_FORCE_CLI=0"
+echo "Desktop launch requested against $codex_shared_url."

package/package.json

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