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

package/dist/src/platform/posix/runtime-paths.mjs

@@ -0,0 +1,25 @@
+import os from 'node:os';
+import path from 'node:path';
+
+// These are user-owned locations; resolving paths does not create or migrate data.
+export function runtimePaths(environment = process.env, home = os.homedir(), platform = process.platform) {
+  if (!['darwin', 'linux'].includes(platform)) throw new Error(`Unsupported POSIX host: ${platform}`);
+  const join = path.posix.join;
+  const xdgRoot = (name, fallback) => path.posix.isAbsolute(environment[name] || '')
+    ? environment[name] : join(home, fallback);
+  const dataRoot = platform === 'darwin'
+    ? join(home, 'Library', 'Application Support', 'CodexRemote')
+    : join(xdgRoot('XDG_DATA_HOME', '.local/share'), 'CodexRemote');
+  const stateRoot = platform === 'darwin'
+    ? join(dataRoot, 'state')
+    : join(xdgRoot('XDG_STATE_HOME', '.local/state'), 'CodexRemote');
+  const codexDataRoot = environment.CODEX_HOME?.trim() || join(home, '.codex');
+  return {
+    codexDataRoot,
+    sessionsRoot: join(codexDataRoot, 'sessions'),
+    stateRoot,
+    serviceRoot: join(dataRoot, 'service'),
+    uploadsRoot: join(dataRoot, 'attachments'),
+    credentialsRoot: join(dataRoot, 'credentials'),
+  };
+}

package/dist/src/platform/power-inhibitor.mjs

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+// stdin is a lifetime lease: even an abrupt service exit releases the assertion.
+export function launchPowerInhibitor() {
+  const lease = "process.stdin.resume();process.stdin.on('end',()=>process.exit(0));console.log('ready')";
+  let executable, args;
+  if (process.platform === 'darwin') {
+    executable = '/usr/bin/caffeinate';
+    args = ['-i', process.execPath, '-e', lease];
+  } else if (process.platform === 'win32') {
+    executable = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
+    args = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File',
+      fileURLToPath(new URL('./windows/keep-awake.ps1', import.meta.url))];
+  } else if (process.platform === 'linux') {
+    executable = '/usr/bin/systemd-inhibit';
+    args = ['--what=idle', '--mode=block', '--who=Code Relax', '--why=Workstation remote access',
+      process.execPath, '-e', lease];
+  } else throw new Error(`保持唤醒不支持当前系统：${process.platform}`);
+  return spawn(executable, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+}

package/dist/src/platform/project-locations.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('project-locations'));
+export const { projectLocations } = adapter;

package/dist/src/platform/runtime-paths.mjs

@@ -0,0 +1,8 @@
+import { runtimePaths as windowsPaths } from './windows/runtime-paths.mjs';
+import { runtimePaths as posixPaths } from './posix/runtime-paths.mjs';
+
+export function runtimePaths(environment = process.env, home, platform = process.platform) {
+  if (platform === 'win32') return windowsPaths(environment, home);
+  if (platform === 'darwin' || platform === 'linux') return posixPaths(environment, home, platform);
+  throw new Error(`Unsupported workstation platform: ${platform}`);
+}

package/dist/src/platform/select.mjs

@@ -0,0 +1,5 @@
+export function platformModule(name, platform = process.platform) {
+  const directory = { win32: 'windows', darwin: 'macos', linux: 'linux' }[platform];
+  if (!directory) throw new Error(`工作站暂不支持此系统：${platform}`);
+  return new URL(`./${directory}/${name}.mjs`, import.meta.url);
+}

package/dist/src/platform/service-host.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('service-host'));
+export const { sharedServiceUrl, lanAddress, lanNetworks, bridgeEnvironment } = adapter;

package/dist/src/platform/user-environment.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('user-environment'));
+export const { configureManagedEnvironment, clearManagedEnvironment } = adapter;

package/dist/src/platform/windows/IsolatedProcess.cs

@@ -48,8 +48,8 @@ public static class IsolatedProcess {
         if(handle==new IntPtr(-1)) throw new Win32Exception(Marshal.GetLastWin32Error());
         return handle;
     }
