evolcore 0.0.23 → 0.0.24

package/CHANGELOG.md

@@ -3,6 +3,56 @@
 本文件记录 EvolCore 的重要变更。EvolClaw 版本线的历史记录已归档至
 [`docs/_archive/CHANGELOG-evolclaw.md`](docs/_archive/CHANGELOG-evolclaw.md)。
 
+## 0.0.24 (2026-09-14)
+
+### Windows 与 Codex 运行时
+
+- 启动、重启前统一检查 Codex managed hook；
+  缺失时自动安装并验证，异常时保持失败关闭。
+- managed hook 按 thread 凭据分流；
+  非托管 Codex 不再受机器级策略误伤。
+- 凭据可跨 daemon 重启恢复；
+  失效或伪造凭据继续保持失败关闭。
+- 修复 Windows ACL、npm 子进程和安全输出解析；
+  兼容 cmd.exe 包装与跨平台可执行文件查找。
+- 修复 Windows Codex 沙箱配置；
+  提升自启动任务的运行权限。
+- 将 Windows Hook 启动探针并入 `ec diagnose --codex-hook`；
+  不再增加 Hook 热路径入口。
+- 恢复 Codex 会话共享策略并保留 Agent 描述；
+  修复单 runner 与直接 backend key 的解析。
+- Codex 首轮会话在 rollout 可恢复后绑定；
+  审批请求、响应和终态统一记录生命周期审计。
+
+### Agent、AID 与生命周期
+
+- 新增受权限约束的 AID 查询、展示和管理能力。
+- 新增 Agent 创建、委托创建和创建进度管理；
+  统一创建参数与 Base Agent 探测。
+- 完善 Agent 生命周期、Bootstrap、Owner Welcome；
+  收敛会话交接与主会话切换行为。
+- Claude 会话恢复增加 transcript 就绪校验；
+  失效话题提供 `/renew` 恢复提示。
+- 统一 Agent outbox 的 canonical 路径；
+  旧布局首次读写时执行去重导入。
+- 推理心跳与空闲通知状态隔离；
+  修复话题会话命令的回复路由。
+- `ec stats` 支持托管任务和关系角色范围；
+  `ec msg history` 支持管理角色跨对端查询。
+- 自动安装插件，并修复 Evol App 的 Menu 兼容访问。
+
+### AUN、权限与模型
+
+- 增强 AUN 消息可靠投递、去重恢复和群消息处理。
+- 统一远程配对、token 鉴权和 Menu 命令权限边界。
+- 主机支持查询 Base Agent 模型列表；
+  统一模型目录与推理强度回退。
+- 合并模型价格与能力参数表；
+  统一维护价格、上下文窗口和模型能力。
+- `max_tokens` 改用模型真实 `context_window`；
+  未知模型继续使用兼容性默认值。
+- 重启与升级流程改为事务化；
+  编译失败时回滚并保持服务运行。
 ## 0.0.23 (2026-09-08)
 
 ### 会话、Trigger 与 Codex 运行时

package/README.md

@@ -105,7 +105,9 @@ npm install -g evolcore
 
 Linux 全局安装会在 `postinstall` 阶段准备 Codex 受管运行所需的真实目录 `/etc/codex`。如果当前 npm 全局目录属于普通用户且该系统目录尚不存在，请先执行 `sudo install -d -m 0755 /etc/codex`，再重新安装。
 
