codex-plugin-doctor 1.4.0 → 1.6.0

package/README.md

@@ -218,6 +218,8 @@ 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-policy .
 codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.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 mcp .
 codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
 codex-plugin-doctor doctor export --bundle .
@@ -289,7 +291,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `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. 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. `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.
+`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. 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, and Markdown summary files. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `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.
 
 `audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
 
@@ -355,9 +357,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.4.0
+      - uses: Esquetta/CodexPluginDoctor@v1.6.0
         with:
-          version: "1.4.0"
+          version: "1.6.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/output-contract.js

@@ -83,6 +83,18 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.runtime.policy",
         required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "status", "exitCode", "runtimeExecution", "planDigest", "recommendation", "summary", "servers"]
     },
+    {
+        id: "doctor.review.bundle.json",
+        command: "codex-plugin-doctor doctor review-bundle <path> --json",
+        outputKind: "doctor.review.bundle",
+        required: ["schemaVersion", "kind", "generatedAt", "version", "targetPath", "outputDirectory", "status", "exitCode", "summary", "files"]
+    },
+    {
+        id: "doctor.review.bundle.verification.json",
+        command: "codex-plugin-doctor doctor review-bundle verify <bundle-dir> --target <path> --json",
+        outputKind: "doctor.review.bundle.verification",
+        required: ["schemaVersion", "kind", "generatedAt", "bundleDirectory", "targetPath", "status", "exitCode", "summary", "checks", "attestation", "releaseEvidence"]
+    },
     {
         id: "doctor.export.bundle.json",
         command: "codex-plugin-doctor doctor export --bundle <path> --json",

package/dist/core/review-bundle.d.ts

@@ -0,0 +1,77 @@
+import { type DoctorAttestationVerificationReport, type DoctorAttestation } from "./attestation.js";
+import { type DoctorReleaseEvidenceReport, type DoctorReleaseEvidenceVerificationReport } from "./release-evidence.js";
+import { type DoctorRuntimePlan } from "./runtime-plan.js";
+import { type DoctorRuntimePolicyReport } from "./runtime-policy.js";
+export interface BuildDoctorReviewBundleOptions {
+    outputDirectory: string;
+    signingKey: string;
+    signingKeyEnv: string;
+    allowDirty?: boolean;
+    allowUntagged?: boolean;
+}
+export interface DoctorReviewBundleManifest {
+    schemaVersion: "1.0.0";
+    kind: "doctor.review.bundle";
+    generatedAt: string;
+    version: string;
+    targetPath: string;
+    outputDirectory: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    summary: {
+        runtimePolicy: DoctorRuntimePolicyReport["recommendation"]["decision"];
+        releaseReady: boolean;
+        attestation: DoctorAttestation["summary"]["status"];
+        releaseEvidence: DoctorReleaseEvidenceReport["status"];
+    };
+    files: {
+        manifest: string;
+        summary: string;
+        runtimePlanJson: string;
+        runtimePlanMarkdown: string;
+        runtimePolicyJson: string;
+        runtimePolicyText: string;
+        attestationJson: string;
+        releaseEvidenceJson: string;
+    };
+}
+export interface DoctorReviewBundle {
+    manifest: DoctorReviewBundleManifest;
+    runtimePlan: DoctorRuntimePlan;
+    runtimePolicy: DoctorRuntimePolicyReport;
+    attestation: DoctorAttestation;
+    releaseEvidence: DoctorReleaseEvidenceReport;
+}
+export interface DoctorReviewBundleVerificationReport {
+    schemaVersion: "1.0.0";
+    kind: "doctor.review.bundle.verification";
+    generatedAt: string;
+    bundleDirectory: string;
+    targetPath: string;
+    status: "pass" | "fail";
+    exitCode: 0 | 1;
+    summary: {
+        manifest: "pass" | "fail";
+        files: "pass" | "fail";
+        runtimePlan: "pass" | "fail";
+        runtimePolicy: "pass" | "fail";
+        attestation: "pass" | "fail";
+        releaseEvidence: "pass" | "fail";
+    };
+    checks: Array<{
+        id: string;
+        status: "pass" | "fail";
+        message: string;
+    }>;
+    attestation: DoctorAttestationVerificationReport | null;
+    releaseEvidence: DoctorReleaseEvidenceVerificationReport | null;
+}
+export declare function buildDoctorReviewBundle(targetPath: string, options: BuildDoctorReviewBundleOptions): Promise<DoctorReviewBundle>;
+export declare function renderDoctorReviewBundleJson(bundle: DoctorReviewBundle): string;
+export declare function verifyDoctorReviewBundle(bundleDirectory: string, options: {
+    signingKey: string;
+    targetPath: string;
+}): Promise<DoctorReviewBundleVerificationReport>;
+export declare function renderDoctorReviewBundleVerificationJson(report: DoctorReviewBundleVerificationReport): string;
+export declare function renderDoctorReviewBundleVerification(report: DoctorReviewBundleVerificationReport): string;
+export declare function renderDoctorReviewBundle(bundle: DoctorReviewBundle): string;

package/dist/core/review-bundle.js

@@ -0,0 +1,327 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { buildDoctorAttestation, renderDoctorAttestationJson, verifyDoctorAttestation } from "./attestation.js";
+import { buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceJson, verifyDoctorReleaseEvidence } from "./release-evidence.js";
+import { buildDoctorRuntimePlan, renderDoctorRuntimePlanJson, renderDoctorRuntimePlanMarkdown } from "./runtime-plan.js";
+import { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./runtime-policy.js";
+import { packageVersion } from "../version.js";
+import { readJsonFile } from "./read-json-file.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDoctorReviewBundleManifest(value) {
+    return isPlainObject(value) &&
+        value.schemaVersion === "1.0.0" &&
+        value.kind === "doctor.review.bundle" &&
+        typeof value.targetPath === "string" &&
+        typeof value.outputDirectory === "string" &&
+        isPlainObject(value.summary) &&
+        isPlainObject(value.files);
+}
+function relativeBundleFiles() {
+    return {
+        manifest: "manifest.json",
+        summary: "summary.md",
+        runtimePlanJson: "runtime-plan.json",
+        runtimePlanMarkdown: "runtime-plan.md",
+        runtimePolicyJson: "runtime-policy.json",
+        runtimePolicyText: "runtime-policy.txt",
+        attestationJson: "attestation.json",
+        releaseEvidenceJson: "release-evidence.json"
+    };
+}
+function bundleStatus(runtimePolicy, releaseEvidence) {
+    if (runtimePolicy.status === "fail" || releaseEvidence.status === "fail") {
+        return "fail";
+    }
+    if (runtimePolicy.status === "warn") {
+        return "warn";
+    }
+    return "pass";
+}
+function renderSummary(bundle) {
+    return [
+        "# Codex Plugin Doctor Review Bundle",
+        "",
+        `- Target: \`${bundle.manifest.targetPath}\``,
+        `- Status: **${bundle.manifest.status.toUpperCase()}**`,
+        `- Runtime policy: \`${bundle.runtimePolicy.recommendation.decision}\``,
+        `- Runtime plan digest: \`${bundle.runtimePlan.digest}\``,
+        `- Release ready: ${bundle.releaseEvidence.releaseReady ? "yes" : "no"}`,
+        `- Attestation: ${bundle.attestation.summary.status.toUpperCase()}`,
+        `- Release evidence: ${bundle.releaseEvidence.status.toUpperCase()}`,
+        "",
+        "## Files",
+        "",
+        `- [Runtime plan JSON](${bundle.manifest.files.runtimePlanJson})`,
+        `- [Runtime plan Markdown](${bundle.manifest.files.runtimePlanMarkdown})`,
+        `- [Runtime policy JSON](${bundle.manifest.files.runtimePolicyJson})`,
+        `- [Runtime policy text](${bundle.manifest.files.runtimePolicyText})`,
+        `- [Attestation JSON](${bundle.manifest.files.attestationJson})`,
+        `- [Release evidence JSON](${bundle.manifest.files.releaseEvidenceJson})`,
+        "",
+        "## Runtime Policy Actions",
+        "",
+        ...bundle.runtimePolicy.recommendation.actions.map((action) => `- ${action}`)
+    ].join("\n");
+}
+async function writeBundleFiles(bundle) {
+    const outputDirectory = bundle.manifest.outputDirectory;
+    const files = bundle.manifest.files;
+    await mkdir(outputDirectory, { recursive: true });
+    await Promise.all([
+        writeFile(path.join(outputDirectory, files.manifest), JSON.stringify(bundle.manifest, null, 2), "utf8"),
+        writeFile(path.join(outputDirectory, files.summary), renderSummary(bundle), "utf8"),
+        writeFile(path.join(outputDirectory, files.runtimePlanJson), renderDoctorRuntimePlanJson(bundle.runtimePlan), "utf8"),
+        writeFile(path.join(outputDirectory, files.runtimePlanMarkdown), renderDoctorRuntimePlanMarkdown(bundle.runtimePlan), "utf8"),
+        writeFile(path.join(outputDirectory, files.runtimePolicyJson), renderDoctorRuntimePolicyJson(bundle.runtimePolicy), "utf8"),
+        writeFile(path.join(outputDirectory, files.runtimePolicyText), renderDoctorRuntimePolicy(bundle.runtimePolicy), "utf8"),
+        writeFile(path.join(outputDirectory, files.attestationJson), renderDoctorAttestationJson(bundle.attestation), "utf8"),
+        writeFile(path.join(outputDirectory, files.releaseEvidenceJson), renderDoctorReleaseEvidenceJson(bundle.releaseEvidence), "utf8")
+    ]);
+}
+export async function buildDoctorReviewBundle(targetPath, options) {
+    const outputDirectory = path.resolve(options.outputDirectory);
+    const releaseEvidenceOptions = {
+        signingKey: options.signingKey,
+        signingKeyEnv: options.signingKeyEnv,
+        allowDirty: options.allowDirty,
+        allowUntagged: options.allowUntagged
+    };
+    const [runtimePlan, runtimePolicy, attestation, releaseEvidence] = await Promise.all([
+        buildDoctorRuntimePlan(targetPath),
+        buildDoctorRuntimePolicyReport(targetPath),
+        buildDoctorAttestation(targetPath, {
+            signingKey: options.signingKey,
+            signingKeyHint: `env:${options.signingKeyEnv}`,
+            recomputeKeyEnv: options.signingKeyEnv
+        }),
+        buildDoctorReleaseEvidenceReport(targetPath, releaseEvidenceOptions)
+    ]);
+    const files = relativeBundleFiles();
+    const status = bundleStatus(runtimePolicy, releaseEvidence);
+    const manifest = {
+        schemaVersion: "1.0.0",
+        kind: "doctor.review.bundle",
+        generatedAt: new Date().toISOString(),
+        version: packageVersion,
+        targetPath: releaseEvidence.targetPath,
+        outputDirectory,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        summary: {
+            runtimePolicy: runtimePolicy.recommendation.decision,
+            releaseReady: releaseEvidence.releaseReady,
+            attestation: attestation.summary.status,
+            releaseEvidence: releaseEvidence.status
+        },
+        files
+    };
+    const bundle = {
+        manifest,
+        runtimePlan,
+        runtimePolicy,
+        attestation,
+        releaseEvidence
+    };
+    await writeBundleFiles(bundle);
+    return bundle;
+}
+export function renderDoctorReviewBundleJson(bundle) {
+    return JSON.stringify(bundle.manifest, null, 2);
+}
+async function readBundleJsonFile(bundleDirectory, relativePath) {
+    return readJsonFile(path.join(bundleDirectory, relativePath));
+}
+export async function verifyDoctorReviewBundle(bundleDirectory, options) {
+    const resolvedBundleDirectory = path.resolve(bundleDirectory);
+    const targetPath = path.resolve(options.targetPath);
+    const checks = [];
+    let manifest = null;
+    let runtimePlanStatus = "fail";
+    let runtimePolicyStatus = "fail";
+    let attestation = null;
+    let releaseEvidence = null;
+    try {
+        const manifestArtifact = await readBundleJsonFile(resolvedBundleDirectory, "manifest.json");
+        if (isDoctorReviewBundleManifest(manifestArtifact)) {
+            manifest = manifestArtifact;
+            checks.push({
+                id: "review_bundle.manifest.valid",
+                status: "pass",
+                message: "The review bundle manifest has the expected schema and kind."
+            });
+        }
+        else {
+            checks.push({
+                id: "review_bundle.manifest.valid",
+                status: "fail",
+                message: "The review bundle manifest is missing or invalid."
+            });
+        }
+    }
+    catch {
+        checks.push({
+            id: "review_bundle.manifest.valid",
+            status: "fail",
+            message: "The review bundle manifest could not be read."
+        });
+    }
+    const files = manifest?.files ?? relativeBundleFiles();
+    for (const [fileKey, relativePath] of Object.entries(files)) {
+        try {
+            const fileStat = await stat(path.join(resolvedBundleDirectory, relativePath));
+            checks.push({
+                id: `review_bundle.file.${fileKey}`,
+                status: fileStat.isFile() ? "pass" : "fail",
+                message: fileStat.isFile()
+                    ? `${relativePath} is present.`
+                    : `${relativePath} is not a regular file.`
+            });
+        }
+        catch {
+            checks.push({
+                id: `review_bundle.file.${fileKey}`,
+                status: "fail",
+                message: `${relativePath} is missing.`
+            });
+        }
+    }
+    try {
+        const runtimePlan = await readBundleJsonFile(resolvedBundleDirectory, files.runtimePlanJson);
+        runtimePlanStatus = isPlainObject(runtimePlan) && runtimePlan.kind === "doctor.runtime.plan" ? "pass" : "fail";
+        checks.push({
+            id: "review_bundle.runtime_plan",
+            status: runtimePlanStatus,
+            message: runtimePlanStatus === "pass"
+                ? "The runtime plan artifact has the expected kind."
+                : "The runtime plan artifact is invalid."
+        });
+    }
+    catch {
+        checks.push({
+            id: "review_bundle.runtime_plan",
+            status: "fail",
+            message: "The runtime plan artifact could not be read."
+        });
+    }
+    try {
+        const runtimePolicy = await readBundleJsonFile(resolvedBundleDirectory, files.runtimePolicyJson);
+        runtimePolicyStatus = isPlainObject(runtimePolicy) && runtimePolicy.kind === "doctor.runtime.policy" ? "pass" : "fail";
+        checks.push({
+            id: "review_bundle.runtime_policy",
+            status: runtimePolicyStatus,
+            message: runtimePolicyStatus === "pass"
+                ? "The runtime policy artifact has the expected kind."
+                : "The runtime policy artifact is invalid."
+        });
+    }
+    catch {
+        checks.push({
+            id: "review_bundle.runtime_policy",
+            status: "fail",
+            message: "The runtime policy artifact could not be read."
+        });
+    }
+    try {
+        attestation = await verifyDoctorAttestation(path.join(resolvedBundleDirectory, files.attestationJson), targetPath, { signingKey: options.signingKey });
+        checks.push({
+            id: "review_bundle.attestation",
+            status: attestation.status,
+            message: attestation.status === "pass"
+                ? "The bundled attestation verifies against the target package."
+                : "The bundled attestation does not verify against the target package."
+        });
+    }
+    catch {
+        checks.push({
+            id: "review_bundle.attestation",
+            status: "fail",
+            message: "The bundled attestation could not be verified."
+        });
+    }
+    try {
+        releaseEvidence = await verifyDoctorReleaseEvidence(path.join(resolvedBundleDirectory, files.releaseEvidenceJson), {
+            signingKey: options.signingKey,
+            targetPath
+        });
+        checks.push({
+            id: "review_bundle.release_evidence",
+            status: releaseEvidence.status,
+            message: releaseEvidence.status === "pass"
+                ? "The bundled release evidence verifies against the target package."
+                : "The bundled release evidence does not verify against the target package."
+        });
+    }
+    catch {
+        checks.push({
+            id: "review_bundle.release_evidence",
+            status: "fail",
+            message: "The bundled release evidence could not be verified."
+        });
+    }
+    const failedChecks = checks.filter((check) => check.status === "fail");
+    const fileChecks = checks.filter((check) => check.id.startsWith("review_bundle.file."));
+    const manifestStatus = checks.find((check) => check.id === "review_bundle.manifest.valid")?.status ?? "fail";
+    return {
+        schemaVersion: "1.0.0",
+        kind: "doctor.review.bundle.verification",
+        generatedAt: new Date().toISOString(),
+        bundleDirectory: resolvedBundleDirectory,
+        targetPath,
+        status: failedChecks.length === 0 ? "pass" : "fail",
+        exitCode: failedChecks.length === 0 ? 0 : 1,
+        summary: {
+            manifest: manifestStatus,
+            files: fileChecks.every((check) => check.status === "pass") ? "pass" : "fail",
+            runtimePlan: runtimePlanStatus,
+            runtimePolicy: runtimePolicyStatus,
+            attestation: attestation?.status ?? "fail",
+            releaseEvidence: releaseEvidence?.status ?? "fail"
+        },
+        checks,
+        attestation,
+        releaseEvidence
+    };
+}
+export function renderDoctorReviewBundleVerificationJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorReviewBundleVerification(report) {
+    const lines = [
+        "Doctor Review Bundle Verification",
+        "=================================",
+        `Bundle: ${report.bundleDirectory}`,
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Manifest: ${report.summary.manifest.toUpperCase()}`,
+        `Files: ${report.summary.files.toUpperCase()}`,
+        `Runtime plan: ${report.summary.runtimePlan.toUpperCase()}`,
+        `Runtime policy: ${report.summary.runtimePolicy.toUpperCase()}`,
+        `Attestation: ${report.summary.attestation.toUpperCase()}`,
+        `Release evidence: ${report.summary.releaseEvidence.toUpperCase()}`,
+        "",
+        "Checks",
+        "------"
+    ];
+    for (const check of report.checks) {
+        lines.push(`${check.status === "pass" ? "PASS" : "FAIL"} ${check.id}`);
+        lines.push(`  ${check.message}`);
+    }
+    return lines.join("\n");
+}
+export function renderDoctorReviewBundle(bundle) {
+    return [
+        "Doctor Review Bundle",
+        "====================",
+        `Target: ${bundle.manifest.targetPath}`,
+        `Output: ${bundle.manifest.outputDirectory}`,
+        `Status: ${bundle.manifest.status.toUpperCase()}`,
+        `Runtime policy: ${bundle.manifest.summary.runtimePolicy}`,
+        `Release ready: ${bundle.manifest.summary.releaseReady ? "yes" : "no"}`,
+        "",
+        "Files",
+        "-----",
+        ...Object.values(bundle.manifest.files).map((file) => `- ${file}`)
+    ].join("\n");
+}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnal
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";
 export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed, type DoctorRuntimePlan, type RuntimeApprovalReport, type RuntimePlanServer } from "./core/runtime-plan.js";
 export { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson, type DoctorRuntimePolicyReport, type RuntimePolicyDecision, type RuntimePolicyRecommendation } from "./core/runtime-policy.js";
+export { buildDoctorReviewBundle, renderDoctorReviewBundle, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle, type BuildDoctorReviewBundleOptions, type DoctorReviewBundle, type DoctorReviewBundleManifest, type DoctorReviewBundleVerificationReport } from "./core/review-bundle.js";
 export { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence, type BuildDoctorReleaseEvidenceOptions, type DoctorReleaseEvidenceAssetReport, type DoctorReleaseEvidenceGitMetadata, type DoctorReleaseEvidencePackageMetadata, type DoctorReleaseEvidenceReport, type DoctorReleaseEvidenceVerificationReport } from "./core/release-evidence.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson, type BuildDoctorNpmPackageReportOptions, type DoctorNpmPackageReport } from "./core/npm-package-doctor.js";
 export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson, type BuildDoctorRiskDiffReportOptions, type DoctorRiskDiffReport, type RiskDiffFinding, type RiskFindingCategory } from "./core/risk-diff.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnal
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 export { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
 export { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./core/runtime-policy.js";
+export { buildDoctorReviewBundle, renderDoctorReviewBundle, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle } from "./core/review-bundle.js";
 export { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence } from "./core/release-evidence.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 export { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";

package/dist/run-cli.js

@@ -22,6 +22,7 @@ import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, re
 import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 import { buildDoctorRuntimePlan, evaluateRuntimeApproval, renderDoctorRuntimePlan, renderDoctorRuntimePlanMarkdown, renderDoctorRuntimePlanJson, runtimeApprovalPassed } from "./core/runtime-plan.js";
 import { buildDoctorRuntimePolicyReport, renderDoctorRuntimePolicy, renderDoctorRuntimePolicyJson } from "./core/runtime-policy.js";
+import { buildDoctorReviewBundle, renderDoctorReviewBundle, renderDoctorReviewBundleJson, renderDoctorReviewBundleVerification, renderDoctorReviewBundleVerificationJson, verifyDoctorReviewBundle } from "./core/review-bundle.js";
 import { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence } from "./core/release-evidence.js";
 import { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 import { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
@@ -72,7 +73,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
 }
 const performanceStageNames = new Set([
     "validation",
@@ -412,6 +413,99 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStdout(renderedReport);
             return report.exitCode;
         }
+        if (maybePath === "review-bundle") {
+            if (remainingArgs[0] === "verify") {
+                const bundleDirectory = remainingArgs[1] && !remainingArgs[1].startsWith("--")
+                    ? remainingArgs[1]
+                    : null;
+                const verifyFlags = bundleDirectory ? remainingArgs.slice(2) : remainingArgs.slice(1);
+                const jsonOutput = verifyFlags.includes("--json");
+                const targetIndex = verifyFlags.indexOf("--target");
+                const targetPath = targetIndex === -1 ? null : verifyFlags[targetIndex + 1];
+                const signKeyEnvIndex = verifyFlags.indexOf("--sign-key-env");
+                const signKeyEnv = signKeyEnvIndex === -1 ? null : verifyFlags[signKeyEnvIndex + 1];
+                if (!bundleDirectory) {
+                    io.writeStderr("Missing review bundle directory.");
+                    return 2;
+                }
+                if (targetIndex === -1) {
+                    io.writeStderr("Missing target path. Use --target <path>.");
+                    return 2;
+                }
+                if (!targetPath || targetPath.startsWith("--")) {
+                    io.writeStderr("Missing path after --target.");
+                    return 2;
+                }
+                if (signKeyEnvIndex === -1) {
+                    io.writeStderr("Missing signing key. Use --sign-key-env <name>.");
+                    return 2;
+                }
+                if (!signKeyEnv || signKeyEnv.startsWith("--")) {
+                    io.writeStderr("Missing environment variable name after --sign-key-env.");
+                    return 2;
+                }
+                const signingKey = terminalContext.env[signKeyEnv];
+                if (!signingKey) {
+                    io.writeStderr(`Signing key environment variable is not set: ${signKeyEnv}`);
+                    return 2;
+                }
+                const report = await verifyDoctorReviewBundle(bundleDirectory, {
+                    signingKey,
+                    targetPath
+                });
+                io.writeStdout(jsonOutput
+                    ? renderDoctorReviewBundleVerificationJson(report)
+                    : renderDoctorReviewBundleVerification(report));
+                return report.exitCode;
+            }
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : null;
+            const reviewBundleFlags = targetPath ? remainingArgs.slice(1) : remainingArgs;
+            const jsonOutput = reviewBundleFlags.includes("--json");
+            const outputIndex = reviewBundleFlags.indexOf("--output");
+            const outputDirectory = outputIndex === -1 ? null : reviewBundleFlags[outputIndex + 1];
+            const signKeyEnvIndex = reviewBundleFlags.indexOf("--sign-key-env");
+            const signKeyEnv = signKeyEnvIndex === -1 ? null : reviewBundleFlags[signKeyEnvIndex + 1];
+            const allowDirty = reviewBundleFlags.includes("--allow-dirty");
+            const allowUntagged = reviewBundleFlags.includes("--allow-untagged");
+            if (!targetPath) {
+                io.writeStderr("Missing target path for review bundle.");
+                return 2;
+            }
+            if (outputIndex === -1) {
+                io.writeStderr("Missing output directory. Use --output <dir>.");
+                return 2;
+            }
+            if (!outputDirectory || outputDirectory.startsWith("--")) {
+                io.writeStderr("Missing directory after --output.");
+                return 2;
+            }
+            if (signKeyEnvIndex === -1) {
+                io.writeStderr("Missing signing key. Use --sign-key-env <name>.");
+                return 2;
+            }
+            if (!signKeyEnv || signKeyEnv.startsWith("--")) {
+                io.writeStderr("Missing environment variable name after --sign-key-env.");
+                return 2;
+            }
+            const signingKey = terminalContext.env[signKeyEnv];
+            if (!signingKey) {
+                io.writeStderr(`Signing key environment variable is not set: ${signKeyEnv}`);
+                return 2;
+            }
+            const bundle = await buildDoctorReviewBundle(targetPath, {
+                outputDirectory,
+                signingKey,
+                signingKeyEnv: signKeyEnv,
+                allowDirty,
+                allowUntagged
+            });
+            io.writeStdout(jsonOutput
+                ? renderDoctorReviewBundleJson(bundle)
+                : renderDoctorReviewBundle(bundle));
+            return bundle.manifest.exitCode;
+        }
         if (maybePath === "release-evidence") {
             if (remainingArgs[0] === "asset") {
                 const targetPath = remainingArgs[1] && !remainingArgs[1].startsWith("--")

package/package.json

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