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

package/dist/src/platform/windows/codex-runtime.mjs

@@ -1,251 +1,253 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { createRequire } from 'node:module';
-import { execFile } from 'node:child_process';
-import { createHash, randomUUID } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-import { promisify } from 'node:util';
-import { readRecord, writeRecord } from '../../service-lifecycle.mjs';
-
-const exec = promisify(execFile);
-const requiredMethods = ['thread/start', 'thread/resume', 'thread/list', 'thread/turns/list',
-  'thread/items/list', 'turn/start', 'turn/steer', 'turn/interrupt', 'model/list', 'project/list',
-  'thread/settings/update', 'configRequirements/read', 'thread/queue/list', 'thread/queue/add',
-  'thread/queue/delete', 'thread/queue/start', 'thread/read', 'thread/unsubscribe', 'config/read', 'account/rateLimits/read'];
-export const codeModeHostPath = executable => path.join(path.dirname(executable), 'codex-code-mode-host.exe');
-export const runtimeFilesAvailable = executable => fs.existsSync(executable) && fs.existsSync(codeModeHostPath(executable));
-const fingerprint = executable => [executable, codeModeHostPath(executable)]
-  .map(file => { const s = fs.statSync(file); return `${s.size}:${s.mtimeMs}`; }).join('|');
-const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
-const desktopRuntimeScript = path.join(path.dirname(fileURLToPath(import.meta.url)), 'desktop-runtime.ps1');
-
-async function fileHash(file) {
-  const hash = createHash('sha256');
-  for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
-  return hash.digest('hex');
-}
-
-async function installedDesktopRuntime() {
-  const { stdout } = await exec(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
-    '-File', desktopRuntimeScript], { windowsHide: true, encoding: 'utf8', timeout: 30000 });
-  return JSON.parse(stdout.trim());
-}
-
-async function matchesInstalledDesktop(executable, installed) {
-  if (!installed || !runtimeFilesAvailable(executable) || !runtimeFilesAvailable(installed.executable)) return false;
-  const files = [[executable, installed.executable], [codeModeHostPath(executable), installed.codeModeHost]];
-  for (const [candidate, bundled] of files) {
-    if (fs.statSync(candidate).size !== fs.statSync(bundled).size || await fileHash(candidate) !== await fileHash(bundled)) return false;
-  }
-  return true;
-}
-
-function runtimeFiles(directory, relative = '') {
-  const files = [];
-  for (const entry of fs.readdirSync(path.join(directory, relative), { withFileTypes: true })) {
-    const name = path.join(relative, entry.name);
-    if (entry.isDirectory()) files.push(...runtimeFiles(directory, name));
-    else if (entry.isFile()) files.push(name);
-    else throw new Error(`Codex 内核目录包含不支持的文件类型：${name}`);
-  }
-  return files.sort();
-}
-
-function runtimeDirectories(files) {
-  const directories = new Set();
-  for (const file of files) {
-    let directory = path.dirname(file);
-    while (directory !== '.') { directories.add(directory); directory = path.dirname(directory); }
-  }
-  return [...directories].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
-}
-
-async function retainDesktopRuntime(executable, installed, stateRoot) {
-  if (!/^[\w.-]+$/.test(installed.package)) throw new Error('Codex Desktop 安装包名称无效。');
-  const source = path.dirname(executable);
-  const files = runtimeFiles(source);
-  if (files.includes('runtime.json')) throw new Error('Codex 内核目录与保留清单文件名冲突。');
-  const directories = runtimeDirectories(files);
-  const root = path.join(stateRoot, 'desktop-runtimes');
-  const target = path.join(root, installed.package);
-  const retained = path.join(target, 'codex.exe');
-  if (fs.existsSync(target)) {
-    const manifest = readRecord(path.join(target, 'runtime.json'));
-    if (manifest?.package !== installed.package || JSON.stringify(manifest.files) !== JSON.stringify(files)
-      || JSON.stringify(runtimeFiles(target)) !== JSON.stringify([...files, 'runtime.json'].sort())
-      || !await matchesInstalledDesktop(retained, installed)) {
-      throw new Error(`已保留的 Codex 内核文件不完整：${target}`);
-    }
-    return retained;
-  }
-  fs.mkdirSync(root, { recursive: true });
-  const staging = path.join(root, `.${installed.package}.${randomUUID()}.tmp`);
-  fs.mkdirSync(staging);
-  const created = [];
-  try {
-    for (const directory of directories) fs.mkdirSync(path.join(staging, directory));
-    for (const name of files) {
-      const from = path.join(source, name), to = path.join(staging, name);
-      created.push(to);
-      try { fs.linkSync(from, to); }
-      catch (error) {
-        if (error.code !== 'EXDEV') throw error;
-        fs.copyFileSync(from, to);
-      }
-    }
-    if (!await matchesInstalledDesktop(path.join(staging, 'codex.exe'), installed)) {
-      throw new Error('保留的 Codex 内核与当前安装包不一致。');
-    }
-    const manifestPath = path.join(staging, 'runtime.json');
-    writeRecord(manifestPath, { package: installed.package, files });
-    created.push(manifestPath);
-    fs.renameSync(staging, target);
-    return retained;
-  } catch (error) {
-    for (const file of created) fs.rmSync(file, { force: true });
-    for (const directory of directories.reverse()) {
-      const nested = path.join(staging, directory);
-      if (fs.existsSync(nested)) fs.rmdirSync(nested);
-    }
-    fs.rmdirSync(staging);
-    throw error;
-  }
-}
-
-export function pruneRetainedDesktopRuntimes(stateRoot, keepExecutable) {
-  const root = path.join(stateRoot, 'desktop-runtimes');
-  if (!fs.existsSync(root)) return;
-  const keep = path.resolve(path.dirname(keepExecutable)).toLowerCase();
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !/^OpenAI\.Codex_[\w.-]+$/.test(entry.name)) continue;
-    const directory = path.join(root, entry.name);
-    if (path.resolve(directory).toLowerCase() === keep || fs.lstatSync(directory).isSymbolicLink()) continue;
-    const manifest = readRecord(path.join(directory, 'runtime.json'));
-    const files = manifest?.files;
-    if (manifest?.package !== entry.name || !Array.isArray(files) || !files.includes('codex.exe')
-      || !files.includes('codex-code-mode-host.exe') || new Set(files).size !== files.length
-      || !files.every(name => typeof name === 'string' && name !== 'runtime.json'
-        && path.resolve(directory, name).toLowerCase().startsWith(`${path.resolve(directory).toLowerCase()}${path.sep}`))) continue;
-    const expected = [...files, 'runtime.json'].sort();
-    if (JSON.stringify(runtimeFiles(directory)) !== JSON.stringify(expected)) continue;
-    if (!fs.lstatSync(path.join(directory, 'runtime.json')).isFile()
-      || !files.every(name => fs.lstatSync(path.join(directory, name)).isFile())) continue;
-    for (const name of files) fs.unlinkSync(path.join(directory, name));
-    fs.unlinkSync(path.join(directory, 'runtime.json'));
-    for (const name of runtimeDirectories(files).reverse()) fs.rmdirSync(path.join(directory, name));
-    fs.rmdirSync(directory);
-  }
-}
-
-// Resolve native binaries, never execute a shell shim from a background task.
-export function discoverCodex(environment = process.env) {
-  const found = new Map();
-  const add = (file, source) => {
-    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return;
-    const executable = fs.realpathSync(file);
-    if (!found.has(executable.toLowerCase()) || source === 'desktop') found.set(executable.toLowerCase(), { executable, source });
-  };
-  if (environment.CODE_RELAX_CODEX_PATH) {
-    const file = environment.CODE_RELAX_CODEX_PATH;
-    if (!path.isAbsolute(file) || path.basename(file).toLowerCase() !== 'codex.exe') throw new Error('CODE_RELAX_CODEX_PATH 必须是 codex.exe 的绝对路径。');
-    add(file, 'explicit');
-    if (!found.size) throw new Error('CODE_RELAX_CODEX_PATH 指定的程序不存在。');
-    return [...found.values()];
-  }
-  const local = environment.LOCALAPPDATA || path.join(os.homedir(), 'AppData/Local');
-  const home = environment.CODEX_HOME || path.join(os.homedir(), '.codex');
-  const directories = [...String(environment.PATH || environment.Path || '').split(';').filter(Boolean),
-    environment.CODEX_INSTALL_DIR, path.join(local, 'Programs/OpenAI/Codex/bin'),
-    path.join(home, 'packages/standalone/current/bin')].filter(Boolean);
-  for (const directory of directories) {
-    add(path.join(directory, 'codex.exe'), 'cli');
-    const packageFile = path.join(directory, 'node_modules/@openai/codex/package.json');
-    if (!fs.existsSync(packageFile)) continue;
-    const root = path.dirname(fs.realpathSync(packageFile));
-    let vendor = path.join(root, 'vendor');
-    try { vendor = path.join(path.dirname(createRequire(packageFile).resolve('@openai/codex-win32-x64/package.json')), 'vendor'); }
-    catch (error) { if (error.code !== 'MODULE_NOT_FOUND') throw error; }
-    add(path.join(vendor, 'x86_64-pc-windows-msvc/bin/codex.exe'), 'npm');
-  }
-  const desktopRoot = path.join(local, 'OpenAI/Codex/bin');
-  add(path.join(desktopRoot, 'codex.exe'), 'desktop');
-  if (fs.existsSync(desktopRoot)) for (const entry of fs.readdirSync(desktopRoot, { withFileTypes: true })) {
-    if (entry.isDirectory()) add(path.join(desktopRoot, entry.name, 'codex.exe'), 'desktop');
-  }
-  return [...found.values()];
-}
-
-function compareVersions(a, b) {
-  const parse = v => v.split(/[.-]/).map(part => /^\d+$/.test(part) ? Number(part) : part);
-  const aa = parse(a), bb = parse(b);
-  for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
-    if (aa[i] === bb[i]) continue;
-    if (aa[i] === undefined) return 1;
-    if (bb[i] === undefined) return -1;
-    return typeof aa[i] === 'number' && typeof bb[i] === 'number' ? aa[i] - bb[i] : String(aa[i]).localeCompare(String(bb[i]));
-  }
-  return 0;
-}
-
-async function verifyProtocol(executable, stateRoot) {
-  const directory = fs.mkdtempSync(path.join(stateRoot, 'cli-schema-'));
-  try {
-    await exec(executable, ['app-server', 'generate-json-schema', '--experimental', '--out', directory],
-      { windowsHide: true, timeout: 30000, maxBuffer: 4 * 1024 * 1024 });
-    const request = fs.readFileSync(path.join(directory, 'ClientRequest.json'), 'utf8');
-    const missing = requiredMethods.filter(method => !request.includes(`"${method}"`));
-    const turns = fs.readFileSync(path.join(directory, 'v2/ThreadTurnsListParams.json'), 'utf8');
-    if (!turns.includes('"itemsView"') || !turns.includes('"summary"')) missing.push('turn summary pagination');
-    if (missing.length) throw new Error(`缺少协议能力：${missing.join(', ')}`);
-  } finally {
-    const remove = dir => {
-      for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
-        const file = path.join(dir, item.name);
-        if (item.isDirectory()) remove(file); else fs.unlinkSync(file);
-      }
-      fs.rmdirSync(dir);
-    };
-    remove(directory);
-  }
-}
-
-export async function resolveCodexRuntime(stateRoot, { refresh = false, environment = process.env } = {}) {
-  fs.mkdirSync(stateRoot, { recursive: true });
-  const recordFile = path.join(stateRoot, 'codex-runtime.json');
-  const saved = readRecord(recordFile);
-  environment = { ...environment,
-    CODEX_HOME: environment.CODEX_HOME || saved?.codexHome || path.join(os.homedir(), '.codex'),
-    CODE_RELAX_CODEX_PATH: environment.CODE_RELAX_CODEX_PATH || (saved?.source === 'explicit' ? saved.executable : '') };
-  if (!refresh && saved?.executable && runtimeFilesAvailable(saved.executable)
-    && saved.fingerprint === fingerprint(saved.executable)) return saved;
-  const candidates = [], rejected = [];
-  let installed = null;
-  try { installed = await installedDesktopRuntime(); }
-  catch (error) { rejected.push(`无法读取当前 Codex Desktop 安装包：${error.message}`); }
-  for (const candidate of discoverCodex(environment)) {
-    try {
-      if (!runtimeFilesAvailable(candidate.executable)) throw new Error('缺少同目录的 codex-code-mode-host.exe');
-      if (candidate.source === 'desktop' && !await matchesInstalledDesktop(candidate.executable, installed)) {
-        throw new Error('不是当前 Codex Desktop 安装包配套的 CLI');
-      }
-      const { stdout } = await exec(candidate.executable, ['--version'], { windowsHide: true, timeout: 10000 });
-      const version = /^codex-cli (\d+\.\d+\.\d+(?:-[\w.]+)?)/m.exec(stdout)?.[1];
-      if (!version) throw new Error('无法识别版本');
-      candidates.push({ ...candidate, version });
-    } catch (error) { rejected.push(`${candidate.executable}: ${error.message}`); }
-  }
-  candidates.sort((a, b) => Number(b.source === 'desktop') - Number(a.source === 'desktop') || compareVersions(b.version, a.version));
-  for (const candidate of candidates) {
-    try {
-      const executable = candidate.source === 'desktop'
-        ? await retainDesktopRuntime(candidate.executable, installed, stateRoot) : candidate.executable;
-      await verifyProtocol(executable, stateRoot);
-      const result = { ...candidate, executable, fingerprint: fingerprint(executable),
-        codexHome: path.resolve(environment.CODEX_HOME || path.join(os.homedir(), '.codex')) };
-      writeRecord(recordFile, result);
-      return result;
-    } catch (error) { rejected.push(`${candidate.executable}: ${error.message}`); }
-  }
-  throw new Error(`未找到兼容的 Codex CLI，请安装或更新 Codex CLI 后执行 relax setup。${rejected.length ? '\n' + rejected.join('\n') : ''}`);
-}
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { readRecord, writeRecord } from '../../service-lifecycle.mjs';
+
+const exec = promisify(execFile);
+const requiredMethods = ['thread/start', 'thread/resume', 'thread/list', 'thread/turns/list',
+  'thread/items/list', 'turn/start', 'turn/steer', 'turn/interrupt', 'model/list', 'project/list',
+  'project/create', 'project/update', 'project/move',
+  'fs/getMetadata', 'fs/readDirectory', 'fs/createDirectory', 'command/exec',
+  'thread/settings/update', 'configRequirements/read', 'thread/queue/list', 'thread/queue/add',
+  'thread/queue/delete', 'thread/queue/start', 'thread/read', 'thread/unsubscribe', 'config/read', 'account/rateLimits/read'];
+export const codeModeHostPath = executable => path.join(path.dirname(executable), 'codex-code-mode-host.exe');
+export const runtimeFilesAvailable = executable => fs.existsSync(executable) && fs.existsSync(codeModeHostPath(executable));
+const fingerprint = executable => [executable, codeModeHostPath(executable)]
+  .map(file => { const s = fs.statSync(file); return `${s.size}:${s.mtimeMs}`; }).join('|');
+const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
+const desktopRuntimeScript = path.join(path.dirname(fileURLToPath(import.meta.url)), 'desktop-runtime.ps1');
+
+async function fileHash(file) {
+  const hash = createHash('sha256');
+  for await (const chunk of fs.createReadStream(file)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function installedDesktopRuntime() {
+  const { stdout } = await exec(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+    '-File', desktopRuntimeScript], { windowsHide: true, encoding: 'utf8', timeout: 30000 });
+  return JSON.parse(stdout.trim());
+}
+
+async function matchesInstalledDesktop(executable, installed) {
+  if (!installed || !runtimeFilesAvailable(executable) || !runtimeFilesAvailable(installed.executable)) return false;
+  const files = [[executable, installed.executable], [codeModeHostPath(executable), installed.codeModeHost]];
+  for (const [candidate, bundled] of files) {
+    if (fs.statSync(candidate).size !== fs.statSync(bundled).size || await fileHash(candidate) !== await fileHash(bundled)) return false;
+  }
+  return true;
+}
+
+function runtimeFiles(directory, relative = '') {
+  const files = [];
+  for (const entry of fs.readdirSync(path.join(directory, relative), { withFileTypes: true })) {
+    const name = path.join(relative, entry.name);
+    if (entry.isDirectory()) files.push(...runtimeFiles(directory, name));
+    else if (entry.isFile()) files.push(name);
+    else throw new Error(`Codex 内核目录包含不支持的文件类型：${name}`);
+  }
+  return files.sort();
+}
+
+function runtimeDirectories(files) {
+  const directories = new Set();
+  for (const file of files) {
+    let directory = path.dirname(file);
+    while (directory !== '.') { directories.add(directory); directory = path.dirname(directory); }
+  }
+  return [...directories].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
+}
+
+async function retainDesktopRuntime(executable, installed, stateRoot) {
+  if (!/^[\w.-]+$/.test(installed.package)) throw new Error('Codex Desktop 安装包名称无效。');
+  const source = path.dirname(executable);
+  const files = runtimeFiles(source);
+  if (files.includes('runtime.json')) throw new Error('Codex 内核目录与保留清单文件名冲突。');
+  const directories = runtimeDirectories(files);
+  const root = path.join(stateRoot, 'desktop-runtimes');
+  const target = path.join(root, installed.package);
+  const retained = path.join(target, 'codex.exe');
+  if (fs.existsSync(target)) {
+    const manifest = readRecord(path.join(target, 'runtime.json'));
+    if (manifest?.package !== installed.package || JSON.stringify(manifest.files) !== JSON.stringify(files)
+      || JSON.stringify(runtimeFiles(target)) !== JSON.stringify([...files, 'runtime.json'].sort())
+      || !await matchesInstalledDesktop(retained, installed)) {
+      throw new Error(`已保留的 Codex 内核文件不完整：${target}`);
+    }
+    return retained;
+  }
+  fs.mkdirSync(root, { recursive: true });
+  const staging = path.join(root, `.${installed.package}.${randomUUID()}.tmp`);
+  fs.mkdirSync(staging);
+  const created = [];
+  try {
+    for (const directory of directories) fs.mkdirSync(path.join(staging, directory));
+    for (const name of files) {
+      const from = path.join(source, name), to = path.join(staging, name);
+      created.push(to);
+      try { fs.linkSync(from, to); }
+      catch (error) {
+        if (error.code !== 'EXDEV') throw error;
+        fs.copyFileSync(from, to);
+      }
+    }
+    if (!await matchesInstalledDesktop(path.join(staging, 'codex.exe'), installed)) {
+      throw new Error('保留的 Codex 内核与当前安装包不一致。');
+    }
+    const manifestPath = path.join(staging, 'runtime.json');
+    writeRecord(manifestPath, { package: installed.package, files });
+    created.push(manifestPath);
+    fs.renameSync(staging, target);
+    return retained;
+  } catch (error) {
+    for (const file of created) fs.rmSync(file, { force: true });
+    for (const directory of directories.reverse()) {
+      const nested = path.join(staging, directory);
+      if (fs.existsSync(nested)) fs.rmdirSync(nested);
+    }
+    fs.rmdirSync(staging);
+    throw error;
+  }
+}
+
+export function pruneRetainedDesktopRuntimes(stateRoot, keepExecutable) {
+  const root = path.join(stateRoot, 'desktop-runtimes');
+  if (!fs.existsSync(root)) return;
+  const keep = path.resolve(path.dirname(keepExecutable)).toLowerCase();
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^OpenAI\.Codex_[\w.-]+$/.test(entry.name)) continue;
+    const directory = path.join(root, entry.name);
+    if (path.resolve(directory).toLowerCase() === keep || fs.lstatSync(directory).isSymbolicLink()) continue;
+    const manifest = readRecord(path.join(directory, 'runtime.json'));
+    const files = manifest?.files;
+    if (manifest?.package !== entry.name || !Array.isArray(files) || !files.includes('codex.exe')
+      || !files.includes('codex-code-mode-host.exe') || new Set(files).size !== files.length
+      || !files.every(name => typeof name === 'string' && name !== 'runtime.json'
+        && path.resolve(directory, name).toLowerCase().startsWith(`${path.resolve(directory).toLowerCase()}${path.sep}`))) continue;
+    const expected = [...files, 'runtime.json'].sort();
+    if (JSON.stringify(runtimeFiles(directory)) !== JSON.stringify(expected)) continue;
+    if (!fs.lstatSync(path.join(directory, 'runtime.json')).isFile()
+      || !files.every(name => fs.lstatSync(path.join(directory, name)).isFile())) continue;
+    for (const name of files) fs.unlinkSync(path.join(directory, name));
+    fs.unlinkSync(path.join(directory, 'runtime.json'));
+    for (const name of runtimeDirectories(files).reverse()) fs.rmdirSync(path.join(directory, name));
+    fs.rmdirSync(directory);
+  }
+}
+
+// Resolve native binaries, never execute a shell shim from a background task.
+export function discoverCodex(environment = process.env) {
+  const found = new Map();
+  const add = (file, source) => {
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return;
+    const executable = fs.realpathSync(file);
+    if (!found.has(executable.toLowerCase()) || source === 'desktop') found.set(executable.toLowerCase(), { executable, source });
+  };
+  if (environment.CODE_RELAX_CODEX_PATH) {
+    const file = environment.CODE_RELAX_CODEX_PATH;
+    if (!path.isAbsolute(file) || path.basename(file).toLowerCase() !== 'codex.exe') throw new Error('CODE_RELAX_CODEX_PATH 必须是 codex.exe 的绝对路径。');
+    add(file, 'explicit');
+    if (!found.size) throw new Error('CODE_RELAX_CODEX_PATH 指定的程序不存在。');
+    return [...found.values()];
+  }
+  const local = environment.LOCALAPPDATA || path.join(os.homedir(), 'AppData/Local');
+  const home = environment.CODEX_HOME || path.join(os.homedir(), '.codex');
+  const directories = [...String(environment.PATH || environment.Path || '').split(';').filter(Boolean),
+    environment.CODEX_INSTALL_DIR, path.join(local, 'Programs/OpenAI/Codex/bin'),
+    path.join(home, 'packages/standalone/current/bin')].filter(Boolean);
+  for (const directory of directories) {
+    add(path.join(directory, 'codex.exe'), 'cli');
+    const packageFile = path.join(directory, 'node_modules/@openai/codex/package.json');
+    if (!fs.existsSync(packageFile)) continue;
+    const root = path.dirname(fs.realpathSync(packageFile));
+    let vendor = path.join(root, 'vendor');
+    try { vendor = path.join(path.dirname(createRequire(packageFile).resolve('@openai/codex-win32-x64/package.json')), 'vendor'); }
+    catch (error) { if (error.code !== 'MODULE_NOT_FOUND') throw error; }
+    add(path.join(vendor, 'x86_64-pc-windows-msvc/bin/codex.exe'), 'npm');
+  }
+  const desktopRoot = path.join(local, 'OpenAI/Codex/bin');
+  add(path.join(desktopRoot, 'codex.exe'), 'desktop');
+  if (fs.existsSync(desktopRoot)) for (const entry of fs.readdirSync(desktopRoot, { withFileTypes: true })) {
+    if (entry.isDirectory()) add(path.join(desktopRoot, entry.name, 'codex.exe'), 'desktop');
+  }
+  return [...found.values()];
+}
+
+function compareVersions(a, b) {
+  const parse = v => v.split(/[.-]/).map(part => /^\d+$/.test(part) ? Number(part) : part);
+  const aa = parse(a), bb = parse(b);
+  for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+    if (aa[i] === bb[i]) continue;
+    if (aa[i] === undefined) return 1;
+    if (bb[i] === undefined) return -1;
+    return typeof aa[i] === 'number' && typeof bb[i] === 'number' ? aa[i] - bb[i] : String(aa[i]).localeCompare(String(bb[i]));
+  }
+  return 0;
+}
+
+async function verifyProtocol(executable, stateRoot) {
+  const directory = fs.mkdtempSync(path.join(stateRoot, 'cli-schema-'));
+  try {
+    await exec(executable, ['app-server', 'generate-json-schema', '--experimental', '--out', directory],
+      { windowsHide: true, timeout: 30000, maxBuffer: 4 * 1024 * 1024 });
+    const request = fs.readFileSync(path.join(directory, 'ClientRequest.json'), 'utf8');
+    const missing = requiredMethods.filter(method => !request.includes(`"${method}"`));
+    const turns = fs.readFileSync(path.join(directory, 'v2/ThreadTurnsListParams.json'), 'utf8');
+    if (!turns.includes('"itemsView"') || !turns.includes('"summary"')) missing.push('turn summary pagination');
+    if (missing.length) throw new Error(`缺少协议能力：${missing.join(', ')}`);
+  } finally {
+    const remove = dir => {
+      for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+        const file = path.join(dir, item.name);
+        if (item.isDirectory()) remove(file); else fs.unlinkSync(file);
+      }
+      fs.rmdirSync(dir);
+    };
+    remove(directory);
+  }
+}
+
+export async function resolveCodexRuntime(stateRoot, { refresh = false, environment = process.env } = {}) {
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const recordFile = path.join(stateRoot, 'codex-runtime.json');
+  const saved = readRecord(recordFile);
+  environment = { ...environment,
+    CODEX_HOME: environment.CODEX_HOME || saved?.codexHome || path.join(os.homedir(), '.codex'),
+    CODE_RELAX_CODEX_PATH: environment.CODE_RELAX_CODEX_PATH || (saved?.source === 'explicit' ? saved.executable : '') };
+  if (!refresh && saved?.executable && runtimeFilesAvailable(saved.executable)
+    && saved.fingerprint === fingerprint(saved.executable)) return saved;
+  const candidates = [], rejected = [];
+  let installed = null;
+  try { installed = await installedDesktopRuntime(); }
+  catch (error) { rejected.push(`无法读取当前 Codex Desktop 安装包：${error.message}`); }
+  for (const candidate of discoverCodex(environment)) {
+    try {
+      if (!runtimeFilesAvailable(candidate.executable)) throw new Error('缺少同目录的 codex-code-mode-host.exe');
+      if (candidate.source === 'desktop' && !await matchesInstalledDesktop(candidate.executable, installed)) {
+        throw new Error('不是当前 Codex Desktop 安装包配套的 CLI');
+      }
+      const { stdout } = await exec(candidate.executable, ['--version'], { windowsHide: true, timeout: 10000 });
+      const version = /^codex-cli (\d+\.\d+\.\d+(?:-[\w.]+)?)/m.exec(stdout)?.[1];
+      if (!version) throw new Error('无法识别版本');
+      candidates.push({ ...candidate, version });
+    } catch (error) { rejected.push(`${candidate.executable}: ${error.message}`); }
+  }
+  candidates.sort((a, b) => Number(b.source === 'desktop') - Number(a.source === 'desktop') || compareVersions(b.version, a.version));
+  for (const candidate of candidates) {
+    try {
+      const executable = candidate.source === 'desktop'
+        ? await retainDesktopRuntime(candidate.executable, installed, stateRoot) : candidate.executable;
+      await verifyProtocol(executable, stateRoot);
+      const result = { ...candidate, executable, fingerprint: fingerprint(executable),
+        codexHome: path.resolve(environment.CODEX_HOME || path.join(os.homedir(), '.codex')) };
+      writeRecord(recordFile, result);
+      return result;
+    } catch (error) { rejected.push(`${candidate.executable}: ${error.message}`); }
+  }
+  throw new Error(`未找到兼容的 Codex CLI，请安装或更新 Codex CLI 后执行 relax setup。${rejected.length ? '\n' + rejected.join('\n') : ''}`);
+}