codex-copilot-dx 0.6.1 → 0.6.2

package/README.md

@@ -34,6 +34,8 @@ command remains an equivalent compatibility alias. For a one-off run without a
 global install, use `npx codex-copilot-dx@latest`.
 Both installed commands expose the same options and subcommands; help, version,
 doctor, status, and argument-error output use the command name that was invoked.
+Run `ccdx <command> --help` (including `auth login claude --help` and
+`pms status --help`) for command-specific behavior and side-effect details.
 
 To query the models currently advertised as selectable for the saved Codex
 Copilot account, run:
@@ -60,11 +62,14 @@ while using a different personal account that has Claude models enabled, run:
 ccdx auth login claude --github-login <personal-github-login>
 ```
 
-This is the only command that starts the additional Device Flow. It verifies
+This is the only command that may start the additional Device Flow. Before
+opening a browser, it checks compatible local Copilot credentials, excludes the
+current Codex identity, and reuses an unambiguous valid account. It then verifies
 the selected GitHub identity, Copilot entitlement, and an enabled Claude model
 before saving anything. It refuses the current Codex account and never changes,
 migrates, or deletes the existing Codex credential. The optional login pin is
-recommended so authorizing the wrong browser account fails before activation.
+recommended so a machine with multiple accounts selects only the requested
+identity. Use `--reauth` to bypass local discovery and force Device Flow.
 
 The existing Codex token remains at
 `~/.local/share/copilot-api/github_token`. The isolated Claude credential is
@@ -80,7 +85,8 @@ Once enabled, routing is fixed by API surface rather than by model name:
 - `/v1/messages/count_tokens` remains local and uses neither account.
 
 The two profiles keep separate service tokens, API bases, refresh/backoff state,
-model endpoint metadata, and model caches. If the isolated Claude profile later
+model endpoint metadata, and credential-bound model caches. Switching either
+GitHub account invalidates that profile's old cache instead of borrowing it. If the isolated Claude profile later
 becomes invalid, Claude requests fail with a reauthentication instruction while
 Codex remains available; CCDX never silently falls back to the enterprise
 account. Reauthorize it explicitly with:
@@ -114,6 +120,15 @@ ccdx auth login claude --reauth --github-login <personal-github-login>
 ccdx pms setup
 ```
 
+Inspect the installed version, exact patch integrity, isolated Claude profile,
+and relay without changing files:
+
+```bash
+ccdx pms status
+```
+
+`pm-studio status` and `pm-studio setup` are equivalent long-form aliases.
+
 `ccdx pms setup` performs only local preflight, backup, staging, integrity,
 signing, and replacement work. It never starts Device Flow, the adapter,
 Codex, or PM Studio, and it does not modify PM profiles, cached model lists, or
@@ -232,7 +247,11 @@ ccdx doctor
 
 The command exits with status `1` when it finds an invalid configuration and `0` when checks contain only OK or warning results.
 
-The doctor checks the GitHub token, Codex config, Claude Code settings, Claude App gateway profile, and whether the local adapter port is listening.
+The doctor checks the GitHub token, Codex config, Claude Code settings, Claude
+App gateway profile, adapter availability, and an installed PM Studio bundle.
+It ends with passed/warning/error totals and deduplicated next-step commands.
+An absent PM Studio installation is ignored; unsupported versions are reported
+without modification, while integrity drift remains an error.
 
 For a read-only live check of the saved GitHub token, Copilot entitlement, and models endpoint, run:
 
@@ -267,7 +286,7 @@ loopback endpoint directly:
 curl -s http://127.0.0.1:2026/_ccdx/status | jq
 ```
 
-The status endpoint is restricted to the socket's real loopback address, even when LAN binding is explicitly enabled. It reports fixed-size request counters, bounded TTFT/TPOT histograms for streaming routes, admission pressure, memory use, response-history size, image queue/cache state, model cache counts, and token expiry state. It never retains metric samples or includes prompts, completions, tool arguments, image content, account names, or token values. API responses always include a safe `X-Request-Id` for correlation. To include the same ID as `request_id` in related terminal and file log lines, start the adapter with:
+The status endpoint is restricted to the socket's real loopback address, even when LAN binding is explicitly enabled. It reports fixed-size request counters, bounded TTFT/TPOT histograms for streaming routes, admission pressure, memory use, response-history size, image queue/cache state, profile model cache counts, PM relay route totals, and token expiry state. It never retains metric samples or includes prompts, completions, tool arguments, image content, account names, or token values. API responses always include a safe `X-Request-Id` for correlation. If the adapter is not running, the CLI prints the exact start-and-retry command. To include the same ID as `request_id` in related terminal and file log lines, start the adapter with:
 
 ```bash
 ccdx --show-request-id
@@ -287,9 +306,13 @@ ccdx
 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
+npx codex-copilot-dx@latest start --configure-claude-app
 ```
 
+The previous `--configure-claude-desktop` spelling remains a compatibility
+alias. Startup reports Claude App as ready only when a matching managed gateway
+key is restored or the profile is configured in that run.
+
 Or set:
 
 ```bash

package/bin/cli.mjs