-Windows 的 npm 安装和升级不会修改机器级 Codex 配置。首次使用 Codex 托管 Hook 需运行上面的 PowerShell 安装器，并批准 Hook 部署步骤的管理员授权；部署完成后，只要 npm 包位置和 Node.js 路径不变，普通 npm 升级无需再次部署。更换 npm prefix 或 Node.js 路径后需重新部署，详见 [Windows Codex 托管 Hook](docs/evolcore-install-script.md#windows-codex-托管-hook)。
+Windows 的 npm 安装和升级不会直接写入机器级 Codex 配置。配置使用 Codex 后，执行 `ec start` 或 `ec restart` 时会自动检测托管 Hook；缺失时自动请求 Windows 管理员授权（UAC），安装并复检成功后继续启动。已安装时直接继续，无需单独执行安装命令，详见 [Windows Codex 托管 Hook](docs/codex-windows-managed-hook.md)。
+
+如果取消 UAC 或安装失败，本次启动或重启会停止；重启检查发生在停止旧服务之前。已有策略异常或安装位置变化需要管理员核对，自动安装不会覆盖这些状态。
 
 > **Windows 用户**：首次运行前可能需要执行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
 

package/bin/codex-managed-acl.ps1

@@ -3,6 +3,7 @@ param([Parameter(Mandatory = $true)][string]$Request)
 # Called by the Node installer. Paths and security descriptors are data, never
 # interpolated into PowerShell source. Use Windows PowerShell's built-in .NET ACL API.
 $ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
 # A parent pwsh session can export its incompatible PowerShell 7 modules.
 # This helper always runs in Windows PowerShell 5.1.
 $env:PSModulePath = Join-Path $PSHOME 'Modules'
@@ -40,7 +41,8 @@ public static class EvolCoreAclProbe {
   [DllImport("advapi32.dll", SetLastError=true)]
   static extern bool GetTokenInformation(IntPtr token, int type, out IntPtr linked, int size, out int returned);
   [DllImport("advapi32.dll", SetLastError=true)]
-  static extern bool DuplicateToken(IntPtr token, int level, out IntPtr duplicate);
+  static extern bool DuplicateTokenEx(IntPtr token, uint desiredAccess, IntPtr tokenAttributes,
+    int impersonationLevel, int tokenType, out IntPtr duplicate);
   [DllImport("advapi32.dll", SetLastError=true)]
   static extern bool AccessCheck(byte[] descriptor, IntPtr token, uint desired,
     ref Mapping mapping, byte[] privileges, ref uint length, out uint granted, out bool allowed);
@@ -60,7 +62,10 @@ public static class EvolCoreAclProbe {
           token = linked;
           TokenKind = "linked-token";
         } else { TokenKind = "current-token"; }
-        if (!DuplicateToken(token, 2, out duplicate))
+        // AccessCheck only needs SecurityIdentification (1). A UAC linked
+        // token can be limited to that level, so requesting the higher
+        // SecurityImpersonation level fails with ERROR_BAD_IMPERSONATION_LEVEL.
+        if (!DuplicateTokenEx(token, 0x0000000A, IntPtr.Zero, 1, 2, out duplicate))
           throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error());
         var mapping = new Mapping { Read=0x120089, Write=0x120116, Execute=0x1200a0, All=0x1f01ff };
         uint length=1024, granted;

package/bin/codex-managed-hook.mjs

@@ -1,12 +1,67 @@
 import fs from 'node:fs';
 import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const startedAt = Date.now();
+const runId = randomUUID();
+let logPath;
+let logFailed = false;
+let context = {};
+
+// This file is also copied into the Linux runtime; keep diagnostics self-contained.
+function diagnostic(event, details = {}) {
+  if (process.env.EVOLCORE_CODEX_HOOK_LOG === '0' || logFailed) return;
+  try {
+    if (!logPath) {
+      logPath = path.resolve(process.env.EVOLCORE_CODEX_HOOK_LOG
+        || path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'log', 'evolcore-hook.jsonl'));
+      fs.mkdirSync(path.dirname(logPath), { recursive: true, mode: 0o700 });
+      // Rotation is best-effort when concurrent tool calls start together.
+      try {
+        if (fs.statSync(logPath).size >= 2 * 1024 * 1024) fs.renameSync(logPath, `${logPath}.1`);
+      } catch {}
+    }
+    fs.appendFileSync(logPath, JSON.stringify({
+      time: new Date().toISOString(), runId, pid: process.pid,
+      elapsedMs: Date.now() - startedAt, event, ...context, ...details,
+    }) + '\n', { mode: 0o600 });
+  } catch (error) {
+    logFailed = true;
+    process.stderr.write(`[evolcore] Hook diagnostic log unavailable (${error?.code || 'unknown'}): ${logPath || '(unresolved)'}\n`);
+  }
+}
+
+function errorDetails(error) {
+  // JSON parser messages and policy reasons can contain tool input. Omit them.
+  return {
+    errorName: error?.name,
+    errorCode: error?.code,
+    syscall: error?.syscall,
+    frames: typeof error?.stack === 'string'
+      ? error.stack.split('\n').filter(line => /^\s+at /.test(line)).slice(0, 6) : undefined,
+  };
+}
+
+process.on('uncaughtExceptionMonitor', error => diagnostic('uncaught_exception', errorDetails(error)));
+process.on('exit', code => diagnostic('exit', { exitCode: code }));
+diagnostic('start', {
+  nodeVersion: process.version, execPath: process.execPath, entrypoint: process.argv[1],
+  argumentCount: Math.max(0, process.argv.length - 2),
+  socketArgumentPresent: Boolean(process.argv[2]),
+  socketEnvironmentPresent: Boolean(process.env.EVOLCORE_INSTANCE_SOCKET),
+  socketArgumentUnexpanded: /^%EVOLCORE_INSTANCE_SOCKET%$/i.test(process.argv[2] || ''),
+  socketSource: process.argv[2] ? 'argument' : process.env.EVOLCORE_INSTANCE_SOCKET ? 'environment' : 'missing',
+});
 
 // Only bound socket establishment. Once connected, the official Codex hook
 // timeout owns the lifetime of this process; an application timeout here would
 // turn /pause into a denial/allow race.
 const connectTimeoutMs = 1500;
 
