codex-plugin-doctor 1.56.0 → 1.58.0

package/dist/core/plugin-components.js

@@ -0,0 +1,169 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+const interfaceStringFields = [
+    "displayName",
+    "shortDescription",
+    "longDescription",
+    "developerName",
+    "category",
+    "websiteURL",
+    "privacyPolicyURL",
+    "termsOfServiceURL",
+    "brandColor"
+];
+const interfaceUrlFields = new Set(["websiteURL", "privacyPolicyURL", "termsOfServiceURL"]);
+const interfacePathFields = ["composerIcon", "logo"];
+const interfaceStringArrayFields = ["capabilities", "defaultPrompt"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function relativePackagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).split(path.sep).join("/");
+}
+function isWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return relativePath === "" || (!relativePath.startsWith(`..${path.sep}`) && relativePath !== ".." && !path.isAbsolute(relativePath));
+}
+export async function resolveSafePackagePath(rootPath, value) {
+    if (!value.startsWith("./")) {
+        return null;
+    }
+    const resolvedPath = path.resolve(rootPath, value);
+    if (!isWithinRoot(rootPath, resolvedPath)) {
+        return null;
+    }
+    try {
+        const canonicalRoot = await realpath(rootPath);
+        const canonicalPath = await realpath(resolvedPath);
+        if (!isWithinRoot(canonicalRoot, canonicalPath)) {
+            return null;
+        }
+    }
+    catch {
+        // The path may be intentionally absent; callers that require it report that separately.
+    }
+    return { path: resolvedPath, packagePath: relativePackagePath(rootPath, resolvedPath) };
+}
+function invalidField(field, manifestPath) {
+    return failure("plugin.manifest.invalid_field", `The plugin manifest field \`${field}\` has an invalid value.`, "Malformed optional metadata cannot be interpreted reliably by Codex clients.", `Use the official type for \`${field}\` in .codex-plugin/plugin.json.`, { manifestPath, field });
+}
+function invalidPath(id, field, manifestPath) {
+    return failure(id, `The plugin manifest field \`${field}\` must reference a safe package-relative path.`, "Paths outside the plugin package can expose files that are not part of the plugin bundle.", `Use a \`./\` path that remains inside the plugin package for \`${field}\`.`, { manifestPath, field });
+}
+function failure(id, message, impact, suggestedFix, evidence) {
+    return { id, severity: "fail", message, impact, suggestedFix, evidence };
+}
+async function safePath(rootPath, manifestPath, field, value, id) {
+    if (typeof value !== "string") {
+        return invalidField(field, manifestPath);
+    }
+    return (await resolveSafePackagePath(rootPath, value)) ?? invalidPath(id, field, manifestPath);
+}
+function validateString(value, field, manifestPath, findings) {
+    if (value !== undefined && typeof value !== "string") {
+        findings.push(invalidField(field, manifestPath));
+    }
+}
+function validateHttpUrl(value, field, manifestPath, findings) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string" || !isHttpUrl(value)) {
+        findings.push(invalidField(field, manifestPath));
+    }
+}
+function validateStringArray(value, field, manifestPath, findings) {
+    if (value !== undefined && (!Array.isArray(value) || value.some((item) => typeof item !== "string"))) {
+        findings.push(invalidField(field, manifestPath));
+    }
+}
+function validateMetadata(manifest, manifestPath) {
+    const findings = [];
+    if (manifest.author !== undefined) {
+        if (!isPlainObject(manifest.author)) {
+            findings.push(invalidField("author", manifestPath));
+        }
+        else {
+            validateString(manifest.author.name, "author.name", manifestPath, findings);
+            validateString(manifest.author.email, "author.email", manifestPath, findings);
+            validateHttpUrl(manifest.author.url, "author.url", manifestPath, findings);
+        }
+    }
+    validateHttpUrl(manifest.homepage, "homepage", manifestPath, findings);
+    validateHttpUrl(manifest.repository, "repository", manifestPath, findings);
+    validateString(manifest.license, "license", manifestPath, findings);
+    validateStringArray(manifest.keywords, "keywords", manifestPath, findings);
+    if (manifest.interface === undefined)
+        return findings;
+    if (!isPlainObject(manifest.interface)) {
+        findings.push(invalidField("interface", manifestPath));
+        return findings;
+    }
+    for (const field of interfaceStringFields) {
+        const value = manifest.interface[field];
+        if (interfaceUrlFields.has(field)) {
+            validateHttpUrl(value, `interface.${field}`, manifestPath, findings);
+        }
+        else {
+            validateString(value, `interface.${field}`, manifestPath, findings);
+        }
+    }
+    for (const field of interfaceStringArrayFields) {
+        validateStringArray(manifest.interface[field], `interface.${field}`, manifestPath, findings);
+    }
+    return findings;
+}
+export async function validatePluginComponents(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    const manifestPath = relativePackagePath(rootPath, discoveredPackage.manifestPath);
+    const findings = validateMetadata(manifest, manifestPath);
+    const componentPaths = [
+        ["skills", manifest.skills],
+        ["mcpServers", manifest.mcpServers]
+    ];
+    if (isPlainObject(manifest.interface)) {
+        for (const field of interfacePathFields)
+            componentPaths.push([`interface.${field}`, manifest.interface[field]]);
+        const screenshots = manifest.interface.screenshots;
+        if (screenshots !== undefined && (!Array.isArray(screenshots) || screenshots.some((item) => typeof item !== "string"))) {
+            findings.push(invalidField("interface.screenshots", manifestPath));
+        }
+        else if (Array.isArray(screenshots)) {
+            screenshots.forEach((screenshot, index) => componentPaths.push([`interface.screenshots[${index}]`, screenshot]));
+        }
+    }
+    for (const [field, value] of componentPaths) {
+        if (value === undefined)
+            continue;
+        const result = await safePath(rootPath, manifestPath, field, value, "plugin.manifest.invalid_path");
+        if ("id" in result)
+            findings.push(result);
+    }
+    if (manifest.apps === undefined)
+        return findings;
+    const appPath = await safePath(rootPath, manifestPath, "apps", manifest.apps, "plugin.app.invalid_path");
+    if ("id" in appPath)
+        return [...findings, appPath];
+    try {
+        if (!(await stat(appPath.path)).isFile())
+            throw new Error("not a regular file");
+    }
+    catch {
+        return [...findings, failure("plugin.app.missing_file", "The plugin manifest points to a missing .app.json file.", "Codex cannot load an app manifest that is absent or not a regular file.", "Create the referenced app manifest as a regular JSON file inside the plugin package.", { field: "apps", path: appPath.packagePath })];
+    }
+    try {
+        JSON.parse(await readFile(appPath.path, "utf8"));
+    }
+    catch {
+        findings.push(failure("plugin.app.invalid_json", "The referenced .app.json file is not valid JSON.", "Codex cannot parse the app manifest.", "Fix the JSON syntax in the referenced app manifest.", { field: "apps", path: appPath.packagePath }));
+    }
+    return findings;
+}

