@bitkyc08/opencodex 2.39.0 → 2.40.0

package/src/claude/gateway-cache.ts

@@ -26,6 +26,12 @@ export interface GatewayModelCacheRefreshOptions {
   configDir?: string;
   admissionConfig?: Pick<OcxConfig, "apiKeys">;
   env?: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+}
+
+export interface GatewayModelTarget {
+  baseUrl: string;
+  admissionToken: string;
 }
 
 /** Claude Code config dir (CLAUDE_CONFIG_DIR override honored, like the CLI). */
@@ -70,6 +76,14 @@ function serviceFileToken(env: NodeJS.ProcessEnv): string | null {
 /** Fetch the anthropic-flavor /v1/models from the local proxy and write the cache. */
 export async function refreshGatewayModelCacheFromProxy(
   port: number,
+  options?: GatewayModelCacheRefreshOptions,
+): Promise<string | null>;
+export async function refreshGatewayModelCacheFromProxy(
+  target: GatewayModelTarget,
+  options?: GatewayModelCacheRefreshOptions,
+): Promise<string | null>;
+export async function refreshGatewayModelCacheFromProxy(
+  portOrTarget: number | GatewayModelTarget,
   options: GatewayModelCacheRefreshOptions = {},
 ): Promise<string | null> {
   try {
@@ -82,12 +96,18 @@ export async function refreshGatewayModelCacheFromProxy(
     const configuredToken = options.admissionConfig?.apiKeys
       ?.find(entry => entry.key.trim().length > 0)
       ?.key.trim();
-    const admissionToken = envToken || serviceFileToken(options.env ?? process.env) || configuredToken;
+    const admissionToken = typeof portOrTarget === "number"
+      ? envToken || serviceFileToken(options.env ?? process.env) || configuredToken
+      : portOrTarget.admissionToken;
     if (admissionToken) headers.set("x-opencodex-api-key", admissionToken);
 
+    const baseUrl = typeof portOrTarget === "number"
+      ? `http://127.0.0.1:${portOrTarget}`
+      : new URL(portOrTarget.baseUrl).origin;
+
     // ?ids=cli pins the readable claude-ocx id family deterministically (audit 051
     // #5): the cache prewrite must not depend on UA sniffing.
-    const res = await fetch(`http://127.0.0.1:${port}/v1/models?limit=1000&ids=cli`, {
+    const res = await (options.fetchImpl ?? fetch)(`${baseUrl}/v1/models?limit=1000&ids=cli`, {
       headers,
       signal: AbortSignal.timeout(options.timeoutMs ?? 3_000),
     });
@@ -100,7 +120,7 @@ export async function refreshGatewayModelCacheFromProxy(
         id: m.id as string,
         display_name: typeof m.display_name === "string" ? m.display_name : undefined,
       }));
-    return writeGatewayModelCache(`http://127.0.0.1:${port}`, models, options.configDir);
+    return writeGatewayModelCache(baseUrl, models, options.configDir);
   } catch {
     return null;
   }

package/src/claude/model-info.ts

@@ -17,6 +17,7 @@
  */
 import { catalogModelEfforts, nativeEffortClamp, nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, type CatalogModel, type NativeContextLimitsInput } from "../codex/catalog";
 import { claudeCodeAlias, claudeCodeNativeAlias } from "./alias";
+import { cursorFastIdFor } from "../adapters/cursor/catalog";
 import { desktop3pAlias } from "./desktop-3p";
 import { AUTO_CONTEXT_OFF, type AutoContextMode } from "./context-windows";
 
@@ -109,6 +110,7 @@ export function buildAnthropicModelInfos(
   idStyle: AnthropicIdStyle = "desktop3p",
   aliasForRoute: (provider: string, modelId: string) => string = desktop3pAlias,
   nativeContextCap?: NativeContextLimitsInput,
+  fastMode?: boolean,
 ): AnthropicModelInfo[] {
   const out: AnthropicModelInfo[] = [];
   const seen = new Set<string>();
@@ -151,7 +153,16 @@ export function buildAnthropicModelInfos(
     push1mVariant(info, nativeWindow, nativeMaxInput);
   }
   for (const m of routedModels) {
-    const id = idStyle === "readable" ? claudeCodeAlias(m.provider, m.id) : aliasForRoute(m.provider, m.id);
+    // Global Fast has no toggle on this surface, so the fast identity is what gets listed —
+    // a client here can only pick a listed id. Limited to the readable CLI style: Desktop 3P
+    // ids are hashed from the model name, so rewriting them would strand a saved selection.
+    const fastModelId = fastMode === true && m.provider === "cursor" && idStyle === "readable"
+      ? cursorFastIdFor(m.id)
+      : undefined;
+    const listedModelId = fastModelId ?? m.id;
+    const id = idStyle === "readable"
+      ? claudeCodeAlias(m.provider, listedModelId)
+      : aliasForRoute(m.provider, m.id);
     if (seen.has(id)) continue;
     seen.add(id);
     const ladder = Array.isArray(m.reasoningEfforts) ? m.reasoningEfforts : [];
@@ -164,7 +175,7 @@ export function buildAnthropicModelInfos(
         ? Math.min(m.maxInputTokens, m.contextWindow)
         : m.maxInputTokens)
       : undefined;
-    const info = modelInfo(id, `${m.id} (${m.provider})`, ladder, imageInput, routedMaxInput ?? m.contextWindow);
+    const info = modelInfo(id, `${listedModelId} (${m.provider})`, ladder, imageInput, routedMaxInput ?? m.contextWindow);
     out.push(info);
     // Anthropic passthrough guard (audit 021 #3): never auto-widen canonical claude
     // routes — only a genuine >=1M window earns the variant row there.

package/src/cli/access.ts

@@ -12,6 +12,9 @@ import {
 const USAGE = `Usage:
   ocx access key [list] [--json]
   ocx access key create [name] [--json]
+  ocx access key rotate <id> [--json]
+  ocx access key rotate commit <id> <rotation-id> [--json]
+  ocx access key rotate abort <id> <rotation-id> [--json]
   ocx access key remove <id> --yes [--json]
   ocx access endpoints [--json]
   ocx access models [--json]
@@ -87,6 +90,33 @@ async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     ]);
     return;
   }
+  if (action === "rotate") {
+    const operation = args[0] === "commit" || args[0] === "abort" ? args.shift()! : "start";
+    const id = args.shift();
+    if (!id) throw new CliUsageError("key id is required", USAGE);
+    if (operation === "start") {
+      rejectArgs(args, USAGE);
+      const result = await runtimeRequest<Record<string, unknown>>("/api/keys/rotate", {
+        method: "POST",
+        body: JSON.stringify({ id }),
+      }, deps);
+      printData(result, wantsJson, [
+        `Started rotation for API key ${id}.`,
+        `New key (shown once): ${String(result.key ?? "")}`,
+        `After the client accepts it, commit with rotation id ${String(result.rotationId ?? "")}.`,
+      ]);
+      return;
+    }
+    const rotationId = args.shift();
+    if (!rotationId) throw new CliUsageError("rotation id is required", USAGE);
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest(operation === "commit" ? "/api/keys/rotate/commit" : "/api/keys/rotate", {
+      method: operation === "commit" ? "POST" : "DELETE",
+      body: JSON.stringify({ id, rotationId }),
+    }, deps);
+    printData(result, wantsJson, [`${operation === "commit" ? "Committed" : "Aborted"} rotation for API key ${id}.`]);
+    return;
+  }
   if (action === "remove" || action === "delete") {
     const id = args.shift();
     const yes = takeFlag(args, "--yes");

package/src/cli/account-extended.ts

@@ -347,9 +347,12 @@ export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<
   const action = args.shift();
   if (!name || !action) return usage();
   const classified = configAndType(deps, name);
-  if ("error" in classified || classified.type !== "codex") {
-    return usage("Error: auto-switch only applies to the openai Codex account pool");
+  // Anthropic keeps its threshold on its own pool contract; generic OAuth providers (#695)
+  // and the Codex pool are accepted here.
+  if ("error" in classified || classified.type === "api-key" || name === "anthropic") {
+    return usage("Error: auto-switch only applies to the openai Codex account pool or a generic OAuth provider pool");
   }
+  const genericPool = classified.type === "oauth";
   let threshold: number | undefined;
   if (action === "on" && args.length === 0) threshold = 80;
   else if (action === "off" && args.length === 0) threshold = 0;
@@ -361,14 +364,19 @@ export async function cmdAutoSwitch(args: string[], deps: AccountDeps): Promise<
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
   if (action === "status") {
-    const response = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/active");
+    const response = await apiJson(
+      deps, baseUrl, "GET",
+      genericPool ? `/api/oauth/accounts/pool?provider=${encodeURIComponent(name)}` : "/api/codex-auth/active",
+    );
     if (response.status === 0) return proxyUnreachable(response.transportError);
-    if (response.status !== 200 || typeof response.json.autoSwitchThreshold !== "number") {
+    if (response.status !== 200 || (!genericPool && typeof response.json.autoSwitchThreshold !== "number")) {
       return apiError(response.json, "failed to read auto-switch status", response.status);
     }
-    threshold = response.json.autoSwitchThreshold;
+    threshold = typeof response.json.autoSwitchThreshold === "number" ? response.json.autoSwitchThreshold : 0;
   } else {
-    const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/auto-switch", { threshold });
+    const response = genericPool
+      ? await apiJson(deps, baseUrl, "PUT", "/api/oauth/accounts/pool", { provider: name, autoSwitchThreshold: threshold })
+      : await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/auto-switch", { threshold });
     if (response.status === 0) return proxyUnreachable(response.transportError);
     if (response.status !== 200) return apiError(response.json, "failed to update auto-switch", response.status);
   }
@@ -846,16 +854,17 @@ function anthropicPoolTransport(provider: string): PoolTransport {
 }
 
 /**
- * The pool-config route supports `anthropic` only and says so with a 400. Any other OAuth
- * provider is refused here with the same wording rather than spending a round-trip to learn it.
+ * Codex and Anthropic keep their own pool transports; every other OAuth provider speaks the
+ * generic pool-settings contract on the same `/api/oauth/accounts/pool` route (#695).
+ * API-key providers have no pool and are refused here without a round-trip.
  */
 function poolTransportFor(
   classified: { type: "codex" | "oauth" | "api-key" },
   name: string,
 ): PoolTransport | string {
   if (classified.type === "codex") return CODEX_POOL_TRANSPORT;
-  if (classified.type === "oauth" && name === "anthropic") return anthropicPoolTransport(name);
-  return `pool settings apply to the openai Codex pool and the anthropic pool, not "${name}"`;
+  if (classified.type === "oauth") return anthropicPoolTransport(name);
+  return `pool settings apply to OAuth account pools, not the API-key provider "${name}"`;
 }
 
 /**

package/src/cli/capabilities.ts

@@ -107,6 +107,29 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "envelope",
     details: ["Reads /healthz plus local config; drives no management API route."],
   },
+  {
+    command: ["connect", "rotate"],
+    summary: "Rotate the connected client's data key against the hub, with commit and abort.",
+    // One command drives all three: start returns the new secret once, commit promotes it,
+    // and abort unwinds a rotation that could not be confirmed. They are not separate verbs
+    // because a half-rotation is not a state an operator should be able to leave behind.
+    routes: [
+      { method: "POST", path: "/api/keys/rotate" },
+      { method: "POST", path: "/api/keys/rotate/commit" },
+      { method: "DELETE", path: "/api/keys/rotate" },
+    ],
+    flags: [
+      { name: "--pairing-code-stdin", value: "boolean", summary: "Read a one-time pairing code from stdin as the rotation authority." },
+      { name: "--admin-token-stdin", value: "boolean", summary: "Read the hub admin token from stdin as the rotation authority." },
+      { name: "--json", value: "boolean", summary: "Emit the rotation result as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "Requires transient authority on stdin; the credential is never persisted or echoed.",
+      "A rotation left pending by a crash is resumed here — startup and status stop rather than guess which key generation is live.",
+    ],
+  },
   {
     command: ["capabilities"],
     summary: "List the declared CLI capabilities and the management routes they drive.",
@@ -130,6 +153,21 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "envelope",
     details: ["Reads local config; drives no management API route."],
   },
+  {
+    command: ["provider", "keychain"],
+    summary: "Move a provider's API key into the OS keychain, restore it, or report where it lives.",
+    routes: [
+      { method: "GET", path: "/api/providers/keychain" },
+      { method: "POST", path: "/api/providers/keychain" },
+    ],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the keychain status or result as JSON." }],
+    mutates: true,
+    json: "payload",
+    details: [
+      "`store` verifies every keychain write by read-back before config.json is rewritten with keychain: references; an unavailable keychain refuses with 503 and leaves the file untouched.",
+      "Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.",
+    ],
+  },
   {
     command: ["account", "list"],
     summary: "Codex OAuth accounts with pool priority and pause state.",
@@ -460,13 +498,14 @@ export const CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["integration", "native"],
-    summary: "Show or toggle the native Claude, Claude Desktop, Codex, and Grok integrations.",
+    summary: "Show or toggle the native Claude, Claude Desktop, Codex, and Grok integrations, and read the Cursor status (which builds are installed, gateway values, last request seen).",
     routes: [
       { method: "GET", path: "/api/native-integrations" },
       { method: "PUT", path: "/api/native-integrations/claude" },
       { method: "PUT", path: "/api/native-integrations/claude-desktop" },
       { method: "PUT", path: "/api/native-integrations/codex" },
       { method: "PUT", path: "/api/native-integrations/grok" },
+      { method: "GET", path: "/api/native-integrations/cursor" },
     ],
     flags: [{ name: "--json", value: "boolean", summary: "Emit the client rows or toggle result as JSON." }],
     mutates: true,

package/src/cli/claude-agent-startup-sync.ts

@@ -54,6 +54,9 @@ export async function syncClaudeAgentDefsAtProxyStartup(
   const warn = deps.warn ?? (message => console.warn(message));
 
   try {
+    // Hub role: never rewrite this host's ~/.claude roster on startup (same rule as
+    // shouldSyncCodexOnStart / shouldSyncGrokOnStart — the hub serves other machines).
+    if (config.runtimeRole === "hub") return null;
     if (config.claudeCode?.enabled === false || config.claudeCode?.injectAgents === false) {
       return inject(config, {});
     }

package/src/cli/claude.ts

@@ -21,11 +21,22 @@ import { resolveClaudeAuthMode } from "../claude/auth-mode";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { ANTHROPIC_PARENT_ENV_SLOTS, trustedNodeLauncherContext, type AnthropicParentEnvSlot } from "./launcher-context";
+import { readClientConnectionState } from "../client/state";
+import { readServiceApiTokenState } from "../lib/service-secrets";
+import { DEFAULT_CATALOG_PATH } from "../codex/paths";
+import { readFileSync } from "node:fs";
+import { aliasForNative, aliasForRoute } from "../claude/alias";
+import { desktop3pAlias } from "../claude/desktop-3p";
 
 export interface ClaudeLaunchEnv {
   [key: string]: string | undefined;
 }
 
+export interface ClaudeRoutingTarget {
+  baseUrl: string;
+  admissionToken: string;
+}
+
 /**
  * Injectable IO for tests. `env` is deliberately NOT injectable: it is bound to the
  * launch base so detection and the spawned process can never disagree (audit R3-3).
@@ -61,6 +72,20 @@ function targetsLocalClaudeProxy(value: string | undefined, port: number): boole
   }
 }
 
+function targetsClaudeRoutingTarget(value: string | undefined, target: ClaudeRoutingTarget): boolean {
+  if (!value) return false;
+  try {
+    const actual = new URL(value);
+    const expected = new URL(target.baseUrl);
+    return actual.origin === expected.origin
+      && (actual.pathname === "/" || actual.pathname === "")
+      && !actual.username
+      && !actual.password;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Pure env assembly (unit-tested): never sets ANTHROPIC_API_KEY (setting both
  * token vars triggers Claude Code's auth-conflict warning, 003 E1), and never
@@ -70,11 +95,14 @@ function targetsLocalClaudeProxy(value: string | undefined, port: number): boole
  */
 export function buildClaudeEnv(
   config: OcxConfig,
-  port: number,
+  portOrTarget: number | ClaudeRoutingTarget,
   base: ClaudeLaunchEnv,
   contextWindows: Record<string, number> = {},
   deps: ClaudeEnvDeps = {},
 ): ClaudeLaunchEnv {
+  const explicitTarget = typeof portOrTarget === "number" ? null : portOrTarget;
+  const port = typeof portOrTarget === "number" ? portOrTarget : null;
+  const managedBaseUrl = explicitTarget ? new URL(explicitTarget.baseUrl).origin : `http://127.0.0.1:${port}`;
   const env: ClaudeLaunchEnv = { ...base };
   // Step 1 — strip OUR OWN dummy from the inherited environment before anything reads
   // or writes the token slot. setDefault below preserves any non-empty value, so a
@@ -120,9 +148,9 @@ export function buildClaudeEnv(
   if (deps.allowRootSkipPermissions === true) {
     setDefault("IS_SANDBOX", "1");
   }
-  setDefault("ANTHROPIC_BASE_URL", `http://127.0.0.1:${port}`);
+  setDefault("ANTHROPIC_BASE_URL", managedBaseUrl);
   const existingBaseUrl = env.ANTHROPIC_BASE_URL;
-  if (existingBaseUrl) {
+  if (existingBaseUrl && port !== null) {
     try {
       const parsed = new URL(existingBaseUrl);
       const effectivePort = parsed.port === "" ? 80 : Number(parsed.port);
@@ -151,19 +179,23 @@ export function buildClaudeEnv(
   }
   // Subscription-preserving default (teamclaude --no-mitm / Vercel gateway pattern):
   // setting ANTHROPIC_AUTH_TOKEN/API_KEY disables claude.ai connectors and overrides
-  // the user's Claude login. Only inject a token when the proxy actually requires an
-  // admission key; otherwise Claude Code keeps its own OAuth and sends it to us —
-  // native claude models then pass through verbatim (see server/claude-messages.ts).
-  const ownTokens = ownAdmissionTokens(config);
-  const targetsLocalProxy = targetsLocalClaudeProxy(env.ANTHROPIC_BASE_URL, port);
+  // the user's Claude login. Resolve the mode before adding any proxy-owned credential:
+  // subscription launches must keep their OAuth, while proxy launches may use the
+  // admission key or dummy marker (see server/claude-messages.ts).
+  const ownTokens = explicitTarget ? [explicitTarget.admissionToken] : ownAdmissionTokens(config);
+  const targetsLocalProxy = explicitTarget
+    ? targetsClaudeRoutingTarget(env.ANTHROPIC_BASE_URL, explicitTarget)
+    : targetsLocalClaudeProxy(env.ANTHROPIC_BASE_URL, port!);
+  const isOwnAdmissionToken = (value: string): boolean =>
+    ownTokens.includes(value) || isProxyAdmissionSecret(value, config);
   const inheritedApiKey = env.ANTHROPIC_API_KEY;
-  if (typeof inheritedApiKey === "string" && isProxyAdmissionSecret(inheritedApiKey, config)) {
+  if (typeof inheritedApiKey === "string" && isOwnAdmissionToken(inheritedApiKey)) {
     delete env.ANTHROPIC_API_KEY;
   }
   const hasUserApiKey = Boolean(env.ANTHROPIC_API_KEY?.trim());
   const inheritedAuthToken = env.ANTHROPIC_AUTH_TOKEN;
   const inheritedTokenIsOurs = typeof inheritedAuthToken === "string"
-    && isProxyAdmissionSecret(inheritedAuthToken, config);
+    && isOwnAdmissionToken(inheritedAuthToken);
   // system-env may have injected the proxy's admission key into the parent. A
   // proof-bound external BASE_URL is still user-owned, so never let our inherited
   // key follow it. A user API key also wins on a local launch; remove only the token
@@ -172,24 +204,30 @@ export function buildClaudeEnv(
   if (inheritedTokenIsOurs && (!targetsLocalProxy || hasUserApiKey)) {
     delete env.ANTHROPIC_AUTH_TOKEN;
   }
-  if (targetsLocalProxy && !hasUserApiKey && ownTokens.length > 0) {
-    setDefault("ANTHROPIC_AUTH_TOKEN", ownTokens[0]);
-  }
-  // Detection reads the SANITIZED launch env — the exact object spawned below — so the
-  // resolver and the spawned process cannot disagree. It deliberately does NOT read the
-  // raw base: the provenance strip above already removed dotenv-only credentials, and
-  // letting a value the child never receives decide the marker left an auto-mode user
-  // with neither the credential NOR the proxy marker (#701 audit round 2). Injected deps
-  // are spread FIRST and `env` bound LAST, and the injection type excludes `env`, so a
-  // test fake cannot break that. `ownTokens` is bound last for the same reason: it is
-  // config-derived, and a fake that replaced it could make our own admission key look
-  // like user auth.
+  // Detection reads the sanitized launch env before proxy-owned credentials are added.
+  // The provenance strip above removed dotenv-only credentials, and ownTokens keeps a
+  // configured admission key from being mistaken for user auth (#701 audit round 2).
   const resolved = resolveClaudeAuthMode(config, detectClaudeAuth({
     ...defaultAuthDetectDeps(env as NodeJS.ProcessEnv),
     ...(deps.authDetect ?? {}),
     env: () => env as NodeJS.ProcessEnv,
     ownTokens,
   }));
+  // An explicit connected target is not a subscription launch. The caller named a hub and
+  // handed us the client admission token for it, so auth-mode detection - which reads the
+  // local environment - has no bearing on whether that token belongs in the child env.
+  // Without this, a machine whose environment reads as subscription strips the very
+  // credential the connected launch was constructed with (#3148 carry).
+  if (resolved.markerMode === "subscription" && !explicitTarget) {
+    // A prior system-env snapshot may have left our admission key in the inherited
+    // environment. It belongs to the proxy data plane, not Claude subscription OAuth.
+    const token = env.ANTHROPIC_AUTH_TOKEN?.trim();
+    if (token && (token === PROXY_MARKER || isProxyAdmissionSecret(token, config))) {
+      delete env.ANTHROPIC_AUTH_TOKEN;
+    }
+  } else if (targetsLocalProxy && !hasUserApiKey && ownTokens.length > 0) {
+    setDefault("ANTHROPIC_AUTH_TOKEN", ownTokens[0]);
+  }
   if (!env.ANTHROPIC_AUTH_TOKEN && !hasUserApiKey && targetsLocalProxy && resolved.markerMode === "proxy") {
     env.ANTHROPIC_AUTH_TOKEN = PROXY_MARKER;
   }
@@ -199,7 +237,7 @@ export function buildClaudeEnv(
     && typeof finalAuthToken === "string"
     && (
       finalAuthToken.trim() === PROXY_MARKER
-      || isProxyAdmissionSecret(finalAuthToken, config)
+      || isOwnAdmissionToken(finalAuthToken)
     );
   if (resolved.origin === "auto-unknown") {
     console.error("⚠ Claude 인증을 확인하지 못했습니다 — 구독 방식으로 진행합니다. GUI에서 인증 모드를 직접 지정하면 이 판단을 덮어쓸 수 있습니다.");
@@ -282,6 +320,40 @@ export async function fetchClaudeContextWindows(config: OcxConfig, port: number,
   }
 }
 
+export function readConnectedClaudeContextWindows(path = DEFAULT_CATALOG_PATH): Record<string, number> {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { models?: unknown };
+    if (!Array.isArray(parsed.models)) return {};
+    const out: Record<string, number> = {};
+    const put = (key: string, value: number) => { if (out[key] === undefined) out[key] = value; };
+    for (const row of parsed.models) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      const entry = row as Record<string, unknown>;
+      const slug = typeof entry.slug === "string" ? entry.slug : "";
+      const contextWindow = typeof entry.context_window === "number" && entry.context_window > 0
+        ? entry.context_window
+        : undefined;
+      if (!slug || contextWindow === undefined) continue;
+      put(slug, contextWindow);
+      const slash = slug.indexOf("/");
+      if (slash > 0 && slash < slug.length - 1) {
+        const provider = slug.slice(0, slash);
+        const id = slug.slice(slash + 1);
+        const routeAlias = aliasForRoute(provider, id);
+        if (routeAlias) put(routeAlias, contextWindow);
+        put(desktop3pAlias(provider, id), contextWindow);
+      } else {
+        const nativeAlias = aliasForNative(slug);
+        if (nativeAlias) put(nativeAlias, contextWindow);
+        put(desktop3pAlias("native", slug), contextWindow);
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
 async function ensureProxyForClaude(): Promise<number | null> {
   const live = await findLiveProxy();
   if (live) return live.port;
@@ -340,21 +412,45 @@ export async function cmdClaude(args: string[]): Promise<number> {
     console.error("Claude inbound is disabled (config.claudeCode.enabled=false — flip the Claude ON toggle in the GUI or edit config).");
     return 1;
   }
-  const port = await ensureProxyForClaude();
-  if (!port) {
-    console.error("❌ Proxy did not become healthy after starting.");
+  const clientState = readClientConnectionState();
+  if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
+    console.error(`Client state is ${clientState.kind}: ${clientState.reason}`);
     return 1;
   }
-  const contextWindows = await fetchClaudeContextWindows(config, port);
+  let route: number | ClaudeRoutingTarget;
+  let contextWindows: Record<string, number>;
+  if (clientState.kind === "connected") {
+    if (!clientState.value.selectedClients.includes("claude")) {
+      console.error("Claude is not selected for this remote hub connection.");
+      return 1;
+    }
+    const token = readServiceApiTokenState();
+    if (token.kind !== "present" || token.fingerprint !== clientState.value.tokenFingerprint) {
+      console.error(token.kind === "absent" ? "Connected service token is missing." : "Connected service token ownership changed.");
+      return 1;
+    }
+    route = { baseUrl: clientState.value.serverUrl, admissionToken: token.token };
+    contextWindows = readConnectedClaudeContextWindows();
+  } else {
+    const port = await ensureProxyForClaude();
+    if (!port) {
+      console.error("❌ Proxy did not become healthy after starting.");
+      return 1;
+    }
+    route = port;
+    contextWindows = await fetchClaudeContextWindows(config, port);
+  }
   const allowRootSkipPermissions = shouldAllowRootSkipPermissions(args);
-  const env = buildClaudeEnv(config, port, process.env, contextWindows, { allowRootSkipPermissions });
+  const env = buildClaudeEnv(config, route, process.env, contextWindows, { allowRootSkipPermissions });
   if (allowRootSkipPermissions) {
     console.error(rootSkipPermissionsNotice(env));
   }
   // Pre-write the CLI's gateway-model cache (devlog 030): without a token the CLI
   // never refreshes it, so the picker would keep showing yesterday's aliases.
   try {
-    const cachePath = await refreshGatewayModelCacheFromProxy(port, { admissionConfig: config });
+    const cachePath = typeof route === "number"
+      ? await refreshGatewayModelCacheFromProxy(route, { admissionConfig: config })
+      : await refreshGatewayModelCacheFromProxy(route, { admissionConfig: config });
     if (cachePath === null) {
       console.error("⚠ Gateway model cache could not be refreshed; the model picker may be stale.");
     }
@@ -363,14 +459,16 @@ export async function cmdClaude(args: string[]): Promise<number> {
     console.error(`⚠ Gateway model cache could not be refreshed: ${message}`);
   }
   // Sync roster agents (devlog 070): subagentModels + self -> ~/.claude/agents/ocx-*.md.
-  try {
-    const written = injectClaudeAgentDefs(config, contextWindows);
-    if (written === null) {
-      console.error("⚠ Claude agent definitions could not be synced; check ~/.claude/agents permissions.");
+  if (typeof route === "number") {
+    try {
+      const written = injectClaudeAgentDefs(config, contextWindows);
+      if (written === null) {
+        console.error("⚠ Claude agent definitions could not be synced; check ~/.claude/agents permissions.");
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`⚠ Claude agent definitions could not be synced: ${message}`);
     }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`⚠ Claude agent definitions could not be synced: ${message}`);
   }
   return await new Promise<number>(resolve => {
     const inv = commandInvocation("claude", args);