@walkhi/code-relax 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -1,83 +1,72 @@
-# Code Relax Bridge（Windows 私测包）
-
-Bridge 让 HarmonyOS 客户端控制 Windows 上的 Codex Desktop。当前要求 Windows x64、Node >=22.12 和已登录的 Codex Desktop；npm 包不包含 Node，也不修改官方程序文件。
-
-## 安装
-
-计划发布到 npm 后在线安装；当前命令为发布占位，尚不能从 registry 执行：
+# Code Relax Bridge（Windows 私测包）
+
+Bridge 让 HarmonyOS 客户端控制 Windows 上的受管 Codex 内核。当前要求 Windows x64、Node >=22.12，以及已登录的 Codex Desktop 配套内核或独立 Codex CLI；npm 包不包含 Node，也不修改官方程序文件。
+
+## 安装
+
+公开 beta 已发布到 npm，安装或更新使用：
 
 ```powershell
-npm.cmd install -g @walkhi/code-relax@beta
+npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax --foreground-scripts
 ```
 
-首次安装或更新前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。npm 全局安装会自动执行 `setup` 和 Skill 安装。`setup` 将完整服务部署到 `%LOCALAPPDATA%\Programs\CodexRemote\service`，记录安装所用 Node 的绝对路径，不复制 Node。配置、日志和二维码以 `installation.json.stateRoot` 为准，通常位于 `%LOCALAPPDATA%\CodexRemote`，MSIX 环境可能解析到包缓存目录；附件位于 `%ProgramData%\CodexRemote\attachments`。
-
-`setup` 立即启动 Bridge 和固定 45839 受管 app-server，并启用当前用户登录自启；自启不打开 Codex。受管实例健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍在运行，不中断现有任务，允许两个 app-server 暂时共存，并在手机提示立即或稍后重启。
-
-## 基础控制与完整控制
-
-```powershell
-relax shortcuts       # 创建完整控制/基础控制两个桌面快捷方式
-relax shared-start    # 完整控制、Desktop、Bridge
-relax desktop-start   # 基础控制、Desktop、Bridge
-relax start           # 启动/复用常驻 Bridge 和已配置中继
+首次安装前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。更新无需先停止正在运行的 Bridge；安装器会短暂停止、替换并恢复服务。npm 全局安装会自动执行 `setup` 和 Skill 安装。`setup` 将完整服务部署到 `%LOCALAPPDATA%\Programs\CodexRemote\service`，记录安装所用 Node 的绝对路径，不复制 Node。配置、日志和二维码以 `installation.json.stateRoot` 为准，通常位于 `%LOCALAPPDATA%\CodexRemote`，MSIX 环境可能解析到包缓存目录；附件位于 `%ProgramData%\CodexRemote\attachments`。
+
+`setup` 立即启动 Bridge 和固定 45839 受管 app-server，并启用当前用户登录自启；自启不打开 Codex。受管实例健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍未接入，安装器会关闭并重新打开 Desktop；安装前应保存工作。普通更新无接入或启动链迁移需求时复用现有内核。
+
+## Codex 内核
+
+```powershell
+relax start           # 启动/复用 Bridge、受管 Codex 内核和已配置中继
 relax pair            # 启动/复用服务并打开配对二维码
 relax status
 relax stop
