@bitkyc08/opencodex 2.50.0 → 2.52.0-preview.20260911

package/src/providers/registry.ts

@@ -2640,6 +2640,23 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
   // Narrowed carry of #3641: the official Codex example declares a local static catalog,
   // not an HTTP /models contract. Keep Responses separate from the Chat endpoint above.
   // Source: https://docs.bigmodel.cn/cn/coding-plan/tool/codex.md (checked 2026-09-07).
+  //
+  // #4201 completes the roster. The `models.json` example on that Codex page is a *starter
+  // catalog*, not the set of models the endpoint serves, and reading it as the latter is what
+  // left Flash off a subscription that sells it. Three upstream pages say so directly, all
+  // checked 2026-09-11:
+  //   - coding-plan/latest-model.md pins Codex to THIS baseUrl
+  //     (`Codex：https://open.bigmodel.cn/api/v1`) and opens with GLM Coding Plan supporting
+  //     GLM-5.3 and GLM-5.3-Flash for every tier (Max & Pro & Lite), then treats
+  //     `glm-5.3-flash` as an already-callable id in that same tool.
+  //   - coding-plan/overview.md: every plan supports GLM-5.3 and GLM-5.3-Flash, and calls to
+  //     GLM-5-Turbo are auto-switched to GLM-5.3-Flash. Turbo below is therefore an alias of
+  //     the very model this row omitted, which is the clearest statement that the endpoint
+  //     serves Flash: it was already serving it under another name.
+  //   - guide/models/vlm/glm-5.3-flash.md: native multimodal input, 1M context, and text
+  //     parameters explicitly "consistent with GLM-5.3".
+  // No authenticated /models probe is implied by any of this, so `liveModels` and
+  // `apiKeyValidation` below are deliberately unchanged.
   {
     id: "zhipu-bigmodel-responses",
     label: "Zhipu AI — BigModel Coding Plan (Responses)",
@@ -2648,22 +2665,34 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     authKind: "key",
     dashboardUrl: "https://bigmodel.cn/console/usercenter/apikeys",
     defaultModel: "glm-5.3",
-    models: ["glm-5.3", "glm-5-turbo"],
+    models: ["glm-5.3", "glm-5.3-flash", "glm-5-turbo"],
     liveModels: false,
     // The local Codex catalog does not establish an authenticated HTTP /models contract.
     apiKeyValidation: "unknown",
     jawcodeBundle: "zai",
     // A pre-existing same-named custom provider must retain its destination and key boundary.
     preserveCustomDestination: true,
-    modelContextWindows: { "glm-5.3": 1_048_576, "glm-5-turbo": 204_800 },
-    modelInputModalities: { "glm-5.3": ["text"], "glm-5-turbo": ["text"] },
+    // Flash tracks its 5.3 sibling on this row rather than the Chat row's 1_000_000. Both
+    // models are documented as "1M", and this preset expresses that family's 1M the way
+    // BigModel's own Codex declaration does. Splitting the two would leave one preset
+    // claiming two different sizes for one documented window.
+    modelContextWindows: { "glm-5.3": 1_048_576, "glm-5.3-flash": 1_048_576, "glm-5-turbo": 204_800 },
+    // Flash is the only row here that can actually see an image. Its siblings are declared
+    // text-only and get `image` back from the vision sidecar at catalog-build time; declaring
+    // Flash text-only would route a native VLM's pictures through a describe-it-first detour
+    // and hand the model prose about an image it could have read (same defect
+    // ZAI_GLM_5X_SIDECAR_VISION_MODELS exists to prevent on the Chat rows).
+    modelInputModalities: { "glm-5.3": ["text"], "glm-5.3-flash": ["text", "image"], "glm-5-turbo": ["text"] },
     modelReasoningEfforts: {
       "glm-5.3": ZAI_GLM_53_REASONING_EFFORTS,
+      // Same three effective tiers: upstream documents Flash's text parameters as identical
+      // to GLM-5.3, and the Codex effort table folds every inbound value into low/high/max.
+      "glm-5.3-flash": ZAI_GLM_53_REASONING_EFFORTS,
       // Explicitly empty: Turbo must not inherit the generic selectable effort ladder.
       "glm-5-turbo": [],
     },
-    modelDefaultReasoningEfforts: { "glm-5.3": "max", "glm-5-turbo": "max" },
-    modelSupportsReasoningSummaries: { "glm-5.3": true, "glm-5-turbo": true },
+    modelDefaultReasoningEfforts: { "glm-5.3": "max", "glm-5.3-flash": "max", "glm-5-turbo": "max" },
+    modelSupportsReasoningSummaries: { "glm-5.3": true, "glm-5.3-flash": true, "glm-5-turbo": true },
     // Responses replay uses this provider-level flag, not the Chat-path model list.
     preserveResponsesReasoningContent: true,
     note: "Domestic BigModel Coding Plan Responses endpoint; static model roster",

package/src/remote/hub-state.ts

@@ -0,0 +1,182 @@
+/**
+ * The hub-state contract shared by `GET|HEAD /v1/hub-state` and every connected client.
+ *
+ * Why it exists (#4236): an agent working on a connected client machine read that machine's
+ * own `~/.opencodex/config.json` and `ocx status`, saw `xai ✗ not logged in`, no grok provider
+ * and five delegable models, and concluded the hub could not serve grok — while the hub had
+ * xAI logged in and was serving grok all along. A client's local credential store is empty BY
+ * DESIGN, so reporting it as the truth is not a cosmetic defect: it makes the client lie about
+ * the only machine that has the facts.
+ *
+ * What may cross this boundary is deliberately narrow. The client holds a per-client DATA key
+ * and no management credential, so this is a least-privilege data-plane read in the `/v1/catalog`
+ * (#809) tradition rather than a widened `/api/*` boundary. The payload is BOOLEANS and model
+ * ids: `hasCredential` is the same `!!p.apiKey` projection `GET /api/providers` already ships,
+ * and `loggedIn` is `oauthLoginSummary`'s boolean with the email and account id dropped
+ * entirely. No keys, no tokens, no quotas, no usage, no account identity — and nothing of that
+ * shape may be added later, because this surface is reachable with a data key.
+ *
+ * The delta over `/v1/catalog`, stated exactly, because "only two booleans" was wrong and a
+ * wrong boundary claim is worse than none. Provider names already leak through `/v1/catalog`
+ * slugs and `/v1/models` ids, but only for providers those routes list. What this route adds is:
+ * `hasCredential`, `loggedIn`, `authMode`, the featured roster — and the NAME and adapter of an
+ * ENABLED provider that the catalog omits for want of a usable credential. That last one is the
+ * point of the route (a client has to be able to say "the hub has xai configured and has no key
+ * for it" rather than "the hub cannot serve grok"), and it is the whole widening.
+ *
+ * A provider the operator marked `disabled` is NOT exported — see `src/server/hub-state.ts`.
+ * Naming it would tell a data-key holder about a provider no other data-plane route mentions,
+ * and a client has no use for it: it is not routable, so "absent" is the truthful report.
+ */
+
+export const HUB_STATE_SCHEMA_VERSION = 1;
+
+/** Hard caps, so the serialized body is bounded by construction rather than by hope. */
+export const MAX_HUB_STATE_PROVIDERS = 200;
+export const MAX_HUB_STATE_SUBAGENT_MODELS = 32;
+export const MAX_HUB_STATE_OAUTH_PROVIDERS = 200;
+export const MAX_HUB_STATE_STRING_CHARS = 200;
+/** Response/transfer ceiling. The caps above keep a realistic body two orders below this. */
+export const MAX_HUB_STATE_BYTES = 64 * 1024;
+
+/**
+ * Mirrors `OcxProviderConfig.authMode` (src/types/provider.ts); default `"key"`.
+ *
+ * It is shape, not secret: it says HOW a provider authenticates, which is what lets a client
+ * explain `hasCredential: false` on an `oauth` provider without claiming nothing is configured.
+ */
+export const HUB_STATE_AUTH_MODES = ["key", "forward", "oauth", "local"] as const;
+export type HubStateAuthMode = (typeof HUB_STATE_AUTH_MODES)[number] | null;
+
+export interface HubStateProvider {
+  name: string;
+  adapter: string;
+  authMode: HubStateAuthMode;
+  /** Presence only — the same `!!p.apiKey` projection `GET /api/providers` ships. */
+  hasCredential: boolean;
+  /**
+   * Always `false` from a hub of this version, which does not export a disabled provider at all.
+   * The field stays in the contract because an OLDER hub does send `true`, and a client reading
+   * one must still be able to label the row rather than present it as routable.
+   */
+  disabled: boolean;
+}
+
+export interface HubStateOAuthEntry {
+  provider: string;
+  /** `oauthLoginSummary().loggedIn`. The email and account id are dropped, not masked. */
+  loggedIn: boolean;
+}
+
+export interface HubStateDTO {
+  schemaVersion: typeof HUB_STATE_SCHEMA_VERSION;
+  /** Always "hub": the route 404s on any other role, so a client can trust what it reads. */
+  runtimeRole: "hub";
+  hubVersion: string;
+  /** `hub.dataPublicOrigin` when the operator set one; null rather than a guess. */
+  origin: string | null;
+  providers: HubStateProvider[];
+  oauth: HubStateOAuthEntry[];
+  /** The hub's effective featured subagent roster — what a client should delegate to. */
+  subagentModels: string[];
+  /**
+   * At least one row was dropped to fit a cap above, so the arrays are a prefix rather than the
+   * whole truth. Silent truncation is what this flag exists to prevent: a client that lists 200
+   * of 240 providers and says nothing has told the reader the other 40 do not exist, which is
+   * the same class of confident-and-wrong report #4236 is about.
+   */
+  truncated: boolean;
+  claudeCode: { enabled: boolean };
+}
+
+function boundedString(value: unknown, max = MAX_HUB_STATE_STRING_CHARS): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.length > max || /[\x00-\x1f\x7f]/.test(trimmed)) return null;
+  return trimmed;
+}
+
+/**
+ * Validate a hub-state body received over the wire.
+ *
+ * Returns null instead of throwing so both the live fetch and the on-disk cache can reject a
+ * malformed document the same way, and so a client NEVER degrades to its own local login state
+ * on a shape it does not recognize — degrading quietly is the defect being fixed.
+ *
+ * Unknown keys are dropped rather than refused: a newer hub must be readable by an older
+ * client, and the fields this projection reads are all required.
+ */
+export function parseHubStateBody(value: unknown): HubStateDTO | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const raw = value as Record<string, unknown>;
+  if (raw.schemaVersion !== HUB_STATE_SCHEMA_VERSION) return null;
+  if (raw.runtimeRole !== "hub") return null;
+  const hubVersion = boundedString(raw.hubVersion, 64);
+  if (!hubVersion) return null;
+  const origin = raw.origin === null || raw.origin === undefined ? null : boundedString(raw.origin, 512);
+  if (raw.origin !== null && raw.origin !== undefined && origin === null) return null;
+  if (!Array.isArray(raw.providers) || raw.providers.length > MAX_HUB_STATE_PROVIDERS) return null;
+  if (!Array.isArray(raw.oauth) || raw.oauth.length > MAX_HUB_STATE_OAUTH_PROVIDERS) return null;
+  if (!Array.isArray(raw.subagentModels) || raw.subagentModels.length > MAX_HUB_STATE_SUBAGENT_MODELS) return null;
+  const claudeCode = raw.claudeCode;
+  if (!claudeCode || typeof claudeCode !== "object" || Array.isArray(claudeCode)) return null;
+  const enabled = (claudeCode as Record<string, unknown>).enabled;
+  if (typeof enabled !== "boolean") return null;
+  // Absent means false: a hub that predates the flag truncated nothing this client can detect,
+  // and refusing its document would turn a new honesty field into a compatibility break. A
+  // present non-boolean is still refused, like every other field here.
+  if (raw.truncated !== undefined && typeof raw.truncated !== "boolean") return null;
+  const truncated = raw.truncated === true;
+
+  const providers: HubStateProvider[] = [];
+  for (const row of raw.providers) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+    const entry = row as Record<string, unknown>;
+    const name = boundedString(entry.name);
+    const adapter = boundedString(entry.adapter);
+    if (!name || !adapter) return null;
+    if (typeof entry.hasCredential !== "boolean" || typeof entry.disabled !== "boolean") return null;
+    const authMode = entry.authMode;
+    const normalizedAuthMode = typeof authMode === "string" && (HUB_STATE_AUTH_MODES as readonly string[]).includes(authMode)
+      ? authMode as NonNullable<HubStateAuthMode>
+      : null;
+    // An unrecognized authMode is refused rather than nulled: nulling it would let a newer hub's
+    // new mode read as "unset", which is a different claim about the provider.
+    if (authMode !== null && authMode !== undefined && normalizedAuthMode === null) return null;
+    providers.push({
+      name,
+      adapter,
+      authMode: normalizedAuthMode,
+      hasCredential: entry.hasCredential,
+      disabled: entry.disabled,
+    });
+  }
+
+  const oauth: HubStateOAuthEntry[] = [];
+  for (const row of raw.oauth) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+    const entry = row as Record<string, unknown>;
+    const provider = boundedString(entry.provider);
+    if (!provider || typeof entry.loggedIn !== "boolean") return null;
+    oauth.push({ provider, loggedIn: entry.loggedIn });
+  }
+
+  const subagentModels: string[] = [];
+  for (const row of raw.subagentModels) {
+    const model = boundedString(row);
+    if (!model) return null;
+    subagentModels.push(model);
+  }
+
+  return {
+    schemaVersion: HUB_STATE_SCHEMA_VERSION,
+    runtimeRole: "hub",
+    hubVersion,
+    origin,
+    providers,
+    oauth,
+    subagentModels,
+    truncated,
+    claudeCode: { enabled },
+  };
+}

