@walkhi/code-relax 0.1.0-beta.26 → 0.1.0-beta.28

package/dist/bin/codex-remote.mjs

@@ -1,286 +1,333 @@
 #!/usr/bin/env node
 import { phonePairingSteps, desktopSetupSteps, pairingDisplayText } from '../src/onboarding.mjs';
-import { lifecycle, readRecord, writeRecord } from '../src/service-lifecycle.mjs';
+import { lifecycle, readRecord, writeRecord } from '../src/service-lifecycle.mjs';
 import { runtimePaths } from '../src/platform/windows/runtime-paths.mjs';
 import * as host from '../src/platform/windows/service-host.mjs';
 import { installService, uninstallService, packageRoot } from '../src/service-install.mjs';
-import { installSkill, removeSkill, inspectSkill } from '../src/skill-install.mjs';
+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, removeDesktopShortcut, residentStartup, resolveStateRoot } from '../src/platform/windows/desktop-host.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';
 import fs from 'node:fs';
-import { spawn } from 'node:child_process';
-import { setTimeout as delay } from 'node:timers/promises';
-import { requestRecovery, 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';
-import { controlRequest } from '../src/service-control.mjs';
-import { processAlive } from '../src/background-process.mjs';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { requestRecovery, 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';
+import { controlRequest } from '../src/service-control.mjs';
+import { processAlive } from '../src/background-process.mjs';
+import { managedAppServerUrl } from '../src/managed-app-server.mjs';
+import { readDotsTasks } from '../src/dots-task-catalog.mjs';
 
-const help = `Code Relax（Windows）
-用法：relax <命令> [--json]；下列命令均可用
-常用指令：
-  start   启动或复用桌面服务和 Codex 内核，并恢复已配置的 Code Relax 中继
-  pair    启动或复用桌面服务，并打开一次性配对二维码
-维护指令：
-  setup   部署并启动桌面服务、Codex 内核和登录自启动；安全配置 Desktop 后续接入
-  doctor  检查服务、登录自启、最近恢复结果、网络和 Skill
-  desktop-recover --confirm 重新打开 Desktop 并接入 Codex 内核；不强制重启已有内核
-  uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
-默认监听 0.0.0.0，移动端与电脑需在同一受信任局域网。
---json 输出机器可读结果；统一二维码不含 LAN 地址、桌面服务凭据或中继地址。`;
-
-function currentNodeExecutable() {
-  const link = process.env.NVM_SYMLINK && path.join(process.env.NVM_SYMLINK, 'node.exe');
-  if (link && fs.existsSync(link)) {
-    try {
-      if (fs.realpathSync(link).toLowerCase() === fs.realpathSync(process.execPath).toLowerCase()) return link;
-    } catch {}
-  }
-  return process.execPath;
-}
+const help = `Code Relax（Windows）
+用法：relax <命令> [--json]；下列命令均可用
+常用指令：
+  start   启动或复用桌面服务和 Codex 内核，并恢复已配置的 Code Relax 中继
+  pair    启动或复用桌面服务，并打开一次性配对二维码
+  dots-tasks 读取当前 ChatGPT 账号的 Dots 委派任务与最近轮次状态
+维护指令：
+  setup   部署并启动桌面服务、Codex 内核和登录自启动；安全配置 Desktop 后续接入
+  doctor  检查服务、内核更新、登录自启、最近恢复结果、网络和 Skill
+  kernel-restart --confirm 重启 Codex 内核并启用已选更新；等待新内核就绪
+  desktop-recover --confirm 重新打开 Desktop 并接入 Codex 内核；不强制重启已有内核
+  uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
+默认监听 0.0.0.0，移动端与电脑需在同一受信任局域网。
+--json 输出机器可读结果；统一二维码不含 LAN 地址、桌面服务凭据或中继地址。`;
 
-async function main() {
+function currentNodeExecutable() {
+  const link = process.env.NVM_SYMLINK && path.join(process.env.NVM_SYMLINK, 'node.exe');
+  if (link && fs.existsSync(link)) {
+    try {
+      if (fs.realpathSync(link).toLowerCase() === fs.realpathSync(process.execPath).toLowerCase()) return link;
+    } catch {}
+  }
+  return process.execPath;
+}
+
+async function main() {
   const [command, ...flags] = process.argv.slice(2);
   if (!command || command === '--help' || command === '-h') {
     console.log(help);
     return;
   }
-  if (!['desktop-recover', 'setup', 'doctor', 'uninstall', 'start', 'pair'].includes(command)
-    || flags.some(flag => flag !== '--json' && !(command === 'desktop-recover' && flag === '--confirm'))) {
+  if (!['kernel-restart', 'desktop-recover', 'setup', 'doctor', 'uninstall', 'start', 'pair', 'dots-tasks'].includes(command)
+    || flags.some(flag => flag !== '--json' && !(['kernel-restart', 'desktop-recover'].includes(command) && flag === '--confirm'))) {
     throw new Error('无效命令或参数。使用 --help 查看用法。');
   }
   if (process.platform !== 'win32') throw new Error('当前被控端仅支持 Windows。');
   const json = flags.includes('--json');
+  if (command === 'dots-tasks') {
+    const result = await readDotsTasks(managedAppServerUrl);
+    const statuses = { completed: '完成', inProgress: '进行中', failed: '失败', interrupted: '已中断' };
+    console.log(json ? JSON.stringify(result) : result.tasks.length
+      ? result.tasks.map(task => `${task.title || task.id} — ${statuses[task.latestTurn?.status] || task.status || '暂无轮次'}\n${task.cwd || ''}`).join('\n\n')
+      : '当前账号没有未归档的 Dots 委派任务。');
+    return;
+  }
   const paths = runtimePaths();
-  const { stateRoot, serviceRoot } = paths;
-  const installedEntry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
-  const installationPath = path.join(serviceRoot, 'installation.json');
-  const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
-  const currentNodeSupported = nodeMajor > 22 || (nodeMajor === 22 && nodeMinor >= 12);
-  const installed = path.resolve(fileURLToPath(import.meta.url)).toLowerCase() === installedEntry.toLowerCase();
-  const installation = readRecord(installationPath);
-  if (installation?.nodeExecutable && !fs.existsSync(installation.nodeExecutable) && currentNodeSupported
-    && ['start', 'pair', 'doctor'].includes(command)) {
-    writeRecord(installationPath, { ...installation, nodeExecutable: currentNodeExecutable() });
-  }
-  if (['desktop-recover', 'start', 'pair'].includes(command) && !installed) {
-    if (!fs.existsSync(installedEntry)) throw new Error('尚未部署服务，请先执行 relax setup。');
-    const executable = readRecord(installationPath)?.nodeExecutable;
-    if (!executable || !fs.existsSync(executable)) throw new Error('安装时选用的 Node 不存在，请重新执行 relax setup。');
+  const { stateRoot, serviceRoot } = paths;
+  const installedEntry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
+  const installationPath = path.join(serviceRoot, 'installation.json');
+  const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+  const currentNodeSupported = nodeMajor > 22 || (nodeMajor === 22 && nodeMinor >= 12);
+  const installed = path.resolve(fileURLToPath(import.meta.url)).toLowerCase() === installedEntry.toLowerCase();
+  const installation = readRecord(installationPath);
+  if (installation?.nodeExecutable && !fs.existsSync(installation.nodeExecutable) && currentNodeSupported
+    && ['start', 'pair', 'doctor'].includes(command)) {
+    writeRecord(installationPath, { ...installation, nodeExecutable: currentNodeExecutable() });
+  }
+  if (['kernel-restart', 'desktop-recover', 'start', 'pair'].includes(command) && !installed) {
+    if (!fs.existsSync(installedEntry)) throw new Error('尚未部署服务，请先执行 relax setup。');
+    const executable = readRecord(installationPath)?.nodeExecutable;
+    if (!executable || !fs.existsSync(executable)) throw new Error('安装时选用的 Node 不存在，请重新执行 relax setup。');
     const child = spawn(executable, [installedEntry, command, ...flags], { stdio: 'inherit', windowsHide: true });
     const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
     process.exitCode = code ?? 1;
     return;
   }
-  const service = lifecycle({ stateRoot, host });
-  const ensureAutostart = async () => {
-    const currentInstallation = readRecord(installationPath);
-    if (!currentInstallation?.nodeExecutable) throw new Error('请先执行 setup。');
-    const startup = { serviceRoot, nodeExecutable: currentInstallation.nodeExecutable };
-    const current = await residentStartup(startup, 'status');
-    if (current.enabled) return { ...current, repaired: false };
-    const result = await residentStartup(startup, 'enable');
-    return { ...result, repaired: true };
-  };
-  if (command === 'desktop-recover') {
-    if (!flags.includes('--confirm')) throw new Error(recoveryWarning + ' 使用 --confirm 确认。');
-    const result = await requestRecovery(stateRoot, { confirmed: true });
-    console.log(json ? JSON.stringify(result) : `${result.message || result.status}${result.error ? '\n' + result.error : ''}\n${result.operationId || ''}`.trim());
-    return;
-  }
-  if (command === 'pair') {
-    await ensureAutostart();
-    let bridge = await service.status();
-    if (!bridge.running) {
-      await service.start();
-      bridge = await service.status();
-    }
-    if (!bridge.running) throw new Error('Code Relax 工作站服务未能启动。');
-    const result = await selfRelay('relay-pair', stateRoot);
-    if (!json && result.qrPath) {
-      const viewer = spawn('explorer.exe', [result.qrPath], { detached: true, stdio: 'ignore', windowsHide: true });
-      viewer.unref();
-    }
-    console.log(json ? JSON.stringify(result) : `${result.displayText}\n二维码：${result.qrPath}`);
-    return;
-  }
+  const service = lifecycle({ stateRoot, host });
+  const ensureAutostart = async () => {
+    const currentInstallation = readRecord(installationPath);
+    if (!currentInstallation?.nodeExecutable) throw new Error('请先执行 setup。');
+    const startup = { serviceRoot, nodeExecutable: currentInstallation.nodeExecutable };
+    const current = await residentStartup(startup, 'status');
+    if (current.enabled) return { ...current, repaired: false };
+    const result = await residentStartup(startup, 'enable');
+    return { ...result, repaired: true };
+  };
+  if (command === 'kernel-restart') {
+    if (!flags.includes('--confirm')) {
+      throw new Error('重启会立即结束当前 Codex 内核，正在运行的任务、待审批和未确认结果可能中断；恢复后不会自动重发。使用 --confirm 确认。');
+    }
+    const previous = await service.status();
+    if (!previous.running) throw new Error('桌面服务尚未运行，请先执行 relax start。');
+    await service.restartManagedAppServer(true);
+    const deadline = Date.now() + 60_000;
+    let current = await service.status();
+    while (current.managedAppServer?.restart?.status === 'running' && Date.now() < deadline) {
+      await delay(250);
+      current = await service.status();
+    }
+    if (current.managedAppServer?.restart?.status === 'failed') {
+      throw new Error(current.managedAppServer.restart.error || 'Codex 内核重启失败。');
+    }
+    if (!current.running || current.managedAppServer?.state !== 'ready'
+      || current.managedAppServer?.restart?.status !== 'completed') {
+      throw new Error('Codex 内核未在 60 秒内完成重启，请运行 relax doctor 查看状态。');
+    }
+    if (previous.managedAppServer?.updatePending && current.managedAppServer.updatePending) {
+      throw new Error('Codex 内核已重启，但更新仍未应用；请运行 relax doctor 查看状态。');
+    }
+    const result = { status: 'completed', message: previous.managedAppServer?.updatePending
+      ? 'Codex 内核已重启并应用更新。' : 'Codex 内核已重启。',
+      previousVersion: previous.managedAppServer?.version || null,
+      version: current.managedAppServer.version || null,
+      selectedVersion: current.managedAppServer.selectedVersion || null,
+      updateApplied: previous.managedAppServer?.updatePending === true,
+      updatePending: current.managedAppServer.updatePending === true,
+      pid: current.managedAppServer.pid || null,
+      executionReady: current.execution?.ready === true };
+    console.log(json ? JSON.stringify(result) : `${result.message}\n版本：${result.version || '未知'}\n执行状态：${result.executionReady ? '已就绪' : '正在恢复'}`);
+    return;
+  }
+  if (command === 'desktop-recover') {
+    if (!flags.includes('--confirm')) throw new Error(recoveryWarning + ' 使用 --confirm 确认。');
+    const result = await requestRecovery(stateRoot, { confirmed: true });
+    console.log(json ? JSON.stringify(result) : `${result.message || result.status}${result.error ? '\n' + result.error : ''}\n${result.operationId || ''}`.trim());
+    return;
+  }
+  if (command === 'pair') {
+    await ensureAutostart();
+    let bridge = await service.status();
+    if (!bridge.running) {
+      await service.start();
+      bridge = await service.status();
+    }
+    if (!bridge.running) throw new Error('Code Relax 工作站服务未能启动。');
+    const result = await selfRelay('relay-pair', stateRoot);
+    if (!json && result.qrPath) {
+      const viewer = spawn('explorer.exe', [result.qrPath], { detached: true, stdio: 'ignore', windowsHide: true });
+      viewer.unref();
+    }
+    console.log(json ? JSON.stringify(result) : `${result.displayText}\n二维码：${result.qrPath}`);
+    return;
+  }
   if (command === 'doctor') {
-    const result = await doctor({ paths, host, service, ensureAutostart });
+    const result = await doctor({ paths, host, service, ensureAutostart });
     console.log(json ? JSON.stringify(result) : result.checks.map(item => `[${item.status}] ${item.message}`).join('\n'));
     if (!result.ready) process.exitCode = 1;
     return;
   }
-  if (command === 'uninstall') {
-    const skill = inspectSkill();
-    let environment;
-    const result = await uninstallService(paths, service, async () => {
-      environment = await clearManagedEnvironment(stateRoot);
-      const installation = readRecord(path.join(serviceRoot, 'installation.json'));
-      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，已保留。配置、附件和可能仍在执行任务的 app-server 也已保留；重启 Windows可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。'
-      : '固定目录服务已卸载；Code Relax 设置的 app-server 环境变量已清理，其他配置、附件和可能仍在执行任务的 app-server 已保留；重启 Windows可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。';
+  if (command === 'uninstall') {
+    const skill = inspectSkill();
+    let environment;
+    const result = await uninstallService(paths, service, async () => {
+      environment = await clearManagedEnvironment(stateRoot);
+      const installation = readRecord(path.join(serviceRoot, 'installation.json'));
+      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，已保留。配置、附件和可能仍在执行任务的 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;
   }
-  if (command === 'setup') {
-    const [major, minor] = process.versions.node.split('.').map(Number);
+  if (command === 'setup') {
+    const [major, minor] = process.versions.node.split('.').map(Number);
     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',
-      '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 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 legacyRelaySession = readRecord(path.join(stateRoot, 'self-relay-session.json'));
-    const previousRelay = legacyRelaySession ? await controlRequest(legacyRelaySession) : await selfRelay('relay-status', stateRoot);
-    const resumeAfterUpdate = previous.processRunning || previousRelay.running;
-    const executable = currentNodeExecutable();
-    const startInstalled = async () => {
-      const entry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
-      const child = spawn(executable, [entry, 'start', '--json'], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] });
-      let errors = '';
-      child.stderr.on('data', chunk => { errors += chunk; });
-      const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
-      if (code) {
-        try { await selfRelay('relay-stop', stateRoot); } catch {}
-        try { await service.stop(); } catch {}
-        throw new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || '桌面服务启动失败');
-      }
-    };
-    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 && legacyRelaySession) {
-          await controlRequest(legacyRelaySession, 'POST');
-          const deadline = Date.now() + 10000;
-          while (processAlive(legacyRelaySession.pid)) {
-            if (Date.now() >= deadline) throw new Error('旧中继进程未在 10 秒内退出。');
-            await delay(100);
-          }
-        } else if (previousRelay.running) await selfRelay('relay-stop', stateRoot);
-        if (previous.processRunning) await service.stop();
-      },
-      verifyActivation: async () => { await startInstalled(); },
-      restoreActivation: async () => { if (stoppedForUpdate) await startInstalled(); },
-    });
-    const autostart = await residentStartup(installed, 'enable');
-    const deadline = Date.now() + 35_000;
-    let bridge = await service.status();
-    while (bridge.running && !['ready', 'failed'].includes(bridge.managedAppServer?.state) && Date.now() < deadline) {
-      await delay(250);
-      bridge = await service.status();
-    }
-    if (!bridge.running || bridge.managedAppServer?.state !== 'ready') {
-      throw new Error(bridge.managedAppServer?.error || '桌面服务已安装，但 Codex 内核未就绪；未写入 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 || 'Codex 内核启动链迁移失败。');
-        }
-      } 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('Codex 内核未在 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 skill = installSkill(path.join(serviceRoot, 'dist/skills/code-relax/SKILL.md'));
-    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.skill = skill;
-    installed.restarted = resumeAfterUpdate;
-    installed.environment = environment;
-    installed.managedAppServer = bridge.managedAppServer;
-    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 已干净重启并重新接入 Codex 内核。'
-      : desktopBeforeSetup.desktop ? 'Codex Desktop 使用同一 Codex 内核；移动端控制不依赖 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}\nCodex 内核已就绪；首次联网可能需要 Windows 防火墙授权。\n${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}`);
+    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',
+      '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 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 legacyRelaySession = readRecord(path.join(stateRoot, 'self-relay-session.json'));
+    const previousRelay = legacyRelaySession ? await controlRequest(legacyRelaySession) : await selfRelay('relay-status', stateRoot);
+    const resumeAfterUpdate = previous.processRunning || previousRelay.running;
+    const executable = currentNodeExecutable();
+    const startInstalled = async () => {
+      const entry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
+      const child = spawn(executable, [entry, 'start', '--json'], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] });
+      let errors = '';
+      child.stderr.on('data', chunk => { errors += chunk; });
+      const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
+      if (code) {
+        try { await selfRelay('relay-stop', stateRoot); } catch {}
+        try { await service.stop(); } catch {}
+        throw new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || '桌面服务启动失败');
+      }
+    };
+    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 && legacyRelaySession) {
+          await controlRequest(legacyRelaySession, 'POST');
+          const deadline = Date.now() + 10000;
+          while (processAlive(legacyRelaySession.pid)) {
+            if (Date.now() >= deadline) throw new Error('旧中继进程未在 10 秒内退出。');
+            await delay(100);
+          }
+        } else if (previousRelay.running) await selfRelay('relay-stop', stateRoot);
+        if (previous.processRunning) await service.stop();
+      },
+      verifyActivation: async () => { await startInstalled(); },
+      restoreActivation: async () => { if (stoppedForUpdate) await startInstalled(); },
+    });
+    const autostart = await residentStartup(installed, 'enable');
+    const deadline = Date.now() + 35_000;
+    let bridge = await service.status();
+    while (bridge.running && !['ready', 'failed'].includes(bridge.managedAppServer?.state) && Date.now() < deadline) {
+      await delay(250);
+      bridge = await service.status();
+    }
+    if (!bridge.running || bridge.managedAppServer?.state !== 'ready') {
+      throw new Error(bridge.managedAppServer?.error || '桌面服务已安装，但 Codex 内核未就绪；未写入 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 || 'Codex 内核启动链迁移失败。');
+        }
+      } 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('Codex 内核未在 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 skill = installSkill(path.join(serviceRoot, 'dist/skills/code-relax/SKILL.md'));
+    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.skill = skill;
+    installed.restarted = resumeAfterUpdate;
+    installed.environment = environment;
+    installed.managedAppServer = bridge.managedAppServer;
+    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 已干净重启并重新接入 Codex 内核。'
+      : desktopBeforeSetup.desktop ? 'Codex Desktop 使用同一 Codex 内核；移动端控制不依赖 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}\nCodex 内核已就绪；首次联网可能需要 Windows 防火墙授权。\n${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}`);
     return;
   }
