evolcore 0.0.23 → 0.0.24

package/dist/agents/claude-runner.js

@@ -1,6 +1,7 @@
 import { getRunnerCatalog, peekRunnerCatalog, catalogEfforts, resolveCatalogModel, assertCatalogSelectable } from '../core/model/model-catalog.js';
 import { query, forkSession as sdkForkSession, getSessionMessages as sdkGetSessionMessages, resolveSettings as sdkResolveSettings, } from '@anthropic-ai/claude-agent-sdk';
 import { spawn } from 'child_process';
+import { createRequire } from 'module';
 import { ensureDir } from '../utils/atomic-write.js';
 import { resolveAnthropicConfig } from './baseagent.js';
 import { buildModelRequestHeaders } from './request-identity.js';
@@ -30,6 +31,42 @@ import { auditToolInfrastructureFailure, auditToolPreflightDenial } from '../cor
 import { getManagedTaskTempDir, isManagedSessionRuntimeDir } from '../cli/task-context.js';
 import { hasTrustedFullAccessContext } from './runner-types.js';
 import { contextTokensForUsage, usageForContext, isClaudeContextUsageModel, isOneMillionContextModel, realContextWindowForModel, autoCompactWindowForModel } from './runner-types.js';
+const resolveModule = createRequire(import.meta.url);
+/**
+ * Resolve the platform package explicitly instead of relying on the SDK's
+ * internal optional-dependency lookup. The latter is sensitive to the module
+ * installation/loader context and can report a missing binary even when the
+ * package is present in the same node_modules tree.
+ */
+export function resolveBundledClaudeExecutable() {
+    if (process.platform !== 'win32')
+        return undefined;
+    const nativePackage = process.arch === 'arm64'
+        ? '@anthropic-ai/claude-agent-sdk-win32-arm64'
+        : process.arch === 'x64'
+            ? '@anthropic-ai/claude-agent-sdk-win32-x64'
+            : undefined;
+    if (!nativePackage)
+        return undefined;
+    const binarySpecifier = `${nativePackage}/claude.exe`;
+    try {
+        const executable = resolveModule.resolve(binarySpecifier);
+        if (fs.existsSync(executable))
+            return executable;
+    }
+    catch {
+        // Fall through to a direct sibling lookup for package layouts where the
+        // optional package does not expose its binary through exports.
+    }
+    try {
+        const sdkEntry = resolveModule.resolve('@anthropic-ai/claude-agent-sdk');
+        const executable = path.resolve(path.dirname(sdkEntry), '..', '@anthropic-ai', nativePackage.slice('@anthropic-ai/'.length), 'claude.exe');
+        return fs.existsSync(executable) ? executable : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export { hasCompact, hasModelSwitcher, hasPermissionController } from './runner-types.js';
 // Built-in tools execute inside the Claude runtime and are covered by the
 // runner's filesystem/shell policy. MCP and future unknown tools can perform
@@ -109,6 +146,40 @@ function appendQueryParams(baseUrl, queryParams) {
         return baseUrl;
     }
 }
+function claudeSessionFilePath(projectPath, agentSessionId) {
+    return path.join(os.homedir(), '.claude', 'projects', encodePath(projectPath), `${agentSessionId}.jsonl`);
+}
+/** A discovered Claude session is resumable only after its transcript header is durable. */
+function isClaudeSessionFileReady(projectPath, agentSessionId) {
+    const sessionFile = claudeSessionFilePath(projectPath, agentSessionId);
+    if (!fs.existsSync(sessionFile))
+        return false;
+    try {
+        const content = fs.readFileSync(sessionFile, 'utf8');
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const data = JSON.parse(line);
+                if (data.sessionId && data.version)
+                    return true;
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return false;
+}
+async function waitForClaudeSessionFile(projectPath, agentSessionId, timeoutMs = 250) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if (isClaudeSessionFileReady(projectPath, agentSessionId))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise(resolve => setTimeout(resolve, 10));
+    } while (true);
+}
 function stableClaudePermissionValue(value, depth = 0) {
     if (depth > 8)
         return '[truncated]';
@@ -504,9 +575,10 @@ export class AgentRunner {
         this.agentAid = runtime?.agentAid ?? legacy?.['evolcoreAgentAid'];
         this.agentConfig = runtime?.agentConfig ?? legacy?.['evolcoreAgentConfig'];
         this.onSessionIdUpdate = onSessionIdUpdate;
+        this.claudeExecutablePath = resolveBundledClaudeExecutable();
         if (config) {
             const anthropic = resolveAnthropicConfig(config);
-            this.claudeExecutablePath = anthropic.pathToClaudeCodeExecutable;
+            this.claudeExecutablePath = anthropic.pathToClaudeCodeExecutable || this.claudeExecutablePath;
             this.customHeaders = buildModelRequestHeaders({
                 baseagent: 'claude',
                 baseUrl: anthropic.baseUrl,
@@ -1257,8 +1329,9 @@ export class AgentRunner {
      * SDK 原始事件 → 标准 AgentEvent 转换
      * 所有 SDK 特有的事件类型引用封装在此方法内
      */
-    async *transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, isResuming = false, sandboxSettingsFile, permissionMode, turn) {
+    async *transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, isResuming = false, sandboxSettingsFile, permissionMode, turn, projectPath = process.cwd(), topicBinding = false) {
         let lastSessionId;
+        let pendingSessionId;
         let hasTurnActivity = false;
         let ignoredPreTurnResult = false;
         let waitingForBackgroundCompletion = false;
@@ -1278,19 +1351,41 @@ export class AgentRunner {
         let lastAssistantUuid;
         // 流式收集各次大模型调用（fallback：SDK iterations 为空时使用）
         const collectedCalls = [];
+        const activatePendingSession = async (waitForFile) => {
+            const candidate = pendingSessionId;
+            if (!candidate)
+                return undefined;
+            if (!isResuming && topicBinding) {
+                const ready = waitForFile
+                    ? await waitForClaudeSessionFile(projectPath, candidate)
+                    : isClaudeSessionFileReady(projectPath, candidate);
+                if (!ready)
+                    return undefined;
+            }
+            if (!await this.acceptDiscoveredSessionId(sessionId, candidate, turn)) {
+                logger.warn(`[AgentRunner] Rejected stale backend discovery: sessionId=${sessionId} backend=${candidate} turn=${turn?.turnId ?? 'legacy'}`);
+                const error = new Error('backend discovery rejected by active turn lease');
+                error.code = 'TOPIC_BACKEND_DISCOVERY_REJECTED';
+                throw error;
+            }
+            pendingSessionId = undefined;
+            return candidate;
+        };
         try {
             for await (const event of sdkStream) {
+                const activatedBeforeEvent = await activatePendingSession(false);
+                if (activatedBeforeEvent)
+                    yield { type: 'session_id', sessionId: activatedBeforeEvent };
                 // 提取 session_id（任意 SDK 事件都可能携带）
                 if (event.session_id && event.session_id !== lastSessionId) {
                     lastSessionId = event.session_id;
-                    if (await this.acceptDiscoveredSessionId(sessionId, event.session_id, turn)) {
-                        yield { type: 'session_id', sessionId: event.session_id };
+                    pendingSessionId = event.session_id;
+                    const activated = await activatePendingSession(event.type === 'result');
+                    if (activated) {
+                        yield { type: 'session_id', sessionId: activated };
                     }
-                    else {
-                        logger.warn(`[AgentRunner] Rejected stale backend discovery: sessionId=${sessionId} backend=${event.session_id} turn=${turn?.turnId ?? 'legacy'}`);
-                        const error = new Error('backend discovery rejected by active turn lease');
-                        error.code = 'TOPIC_BACKEND_DISCOVERY_REJECTED';
-                        throw error;
+                    else if (!isResuming) {
+                        logger.info(`[AgentRunner] Deferring backend activation until Claude session file is durable: sessionId=${sessionId} backend=${event.session_id}`);
                     }
                 }
                 if (event.type === 'user' && event.uuid === inputId) {
@@ -1385,7 +1480,17 @@ export class AgentRunner {
                 }
                 if (event.type === 'stream_event') {
                     const streamEvent = event.event;
-                    if (streamEvent?.type === 'message_start' && streamEvent.message?.usage) {
+                    if (streamEvent?.type === 'content_block_start'
+                        && (streamEvent.content_block?.type === 'thinking' || streamEvent.content_block?.type === 'redacted_thinking')) {
+                        hasTurnActivity = true;
+                        yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                    }
+                    else if (streamEvent?.type === 'content_block_delta'
+                        && streamEvent.delta?.type === 'thinking_delta') {
+                        hasTurnActivity = true;
+                        yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                    }
+                    else if (streamEvent?.type === 'message_start' && streamEvent.message?.usage) {
                         hasTurnActivity = true;
                         lastAssistantWasSynthetic = streamEvent.message.model === '<synthetic>';
                         lastModelCall = {
@@ -1419,6 +1524,13 @@ export class AgentRunner {
                     }
                     continue;
                 }
+                // During redacted thinking Claude may emit token estimates instead of
+                // readable thinking deltas. They still prove the model is active.
+                if (event.type === 'system' && event.subtype === 'thinking_tokens') {
+                    hasTurnActivity = true;
+                    yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                    continue;
+                }
                 // system: compact_boundary → compact
                 if (event.type === 'system' && event.subtype === 'compact_boundary') {
                     yield {
@@ -1489,7 +1601,11 @@ export class AgentRunner {
                     // 统计本轮 base agent 全部输出字符数（text + tool_use input）
                     let turnOutputChars = 0;
                     for (const content of event.message.content) {
-                        if (content.type === 'tool_use') {
+                        if (content.type === 'thinking' || content.type === 'redacted_thinking') {
+                            hasTurnActivity = true;
+                            yield { type: 'heartbeat', source: 'reasoning', turn: turnCount || undefined };
+                        }
+                        else if (content.type === 'tool_use') {
                             const inputStr = typeof content.input === 'string' ? content.input : JSON.stringify(content.input || '');
                             turnOutputChars += inputStr.length;
                         }
@@ -1532,6 +1648,12 @@ export class AgentRunner {
                 }
                 // result → complete（含 permission_denials 提取）
                 if (event.type === 'result') {
+                    // The SDK may announce session_id on the initial system event and omit
+                    // it from the terminal result. Give the transcript a short grace
+                    // period here before deciding that a topic backend is unavailable.
+                    const activatedAtResult = await activatePendingSession(true);
+                    if (activatedAtResult)
+                        yield { type: 'session_id', sessionId: activatedAtResult };
                     // Most SDK streams surface denials as user-message tool_result blocks.
                     // The terminal summary is only a fallback for incomplete streams.
                     if (Array.isArray(event.permission_denials)) {
@@ -1661,6 +1783,15 @@ export class AgentRunner {
                         modelCalls,
                         assistantUuid: lastAssistantUuid,
                     };
+                    // A topic binding must never outlive the provider transcript that can
+                    // resume it. If Claude reports success before its session file becomes
+                    // durable, fail this turn while leaving the topic unbound; /renew is
+                    // then available for older sessions that already contain a bad bind.
+                    if (!event.is_error && topicBinding && pendingSessionId) {
+                        const error = new Error(`bound topic backend is unavailable: ${pendingSessionId}`);
+                        error.code = 'TOPIC_BACKEND_UNAVAILABLE';
+                        throw error;
+                    }
                     // Fatal results belong to the query transport itself and must terminate
                     // even when the current input was not echoed back by the CLI.
                     if (event.is_error) {
@@ -2613,7 +2744,7 @@ export class AgentRunner {
             this.interruptFns.set(sessionId, () => sdkStream.interrupt());
         }
         // 返回标准 AgentEvent 流（重试由 MessageProcessor 层负责）
-        const transformed = this.transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, !!agentSessionId, sandboxSettingsFile, callPermissionMode, modelOverride?.turn);
+        const transformed = this.transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, !!agentSessionId, sandboxSettingsFile, callPermissionMode, modelOverride?.turn, projectPath, topicBinding);
         const self = this;
         return (async function* () {
             try {
@@ -2768,7 +2899,10 @@ export class AgentRunner {
                 managedSettings: buildClaudeManagedLockdownSettings(),
                 ...(catalog && callEffort ? { effort: callEffort } : {}),
                 permissionMode: this.toSdkPermissionMode(),
-                env: this.getAgentEnv()
+                env: this.getAgentEnv(),
+                ...(this.claudeExecutablePath
+                    ? { pathToClaudeCodeExecutable: this.claudeExecutablePath }
+                    : {})
             }
         });
     }
@@ -3020,6 +3154,7 @@ export class AgentRunner {
                 strictMcpConfig: true,
                 settingSources: [],
                 managedSettings: buildClaudeManagedLockdownSettings(),
+                ...(this.claudeExecutablePath ? { pathToClaudeCodeExecutable: this.claudeExecutablePath } : {}),
                 permissionMode: this.toSdkPermissionMode(),
                 stderr: (data) => { stderrChunks.push(data); },
                 env: this.getAgentEnv(),

package/dist/agents/codex/app-server-client.js

@@ -2,7 +2,7 @@ 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 { resolveCodexLaunchCommand } from '../baseagent.js';
 import { createHash } from 'crypto';
 import { sanitizeShellExecutionEnvironment } from '../../core/permission/shell-environment.js';
 import fs from 'fs';
@@ -65,6 +65,7 @@ export class CodexAppServerClient {
     initialized = false;
     initializing = null;
     stderrBuffer = [];
+    stderrSequence = 0;
     managedHookRuntimeDir = null;
     processRegistrationPath = null;
     constructor(options) {
@@ -539,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}`);
@@ -612,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;
@@ -720,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() {
@@ -769,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;
@@ -843,7 +850,10 @@ 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)) {

package/dist/agents/codex/catalog.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { CodexAppServerClient } from './app-server-client.js';
-import { resolveCodexLaunchCommand } from '../../utils/codex-cli.js';
+import { resolveCodexLaunchCommand } from '../baseagent.js';
 import { parseModelList } from '../../core/model/catalog-service.js';
 async function cliModels() {
     const launch = resolveCodexLaunchCommand(['debug', 'models']);

package/dist/agents/codex/diagnostics.js

@@ -1,6 +1,7 @@
 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() : '';
@@ -51,6 +52,107 @@ export function codexManagedHookPaths(options = {}) {
     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);
@@ -101,6 +203,28 @@ export function inspectCodexManagedHook(options = {}) {
     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' };
     }
@@ -152,3 +276,94 @@ export function inspectCodexManagedHook(options = {}) {
         ? { 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' };
+}