codex-plugin-doctor 1.46.0 → 1.47.0

package/README.md

@@ -79,6 +79,7 @@ Runtime MCP validation with `--runtime`:
 - runtime capability scorecard
 - redacted verbose transcript with `--verbose-runtime`
 - optional runtime approval gating with a precomputed `doctor runtime-plan` digest
+- optional Docker isolation for local Node.js stdio servers with `--sandbox docker`
 
 Output formats:
 
@@ -195,6 +196,7 @@ codex-plugin-doctor doctor contract
 codex-plugin-doctor doctor contract --json --output output-contract.json
 codex-plugin-doctor doctor corpus
 codex-plugin-doctor doctor corpus --json --output validation-corpus.json
+codex-plugin-doctor doctor corpus --manifest ../private-corpus/corpus.json --json
 codex-plugin-doctor doctor npm <published-plugin-package>
 codex-plugin-doctor doctor npm <published-plugin-package> --json --output npm-preinstall.json
 codex-plugin-doctor doctor attest .
@@ -216,8 +218,10 @@ codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=
 codex-plugin-doctor doctor runtime-plan .
 codex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json
 codex-plugin-doctor doctor runtime-plan . --markdown --output runtime-plan.md
+codex-plugin-doctor doctor runtime-plan . --sandbox docker --json
 codex-plugin-doctor doctor runtime-policy .
 codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
+codex-plugin-doctor doctor runtime-policy . --sandbox docker --json
 codex-plugin-doctor doctor review-bundle . --output review-bundle --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
 codex-plugin-doctor doctor review-bundle verify review-bundle --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
 codex-plugin-doctor doctor review-bundle diff --before old-review-bundle --after review-bundle
@@ -287,6 +291,13 @@ codex-plugin-doctor check . --ascii
 codex-plugin-doctor check . --no-animations
 codex-plugin-doctor check . --runtime
 codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
+codex-plugin-doctor check . --runtime --sandbox docker
+codex-plugin-doctor check . --runtime --sandbox docker --require-runtime-approval --runtime-approval-digest sha256:<approved-docker-plan-digest>
+codex-plugin-doctor release check .
+codex-plugin-doctor release check . --json
+codex-plugin-doctor release check . --runtime
+codex-plugin-doctor release check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
+codex-plugin-doctor release check . --runtime --sandbox docker --require-runtime-approval --runtime-approval-digest sha256:<approved-docker-plan-digest>
 codex-plugin-doctor check . --config .codex-doctor.json
 codex-plugin-doctor baseline create . --output .codex-doctor-baseline.json
 codex-plugin-doctor check . --baseline .codex-doctor-baseline.json
@@ -300,6 +311,10 @@ codex-plugin-doctor fix . --apply --backup
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
+Docker runtime mode supports local Node.js stdio MCP servers. It uses a digest-pinned image, no network, read-only container and package filesystems, an unprivileged user, dropped capabilities, bounded resources, and a limited writable `/tmp`. It fails closed without native fallback and rejects package roots containing commas. The Docker daemon, base image, and host kernel remain trusted boundaries. Generate approval digests with the same `--sandbox docker` backend used for execution. See [Runtime Approval And Sandboxing](./docs/security/runtime-approval-and-sandboxing.md).
+
+External corpus evaluation is static and offline. `doctor corpus --manifest <corpus.json>` validates anonymized local snapshots using stable content digests and exact finding fingerprints without downloading dependencies or starting target servers. Reports omit manifest and package paths and fail on digest drift, missing expected findings, present disputed findings, or unreviewed findings. See [Real-World Validation](./docs/guides/real-world-validation.md).
+
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
 `doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
@@ -406,9 +421,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.46.0
+      - uses: Esquetta/CodexPluginDoctor@v1.47.0
         with:
-          version: "1.46.0"
+          version: "1.47.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -435,7 +450,6 @@ docs/                 Public architecture, guides, rules, security, and contribu
 examples/             Manual plugin packs for local CLI testing
 src/                  CLI, validation logic, runtime probing, reports
 tests/                Fixture-based regression tests
-validation-sessions/  Real-world validation waves and tuning notes
 ```
 
 ## Validation Evidence
