@bitkyc08/opencodex 2.50.0 → 2.51.0

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/proxy-liveness.ts

@@ -10,6 +10,7 @@
  * Lives outside cli.ts (which dispatches argv at module top level) so tests can import it.
  */
 import { loadConfig } from "../config";
+import { isWildcardHostname } from "../codex/loopback-target";
 import { readAlivePid, readRuntimePort, verifyPidIdentity } from "../config/process-state";
 import { directLocalHttpFetch } from "./direct-local-http";
 
@@ -82,10 +83,15 @@ export interface LiveProxy {
 /**
  * Host to probe for a given bind hostname: wildcards answer on IPv4 loopback, and raw
  * IPv6 addresses must be bracketed or the composed URL is invalid.
+ *
+ * The wildcard test is `isWildcardHostname`, not a list of spellings. This function used to
+ * know exactly three (`0.0.0.0`, `::`, `[::]`) while the bind-scope predicate knew every
+ * all-zero form, so `ocx` composed `http://0.0.0.0.:10100` or `http://*:10100` — unreachable
+ * URLs — for a config the server itself treated as a wildcard bind. One predicate, both sides.
  */
 export function probeHostname(hostname: string | undefined): string {
   const trimmed = (hostname ?? "").trim();
-  if (!trimmed || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") return "127.0.0.1";
+  if (!trimmed || isWildcardHostname(trimmed)) return "127.0.0.1";
   if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed;
   return trimmed.includes(":") ? `[${trimmed}]` : trimmed;
 }

package/src/server/request-log-conversation.ts

@@ -2,7 +2,7 @@
  * Best-effort chat/session correlation for Logs / usage.jsonl (#330).
  * Opaque ids only — never persist raw emails or Claude Desktop system-hash fallbacks.
  */
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 /** Reject absurdly long client strings before hashing (DoS / JSONL bloat). */
 export const LOG_CONVERSATION_ID_INPUT_MAX = 4096;
@@ -217,3 +217,43 @@ export function summarizeConversationLogs(entries: readonly TotalsSource[]): Con
     unmeteredRequests,
   };
 }
+
+/**
+ * Request-scoped Go affinity for requests that carry no conversation identity.
+ *
+ * A sessionless request must still reach OpenCode Go with `x-opencode-session`, because the upstream
+ * began rejecting requests without it on 2026-09-06. It must not reuse one global value either, which
+ * would smear unrelated probes into a single conversation. So the lane is allocated once per admitted
+ * `Request` object and retained for that object's lifetime.
+ *
+ * The identity has to survive every place the proxy rebuilds a `Request`: translation to the internal
+ * Responses shape, compaction, and — the boundary that matters most — the policy fallback retry, where
+ * a second candidate would otherwise be handed a freshly minted lane after a retryable failure.
+ * `linkRequestSessionLane` carries the allocation across those boundaries.
+ */
+const requestAllocatedSessionLanes = new WeakMap<Request, string>();
+
+/**
+ * Resolve the session lane for a request: real conversation identity when the client supplied it,
+ * otherwise a per-request value allocated once and reused for retries on the same object.
+ */
+export function getOrAllocateRequestSessionLane(req: Request): string {
+  const explicit = sessionLaneIdFromRequest(req.headers)
+    ?? normalizeLogConversationId(req.headers.get("x-opencode-session"));
+  if (explicit) return explicit;
+
+  const existing = requestAllocatedSessionLanes.get(req);
+  if (existing) return existing;
+  const allocated = randomUUID();
+  requestAllocatedSessionLanes.set(req, allocated);
+  return allocated;
+}
+
+/**
+ * Carry a source request's lane onto a request the proxy built from it, so a rebuilt request keeps
+ * the conversation it belongs to instead of looking sessionless again.
+ */
+export function linkRequestSessionLane(sourceReq: Request, targetReq: Request): void {
+  requestAllocatedSessionLanes.set(targetReq, getOrAllocateRequestSessionLane(sourceReq));
+}
+

package/src/server/responses/codex-auth-error.ts

@@ -29,10 +29,27 @@ export function nativeMainRefreshFailureResponse(error: unknown): Response {
   if (error instanceof MainAccountTokenRefreshError
     || error instanceof MainAuthJsonChangedDuringRefreshError
     || (error instanceof NativeProfileError && error.retryable)) {
+    // A bare "retry this request" reads as a transient server fault, which is how #4212's reporter
+    // concluded the proxy had broken while one account was the thing that needed them. The refusal
+    // stays a retryable 503 because the refresh genuinely may succeed, but it now names what is
+    // failing and what to do when retrying stops helping.
+    //
+    // It says "sign in to the main Codex account again" and deliberately does NOT say
+    // "reauthentication", for the same reason the pool counterpart does not — see
+    // `poolCredentialRefreshIncompleteResponse` in ./core.ts. `classifyError` runs
+    // `isAuthenticationMessage` before it reaches the `status === 503` arm, and that check is
+    // status-blind on the bare substring "authentication", which "reauthentication" contains.
+    // A body carrying that word is reclassified to `authentication_error` / `invalid_api_key`
+    // even though the HTTP status stays 503, and Codex keys its retry-after backoff on
+    // `server_is_overloaded` — so the word alone turns a transient refresh into what reads as a
+    // bad API key and the client stops retrying. The pool path documented this trap and this one
+    // walked into it anyway, which is why the test below now asserts the classification and not
+    // just the sentence.
     const response = formatErrorResponse(
       503,
       "server_busy",
-      "Codex main credential refresh did not complete; retry this request",
+      "Codex main credential refresh did not complete; retry this request. "
+        + "If it keeps failing, sign in to the main Codex account again.",
     );
     const headers = new Headers(response.headers);
     headers.set("Retry-After", "1");

package/src/server/responses/codex-ws-exchange.ts

@@ -5,7 +5,8 @@ import { CODEX_RESPONSES_HTTP_URL, type PreparedCodexWsRequest } from "./codex-w
 import { CodexWsCorrelation } from "./codex-ws-correlation";
 import type { CodexWsSession } from "./codex-ws-session";
 import { UPGRADE_DEADLINE_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES,
-  MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage } from "./codex-ws-wire";
+  MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage,
+  codexWsFailureDetail, type CodexWsFailureStage } from "./codex-ws-wire";
 
 interface ExchangeOptions {
   session: CodexWsSession;
@@ -94,6 +95,14 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
     let received = false;
     let responseCommitted = false;
     let terminal = false;
+    // #4191: the counters behind the failure classification. A user whose long
+    // thread died here could not tell an unanswered socket from one that carried
+    // only quota frames, because both arrived as the same one-line message.
+    let upstreamFrames = 0;
+    let controlFrames = 0;
+    let relayedEvents = 0;
+    let sentAt: number | null = null;
+    let firstFrameAt: number | null = null;
     let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
     const encoder = new TextEncoder();
     const metadata = url === CODEX_RESPONSES_HTTP_URL ? new CodexWsMetadata(onQuota) : null;
@@ -123,6 +132,21 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       ws.removeEventListener("error", onError);
     };
 
+    /**
+     * Snapshot the stage for a failure message. Measuring the frame is deferred
+     * to here so the happy path never pays for it: a full-replay thread's frame
+     * runs to megabytes, and this is the only place its size is worth knowing.
+     */
+    const failureStage = (): CodexWsFailureStage => ({
+      requestBytes: Buffer.byteLength(frameText, "utf8"),
+      sent,
+      upstreamFrames,
+      controlFrames,
+      relayedEvents,
+      firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null,
+      elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null,
+    });
+
     const commitResponse = () => {
       if (responseCommitted) return;
       responseCommitted = true;
@@ -192,6 +216,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       sent = true;
       try {
         ws.send(frameText);
+        sentAt = Date.now();
       } catch {
         if (received || responseCommitted) {
           if (terminal) session.dispose();
@@ -211,13 +236,18 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       }
       if (!metadata) commitResponse();
       else if (!responseCommitted && !terminal) {
-        preludeTimer = setTimeout(() => failStream("codex websocket response prelude timed out"), CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS);
+        preludeTimer = setTimeout(
+          () => failStream(`codex websocket response prelude timed out${codexWsFailureDetail(failureStage())}`),
+          CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS,
+        );
       }
     };
 
     const onMessage = (event: MessageEvent) => {
       if (!controller || terminal) return;
       received = true;
+      upstreamFrames += 1;
+      if (firstFrameAt === null) firstFrameAt = Date.now();
       const text = typeof event.data === "string" ? event.data : "";
       if (!text) return;
       // UTF-8 byte length is always at least the JS string length. Reject this
@@ -243,6 +273,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
           if (sanitized !== null) {
             relayText = sanitized;
             controlFrame = true;
+            controlFrames += 1;
           }
         } catch (error) {
           failStream(error);
@@ -296,6 +327,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
         failStream("codex websocket response stream closed while enqueueing");
         return;
       }
+      if (!controlFrame) relayedEvents += 1;
       if (type === "response.completed" || type === "response.failed" || type === "response.incomplete" || type === "error") {
         const completedId = correlation?.completed(normalized.payload) ?? null;
         terminal = true;
@@ -316,7 +348,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
         resolve(sseFallback(url, init));
         return;
       }
-      if (sent && !terminal) failStream(closedBeforeTerminalMessage(event));
+      if (sent && !terminal) failStream(closedBeforeTerminalMessage(event, failureStage()));
     };
 
     const onError = () => {
@@ -327,7 +359,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
         cleanup();
         session.dispose();
         resolve(sseFallback(url, init));
-      } else failStream("codex websocket transport error");
+      } else failStream(`codex websocket transport error${codexWsFailureDetail(failureStage())}`);
     };
     detachOwner = session.bindOwner(reason => cancelExchange(reason));
     ws.addEventListener("open", onOpen);

