evolcore 0.0.22 → 0.0.24

package/dist/agents/{codex-app-server-client.js → codex/app-server-client.js}

@@ -1,17 +1,18 @@
 import { spawn } from 'child_process';
 import readline from 'readline';
-import { logger } from '../utils/logger.js';
-import { buildHClassGuardCommand, collectSandboxGuardDiagnostics, summarizeBubblewrapArgsForLog, summarizeSandboxGuardDiagnostics, } from '../core/permission/sandbox-runtime.js';
-import { resolveCodexLaunchCommand } from '../utils/codex-cli.js';
+import { logger } from '../../utils/logger.js';
+import { buildHClassGuardCommand, collectSandboxGuardDiagnostics, summarizeBubblewrapArgsForLog, summarizeSandboxGuardDiagnostics, } from '../../core/permission/sandbox-runtime.js';
+import { resolveCodexLaunchCommand } from '../baseagent.js';
 import { createHash } from 'crypto';
-import { sanitizeShellExecutionEnvironment } from '../core/permission/shell-environment.js';
+import { sanitizeShellExecutionEnvironment } from '../../core/permission/shell-environment.js';
 import fs from 'fs';
 import path from 'path';
-import { ensureProcessManagedTempDir } from '../cli/task-context.js';
-import { getPackageRoot, resolvePaths } from '../paths.js';
-import { killProcess } from '../utils/cross-platform.js';
-import { registerCodexAppServerProcess, unregisterCodexAppServerProcess, } from '../utils/codex-app-server-registry.js';
+import { ensureProcessManagedTempDir } from '../../cli/task-context.js';
+import { getPackageRoot, resolvePaths } from '../../paths.js';
+import { killProcess } from '../../utils/cross-platform.js';
+import { registerCodexAppServerProcess, unregisterCodexAppServerProcess, } from './app-server-registry.js';
 const BUILT_IN_CODEX_PROVIDER_IDS = new Set(['openai']);
