evolcore 0.0.23 → 0.0.25

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

@@ -1,544 +1,555 @@
-#!/usr/bin/env node
-
-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);
-  return index >= 0 ? process.argv[index + 1] : undefined;
-}
-
-function fail(message) {
-  process.stderr.write(`[evolcore] ${message}\n`);
-  process.exit(1);
-}
-
-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 {
-    stat = fs.lstatSync(directory);
-  } catch (error) {
-    if (error?.code !== 'ENOENT') {
-      fail(`could not inspect the Codex managed requirements mountpoint ${directory}: ${error?.message || String(error)}`);
-    }
-  }
-
-  if (stat) {
-    if (!stat.isDirectory() || stat.isSymbolicLink()) {
-      fail(`Codex managed requirements mountpoint is unsafe: ${directory} must be a real directory.`);
-    }
-    return;
-  }
-
-  try {
-    fs.mkdirSync(directory, { mode: 0o755 });
-    fs.chmodSync(directory, 0o755);
-  } catch (error) {
-    if (error?.code === 'EEXIST') {
-      const raced = fs.lstatSync(directory);
-      if (raced.isDirectory() && !raced.isSymbolicLink()) return;
-    }
-    fail(
-      `Linux global installation requires the real directory ${directory}, but it could not be created: `
-      + `${error?.message || String(error)}. `
-      + `Create it first with: sudo install -d -m 0755 ${directory}`,
-    );
-  }
-
-  const created = fs.lstatSync(directory);
-  if (!created.isDirectory() || created.isSymbolicLink()) {
-    fail(`Codex managed requirements mountpoint provisioning failed: ${directory} must be a real directory.`);
-  }
-  process.stdout.write(`[evolcore] Prepared Codex managed requirements mountpoint at ${directory}.\n`);
-}
-
-function runLinuxPostinstall() {
-  const explicitMountpoint = argument('--mountpoint');
-  if (process.platform !== 'linux') return;
-  // Local source installs do not launch the Linux Codex guard and must not
-  // mutate machine-wide configuration. An explicit path is accepted only for
-  // isolated lifecycle behavior tests.
-  if (!isGlobalInstall() && !explicitMountpoint) return;
-  ensureRealDirectory(explicitMountpoint || '/etc/codex');
-}
-
-function tomlString(value) {
-  return JSON.stringify(value);
-}
-
-function windowsCommandArg(value) {
-  // Keep filesystem separators intact; tomlString() performs the required
-  // TOML escaping after this Windows command-line quoting step.
-  return `"${value.replaceAll('"', '\\"')}"`;
-}
-
-function removeManagedBlock(source) {
-  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 || line.trim().startsWith(`${header} #`))
-    : -1;
-  if (table && start < 0) return null;
-  const from = table ? start + 1 : 0;
-  let to = lines.length;
-  for (let index = from; index < lines.length; index += 1) {
-    if (/^\s*\[\[?[^\]]+\]\]?\s*(?:#.*)?$/.test(lines[index])) {
-      to = index;
-      break;
-    }
-  }
-  return { start, from, to };
-}
-
-function setTomlKey(source, table, key, value) {
-  const lines = source.split('\n');
-  let bounds = tableBounds(lines, table);
-  if (!bounds) {
-    if (table) {
-      if (lines.length && lines.at(-1) !== '') lines.push('');
-      lines.push(`[${table}]`, `${key} = ${value}`);
-    } else {
-      let insertAt = lines.findIndex(line => /^\s*\[/.test(line));
-      if (insertAt < 0) insertAt = lines.length;
-      lines.splice(insertAt, 0, `${key} = ${value}`);
-    }
-    return lines.join('\n');
-  }
-  const keyExpression = new RegExp(`^\\s*${key.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\s*=`);
-  const existing = lines.slice(bounds.from, bounds.to).findIndex(line => keyExpression.test(line));
-  if (existing >= 0) {
-    lines[bounds.from + existing] = `${key} = ${value}`;
-  } else {
-    lines.splice(bounds.from, 0, `${key} = ${value}`);
-  }
-  return lines.join('\n');
-}
-
-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
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-// EVOLCORE_MANAGED_HOOK_LAUNCHER
-const packageRoot = ${JSON.stringify(trustedPackageRoot)};
-
-try {
-  await import(pathToFileURL(path.join(packageRoot, 'bin', 'codex-managed-hook.mjs')).href);
-} catch (error) {
-  process.stderr.write('[evolcore] failed to load the current managed hook: '
-    + (error instanceof Error ? error.message : String(error)) + '\\n');
-  process.exit(2);
-}
-`;
-}
-
-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';
-  // 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]]',
-    'matcher = "*"',
-    '',
-    '[[hooks.PreToolUse.hooks]]',
-    'type = "command"',
-    `command = ${tomlString(command)}`,
-    `command_windows = ${tomlString(command)}`,
-    // Intentionally omit timeout: Codex applies its documented 600-second
-    // default for synchronous PreToolUse hooks. The application pause gate
-    // itself has no timeout; Codex remains the outer infrastructure ceiling.
-    'statusMessage = "Checking EvolCore session policy"',
-    markerEnd,
-    '',
-  ].join('\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;
-}
-
-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));
-  }
-}
+#!/usr/bin/env node
+
+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);
+  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);
+}
+
+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 {
+    stat = fs.lstatSync(directory);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      fail(`could not inspect the Codex managed requirements mountpoint ${directory}: ${error?.message || String(error)}`);
+    }
+  }
+
+  if (stat) {
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      fail(`Codex managed requirements mountpoint is unsafe: ${directory} must be a real directory.`);
+    }
+    return;
+  }
+
+  try {
+    fs.mkdirSync(directory, { mode: 0o755 });
+    fs.chmodSync(directory, 0o755);
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      const raced = fs.lstatSync(directory);
+      if (raced.isDirectory() && !raced.isSymbolicLink()) return;
+    }
+    fail(
+      `Linux global installation requires the real directory ${directory}, but it could not be created: `
+      + `${error?.message || String(error)}. `
+      + `Create it first with: sudo install -d -m 0755 ${directory}`,
+    );
+  }
+
+  const created = fs.lstatSync(directory);
+  if (!created.isDirectory() || created.isSymbolicLink()) {
+    fail(`Codex managed requirements mountpoint provisioning failed: ${directory} must be a real directory.`);
+  }
+  process.stdout.write(`[evolcore] Prepared Codex managed requirements mountpoint at ${directory}.\n`);
+}
+
+function runLinuxPostinstall() {
+  const explicitMountpoint = argument('--mountpoint');
+  if (process.platform !== 'linux') return;
+  // Local source installs do not launch the Linux Codex guard and must not
+  // mutate machine-wide configuration. An explicit path is accepted only for
+  // isolated lifecycle behavior tests.
+  if (!isGlobalInstall() && !explicitMountpoint) return;
+  ensureRealDirectory(explicitMountpoint || '/etc/codex');
+}
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+function windowsCommandArg(value) {
+  // Keep filesystem separators intact; tomlString() performs the required
+  // TOML escaping after this Windows command-line quoting step.
+  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;
+  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 || line.trim().startsWith(`${header} #`))
+    : -1;
+  if (table && start < 0) return null;
+  const from = table ? start + 1 : 0;
+  let to = lines.length;
+  for (let index = from; index < lines.length; index += 1) {
+    if (/^\s*\[\[?[^\]]+\]\]?\s*(?:#.*)?$/.test(lines[index])) {
+      to = index;
+      break;
+    }
+  }
+  return { start, from, to };
+}
+
+function setTomlKey(source, table, key, value) {
+  const lines = source.split('\n');
+  let bounds = tableBounds(lines, table);
+  if (!bounds) {
+    if (table) {
+      if (lines.length && lines.at(-1) !== '') lines.push('');
+      lines.push(`[${table}]`, `${key} = ${value}`);
+    } else {
+      let insertAt = lines.findIndex(line => /^\s*\[/.test(line));
+      if (insertAt < 0) insertAt = lines.length;
+      lines.splice(insertAt, 0, `${key} = ${value}`);
+    }
+    return lines.join('\n');
+  }
+  const keyExpression = new RegExp(`^\\s*${key.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\s*=`);
+  const existing = lines.slice(bounds.from, bounds.to).findIndex(line => keyExpression.test(line));
+  if (existing >= 0) {
+    lines[bounds.from + existing] = `${key} = ${value}`;
+  } else {
+    lines.splice(bounds.from, 0, `${key} = ${value}`);
+  }
+  return lines.join('\n');
+}
+
+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
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// EVOLCORE_MANAGED_HOOK_LAUNCHER
+const packageRoot = ${JSON.stringify(trustedPackageRoot)};
+
+try {
+  await import(pathToFileURL(path.join(packageRoot, 'bin', 'codex-managed-hook.mjs')).href);
+} catch (error) {
+  process.stderr.write('[evolcore] failed to load the current managed hook: '
+    + (error instanceof Error ? error.message : String(error)) + '\\n');
+  process.exit(2);
+}
+`;
+}
+
+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';
+  // 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]]',
+    'matcher = "*"',
+    '',
+    '[[hooks.PreToolUse.hooks]]',
+    'type = "command"',
+    `command = ${tomlString(command)}`,
+    `command_windows = ${tomlString(command)}`,
+    // Intentionally omit timeout: Codex applies its documented 600-second
+    // default for synchronous PreToolUse hooks. The application pause gate
+    // itself has no timeout; Codex remains the outer infrastructure ceiling.
+    'statusMessage = "Checking EvolCore session policy"',
+    markerEnd,
+    '',
+  ].join('\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;
+}
+
+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() {
+  // 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')) {
+    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 (hasArgument('--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));
+  }
+}