oh-my-codex 0.18.13 → 0.18.15

package/dist/cli/doctor.js

@@ -1,10 +1,10 @@
 /**
  * omx doctor - Validate oh-my-codex installation
  */
-import { existsSync, readFileSync } from "fs";
-import { mkdtemp, readdir, readFile, rm } from "fs/promises";
+import { constants, existsSync, readFileSync } from "fs";
+import { access, chown, lstat, mkdtemp, readdir, readFile, rm } from "fs/promises";
 import { spawnSync } from "child_process";
-import { basename, join } from "path";
+import { basename, 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";
@@ -13,7 +13,7 @@ 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, getManagedCodexHookCommandsForEvent, getMissingManagedCodexHookEvents, hasCodexHooksJsonTopLevelState, } from "../config/codex-hooks.js";
+import { MANAGED_HOOK_EVENTS, buildManagedCodexNativeHookCommand, discoverCodexHookConfigPaths, resolveWindowsPowerShellPath, getManagedCodexHookCommandsForEvent, getMissingManagedCodexHookEvents, hasCodexHooksJsonTopLevelState, } 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";
@@ -24,10 +24,11 @@ import { readTriageConfig } from "../hooks/triage-config.js";
 import { readPersistedSetupPreferences, } from "./setup-preferences.js";
 import { OMX_LOCAL_MARKETPLACE_NAME, OMX_LOCAL_PLUGIN_CONFIG_KEY, discoverOmxPluginCacheDirs, expectedPackagedOmxSkillNames, packagedOmxPluginVersion, pluginHookCacheMatchesPackaged, readOmxPluginCacheState, resolvePackagedOmxMarketplace, } from "./plugin-marketplace.js";
 import { hasOmxAgentsContract } from "../utils/agents-md.js";
-import { OMX_DEFAULT_SPARK_MODEL_ENV, OMX_SPARK_MODEL_ENV, getCodexConfigRootModelProvider, getEnvConfiguredSparkDefaultModel, getMainDefaultModel, getSparkDefaultModel, getStandardDefaultModel, } from "../config/models.js";
+import { OMX_DEFAULT_SPARK_MODEL_ENV, OMX_SPARK_MODEL_ENV, getAgentModelOverride, getCodexConfigRootModelProvider, getEnvConfiguredSparkDefaultModel, getMainDefaultModel, getSparkDefaultModel, getStandardDefaultModel, } from "../config/models.js";
 import { AGENT_DEFINITIONS } from "../agents/definitions.js";
 import { getInstallableNativeAgentNames } from "../agents/policy.js";
 import { readCatalogManifest } from "../catalog/reader.js";
