codex-copilot-dx 0.4.8 → 0.4.10

package/README.md

@@ -1,6 +1,6 @@
 # codex-copilot-dx
 
-Use [Codex Desktop](https://openai.com/codex), [Claude Code](https://claude.com/claude-code), and optionally Claude Desktop with your **GitHub Copilot** subscription.
+Use [Codex Desktop](https://openai.com/codex), [Claude Code](https://claude.com/claude-code), and optionally Claude App with your **GitHub Copilot** subscription.
 
 ## How it works
 
@@ -8,7 +8,7 @@ A single in-process adapter (port `2026`) exposes both APIs over your Copilot su
 
 - **Codex** -> OpenAI Responses API (`/v1/responses`, `/v1/responses/compact`); Responses-only models and compaction proxy directly, chat models convert to Chat Completions.
 - **Claude Code** -> Anthropic Messages API (`/v1/messages`, `/v1/messages/count_tokens`), translated to/from Chat Completions.
-- **Claude Desktop** -> optional Anthropic gateway profile using the same local Messages API plus local model discovery for the configured gateway key.
+- **Claude App** -> optional Claude Desktop App gateway profile using the same local Messages API plus local model discovery for the configured gateway key.
 
 Supports both HTTP SSE streaming and non-streaming.
 
@@ -16,7 +16,7 @@ Supports both HTTP SSE streaming and non-streaming.
 
 - GitHub Copilot subscription (Individual, Business, or Enterprise)
 - Node.js 18+
-- [Codex Desktop](https://openai.com/codex), [Claude Code](https://claude.com/claude-code), and/or Claude Desktop installed
+- [Codex Desktop](https://openai.com/codex), [Claude Code](https://claude.com/claude-code), and/or Claude App installed
 
 ## Usage
 
@@ -38,9 +38,19 @@ Claude Code picks up the new `ANTHROPIC_BASE_URL` on its next launch.
 
 Do not set Claude Code by manually exporting `ANTHROPIC_BASE_URL` or `ANTHROPIC_AUTH_TOKEN` in your shell. Let `codex-copilot-dx` write the local config files instead. If you previously exported those variables, remove them from shell startup files and restart the terminal before launching Claude Code.
 
-### Claude Desktop opt-in
+### Diagnostics
 
-Claude Desktop support is opt-in so the default Codex Desktop and Claude Code setup stays unchanged:
+Run a read-only config check without starting the adapter or changing files:
+
+```bash
+codex-copilot-dx doctor
+```
+
+The doctor checks the GitHub token, Codex config, Claude Code settings, Claude App gateway profile, and whether the local adapter port is listening.
+
+### Claude App opt-in
+
+Claude App support is opt-in so the default Codex Desktop and Claude Code setup stays unchanged:
 
 ```bash
 npx codex-copilot-dx@latest --configure-claude-desktop
@@ -52,7 +62,7 @@ Or set:
 CCDX_CONFIGURE_CLAUDE_DESKTOP=1 npx codex-copilot-dx@latest
 ```
 
-This writes a local Claude Desktop 3P gateway profile that points to the adapter root URL, such as `http://127.0.0.1:2026`. The profile uses a generated local bearer key unless `CCDX_CLAUDE_DESKTOP_API_KEY` is set. Restart Claude Desktop after running the command.
+This writes a local Claude App 3P gateway profile that points to the adapter root URL, such as `http://127.0.0.1:2026`. The profile uses a generated local bearer key unless `CCDX_CLAUDE_DESKTOP_API_KEY` is set. Restart Claude App after running the command.
 
 ## Configuration
 
@@ -70,8 +80,8 @@ Environment variables:
 | `CCDX_IMG_MIN_BYTES` | `100000` | Images smaller than this are left untouched |
 | `CCDX_IMG_CONCURRENCY` | `4` | Concurrent image optimization tasks; values above `12` are capped at `12` |
 | `CCDX_DISABLE_IMG_OPT` | unset | Set to `1` to disable image optimization |
-| `CCDX_CONFIGURE_CLAUDE_DESKTOP` | unset | Set to `1` to write the Claude Desktop 3P gateway profile during startup |
-| `CCDX_CLAUDE_DESKTOP_API_KEY` | generated for opt-in setup | Bearer key written into the Claude Desktop profile and recognized by the adapter for model discovery |
+| `CCDX_CONFIGURE_CLAUDE_DESKTOP` | unset | Set to `1` to write the Claude App 3P gateway profile during startup |
+| `CCDX_CLAUDE_DESKTOP_API_KEY` | generated for opt-in setup | Bearer key written into the Claude App profile and recognized by the adapter for model discovery |
 | `CCDX_CLAUDE_MODEL_ALIASES` | built-in Claude aliases | Comma-separated Desktop-to-upstream aliases, for example `claude-sonnet-4-6=claude-sonnet-4.6` |
 | `CCDX_USAGE_PATH` | `~/.local/share/codex-copilot-dx/usage.jsonl` | Local JSONL token usage log |
 | `CCDX_DISABLE_USAGE` | unset | Set to `1` to disable usage logging |

package/bin/cli.mjs

@@ -9,6 +9,7 @@ import { refreshVSCodeVersion } from "../src/copilot.mjs";
 import { status } from "../src/status.mjs";
 import { printUsageSummary } from "../src/usage.mjs";
 import { checkForUpdate, localPackageVersion } from "../src/version.mjs";
+import { runDoctor } from "../src/doctor.mjs";
 
 const ADAPTER_PORT = parseInt(process.env.ADAPTER_PORT || "2026");
 const ADAPTER_HOST = process.env.ADAPTER_HOST || "127.0.0.1";
@@ -30,9 +31,14 @@ if (command === "usage") {
   process.exit(0);
 }
 
+if (command === "doctor" || command === "--doctor") {
+  await runDoctor({ port: ADAPTER_PORT, host: ADAPTER_HOST });
+  process.exit(0);
+}
+
 console.log(`
   codex-copilot-dx v${LOCAL_VERSION}
-  Use Codex Desktop, Claude Code, and Claude Desktop with GitHub Copilot
+  Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot
 `);
 
 checkForUpdate({ currentVersion: LOCAL_VERSION }).then(({ latestVersion, updateAvailable }) => {
@@ -68,8 +74,10 @@ try {
       host: ADAPTER_HOST,
       gatewayApiKey: claudeDesktopApiKey,
     });
-    console.log(status("ok", `Configured Claude Desktop gateway profile at ${result.baseUrl}`));
+    console.log(status("ok", `Configured Claude App gateway profile at ${result.baseUrl}`));
     console.log(formatClaudeDesktopApplyResult(result));
+  } else {
+    console.log(status("ok", "Claude App support available with --configure-claude-desktop"));
   }
 
   // Launch Codex when available.
@@ -77,8 +85,8 @@ try {
 
   console.log(`
   ${status("ok", CONFIGURE_CLAUDE_DESKTOP
-    ? "Ready. Codex, Claude Code, and Claude Desktop are using your GitHub Copilot subscription."
-    : "Ready. Codex and Claude Code are using your GitHub Copilot subscription.")}
+    ? "Ready. Codex, Claude Code, and Claude App are using your GitHub Copilot subscription."
+    : "Ready. Codex and Claude Code are using your GitHub Copilot subscription. Claude App support is available with --configure-claude-desktop.")}
 
   Adapter: http://${ADAPTER_HOST}:${ADAPTER_PORT}
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.4.8",
-  "description": "Use Codex Desktop, Claude Code, and Claude Desktop with GitHub Copilot",
+  "version": "0.4.10",
+  "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "type": "module",
   "bin": {
     "codex-copilot-dx": "bin/cli.mjs"
@@ -16,6 +16,7 @@
     "copilot",
     "github",
     "claude",
+    "claude-app",
     "claude-code",
     "claude-desktop",
     "anthropic",

package/src/adapter.mjs

@@ -122,6 +122,7 @@ export async function readJsonBody(req, {
 }
 
 function sendJsonError(res, err, fallbackStatus = 400) {
+  if (res.destroyed || res.writableEnded) return;
   if (!res.headersSent) res.writeHead(err?.statusCode || fallbackStatus, { "Content-Type": "application/json" });
   res.end(JSON.stringify({ error: err?.message || "Request failed" }));
 }
@@ -164,30 +165,61 @@ export function writeOrDrain(res, chunk) {
   });
 }
 
-function createRequestAbort(req, res) {
+export function isAbortLikeError(err) {
+  return err?.name === "AbortError" || /operation was aborted/i.test(String(err?.message || ""));
+}
+
+export function abortErrorStatusCode(reason) {
+  if (reason === "upstream_timeout") return 504;
+  if (reason === "client_aborted" || reason === "client_closed") return 499;
+  return 400;
+}
+
+export function createRequestAbort(req, res) {
   const controller = new AbortController();
   let timer = null;
   let cleaned = false;
-  const abort = () => {
-    if (!cleaned && !controller.signal.aborted) controller.abort();
+  let reason = null;
+  const abort = (nextReason = "aborted") => {
+    if (!cleaned && !controller.signal.aborted) {
+      reason = nextReason;
+      controller.abort();
+    }
+  };
+  const onReqAborted = () => abort("client_aborted");
+  const onResClose = () => {
+    if (!res.writableEnded) abort("client_closed");
   };
-  req.on("aborted", abort);
-  res.on("close", abort);
+  req.on("aborted", onReqAborted);
+  res.on("close", onResClose);
   return {
     signal: controller.signal,
+    get reason() { return reason; },
     setTimeout(ms) {
       if (timer) clearTimeout(timer);
-      if (ms > 0) timer = setTimeout(abort, ms);
+      if (ms > 0) timer = setTimeout(() => abort("upstream_timeout"), ms);
     },
     cleanup() {
       cleaned = true;
       if (timer) clearTimeout(timer);
-      req.off("aborted", abort);
-      res.off("close", abort);
+      req.off("aborted", onReqAborted);
+      res.off("close", onResClose);
     },
   };
 }
 
+function logRequestFailure(label, err, abort) {
+  if (!isAbortLikeError(err)) {
+    console.error(status("err", `${label} request failed: ${err.message}`));
+    return;
+  }
+
+  const reason = abort?.reason || "aborted";
+  err.statusCode ||= abortErrorStatusCode(reason);
+  const detail = reason === "upstream_timeout" ? `${reason} after ${UPSTREAM_TIMEOUT_MS}ms` : reason;
+  console.warn(status("warn", `${label} request aborted: ${detail}`));
+}
+
 function responsesInputItems(input) {
   if (input === undefined || input === null) return [];
   if (typeof input === "string") {
@@ -562,13 +594,16 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify(resp));
               } catch (e) {
-                if (!res.headersSent) res.writeHead(502);
-                res.end("Bad Gateway");
+                logRequestFailure("Responses", e, abort);
+                if (!res.destroyed && !res.writableEnded) {
+                  if (!res.headersSent) res.writeHead(e?.statusCode || 502);
+                  res.end("Bad Gateway");
+                }
               }
             }
           }
         } catch (e) {
-          console.error(status("err", `Responses request failed: ${e.message}`));
+          logRequestFailure("Responses", e, abort);
           sendJsonError(res, e);
         } finally {
           abort.cleanup();
@@ -589,7 +624,7 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
           console.log(status("info", `responses compact model=${model} stream=${!!parsed.stream}`));
           await proxyCopilotResponses(prepared, req, res, copilotResponsesCompact, { signal: abort.signal });
         } catch (e) {
-          console.error(status("err", `Responses compact request failed: ${e.message}`));
+          logRequestFailure("Responses compact", e, abort);
           sendJsonError(res, e);
         } finally {
           abort.cleanup();
@@ -608,7 +643,13 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
       abort.setTimeout(UPSTREAM_TIMEOUT_MS);
       listModels({ signal: abort.signal })
         .then(({ status, body }) => { res.writeHead(status, { "Content-Type": "application/json" }); res.end(body); })
-        .catch((e) => { if (!res.headersSent) res.writeHead(502); res.end(JSON.stringify({ error: e.message })); })
+        .catch((e) => {
+          logRequestFailure("Models", e, abort);
+          if (!res.destroyed && !res.writableEnded) {
+            if (!res.headersSent) res.writeHead(e?.statusCode || 502);
+            res.end(JSON.stringify({ error: e.message }));
+          }
+        })
         .finally(() => abort.cleanup());
       return;
     }
@@ -671,7 +712,7 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
             res.end(JSON.stringify(anthropicMsg));
           }
         } catch (e) {
-          console.error(status("err", `Messages request failed: ${e.message}`));
+          logRequestFailure("Messages", e, abort);
           sendJsonError(res, e);
         } finally {
           abort.cleanup();

package/src/auth.mjs

@@ -6,7 +6,10 @@ import { status } from "./status.mjs";
 
 const CLIENT_ID = "Iv1.b507a08c87ecfe98"; // Public GitHub Copilot client ID.
 const SCOPE = "read:user";
-const GITHUB_TOKEN_PATH = path.join(os.homedir(), ".local", "share", "copilot-api", "github_token");
+
+export function githubTokenPath(home = os.homedir()) {
+  return path.join(home, ".local", "share", "copilot-api", "github_token");
+}
 
 // Map GitHub polling responses to a small local state machine.
 export function interpretPoll(data) {
@@ -40,6 +43,7 @@ function openAndCopy(userCode, verificationUri) {
 }
 
 export async function ensureAuth() {
+  const GITHUB_TOKEN_PATH = githubTokenPath();
   if (fs.existsSync(GITHUB_TOKEN_PATH)) {
     console.log(status("ok", "GitHub token found"));
     return;
@@ -90,6 +94,7 @@ export async function ensureAuth() {
 }
 
 function writeToken(token) {
+  const GITHUB_TOKEN_PATH = githubTokenPath();
   fs.mkdirSync(path.dirname(GITHUB_TOKEN_PATH), { recursive: true });
   fs.writeFileSync(GITHUB_TOKEN_PATH, token, { mode: 0o600 });
 }

package/src/claude-desktop-config.mjs

@@ -54,16 +54,16 @@ export function validateClaudeDesktopBaseUrl(raw) {
   try {
     parsed = new URL(raw);
   } catch {
-    throw new Error(`Claude Desktop gateway base URL is not valid: ${raw}`);
+    throw new Error(`Claude App gateway base URL is not valid: ${raw}`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error("Claude Desktop gateway base URL must use http or https");
+    throw new Error("Claude App gateway base URL must use http or https");
   }
   if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
-    throw new Error("Claude Desktop allows http only for loopback; use https for LAN or remote gateways");
+    throw new Error("Claude App allows http only for loopback; use https for LAN or remote gateways");
   }
   if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
-    throw new Error("Claude Desktop gateway base URL must be the root URL without /v1, query, or hash");
+    throw new Error("Claude App gateway base URL must be the root URL without /v1, query, or hash");
   }
 }
 
@@ -84,7 +84,7 @@ export function computeClaudeDesktopProfile(sourceProfile = {}, {
 } = {}) {
   validateClaudeDesktopBaseUrl(baseUrl);
   if (!String(gatewayApiKey || "").trim()) {
-    throw new Error("Claude Desktop gateway API key is required");
+    throw new Error("Claude App gateway API key is required");
   }
 
   const profile = {};
@@ -207,7 +207,7 @@ export function applyClaudeDesktopConfig({
 
 export function formatClaudeDesktopApplyResult(result) {
   return [
-    "Claude Desktop local gateway profile",
+    "Claude App local gateway profile",
     `profile id: ${result.profileId}`,
     `profile path: ${result.profilePath}`,
     `base url: ${result.baseUrl}`,
@@ -222,7 +222,7 @@ export function ensureClaudeDesktopConfig(port = 2026, host = "127.0.0.1") {
     host,
     gatewayApiKey: process.env.CCDX_CLAUDE_DESKTOP_API_KEY || process.env.CCDX_PROXY_API_KEY || generatedClaudeDesktopApiKey(),
   });
-  console.log(status("ok", `Configured Claude Desktop gateway profile at ${result.baseUrl}`));
+  console.log(status("ok", `Configured Claude App gateway profile at ${result.baseUrl}`));
   console.log(formatClaudeDesktopApplyResult(result));
   return result;
 }

package/src/doctor.mjs

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import net from "node:net";
+import { githubTokenPath } from "./auth.mjs";
+import { claudeDesktopPaths } from "./claude-desktop-config.mjs";
+import { status } from "./status.mjs";
+
+function localGatewayBaseUrl(host, port) {
+  const safeHost = String(host || "127.0.0.1");
+  const urlHost = safeHost.includes(":") && !safeHost.startsWith("[") ? `[${safeHost}]` : safeHost;
+  return `http://${urlHost}:${port}`;
+}
+
+function readText(filePath) {
+  try {
+    return { ok: true, text: fs.readFileSync(filePath, "utf8") };
+  } catch (e) {
+    return { ok: false, missing: e?.code === "ENOENT", error: e };
+  }
+}
+
+function readJson(filePath) {
+  const raw = readText(filePath);
+  if (!raw.ok) return raw;
+  try {
+    return { ok: true, json: JSON.parse(raw.text) };
+  } catch (e) {
+    return { ok: false, parseError: true, error: e };
+  }
+}
+
+function tomlString(content, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`^\\s*${escaped}\\s*=\\s*"([^"]*)"`, "m").exec(content);
+  return match?.[1] || "";
+}
+
+function displayPath(home, filePath) {
+  const rel = path.relative(home, filePath);
+  if (!rel.startsWith("..") && !path.isAbsolute(rel)) return `~/${rel}`;
+  return filePath;
+}
+
+function valueLabel(value) {
+  return value ? `"${value}"` : "missing";
+}
+
+export function inspectGitHubToken({ home = os.homedir() } = {}) {
+  const filePath = githubTokenPath(home);
+  const token = readText(filePath);
+  if (!token.ok) {
+    return [{ kind: "warn", message: `GitHub token not found at ${displayPath(home, filePath)}` }];
+  }
+  if (!token.text.trim()) {
+    return [{ kind: "err", message: `GitHub token file is empty at ${displayPath(home, filePath)}` }];
+  }
+  return [{ kind: "ok", message: "GitHub token found" }];
+}
+
+export function inspectCodexConfig({ home = os.homedir(), 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 config = readText(filePath);
+  if (!config.ok) {
+    return [{ kind: "warn", message: `Codex config not found at ${displayPath(home, filePath)}` }];
+  }
+
+  const checks = [];
+  const baseUrl = tomlString(config.text, "openai_base_url");
+  checks.push(baseUrl === expectedBaseUrl
+    ? { kind: "ok", message: `Codex base URL points to ${expectedBaseUrl}` }
+    : { kind: "warn", message: `Codex base URL is ${valueLabel(baseUrl)}; expected "${expectedBaseUrl}"` });
+
+  const missing = [];
+  if (tomlString(config.text, "OPENAI_BASE_URL") !== expectedBaseUrl) missing.push("OPENAI_BASE_URL");
+  if (tomlString(config.text, "OPENAI_API_KEY") !== "dummy") missing.push("OPENAI_API_KEY");
+  if (tomlString(config.text, "ANTHROPIC_BASE_URL") !== expectedAnthropicBaseUrl) missing.push("ANTHROPIC_BASE_URL");
+  if (tomlString(config.text, "ANTHROPIC_AUTH_TOKEN") !== "dummy") missing.push("ANTHROPIC_AUTH_TOKEN");
+  checks.push(missing.length === 0
+    ? { kind: "ok", message: "Codex shell env local API keys are configured" }
+    : { kind: "warn", message: `Codex shell env local API keys need update: ${missing.join(", ")}` });
+  return checks;
+}
+
+export function inspectClaudeCodeConfig({ home = os.homedir(), port = 2026 } = {}) {
+  const filePath = path.join(home, ".claude", "settings.json");
+  const expectedBaseUrl = `http://127.0.0.1:${port}`;
+  const settings = readJson(filePath);
+  if (!settings.ok) {
+    const reason = settings.parseError ? `could not parse: ${settings.error.message}` : `not found at ${displayPath(home, filePath)}`;
+    return [{ kind: settings.parseError ? "err" : "warn", message: `Claude Code settings ${reason}` }];
+  }
+
+  const env = settings.json?.env || {};
+  const missing = [];
+  if (env.ANTHROPIC_BASE_URL !== expectedBaseUrl) missing.push("ANTHROPIC_BASE_URL");
+  if (env.ANTHROPIC_AUTH_TOKEN !== "dummy") missing.push("ANTHROPIC_AUTH_TOKEN");
+  return [missing.length === 0
+    ? { kind: "ok", message: `Claude Code points to ${expectedBaseUrl}` }
+    : { kind: "warn", message: `Claude Code settings need update: ${missing.join(", ")}` }];
+}
+
+export function inspectClaudeAppConfig({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+  host = "127.0.0.1",
+  port = 2026,
+} = {}) {
+  const paths = claudeDesktopPaths(home, platform, env);
+  const expectedBaseUrl = localGatewayBaseUrl(host, port);
+  const checks = [];
+
+  const normalConfig = readJson(paths.normalConfigPath);
+  const threepConfig = readJson(paths.threepConfigPath);
+  if (normalConfig.ok && threepConfig.ok
+    && normalConfig.json?.deploymentMode === "3p"
+    && threepConfig.json?.deploymentMode === "3p") {
+    checks.push({ kind: "ok", message: "Claude App deployment mode is 3p" });
+  } else {
+    checks.push({ kind: "warn", message: "Claude App deployment mode is not fully configured for 3p" });
+  }
+
+  const meta = readJson(paths.metaPath);
+  const appliedId = meta.ok ? String(meta.json?.appliedId || "").trim() : "";
+  if (!appliedId) {
+    checks.push({ kind: "warn", message: "Claude App gateway profile is not configured; run with --configure-claude-desktop" });
+    return checks;
+  }
+
+  const profilePath = path.join(paths.configLibraryPath, `${appliedId}.json`);
+  const profile = readJson(profilePath);
+  if (!profile.ok) {
+    checks.push({ kind: "warn", message: `Claude App active gateway profile not found at ${displayPath(home, profilePath)}` });
+    return checks;
+  }
+
+  const p = profile.json || {};
+  const missing = [];
+  if (p.inferenceProvider !== "gateway") missing.push("inferenceProvider");
+  if (p.inferenceGatewayBaseUrl !== expectedBaseUrl) missing.push(`inferenceGatewayBaseUrl expected "${expectedBaseUrl}"`);
+  if (p.inferenceGatewayAuthScheme !== "bearer") missing.push("inferenceGatewayAuthScheme");
+  if (!String(p.inferenceGatewayApiKey || "").trim()) missing.push("inferenceGatewayApiKey");
+  if (!String(p.inferenceModels || "").trim()) missing.push("inferenceModels");
+  checks.push(missing.length === 0
+    ? { kind: "ok", message: `Claude App gateway profile points to ${expectedBaseUrl}` }
+    : { kind: "warn", message: `Claude App gateway profile needs update: ${missing.join(", ")}` });
+  return checks;
+}
+
+function connectHost(host) {
+  const normalized = String(host || "127.0.0.1").replace(/^\[(.*)\]$/, "$1");
+  if (normalized === "0.0.0.0") return "127.0.0.1";
+  if (normalized === "::") return "::1";
+  return normalized;
+}
+
+export function checkAdapterListening({ host = "127.0.0.1", port = 2026, timeoutMs = 500 } = {}) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host: connectHost(host), port });
+    const done = (ok) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+export async function collectDoctorChecks({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+  host = "127.0.0.1",
+  port = 2026,
+  checkAdapter = true,
+  checkAdapterListeningFn = checkAdapterListening,
+} = {}) {
+  const checks = [
+    ...inspectGitHubToken({ home }),
+    ...inspectCodexConfig({ home, port }),
+    ...inspectClaudeCodeConfig({ home, port }),
+    ...inspectClaudeAppConfig({ home, platform, env, host, port }),
+  ];
+
+  if (checkAdapter) {
+    const listening = await checkAdapterListeningFn({ host, port });
+    checks.push(listening
+      ? { kind: "ok", message: `Adapter is listening on ${localGatewayBaseUrl(host, port)}` }
+      : { kind: "warn", message: `Adapter is not listening on ${localGatewayBaseUrl(host, port)}` });
+  }
+
+  return checks;
+}
+
+export async function runDoctor(options = {}) {
+  const log = options.log || console.log;
+  log("codex-copilot-dx doctor");
+  const checks = await collectDoctorChecks(options);
+  for (const check of checks) log(status(check.kind, check.message));
+  return checks;
+}