codex-plugin-doctor 1.46.0 → 1.47.0

package/dist/core/runtime-sandbox.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+export class RuntimeSandboxError extends Error {
+}
+export const DOCKER_RUNTIME_STARTUP_TIMEOUT_MS = 60_000;
+export const DOCKER_RUNTIME_IMAGE = "node:22-bookworm-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3";
+export function buildRuntimeLaunch(input) {
+    if (input.sandbox !== "docker") {
+        throw new RuntimeSandboxError("Unsupported sandbox mode.");
+    }
+    if (!/^(node|node\.exe)$/i.test(path.basename(input.command))) {
+        throw new RuntimeSandboxError("Docker sandbox supports Node.js stdio commands only.");
+    }
+    const relativeCwd = path.relative(input.packageRoot, input.cwd);
+    if (relativeCwd === ".." ||
+        relativeCwd.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeCwd)) {
+        throw new RuntimeSandboxError("Runtime cwd escapes the package root.");
+    }
+    if (input.packageRoot.includes(",")) {
+        throw new RuntimeSandboxError("Docker sandbox does not support commas in package paths.");
+    }
+    const workdir = relativeCwd
+        ? `/workspace/${relativeCwd.split(path.sep).join("/")}`
+        : "/workspace";
+    return {
+        command: "docker",
+        args: [
+            "run",
+            "--rm",
+            "-i",
+            "--init",
+            "--name",
+            input.containerName,
+            "--network",
+            "none",
+            "--read-only",
+            "--cap-drop",
+            "ALL",
+            "--security-opt",
+            "no-new-privileges",
+            "--user",
+            "65532:65532",
+            "--pids-limit",
+            "64",
+            "--memory",
+            "256m",
+            "--cpus",
+            "1",
+            "--tmpfs",
+            "/tmp:rw,noexec,nosuid,size=16m",
+            "--mount",
+            `type=bind,source=${input.packageRoot},target=/workspace,readonly`,
+            "--workdir",
+            workdir,
+            DOCKER_RUNTIME_IMAGE,
+            "node",
+            ...input.args
+        ],
+        cwd: input.packageRoot,
+        containerName: input.containerName,
+        evidence: {
+            backend: "docker",
+            image: DOCKER_RUNTIME_IMAGE,
+            network: "none",
+            packageMount: "read_only"
+        }
+    };
+}

package/dist/core/validate-plugin.js

@@ -404,18 +404,23 @@ export async function validatePlugin(targetPath, options = {}) {
             findings: withFindingFingerprints([await buildMissingManifestFailure(rootPath)], rootPath)
         };
     }
-    const runtimeResult = options.runtime
+    const staticFindings = [
+        ...validateRequiredManifestFields(discoveredPackage),
+        ...(await validateSkillsDirectory(discoveredPackage)),
+        ...(await validateSkillDefinitions(discoveredPackage)),
+        ...(await validateMcpConfig(discoveredPackage))
+    ];
+    const staticFailed = staticFindings.some((finding) => finding.severity === "fail");
+    const runtimeResult = options.runtime && !staticFailed
         ? await probeRuntime(discoveredPackage, {
             startupTimeoutMs: options.runtimeStartupTimeoutMs,
+            sandbox: options.runtimeSandbox,
             transcript: options.runtimeTranscript
         })
         : null;
     const findings = [
-        ...validateRequiredManifestFields(discoveredPackage),
-        ...(await validateSkillsDirectory(discoveredPackage)),
-        ...(await validateSkillDefinitions(discoveredPackage)),
-        ...(await validateMcpConfig(discoveredPackage)),
-        ...(runtimeResult ? runtimeResult.findings : [])
+        ...staticFindings,
+        ...(runtimeResult?.findings ?? [])
     ];
     const fingerprintedFindings = withFindingFingerprints(findings, discoveredPackage.rootPath);
     const hasFailures = fingerprintedFindings.some((finding) => finding.severity === "fail");
@@ -426,7 +431,10 @@ export async function validatePlugin(targetPath, options = {}) {
             status: "pass",
             exitCode: 0,
             findings: [],
-            ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {})
+            ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {}),
+            ...(runtimeResult?.execution
+                ? { runtimeExecution: runtimeResult.execution }
+                : {})
         };
     }
     return {
@@ -434,6 +442,9 @@ export async function validatePlugin(targetPath, options = {}) {
         status: hasFailures ? "fail" : "warn",
         exitCode: hasFailures ? 1 : 0,
         findings: fingerprintedFindings,
-        ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {})
+        ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {}),
+        ...(runtimeResult?.execution
+            ? { runtimeExecution: runtimeResult.execution }
+            : {})
     };
 }