+export const CODEX_THREAD_ACTIVE_WRITER = 'THREAD_ACTIVE_WRITER';
 function tomlProviderKey(value) {
     if (!value || /[\0\r\n]/.test(value)) {
         throw new Error(`Invalid Codex provider name: ${value}`);
@@ -64,6 +65,7 @@ export class CodexAppServerClient {
     initialized = false;
     initializing = null;
     stderrBuffer = [];
+    stderrSequence = 0;
     managedHookRuntimeDir = null;
     processRegistrationPath = null;
     constructor(options) {
@@ -115,6 +117,61 @@ export class CodexAppServerClient {
             ...(options?.selectedCapabilityRoots ? { selectedCapabilityRoots: options.selectedCapabilityRoots } : {}),
         });
     }
+    async threadArchive(threadId) {
+        await this.request('thread/archive', { threadId });
+        return true;
+    }
+    async threadUnarchive(threadId) {
+        return this.request('thread/unarchive', { threadId });
+    }
+    async threadUnsubscribe(threadId) {
+        return this.request('thread/unsubscribe', { threadId });
+    }
+    /**
+     * Drop this connection's subscription and wait until the server has released
+     * the in-memory thread. This is deliberately scoped to one thread; closing
+     * the app-server process would also disrupt unrelated concurrent sessions.
+     */
+    async threadUnsubscribeAndWait(threadId, timeoutMs = 2_000) {
+        let closed = false;
+        let resolveClosed;
+        const closedPromise = new Promise(resolve => {
+            resolveClosed = resolve;
+        });
+        const removeNotificationHandler = this.onNotification(notification => {
+            if (notification.method !== 'thread/closed')
+                return;
+            const params = (notification.params || {});
+            const closedThreadId = params.threadId ?? params.thread_id;
+            if (closedThreadId !== threadId || closed)
+                return;
+            closed = true;
+            resolveClosed();
+        });
+        let timer;
+        try {
+            const response = await this.threadUnsubscribe(threadId);
+            if (response.status !== 'unsubscribed')
+                return response;
+            const timeoutPromise = new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    if (closed)
+                        return;
+                    const error = new Error(`thread/closed timed out for thread ${threadId}`);
+                    error.code = 'CODEX_THREAD_CLOSE_TIMEOUT';
+                    reject(error);
+                }, timeoutMs);
+                timer.unref?.();
+            });
+            await Promise.race([closedPromise, timeoutPromise]);
+            return response;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            removeNotificationHandler();
+        }
+    }
     async turnStart(threadId, input, options) {
         const sandboxPolicy = this.toTurnSandboxPolicy(options?.sandbox);
         return this.request('turn/start', {
@@ -295,8 +352,8 @@ export class CodexAppServerClient {
         await this.request('turn/interrupt', { threadId, turnId });
         return true;
     }
-    async modelList(includeHidden = false) {
-        return this.request('model/list', { includeHidden });
+    async modelList(includeHidden = false, cursor) {
+        return this.request('model/list', { includeHidden, ...(cursor ? { cursor } : {}) });
     }
     async modelProviderCapabilitiesRead() {
         return this.request('modelProvider/capabilities/read', {});
@@ -431,6 +488,7 @@ export class CodexAppServerClient {
                 const managedRequirements = this.ensureManagedHookRuntime();
                 const guardedCommand = buildHClassGuardCommand(command, commandArgs, guardRoot, {
                     managedCodexRequirements: managedRequirements,
+                    protectEvolcoreFilesystem: this.options.protectEvolcoreFilesystem !== false,
                 });
                 if (!guardedCommand) {
                     throw new Error('Codex 缺少 EvolCore managed-hook 隔离运行时，已拒绝启动 app-server');
@@ -482,7 +540,7 @@ export class CodexAppServerClient {
             const text = String(chunk).trim();
             if (!text)
                 return;
-            this.stderrBuffer.push(text);
+            this.stderrBuffer.push({ sequence: ++this.stderrSequence, text });
             if (this.stderrBuffer.length > 20)
                 this.stderrBuffer.shift();
             logger.debug(`[CodexAppServer] ${text}`);
@@ -555,9 +613,8 @@ export class CodexAppServerClient {
             ...process.env,
             ...this.options.env,
         });
-        // The app-server is shared by multiple EvolCore sessions. Its process
-        // environment must therefore use the daemon's trusted private root;
-        // per-thread session roots are injected later through thread config.
+        // Use the normal user CODEX_HOME so EvolCore and Codex Desktop share
+        // threads, SQLite state, writer locks, and sandbox state.
         const managedTmpDir = ensureProcessManagedTempDir();
         env.TMPDIR = managedTmpDir;
         delete env.EVOLCORE_RUNTIME_LOCK_DIR;
@@ -576,8 +633,8 @@ export class CodexAppServerClient {
                 }
                 const stat = fs.lstatSync(runtimeLockDir);
                 if (!stat.isDirectory() || stat.isSymbolicLink()
-                    || (typeof process.getuid === 'function' && stat.uid !== process.getuid())
-                    || (stat.mode & 0o077) !== 0) {
+                    || (process.platform !== 'win32' && typeof process.getuid === 'function' && stat.uid !== process.getuid())
+                    || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)) {
                     throw new Error('runtime lock directory is not private');
                 }
                 env.EVOLCORE_RUNTIME_LOCK_DIR = runtimeLockDir;
@@ -663,7 +720,8 @@ export class CodexAppServerClient {
         if (typeof managedDir !== 'string' || !path.isAbsolute(managedDir)
             || !fs.existsSync(managedDir) || !managedHookLoaded || !lockdownEnabled || !hooksEnabled) {
             throw new Error('Codex Windows proactive requires an installed and loaded EvolCore managed PreToolUse hook. '
-                + 'Run the elevated Windows installer again to provision %ProgramData%\\OpenAI\\Codex\\requirements.toml.');
+                + 'ec start/restart automatically checks and installs missing hooks with Windows administrator approval. '
+                + 'Restart EvolCore to install missing hooks and reload the Codex policy.');
         }
     }
     buildProcessArgs() {
@@ -677,7 +735,7 @@ export class CodexAppServerClient {
         const headerEnvNames = Object.fromEntries(Object.keys(this.options.headers ?? {}).map(name => [name, codexHeaderEnvName(name)]));
         const hasHeaders = Object.keys(headerEnvNames).length > 0;
         const hasQueryParams = Object.keys(this.options.queryParams ?? {}).length > 0;
-        if (hasHeaders || hasQueryParams) {
+        if (hasHeaders || hasQueryParams || this.options.baseUrl || this.options.provider) {
             const configuredProvider = this.options.provider?.trim();
             const useRuntimeProvider = !configuredProvider || BUILT_IN_CODEX_PROVIDER_IDS.has(configuredProvider.toLowerCase());
             const providerName = !useRuntimeProvider
@@ -712,7 +770,13 @@ export class CodexAppServerClient {
         if (params !== undefined && params !== null)
             payload.params = params;
         return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve, reject, method, params });
+            this.pending.set(id, {
+                resolve,
+                reject,
+                method,
+                params,
+                stderrStartSequence: this.stderrSequence,
+            });
             proc.stdin.write(`${JSON.stringify(payload)}\n`, error => {
                 if (!error)
                     return;
@@ -786,12 +850,18 @@ export class CodexAppServerClient {
             // The CLI's one-time bubblewrap configuration warning is process-wide
             // startup noise, not evidence about this RPC. Do not append it to an
             // unrelated request failure such as thread/resume.
-            const stderrLines = this.stderrBuffer.filter(line => !/could not find bubblewrap on PATH/i.test(line));
+            const stderrLines = this.stderrBuffer
+                .filter(entry => entry.sequence > pending.stderrStartSequence)
+                .map(entry => entry.text)
+                .filter(line => !/could not find bubblewrap on PATH/i.test(line));
             const stderr = stderrLines.length ? `\n${stderrLines.join('\n')}` : '';
             const error = new Error(`${pending.method} failed: ${detail}${stderr}`);
             if (/no rollout found for thread id/i.test(detail)) {
                 error.code = 'CODEX_ROLLOUT_NOT_FOUND';
             }
+            else if (/already has an active writer/i.test(detail)) {
+                error.code = CODEX_THREAD_ACTIVE_WRITER;
+            }
             pending.reject(error);
             return;
         }

package/dist/{utils/codex-app-server-registry.js → agents/codex/app-server-registry.js}

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
-import { resolvePaths } from '../paths.js';
-import { getProcessStartTime } from './process-introspect.js';
+import { resolvePaths } from '../../paths.js';
+import { getProcessStartTime } from '../../utils/process-introspect.js';
 const CODEX_APP_SERVER_RECORD_PREFIX = 'codex-app-server-';
 const CODEX_APP_SERVER_RECORD_SUFFIX = '.json';
 function recordFilePath(pid) {

package/dist/agents/codex/catalog.js

@@ -0,0 +1,70 @@
+import { execFile } from 'node:child_process';
+import { CodexAppServerClient } from './app-server-client.js';
+import { resolveCodexLaunchCommand } from '../baseagent.js';
+import { parseModelList } from '../../core/model/catalog-service.js';
+async function cliModels() {
+    const launch = resolveCodexLaunchCommand(['debug', 'models']);
+    if (!launch)
+        return null;
+    return new Promise(resolve => {
+        execFile(launch.command, launch.args, { timeout: 3000, windowsHide: true, maxBuffer: 16 * 1024 * 1024, encoding: 'utf8' }, (error, stdout) => {
+            try {
+                if (error)
+                    return resolve(null);
+                const json = JSON.parse(stdout);
+                if (!Array.isArray(json?.models))
+                    return resolve(null);
+                resolve(parseModelList(json.models.filter((m) => m.visibility === 'list'))
+                    .map(m => ({ ...m, verification: 'unverified' })));
+            }
+            catch {
+                resolve(null);
+            }
+        });
+    });
+}
+/** A catalog-only client uses the same transport configuration as inference. */
+export async function codexNativeCatalog(context) {
+    if (context.baseagent !== 'codex')
+        return null;
+    const client = new CodexAppServerClient({
+        apiKey: context.apiKey ?? '', baseUrl: context.baseUrl, provider: context.provider,
+        headers: context.headers, queryParams: context.queryParams,
+    });
+    let timer;
+    let expired = false;
+    try {
+        return await Promise.race([
+            (async () => {
+                const models = [];
+                const seen = new Set();
+                let cursor;
+                do {
+                    const page = await client.modelList(false, cursor);
+                    if (expired)
+                        throw new Error('Model catalog timeout');
+                    if (!Array.isArray(page.data))
+                        throw new Error('Invalid native model list');
+                    models.push(...parseModelList(page.data.filter(m => !m.hidden)));
+                    cursor = page.nextCursor || undefined;
+                    if (cursor && (seen.has(cursor) || seen.size >= 100))
+                        throw new Error('Invalid native model pagination');
+                    if (cursor)
+                        seen.add(cursor);
+                } while (cursor);
+                return [...new Map(models.map(m => [m.id, m])).values()];
+            })(),
+            new Promise((_, reject) => { timer = setTimeout(() => { expired = true; reject(new Error('Model catalog timeout')); }, 5000); }),
+        ]);
+    }
+    catch {
+        // The host CLI catalog has no guarantee of matching this Agent connection.
+        // It is useful metadata/suggestions and always remains unverified.
+        return await cliModels();
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        await client.close();
+    }
+}

package/dist/agents/codex/diagnostics.js

@@ -0,0 +1,369 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { parse as parseToml } from 'smol-toml';
+export function checkCodexProjectPath(value, options = {}) {
+    const configured = typeof value === 'string' ? value.trim() : '';
+    if (!configured) {
+        return { status: 'invalid', path: configured, warnings: [], reason: 'projects.defaultPath is not configured' };
+    }
+    const projectPath = path.resolve(configured);
+    const warnings = [];
+    if ((options.platform ?? process.platform) === 'win32') {
+        if (projectPath.length >= 240) {
+            warnings.push(`Windows path is long (${projectPath.length} characters); Codex or a child tool may reject it.`);
+        }
+        if (projectPath.startsWith('\\\\')) {
+            warnings.push('Windows UNC/network project path may be unavailable to Codex sandboxed processes.');
+        }
+        const systemRoot = process.env.SystemRoot ? path.resolve(process.env.SystemRoot).toLowerCase() : '';
+        if (systemRoot && projectPath.toLowerCase().startsWith(`${systemRoot}${path.sep}`)) {
+            warnings.push('Project path is under the Windows system directory; use a dedicated workspace when possible.');
+        }
+    }
+    const root = path.parse(projectPath).root;
+    if (projectPath === root)
+        warnings.push('Project path is a filesystem root; use a dedicated project directory when possible.');
+    try {
+        const stat = fs.statSync(projectPath);
+        if (!stat.isDirectory())
+            return { status: 'not-directory', path: projectPath, warnings, reason: 'path exists but is not a directory' };
+        try {
+            fs.accessSync(projectPath, fs.constants.R_OK | fs.constants.W_OK);
+        }
+        catch (error) {
+            return { status: 'inaccessible', path: projectPath, warnings, reason: error instanceof Error ? error.message : String(error) };
+        }
+        return { status: 'ok', path: projectPath, warnings };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return { status: 'missing', path: projectPath, warnings, reason: 'directory does not exist' };
+        }
+        return { status: 'inaccessible', path: projectPath, warnings, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function codexManagedHookPaths(options = {}) {
+    if ((options.platform ?? process.platform) !== 'win32')
+        return null;
+    const programData = options.programData || process.env.ProgramData || path.join(options.homeDir || os.homedir(), 'ProgramData');
+    const requirements = path.resolve(programData, 'OpenAI', 'Codex', 'requirements.toml');
+    const managedDir = path.join(path.dirname(requirements), 'EvolCore', 'hooks');
+    return { requirements, managedDir, hookPath: path.join(managedDir, 'pre-tool-use.mjs') };
+}
+function decodeProbeOutput(buffer) {
+    if (!buffer?.length)
+        return '';
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+    }
+    catch {
+        return new TextDecoder('gb18030').decode(buffer);
+    }
+}
+function windowsCommandArg(value) {
+    return '"' + value.replaceAll('"', '\\"') + '"';
+}
+function expectedWindowsHookCommand(nodePath, hookPath) {
+    return windowsCommandArg(nodePath) + ' ' + windowsCommandArg(hookPath) + ' %EVOLCORE_INSTANCE_SOCKET%';
+}
+/**
+ * Run synthetic Windows shell probes for the managed Codex hook.
+ *
+ * This is intentionally called by ec diagnose, never by the hot hook path.
+ * The probes pass {} and therefore stop before contacting a live daemon.
+ */
+export function runCodexHookLaunchDiagnostic(options = {}) {
+    if ((options.platform ?? process.platform) !== 'win32') {
+        return {
+            status: 'skipped',
+            reason: 'Windows managed-hook launch probes are not applicable on this platform',
+            results: [],
+        };
+    }
+    const paths = codexManagedHookPaths(options);
+    if (!paths) {
+        return {
+            status: 'skipped',
+            reason: 'Windows managed-hook paths are unavailable on this platform',
+            results: [],
+        };
+    }
+    const requirements = path.resolve(options.requirements || paths.requirements);
+    const managedDir = path.resolve(options.managedDir || paths.managedDir);
+    const hookPath = path.join(managedDir, 'pre-tool-use.mjs');
+    const output = path.resolve(options.output
+        || path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'log', 'evolcore-hook-diagnostic.json'));
+    const runtimeLog = output + '.runtime.jsonl';
+    const nodePath = path.resolve(options.nodePath || process.execPath);
+    const config = parseToml(fs.readFileSync(requirements, 'utf8'));
+    const configuredDir = config.hooks?.windows_managed_dir ?? config.hooks?.managed_dir;
+    if (typeof configuredDir !== 'string')
+        throw new Error('No Windows managed hook directory configured.');
+    const expected = expectedWindowsHookCommand(nodePath, hookPath);
+    const handlers = Array.isArray(config.hooks?.PreToolUse)
+        ? config.hooks.PreToolUse.flatMap((group) => group?.hooks || [])
+        : [];
+    const handler = handlers.find((item) => (item?.type === 'command'
+        && (item.command_windows ?? item.commandWindows) === expected));
+    if (!handler || /[\r\n%;&|<>]/.test(nodePath + hookPath)) {
+        throw new Error('Managed command differs from the expected EvolCore command for this Node path; no hooks executed.');
+    }
+    fs.mkdirSync(path.dirname(output), { recursive: true, mode: 0o700 });
+    const env = { ...process.env, EVOLCORE_CODEX_HOOK_LOG: runtimeLog };
+    delete env.EVOLCORE_INSTANCE_SOCKET;
+    const comSpec = options.comSpec || process.env.ComSpec || 'C:/Windows/System32/cmd.exe';
+    const probes = [
+        { label: 'direct_node', executable: nodePath, args: [hookPath] },
+        { label: 'cmd_raw_command', executable: comSpec, args: ['/d', '/s', '/c', expected], windowsVerbatimArguments: true },
+        { label: 'cmd_outer_quotes', executable: comSpec, args: ['/d', '/s', '/c', '"' + expected + '"'], windowsVerbatimArguments: true },
+    ];
+    const results = probes.map(probe => {
+        const result = spawnSync(probe.executable, probe.args, {
+            input: '{}',
+            env,
+            windowsHide: true,
+            timeout: 5000,
+            maxBuffer: 64 * 1024,
+            windowsVerbatimArguments: probe.windowsVerbatimArguments,
+        });
+        return {
+            label: probe.label,
+            pid: result.pid,
+            exitCode: result.status,
+            signal: result.signal,
+            error: result.error?.message,
+            stdout: decodeProbeOutput(result.stdout),
+            stderr: decodeProbeOutput(result.stderr),
+            stderrBase64: result.stderr?.toString('base64'),
+        };
+    });
+    fs.writeFileSync(output, JSON.stringify({
+        time: new Date().toISOString(),
+        requirements,
+        hookPath,
+        command: expected,
+        nodeVersion: process.version,
+        nodePath,
+        socketEnvironmentPresent: Boolean(process.env.EVOLCORE_INSTANCE_SOCKET),
+        runtimeLog,
+        note: 'Synthetic launch probes; shell variants do not establish how Codex invoked the hook.',
+        results,
+    }, null, 2) + '\n', { mode: 0o600 });
+    return { status: 'ok', output, runtimeLog, results };
+}
+function regularFileState(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return 'unsafe';
+        return 'ok';
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return 'missing';
+        return 'unavailable';
+    }
+}
+function realDirectoryState(directory) {
+    try {
+        const stat = fs.lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return 'unsafe';
+        return 'ok';
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return 'missing';
+        return 'unavailable';
+    }
+}
+/** Read-only inspection of the machine-wide Windows Codex managed hook. */
+export function inspectCodexManagedHook(options = {}) {
+    const paths = codexManagedHookPaths(options);
+    if (!paths)
+        return { status: 'skipped', reason: 'Windows managed hooks are not applicable on this platform' };
+    const requirements = path.resolve(options.requirements || paths.requirements);
+    const managedDir = path.resolve(options.managedDir || paths.managedDir);
+    const hookPath = path.join(managedDir, 'pre-tool-use.mjs');
+    const configDirState = realDirectoryState(path.dirname(requirements));
+    const managedDirState = realDirectoryState(managedDir);
+    if ([configDirState, managedDirState].includes('unsafe')) {
+        return { status: 'unsafe', requirements, managedDir, hookPath, reason: 'requirements or managed-hook directory is not a real directory' };
+    }
+    if ([configDirState, managedDirState].includes('unavailable')) {
+        return { status: 'unavailable', requirements, managedDir, hookPath, reason: 'unable to inspect requirements or managed-hook directory' };
+    }
+    const requirementState = regularFileState(requirements);
+    const hookState = regularFileState(hookPath);
+    if ([requirementState, hookState].includes('unsafe')) {
+        return { status: 'unsafe', requirements, managedDir, hookPath, reason: 'requirements.toml or launcher is not a regular file' };
+    }
+    if ([requirementState, hookState].includes('unavailable')) {
+        return { status: 'unavailable', requirements, managedDir, hookPath, reason: 'unable to read requirements.toml or launcher' };
+    }
+    if (requirementState === 'missing' && hookState === 'ok') {
+        return { status: 'unsafe', requirements, managedDir, hookPath, reason: 'canonical launcher exists but requirements.toml is missing' };
+    }
+    if (requirementState === 'ok' && hookState === 'missing') {
+        // Match the installer's repair contract: a partial managed installation
+        // is drift; only an untouched user requirements file can be provisioned.
+        try {
+            const source = fs.readFileSync(requirements, 'utf8');
+            const partial = parseToml(source);
+            const hooks = partial.hooks;
+            if (source.includes('# BEGIN EVOLCORE MANAGED CODEX HOOK')
+                || source.includes('# END EVOLCORE MANAGED CODEX HOOK')
+                || partial.allow_managed_hooks_only !== undefined
+                || hooks?.windows_managed_dir !== undefined
+                || hooks?.managed_dir !== undefined) {
+                return { status: 'unsafe', requirements, managedDir, hookPath, reason: 'requirements contains managed-hook policy but the canonical launcher is missing' };
+            }
+        }
+        catch (error) {
+            return { status: 'unsafe', requirements, managedDir, hookPath, reason: `requirements.toml cannot be safely repaired: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    if ([requirementState, hookState].includes('missing')) {
+        return { status: 'missing', requirements, managedDir, hookPath, reason: 'requirements.toml or launcher is missing' };
+    }
+    let config;
+    let launcher;
+    let source;
+    try {
+        source = fs.readFileSync(requirements, 'utf8');
+    }
+    catch (error) {
+        return { status: 'unavailable', requirements, managedDir, hookPath, reason: error instanceof Error ? error.message : String(error) };
+    }
+    try {
+        config = parseToml(source);
+    }
+    catch (error) {
+        return { status: 'unsafe', requirements, managedDir, hookPath, reason: `requirements.toml is invalid: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    try {
+        launcher = fs.readFileSync(hookPath, 'utf8');
+    }
+    catch (error) {
+        return { status: 'unavailable', requirements, managedDir, hookPath, reason: error instanceof Error ? error.message : String(error) };
+    }
+    const normalized = (value) => path.normalize(String(value || '')).toLowerCase();
+    const expectedPackageRoot = path.resolve(options.packageRoot || process.cwd());
+    const launcherValid = launcher.includes('EVOLCORE_MANAGED_HOOK_LAUNCHER')
+        && launcher.toLowerCase().includes(JSON.stringify(expectedPackageRoot).toLowerCase());
+    const configuredDir = config.hooks?.windows_managed_dir ?? config.hooks?.managed_dir;
+    const groups = config.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 hookLoaded = Array.isArray(groups) && groups.some((group) => group?.matcher === '*'
+        && Array.isArray(group.hooks) && group.hooks.some((handler) => {
+        const command = typeof handler?.command === 'string' ? handler.command : '';
+        const windowsCommand = typeof handler?.command_windows === 'string' ? handler.command_windows : '';
+        return handler?.type === 'command' && handler.async !== true
+            && canonicalCommand(command) && canonicalCommand(windowsCommand);
+    }));
+    const valid = config.allow_managed_hooks_only === true
+        && config.features?.hooks === true
+        && normalized(configuredDir) === normalized(managedDir)
+        && launcherValid && hookLoaded;
+    return valid
+        ? { status: 'installed', requirements, managedDir, hookPath }
+        : { status: 'unsafe', requirements, managedDir, hookPath, reason: 'managed-hook policy is missing, altered, or points outside the canonical target' };
+}
+function powershellLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+/** Start-Process joins ArgumentList into a native command line, even for arrays. */
+function windowsArgument(value) {
+    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`;
+}
+export function buildCodexManagedHookElevationCommand(options) {
+    const argumentLine = [options.installer, '--package-root', options.packageRoot,
+        '--requirements', options.requirements, '--managed-dir', options.managedDir, '--repair']
+        .map(windowsArgument).join(' ');
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        "$ProgressPreference = 'SilentlyContinue'",
+        'try {',
+        `  $p = Start-Process -FilePath ${powershellLiteral(options.nodePath)} -ArgumentList ${powershellLiteral(argumentLine)} -WorkingDirectory ${powershellLiteral(options.packageRoot)} -Verb RunAs -WindowStyle Hidden -Wait -PassThru -ErrorAction Stop`,
+        '  exit $p.ExitCode',
+        '} catch {',
+        '  [Console]::Error.WriteLine($_.Exception.Message)',
+        '  exit 1',
+        '}',
+    ].join('\n');
+}
+/**
+ * Ensure the machine-wide Windows hook before starting the daemon. Missing
+ * files are repaired through one UAC elevation; altered policy remains
+ * fail-closed and is never overwritten automatically.
+ */
+export function ensureCodexManagedHook(options) {
+    const platformName = options.platform ?? process.platform;
+    const paths = codexManagedHookPaths({
+        platform: platformName,
+        programData: options.programData,
+        homeDir: options.homeDir,
+    });
+    if (!paths)
+        return { status: 'skipped', reason: 'Windows managed hooks are not applicable on this platform' };
+    const inspectOptions = {
+        platform: platformName,
+        packageRoot: options.packageRoot,
+        requirements: options.requirements || paths.requirements,
+        managedDir: options.managedDir || paths.managedDir,
+        programData: options.programData,
+        homeDir: options.homeDir,
+    };
+    let state = inspectCodexManagedHook(inspectOptions);
+    if (state.status === 'installed')
+        return { ...state, repaired: false };
+    if (state.status !== 'missing')
+        return { ...state, repaired: false };
+    const installer = path.join(path.resolve(options.packageRoot), 'bin', 'install-codex-managed-hooks.mjs');
+    if (!fs.existsSync(installer)) {
+        return { ...state, repaired: false, error: `managed-hook installer is missing: ${installer}` };
+    }
+    const runElevated = options.runElevated || ((script, packageRoot) => {
+        const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+        const command = buildCodexManagedHookElevationCommand({
+            nodePath: process.execPath, installer: script, packageRoot,
+            requirements: path.resolve(inspectOptions.requirements),
+            managedDir: path.resolve(inspectOptions.managedDir),
+        });
+        const result = spawnSync(powershell, [
+            // Do not use -NonInteractive here: Start-Process -Verb RunAs must be
+            // able to show the UAC consent dialog on the secure desktop.
+            '-NoProfile', '-ExecutionPolicy', 'Bypass',
+            '-EncodedCommand', Buffer.from(command, 'utf16le').toString('base64'),
+        ], { encoding: 'utf8', windowsHide: true });
+        if (result.error)
+            return { ok: false, detail: result.error.message };
+        if (result.status !== 0) {
+            const detail = (result.stderr || '').replace(/#<\s*CLIXML[\s\S]*?<\/Objs>\s*/gi, '').trim();
+            return { ok: false, detail: detail || `installer exited with code ${result.status}` };
+        }
+        return { ok: true };
+    });
+    options.onInstallRequired?.();
+    let elevated;
+    try {
+        elevated = runElevated(installer, path.resolve(options.packageRoot));
+    }
+    catch (error) {
+        elevated = { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+    if (!elevated.ok) {
+        return { ...state, repaired: false, error: elevated.detail || 'elevated managed-hook installation failed' };
+    }
+    state = inspectCodexManagedHook(inspectOptions);
+    return state.status === 'installed'
+        ? { ...state, repaired: true }
+        : { ...state, repaired: false, error: state.reason || 'managed-hook installation did not pass verification' };
+}