@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/server/index.ts

@@ -17,6 +17,7 @@ import {
   loadConfig,
   saveConfig,
   getConfigDir,
+  loopbackCompanionBindError,
   websocketsEnabled,
 } from "../config";
 import { grokDefaultReasoningEffort } from "../grok/effort";
@@ -28,6 +29,7 @@ import { withCatalogWriteSerialization } from "../codex/catalog-write-serializat
 import { invalidateCodexModelsCacheWithPermit } from "../codex/catalog/sync";
 import { currentServiceHomes, serviceStatePathsForOpenCodexHome } from "../service";
 import { shouldSyncCodexOnStart } from "../codex/desired-state";
+import { effectiveLoopbackListenerPort } from "../codex/loopback-target";
 import {
   createWindowsTaskListingCache,
   inspectNativeCodexOwnership,
@@ -63,7 +65,11 @@ import { runModelRenameStartupMigration } from "../providers/model-rename-startu
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
 import type { StorageCleanupPolicy } from "../types";
-import { MAX_DECOMPRESSED_BODY_BYTES } from "./request-decompress";
+import {
+  MAX_CONFIGURABLE_INBOUND_BODY_BYTES,
+  MIN_CONFIGURABLE_INBOUND_BODY_BYTES,
+  resolveInboundBodyLimitBytes,
+} from "./request-decompress";
 import {
   CodexAccountCooldownError,
   cooldownErrorMessage,
@@ -769,8 +775,16 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   const bindHost = !configuredHost || /^localhost$/i.test(configuredHost) ? "127.0.0.1" : configuredHost;
 
   // Unauthenticated loopback listener (#1102). Off unless explicitly enabled.
+  // A port-less enabled entry is the companion form: same port as the public listener, on
+  // 127.0.0.1 (#4236). Refuse an impossible pair here, before any bind, so a hand edit that
+  // bypassed validateConfigCandidate reports the collision rather than EADDRINUSE from a
+  // rollback that looks like a foreign process holding the port.
   const loopbackListener = config.unauthenticatedLoopbackListener;
-  const loopbackListenerPort = loopbackListener?.enabled ? loopbackListener.port : null;
+  if (loopbackListener?.enabled === true && loopbackListener.port === undefined) {
+    const companionError = loopbackCompanionBindError(config.hostname, listenPort);
+    if (companionError) throw new Error(companionError);
+  }
+  const loopbackListenerPort = effectiveLoopbackListenerPort(config, listenPort);
   // Hub management ingress is a third, management-only listener. Its address is intentionally
   // fixed: the kernel loopback bind is the trust boundary that permits Tailscale identity headers.
   const managementIngress = config.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
@@ -808,6 +822,25 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
    * keeps the paid upstream behind its own admission and forward-credential checks, so admit only
    * the exact methods and paths it serves (#3428).
    *
+   * `POST /v1/messages` (Anthropic wire) and `POST /v1/chat/completions` (OpenAI chat wire)
+   * are the inference endpoints the hub's OWN local clients speak: `ocx claude` and the
+   * `system-env` injection and Claude Desktop 3P dial the first, Cursor Private Inference, the
+   * vision `routed-describe` helper and aside/opencode the second (#4236). On a hub whose
+   * public listener binds a tailnet address there is no other local socket for them, so
+   * leaving them off this list left every non-Codex local client pointed at a closed port.
+   * Both handlers resolve their own admission from the RECEIVING listener's policy view — the
+   * same resolver and the same loopback short-circuit `/v1/responses` already uses — so this
+   * adds a wire, not a trust level. `/api/*` is deliberately still absent: local management
+   * discovery goes to the authenticated management surface, never to this listener.
+   *
+   * `POST /v1/messages/count_tokens` completes that Anthropic wire. It is admitted on a
+   * narrower argument than the other two rather than on symmetry: it spends no provider quota,
+   * reaches no stored credential, and returns a token count computed from the request body the
+   * caller already holds. Withholding it bought no confinement — the same caller may POST the
+   * whole conversation to `/v1/messages` on this socket — and cost Claude Code its server-side
+   * count, which it then silently replaces with a local estimate. `/api/*`, `/healthz`,
+   * `/readyz` and the GUI remain 404 here, which is the boundary that actually matters.
+   *
    * `GET /v1/models` is on the list for a reason that is easy to miss. When catalog
    * materialization fails or finds no source, `syncCodex` warns and injects with
    * `catalogPath: null`; Codex then builds an ONLINE model manager and `model/list` refreshes
@@ -820,6 +853,8 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
       return req.method === "POST" || req.headers.get("upgrade")?.toLowerCase() === "websocket";
     }
     if (path === "/v1/responses/compact") return req.method === "POST";
+    if (path === "/v1/messages" || path === "/v1/chat/completions") return req.method === "POST";
+    if (path === "/v1/messages/count_tokens") return req.method === "POST";
     if (path === "/v1/alpha/search") return req.method === "POST";
     if (path === "/v1/images/generations" || path === "/v1/images/edits") {
       return req.method === "POST";
@@ -1023,6 +1058,22 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
   let loopbackServer: Server<WsData> | null = null;
   let managementIngressServer: Server<WsData> | null = null;
 
+  // Resolved once, before any listener binds. The clamp is silent inside the resolver so it
+  // stays pure and per-request cheap; the operator is told here instead, once, because a
+  // config value that was quietly reduced is exactly the thing they would otherwise debug
+  // against the wrong limit.
+  const inboundBodyLimitBytes = resolveInboundBodyLimitBytes(config.maxInboundBodyBytes);
+  const requestedInboundBodyLimit = config.maxInboundBodyBytes;
+  if (requestedInboundBodyLimit !== undefined
+    && requestedInboundBodyLimit > 0
+    && requestedInboundBodyLimit !== inboundBodyLimitBytes) {
+    console.warn(
+      `[server] maxInboundBodyBytes=${requestedInboundBodyLimit} is outside the supported range `
+      + `[${MIN_CONFIGURABLE_INBOUND_BODY_BYTES}, ${MAX_CONFIGURABLE_INBOUND_BODY_BYTES}]; `
+      + `using ${inboundBodyLimitBytes} bytes.`,
+    );
+  }
+
   type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management";
   function ingressForServer(requestServer: Server<WsData>): ServerIngress {
     if (requestServer === loopbackServer) return "unauthenticated-loopback";
@@ -1042,7 +1093,10 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     userCostOverlayReconciler = startUserCostOverlayReconciler({ liveConfig: config });
     const serveOptions = {
       idleTimeout: 255,
-      maxRequestBodySize: MAX_DECOMPRESSED_BODY_BYTES,
+      // Bun rejects an oversized body before `fetch` runs, so the listener has to be raised
+      // with the admission limit or the opt-in would do nothing. Fixed at bind time: a live
+      // `maxInboundBodyBytes` edit needs a restart, which the config doc states.
+      maxRequestBodySize: inboundBodyLimitBytes,
       async fetch(req: Request, requestServer: Server<WsData>): Promise<Response> {
       const ingress = ingressForServer(requestServer);
       // The unauthenticated loopback listener (#1102) serves a fixed allowlist and nothing
@@ -1347,6 +1401,83 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
         );
       }
 
+      if (url.pathname === "/v1/hub-state" && (req.method === "GET" || req.method === "HEAD")) {
+        // #4236: a connected client had no way to learn which providers this hub can actually
+        // serve, so `ocx status` on the client reported the CLIENT's empty credential store as
+        // if it were the truth — "xai ✗ not logged in" on a machine whose hub has xAI logged
+        // in. The fix is one least-privilege data-plane read, in the /v1/catalog (#809)
+        // tradition: same admission resolver, same origin check, no parameters, no caller
+        // credential forwarded upstream, and a body of booleans plus model ids. Widening
+        // `/api/*` or handing the client an admin token to read `GET /api/providers` would
+        // have traded a reporting defect for a credential one.
+        //
+        // What it discloses beyond /v1/catalog and /v1/models, exactly: `hasCredential`,
+        // `loggedIn`, `authMode`, the featured roster, and the NAME and adapter of an ENABLED
+        // provider those routes omit for want of a usable credential — which is the point of
+        // the route. A `disabled` provider is NOT exported (`buildHubState` drops it), because
+        // the catalog filters it out too and naming it here would be the only place a data key
+        // learns of it.
+        //
+        // Placed between /v1/catalog and /v1/models so all three least-privilege client reads
+        // stay in sight of each other.
+        const admission = resolveApiAuth(req, policy);
+        if (!admission) return withCors(formatErrorResponse(401, "authentication_error", "opencodex API key required"), req, policy);
+        if (!isAllowedRequestOrigin(req, policy)) {
+          return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, policy);
+        }
+        // Role gate AFTER admission, deliberately: answering an unauthenticated caller would
+        // turn this into a free "is that machine a hub?" probe. A standalone or client install
+        // gains no surface at all — the route simply does not exist there.
+        //
+        // Built, not formatErrorResponse'd, for the same reason /v1/catalog builds its 404: the
+        // code has to distinguish "this route exists and this host is not a hub" from "this
+        // build has no such route", which is the difference between admission proof and a
+        // vacuous pass in tests/server/api-key-attribution.test.ts.
+        if (config.runtimeRole !== "hub") {
+          return withCors(
+            new Response(JSON.stringify({
+              error: {
+                type: "invalid_request_error",
+                code: "hub_state_not_a_hub",
+                message: "hub state is served only by a host whose runtimeRole is hub",
+              },
+            }), { status: 404, headers: { "content-type": "application/json" } }),
+            req,
+            policy,
+          );
+        }
+        const { buildHubState } = await import("./hub-state");
+        const { MAX_HUB_STATE_BYTES } = await import("../remote/hub-state");
+        const { oauthLoginSummary } = await import("../oauth");
+        // `true` masks emails, but the projection drops the field entirely; passing the mask
+        // anyway means a future refactor that starts copying fields cannot leak a raw address.
+        const body = JSON.stringify(buildHubState(config, oauthLoginSummary(true), VERSION));
+        const bytes = Buffer.byteLength(body);
+        if (bytes > MAX_HUB_STATE_BYTES) {
+          return withCors(
+            new Response(JSON.stringify({
+              error: { type: "server_error", code: "hub_state_too_large", message: "hub state exceeds the maximum served size" },
+            }), { status: 507, headers: { "content-type": "application/json" } }),
+            req,
+            policy,
+          );
+        }
+        return withCors(
+          new Response(req.method === "HEAD" ? null : body, {
+            status: 200,
+            headers: {
+              "content-type": "application/json",
+              // Varies by credential-bearing identity and by live login state: never cached,
+              // and no validator to revalidate with (same rule as /v1/catalog).
+              "cache-control": "no-store",
+              "content-length": String(bytes),
+            },
+          }),
+          req,
+          policy,
+        );
+      }
+
       if (url.pathname === "/v1/models" && req.method === "GET") {
         // #809: the catalog read sits immediately before model discovery because it shares
         // that route's admission rationale exactly. Keep them adjacent so a future change to
@@ -1981,10 +2112,13 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
           ...admissionFields(admission),
           inboundProtocol: "chat",
         };
+        // `policy`, not `config`: this route is now served on the unauthenticated loopback
+        // listener too (#4236), and only the receiving listener's view produces CORS headers
+        // that match the admission decision made above.
         return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => withCors(
           await handleChatCompletions(req, config, logCtx, { requestId, start, turnAdmissionLease, admission }),
           req,
-          config,
+          policy,
         ));
       }
 
@@ -2488,10 +2622,17 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     // who forgot, has to be able to see that an unauthenticated surface is live without
     // reading the file.
     const loopbackPort = loopbackServer.port ?? loopbackListenerPort;
-    console.warn(`⚠️  Unauthenticated loopback listener active on http://127.0.0.1:${loopbackPort}`);
-    console.warn(`   Any local process can use it without a credential — it spends account`);
-    console.warn(`   quota and paid provider credentials, and can starve authenticated`);
-    console.warn(`   remote clients. Not for shared or multi-tenant hosts.`);
+    if (loopbackListener?.enabled === true && loopbackListener.port === undefined) {
+      // The companion form is the intended one-port hub topology, not a surprise surface: the
+      // public listener is already on a non-loopback address, so this line states where local
+      // processes go rather than warning about a second port nobody asked for.
+      console.log(`🔁 Loopback companion active on http://127.0.0.1:${loopbackPort} — same port as the public listener; local processes need no credential`);
+    } else {
+      console.warn(`⚠️  Unauthenticated loopback listener active on http://127.0.0.1:${loopbackPort}`);
+      console.warn(`   Any local process can use it without a credential — it spends account`);
+      console.warn(`   quota and paid provider credentials, and can starve authenticated`);
+      console.warn(`   remote clients. Not for shared or multi-tenant hosts.`);
+    }
   }
 
   if (managementIngressServer) {

package/src/server/management/api-access.ts

@@ -1,4 +1,6 @@
 import type { OcxConfig } from "../../types";
+import { isWildcardHostname } from "../../codex/loopback-target";
+import { localInferenceDestination } from "../../lib/local-destinations";
 import { probeHostname } from "../proxy-liveness";
 
 export interface ApiAccessEndpoints {
@@ -21,9 +23,14 @@ export type BuildApiAccessEndpointsOptions = {
   requestOrigin?: string | null;
 };
 
+/**
+ * Wildcard bind scope, shared with `probeHostname` and the loopback-companion gate rather than
+ * re-spelled here: a third list of three spellings is how `0.0.0.0.` and `::0` ended up treated
+ * as specific bind addresses on one side and wildcards on the other.
+ */
 function isWildcardBindHost(hostname: string | undefined): boolean {
   const trimmed = (hostname ?? "").trim();
-  return !trimmed || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]";
+  return !trimmed || isWildcardHostname(trimmed);
 }
 
 /** Bracket bare IPv6 literals for URL authority composition. */
@@ -66,7 +73,7 @@ function originBaseUrl(raw: string): string | null {
  * Falls back to loopback only when no usable request context is available.
  */
 export function resolveApiAccessBaseUrl(
-  config: Pick<OcxConfig, "hostname" | "port">,
+  config: Pick<OcxConfig, "hostname" | "port" | "unauthenticatedLoopbackListener">,
   opts: BuildApiAccessEndpointsOptions = {},
 ): string {
   const port = config.port ?? 10100;
@@ -104,7 +111,11 @@ export function resolveApiAccessBaseUrl(
     }
   }
 
-  return `http://127.0.0.1:${port}/v1`;
+  // Last resort: a wildcard bind with no usable request context, so the only address we can
+  // name is loopback — and on that address the unauthenticated loopback listener, when one is
+  // enabled, is the port a local caller should use (#4236). The branches above are unchanged:
+  // a specific bind or a real request host still describes the address the CLIENT reached.
+  return `${localInferenceDestination(config, port).origin}/v1`;
 }
 
 /** @deprecated Prefer resolveApiAccessBaseUrl; retained for focused host-format tests. */

package/src/server/management/config-routes.ts

@@ -110,7 +110,7 @@ import { applySystemEnvToggle } from "../system-env";
 import { getCachedStartupHealth, invalidateStartupHealthCache } from "../startup-health-cache";
 import { runWindowsTrayAction } from "../windows-tray-control";
 import { runStartupInstallAction, type StartupInstallAction } from "../startup-action-control";
-import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../../codex/runtime";
+import { displayCodexRuntimePath, effortClampAppliesToRuntime, liveRemovedEfforts, loadLastEffortClamp, resolveCodexRuntime } from "../../codex/runtime";
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
@@ -344,7 +344,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
           : null,
         catalogClamp: {
           active: clampActive,
-          removedEfforts: clampActive ? (lastClamp?.removedEfforts ?? []) : [],
+          removedEfforts: clampActive ? [...liveRemovedEfforts(lastClamp)] : [],
           runtimeVersion: clampActive ? (lastClamp?.runtimeVersion ?? null) : null,
         },
         warning: warningParts.length > 0 ? warningParts.join(" ") : null,

package/src/server/management/cursor-integration-routes.ts

@@ -14,6 +14,7 @@ import { cursorLastSeen, type CursorSeen } from "../../integrations/cursor-seen"
 import { detectCursorInstalls, type CursorInstall } from "../../integrations/cursor-detect";
 import { loadCursorEffortTable } from "../../integrations/cursor-effort-table";
 import { configuredApiAuthToken, isApiAuthRequired, jsonResponse } from "../auth-cors";
+import { localInferenceDestination } from "../../lib/local-destinations";
 import { fetchAllModels } from "../management-api";
 import { predictCursorEffort } from "../models-capabilities";
 import { expandCursorEffortRow, knownEffortRowIds } from "../effort-row";
@@ -54,11 +55,19 @@ export async function buildCursorIntegrationStatus(
   // The port the browser reached is the one Cursor on the same machine will reach too; the
   // runtime record and config.port are fallbacks for a request that carries no port.
   const port = runtime?.port ?? (Number(ctx.url?.port) || config.port);
-  // Describes the public bind. A second unauthenticated loopback listener may exist, but the
-  // value a user pastes into Cursor must work against the bind they will actually reach.
+  // Cursor runs on this machine, so the gateway URL it is told to paste is the LOCAL one: the
+  // unauthenticated loopback listener when one is enabled, and otherwise the bind address on the
+  // public port — 127.0.0.1 for a loopback or wildcard bind exactly as before, and the tailnet
+  // or LAN address on a hub, where no loopback socket exists to paste (#4236).
+  const gateway = localInferenceDestination(config, port ?? 10100);
+  // apiKeyMode describes the admission rule of the destination just resolved, which on the
+  // loopback listener is "no key needed" and on every other form is "a key is required".
+  // Pasting one into the listener is harmless; omitting one on a bind that demands it is not.
   const credentialConfigured = !!configuredApiAuthToken(config)
     || (config.apiKeys ?? []).some(entry => !!entry.key.trim());
-  const apiKeyMode = isApiAuthRequired(config) || credentialConfigured ? "credential" : "placeholder";
+  const apiKeyMode = gateway.requiresAdmissionToken || isApiAuthRequired(config) || credentialConfigured
+    ? "credential"
+    : "placeholder";
 
   const limits = nativeContextLimits(config);
   // Same visibility rules as the raw /v1/models list Cursor will read: disabled models and
@@ -107,7 +116,7 @@ export async function buildCursorIntegrationStatus(
     },
     regularCursor: { installed: regular !== undefined, path: regular?.path ?? null },
     gateway: {
-      baseUrl: `http://127.0.0.1:${port}/v1`,
+      baseUrl: `${gateway.origin}/v1`,
       apiKeyMode,
       placeholder: CURSOR_GATEWAY_PLACEHOLDER_KEY,
     },

package/src/server/management/logs-usage-routes.ts

@@ -115,7 +115,10 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
     }
     const all = getRequestLogEntries();
     const total = filteredRequestLogCount(all, url.searchParams);
-    const logs = filterRequestLogs(all, url.searchParams).map(requestLogDto);
+    // Not point-free: requestLogDto takes an options object second, and Array.map would pass the
+    // element INDEX into it. An explicit arrow keeps the default (decode rate included) and is
+    // what /api/logs wants; /api/request-history opts out at its own call sites.
+    const logs = filterRequestLogs(all, url.searchParams).map(entry => requestLogDto(entry));
     const poll = selectRequestLogPoll(logs, url.searchParams, cursor);
     return jsonResponse({
       timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,

package/src/server/management/model-rows.ts

@@ -147,10 +147,25 @@ export async function listManagementModelRows(
     };
   });
   const publicModels = uniqueCatalogModelsForPublicList(models);
+  // Custom rows below are REBUILT from config.customModels rather than spread from a
+  // CatalogModel, so every field gather computed for the same slug has to be carried across by
+  // hand. Without this a custom model whose provider is out of credit would be the one row on
+  // the page that never shows as inactive (#1711), because the gather-derived row it replaces
+  // is dropped by the slug dedup below.
+  const quotaInactiveByNamespaced = new Map(
+    publicModels
+      .filter(model => model.quotaInactiveReason !== undefined)
+      .map(model => [catalogModelSlug(model), model.quotaInactiveReason!] as const),
+  );
   const comboNamespaced = new Set(
     publicModels.filter(model => model.provider === "combo").map(catalogModelSlug),
   );
-  const visibleCustomModels = customModels.filter(model => !comboNamespaced.has(model.namespaced));
+  const visibleCustomModels = customModels
+    .filter(model => !comboNamespaced.has(model.namespaced))
+    .map(model => {
+      const quotaInactiveReason = quotaInactiveByNamespaced.get(model.namespaced);
+      return quotaInactiveReason ? { ...model, quotaInactiveReason } : model;
+    });
   // Custom metadata wins when a physical live/static row resolves to the same Codex-facing
   // slug, while a combo keeps the same precedence it has in routing and /v1/models.
   const customNamespaced = new Set(visibleCustomModels.map(c => c.namespaced));

package/src/server/management/oauth-account-routes.ts

@@ -25,6 +25,7 @@ import {
 } from "../../oauth";
 import { OAuthMutationBusyError, removeCredential } from "../../oauth/store";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
+import { emailMaskingEnabled } from "../../lib/privacy";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
 import { deriveProviderPresets } from "../../providers/derive";
@@ -233,7 +234,10 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
   if (url.pathname === "/api/oauth/status" && req.method === "GET") {
     const provider = (url.searchParams.get("provider") ?? "").trim().toLowerCase();
     if (!isPublicOAuthProvider(provider)) return jsonResponse({ error: "unknown oauth provider" }, 400);
-    const status = getLoginStatus(provider);
+    // Resolved here, at the request boundary that already holds the config, and passed down.
+    // getLoginStatus stays free of config I/O. This route does not re-mask afterwards: it
+    // consumes the already-projected status rather than redacting a second time.
+    const status = getLoginStatus(provider, emailMaskingEnabled(config));
     return jsonResponse(status);
   }
 
@@ -269,7 +273,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     } = await import("../../oauth/health");
     const projectAccounts = () => {
       const set = getAccountSet(provider);
-      const current = getLoginStatus(provider);
+      const current = getLoginStatus(provider, emailMaskingEnabled(config));
       return {
         activeAccountId: current.activeAccountId ?? null,
         accounts: (current.accounts ?? []).map(summary => {

package/src/server/management/provider-routes.ts

@@ -54,6 +54,7 @@ import {
   readBoundedDiscoveryJson,
   resolveProviderModelDiscovery,
 } from "../../providers/model-discovery";
+import { extractGoogleAiStudioModelItems } from "../../providers/google-ai-studio-model-discovery";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import { clearAccountQuotaCache, clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
 import { clearKeyCooldowns } from "../../providers/key-failover";
@@ -1428,13 +1429,19 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
         return jsonResponse({ ok: false, latencyMs, error: "upstream CCA model discovery returned an unexpected shape" });
       }
       // OpenAI-style lists (and Together top-level arrays) use the same validation/dedupe/filter
-      // as catalog discovery. Google's /v1beta/models uses `models[].name` and remains a
-      // connectivity-only count because it is not an authoritative catalog source.
+      // as catalog discovery. Google AI Studio parses the native `models[]` envelope and filters to
+      // `generateContent`, while other providers fall back to generic envelope rows if they return `models[]`.
       const record = bounded.value !== null && typeof bounded.value === "object" && !Array.isArray(bounded.value)
         ? bounded.value as Record<string, unknown>
         : undefined;
+      const isAiStudio = effectiveGoogleMode(name, prov) === "ai-studio";
+      const googleAiStudio = !ccaModels && isAiStudio
+        ? extractGoogleAiStudioModelItems(bounded.value, discovery.maxModels)
+        : undefined;
       const extracted = ccaModels
         ? undefined
+        : googleAiStudio?.ok
+        ? googleAiStudio
         : Array.isArray(bounded.value) || Array.isArray(record?.data)
         ? extractProviderModelItems(bounded.value, discovery)
         : extractModelEnvelopeRows(bounded.value, discovery.maxModels, ["models"]);

package/src/server/management/request-history-routes.ts

@@ -106,7 +106,9 @@ export async function handleRequestHistoryRoutes(ctx: ManagementContext): Promis
         to,
       }, cursor, limit);
       return jsonResponse({
-        entries: page.rows.map(row => requestLogDto(requestLogEntryFromPersistedUsage(row))),
+        // The decode rate is a Logs-page metric; this endpoint shares the DTO but not its
+        // contract, so it opts out rather than silently widening its own response shape (#4038).
+        entries: page.rows.map(row => requestLogDto(requestLogEntryFromPersistedUsage(row), { includeDecodeRate: false })),
         ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
         hasMore: page.hasMore,
         index: {
@@ -184,7 +186,7 @@ export async function handleRequestHistoryRoutes(ctx: ManagementContext): Promis
     if (!entry) {
       return jsonResponse({ error: { code: "not_found", message: "unknown request" } }, 404, req, config);
     }
-    return jsonResponse(requestLogDto(requestLogEntryFromPersistedUsage(entry)), 200, req, config);
+    return jsonResponse(requestLogDto(requestLogEntryFromPersistedUsage(entry), { includeDecodeRate: false }), 200, req, config);
   }
 
   return null;

package/src/server/management/route-registry.ts

@@ -95,6 +95,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "PATCH", path: "/api/codex-auth/pool-strategy", module: "codex/auth-api", mutates: true },
   { method: "POST", path: "/api/codex-auth/accounts", module: "codex/auth-api", mutates: true },
   { method: "POST", path: "/api/codex-auth/accounts/clear-cooldown", module: "codex/auth-api", mutates: true },
+  { method: "POST", path: "/api/codex-auth/accounts/refresh", module: "codex/auth-api", mutates: true },
   { method: "POST", path: "/api/codex-auth/login", module: "codex/auth-api", mutates: true },
   { method: "POST", path: "/api/codex-auth/login/cancel", module: "codex/auth-api", mutates: true },
   { method: "POST", path: "/api/codex-auth/login/code", module: "codex/auth-api", mutates: true },
@@ -148,9 +149,9 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
   { method: "PUT", path: "/api/client-integrations/aside/profiles/{profileId}", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode" },
   { method: "GET", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
-  { method: "DELETE", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside history deletion uses the dashboard journal cleanup; the CLI has history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_plan/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
+  { method: "DELETE", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside history deletion uses the dashboard journal cleanup; the CLI has history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
-  { method: "DELETE", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside profile history deletion uses the dashboard journal cleanup; the CLI has scoped history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_plan/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
+  { method: "DELETE", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside profile history deletion uses the dashboard journal cleanup; the CLI has scoped history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/restore", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode" },
   // server/management/codex-prompt-routes
   { method: "GET", path: "/api/codex-prompt", module: "server/management/codex-prompt-routes", mutates: false },
@@ -186,7 +187,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   // server/management/integration-routes
   { method: "GET", path: "/api/client-integrations", module: "server/management/integration-routes", mutates: false },
   { method: "GET", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: false },
-  { method: "DELETE", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Retiring one rollback row is a dashboard-local cleanup; the CLI verb that would drive it is owed by a later work-phase and is not implemented here.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_plan/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
+  { method: "DELETE", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Retiring one rollback row is a dashboard-local cleanup; the CLI verb that would drive it is owed by a later work-phase and is not implemented here.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/restore", module: "server/management/integration-routes", mutates: true },
   // server/management/lab-automation-routes
   { method: "GET", path: "/api/lab/automation", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
@@ -292,7 +293,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "PATCH", path: "/api/providers", module: "server/management/provider-routes", mutates: true },
   { method: "POST", path: "/api/providers", module: "server/management/provider-routes", mutates: true },
   { method: "POST", path: "/api/providers/test", module: "server/management/provider-routes", mutates: true },
-  { method: "PUT", path: "/api/providers", module: "server/management/provider-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Issue #3280 scopes this atomic batch endpoint to the GUI JSON editor; a matching CLI verb is outside wp5 and remains owed.", owner: "wp5-followup", ownerDoc: "devlog/_plan/260903_bug_drawdown_bcda/050_phase5.md" } },
+  { method: "PUT", path: "/api/providers", module: "server/management/provider-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Issue #3280 scopes this atomic batch endpoint to the GUI JSON editor; a matching CLI verb is outside wp5 and remains owed.", owner: "wp5-followup", ownerDoc: "devlog/_fin/260903_bug_drawdown_bcda/050_phase5.md" } },
   { method: "PUT", path: "/api/provider-context-caps", module: "server/management/provider-routes", mutates: true },
   // server/management/quota-reset-routes
   { method: "GET", path: "/api/quota-resets", module: "server/management/quota-reset-routes", mutates: false, mechanism: "negated-guard" },

package/src/server/management/shared.ts

@@ -79,7 +79,8 @@ export function parseDebugLogQuery(url: URL): { after: number; limit: number } {
 export type MetricUnavailableReason =
   | "usage_missing" | "usage_unsupported" | "output_missing" | "invalid_duration"
   | "price_unmatched" | "invalid_cache_breakdown"
-  | "invalid_usage" | "combo_attempt_unavailable";
+  | "invalid_usage" | "combo_attempt_unavailable"
+  | "ttft_missing" | "decode_window_too_short";
 
 export type TokPerSecondResult =
   | { kind: "value"; value: number; estimated: boolean }
@@ -96,7 +97,7 @@ export type CostResult =
   | { kind: "value"; estimate: NonNullable<ReturnType<typeof estimateRequestCost>>; estimateReasons: CostEstimateReason[] }
   | { kind: "unavailable"; reason: MetricUnavailableReason };
 
-export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "usageStatus" | "usage" | "requestedServiceTier" | "configuredServiceTier" | "responseServiceTier" | "tierOutcome" | "routeDecision"> & {
+export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "firstOutputMs" | "usageStatus" | "usage" | "requestedServiceTier" | "configuredServiceTier" | "responseServiceTier" | "tierOutcome" | "routeDecision"> & {
   attempts?: readonly PersistedUsageAttempt[];
 };
 
@@ -113,6 +114,51 @@ export function tokPerSecondResult(entry: Pick<MetricSource, "durationMs" | "usa
   return { kind: "value", value, estimated: entry.usageStatus === "estimated" || entry.usage.estimated === true };
 }
 
+/**
+ * Shortest post-TTFT window that can carry a decode-rate estimate (#4038).
+ *
+ * Below one second the window is dominated by things that are not decoding: TTFT jitter, the
+ * proxy's own buffering, and the granularity of the timestamps themselves. A 240-token response
+ * whose first token arrived 50 ms before the last one is not a 4800 tok/s model, and printing
+ * that number is worse than printing nothing — which is precisely why the earlier attempt at
+ * this metric (#4040) was closed as an unreliable estimate.
+ */
+export const MIN_DECODE_WINDOW_MS = 1_000;
+
+/**
+ * Estimated DECODE throughput: output tokens over the window after the first token (#4038).
+ *
+ * Strictly additive. `tokensPerSecond`, `tokPerSecondResult`, `RequestLogEntry` and
+ * `usage.jsonl` are untouched, and the end-to-end rate beside it keeps meaning exactly what it
+ * has always meant — it is documented as end-to-end, so this is a missing metric rather than a
+ * miscalculated one.
+ *
+ * Always `estimated: true`. The proxy's TTFT is when the FIRST BYTE reached the proxy, which is
+ * not the provider's own generation start, so this can never be more than an estimate no matter
+ * how long the window is. Saying so in the payload is the honest half of the answer to #4040;
+ * MIN_DECODE_WINDOW_MS is the other half.
+ */
+export function decodeTokPerSecondResult(
+  entry: Pick<MetricSource, "durationMs" | "firstOutputMs" | "usageStatus" | "usage">,
+): TokPerSecondResult {
+  if (!entry.usage) return { kind: "unavailable", reason: "usage_missing" };
+  if (entry.usageStatus === "unsupported") return { kind: "unavailable", reason: "usage_unsupported" };
+  if (entry.usage.outputTokens <= 0) return { kind: "unavailable", reason: "output_missing" };
+  // A row that predates TTFT capture, or a non-streaming turn that never recorded one, has no
+  // window to measure. That is a different fact from a bad duration, so it gets its own reason.
+  if (entry.firstOutputMs === undefined) return { kind: "unavailable", reason: "ttft_missing" };
+  if (!Number.isFinite(entry.firstOutputMs) || entry.firstOutputMs < 0 || !Number.isFinite(entry.durationMs)) {
+    return { kind: "unavailable", reason: "invalid_duration" };
+  }
+  const windowMs = entry.durationMs - entry.firstOutputMs;
+  // TTFT at or past the total duration means the two clocks disagree; there is no window.
+  if (windowMs <= 0) return { kind: "unavailable", reason: "invalid_duration" };
+  if (windowMs < MIN_DECODE_WINDOW_MS) return { kind: "unavailable", reason: "decode_window_too_short" };
+  const value = tokensPerSecond(entry.usage.outputTokens, windowMs);
+  if (value === null) return { kind: "unavailable", reason: "invalid_duration" };
+  return { kind: "value", value, estimated: true };
+}
+
 export function unavailableCostReason(entry: MetricSource): MetricUnavailableReason {
   // Normalizer-first classification: the landed normalizer recovers legacy
   // cachedInputTokens=read+write rows via retry, so a raw read+write>input
@@ -152,11 +198,26 @@ export function costResult(entry: MetricSource): CostResult {
   return { kind: "value", estimate, estimateReasons };
 }
 
-export function requestLogDto(entry: RequestLogEntry): Record<string, unknown> {
+/**
+ * `/api/logs` row projection.
+ *
+ * `includeDecodeRate` exists because `/api/request-history` shares this DTO but not its
+ * contract (#4038). The value would be meaningful there — `firstOutputMs` does survive into a
+ * persisted-usage row — so this is a scope decision, not a correctness one: the decode rate is
+ * a Logs-page metric, and widening a separate endpoint's response shape is not this change's
+ * business. Flipping it on later is one argument.
+ */
+export function requestLogDto(
+  entry: RequestLogEntry,
+  { includeDecodeRate = true }: { includeDecodeRate?: boolean } = {},
+): Record<string, unknown> {
   return {
     ...entry,
     displayMetrics: {
       tokPerSecond: tokPerSecondResult(entry),
+      // The parent uses the REQUEST's own TTFT. A combo parent must not borrow an attempt's,
+      // which would measure a window the parent never had.
+      ...(includeDecodeRate ? { decodeTokPerSecond: decodeTokPerSecondResult(entry) } : {}),
       cost: costResult(entry),
     },
     ...(entry.attempts?.length
@@ -165,6 +226,8 @@ export function requestLogDto(entry: RequestLogEntry): Record<string, unknown> {
           ...attempt,
           displayMetrics: {
             tokPerSecond: tokPerSecondResult(attempt),
+            // Each attempt measures its own attempt-relative TTFT.
+            ...(includeDecodeRate ? { decodeTokPerSecond: decodeTokPerSecondResult(attempt) } : {}),
             cost: costResult({ ...attempt, attempts: undefined, routeDecision: entry.routeDecision, requestedServiceTier: entry.requestedServiceTier, configuredServiceTier: entry.configuredServiceTier, responseServiceTier: entry.responseServiceTier }),
           },
         })),

package/src/server/management-api.ts

@@ -385,7 +385,7 @@ export async function handleManagementAPI(
     const { ConfigMutationLockError } = await import("../config");
     const { CodexCredentialRefreshLockTimeoutError } = await import("../codex/account-store");
     try {
-      return await handleCodexAuthAPI(req, url, config, convergeCodexCatalog);
+      return await handleCodexAuthAPI(req, url, config, convergeCodexCatalog, principal);
     } catch (error) {
       // Credential writers remap ConfigMutationLockError to CodexCredentialRefreshLockTimeoutError;
       // treat both as the same retryable busy response.