package/src/server/responses/codex-ws-wire.ts

@@ -50,6 +50,72 @@ export function markCodexWsResponse(response: Response, observed: boolean): void
 
 const CLOSED_BEFORE_TERMINAL = "codex websocket closed before a Responses terminal event";
 
+/**
+ * Content-free stage record for an exchange that ended without a Responses
+ * terminal event (#4191).
+ *
+ * The field report that drove this could not be told apart from a network
+ * outage, because every such failure reached the user as one of two bare
+ * sentences. Both are true of a socket that was never answered, a socket that
+ * carried only quota control frames, and a socket that died mid-response —
+ * three different upstream stories with three different owners. These counters
+ * are the smallest set that separates them, and every one of them is a size, a
+ * count, or a duration: no request body, no header, no account identifier, and
+ * no conversation text can reach a message built from this record.
+ */
+export type CodexWsFailureStage = {
+  /** UTF-8 size of the `response.create` frame this exchange dialled with. */
+  requestBytes: number;
+  /** True once `ws.send()` returned, so the turn may be executing upstream. */
+  sent: boolean;
+  /** Frames the socket delivered, of any kind, including ones that did not parse. */
+  upstreamFrames: number;
+  /** Frames the metadata channel claimed (quota, response metadata). */
+  controlFrames: number;
+  /** Responses events actually written to the downstream SSE body. */
+  relayedEvents: number;
+  /** Milliseconds from send to the first upstream frame; null when none arrived. */
+  firstFrameMs: number | null;
+  /** Milliseconds from send to this failure; null when the failure predates the send. */
+  elapsedMs: number | null;
+};
+
+/**
+ * Which upstream story the counters tell. Ordered by how much the upstream had
+ * committed to, because that is what decides who owns the failure — and, for a
+ * future maintainer reading #4191, it is deliberately NOT a fallback-eligibility
+ * signal. `no-upstream-frame` does not mean the frame was not accepted; the
+ * no-replay-after-send contract in `codex-ws-exchange.ts` stands regardless of
+ * what this classifier says.
+ */
+export type CodexWsFailureCause =
+  | "before-send"
+  | "no-upstream-frame"
+  | "no-response-event"
+  | "after-response-started";
+
+export function classifyCodexWsFailure(stage: CodexWsFailureStage): CodexWsFailureCause {
+  if (!stage.sent) return "before-send";
+  if (stage.relayedEvents > 0) return "after-response-started";
+  if (stage.upstreamFrames === 0) return "no-upstream-frame";
+  return "no-response-event";
+}
+
+/**
+ * Render the stage as a suffix appended to an existing failure message.
+ *
+ * It is a suffix, not an interpolation, on purpose: the close-code tail these
+ * messages already carry is matched as a contiguous substring by the callers
+ * and tests that read it, so nothing may be inserted ahead of it.
+ */
+export function codexWsFailureDetail(stage: CodexWsFailureStage): string {
+  const duration = (value: number | null): string => (value === null ? "n/a" : `${value}ms`);
+  return ` [cause=${classifyCodexWsFailure(stage)} request=${stage.requestBytes}B`
+    + ` sent=${stage.sent ? "yes" : "no"} frames=${stage.upstreamFrames}`
+    + ` control=${stage.controlFrames} relayed=${stage.relayedEvents}`
+    + ` first-frame=${duration(stage.firstFrameMs)} elapsed=${duration(stage.elapsedMs)}]`;
+}
+
 export type ResponsesWsRelayEvent = {
   type: string;
   text: string;
@@ -111,18 +177,23 @@ export function normalizeResponsesWsRelayEvent(text: string): ResponsesWsRelayEv
  * inspector, so `/api/logs` keeps neither this message nor a specific code —
  * only `streamAborted`. Machine-readable typing would mean changing the error
  * taxonomy, which is deliberately out of scope for this transport fix.
+ *
+ * When a stage is supplied its detail is appended last, after the close-code
+ * tail, so the code and reason stay one contiguous substring.
  */
-export function closedBeforeTerminalMessage(event: unknown): string {
+export function closedBeforeTerminalMessage(event: unknown, stage?: CodexWsFailureStage): string {
   const detail = event as { code?: unknown; reason?: unknown } | null | undefined;
   const code = typeof detail?.code === "number" ? detail.code : null;
   const reason = typeof detail?.reason === "string" ? detail.reason.trim() : "";
-  if (code === null) return CLOSED_BEFORE_TERMINAL;
+  const stageDetail = stage ? codexWsFailureDetail(stage) : "";
+  if (code === null) return `${CLOSED_BEFORE_TERMINAL}${stageDetail}`;
   const suffix = reason ? ` ${code} ${reason}` : ` ${code}`;
   if (code === WS_CLOSE_MESSAGE_TOO_BIG) {
     return `codex websocket rejected the request frame as too large (close${suffix});`
-      + ` requests at or above ${MAX_CODEX_WS_CREATE_FRAME_BYTES} bytes must use the HTTP SSE transport`;
+      + ` requests at or above ${MAX_CODEX_WS_CREATE_FRAME_BYTES} bytes must use the HTTP SSE transport`
+      + stageDetail;
   }
-  return `${CLOSED_BEFORE_TERMINAL} (close${suffix})`;
+  return `${CLOSED_BEFORE_TERMINAL} (close${suffix})${stageDetail}`;
 }
 
 /**

package/src/server/responses/compact.ts

@@ -152,12 +152,13 @@ import {
   decodeRequestErrorResponse,
   handleResponses,
   preAuthUpstreamHostCircuitKey,
+  poolCredentialRefreshIncompleteResponse,
   upstreamHostCircuitOpenResponse,
   usesCodexForwardPoolAuth,
 } from "./core";
 import { fetchWithHeaderTimeout, providerFetch, safeHostLabel, safeOriginLabel } from "./fetch-helpers";
 import { mapCodexAuthContextErrorToResponse, nativeMainRefreshFailureResponse } from "./codex-auth-error";
-import { sessionLaneIdFromRequest } from "../request-log-conversation";
+import { linkRequestSessionLane, sessionLaneIdFromRequest } from "../request-log-conversation";
 import { recallComboForLane } from "./combo-session-recall";
 
 export const COMPACT_RESPONSE_MAX_BYTES = 32 * 1024 * 1024;
@@ -317,6 +318,13 @@ async function refreshPoolCompactContext(args: {
   authCtx: CodexAuthContext & { kind: "pool" };
   provider: OcxProviderConfig;
   codexAccountMode?: CodexAccountMode;
+  /**
+   * Public selector for the account this refresh is for, when the request carried one. The
+   * caller has it and this function does not, because compact takes no `RouteResult` — which
+   * is the whole reason the refusal here used to be less specific than the one core returns
+   * for the identical failure.
+   */
+  codexAccountNamespace?: string;
   substituteMainCredential: boolean;
   options: HandleResponsesCompactOptions;
 }): Promise<