@@ -443,7 +457,6 @@ validation-sessions/  Real-world validation waves and tuning notes
 The validator is tuned against local fixtures and real marketplace-style plugin packages. See:
 
 - [Real-World Validation Workflow](./docs/guides/real-world-validation.md)
-- [Validation Sessions](./validation-sessions/README.md)
 - [Examples](./examples/README.md)
 - [Rule Catalog](./docs/rules/catalog.md)
 
@@ -463,7 +476,9 @@ npm run prepare-release
 npm run release-check
 ```
 
-`prepare-release` runs tests, builds the TypeScript output, and performs `npm pack --dry-run`. `release-check` adds release preflight checks for a clean git tree, existing npm versions, existing version tags, tests, build, pack dry-run, fresh temp install audit, and publish dry-run.
+`prepare-release` runs tests, builds the TypeScript output, and performs `npm pack --dry-run`. `release-check` adds release preflight checks for a clean git tree, existing npm versions, existing version tags, package/lockfile/changelog version consistency, tests, build, pack dry-run, fresh temp install audit, and publish dry-run.
+
+For plugin packages, `codex-plugin-doctor release check .` performs static readiness checks by default. Runtime probing executes package-local MCP servers and therefore requires an explicit `--runtime`; protected workflows can also require the approved runtime-plan digest.
 
 Related docs:
 

package/dist/core/attestation.d.ts

@@ -95,6 +95,7 @@ export interface VerifyDoctorAttestationOptions {
     signingKey: string;
     artifactPath?: string;
 }
+export declare function buildPackageFingerprint(rootPath: string): Promise<PackageFingerprint>;
 export declare function buildDoctorAttestation(targetPath: string, options?: BuildDoctorAttestationOptions): Promise<DoctorAttestation>;
 export declare function verifyDoctorAttestation(artifactPath: string, targetPath: string, options: VerifyDoctorAttestationOptions): Promise<DoctorAttestationVerificationReport>;
 export declare function verifyDoctorAttestationObject(artifact: unknown, targetPath: string, options: VerifyDoctorAttestationOptions): Promise<DoctorAttestationVerificationReport>;

package/dist/core/attestation.js

@@ -61,7 +61,7 @@ async function collectFileEntries(rootPath, currentPath = rootPath) {
     }));
     return fileEntries.flat().sort((left, right) => left.relativePath.localeCompare(right.relativePath));
 }
-async function buildPackageFingerprint(rootPath) {
+export async function buildPackageFingerprint(rootPath) {
     const files = await collectFileEntries(rootPath);
     const bytes = files.reduce((total, file) => total + file.size, 0);
     const digest = sha256(stableStringify(files));

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

@@ -0,0 +1,88 @@
+export type ExternalCorpusProfile = "healthy" | "broken" | "edge-case";
+export type ExternalCorpusSourceType = "public-package" | "local-snapshot" | "derived-fixture";
+export type ExternalCorpusMode = "codex-plugin" | "generic-mcp";
+export type FindingReviewClassification = "true_positive" | "false_positive" | "unclear";
+export interface ExternalCorpusFindingReview {
+    findingId: string;
+    fingerprint: string;
+    classification: FindingReviewClassification;
+}
+export interface ExternalCorpusTarget {
+    id: string;
+    profile: ExternalCorpusProfile;
+    sourceType: ExternalCorpusSourceType;
+    disclosure: "anonymized";
+    path: string;
+    mode: ExternalCorpusMode;
+    contentDigest: string;
+    expectedStatus: "pass" | "warn" | "fail";
+    reviews: ExternalCorpusFindingReview[];
+}
+export interface ExternalCorpusManifest {
+    schemaVersion: "1.0.0";
+    targets: ExternalCorpusTarget[];
+}
+export interface LoadedExternalCorpusTarget extends ExternalCorpusTarget {
+    resolvedPath: string;
+}
+export interface LoadedExternalCorpusManifest extends ExternalCorpusManifest {
+    targets: LoadedExternalCorpusTarget[];
+}
+export interface ExternalCorpusReportedFinding {
+    findingId: string;
+    fingerprint: string;
+    classification: FindingReviewClassification | "unreviewed";
+}
+export interface ExternalCorpusCaseResult {
+    id: string;
+    profile: ExternalCorpusProfile;
+    sourceType: ExternalCorpusSourceType;
+    disclosure: "anonymized";
+    mode: ExternalCorpusMode;
+    expected: {
+        status: ExternalCorpusTarget["expectedStatus"];
+        contentDigest: string;
+        findings: ExternalCorpusFindingReview[];
+    };
+    actual: {
+        status: ExternalCorpusTarget["expectedStatus"];
+        contentDigest: string;
+        findings: ExternalCorpusReportedFinding[];
+    };
+    digestMatched: boolean;
+    classificationCounts: ExternalCorpusClassificationCounts;
+    expectationMatched: boolean;
+}
+export interface ExternalCorpusClassificationCounts {
+    truePositive: number;
+    falsePositive: number;
+    unclear: number;
+    missingExpectedFinding: number;
+}
+export interface ExternalValidationCorpusReport {
+    schemaVersion: "1.0.0";
+    kind: "doctor.validation.corpus";
+    corpusType: "external";
+    generatedAt: string;
+    version: string;
+    summary: {
+        status: "pass" | "fail";
+        caseCount: number;
+        passedExpectations: number;
+        failedExpectations: number;
+        runtimeCases: 0;
+        classificationCounts: ExternalCorpusClassificationCounts;
+    };
+    cases: ExternalCorpusCaseResult[];
+}
+export interface BuildExternalValidationCorpusOptions {
+    environment?: {
+        env?: NodeJS.ProcessEnv;
+        platform?: NodeJS.Platform;
+    };
+}
+export declare class ExternalCorpusManifestError extends Error {
+    constructor(message: string);
+}
+export declare function loadExternalCorpusManifest(manifestPath: string): Promise<LoadedExternalCorpusManifest>;
+export declare function buildExternalValidationCorpusReport(manifestPath: string, options?: BuildExternalValidationCorpusOptions): Promise<ExternalValidationCorpusReport>;

package/dist/core/external-validation-corpus.js

@@ -0,0 +1,271 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { buildGenericMcpDoctor } from "../mcp/generic-mcp-doctor.js";
+import { packageVersion } from "../version.js";
+import { buildPackageFingerprint } from "./attestation.js";
+import { readJsonFile } from "./read-json-file.js";
+import { validatePlugin } from "./validate-plugin.js";
+export class ExternalCorpusManifestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExternalCorpusManifestError";
+    }
+}
+const topLevelKeys = new Set(["schemaVersion", "targets"]);
+const targetKeys = new Set([
+    "id",
+    "profile",
+    "sourceType",
+    "disclosure",
+    "path",
+    "mode",
+    "contentDigest",
+    "expectedStatus",
+    "reviews"
+]);
+const reviewKeys = new Set(["findingId", "fingerprint", "classification"]);
+const profiles = new Set(["healthy", "broken", "edge-case"]);
+const sourceTypes = new Set([
+    "public-package",
+    "local-snapshot",
+    "derived-fixture"
+]);
+const modes = new Set(["codex-plugin", "generic-mcp"]);
+const statuses = new Set(["pass", "warn", "fail"]);
+const classifications = new Set([
+    "true_positive",
+    "false_positive",
+    "unclear"
+]);
+const sha256Digest = /^sha256:[a-f0-9]{64}$/;
+const findingFingerprint = /^[a-f0-9]{64}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0) {
+        throw new ExternalCorpusManifestError(`${label} contains unsupported field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`);
+    }
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ExternalCorpusManifestError(`${label} must be a non-empty string.`);
+    }
+    return value;
+}
+function parseReview(value, targetId, index) {
+    if (!isRecord(value)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${targetId} review ${index} must be an object.`);
+    }
+    rejectUnknownKeys(value, reviewKeys, `Corpus target ${targetId} review ${index}`);
+    const findingId = requireString(value.findingId, `Corpus target ${targetId} review ${index} findingId`);
+    const fingerprint = requireString(value.fingerprint, `Corpus target ${targetId} review ${index} fingerprint`);
+    const classification = value.classification;
+    if (typeof classification !== "string" || !classifications.has(classification)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${targetId} review ${index} has an unsupported classification.`);
+    }
+    if (!findingFingerprint.test(fingerprint)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${targetId} review ${index} fingerprint must be a sha256 fingerprint.`);
+    }
+    return {
+        findingId,
+        fingerprint,
+        classification: classification
+    };
+}
+async function parseTarget(value, manifestDirectory, index) {
+    if (!isRecord(value)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${index} must be an object.`);
+    }
+    rejectUnknownKeys(value, targetKeys, `Corpus target ${index}`);
+    const id = requireString(value.id, `Corpus target ${index} id`);
+    const targetPath = requireString(value.path, `Corpus target ${id} path`);
+    if (path.posix.isAbsolute(targetPath) || path.win32.isAbsolute(targetPath)) {
+        throw new ExternalCorpusManifestError("Corpus target path must be relative to the manifest file.");
+    }
+    if (typeof value.profile !== "string" || !profiles.has(value.profile)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported profile.`);
+    }
+    if (typeof value.sourceType !== "string" || !sourceTypes.has(value.sourceType)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported sourceType.`);
+    }
+    if (value.disclosure !== "anonymized") {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} disclosure must be anonymized.`);
+    }
+    if (typeof value.mode !== "string" || !modes.has(value.mode)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported mode.`);
+    }
+    if (typeof value.expectedStatus !== "string" || !statuses.has(value.expectedStatus)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} has an unsupported expectedStatus.`);
+    }
+    if (typeof value.contentDigest !== "string" || !sha256Digest.test(value.contentDigest)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} contentDigest must be a sha256 digest.`);
+    }
+    if (!Array.isArray(value.reviews)) {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} reviews must be an array.`);
+    }
+    const reviews = value.reviews.map((review, reviewIndex) => parseReview(review, id, reviewIndex));
+    const reviewKeySet = new Set();
+    for (const review of reviews) {
+        const key = `${review.findingId}:${review.fingerprint}`;
+        if (reviewKeySet.has(key)) {
+            throw new ExternalCorpusManifestError(`Corpus target ${id} contains a duplicate finding review.`);
+        }
+        reviewKeySet.add(key);
+    }
+    const resolvedPath = path.resolve(manifestDirectory, targetPath);
+    try {
+        if (!(await stat(resolvedPath)).isDirectory()) {
+            throw new Error("not a directory");
+        }
+    }
+    catch {
+        throw new ExternalCorpusManifestError(`Corpus target ${id} directory does not exist.`);
+    }
+    return {
+        id,
+        profile: value.profile,
+        sourceType: value.sourceType,
+        disclosure: "anonymized",
+        path: targetPath,
+        mode: value.mode,
+        contentDigest: value.contentDigest,
+        expectedStatus: value.expectedStatus,
+        reviews,
+        resolvedPath
+    };
+}
+export async function loadExternalCorpusManifest(manifestPath) {
+    let value;
+    try {
+        value = await readJsonFile(path.resolve(manifestPath));
+    }
+    catch {
+        throw new ExternalCorpusManifestError("Corpus manifest could not be read as JSON.");
+    }
+    if (!isRecord(value)) {
+        throw new ExternalCorpusManifestError("Corpus manifest must be an object.");
+    }
+    rejectUnknownKeys(value, topLevelKeys, "Corpus manifest");
+    if (value.schemaVersion !== "1.0.0") {
+        throw new ExternalCorpusManifestError("Unsupported corpus manifest schemaVersion.");
+    }
+    if (!Array.isArray(value.targets) || value.targets.length === 0) {
+        throw new ExternalCorpusManifestError("Corpus manifest targets must be a non-empty array.");
+    }
+    const manifestDirectory = path.dirname(path.resolve(manifestPath));
+    const targets = await Promise.all(value.targets.map((target, index) => parseTarget(target, manifestDirectory, index)));
+    const seenIds = new Set();
+    for (const target of targets) {
+        if (seenIds.has(target.id)) {
+            throw new ExternalCorpusManifestError(`Corpus target id ${target.id} is duplicated.`);
+        }
+        seenIds.add(target.id);
+    }
+    return { schemaVersion: "1.0.0", targets };
+}
+function findingKey(findingId, fingerprint) {
+    return `${findingId}:${fingerprint}`;
+}
+function emptyClassificationCounts() {
+    return {
+        truePositive: 0,
+        falsePositive: 0,
+        unclear: 0,
+        missingExpectedFinding: 0
+    };
+}
+function addClassificationCounts(total, value) {
+    return {
+        truePositive: total.truePositive + value.truePositive,
+        falsePositive: total.falsePositive + value.falsePositive,
+        unclear: total.unclear + value.unclear,
+        missingExpectedFinding: total.missingExpectedFinding + value.missingExpectedFinding
+    };
+}
+async function evaluateExternalCorpusTarget(target, options) {
+    const report = target.mode === "generic-mcp"
+        ? await buildGenericMcpDoctor(target.resolvedPath, options.environment)
+        : await validatePlugin(target.resolvedPath);
+    const packageFingerprint = await buildPackageFingerprint(target.resolvedPath);
+    const findings = report.findings.map((finding) => {
+        if (!finding.fingerprint) {
+            throw new ExternalCorpusManifestError(`Corpus target ${target.id} produced a finding without a fingerprint.`);
+        }
+        return {
+            findingId: finding.id,
+            fingerprint: finding.fingerprint
+        };
+    });
+    const reviewsByKey = new Map(target.reviews.map((review) => [
+        findingKey(review.findingId, review.fingerprint),
+        review
+    ]));
+    const actualKeys = new Set(findings.map((finding) => findingKey(finding.findingId, finding.fingerprint)));
+    const missingExpectedFinding = target.reviews.filter((review) => review.classification === "true_positive" &&
+        !actualKeys.has(findingKey(review.findingId, review.fingerprint))).length;
+    const classifiedFindings = findings
+        .map((finding) => ({
+        ...finding,
+        classification: reviewsByKey.get(findingKey(finding.findingId, finding.fingerprint))?.classification ?? "unreviewed"
+    }))
+        .sort((left, right) => findingKey(left.findingId, left.fingerprint)
+        .localeCompare(findingKey(right.findingId, right.fingerprint)));
+    const classificationCounts = {
+        truePositive: classifiedFindings.filter((finding) => finding.classification === "true_positive").length,
+        falsePositive: classifiedFindings.filter((finding) => finding.classification === "false_positive").length,
+        unclear: classifiedFindings.filter((finding) => finding.classification === "unclear").length,
+        missingExpectedFinding
+    };
+    const digestMatched = packageFingerprint.digest === target.contentDigest;
+    const expectationMatched = digestMatched &&
+        report.status === target.expectedStatus &&
+        classificationCounts.falsePositive === 0 &&
+        classificationCounts.unclear === 0 &&
+        classificationCounts.missingExpectedFinding === 0 &&
+        classifiedFindings.every((finding) => finding.classification !== "unreviewed");
+    return {
+        id: target.id,
+        profile: target.profile,
+        sourceType: target.sourceType,
+        disclosure: target.disclosure,
+        mode: target.mode,
+        expected: {
+            status: target.expectedStatus,
+            contentDigest: target.contentDigest,
+            findings: [...target.reviews].sort((left, right) => findingKey(left.findingId, left.fingerprint)
+                .localeCompare(findingKey(right.findingId, right.fingerprint)))
+        },
+        actual: {
+            status: report.status,
+            contentDigest: packageFingerprint.digest,
+            findings: classifiedFindings
+        },
+        digestMatched,
+        classificationCounts,
+        expectationMatched
+    };
+}
+export async function buildExternalValidationCorpusReport(manifestPath, options = {}) {
+    const manifest = await loadExternalCorpusManifest(manifestPath);
+    const cases = await Promise.all(manifest.targets.map((target) => evaluateExternalCorpusTarget(target, options)));
+    const failedExpectations = cases.filter((result) => !result.expectationMatched).length;
+    const classificationCounts = cases.reduce((total, result) => addClassificationCounts(total, result.classificationCounts), emptyClassificationCounts());
+    return {
+        schemaVersion: "1.0.0",
+        kind: "doctor.validation.corpus",
+        corpusType: "external",
+        generatedAt: new Date().toISOString(),
+        version: packageVersion,
+        summary: {
+            status: failedExpectations === 0 ? "pass" : "fail",
+            caseCount: cases.length,
+            passedExpectations: cases.length - failedExpectations,
+            failedExpectations,
+            runtimeCases: 0,
+            classificationCounts
+        },
+        cases
+    };
+}

