@walkhi/code-relax 0.1.0-beta.3 → 0.1.0-beta.30

package/dist/src/shared-catalog.mjs

@@ -1,50 +1,132 @@
-import events from '../shared/app-server-events.cjs';
-
-export function sharedThreadProjectId(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 = events.threadProjectId({ cwd: root }, projects);
-      if (projectId) return projectId;
-    }
-    return null;
-  }
-  // Unloaded Desktop history omits environments and often has no persisted project ID.
-  return events.threadProjectId({ cwd: thread.cwd }, projects);
-}
-
-// Mobile catalog order comes entirely from app-server authority, independent of Desktop UI state.
-export class SharedCatalog {
-  constructor(server) { this.server = server; }
-
-  async projects() {
-    const native = await this.server.projects();
-    const projects = native.map(project => ({ projectId: project.id, name: project.name,
-      label: project.name, path: project.roots[0]?.path || '', cwd: project.roots[0]?.path || '', hostId: 'local' }));
-    return { projects, native };
-  }
-
-  async threads(limit, archived = false) {
-    const { projects, native } = await this.projects();
-    const threads = []; let cursor;
-    do {
-      const page = await this.server.request('thread/list', { limit: Math.min(100, limit - threads.length),
-        sortKey: 'recency_at', sortDirection: 'desc', archived, ...(cursor ? { cursor } : {}) });
-      threads.push(...page.data); cursor = page.nextCursor;
-    } while (cursor && threads.length < limit);
-    const summaries = threads.map(thread => ({ id: thread.id, kind: 'codex', hostId: 'local',
-      title: thread.name || thread.preview || '', cwd: thread.cwd,
-      projectId: sharedThreadProjectId(thread, native), updatedAt: thread.updatedAt,
-      recencyAt: thread.recencyAt ?? thread.updatedAt,
-      status: typeof thread.status === 'string' ? thread.status : thread.status?.type || 'unknown',
-      activeFlags: threadActiveFlags(thread.status) }));
-    return { projects, pinnedThreads: [], threads: summaries };
-  }
-}
-
-function threadActiveFlags(status) {
-  return status && typeof status === 'object' && Array.isArray(status.activeFlags)
-    ? status.activeFlags.filter(flag => typeof flag === 'string')
-    : [];
-}
+import events from '../shared/app-server-events.cjs';
+import { projectSummary } from './project-management.mjs';
+
+export function sharedThreadProjectId(thread, projects) {
+  return events.catalogThreadProjectId(thread, projects);
+}
+
+export function dotsThreadProjectId(thread, projects) {
+  if (thread.projectId && projects.some(project => project.id === thread.projectId)) return thread.projectId;
+  if (thread.environments?.length) {
+    for (const environment of thread.environments) {
+      const roots = Array.isArray(environment.runtimeWorkspaceRoots) ? environment.runtimeWorkspaceRoots : [];
+      for (const root of roots) {
+        if (!root) continue;
+        const projectId = events.threadProjectId({ cwd: root }, projects);
+        if (projectId) return projectId;
+      }
+    }
+    // Display grouping may use the execution directory when workspace roots
+    // do not map to a known project. This never changes the thread's workspace
+    // permissions or its native project assignment.
+    for (const environment of thread.environments) {
+      if (!environment.cwd) continue;
+      const projectId = events.threadProjectId({ cwd: environment.cwd }, projects);
+      if (projectId) return projectId;
+    }
+  }
+  return events.threadProjectId({ cwd: thread.cwd }, projects);
+}
+
+// Mobile catalog order comes entirely from app-server authority, independent of Desktop UI state.
+export class SharedCatalog {
+  constructor(server, dotsServer, dotsChat) {
+    this.server = server; this.dotsServer = dotsServer; this.dotsChat = dotsChat;
+    this.states = new Map();
+    dotsServer?.on('disconnected', () => this.states.clear());
+  }
+
+  threadState(thread, refresh = false) {
+    const client = thread.threadSource === 'aeon' ? this.dotsChat : this.dotsServer;
+    const observed = client?.threads.get(thread.id);
+    if (client?.ready && observed && !observed.needsReload && !observed.hydrating && !observed.refresh) {
+      const current = observed.thread;
+      return { chatRevision: current.chatRevision,
+        ...(thread.threadSource === 'aeon' ? { chatMessageRevision: current.chatMessageRevision, updatedAt: current.updatedAt }
+          : { lastTurnStatus: current.turns.at(-1)?.status || null }) };
+    }
+    const identity = this.dotsServer.profileIdentity;
+    let entry = this.states.get(thread.id);
+    const version = JSON.stringify([thread.updatedAt, thread.status]);
+    if (!entry) { entry = { value: {} }; this.states.set(thread.id, entry); }
+    if (!entry.work && (refresh || entry.version !== version || Date.now() - (entry.at || 0) >= 30000)) {
+      const work = (async () => {
+        try {
+          const value = thread.threadSource === 'aeon'
+            ? await this.dotsChat.latestChatState(thread.id)
+            : await this.dotsServer.latestTaskState(thread.id, refresh || entry.version !== version);
+          if (identity !== this.dotsServer.profileIdentity || this.states.get(thread.id) !== entry) return;
+          const changed = JSON.stringify(entry.value) !== JSON.stringify(value);
+          entry.value = value; entry.version = version; entry.at = Date.now();
+          if (changed) this.dotsServer.emit('notification', {
+            method: 'thread/status/changed', params: { threadId: thread.id, ...value },
+          });
+        } catch (error) {
+          entry.version = version; entry.at = Date.now();
+          console.error('云端目录修订读取失败：', thread.id, error.message);
+        }
+      })().finally(() => { if (entry.work === work) entry.work = null; });
+      entry.work = work;
+    }
+    // The live chat updates its revision before notifying stream listeners.
+    // A directory refresh can still be in flight with an older cached value;
+    // never return that value after the rendered timeline has advanced.
+    if (thread.threadSource === 'aeon') {
+      const current = this.dotsChat.threads.get(thread.id)?.thread;
+      return current?.chatRevision === undefined ? {} : {
+        chatRevision: current.chatRevision, chatMessageRevision: current.chatMessageRevision, updatedAt: current.updatedAt,
+      };
+    }
+    return entry.value;
+  }
+
+  async projects() {
+    const native = await this.server.projects();
+    const projects = native.map(projectSummary);
+    return { projects, native };
+  }
+
+  async threads(limit, archived = false, scope = 'all', refresh = false) {
+    const { projects, native } = await this.projects();
+    const threads = []; let cursor;
+    if (scope !== 'durable') do {
+      const page = await this.server.request('thread/list', { limit: Math.min(100, limit - threads.length),
+        sortKey: 'recency_at', sortDirection: 'desc', archived, ...(cursor ? { cursor } : {}) });
+      threads.push(...page.data); cursor = page.nextCursor;
+    } while (cursor && threads.length < limit);
+    const summaries = threads.map(thread => ({ id: thread.id, kind: 'codex', hostId: 'local',
+      ...(thread.model ? { model: thread.model, reasoningEffort: thread.reasoningEffort } : {}),
+      title: thread.name || thread.preview || '', cwd: thread.cwd,
+      projectId: sharedThreadProjectId(thread, native), updatedAt: thread.updatedAt,
+      recencyAt: thread.recencyAt ?? thread.updatedAt,
+      status: typeof thread.status === 'string' ? thread.status : thread.status?.type || 'unknown',
+      activeFlags: threadActiveFlags(thread.status) }));
+    let catalogError;
+    if (scope !== 'local' && this.dotsServer) {
+      try {
+        const dots = await this.dotsServer.catalog(archived, refresh);
+        summaries.push(...dots.map(thread => ({ id: thread.id, kind: thread.threadSource === 'aeon' ? 'dots' : 'codex', hostId: 'durable',
+          threadSource: thread.threadSource,
+          ...(thread.threadSource === 'aeon_child' && thread.model ? { model: thread.model, reasoningEffort: thread.reasoningEffort } : {}),
+          ...this.threadState(thread, refresh),
+          ...(thread.threadSource === 'aeon' ? { avatar: thread.avatar || '', color: thread.color || '' } : {}),
+          title: thread.name || (thread.threadSource === 'aeon' ? 'Dots' : thread.preview || ''), cwd: thread.cwd,
+          projectId: thread.threadSource === 'aeon' ? null : dotsThreadProjectId(thread, native),
+          updatedAt: thread.threadSource === 'aeon' ? this.dotsChat.threads.get(thread.id)?.thread.updatedAt || 0 : thread.updatedAt,
+          recencyAt: thread.recencyAt ?? thread.updatedAt,
+          status: thread.threadSource === 'aeon' ? this.dotsChat?.threads.get(thread.id)?.thread.status || 'unknown'
+            : typeof thread.status === 'string' ? thread.status : thread.status?.type || 'unknown',
+          activeFlags: thread.threadSource === 'aeon' ? [] : threadActiveFlags(thread.status) })));
+      } catch (error) { catalogError = `Dots 对话读取失败：${error.message}`; }
+    }
+    summaries.sort((a, b) => b.recencyAt - a.recencyAt);
+    return { catalogScope: scope, projects, pinnedThreads: [], threads: [...summaries.filter(thread => thread.kind === 'dots'),
+      ...summaries.filter(thread => thread.kind !== 'dots').slice(0, limit)], ...(catalogError ? { catalogError } : {}) };
+  }
+}
+
+function threadActiveFlags(status) {
+  return status && typeof status === 'object' && Array.isArray(status.activeFlags)
+    ? status.activeFlags.filter(flag => typeof flag === 'string')
+    : [];
+}