package/src/server/auth-cors.ts

@@ -439,6 +439,11 @@ export const AUTH_MATRIX: readonly ApiAuthMatrixRow[] = [
   // /v1/models and for the same reason — it forwards no caller credential upstream — so a
   // remote client no longer needs an admin token just to read the model catalog.
   { endpoint: "/v1/catalog", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
+  // #4236: the hub-state read a connected client uses instead of reporting its own empty
+  // credential store. Same admission set and the same justification as the two rows above —
+  // it forwards no caller credential upstream and its body is booleans plus model ids — and it
+  // 404s on any host whose runtimeRole is not "hub", so no standalone install gains a surface.
+  { endpoint: "/v1/hub-state", bearer: "accepted", dedicated: "accepted", xApiKey: "accepted" },
 ];
 
 /** Whether `token` is the environment-provided management secret. */

package/src/server/chat-completions.ts

@@ -26,7 +26,10 @@ import { NoEligiblePolicyCandidateError, UnknownRoutingPolicyError, routeModel }
 import { evidenceFromBody } from "../routing/request-evidence";
 import { resolveWireProtocolOverride } from "./adapter-resolve";
 import { resolveOpenCodeGoTransport } from "../providers/opencode-go-transport";
-import { normalizeLogConversationId, sessionLaneIdFromRequest } from "./request-log-conversation";
+import {
+  getOrAllocateRequestSessionLane,
+  linkRequestSessionLane,
+} from "./request-log-conversation";
 import type { OcxConfig } from "../types";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import {
@@ -142,8 +145,7 @@ async function handleChatCompletionsWithBudget(
   let chatNativeRoute: ReturnType<typeof routeModel> | null = null;
   try {
     const route = routeModel(config, chatBody.model as string, evidenceFromBody(chatBody));
-    route.provider = resolveOpenCodeGoTransport(route.provider,
-      sessionLaneIdFromRequest(req.headers) ?? normalizeLogConversationId(req.headers.get("x-opencode-session")));
+    route.provider = resolveOpenCodeGoTransport(route.provider, getOrAllocateRequestSessionLane(req));
     // Settle the wire once so every branch below reads the adapter this model will
     // actually use, not the provider-wide default (#404).
     route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, "chat");
@@ -305,6 +307,7 @@ async function handleChatCompletionsWithBudget(
     headers,
     body: internalBodyJson,
   });
+  linkRequestSessionLane(req, internalReq);
 
   let nativeLogged = false;
   const finalizeNativeLog = (status: number, meta: { terminalStatus?: RequestLogEntry["terminalStatus"]; closeReason: "terminal" | "client_cancel" | "non_stream" }) => {

package/src/server/claude-messages.ts

@@ -36,7 +36,12 @@ import { resolveWireProtocolOverride } from "./adapter-resolve";
 import type { OcxConfig } from "../types";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import { addFinalRequestLog, httpStatusForRequestLogTerminal, recordFirstOutput, type RequestLogContext, type RequestLogEntry } from "./request-log";
-import { conversationIdFromClaudeMetadata, normalizeLogConversationId, sessionLaneIdFromRequest } from "./request-log-conversation";
+import {
+  conversationIdFromClaudeMetadata,
+  linkRequestSessionLane,
+  normalizeLogConversationId,
+  sessionLaneIdFromRequest,
+} from "./request-log-conversation";
 import { responseWithDeferredRequestLog } from "./relay";
 import { handleResponses } from "./responses";
 import {
@@ -897,6 +902,7 @@ async function handleClaudeMessagesWithBudget(
         headers,
         body: JSON.stringify(internalBody),
       });
+      linkRequestSessionLane(req, internalReq);
     } finally {
       reservation.release();
     }

package/src/server/hub-state.ts

@@ -0,0 +1,98 @@
+/**
+ * The hub's own projection for `GET|HEAD /v1/hub-state` (#4236).
+ *
+ * Pure: it takes the config and an already-computed login summary and returns the DTO. The
+ * route owns admission, the role gate and the size ceiling; this module owns what a client is
+ * allowed to learn. Keeping the projection here — and building each row field by field rather
+ * than spreading a provider or a login summary — is what makes "no keys, no emails, no account
+ * ids" checkable by reading one function. A spread would silently start exporting whatever the
+ * next field added to those records happens to be.
+ *
+ * Contract and caps live in `src/remote/hub-state.ts` so the client validates the same shape.
+ */
+import {
+  HUB_STATE_SCHEMA_VERSION,
+  MAX_HUB_STATE_OAUTH_PROVIDERS,
+  MAX_HUB_STATE_PROVIDERS,
+  MAX_HUB_STATE_SUBAGENT_MODELS,
+  HUB_STATE_AUTH_MODES,
+  type HubStateDTO,
+  type HubStateOAuthEntry,
+  type HubStateProvider,
+} from "../remote/hub-state";
+import { DEFAULT_SUBAGENT_MODELS } from "../config/subagent-models";
+import type { OcxConfig } from "../types";
+
+export type HubStateConfigView = Pick<OcxConfig, "providers" | "subagentModels" | "claudeCode" | "hub">;
+
+/** A login summary row as `oauthLoginSummary()` returns it; extra fields are never read. */
+export interface HubStateLoginRow {
+  provider: string;
+  loggedIn: boolean;
+}
+
+/**
+ * The hub's effective featured roster: the same "unset means the defaults, an explicit `[]`
+ * means none" rule `buildClaudeAgentDefs` applies, so a client that delegates from this list
+ * sees exactly what the hub itself would offer.
+ */
+export function hubSubagentRoster(config: Pick<OcxConfig, "subagentModels">): string[] {
+  return uncappedSubagentRoster(config).slice(0, MAX_HUB_STATE_SUBAGENT_MODELS);
+}
+
+/** The same roster before the cap, so `truncated` can be computed instead of guessed. */
+function uncappedSubagentRoster(config: Pick<OcxConfig, "subagentModels">): string[] {
+  const roster = config.subagentModels === undefined ? DEFAULT_SUBAGENT_MODELS : config.subagentModels;
+  return roster
+    .filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "")
+    .map(entry => entry.trim());
+}
+
+export function buildHubState(
+  config: HubStateConfigView,
+  logins: readonly HubStateLoginRow[],
+  hubVersion: string,
+): HubStateDTO {
+  // A disabled provider is dropped, not exported with a flag. `/v1/catalog` and `/v1/models`
+  // both filter it out (`src/router.ts`, `src/codex/catalog/*`), so exporting it here was the
+  // one thing this route told a data-key holder that no other data-plane route does — and a
+  // client has no use for it either: it cannot be routed to, so absence IS the truthful report,
+  // and `authMode` already explains a present-but-credential-less row without it.
+  const enabledProviders = Object.entries(config.providers ?? {}).filter(([, provider]) => provider.disabled !== true);
+  const providers: HubStateProvider[] = enabledProviders
+    .slice(0, MAX_HUB_STATE_PROVIDERS)
+    .map(([name, provider]) => ({
+      name,
+      adapter: provider.adapter,
+      authMode: provider.authMode !== undefined && HUB_STATE_AUTH_MODES.includes(provider.authMode)
+        ? provider.authMode
+        : null,
+      // Presence only. Identical to the projection GET /api/providers already ships.
+      hasCredential: Boolean(provider.apiKey),
+      // Always false here. The field stays in the contract for an older hub's documents; see
+      // `HubStateProvider` in src/remote/hub-state.ts.
+      disabled: false,
+    }));
+  // Field-by-field, never a spread: oauthLoginSummary also carries the operator's email.
+  const oauth: HubStateOAuthEntry[] = logins
+    .slice(0, MAX_HUB_STATE_OAUTH_PROVIDERS)
+    .map(entry => ({ provider: entry.provider, loggedIn: entry.loggedIn === true }));
+  const rosterBeforeCap = uncappedSubagentRoster(config).length;
+  // Said out loud rather than silently: the caps are a prefix, and a client presenting a prefix
+  // as the whole list is the same confident-and-wrong report this route exists to prevent.
+  const truncated = enabledProviders.length > MAX_HUB_STATE_PROVIDERS
+    || logins.length > MAX_HUB_STATE_OAUTH_PROVIDERS
+    || rosterBeforeCap > MAX_HUB_STATE_SUBAGENT_MODELS;
+  return {
+    schemaVersion: HUB_STATE_SCHEMA_VERSION,
+    runtimeRole: "hub",
+    hubVersion,
+    origin: config.hub?.dataPublicOrigin ?? null,
+    providers,
+    oauth,
+    subagentModels: hubSubagentRoster(config),
+    truncated,
+    // Same predicate the launch path uses: absence means enabled.
+    claudeCode: { enabled: config.claudeCode?.enabled !== false },
+  };
+}

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,
@@ -773,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;
@@ -812,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
@@ -824,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";
@@ -1370,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
@@ -2004,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,
         ));
       }
 
@@ -2511,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. */