@walkhi/code-relax 0.1.0-beta.1

package/dist/src/shared-app-server.mjs

@@ -0,0 +1,356 @@
+import WebSocket from 'ws';
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import events from '../shared/app-server-events.cjs';
+import serverRequests from '../shared/server-requests.cjs';
+
+const syncTokenTtlMs = 30_000;
+const syncBufferMaxBytes = 8 * 1024 * 1024;
+const writerConflictMessages = ['already has an active writer', 'already has a live local writer'];
+
+export class ThreadWriterConflictError extends Error {
+  constructor(threadId, message) {
+    super('该对话正在另一个 Codex 实例中使用。');
+    this.name = 'ThreadWriterConflictError';
+    this.code = 'thread_writer_owned_elsewhere';
+    this.threadId = threadId;
+    this.readOnly = true;
+    this.details = message;
+  }
+}
+
+export function isThreadWriterConflict(error) {
+  const message = String(error?.message || error).toLowerCase();
+  return error instanceof ThreadWriterConflictError || writerConflictMessages.some(text => message.includes(text));
+}
+
+// Connect to the Desktop's existing execution service; never spawn or adopt a task.
+export class SharedAppServer extends EventEmitter {
+  constructor(url) {
+    super();
+    const address = new URL(url);
+    if (address.protocol !== 'ws:' || address.hostname !== '127.0.0.1') throw new Error('完整控制必须使用本机回环 WebSocket。');
+    this.url = url;
+    this.epoch = randomUUID();
+    this.sequence = 0;
+    this.pending = new Map();
+    this.serverRequests = new serverRequests.Store(randomUUID(), id => this.emit('requests-changed', id));
+    this.threads = new Map();
+    this.contexts = new Map();
+    this.settingsNotifications = new Map();
+    this.permissionOptions = new events.PermissionOptionsCache();
+    this.subscriptions = new Map();
+    this.usageCache = new events.UsageCache(value => this.emit('usage', value));
+  }
+
+  async connect() {
+    if (this.socket?.readyState === WebSocket.OPEN && this.ready) return;
+    if (this.connecting) return this.connecting;
+    this.connecting = this.open().finally(() => { this.connecting = null; });
+    return this.connecting;
+  }
+
+  async open() {
+    const socket = new WebSocket(this.url, { handshakeTimeout: 5000 });
+    this.socket = socket;
+    this.ready = false;
+    this.serverRequests.reset(randomUUID());
+    socket.on('message', bytes => {
+      let message;
+      try { message = JSON.parse(bytes.toString()); } catch { socket.close(); return; }
+      if (message.method && message.id !== undefined) { this.serverRequests.receive(message); return; }
+      if (message.method) { this.notification(message.method, message.params || {}); return; }
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) {
+        const text = String(message.error.message || 'app-server 请求失败');
+        pending.reject(writerConflictMessages.some(value => text.toLowerCase().includes(value))
+          ? new ThreadWriterConflictError(pending.threadId, text)
+          : Object.assign(new Error(text), { rpcCode: message.error.code, details: message.error.data }));
+      }
+      else pending.resolve(message.result);
+    });
+    socket.on('close', () => {
+      this.ready = false;
+      for (const pending of this.pending.values()) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error('完整控制连接断开；发送结果可能未确认，请检查对话后再操作。'));
+      }
+      this.pending.clear();
+      this.serverRequests.reset(randomUUID());
+      this.threads.clear();
+      for (const slot of this.subscriptions.values()) clearTimeout(slot.expiry);
+      this.subscriptions.clear();
+      this.contexts.clear();
+      this.settingsNotifications.clear();
+      this.permissionOptions.clear();
+      this.usageCache.reset();
+      this.emit('disconnected');
+    });
+    socket.on('error', () => {}); // open/request reports the connection error to the caller.
+    await new Promise((resolve, reject) => { socket.once('open', resolve); socket.once('error', reject); });
+    try {
+      await this.request('initialize', { clientInfo: { name: 'codex_remote_shared', version: '1.0.0' }, capabilities: { experimentalApi: true } });
+      socket.send(JSON.stringify({ method: 'initialized' }));
+      this.ready = true;
+      this.usageCache.read(() => this.request('account/rateLimits/read')).catch(error => this.emit('usage-error', error));
+    } catch (error) { socket.close(); throw error; }
+  }
+
+  request(method, params) {
+    const id = ++this.sequence;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} 超时；不会自动重发，请先检查对话。`));
+      }, 30000);
+      this.pending.set(id, { resolve, reject, timer, threadId: params?.threadId });
+      this.socket.send(JSON.stringify({ id, method, params }), error => {
+        if (!error || !this.pending.delete(id)) return;
+        clearTimeout(timer); reject(error);
+      });
+    });
+  }
+
+  async projects() {
+    await this.connect();
+    return events.readProjects((method, params) => this.request(method, params));
+  }
+
+  async send(args) {
+    await this.connect();
+    this.requireWritable(args.threadId);
+    // Reading the live thread checks this service owns it without resume changing settings.
+    const { thread } = await this.request('thread/read', { threadId: args.threadId, includeTurns: false });
+    const status = typeof thread.status === 'string' ? thread.status : thread.status?.type;
+    if (status === 'active') {
+      const live = await this.request('thread/read', { threadId: args.threadId, includeTurns: true });
+      const active = live.thread.turns?.findLast(turn => turn.status === 'inProgress');
+      if (!active) throw new Error('活动轮次已变化，请刷新后再发送。');
+      return this.request('turn/steer', { threadId: args.threadId, expectedTurnId: active.id, input: args.input, ...(args.clientUserMessageId ? { clientUserMessageId: args.clientUserMessageId } : {}) });
+    }
+    return this.request('turn/start', args);
+  }
+
+  respondApproval(threadId, body) {
+    if (!this.ready || this.socket?.readyState !== WebSocket.OPEN) throw new Error('完整控制未连接');
+    this.requireWritable(threadId);
+    return this.serverRequests.respond(threadId, body, message => new Promise((resolve, reject) => {
+      this.socket.send(JSON.stringify(message), error => error ? reject(error) : resolve());
+    }));
+  }
+
+  notification(method, params) {
+    this.serverRequests.notification(method, params);
+    this.emit('notification', { method, params });
+    if (method === 'thread/queue/changed') { this.emit('queue-changed', params.threadId); return; }
+    if (method === 'account/rateLimits/updated') { this.usageCache.update(params); return; }
+    const id = params.threadId;
+    if (method === 'thread/settings/updated') {
+      const settings = params.threadSettings;
+      this.contexts.set(id, { ...this.contexts.get(id), model: settings.model, thinking: settings.effort, serviceTier: settings.serviceTier ?? null,
+        cwd: settings.cwd, ...events.permissionState(settings) });
+      this.settingsNotifications.set(id, settings);
+      this.emit('settings', id);
+      return;
+    }
+    if (method === 'thread/tokenUsage/updated') {
+      this.contexts.set(id, { ...this.contexts.get(id), tokenUsage: params.tokenUsage });
+      return;
+    }
+    const record = this.threads.get(id);
+    if (!record) return;
+    const turn = events.applyNotification(record.thread, method, params);
+    if (turn) {
+      const sequence = ++record.sequence;
+      record.changes.set(turn.id, { sequence, turn });
+      record.changeBytes += Buffer.byteLength(JSON.stringify({ method, params }));
+      if (record.changeBytes > syncBufferMaxBytes) {
+        record.recoverAfter = sequence;
+        record.changes.clear(); record.changeBytes = 0;
+      }
+      this.emit('turn', { thread: record.thread, turn, sequence,
+        immediate: ['turn/completed', 'item/completed'].includes(method) });
+    }
+    if (method === 'turn/completed') record.thread.turns = record.thread.turns.slice(-10);
+  }
+
+  async timeline(threadId) {
+    await this.connect();
+    const slot = this.slot(threadId);
+    const task = slot.tail.then(async () => {
+      let record = this.threads.get(threadId);
+      if (record?.readOnly) {
+        this.threads.delete(threadId);
+        this.contexts.delete(threadId);
+        record = null;
+      }
+      if (!record) {
+        let result;
+        try {
+          result = await this.request('thread/resume', { threadId, excludeTurns: true,
+            initialTurnsPage: { limit: 10, sortDirection: 'desc', itemsView: 'full' } });
+        } catch (error) {
+          if (!isThreadWriterConflict(error)) throw error;
+          const read = await this.request('thread/read', { threadId, includeTurns: true });
+          const turns = Array.isArray(read.thread?.turns) ? read.thread.turns.slice(-10) : [];
+          const thread = { ...read.thread, turns, readOnly: true,
+            readOnlyReason: '该对话正在另一个 Codex 实例中使用。' };
+          record = { thread, nextCursor: null, sequence: 0, recoverAfter: 0,
+            changes: new Map(), changeBytes: 0, tokens: new Map(), readOnly: true };
+          this.threads.set(threadId, record);
+          result = null;
+        }
+        if (result) {
+          if (!Array.isArray(result.initialTurnsPage?.data)) throw new Error('完整控制未返回分页历史。');
+          const thread = { ...result.thread, turns: [...result.initialTurnsPage.data].reverse() };
+          record = { thread, nextCursor: result.initialTurnsPage.nextCursor ?? null, sequence: 0,
+            recoverAfter: 0, changes: new Map(), changeBytes: 0, tokens: new Map() };
+          this.threads.set(threadId, record);
+          this.contexts.set(threadId, { ...this.contexts.get(threadId), model: result.model, thinking: result.reasoningEffort, serviceTier: result.serviceTier ?? null,
+            cwd: result.cwd, ...events.permissionState(result) });
+        }
+      }
+      const id = randomUUID(), expires = Date.now() + syncTokenTtlMs;
+      record.tokens.set(id, { sequence: record.sequence, expires });
+      this.scheduleCleanup(threadId, slot);
+      return { thread: record.thread, nextCursor: record.nextCursor,
+        sync: { id, epoch: this.epoch, seq: record.sequence } };
+    });
+    slot.tail = task.catch(() => {});
+    task.catch(() => {
+      if (!slot.users && !this.threads.has(threadId) && this.subscriptions.get(threadId) === slot) {
+        clearTimeout(slot.expiry);
+        this.subscriptions.delete(threadId);
+      }
+    });
+    return task;
+  }
+
+  slot(threadId) {
+    let slot = this.subscriptions.get(threadId);
+    if (!slot) { slot = { users: 0, tail: Promise.resolve(), expiry: null }; this.subscriptions.set(threadId, slot); }
+    return slot;
+  }
+
+  scheduleCleanup(threadId, slot) {
+    clearTimeout(slot.expiry);
+    const record = this.threads.get(threadId);
+    const expiries = record ? [...record.tokens.values()].map(token => token.expires) : [];
+    const next = expiries.length ? Math.max(1, Math.min(...expiries) - Date.now()) : 1;
+    slot.expiry = setTimeout(() => this.cleanup(threadId, slot), next);
+  }
+
+  cleanup(threadId, slot) {
+    const record = this.threads.get(threadId), now = Date.now();
+    if (record) for (const [id, token] of record.tokens) if (token.expires <= now) record.tokens.delete(id);
+    if (slot.users) { clearTimeout(slot.expiry); slot.expiry = null; return; }
+    if (record?.tokens.size) { this.scheduleCleanup(threadId, slot); return; }
+    slot.tail = slot.tail.then(async () => {
+      if (slot.users || this.threads.get(threadId)?.tokens.size) return;
+      this.threads.delete(threadId); this.contexts.delete(threadId); this.permissionOptions.delete(threadId);
+      this.subscriptions.delete(threadId); clearTimeout(slot.expiry);
+      if (this.ready && !record?.readOnly) await this.request('thread/unsubscribe', { threadId });
+      this.serverRequests.forget(threadId);
+    }).catch(error => this.emit('subscription-error', error));
+  }
+
+  async acquire(threadId, requested) {
+    const slot = this.slot(threadId);
+    let record = this.threads.get(threadId), token;
+    if (record && requested?.epoch === this.epoch && requested.id && Number.isSafeInteger(requested.after)) {
+      token = record.tokens.get(requested.id);
+      if (!token || token.expires <= Date.now() || token.sequence !== requested.after) token = undefined;
+    }
+    let snapshot = false, catchup;
+    if (!record || !token) {
+      const fresh = await this.timeline(threadId);
+      record = this.threads.get(threadId); token = record.tokens.get(fresh.sync.id);
+      requested = { id: fresh.sync.id, epoch: fresh.sync.epoch, after: fresh.sync.seq };
+      snapshot = true;
+    }
+    slot.users++; record.tokens.delete(requested.id); clearTimeout(slot.expiry);
+    const current = record.sequence;
+    if (!snapshot && requested.after < record.recoverAfter) snapshot = true;
+    if (!snapshot && current > requested.after) {
+      const turns = [...record.changes.values()].filter(change => change.sequence > requested.after)
+        .sort((left, right) => record.thread.turns.findIndex(turn => turn.id === left.turn.id)
+          - record.thread.turns.findIndex(turn => turn.id === right.turn.id)).map(change => change.turn);
+      catchup = { thread: { ...record.thread, turns },
+        sync: { id: requested.id, epoch: this.epoch, fromSeq: requested.after + 1, toSeq: current } };
+    }
+    const release = () => {
+      slot.users--;
+      this.cleanup(threadId, slot);
+      return slot.tail;
+    };
+    return { record: { thread: record.thread, nextCursor: record.nextCursor,
+      sync: { id: requested.id, epoch: this.epoch, seq: current, ...(snapshot ? { reset: true } : {}) } },
+      snapshot, catchup, release };
+  }
+
+  async history(threadId, cursor) {
+    await this.connect();
+    if (!cursor) throw new Error('缺少历史分页游标。');
+    const result = await this.request('thread/turns/list', { threadId, cursor, limit: 10, sortDirection: 'desc', itemsView: 'full' });
+    return { thread: { id: threadId, turns: [...result.data].reverse() }, nextCursor: result.nextCursor ?? null };
+  }
+
+  async interrupt(threadId, turnId) {
+    await this.connect();
+    this.requireWritable(threadId);
+    return this.request('turn/interrupt', { threadId, turnId });
+  }
+
+  async models() {
+    await this.connect();
+    const models = []; let cursor;
+    do {
+      const result = await this.request('model/list', { limit: 100, ...(cursor ? { cursor } : {}) });
+      models.push(...result.data); cursor = result.nextCursor;
+    } while (cursor);
+    const config = await this.request('config/read', { includeLayers: false });
+    return { models: models.filter(model => !model.hidden), enabledReasoningEfforts: config.config?.desktop?.['enabled-reasoning-efforts'] ?? null };
+  }
+
+  async usage() {
+    await this.connect();
+    return this.usageCache.read(() => this.request('account/rateLimits/read'));
+  }
+
+  async settings(threadId, model, effort, serviceTier) {
+    await this.connect();
+    this.requireWritable(threadId);
+    await events.updateSettings((method, params) => this.request(method, params), this.contexts, this.settingsNotifications, threadId, model, effort, serviceTier);
+    return this.context(threadId);
+  }
+
+  async permissions(threadId, mode) {
+    await this.connect();
+    this.requireWritable(threadId);
+    await events.updatePermissions((method, params) => this.request(method, params), this.contexts, this.settingsNotifications, this.permissionOptions, threadId, mode);
+    return this.context(threadId);
+  }
+
+  async readContext(threadId) {
+    const context = this.contexts.get(threadId);
+    if (context) await this.permissionOptions.read((method, params) => this.request(method, params), threadId, context);
+    return this.context(threadId);
+  }
+
+  context(threadId) {
+    const context = this.permissionOptions.context(threadId, this.contexts.get(threadId) || {}), usage = context.tokenUsage;
+    const usedTokens = usage?.last?.totalTokens, contextWindow = usage?.modelContextWindow;
+    return { ...context, available: Boolean(contextWindow), usedTokens, contextWindow,
+      usedPercent: contextWindow ? 100 * usedTokens / contextWindow : 0 };
+  }
+
+  requireWritable(threadId) {
+    const record = this.threads.get(threadId);
+    if (record?.readOnly) throw new ThreadWriterConflictError(threadId, record.thread.readOnlyReason);
+  }
+
+  close() { this.socket?.close(); }
+}

package/dist/src/shared-catalog.mjs

@@ -0,0 +1,60 @@
+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);
+}
+
+// Native IDs remain stable when optional Desktop presentation data arrives.
+export class SharedCatalog {
+  constructor(server, desktop) { this.server = server; this.desktop = desktop; }
+
+  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' }));
+    const ordered = this.desktop.snapshot?.projects || [];
+    const key = value => value.replace(/^\\\\\?\\/, '').replaceAll('\\', '/').replace(/\/+$/, '').toLowerCase();
+    const ranks = new Map(ordered.filter(p => p.hostId === 'local').map((p, i) => [key(p.path || ''), i]));
+    projects.sort((a, b) => (ranks.get(key(a.path)) ?? Infinity) - (ranks.get(key(b.path)) ?? Infinity));
+    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,
+      status: typeof thread.status === 'string' ? thread.status : thread.status?.type || 'unknown',
+      activeFlags: threadActiveFlags(thread.status) }));
+    const listing = this.desktop.snapshot?.listing;
+    const byId = new Map(summaries.map(thread => [thread.id, thread]));
+    const pinnedThreads = (listing?.pinnedThreads || []).filter(t => t.hostId === 'local' && byId.has(t.id)).map(t => byId.get(t.id));
+    const pinned = new Set(pinnedThreads.map(t => t.id));
+    const ranks = new Map((listing?.threads || []).filter(t => t.hostId === 'local').map((t, i) => [t.id, i]));
+    const rest = summaries.filter(t => !pinned.has(t.id));
+    rest.sort((a, b) => (ranks.get(a.id) ?? Infinity) - (ranks.get(b.id) ?? Infinity));
+    return { projects, pinnedThreads, threads: rest };
+  }
+}
+
+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

@@ -0,0 +1,142 @@
+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); });
+}

package/dist/src/shared-thread-stream.mjs

@@ -0,0 +1,80 @@
+// Event-driven subscription adapter. Normal desktop-tool polling remains in its own adapter.
+import timelineSync from '../shared/timeline-sync.cjs';
+const threadListNotificationMethods = new Set([
+  'thread/started', 'thread/status/changed', 'thread/name/updated',
+  'thread/archived', 'thread/unarchived', 'thread/deleted',
+  'thread/project/updated', 'project/changed', 'turn/started', 'turn/completed',
+]);
+export async function streamSharedThread(response, threadId, client, normalize, requestedSync, known) {
+  response.startEvents();
+  let closed = false, timer, subscription, streamReady = false;
+  const pending = new Map(), sentTurns = new Map();
+  let fromSeq, toSeq, syncId = requestedSync?.id, epoch = requestedSync?.epoch;
+  let finish;
+  const done = new Promise(resolve => { finish = resolve; });
+  const emit = (name, value) => { if (!closed) response.event(name, value); };
+  const flush = () => {
+    clearTimeout(timer); timer = null;
+    const record = client.threads.get(threadId);
+    if (!streamReady || !record || !pending.size) return;
+    const base = normalize({ thread: { ...record.thread, turns: [] }, sync: { id: syncId, epoch, fromSeq, toSeq } });
+    const turns = [], turnPatches = [];
+    for (const turn of pending.values()) {
+      const normalized = normalize({ thread: { ...record.thread, turns: [turn] } }).turns[0];
+      const patch = timelineSync.diffTurn(sentTurns.get(turn.id), normalized);
+      if (patch) turnPatches.push(patch); else turns.push(normalized);
+      sentTurns.set(turn.id, normalized);
+    }
+    emit('update', { ...base, turns, ...(turnPatches.length ? { turnPatches } : {}) });
+    pending.clear();
+    fromSeq = toSeq = undefined;
+  };
+  const onTurn = ({ thread, turn, sequence, immediate }) => {
+    if (thread.id !== threadId) return;
+    if (!fromSeq) fromSeq = sequence;
+    toSeq = sequence;
+    pending.set(turn.id, turn);
+    if (immediate) flush(); else if (!timer) timer = setTimeout(flush, 50);
+  };
+  const onSettings = id => { if (id === threadId) emit('settings', client.context(id)); };
+  const onRequests = id => { if (id === threadId) emit('approvals', { requests: client.serverRequests.list(threadId) }); };
+  const onQueue = id => { if (id === threadId) emit('queue-changed', {}); };
+  const onNotification = ({ method, params }) => {
+    if (!threadListNotificationMethods.has(method)) return;
+    emit('thread-list-changed', { method, threadId: params.threadId || params.thread?.id || '' });
+  };
+  const onDisconnected = () => { emit('bridge-error', { error: '完整控制已断开，请重新连接。' }); response.end(); finish(); };
+  response.once('close', () => { closed = true; finish(); });
+  client.on('turn', onTurn); client.on('settings', onSettings); client.on('disconnected', onDisconnected);
+  client.on('queue-changed', onQueue);
+  client.on('requests-changed', onRequests);
+  client.on('notification', onNotification);
+  try {
+    subscription = await client.acquire(threadId, requestedSync);
+    syncId = subscription.record.sync.id; epoch = subscription.record.sync.epoch;
+    streamReady = true;
+    if (!closed) {
+      const normalized = normalize(subscription.record);
+      const latest = normalized.turns.at(-1);
+      const unchanged = subscription.snapshot && known?.turnId && known.turnId === latest?.id
+        && known.updatedAt > 0 && known.updatedAt === Number(normalized.thread.updatedAt)
+        && normalized.thread.status === 'idle' && latest?.status !== 'inProgress'
+        && known.turnStatus && known.turnStatus !== 'inProgress';
+      if (subscription.snapshot) emit('update', unchanged ? { ...normalized, turns: [], notModified: true } : normalized);
+      else if (subscription.catchup) emit('update', normalize(subscription.catchup));
+      for (const turn of normalized.turns) sentTurns.set(turn.id, turn);
+      emit('queue-changed', {});
+      onRequests(threadId);
+      flush();
+    }
+    await done;
+  } catch (error) { emit('bridge-error', { error: error.message }); response.end(); }
+  finally {
+    clearTimeout(timer);
+    client.off('turn', onTurn); client.off('settings', onSettings); client.off('disconnected', onDisconnected);
+    client.off('queue-changed', onQueue);
+    client.off('requests-changed', onRequests);
+    client.off('notification', onNotification);
+    if (subscription) await subscription.release();
+  }
+}