oh-my-codex 0.20.0 → 0.20.2

package/dist/cli/doctor.js

@@ -1,10 +1,11 @@
 /**
  * omx doctor - Validate oh-my-codex installation
  */
+import { recoverNativeHookClaimJournal } from "./native-hook-claim-journal.js";
 import { constants, existsSync, readFileSync } from "fs";
-import { access, chown, lstat, mkdtemp, readdir, readFile, rm } from "fs/promises";
+import { access, chown, lstat, mkdtemp, readdir, readFile, rmdir, rm } from "fs/promises";
 import { spawnSync } from "child_process";
-import { basename, join, relative } from "path";
+import { basename, dirname, join, relative } from "path";
 import { tmpdir } from "os";
 import { codexHome, codexConfigPath, codexPromptsDir, userSkillsDir, projectSkillsDir, omxStateDir, detectLegacySkillRootOverlap, codexAgentsDir, } from "../utils/paths.js";
 import { classifySpawnError, spawnPlatformCommandSync, } from "../utils/platform-command.js";
@@ -12,8 +13,8 @@ import { getCatalogExpectations } from "./catalog-contract.js";
 import { parse as parseToml } from "@iarna/toml";
 import { getBuiltinExploreHarnessUnsupportedReason, resolvePackagedExploreHarnessCommand, EXPLORE_BIN_ENV, } from "./explore.js";
 import { getPackageRoot } from "../utils/package.js";
-import { hasLegacyOmxTeamRunTable, getModelContextRecommendation, } from "../config/generator.js";
-import { MANAGED_HOOK_EVENTS, buildManagedCodexNativeHookCommand, discoverCodexHookConfigPaths, resolveWindowsPowerShellPath, getManagedCodexHookCommandsForEvent, getMissingManagedCodexHookEvents, hasCodexHooksJsonTopLevelState, } from "../config/codex-hooks.js";
+import { analyzeLegacyMultiAgentConfig, hasExactOmxSeededBehavioralDefaultsPair, hasLegacyOmxTeamRunTable, } from "../config/generator.js";
+import { MANAGED_HOOK_EVENTS, buildManagedCodexNativeHookCommand, buildManagedCodexNativeHookWindowsShimContent, classifyManagedCodexNativeHookWindowsShimOwnership, discoverCodexHookConfigPaths, isManagedCodexHookCommand, parseManagedCodexNativeHookWindowsShimCommand, planManagedCodexHooksRemoval, resolveWindowsPowerShellPath, validateCodexHooksConfigStrict, } from "../config/codex-hooks.js";
 import { OMX_FIRST_PARTY_MCP_SERVER_NAMES } from "../config/omx-first-party-mcp.js";
 import { getDefaultBridge, isBridgeEnabled } from "../runtime/bridge.js";
 import { OMX_EXPLORE_CMD_ENV, isExploreCommandRoutingEnabled, } from "../hooks/explore-routing.js";