package/dist/core/plugin-hooks.d.ts

@@ -0,0 +1,2 @@
+import { type DiscoveredPackage, type Finding } from "../domain/types.js";
+export declare function validatePluginHooks(discoveredPackage: DiscoveredPackage): Promise<Finding[]>;

package/dist/core/plugin-hooks.js

@@ -0,0 +1,190 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { pluginHookEvents } from "../domain/types.js";
+import { auditHookCommand } from "../security/security-audit.js";
+import { resolveSafePackagePath } from "./plugin-components.js";
+const ignoredMatcherEvents = new Set(["Stop", "UserPromptSubmit"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function packagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).replace(/\\/g, "/") || ".";
+}
+function finding(severity, id, message, impact, suggestedFix, evidence) {
+    return { severity, id, message, impact, suggestedFix, evidence };
+}
+function invalidShape(sourcePath, field) {
+    return finding("fail", "plugin.hook.invalid_shape", "The plugin lifecycle hook configuration has an invalid shape.", "Codex cannot safely interpret malformed lifecycle hook metadata.", "Use the official hook configuration schema for this field.", { sourcePath, field });
+}
+function unsupportedEvent(sourcePath, event) {
+    return finding("fail", "plugin.hook.unsupported_event", `The plugin lifecycle hook event \`${event}\` is not supported.`, "Codex will not invoke hook events outside the official lifecycle event set.", "Use one of the official plugin lifecycle hook events.", { sourcePath, event });
+}
+function invalidHookPath(manifestPath) {
+    return finding("fail", "plugin.hook.invalid_path", "The plugin lifecycle hook source must be a safe package-relative path.", "Paths outside the plugin package can expose unreviewed files to hook configuration loading.", "Use a `./` hook configuration path that stays within the plugin package.", { sourcePath: manifestPath, field: "hooks" });
+}
+function warning(id, sourcePath, event, field) {
+    const messages = {
+        "plugin.hook.unsupported_handler": [
+            "A plugin lifecycle hook uses a handler type the host skips.",
+            "Prompt and agent lifecycle handlers are not executed by this host.",
+            "Use a command handler for behavior that must run in this host."
+        ],
+        "plugin.hook.async_unsupported": [
+            "A plugin lifecycle hook requests unsupported asynchronous execution.",
+            "The host does not support asynchronous lifecycle hook execution.",
+            "Remove `async: true` or run the command synchronously."
+        ],
+        "plugin.hook.matcher_ignored": [
+            "A plugin lifecycle hook matcher is ignored for this event.",
+            "This lifecycle event does not use matcher filtering.",
+            "Remove the matcher from this event group."
+        ]
+    };
+    const [message, impact, suggestedFix] = messages[id];
+    return finding("warn", id, message, impact, suggestedFix, { sourcePath, event, field });
+}
+function validateHandler(rootPath, value, sourcePath, event, groupIndex, handlerIndex) {
+    const field = `hooks.${event}[${groupIndex}].hooks[${handlerIndex}]`;
+    if (!isPlainObject(value) || typeof value.type !== "string") {
+        return [invalidShape(sourcePath, field)];
+    }
+    const findings = [];
+    if (value.type !== "command" && value.type !== "prompt" && value.type !== "agent") {
+        return [invalidShape(sourcePath, `${field}.type`)];
+    }
+    if (value.async !== undefined && typeof value.async !== "boolean") {
+        findings.push(invalidShape(sourcePath, `${field}.async`));
+    }
+    else if (value.async === true) {
+        findings.push(warning("plugin.hook.async_unsupported", sourcePath, event, `${field}.async`));
+    }
+    if (value.type === "prompt" || value.type === "agent") {
+        findings.push(warning("plugin.hook.unsupported_handler", sourcePath, event, `${field}.type`));
+        return findings;
+    }
+    if (typeof value.command !== "string") {
+        findings.push(invalidShape(sourcePath, `${field}.command`));
+    }
+    else {
+        findings.push(...auditHookCommand(rootPath, sourcePath, event, `${field}.command`, value.command));
+    }
+    if (value.commandWindows !== undefined) {
+        if (typeof value.commandWindows !== "string") {
+            findings.push(invalidShape(sourcePath, `${field}.commandWindows`));
+        }
+        else {
+            findings.push(...auditHookCommand(rootPath, sourcePath, event, `${field}.commandWindows`, value.commandWindows));
+        }
+    }
+    if (value.timeout !== undefined && (typeof value.timeout !== "number" || !Number.isFinite(value.timeout) || value.timeout <= 0)) {
+        findings.push(invalidShape(sourcePath, `${field}.timeout`));
+    }
+    if (event === "SessionEnd" && typeof value.timeout === "number" && value.timeout > 3) {
+        findings.push(invalidShape(sourcePath, `${field}.timeout`));
+    }
+    if (value.statusMessage !== undefined && typeof value.statusMessage !== "string") {
+        findings.push(invalidShape(sourcePath, `${field}.statusMessage`));
+    }
+    if (value.additionalContextLimit !== undefined && (typeof value.additionalContextLimit !== "number" ||
+        !Number.isFinite(value.additionalContextLimit) ||
+        value.additionalContextLimit < 0)) {
+        findings.push(invalidShape(sourcePath, `${field}.additionalContextLimit`));
+    }
+    return findings;
+}
+function validateConfig(rootPath, config, sourcePath) {
+    if (!isPlainObject(config))
+        return [invalidShape(sourcePath, "root")];
+    const findings = [];
+    if (config.description !== undefined && typeof config.description !== "string") {
+        findings.push(invalidShape(sourcePath, "description"));
+    }
+    if (!isPlainObject(config.hooks)) {
+        findings.push(invalidShape(sourcePath, "hooks"));
+        return findings;
+    }
+    for (const [event, groups] of Object.entries(config.hooks)) {
+        if (!pluginHookEvents.includes(event)) {
+            findings.push(unsupportedEvent(sourcePath, event));
+            continue;
+        }
+        if (!Array.isArray(groups)) {
+            findings.push(invalidShape(sourcePath, `hooks.${event}`));
+            continue;
+        }
+        groups.forEach((group, groupIndex) => {
+            const groupField = `hooks.${event}[${groupIndex}]`;
+            if (!isPlainObject(group)) {
+                findings.push(invalidShape(sourcePath, groupField));
+                return;
+            }
+            if (group.matcher !== undefined && typeof group.matcher !== "string") {
+                findings.push(invalidShape(sourcePath, `${groupField}.matcher`));
+            }
+            else if (typeof group.matcher === "string" && ignoredMatcherEvents.has(event)) {
+                findings.push(warning("plugin.hook.matcher_ignored", sourcePath, event, `${groupField}.matcher`));
+            }
+            if (!Array.isArray(group.hooks)) {
+                findings.push(invalidShape(sourcePath, `${groupField}.hooks`));
+                return;
+            }
+            group.hooks.forEach((handler, handlerIndex) => {
+                findings.push(...validateHandler(rootPath, handler, sourcePath, event, groupIndex, handlerIndex));
+            });
+        });
+    }
+    return findings;
+}
+async function validateHookFile(rootPath, manifestPath, source) {
+    const resolved = await resolveSafePackagePath(rootPath, source);
+    if (!resolved) {
+        return [invalidHookPath(manifestPath)];
+    }
+    try {
+        if (!(await stat(resolved.path)).isFile())
+            throw new Error("not a regular file");
+    }
+    catch {
+        return [finding("fail", "plugin.hook.missing_file", "The plugin lifecycle hook source file is missing.", "Codex cannot load a hook configuration file that is absent or not a regular file.", "Create the referenced hook configuration JSON file inside the plugin package.", { sourcePath: resolved.packagePath })];
+    }
+    try {
+        return validateConfig(rootPath, JSON.parse(await readFile(resolved.path, "utf8")), resolved.packagePath);
+    }
+    catch {
+        return [finding("fail", "plugin.hook.invalid_json", "The plugin lifecycle hook source is not valid JSON.", "Codex cannot parse the hook configuration.", "Fix the JSON syntax in the hook configuration file.", { sourcePath: resolved.packagePath })];
+    }
+}
+export async function validatePluginHooks(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    const manifestPath = packagePath(rootPath, discoveredPackage.manifestPath);
+    const configuredHooks = manifest.hooks;
+    if (configuredHooks === undefined) {
+        const defaultPath = "./hooks/hooks.json";
+        const resolved = await resolveSafePackagePath(rootPath, defaultPath);
+        if (!resolved)
+            return [invalidHookPath(manifestPath)];
+        try {
+            if (!(await stat(resolved.path)).isFile())
+                return [];
+        }
+        catch {
+            return [];
+        }
+        return validateHookFile(rootPath, manifestPath, defaultPath);
+    }
+    if (typeof configuredHooks === "string") {
+        return validateHookFile(rootPath, manifestPath, configuredHooks);
+    }
+    if (Array.isArray(configuredHooks)) {
+        if (configuredHooks.length === 0)
+            return [];
+        if (configuredHooks.every((value) => typeof value === "string")) {
+            return (await Promise.all(configuredHooks.map((source) => validateHookFile(rootPath, manifestPath, source)))).flat();
+        }
+        if (configuredHooks.every(isPlainObject)) {
+            return configuredHooks.flatMap((config) => validateConfig(rootPath, config, manifestPath));
+        }
+        return [invalidShape(manifestPath, "hooks")];
+    }
+    return validateConfig(rootPath, configuredHooks, manifestPath);
+}

