codex-plugin-doctor 1.1.0 → 1.2.0

package/README.md

@@ -64,7 +64,7 @@ Security scorecard with `security`:
 - MCP server `cwd` paths that escape the package root
 - plain HTTP remote transport warnings
 
-Runtime MCP validation with `--runtime`:
+Runtime MCP validation with `--runtime`:
 
 - `initialize`
 - `notifications/initialized`
@@ -76,8 +76,9 @@ Runtime MCP validation with `--runtime`:
 - `prompts/list`
 - `prompts/get`
 - paginated list responses
-- runtime capability scorecard
-- redacted verbose transcript with `--verbose-runtime`
+- runtime capability scorecard
+- redacted verbose transcript with `--verbose-runtime`
+- optional runtime approval gating with a precomputed `doctor runtime-plan` digest
 
 Output formats:
 
@@ -212,6 +213,8 @@ codex-plugin-doctor doctor trust . --json --output trust-score.json
 codex-plugin-doctor doctor perf .
 codex-plugin-doctor doctor perf . --json --output perf.json
 codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=500
+codex-plugin-doctor doctor runtime-plan .
+codex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json
 codex-plugin-doctor doctor mcp .
 codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
 codex-plugin-doctor doctor export --bundle .
@@ -267,9 +270,10 @@ codex-plugin-doctor check . --badge-json --output doctor-badge.json
 codex-plugin-doctor check . --badge-markdown
 codex-plugin-doctor check . --sarif --output results.sarif
 codex-plugin-doctor check . --ascii
-codex-plugin-doctor check . --no-animations
-codex-plugin-doctor check . --runtime
-codex-plugin-doctor check . --config .codex-doctor.json
+codex-plugin-doctor check . --no-animations
+codex-plugin-doctor check . --runtime
+codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
+codex-plugin-doctor check . --config .codex-doctor.json
 codex-plugin-doctor check . --history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl --json
