codex-plugin-doctor 1.46.0 → 1.47.0

package/dist/core/release-check.js

@@ -1,9 +1,83 @@
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { validatePlugin } from "./validate-plugin.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
 import { buildDepAudit } from "./dep-audit.js";
 import { buildCompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
 import { buildTrustScore } from "../security/trust-score.js";
+async function readOptionalFile(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function buildReleaseMetadataCheck(targetPath) {
+    const packageContent = await readOptionalFile(path.join(targetPath, "package.json"));
+    if (packageContent === null) {
+        return {
+            status: "skipped",
+            packageVersion: null,
+            lockfileVersion: null,
+            changelogVersion: null,
+            findings: []
+        };
+    }
+    const findings = [];
+    let packageVersion = null;
+    let lockfileVersion = null;
+    try {
+        const packageJson = JSON.parse(packageContent);
+        packageVersion = typeof packageJson.version === "string" ? packageJson.version : null;
+    }
+    catch {
+        findings.push("package.json is not valid JSON.");
+    }
+    if (!packageVersion) {
+        findings.push("package.json must contain a version.");
+    }
+    const lockContent = await readOptionalFile(path.join(targetPath, "package-lock.json"));
+    if (lockContent !== null) {
+        try {
+            const lock = JSON.parse(lockContent);
+            const rootVersion = lock.packages?.[""]?.version ?? lock.version;
+            lockfileVersion = typeof rootVersion === "string" ? rootVersion : null;
+        }
+        catch {
+            findings.push("package-lock.json is not valid JSON.");
+        }
+        if (!lockfileVersion) {
+            findings.push("package-lock.json must contain the root package version.");
+        }
+        else if (packageVersion && lockfileVersion !== packageVersion) {
+            findings.push(`package-lock.json version ${lockfileVersion} does not match package.json ${packageVersion}.`);
+        }
+    }
+    const changelog = await readOptionalFile(path.join(targetPath, "CHANGELOG.md"));
+    const changelogVersion = changelog === null || !packageVersion
+        ? null
+        : new RegExp(`^## \\[${packageVersion.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\](?:\\s|$)`, "m").test(changelog);
+    if (changelogVersion === false) {
+        findings.push(`CHANGELOG.md does not contain a ${packageVersion} release section.`);
+    }
+    return {
+        status: findings.length === 0 ? "pass" : "fail",
+        packageVersion,
+        lockfileVersion,
+        changelogVersion,
+        findings
+    };
+}
+export async function assertReleaseMetadataSync(targetPath) {
+    const metadata = await buildReleaseMetadataCheck(path.resolve(targetPath));
+    if (metadata.status === "fail") {
+        throw new Error(`Release metadata is inconsistent: ${metadata.findings.join(" ")}`);
+    }
+}
 function matrixOverallStatus(matrix) {
     const statuses = matrix.results.map((r) => r.status);
     const passCount = statuses.filter((s) => s === "pass").length;
@@ -29,11 +103,16 @@ export async function buildReleaseCheck(targetPath, options = {}) {
     const resolvedPath = path.resolve(targetPath);
     const env = options.env ?? process.env;
     const platform = options.platform ?? process.platform;
-    const validationResult = await validatePlugin(resolvedPath, { runtime: true });
+    const runtimeProbeEnabled = options.runtime ?? false;
+    const validationResult = await (options.runCheck ?? validatePlugin)(resolvedPath, {
+        runtime: runtimeProbeEnabled,
+        ...(options.runtimeSandbox ? { runtimeSandbox: options.runtimeSandbox } : {})
+    });
     const securityResult = await buildSecurityAudit(resolvedPath);
     const depResult = await buildDepAudit(resolvedPath);
     const compatResult = await buildCompatibilityMatrix(resolvedPath, { env, platform });
     const trustResult = await buildTrustScore(resolvedPath);
+    const metadataResult = await buildReleaseMetadataCheck(resolvedPath);
     const checks = {
         validation: {
             status: validationResult.status,
@@ -56,16 +135,19 @@ export async function buildReleaseCheck(targetPath, options = {}) {
         trust: {
             status: trustResult.status,
             score: trustResult.score
-        }
+        },
+        metadata: metadataResult
     };
     const ready = checks.validation.status === "pass" &&
         checks.security.status === "pass" &&
         checks.dependencies.status !== "fail" &&
         checks.compatibility.status !== "fail" &&
-        checks.trust.status === "pass";
+        checks.trust.status === "pass" &&
+        checks.metadata.status !== "fail";
     return {
         targetPath: resolvedPath,
         status: ready ? "pass" : "fail",
+        runtimeProbeEnabled,
         checks,
         ready
     };
@@ -77,6 +159,7 @@ export function renderReleaseCheck(report) {
         "==================================",
         `Path: ${report.targetPath}`,
         `Ready: ${report.ready ? "YES" : "NO"}`,
+        `Runtime probe: ${report.runtimeProbeEnabled ? "enabled" : "disabled"}`,
         "",
         "Checks",
         "------",
@@ -85,6 +168,9 @@ export function renderReleaseCheck(report) {
         `  ${icon(report.checks.dependencies.status === "pass")}  dependencies  ${report.checks.dependencies.status}  (${report.checks.dependencies.vulnerabilities} vulns)`,
         `  ${icon(report.checks.compatibility.status === "pass")}  compatibility ${report.checks.compatibility.status}  (score: ${report.checks.compatibility.score})`,
         `  ${icon(report.checks.trust.status === "pass")}  trust         ${report.checks.trust.status}  (score: ${report.checks.trust.score})`,
+        ...(report.checks.metadata
+            ? [`  ${icon(report.checks.metadata.status !== "fail")}  metadata      ${report.checks.metadata.status}  (${report.checks.metadata.findings.length} findings)`]
+            : []),
         "",
         report.ready
             ? "All release checks passed. Ready to publish."
@@ -97,6 +183,7 @@ export function renderReleaseCheckJson(report) {
         schemaVersion: "1.0.0",
         targetPath: report.targetPath,
         status: report.status,
+        runtimeProbeEnabled: report.runtimeProbeEnabled ?? false,
         ready: report.ready,
         checks: report.checks
     }, null, 2);

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

@@ -5,7 +5,7 @@ import { type SecurityAudit } from "../security/security-audit.js";
 import { type TrustScoreReport } from "../security/trust-score.js";
 import { type RuntimeApprovalReport } from "./runtime-plan.js";
 import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
-import type { CheckResult } from "../domain/types.js";
+import type { CheckOptions, CheckResult, RuntimeExecutionEvidence, RuntimeSandboxMode } from "../domain/types.js";
 type EvidenceStatus = "pass" | "warn" | "fail";
 export interface DoctorReleaseEvidenceSignature {
     status: "signed";
@@ -52,6 +52,7 @@ export interface DoctorReleaseEvidenceReport {
         }>;
     };
     runtimeApproval: RuntimeApprovalReport;
+    execution?: RuntimeExecutionEvidence;
     package: DoctorReleaseEvidencePackageMetadata;
     git: DoctorReleaseEvidenceGitMetadata;
     attestation: DoctorAttestation;
@@ -109,8 +110,10 @@ export interface BuildDoctorReleaseEvidenceOptions {
     allowUntagged?: boolean;
     requireRuntimeApproval?: boolean;
     runtimeApprovalDigest?: string | null;
+    runtime?: boolean;
+    sandbox?: RuntimeSandboxMode;
     environment?: CompatibilityEnvironment;
-    runCheck?: (targetPath: string) => Promise<CheckResult>;
+    runCheck?: (targetPath: string, options?: CheckOptions) => Promise<CheckResult>;
     performanceThresholds?: DoctorPerformanceThresholdOptions;
 }
 export declare function buildDoctorReleaseEvidenceReport(targetPath: string, options: BuildDoctorReleaseEvidenceOptions): Promise<DoctorReleaseEvidenceReport>;

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;