codex-plugin-doctor 1.68.0 → 1.69.1

package/README.md

@@ -120,7 +120,7 @@ codex-plugin-doctor doctor tools-diff --before ./tools-old.json --after ./tools-
 This reports added, removed, and structurally changed definitions using numeric
 locations, and labels each change `breaking`, `compatible`, or `unclassified`
 with fixed reason codes. Add `--fail-on breaking` to fail CI only on breaking or
-unclassified changes. Incomplete inputs, invalid definitions, or duplicate names
+unclassified changes, and `--markdown` for pull request tables. Incomplete inputs, invalid definitions, or duplicate names
 prevent a comparison. Impact labels follow nested object properties, array
 items, and common length and range bounds, but remain heuristics, not proof of
 compatibility.
@@ -141,10 +141,13 @@ and partial inspection limits. It does not claim full schema validation, tool
 execution, or client compatibility. Existing `doctor discover` behavior is unchanged.
 Add `--save-response <path>` to record a completely enumerated catalog as a
 `tools/list` response for `tools-file` and `tools-diff`; nothing is written when
-enumeration is incomplete. The GitHub Action can compare saved responses with
+enumeration is incomplete. For protected servers, `--bearer-token-env <NAME>`
+sends a bearer token from an environment variable only over HTTPS or to an
+approved loopback endpoint; it is never printed or saved. The GitHub Action can compare saved responses with
 `tools-diff-before`, `tools-diff-after`, and `tools-diff-fail-on`, capture the
