evolcore 0.0.21 → 0.0.23

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

@@ -3,10 +3,15 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+import { parse as parseToml } from 'smol-toml';
 
 const markerStart = '# BEGIN EVOLCORE MANAGED CODEX HOOK';
 const markerEnd = '# END EVOLCORE MANAGED CODEX HOOK';
+const aclScript = fileURLToPath(new URL('./codex-managed-acl.ps1', import.meta.url));
 
 function argument(name) {
   const index = process.argv.indexOf(name);
@@ -22,6 +27,11 @@ function isGlobalInstall() {
   return ['1', 'true'].includes(String(process.env.npm_config_global || '').toLowerCase());
 }
 
+function lifecycleEvent() {
+  const entry = Object.entries(process.env).find(([key]) => key.toLowerCase() === 'npm_lifecycle_event');
+  return String(entry?.[1] || '').toLowerCase();
+}
+
 function ensureRealDirectory(directory) {
   let stat;
   try {
@@ -82,14 +92,38 @@ function windowsCommandArg(value) {
 }
 
 function removeManagedBlock(source) {
-  const expression = new RegExp(`\\n?${markerStart}[\\s\\S]*?${markerEnd}\\n?`, 'g');
-  return source.replace(expression, '\n').replace(/\n{3,}/g, '\n\n');
+  const original = parseToml(source);
+  if (!source.includes(markerStart) && !source.includes(markerEnd)) return source;
+  const unsafe = () => new Error('Ambiguous EvolCore managed Hook markers in requirements.toml. Existing configuration was not modified.');
+  const expression = new RegExp(`^${markerStart}\\r?\\n[\\s\\S]*?^${markerEnd}(?:\\r?\\n|$)`, 'gm');
+  const matches = [...source.matchAll(expression)];
+  if (matches.length !== 1 || source.split(markerStart).length !== 2 || source.split(markerEnd).length !== 2) throw unsafe();
+  const block = parseToml(matches[0][0]);
+  const groups = block.hooks?.PreToolUse;
+  if (!Array.isArray(groups) || groups.length !== 1
+    || !isDeepStrictEqual(block, { hooks: { PreToolUse: groups } })) throw unsafe();
+  const content = source.replace(matches[0][0], '');
+  const retained = parseToml(content);
+  const originalGroups = original.hooks?.PreToolUse;
+  if (!Array.isArray(originalGroups)) throw unsafe();
+  // Markers inside a TOML string are not comments. Prove that removing the
+  // block removes only its Hook group, with every other policy unchanged.
+  const safe = originalGroups.some((group, index) => {
+    if (!isDeepStrictEqual(group, groups[0])) return false;
+    const expected = structuredClone(original);
+    expected.hooks.PreToolUse.splice(index, 1);
+    if (!expected.hooks.PreToolUse.length && !retained.hooks?.PreToolUse) delete expected.hooks.PreToolUse;
+    if (!Object.keys(expected.hooks).length && !retained.hooks) delete expected.hooks;
+    return isDeepStrictEqual(expected, retained);
+  });
+  if (!safe) throw unsafe();
+  return content;
 }
 
 function tableBounds(lines, table) {
   const header = table ? `[${table}]` : null;
   const start = header
-    ? lines.findIndex(line => line.trim() === header)
+    ? lines.findIndex(line => line.trim() === header || line.trim().startsWith(`${header} #`))
     : -1;
   if (table && start < 0) return null;
   const from = table ? start + 1 : 0;
@@ -127,51 +161,9 @@ function setTomlKey(source, table, key, value) {
   return lines.join('\n');
 }
 
-function atomicReplace(file, temporary) {
-  try {
-    fs.renameSync(temporary, file);
-    return;
-  } catch (error) {
-    if (error?.code !== 'EEXIST' && error?.code !== 'EPERM') throw error;
-  }
-  const backup = `${file}.evolcore-backup-${process.pid}-${Date.now()}`;
-  fs.renameSync(file, backup);
-  try {
-    fs.renameSync(temporary, file);
-  } catch (error) {
-    try { fs.renameSync(backup, file); } catch {}
-    throw error;
-  }
-  try { fs.rmSync(backup, { force: true }); } catch {}
-}
-
-function atomicWrite(file, content) {
-  const temporary = `${file}.evolcore-${process.pid}-${Date.now()}.tmp`;
-  try {
-    fs.writeFileSync(temporary, content, { encoding: 'utf8', mode: 0o440, flag: 'wx' });
-    atomicReplace(file, temporary);
-  } finally {
-    try { fs.rmSync(temporary, { force: true }); } catch {}
-  }
-}
-
-function restrictWindowsAcl(target) {
-  if (process.platform !== 'win32') return;
-  // Keep the hook and requirements administrator-owned while allowing the
-  // daemon's normal user token to read and execute them.
-  execFileSync('icacls.exe', [
-    target,
-    '/inheritance:r',
-    '/grant:r',
-    '*S-1-5-18:(OI)(CI)F',
-    '*S-1-5-32-544:(OI)(CI)F',
-    '*S-1-5-32-545:(OI)(CI)RX',
-  ], { stdio: 'ignore' });
-}
-
-function managedHookLauncher(packageRoot) {
-  // Keep the machine-wide entrypoint stable across npm upgrades. The app
-  // npm upgrades replace the package contents at this stable global path, so
+export function managedHookLauncher(packageRoot) {
+  // Keep the machine-wide entrypoint stable across npm upgrades. Those
+  // upgrades replace the package contents at this stable global path, so
   // this file never needs to be rewritten just because the hook changed.
   const trustedPackageRoot = path.resolve(packageRoot);
   return `#!/usr/bin/env node
@@ -191,47 +183,18 @@ try {
 `;
 }
 
-function main() {
-  if (process.env.npm_lifecycle_event === 'postinstall') {
-    runLinuxPostinstall();
-    return;
-  }
-  if (process.platform === 'linux' && argument('--mountpoint')) {
-    runLinuxPostinstall();
-    return;
-  }
-  if (process.platform !== 'win32' && !argument('--requirements')) {
-    fail('Codex managed hook provisioning is only supported on Windows.');
-  }
-  const packageRoot = argument('--package-root');
-  const nodePath = argument('--node-path') || process.execPath;
-  const requirements = argument('--requirements')
-    || path.join(process.env.ProgramData || path.join(os.homedir(), 'ProgramData'), 'OpenAI', 'Codex', 'requirements.toml');
-  if (!packageRoot) fail('--package-root is required.');
-  const existingRequirements = fs.existsSync(requirements) ? fs.readFileSync(requirements, 'utf8') : '';
-  const targetDirectory = argument('--managed-dir')
-    || path.join(path.dirname(requirements), 'EvolCore', 'hooks');
-  const sourceHook = path.join(packageRoot, 'bin', 'codex-managed-hook.mjs');
-  if (!fs.existsSync(sourceHook) || !fs.statSync(sourceHook).isFile()) fail(`Codex PreToolUse hook source was not found: ${sourceHook}`);
-
-  fs.mkdirSync(targetDirectory, { recursive: true, mode: 0o700 });
-  const hookPath = path.join(targetDirectory, 'pre-tool-use.mjs');
-  const temporaryHook = `${hookPath}.evolcore-${process.pid}-${Date.now()}.tmp`;
-  try {
-    fs.writeFileSync(temporaryHook, managedHookLauncher(packageRoot), { encoding: 'utf8', mode: 0o500, flag: 'wx' });
-    fs.chmodSync(temporaryHook, 0o500);
-    atomicReplace(hookPath, temporaryHook);
-  } finally {
-    try { fs.rmSync(temporaryHook, { force: true }); } catch {}
-  }
-
-  let content = existingRequirements;
-  content = removeManagedBlock(content);
+export function buildManagedRequirements(source, { targetDirectory, nodePath, hookPath }) {
+  // Keep the existing text editor, but reject unsupported TOML layouts before
+  // writing anything. Parsing also catches duplicate tables/keys on reinstall.
+  let content = removeManagedBlock(source);
+  const before = parseToml(content);
   content = setTomlKey(content, null, 'allow_managed_hooks_only', 'true');
   content = setTomlKey(content, 'features', 'hooks', 'true');
   content = setTomlKey(content, 'hooks', 'windows_managed_dir', tomlString(path.resolve(targetDirectory)));
   if (!content.endsWith('\n')) content += '\n';
-  const command = `${windowsCommandArg(nodePath)} ${windowsCommandArg(hookPath)}`;
+  // Windows hook command must include %EVOLCORE_INSTANCE_SOCKET% so Codex
+  // expands it at runtime with the per-daemon socket path
+  const command = `${windowsCommandArg(nodePath)} ${windowsCommandArg(hookPath)} %EVOLCORE_INSTANCE_SOCKET%`;
   content += [
     markerStart,
     '[[hooks.PreToolUse]]',
@@ -248,17 +211,334 @@ function main() {
     markerEnd,
     '',
   ].join('\n');
-  fs.mkdirSync(path.dirname(requirements), { recursive: true });
-  atomicWrite(requirements, content);
-  try { fs.chmodSync(requirements, 0o440); } catch {}
-  restrictWindowsAcl(targetDirectory);
-  restrictWindowsAcl(hookPath);
-  restrictWindowsAcl(requirements);
-  process.stdout.write(`${JSON.stringify({ requirements, managedDir: path.resolve(targetDirectory), hookPath })}\n`);
+  const after = parseToml(content);
+  const expected = {
+    ...before,
+    allow_managed_hooks_only: true,
+    features: { ...before.features, hooks: true },
+    hooks: {
+      ...before.hooks,
+      windows_managed_dir: path.resolve(targetDirectory),
+      PreToolUse: [
+        ...(before.hooks?.PreToolUse || []),
+        { matcher: '*', hooks: [{ type: 'command', command, command_windows: command, statusMessage: 'Checking EvolCore session policy' }] },
+      ],
+    },
+  };
+  if (!isDeepStrictEqual(after, expected)) {
+    throw new Error('Could not safely update requirements.toml without changing unrelated policy. Existing configuration was not modified.');
+  }
+  return content;
 }
 
-try {
-  main();
-} catch (error) {
-  fail(error instanceof Error ? error.message : String(error));
+function regularFile(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) return { ok: false, unsafe: true };
+    return { ok: true };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { ok: false, unsafe: false };
+    return { ok: false, unsafe: true, error };
+  }
+}
+
+function sourceHasManagedMarker(source) {
+  return source.includes(markerStart) || source.includes(markerEnd);
+}
+
+/** Inspect only the canonical EvolCore managed-hook targets. */
+export function inspectManagedHookInstallation({ requirements, managedDir, packageRoot }) {
+  const canonicalRequirements = path.resolve(requirements);
+  const canonicalManagedDir = path.resolve(managedDir);
+  const hookPath = path.join(canonicalManagedDir, 'pre-tool-use.mjs');
+  for (const directory of [path.dirname(canonicalRequirements), canonicalManagedDir]) {
+    try {
+      const stat = fs.lstatSync(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        return { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: `${directory} must be a real directory` };
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: error?.message || String(error) };
+    }
+  }
+  const req = regularFile(canonicalRequirements);
+  const hook = regularFile(hookPath);
+  if (req.unsafe || hook.unsafe) return { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: 'requirements or launcher is not a regular file' };
+  if (!req.ok && hook.ok) return { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: 'canonical launcher exists but requirements.toml is missing' };
+  if (req.ok && !hook.ok) {
+    // A missing launcher can be repaired only when the requirements file is
+    // still an untouched user configuration. If it already contains any
+    // EvolCore-managed policy, treat the partial state as drift and fail
+    // closed instead of guessing which policy is authoritative.
+    try {
+      const source = fs.readFileSync(canonicalRequirements, 'utf8');
+      const partial = parseToml(source);
+      const managedPolicyPresent = sourceHasManagedMarker(source)
+        || partial.allow_managed_hooks_only !== undefined
+        || partial.hooks?.windows_managed_dir !== undefined
+        || partial.hooks?.managed_dir !== undefined;
+      if (managedPolicyPresent) {
+        return { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: 'requirements contains managed-hook policy but the canonical launcher is missing' };
+      }
+    } catch (error) {
+      return { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: `requirements.toml is invalid: ${error?.message || String(error)}` };
+    }
+  }
+  if (!req.ok || !hook.ok) return { status: 'missing', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: 'requirements or launcher is missing' };
+  let parsed;
+  try { parsed = parseToml(fs.readFileSync(canonicalRequirements, 'utf8')); }
+  catch (error) { return { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: `requirements.toml is invalid: ${error?.message || String(error)}` }; }
+  const configured = parsed.hooks?.windows_managed_dir ?? parsed.hooks?.managed_dir;
+  const normalized = value => path.normalize(String(value || '')).toLowerCase();
+  const launcher = fs.readFileSync(hookPath, 'utf8');
+  const packageMarker = launcher.includes('EVOLCORE_MANAGED_HOOK_LAUNCHER')
+    && launcher.toLowerCase().includes(JSON.stringify(path.resolve(packageRoot || process.cwd())).toLowerCase());
+  const preToolUse = parsed.hooks?.PreToolUse;
+  const canonicalCommand = value => {
+    if (typeof value !== 'string' || !value || /[\r\n;&|<>]/.test(value)) return false;
+    const withoutSocket = value.replace(/\s+%EVOLCORE_INSTANCE_SOCKET%\s*$/i, '').trim();
+    return withoutSocket.replace(/["']+$/, '').toLowerCase().endsWith(normalized(hookPath));
+  };
+  const loaded = Array.isArray(preToolUse) && preToolUse.some(group => group?.matcher === '*'
+    && Array.isArray(group.hooks) && group.hooks.some(handler => handler?.type === 'command'
+      && handler.async !== true && typeof handler.command === 'string'
+      && canonicalCommand(handler.command)
+      && canonicalCommand(handler.command_windows ?? handler.commandWindows)));
+  const valid = parsed.allow_managed_hooks_only === true
+    && parsed.features?.hooks === true
+    && normalized(configured) === normalized(canonicalManagedDir)
+    && packageMarker && loaded;
+  return valid
+    ? { status: 'installed', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath }
+    : { status: 'unsafe', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, reason: 'managed-hook policy is missing, altered, or points outside the canonical target' };
+}
+
+/** Idempotently repair a missing canonical installation; unsafe edits fail closed. */
+export function repairManagedHookInstallation(options, acl = windowsAcl) {
+  const { requirements, managedDir, packageRoot, nodePath = process.execPath } = options;
+  const canonicalRequirements = path.resolve(requirements);
+  const canonicalManagedDir = path.resolve(managedDir);
+  const hookPath = path.join(canonicalManagedDir, 'pre-tool-use.mjs');
+  const sourceHook = path.join(packageRoot, 'bin', 'codex-managed-hook.mjs');
+  const state = inspectManagedHookInstallation({ requirements: canonicalRequirements, managedDir: canonicalManagedDir, packageRoot });
+  if (state.status === 'installed') return { ...state, repaired: false, warnings: [] };
+  if (state.status === 'unsafe') throw new Error(`Refusing automatic managed-hook repair: ${state.reason}`);
+  if (!fs.existsSync(sourceHook)) throw new Error(`Required Hook runtime file was not found: ${sourceHook}`);
+  const previousContent = fs.existsSync(canonicalRequirements) ? fs.readFileSync(canonicalRequirements, 'utf8') : '';
+  const content = buildManagedRequirements(previousContent, { targetDirectory: canonicalManagedDir, nodePath, hookPath });
+  const warnings = provisionManagedFiles({ requirements: canonicalRequirements, hookPath, sourceHook, nodePath, previousContent, content, launcher: managedHookLauncher(packageRoot) }, acl);
+  return { status: 'installed', requirements: canonicalRequirements, managedDir: canonicalManagedDir, hookPath, repaired: true, warnings };
+}
+
+export function windowsAcl(action, payload = {}, run = execFileSync) {
+  const executable = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  try {
+    const output = run(executable, [
+      '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', aclScript,
+      '-Request', Buffer.from(JSON.stringify({ action, ...payload })).toString('base64'),
+    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 30_000 });
+    return JSON.parse(output.replace(/^\uFEFF/, '').trim());
+  } catch (error) {
+    const detail = error.stderr?.toString().trim() || error.message || String(error);
+    throw new Error(`Windows ACL ${action} failed (${payload.path || 'access verification'}, exit=${error.status ?? 'unknown'}): ${detail}`, { cause: error });
+  }
+}
+
+function existingFile(file, io) {
+  try {
+    const stat = io.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Expected a regular file: ${file}`);
+    return stat;
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function makeReplaceable(file, io) {
+  const stat = existingFile(file, io);
+  // Windows' readonly attribute prevents replacement even for Administrators.
+  // chmod affects that attribute, not the DACL. Restore it on the old inode.
+  if (process.platform === 'win32' && stat && !(stat.mode & 0o200)) io.chmodSync(file, 0o600);
+}
+
+/** Keep the original inodes (including ACLs) until both replacements validate. */
+export function commitPreparedFiles(entries, verify, io = fs) {
+  const records = [];
+  try {
+    for (const entry of entries) {
+      const stat = existingFile(entry.file, io);
+      const record = { ...entry, mode: stat?.mode, backup: undefined, installed: false };
+      if (stat) {
+        const backup = `${entry.file}.evolcore-backup-${randomUUID()}`;
+        // A same-directory hard link retains the exact original security
+        // descriptor. If unsupported, stop before replacing any live file.
+        io.linkSync(entry.file, backup);
+        record.backup = backup;
+      }
+      records.push(record);
+    }
+    for (const record of records) {
+      makeReplaceable(record.file, io);
+      io.renameSync(record.temporary, record.file);
+      record.installed = true;
+      if (record.backup) io.chmodSync(record.backup, record.mode);
+    }
+    verify();
+  } catch (error) {
+    const recoveryErrors = [];
+    for (const record of records.toReversed()) {
+      try {
+        if (record.installed) {
+          makeReplaceable(record.file, io);
+          if (record.backup) io.renameSync(record.backup, record.file);
+          else io.unlinkSync(record.file);
+        }
+        if (record.backup && io.existsSync(record.backup)) {
+          makeReplaceable(record.backup, io);
+          io.unlinkSync(record.backup);
+        }
+        if (record.mode !== undefined) io.chmodSync(record.file, record.mode);
+      } catch (recoveryError) {
+        recoveryErrors.push(`${record.file}: ${recoveryError.message}; original retained at ${record.backup || '(new installation)'}`);
+      }
+    }
+    throw new Error(`${error.message}${recoveryErrors.length
+      ? `; rollback incomplete: ${recoveryErrors.join(' | ')}`
+      : '; previous files and permissions restored'}`, { cause: error });
+  }
+  const warnings = [];
+  for (const record of records) {
+    if (!record.backup) continue;
+    try {
+      makeReplaceable(record.backup, io);
+      io.unlinkSync(record.backup);
+    } catch (error) {
+      warnings.push(`Installed successfully, but could not remove backup ${record.backup}: ${error.message}`);
+    }
+  }
+  return warnings;
+}
+
+/** This transaction is used only by explicit provisioning, never npm upgrades. */
+export function provisionManagedFiles(options, acl = windowsAcl) {
+  const { requirements, hookPath, sourceHook, nodePath, content, launcher } = options;
+  const directory = path.dirname(hookPath);
+  const configDirectory = path.dirname(requirements);
+  acl('preflight');
+  fs.mkdirSync(configDirectory, { recursive: true });
+  const lockPath = path.join(configDirectory, '.evolcore-hooks.install.lock');
+  let lock;
+  try { lock = fs.openSync(lockPath, 'wx', 0o600); } catch (error) {
+    throw new Error(`Cannot acquire installer lock ${lockPath}: ${error.message}. If an installer crashed, confirm it has stopped before removing the lock.`, { cause: error });
+  }
+  const staged = [];
+  let committed = false;
+  try {
+    fs.writeFileSync(lock, JSON.stringify({ pid: process.pid, started: new Date().toISOString() }));
+    const existing = existingFile(requirements, fs);
+    // Detect edits made after configuration generation, including a second
+    // installer completing just before this process acquired the lock.
+    if ((existing ? fs.readFileSync(requirements, 'utf8') : '') !== options.previousContent) {
+      throw new Error(`Configuration changed while preparing installation: ${requirements}. Retry using the latest configuration.`);
+    }
+    if (fs.existsSync(directory)) {
+      const stat = fs.lstatSync(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Expected a real hook directory: ${directory}`);
+    } else {
+      fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+      acl('prepare', { path: directory, directory: true });
+    }
+    // Existing directory ACLs are checked below, never rewritten: changing
+    // inheritable ACEs could alter the live Hook before the transaction starts.
+    for (const [file, value, reference] of [
+      [hookPath, launcher, undefined],
+      [requirements, content, existing ? requirements : undefined],
+    ]) {
+      const temporary = `${file}.evolcore-${randomUUID()}.tmp`;
+      staged.push({ file, temporary, value });
+      fs.writeFileSync(temporary, value, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      acl('prepare', { path: temporary, reference });
+    }
+    const readable = [
+      { path: configDirectory, execute: true },
+      { path: sourceHook },
+      { path: nodePath, execute: true },
+    ];
+    const verify = (temporary) => {
+      for (const entry of staged) {
+        const target = temporary ? entry.temporary : entry.file;
+        if (fs.readFileSync(target, 'utf8') !== entry.value) throw new Error(`Installed content differs: ${target}`);
+      }
+      return acl('verify', { entries: [
+        { path: directory, protected: true, execute: true },
+        ...staged.map(entry => ({ path: temporary ? entry.temporary : entry.file, protected: true })),
+        ...readable,
+      ] });
+    };
+    verify(true);
+    let accessReport;
+    const warnings = commitPreparedFiles(staged, () => { accessReport = verify(false); });
+    committed = true;
+    if ([accessReport].flat().some(entry => entry?.userProbe === 'unavailable')) {
+      warnings.push('ACLs verified, but this elevated account has no normal UAC linked token. Verify file reads and Hook execution from the intended non-elevated user before use.');
+    }
+    return warnings;
+  } finally {
+    for (const entry of staged) {
+      try { fs.rmSync(entry.temporary, { force: true }); } catch (error) {
+        process.stderr.write(`[evolcore] Could not clean staging file ${entry.temporary}: ${error.message}\n`);
+      }
+    }
+    fs.closeSync(lock);
+    try { fs.unlinkSync(lockPath); } catch (error) {
+      process.stderr.write(`[evolcore] ${committed ? 'Installed; ' : ''}could not remove installer lock ${lockPath}: ${error.message}\n`);
+    }
+  }
+}
+
+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'))) {
+    runLinuxPostinstall();
+    return;
+  }
+  if (process.platform === 'linux' && argument('--mountpoint')) {
+    runLinuxPostinstall();
+    return;
+  }
+  if (process.platform !== 'win32') fail('Codex managed hook provisioning is only supported on Windows.');
+  if (!argument('--package-root')) fail('--package-root is required.');
+  const packageRoot = path.resolve(argument('--package-root'));
+  const nodePath = path.resolve(argument('--node-path') || process.execPath);
+  const requirements = path.resolve(argument('--requirements')
+    || path.join(process.env.ProgramData || path.join(os.homedir(), 'ProgramData'), 'OpenAI', 'Codex', 'requirements.toml'));
+  const targetDirectory = path.resolve(argument('--managed-dir') || path.join(path.dirname(requirements), 'EvolCore', 'hooks'));
+  const hookPath = path.join(targetDirectory, 'pre-tool-use.mjs');
+  const sourceHook = path.join(packageRoot, 'bin', 'codex-managed-hook.mjs');
+  for (const file of [sourceHook, nodePath]) {
+    if (!fs.statSync(file).isFile()) fail(`Required Hook runtime file was not found: ${file}`);
+  }
+  if (argument('--repair')) {
+    const result = repairManagedHookInstallation({ requirements, managedDir: targetDirectory, packageRoot, nodePath });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  const previousContent = fs.existsSync(requirements) ? fs.readFileSync(requirements, 'utf8') : '';
+  const content = buildManagedRequirements(previousContent, { targetDirectory, nodePath, hookPath });
+  const warnings = provisionManagedFiles({
+    requirements, hookPath, sourceHook, nodePath, previousContent, content,
+    launcher: managedHookLauncher(packageRoot),
+  });
+  for (const warning of warnings) process.stderr.write(`[evolcore] ${warning}\n`);
+  process.stdout.write(`${JSON.stringify({ requirements, managedDir: targetDirectory, hookPath })}\n`);
+}
+
+if (process.argv[1] && pathToFileURL(fs.realpathSync(process.argv[1])).href === import.meta.url) {
+  try { main(); } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
 }

package/dist/agents/baseagent-availability.js

@@ -0,0 +1,48 @@
+import { resolveCommandPath } 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'];
+/**
+ * Single source of truth for init and ECWeb base-agent probing.
+ * Claude/Gemini require an executable; Codex additionally requires a supported
+ * CLI with app-server; ecagent is bundled with EvolCore.
+ */
+export function detectAvailableBaseagents(codexAvailability = getCodexAppServerAvailability()) {
+    return BASEAGENT_CANDIDATES.filter((baseagent) => {
+        if (baseagent === 'ecagent')
+            return true;
+        if (baseagent === 'codex')
+            return codexAvailability.available;
+        return resolveCommandPath(baseagent) !== null;
+    });
+}
+export function detectBaseagentDetails(codexAvailability = getCodexAppServerAvailability()) {
+    const claude = resolveCommandPath('claude') !== null;
+    const gemini = resolveCommandPath('gemini') !== null;
+    return [
+        {
+            id: 'claude',
+            detected: claude,
+            detectionSource: claude ? ['PATH'] : [],
+            reason: claude ? undefined : '未检测到 Claude CLI。',
+        },
+        {
+            id: 'codex',
+            detected: codexAvailability.available,
+            detectionSource: codexAvailability.available ? ['Codex CLI app-server'] : [],
+            reason: codexAvailability.available ? undefined : codexAvailability.reason,
+            version: codexAvailability.version,
+        },
+        {
+            id: 'gemini',
+            detected: gemini,
+            detectionSource: gemini ? ['PATH'] : [],
+            reason: gemini ? undefined : '未检测到 Gemini CLI。',
+        },
+        {
+            id: 'ecagent',
+            detected: true,
+            detectionSource: ['内置'],
+        },
+    ];
+}

package/dist/agents/baseagent.js

@@ -157,7 +157,7 @@ export function resolveAnthropicConfig(config, override) {
         || pickExec(config.agents?.claude?.pathToClaudeCodeExecutable);
     return { apiKey, baseUrl, headers, queryParams, model, effort, pathToClaudeCodeExecutable };
 }
-function loadCodexSettings() {
+export function loadCodexSettings() {
     try {
         const configuredHome = process.env.CODEX_HOME?.trim();
         const codexHome = configuredHome ? path.resolve(configuredHome) : path.join(os.homedir(), '.codex');