-function deny(reason) {
+function deny(reason, category) {
+  diagnostic('decision', { decision: 'deny', category });
   process.stdout.write(JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
@@ -21,6 +76,7 @@ function deny(reason) {
 }
 
 function queryDaemon(socketPath, payload) {
+  diagnostic('connect_start', { timeoutMs: connectTimeoutMs });
   return new Promise(resolve => {
     const socket = net.createConnection(socketPath);
     let buffer = '';
@@ -35,24 +91,53 @@ function queryDaemon(socketPath, payload) {
       resolve(value);
     };
     timer = setTimeout(() => {
-      if (!connected) finish(null);
+      if (!connected) {
+        diagnostic('connect_timeout');
+        finish(null);
+      }
     }, connectTimeoutMs);
     timer.unref?.();
-    socket.once('error', () => finish(null));
+    socket.once('error', error => {
+      diagnostic('socket_error', { connected, ...errorDetails(error) });
+      finish(null);
+    });
+    socket.once('close', () => {
+      if (!settled) diagnostic('socket_closed_without_response', { connected, responseBytes: Buffer.byteLength(buffer) });
+    });
     socket.once('connect', () => {
       connected = true;
       clearTimeout(timer);
+      diagnostic('connected');
       socket.write(JSON.stringify(payload) + '\n');
     });
     socket.on('data', chunk => {
       buffer += String(chunk);
       const index = buffer.indexOf('\n');
       if (index < 0) return;
-      try { finish(JSON.parse(buffer.slice(0, index))); } catch { finish(null); }
+      try {
+        const result = JSON.parse(buffer.slice(0, index));
+        diagnostic('response', {
+          ok: result?.ok === true, applicable: result?.applicable === true,
+          decision: ['allow', 'deny'].includes(result?.decision) ? result.decision : 'other',
+          reasonPresent: typeof result?.reason === 'string',
+        });
+        finish(result);
+      } catch (error) {
+        diagnostic('invalid_response', { responseBytes: Buffer.byteLength(buffer), ...errorDetails(error) });
+        finish(null);
+      }
     });
   });
 }
 
+// The Windows managed requirements are machine-wide, so unmanaged Codex
+// processes also reach this hook. EvolCore-owned threads carry a per-thread
+// credential (EVOLCORE_CODEX_SESSION_TOKEN, injected through the thread's
+// shell environment policy); unmanaged ones do not. Unmanaged calls are
+// allowed outright and never contact the daemon — EvolCore being stopped must
+// not break a standalone Codex. Credentialed calls always require an explicit
+// daemon allow: a credential without its daemon is an orphaned managed thread
+// and fails closed.
 async function main() {
   // Windows managed requirements use one machine-wide command. Resolve the
   // per-daemon named pipe from the inherited environment so multiple EvolCore
@@ -61,17 +146,45 @@ async function main() {
   let input;
   try {
     input = JSON.parse(fs.readFileSync(0, 'utf8'));
-  } catch {
-    deny('Invalid Codex PreToolUse payload.');
+  } catch (error) {
+    diagnostic('invalid_input', errorDetails(error));
+    deny('Invalid Codex PreToolUse payload.', 'invalid_input');
     return;
   }
+  context = {
+    sessionId: typeof input?.session_id === 'string' ? input.session_id.slice(0, 128) : undefined,
+    toolName: typeof input?.tool_name === 'string' ? input.tool_name.slice(0, 128) : undefined,
+    callId: typeof (input?.tool_use_id ?? input?.toolUseId ?? input?.item_id ?? input?.itemId) === 'string'
+      ? (input.tool_use_id ?? input.toolUseId ?? input.item_id ?? input.itemId).slice(0, 128) : undefined,
+  };
+  diagnostic('input', {
+    preToolUse: input?.hook_event_name === 'PreToolUse',
+    sessionIdPresent: typeof input?.session_id === 'string' && Boolean(input.session_id),
+    toolNamePresent: typeof input?.tool_name === 'string' && Boolean(input.tool_name),
+    toolInputPresent: input?.tool_input !== undefined,
+  });
   if (!socketPath
     || input?.hook_event_name !== 'PreToolUse'
     || typeof input?.session_id !== 'string'
     || !input.session_id
     || typeof input?.tool_name !== 'string'
     || !input.tool_name) {
-    deny('Incomplete Codex PreToolUse payload.');
+    deny('Incomplete Codex PreToolUse payload.', 'incomplete_input');
+    return;
+  }
+
+  const sessionToken = typeof process.env.EVOLCORE_CODEX_SESSION_TOKEN === 'string'
+    && process.env.EVOLCORE_CODEX_SESSION_TOKEN
+    ? process.env.EVOLCORE_CODEX_SESSION_TOKEN
+    : undefined;
+
+  if (!sessionToken) {
+    // Unmanaged process: nothing to enforce, and no reason to pay the daemon
+    // round-trip (or its outage) for a call we would allow anyway.
+    return;
+  }
+  if (!socketPath) {
+    deny('EvolCore session credential is present but the policy service address is missing.');
     return;
   }
 
@@ -80,16 +193,20 @@ async function main() {
     threadId: input.session_id,
     toolName: input.tool_name,
     toolInput: input.tool_input ?? null,
+    sessionToken,
     ...(typeof (input.tool_use_id ?? input.toolUseId ?? input.item_id ?? input.itemId) === 'string'
       ? { callId: input.tool_use_id ?? input.toolUseId ?? input.item_id ?? input.itemId }
       : {}),
   });
   if (!result) {
-    deny('EvolCore policy service is unavailable.');
+    deny('EvolCore policy service is unavailable.', 'service_unavailable');
+    return;
+  }
+  if (result.ok === true && result.applicable === true && result.decision === 'allow') {
+    diagnostic('decision', { decision: 'allow' });
     return;
   }
-  if (result.ok === true && result.applicable === true && result.decision === 'allow') return;
-  deny(result.reason || 'EvolCore policy did not explicitly allow this tool call.');
+  deny(result.reason || 'EvolCore policy did not explicitly allow this tool call.', 'policy_denied');
 }
 
 void main();

package/bin/ec-safe-output.js

@@ -2,17 +2,95 @@
 import fs from 'fs';
 import path from 'path';
 import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
 
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const EC_EXECUTABLES = new Set(['ec']);
 const HOST_PROCESS_EXECUTABLES = new Set(['ps', 'pgrep', 'pidof', 'kill', 'pkill', 'killall']);
-const HEAD_EXECUTABLE = ['/usr/bin/head', '/bin/head'].find(candidate => {
+const IS_WINDOWS = process.platform === 'win32';
+const HELPER_DIR = path.dirname(fileURLToPath(import.meta.url));
+// A rooted POSIX path is not absolute on Windows: Node resolves `/usr/bin/head`
+// onto the current drive as `C:\usr\bin\head`. Keep these fixed candidates as
+// the trusted fast path where they are genuinely absolute, and discover the
+// executable through PATH everywhere else.
+const POSIX_HEAD_CANDIDATES = ['/usr/bin/head', '/bin/head'];
+
+function isRegularFile(candidate) {
   try {
     return fs.statSync(candidate).isFile();
   } catch {
     return false;
   }
-});
+}
+
+function pathExtensionCandidates() {
+  if (!IS_WINDOWS) return [''];
+  const configured = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .map(value => value.trim())
+    .filter(Boolean);
+  // The extensionless name is tried first so an explicitly named file wins over
+  // a same-named shim; npm publishes both `ec` (sh) and `ec.cmd` on Windows.
+  return ['', ...configured];
+}
+
+/**
+ * Resolve one executable to an absolute path without invoking a shell.
+ * `spawn` performs no PATH or PATHEXT lookup on Windows, which is why a bare
+ * command name has to be materialized here before the child is started.
+ */
+function resolveExecutablePath(executable) {
+  if (executable.includes('/') || executable.includes('\\')) {
+    return isRegularFile(executable) ? path.resolve(executable) : undefined;
+  }
+  const entries = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const entry of entries) {
+    for (const extension of pathExtensionCandidates()) {
+      const candidate = path.join(entry, `${executable}${extension}`);
+      if (isRegularFile(candidate)) return path.resolve(candidate);
+    }
+  }
+  return undefined;
+}
+
+function resolveHeadExecutable() {
+  if (!IS_WINDOWS) {
+    const fixed = POSIX_HEAD_CANDIDATES.find(isRegularFile);
+    if (fixed) return fixed;
+  }
+  return resolveExecutablePath('head');
+}
+
+const HEAD_EXECUTABLE = resolveHeadExecutable();
+
+/**
+ * Resolve the concrete process for a validated payload.
+ *
+ * For `ec`, prefer this package's own Node entrypoint next to the helper. It is
+ * the same installation that published this file, needs no PATH lookup, and
+ * avoids the Windows batch shim entirely — `CreateProcess` cannot execute a
+ * `.cmd` wrapper, so `spawn('ec')` fails with ENOENT there.
+ */
+function resolveChildProcessCommand(payload) {
+  if (payload.kind === 'ec') {
+    const nodeEntrypoint = path.join(HELPER_DIR, 'ec.js');
+    // On Windows CreateProcess cannot execute the npm `.cmd` shim reliably,
+    // so prefer this package's Node entrypoint. POSIX hosts can resolve the
+    // trusted `ec` executable normally; this also preserves caller-provided
+    // PATH shims used by isolated runtimes and tests.
+    if (IS_WINDOWS && isRegularFile(nodeEntrypoint)) {
+      return { file: process.execPath, args: [nodeEntrypoint, ...payload.argv.slice(1)] };
+    }
+  }
+  const resolved = resolveExecutablePath(payload.argv[0]);
+  if (!resolved) fail(`unable to resolve executable: ${payload.argv[0]}`);
+  // Quoting rules for batch files differ from CreateProcess argument parsing,
+  // so a `.cmd`/`.bat` target could execute something other than this argv.
+  if (IS_WINDOWS && /\.(?:cmd|bat)$/i.test(resolved)) {
+    fail(`refusing to run a batch wrapper: ${resolved}`);
+  }
+  return { file: resolved, args: payload.argv.slice(1) };
+}
 
 function fail(message) {
   process.stderr.write(`ec-safe-output: ${message}\n`);
@@ -143,6 +221,9 @@ if (!validateCommand(payload)) fail('command is not permitted');
 if (!validateStdinOnlyHeadArgs(payload.headArgs)) fail('head may only consume stdin');
 if (payload.headArgs !== undefined && !HEAD_EXECUTABLE) fail('trusted head executable is unavailable');
 
+// Resolve the child executable before anything with a side effect: an
+// unresolvable command must not leave an empty create-only output file behind.
+const childCommand = resolveChildProcessCommand(payload);
 const paths = resolveExecutionPaths(payload);
 const output = openOutputFile(payload, paths);
 let bytesWritten = 0;
@@ -182,10 +263,11 @@ if (head) {
   head.stdin.on('error', () => {});
 }
 
-const child = spawn(payload.argv[0], payload.argv.slice(1), {
+const child = spawn(childCommand.file, childCommand.args, {
   cwd: paths.cwd,
   env: process.env,
   stdio: ['ignore', 'pipe', payload.mergeStderr ? 'pipe' : 'inherit'],
+  windowsHide: IS_WINDOWS,
 });
 const sourceStreams = [child.stdout, ...(payload.mergeStderr ? [child.stderr] : [])];
 if (head) {

package/bin/install-codex-managed-hooks.mjs

@@ -18,6 +18,10 @@ function argument(name) {
   return index >= 0 ? process.argv[index + 1] : undefined;
 }
 
+function hasArgument(name) {
+  return process.argv.includes(name);
+}
+
 function fail(message) {
   process.stderr.write(`[evolcore] ${message}\n`);
   process.exit(1);
@@ -91,6 +95,14 @@ function windowsCommandArg(value) {
   return `"${value.replaceAll('"', '\\"')}"`;
 }
 
+function windowsPostinstallNotice() {
+  if (process.platform !== 'win32') return;
+  process.stderr.write(
+    '[evolcore] ec start/restart automatically checks and installs missing Codex managed hooks on Windows.\n'
+    + '[evolcore] Accept the Windows administrator (UAC) prompt when installation is needed; no separate setup command is required.\n',
+  );
+}
+
 function removeManagedBlock(source) {
   const original = parseToml(source);
   if (!source.includes(markerStart) && !source.includes(markerEnd)) return source;
@@ -498,12 +510,11 @@ export function provisionManagedFiles(options, acl = windowsAcl) {
 }
 
 function main() {
-  // npm may preserve its parent lifecycle variable on Windows when this
-  // script is spawned from a test runner. A global install without an
-  // explicit package root is still the postinstall shape; never enter the
-  // machine provisioning branch on an ordinary Windows lifecycle.
-  if (lifecycleEvent() === 'postinstall' || (isGlobalInstall() && !argument('--package-root'))) {
+  // An explicit package root selects provisioning, even if the elevated
+  // child inherited npm lifecycle variables. Ordinary postinstall skips it.
+  if (!argument('--package-root') && (lifecycleEvent() === 'postinstall' || isGlobalInstall())) {
     runLinuxPostinstall();
+    windowsPostinstallNotice();
     return;
   }
   if (process.platform === 'linux' && argument('--mountpoint')) {
@@ -522,7 +533,7 @@ function main() {
   for (const file of [sourceHook, nodePath]) {
     if (!fs.statSync(file).isFile()) fail(`Required Hook runtime file was not found: ${file}`);
   }
-  if (argument('--repair')) {
+  if (hasArgument('--repair')) {
     const result = repairManagedHookInstallation({ requirements, managedDir: targetDirectory, packageRoot, nodePath });
     process.stdout.write(`${JSON.stringify(result)}\n`);
     return;

package/dist/agents/baseagent-availability.js

@@ -1,4 +1,4 @@
-import { resolveCommandPath } from '../utils/cross-platform.js';
+import { commandExists } from '../utils/cross-platform.js';
 import { getCodexAppServerAvailability } from './codex-runner.js';
 export const BASEAGENT_CANDIDATES = ['claude', 'codex', 'gemini', 'ecagent'];
 export const AUTO_BASEAGENT_CANDIDATES = ['claude', 'codex', 'gemini'];
@@ -13,12 +13,12 @@ export function detectAvailableBaseagents(codexAvailability = getCodexAppServerA
             return true;
         if (baseagent === 'codex')
             return codexAvailability.available;
-        return resolveCommandPath(baseagent) !== null;
+        return commandExists(baseagent);
     });
 }
 export function detectBaseagentDetails(codexAvailability = getCodexAppServerAvailability()) {
-    const claude = resolveCommandPath('claude') !== null;
-    const gemini = resolveCommandPath('gemini') !== null;
+    const claude = commandExists('claude');
+    const gemini = commandExists('gemini');
     return [
         {
             id: 'claude',

package/dist/agents/baseagent.js

@@ -12,7 +12,35 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { commandExists } from '../utils/cross-platform.js';
+import { commandExists, isWindows, resolveProbePath } from '../utils/cross-platform.js';
+import { execFileSync } from 'child_process';
+/** Resolve the installed Codex CLI entrypoint, including npm shims on Windows. */
+export function resolveCodexCliPath() {
+    return resolveProbePath('codex');
+}
+export function resolveCodexLaunchCommand(args, options = {}) {
+    const windows = options.isWindows ?? isWindows;
+    const commandPath = options.commandPath !== undefined ? options.commandPath : resolveCodexCliPath();
+    if (!commandPath)
+        return null;
+    if (windows && /\.(cmd|bat)$/i.test(commandPath)) {
+        return { command: options.comSpec ?? process.env.ComSpec ?? 'cmd.exe', args: ['/d', '/s', '/c', commandPath, ...args] };
+    }
+    return { command: commandPath, args };
+}
+/** Execute a Codex CLI command using the resolved npm shim/path. */
+export function execCodexCliSync(args, options) {
+    const commandPath = resolveCodexCliPath();
+    if (!commandPath)
+        throw new Error('Codex CLI not found');
+    const launchCommand = resolveCodexLaunchCommand(args, { commandPath });
+    if (!launchCommand)
+        throw new Error('Codex CLI not found');
+    return execFileSync(launchCommand.command, launchCommand.args, {
+        ...(options ?? {}),
+        windowsHide: isWindows,
+    });
+}
 const BASEAGENT_ALIASES = {
     claude: { canonical: 'claude', displayName: 'Claude Code' },
     cc: { canonical: 'claude', displayName: 'Claude Code' },