package/dist/core/validation-corpus.d.ts

@@ -1,4 +1,5 @@
 import { type PackageAnalysisOptions } from "./package-analysis.js";
+import type { ExternalValidationCorpusReport } from "./external-validation-corpus.js";
 type ValidationStatus = "pass" | "warn" | "fail";
 export interface ValidationCorpusCaseDefinition {
     id: string;
@@ -36,6 +37,7 @@ export interface ValidationCorpusCaseResult {
 export interface DoctorValidationCorpusReport {
     schemaVersion: "1.0.0";
     kind: "doctor.validation.corpus";
+    corpusType?: "bundled";
     generatedAt: string;
     version: string;
     summary: {
@@ -51,8 +53,8 @@ export interface BuildDoctorValidationCorpusOptions {
     environment?: PackageAnalysisOptions["environment"];
 }
 export declare function buildDoctorValidationCorpusReport(options?: BuildDoctorValidationCorpusOptions): Promise<DoctorValidationCorpusReport>;
-export declare function renderDoctorValidationCorpusJson(report: DoctorValidationCorpusReport): string;
-export declare function renderDoctorValidationCorpusReport(report: DoctorValidationCorpusReport, options?: {
+export declare function renderDoctorValidationCorpusJson(report: DoctorValidationCorpusReport | ExternalValidationCorpusReport): string;
+export declare function renderDoctorValidationCorpusReport(report: DoctorValidationCorpusReport | ExternalValidationCorpusReport, options?: {
     outputPath?: string | null;
 }): string;
 export {};

package/dist/core/validation-corpus.js

@@ -163,8 +163,19 @@ export function renderDoctorValidationCorpusReport(report, options = {}) {
     }
     lines.push("", "Cases", "-----");
     for (const caseResult of report.cases) {
+        const actual = caseResult.actual;
+        let status;
+        let findingCount;
+        if ("status" in actual) {
+            status = actual.status;
+            findingCount = actual.findings.length;
+        }
+        else {
+            status = actual.validationStatus;
+            findingCount = actual.findingIds.length;
+        }
         lines.push(`${caseResult.id}: ${caseResult.expectationMatched ? "PASS" : "FAIL"} ` +
-            `(${caseResult.actual.validationStatus.toUpperCase()}, ${caseResult.actual.findingIds.length} findings)`);
+            `(${status.toUpperCase()}, ${findingCount} findings)`);
     }
     return lines.join("\n");
 }

package/dist/domain/types.d.ts

@@ -30,6 +30,7 @@ export interface CheckResult {
     suppressedFindings?: SuppressedFinding[];
     suppressionSummary?: SuppressionSummary;
     runtimeScorecard?: RuntimeScorecard;
+    runtimeExecution?: RuntimeExecutionEvidence;
     baselinedFindings?: Finding[];
     baselineSummary?: BaselineSummary;
 }
@@ -42,6 +43,7 @@ export interface CheckOptions {
     runtime?: boolean;
     runtimeTranscript?: (line: string) => void;
     runtimeStartupTimeoutMs?: number;
+    runtimeSandbox?: RuntimeSandboxMode;
 }
 export interface PluginManifest {
     name?: string;
@@ -61,6 +63,7 @@ export interface JsonReportSummary {
     exitCode: 0 | 1;
     runtimeProbeEnabled: boolean;
     runtimeScorecard?: RuntimeScorecard;
+    runtimeExecution?: RuntimeExecutionEvidence;
     findingCounts: {
         fail: number;
         warn: number;
@@ -91,4 +94,12 @@ export interface RuntimeScorecard {
 export interface RuntimeProbeResult {
     findings: Finding[];
     scorecard: RuntimeScorecard;
+    execution?: RuntimeExecutionEvidence;
+}
+export type RuntimeSandboxMode = "docker";
+export interface RuntimeExecutionEvidence {
+    backend: "native" | "docker";
+    image: string | null;
+    network: "host" | "none";
+    packageMount: "host" | "read_only";
 }

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson, ty
 export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson, type DoctorRecommendationAction, type DoctorRecommendationsReport } from "./core/doctor-recommendations.js";
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson, type DoctorExportBundle } from "./core/doctor-export-bundle.js";
 export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson, renderDoctorAttestationVerification, renderDoctorAttestationVerificationJson, verifyDoctorAttestation, type DoctorAttestation, type DoctorAttestationVerificationCheck, type DoctorAttestationVerificationReport, type Digest, type PackageFingerprint } from "./core/attestation.js";
+export { buildExternalValidationCorpusReport, ExternalCorpusManifestError, loadExternalCorpusManifest, type BuildExternalValidationCorpusOptions, type ExternalCorpusCaseResult, type ExternalCorpusClassificationCounts, type ExternalCorpusFindingReview, type ExternalCorpusManifest, type ExternalCorpusMode, type ExternalCorpusProfile, type ExternalCorpusSourceType, type ExternalValidationCorpusReport, type FindingReviewClassification } from "./core/external-validation-corpus.js";
 export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson, type DoctorOutputContract, type OutputContractRule, type OutputContractSchema } from "./core/output-contract.js";
 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";
@@ -29,5 +30,5 @@ export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepA
 export { initGitHooks, removeGitHooks, type InitGitHooksResult, type RemoveGitHooksResult } from "./core/init-git-hooks.js";
 export { generateCompletion, type CompletionShell } from "./core/shell-completion.js";
 export { validateConfigFile, renderConfigValidation, renderConfigValidationJson, type ConfigValidationFinding, type ConfigValidationReport } from "./core/config-validate.js";
-export { buildReleaseCheck, renderReleaseCheck, renderReleaseCheckJson, type ReleaseCheckReport } from "./core/release-check.js";
+export { assertReleaseMetadataSync, buildReleaseCheck, buildReleaseMetadataCheck, renderReleaseCheck, renderReleaseCheckJson, type BuildReleaseCheckOptions, type ReleaseMetadataCheck, type ReleaseCheckReport } from "./core/release-check.js";
 export declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -10,6 +10,7 @@ export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } f
 export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson } from "./core/doctor-recommendations.js";
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
 export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson, renderDoctorAttestationVerification, renderDoctorAttestationVerificationJson, verifyDoctorAttestation } from "./core/attestation.js";
+export { buildExternalValidationCorpusReport, ExternalCorpusManifestError, loadExternalCorpusManifest } from "./core/external-validation-corpus.js";
 export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
@@ -29,7 +30,7 @@ export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepA
 export { initGitHooks, removeGitHooks } from "./core/init-git-hooks.js";
 export { generateCompletion } from "./core/shell-completion.js";
 export { validateConfigFile, renderConfigValidation, renderConfigValidationJson } from "./core/config-validate.js";
-export { buildReleaseCheck, renderReleaseCheck, renderReleaseCheckJson } from "./core/release-check.js";
+export { assertReleaseMetadataSync, buildReleaseCheck, buildReleaseMetadataCheck, renderReleaseCheck, renderReleaseCheckJson } from "./core/release-check.js";
 export async function runCheck(targetPath, options = {}) {
     return validatePlugin(targetPath, options);
 }

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");
@@ -2253,7 +2338,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
     if (command === "release") {
         const subCommand = maybePath;
         if (subCommand !== "check") {
-            io.writeStderr("Usage: codex-plugin-doctor release check <path> [--json]");
+            io.writeStderr("Usage: codex-plugin-doctor release check <path> [--json] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>]");
             return 2;
         }
         const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--") ? remainingArgs[0] : ".";
@@ -2261,9 +2346,46 @@ export async function runCli(args, io = defaultIo, options = {}) {
             ? remainingArgs
             : 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
+            ? null
+            : releaseFlags[runtimeApprovalDigestIndex + 1];
+        if (requireRuntimeApproval && !runtimeProbeEnabled) {
+            io.writeStderr("Runtime approval requires --runtime.");
+            return 2;
+        }
+        if (runtimeApprovalDigestIndex !== -1 &&
+            (!runtimeApprovalDigest || runtimeApprovalDigest.startsWith("--"))) {
+            io.writeStderr("Missing digest after --runtime-approval-digest.");
+            return 2;
+        }
+        if (requireRuntimeApproval) {
+            const runtimePlan = await buildDoctorRuntimePlan(targetPath, new Date().toISOString(), runtimeSandbox ? { sandbox: runtimeSandbox } : {});
+            const approval = evaluateRuntimeApproval(runtimePlan, {
+                required: true,
+                approvedDigest: runtimeApprovalDigest
+            });
+            if (!runtimeApprovalPassed(approval)) {
+                io.writeStderr(`${approval.message}\nCurrent runtime plan digest: ${runtimePlan.digest}`);
+                return 1;
+            }
+        }
         const report = await buildReleaseCheck(targetPath, {
             env: terminalContext.env,
-            platform: terminalContext.platform
+            platform: terminalContext.platform,
+            runtime: runtimeProbeEnabled,
+            ...(runtimeSandbox ? { runtimeSandbox } : {}),
+            runCheck: options.runCheckImpl
         });
         const output = jsonOutput
             ? renderReleaseCheckJson(report)
@@ -2303,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");
@@ -2430,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
@@ -2552,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.0",
+  "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",