-  if (!json && command === 'start') console.log('正在检查电脑连接并准备桌面服务…');
-  await ensureAutostart();
-  const result = await service[command]();
-  const { accessUrl, qrPath: _legacyQrPath, ...metadata } = result;
-  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, ...(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 };
+  if (!json && command === 'start') console.log('正在检查电脑连接并准备桌面服务…');
+  await ensureAutostart();
+  const result = await service[command]();
+  const { accessUrl, qrPath: _legacyQrPath, ...metadata } = result;
+  const notice = '本机服务检查通过，移动端连通性尚未验证。若电脑弹出 Node 网络访问提示，请先处理 Windows 防火墙授权，再用移动端连接。';
+  let relay;
+  if (fs.existsSync(path.join(stateRoot, 'self-relay-config.json'))) relay = await selfRelay('relay-status', stateRoot);
+  const nextSteps = phonePairingSteps(metadata.transportMode, relay?.paired === true);
+  const displayText = pairingDisplayText(nextSteps, notice);
+  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 };
   if (json) console.log(JSON.stringify(output));
   else {
-    console.log('电脑连接检查通过 · 桌面服务已就绪');
-    console.log(`局域网模式：监听 0.0.0.0:${result.port}，连接地址 ${output.address}，PID ${result.pid}`);
-    if (relay?.qrPath) console.log(`配对二维码：${relay.qrPath}`);
-    console.log(displayText);
+    console.log('电脑连接检查通过 · 桌面服务已就绪');
+    console.log(`局域网模式：监听 0.0.0.0:${result.port}，连接地址 ${output.address}，PID ${result.pid}`);
+    if (relay?.qrPath) console.log(`配对二维码：${relay.qrPath}`);
+    console.log(displayText);
   }
 }
 
 main().catch(error => {
-  console.error(`Code Relax：${error.message}`);
+  console.error(`Code Relax：${error.message}`);
   process.exitCode = 1;
 });