codex-plugin-doctor 1.46.1 → 1.47.0

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

@@ -12,6 +12,9 @@ export function buildJsonReport(result, options) {
             ...(result.runtimeScorecard
                 ? { runtimeScorecard: result.runtimeScorecard }
                 : {}),
+            ...(result.runtimeExecution
+                ? { runtimeExecution: result.runtimeExecution }
+                : {}),
             findingCounts: {
                 fail: failCount,
                 warn: warnCount,

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

@@ -23,6 +23,9 @@ export function buildMarkdownReport(result, options) {
     if (result.baselineSummary) {
         lines.push(`| Baseline New | ${result.baselineSummary.new} |`, `| Baseline Matched | ${result.baselineSummary.matched} |`, `| Baseline Resolved | ${result.baselineSummary.resolved} |`);
     }
+    if (result.runtimeExecution) {
+        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) {
         lines.push("", result.baselineSummary ? "No new findings." : "No findings.");
         return lines.join("\n");

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

@@ -42,6 +42,9 @@ export function renderTextReport(result, options = {}) {
     if (result.baselineSummary) {
         lines.push(`Baseline: ${result.baselineSummary.new} new, ${result.baselineSummary.matched} matched, ${result.baselineSummary.resolved} resolved`);
     }
+    if (result.runtimeExecution) {
+        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", "----------------");

package/dist/run-cli.js

@@ -20,6 +20,7 @@ import { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBu
 import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson, renderDoctorAttestationVerification, renderDoctorAttestationVerificationJson, verifyDoctorAttestation } from "./core/attestation.js";
 import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
+import { buildExternalValidationCorpusReport, ExternalCorpusManifestError } from "./core/external-validation-corpus.js";
 import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 import { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
 import { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./core/runtime-policy.js";
@@ -81,8 +82,24 @@ const defaultIo = {
         }
     }
 };
+class CliUsageError extends Error {
+}
+function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
+    const index = flags.indexOf("--sandbox");
+    if (index === -1) {
+        return null;
+    }
+    const value = flags[index + 1];
+    if (value !== "docker") {
+        throw new CliUsageError("Expected --sandbox docker.");
+    }
+    if (options.requireRuntime !== false && !flags.includes("--runtime")) {
+        throw new CliUsageError("--sandbox docker requires --runtime.");
+    }
+    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] [--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|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--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 [--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]\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> [--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>]|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("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>");
 }
@@ -805,6 +822,17 @@ function parseSelectedFixActionIndexes(answer, actionCount) {
 }
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
+    const runtimeSandboxSupported = (command === "check" &&
+        !args.includes("--installed") &&
+        !args.includes("--changed-since")) ||
+        (command === "release" && maybePath === "check") ||
+        (command === "doctor" &&
+            (["runtime-plan", "runtime-policy"].includes(maybePath ?? "") ||
+                (maybePath === "release-evidence" && remainingArgs[0] !== "verify")));
+    if (args.includes("--sandbox") && !runtimeSandboxSupported) {
+        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, and release-evidence.");
+        return 2;
+    }
     if (command === "--version" || command === "-v" || command === "version") {
         io.writeStdout(packageVersion);
         return 0;
@@ -933,6 +961,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const markdownOutput = runtimePlanFlags.includes("--markdown");
             const outputIndex = runtimePlanFlags.indexOf("--output");
             const outputPath = outputIndex === -1 ? null : runtimePlanFlags[outputIndex + 1];
+            let runtimeSandbox;
+            try {
+                runtimeSandbox = parseRuntimeSandbox(runtimePlanFlags, { requireRuntime: false });
+            }
+            catch (error) {
+                io.writeStderr(error.message);
+                return 2;
+            }
             if (!targetPath) {
                 io.writeStderr("Missing target path for runtime plan.");
                 return 2;
@@ -945,7 +981,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr("Use either --json or --markdown, not both.");
                 return 2;
             }
-            const plan = await buildDoctorRuntimePlan(targetPath);
+            const plan = await buildDoctorRuntimePlan(targetPath, new Date().toISOString(), runtimeSandbox ? { sandbox: runtimeSandbox } : {});
             const renderedPlan = jsonOutput
                 ? renderDoctorRuntimePlanJson(plan)
                 : markdownOutput
@@ -965,6 +1001,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const jsonOutput = runtimePolicyFlags.includes("--json");
             const outputIndex = runtimePolicyFlags.indexOf("--output");
             const outputPath = outputIndex === -1 ? null : runtimePolicyFlags[outputIndex + 1];
+            let runtimeSandbox;
+            try {
+                runtimeSandbox = parseRuntimeSandbox(runtimePolicyFlags, { requireRuntime: false });
+            }
+            catch (error) {
+                io.writeStderr(error.message);
+                return 2;
+            }
             if (!targetPath) {
                 io.writeStderr("Missing target path for runtime policy.");
                 return 2;
@@ -973,7 +1017,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr("Missing path after --output.");
                 return 2;
             }
-            const report = await buildDoctorRuntimePolicyReport(targetPath);
+            const report = await buildDoctorRuntimePolicyReport(targetPath, new Date().toISOString(), runtimeSandbox ? { sandbox: runtimeSandbox } : {});
             const renderedReport = jsonOutput
                 ? renderDoctorRuntimePolicyJson(report)
                 : renderDoctorRuntimePolicy(report);
@@ -1138,6 +1182,15 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 const runtimeApprovalDigest = runtimeApprovalDigestIndex === -1
                     ? null
                     : assetFlags[runtimeApprovalDigestIndex + 1];
+                const runtime = assetFlags.includes("--runtime");
+                let runtimeSandbox;
+                try {
+                    runtimeSandbox = parseRuntimeSandbox(assetFlags);
+                }
+                catch (error) {
+                    io.writeStderr(error.message);
+                    return 2;
+                }
                 if (!targetPath) {
                     io.writeStderr("Missing target path for release evidence asset.");
                     return 2;
@@ -1193,13 +1246,13 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     allowUntagged,
                     requireRuntimeApproval,
                     runtimeApprovalDigest,
+                    runtime,
+                    ...(runtimeSandbox ? { sandbox: runtimeSandbox } : {}),
                     environment: {
                         env: terminalContext.env,
                         platform: terminalContext.platform
                     },
-                    runCheck: options.runCheckImpl
-                        ? (pathToCheck) => options.runCheckImpl(pathToCheck)
-                        : undefined,
+                    runCheck: options.runCheckImpl ?? runCheck,
                     performanceThresholds: parsedThresholds.thresholds
                 });
                 await writeFile(resolvedOutputPath, renderDoctorReleaseEvidenceJson(evidence), "utf8");
@@ -1298,6 +1351,15 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const runtimeApprovalDigest = runtimeApprovalDigestIndex === -1
                 ? null
                 : evidenceFlags[runtimeApprovalDigestIndex + 1];
+            const runtime = evidenceFlags.includes("--runtime");
+            let runtimeSandbox;
+            try {
+                runtimeSandbox = parseRuntimeSandbox(evidenceFlags);
+            }
+            catch (error) {
+                io.writeStderr(error.message);
+                return 2;
+            }
             if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
                 io.writeStderr("Missing path after --output.");
                 return 2;
@@ -1336,13 +1398,13 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 allowUntagged,
                 requireRuntimeApproval,
                 runtimeApprovalDigest,
+                runtime,
+                ...(runtimeSandbox ? { sandbox: runtimeSandbox } : {}),
                 environment: {
                     env: terminalContext.env,
                     platform: terminalContext.platform
                 },
-                runCheck: options.runCheckImpl
-                    ? (pathToCheck) => options.runCheckImpl(pathToCheck)
-                    : undefined,
+                runCheck: options.runCheckImpl ?? runCheck,
                 performanceThresholds: parsedThresholds.thresholds
             });
             const reportJson = renderDoctorReleaseEvidenceJson(report);
@@ -1357,16 +1419,39 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const jsonOutput = remainingArgs.includes("--json");
             const outputIndex = remainingArgs.indexOf("--output");
             const outputPath = outputIndex === -1 ? null : remainingArgs[outputIndex + 1];
+            const manifestIndex = remainingArgs.indexOf("--manifest");
+            const manifestPath = manifestIndex === -1 ? null : remainingArgs[manifestIndex + 1];
             if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
                 io.writeStderr("Missing path after --output.");
                 return 2;
             }
-            const report = await buildDoctorValidationCorpusReport({
-                environment: {
-                    env: terminalContext.env,
-                    platform: terminalContext.platform
+            if (manifestIndex !== -1 && (!manifestPath || manifestPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --manifest.");
+                return 2;
+            }
+            let report;
+            try {
+                report = manifestPath
+                    ? await buildExternalValidationCorpusReport(manifestPath, {
+                        environment: {
+                            env: terminalContext.env,
+                            platform: terminalContext.platform
+                        }
+                    })
+                    : await buildDoctorValidationCorpusReport({
+                        environment: {
+                            env: terminalContext.env,
+                            platform: terminalContext.platform
+                        }
+                    });
+            }
+            catch (error) {
+                if (error instanceof ExternalCorpusManifestError) {
+                    io.writeStderr(error.message);
+                    return 2;
                 }
-            });
+                throw error;
+            }
             const reportJson = renderDoctorValidationCorpusJson(report);
             if (outputPath) {
                 await writeFile(outputPath, reportJson, "utf8");
@@ -2262,6 +2347,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
             : remainingArgs.slice(1);
         const jsonOutput = releaseFlags.includes("--json");
         const runtimeProbeEnabled = releaseFlags.includes("--runtime");
+        let runtimeSandbox;
+        try {
+            runtimeSandbox = parseRuntimeSandbox(releaseFlags);
+        }
+        catch (error) {
+            io.writeStderr(error.message);
+            return 2;
+        }
         const requireRuntimeApproval = releaseFlags.includes("--require-runtime-approval");
         const runtimeApprovalDigestIndex = releaseFlags.indexOf("--runtime-approval-digest");
         const runtimeApprovalDigest = runtimeApprovalDigestIndex === -1
@@ -2277,7 +2370,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
             return 2;
         }
         if (requireRuntimeApproval) {
-            const runtimePlan = await buildDoctorRuntimePlan(targetPath);
+            const runtimePlan = await buildDoctorRuntimePlan(targetPath, new Date().toISOString(), runtimeSandbox ? { sandbox: runtimeSandbox } : {});
             const approval = evaluateRuntimeApproval(runtimePlan, {
                 required: true,
                 approvedDigest: runtimeApprovalDigest
@@ -2291,6 +2384,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
             env: terminalContext.env,
             platform: terminalContext.platform,
             runtime: runtimeProbeEnabled,
+            ...(runtimeSandbox ? { runtimeSandbox } : {}),
             runCheck: options.runCheckImpl
         });
         const output = jsonOutput
@@ -2331,6 +2425,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
         : maybePath && maybePath.startsWith("--")
             ? [maybePath, ...remainingArgs]
             : remainingArgs;
+    let runtimeSandbox;
+    try {
+        runtimeSandbox = parseRuntimeSandbox(normalizedFlags);
+    }
+    catch (error) {
+        io.writeStderr(error.message);
+        return 2;
+    }
     const jsonOutput = normalizedFlags.includes("--json");
     const markdownOutput = normalizedFlags.includes("--markdown");
     const badgeJsonOutput = normalizedFlags.includes("--badge-json");
@@ -2458,7 +2560,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
     });
     const runCheckImpl = options.runCheckImpl ?? runCheck;
     if (!checkInstalled && effectiveRuntimeProbeEnabled && requireRuntimeApproval) {
-        const runtimePlan = await buildDoctorRuntimePlan(targetPath);
+        const runtimePlan = await buildDoctorRuntimePlan(targetPath, new Date().toISOString(), runtimeSandbox ? { sandbox: runtimeSandbox } : {});
         const approval = evaluateRuntimeApproval(runtimePlan, {
             required: true,
             approvedDigest: runtimeApprovalDigest
@@ -2580,9 +2682,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const doctorConfig = applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy);
     const configuredResult = applyDoctorConfig(await runCheckImpl(targetPath, {
         runtime: effectiveRuntimeProbeEnabled,
-        runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
-            ? (line) => io.writeStderr(line)
-            : undefined
+        ...(runtimeSandbox ? { runtimeSandbox } : {}),
+        ...(effectiveRuntimeProbeEnabled && verboseRuntime
+            ? { runtimeTranscript: (line) => io.writeStderr(line) }
+            : {})
     }), doctorConfig);
     const result = baseline
         ? applyValidationBaseline(configuredResult, baseline, {

package/package.json

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