@@ -282,7 +286,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, and git release gates. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
 
 `audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
 
@@ -348,9 +352,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.1.0
+      - uses: Esquetta/CodexPluginDoctor@v1.2.0
         with:
-          version: "1.1.0"
+          version: "1.2.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/output-contract.js

@@ -71,6 +71,12 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.perf",
         required: ["schemaVersion", "kind", "generatedAt", "targetPath", "status", "exitCode", "summary", "stages", "thresholds"]
     },
+    {
+        id: "doctor.runtime.plan.json",
+        command: "codex-plugin-doctor doctor runtime-plan <path> --json",
+        outputKind: "doctor.runtime.plan",
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "digest", "summary", "servers", "findings"]
+    },
     {
         id: "doctor.export.bundle.json",
         command: "codex-plugin-doctor doctor export --bundle <path> --json",
@@ -93,7 +99,7 @@ const publicSchemaDefinitions = [
         id: "doctor.release.evidence.json",
         command: "codex-plugin-doctor doctor release-evidence <path> --json",
         outputKind: "doctor.release.evidence",
-        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "releaseReady", "summary", "package", "git", "releaseGates", "attestation", "attestationVerification", "corpus", "performance", "security", "trust", "evidenceSignature"]
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "releaseReady", "summary", "package", "git", "releaseGates", "runtimeApproval", "attestation", "attestationVerification", "corpus", "performance", "security", "trust", "evidenceSignature"]
     },
     {
         id: "doctor.release.evidence.verification.json",

package/dist/core/release-evidence.d.ts

@@ -3,6 +3,7 @@ import { type DoctorPerformanceReport, type DoctorPerformanceThresholdOptions }
 import { type DoctorValidationCorpusReport } from "./validation-corpus.js";
 import { type SecurityAudit } from "../security/security-audit.js";
 import { type TrustScoreReport } from "../security/trust-score.js";
+import { type RuntimeApprovalReport } from "./runtime-plan.js";
 import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
 import type { CheckResult } from "../domain/types.js";
 type EvidenceStatus = "pass" | "warn" | "fail";
@@ -38,6 +39,7 @@ export interface DoctorReleaseEvidenceReport {
         corpus: EvidenceStatus;
         performance: EvidenceStatus;
         releaseGates: EvidenceStatus;
+        runtimeApproval: EvidenceStatus;
         security: EvidenceStatus;
         trust: EvidenceStatus;
     };
@@ -49,6 +51,7 @@ export interface DoctorReleaseEvidenceReport {
             message: string;
         }>;
     };
+    runtimeApproval: RuntimeApprovalReport;
     package: DoctorReleaseEvidencePackageMetadata;
     git: DoctorReleaseEvidenceGitMetadata;
     attestation: DoctorAttestation;
@@ -104,6 +107,8 @@ export interface BuildDoctorReleaseEvidenceOptions {
     signingKeyEnv: string;
     allowDirty?: boolean;
     allowUntagged?: boolean;
+    requireRuntimeApproval?: boolean;
+    runtimeApprovalDigest?: string | null;
     environment?: CompatibilityEnvironment;
     runCheck?: (targetPath: string) => Promise<CheckResult>;
     performanceThresholds?: DoctorPerformanceThresholdOptions;

package/dist/core/release-evidence.js

@@ -9,6 +9,7 @@ import { redactValue } from "./doctor-export-bundle.js";
 import { readJsonFile } from "./read-json-file.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
 import { buildTrustScore } from "../security/trust-score.js";
+import { buildDoctorRuntimePlan, evaluateRuntimeApproval, runtimeApprovalPassed } from "./runtime-plan.js";
 import { packageVersion } from "../version.js";
 const execFileAsync = promisify(execFile);
 function isPlainObject(value) {
@@ -102,6 +103,7 @@ function releaseReady(report) {
         report.corpus.summary.status === "pass" &&
         report.performance.status === "pass" &&
         report.releaseGates.status === "pass" &&
+        runtimeApprovalPassed(report.runtimeApproval) &&
         report.security.status !== "fail" &&
         report.trust.status !== "fail";
 }
@@ -149,6 +151,7 @@ function buildReleaseEvidenceSigningPayload(report) {
         package: report.package,
         git: report.git,
         releaseGates: report.releaseGates,
+        runtimeApproval: report.runtimeApproval,
         attestation: {
             version: report.attestation.version,
             subject: report.attestation.subject,
@@ -190,7 +193,7 @@ function signReleaseEvidence(report, signingKey, keyHint) {
 export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
     const rootPath = path.resolve(targetPath);
     const security = await buildSecurityAudit(rootPath);
-    const [attestation, corpus, performance, trust, packageMetadata, git] = await Promise.all([
+    const [attestation, corpus, performance, trust, packageMetadata, git, runtimePlan] = await Promise.all([
         buildDoctorAttestation(rootPath, {
             signingKey: options.signingKey,
             signingKeyHint: `env:${options.signingKeyEnv}`,
@@ -204,7 +207,8 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         }),
         buildTrustScore(rootPath, { securityAudit: security }),
         readPackageMetadata(rootPath),
-        readGitMetadata(rootPath)
+        readGitMetadata(rootPath),
+        buildDoctorRuntimePlan(rootPath)
     ]);
     const normalizedPackageMetadata = {
         name: packageMetadata.name ?? attestation.subject.name,
@@ -216,6 +220,10 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         artifactPath: "inline:doctor.release-evidence.attestation"
     });
     const releaseGates = buildReleaseGateReport(git, options);
+    const runtimeApproval = evaluateRuntimeApproval(runtimePlan, {
+        required: options.requireRuntimeApproval ?? false,
+        approvedDigest: options.runtimeApprovalDigest
+    });
     const partialReport = {
         schemaVersion: "1.0.0",
         kind: "doctor.release.evidence",
@@ -228,12 +236,14 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
             corpus: corpus.summary.status,
             performance: performance.status,
             releaseGates: releaseGates.status,
+            runtimeApproval: runtimeApprovalPassed(runtimeApproval) ? "pass" : "fail",
             security: toEvidenceStatus(security.status),
             trust: toEvidenceStatus(trust.status)
         },
         package: normalizedPackageMetadata,
         git,
         releaseGates,
+        runtimeApproval,
         attestation,
         attestationVerification,
         corpus,
@@ -447,6 +457,7 @@ export function renderDoctorReleaseEvidence(report) {
         `Corpus: ${report.summary.corpus.toUpperCase()}`,
         `Performance: ${report.summary.performance.toUpperCase()}`,
         `Release gates: ${report.summary.releaseGates.toUpperCase()}`,
+        `Runtime approval: ${report.summary.runtimeApproval.toUpperCase()} (${report.runtimeApproval.status})`,
         `Security: ${report.summary.security.toUpperCase()} (${report.security.score}/100)`,
         `Trust: ${report.summary.trust.toUpperCase()} (${report.trust.score}/100)`,
         `Git commit: ${report.git.commit ?? "unknown"}`,

package/dist/core/runtime-plan.d.ts

@@ -0,0 +1,51 @@
+import { type SecurityAudit } from "../security/security-audit.js";
+import type { Finding } from "../domain/types.js";
+type RuntimePlanStatus = "pass" | "warn" | "fail";
+type RuntimePlanRiskLevel = "low" | "medium" | "high";
+type RuntimePlanTransport = "stdio" | "http";
+export interface RuntimePlanServer {
+    name: string;
+    transport: RuntimePlanTransport;
+    command: string | null;
+    args: string[];
+    cwd: string | null;
+    url: string | null;
+    probeMethods: string[];
+    riskLevel: RuntimePlanRiskLevel;
+    riskReasons: string[];
+}
+export interface DoctorRuntimePlan {
+    schemaVersion: "1.0.0";
+    kind: "doctor.runtime.plan";
+    generatedAt: string;
+    version: string;
+    targetPath: string;
+    status: RuntimePlanStatus;
+    exitCode: 0 | 1;
+    runtimeExecution: "not_started";
+    digest: string;
+    summary: {
+        serverCount: number;
+        executableServerCount: number;
+        highRiskServerCount: number;
+        findings: SecurityAudit["findingCounts"];
+    };
+    servers: RuntimePlanServer[];
+    findings: Finding[];
+}
+export interface RuntimeApprovalReport {
+    required: boolean;
+    status: "approved" | "missing" | "mismatch" | "not_required";
+    planDigest: string;
+    approvedDigest: string | null;
+    message: string;
+}
+export declare function buildDoctorRuntimePlan(targetPath: string, generatedAt?: string): Promise<DoctorRuntimePlan>;
+export declare function evaluateRuntimeApproval(plan: DoctorRuntimePlan, options: {
+    required: boolean;
+    approvedDigest?: string | null;
+}): RuntimeApprovalReport;
+export declare function runtimeApprovalPassed(approval: RuntimeApprovalReport): boolean;
+export declare function renderDoctorRuntimePlanJson(plan: DoctorRuntimePlan): string;
+export declare function renderDoctorRuntimePlan(plan: DoctorRuntimePlan): string;
+export {};

package/dist/core/runtime-plan.js

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { packageVersion } from "../version.js";
+import { discoverPackage } from "./discover-package.js";
+import { readJsonFile } from "./read-json-file.js";
+import { buildSecurityAudit } from "../security/security-audit.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    if (isPlainObject(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function sha256(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function normalizeCwd(rootPath, cwd) {
+    if (typeof cwd !== "string") {
+        return ".";
+    }
+    const resolvedCwd = path.resolve(rootPath, cwd);
+    const relativeCwd = path.relative(rootPath, resolvedCwd).replace(/\\/g, "/");
+    return relativeCwd.length === 0 ? "." : relativeCwd;
+}
+function buildRisk(serverName, serverConfig, findings) {
+    const matchingFindings = findings.filter((finding) => finding.message.includes(`\`${serverName}\``));
+    const riskReasons = matchingFindings.map((finding) => finding.id);
+    const hasFail = matchingFindings.some((finding) => finding.severity === "fail");
+    const hasWarn = matchingFindings.some((finding) => finding.severity === "warn");
+    if (typeof serverConfig.command === "string") {
+        riskReasons.push("runtime.executes_local_command");
+    }
+    if (typeof serverConfig.url === "string") {
+        riskReasons.push("runtime.connects_remote_server");
+    }
+    return {
+        riskLevel: hasFail ? "high" : hasWarn ? "medium" : "low",
+        riskReasons: [...new Set(riskReasons)]
+    };
+}
+function planDigestPayload(plan) {
+    return {
+        schemaVersion: plan.schemaVersion,
+        kind: "doctor.runtime.plan.digest.v1",
+        version: plan.version,
+        status: plan.status,
+        summary: plan.summary,
+        servers: plan.servers,
+        findings: plan.findings.map((finding) => ({
+            id: finding.id,
+            severity: finding.severity,
+            message: finding.message
+        }))
+    };
+}
+function buildRuntimePlanDigest(plan) {
+    return sha256(stableStringify(planDigestPayload(plan)));
+}
+export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date().toISOString()) {
+    const rootPath = path.resolve(targetPath);
+    const discoveredPackage = await discoverPackage(rootPath);
+    const security = await buildSecurityAudit(rootPath);
+    if (!discoveredPackage?.manifest.mcpServers) {
+        const partialPlan = {
+            schemaVersion: "1.0.0",
+            kind: "doctor.runtime.plan",
+            version: packageVersion,
+            targetPath: rootPath,
+            status: security.status,
+            exitCode: (security.status === "fail" ? 1 : 0),
+            runtimeExecution: "not_started",
+            summary: {
+                serverCount: 0,
+                executableServerCount: 0,
+                highRiskServerCount: 0,
+                findings: security.findingCounts
+            },
+            servers: [],
+            findings: security.findings
+        };
+        return {
+            ...partialPlan,
+            generatedAt,
+            digest: buildRuntimePlanDigest(partialPlan)
+        };
+    }
+    let parsedConfig;
+    try {
+        parsedConfig = await readJsonFile(path.resolve(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers));
+    }
+    catch {
+        parsedConfig = {};
+    }
+    const serverEntries = isPlainObject(parsedConfig) && isPlainObject(parsedConfig.mcpServers)
+        ? Object.entries(parsedConfig.mcpServers)
+        : [];
+    const servers = serverEntries
+        .filter((entry) => isPlainObject(entry[1]))
+        .map(([serverName, serverConfig]) => {
+        const command = typeof serverConfig.command === "string" ? serverConfig.command : null;
+        const url = typeof serverConfig.url === "string" ? serverConfig.url : null;
+        const { riskLevel, riskReasons } = buildRisk(serverName, serverConfig, security.findings);
+        return {
+            name: serverName,
+            transport: command ? "stdio" : "http",
+            command,
+            args: Array.isArray(serverConfig.args)
+                ? serverConfig.args.filter((arg) => typeof arg === "string")
+                : [],
+            cwd: command ? normalizeCwd(discoveredPackage.rootPath, serverConfig.cwd) : null,
+            url,
+            probeMethods: command
+                ? [
+                    "initialize",
+                    "tools/list",
+                    "tools/call:safe-only",
+                    "resources/list",
+                    "resources/read:first-resource-only",
+                    "resources/templates/list",
+                    "prompts/list",
+                    "prompts/get:first-prompt-only"
+                ]
+                : [],
+            riskLevel,
+            riskReasons
+        };
+    });
+    const highRiskServerCount = servers.filter((server) => server.riskLevel === "high").length;
+    const partialPlan = {
+        schemaVersion: "1.0.0",
+        kind: "doctor.runtime.plan",
+        version: packageVersion,
+        targetPath: discoveredPackage.rootPath,
+        status: highRiskServerCount > 0
+            ? "fail"
+            : security.status === "warn"
+                ? "warn"
+                : "pass",
+        exitCode: (highRiskServerCount > 0 ? 1 : 0),
+        runtimeExecution: "not_started",
+        summary: {
+            serverCount: servers.length,
+            executableServerCount: servers.filter((server) => server.command).length,
+            highRiskServerCount,
+            findings: security.findingCounts
+        },
+        servers,
+        findings: security.findings
+    };
+    return {
+        ...partialPlan,
+        generatedAt,
+        digest: buildRuntimePlanDigest(partialPlan)
+    };
+}
+export function evaluateRuntimeApproval(plan, options) {
+    if (!options.required) {
+        return {
+            required: false,
+            status: "not_required",
+            planDigest: plan.digest,
+            approvedDigest: options.approvedDigest ?? null,
+            message: "Runtime approval was not required for this run."
+        };
+    }
+    if (!options.approvedDigest) {
+        return {
+            required: true,
+            status: "missing",
+            planDigest: plan.digest,
+            approvedDigest: null,
+            message: "Runtime approval was required, but no approved plan digest was provided."
+        };
+    }
+    if (options.approvedDigest !== plan.digest) {
+        return {
+            required: true,
+            status: "mismatch",
+            planDigest: plan.digest,
+            approvedDigest: options.approvedDigest,
+            message: "Runtime approval digest does not match the current runtime plan."
+        };
+    }
+    return {
+        required: true,
+        status: "approved",
+        planDigest: plan.digest,
+        approvedDigest: options.approvedDigest,
+        message: "Runtime approval digest matches the current runtime plan."
+    };
+}
+export function runtimeApprovalPassed(approval) {
+    return approval.status === "approved" || approval.status === "not_required";
+}
+export function renderDoctorRuntimePlanJson(plan) {
+    return JSON.stringify(plan, null, 2);
+}
+export function renderDoctorRuntimePlan(plan) {
+    const lines = [
+        "Doctor Runtime Plan",
+        "===================",
+        `Target: ${plan.targetPath}`,
+        `Status: ${plan.status.toUpperCase()}`,
+        `Runtime execution: ${plan.runtimeExecution}`,
+        `Digest: ${plan.digest}`,
+        `Servers: ${plan.summary.serverCount}`,
+        `Executable servers: ${plan.summary.executableServerCount}`,
+        `High-risk servers: ${plan.summary.highRiskServerCount}`
+    ];
+    if (plan.servers.length === 0) {
+        lines.push("", "No MCP runtime servers found.");
+        return lines.join("\n");
+    }
+    lines.push("", "Servers", "-------");
+    for (const server of plan.servers) {
+        lines.push(`${server.riskLevel.toUpperCase()} ${server.name}`);
+        lines.push(`  Transport: ${server.transport}`);
+        lines.push(`  Command: ${server.command ?? server.url ?? "not executable by runtime probe"}`);
+        lines.push(`  Cwd: ${server.cwd ?? "n/a"}`);
+        lines.push(`  Probes: ${server.probeMethods.length > 0 ? server.probeMethods.join(", ") : "none"}`);
+        lines.push(`  Risk reasons: ${server.riskReasons.length > 0 ? server.riskReasons.join(", ") : "none"}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutp
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport, type BuildDoctorValidationCorpusOptions, type DoctorValidationCorpusReport, type ValidationCorpusCaseDefinition, type ValidationCorpusCaseResult } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis, type PackageAnalysis, type PackageAnalysisOptions, type PackageAnalysisStage, type PackageAnalysisTiming } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";
+export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanJson, runtimeApprovalPassed, type DoctorRuntimePlan, type RuntimeApprovalReport, type RuntimePlanServer } from "./core/runtime-plan.js";
 export { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence, type BuildDoctorReleaseEvidenceOptions, type DoctorReleaseEvidenceAssetReport, type DoctorReleaseEvidenceGitMetadata, type DoctorReleaseEvidencePackageMetadata, type DoctorReleaseEvidenceReport, type DoctorReleaseEvidenceVerificationReport } from "./core/release-evidence.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson, type BuildDoctorNpmPackageReportOptions, type DoctorNpmPackageReport } from "./core/npm-package-doctor.js";
 export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson, type BuildDoctorRiskDiffReportOptions, type DoctorRiskDiffReport, type RiskDiffFinding, type RiskFindingCategory } from "./core/risk-diff.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutp
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
+export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
 export { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence } from "./core/release-evidence.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";

package/dist/run-cli.js

@@ -20,6 +20,7 @@ import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
+import { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
 import { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence } from "./core/release-evidence.js";
 import { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 import { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
@@ -70,7 +71,7 @@ const defaultIo = {
     }
 };
 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] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--allow-dirty] [--allow-untagged]|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 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] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|runtime-plan <path>|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--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 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");
 }
 const performanceStageNames = new Set([
     "validation",
@@ -351,6 +352,32 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStdout(renderedReport);
             return report.exitCode;
         }
+        if (maybePath === "runtime-plan") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : null;
+            const runtimePlanFlags = targetPath ? remainingArgs.slice(1) : remainingArgs;
+            const jsonOutput = runtimePlanFlags.includes("--json");
+            const outputIndex = runtimePlanFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : runtimePlanFlags[outputIndex + 1];
+            if (!targetPath) {
+                io.writeStderr("Missing target path for runtime plan.");
+                return 2;
+            }
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const plan = await buildDoctorRuntimePlan(targetPath);
+            const renderedPlan = jsonOutput
+                ? renderDoctorRuntimePlanJson(plan)
+                : renderDoctorRuntimePlan(plan);
+            if (outputPath) {
+                await writeFile(outputPath, renderDoctorRuntimePlanJson(plan), "utf8");
+            }
+            io.writeStdout(renderedPlan);
+            return plan.exitCode;
+        }
         if (maybePath === "release-evidence") {
             if (remainingArgs[0] === "asset") {
                 const targetPath = remainingArgs[1] && !remainingArgs[1].startsWith("--")
@@ -368,6 +395,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 const signKeyEnv = signKeyEnvIndex === -1 ? null : assetFlags[signKeyEnvIndex + 1];
                 const allowDirty = assetFlags.includes("--allow-dirty");
                 const allowUntagged = assetFlags.includes("--allow-untagged");
+                const requireRuntimeApproval = assetFlags.includes("--require-runtime-approval");
+                const runtimeApprovalDigestIndex = assetFlags.indexOf("--runtime-approval-digest");
+                const runtimeApprovalDigest = runtimeApprovalDigestIndex === -1
+                    ? null
+                    : assetFlags[runtimeApprovalDigestIndex + 1];
                 if (!targetPath) {
                     io.writeStderr("Missing target path for release evidence asset.");
                     return 2;
@@ -400,6 +432,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     io.writeStderr("Missing environment variable name after --sign-key-env.");
                     return 2;
                 }
+                if (runtimeApprovalDigestIndex !== -1 &&
+                    (!runtimeApprovalDigest || runtimeApprovalDigest.startsWith("--"))) {
+                    io.writeStderr("Missing digest after --runtime-approval-digest.");
+                    return 2;
+                }
                 const signingKey = terminalContext.env[signKeyEnv];
                 if (!signingKey) {
                     io.writeStderr(`Environment variable ${signKeyEnv} is not set.`);
@@ -416,6 +453,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     signingKeyEnv: signKeyEnv,
                     allowDirty,
                     allowUntagged,
+                    requireRuntimeApproval,
+                    runtimeApprovalDigest,
                     environment: {
                         env: terminalContext.env,
                         platform: terminalContext.platform
@@ -516,6 +555,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const signKeyEnv = signKeyEnvIndex === -1 ? null : evidenceFlags[signKeyEnvIndex + 1];
             const allowDirty = evidenceFlags.includes("--allow-dirty");
             const allowUntagged = evidenceFlags.includes("--allow-untagged");
+            const requireRuntimeApproval = evidenceFlags.includes("--require-runtime-approval");
+            const runtimeApprovalDigestIndex = evidenceFlags.indexOf("--runtime-approval-digest");
+            const runtimeApprovalDigest = runtimeApprovalDigestIndex === -1
+                ? null
+                : evidenceFlags[runtimeApprovalDigestIndex + 1];
             if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
                 io.writeStderr("Missing path after --output.");
                 return 2;
@@ -532,6 +576,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr("Missing environment variable name after --sign-key-env.");
                 return 2;
             }
+            if (runtimeApprovalDigestIndex !== -1 &&
+                (!runtimeApprovalDigest || runtimeApprovalDigest.startsWith("--"))) {
+                io.writeStderr("Missing digest after --runtime-approval-digest.");
+                return 2;
+            }
             const signingKey = terminalContext.env[signKeyEnv];
             if (!signingKey) {
                 io.writeStderr(`Environment variable ${signKeyEnv} is not set.`);
@@ -547,6 +596,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 signingKeyEnv: signKeyEnv,
                 allowDirty,
                 allowUntagged,
+                requireRuntimeApproval,
+                runtimeApprovalDigest,
                 environment: {
                     env: terminalContext.env,
                     platform: terminalContext.platform
@@ -1328,6 +1379,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const policy = parsePolicyPack(policyName);
     const historyIndex = normalizedFlags.indexOf("--history");
     const historyPath = historyIndex === -1 ? null : normalizedFlags[historyIndex + 1];
+    const requireRuntimeApproval = normalizedFlags.includes("--require-runtime-approval");
+    const runtimeApprovalDigestIndex = normalizedFlags.indexOf("--runtime-approval-digest");
+    const runtimeApprovalDigest = runtimeApprovalDigestIndex === -1
+        ? null
+        : normalizedFlags[runtimeApprovalDigestIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
         io.writeStderr("Missing path after --output.");
         return 2;
@@ -1356,6 +1412,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Missing path after --history.");
         return 2;
     }
+    if (runtimeApprovalDigestIndex !== -1 &&
+        (!runtimeApprovalDigest || runtimeApprovalDigest.startsWith("--"))) {
+        io.writeStderr("Missing digest after --runtime-approval-digest.");
+        return 2;
+    }
     if (checkInstalled && (badgeJsonOutput || badgeMarkdownOutput)) {
         io.writeStderr("Badge output requires a single package target.");
         return 2;
@@ -1367,6 +1428,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const effectiveRuntimeProbeEnabled = runtimeProbeEnabled ||
         checkProfile === "publish" ||
         policyEnablesRuntime(policy);
+    if (requireRuntimeApproval && !effectiveRuntimeProbeEnabled) {
+        io.writeStderr("Runtime approval requires runtime probing. Add --runtime, --profile publish, or a runtime-enabled policy.");
+        return 2;
+    }
+    if (checkInstalled && requireRuntimeApproval) {
+        io.writeStderr("Runtime approval gating requires a single package target, not --installed.");
+        return 2;
+    }
     const outputPolicy = determineOutputPolicy({
         jsonOutput: jsonOutput || badgeJsonOutput,
         markdownOutput: markdownOutput || badgeMarkdownOutput,
@@ -1378,6 +1447,17 @@ export async function runCli(args, io = defaultIo, options = {}) {
         env: terminalContext.env
     });
     const runCheckImpl = options.runCheckImpl ?? runCheck;
+    if (!checkInstalled && effectiveRuntimeProbeEnabled && requireRuntimeApproval) {
+        const runtimePlan = await buildDoctorRuntimePlan(targetPath);
+        const approval = evaluateRuntimeApproval(runtimePlan, {
+            required: true,
+            approvedDigest: runtimeApprovalDigest
+        });
+        if (!runtimeApprovalPassed(approval)) {
+            io.writeStderr(`${approval.message}\nCurrent runtime plan digest: ${runtimePlan.digest}`);
+            return 1;
+        }
+    }
     if (checkInstalled) {
         const installedPlugins = filterInstalledPlugins(await discoverInstalledPlugins({ env: terminalContext.env }), installedFilter);
         if (installedPlugins.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",