@@ -39,7 +39,7 @@ try {
 }
 
 if (CLI.command === "help") {
-  console.log(cliHelp(CLI_NAME));
+  console.log(cliHelp(CLI_NAME, CLI.helpTopic));
   process.exit(0);
 }
 if (CLI.command === "version") {
@@ -125,6 +125,11 @@ if (CLI.command === "update") {
 }
 if (CLI.command === "pms") {
   try {
+    if (CLI.action === "status") {
+      const { runPmStudioStatus } = await import("../src/pm-studio-status.mjs");
+      const result = await runPmStudioStatus({ commandName: CLI_NAME });
+      process.exit(result.ok ? 0 : 1);
+    }
     const { runPmStudioSetup } = await import("../src/pm-studio-setup.mjs");
     await runPmStudioSetup({ commandName: CLI_NAME });
     process.exit(0);
@@ -206,7 +211,7 @@ async function reuseRunningAdapterIfAvailable() {
       console.log(status("warn", "Existing adapter is running; skip Claude App profile update unless CCDX_CLAUDE_DESKTOP_API_KEY or CCDX_PROXY_API_KEY is set"));
     }
   } else {
-    console.log(status("ok", "Claude App support available with --configure-claude-desktop"));
+    console.log(status("ok", "Claude App support available with --configure-claude-app"));
   }
 
   await openCodex();
@@ -270,6 +275,7 @@ try {
     codexClient: profileRuntime.codexClient,
     claudeClient: profileRuntime.claudeClient,
     claudeMode: profileRuntime.claudeMode,
+    codexCredentialFingerprint: profileRuntime.codexCredentialFingerprint,
     claudeCredentialFingerprint: profileRuntime.claudeCredentialFingerprint,
     timeoutMs: MODEL_REFRESH_TIMEOUT_MS,
     commandName: CLI_NAME,
@@ -329,7 +335,7 @@ try {
     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"));
+    console.log(status("ok", "Claude App support available with --configure-claude-app"));
   }
 
   // Launch Codex when available.
@@ -345,8 +351,10 @@ try {
     modelRefreshTimer.unref?.();
   }
 
+  const readyClients = ["Codex App", "Claude Code"];
+  if (claudeDesktopApiKey) readyClients.splice(1, 0, "Claude App");
   console.log(`
-  ${status("ok", "Ready, Claude Code, Claude App and Codex App are now ready to use")}
+  ${status("ok", `Ready, ${readyClients.join(", ")} ${readyClients.length === 1 ? "is" : "are"} ready to use`)}
 
   Adapter: ${adapterBaseUrl(ADAPTER_HOST, ADAPTER_PORT)}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/scripts/benchmark.mjs

@@ -8,6 +8,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import sharp from "sharp";
 import { optimizeImagesInBody, prepareResponsesPayload } from "../src/image-optimization.mjs";
+import { createPmStudioModelRouter } from "../src/profile-routing.mjs";
 
 const packageRoot = fileURLToPath(new URL("../", import.meta.url));
 
@@ -235,6 +236,34 @@ const duplicateImages = {
   optimizer_calls: duplicateCalls,
 };
 
+const routingCatalog = {
+  data: Array.from({ length: 1000 }, (_, index) => index % 5 === 0
+    ? {
+        id: `claude-benchmark-${index}`,
+        vendor: "Anthropic",
+        model_picker_enabled: true,
+        supported_endpoints: ["/chat/completions"],
+      }
+    : { id: `gpt-benchmark-${index}`, vendor: "OpenAI", supported_endpoints: ["/responses"] }),
+};
+const modelRouter = createPmStudioModelRouter({
+  getCatalog: () => routingCatalog,
+  isClaudeEnabled: () => true,
+});
+const routingIterations = 100000;
+const routingStarted = performance.now();
+let claudeClassifications = 0;
+for (let index = 0; index < routingIterations; index += 1) {
+  if (modelRouter.classify("claude-benchmark-0") === "claude") claudeClassifications += 1;
+}
+const pmModelRouting = {
+  catalog_models: routingCatalog.data.length,
+  iterations: routingIterations,
+  elapsed_ms: +(performance.now() - routingStarted).toFixed(1),
+  claude_classifications: claudeClassifications,
+  availability_rebuilds: modelRouter.diagnostics().rebuilds,
+};
+
 const pixels = deterministicPixels(1024 * 1024 * 3, 0x87654321);
 const webp = await sharp(pixels, { raw: { width: 1024, height: 1024, channels: 3 } })
   .webp({ quality: 100 })
@@ -281,6 +310,7 @@ const report = {
   adapter_import: adapterImport,
   token_count_100kb: tokenCount,
   duplicate_images: duplicateImages,
+  pm_model_routing: pmModelRouting,
   oversized_payload: oversizedPayload,
 };
 
@@ -308,6 +338,10 @@ console.log(JSON.stringify(report, null, 2));
 
 if (checkMode) {
   const failures = [];
+  if (report.pm_model_routing.availability_rebuilds !== 1
+    || report.pm_model_routing.claude_classifications !== report.pm_model_routing.iterations) {
+    failures.push("PM Studio model routing did not reuse the memoized catalog classification");
+  }
   const proxy = report.large_token_count.proxy;
   const array = report.large_token_count.materialized_array;
   if (proxy.tokens !== array.tokens) failures.push(`token counts differ: proxy=${proxy.tokens} array=${array.tokens}`);

package/src/auth.mjs

@@ -326,6 +326,7 @@ export async function discoverGithubToken({
   fetchImpl = fetch,
   signal,
   excludeTokens = [],
+  excludeIdentities = [],
   expectedIdentity,
   strictExpectedIdentity = false,
 } = {}) {
@@ -348,6 +349,10 @@ export async function discoverGithubToken({
 
     const validation = await validateGithubToken(token, { fetchImpl, signal });
     if (validation.ok) {
+      if (excludeIdentities.some((identity) => githubIdentityMatchesExpected(validation, identity))) {
+        failures.push({ source, validation, reason: "github_account_excluded" });
+        continue;
+      }
       const candidate = { ok: true, token, source, validation };
       const explicitSource = source.type === "env" || source.type === "token-file";
       if (expectedIdentity && (strictExpectedIdentity || !explicitSource)) {

package/src/cli-auth.mjs

@@ -1,8 +1,10 @@
 import os from "node:os";
 import { spawn } from "node:child_process";
 import {
+  discoverGithubToken,
   fetchGithubIdentity,
   interpretPoll,
+  sourceDescription,
   validateGithubToken,
 } from "./auth.mjs";
 import {
@@ -19,6 +21,7 @@ import {
   normalizeGithubIdentity,
 } from "./github-identity.mjs";
 import { saveModelCache } from "./model-cache.mjs";
+import { profileRouting } from "./profile-routing.mjs";
 import { status } from "./status.mjs";
 
 const CLIENT_ID = "Iv1.b507a08c87ecfe98";
@@ -267,14 +270,45 @@ export async function authorizeClaudeProfile({
       throw new Error(`Claude profile is configured but invalid (${current.reason}); run ccdx auth login claude --reauth`);
     }
 
-    const githubToken = await requestDeviceFlowToken({
-      fetchImpl,
-      signal,
-      log,
-      openAndCopyFn,
-      sleepImpl,
-      now,
-    });
+    let githubToken = "";
+    if (!reauth) {
+      const codex = readAuthProfileCredentials(AUTH_PROFILE_CODEX, { home });
+      if (!codex.valid) {
+        throw new Error("The existing Codex GitHub account is not configured; refusing to create an unbound Claude profile");
+      }
+      const existingCodex = await codexIdentity({ home, fetchImpl, signal });
+      const pinnedLogin = String(expectedLogin || "").trim();
+      const discovered = await discoverGithubToken({
+        home,
+        env,
+        fetchImpl,
+        signal,
+        excludeTokens: [codex.token],
+        excludeIdentities: [existingCodex.identity],
+        expectedIdentity: pinnedLogin ? { login: pinnedLogin } : undefined,
+        strictExpectedIdentity: Boolean(pinnedLogin),
+      });
+      if (discovered.ambiguous) {
+        const accounts = [...new Set(discovered.candidates
+          .map((candidate) => candidate.login || candidate.id || "unknown"))];
+        throw new Error(`Multiple reusable GitHub Copilot accounts were found (${accounts.join(", ")}). Use --github-login or CCDX_GITHUB_TOKEN_PATH to select the Claude account.`);
+      }
+      if (discovered.ok) {
+        githubToken = discovered.token;
+        const login = discovered.validation?.login ? ` for ${discovered.validation.login}` : "";
+        log(status("info", `Reusing a local Copilot credential from ${sourceDescription(discovered.source)}${login}`));
+      }
+    }
+    if (!githubToken) {
+      githubToken = await requestDeviceFlowToken({
+        fetchImpl,
+        signal,
+        log,
+        openAndCopyFn,
+        sleepImpl,
+        now,
+      });
+    }
     const candidate = await validateClaudeCandidate(githubToken, {
       home,
       expectedLogin,
@@ -350,10 +384,7 @@ export function authStatus({ home = os.homedir() } = {}) {
       codex: publicProfile(codex, "legacy"),
       claude: publicProfile(claude, "isolated"),
     },
-    routing: {
-      responses: AUTH_PROFILE_CODEX,
-      messages: claude.configured ? AUTH_PROFILE_CLAUDE : AUTH_PROFILE_CODEX,
-    },
+    routing: profileRouting({ claudeConfigured: claude.configured }),
   };
 }
 

package/src/cli-options.mjs

@@ -1,7 +1,29 @@
 const HELP_COMMANDS = new Set(["help", "--help", "-h"]);
 const VERSION_COMMANDS = new Set(["version", "--version", "-v"]);
-const START_OPTIONS = new Set(["--configure-claude-desktop", "--show-request-id"]);
+const START_OPTIONS = new Map([
+  ["--configure-claude-desktop", "configure-claude-app"],
+  ["--configure-claude-app", "configure-claude-app"],
+  ["--show-request-id", "show-request-id"],
+]);
 const CLI_COMMANDS = new Set(["ccdx", "codex-copilot-dx"]);
+const PM_COMMANDS = new Set(["pms", "pm-studio"]);
+const HELP_TOPICS = new Set([
+  "",
+  "start",
+  "auth",
+  "auth status",
+  "auth login",
+  "doctor",
+  "status",
+  "models",
+  "pms",
+  "pms setup",
+  "pms status",
+  "usage",
+  "auto-review-model",
+  "update",
+  "version",
+]);
 
 function unexpectedArgs(args) {
   throw new Error(`Unexpected argument${args.length === 1 ? "" : "s"}: ${args.join(" ")}`);
@@ -39,40 +61,97 @@ function checkedProfile(value, { allowAll = false } = {}) {
   return profile;
 }
 
+function baseCommand(command, extra = {}) {
+  return {
+    command,
+    configureClaudeDesktop: false,
+    showRequestId: false,
+    online: false,
+    compat: false,
+    ...extra,
+  };
+}
+
+function checkedHelpTopic(parts = []) {
+  const normalized = parts.map((part, index) => {
+    if (index === 0 && part === "pm-studio") return "pms";
+    return part;
+  }).join(" ");
+  if (!HELP_TOPICS.has(normalized)) throw new Error(`Unknown help topic: ${parts.join(" ")}`);
+  return normalized;
+}
+
+function helpCommand(parts = []) {
+  return baseCommand("help", { helpTopic: checkedHelpTopic(parts) });
+}
+
+function nestedHelp(command, rest) {
+  if (!rest.length || !HELP_COMMANDS.has(rest.at(-1))) return null;
+  const args = rest.slice(0, -1);
+  if (PM_COMMANDS.has(command)) {
+    if (args.length > 1) unexpectedArgs(args.slice(1));
+    return helpCommand(["pms", ...args]);
+  }
+  if (command === "auth") {
+    if (args[0] === "login" && args[1] === "claude" && args.length === 2) {
+      return helpCommand(["auth", "login"]);
+    }
+    if (args.length > 1) unexpectedArgs(args.slice(1));
+    return helpCommand(["auth", ...args]);
+  }
+  if (args.length) unexpectedArgs(args);
+  return helpCommand([command]);
+}
+
+function parseStartOptions(args) {
+  const seen = new Set();
+  for (const option of args) {
+    const kind = START_OPTIONS.get(option);
+    if (!kind || seen.has(kind)) unexpectedArgs([option]);
+    seen.add(kind);
+  }
+  return baseCommand("start", {
+    configureClaudeDesktop: seen.has("configure-claude-app"),
+    showRequestId: seen.has("show-request-id"),
+  });
+}
+
 export function parseCliArgs(args = []) {
   const [command, ...rest] = args;
-  if (!command) return { command: "start", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+  if (!command) return baseCommand("start");
   if (HELP_COMMANDS.has(command)) {
-    if (rest.length) unexpectedArgs(rest);
-    return { command: "help", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+    const topic = rest[0] === "auth" && rest[1] === "login" && rest[2] === "claude"
+      ? ["auth", "login"]
+      : rest;
+    if (topic.length > 2) unexpectedArgs(topic.slice(2));
+    return helpCommand(topic);
   }
+  const requestedHelp = nestedHelp(command, rest);
+  if (requestedHelp) return requestedHelp;
   if (VERSION_COMMANDS.has(command)) {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "version", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+    return baseCommand("version");
   }
+  if (command === "start") return parseStartOptions(rest);
   if (command === "status" || command === "--status") {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "status", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+    return baseCommand("status");
   }
   if (command === "usage") {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "usage", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+    return baseCommand("usage");
   }
-  if (command === "pms") {
+  if (PM_COMMANDS.has(command)) {
     const [action, ...pmsArgs] = rest;
-    if (!action) throw new Error("Missing pms action: expected setup");
-    if (action !== "setup") throw new Error(`Unknown pms action: ${action}`);
+    if (!action) throw new Error("Missing pms action: expected setup or status");
+    if (!new Set(["setup", "status"]).has(action)) throw new Error(`Unknown pms action: ${action}`);
     if (pmsArgs.length) unexpectedArgs(pmsArgs);
-    return { command: "pms", action: "setup", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+    return baseCommand("pms", { action });
   }
   if (command === "models") {
     const options = parseOptions(rest, new Map([["--profile", "value"]]));
     return {
-      command: "models",
-      configureClaudeDesktop: false,
-      showRequestId: false,
-      online: false,
-      compat: false,
+      ...baseCommand("models"),
       profile: checkedProfile(options["--profile"]),
     };
   }
@@ -82,13 +161,10 @@ export function parseCliArgs(args = []) {
     if (action === "status") {
       const options = parseOptions(authArgs, new Map([["--online", "flag"]]));
       return {
-        command: "auth",
+        ...baseCommand("auth"),
         action: "status",
         profile: "",
-        configureClaudeDesktop: false,
-        showRequestId: false,
         online: Boolean(options["--online"]),
-        compat: false,
         expectedLogin: "",
         reauth: false,
       };
@@ -102,13 +178,9 @@ export function parseCliArgs(args = []) {
         ["--reauth", "flag"],
       ]));
       return {
-        command: "auth",
+        ...baseCommand("auth"),
         action: "login",
         profile: "claude",
-        configureClaudeDesktop: false,
-        showRequestId: false,
-        online: false,
-        compat: false,
         expectedLogin: options["--github-login"] || "",
         reauth: Boolean(options["--reauth"]),
       };
@@ -117,7 +189,7 @@ export function parseCliArgs(args = []) {
   }
   if (command === "auto-review-model") {
     if (rest.length) unexpectedArgs(rest);
-    return { command: "auto-review-model", configureClaudeDesktop: false, showRequestId: false, online: false, compat: false };
+    return baseCommand("auto-review-model");
   }
   if (command === "update") {
     if (rest.length > 1) unexpectedArgs(rest.slice(1));
@@ -126,11 +198,7 @@ export function parseCliArgs(args = []) {
       throw new Error(`Update source must be npm or github: ${source}`);
     }
     return {
-      command: "update",
-      configureClaudeDesktop: false,
-      showRequestId: false,
-      online: false,
-      compat: false,
+      ...baseCommand("update"),
       updateSource: source === "gh" ? "github" : source,
     };
   }
@@ -141,29 +209,13 @@ export function parseCliArgs(args = []) {
       ["--profile", "value"],
     ]));
     return {
-      command: "doctor",
-      configureClaudeDesktop: false,
-      showRequestId: false,
+      ...baseCommand("doctor"),
       online: Boolean(options["--online"]),
       compat: Boolean(options["--compat"]),
       profile: checkedProfile(options["--profile"], { allowAll: true }),
     };
   }
-  if (START_OPTIONS.has(command)) {
-    const options = [command, ...rest];
-    const invalid = options.filter((arg) => !START_OPTIONS.has(arg));
-    if (invalid.length) unexpectedArgs(invalid);
-    for (const option of START_OPTIONS) {
-      if (options.filter((arg) => arg === option).length > 1) unexpectedArgs([option]);
-    }
-    return {
-      command: "start",
-      configureClaudeDesktop: options.includes("--configure-claude-desktop"),
-      showRequestId: options.includes("--show-request-id"),
-      online: false,
-      compat: false,
-    };
-  }
+  if (START_OPTIONS.has(command)) return parseStartOptions([command, ...rest]);
   throw new Error(`Unknown command or option: ${command}`);
 }
 
@@ -207,16 +259,39 @@ export function cliCommandName(executable = process.argv[1]) {
   return CLI_COMMANDS.has(name) ? name : "ccdx";
 }
 
-export function cliHelp(commandName = "ccdx") {
+function topicHelp(name, topic) {
+  const sections = {
+    start: `Usage:\n  ${name} [start] [--configure-claude-app] [--show-request-id]\n\nStarts or reuses the local adapter, updates Codex and Claude Code configuration, and opens Codex.\n--configure-claude-app also creates or updates the managed Claude App gateway profile.`,
+    auth: `Usage:\n  ${name} auth status [--online]\n  ${name} auth login claude [--github-login <login>] [--reauth]\n\nShows the two account profiles or configures the isolated Claude account. Device login starts only when no reusable local Copilot credential is available or --reauth is used.`,
+    "auth status": `Usage:\n  ${name} auth status [--online]\n\nShows account routing without exposing credentials. --online also verifies both configured Copilot entitlements and model catalogs.`,
+    "auth login": `Usage:\n  ${name} auth login claude [--github-login <login>] [--reauth]\n\nReuses a compatible local Copilot credential when possible. --reauth forces GitHub Device Flow.`,
+    doctor: `Usage:\n  ${name} doctor [--online] [--compat] [--profile codex|claude|all]\n\nChecks local credentials, client configuration, PM Studio state, and the adapter. --online validates account entitlement; --compat sends minimal inference requests and consumes a small amount of Copilot usage.`,
+    status: `Usage:\n  ${name} status\n\nShows bounded runtime, routing, performance, cache, queue, and PM relay metrics from a running adapter.`,
+    models: `Usage:\n  ${name} models [--profile codex|claude]\n\nPerforms a fresh, read-only Copilot model-directory lookup for one saved profile.`,
+    pms: `Usage:\n  ${name} pms status\n  ${name} pms setup\n  ${name} pm-studio status\n  ${name} pm-studio setup\n\nInspects or installs the version-locked PM Studio loopback patch. setup modifies the installed app only after all preflight checks pass.`,
+    "pms setup": `Usage:\n  ${name} pms setup\n\nBacks up, patches, verifies, and ad-hoc signs an exactly supported PM Studio bundle. Unknown versions and drift are never modified.`,
+    "pms status": `Usage:\n  ${name} pms status\n\nRead-only inspection of the installed PM Studio version, patch integrity, Claude profile, and relay availability.`,
+    usage: `Usage:\n  ${name} usage\n\nSummarizes local token usage metadata without reading prompt or completion content.`,
+    "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nInteractively selects an enabled Responses model for Codex Auto-review.`,
+    update: `Usage:\n  ${name} update [npm|github]\n\nUpdates the global package from the configured npm registry or GitHub main. With no source, an interactive terminal prompts for one.`,
+    version: `Usage:\n  ${name} --version`,
+  };
+  return sections[topic];
+}
+
+export function cliHelp(commandName = "ccdx", topic = "") {
   const name = CLI_COMMANDS.has(commandName) ? commandName : "ccdx";
   const alias = name === "ccdx" ? "codex-copilot-dx" : "ccdx";
+  const normalizedTopic = checkedHelpTopic(topic ? topic.split(" ") : []);
+  if (normalizedTopic) return `${topicHelp(name, normalizedTopic)}\n\nEquivalent command: ${alias}`;
   return `Usage:
-  ${name} [--configure-claude-desktop] [--show-request-id]
+  ${name} [start] [--configure-claude-app] [--show-request-id]
   ${name} auth status [--online]
   ${name} auth login claude [--github-login <login>] [--reauth]
   ${name} doctor [--online] [--compat] [--profile codex|claude|all]
   ${name} status
   ${name} models [--profile codex|claude]
+  ${name} pms status
   ${name} pms setup
   ${name} usage
   ${name} auto-review-model
@@ -224,5 +299,18 @@ export function cliHelp(commandName = "ccdx") {
   ${name} --version
   ${name} --help
 
+Commands:
+  start              Start or reuse the adapter and configure local clients
+  auth               Inspect or configure the Codex and Claude accounts
+  doctor             Diagnose local config; optional live and inference checks
+  status             Show runtime routing, performance, queue, and cache health
+  models             Query a saved account's live Copilot model catalog
+  pms, pm-studio     Inspect or install the PM Studio patch
+  usage              Summarize locally recorded token usage
+  auto-review-model  Select the Codex Auto-review Responses model
+  update             Update the global package from npm or GitHub
+
+Run ${name} <command> --help for command details.
+
 Equivalent command: ${alias}`;
 }

package/src/cli-status.mjs

@@ -70,6 +70,33 @@ function routingTarget(value) {
   return "unknown";
 }
 
+function pmRouteSummary(requests = {}) {
+  const routes = requests.by_route;
+  if (!routes || typeof routes !== "object") return null;
+  const names = ["pm_models", "pm_chat_completions", "pm_responses", "pm_embeddings"];
+  const totals = names.reduce((summary, name) => {
+    const route = routes[name] || {};
+    summary.total += finiteNumber(route.total) || 0;
+    summary.active += finiteNumber(route.active) || 0;
+    summary.errors += finiteNumber(route.errors) || 0;
+    return summary;
+  }, { total: 0, active: 0, errors: 0 });
+  return `PM relay: ${count(totals.total)} requests, ${count(totals.active)} active, ${count(totals.errors)} errors; models ${count(routes.pm_models?.total)}, chat ${count(routes.pm_chat_completions?.total)}, responses ${count(routes.pm_responses?.total)}, embeddings ${count(routes.pm_embeddings?.total)}`;
+}
+
+function errorCode(error) {
+  const seen = new Set();
+  const pending = [error];
+  while (pending.length) {
+    const current = pending.shift();
+    if (!current || typeof current !== "object" || seen.has(current)) continue;
+    seen.add(current);
+    if (typeof current.code === "string") return current.code;
+    pending.push(current.cause, ...(Array.isArray(current.errors) ? current.errors : []));
+  }
+  return "";
+}
+
 export async function readAdapterStatus({
   host = "127.0.0.1",
   port = 2026,
@@ -101,12 +128,16 @@ export async function readAdapterStatus({
     }
     return { baseUrl, data };
   } catch (error) {
+    const code = errorCode(error);
     const reason = ctrl.signal.aborted
       ? `timed out after ${timeoutMs}ms`
-      : error?.cause?.code === "ECONNREFUSED"
+      : code === "ECONNREFUSED" || code === "ENETUNREACH"
         ? "adapter is not running"
         : error?.message || String(error);
-    throw new Error(`Could not read adapter status at ${baseUrl}: ${reason}`);
+    const nextStep = reason === "adapter is not running"
+      ? `. Run ccdx start, then retry ccdx status`
+      : "";
+    throw new Error(`Could not read adapter status at ${baseUrl}: ${reason}${nextStep}`);
   } finally {
     clearTimeout(timer);
   }
@@ -143,6 +174,8 @@ export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", c
   if (data.routing) {
     lines.push(status("info", `Routing: /v1/responses -> ${routingTarget(data.routing.responses)}; /v1/messages -> ${routingTarget(data.routing.messages)}`));
   }
+  const pmSummary = pmRouteSummary(requests);
+  if (pmSummary) lines.push(status("info", pmSummary));
   lines.push(status("info", `Limits: request body ${mebibytes(limits.max_body_bytes)}, decoded body ${mebibytes(limits.max_decoded_body_bytes)}`));
   return lines.join("\n");
 }

package/src/doctor.mjs

@@ -251,7 +251,11 @@ export function inspectAuthProfiles({ home = os.homedir() } = {}) {
     if (!claude.configured) {
       checks.push({ kind: "ok", message: "Claude authentication profile is not isolated and inherits Codex" });
     } else if (!claude.valid) {
-      checks.push({ kind: "err", message: `Claude isolated authentication profile is invalid: ${claude.reason}` });
+      checks.push({
+        kind: "err",
+        message: `Claude isolated authentication profile is invalid: ${claude.reason}`,
+        fix: "ccdx auth login claude --reauth",
+      });
     } else {
       const account = claude.identity?.login ? ` for ${claude.identity.login}` : "";
       checks.push({ kind: "ok", message: `Claude isolated authentication profile is configured${account}` });
@@ -455,7 +459,11 @@ export function inspectClaudeAppConfig({
   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" });
+    checks.push({
+      kind: "warn",
+      message: "Claude App gateway profile is not configured",
+      fix: "ccdx start --configure-claude-app",
+    });
     return checks;
   }
 
@@ -508,6 +516,7 @@ export async function collectDoctorChecks({
   host = "127.0.0.1",
   port = 2026,
   checkAdapter = true,
+  checkPmStudio = checkAdapter,
   checkAdapterListeningFn = checkAdapterListening,
   checkRunningAdapterFn = checkRunningAdapter,
   online = false,
@@ -517,6 +526,7 @@ export async function collectDoctorChecks({
   onlineTimeoutMs = 10000,
   compatTimeoutMs = 120000,
   inspectAdapterCompatibilityFn = inspectAdapterCompatibility,
+  inspectPmStudioHealthFn,
 } = {}) {
   const checks = [
     ...inspectAuthProfiles({ home }),
@@ -552,7 +562,43 @@ export async function collectDoctorChecks({
       const listening = await checkAdapterListeningFn({ host, port });
       checks.push(listening
         ? { kind: "warn", message: `A service is listening on ${localGatewayBaseUrl(host, port)}, but it is not a compatible codex-copilot-dx adapter` }
-        : { kind: "warn", message: `Adapter is not listening on ${localGatewayBaseUrl(host, port)}` });
+        : {
+          kind: "warn",
+          message: `Adapter is not listening on ${localGatewayBaseUrl(host, port)}`,
+          fix: "ccdx start",
+        });
+    }
+  }
+
+  if (checkPmStudio && platform === "darwin") {
+    const inspect = inspectPmStudioHealthFn || (async (options) => {
+      const module = await import("./pm-studio-status.mjs");
+      return module.inspectPmStudioStatus(options);
+    });
+    const pm = await inspect({ home });
+    const version = pm.app.metadata ? `${pm.app.metadata.version} build ${pm.app.metadata.build}` : "";
+    if (pm.app.state === "patched") {
+      checks.push({ kind: "ok", message: `PM Studio ${version} patch is verified` });
+      if (!pm.claude.valid) {
+        checks.push({
+          kind: "warn",
+          message: "PM Studio Claude routing requires a valid isolated Claude profile",
+          fix: "ccdx auth login claude --reauth",
+        });
+      }
+      if (!pm.adapter?.ok) {
+        checks.push({ kind: "warn", message: "PM Studio relay is not currently available", fix: "ccdx start" });
+      }
+    } else if (pm.app.state === "clean") {
+      checks.push({
+        kind: "warn",
+        message: `PM Studio ${version} is supported but not patched`,
+        fix: "ccdx pms setup",
+      });
+    } else if (pm.app.state === "unsupported") {
+      checks.push({ kind: "warn", message: `PM Studio ${version} has no exact patch recipe; no files will be changed` });
+    } else if (pm.app.state === "drift" || pm.app.state === "error") {
+      checks.push({ kind: "err", message: `PM Studio integrity check failed: ${pm.app.issues.join("; ")}` });
     }
   }
 
@@ -604,5 +650,12 @@ export async function runDoctor(options = {}) {
   log(`${options.commandName || "ccdx"} doctor${flags.length ? ` ${flags.join(" ")}` : ""}`);
   const checks = await collectDoctorChecks(options);
   for (const check of checks) log(status(check.kind, check.message));
+  const totals = { ok: 0, warn: 0, err: 0 };
+  for (const check of checks) totals[check.kind] = (totals[check.kind] || 0) + 1;
+  log(status(totals.err ? "err" : totals.warn ? "warn" : "ok",
+    `Summary: ${totals.ok} passed, ${totals.warn} warning(s), ${totals.err} error(s)`));
+  for (const fix of new Set(checks.map((check) => check.fix).filter(Boolean))) {
+    log(status("info", `Next step: ${fix}`));
+  }
   return checks;
 }

package/src/observability.mjs

@@ -4,6 +4,7 @@ import { copilotRuntimeStatus } from "./copilot.mjs";
 import { imageOptimizationStats } from "./image-optimization.mjs";
 import { responseHistoryStats } from "./response-history.mjs";
 import { loadRuntimeConfig } from "./runtime-config.mjs";
+import { profileRouting } from "./profile-routing.mjs";
 
 export { ADAPTER_STATUS_PATH };
 const OBSERVABILITY_RUNTIME_CONFIG = loadRuntimeConfig();
@@ -191,10 +192,7 @@ export function runtimeStatusPayload({
       codex: { mode: "legacy", client: codexRuntime, models: codexModels },
       claude: { mode: resolvedClaudeMode, client: claudeRuntime, models: claudeModels },
     },
-    routing: {
-      responses: "codex",
-      messages: resolvedClaudeMode === "isolated" ? "claude" : "codex",
-    },
+    routing: profileRouting({ claudeMode: resolvedClaudeMode }),
     limits: {
       max_body_bytes: OBSERVABILITY_RUNTIME_CONFIG.maxBodyBytes,
       max_decoded_body_bytes: OBSERVABILITY_RUNTIME_CONFIG.maxDecodedBodyBytes,

package/src/pm-studio-relay.mjs

@@ -10,6 +10,7 @@ import {
   writeOrDrain,
 } from "./http-transport.mjs";
 import { isLoopbackAddress } from "./observability.mjs";
+import { createPmStudioModelRouter } from "./profile-routing.mjs";
 import { loadRuntimeConfig, parsePositiveInteger } from "./runtime-config.mjs";
 import { requireUpstreamEventStream } from "./stream-contract.mjs";
 import { safeUpstreamResponseHeaders } from "./upstream-headers.mjs";
@@ -147,48 +148,6 @@ function catalogData(catalog) {
   return Array.isArray(catalog?.data) ? catalog.data : null;
 }
 
-function originalClaudeModels(registry) {
-  return catalogData(registry?.models) || [];
-}
-
-function isClaudeCatalogEntry(model) {
-  const id = String(model?.id || "").trim();
-  const vendor = String(model?.vendor || "").trim().toLowerCase();
-  return Boolean(id) && (vendor === "anthropic" || id.toLowerCase().startsWith("claude-"));
-}
-
-function isAllowedClaudeModel(model) {
-  return isClaudeCatalogEntry(model)
-    && String(model?.vendor || "").trim().toLowerCase() === "anthropic"
-    && model?.model_picker_enabled !== false
-    && Array.isArray(model?.supported_endpoints)
-    && model.supported_endpoints.includes("/chat/completions");
-}
-
-function claudeAvailability(options) {
-  const enabled = options.claudeMode === "isolated"
-    && options.claudeProfile?.valid === true
-    && typeof options.claudeClient?.chatCompletions === "function";
-  const catalog = originalClaudeModels(options.claudeModelRegistry);
-  const allowed = new Map();
-  const known = new Set();
-  for (const model of catalog) {
-    const id = String(model?.id || "").trim();
-    if (!id || !isClaudeCatalogEntry(model)) continue;
-    known.add(id);
-    if (enabled && isAllowedClaudeModel(model) && !allowed.has(id)) allowed.set(id, model);
-  }
-  return { allowed, known };
-}
-
-function classifyModel(modelId, options) {
-  const id = String(modelId || "").trim();
-  const { allowed, known } = claudeAvailability(options);
-  if (allowed.has(id)) return "claude";
-  if (known.has(id) || id.toLowerCase().startsWith("claude-")) return "unsupported_claude";
-  return "enterprise";
-}
-
 async function responseSnapshot(response) {
   return {
     status: response.status,
@@ -218,10 +177,10 @@ function rejectUpstreamRedirect(response) {
   return response;
 }
 
-function mergeModelCatalog(snapshot, options) {
+function mergeModelCatalog(snapshot, modelRouter) {
   if (!snapshot.ok) return null;
-  const { allowed } = claudeAvailability(options);
-  if (!allowed.size) return null;
+  const allowed = modelRouter.allowedModels();
+  if (!allowed.length) return null;
   let enterprise;
   try {
     enterprise = JSON.parse(snapshot.body.toString("utf8"));
@@ -232,7 +191,8 @@ function mergeModelCatalog(snapshot, options) {
   if (!data) return null;
   const seen = new Set(data.map((model) => String(model?.id || "").trim()).filter(Boolean));
   const additions = [];
-  for (const [id, model] of allowed) {
+  for (const model of allowed) {
+    const id = String(model?.id || "").trim();
     if (seen.has(id)) continue;
     seen.add(id);
     additions.push(model);
@@ -332,6 +292,12 @@ export function createPmStudioRelayHandler(options = {}) {
   const validated = new Map();
   const validationFlights = new Map();
   let activeModelRequests = 0;
+  const modelRouter = createPmStudioModelRouter({
+    getCatalog: () => options.claudeModelRegistry?.models,
+    isClaudeEnabled: () => options.claudeMode === "isolated"
+      && options.claudeProfile?.valid === true
+      && typeof options.claudeClient?.chatCompletions === "function",
+  });
 
   function isValidated(fingerprint) {
     const expiresAt = validated.get(fingerprint);
@@ -452,7 +418,7 @@ export function createPmStudioRelayHandler(options = {}) {
       sendSnapshot(res, snapshot);
       return;
     }
-    const merged = mergeModelCatalog(snapshot, options);
+    const merged = mergeModelCatalog(snapshot, modelRouter);
     if (!merged) {
       sendSnapshot(res, snapshot);
       return;
@@ -480,7 +446,7 @@ export function createPmStudioRelayHandler(options = {}) {
       }
       abort.setTimeout(requestTimeoutMs, timeoutReason);
 
-      const modelType = classifyModel(body?.model, options);
+      const modelType = modelRouter.classify(body?.model);
       if (modelType === "unsupported_claude" || (modelType === "claude" && pathname !== "/chat/completions")) {
         throw localError(400, "model_not_supported", "The requested Claude model is not available for this endpoint");
       }

package/src/pm-studio-status.mjs

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  AUTH_PROFILE_CLAUDE,
+  readAuthProfileCredentials,
+} from "./auth-profile.mjs";
+import { PM_STUDIO_RECIPES } from "./pm-studio-asar.mjs";
+import {
+  createPmStudioSetupOperations,
+  DEFAULT_PM_STUDIO_APP_PATH,
+  inspectPmStudioApp,
+  PM_STUDIO_CLAUDE_AUTH_COMMAND,
+} from "./pm-studio-setup.mjs";
+import { checkRunningAdapter } from "./running-adapter.mjs";
+import { status } from "./status.mjs";
+
+const PM_RELAY_HOST = "127.0.0.1";
+const PM_RELAY_PORT = 2026;
+
+function selectRecipe(metadata, recipes) {
+  return recipes.find((recipe) => recipe.version === String(metadata.version)
+    && recipe.build === String(metadata.build)
+    && recipe.bundleIdentifier === String(metadata.bundleIdentifier));
+}
+
+function safeMessage(error) {
+  return String(error?.message || "inspection failed").replace(/\s+/g, " ").trim();
+}
+
+function inspectClaudeProfile(home, readCredentials) {
+  try {
+    const credentials = readCredentials(AUTH_PROFILE_CLAUDE, { home });
+    return {
+      configured: credentials.configured === true,
+      valid: credentials.valid === true,
+      reason: credentials.reason || "",
+      login: credentials.identity?.login || "",
+    };
+  } catch (error) {
+    return { configured: true, valid: false, reason: safeMessage(error), login: "" };
+  }
+}
+
+export async function inspectPmStudioStatus({
+  appPath = DEFAULT_PM_STUDIO_APP_PATH,
+  home = os.homedir(),
+  recipes = PM_STUDIO_RECIPES,
+  operationOverrides = {},
+  existsSync = fs.existsSync,
+  inspectApp = inspectPmStudioApp,
+  readClaudeCredentials = readAuthProfileCredentials,
+  checkRunningAdapterFn = checkRunningAdapter,
+} = {}) {
+  const operations = createPmStudioSetupOperations(operationOverrides);
+  let app;
+  if (!existsSync(appPath)) {
+    app = { state: "not_installed", metadata: null, issues: [] };
+  } else {
+    try {
+      const metadata = operations.readBundleMetadata({
+        appPath,
+        infoPlistPath: path.join(appPath, "Contents/Info.plist"),
+        processRunner: operations.processRunner,
+      });
+      const normalized = {
+        version: String(metadata.version),
+        build: String(metadata.build),
+        bundleIdentifier: String(metadata.bundleIdentifier),
+      };
+      const recipe = selectRecipe(normalized, recipes);
+      app = recipe
+        ? { ...inspectApp({ appPath, recipe, operations }), recipe: recipe.id }
+        : { state: "unsupported", metadata: normalized, issues: [], recipe: "" };
+    } catch (error) {
+      app = { state: "error", metadata: null, issues: [safeMessage(error)], recipe: "" };
+    }
+  }
+
+  const claude = inspectClaudeProfile(home, readClaudeCredentials);
+  let adapter;
+  try {
+    adapter = await checkRunningAdapterFn({ host: PM_RELAY_HOST, port: PM_RELAY_PORT });
+  } catch (error) {
+    adapter = { ok: false, error };
+  }
+  const operational = app.state === "patched" && claude.valid && adapter?.ok === true;
+  return { ok: operational, appPath, app, claude, adapter };
+}
+
+function appStatusLine(result, commandName) {
+  const { app } = result;
+  const version = app.metadata ? `${app.metadata.version} build ${app.metadata.build}` : "";
+  if (app.state === "patched") return status("ok", `PM Studio ${version} is patched and verified`);
+  if (app.state === "clean") return status("warn", `PM Studio ${version} is supported but not patched; run ${commandName} pms setup`);
+  if (app.state === "unsupported") return status("err", `PM Studio ${version} has no exact patch recipe; no files will be changed`);
+  if (app.state === "drift") return status("err", `PM Studio ${version} does not match the clean or patched recipe: ${app.issues.join("; ")}`);
+  if (app.state === "not_installed") return status("warn", `PM Studio is not installed at ${result.appPath}`);
+  return status("err", `PM Studio could not be inspected: ${app.issues.join("; ")}`);
+}
+
+export function formatPmStudioStatus(result, { commandName = "ccdx" } = {}) {
+  const lines = [
+    `${commandName} pms status`,
+    appStatusLine(result, commandName),
+  ];
+  if (result.claude.valid) {
+    const account = result.claude.login ? ` for ${result.claude.login}` : "";
+    lines.push(status("ok", `Isolated Claude profile is valid${account}`));
+  } else {
+    const reason = result.claude.configured && result.claude.reason ? ` (${result.claude.reason})` : "";
+    lines.push(status("err", `Isolated Claude profile is not ready${reason}; run ${PM_STUDIO_CLAUDE_AUTH_COMMAND}`));
+  }
+  if (result.adapter?.ok) {
+    lines.push(status("ok", `PM relay is available at ${result.adapter.baseUrl}`));
+  } else if (result.adapter?.incompatible) {
+    lines.push(status("err", `The adapter at ${result.adapter.baseUrl} is incompatible; stop it and run ${commandName} start`));
+  } else {
+    lines.push(status("warn", `PM relay is not running at http://${PM_RELAY_HOST}:${PM_RELAY_PORT}; run ${commandName} start`));
+  }
+  lines.push(status("info", "Routing: PM GPT uses the PM Studio bearer; eligible Claude chat uses the isolated Claude profile"));
+  return lines.join("\n");
+}
+
+export async function runPmStudioStatus(options = {}) {
+  const result = await inspectPmStudioStatus(options);
+  const output = formatPmStudioStatus(result, options);
+  (options.log || console.log)(output);
+  return { ...result, output };
+}

package/src/profile-model-runtime.mjs

@@ -33,6 +33,7 @@ export function createProfileModelRuntime({
   codexClient,
   claudeClient = codexClient,
   claudeMode = "inherited",
+  codexCredentialFingerprint = "",
   claudeCredentialFingerprint = "",
   home,
   env = process.env,
@@ -93,7 +94,7 @@ export function createProfileModelRuntime({
   function loadCached({ client, profile, registry, ownsClaudeModels }) {
     const credentialFingerprint = profile === "claude"
       ? String(claudeCredentialFingerprint || "").trim()
-      : "";
+      : String(codexCredentialFingerprint || "").trim();
     if (profile === "claude" && !credentialFingerprint) return false;
     const cached = loadModelCache({ home, profile, credentialFingerprint });
     if (!cached) return false;
@@ -133,7 +134,7 @@ export function createProfileModelRuntime({
   function persist(models, profile) {
     const credentialFingerprint = profile === "claude"
       ? String(claudeCredentialFingerprint || "").trim()
-      : "";
+      : String(codexCredentialFingerprint || "").trim();
     if (profile === "claude" && !credentialFingerprint) return;
     try {
       saveModelCache(models, { home, profile, credentialFingerprint });

package/src/profile-routing.mjs

@@ -0,0 +1,74 @@
+function catalogData(catalog) {
+  if (Array.isArray(catalog)) return catalog;
+  return Array.isArray(catalog?.data) ? catalog.data : [];
+}
+
+function isClaudeCatalogEntry(model) {
+  const id = String(model?.id || "").trim();
+  const vendor = String(model?.vendor || "").trim().toLowerCase();
+  return Boolean(id) && (vendor === "anthropic" || id.toLowerCase().startsWith("claude-"));
+}
+
+function isAllowedClaudeModel(model) {
+  return isClaudeCatalogEntry(model)
+    && String(model?.vendor || "").trim().toLowerCase() === "anthropic"
+    && model?.model_picker_enabled !== false
+    && Array.isArray(model?.supported_endpoints)
+    && model.supported_endpoints.includes("/chat/completions");
+}
+
+export function profileRouting({ claudeMode = "inherited", claudeConfigured = false } = {}) {
+  const isolated = claudeMode === "isolated" || claudeConfigured === true;
+  return Object.freeze({ responses: "codex", messages: isolated ? "claude" : "codex" });
+}
+
+export function createPmStudioModelRouter({ getCatalog, isClaudeEnabled } = {}) {
+  if (typeof getCatalog !== "function") throw new Error("getCatalog is required");
+  if (typeof isClaudeEnabled !== "function") throw new Error("isClaudeEnabled is required");
+
+  const unset = Symbol("unset");
+  let cachedCatalog = unset;
+  let cachedEnabled = false;
+  let cachedAllowed = new Map();
+  let cachedKnown = new Set();
+  let rebuilds = 0;
+
+  function availability() {
+    const catalog = getCatalog();
+    const enabled = isClaudeEnabled() === true;
+    if (catalog === cachedCatalog && enabled === cachedEnabled) {
+      return { allowed: cachedAllowed, known: cachedKnown };
+    }
+
+    const allowed = new Map();
+    const known = new Set();
+    for (const model of catalogData(catalog)) {
+      const id = String(model?.id || "").trim();
+      if (!id || !isClaudeCatalogEntry(model)) continue;
+      known.add(id);
+      if (enabled && isAllowedClaudeModel(model) && !allowed.has(id)) allowed.set(id, model);
+    }
+    cachedCatalog = catalog;
+    cachedEnabled = enabled;
+    cachedAllowed = allowed;
+    cachedKnown = known;
+    rebuilds += 1;
+    return { allowed, known };
+  }
+
+  return Object.freeze({
+    classify(modelId) {
+      const id = String(modelId || "").trim();
+      const { allowed, known } = availability();
+      if (allowed.has(id)) return "claude";
+      if (known.has(id) || id.toLowerCase().startsWith("claude-")) return "unsupported_claude";
+      return "enterprise";
+    },
+    allowedModels() {
+      return [...availability().allowed.values()];
+    },
+    diagnostics() {
+      return { rebuilds, allowed: cachedAllowed.size, known: cachedKnown.size };
+    },
+  });
+}

package/src/profile-runtime.mjs

@@ -1,5 +1,6 @@
 import {
   AUTH_PROFILE_CLAUDE,
+  AUTH_PROFILE_CODEX,
   authProfilePaths,
   profileReauthMessage,
   readAuthProfileCredentials,
@@ -45,6 +46,16 @@ export function createProfileRuntime({
   };
   const credentials = readCredentials();
   const claudeProfile = safeProfileStatus(credentials);
+  let codexCredentialFingerprint = "";
+  try {
+    const codexCredentials = readAuthProfileCredentials(AUTH_PROFILE_CODEX, { home });
+    if (codexCredentials.valid) {
+      codexCredentialFingerprint = githubTokenFingerprint(codexCredentials.token);
+    }
+  } catch {
+    // The Codex client remains authoritative if its optional metadata cannot
+    // be inspected; only credential-bound cache reuse is disabled.
+  }
 
   if (!credentials.configured) {
     return Object.freeze({
@@ -52,6 +63,7 @@ export function createProfileRuntime({
       claudeClient: codexClient,
       claudeMode: "inherited",
       claudeProfile,
+      codexCredentialFingerprint,
       claudeCredentialFingerprint: "",
     });
   }
@@ -73,6 +85,7 @@ export function createProfileRuntime({
     claudeClient,
     claudeMode: "isolated",
     claudeProfile,
+    codexCredentialFingerprint,
     claudeCredentialFingerprint: credentials.valid
       ? githubTokenFingerprint(credentials.token)
       : "",