-    public static int Start(string executable,string[] arguments,string stdout,string stderr) {
-        IntPtr input=IntPtr.Zero,output=IntPtr.Zero,error=IntPtr.Zero,list=IntPtr.Zero,handles=IntPtr.Zero;
+    public static int Start(string executable,string[] arguments,string stdout,string stderr,string[] environment) {
+        IntPtr input=IntPtr.Zero,output=IntPtr.Zero,error=IntPtr.Zero,list=IntPtr.Zero,handles=IntPtr.Zero,environmentBlock=IntPtr.Zero;
         bool initialized=false;
         try {
             input=File("NUL",true); output=File(String.IsNullOrEmpty(stdout)?"NUL":stdout,false); error=File(String.IsNullOrEmpty(stderr)?"NUL":stderr,false);
@@ -63,12 +63,16 @@ public static class IsolatedProcess {
             startup.startup.flags=0x101; startup.startup.show=0;
             startup.startup.input=input; startup.startup.output=output; startup.startup.error=error; startup.attributes=list;
             var command=new StringBuilder(Quote(executable)); foreach(var argument in arguments) command.Append(' ').Append(Quote(argument));
+            Array.Sort(environment,StringComparer.OrdinalIgnoreCase);
+            var environmentBytes=Encoding.Unicode.GetBytes(String.Join("\0",environment)+"\0\0");
+            environmentBlock=Marshal.AllocHGlobal(environmentBytes.Length); Marshal.Copy(environmentBytes,0,environmentBlock,environmentBytes.Length);
             ProcessInfo info;
-            if(!CreateProcessW(executable,command,IntPtr.Zero,IntPtr.Zero,true,0x80010,IntPtr.Zero,null,ref startup,out info)) throw new Win32Exception(Marshal.GetLastWin32Error());
+            if(!CreateProcessW(executable,command,IntPtr.Zero,IntPtr.Zero,true,0x80410,environmentBlock,null,ref startup,out info)) throw new Win32Exception(Marshal.GetLastWin32Error());
             CloseHandle(info.thread); CloseHandle(info.process); return info.pid;
         } finally {
             if(initialized) DeleteProcThreadAttributeList(list);
             if(list!=IntPtr.Zero) Marshal.FreeHGlobal(list); if(handles!=IntPtr.Zero) Marshal.FreeHGlobal(handles);
+            if(environmentBlock!=IntPtr.Zero) Marshal.FreeHGlobal(environmentBlock);
             if(input!=IntPtr.Zero) CloseHandle(input); if(output!=IntPtr.Zero) CloseHandle(output); if(error!=IntPtr.Zero) CloseHandle(error);
         }
     }

package/dist/src/platform/windows/activate-desktop.ps1

@@ -0,0 +1,49 @@
+param(
+    [Parameter(Mandatory=$true)][string]$Executable,
+    [Parameter(Mandatory=$true)][string]$AppServerUrl
+)
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+if ($AppServerUrl -cnotmatch '^ws://127\.0\.0\.1:([1-9][0-9]{0,4})\z' -or [int]$Matches[1] -gt 65535) { throw 'Invalid managed app-server URL.' }
+$package = Get-AppxPackage OpenAI.Codex | Select-Object -First 1
+if (-not $package -or $Executable -ne (Join-Path $package.InstallLocation 'app/ChatGPT.exe')) {
+    throw 'Desktop executable identity changed; activation stopped.'
+}
+# Packaged activation uses the user's environment, not the worker's env block.
+# Installation already owns and broadcasts this setting. Do not silently launch
+# a separate app-server if it has been removed or changed since installation.
+if ([Environment]::GetEnvironmentVariable('CODEX_APP_SERVER_WS_URL', 'User') -ne $AppServerUrl) {
+    throw 'Desktop app-server environment differs from the workstation; run relax setup to repair it.'
+}
+if ([Environment]::GetEnvironmentVariable('CODEX_APP_SERVER_FORCE_CLI', 'User') -eq '1' -or
+    [Environment]::GetEnvironmentVariable('CODEX_APP_SERVER_FORCE_CLI', 'Machine') -eq '1') {
+    throw 'CODEX_APP_SERVER_FORCE_CLI=1 prevents Desktop from connecting to the workstation.'
+}
+# Activate the registered application so Windows supplies its MSIX identity.
+# Never spawn ChatGPT.exe through the hidden-console broker: a bootstrap failure
+# can leave a windowless Electron singleton blocking subsequent taskbar launches.
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+namespace CodeRelax {
+    [ComImport, Guid("2e941141-7f97-4756-ba1d-9decde894a3d"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    interface IApplicationActivationManager {
+        void ActivateApplication([MarshalAs(UnmanagedType.LPWStr)] string appId,
+            [MarshalAs(UnmanagedType.LPWStr)] string arguments, uint options, out uint processId);
+        void ActivateForFile([MarshalAs(UnmanagedType.LPWStr)] string appId, IntPtr items,
+            [MarshalAs(UnmanagedType.LPWStr)] string verb, out uint processId);
+        void ActivateForProtocol([MarshalAs(UnmanagedType.LPWStr)] string appId, IntPtr items, out uint processId);
+    }
+    public static class DesktopActivation {
+        public static uint Activate(string appId) {
+            object instance = Activator.CreateInstance(Type.GetTypeFromCLSID(new Guid("45BA127D-10A8-46EA-8AB7-56EA9078943C")));
+            try {
+                uint processId;
+                ((IApplicationActivationManager)instance).ActivateApplication(appId, "", 2, out processId);
+                return processId;
+            } finally { Marshal.ReleaseComObject(instance); }
+        }
+    }
+}
+'@
+[CodeRelax.DesktopActivation]::Activate($package.PackageFamilyName + '!App')

package/dist/src/platform/windows/background-process.mjs

@@ -5,9 +5,14 @@ import path from 'node:path';
 export function startWindowsProcess(executable, args, environment, logs = []) {
   return new Promise((resolve, reject) => {
     const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
+    const helperEnvironment = {};
+    for (const name of ['SystemRoot', 'windir', 'LOCALAPPDATA', 'USERPROFILE', 'TEMP', 'TMP', 'PSModulePath']) {
+      const key = Object.keys(process.env).find(item => item.toLowerCase() === name.toLowerCase());
+      if (key) helperEnvironment[key] = process.env[key];
+    }
     const helper = spawn(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File',
       fileURLToPath(new URL('./start-hidden-console.ps1', import.meta.url))], {
-      windowsHide: true, env: environment, stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true, env: helperEnvironment, stdio: ['pipe', 'pipe', 'pipe'],
     });
     let output = '', error = '';
     helper.stdout.setEncoding('utf8').on('data', chunk => { output += chunk; });
@@ -20,6 +25,6 @@ export function startWindowsProcess(executable, args, environment, logs = []) {
       if (!Number.isSafeInteger(pid) || pid <= 0) return reject(new Error('后台启动未返回有效 PID'));
       resolve(pid);
     });
-    helper.stdin.end(JSON.stringify({ executable, args, logs }));
+    helper.stdin.end(JSON.stringify({ brokerExecutable: process.execPath, executable, args, logs, environment }));
   });
 }

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

@@ -0,0 +1,225 @@
+import fs from 'node:fs';
+import { newestRuntime, verifyProtocol } from '../codex-protocol.mjs';
+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);
+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('|');
+export const runtimeFingerprint = fingerprint;
+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());
+}
+
+export async function runtimeInstallationFingerprint() {
+  const installed = await installedDesktopRuntime();
+  return installed ? [installed.package, fingerprint(installed.executable)] : null;
+}
+
+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()];
+}
+
+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 = [];
+  let installed = null;
+  if (!environment.CODE_RELAX_CODEX_PATH) {
+    try { installed = await installedDesktopRuntime(); }
+    catch (error) { throw new Error(`无法确认最新 Codex Desktop 内核，未降级到其他 CLI：${error.message}`); }
+  }
+  for (const candidate of discoverCodex(environment)) {
+    try {
+      if (candidate.source === 'desktop' && !await matchesInstalledDesktop(candidate.executable, installed)) {
+        continue; // Superseded Desktop extraction directories are not installed candidates.
+      }
+      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) { throw new Error(`无法确认 Codex 候选版本，未降级：${candidate.executable}: ${error.message}`); }
+  }
+  if (installed && !candidates.some(candidate => candidate.source === 'desktop')) {
+    throw new Error(`当前 Codex Desktop 内核尚未准备完整，未降级到旧 CLI：${installed.package}。请打开更新后的桌面端完成内核提取。`);
+  }
+  const candidate = newestRuntime(candidates);
+  if (candidate) {
+    try {
+      if (!runtimeFilesAvailable(candidate.executable)) throw new Error('缺少同目录的 codex-code-mode-host.exe');
+      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) { throw new Error(`最新 Codex 内核 ${candidate.version} 校验失败，未降级：${candidate.executable}: ${error.message}`); }
+  }
+  throw new Error('未找到 Codex CLI，请安装或更新 Codex CLI 后执行 relax setup。');
+}