@@ -377,14 +385,15 @@ async function refreshPoolCompactContext(args: {
     if (isTerminalCompactPoolRefreshFailure(error)) {
       return { ok: false, quarantine: true, response: reauthResponse() };
     }
-    const response = formatErrorResponse(
-      503,
-      "server_busy",
-      "Codex credential refresh did not complete; retry this request",
-    );
-    const headers = new Headers(response.headers);
-    headers.set("Retry-After", "1");
-    return { ok: false, quarantine: false, response: new Response(response.body, { status: response.status, headers }) };
+    return {
+      ok: false,
+      quarantine: false,
+      response: poolCredentialRefreshIncompleteResponse({
+        authCtx,
+        config,
+        accountSelector: args.codexAccountNamespace,
+      }),
+    };
   }
 }
 
@@ -917,6 +926,7 @@ export async function handleResponsesCompact(
           authCtx: poolAuthCtx,
           provider: compactProvider,
           codexAccountMode: route.codexAccountMode,
+          codexAccountNamespace: route.codexAccountNamespace,
           substituteMainCredential,
           options,
         })
@@ -1149,6 +1159,7 @@ export async function handleResponsesCompact(
     headers: internalHeaders,
     body: JSON.stringify(internalBody),
   });
+  linkRequestSessionLane(req, internalReq);
   const response = await handleResponses(internalReq, config, logCtx, { abortSignal: req.signal, turnAdmissionLease, ...(admission ? { admission } : {}) });
   if (!response.ok) return response;
   let json: { output?: unknown[]; status?: unknown; error?: unknown };

