codex-copilot-dx 0.4.33 → 0.4.35

package/src/config.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import os from "node:os";
 import { status } from "./status.mjs";
 import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
+import { adapterBaseUrl } from "./running-adapter.mjs";
 
 const CONFIG_PATH = path.join(os.homedir(), ".codex", "config.toml");
 
@@ -33,9 +34,9 @@ function setTomlKey(lines, sectionName, key, value) {
   return true;
 }
 
-export function computeUpdatedCodexConfig(content, adapterPort = 2026) {
-  const baseUrl = `http://127.0.0.1:${adapterPort}/v1`;
-  const anthropicBaseUrl = `http://127.0.0.1:${adapterPort}`;
+export function computeUpdatedCodexConfig(content, adapterPort = 2026, adapterHost = "127.0.0.1") {
+  const anthropicBaseUrl = adapterBaseUrl(adapterHost, adapterPort);
+  const baseUrl = `${anthropicBaseUrl}/v1`;
   const hadTrailingNewline = content.endsWith("\n");
   const lines = content.split("\n");
   if (hadTrailingNewline) lines.pop();
@@ -59,9 +60,9 @@ export function computeUpdatedCodexConfig(content, adapterPort = 2026) {
   return { content: lines.join("\n") + (hadTrailingNewline ? "\n" : ""), changed };
 }
 
-function initialCodexConfig(adapterPort) {
-  const baseUrl = `http://127.0.0.1:${adapterPort}/v1`;
-  const anthropicBaseUrl = `http://127.0.0.1:${adapterPort}`;
+function initialCodexConfig(adapterPort, adapterHost) {
+  const anthropicBaseUrl = adapterBaseUrl(adapterHost, adapterPort);
+  const baseUrl = `${anthropicBaseUrl}/v1`;
   return `openai_base_url = "${baseUrl}"
 
 [shell_environment_policy]
@@ -75,18 +76,18 @@ OPENAI_API_KEY = "dummy"
 `;
 }
 
-export function ensureCodexConfig(adapterPort = 2026, { filePath = CONFIG_PATH } = {}) {
-  const baseUrl = `http://127.0.0.1:${adapterPort}/v1`;
+export function ensureCodexConfig(adapterPort = 2026, { filePath = CONFIG_PATH, host = "127.0.0.1" } = {}) {
+  const baseUrl = `${adapterBaseUrl(host, adapterPort)}/v1`;
 
   if (!fs.existsSync(filePath)) {
     // Codex config does not exist yet; create the local proxy defaults.
-    atomicWriteFileIfChangedSync(filePath, initialCodexConfig(adapterPort));
+    atomicWriteFileIfChangedSync(filePath, initialCodexConfig(adapterPort, host));
     console.log(status("ok", "Created ~/.codex/config.toml"));
     return;
   }
 
   const content = fs.readFileSync(filePath, "utf-8");
-  const updated = computeUpdatedCodexConfig(content, adapterPort);
+  const updated = computeUpdatedCodexConfig(content, adapterPort, host);
 
   if (!updated.changed) {
     console.log(status("ok", `Codex already points to ${baseUrl}`));

package/src/copilot.mjs

@@ -1,9 +1,16 @@
 import fs from "node:fs";
 import os from "node:os";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { status } from "./status.mjs";
 import { debugLog } from "./log.mjs";
-import { ensureGithubTokenMetadata, githubReauthMessage, githubTokenPath, importDiscoveredGithubToken } from "./auth.mjs";
+import {
+  fetchGithubIdentity,
+  githubReauthMessage,
+  githubTokenPath,
+  importDiscoveredGithubToken,
+  readGithubTokenMetadata,
+  writeGithubTokenMetadata,
+} from "./auth.mjs";
 import { prepareResponsesPayload } from "./image-optimization.mjs";
 
 export {
@@ -88,6 +95,12 @@ const RETRYABLE_UPSTREAM_ERROR_CODES = new Set([
   "EAI_AGAIN",
   "ENOTFOUND",
 ]);
+const RETRYABLE_POST_CONNECT_ERROR_CODES = new Set([
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ECONNREFUSED",
+  "EAI_AGAIN",
+  "ENOTFOUND",
+]);
 const RETRYABLE_UPSTREAM_STATUSES = new Set([408, 502, 503, 504]);
 
 function upstreamTarget(url) {
@@ -139,9 +152,15 @@ function requestMethod(init = {}) {
   return String(init.method || "GET").toUpperCase();
 }
 
-export function isRetryableUpstreamError(err, { signal } = {}) {
+export function isRetryableUpstreamError(err, { signal, method = "GET" } = {}) {
   if (isAbortError(err, signal)) return false;
-  return RETRYABLE_UPSTREAM_ERROR_CODES.has(upstreamErrorCode(err));
+  const code = upstreamErrorCode(err);
+  if (!["GET", "HEAD", "OPTIONS"].includes(String(method || "GET").toUpperCase())) {
+    const syscall = err?.cause?.syscall || err?.syscall || "";
+    return RETRYABLE_POST_CONNECT_ERROR_CODES.has(code)
+      || (syscall === "connect" && ["ETIMEDOUT", "ECONNRESET"].includes(code));
+  }
+  return RETRYABLE_UPSTREAM_ERROR_CODES.has(code);
 }
 
 export function isRetryableUpstreamStatus(status, method = "GET") {
@@ -190,7 +209,7 @@ export async function fetchCopilotUpstream(
       return resp;
     } catch (e) {
       debugLog(`upstream ${method} ${target} error=${describeUpstreamError(e)} attempt=${attempt + 1}/${retryCount + 1} attempt_ms=${Date.now() - attemptStart} total_ms=${Date.now() - totalStart}`);
-      if (attempt >= retryCount || !isRetryableUpstreamError(e, { signal })) throw e;
+      if (attempt >= retryCount || !isRetryableUpstreamError(e, { signal, method })) throw e;
       const delay = upstreamRetryDelay(attempt, baseDelay);
       console.warn(status("warn", `upstream ${target} ${describeUpstreamError(e)}; retry ${attempt + 1}/${retryCount} in ${delay}ms`));
       await sleep(delay, { signal });
@@ -267,6 +286,10 @@ export async function refreshVSCodeVersion() {
 let copilotToken = null;
 let copilotTokenExpiry = 0;
 let copilotTokenRefresh = null;
+let copilotTokenSourceKey = null;
+let copilotTokenGithubFingerprint = "";
+let copilotTokenGithubIdentity = null;
+let copilotTokenRefreshRetryAt = 0;
 const modelListFlights = new Map();
 
 function getGithubToken({ home = os.homedir() } = {}) {
@@ -286,17 +309,76 @@ function requestCopilotToken(ghToken, { fetchImpl = fetch, signal } = {}) {
   });
 }
 
-function cacheCopilotTokenData(data) {
+function githubTokenFingerprint(token) {
+  return createHash("sha256").update(String(token || "")).digest("hex").slice(0, 24);
+}
+
+function normalizeGithubIdentity(identity) {
+  if (!identity || typeof identity !== "object") return null;
+  const login = typeof identity.login === "string" ? identity.login.trim() : "";
+  const id = identity.id === undefined || identity.id === null ? "" : String(identity.id).trim();
+  return login || id ? { login, id } : null;
+}
+
+function githubIdentitiesMatch(first, second) {
+  const a = normalizeGithubIdentity(first);
+  const b = normalizeGithubIdentity(second);
+  if (!a || !b) return false;
+  if (a.id && b.id) return a.id === b.id;
+  return Boolean(a.login && b.login && a.login.toLowerCase() === b.login.toLowerCase());
+}
+
+function githubIdentityLabel(identity) {
+  const normalized = normalizeGithubIdentity(identity);
+  return normalized?.login || normalized?.id || "unknown";
+}
+
+function cacheCopilotTokenData(data, {
+  sourceKey,
+  githubToken,
+  githubIdentity,
+  allowAccountSwitch = false,
+} = {}) {
   if (!data.token) throw new Error("Copilot token response missing token field");
+  const fingerprint = githubTokenFingerprint(githubToken);
+  const identity = normalizeGithubIdentity(githubIdentity);
+  const tokenChanged = Boolean(copilotTokenGithubFingerprint && fingerprint !== copilotTokenGithubFingerprint);
+  if (!allowAccountSwitch && copilotTokenGithubIdentity && identity
+    && !githubIdentitiesMatch(copilotTokenGithubIdentity, identity)) {
+    throw new Error(`Refusing to switch GitHub Copilot account from ${githubIdentityLabel(copilotTokenGithubIdentity)} to ${githubIdentityLabel(identity)} while the adapter is running. Restart codex-copilot-dx to switch accounts intentionally.`);
+  }
+  if (!allowAccountSwitch && copilotTokenGithubIdentity && tokenChanged && !identity) {
+    const error = new Error("The saved GitHub token changed, but its account could not be verified. Keeping the running adapter bound to the existing GitHub account.");
+    error.transient = true;
+    throw error;
+  }
   copilotToken = data.token;
   apiBase = parseApiBase(data);
   copilotTokenExpiry = typeof data.expires_at === "number"
     ? data.expires_at * 1000
     : Date.now() + 25 * 60 * 1000; // fallback if expires_at absent: refresh in ~25min
+  copilotTokenSourceKey = sourceKey || copilotTokenSourceKey;
+  copilotTokenGithubFingerprint = fingerprint;
+  if (identity) copilotTokenGithubIdentity = identity;
+  copilotTokenRefreshRetryAt = 0;
   console.log(status("ok", "Copilot token refreshed"));
   return copilotToken;
 }
 
+async function githubIdentityForToken(token, { home, fetchImpl, signal }) {
+  const cached = readGithubTokenMetadata(home, token);
+  if (cached) return cached;
+  const identity = await fetchGithubIdentity(token, { fetchImpl, signal });
+  return identity.ok ? identity : null;
+}
+
+function tokenRefreshError(message, { statusCode, transient = false } = {}) {
+  const error = new Error(message);
+  if (statusCode) error.statusCode = statusCode;
+  if (transient) error.transient = true;
+  return error;
+}
+
 async function refreshCopilotToken({
   signal,
   home = os.homedir(),
@@ -304,7 +386,14 @@ async function refreshCopilotToken({
   fetchImpl = fetch,
 } = {}) {
   const ghToken = getGithubToken({ home });
-  const resp = await requestCopilotToken(ghToken, { fetchImpl, signal });
+  const sourceKey = githubTokenPath(home);
+  let resp;
+  try {
+    resp = await requestCopilotToken(ghToken, { fetchImpl, signal });
+  } catch (e) {
+    if (!isAbortError(e, signal)) e.transient = true;
+    throw e;
+  }
   if (!resp.ok) {
     if (resp.status === 401 || resp.status === 403) {
       const imported = await importDiscoveredGithubToken({
@@ -316,34 +405,87 @@ async function refreshCopilotToken({
         validateSavedToken: true,
       });
       if (imported?.validation?.copilotTokenData?.token) {
-        return cacheCopilotTokenData(imported.validation.copilotTokenData);
+        const explicitSource = imported.source?.type === "env" || imported.source?.type === "token-file";
+        return cacheCopilotTokenData(imported.validation.copilotTokenData, {
+          sourceKey,
+          githubToken: imported.token,
+          githubIdentity: imported.validation,
+          allowAccountSwitch: explicitSource,
+        });
       }
       throw new Error(githubReauthMessage(`Failed to get Copilot token: ${resp.status}. The saved GitHub token may be expired, revoked, or missing Copilot access.`));
     }
-    throw new Error(`Failed to get Copilot token: ${resp.status}`);
+    throw tokenRefreshError(`Failed to get Copilot token: ${resp.status}`, {
+      statusCode: resp.status,
+      transient: resp.status === 408 || resp.status === 425 || resp.status === 429 || resp.status >= 500,
+    });
   }
   const data = await resp.json();
-  await ensureGithubTokenMetadata(ghToken, { home, fetchImpl, signal });
-  return cacheCopilotTokenData(data);
+  const identity = await githubIdentityForToken(ghToken, { home, fetchImpl, signal });
+  const token = cacheCopilotTokenData(data, {
+    sourceKey,
+    githubToken: ghToken,
+    githubIdentity: identity,
+  });
+  if (identity) writeGithubTokenMetadata(identity, home, ghToken);
+  return token;
 }
 
-export async function getCopilotToken(options = {}) {
-  if (copilotToken && Date.now() < copilotTokenExpiry - 60000) return copilotToken;
+function canUseCachedToken(sourceKey, now = Date.now(), allowCurrentProcessToken = false) {
+  const sameSource = copilotTokenSourceKey === sourceKey || allowCurrentProcessToken;
+  return Boolean(copilotToken && sameSource && now < copilotTokenExpiry);
+}
+
+export function getCopilotToken(options = {}) {
   const home = options.home || os.homedir();
-  const refreshKey = githubTokenPath(home);
-  if (copilotTokenRefresh?.key === refreshKey) return copilotTokenRefresh.promise;
+  const sourceKey = githubTokenPath(home);
+  const now = Date.now();
+  const allowCurrentProcessToken = options.home === undefined;
+  if (canUseCachedToken(sourceKey, now, allowCurrentProcessToken) && now < copilotTokenExpiry - 60000) {
+    return Promise.resolve(copilotToken);
+  }
+  if (canUseCachedToken(sourceKey, now, allowCurrentProcessToken) && now < copilotTokenRefreshRetryAt) {
+    return Promise.resolve(copilotToken);
+  }
+  if (options.signal?.aborted) return Promise.reject(abortError(options.signal));
 
-  const promise = refreshCopilotToken(options).finally(() => {
-    if (copilotTokenRefresh?.promise === promise) copilotTokenRefresh = null;
-  });
-  copilotTokenRefresh = { key: refreshKey, promise };
-  return promise;
+  let flight = copilotTokenRefresh?.key === sourceKey ? copilotTokenRefresh : null;
+  if (flight?.controller.signal.aborted) {
+    if (copilotTokenRefresh === flight) copilotTokenRefresh = null;
+    flight = null;
+  }
+
+  if (!flight) {
+    const controller = new AbortController();
+    flight = { key: sourceKey, controller, waiters: 0, settled: false, promise: null };
+    flight.promise = refreshCopilotToken({ ...options, home, signal: controller.signal })
+      .catch((error) => {
+        const fallbackNow = Date.now();
+        if (error?.transient && canUseCachedToken(sourceKey, fallbackNow)) {
+          copilotTokenRefreshRetryAt = Math.min(copilotTokenExpiry, fallbackNow + 5000);
+          console.warn(status("warn", `Copilot token refresh failed temporarily; using the existing token until ${new Date(copilotTokenExpiry).toISOString()} (${error.message})`));
+          return copilotToken;
+        }
+        throw error;
+      })
+      .finally(() => {
+        flight.settled = true;
+        if (copilotTokenRefresh === flight) copilotTokenRefresh = null;
+      });
+    copilotTokenRefresh = flight;
+  }
+  return waitForSingleflight(flight, options.signal);
 }
 
 export function resetCopilotTokenForTests() {
+  copilotTokenRefresh?.controller.abort();
   copilotToken = null;
   copilotTokenExpiry = 0;
   copilotTokenRefresh = null;
+  copilotTokenSourceKey = null;
+  copilotTokenGithubFingerprint = "";
+  copilotTokenGithubIdentity = null;
+  copilotTokenRefreshRetryAt = 0;
   apiBase = DEFAULT_API_BASE;
   resetModelListSingleflightForTests();
 }
@@ -379,7 +521,7 @@ async function fetchModels({ signal, fetchImpl, retryOptions }) {
   return { status: resp.status, body };
 }
 
-function waitForModelListFlight(flight, signal) {
+function waitForSingleflight(flight, signal) {
   if (signal?.aborted) return Promise.reject(abortError(signal));
   flight.waiters += 1;
 
@@ -422,7 +564,7 @@ export function listModels({ signal, fetchImpl = fetch, retryOptions } = {}) {
     modelListFlights.set(fetchImpl, flight);
   }
 
-  return waitForModelListFlight(flight, signal);
+  return waitForSingleflight(flight, signal);
 }
 
 export function resetModelListSingleflightForTests() {

package/src/doctor.mjs

@@ -6,7 +6,8 @@ import { githubTokenPath, readGithubTokenMetadata, validateGithubToken } from ".
 import { claudeDesktopPaths } from "./claude-desktop-config.mjs";
 import { status } from "./status.mjs";
 import { buildHeaders, DEFAULT_API_BASE, FALLBACK_VSCODE_VERSION } from "./copilot.mjs";
-import { checkRunningAdapter } from "./running-adapter.mjs";
+import { adapterBaseUrl, checkRunningAdapter } from "./running-adapter.mjs";
+import { CODEX_AUTO_REVIEW_MODEL } from "./models.mjs";
 
 function localGatewayBaseUrl(host, port) {
   const safeHost = String(host || "127.0.0.1");
@@ -48,6 +49,161 @@ function valueLabel(value) {
   return value ? `"${value}"` : "missing";
 }
 
+function copilotModelData(models) {
+  const data = Array.isArray(models) ? models : models?.data;
+  return Array.isArray(data) ? data : [];
+}
+
+function modelEndpoints(model) {
+  return Array.isArray(model?.supported_endpoints) ? model.supported_endpoints : [];
+}
+
+export function selectCompatibilityModels(models) {
+  const data = copilotModelData(models).filter((model) => model?.model_picker_enabled !== false);
+  const responsesCandidates = data.filter((model) => {
+    const id = String(model?.id || "");
+    const endpoints = modelEndpoints(model);
+    return id.startsWith("gpt-") && (endpoints.includes("/responses") || endpoints.includes("/v1/responses"));
+  });
+  const responsesOnly = [...responsesCandidates].reverse()
+    .find((model) => !modelEndpoints(model).includes("/chat/completions"));
+  const claude = data.find((model) => {
+    const id = String(model?.id || "");
+    const vendor = String(model?.vendor || "").toLowerCase();
+    return (id.startsWith("claude-") || vendor === "anthropic")
+      && modelEndpoints(model).includes("/chat/completions");
+  });
+  return {
+    responsesModel: String((responsesOnly || responsesCandidates[0])?.id || ""),
+    claudeModel: String(claude?.id || ""),
+  };
+}
+
+async function fetchTextWithTimeout(fetchImpl, url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetchImpl(url, { ...init, signal: controller.signal });
+    return { resp, text: await resp.text() };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function responseFailure(resp, text) {
+  const detail = String(text || "").replace(/\s+/g, " ").trim().slice(0, 240);
+  return new Error(`HTTP ${resp.status}${detail ? `: ${detail}` : ""}`);
+}
+
+async function compatibilityRequest(fetchImpl, url, body, timeoutMs) {
+  const { resp, text } = await fetchTextWithTimeout(fetchImpl, url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: body.stream ? "text/event-stream" : "application/json" },
+    body: JSON.stringify(body),
+  }, timeoutMs);
+  if (!resp.ok) throw responseFailure(resp, text);
+  return text;
+}
+
+async function runCompatibilityCheck(checks, label, task) {
+  const started = Date.now();
+  try {
+    const value = await task();
+    checks.push({ kind: "ok", message: `${label} passed (${Date.now() - started}ms)` });
+    return value;
+  } catch (e) {
+    const reason = e?.name === "AbortError" ? "timed out" : e?.message || "unknown error";
+    checks.push({ kind: "err", message: `${label} failed: ${reason}` });
+    return null;
+  }
+}
+
+function parseResponseObject(text) {
+  const response = JSON.parse(text);
+  if (!response?.id || !Array.isArray(response.output)) throw new Error("response body is missing id or output");
+  return response;
+}
+
+export async function inspectAdapterCompatibility({
+  host = "127.0.0.1",
+  port = 2026,
+  fetchImpl = fetch,
+  timeoutMs = 120000,
+} = {}) {
+  const baseUrl = localGatewayBaseUrl(connectHost(host), port);
+  const checks = [];
+  const models = await runCompatibilityCheck(checks, "Compatibility model discovery", async () => {
+    const { resp, text } = await fetchTextWithTimeout(fetchImpl, `${baseUrl}/v1/models`, { headers: { Accept: "application/json" } }, timeoutMs);
+    if (!resp.ok) throw responseFailure(resp, text);
+    const parsed = JSON.parse(text);
+    if (!copilotModelData(parsed).length) throw new Error("model list is empty");
+    return parsed;
+  });
+  if (!models) return checks;
+
+  const { responsesModel, claudeModel } = selectCompatibilityModels(models);
+  if (!responsesModel) {
+    checks.push({ kind: "err", message: "Compatibility Responses check failed: no GPT model advertises /responses" });
+    return checks;
+  }
+
+  await runCompatibilityCheck(checks, "Codex Auto-review", async () => {
+    const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/responses`, {
+      model: CODEX_AUTO_REVIEW_MODEL,
+      stream: false,
+      input: "Reply with OK only.",
+    }, timeoutMs);
+    parseResponseObject(text);
+  });
+
+  const firstResponse = await runCompatibilityCheck(checks, `Native Responses (${responsesModel})`, async () => {
+    const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/responses`, {
+      model: responsesModel,
+      stream: false,
+      input: "Reply with OK only.",
+    }, timeoutMs);
+    return parseResponseObject(text);
+  });
+
+  if (firstResponse) {
+    await runCompatibilityCheck(checks, "Responses stream, history, and image tool compatibility", async () => {
+      const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/responses`, {
+        model: responsesModel,
+        stream: true,
+        previous_response_id: firstResponse.id,
+        input: "Reply with OK again.",
+        tools: [{ type: "image_generation" }],
+      }, timeoutMs);
+      if (!/^event:\s*response\.completed\s*$/m.test(text)) throw new Error("stream did not contain response.completed");
+    });
+  }
+
+  await runCompatibilityCheck(checks, "Responses compact", async () => {
+    const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/responses/compact`, {
+      model: responsesModel,
+      stream: false,
+      input: "Compact this short context.",
+    }, timeoutMs);
+    parseResponseObject(text);
+  });
+
+  if (!claudeModel) {
+    checks.push({ kind: "warn", message: "Anthropic stream compatibility skipped because no Claude chat model was advertised" });
+    return checks;
+  }
+
+  await runCompatibilityCheck(checks, `Anthropic Messages stream (${claudeModel})`, async () => {
+    const text = await compatibilityRequest(fetchImpl, `${baseUrl}/v1/messages`, {
+      model: claudeModel,
+      max_tokens: 16,
+      stream: true,
+      messages: [{ role: "user", content: "Reply with OK only." }],
+    }, timeoutMs);
+    if (!/^event:\s*message_stop\s*$/m.test(text)) throw new Error("stream did not contain message_stop");
+  });
+  return checks;
+}
+
 export function inspectGitHubToken({ home = os.homedir() } = {}) {
   const filePath = githubTokenPath(home);
   const token = readText(filePath);
@@ -113,10 +269,10 @@ export async function inspectGitHubTokenOnline({
   }
 }
 
-export function inspectCodexConfig({ home = os.homedir(), port = 2026 } = {}) {
+export function inspectCodexConfig({ home = os.homedir(), host = "127.0.0.1", port = 2026 } = {}) {
   const filePath = path.join(home, ".codex", "config.toml");
-  const expectedBaseUrl = `http://127.0.0.1:${port}/v1`;
-  const expectedAnthropicBaseUrl = `http://127.0.0.1:${port}`;
+  const expectedAnthropicBaseUrl = adapterBaseUrl(host, port);
+  const expectedBaseUrl = `${expectedAnthropicBaseUrl}/v1`;
   const config = readText(filePath);
   if (!config.ok) {
     return [{ kind: "warn", message: `Codex config not found at ${displayPath(home, filePath)}` }];
@@ -139,9 +295,9 @@ export function inspectCodexConfig({ home = os.homedir(), port = 2026 } = {}) {
   return checks;
 }
 
-export function inspectClaudeCodeConfig({ home = os.homedir(), port = 2026 } = {}) {
+export function inspectClaudeCodeConfig({ home = os.homedir(), host = "127.0.0.1", port = 2026 } = {}) {
   const filePath = path.join(home, ".claude", "settings.json");
-  const expectedBaseUrl = `http://127.0.0.1:${port}`;
+  const expectedBaseUrl = adapterBaseUrl(host, port);
   const settings = readJson(filePath);
   if (!settings.ok) {
     const reason = settings.parseError ? `could not parse: ${settings.error.message}` : `not found at ${displayPath(home, filePath)}`;
@@ -237,13 +393,16 @@ export async function collectDoctorChecks({
   checkAdapterListeningFn = checkAdapterListening,
   checkRunningAdapterFn = checkRunningAdapter,
   online = false,
+  compat = false,
   fetchImpl = fetch,
   onlineTimeoutMs = 10000,
+  compatTimeoutMs = 120000,
+  inspectAdapterCompatibilityFn = inspectAdapterCompatibility,
 } = {}) {
   const checks = [
     ...inspectGitHubToken({ home }),
-    ...inspectCodexConfig({ home, port }),
-    ...inspectClaudeCodeConfig({ home, port }),
+    ...inspectCodexConfig({ home, host, port }),
+    ...inspectClaudeCodeConfig({ home, host, port }),
     ...inspectClaudeAppConfig({ home, platform, env, host, port }),
   ];
 
@@ -251,13 +410,16 @@ export async function collectDoctorChecks({
     checks.push(...await inspectGitHubTokenOnline({ home, fetchImpl, timeoutMs: onlineTimeoutMs }));
   }
 
-  if (checkAdapter) {
-    let running;
+  let running = null;
+  if (checkAdapter || compat) {
     try {
       running = await checkRunningAdapterFn({ host, port, fetchImpl });
     } catch {
       running = null;
     }
+  }
+
+  if (checkAdapter) {
     if (running?.ok) {
       checks.push({ kind: "ok", message: `Adapter ${running.data.version} is listening on ${running.baseUrl}` });
     } else if (running?.incompatible) {
@@ -270,12 +432,21 @@ export async function collectDoctorChecks({
     }
   }
 
+  if (compat) {
+    if (!running?.ok) {
+      checks.push({ kind: "err", message: "Compatibility checks require a running, version-compatible codex-copilot-dx adapter" });
+    } else {
+      checks.push(...await inspectAdapterCompatibilityFn({ host, port, fetchImpl, timeoutMs: compatTimeoutMs }));
+    }
+  }
+
   return checks;
 }
 
 export async function runDoctor(options = {}) {
   const log = options.log || console.log;
-  log(`codex-copilot-dx doctor${options.online ? " --online" : ""}`);
+  const flags = [options.online ? "--online" : "", options.compat ? "--compat" : ""].filter(Boolean);
+  log(`codex-copilot-dx doctor${flags.length ? ` ${flags.join(" ")}` : ""}`);
   const checks = await collectDoctorChecks(options);
   for (const check of checks) log(status(check.kind, check.message));
   return checks;