package/dist/core/runtime-plan.js

@@ -2,10 +2,12 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import { packageVersion } from "../version.js";
 import { discoverPackage } from "./discover-package.js";
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
 import { readJsonFile } from "./read-json-file.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
 import { DOCKER_RUNTIME_IMAGE } from "./runtime-sandbox.js";
 import { inspectRemoteMcpUrl } from "./remote-url-policy.js";
+import { resolveContainedPackagePath } from "./package-path.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -68,7 +70,7 @@ function remoteNetworkClass(rawUrl) {
     }
     return "public_https";
 }
-function planDigestPayload(plan) {
+function planDigestPayload(plan, rawServerArgs = {}) {
     return {
         schemaVersion: plan.schemaVersion,
         kind: "doctor.runtime.plan.digest.v1",
@@ -76,7 +78,10 @@ function planDigestPayload(plan) {
         execution: plan.execution,
         status: plan.status,
         summary: plan.summary,
-        servers: plan.servers,
+        servers: plan.servers.map((server) => ({
+            ...server,
+            args: rawServerArgs[server.name] ?? server.args
+        })),
         findings: plan.findings.map((finding) => ({
             id: finding.id,
             severity: finding.severity,
@@ -84,13 +89,59 @@ function planDigestPayload(plan) {
         }))
     };
 }
-function buildRuntimePlanDigest(plan) {
-    return sha256(stableStringify(planDigestPayload(plan)));
+function buildRuntimePlanDigest(plan, rawServerArgs = {}) {
+    return sha256(stableStringify(planDigestPayload(plan, rawServerArgs)));
+}
+const secretRuntimeArgumentFlag = /^--?(?:token|api[-_]?key|apikey|password|secret|credential|authorization|bearer)$/i;
+const secretRuntimeArgumentInline = /^(--?(?:token|api[-_]?key|apikey|password|secret|credential|authorization|bearer))[=:].*$/i;
+const authorizationBearerHeader = /^authorization\s*:\s*bearer\s+\S+/i;
+const inlineAuthorizationBearerHeader = /^(?:--header|-H)=authorization\s*:\s*bearer\s+\S+/i;
+function redactRuntimeArguments(args) {
+    return args.map((arg, index) => {
+        const inlineMatch = arg.match(secretRuntimeArgumentInline);
+        if (inlineMatch) {
+            return `${inlineMatch[1]}=[REDACTED]`;
+        }
+        if (authorizationBearerHeader.test(arg)) {
+            return "[REDACTED]";
+        }
+        if (inlineAuthorizationBearerHeader.test(arg)) {
+            return "[REDACTED]";
+        }
+        if (index > 0 && secretRuntimeArgumentFlag.test(args[index - 1])) {
+            return "[REDACTED]";
+        }
+        return arg;
+    });
+}
+function buildFailedRuntimePlan(targetPath, generatedAt, execution, finding) {
+    const partialPlan = {
+        schemaVersion: "1.0.0",
+        kind: "doctor.runtime.plan",
+        version: packageVersion,
+        targetPath,
+        status: "fail",
+        exitCode: 1,
+        runtimeExecution: "not_started",
+        execution,
+        summary: {
+            serverCount: 0,
+            executableServerCount: 0,
+            highRiskServerCount: 0,
+            findings: { fail: 1, warn: 0, total: 1 }
+        },
+        servers: [],
+        findings: [finding]
+    };
+    return {
+        ...partialPlan,
+        generatedAt,
+        digest: buildRuntimePlanDigest(partialPlan)
+    };
 }
 export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date().toISOString(), options = {}) {
     const rootPath = path.resolve(targetPath);
     const discoveredPackage = await discoverPackage(rootPath);
-    const security = await buildSecurityAudit(rootPath);
     const execution = options.sandbox === "docker"
         ? {
             backend: "docker",
@@ -99,7 +150,8 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
             packageMount: "read_only"
         }
         : { backend: "native", image: null, network: "host", packageMount: "host" };
-    if (!discoveredPackage?.manifest.mcpServers) {
+    if (!discoveredPackage || !Object.hasOwn(discoveredPackage.manifest, "mcpServers")) {
+        const security = await buildSecurityAudit(rootPath);
         const partialPlan = {
             schemaVersion: "1.0.0",
             kind: "doctor.runtime.plan",
@@ -124,16 +176,43 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
             digest: buildRuntimePlanDigest(partialPlan)
         };
     }
+    const manifestMcpServers = discoveredPackage.manifest.mcpServers;
+    if (typeof manifestMcpServers !== "string" ||
+        !manifestMcpServers ||
+        !manifestMcpServers.startsWith("./")) {
+        return buildFailedRuntimePlan(discoveredPackage.rootPath, generatedAt, execution, {
+            id: typeof manifestMcpServers === "string"
+                ? "plugin.manifest.invalid_path"
+                : "plugin.manifest.invalid_field",
+            severity: "fail",
+            message: "The plugin manifest mcpServers field must be a non-empty package-relative path.",
+            impact: "Runtime planning cannot safely resolve malformed MCP server configuration metadata.",
+            suggestedFix: "Use a non-empty ./ path for mcpServers that remains inside the package.",
+            evidence: { manifestPath: ".codex-plugin/plugin.json", field: "mcpServers" }
+        });
+    }
+    const mcpConfigPath = await resolveContainedPackagePath(discoveredPackage.rootPath, manifestMcpServers);
+    if (!mcpConfigPath) {
+        return buildFailedRuntimePlan(discoveredPackage.rootPath, generatedAt, execution, {
+            id: "plugin.security.mcp_config_path",
+            severity: "fail",
+            message: "The MCP server config path resolves outside the package root.",
+            impact: "Runtime planning cannot safely inspect MCP server metadata outside the package.",
+            suggestedFix: "Use an MCP server config path that remains inside the package root.",
+            evidence: { manifestPath: ".codex-plugin/plugin.json", field: "mcpServers" }
+        });
+    }
+    const security = await buildSecurityAudit(rootPath);
     let parsedConfig;
     try {
-        parsedConfig = await readJsonFile(path.resolve(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers));
+        parsedConfig = await readJsonFile(mcpConfigPath);
     }
     catch {
         parsedConfig = {};
     }
-    const serverEntries = isPlainObject(parsedConfig) && isPlainObject(parsedConfig.mcpServers)
-        ? Object.entries(parsedConfig.mcpServers)
-        : [];
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    const serverEntries = normalizedConfig.ok ? Object.entries(normalizedConfig.servers) : [];
+    const rawServerArgs = {};
     const servers = serverEntries
         .filter((entry) => isPlainObject(entry[1]))
         .map(([serverName, serverConfig]) => {
@@ -142,13 +221,15 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
         const { riskLevel, riskReasons } = buildRisk(serverName, serverConfig, security.findings);
         const networkClass = url ? remoteNetworkClass(url) : undefined;
         const sanitizedUrl = url ? inspectRemoteMcpUrl(url).sanitizedUrl : null;
+        const args = Array.isArray(serverConfig.args)
+            ? serverConfig.args.filter((arg) => typeof arg === "string")
+            : [];
+        rawServerArgs[serverName] = args;
         return {
             name: serverName,
             transport: command ? "stdio" : "http",
             command,
-            args: Array.isArray(serverConfig.args)
-                ? serverConfig.args.filter((arg) => typeof arg === "string")
-                : [],
+            args: redactRuntimeArguments(args),
             cwd: command ? normalizeCwd(discoveredPackage.rootPath, serverConfig.cwd) : null,
             url: sanitizedUrl,
             ...(networkClass ? { networkClass } : {}),
@@ -182,12 +263,12 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
         kind: "doctor.runtime.plan",
         version: packageVersion,
         targetPath: discoveredPackage.rootPath,
-        status: highRiskServerCount > 0
+        status: !normalizedConfig.ok || highRiskServerCount > 0 || security.status === "fail"
             ? "fail"
             : security.status === "warn"
                 ? "warn"
                 : "pass",
-        exitCode: (highRiskServerCount > 0 ? 1 : 0),
+        exitCode: (!normalizedConfig.ok || highRiskServerCount > 0 || security.status === "fail" ? 1 : 0),
         runtimeExecution: "not_started",
         execution,
         summary: {
@@ -202,7 +283,7 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
     return {
         ...partialPlan,
         generatedAt,
-        digest: buildRuntimePlanDigest(partialPlan)
+        digest: buildRuntimePlanDigest(partialPlan, rawServerArgs)
     };
 }
 export function evaluateRuntimeApproval(plan, options) {

package/dist/core/runtime-probe.js

@@ -6,6 +6,7 @@ import readline from "node:readline";
 import { evaluateMcpConformance } from "./mcp-conformance.js";
 import { probeRemoteMcpServer } from "./remote-mcp-probe.js";
 import { buildRuntimeLaunch, DOCKER_RUNTIME_STARTUP_TIMEOUT_MS, RuntimeSandboxError } from "./runtime-sandbox.js";
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
 import { formatRequestTranscript as formatRequestTranscriptForLog, formatResponseTranscript as formatResponseTranscriptForLog } from "./runtime-transcript.js";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const PROMPT_PROBE_PLACEHOLDER = "codex-plugin-doctor-probe";
@@ -262,14 +263,8 @@ async function loadMcpServers(mcpConfigPath) {
     catch {
         return null;
     }
-    if (!isPlainObject(parsedConfig)) {
-        return null;
-    }
-    const servers = parsedConfig.mcpServers;
-    if (!isPlainObject(servers)) {
-        return null;
-    }
-    return servers;
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    return normalizedConfig.ok ? normalizedConfig.servers : null;
 }
 function getCapabilities(message) {
     if (!isPlainObject(message.result)) {