package/src/server/responses/core.ts

@@ -320,6 +320,8 @@ import {
 } from "../request-log";
 import {
   conversationIdFromResponsesRequest,
+  getOrAllocateRequestSessionLane,
+  linkRequestSessionLane,
   normalizeLogConversationId,
   reasoningReplayConversationIdFromResponsesRequest,
   sessionLaneIdFromRequest,
@@ -2260,6 +2262,50 @@ function isTerminalPoolRefreshFailure(error: unknown): boolean {
   return error instanceof TokenRefreshError && (error.reason === "revoked" || error.reason === "expired");
 }
 
+/**
+ * The refusal an operator meets when a stored pool credential's forced refresh does not complete.
+ *
+ * A bare "retry this request" reads as a transient fault in the proxy, which is how #4212's
+ * reporter spent an afternoon concluding OpenCodex had broken while one of their own accounts was
+ * the thing that needed them. It stays a retryable 503 and stays non-quarantining, because the
+ * refresh genuinely may succeed and a token-endpoint 5xx must not retire a healthy account
+ * (#2887). What it adds is the account and the exit: when retrying stops helping, that account
+ * has to be signed in again.
+ *
+ * The label is a public account selector when the request carried one, otherwise the durable
+ * `p`-prefixed log label — never the raw pool id and never the email. Those are the identifiers
+ * `responses-compaction-routing.test.ts` and `codex-auth-context.test.ts` already assert must not
+ * reach an operator-facing surface, and an error body travels further than a log line, not less.
+ * When neither is resolvable the sentence degrades to "the selected Codex pool account" rather
+ * than naming something opaque, because a wrong name is worse than no name.
+ *
+ * The wording says "sign in to that account again" and deliberately does NOT say
+ * "reauthentication". `classifyError` runs `isAuthenticationMessage` before it reaches the
+ * `status === 503` arm, and that check is status-blind on the bare substring "authentication",
+ * which "reauthentication" contains. A body carrying that word is reclassified to
+ * `authentication_error` / `invalid_api_key` even though the HTTP status stays 503 — and Codex
+ * applies retry-after backoff only for `server_is_overloaded`, so the friendlier sentence would
+ * have quietly disabled the retry this refusal exists to ask for. `options.code` cannot buy the
+ * classification back; only the wording can.
+ */
+export function poolCredentialRefreshIncompleteResponse(args: {
+  authCtx: CodexAuthContext;
+  config: Pick<OcxConfig, "codexAccounts">;
+  accountSelector?: string;
+}): Response {
+  const label = args.accountSelector ?? codexAuthContextLogLabel(args.authCtx, args.config);
+  const account = label ? `Codex pool account ${label}` : "the selected Codex pool account";
+  const response = formatErrorResponse(
+    503,
+    "server_busy",
+    `Codex credential refresh did not complete for ${account}; retry this request. `
+      + "If it keeps failing, sign in to that account again.",
+  );
+  const headers = new Headers(response.headers);
+  headers.set("Retry-After", "1");
+  return new Response(response.body, { status: response.status, headers });
+}
+
 /**
  * One forced refresh and one same-account rebuild for a stored pool credential that
  * upstream rejected with a pre-stream 401. `quarantine` distinguishes a dead grant,
@@ -2330,14 +2376,15 @@ async function refreshPoolForwardAuth(args: {
         response: formatErrorResponse(401, "authentication_error", "Selected Codex account needs reauthentication"),
       };
     }
-    const response = formatErrorResponse(
-      503,
-      "server_busy",
-      "Codex credential refresh did not complete; retry this request",
-    );
-    const headers = new Headers(response.headers);
-    headers.set("Retry-After", "1");
-    return { ok: false, quarantine: false, response: new Response(response.body, { status: response.status, headers }) };
+    return {
+      ok: false,
+      quarantine: false,
+      response: poolCredentialRefreshIncompleteResponse({
+        authCtx,
+        config,
+        accountSelector: route.codexAccountNamespace,
+      }),
+    };
   }
 }
 
@@ -2451,8 +2498,7 @@ async function applyFinalRouteRequestNormalization(args: {
 
   // Settle the wire once so logging, fast-mode, auth, and sidecars read the adapter
   // this request will actually use (#404).
-  route.provider = resolveOpenCodeGoTransport(route.provider,
-    sessionLaneIdFromRequest(req.headers) ?? normalizeLogConversationId(req.headers.get("x-opencode-session")));
+  route.provider = resolveOpenCodeGoTransport(route.provider, getOrAllocateRequestSessionLane(req));
   route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire);
   if (preserveAnthropicResponseModel) parsed._responseModelId = responseModelId;
   logCtx.model = route.modelId;
@@ -2816,6 +2862,7 @@ export async function handleComboResponses(
       headers: childHeaders,
       body: JSON.stringify(childBody),
     });
+    linkRequestSessionLane(req, childRequest);
     let resolvedAuth: CodexAuthContext | undefined;
     let terminalRecorder: ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined;
     const started = Date.now();

package/src/server/responses/policy-fallback.ts

@@ -2,6 +2,7 @@ import { comboFailureDecision } from "../../combos/failover";
 import { readBoundedResponseBody } from "../../lib/bounded-body";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "../request-decompress";
 import { finishRequestAttempt, type RequestLogContext } from "../request-log";
+import { linkRequestSessionLane } from "../request-log-conversation";
 import type { OcxConfig } from "../../types";
 import type { RouteCandidateTrace, RouteDecisionTraceV1 } from "../../routing/trace";
 import { handleResponses as handleResponsesCore } from "./core";
@@ -56,12 +57,17 @@ function requestWithCandidate(
   headers.delete("content-encoding");
   headers.delete("content-length");
   headers.set("content-type", "application/json");
-  return new Request(req.url, {
+  const retryRequest = new Request(req.url, {
     method: req.method,
     headers,
     body: JSON.stringify({ ...rawBody, model: `${candidate.provider}/${candidate.model}` }),
     signal: req.signal,
   });
+  // A sessionless request keeps the lane it was already allocated. Without this the second
+  // candidate reaches OpenCode Go under a different x-opencode-session than the first attempt,
+  // which is the same conversation split the header exists to prevent.
+  linkRequestSessionLane(req, retryRequest);
+  return retryRequest;
 }
 
 function errorCodeFromText(text: string): string | undefined {

package/src/server/system-env-shell.ts

@@ -7,6 +7,7 @@ import { resolveClaudeAuthMode } from "../claude/auth-mode";
 import { ANTHROPIC_PARENT_ENV_SLOTS, trustedNodeLauncherContext, type AnthropicParentEnvSlot } from "../cli/launcher-context";
 import type { OcxConfig } from "../types";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
+import { localAdmissionToken, localInferenceDestination } from "../lib/local-destinations";
 
 /**
  * Does the opencodex dummy marker belong in the system environment?
@@ -79,9 +80,14 @@ export function writeShellEnvFile(
   auto?: AutoContextMode,
   deps: SystemEnvDeps = {},
 ): void {
+  // Same local destination the launchd domain gets, resolved through the same resolver rather
+  // than re-derived: the unauthenticated loopback listener when one is enabled, otherwise the
+  // bind address (#4236). The two files must not disagree, or a new shell and a launchd-started
+  // `claude` would dial different sockets.
+  const destination = localInferenceDestination(config, port);
   const lines = [
     `# Generated by opencodex — do not edit manually`,
-    `export ANTHROPIC_BASE_URL=${shellValue(`http://127.0.0.1:${port}`)}`,
+    `export ANTHROPIC_BASE_URL=${shellValue(destination.origin)}`,
     `export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=${shellValue("1")}`,
   ];
   // New lever keys are CONDITIONAL exports (audit 139 R2#1): a value the user already
@@ -89,7 +95,13 @@ export function writeShellEnvFile(
   const conditional = (name: string, value: string) =>
     `[ -z "\${${name}+x}" ] && export ${name}=${shellValue(value)}`;
   if (systemEnvMarkerMode(config, deps) === "proxy") {
-    if (config.apiKeys?.length) {
+    // On a bind that demands data-plane admission the credential may live only in
+    // `OPENCODEX_API_AUTH_TOKEN` or the hardened service token file, so the same ladder the
+    // launchd injection uses applies here. Never the admin token (reviewer constraint on #4236).
+    const hostAdmissionToken = destination.requiresAdmissionToken ? localAdmissionToken(config) : undefined;
+    if (hostAdmissionToken) {
+      lines.push(`export ANTHROPIC_AUTH_TOKEN=${shellValue(hostAdmissionToken)}`);
+    } else if (config.apiKeys?.length) {
       lines.push(`export ANTHROPIC_AUTH_TOKEN=${shellValue(config.apiKeys[0].key)}`);
     } else {
       lines.push(conditional("ANTHROPIC_AUTH_TOKEN", PROXY_MARKER));