-live list with `tools-capture-url`, and skip the plugin package check with
-`check: "false"` in repositories that only ship an MCP server.
+live list with `tools-capture-url` (and `tools-capture-token-env`), and skip the
+plugin package check with `check: "false"` in repositories that only ship an MCP
+server.
 See [HTTP MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
 
 ### Remote MCP Readiness
@@ -565,9 +568,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.68.0
+      - uses: Esquetta/CodexPluginDoctor@v1.69.1
         with:
-          version: "1.68.0"
+          version: "1.69.1"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/bounded-http-client.d.ts

@@ -7,17 +7,20 @@ export interface BoundedHttpRequestOptions {
     method?: string;
     body?: string | Buffer;
     headers?: Record<string, string | undefined>;
+    bearerToken?: string;
     stopAfter?: (body: Buffer) => boolean;
 }
+/** RFC 6750 b64token syntax, which also rules out header injection. */
+export declare function isValidBearerToken(token: string): boolean;
 export interface BoundedHttpResponse {
     statusCode: number;
     headers: Record<string, string | string[]>;
     body: Buffer;
 }
 export declare class BoundedHttpError extends Error {
-    readonly code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED";
+    readonly code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_INSECURE_CREDENTIALS" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED";
     readonly statusCode?: number | undefined;
     readonly headers?: Record<string, string | string[]> | undefined;
-    constructor(code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED", message: string, statusCode?: number | undefined, headers?: Record<string, string | string[]> | undefined);
+    constructor(code: "REMOTE_HTTP_ENCODING_UNSUPPORTED" | "REMOTE_HTTP_HEADER_FORBIDDEN" | "REMOTE_HTTP_INSECURE_CREDENTIALS" | "REMOTE_HTTP_OPTIONS_INVALID" | "REMOTE_HTTP_PEER_MISMATCH" | "REMOTE_HTTP_REDIRECT" | "REMOTE_HTTP_REQUEST_FAILED" | "REMOTE_HTTP_RESPONSE_TOO_LARGE" | "REMOTE_HTTP_STOP_CONDITION_FAILED" | "REMOTE_HTTP_TIMEOUT" | "REMOTE_HTTP_URL_CREDENTIALS" | "REMOTE_HTTP_URL_UNSUPPORTED", message: string, statusCode?: number | undefined, headers?: Record<string, string | string[]> | undefined);
 }
 export declare function requestBoundedHttp(rawUrl: string, options?: BoundedHttpRequestOptions): Promise<BoundedHttpResponse>;

package/dist/core/bounded-http-client.js

@@ -20,6 +20,11 @@ const safeResponseHeaders = new Set([
     "mcp-protocol-version",
     "location"
 ]);
+const MAX_BEARER_TOKEN_LENGTH = 4_096;
+/** RFC 6750 b64token syntax, which also rules out header injection. */
+export function isValidBearerToken(token) {
+    return token.length > 0 && token.length <= MAX_BEARER_TOKEN_LENGTH && /^[A-Za-z0-9\-._~+/]+=*$/u.test(token);
+}
 export class BoundedHttpError extends Error {
     code;
     statusCode;
@@ -127,8 +132,17 @@ export async function requestBoundedHttp(rawUrl, options = {}) {
     }
     const { timeoutMs, maxResponseBytes } = validateOptions(options);
     const headers = validateHeaders(options.headers);
+    if (options.bearerToken !== undefined && !isValidBearerToken(options.bearerToken)) {
+        throw new BoundedHttpError("REMOTE_HTTP_OPTIONS_INVALID", "Remote HTTP bearer token is invalid.");
+    }
     const deadline = Date.now() + timeoutMs;
     const target = await resolveWithinDeadline(url, options, timeoutMs);
+    if (options.bearerToken !== undefined) {
+        if (url.protocol !== "https:" && !target.local) {
+            throw new BoundedHttpError("REMOTE_HTTP_INSECURE_CREDENTIALS", "Remote HTTP bearer tokens require HTTPS or an approved loopback target.");
+        }
+        headers.authorization = `Bearer ${options.bearerToken}`;
+    }
     const remainingMs = deadline - Date.now();
     if (remainingMs <= 0) {
         throw new BoundedHttpError("REMOTE_HTTP_TIMEOUT", "Remote HTTP request timed out.");

package/dist/core/mcp-discovery.d.ts

@@ -9,6 +9,7 @@ export interface McpDiscoveryOptions {
     requestTimeoutMs?: number;
     lookup?: RemoteLookup;
     request?: RemoteMcpRequest;
+    bearerToken?: string;
 }
 export interface McpDiscoveryReport {
     schemaVersion: 1;

package/dist/core/mcp-discovery.js

@@ -125,7 +125,7 @@ export async function discoverMcpServer(rawUrl, options = {}) {
     try {
         response = await request(rawUrl, {
             allowLocalNetwork: options.allowLocalNetwork, lookup: options.lookup, timeoutMs: options.requestTimeoutMs,
-            method: "POST", body,
+            method: "POST", body, bearerToken: options.bearerToken,
             headers: { Accept: "application/json, text/event-stream", "Content-Type": "application/json", "MCP-Protocol-Version": REQUESTED_VERSION, "Mcp-Method": "server/discover" },
             stopAfter: (received) => findMcpSseResponse(received) !== null
         });
@@ -134,10 +134,15 @@ export async function discoverMcpServer(rawUrl, options = {}) {
         if (error instanceof RemoteNetworkPolicyError) {
             return report("blocked", "skipped", [finding("plugin.discovery.network.blocked", "warn", "The MCP discovery target is blocked by the remote network policy.", "Discovery could not safely reach the configured target.", "Use an endpoint permitted by the remote network policy.")]);
         }
+        if (error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_INSECURE_CREDENTIALS") {
+            return report("blocked", "skipped", [finding("plugin.discovery.credentials.insecure_transport", "warn", "The bearer token was not sent because the endpoint is neither HTTPS nor an approved loopback target.", "Sending a token over plain HTTP would expose it to the network.", "Use an HTTPS endpoint, or a loopback endpoint with local network access approved.")]);
+        }
         return failureReport(error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_TIMEOUT" ? "plugin.discovery.transport.timeout" : "plugin.discovery.transport.failed", "The MCP discovery request did not complete within the configured transport bounds.");
     }
     if (response.statusCode === 401 || response.statusCode === 403) {
-        return unsupportedReport("plugin.discovery.authorization.required", "The MCP endpoint requires authorization before discovery can be assessed.");
+        return options.bearerToken === undefined
+            ? unsupportedReport("plugin.discovery.authorization.required", "The MCP endpoint requires authorization before discovery can be assessed.")
+            : unsupportedReport("plugin.discovery.authorization.rejected", "The MCP endpoint rejected the supplied bearer token.");
     }
     const message = parseMcpResponse(response);
     if (!message || !hasMatchingResponseEnvelope(message))

package/dist/core/mcp-tool-catalog.d.ts

@@ -10,6 +10,7 @@ export interface McpToolCatalogOptions {
     lookup?: RemoteLookup;
     request?: RemoteMcpRequest;
     now?: () => number;
+    bearerToken?: string;
 }
 export interface McpToolCatalogReport {
     schemaVersion: 1;

package/dist/core/mcp-tool-catalog.js

@@ -71,7 +71,7 @@ function finalStatus(findings) {
             : "pass";
 }
 function isAuthorizationFinding(discovery) {
-    return discovery.findings.some((item) => item.id === "plugin.discovery.authorization.required");
+    return discovery.findings.some((item) => item.id === "plugin.discovery.authorization.required" || item.id === "plugin.discovery.authorization.rejected");
 }
 function requestBody(id, cursor) {
     return JSON.stringify({
@@ -128,6 +128,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
         allowNetwork: options.allowNetwork,
         allowLocalNetwork: options.allowLocalNetwork,
         lookup: options.lookup,
+        bearerToken: options.bearerToken,
         request: async (url, requestOptions) => {
             const response = await requestWithinBudget(url, requestOptions);
             discoveryResponse = response;
@@ -137,7 +138,10 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
     const partial = (report) => ({ report, tools: null, cache: null });
     const emptyCatalog = { complete: false, pagesRead: 0, toolsChecked: 0, reason: null };
     if (discovery.status === "blocked") {
-        return partial(catalogReport(discovery, "blocked", { ...emptyCatalog, reason: "network-blocked" }, "not-tested", []));
+        const reason = discovery.findings.some((item) => item.id === "plugin.discovery.credentials.insecure_transport")
+            ? "credentials-insecure-transport"
+            : "network-blocked";
+        return partial(catalogReport(discovery, "blocked", { ...emptyCatalog, reason }, "not-tested", []));
     }
     if (isAuthorizationFinding(discovery)) {
         return partial(catalogReport(discovery, "incomplete", { ...emptyCatalog, reason: "authorization-required" }, "not-tested", []));
@@ -189,6 +193,7 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
             response = await requestWithinBudget(rawUrl, {
                 allowLocalNetwork: options.allowLocalNetwork,
                 lookup: options.lookup,
+                bearerToken: options.bearerToken,
                 method: "POST",
                 body: requestBody(requestId, cursor),
                 headers: {
@@ -205,11 +210,13 @@ export async function captureMcpToolCatalog(rawUrl, options = {}) {
                 blocked = true;
             }
             else {
-                incompleteReason = budgetReason ?? (error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_TIMEOUT"
-                    ? "request-timeout"
-                    : error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_RESPONSE_TOO_LARGE"
-                        ? "response-byte-limit"
-                        : "request-failed");
+                incompleteReason = budgetReason ?? (error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_INSECURE_CREDENTIALS"
+                    ? "credentials-insecure-transport"
+                    : error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_TIMEOUT"
+                        ? "request-timeout"
+                        : error instanceof BoundedHttpError && error.code === "REMOTE_HTTP_RESPONSE_TOO_LARGE"
+                            ? "response-byte-limit"
+                            : "request-failed");
             }
             break;
         }

package/dist/core/mcp-tool-impact.js

@@ -34,6 +34,9 @@ const NESTED_STRUCTURAL_KEYWORDS = new Set([
 ]);
 // Subschemas nested deeper than this below the root are not compared and stay unclassified.
 const MAX_NESTED_DEPTH = 8;
+// Keywords that only hold or name subschemas and never validate the object's own keys, so a
+// new property beside them stays compatible. Any other unclassified keyword may govern keys.
+const DEFINITION_KEYWORDS = new Set(["$defs", "definitions", "$id", "$anchor", "$dynamicAnchor"]);
 const CODES = {
     input: {
         unclassified: "input-schema-unclassified",
@@ -197,13 +200,14 @@ function compareSchema(before, after, direction, depth, equal, reasons) {
         else
             compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons);
     }
-    // In a nested object whose undeclared keys were open or governed by other keywords, a newly
-    // declared property can reject values callers send (input) or produce values consumers did
-    // not expect (output).
+    // In an object whose undeclared keys were governed by other keywords, or a nested input object
+    // that left them open, a newly declared property can reject values callers send (input) or
+    // produce values consumers did not expect (output).
     const addedKeys = Object.keys(afterProperties).filter((key) => !Object.hasOwn(beforeProperties, key));
-    if (!root && addedKeys.length > 0) {
-        const governed = isJsonObject(before.additionalProperties) || Object.keys(keywordsOutside(before, structural)).length > 0;
-        const open = Object.keys(beforeProperties).length === 0 && before.additionalProperties !== false;
+    if (addedKeys.length > 0) {
+        const governed = isJsonObject(before.additionalProperties)
+            || Object.keys(keywordsOutside(before, structural)).some((key) => !DEFINITION_KEYWORDS.has(key));
+        const open = !root && Object.keys(beforeProperties).length === 0 && before.additionalProperties !== false;
         if (governed || (direction === "input" && open))
             reasons.add(codes.unclassified);
     }

package/dist/reporting/render-mcp-tool-diff-markdown.d.ts

@@ -0,0 +1,2 @@
+import type { McpToolDiffReport } from "../core/mcp-tool-diff.js";
+export declare function renderMcpToolDiffMarkdown(report: McpToolDiffReport): string;

package/dist/reporting/render-mcp-tool-diff-markdown.js

@@ -0,0 +1,33 @@
+function count(value) {
+    return value === null || value === undefined ? "not compared" : String(value);
+}
+function toolIndex(value) {
+    return value === null ? "-" : String(value);
+}
+export function renderMcpToolDiffMarkdown(report) {
+    const comparison = report.comparison;
+    const lines = [
+        "## MCP Tool Definition Diff",
+        "",
+        `**Status:** \`${report.status}\` · **Comparison complete:** ${comparison.complete ? "yes" : "no"}${comparison.reason === null ? "" : ` · **Reason:** \`${comparison.reason}\``}`,
+        "",
+        "| Added | Removed | Changed | Unchanged | Breaking | Unclassified |",
+        "| --- | --- | --- | --- | --- | --- |",
+        `| ${count(comparison.added)} | ${count(comparison.removed)} | ${count(comparison.changed)} | ${count(comparison.unchanged)} | ${count(comparison.breaking)} | ${count(comparison.unclassified)} |`
+    ];
+    if (report.changes.length > 0) {
+        lines.push("", "### Changes", "", "| Change | Before tool | After tool | Fields | Impact | Reasons |", "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind} | ${toolIndex(change.beforeToolIndex)} | ${toolIndex(change.afterToolIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+    }
+    const findings = ["before", "after"].flatMap((side) => report[side].findings.map((finding) => {
+        const location = finding.location;
+        const locator = location
+            ? `${side} tool ${location.toolIndex}${location.schema ? `, ${location.schema}` : ""}${location.relatedToolIndex ? `, related tool ${location.relatedToolIndex}` : ""}`
+            : side;
+        return `| ${finding.severity} | \`${finding.id}\` | ${locator} | ${finding.message} |`;
+    }));
+    if (findings.length > 0) {
+        lines.push("", "### Input Findings", "", "| Severity | Finding | Location | Message |", "| --- | --- | --- | --- |", ...findings);
+    }
+    lines.push("", `Tool numbers are one-based positions in the before and after files; names and schema values are not reported. Impact labels are ${report.coverage.impactClassification} schema checks, not proof of compatibility.`);
+    return lines.join("\n");
+}

package/dist/run-cli.js

@@ -21,11 +21,13 @@ import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 import { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./core/submission-archive-preflight.js";
 import { buildSubmissionPreflight } from "./core/submission-preflight.js";
+import { isValidBearerToken } from "./core/bounded-http-client.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { captureMcpToolCatalog, inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
 import { inspectMcpToolFile, isBlockedOfflinePath } from "./core/mcp-tool-file.js";
 import { saveMcpToolsListResponse } from "./core/mcp-tool-response-file.js";
 import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
+import { renderMcpToolDiffMarkdown } from "./reporting/render-mcp-tool-diff-markdown.js";
 import { renderMcpToolDiffReport } from "./reporting/render-mcp-tool-diff-report.js";
 import { renderMcpToolFileReport } from "./reporting/render-mcp-tool-file-report.js";
 import { renderMcpToolCatalogReport } from "./reporting/render-mcp-tool-catalog-report.js";
@@ -108,10 +110,24 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
-const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json] [--fail-on any|breaking]";
+const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json|--markdown] [--fail-on any|breaking]";
 const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
-const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>]";
-const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json]";
+const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>] [--bearer-token-env <NAME>]";
+const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json] [--bearer-token-env <NAME>]";
+const bearerTokenHelp = "--bearer-token-env reads a bearer token from the named environment variable and sends it only over HTTPS or to an approved loopback target; the token is never printed or saved.";
+const ENVIRONMENT_VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+function resolveBearerToken(name, env) {
+    if (name === undefined)
+        return {};
+    if (!ENVIRONMENT_VARIABLE_NAME.test(name))
+        return { error: "--bearer-token-env requires an environment variable name." };
+    const token = env[name];
+    if (token === undefined || token === "")
+        return { error: `Bearer token environment variable is not set: ${name}` };
+    if (!isValidBearerToken(token))
+        return { error: `Bearer token environment variable does not hold a valid bearer token: ${name}` };
+    return { token };
+}
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     const index = flags.indexOf("--sandbox");
     if (index === -1) {
@@ -1215,13 +1231,13 @@ export async function runCli(args, io = defaultIo, options = {}) {
             }
             let beforePath;
             let afterPath;
-            let json = false;
+            let format;
             let failOn;
             let invalid = false;
             for (let index = 0; index < remainingArgs.length; index += 1) {
                 const flag = remainingArgs[index];
-                if (flag === "--json" && !json) {
-                    json = true;
+                if ((flag === "--json" || flag === "--markdown") && format === undefined) {
+                    format = flag === "--json" ? "json" : "markdown";
                 }
                 else if (flag === "--fail-on" && failOn === undefined) {
                     const value = remainingArgs[index + 1];
@@ -1254,7 +1270,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 return 2;
             }
             const report = await (options.compareMcpToolFilesImpl ?? compareMcpToolFiles)(beforePath, afterPath);
-            io.writeStdout(json ? JSON.stringify(report, null, 2) : renderMcpToolDiffReport(report));
+            io.writeStdout(format === "json" ? JSON.stringify(report, null, 2)
+                : format === "markdown" ? renderMcpToolDiffMarkdown(report)
+                    : renderMcpToolDiffReport(report));
             if (report.status !== "pass" && report.status !== "warn")
                 return 2;
             if (failOn === "breaking") {
@@ -1281,7 +1299,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         if (maybePath === "tools") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
-                io.writeStdout(`${toolsUsage}\nHTTP tool catalog structure only; tools are not executed.\n--save-response writes a complete enumeration as one tools/list response for doctor tools-file and tools-diff; nothing is written when enumeration is incomplete.`);
+                io.writeStdout(`${toolsUsage}\nHTTP tool catalog structure only; tools are not executed.\n--save-response writes a complete enumeration as one tools/list response for doctor tools-file and tools-diff; nothing is written when enumeration is incomplete.\n${bearerTokenHelp}`);
                 return 0;
             }
             const [url, ...flags] = remainingArgs;
@@ -1292,16 +1310,20 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
             const switches = [];
             let savePath;
+            let tokenEnv;
             let invalid = false;
             for (let index = 0; index < flags.length; index += 1) {
                 const flag = flags[index];
-                if (flag === "--save-response" && savePath === undefined) {
+                if ((flag === "--save-response" && savePath === undefined) || (flag === "--bearer-token-env" && tokenEnv === undefined)) {
                     const value = flags[index + 1];
                     if (!value || value.startsWith("-")) {
                         invalid = true;
                         break;
                     }
-                    savePath = value;
+                    if (flag === "--save-response")
+                        savePath = value;
+                    else
+                        tokenEnv = value;
                     index += 1;
                 }
                 else if (allowedFlags.has(flag) && !switches.includes(flag)) {
@@ -1324,7 +1346,16 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr("doctor tools --save-response requires a local file path.");
                 return 2;
             }
-            const catalogOptions = { allowNetwork: true, allowLocalNetwork: switches.includes("--allow-local-network") };
+            const bearer = resolveBearerToken(tokenEnv, terminalContext.env);
+            if ("error" in bearer) {
+                io.writeStderr(bearer.error);
+                return 2;
+            }
+            const catalogOptions = {
+                allowNetwork: true,
+                allowLocalNetwork: switches.includes("--allow-local-network"),
+                ...(bearer.token === undefined ? {} : { bearerToken: bearer.token })
+            };
             const snapshot = savePath === undefined
                 ? { report: await (options.inspectMcpToolCatalogImpl ?? inspectMcpToolCatalog)(url, catalogOptions), tools: null, cache: null }
                 : await (options.captureMcpToolCatalogImpl ?? captureMcpToolCatalog)(url, catalogOptions);
@@ -1355,7 +1386,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         if (maybePath === "discover") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
-                io.writeStdout(`${discoveryUsage}\nHTTP discovery only; runtime behavior is not tested.`);
+                io.writeStdout(`${discoveryUsage}\nHTTP discovery only; runtime behavior is not tested.\n${bearerTokenHelp}`);
                 return 0;
             }
             const [url, ...flags] = remainingArgs;
@@ -1364,19 +1395,47 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 return 2;
             }
             const allowedFlags = new Set(["--allow-network", "--allow-local-network", "--json"]);
-            if (flags.some((flag) => !allowedFlags.has(flag)) || new Set(flags).size !== flags.length) {
+            const switches = [];
+            let tokenEnv;
+            let invalid = false;
+            for (let index = 0; index < flags.length; index += 1) {
+                const flag = flags[index];
+                if (flag === "--bearer-token-env" && tokenEnv === undefined) {
+                    const value = flags[index + 1];
+                    if (!value || value.startsWith("-")) {
+                        invalid = true;
+                        break;
+                    }
+                    tokenEnv = value;
+                    index += 1;
+                }
+                else if (allowedFlags.has(flag) && !switches.includes(flag)) {
+                    switches.push(flag);
+                }
+                else {
+                    invalid = true;
+                    break;
+                }
+            }
+            if (invalid) {
                 io.writeStderr(`Invalid or duplicate discovery arguments. ${discoveryUsage}`);
                 return 2;
             }
-            if (!flags.includes("--allow-network")) {
+            if (!switches.includes("--allow-network")) {
                 io.writeStderr("doctor discover requires explicit --allow-network consent.");
                 return 2;
             }
+            const bearer = resolveBearerToken(tokenEnv, terminalContext.env);
+            if ("error" in bearer) {
+                io.writeStderr(bearer.error);
+                return 2;
+            }
             const report = await (options.discoverMcpServerImpl ?? discoverMcpServer)(url, {
                 allowNetwork: true,
-                allowLocalNetwork: flags.includes("--allow-local-network")
+                allowLocalNetwork: switches.includes("--allow-local-network"),
+                ...(bearer.token === undefined ? {} : { bearerToken: bearer.token })
             });
-            io.writeStdout(flags.includes("--json")
+            io.writeStdout(switches.includes("--json")
                 ? JSON.stringify(report, null, 2)
                 : renderMcpDiscoveryReport(report));
             return report.status === "discovered" ? 0 : report.status === "unsupported" ? 1 : 2;

package/package.json

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