codex-plugin-doctor 1.49.0 → 1.51.0

package/dist/mcp/generic-mcp-doctor.js

@@ -1,7 +1,8 @@
-import { stat } from "node:fs/promises";
+import { realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { buildCompatibilityMatrix, readMcpConfigPath } from "../compatibility/compatibility-matrix.js";
 import { readJsonFile } from "../core/read-json-file.js";
+import { probeRuntimeConfig } from "../core/runtime-probe.js";
 import { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { auditMcpServerConfig, buildSecurityAuditFromFindings } from "../security/security-audit.js";
 function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
@@ -72,30 +73,36 @@ function buildStaticMcpFindings(configPath, parsedConfig) {
         findings
     };
 }
-function mergeReportStatus(staticFindings, security) {
-    if (staticFindings.some((finding) => finding.severity === "fail") || security.status === "fail") {
+function mergeReportStatus(findings, security) {
+    if (findings.some((finding) => finding.severity === "fail") || security.status === "fail") {
         return "fail";
     }
-    if (staticFindings.some((finding) => finding.severity === "warn") || security.status === "warn") {
+    if (findings.some((finding) => finding.severity === "warn") || security.status === "warn") {
         return "warn";
     }
     return "pass";
 }
-export async function buildGenericMcpDoctor(targetPath, environment = {}) {
+export async function buildGenericMcpDoctor(targetPath, environment = {}, options = {}) {
     const rootPath = path.resolve(targetPath);
     const compatibility = await buildCompatibilityMatrix(rootPath, environment);
     const mcpConfigPath = await readMcpConfigPath(rootPath);
+    const canonicalRootPath = await realpath(rootPath).catch(() => null);
+    const canonicalMcpConfigPath = mcpConfigPath
+        ? await realpath(mcpConfigPath).catch(() => null)
+        : null;
     let parsedConfig = null;
     let staticFindings = [];
     let serverCount = 0;
     if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
         staticFindings = buildStaticMcpFindings(null, null).findings;
     }
-    else if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+    else if (!canonicalRootPath ||
+        !canonicalMcpConfigPath ||
+        !isPathWithinRoot(canonicalRootPath, canonicalMcpConfigPath)) {
         staticFindings = [
             buildFinding("fail", "mcp.config.path_outside_root", "The MCP config path resolves outside the target root.", "A package that reads MCP configuration outside its root is harder to audit and can depend on unreviewed local files.", "Keep `.mcp.json` or the manifest `mcpServers` reference inside the package root.", {
                 configPath: path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"),
-                resolvedPath: mcpConfigPath,
+                resolvedPath: canonicalMcpConfigPath ?? mcpConfigPath,
                 field: "configPath"
             })
         ];
@@ -119,17 +126,31 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}) {
     const security = buildSecurityAuditFromFindings(rootPath, mcpConfigPath && parsedConfig !== null
         ? auditMcpServerConfig(rootPath, parsedConfig)
         : []);
-    const fingerprintedStaticFindings = withFindingFingerprints(staticFindings, rootPath);
-    const status = mergeReportStatus(fingerprintedStaticFindings, security);
+    const runtimeResult = options.runtime &&
+        mcpConfigPath !== null &&
+        parsedConfig !== null &&
+        canonicalRootPath !== null &&
+        canonicalMcpConfigPath !== null &&
+        isPathWithinRoot(canonicalRootPath, canonicalMcpConfigPath) &&
+        !staticFindings.some((finding) => finding.severity === "fail") &&
+        security.status !== "fail"
+        ? await probeRuntimeConfig(canonicalRootPath, canonicalMcpConfigPath, {
+            startupTimeoutMs: options.runtimeStartupTimeoutMs
+        })
+        : null;
+    const fingerprintedFindings = withFindingFingerprints([...staticFindings, ...(runtimeResult?.findings ?? [])], rootPath);
+    const status = mergeReportStatus(fingerprintedFindings, security);
     return {
         targetPath: rootPath,
         status,
         exitCode: status === "fail" ? 1 : 0,
         mcpConfigPath,
         serverCount,
-        findings: [...fingerprintedStaticFindings, ...security.findings],
+        findings: [...fingerprintedFindings, ...security.findings],
         security,
-        compatibility
+        compatibility,
+        ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {}),
+        ...(runtimeResult?.execution ? { runtimeExecution: runtimeResult.execution } : {})
     };
 }
 export function renderGenericMcpDoctorJson(report) {
@@ -153,6 +174,9 @@ export function renderGenericMcpDoctor(report) {
             .map((result) => `${result.client}=${result.status}`)
             .join(", ")}`
     ];
+    if (report.runtimeScorecard?.conformance) {
+        lines.push(`Runtime conformance: ${report.runtimeScorecard.conformance.overall.toUpperCase()}`);
+    }
     if (report.findings.length === 0) {
         lines.push("", "No findings.");
         return lines.join("\n");

package/dist/reporting/render-markdown-report.js

@@ -1,6 +1,36 @@
 import { formatFindingEvidenceLine } from "./format-finding-evidence.js";
 import { formatFindingFingerprintLine } from "./finding-fingerprint.js";
 import { buildRecommendedCommands } from "./recommended-commands.js";
+function appendRuntimeScorecard(lines, result) {
+    if (!result.runtimeScorecard) {
+        return;
+    }
+    lines.push("", "## Runtime Scorecard", "");
+    lines.push("| Operation | Status |");
+    lines.push("| --- | --- |");
+    lines.push(`| initialize | ${result.runtimeScorecard.initialize.toUpperCase()} |`);
+    lines.push(`| tools/list | ${result.runtimeScorecard.toolsList.toUpperCase()} |`);
+    lines.push(`| tools/call | ${result.runtimeScorecard.toolsCall.toUpperCase()} |`);
+    lines.push(`| resources/list | ${result.runtimeScorecard.resourcesList.toUpperCase()} |`);
+    lines.push(`| resources/read | ${result.runtimeScorecard.resourceRead.toUpperCase()} |`);
+    lines.push(`| resources/templates/list | ${result.runtimeScorecard.resourceTemplatesList.toUpperCase()} |`);
+    lines.push(`| prompts/list | ${result.runtimeScorecard.promptsList.toUpperCase()} |`);
+    lines.push(`| prompts/get | ${result.runtimeScorecard.promptGet.toUpperCase()} |`);
+    const conformance = result.runtimeScorecard.conformance;
+    if (!conformance) {
+        return;
+    }
+    lines.push("", "## MCP Conformance", "");
+    lines.push("| Check | Status |");
+    lines.push("| --- | --- |");
+    lines.push(`| Protocol version | ${conformance.protocolVersion ?? "unavailable"} |`);
+    lines.push(`| Profile | ${conformance.profile ?? "unavailable"} |`);
+    lines.push(`| Capability consistency | ${conformance.capabilityConsistency.toUpperCase()} |`);
+    lines.push(`| Task declarations | ${conformance.taskDeclarations.toUpperCase()} |`);
+    lines.push(`| Tasks list | ${conformance.tasksList.toUpperCase()} |`);
+    lines.push(`| Schema dialect | ${conformance.schemaDialect.toUpperCase()} |`);
+    lines.push(`| Overall | ${conformance.overall.toUpperCase()} |`);
+}
 export function buildMarkdownReport(result, options) {
     const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
     const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
@@ -26,23 +56,11 @@ export function buildMarkdownReport(result, options) {
     if (result.runtimeExecution) {
         lines.push("", `Runtime backend: ${result.runtimeExecution.backend.toUpperCase()}`, `Runtime isolation: network=${result.runtimeExecution.network}, package=${result.runtimeExecution.packageMount}`);
     }
+    appendRuntimeScorecard(lines, result);
     if (result.findings.length === 0 && !result.suppressedFindings?.length) {
         lines.push("", result.baselineSummary ? "No new findings." : "No findings.");
         return lines.join("\n");
     }
-    if (result.runtimeScorecard) {
-        lines.push("", "## Runtime Scorecard", "");
-        lines.push("| Operation | Status |");
-        lines.push("| --- | --- |");
-        lines.push(`| initialize | ${result.runtimeScorecard.initialize.toUpperCase()} |`);
-        lines.push(`| tools/list | ${result.runtimeScorecard.toolsList.toUpperCase()} |`);
-        lines.push(`| tools/call | ${result.runtimeScorecard.toolsCall.toUpperCase()} |`);
-        lines.push(`| resources/list | ${result.runtimeScorecard.resourcesList.toUpperCase()} |`);
-        lines.push(`| resources/read | ${result.runtimeScorecard.resourceRead.toUpperCase()} |`);
-        lines.push(`| resources/templates/list | ${result.runtimeScorecard.resourceTemplatesList.toUpperCase()} |`);
-        lines.push(`| prompts/list | ${result.runtimeScorecard.promptsList.toUpperCase()} |`);
-        lines.push(`| prompts/get | ${result.runtimeScorecard.promptGet.toUpperCase()} |`);
-    }
     if (result.findings.length > 0) {
         const nextActions = Array.from(new Set(result.findings.map((finding) => finding.suggestedFix))).slice(0, 5);
         if (nextActions.length > 0) {

package/dist/reporting/render-text-report.js

@@ -24,6 +24,32 @@ function getGlyphs(ascii) {
             ok: "✔"
         };
 }
+function appendRuntimeScorecard(lines, result) {
+    if (!result.runtimeScorecard) {
+        return;
+    }
+    lines.push("", "Runtime Scorecard", "----------------");
+    lines.push(`initialize: ${result.runtimeScorecard.initialize}`);
+    lines.push(`tools/list: ${result.runtimeScorecard.toolsList}`);
+    lines.push(`tools/call: ${result.runtimeScorecard.toolsCall}`);
+    lines.push(`resources/list: ${result.runtimeScorecard.resourcesList}`);
+    lines.push(`resources/read: ${result.runtimeScorecard.resourceRead}`);
+    lines.push(`resources/templates/list: ${result.runtimeScorecard.resourceTemplatesList}`);
+    lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
+    lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
+    const conformance = result.runtimeScorecard.conformance;
+    if (!conformance) {
+        return;
+    }
+    lines.push("", "MCP Conformance", "---------------");
+    lines.push(`Protocol version: ${conformance.protocolVersion ?? "unavailable"}`);
+    lines.push(`Profile: ${conformance.profile ?? "unavailable"}`);
+    lines.push(`Capability consistency: ${conformance.capabilityConsistency}`);
+    lines.push(`Task declarations: ${conformance.taskDeclarations}`);
+    lines.push(`Tasks list: ${conformance.tasksList}`);
+    lines.push(`Schema dialect: ${conformance.schemaDialect}`);
+    lines.push(`Overall: ${conformance.overall}`);
+}
 export function renderTextReport(result, options = {}) {
     const ascii = options.ascii ?? false;
     const explain = options.explain ?? false;
@@ -46,17 +72,7 @@ export function renderTextReport(result, options = {}) {
         lines.push(`Runtime backend: ${result.runtimeExecution.backend.toUpperCase()}`, `Runtime isolation: network=${result.runtimeExecution.network}, package=${result.runtimeExecution.packageMount}`);
     }
     if (result.findings.length === 0 && !result.suppressedFindings?.length) {
-        if (result.runtimeScorecard) {
-            lines.push("", "Runtime Scorecard", "----------------");
-            lines.push(`initialize: ${result.runtimeScorecard.initialize}`);
-            lines.push(`tools/list: ${result.runtimeScorecard.toolsList}`);
-            lines.push(`tools/call: ${result.runtimeScorecard.toolsCall}`);
-            lines.push(`resources/list: ${result.runtimeScorecard.resourcesList}`);
-            lines.push(`resources/read: ${result.runtimeScorecard.resourceRead}`);
-            lines.push(`resources/templates/list: ${result.runtimeScorecard.resourceTemplatesList}`);
-            lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
-            lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
-        }
+        appendRuntimeScorecard(lines, result);
         lines.push("", result.baselineSummary ? "No new findings." : "No findings.");
         return lines.join("\n");
     }
@@ -114,17 +130,7 @@ export function renderTextReport(result, options = {}) {
             lines.push(`  Expires: ${finding.suppression.expiresAt}`);
         }
     }
-    if (result.runtimeScorecard) {
-        lines.push("", "Runtime Scorecard", "----------------");
-        lines.push(`initialize: ${result.runtimeScorecard.initialize}`);
-        lines.push(`tools/list: ${result.runtimeScorecard.toolsList}`);
-        lines.push(`tools/call: ${result.runtimeScorecard.toolsCall}`);
-        lines.push(`resources/list: ${result.runtimeScorecard.resourcesList}`);
-        lines.push(`resources/read: ${result.runtimeScorecard.resourceRead}`);
-        lines.push(`resources/templates/list: ${result.runtimeScorecard.resourceTemplatesList}`);
-        lines.push(`prompts/list: ${result.runtimeScorecard.promptsList}`);
-        lines.push(`prompts/get: ${result.runtimeScorecard.promptGet}`);
-    }
+    appendRuntimeScorecard(lines, result);
     const recommendedCommands = buildRecommendedCommands(result);
     if (recommendedCommands.length > 0) {
         lines.push("", "Recommended Commands", "--------------------");

package/dist/rules/rule-catalog.js

@@ -278,6 +278,78 @@ export const ruleCatalog = [
         fix: "Remove hidden override or exfiltration instructions and keep descriptions scoped to legitimate behavior.",
         example: "Keep SKILL.md, prompt, resource, and tool descriptions direct and user-facing."
     },
+    {
+        id: "mcp.conformance.protocol.unknown_newer",
+        category: "mcp",
+        defaultSeverity: "warn",
+        summary: "The server advertises a newer MCP protocol version.",
+        why: "The validator applies the 2025-11-25 structural baseline, which may not cover newer protocol requirements.",
+        fix: "Confirm the server's newer protocol changes remain compatible with the 2025-11-25 MCP contract.",
+        example: '{ "protocolVersion": "2026-01-01" }'
+    },
+    {
+        id: "mcp.conformance.tasks.capability_invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A Tasks capability declaration is malformed.",
+        why: "Codex cannot safely determine whether the server supports task-aware tool calls.",
+        fix: "Return an object for the affected Tasks capability field, or omit the capability until it is implemented.",
+        example: '{ "capabilities": { "tasks": { "requests": { "tools": { "call": {} } } } } }'
+    },
+    {
+        id: "mcp.conformance.tasks.task_support_invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A tool declares invalid task support.",
+        why: "Codex cannot safely interpret the tool's task support contract.",
+        fix: "Set execution.taskSupport to required, optional, or forbidden.",
+        example: '{ "execution": { "taskSupport": "optional" } }'
+    },
+    {
+        id: "mcp.conformance.tasks.capability_mismatch",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A tool's task support does not match server capability.",
+        why: "Codex may attempt task-aware tool calls that the server did not advertise as supported.",
+        fix: "Advertise capabilities.tasks.requests.tools.call as an object, or set execution.taskSupport to forbidden.",
+        example: '{ "capabilities": { "tasks": { "requests": { "tools": { "call": {} } } } }, "execution": { "taskSupport": "required" } }'
+    },
+    {
+        id: "mcp.conformance.tasks_list.timeout",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The server did not complete tasks/list in time.",
+        why: "Codex cannot rely on task discovery when tasks/list cannot complete with a valid response.",
+        fix: "Reduce tasks/list latency and verify pagination completes.",
+        example: "Return a valid tasks/list response before the configured runtime timeout."
+    },
+    {
+        id: "mcp.conformance.tasks_list.invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The server returned an invalid tasks/list response.",
+        why: "Codex cannot rely on task discovery when tasks/list cannot complete with a valid response.",
+        fix: "Return a valid tasks/list response with well-formed task items and pagination.",
+        example: '{ "tasks": [] }'
+    },
+    {
+        id: "mcp.conformance.schema.dialect_invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A tool schema declares an invalid dialect.",
+        why: "Codex cannot reliably select a schema dialect for this tool.",
+        fix: "Omit $schema or provide an absolute URI in the affected tool schema.",
+        example: '{ "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } }'
+    },
+    {
+        id: "mcp.conformance.schema.dialect_unsupported",
+        category: "mcp",
+        defaultSeverity: "warn",
+        summary: "A tool schema uses a non-canonical dialect.",
+        why: "The schema may be valid, but its dialect is outside the validator's latest compatibility baseline.",
+        fix: "Use https://json-schema.org/draft/2020-12/schema or omit $schema.",
+        example: '{ "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } }'
+    },
     {
         id: "plugin.runtime.exited_early",
         category: "runtime",

package/dist/run-cli.js

@@ -100,7 +100,7 @@ function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     return value;
 }
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--runtime --sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--runtime --sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime --sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime --sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime] [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--runtime --sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--runtime --sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime --sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime --sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
     io.writeStderr("Corpus quality regression: codex-plugin-doctor doctor corpus metrics diff --before <metrics.json> --after <metrics.json> [--fail-on-regression] [--json|--markdown] [--output <path>]");
     io.writeStderr("Suppression governance: codex-plugin-doctor suppress list <path> [--fail-on-expired] [--fail-on-invalid] [--warn-expiring-within-days <days>]\n       codex-plugin-doctor suppress prune <path> [--apply] [--json]");
     io.writeStderr("Baseline gating: codex-plugin-doctor baseline create <path> --output <path> [--runtime]\n       codex-plugin-doctor check <path> --baseline <path>");
@@ -647,17 +647,48 @@ async function executeSuppressCommand(command, io, options = {}) {
 }
 function buildGenericMcpDoctorCommandArgs(commandTarget, flags) {
     if (!commandTarget || commandTarget.startsWith("--")) {
-        return "Missing target path. Usage: codex-plugin-doctor mcp <path> [--json] [--output <path>]";
+        return "Missing target path. Usage: codex-plugin-doctor mcp <path> [--runtime] [--json] [--output <path>]";
     }
-    const outputIndex = flags.indexOf("--output");
-    const outputPath = outputIndex === -1 ? null : flags[outputIndex + 1];
-    if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
-        return "Missing path after --output.";
+    let jsonOutput = false;
+    let outputPath = null;
+    let runtime = false;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        if (flag === "--runtime") {
+            if (runtime) {
+                return "Duplicate MCP flag: --runtime.";
+            }
+            runtime = true;
+            continue;
+        }
+        if (flag === "--json") {
+            if (jsonOutput) {
+                return "Duplicate MCP flag: --json.";
+            }
+            jsonOutput = true;
+            continue;
+        }
+        if (flag === "--output") {
+            if (outputPath !== null) {
+                return "Duplicate MCP flag: --output.";
+            }
+            const value = flags[index + 1];
+            if (!value || value.startsWith("--")) {
+                return "Missing path after --output.";
+            }
+            outputPath = value;
+            index += 1;
+            continue;
+        }
+        return flag.startsWith("--")
+            ? `Unknown MCP flag: ${flag}.`
+            : `Unexpected MCP argument: ${flag}.`;
     }
     return {
         targetPath: commandTarget,
-        jsonOutput: flags.includes("--json"),
-        outputPath
+        jsonOutput,
+        outputPath,
+        runtime
     };
 }
 function parsePerformanceThresholds(flags) {
@@ -944,6 +975,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const report = await buildGenericMcpDoctor(parsedMcpArgs.targetPath, {
                 env: terminalContext.env,
                 platform: terminalContext.platform
+            }, {
+                runtime: parsedMcpArgs.runtime
             });
             const renderedReport = parsedMcpArgs.jsonOutput
                 ? renderGenericMcpDoctorJson(report)
@@ -2223,6 +2256,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const report = await buildGenericMcpDoctor(parsedMcpArgs.targetPath, {
             env: terminalContext.env,
             platform: terminalContext.platform
+        }, {
+            runtime: parsedMcpArgs.runtime
         });
         const renderedReport = parsedMcpArgs.jsonOutput
             ? renderGenericMcpDoctorJson(report)

package/examples/README.md

@@ -1,94 +1,94 @@
-# Examples
-
-This folder contains manual example packs for local testing. Unlike `tests/fixtures`, these examples are meant for humans to run directly against the CLI.
-
-## Example Packs
-
-Use the smallest example that matches what you need to prove:
-
-- `codex-doctor-starter` for static manifest and skill validation.
-- `codex-doctor-runtime` for full MCP runtime probing and compatibility scoring.
-- `codex-doctor-risky` for security finding output.
-- `codex-doctor-generic-mcp` for MCP-only packages without a Codex plugin manifest.
-
-### `codex-doctor-starter`
-
-Minimal valid Codex plugin package with one skill and no runtime MCP server.
-
-Expected result:
-
-- static validation passes
-- no runtime probing needed
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-starter
-```
-
-### `codex-doctor-runtime`
-
-Valid Codex plugin package with:
-
-- skill metadata
-- `.mcp.json`
-- mock MCP stdio server
-- `tools/list`
-- `tools/call`
-- `resources/list`
-- `resources/read`
-- `resources/templates/list`
-- `prompts/list`
-- `prompts/get`
-
-Expected result:
-
-- static validation passes
-- runtime validation passes
-- runtime scorecard shows all supported runtime capabilities as `pass`
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
-```
-
-### `codex-doctor-risky`
-
-Intentionally flawed package for showing failure output.
-
-Expected result:
-
-- security finding for hard-coded secret
-
-Command:
-
-```bash
-codex-plugin-doctor check examples/codex-doctor-risky --ascii
-```
-
-### `codex-doctor-generic-mcp`
-
-Generic MCP package with a `.mcp.json` file and no Codex plugin manifest.
-
-Expected result:
-
-- `codex-plugin-doctor mcp` passes generic MCP static health checks
-- `codex-plugin-doctor check` still reports the missing Codex plugin manifest
-
-Command:
-
-```bash
-codex-plugin-doctor mcp examples/codex-doctor-generic-mcp
-```
-
-## Suggested Local Flow
-
-```bash
-npm install
-npm run build
-npm link
-codex-plugin-doctor check examples/codex-doctor-starter
-codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
-codex-plugin-doctor check examples/codex-doctor-risky --ascii
-```
+# Examples
+
+This folder contains manual example packs for local testing. Unlike `tests/fixtures`, these examples are meant for humans to run directly against the CLI.
+
+## Example Packs
+
+Use the smallest example that matches what you need to prove:
+
+- `codex-doctor-starter` for static manifest and skill validation.
+- `codex-doctor-runtime` for full MCP runtime probing and compatibility scoring.
+- `codex-doctor-risky` for security finding output.
+- `codex-doctor-generic-mcp` for MCP-only packages without a Codex plugin manifest.
+
+### `codex-doctor-starter`
+
+Minimal valid Codex plugin package with one skill and no runtime MCP server.
+
+Expected result:
+
+- static validation passes
+- no runtime probing needed
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-starter
+```
+
+### `codex-doctor-runtime`
+
+Valid Codex plugin package with:
+
+- skill metadata
+- `.mcp.json`
+- mock MCP stdio server
+- `tools/list`
+- `tools/call`
+- `resources/list`
+- `resources/read`
+- `resources/templates/list`
+- `prompts/list`
+- `prompts/get`
+
+Expected result:
+
+- static validation passes
+- runtime validation passes
+- runtime scorecard shows all supported runtime capabilities as `pass`
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+```
+
+### `codex-doctor-risky`
+
+Intentionally flawed package for showing failure output.
+
+Expected result:
+
+- security finding for hard-coded secret
+
+Command:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```
+
+### `codex-doctor-generic-mcp`
+
+Generic MCP package with a `.mcp.json` file and no Codex plugin manifest.
+
+Expected result:
+
+- `codex-plugin-doctor mcp` passes generic MCP static health checks
+- `codex-plugin-doctor check` still reports the missing Codex plugin manifest
+
+Command:
+
+```bash
+codex-plugin-doctor mcp examples/codex-doctor-generic-mcp
+```
+
+## Suggested Local Flow
+
+```bash
+npm install
+npm run build
+npm link
+codex-plugin-doctor check examples/codex-doctor-starter
+codex-plugin-doctor check examples/codex-doctor-runtime --json --runtime --verbose-runtime
+codex-plugin-doctor check examples/codex-doctor-risky --ascii
+```

package/examples/codex-doctor-generic-mcp/.mcp.json

@@ -1,10 +1,10 @@
-{
-  "mcpServers": {
-    "genericRuntime": {
-      "command": "node",
-      "args": [
-        "server.js"
-      ]
-    }
-  }
-}
+{
+  "mcpServers": {
+    "genericRuntime": {
+      "command": "node",
+      "args": [
+        "server.js"
+      ]
+    }
+  }
+}

package/examples/codex-doctor-generic-mcp/server.js

@@ -1 +1 @@
-process.stdin.resume();
+process.stdin.resume();

package/examples/codex-doctor-risky/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
-{
-  "name": "codex-doctor-risky",
-  "version": "1.0.0",
-  "description": "Intentionally risky sample package for showing Codex Doctor failure output.",
-  "mcpServers": "./.mcp.json"
-}
-
+{
+  "name": "codex-doctor-risky",
+  "version": "1.0.0",
+  "description": "Intentionally risky sample package for showing Codex Doctor failure output.",
+  "mcpServers": "./.mcp.json"
+}
+