-```
-
-基础控制使用普通 Desktop 工具管道。完整控制由官方 `codex app-server --listen ws://127.0.0.1:45839` 提供执行服务，Desktop 和 Bridge 同时连接；它只监听回环地址。Bridge 独立报告 app-server 健康、Desktop 接入和手机可写状态；Desktop 离线时不允许手机发起任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
-
-手机工作站详情可确认启用完整控制，独立进程逐步执行并保留 Bridge/中继连接，见[启用流程](../docs/shared-recovery.md)。本地 `shared-start` / `desktop-start` 在控制方式不匹配时要求先自行退出 Desktop，不强制结束任务。Bridge 状态匹配且健康时直接复用；未知进程占用 45831/45839 时拒绝接管。`stop` 只停止 Bridge，不停止 Desktop 或完整控制使用的 app-server。
-
-完整控制使用的 app-server 通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。完整控制不等待 Desktop 工具管道：项目、任务列表和新建任务使用 app-server；Bridge 在后台发现工具管道并读取桌面排序、置顶信息，后续列表读取应用这些信息，项目和任务 ID 保持不变。工具通道断开后重新发现，不中断手机聊天；Desktop 页面跳转在通道就绪后可用。
-
-基础控制聊天仍依赖 Desktop 工具管道；Bridge 启动不等待管道，后台发现成功后恢复聊天能力。管道缺失或多个候选时保留管理连接并报告执行不可用，不猜测目标。
-
-## Code Relax 中继
-
-私有中继仍需要本机 Bridge：
-
-```powershell
-relax relay-shared-start --json
+```
+
+Codex 内核由官方 `codex app-server --listen ws://127.0.0.1:45839` 提供执行服务，Desktop 和 Bridge 均可连接；它只监听回环地址。Bridge 独立报告内核健康、Desktop 接入和手机可写状态；Desktop 退出后，手机仍可操作内核中的任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
+
+手机工作站详情可确认让 Desktop 接入 Codex 内核，独立进程逐步执行并保留 Bridge/中继连接，见[启用流程](../docs/shared-recovery.md)。本机恢复命令为 `relax shared-recover --confirm`，查看恢复结果用 `relax shared-recovery-status`。Bridge 状态匹配且健康时直接复用；未知进程占用 45831/45839 时拒绝接管。`stop` 只停止 Bridge，不停止 Desktop 或受管 app-server。
+
+受管 app-server 通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。手机的项目、任务列表和新建任务均使用受管内核，不依赖 Desktop 工具管道；项目和任务 ID 保持原生值。
+
+受管 app-server 未就绪时，手机停留在连接界面并显示“Codex 内核未就绪”；Bridge 保留健康和恢复接口，聊天请求返回错误。
+
+## Code Relax 中继
+
+私有中继仍需要本机 Bridge：
+
+```powershell
+relax start --json
 relax relay-start --json
 relax relay-status --json
 relax pair --json
 relax relay-stop --json
 relax relay-revoke --json
-```
-
-`relay-shared-start` 先准备完整控制和 Bridge，再连接公网私有中继。每台移动设备通过 `pair` 配对一次；新增设备不替换已有设备。连接器把 Windows hostname 和当前 Wi-Fi/有线网络候选经已认证 WebSocket 临时发送给手机，手机本地保存电脑名，只在设备身份验证通过后保存可达地址；服务器不持久化这些 Code Relax 中继 hostname、IP 或网络名。OpenAI 官方认证和设备配对仍直接访问 OpenAI；完成后，手机使用统一配对产生的设备凭据，通过独立元数据 WebSocket 把官方环境 ID、名称和 hostname 写入设备记录，不上传 OpenAI access token、配对码或登录态。停止连接器不撤销授权。
-
-## Bridge 调试页面
-
-```powershell
-relax dev --json
-relax dev-status --json
-relax dev-stop --json
-```
-
-调试页面与 Bridge 共用进程和端口（默认 45831），只额外提供白名单静态资源，用于基础控制和完整控制的局域网页面调试。`dev-stop` 只关闭静态页面，不影响 Bridge WebSocket。Code Relax 中继和 OpenAI 中继均使用 HAP 内置页面。
-
-## 更新与卸载
-
-更新固定服务：
-
+```
+
+`start` 启动内核和 Bridge，并恢复已配置中继；`relay-start` 单独管理中继连接器。每台移动设备通过 `pair` 配对一次；新增设备不替换已有设备。连接器把 Windows hostname 和当前 Wi-Fi/有线网络候选经已认证 WebSocket 临时发送给手机，手机本地保存电脑名，只在设备身份验证通过后保存可达地址；服务器不持久化这些 Code Relax 中继 hostname、IP 或网络名。OpenAI 官方认证和设备配对仍直接访问 OpenAI；完成后，手机使用统一配对产生的设备凭据，通过独立元数据 WebSocket 把官方环境 ID、名称和 hostname 写入设备记录，不上传 OpenAI access token、配对码或登录态。停止连接器不撤销授权。
+
+Bridge 的局域网端口仅提供鉴权 WebSocket，普通 HTTP 请求返回 404；手机聊天页面随 HAP 安装。
+
+## 更新与卸载
+
+更新固定服务：
+
 ```powershell
-npm.cmd install -g @walkhi/code-relax@beta
+npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax --foreground-scripts
 ```
 
 `setup` 先暂存并校验新版本，再短暂停止 Bridge/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前执行 `stop`。Node 路径变化或原 Node 被删除后需重新 setup。升级可能因 Node 可执行文件路径变化而再次触发 Windows 防火墙授权。
-
-卸载：
-
-```powershell
+
+卸载：
+
+```powershell
 relax uninstall
 npm uninstall -g @walkhi/code-relax
-```
-
+```
+
 `uninstall` 停止 Bridge 后先核对并清理 Code Relax 所有的当前用户 `CODEX_APP_SERVER_WS_URL`；用户后来修改或不归属 Code Relax 的值会保留。随后删除固定程序和本包管理且未修改的 Skill；保留其他配置、Token、日志、长期设备凭据、附件和自定义 Skill。它不卸载 Node、Codex Desktop，也不强制结束完整控制的执行进程。
-
-## 发布边界
-
-包名为 `@walkhi/code-relax@0.1.0-beta.1`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。首次公开 beta 发布前仍需确认 npm scope 所有权、第三方许可、新电脑首次安装、防火墙、升级/卸载和移动端到端验收。详细规则见 [npm 分发](../docs/npm-distribution.md)。
+
+## 发布边界
+
+registry 测试包使用 `@walkhi/code-relax@beta`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。安装摘要通过 `--foreground-scripts` 显示，首次安装或启动链迁移时干净重启 Desktop，分别报告已安装与实际运行版本；登录启动使用当前用户任务计划。通信协议仍为 7。详细规则见 [npm 分发](../docs/npm-distribution.md)。

package/dist/bin/codex-remote.mjs

@@ -7,8 +7,7 @@ import { installService, uninstallService, packageRoot } from '../src/service-in
 import { installSkill, removeSkill, inspectSkill } from '../src/skill-install.mjs';
 import { doctor } from '../src/service-doctor.mjs';
 import { launchDesktop } from '../src/desktop-launcher.mjs';
-import { desktopHost, desktopShortcuts, residentStartup, resolveStateRoot } from '../src/platform/windows/desktop-host.mjs';
-import { debugUi } from '../src/debug-ui.mjs';
+import { desktopHost, removeDesktopShortcut, residentStartup, resolveStateRoot } from '../src/platform/windows/desktop-host.mjs';
 import { selfRelay } from '../src/self-relay/lifecycle.mjs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
@@ -17,33 +16,27 @@ import { spawn } from 'node:child_process';
 import { setTimeout as delay } from 'node:timers/promises';
 import { requestRecovery, recoveryStatus, recoveryWarning } from '../src/shared-recovery.mjs';
 import { configureManagedEnvironment, clearManagedEnvironment } from '../src/platform/windows/user-environment.mjs';
+import { resolveCodexRuntime } from '../src/platform/windows/codex-runtime.mjs';
 
 const help = `Code Relax（Windows）