package/dist/src/shared-recovery.mjs

@@ -1,142 +1,146 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { setTimeout as delay } from 'node:timers/promises';
-import { fileURLToPath } from 'node:url';
-import { readRecord, writeRecord, lifecycle } from './service-lifecycle.mjs';
-import { startBackground } from './background-process.mjs';
-import { desktopHost } from './platform/windows/desktop-host.mjs';
-import * as serviceHost from './platform/windows/service-host.mjs';
-import { launchDesktop, portAvailable } from './desktop-launcher.mjs';
-
-const script = fileURLToPath(import.meta.url);
-const recordPath = root => path.join(root, 'shared-recovery.json');
-const lockPath = root => path.join(root, 'shared-recovery.lock');
-const sameProcess = (a, b) => a && b && a.pid === b.pid && a.created === b.created && a.executable === b.executable;
-const active = value => value && ['scheduled', 'running'].includes(value.status);
-const recoverySteps = () => [
-  ['checking', '检查启动条件'], ['stopping-desktop', '关闭当前 Codex'],
-  ['starting-app-server', '确认 Codex 内核'], ['starting-desktop', '重新打开 Codex'],
-  ['checking-execution', '确认手机控制就绪'],
-].map(([id, label]) => ({ id, label, status: 'pending' }));
-export const recoveryWarning = 'Codex Desktop 需要重新打开，才能接入同一个 Codex 内核。手机完整控制和 Codex 内核会保持运行；旧 Desktop 实例中的任务可能中断，未发送内容请先保存。切换不会清空项目、对话历史、设置或设备授权。';
-
-export async function recoveryStatus(stateRoot, host = desktopHost) {
-  const record = readRecord(recordPath(stateRoot));
-  if (!record) return { status: 'none', message: '尚未执行 Desktop 接入流程。' };
-  const lostWorker = active(record) && (record.worker
-    ? !sameProcess(record.worker, await host.process(record.worker.pid))
-    : Date.now() - Date.parse(record.startedAt) > 30000);
-  if (lostWorker) {
-    record.status = 'failed'; record.error = '独立恢复进程已退出，恢复未完成。';
-    record.steps = record.steps?.map(step => ({ ...step, status: step.status === 'running' ? 'failed' : step.status }));
-    writeRecord(recordPath(stateRoot), record);
-    if (readRecord(lockPath(stateRoot))?.operationId === record.operationId) fs.rmSync(lockPath(stateRoot));
-  }
-  const { worker, oldService, desktop, ...publicRecord } = record;
-  return publicRecord;
-}
-
-export async function planRecovery(stateRoot, host, available = portAvailable) {
-  const info = await host.inspect();
-  const action = await host.sharedServiceUrl() ? 'restart' : 'switch';
-  if (!info.desktop || !info.cli) throw new Error('未找到 Codex Desktop 或执行程序，请先在电脑完成安装和登录。');
-  const record = readRecord(path.join(stateRoot, 'managed-app-server.json')) || readRecord(path.join(stateRoot, 'shared-desktop.json'));
-  const actual = record ? await host.process(record.pid) : null;
-  if (actual && (!sameProcess(record, actual) || !actual.command?.includes('app-server') || !actual.command.includes('ws://127.0.0.1:45839'))) {
-    throw new Error('完整控制进程身份与记录不符，未结束任何进程。');
-  }
-  if (!actual && !await available()) throw new Error('45839 被未识别进程占用，未关闭 Desktop 或结束任何进程。');
-  return { desktop: info.desktop, action };
-}
-
-export async function requestRecovery(stateRoot, { confirmed, operationId = randomUUID() } = {}, host = desktopHost) {
-  if (confirmed !== true) throw new Error(recoveryWarning + ' 请明确确认后再执行。');
-  if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(operationId)) throw new Error('无效的恢复操作编号。');
-  fs.mkdirSync(stateRoot, { recursive: true });
-  const previous = await recoveryStatus(stateRoot, host);
-  if (previous.operationId === operationId) return previous;
-  if (active(previous)) throw new Error('已有恢复操作正在执行，请查看恢复状态。');
-  const planned = await planRecovery(stateRoot, host);
-  let lock;
-  try { lock = fs.openSync(lockPath(stateRoot), 'wx'); }
-  catch (error) { if (error.code === 'EEXIST') throw new Error('已有恢复操作，请先查看恢复状态。'); throw error; }
-  fs.writeFileSync(lock, JSON.stringify({ operationId })); fs.closeSync(lock);
-  const record = { operationId, status: 'scheduled', stage: 'prepared', startedAt: new Date().toISOString(),
-    message: '完整控制请求已接受，电脑管理连接保持运行。', steps: recoverySteps(), ...planned };
-  try {
-    writeRecord(recordPath(stateRoot), record);
-    const log = path.join(stateRoot, 'shared-recovery.log');
-    const pid = await startBackground(process.execPath, [script, '--worker', stateRoot, operationId], process.env, [log, log]);
-    const worker = await host.process(pid);
-    if (!worker) throw new Error('独立恢复进程未启动，请查看 shared-recovery.log。');
-    // Publish the process identity before allowing the worker to begin disruption.
-    writeRecord(recordPath(stateRoot), { ...record, worker });
-    return { operationId, status: record.status, message: record.message };
-  } catch (error) {
-    writeRecord(recordPath(stateRoot), { ...record, status: 'failed', error: error.message });
-    fs.rmSync(lockPath(stateRoot), { force: true }); throw error;
-  }
-}
-
-export async function runRecovery(stateRoot, operationId, dependencies = {}) {
-  const host = dependencies.host || desktopHost;
-  const service = dependencies.service || lifecycle({ stateRoot, host: serviceHost });
-  const available = dependencies.available || portAvailable;
-  const start = dependencies.launch || (options => launchDesktop('shared', options));
-  let record = readRecord(recordPath(stateRoot));
-  if (record?.operationId !== operationId || readRecord(lockPath(stateRoot))?.operationId !== operationId) throw new Error('恢复实例已失效。');
-  record.steps ||= recoverySteps();
-  const stage = name => {
-    record = { ...record, status: 'running', stage: name, steps: record.steps.map(step => ({ ...step,
-      status: step.id === name ? 'running' : step.status === 'running' ? 'completed' : step.status })) };
-    writeRecord(recordPath(stateRoot), record);
-  };
-  const waitFor = async (check, message) => {
-    const deadline = Date.now() + (dependencies.timeout ?? 10000);
-    while (!await check()) { if (Date.now() >= deadline) throw new Error(message); await delay(100); }
-  };
-  try {
-    stage('checking');
-    const planned = await planRecovery(stateRoot, host, available);
-    record = { ...record, ...planned };
-    if (fs.existsSync(path.join(stateRoot, 'desktop-launch.lock'))) throw new Error('Desktop 正在启动，未与启动操作并行恢复。');
-    stage('stopping-desktop'); await host.closeDesktop(record.desktop);
-    await waitFor(async () => !(await host.inspect()).running, '当前 Codex Desktop 未退出，未继续接入 Codex 内核。');
-    stage('starting-app-server'); await start({ stateRoot, host, recoveryId: operationId, progress: stage });
-    stage('checking-execution');
-    await service.start(); // Refresh the execution adapter; resident Bridge retains its PID and sockets.
-    await waitFor(async () => {
-      const health = await service.status();
-      return health.running && health.mode === 'lan-shared' && health.execution?.ready === true;
-    }, '完整控制未就绪；Bridge 和中继管理连接仍保留。');
-    record = { ...record, status: 'completed', stage: 'ready', steps: record.steps.map(step => ({ ...step, status: 'completed' })),
-      message: 'Codex Desktop 已接入 Codex 内核；手机完整控制保持就绪，原任务未自动重发。' };
-  } catch (error) { record = { ...record, status: 'failed', error: error.message,
-    steps: record.steps.map(step => ({ ...step, status: step.status === 'running' ? 'failed' : step.status })),
-    message: 'Codex Desktop 未完成接入，已停止后续步骤。' }; }
-  finally {
-    record.finishedAt = new Date().toISOString(); writeRecord(recordPath(stateRoot), record);
-    if (readRecord(lockPath(stateRoot))?.operationId === operationId) fs.rmSync(lockPath(stateRoot));
-  }
-  return record;
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === script && process.argv[2] === '--worker') {
-  const [stateRoot, operationId] = process.argv.slice(3);
-  (async () => {
-    const deadline = Date.now() + 15000;
-    while (true) {
-      const record = readRecord(recordPath(stateRoot));
-      if (record?.operationId !== operationId || record.status !== 'scheduled') throw new Error('恢复调度已失效。');
-      if (record.worker?.pid === process.pid) break;
-      if (Date.now() >= deadline) throw new Error('恢复启动交接超时。');
-      await delay(100);
-    }
-    // A deliberate handoff window lets the caller display the accepted operation ID.
-    await delay(3000);
-    const result = await runRecovery(stateRoot, operationId);
-    console.log(JSON.stringify({ operationId, status: result.status, stage: result.stage, error: result.error }));
-    process.exit(result.status === 'completed' ? 0 : 1);
-  })().catch(error => { console.error(error.message); process.exit(1); });
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { readRecord, writeRecord, lifecycle } from './service-lifecycle.mjs';
+import { startBackground } from './background-process.mjs';
+import { desktopHost } from './platform/desktop-host.mjs';
+import * as serviceHost from './platform/service-host.mjs';
+import { launchDesktop, portAvailable } from './desktop-launcher.mjs';
+import { configureManagedEnvironment } from './platform/user-environment.mjs';
+
+const script = fileURLToPath(import.meta.url);
+const recordPath = root => path.join(root, 'shared-recovery.json');
+const lockPath = root => path.join(root, 'shared-recovery.lock');
+const sameProcess = (a, b) => a && b && a.pid === b.pid && a.created === b.created && a.executable === b.executable;
+const active = value => value && ['scheduled', 'running'].includes(value.status);
+const recoverySteps = () => [
+  ['checking', '检查启动条件'], ['stopping-desktop', '关闭当前 Codex'],
+  ['starting-app-server', '确认 Codex 内核'], ['starting-desktop', '重新打开 Codex'],
+  ['checking-execution', '确认移动端控制就绪'],
+].map(([id, label]) => ({ id, label, status: 'pending' }));
+export const recoveryWarning = 'Codex Desktop 需要重新打开，才能接入同一个 Codex 内核。移动端连接和 Codex 内核会保持运行；旧 Desktop 实例中的任务可能中断，未发送内容请先保存。切换不会清空项目、对话历史、设置或设备授权。';
+
+export async function recoveryStatus(stateRoot, host = desktopHost) {
+  if (host.desktopIntegration === false) return { status: 'unsupported', message: '此平台尚不支持 Desktop 自动接入。' };
+  const record = readRecord(recordPath(stateRoot));
+  if (!record) return { status: 'none', message: '尚未执行 Desktop 接入流程。' };
+  const lostWorker = active(record) && (record.worker
+    ? !sameProcess(record.worker, await host.process(record.worker.pid))
+    : Date.now() - Date.parse(record.startedAt) > 30000);
+  if (lostWorker) {
+    record.status = 'failed'; record.error = '独立恢复进程已退出，恢复未完成。';
+    record.steps = record.steps?.map(step => ({ ...step, status: step.status === 'running' ? 'failed' : step.status }));
+    writeRecord(recordPath(stateRoot), record);
+    if (readRecord(lockPath(stateRoot))?.operationId === record.operationId) fs.rmSync(lockPath(stateRoot));
+  }
+  const { worker, oldService, desktop, ...publicRecord } = record;
+  return publicRecord;
+}
+
+export async function planRecovery(stateRoot, host, available = portAvailable) {
+  const info = await host.inspect();
+  const action = await host.sharedServiceUrl() ? 'restart' : 'switch';
+  if (!info.desktop) throw new Error('未找到 Codex Desktop；CLI 用户无需执行 Desktop 接入。');
+  const record = readRecord(path.join(stateRoot, 'managed-app-server.json'));
+  const actual = record ? await host.process(record.pid) : null;
+  if (actual && (!sameProcess(record, actual) || !actual.command?.includes('app-server') || !actual.command.includes('ws://127.0.0.1:45839'))) {
+    throw new Error('Codex 内核进程身份与记录不符，未结束任何进程。');
+  }
+  if (!actual && !await available()) throw new Error('45839 被未识别进程占用，未关闭 Desktop 或结束任何进程。');
+  return { desktop: info.desktop, action };
+}
+
+export async function requestRecovery(stateRoot, { confirmed, operationId = randomUUID() } = {}, host = desktopHost) {
+  if (host.desktopIntegration === false) throw new Error('此平台尚不支持 Desktop 自动接入。');
+  if (confirmed !== true) throw new Error(recoveryWarning + ' 请明确确认后再执行。');
+  if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(operationId)) throw new Error('无效的恢复操作编号。');
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const previous = await recoveryStatus(stateRoot, host);
+  if (previous.operationId === operationId) return previous;
+  if (active(previous)) throw new Error('已有恢复操作正在执行，请查看恢复状态。');
+  const planned = await planRecovery(stateRoot, host);
+  let lock;
+  try { lock = fs.openSync(lockPath(stateRoot), 'wx'); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error('已有恢复操作，请先查看恢复状态。'); throw error; }
+  fs.writeFileSync(lock, JSON.stringify({ operationId })); fs.closeSync(lock);
+  const record = { operationId, status: 'scheduled', stage: 'prepared', startedAt: new Date().toISOString(),
+    message: 'Codex 连接请求已接受，电脑管理连接保持运行。', steps: recoverySteps(), ...planned };
+  try {
+    writeRecord(recordPath(stateRoot), record);
+    const log = path.join(stateRoot, 'shared-recovery.log');
+    const pid = await startBackground(process.execPath, [script, '--worker', stateRoot, operationId], process.env, [log, log]);
+    const worker = await host.process(pid);
+    if (!worker) throw new Error('独立恢复进程未启动，请查看 shared-recovery.log。');
+    // Publish the process identity before allowing the worker to begin disruption.
+    writeRecord(recordPath(stateRoot), { ...record, worker });
+    return { operationId, status: record.status, message: record.message };
+  } catch (error) {
+    writeRecord(recordPath(stateRoot), { ...record, status: 'failed', error: error.message });
+    fs.rmSync(lockPath(stateRoot), { force: true }); throw error;
+  }
+}
+
+export async function runRecovery(stateRoot, operationId, dependencies = {}) {
+  const host = dependencies.host || desktopHost;
+  const service = dependencies.service || lifecycle({ stateRoot, host: serviceHost });
+  const available = dependencies.available || portAvailable;
+  const start = dependencies.launch || launchDesktop;
+  let record = readRecord(recordPath(stateRoot));
+  if (record?.operationId !== operationId || readRecord(lockPath(stateRoot))?.operationId !== operationId) throw new Error('恢复实例已失效。');
+  record.steps ||= recoverySteps();
+  const stage = name => {
+    record = { ...record, status: 'running', stage: name, steps: record.steps.map(step => ({ ...step,
+      status: step.id === name ? 'running' : step.status === 'running' ? 'completed' : step.status })) };
+    writeRecord(recordPath(stateRoot), record);
+  };
+  const waitFor = async (check, message) => {
+    const deadline = Date.now() + (dependencies.timeout ?? 10000);
+    while (!await check()) { if (Date.now() >= deadline) throw new Error(message); await delay(100); }
+  };
+  try {
+    stage('checking');
+    const planned = await planRecovery(stateRoot, host, available);
+    await configureManagedEnvironment(stateRoot);
+    record = { ...record, ...planned };
+    if (fs.existsSync(path.join(stateRoot, 'desktop-launch.lock'))) throw new Error('Desktop 正在启动，未与启动操作并行恢复。');
+    stage('stopping-desktop'); await host.closeDesktop(record.desktop);
+    await waitFor(async () => !(await host.inspect()).running, '当前 Codex Desktop 未退出，未继续接入 Codex 内核。');
+    stage('starting-app-server'); await start({ stateRoot, host, recoveryId: operationId, progress: stage });
+    stage('checking-execution');
+    await service.start(); // Refresh the execution adapter; resident Bridge retains its PID and sockets.
+    await waitFor(async () => {
+      const health = await service.status();
+      return health.running && health.mode === 'lan-shared' && health.execution?.ready === true;
+    }, 'Codex 内核未就绪；桌面服务和中继连接仍保留。');
+    record = { ...record, status: 'completed', stage: 'ready', steps: record.steps.map(step => ({ ...step, status: 'completed' })),
+      message: 'Codex Desktop 已接入 Codex 内核；移动端控制保持就绪，原任务未自动重发。' };
+  } catch (error) { record = { ...record, status: 'failed', error: error.message,
+    steps: record.steps.map(step => ({ ...step, status: step.status === 'running' ? 'failed' : step.status })),
+    message: 'Codex Desktop 未完成接入，已停止后续步骤。' }; }
+  finally {
+    record.finishedAt = new Date().toISOString(); writeRecord(recordPath(stateRoot), record);
+    if (readRecord(lockPath(stateRoot))?.operationId === operationId) fs.rmSync(lockPath(stateRoot));
+  }
+  return record;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === script && process.argv[2] === '--worker') {
+  const [stateRoot, operationId] = process.argv.slice(3);
+  (async () => {
+    const deadline = Date.now() + 15000;
+    while (true) {
+      const record = readRecord(recordPath(stateRoot));
+      if (record?.operationId !== operationId || record.status !== 'scheduled') throw new Error('恢复调度已失效。');
+      if (record.worker?.pid === process.pid) break;
+      if (Date.now() >= deadline) throw new Error('恢复启动交接超时。');
+      await delay(100);
+    }
+    // A deliberate handoff window lets the caller display the accepted operation ID.
+    await delay(3000);
+    const result = await runRecovery(stateRoot, operationId);
+    console.log(JSON.stringify({ operationId, status: result.status, stage: result.stage, error: result.error }));
+    process.exit(result.status === 'completed' ? 0 : 1);
+  })().catch(error => { console.error(error.message); process.exit(1); });
+}