codex-plugin-doctor 1.46.1 → 1.47.0

package/dist/core/release-evidence.js

@@ -10,6 +10,7 @@ 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 { validatePlugin } from "./validate-plugin.js";
 import { packageVersion } from "../version.js";
 const execFileAsync = promisify(execFile);
 function isPlainObject(value) {
@@ -152,6 +153,7 @@ function buildReleaseEvidenceSigningPayload(report) {
         git: report.git,
         releaseGates: report.releaseGates,
         runtimeApproval: report.runtimeApproval,
+        ...(report.execution ? { execution: report.execution } : {}),
         attestation: {
             version: report.attestation.version,
             subject: report.attestation.subject,
@@ -193,6 +195,13 @@ function signReleaseEvidence(report, signingKey, keyHint) {
 export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
     const rootPath = path.resolve(targetPath);
     const security = await buildSecurityAudit(rootPath);
+    const runCheck = options.runCheck ?? validatePlugin;
+    const checkOptions = options.runtime
+        ? {
+            runtime: true,
+            ...(options.sandbox ? { runtimeSandbox: options.sandbox } : {})
+        }
+        : {};
     const [attestation, corpus, performance, trust, packageMetadata, git, runtimePlan] = await Promise.all([
         buildDoctorAttestation(rootPath, {
             signingKey: options.signingKey,
@@ -202,13 +211,13 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         buildDoctorValidationCorpusReport({ environment: options.environment }),
         buildDoctorPerformanceReport(rootPath, {
             environment: options.environment,
-            runCheck: options.runCheck,
+            runCheck: (pathToCheck) => runCheck(pathToCheck, checkOptions),
             thresholds: options.performanceThresholds
         }),
         buildTrustScore(rootPath, { securityAudit: security }),
         readPackageMetadata(rootPath),
         readGitMetadata(rootPath),
-        buildDoctorRuntimePlan(rootPath)
+        buildDoctorRuntimePlan(rootPath, new Date().toISOString(), options.sandbox ? { sandbox: options.sandbox } : {})
     ]);
     const normalizedPackageMetadata = {
         name: packageMetadata.name ?? attestation.subject.name,
@@ -244,6 +253,7 @@ export async function buildDoctorReleaseEvidenceReport(targetPath, options) {
         git,
         releaseGates,
         runtimeApproval,
+        ...(options.runtime ? { execution: runtimePlan.execution } : {}),
         attestation,
         attestationVerification,
         corpus,

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

@@ -1,5 +1,6 @@
 import { type SecurityAudit } from "../security/security-audit.js";
 import type { Finding } from "../domain/types.js";
+import type { RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
 type RuntimePlanStatus = "pass" | "warn" | "fail";
 type RuntimePlanRiskLevel = "low" | "medium" | "high";
 type RuntimePlanTransport = "stdio" | "http";
@@ -23,6 +24,7 @@ export interface DoctorRuntimePlan {
     status: RuntimePlanStatus;
     exitCode: 0 | 1;
     runtimeExecution: "not_started";
+    execution: RuntimeExecutionEvidence;
     digest: string;
     summary: {
         serverCount: number;
@@ -40,7 +42,9 @@ export interface RuntimeApprovalReport {
     approvedDigest: string | null;
     message: string;
 }
-export declare function buildDoctorRuntimePlan(targetPath: string, generatedAt?: string): Promise<DoctorRuntimePlan>;
+export declare function buildDoctorRuntimePlan(targetPath: string, generatedAt?: string, options?: {
+    sandbox?: RuntimeSandboxMode;
+}): Promise<DoctorRuntimePlan>;
 export declare function evaluateRuntimeApproval(plan: DoctorRuntimePlan, options: {
     required: boolean;
     approvedDigest?: string | null;

package/dist/core/runtime-plan.js

@@ -4,6 +4,7 @@ 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";
+import { DOCKER_RUNTIME_IMAGE } from "./runtime-sandbox.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -51,6 +52,7 @@ function planDigestPayload(plan) {
         schemaVersion: plan.schemaVersion,
         kind: "doctor.runtime.plan.digest.v1",
         version: plan.version,
+        execution: plan.execution,
         status: plan.status,
         summary: plan.summary,
         servers: plan.servers,
@@ -64,10 +66,18 @@ function planDigestPayload(plan) {
 function buildRuntimePlanDigest(plan) {
     return sha256(stableStringify(planDigestPayload(plan)));
 }
-export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date().toISOString()) {
+export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date().toISOString(), options = {}) {
     const rootPath = path.resolve(targetPath);
     const discoveredPackage = await discoverPackage(rootPath);
     const security = await buildSecurityAudit(rootPath);
+    const execution = options.sandbox === "docker"
+        ? {
+            backend: "docker",
+            image: DOCKER_RUNTIME_IMAGE,
+            network: "none",
+            packageMount: "read_only"
+        }
+        : { backend: "native", image: null, network: "host", packageMount: "host" };
     if (!discoveredPackage?.manifest.mcpServers) {
         const partialPlan = {
             schemaVersion: "1.0.0",
@@ -77,6 +87,7 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
             status: security.status,
             exitCode: (security.status === "fail" ? 1 : 0),
             runtimeExecution: "not_started",
+            execution,
             summary: {
                 serverCount: 0,
                 executableServerCount: 0,
@@ -146,6 +157,7 @@ export async function buildDoctorRuntimePlan(targetPath, generatedAt = new Date(
                 : "pass",
         exitCode: (highRiskServerCount > 0 ? 1 : 0),
         runtimeExecution: "not_started",
+        execution,
         summary: {
             serverCount: servers.length,
             executableServerCount: servers.filter((server) => server.command).length,

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

@@ -1,3 +1,4 @@
+import type { RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
 import { type DoctorRuntimePlan, type RuntimePlanServer } from "./runtime-plan.js";
 export type RuntimePolicyDecision = "allow" | "review" | "sandbox_recommended" | "deny";
 export interface RuntimePolicyRecommendation {
@@ -14,6 +15,7 @@ export interface DoctorRuntimePolicyReport {
     status: "pass" | "warn" | "fail";
     exitCode: 0 | 1;
     runtimeExecution: "not_started";
+    execution: RuntimeExecutionEvidence;
     planDigest: string;
     recommendation: RuntimePolicyRecommendation;
     summary: {
@@ -29,6 +31,8 @@ export interface DoctorRuntimePolicyReport {
         reasons: string[];
     }>;
 }
-export declare function buildDoctorRuntimePolicyReport(targetPath: string, generatedAt?: string): Promise<DoctorRuntimePolicyReport>;
+export declare function buildDoctorRuntimePolicyReport(targetPath: string, generatedAt?: string, options?: {
+    sandbox?: RuntimeSandboxMode;
+}): Promise<DoctorRuntimePolicyReport>;
 export declare function renderDoctorRuntimePolicyJson(report: DoctorRuntimePolicyReport): string;
 export declare function renderDoctorRuntimePolicy(report: DoctorRuntimePolicyReport): string;

package/dist/core/runtime-policy.js

@@ -91,8 +91,8 @@ function buildRecommendation(plan, decision, reasons) {
         ]
     };
 }
-export async function buildDoctorRuntimePolicyReport(targetPath, generatedAt = new Date().toISOString()) {
-    const plan = await buildDoctorRuntimePlan(targetPath, generatedAt);
+export async function buildDoctorRuntimePolicyReport(targetPath, generatedAt = new Date().toISOString(), options = {}) {
+    const plan = await buildDoctorRuntimePlan(targetPath, generatedAt, options);
     const servers = plan.servers.map((server) => ({
         name: server.name,
         decision: serverDecision(server),
@@ -118,6 +118,7 @@ export async function buildDoctorRuntimePolicyReport(targetPath, generatedAt = n
         status,
         exitCode: status === "fail" ? 1 : 0,
         runtimeExecution: "not_started",
+        execution: plan.execution,
         planDigest: plan.digest,
         recommendation,
         summary: {

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

@@ -1,5 +1,6 @@
-import type { DiscoveredPackage, RuntimeProbeResult } from "../domain/types.js";
+import type { DiscoveredPackage, RuntimeProbeResult, RuntimeSandboxMode } from "../domain/types.js";
 export declare function probeRuntime(discoveredPackage: DiscoveredPackage, options?: {
     startupTimeoutMs?: number;
+    sandbox?: RuntimeSandboxMode;
     transcript?: (line: string) => void;
 }): Promise<RuntimeProbeResult>;

package/dist/core/runtime-probe.js

@@ -1,7 +1,9 @@
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline";
+import { buildRuntimeLaunch, DOCKER_RUNTIME_STARTUP_TIMEOUT_MS, RuntimeSandboxError } from "./runtime-sandbox.js";
 import { formatRequestTranscript as formatRequestTranscriptForLog, formatResponseTranscript as formatResponseTranscriptForLog } from "./runtime-transcript.js";
 const MCP_PROTOCOL_VERSION = "2025-11-25";
 const PROMPT_PROBE_PLACEHOLDER = "codex-plugin-doctor-probe";
@@ -9,6 +11,19 @@ const METHOD_NOT_FOUND = -32601;
 const MAX_TOOL_CALL_CONTENT_LENGTH = 4096;
 const MAX_RESOURCE_READ_CONTENT_LENGTH = 4096;
 const MAX_PROMPT_GET_CONTENT_LENGTH = 4096;
+const DOCKER_CLEANUP_TIMEOUT_MS = 5_000;
+function buildNativeRuntimeLaunch(input) {
+    return {
+        ...input,
+        containerName: null,
+        evidence: {
+            backend: "native",
+            image: null,
+            network: "host",
+            packageMount: "host"
+        }
+    };
+}
 function createRuntimeScorecard() {
     return {
         initialize: "skipped",
@@ -72,6 +87,21 @@ function withRuntimeEvidence(finding, serverName) {
         }
     };
 }
+function cleanupDockerContainer(containerName) {
+    return new Promise((resolve) => {
+        execFile("docker", ["rm", "-f", containerName], {
+            encoding: "utf8",
+            timeout: DOCKER_CLEANUP_TIMEOUT_MS,
+            windowsHide: true
+        }, (error, _stdout, stderr) => {
+            if (!error || /no such container/i.test(stderr)) {
+                resolve(null);
+                return;
+            }
+            resolve(buildFailure("plugin.runtime.sandbox.cleanup_failed", "The Docker runtime container could not be removed after probing.", "A leftover runtime container weakens cleanup guarantees and may continue consuming local resources.", "Verify the Docker daemon is available, then remove the codex-doctor container before retrying."));
+        });
+    });
+}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -605,16 +635,42 @@ function collectOversizedPromptGetWarnings(message, evidence) {
     ];
 }
 async function probeCommandServer(input) {
-    const { serverName, command, args, cwd, startupTimeoutMs, transcript } = input;
+    const { serverName, packageRoot, command, args, cwd, startupTimeoutMs, sandbox, transcript } = input;
+    let launch;
+    try {
+        launch = sandbox === "docker"
+            ? buildRuntimeLaunch({
+                sandbox,
+                packageRoot,
+                command,
+                args,
+                cwd,
+                containerName: `codex-doctor-${randomUUID()}`
+            })
+            : buildNativeRuntimeLaunch({ command, args, cwd });
+    }
+    catch (error) {
+        const scorecard = createRuntimeScorecard();
+        scorecard.initialize = "fail";
+        return {
+            findings: [
+                withRuntimeEvidence(buildFailure("plugin.runtime.startup.failed", `The MCP server \`${serverName}\` could not be started in the requested runtime backend.`, "The configured stdio server is not supported by the selected runtime backend, so runtime validation cannot proceed.", error instanceof RuntimeSandboxError
+                    ? error.message
+                    : "Verify the runtime command and selected sandbox before retrying."), serverName)
+            ],
+            scorecard
+        };
+    }
     return new Promise((resolve) => {
         const scorecard = createRuntimeScorecard();
         const warnings = [];
         let settled = false;
+        let runtimeExecuted = false;
         let stderrPreview = "";
         let finalizeRequested = false;
         let nextRequestId = 1;
-        const child = spawn(command, args, {
-            cwd,
+        const child = spawn(launch.command, launch.args, {
+            cwd: launch.cwd,
             stdio: ["pipe", "pipe", "pipe"]
         });
         const stdoutReader = readline.createInterface({
@@ -637,21 +693,33 @@ async function probeCommandServer(input) {
                 child.stdin.end();
                 child.kill("SIGTERM");
             }
-            resolve({
-                findings: [
-                    ...warnings.map((warning) => withRuntimeEvidence(warning, serverName)),
-                    ...(finding ? [withRuntimeEvidence(finding, serverName)] : [])
-                ],
-                scorecard
-            });
+            void (async () => {
+                const cleanupFinding = launch.containerName && runtimeExecuted
+                    ? await cleanupDockerContainer(launch.containerName)
+                    : null;
+                resolve({
+                    findings: [
+                        ...warnings.map((warning) => withRuntimeEvidence(warning, serverName)),
+                        ...(finding ? [withRuntimeEvidence(finding, serverName)] : []),
+                        ...(cleanupFinding
+                            ? [withRuntimeEvidence(cleanupFinding, serverName)]
+                            : [])
+                    ],
+                    scorecard,
+                    ...(runtimeExecuted ? { execution: launch.evidence } : {})
+                });
+            })();
         };
         const sendRequest = (method, params, timeoutFinding) => new Promise((requestResolve, requestReject) => {
             const id = nextRequestId++;
             transcript?.(formatRequestTranscriptForLog(method, params));
+            const requestTimeoutMs = launch.evidence.backend === "docker" && method === "initialize"
+                ? DOCKER_RUNTIME_STARTUP_TIMEOUT_MS
+                : startupTimeoutMs;
             const timer = setTimeout(() => {
                 pendingRequests.delete(id);
                 requestReject(timeoutFinding);
-            }, startupTimeoutMs);
+            }, requestTimeoutMs);
             pendingRequests.set(id, {
                 method,
                 resolve: requestResolve,
@@ -701,6 +769,9 @@ async function probeCommandServer(input) {
             }
             stderrPreview += chunk.toString();
         });
+        child.on("spawn", () => {
+            runtimeExecuted = true;
+        });
         stdoutReader.on("line", (line) => {
             if (settled) {
                 return;
@@ -731,7 +802,9 @@ async function probeCommandServer(input) {
         });
         child.on("error", () => {
             scorecard.initialize = "fail";
-            settle(buildFailure("plugin.runtime.startup.failed", `The MCP server \`${serverName}\` could not be started.`, "The configured stdio server could not be launched, so runtime validation cannot proceed.", `Verify the command \`${command}\` is installed and executable from \`${cwd}\`.`));
+            settle(buildFailure("plugin.runtime.startup.failed", `The MCP server \`${serverName}\` could not be started.`, "The configured stdio server could not be launched, so runtime validation cannot proceed.", launch.evidence.backend === "docker"
+                ? "Verify Docker is installed and the Docker daemon is available."
+                : `Verify the command \`${command}\` is installed and executable from \`${cwd}\`.`));
         });
         child.on("exit", () => {
             if (settled || finalizeRequested) {
@@ -740,9 +813,11 @@ async function probeCommandServer(input) {
             if (scorecard.initialize === "skipped") {
                 scorecard.initialize = "fail";
             }
-            settle(buildFailure("plugin.runtime.exited_early", `The MCP server \`${serverName}\` exited before the startup probe completed.`, "A server that exits immediately is unlikely to remain available for Codex during normal use.", stderrPreview.trim().length > 0
+            settle(buildFailure("plugin.runtime.exited_early", `The MCP server \`${serverName}\` exited before the startup probe completed.`, "A server that exits immediately is unlikely to remain available for Codex during normal use.", launch.evidence.backend !== "docker" && stderrPreview.trim().length > 0
                 ? `Inspect the startup error output: ${stderrPreview.trim()}`
-                : `Keep the \`${serverName}\` process running after startup and inspect its command or arguments.`));
+                : launch.evidence.backend === "docker"
+                    ? "Verify Docker can start the pinned runtime image and keep the server process running."
+                    : `Keep the \`${serverName}\` process running after startup and inspect its command or arguments.`));
         });
         const runProtocolProbe = async () => {
             const initializeResponse = await sendRequest("initialize", {
@@ -917,9 +992,11 @@ async function probeCommandServer(input) {
             if (scorecard.initialize === "skipped") {
                 scorecard.initialize = "fail";
             }
-            settle(buildFailure("plugin.runtime.protocol.unhandled", `The MCP server \`${serverName}\` triggered an unexpected protocol probe failure.`, "Unexpected probe failures reduce confidence in runtime validation results.", stderrPreview.trim().length > 0
+            settle(buildFailure("plugin.runtime.protocol.unhandled", `The MCP server \`${serverName}\` triggered an unexpected protocol probe failure.`, "Unexpected probe failures reduce confidence in runtime validation results.", launch.evidence.backend !== "docker" && stderrPreview.trim().length > 0
                 ? `Inspect stderr for details: ${stderrPreview.trim()}`
-                : "Inspect the server output and protocol implementation for unexpected runtime errors."));
+                : launch.evidence.backend === "docker"
+                    ? "Inspect Docker availability and the server protocol implementation without exposing raw runtime output."
+                    : "Inspect the server output and protocol implementation for unexpected runtime errors."));
         });
     });
 }
@@ -934,6 +1011,7 @@ export async function probeRuntime(discoveredPackage, options = {}) {
     }
     const findings = [];
     let scorecard = createRuntimeScorecard();
+    let execution;
     for (const [serverName, config] of Object.entries(servers)) {
         if (!isPlainObject(config)) {
             continue;
@@ -950,19 +1028,23 @@ export async function probeRuntime(discoveredPackage, options = {}) {
             : discoveredPackage.rootPath;
         const result = await probeCommandServer({
             serverName,
+            packageRoot: discoveredPackage.rootPath,
             command,
             args,
             cwd,
             startupTimeoutMs,
+            sandbox: options.sandbox,
             transcript: options.transcript
         });
         scorecard = result.scorecard;
+        execution = result.execution ?? execution;
         if (result.findings.length > 0) {
             findings.push(...result.findings);
         }
     }
     return {
         findings,
-        scorecard
+        scorecard,
+        ...(execution ? { execution } : {})
     };
 }

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

@@ -0,0 +1,21 @@
+import type { RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
+export interface RuntimeLaunchInput {
+    sandbox: RuntimeSandboxMode;
+    packageRoot: string;
+    cwd: string;
+    command: string;
+    args: string[];
+    containerName: string;
+}
+export interface RuntimeLaunchSpec {
+    command: string;
+    args: string[];
+    cwd: string;
+    containerName: string;
+    evidence: RuntimeExecutionEvidence;
+}
+export declare class RuntimeSandboxError extends Error {
+}
+export declare const DOCKER_RUNTIME_STARTUP_TIMEOUT_MS = 60000;
+export declare const DOCKER_RUNTIME_IMAGE = "node:22-bookworm-slim@sha256:6c74791e557ce11fc957704f6d4fe134a7bc8d6f5ca4403205b2966bd488f6b3";
+export declare function buildRuntimeLaunch(input: RuntimeLaunchInput): RuntimeLaunchSpec;

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";

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";