-用法：relax <setup|doctor|skill-install|skill-remove|uninstall|start|shared-start|desktop-start|shortcuts|pair|status|stop> [--json]
+用法：relax <setup|doctor|skill-install|skill-remove|uninstall|start|pair|status|stop> [--json]
   setup   部署并启动固定目录服务、受管 app-server 和登录自启动；安全配置 Desktop 后续接入
-  start   启动或复用 Bridge，并恢复已配置的私有中继
-  shared-start 启动或复用完整控制，再启动 Bridge 和已配置的私有中继
-  shared-recover --confirm 启用或重新启动完整控制，保留 Bridge 和中继，可能中断当前任务
+  start   启动或复用 Bridge 和 Codex 内核，并恢复已配置的私有中继
+  shared-recover --confirm 重新打开 Desktop 并接入 Codex 内核；不强制重启已有内核
   shared-recovery-status 查看最近一次恢复的实际阶段和结果
   autostart-enable / autostart-disable / autostart-status 管理当前用户登录时启动 Bridge
-  desktop-start 恢复基础控制，再启动 Bridge（切换前须自行退出 Desktop）
-  shortcuts 创建完整控制/基础控制桌面快捷方式
   pair    启动或复用工作站服务，并打开一次性配对二维码
   status  查看服务健康状态
   stop    停止服务
-  dev     在 Bridge 端口开启调试页面（实时读取当前源码/包资源）
-  dev-status 查看 Bridge 调试页面状态
-  dev-stop 关闭调试页面，不停止 Bridge
   relay-start 启动或复用私有中继，已有授权直接恢复，首次授权生成二维码
-  relay-shared-start 启动完整控制和 Bridge 后连接私有中继（需先退出当前 Codex）
-  relay-status 查看私有中继连接器及手机连接状态
+  relay-status 查看私有中继连接器及移动端连接状态
   relay-stop 停止私有中继连接器，不停止 Bridge 或 Codex
   relay-revoke 撤销这台电脑的全部移动设备授权（停止连接器不会撤销授权）
-  doctor  检查安装、Node、Desktop、网络和 Skill，提示防火墙处理方式
+  doctor  检查安装、Node、Codex 内核、网络和 Skill，提示防火墙处理方式
   skill-install 安装/更新当前用户的 Codex Skill，不覆盖自定义文件
   skill-remove  移除本包安装且未修改的 Skill
   uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