package/dist/core/init-git-hooks.js

@@ -1,4 +1,4 @@
-import { chmod, mkdir, stat, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 const isWindows = process.platform === "win32";
 const preCommitHook = isWindows
@@ -81,6 +81,45 @@ async function fileExists(filePath) {
         return false;
     }
 }
+async function resolveHooksDirectory(rootPath) {
+    const dotGitPath = path.join(rootPath, ".git");
+    let dotGitStat;
+    try {
+        dotGitStat = await stat(dotGitPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return path.join(dotGitPath, "hooks");
+        }
+        throw error;
+    }
+    if (dotGitStat.isDirectory()) {
+        return path.join(dotGitPath, "hooks");
+    }
+    let gitFile;
+    try {
+        gitFile = (await readFile(dotGitPath, "utf8")).trim();
+    }
+    catch {
+        throw new Error("Invalid linked-worktree .git file.");
+    }
+    const match = /^gitdir:\s*(.+)$/i.exec(gitFile);
+    if (!match) {
+        throw new Error("Invalid linked-worktree .git file.");
+    }
+    const worktreeGitDir = path.resolve(rootPath, match[1]);
+    let commonDirValue;
+    try {
+        commonDirValue = (await readFile(path.join(worktreeGitDir, "commondir"), "utf8")).trim();
+    }
+    catch {
+        throw new Error("Invalid linked-worktree commondir file.");
+    }
+    if (!commonDirValue) {
+        throw new Error("Invalid linked-worktree commondir file.");
+    }
+    return path.join(path.resolve(worktreeGitDir, commonDirValue), "hooks");
+}
 async function writeHook(hookPath, content, force) {
     const exists = await fileExists(hookPath);
     if (exists && !force) {
@@ -94,14 +133,14 @@ async function writeHook(hookPath, content, force) {
 }
 export async function removeGitHooks(targetPath) {
     const rootPath = path.resolve(targetPath);
-    const hooksDir = path.join(rootPath, ".git", "hooks");
+    const hooksDir = await resolveHooksDirectory(rootPath);
     const hookNames = Array.from(new Set([`pre-commit${hookExtension}`, `pre-push${hookExtension}`, "pre-commit", "pre-push"]));
     const removed = [];
     const skipped = [];
     for (const name of hookNames) {
         const hookPath = path.join(hooksDir, name);
         if (await fileExists(hookPath)) {
-            const content = await import("node:fs/promises").then((m) => m.readFile(hookPath, "utf8"));
+            const content = await readFile(hookPath, "utf8");
             if (content.includes("Generated by codex-plugin-doctor init git-hooks")) {
                 await import("node:fs/promises").then((m) => m.rm(hookPath));
                 removed.push(hookPath);
@@ -115,7 +154,7 @@ export async function removeGitHooks(targetPath) {
 }
 export async function initGitHooks(targetPath, options = {}) {
     const rootPath = path.resolve(targetPath);
-    const hooksDir = path.join(rootPath, ".git", "hooks");
+    const hooksDir = await resolveHooksDirectory(rootPath);
     const force = options.force ?? false;
     await mkdir(hooksDir, { recursive: true });
     const hookPaths = [];

package/dist/core/output-contract.js

@@ -95,6 +95,12 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.validation.corpus",
         required: ["schemaVersion", "kind", "generatedAt", "version", "summary", "cases"]
     },
+    {
+        id: "doctor.validation.corpus.external.json",
+        command: "codex-plugin-doctor doctor corpus --manifest <corpus.json> --json",
+        outputKind: "doctor.validation.corpus",
+        required: ["schemaVersion", "kind", "corpusType", "generatedAt", "version", "summary", "cases"]
+    },
     {
         id: "doctor.recommendations.json",
         command: "codex-plugin-doctor doctor recommend <path> --json",
@@ -115,13 +121,13 @@ const publicSchemaDefinitions = [
         id: "doctor.runtime.plan.json",
         command: "codex-plugin-doctor doctor runtime-plan <path> --json",
         outputKind: "doctor.runtime.plan",
-        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "digest", "summary", "servers", "findings"]
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "execution", "digest", "summary", "servers", "findings"]
     },
     {
         id: "doctor.runtime.policy.json",
         command: "codex-plugin-doctor doctor runtime-policy <path> --json",
         outputKind: "doctor.runtime.policy",
-        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "planDigest", "recommendation", "summary", "servers"]
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "execution", "planDigest", "recommendation", "summary", "servers"]
     },
     {
         id: "doctor.review.bundle.json",

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

@@ -1,6 +1,8 @@
+import type { CheckOptions, CheckResult, RuntimeSandboxMode } from "../domain/types.js";
 export interface ReleaseCheckReport {
     targetPath: string;
     status: "pass" | "fail";
+    runtimeProbeEnabled?: boolean;
     checks: {
         validation: {
             status: string;
@@ -24,12 +26,26 @@ export interface ReleaseCheckReport {
             status: string;
             score: number;
         };
+        metadata?: ReleaseMetadataCheck;
     };
     ready: boolean;
 }
-export declare function buildReleaseCheck(targetPath: string, options?: {
+export interface ReleaseMetadataCheck {
+    status: "pass" | "fail" | "skipped";
+    packageVersion: string | null;
+    lockfileVersion: string | null;
+    changelogVersion: boolean | null;
+    findings: string[];
+}
+export interface BuildReleaseCheckOptions {
     env?: Record<string, string | undefined>;
     platform?: NodeJS.Platform;
-}): Promise<ReleaseCheckReport>;
+    runtime?: boolean;
+    runtimeSandbox?: RuntimeSandboxMode;
+    runCheck?: (targetPath: string, options: CheckOptions) => Promise<CheckResult>;
+}
+export declare function buildReleaseMetadataCheck(targetPath: string): Promise<ReleaseMetadataCheck>;
+export declare function assertReleaseMetadataSync(targetPath: string): Promise<void>;
+export declare function buildReleaseCheck(targetPath: string, options?: BuildReleaseCheckOptions): Promise<ReleaseCheckReport>;
 export declare function renderReleaseCheck(report: ReleaseCheckReport): string;
 export declare function renderReleaseCheckJson(report: ReleaseCheckReport): string;