@@ -124,6 +125,7 @@ export async function doctor(options = {}) {
     const cwd = process.cwd();
     const scopeResolution = await resolveDoctorScope(cwd);
     const paths = resolveDoctorPaths(cwd, scopeResolution.scope);
+    await recoverNativeHookClaimJournal(paths.codexHomeDir);
     const scopeSourceMessage = scopeResolution.source === "persisted"
         ? " (from .omx/setup-scope.json)"
         : scopeResolution.source === "config"
@@ -170,19 +172,26 @@ export async function doctor(options = {}) {
     // Check 3: Codex home directory
     checks.push(checkDirectory("Codex home", paths.codexHomeDir));
     // Check 4: Config file
-    checks.push(await checkConfig(paths.configPath));
-    // Check 4.1: Model context recommendation
-    const contextRecommendationCheck = await checkModelContextRecommendation(paths.configPath);
-    if (contextRecommendationCheck)
-        checks.push(contextRecommendationCheck);
+    const configCheck = await checkConfig(paths.configPath);
+    checks.push(configCheck);
+    const multiAgentCompatibilityCheck = await checkLegacyMultiAgentCompatibility(paths.configPath, scopeResolution.scope);
+    if (multiAgentCompatibilityCheck)
+        checks.push(multiAgentCompatibilityCheck);
+    // Check 4.1: unchanged OMX-seeded context defaults
+    if (configCheck.status !== "fail") {
+        const seededContextDefaultsCheck = await checkSeededContextDefaults(paths.configPath);
+        if (seededContextDefaultsCheck)
+            checks.push(seededContextDefaultsCheck);
+    }
     // Check 4.25: Native hooks coverage
-    checks.push(await checkNativeHooks(paths.hooksPath, paths.configPath, {
+    const nativeHooksCheck = await checkNativeHooks(paths.hooksPath, paths.configPath, {
         codexHomeDir: paths.codexHomeDir,
         installMode: scopeResolution.installMode,
-    }));
+    });
+    checks.push(nativeHooksCheck);
     checks.push(await checkNativeHookDistSmoke());
     if (options.verbose) {
-        const postCompactRuntimeCheck = await checkNativePostCompactHookRuntime(paths.hooksPath, cwd, paths.codexHomeDir);
+        const postCompactRuntimeCheck = await checkNativePostCompactHookRuntime(paths.hooksPath, cwd, paths.codexHomeDir, { nativeHooksCheck });
         if (postCompactRuntimeCheck)
             checks.push(postCompactRuntimeCheck);
     }
@@ -243,10 +252,10 @@ export async function doctor(options = {}) {
     }
     console.log(`\nResults: ${passCount} passed, ${warnCount} warnings, ${failCount} failed`);
     if (failCount > 0) {
-        console.log('\nRun "omx setup" to fix installation issues.');
+        console.log('\nReview failed checks above. Follow the check-specific recovery guidance; inspect invalid or ambiguous hook documents manually because doctor will not modify them.');
     }
     else if (warnCount > 0) {
-        console.log('\nReview warnings above. Use "omx setup --force" only when a warning recommends full replacement; for AGENTS.md preservation prefer "omx setup --merge-agents".');
+        console.log('\nReview warnings above. Follow the check-specific recovery guidance; for AGENTS.md preservation prefer "omx setup --merge-agents".');
     }
     else {
         console.log("\nAll checks passed! oh-my-codex is ready.");
@@ -854,6 +863,32 @@ function validateToml(content) {
         return "unknown TOML parse error";
     }
 }
+export async function checkLegacyMultiAgentCompatibility(configPath, scope) {
+    if (!existsSync(configPath))
+        return null;
+    try {
+        const content = await readFile(configPath, "utf-8");
+        if (validateToml(content))
+            return null;
+        const affected = Object.values(analyzeLegacyMultiAgentConfig(content).assessments).filter((assessment) => assessment.state !== "absent");
+        if (affected.length === 0)
+            return null;
+        const details = affected
+            .map(({ key, state, reasonCode }) => `${key} (${state}; ${reasonCode})`)
+            .join(", ");
+        return {
+            name: "GPT-5.6 multi-agent compatibility",
+            status: "warn",
+            message: `${scope} scope config at ${configPath}: ${details}. ` +
+                "OMX preserves these settings because historical ownership cannot be proven. " +
+                `Back up ${configPath}, remove only keys you confirm OMX authored, rerun omx setup --scope ${scope}, then omx doctor. ` +
+                "Setup does not auto-delete them.",
+        };
+    }
+    catch {
+        return null;
+    }
+}
 async function checkConfig(configPath) {
     if (!existsSync(configPath)) {
         return { name: "Config", status: "warn", message: "config.toml not found" };
@@ -902,38 +937,17 @@ async function checkConfig(configPath) {
         };
     }
 }
-function formatContextRecommendationWarning(configuredValues, recommendedContextWindow, recommendedAutoCompactLimit) {
-    return `${configuredValues.join(", ")} exceeds the OMX setup recommendation for gpt-5.6-sol (${recommendedContextWindow} / ${recommendedAutoCompactLimit}); doctor does not rewrite user config, so lower these values or verify your active Codex runtime/provider behavior if this customization is intentional`;
-}
-async function checkModelContextRecommendation(configPath) {
+async function checkSeededContextDefaults(configPath) {
     if (!existsSync(configPath))
         return null;
     try {
         const content = await readFile(configPath, "utf-8");
-        const parsed = parseToml(content);
-        const model = parsed.model;
-        if (typeof model !== "string")
-            return null;
-        const recommendation = getModelContextRecommendation(model);
-        if (!recommendation)
-            return null;
-        const configuredValues = [];
-        const contextWindow = parsed.model_context_window;
-        if (typeof contextWindow === "number" &&
-            contextWindow > recommendation.modelContextWindow) {
-            configuredValues.push(`model_context_window=${contextWindow}`);
-        }
-        const autoCompactLimit = parsed.model_auto_compact_token_limit;
-        if (typeof autoCompactLimit === "number" &&
-            autoCompactLimit > recommendation.modelAutoCompactTokenLimit) {
-            configuredValues.push(`model_auto_compact_token_limit=${autoCompactLimit}`);
-        }
-        if (configuredValues.length === 0)
+        if (!hasExactOmxSeededBehavioralDefaultsPair(content))
             return null;
         return {
-            name: "Model context recommendation",
+            name: "Legacy OMX context defaults",
             status: "warn",
-            message: formatContextRecommendationWarning(configuredValues, recommendation.modelContextWindow, recommendation.modelAutoCompactTokenLimit),
+            message: "config.toml contains unchanged OMX-seeded context defaults; rerun \"omx setup\" to migrate them. Doctor did not rewrite config.",
         };
     }
     catch {
@@ -1218,6 +1232,183 @@ function configEnablesPluginScopedHooks(configContent) {
         return /^\s*plugin_hooks\s*=\s*(?:true|1|"true"|"1"|"yes"|"on")\s*$/m.test(configContent);
     }
 }
+function trimNativeHookDetailTerminalPeriod(detail) {
+    return detail.endsWith(".") ? detail.slice(0, -1) : detail;
+}
+function formatNativeHookDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => {
+        const coordinate = `${diagnostic.eventName}[${diagnostic.groupIndex}]${diagnostic.handlerIndex === undefined
+            ? ""
+            : `.${diagnostic.handlerIndex}`}`;
+        return `${coordinate}: ${trimNativeHookDetailTerminalPeriod(diagnostic.message)}`;
+    })
+        .join("; ");
+}
+function isJsonRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const WINDOWS_SHIM_SCAN_EVENTS = [
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "SessionStart",
+    "UserPromptSubmit",
+    "SubagentStart",
+    "SubagentStop",
+    "Stop",
+];
+function effectiveWindowsHookCommand(handler) {
+    const commandWindows = handler.commandWindows;
+    if (typeof commandWindows === "string")
+        return commandWindows;
+    const commandWindowsSnakeCase = handler.command_windows;
+    if (typeof commandWindowsSnakeCase === "string")
+        return commandWindowsSnakeCase;
+    return typeof handler.command === "string" ? handler.command : null;
+}
+function referencedWindowsNativeHookShimPaths(root, diagnostics, codexHomeDir) {
+    if (!isJsonRecord(root.hooks))
+        return [];
+    const skippedGroups = new Set(diagnostics
+        .filter((diagnostic) => diagnostic.code === "invalid_matcher")
+        .map((diagnostic) => `${diagnostic.eventName}:${diagnostic.groupIndex}`));
+    const skippedHandlers = new Set(diagnostics
+        .filter((diagnostic) => diagnostic.code === "async_command" || diagnostic.code === "empty_command")
+        .map((diagnostic) => `${diagnostic.eventName}:${diagnostic.groupIndex}:${diagnostic.handlerIndex}`));
+    const shimPaths = new Set();
+    for (const eventName of WINDOWS_SHIM_SCAN_EVENTS) {
+        const eventGroups = root.hooks[eventName];
+        if (!Array.isArray(eventGroups))
+            continue;
+        for (const [groupIndex, group] of eventGroups.entries()) {
+            if (skippedGroups.has(`${eventName}:${groupIndex}`) || !isJsonRecord(group) || !Array.isArray(group.hooks))
+                continue;
+            for (const [handlerIndex, handler] of group.hooks.entries()) {
+                if (skippedHandlers.has(`${eventName}:${groupIndex}:${handlerIndex}`) ||
+                    !isJsonRecord(handler) ||
+                    handler.type !== "command")
+                    continue;
+                const command = effectiveWindowsHookCommand(handler);
+                if (!command)
+                    continue;
+                const shimPath = parseManagedCodexNativeHookWindowsShimCommand(command, {
+                    platform: "win32",
+                    codexHomeDir,
+                });
+                if (shimPath)
+                    shimPaths.add(shimPath);
+            }
+        }
+    }
+    return [...shimPaths];
+}
+async function checkWindowsNativeHookShimParentTopology(shimPath, codexHomeDir) {
+    let ancestorPath = dirname(shimPath);
+    for (;;) {
+        try {
+            const ancestorStat = await lstat(ancestorPath);
+            if (ancestorStat.isSymbolicLink() || !ancestorStat.isDirectory()) {
+                return {
+                    name: "Native hooks",
+                    status: "fail",
+                    message: `referenced Windows native hook shim at ${shimPath} has an unsafe parent topology at ${ancestorPath}; doctor will not follow or modify it`,
+                };
+            }
+        }
+        catch {
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: `referenced Windows native hook shim at ${shimPath} has a parent topology that cannot be safely validated; doctor will not follow or modify it`,
+            };
+        }
+        if (ancestorPath === codexHomeDir)
+            return null;
+        const parentPath = dirname(ancestorPath);
+        if (parentPath === ancestorPath) {
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: `referenced Windows native hook shim at ${shimPath} is outside the controlled Codex home topology; doctor will not follow or modify it`,
+            };
+        }
+        ancestorPath = parentPath;
+    }
+}
+async function checkWindowsNativeHookShims(root, diagnostics, codexHomeDir, requireCurrent = false) {
+    const expected = Buffer.from(buildManagedCodexNativeHookWindowsShimContent(getPackageRoot()), "utf-8");
+    for (const shimPath of referencedWindowsNativeHookShimPaths(root, diagnostics, codexHomeDir)) {
+        let shimContent;
+        try {
+            const shimStat = await lstat(shimPath);
+            if (shimStat.isSymbolicLink() || !shimStat.isFile()) {
+                return {
+                    name: "Native hooks",
+                    status: "fail",
+                    message: `referenced Windows native hook shim at ${shimPath} is not a regular file; doctor will not follow or modify it`,
+                };
+            }
+            if (shimStat.nlink !== 1) {
+                return {
+                    name: "Native hooks",
+                    status: "fail",
+                    message: `referenced Windows native hook shim at ${shimPath} is hard-linked; doctor will not execute or modify it`,
+                };
+            }
+            shimContent = await readFile(shimPath);
+            const topologyCheck = await checkWindowsNativeHookShimParentTopology(shimPath, codexHomeDir);
+            if (topologyCheck)
+                return topologyCheck;
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null && "code" in error
+                ? String(error.code)
+                : undefined;
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: code === "ENOENT"
+                    ? `referenced Windows native hook shim is missing at ${shimPath}; manually reinstall the matching oh-my-codex version because doctor will not create or modify shims`
+                    : `cannot read referenced Windows native hook shim at ${shimPath}; inspect it and manually reinstall the matching oh-my-codex version because doctor will not modify shims`,
+            };
+        }
+        const ownership = classifyManagedCodexNativeHookWindowsShimOwnership(shimContent, expected);
+        if (ownership === "modified") {
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: `referenced Windows native hook shim at ${shimPath} is not an exact current or complete historical generated shim; it may be modified, truncated, have extra content, or use ambiguous encoding. Manually reinstall the matching oh-my-codex version because doctor will not overwrite it`,
+            };
+        }
+        if (requireCurrent && ownership !== "current") {
+            return {
+                name: "Native hooks",
+                status: "warn",
+                message: `referenced Windows native hook shim at ${shimPath} is a complete historical generated shim, but verbose execution requires exact current shim bytes; run "omx setup" to migrate it before retrying`,
+            };
+        }
+    }
+    return null;
+}
+const MANAGED_HOOK_TRUST_KEY_LABELS = {
+    SessionStart: "session_start",
+    PreToolUse: "pre_tool_use",
+    PostToolUse: "post_tool_use",
+    UserPromptSubmit: "user_prompt_submit",
+    PreCompact: "pre_compact",
+    PostCompact: "post_compact",
+    Stop: "stop",
+};
+function getMissingManagedHookEventsFromPlan(plan) {
+    return MANAGED_HOOK_EVENTS.filter((eventName) => {
+        const label = MANAGED_HOOK_TRUST_KEY_LABELS[eventName];
+        const keyPattern = new RegExp(`:${label}:\\d+:\\d+$`);
+        return !Object.keys(plan.priorTrustState).some((key) => keyPattern.test(key));
+    });
+}
 function pluginHooksJsonHasNativeCoverage(content) {
     try {
         const parsed = JSON.parse(content);
@@ -1249,7 +1440,7 @@ function pluginHooksJsonHasNativeCoverage(content) {
 }
 async function checkPluginScopedNativeHooks(codexHomeDir, setupHooksPath) {
     const setupHooksPathDescription = existsSync(setupHooksPath)
-        ? `existing hooks.json at ${setupHooksPath} is treated as user-owned because plugin-scoped hooks are enabled`
+        ? `existing hooks.json at ${setupHooksPath} is retained read-only and validated separately because plugin-scoped hooks are enabled`
         : `setup-owned hooks.json is intentionally absent at ${setupHooksPath}`;
     const packagedMarketplace = await resolvePackagedOmxMarketplace(getPackageRoot());
     if (!packagedMarketplace) {
@@ -1271,14 +1462,14 @@ async function checkPluginScopedNativeHooks(codexHomeDir, setupHooksPath) {
         return {
             name: "Native hooks",
             status: "warn",
-            message: `plugin-scoped hooks are enabled, but the expected Codex plugin cache manifest is missing at ${join(expectedCacheDir, ".codex-plugin", "plugin.json")}; ${setupHooksPathDescription}; run "omx setup --plugin --force" to refresh the plugin cache`,
+            message: `plugin-scoped hooks are enabled, but the expected Codex plugin cache manifest is missing at ${join(expectedCacheDir, ".codex-plugin", "plugin.json")}; ${setupHooksPathDescription}; run "omx setup --plugin" to refresh the plugin cache`,
         };
     }
     if (state.hooksPointer !== "./hooks/hooks.json") {
         return {
             name: "Native hooks",
             status: "warn",
-            message: `plugin-scoped hooks are enabled, but the Codex plugin cache manifest points hooks to ${String(state.hooksPointer)} instead of ./hooks/hooks.json at ${expectedHooksPath}; run "omx setup --plugin --force" to refresh the plugin cache`,
+            message: `plugin-scoped hooks are enabled, but the Codex plugin cache manifest points hooks to ${String(state.hooksPointer)} instead of ./hooks/hooks.json at ${expectedHooksPath}; run "omx setup --plugin" to refresh the plugin cache`,
         };
     }
     for (const expectedPath of [expectedHooksPath, expectedHookLauncherPath, expectedPinnedLauncherPath]) {
@@ -1286,7 +1477,7 @@ async function checkPluginScopedNativeHooks(codexHomeDir, setupHooksPath) {
             return {
                 name: "Native hooks",
                 status: "warn",
-                message: `plugin-scoped hooks are enabled, but expected plugin hook file is missing at ${expectedPath}; ${setupHooksPathDescription}; run "omx setup --plugin --force" to refresh the plugin cache`,
+                message: `plugin-scoped hooks are enabled, but expected plugin hook file is missing at ${expectedPath}; ${setupHooksPathDescription}; run "omx setup --plugin" to refresh the plugin cache`,
             };
         }
     }
@@ -1294,7 +1485,7 @@ async function checkPluginScopedNativeHooks(codexHomeDir, setupHooksPath) {
         return {
             name: "Native hooks",
             status: "warn",
-            message: `plugin-scoped hooks are enabled, but cached plugin hook files or pinned hook launcher in ${expectedCacheDir} do not match the packaged plugin; ${setupHooksPathDescription}; run "omx setup --plugin --force" to refresh the plugin cache`,
+            message: `plugin-scoped hooks are enabled, but cached plugin hook files or pinned hook launcher in ${expectedCacheDir} do not match the packaged plugin; ${setupHooksPathDescription}; run "omx setup --plugin" to refresh the plugin cache`,
         };
     }
     let hookContent;
@@ -1320,7 +1511,7 @@ async function checkPluginScopedNativeHooks(codexHomeDir, setupHooksPath) {
         return {
             name: "Native hooks",
             status: "warn",
-            message: `plugin-scoped hooks.json at ${expectedHooksPath} is missing OMX native coverage for one or more events; run "omx setup --plugin --force" to refresh the plugin cache`,
+            message: `plugin-scoped hooks.json at ${expectedHooksPath} is missing OMX native coverage for one or more events; run "omx setup --plugin" to refresh the plugin cache`,
         };
     }
     const smokeCwd = await mkdtemp(join(tmpdir(), "omx-doctor-plugin-hook-"));
@@ -1373,12 +1564,145 @@ async function checkPluginScopedNativeHooks(codexHomeDir, setupHooksPath) {
         message: `plugin-scoped hooks are enabled; ${setupHooksPathDescription}, and plugin cache native hook coverage smoke passed via ${expectedHooksPath}`,
     };
 }
-async function checkNativeHooks(hooksPath, configPath, context) {
+function decodeStrictUtf8(bytes) {
+    try {
+        const content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        return Buffer.from(content, "utf-8").equals(bytes) ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+function combinePluginAndGlobalNativeHookChecks(plugin, global) {
+    if (!global)
+        return plugin;
+    const status = plugin.status === "fail" || global.status === "fail"
+        ? "fail"
+        : plugin.status === "warn" || global.status === "warn"
+            ? "warn"
+            : "pass";
+    return {
+        name: "Native hooks",
+        status,
+        message: `${plugin.message}; existing global hooks.json: ${global.message}`,
+    };
+}
+function combineNativeHookIntegrityAndRemovalChecks(integrityCheck, removalCheck) {
+    if (!integrityCheck)
+        return removalCheck;
+    return {
+        name: "Native hooks",
+        status: integrityCheck.status === "fail" || removalCheck.status === "fail"
+            ? "fail"
+            : "warn",
+        message: `${integrityCheck.message}; ${removalCheck.message}`,
+    };
+}
+async function checkExistingNativeHooks(hooksPath, context) {
+    const platform = context.platform ?? process.platform;
+    try {
+        const hooksStat = await lstat(hooksPath);
+        if (hooksStat.isSymbolicLink() || !hooksStat.isFile()) {
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: `hooks.json at ${hooksPath} is not a regular file; doctor will not follow or modify it`,
+            };
+        }
+        const content = decodeStrictUtf8(await readFile(hooksPath));
+        if (content === null) {
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: `hooks.json at ${hooksPath} is not valid UTF-8; inspect the file manually because doctor will not modify it`,
+            };
+        }
+        const validation = validateCodexHooksConfigStrict(content, {
+            platform,
+            codexHomeDir: context.codexHomeDir,
+        });
+        if (!validation.ok) {
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: `hooks.json failed strict load validation (${validation.error.code}): ${trimNativeHookDetailTerminalPeriod(validation.error.message)}; inspect the file manually because doctor will not modify it`,
+            };
+        }
+        const removalPlan = planManagedCodexHooksRemoval(content, hooksPath, {
+            platform,
+            codexHomeDir: context.codexHomeDir,
+        });
+        const windowsShimCheck = platform === "win32"
+            ? await checkWindowsNativeHookShims(validation.root, validation.diagnostics, context.codexHomeDir)
+            : null;
+        if (!removalPlan.ok) {
+            const removalIsCoordinateOnly = removalPlan.error.code === "unsafe_managed_removal";
+            const removalCheck = {
+                name: "Native hooks",
+                status: removalIsCoordinateOnly ? "warn" : "fail",
+                message: removalIsCoordinateOnly
+                    ? `hooks.json has OMX entries that cannot be safely removed (${removalPlan.error.code}): ${trimNativeHookDetailTerminalPeriod(removalPlan.error.message)}; manual cleanup is required because doctor will not overwrite or remove it`
+                    : `hooks.json has ambiguous or untrusted OMX ownership (${removalPlan.error.code}): ${trimNativeHookDetailTerminalPeriod(removalPlan.error.message)}; inspect the file manually because doctor will not overwrite or remove it`,
+            };
+            return combineNativeHookIntegrityAndRemovalChecks(windowsShimCheck, removalCheck);
+        }
+        if (windowsShimCheck)
+            return windowsShimCheck;
+        const legacyTrustStateEntries = Object.keys(removalPlan.legacyTrustState).length;
+        if (legacyTrustStateEntries > 0) {
+            return {
+                name: "Native hooks",
+                status: "warn",
+                message: `hooks.json contains ${legacyTrustStateEntries} exact historical OMX hook trust-state ${legacyTrustStateEntries === 1 ? "entry that requires" : "entries that require"} migration; run "omx setup" to migrate ${legacyTrustStateEntries === 1 ? "it" : "them"} after reviewing the configuration`,
+            };
+        }
+        if (validation.diagnostics.length > 0) {
+            return {
+                name: "Native hooks",
+                status: "warn",
+                message: `hooks.json discovery warnings: ${formatNativeHookDiagnostics(validation.diagnostics)}; Codex may ignore the listed entries, and doctor will not modify them`,
+            };
+        }
+        const missingEvents = getMissingManagedHookEventsFromPlan(removalPlan);
+        if (removalPlan.hasForeignHooks &&
+            removalPlan.removedCount === 0 &&
+            missingEvents.length === MANAGED_HOOK_EVENTS.length) {
+            return {
+                name: "Native hooks",
+                status: "pass",
+                message: "hooks.json contains valid foreign hook entries and no OMX-managed wrappers; doctor will preserve the user-owned configuration",
+            };
+        }
+        if (missingEvents.length > 0) {
+            return {
+                name: "Native hooks",
+                status: "warn",
+                message: `hooks.json is missing OMX-managed coverage for ${missingEvents.join(", ")}; run "omx setup" to restore native hooks${removalPlan.hasForeignHooks ? "; valid foreign hooks will be preserved" : ""}`,
+            };
+        }
+        return {
+            name: "Native hooks",
+            status: "pass",
+            message: `hooks.json includes OMX-managed coverage for all native hook events${removalPlan.hasForeignHooks ? "; valid foreign hooks will be preserved" : ""}`,
+        };
+    }
+    catch {
+        return {
+            name: "Native hooks",
+            status: "fail",
+            message: "cannot read hooks.json",
+        };
+    }
+}
+export async function checkNativeHooks(hooksPath, configPath, context) {
     if (existsSync(configPath) && context.installMode === "plugin") {
         try {
             const configContent = await readFile(configPath, "utf-8");
             if (configEnablesPluginScopedHooks(configContent)) {
-                return checkPluginScopedNativeHooks(context.codexHomeDir, hooksPath);
+                const globalCheck = existsSync(hooksPath)
+                    ? await checkExistingNativeHooks(hooksPath, context)
+                    : null;
+                return combinePluginAndGlobalNativeHookChecks(await checkPluginScopedNativeHooks(context.codexHomeDir, hooksPath), globalCheck);
             }
         }
         catch {
@@ -1390,25 +1714,23 @@ async function checkNativeHooks(hooksPath, configPath, context) {
         if (existsSync(configPath)) {
             try {
                 const configContent = await readFile(configPath, "utf-8");
-                if (context.installMode === "plugin") {
-                    if (configHasOmxEntries(configContent)) {
-                        return {
-                            name: "Native hooks",
-                            status: "warn",
-                            message: `plugin mode is using legacy native hook fallback, but expected setup-owned hooks.json is missing at ${hooksPath}; run "omx setup --plugin --force" to restore the fallback hook file, or upgrade Codex to plugin_hooks support so setup can use plugin-scoped hooks`,
-                        };
-                    }
+                if (context.installMode === "plugin" && configHasOmxEntries(configContent)) {
+                    return {
+                        name: "Native hooks",
+                        status: "warn",
+                        message: `plugin mode is using legacy native hook fallback, but expected setup-owned hooks.json is missing at ${hooksPath}; run "omx setup --plugin" to restore the fallback hook file, or upgrade Codex to plugin_hooks support so setup can use plugin-scoped hooks`,
+                    };
                 }
                 if (configHasOmxEntries(configContent)) {
                     return {
                         name: "Native hooks",
                         status: "warn",
-                        message: `expected setup-owned hooks.json is missing at ${hooksPath} even though config.toml has OMX entries; run "omx setup --force" to restore native hook coverage`,
+                        message: `expected setup-owned hooks.json is missing at ${hooksPath} even though config.toml has OMX entries; run "omx setup" to restore native hook coverage`,
                     };
                 }
             }
             catch {
-                // fall through to the neutral first-setup path when config cannot be read here;
+                // Fall through to the neutral first-setup path when config cannot be read here;
                 // the dedicated config check will report read failures separately.
             }
         }
@@ -1418,66 +1740,18 @@ async function checkNativeHooks(hooksPath, configPath, context) {
             message: "hooks.json not found yet (expected before first setup)",
         };
     }
-    try {
-        const content = await readFile(hooksPath, "utf-8");
-        const missingEvents = getMissingManagedCodexHookEvents(content);
-        if (missingEvents === null) {
-            return {
-                name: "Native hooks",
-                status: "fail",
-                message: 'invalid hooks.json; Codex may skip OMX hook coverage until "omx setup --force" repairs it',
-            };
-        }
-        const hasTopLevelState = hasCodexHooksJsonTopLevelState(content);
-        if (hasTopLevelState === true) {
-            return {
-                name: "Native hooks",
-                status: "fail",
-                message: 'top-level state in hooks.json is incompatible with Codex 0.140 (unknown field state, expected hooks); run "omx setup --force" to migrate trust state to config.toml and repair hooks.json',
-            };
-        }
-        if (missingEvents.length > 0) {
-            return {
-                name: "Native hooks",
-                status: "warn",
-                message: `hooks.json is missing OMX-managed coverage for ${missingEvents.join(", ")}; run "omx setup --force" to restore native hooks`,
-            };
-        }
-        return {
-            name: "Native hooks",
-            status: "pass",
-            message: "hooks.json includes OMX-managed coverage for all native hook events",
-        };
-    }
-    catch {
-        return {
-            name: "Native hooks",
-            status: "fail",
-            message: "cannot read hooks.json",
-        };
-    }
+    return checkExistingNativeHooks(hooksPath, context);
 }
 export async function checkNativeHookDistSmoke(options = {}) {
     const packageRoot = options.packageRoot ?? getPackageRoot();
     const nodePath = options.nodePath ?? process.execPath;
     const runner = options.runner ?? spawnSync;
     const scriptPath = join(packageRoot, "dist", "scripts", "codex-native-hook.js");
-    const packageJsonPath = join(packageRoot, "package.json");
-    let packageVersion = "current";
-    try {
-        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-        if (typeof packageJson.version === "string" && packageJson.version.trim()) {
-            packageVersion = packageJson.version.trim();
-        }
-    }
-    catch {
-        // Keep the generic recovery copy when package metadata is not readable.
-    }
     if (!existsSync(scriptPath)) {
         return {
             name: "Native hook dist smoke",
             status: "fail",
-            message: `installed native hook script is missing at ${scriptPath}; reinstall oh-my-codex and run "omx setup --force"`,
+            message: `installed native hook script is missing at ${scriptPath}; reinstall oh-my-codex and run "omx setup"`,
         };
     }
     const smokeCwd = await mkdtemp(join(tmpdir(), "omx-doctor-native-hook-dist-"));
@@ -1507,7 +1781,7 @@ export async function checkNativeHookDistSmoke(options = {}) {
             return {
                 name: "Native hook dist smoke",
                 status: "fail",
-                message: `installed native hook dist smoke failed to run (${result.error.message}); reinstall oh-my-codex and run "omx setup --force"`,
+                message: `installed native hook dist smoke failed to run (${result.error.message}); reinstall oh-my-codex and run "omx setup"`,
             };
         }
         if (result.status !== 0) {
@@ -1517,7 +1791,7 @@ export async function checkNativeHookDistSmoke(options = {}) {
             return {
                 name: "Native hook dist smoke",
                 status: "fail",
-                message: `installed native hook dist failed a minimal UserPromptSubmit smoke (${detail}); reinstall with "npm install -g oh-my-codex@${packageVersion} --force --min-release-age=0 --before=" and then run "omx setup --force"`,
+                message: `installed native hook dist failed a minimal UserPromptSubmit smoke (${detail}); reinstall the matching oh-my-codex version and then run "omx setup"`,
             };
         }
         return {
@@ -1539,14 +1813,14 @@ export function classifyPostCompactHookStdout(stdout) {
         return {
             name: "Native PostCompact hook",
             status: "fail",
-            message: "PostCompact hook emitted JSON stdout, but OMX PostCompact must emit no stdout until Codex defines a supported PostCompact output contract; run \"omx setup --force\" after upgrading",
+            message: "PostCompact hook emitted JSON stdout, but OMX PostCompact must emit no stdout until Codex defines a supported PostCompact output contract; rerun \"omx setup\" after upgrading",
         };
     }
     catch (error) {
         return {
             name: "Native PostCompact hook",
             status: "fail",
-            message: `PostCompact hook emitted invalid JSON stdout (${error instanceof Error ? error.message : String(error)}); run "omx setup --force" after upgrading`,
+            message: `PostCompact hook emitted invalid JSON stdout (${error instanceof Error ? error.message : String(error)}); rerun "omx setup" after upgrading`,
         };
     }
 }
@@ -1571,77 +1845,278 @@ export function buildPostCompactSmokeSpawnInvocation(expectedCommand, options =
         shell: true,
     };
 }
-async function checkNativePostCompactHookRuntime(hooksPath, cwd, codexHomeDir) {
-    if (!existsSync(hooksPath))
+function buildInMemoryWindowsShimSmokeInvocation(expectedShimContent, options = {}) {
+    const shimSource = decodeStrictUtf8(expectedShimContent);
+    if (shimSource === null)
         return null;
-    let content;
+    const encodedShimBytes = expectedShimContent.toString("base64");
+    const command = [
+        "$ErrorActionPreference = 'Stop'",
+        `$omxShimSource = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('${encodedShimBytes}'))`,
+        "if ($omxShimSource.Length -gt 0 -and [int][char]$omxShimSource[0] -eq 0xFEFF) { $omxShimSource = $omxShimSource.Substring(1) }",
+        "& ([ScriptBlock]::Create($omxShimSource))",
+        "exit $LASTEXITCODE",
+    ].join("; ");
+    return {
+        command: resolveWindowsPowerShellPath(options.env),
+        args: [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-EncodedCommand",
+            Buffer.from(command, "utf16le").toString("base64"),
+        ],
+        shell: false,
+    };
+}
+function smokeDirectoryIdentity(stat) {
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
+        return null;
+    return { dev: stat.dev, ino: stat.ino };
+}
+async function readSmokeDirectoryIdentity(smokeCwd) {
     try {
-        content = await readFile(hooksPath, "utf-8");
+        return smokeDirectoryIdentity(await lstat(smokeCwd));
     }
     catch {
         return null;
     }
-    const postCompactCommands = getManagedCodexHookCommandsForEvent(content, "PostCompact");
-    if (postCompactCommands === null || postCompactCommands.length === 0) {
+}
+function sameSmokeDirectoryIdentity(expected, actual) {
+    return actual !== null && actual.dev === expected.dev && actual.ino === expected.ino;
+}
+function smokeDirectorySafetyCheck(message) {
+    return {
+        name: "Native PostCompact hook",
+        status: "warn",
+        message,
+    };
+}
+async function cleanupSmokeDirectoryIfUnchanged(smokeCwd, identity) {
+    if (!sameSmokeDirectoryIdentity(identity, await readSmokeDirectoryIdentity(smokeCwd))) {
+        return smokeDirectorySafetyCheck("temporary PostCompact smoke directory changed during validation; doctor preserved it for manual recovery and skipped cleanup for safety");
+    }
+    try {
+        // Only remove the empty, identity-checked directory. Never recursively remove
+        // a directory that another process could have replaced or populated.
+        await rmdir(smokeCwd);
         return null;
     }
-    const expectedCommand = buildManagedCodexNativeHookCommand(getPackageRoot(), {
+    catch {
+        return smokeDirectorySafetyCheck("temporary PostCompact smoke directory could not be removed without recursive deletion; doctor preserved it for manual recovery");
+    }
+}
+function inMemoryWindowsShimSmokeCheck() {
+    return {
+        name: "Native PostCompact hook",
+        status: "warn",
+        message: "doctor could not build an in-memory Windows native hook smoke command from exact validated shim bytes; doctor skipped execution for safety",
+    };
+}
+function getManagedPostCompactHookCommands(content, platform, codexHomeDir) {
+    const validation = validateCodexHooksConfigStrict(content, {
+        platform,
+        codexHomeDir,
+    });
+    if (!validation.ok)
+        return null;
+    return validation.discoveredCommands
+        .filter((command) => command.eventName === "PostCompact")
+        .map((command) => command.command)
+        .filter((command) => isManagedCodexHookCommand(command) ||
+        (platform === "win32" && parseManagedCodexNativeHookWindowsShimCommand(command, {
+            platform,
+            codexHomeDir,
+        }) !== null));
+}
+function currentPostCompactCommandCheck() {
+    return {
+        name: "Native PostCompact hook",
+        status: "warn",
+        message: "effective PostCompact OMX command does not match this installation's managed hook command; doctor skipped execution for safety, and rerunning \"omx setup\" should refresh stale hooks.json entries",
+    };
+}
+function skippedPostCompactIntegrityCheck(integrityCheck) {
+    return {
+        name: "Native PostCompact hook",
+        status: integrityCheck.status === "fail" ? "fail" : "warn",
+        message: `${integrityCheck.message}; doctor skipped execution because native hook integrity validation did not pass`,
+    };
+}
+export async function checkNativePostCompactHookRuntime(hooksPath, cwd, codexHomeDir, options = {}) {
+    if (!existsSync(hooksPath))
+        return null;
+    if (options.nativeHooksCheck && options.nativeHooksCheck.status !== "pass")
+        return null;
+    const platform = options.platform ?? process.platform;
+    const expectedCommand = options.expectedCommand ?? buildManagedCodexNativeHookCommand(getPackageRoot(), {
         codexHomeDir,
+        platform,
     });
+    let content;
+    try {
+        content = decodeStrictUtf8(await readFile(hooksPath));
+    }
+    catch {
+        return null;
+    }
+    if (content === null)
+        return null;
+    const postCompactCommands = getManagedPostCompactHookCommands(content, platform, codexHomeDir);
+    if (postCompactCommands === null || postCompactCommands.length === 0)
+        return null;
     const uniqueCommands = [...new Set(postCompactCommands)];
     if (uniqueCommands.length !== 1 || uniqueCommands[0] !== expectedCommand) {
-        return {
-            name: "Native PostCompact hook",
-            status: "warn",
-            message: "effective PostCompact OMX command does not match this installation's managed hook command; doctor skipped execution for safety, and \"omx setup --force\" should refresh stale hooks.json entries",
-        };
+        return currentPostCompactCommandCheck();
     }
     const smokeCwd = await mkdtemp(join(tmpdir(), "omx-doctor-postcompact-"));
+    const smokeDirectory = await readSmokeDirectoryIdentity(smokeCwd);
+    if (!smokeDirectory) {
+        return smokeDirectorySafetyCheck("temporary PostCompact smoke directory could not be validated; doctor preserved it for manual recovery and skipped execution for safety");
+    }
+    let primaryResult = null;
+    let primaryError = null;
     try {
-        const payload = JSON.stringify({
-            hook_event_name: "PostCompact",
-            cwd: smokeCwd,
-            session_id: "omx-doctor-postcompact-smoke",
-        });
-        const smokeInvocation = buildPostCompactSmokeSpawnInvocation(expectedCommand);
-        const result = spawnSync(smokeInvocation.command, smokeInvocation.args, {
-            cwd,
-            encoding: "utf-8",
-            env: {
-                ...process.env,
-                OMX_NATIVE_HOOK_DOCTOR_SMOKE: "1",
-            },
-            input: payload,
-            shell: smokeInvocation.shell,
-            timeout: 5_000,
-        });
-        if (result.error) {
-            return {
-                name: "Native PostCompact hook",
-                status: "fail",
-                message: `PostCompact hook smoke validation failed to run (${result.error.message})`,
-            };
-        }
-        if (result.status !== 0) {
-            const stderr = (result.stderr || "").trim();
+        primaryResult = await (async () => {
+            const revalidatedIntegrity = await checkExistingNativeHooks(hooksPath, {
+                codexHomeDir,
+                platform,
+            });
+            if (revalidatedIntegrity.status !== "pass") {
+                return skippedPostCompactIntegrityCheck(revalidatedIntegrity);
+            }
+            let revalidatedContent;
+            try {
+                revalidatedContent = decodeStrictUtf8(await readFile(hooksPath));
+            }
+            catch {
+                return {
+                    name: "Native PostCompact hook",
+                    status: "warn",
+                    message: "hooks.json changed during verbose validation; doctor skipped execution for safety",
+                };
+            }
+            if (revalidatedContent === null) {
+                return {
+                    name: "Native PostCompact hook",
+                    status: "warn",
+                    message: "hooks.json changed during verbose validation; doctor skipped execution for safety",
+                };
+            }
+            const revalidatedCommands = getManagedPostCompactHookCommands(revalidatedContent, platform, codexHomeDir);
+            if (revalidatedCommands === null ||
+                revalidatedCommands.length === 0 ||
+                new Set(revalidatedCommands).size !== 1 ||
+                revalidatedCommands[0] !== expectedCommand) {
+                return currentPostCompactCommandCheck();
+            }
+            if (platform === "win32") {
+                const validation = validateCodexHooksConfigStrict(revalidatedContent, {
+                    platform,
+                    codexHomeDir,
+                });
+                if (!validation.ok) {
+                    return {
+                        name: "Native PostCompact hook",
+                        status: "warn",
+                        message: "hooks.json changed during verbose validation; doctor skipped execution for safety",
+                    };
+                }
+                const currentShimCheck = await checkWindowsNativeHookShims(validation.root, validation.diagnostics, codexHomeDir, true);
+                if (currentShimCheck)
+                    return skippedPostCompactIntegrityCheck(currentShimCheck);
+            }
+            let smokeInvocation;
+            if (platform === "win32") {
+                const canonicalShimPath = parseManagedCodexNativeHookWindowsShimCommand(expectedCommand, {
+                    platform,
+                    codexHomeDir,
+                });
+                if (!canonicalShimPath)
+                    return currentPostCompactCommandCheck();
+                const expectedShimContent = Buffer.from(buildManagedCodexNativeHookWindowsShimContent(getPackageRoot()), "utf-8");
+                const inMemoryInvocation = buildInMemoryWindowsShimSmokeInvocation(expectedShimContent);
+                if (!inMemoryInvocation)
+                    return inMemoryWindowsShimSmokeCheck();
+                smokeInvocation = inMemoryInvocation;
+                try {
+                    await options.beforeWindowsShimSmoke?.({ canonicalShimPath, smokeCwd });
+                }
+                catch {
+                    return smokeDirectorySafetyCheck("Windows native hook changed during validation; doctor skipped execution for safety");
+                }
+            }
+            else {
+                smokeInvocation = buildPostCompactSmokeSpawnInvocation(expectedCommand, { platform });
+            }
+            if (!sameSmokeDirectoryIdentity(smokeDirectory, await readSmokeDirectoryIdentity(smokeCwd))) {
+                return smokeDirectorySafetyCheck("temporary PostCompact smoke directory changed during validation; doctor preserved it for manual recovery and skipped execution for safety");
+            }
+            const payload = JSON.stringify({
+                hook_event_name: "PostCompact",
+                cwd: smokeCwd,
+                session_id: "omx-doctor-postcompact-smoke",
+            });
+            const result = (options.runner ?? spawnSync)(smokeInvocation.command, smokeInvocation.args, {
+                cwd,
+                encoding: "utf-8",
+                env: {
+                    ...process.env,
+                    OMX_NATIVE_HOOK_DOCTOR_SMOKE: "1",
+                    OMX_ROOT: smokeCwd,
+                    OMX_SESSION_ID: "omx-doctor-postcompact-smoke",
+                    OMX_SOURCE_CWD: smokeCwd,
+                    OMX_STARTUP_CWD: smokeCwd,
+                },
+                input: payload,
+                shell: smokeInvocation.shell,
+                timeout: 5_000,
+            });
+            if (result.error) {
+                return {
+                    name: "Native PostCompact hook",
+                    status: "fail",
+                    message: `PostCompact hook smoke validation failed to run (${result.error.message})`,
+                };
+            }
+            if (result.status !== 0) {
+                const stderr = (result.stderr || "").trim();
+                return {
+                    name: "Native PostCompact hook",
+                    status: "fail",
+                    message: `PostCompact hook smoke validation exited ${result.status}${stderr ? `: ${stderr}` : ""}`,
+                };
+            }
+            const stdoutCheck = classifyPostCompactHookStdout(result.stdout || "");
+            if (stdoutCheck)
+                return stdoutCheck;
             return {
                 name: "Native PostCompact hook",
-                status: "fail",
-                message: `PostCompact hook smoke validation exited ${result.status}${stderr ? `: ${stderr}` : ""}`,
+                status: "pass",
+                message: "verbose smoke validation confirmed the effective PostCompact hook exits successfully with no stdout",
             };
-        }
-        const stdoutCheck = classifyPostCompactHookStdout(result.stdout || "");
-        if (stdoutCheck)
-            return stdoutCheck;
-        return {
-            name: "Native PostCompact hook",
-            status: "pass",
-            message: "verbose smoke validation confirmed the effective PostCompact hook exits successfully with no stdout",
-        };
+        })();
+    }
+    catch (error) {
+        primaryError = error instanceof Error ? error : new Error(String(error));
+        throw primaryError;
     }
     finally {
-        await rm(smokeCwd, { recursive: true, force: true });
+        const cleanupCheck = await cleanupSmokeDirectoryIfUnchanged(smokeCwd, smokeDirectory);
+        if (cleanupCheck) {
+            if (primaryResult) {
+                if (primaryResult.status === "pass")
+                    primaryResult.status = cleanupCheck.status;
+                primaryResult.message = `${primaryResult.message}; ${cleanupCheck.message}`;
+            }
+            else if (primaryError) {
+                primaryError.message = `${primaryError.message}; ${cleanupCheck.message}`;
+            }
+        }
     }
+    return primaryResult;
 }
 async function checkNativeHookRuntimeMirrors(cwd, hooksPath) {
     if (!existsSync(hooksPath))