-默认监听 0.0.0.0，手机与电脑需在同一受信任局域网。
+默认监听 0.0.0.0，移动端与电脑需在同一受信任局域网。
 --json 输出机器可读结果；统一二维码不含 LAN 地址、Bridge Token 或中继地址。`;
 
 async function main() {
@@ -52,7 +45,7 @@ async function main() {
     console.log(help);
     return;
   }
-  if (!['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', 'relay-shared-start', 'relay-revoke', 'relay-start', 'relay-status', 'relay-stop', 'dev', 'dev-status', 'dev-stop', 'setup', 'doctor', 'skill-install', 'skill-remove', 'uninstall', 'shared-start', 'desktop-start', 'shortcuts', 'start', 'pair', 'status', 'stop'].includes(command)
+  if (!['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', 'relay-revoke', 'relay-start', 'relay-status', 'relay-stop', 'setup', 'doctor', 'skill-install', 'skill-remove', 'uninstall', 'start', 'pair', 'status', 'stop'].includes(command)
     || flags.some(flag => flag !== '--json' && !(command === 'shared-recover' && flag === '--confirm'))) {
     throw new Error('无效命令或参数。使用 --help 查看用法。');
   }
@@ -60,30 +53,13 @@ async function main() {
   const json = flags.includes('--json');
   const paths = runtimePaths();
   const { stateRoot, serviceRoot } = paths;
-  if (['relay-shared-start', 'relay-revoke', 'relay-start', 'relay-status', 'relay-stop'].includes(command)) {
-    if (command === 'relay-shared-start') {
-      const existing = await selfRelay('relay-status', stateRoot);
-      if (existing.running && existing.transportMode !== 'lan-shared') throw new Error('基础控制的中继连接器仍在运行，请先执行 relay-stop；不会自动中断手机连接。');
-      const result = await new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, [fileURLToPath(import.meta.url), 'shared-start', '--json'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
-        let output = '', errors = '';
-        child.stdout.on('data', chunk => { output += chunk; }); child.stderr.on('data', chunk => { errors += chunk; });
-        child.once('error', reject);
-        child.once('exit', code => { if (code) reject(new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || '完整控制启动失败')); else { try { resolve(JSON.parse(output)); } catch { reject(new Error('完整控制启动结果无法确认，未启动中继')); } } });
-      });
-      if (!result.bridgeReady) { console.log(json ? JSON.stringify(result) : result.displayText); return; }
-    }
-    const result = await selfRelay(command === 'relay-shared-start' ? 'relay-start' : command, stateRoot, command === 'relay-shared-start' ? 'lan-shared' : '');
+  if (['relay-revoke', 'relay-start', 'relay-status', 'relay-stop'].includes(command)) {
+    const result = await selfRelay(command, stateRoot);
     console.log(json ? JSON.stringify(result) : `${result.displayText}${result.qrPath ? '\n二维码：' + result.qrPath : ''}`);
     return;
   }
-  if (['dev', 'dev-status', 'dev-stop'].includes(command)) {
-    const result = await debugUi(command, stateRoot);
-    console.log(json ? JSON.stringify(result) : result.message || JSON.stringify(result));
-    return;
-  }
   const installedEntry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
-  if (['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', 'shared-start', 'desktop-start', 'shortcuts', 'start', 'pair', 'status', 'stop'].includes(command) && path.resolve(fileURLToPath(import.meta.url)).toLowerCase() !== installedEntry.toLowerCase()) {
+  if (['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', 'start', 'pair', 'status', 'stop'].includes(command) && path.resolve(fileURLToPath(import.meta.url)).toLowerCase() !== installedEntry.toLowerCase()) {
     if (!fs.existsSync(installedEntry)) throw new Error('尚未部署服务，请先执行 relax setup。');
     const executable = readRecord(path.join(serviceRoot, 'installation.json'))?.nodeExecutable;
     if (!executable || !fs.existsSync(executable)) throw new Error('安装时选用的 Node 不存在，请重新执行 relax setup。');
@@ -92,7 +68,6 @@ async function main() {
     process.exitCode = code ?? 1;
     return;
   }
-  host.migrateState(stateRoot);
   const service = lifecycle({ stateRoot, host });
   if (command.startsWith('autostart-')) {
     const installation = readRecord(path.join(serviceRoot, 'installation.json'));
@@ -122,13 +97,6 @@ async function main() {
     console.log(json ? JSON.stringify(result) : `${result.displayText}\n二维码：${result.qrPath}`);
     return;
   }
-  if (command === 'shortcuts') {
-    const installation = readRecord(path.join(serviceRoot, 'installation.json'));
-    if (!installation?.nodeExecutable) throw new Error('请先执行 relax setup。');
-    const shortcuts = await desktopShortcuts({ serviceRoot, nodeExecutable: installation.nodeExecutable });
-    console.log(json ? JSON.stringify({ shortcuts }) : `桌面快捷方式已创建：\n${shortcuts.join('\n')}`);
-    return;
-  }
   if (command === 'doctor') {
     const result = await doctor({ paths, host, service });
     console.log(json ? JSON.stringify(result) : result.checks.map(item => `[${item.status}] ${item.message}`).join('\n'));
@@ -148,14 +116,14 @@ async function main() {
     const result = await uninstallService(paths, service, async () => {
       environment = await clearManagedEnvironment(stateRoot);
       const installation = readRecord(path.join(serviceRoot, 'installation.json'));
-      if (installation?.nodeExecutable) await desktopShortcuts({ serviceRoot, nodeExecutable: installation.nodeExecutable }, true);
+      if (installation?.nodeExecutable) await removeDesktopShortcut({ serviceRoot, nodeExecutable: installation.nodeExecutable });
       if (installation?.nodeExecutable) await residentStartup({ serviceRoot, nodeExecutable: installation.nodeExecutable }, 'disable');
     });
     result.environment = environment;
     result.skill = skill.managed ? removeSkill() : { removed: false, message: '未移除自定义或未安装的 Skill。' };
     result.message = environment?.preserved
-      ? '固定目录服务已卸载；检测到用户自定义的 CODEX_APP_SERVER_WS_URL，已保留。配置、附件也已保留。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。'
-      : '固定目录服务已卸载；Code Relax 设置的 app-server 环境变量已清理，其他配置和附件已保留。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。';
+      ? '固定目录服务已卸载；检测到用户自定义的 CODEX_APP_SERVER_WS_URL，已保留。配置、附件和可能仍在执行任务的 app-server 也已保留；重启 Windows可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。'
+      : '固定目录服务已卸载；Code Relax 设置的 app-server 环境变量已清理，其他配置、附件和可能仍在执行任务的 app-server 已保留；重启 Windows可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。';
     console.log(json ? JSON.stringify(result) : `${result.message}\n${result.skill.message}`);
     return;
   }
@@ -164,13 +132,19 @@ async function main() {
     if (major < 22 || (major === 22 && minor < 12)) throw new Error('需要 Node >=22.12。');
     const physicalStateRoot = await resolveStateRoot(stateRoot);
     // Preserve the effective package view; never replace a newer file already in it.
-    for (const name of ['bridge-config.json', 'bridge-session.json', 'bridge-startup-context.json', 'execution-mode.json',
-      'self-relay-config.json', 'self-relay-session.json', 'lan-device-authorizations.json', 'shared-desktop.json',
-      'managed-app-server.json', 'managed-environment.json', 'shared-recovery.json', 'shared-recovery.lock', 'debug-ui-session.json']) {
+    for (const name of ['bridge-config.json', 'bridge-session.json', 'bridge-startup-context.json',
+      'self-relay-config.json', 'self-relay-session.json', 'lan-device-authorizations.json',
+      'managed-app-server.json', 'managed-environment.json', 'shared-recovery.json', 'shared-recovery.lock']) {
       const source = path.join(stateRoot, name), target = path.join(physicalStateRoot, name);
       if (fs.existsSync(source) && !fs.existsSync(target)) fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
     }
-    const previous = fs.existsSync(serviceRoot) ? await service.status() : { processRunning: false };
+    const hadInstalledService = fs.existsSync(path.join(serviceRoot, 'installation.json'));
+    const previousInstallation = readRecord(path.join(serviceRoot, 'installation.json'));
+    if (previousInstallation?.nodeExecutable) await removeDesktopShortcut({ serviceRoot, nodeExecutable: previousInstallation.nodeExecutable });
+    const desktopBeforeSetup = await desktopHost.inspect();
+    const runtime = await resolveCodexRuntime(physicalStateRoot, { refresh: true });
+    const desktopNeedsAttach = desktopBeforeSetup.running && !await host.sharedServiceUrl();
+    const previous = hadInstalledService ? await service.status() : { processRunning: false };
     const previousRelay = await selfRelay('relay-status', stateRoot);
     const resumeAfterUpdate = previous.processRunning || previousRelay.running;
     const executable = fs.realpathSync(process.execPath);
@@ -189,6 +163,7 @@ async function main() {
     let stoppedForUpdate = false;
     const installed = await installService(packageRoot(path.dirname(fileURLToPath(import.meta.url))), serviceRoot, executable, physicalStateRoot, {
       beforeActivate: async () => {
+        if (desktopNeedsAttach) await desktopHost.closeDesktop(desktopBeforeSetup.desktop);
         stoppedForUpdate = resumeAfterUpdate;
         if (previousRelay.running) await selfRelay('relay-stop', stateRoot);
         if (previous.processRunning) await service.stop();
@@ -205,18 +180,68 @@ async function main() {
     if (!bridge.running || bridge.managedAppServer?.state !== 'ready') {
       throw new Error(bridge.managedAppServer?.error || 'Bridge 已安装，但受管 app-server 未就绪；未写入 Desktop 环境变量。');
     }
+    const environment = desktopBeforeSetup.desktop
+      ? await configureManagedEnvironment(physicalStateRoot) : { configured: false, reason: 'desktop-not-installed' };
+    let managedAppServerMigrated = false;
+    const managedAppServerMigration = {
+      required: bridge.managedAppServer.launcherRestartRequired === true,
+      restarted: false,
+      previousPid: bridge.managedAppServer.pid || null,
+    };
+    let desktopRestarted = false;
+    let desktopRestartReason = null;
+    if (managedAppServerMigration.required) {
+      const desktopInfo = await desktopHost.inspect();
+      const desktopAttached = desktopInfo.running
+        && (bridge.desktop?.attachedToManagedServer === true || Boolean(await host.sharedServiceUrl()));
+      if (desktopAttached) await desktopHost.closeDesktop(desktopInfo.desktop);
+      await service.restartManagedAppServer();
+      const migrationDeadline = Date.now() + 40_000;
+      do {
+        await delay(250);
+        bridge = await service.status();
+        if (bridge.managedAppServer?.restart?.status === 'failed') {
+          throw new Error(bridge.managedAppServer.restart.error || '受管 app-server 启动链迁移失败。');
+        }
+      } while (Date.now() < migrationDeadline && (!bridge.running || bridge.managedAppServer?.state !== 'ready' || bridge.managedAppServer.launcherRestartRequired));
+      if (!bridge.running || bridge.managedAppServer?.state !== 'ready' || bridge.managedAppServer.launcherRestartRequired) {
+        throw new Error('受管 app-server 未在 40 秒内完成启动链迁移。');
+      }
+      managedAppServerMigrated = true;
+      managedAppServerMigration.restarted = true;
+      if (desktopAttached) {
+        await launchDesktop({ stateRoot: physicalStateRoot, host: desktopHost });
+        desktopRestarted = true;
+        desktopRestartReason = 'app-server-migration';
+        bridge = await service.status();
+      }
+    }
     const autostart = await residentStartup(installed, 'enable');
-    const environment = await configureManagedEnvironment(physicalStateRoot);
+    if (desktopNeedsAttach && !desktopRestarted) {
+      const currentDesktop = await desktopHost.inspect();
+      if (currentDesktop.running) await desktopHost.closeDesktop(currentDesktop.desktop);
+      await launchDesktop({ stateRoot: physicalStateRoot, host: desktopHost });
+      desktopRestarted = true;
+      desktopRestartReason = 'attach-managed-server';
+      bridge = await service.status();
+    }
     installed.autostart = autostart;
     installed.restarted = resumeAfterUpdate;
     installed.environment = environment;
     installed.managedAppServer = bridge.managedAppServer;
-    installed.desktop = bridge.desktop;
-    installed.desktopRestartRecommended = bridge.desktop?.state === 'ordinary';
-    const restartText = installed.desktopRestartRecommended
-      ? 'Codex 当前仍在使用原连接。可以在手机端选择“立即重启（推荐）”，或稍后自行完全退出再启动。'
-      : '下次正常启动 Codex 时会连接受管 app-server。';
-    console.log(json ? JSON.stringify({ ...installed, nextSteps: desktopSetupSteps, displayText: `${desktopSetupSteps.join('\n')}\n${restartText}` }) : `服务已安装：${installed.serviceRoot}\n使用已安装的 Node：${installed.nodeExecutable}\n受管 app-server 已就绪；首次联网可能需要 Windows 防火墙授权。\n${desktopSetupSteps.join('\n')}\n${restartText}`);
+    installed.codexRuntime = runtime;
+    installed.managedAppServerMigrated = managedAppServerMigrated;
+    installed.managedAppServerMigration = { ...managedAppServerMigration,
+      currentPid: bridge.managedAppServer.pid || null,
+      launcherRevision: bridge.managedAppServer.launcherRevision ?? null };
+    installed.desktopRestarted = desktopRestarted;
+    installed.desktopRestartReason = desktopRestartReason;
+    const migrationText = managedAppServerMigrated ? '已自动重建旧启动链的 app-server；安装前尚未完成的任务可能已中断。\n' : '';
+    const restartText = desktopRestarted
+      ? 'Codex Desktop 已干净重启并重新接入受管 app-server。'
+      : desktopBeforeSetup.desktop ? 'Codex Desktop 使用同一受管 app-server；移动端控制不依赖 Desktop 是否打开。'
+      : '使用独立 Codex CLI；无需安装 Codex Desktop。';
+    console.log(json ? JSON.stringify({ ...installed, nextSteps: desktopSetupSteps, displayText: `${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}` }) : `服务已安装：${installed.serviceRoot}\n使用已安装的 Node：${installed.nodeExecutable}\n受管 app-server 已就绪；首次联网可能需要 Windows 防火墙授权。\n${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}`);
     return;
   }
   if (command === 'stop') {
@@ -224,26 +249,20 @@ async function main() {
     console.log(json ? JSON.stringify(result) : result.message);
     return;
   }
-  let desktop;
-  if (command === 'shared-start' || command === 'desktop-start') {
-    if (!json) console.log('正在检查 Codex 的启动模式…');
-    desktop = await launchDesktop(command === 'shared-start' ? 'shared' : 'ordinary', { stateRoot, host: desktopHost });
-    delete process.env.CODEX_APP_TOOLS_PIPE_PATH;
-  }
-  if (!json && (desktop || command === 'start')) console.log('正在检查电脑连接并准备 Bridge…');
-  const result = await service[desktop ? 'start' : command]();
-  if (command === 'status') {
-    console.log(json ? JSON.stringify(result) : result.running
-      ? `服务正常：${result.mode}，端口 ${result.port}，PID ${result.pid}` : '服务未就绪。');
+  if (!json && command === 'start') console.log('正在检查电脑连接并准备 Bridge…');
+  const result = await service[command]();
+  if (command === 'status') {
+    console.log(json ? JSON.stringify(result) : result.running
+      ? `服务正常：${result.mode}，版本 ${result.version || '未知'}，端口 ${result.port}，PID ${result.pid}` : '服务未就绪。');
     return;
   }
   const { accessUrl, qrPath: _legacyQrPath, ...metadata } = result;
-  const notice = '本机服务检查通过，手机连通性尚未验证。若电脑弹出 Node 网络访问提示，请先处理 Windows 防火墙授权，再用手机连接。';
+  const notice = '本机服务检查通过，移动端连通性尚未验证。若电脑弹出 Node 网络访问提示，请先处理 Windows 防火墙授权，再用移动端连接。';
   let relay;
   if (fs.existsSync(path.join(stateRoot, 'self-relay-config.json'))) relay = await selfRelay('relay-start', stateRoot);
   const nextSteps = phonePairingSteps(metadata.transportMode, relay?.paired === true);
   const displayText = pairingDisplayText(nextSteps, notice);
-  const output = { ...metadata, ...(desktop ? { desktop, bridgeReady: true } : {}), ...(relay ? { relayConnected: relay.relayConnected,
+  const output = { ...metadata, ...(relay ? { relayConnected: relay.relayConnected,
     paired: relay.paired, clientCount: relay.clientCount, ...(relay.qrPath ? { qrPath: relay.qrPath, expiresAt: relay.expiresAt } : {}) } : {}),
     nextSteps, displayText, mode: 'lan', listenAddress: '0.0.0.0', address: new URL(accessUrl).host,
     lanAccess: 'unverified', notice };

package/dist/bin/self-relay-admin.mjs

@@ -0,0 +1,8 @@
+import { startAdminServer } from '../src/self-relay/admin-server.mjs';
+
+const port = Number(process.env.RELAY_ADMIN_PORT || 45851);
+if (!Number.isSafeInteger(port) || port < 1 || port > 65535) throw new Error('Invalid RELAY_ADMIN_PORT');
+const server = await startAdminServer({ port });
+console.log(JSON.stringify({ service: 'codex-relay-admin', port: server.port }));
+await new Promise(resolve => { process.once('SIGTERM', resolve); process.once('SIGINT', resolve); });
+await server.close();

package/dist/bin/self-relay-demo.mjs

@@ -3,7 +3,7 @@ import { startRelayDemo } from '../src/self-relay/demo.mjs';
 import fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 
-const mode = process.argv.includes('--legacy') ? 'lan-legacy' : 'lan-shared';
+const mode = 'lan-shared';
 let remoteRelay;
 if (process.env.RELAY_URL) {
   let hostKey;

package/dist/bin/self-relay-server.mjs

@@ -12,6 +12,9 @@ if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('Inv
 const stateFile = process.env.RELAY_STATE_FILE;
 if (!stateFile) throw new Error('RELAY_STATE_FILE is required');
 const debugAllowlistFile = process.env.RELAY_DEBUG_ALLOWLIST_FILE || '/etc/codex-relay/debug-allowlist.json';
+const adminStateFile = process.env.RELAY_ADMIN_STATE_FILE || '/var/lib/codex-relay/admin.json';
+const maxRelaySessions = Number(process.env.RELAY_MAX_RELAY_SESSIONS || 8);
+if (!Number.isSafeInteger(maxRelaySessions) || maxRelaySessions < 1 || maxRelaySessions > 256) throw new Error('Invalid RELAY_MAX_RELAY_SESSIONS');
 const debugCommand = process.argv.find(value => ['--debug-list', '--debug-allow', '--debug-deny'].includes(value));
 if (debugCommand) {
   const records = deviceStore(stateFile).entries();
@@ -41,10 +44,10 @@ if (revokeIndex >= 0) {
   store.save({ ...record, status: 'revoked', clientHash: undefined, clientId: undefined, revision: record.revision + 1, updatedAt: new Date().toISOString() });
   console.log('Computer and phone authorization revoked'); process.exit(0);
 }
-const relay = await startSelfRelay({ port, hostKey, stateFile, debugAllowlistFile,
+const relay = await startSelfRelay({ port, hostKey, stateFile, debugAllowlistFile, adminStateFile, maxRelaySessions,
   publicRelayUrl: process.env.RELAY_PUBLIC_URL || '', appDownloadUrl: process.env.RELAY_APP_DOWNLOAD_URL || '',
   log: entry => console.log(JSON.stringify({ time: new Date().toISOString(), ...entry })) });
-console.log(JSON.stringify({ service: 'codex-self-relay', listen: relay.url, maxConnections: 32,
+console.log(JSON.stringify({ service: 'codex-self-relay', listen: relay.url, maxConnections: 32, maxRelaySessions,
   maxFrameMiB: 8, encryption: 'TLS must be supplied by reverse proxy; no end-to-end encryption' }));
 await new Promise(resolve => { process.once('SIGTERM', resolve); process.once('SIGINT', resolve); });
 await relay.close();

package/dist/shared/app-server-events.cjs

@@ -1,32 +1,59 @@
 (function (root, factory) {
   if (typeof module === 'object' && module.exports) module.exports = factory();
   else root.CodexAppServerEvents = factory();
-})(globalThis, function () {
-  function mergeItems(existing, incoming = []) {
-    for (const item of incoming) {
-      const index = existing.findIndex(current => current.id === item.id);
-      if (index < 0) existing.push(item);
-      else existing[index] = { ...existing[index], ...item };
-    }
-    return existing;
-  }
+})(globalThis, function () {
+  function mergeItems(existing, incoming = []) {
+    for (const source of incoming) {
+      const item = compactItem(source);
+      const index = existing.findIndex(current => current.id === item.id);
+      if (index < 0) existing.push(item);
+      else existing[index] = { ...existing[index], ...item };
+    }
+    return existing;
+  }
+
+  function compactItem(item) {
+    if (!item || typeof item !== 'object') return item;
+    if (item.type === 'commandExecution') {
+      const { aggregatedOutput, output, ...metadata } = item;
+      return metadata;
+    }
+    if (item.type === 'mcpToolCall') {
+      const { result, ...metadata } = item;
+      return metadata;
+    }
+    if (item.type === 'dynamicToolCall') {
+      const { contentItems, ...metadata } = item;
+      return metadata;
+    }
+    if (item.type === 'imageGeneration') {
+      const { result, ...metadata } = item;
+      return metadata;
+    }
+    return item;
+  }
+
+  function compactTurn(turn) {
+    return { ...turn, items: Array.isArray(turn?.items) ? turn.items.map(compactItem) : [] };
+  }
 
   // Both relay and local WebSocket carry these same app-server notifications.
   // Mutate one thread and return only the affected turn for incremental rendering.
   function applyNotification(thread, method, p) {
     if (method === 'thread/status/changed') thread.status = p.status;
     else if (method === 'thread/name/updated') thread.name = p.threadName;
-    else if (!['turn/started', 'turn/completed', 'item/started', 'item/completed', 'item/agentMessage/delta',
-      'item/reasoning/summaryTextDelta', 'item/reasoning/summaryPartAdded', 'item/commandExecution/outputDelta'].includes(method)) return null;
+    else if (!['turn/started', 'turn/completed', 'item/started', 'item/completed', 'item/agentMessage/delta',
+      'item/reasoning/summaryTextDelta', 'item/reasoning/summaryPartAdded'].includes(method)) return null;
     thread.turns ||= [];
     let turn = thread.turns.find(t => t.id === (p.turnId || p.turn?.id));
-    if (!turn && p.turnId && p.item) { turn = { id: p.turnId, status: 'inProgress', items: [] }; thread.turns.push(turn); }
-    if (p.turn) {
-      if (!turn) { turn = { ...p.turn, items: p.turn.items || [] }; thread.turns.push(turn); }
-      else Object.assign(turn, { ...p.turn, items: mergeItems(turn.items || [], p.turn.items) });
-      thread.status = method === 'turn/started' ? 'active' : method === 'turn/completed' ? 'idle' : thread.status;
-    }
-    if (p.item && turn) mergeItems(turn.items, [p.item]);
+    if (!turn && p.turnId && p.item) { turn = { id: p.turnId, status: 'inProgress', items: [] }; thread.turns.push(turn); }
+    if (p.turn) {
+      const incomingTurn = compactTurn(p.turn);
+      if (!turn) { turn = incomingTurn; thread.turns.push(turn); }
+      else Object.assign(turn, { ...incomingTurn, items: mergeItems(turn.items || [], incomingTurn.items) });
+      thread.status = method === 'turn/started' ? 'active' : method === 'turn/completed' ? 'idle' : thread.status;
+    }
+    if (p.item && turn) mergeItems(turn.items, [compactItem(p.item)]);
     const item = turn?.items.find(item => item.id === p.itemId);
     if (item) {
       if (method === 'item/agentMessage/delta') item.text = (item.text || '') + p.delta;
@@ -34,8 +61,7 @@
         item.summary ||= []; item.summary[p.summaryIndex] = (item.summary[p.summaryIndex] || '') + p.delta;
       }
       if (method === 'item/reasoning/summaryPartAdded') { item.summary ||= []; item.summary[p.summaryIndex] ??= ''; }
-      if (method === 'item/commandExecution/outputDelta') item.aggregatedOutput = (item.aggregatedOutput || '') + p.delta;
-    }
+    }
     return turn || (['thread/status/changed', 'thread/name/updated'].includes(method) ? thread.turns.at(-1) : null);
   }
   function mergeAvailable(previous, incoming) {
@@ -111,6 +137,18 @@
     }
     return match;
   }
+  function catalogThreadProjectId(thread, projects) {
+    if (thread.projectId) return thread.projectId;
+    const local = thread.environments?.find(environment => environment.environmentId === 'local');
+    if (local && Array.isArray(local.runtimeWorkspaceRoots)) {
+      for (const root of local.runtimeWorkspaceRoots) {
+        const projectId = threadProjectId({ cwd: root }, projects);
+        if (projectId) return projectId;
+      }
+      return null;
+    }
+    return threadProjectId({ cwd: thread.cwd }, projects);
+  }
   function projectlessThreadTarget(cwd = '') {
     return { projectId: null, runtimeWorkspaceRoots: [], ...(cwd ? { cwd } : {}) };
   }
@@ -246,9 +284,11 @@
     if (action === 'steer') {
       const item = (await readQueueItems(request, threadId)).find(item => item.id === queuedSubmissionId);
       if (!item) throw new Error('该排队消息已不在队列中');
-      const { thread } = await request('thread/read', { threadId, includeTurns: true });
-      const active = thread.turns.findLast(turn => turn.status === 'inProgress');
-      if (active) {
+      const page = await request('thread/turns/list', {
+        threadId, limit: 1, sortDirection: 'desc', itemsView: 'summary',
+      });
+      const active = page.data?.[0];
+      if (active?.status === 'inProgress') {
         await request('turn/steer', { threadId, expectedTurnId: active.id, input: item.input,
           clientUserMessageId: item.clientUserMessageId });
         const { deleted } = await request('thread/queue/delete', { threadId, queuedSubmissionId });
@@ -261,6 +301,6 @@
     }
     return readQueue(request, threadId);
   }
-  return { createThread, readQueue, addQueue, changeQueue, mergeItems, applyNotification, mergeUsage, UsageCache, readProjects, orderDesktopProjects, threadProjectId, projectlessThreadTarget, updateSettings,
+  return { createThread, readQueue, addQueue, changeQueue, compactItem, compactTurn, mergeItems, applyNotification, mergeUsage, UsageCache, readProjects, orderDesktopProjects, threadProjectId, catalogThreadProjectId, projectlessThreadTarget, updateSettings,
     permissionState, availablePermissionModes, PermissionOptionsCache, updatePermissions };
 });