+const REPO_ARTIFACT_DIRS = [".omx", ".beads"];
 async function resolveDoctorScope(cwd) {
     const persisted = await readPersistedSetupPreferences(cwd);
     if (persisted?.scope) {
@@ -128,6 +129,24 @@ export async function doctor(options = {}) {
         : scopeResolution.source === "config"
             ? " (inferred from Codex plugin config)"
             : "";
+    if (options.force) {
+        if (options.dryRun) {
+            const check = await checkRepoArtifactOwnership(cwd);
+            if (check.status !== "pass") {
+                console.log(`Dry run: ${check.message}`);
+                console.log();
+            }
+        }
+        else {
+            const repair = await repairRepoArtifactOwnership(cwd);
+            if (repair.repaired > 0 || repair.skipped.length > 0) {
+                console.log(`Repo artifact ownership repair: ${repair.repaired} path(s) repaired${repair.skipped.length > 0
+                    ? `, ${repair.skipped.length} skipped (${repair.skipped.join("; ")})`
+                    : ""}`);
+                console.log();
+            }
+        }
+    }
     console.log("oh-my-codex doctor");
     console.log("==================\n");
     console.log(`Resolved setup scope: ${scopeResolution.scope}${scopeSourceMessage}`);
@@ -144,7 +163,10 @@ export async function doctor(options = {}) {
     // Check 2: Node.js version
     checks.push(checkNodeVersion());
     // Check 2.5: Explore harness readiness
-    checks.push(checkExploreHarness());
+    const exploreRoutingState = await resolveExploreRoutingState(paths.configPath);
+    checks.push(checkExploreHarness(process.platform, process.env, {
+        exploreRoutingEnabled: exploreRoutingState.enabled,
+    }));
     // Check 3: Codex home directory
     checks.push(checkDirectory("Codex home", paths.codexHomeDir));
     // Check 4: Config file
@@ -168,13 +190,20 @@ export async function doctor(options = {}) {
     if (runtimeMirrorCheck)
         checks.push(runtimeMirrorCheck);
     // Check 4.5: Explore routing default
-    checks.push(await checkExploreRouting(paths.configPath));
+    checks.push(checkExploreRoutingFromState(exploreRoutingState));
     // Check 4.6: Lore commit guard default
     checks.push(await checkLoreCommitGuard(paths.configPath));
+    // Check 4.7: External process guards
+    const externalProcessGuardCheck = await checkExternalCodexProcessGuards();
+    if (externalProcessGuardCheck)
+        checks.push(externalProcessGuardCheck);
     // Check 5: Prompts installed
     checks.push(await checkPrompts(paths.promptsDir, scopeResolution.installMode));
     // Check 6: Skills installed
     checks.push(await checkSkills(paths, scopeResolution.installMode));
+    if (scopeResolution.installMode === "plugin") {
+        checks.push(await checkPluginVersionDiagnostics(paths.codexHomeDir));
+    }
     // Check 6.25: Native reviewer roles required by RALPLAN/Autopilot
     const nativeReviewerRolesCheck = checkNativeReviewerRoles(paths, scopeResolution.installMode);
     if (nativeReviewerRolesCheck)
@@ -189,6 +218,7 @@ export async function doctor(options = {}) {
     checks.push(checkAgentsMd(scopeResolution.scope, paths.codexHomeDir, scopeResolution.installMode));
     // Check 8: State directory
     checks.push(checkDirectory("State dir", paths.stateDir));
+    checks.push(await checkRepoArtifactOwnership(cwd));
     // Check 9: MCP servers configured
     checks.push(await checkMcpServers(paths.configPath, scopeResolution.installMode, scopeResolution.mcpMode));
     // Check 10: Prompt triage
@@ -559,7 +589,16 @@ function checkNodeVersion() {
         message: `v${process.versions.node} (need >= 20)`,
     };
 }
-export function checkExploreHarness(platform = process.platform, env = process.env) {
+export function checkExploreHarness(platform = process.platform, env = process.env, options = {}) {
+    const override = env[EXPLORE_BIN_ENV]?.trim();
+    const exploreRoutingEnabled = options.exploreRoutingEnabled ?? isExploreCommandRoutingEnabled(env);
+    if (!override && !exploreRoutingEnabled) {
+        return {
+            name: "Explore Harness",
+            status: "pass",
+            message: "skipped: omx explore is hard-deprecated and explore routing is disabled by default; use omx sparkshell for shell-native read-only evidence",
+        };
+    }
     const packageRoot = getPackageRoot();
     const manifestPath = join(packageRoot, "crates", "omx-explore", "Cargo.toml");
     if (!existsSync(manifestPath)) {
@@ -569,7 +608,6 @@ export function checkExploreHarness(platform = process.platform, env = process.e
             message: "Rust harness sources not found in this install (omx explore unavailable until packaged or OMX_EXPLORE_BIN is set)",
         };
     }
-    const override = env[EXPLORE_BIN_ENV]?.trim();
     if (override) {
         const resolved = join(packageRoot, override);
         if (existsSync(override) || existsSync(resolved)) {
@@ -640,6 +678,166 @@ function checkDirectory(name, path) {
     }
     return { name, status: "warn", message: `${path} (not created yet)` };
 }
+function currentProcessUid() {
+    return typeof process.getuid === "function" ? process.getuid() : undefined;
+}
+function currentProcessGid() {
+    return typeof process.getgid === "function" ? process.getgid() : undefined;
+}
+function remediationCommand(repoRoot) {
+    return `sudo chown -R $(id -u):$(id -g) ${JSON.stringify(repoRoot)}`;
+}
+function formatArtifactPath(repoRoot, path) {
+    const rel = relative(repoRoot, path);
+    return rel === "" ? "." : rel;
+}
+function formatArtifactIssue(repoRoot, issue) {
+    const owner = typeof issue.uid === "number" && typeof issue.gid === "number"
+        ? ` uid=${issue.uid} gid=${issue.gid}`
+        : "";
+    return `${formatArtifactPath(repoRoot, issue.path)} (${issue.reason}${owner})`;
+}
+function shouldReportOwnerMismatch(uid, currentUid) {
+    if (typeof uid !== "number")
+        return false;
+    if (uid === 0)
+        return true;
+    return typeof currentUid === "number" && uid !== currentUid;
+}
+function isOwnershipIssue(issue) {
+    return issue.type === "ownership";
+}
+async function collectRepoArtifactOwnershipIssues(repoRoot, options = {}) {
+    if (process.platform === "win32")
+        return [];
+    const currentUid = options.currentUid ?? currentProcessUid();
+    const maxExamples = options.maxExamples ?? 20;
+    const statPath = options.statPath ?? lstat;
+    const readDir = options.readDir ?? readdir;
+    const accessPath = options.accessPath ?? access;
+    const issues = [];
+    const visited = new Set();
+    async function visit(path) {
+        if (issues.length >= maxExamples)
+            return;
+        let info;
+        try {
+            info = await statPath(path);
+        }
+        catch {
+            return;
+        }
+        if (info.isSymbolicLink())
+            return;
+        const uid = typeof info.uid === "number" ? info.uid : undefined;
+        const gid = typeof info.gid === "number" ? info.gid : undefined;
+        let reason = null;
+        if (uid === 0)
+            reason = "root-owned";
+        else if (shouldReportOwnerMismatch(uid, currentUid))
+            reason = "owner-mismatch";
+        else {
+            try {
+                await accessPath(path, constants.W_OK);
+            }
+            catch {
+                reason = "not-writable";
+            }
+        }
+        if (reason) {
+            issues.push({
+                path,
+                reason,
+                type: reason === "not-writable" ? "writability" : "ownership",
+                uid,
+                gid,
+            });
+        }
+        if (issues.length >= maxExamples || !info.isDirectory())
+            return;
+        if (visited.has(path))
+            return;
+        visited.add(path);
+        let entries;
+        try {
+            entries = await readDir(path);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            await visit(join(path, entry));
+            if (issues.length >= maxExamples)
+                return;
+        }
+    }
+    for (const dir of REPO_ARTIFACT_DIRS) {
+        const root = join(repoRoot, dir);
+        if (existsSync(root))
+            await visit(root);
+    }
+    return issues;
+}
+export async function checkRepoArtifactOwnership(repoRoot, options = {}) {
+    const issues = await collectRepoArtifactOwnershipIssues(repoRoot, options);
+    if (issues.length === 0) {
+        return {
+            name: "Repo artifact ownership",
+            status: "pass",
+            message: "repo-local .omx/.beads artifacts are writable by the current user",
+        };
+    }
+    const examples = issues
+        .slice(0, options.maxExamples ?? 5)
+        .map((issue) => formatArtifactIssue(repoRoot, issue))
+        .join("; ");
+    const repair = remediationCommand(repoRoot);
+    return {
+        name: "Repo artifact ownership",
+        status: "warn",
+        message: `${issues.length} root-owned, owner-mismatched, or non-writable repo artifact(s): ${examples}. Safe remediation: ${repair}. Automatic repair is only run by \"omx doctor --force\" when the repo root is owned by the current user.`,
+    };
+}
+export async function repairRepoArtifactOwnership(repoRoot, options = {}) {
+    if (process.platform === "win32")
+        return { repaired: 0, skipped: [] };
+    const currentUid = options.currentUid ?? currentProcessUid();
+    const currentGid = options.currentGid ?? currentProcessGid();
+    if (typeof currentUid !== "number" || typeof currentGid !== "number") {
+        return { repaired: 0, skipped: ["current uid/gid unavailable"] };
+    }
+    const statPath = options.statPath ?? lstat;
+    const repoInfo = await statPath(repoRoot);
+    if (repoInfo.uid !== currentUid) {
+        return { repaired: 0, skipped: ["repo root is not owned by the current user"] };
+    }
+    const issues = await collectRepoArtifactOwnershipIssues(repoRoot, {
+        ...options,
+        currentUid,
+        currentGid,
+        maxExamples: Number.MAX_SAFE_INTEGER,
+        statPath,
+    });
+    const ownershipIssues = issues.filter(isOwnershipIssue);
+    const writabilityIssues = issues.filter((issue) => !isOwnershipIssue(issue));
+    const chownPath = options.chownPath ?? chown;
+    let repaired = 0;
+    const skipped = [];
+    for (const issue of writabilityIssues) {
+        skipped.push(`${formatArtifactPath(repoRoot, issue.path)}: not writable by current user`);
+    }
+    for (const issue of ownershipIssues) {
+        try {
+            await chownPath(issue.path, currentUid, currentGid);
+            repaired++;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            skipped.push(`${formatArtifactPath(repoRoot, issue.path)}: ${message}`);
+        }
+    }
+    return { repaired, skipped };
+}
 function validateToml(content) {
     try {
         parseToml(content);
@@ -738,10 +936,36 @@ async function checkModelContextRecommendation(configPath) {
         return null;
     }
 }
-async function checkExploreRouting(configPath) {
-    const envValue = process.env[OMX_EXPLORE_CMD_ENV];
+async function resolveExploreRoutingState(configPath, env = process.env) {
+    const envValue = env[OMX_EXPLORE_CMD_ENV];
     if (typeof envValue === "string") {
-        if (isExploreCommandRoutingEnabled(process.env)) {
+        return { source: "env", enabled: isExploreCommandRoutingEnabled(env) };
+    }
+    if (!existsSync(configPath)) {
+        return { source: "default", enabled: false, reason: "missing-config" };
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const parsed = parseToml(content);
+        const configuredValue = parsed?.shell_environment_policy?.set?.USE_OMX_EXPLORE_CMD ??
+            parsed?.env?.USE_OMX_EXPLORE_CMD;
+        if (typeof configuredValue === "string") {
+            return {
+                source: "config",
+                enabled: isExploreCommandRoutingEnabled({
+                    USE_OMX_EXPLORE_CMD: configuredValue,
+                }),
+            };
+        }
+        return { source: "default", enabled: false, reason: "unset" };
+    }
+    catch {
+        return { source: "unreadable", enabled: false };
+    }
+}
+function checkExploreRoutingFromState(state) {
+    if (state.source === "env") {
+        if (state.enabled) {
             return {
                 name: "Explore routing",
                 status: "warn",
@@ -754,47 +978,34 @@ async function checkExploreRouting(configPath) {
             message: "deprecated compatibility routing disabled by environment override (recommended)",
         };
     }
-    if (!existsSync(configPath)) {
-        return {
-            name: "Explore routing",
-            status: "pass",
-            message: "deprecated by default (config.toml not found yet)",
-        };
-    }
-    try {
-        const content = await readFile(configPath, "utf-8");
-        const parsed = parseToml(content);
-        const configuredValue = parsed?.shell_environment_policy?.set?.USE_OMX_EXPLORE_CMD ??
-            parsed?.env?.USE_OMX_EXPLORE_CMD;
-        if (typeof configuredValue === "string") {
-            if (isExploreCommandRoutingEnabled({
-                USE_OMX_EXPLORE_CMD: configuredValue,
-            })) {
-                return {
-                    name: "Explore routing",
-                    status: "warn",
-                    message: 'deprecated compatibility routing enabled in config.toml; set USE_OMX_EXPLORE_CMD = "0" under [shell_environment_policy.set] and use normal Codex repo inspection or omx sparkshell instead',
-                };
-            }
+    if (state.source === "config") {
+        if (state.enabled) {
             return {
                 name: "Explore routing",
-                status: "pass",
-                message: "deprecated compatibility routing disabled in config.toml (recommended)",
+                status: "warn",
+                message: 'deprecated compatibility routing enabled in config.toml; set USE_OMX_EXPLORE_CMD = "0" under [shell_environment_policy.set] and use normal Codex repo inspection or omx sparkshell instead',
             };
         }
         return {
             name: "Explore routing",
             status: "pass",
-            message: "deprecated by default",
+            message: "deprecated compatibility routing disabled in config.toml (recommended)",
         };
     }
-    catch {
+    if (state.source === "unreadable") {
         return {
             name: "Explore routing",
             status: "fail",
             message: "cannot read config.toml for explore routing check",
         };
     }
+    return {
+        name: "Explore routing",
+        status: "pass",
+        message: state.reason === "missing-config"
+            ? "deprecated by default (config.toml not found yet)"
+            : "deprecated by default",
+    };
 }
 const LORE_COMMIT_GUARD_EXPLICIT_OPT_OUT_VALUES = new Set([
     "0",
@@ -877,6 +1088,117 @@ async function checkLoreCommitGuard(configPath) {
 function isExplicitLoreCommitGuardOptOut(value) {
     return LORE_COMMIT_GUARD_EXPLICIT_OPT_OUT_VALUES.has(value.trim().toLowerCase());
 }
+function decodeBasicXmlEntities(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&apos;", "'");
+}
+function extractPlistStrings(content) {
+    return [...content.matchAll(/<string>([^<]+)<\/string>/g)].map((match) => decodeBasicXmlEntities(match[1]?.trim() ?? ""));
+}
+function extractPlistLabel(content, fallback) {
+    const labelMatch = content.match(/<key>Label<\/key>\s*<string>([^<]+)<\/string>/);
+    return decodeBasicXmlEntities(labelMatch?.[1]?.trim() || fallback);
+}
+async function readExistingTextFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+function expandLaunchAgentPath(value, homeDir) {
+    if (value === "~")
+        return homeDir;
+    if (value.startsWith("~/"))
+        return join(homeDir, value.slice(2));
+    if (value === "$HOME")
+        return homeDir;
+    if (value.startsWith("$HOME/"))
+        return join(homeDir, value.slice(6));
+    if (value === "${HOME}")
+        return homeDir;
+    if (value.startsWith("${HOME}/"))
+        return join(homeDir, value.slice(8));
+    return value;
+}
+function classifyExternalCodexProcessGuard(plistContent, combinedContent) {
+    const lowerPlist = plistContent.toLowerCase();
+    const lower = combinedContent.toLowerCase();
+    if (lower.includes("codex-mcp-child-guard") ||
+        lower.includes("codex_mcp_child_guard") ||
+        combinedContent.includes("CODEX_MCP_GUARD_DEDUPE_APP_CHILDREN") ||
+        (lower.includes("codex app-server") &&
+            lower.includes("pgrep -p") &&
+            lower.includes("kill"))) {
+        return "Codex app-server MCP child dedupe";
+    }
+    if ((lowerPlist.includes("codex-xcode-mcp-guard") ||
+        lowerPlist.includes("codex_xcode_mcp_guard")) &&
+        lower.includes("xcodebuildmcp") &&
+        lower.includes("kill")) {
+        return "XcodeBuildMCP cleanup";
+    }
+    return null;
+}
+export async function checkExternalCodexProcessGuards(options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin")
+        return null;
+    const homeDir = options.homeDir ?? process.env.HOME;
+    if (!homeDir)
+        return null;
+    const launchAgentsDir = join(homeDir, "Library", "LaunchAgents");
+    if (!existsSync(launchAgentsDir))
+        return null;
+    let entries;
+    try {
+        entries = await readdir(launchAgentsDir);
+    }
+    catch {
+        return null;
+    }
+    const findings = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".plist"))
+            continue;
+        const plistPath = join(launchAgentsDir, entry);
+        const plistContent = await readExistingTextFile(plistPath);
+        if (plistContent.trim() === "")
+            continue;
+        const loweredPlist = plistContent.toLowerCase();
+        if (!loweredPlist.includes("codex") &&
+            !loweredPlist.includes("mcp") &&
+            !loweredPlist.includes("omx")) {
+            continue;
+        }
+        let combinedContent = plistContent;
+        for (const value of extractPlistStrings(plistContent)) {
+            const expandedValue = expandLaunchAgentPath(value, homeDir);
+            if (!expandedValue.startsWith("/"))
+                continue;
+            if (!existsSync(expandedValue))
+                continue;
+            combinedContent += `\n${await readExistingTextFile(expandedValue)}`;
+        }
+        const reason = classifyExternalCodexProcessGuard(plistContent, combinedContent);
+        if (!reason)
+            continue;
+        const label = extractPlistLabel(plistContent, entry);
+        findings.push(`${label} (${reason})`);
+    }
+    if (findings.length === 0)
+        return null;
+    return {
+        name: "External process guards",
+        status: "warn",
+        message: `external LaunchAgent(s) may terminate Codex/MCP helper processes outside OMX setup ownership: ${findings.join(", ")}; unload/remove them before attributing SIGTERM or transport resets to standard OMX MCP configuration`,
+    };
+}
 function isEnabledTomlValue(value) {
     return value === true || (typeof value === "string" && ["1", "true", "yes", "on"].includes(value.trim().toLowerCase()));
 }
@@ -1222,6 +1544,27 @@ export function classifyPostCompactHookStdout(stdout) {
         };
     }
 }
+export function buildPostCompactSmokeSpawnInvocation(expectedCommand, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32") {
+        return {
+            command: resolveWindowsPowerShellPath(options.env),
+            args: [
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-Command",
+                expectedCommand,
+            ],
+            shell: false,
+        };
+    }
+    return {
+        command: expectedCommand,
+        args: [],
+        shell: true,
+    };
+}
 async function checkNativePostCompactHookRuntime(hooksPath, cwd, codexHomeDir) {
     if (!existsSync(hooksPath))
         return null;
@@ -1254,7 +1597,8 @@ async function checkNativePostCompactHookRuntime(hooksPath, cwd, codexHomeDir) {
             cwd: smokeCwd,
             session_id: "omx-doctor-postcompact-smoke",
         });
-        const result = spawnSync(expectedCommand, {
+        const smokeInvocation = buildPostCompactSmokeSpawnInvocation(expectedCommand);
+        const result = spawnSync(smokeInvocation.command, smokeInvocation.args, {
             cwd,
             encoding: "utf-8",
             env: {
@@ -1262,7 +1606,7 @@ async function checkNativePostCompactHookRuntime(hooksPath, cwd, codexHomeDir) {
                 OMX_NATIVE_HOOK_DOCTOR_SMOKE: "1",
             },
             input: payload,
-            shell: true,
+            shell: smokeInvocation.shell,
             timeout: 5_000,
         });
         if (result.error) {
@@ -1490,6 +1834,70 @@ async function checkPluginMarketplaceRegistration(configPath, codexHomeDir) {
         };
     }
 }
+async function readDoctorInstallStamp(codexHomeDir) {
+    try {
+        const parsed = JSON.parse(await readFile(join(codexHomeDir, ".omx", "install-state.json"), "utf-8"));
+        return {
+            ...(typeof parsed.install_channel === "string" ? { install_channel: parsed.install_channel } : {}),
+            ...(typeof parsed.dev_base_version === "string" ? { dev_base_version: parsed.dev_base_version } : {}),
+            ...(typeof parsed.install_revision === "string" ? { install_revision: parsed.install_revision } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function checkPluginVersionDiagnostics(codexHomeDir) {
+    const packagedMarketplace = await resolvePackagedOmxMarketplace(getPackageRoot());
+    if (!packagedMarketplace) {
+        return {
+            name: "Plugin versions",
+            status: "warn",
+            message: `packaged ${OMX_LOCAL_MARKETPLACE_NAME} metadata was not found; reinstall oh-my-codex`,
+        };
+    }
+    const [manifestVersion, stamp] = await Promise.all([
+        packagedOmxPluginVersion(packagedMarketplace),
+        readDoctorInstallStamp(codexHomeDir),
+    ]);
+    if (!manifestVersion) {
+        return {
+            name: "Plugin versions",
+            status: "warn",
+            message: "packaged plugin manifest has no version; reinstall oh-my-codex",
+        };
+    }
+    const cacheDir = join(codexHomeDir, "plugins", "cache", OMX_LOCAL_MARKETPLACE_NAME, "oh-my-codex", manifestVersion);
+    const cacheState = await readOmxPluginCacheState(cacheDir);
+    if (cacheState?.manifestVersion !== manifestVersion) {
+        return {
+            name: "Plugin versions",
+            status: "warn",
+            message: `expected cache directory ${cacheDir} is not materialized with packaged plugin manifest version ${manifestVersion}; run "omx setup --plugin --force" to refresh the plugin cache`,
+        };
+    }
+    if (stamp?.install_channel === "dev") {
+        const devDisplay = stamp.dev_base_version && stamp.install_revision
+            ? `v${stamp.dev_base_version}-dev-${stamp.install_revision}`
+            : null;
+        const stampDetail = [
+            `package/plugin manifest version ${manifestVersion}`,
+            devDisplay ? `dev display version ${devDisplay}` : null,
+            stamp.dev_base_version ? `dev_base_version ${stamp.dev_base_version}` : null,
+            stamp.install_revision ? `install_revision ${stamp.install_revision}` : null,
+        ].filter(Boolean).join("; ");
+        return {
+            name: "Plugin versions",
+            status: "pass",
+            message: `${stampDetail}; Codex may keep current-session plugin skill metadata until a new Codex session starts`,
+        };
+    }
+    return {
+        name: "Plugin versions",
+        status: "pass",
+        message: `cache directory version matches packaged plugin manifest version ${manifestVersion}`,
+    };
+}
 const REQUIRED_NATIVE_REVIEWER_ROLES = ["architect", "critic"];
 const ADVISORY_NATIVE_REVIEWER_ROLES = ["scholastic"];
 function getParsedAgentTables(configPath) {
@@ -1633,6 +2041,9 @@ export function checkSparkRouting(paths) {
     const standardModel = getStandardDefaultModel(codexHomeOverride);
     const sparkSource = resolveSparkModelSource(codexHomeOverride);
     const rootProvider = getCodexConfigRootModelProvider(codexHomeOverride);
+    const explicitSparkAgentOverrides = new Map(getInstallableSparkLaneAgentNames()
+        .map((agentName) => [agentName, getAgentModelOverride(agentName, codexHomeOverride)])
+        .filter((entry) => typeof entry[1] === "string"));
     const laneSummary = `lanes: frontier=\`${frontierModel}\`, standard=\`${standardModel}\`, ` +
         `spark=\`${sparkModel}\` (source: ${sparkSource})`;
     const sparkAgents = getInstallableSparkLaneAgentNames();
@@ -1656,6 +2067,15 @@ export function checkSparkRouting(paths) {
             problems.push(`${agentName}.toml has no model field (stale install; run \`omx setup --force\`)`);
             continue;
         }
+        const explicitOverride = explicitSparkAgentOverrides.get(agentName);
+        if (explicitOverride) {
+            if (info.model !== explicitOverride) {
+                problems.push(`${agentName}.toml model is \`${info.model}\` but agentModels.${agentName} explicitly resolves to \`${explicitOverride}\` (stale install; run \`omx setup --force\`)`);
+                continue;
+            }
+            wired.push(`${agentName} -> \`${info.model}\` (agentModels override)${info.modelProvider ? ` (provider: ${info.modelProvider})` : ""}`);
+            continue;
+        }
         if (info.model !== sparkModel) {
             problems.push(`${agentName}.toml model is \`${info.model}\` but the resolved Spark model is \`${sparkModel}\` (stale install; run \`omx setup --force\`)`);
             continue;