@bitkyc08/opencodex 2.82.0 → 2.84.0

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

@@ -197,6 +197,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/codex-prompt/repair", module: "server/management/codex-prompt-routes", mutates: true, exempt: { reason: "session-only", why: "Prompt repair requires the gui-session principal (codex-prompt-routes.ts:298)." } },
   { method: "PUT", path: "/api/codex-prompt/base", module: "server/management/codex-prompt-routes", mutates: true, exempt: { reason: "session-only", why: "Base prompt write requires the gui-session principal (codex-prompt-routes.ts:298)." } },
   { method: "PUT", path: "/api/codex-prompt/base/select", module: "server/management/codex-prompt-routes", mutates: true, exempt: { reason: "session-only", why: "Base prompt selection requires the gui-session principal (codex-prompt-routes.ts:298)." } },
+  { method: "POST", path: "/api/codex-prompt/base/import", module: "server/management/codex-prompt-routes", mutates: true, exempt: { reason: "session-only", why: "Base prompt import requires the gui-session principal (codex-prompt-routes.ts:298)." } },
   { method: "PUT", path: "/api/codex-prompt/custom", module: "server/management/codex-prompt-routes", mutates: true, exempt: { reason: "session-only", why: "Custom prompt write requires the gui-session principal (codex-prompt-routes.ts:298)." } },
   { method: "PUT", path: "/api/codex-prompt/toggle", module: "server/management/codex-prompt-routes", mutates: true, exempt: { reason: "session-only", why: "Prompt toggle requires the gui-session principal (codex-prompt-routes.ts:298)." } },
   // server/management/combo-routes
@@ -361,8 +362,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/protocols", module: "server/management/protocol-routes", mutates: false },
   { method: "POST", path: "/api/protocols/plan", module: "server/management/protocol-routes", mutates: false },
   { method: "PATCH", path: "/api/protocols/settings", module: "server/management/protocol-routes", mutates: true },
-  { method: "GET", path: "/api/workflow-budget", module: "server/management/workflow-budget-routes", mutates: false, exempt: { reason: "deferred-verb", why: "Reading a root's live budget is owed a CLI verb -- an operator staring at a 429 is usually already in a terminal -- but the ledger is process memory with no local transport to read it through, so the verb has to be an HTTP call the CLI does not yet make.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
-  { method: "POST", path: "/api/workflow-budget/clear", module: "server/management/workflow-budget-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Clearing one root is owed the same verb as the read above and for the same reason. It is deliberately not shipped as a verb in this work-phase: the read comes first, because an operator who cannot see which ceiling fired has no basis for deciding to forgive it.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
+  { method: "GET", path: "/api/workflow-budget", module: "server/management/workflow-budget-routes", mutates: false, exempt: { reason: "deferred-verb", why: "Reading a root's live budget is owed a CLI verb -- an operator staring at a 429 is usually already in a terminal -- but the ledger is process memory with no local transport to read it through, so the verb has to be an HTTP call the CLI does not yet make.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_fin/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
+  { method: "POST", path: "/api/workflow-budget/clear", module: "server/management/workflow-budget-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Clearing one root is owed the same verb as the read above and for the same reason. It is deliberately not shipped as a verb in this work-phase: the read comes first, because an operator who cannot see which ceiling fired has no basis for deciding to forgive it.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_fin/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
   // server/management/request-history-routes
   { method: "GET", path: "/api/request-history", module: "server/management/request-history-routes", mutates: false },
   // server/management/routing-analytics-routes
@@ -390,11 +391,12 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   // server/management/link-routes
   { method: "GET", path: "/api/link/status", module: "server/management/link-routes", mutates: false },
   { method: "GET", path: "/api/link/candidates", module: "server/management/link-routes", mutates: false, exempt: { reason: "session-only", why: "SSH candidates are a dashboard surface: a paired session, or on a standalone runtime the current loopback dashboard session on trusted loopback ingress; admin-token and Tailscale identity sessions are refused." } },
-  { method: "POST", path: "/api/link/probe", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "SSH probing and host-key presentation are part of the interactive dashboard consent flow (paired, or standalone loopback dashboard on trusted loopback ingress)." } },
-  { method: "POST", path: "/api/link/confirm-host", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Persisting a host key requires the dashboard session that saw the fingerprint (paired, or standalone loopback dashboard on trusted loopback ingress)." } },
+  { method: "POST", path: "/api/link/probe", module: "server/management/link-routes", mutates: true },
+  { method: "POST", path: "/api/link/confirm-host", module: "server/management/link-routes", mutates: true },
   { method: "POST", path: "/api/link/join", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Joining a confirmed Home issues a link credential and restarts this standalone runtime as a client on its configured port, which briefly interrupts running Codex turns. It requires an operator-paired dashboard session and a pre-join notice; unpaired standalone loopback, admin-token and Tailscale identity sessions are refused." } },
-  { method: "POST", path: "/api/link/apply", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Applying a link issues a data key and starts a remote tunnel, so it requires a dashboard session (paired, or standalone loopback dashboard on trusted loopback ingress)." } },
+  { method: "POST", path: "/api/link/apply", module: "server/management/link-routes", mutates: true },
   { method: "DELETE", path: "/api/link/{id}", module: "server/management/link-routes", mutates: true, mechanism: "regex" },
+  { method: "POST", path: "/api/link/{id}/reconnect", module: "server/management/link-routes", mutates: true, mechanism: "regex" },
   { method: "POST", path: "/api/link/issue", module: "server/management/link-routes", mutates: true },
   // server/management/remote-workspace-routes
   { method: "GET", path: "/api/remote-workspace", module: "server/management/remote-workspace-routes", mutates: false },

package/src/server/management/shared.ts

@@ -3,6 +3,7 @@ import { captureInitialSelectionBaseline, finalizeInitialModelSelection } from "
 import { captureModelDiscoveryBaseline, finalizeModelDiscovery } from "../../providers/new-model-policy-runtime";
 import { CatalogGatherBusyError } from "../../codex/catalog/routed-gather";
 import { initialModelSelectionPending } from "../../providers/initial-model-selection";
+import { isPassiveRead } from "../../lib/passive-read";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
 import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
@@ -291,6 +292,8 @@ export async function fetchAllModels(
   /** Management renders disabled rows using this detached state after inventory drift. */
   publishProjection?: (projection: OcxConfig) => void,
 ): Promise<CatalogModel[]> {
+  // A Remote Link read: no upstream, no initial selection, no write (#6959).
+  if (isPassiveRead()) return [];
   const { gatherRoutedModels } = await import("../../codex/catalog");
   const baseline = captureInitialSelectionBaseline(config);
   const discoveryBaseline = captureModelDiscoveryBaseline(config);

package/src/server/management-api.ts

@@ -54,7 +54,7 @@ import { noteExplicitShutdownRequested } from "./management/system-restart";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "./request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../usage/cost";
 import type { PersistedUsageAttempt } from "../usage/log";
-import { isAllowedManagementOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "./auth-cors";
+import { inheritTrustedHubManagementRequest, isAllowedManagementOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "./auth-cors";
 import { applySystemEnvToggle } from "./system-env";
 
 import type { ManagementApiDeps } from "./management/context";
@@ -242,7 +242,9 @@ export async function handleManagementAPI(
     if (verified.status !== 200) {
       return jsonResponse({ error: "account switch body rejected" }, verified.status, req, config);
     }
+    const sourceReq = req;
     req = new Request(req.url, { method: req.method, headers: req.headers, body: Buffer.from(verified.body) });
+    inheritTrustedHubManagementRequest(sourceReq, req);
   }
   // Management bodies are small JSON (provider names, key ids, settings). Reject oversized
   // payloads before any handler buffers them — the data plane has its own decompression cap.

package/src/server/messages-native.ts

@@ -115,6 +115,8 @@ import {
   type RequestLogContext,
 } from "./request-log";
 import { fetchWithHeaderTimeout, providerFetch, safeHostLabel, sendWithConnectionPolicy } from "./responses/fetch-helpers";
+import { anthropicBillingPhysicalFetch } from "../providers/anthropic-billing-ownership";
+import { rotateAnthropicBillingKeyOnResponse } from "../providers/anthropic-billing-recovery";
 import { linkAbortSignal } from "./responses/core-lifetime";
 import { attachRequestSpendTracker } from "./responses/request-spend";
 import { workflowRefusalResponse } from "./workflow-refusal";
@@ -441,6 +443,8 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
   if (oauthBinding) logCtx.provider = formatAnthropicProviderForLog(route.providerName, oauthBinding.snapshot.accountId, config);
   const spendTracker = attachRequestSpendTracker(req, logCtx);
   const physicalBudget = createInferenceSendBudget(req, logCtx);
+  // Observe-only spend is already booked by the tracker; count billing sends without booking again.
+  let physicalSendsUsed = 0;
   let activeRequest: AnthropicMessagesPassthroughRequest;
   let retainedRequestBytes = 0;
   const releaseRetainedRequest = () => {
@@ -589,8 +593,9 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
               // exact incarnation across its await; a returned response can never reserve one.
               sendOwner = snapshot ? captureAnthropicPhysicalSendOwnership(snapshot) : null;
               if (snapshot && !sendOwner) throw new NativeOAuthSelectionChangedError();
+              physicalSendsUsed++;
               dispatched = await sendWithConnectionPolicy(
-                (activeProvider as OcxProviderTransport).fetch ?? execute,
+                anthropicBillingPhysicalFetch((activeProvider as OcxProviderTransport).fetch ?? execute, route.providerName, activeProvider),
                 wire.url,
                 applyUpstreamRecoveryInit({ ...init, method: "POST", headers, body: wire.body }, transportRecovery),
                 { providerName: route.providerName, provider: activeProvider },
@@ -638,49 +643,70 @@ export async function handleNativeMessages(options: HandleNativeMessagesOptions)
   let response: Response;
   try {
     response = await send();
-    // A credential-scoped 401 on a static key pool says nothing about the sibling keys.
-    while (response.status === 401 && hasKeyPoolFailover(activeProvider) && transientSendAvailable()) {
-      const rotated = rotateProviderTransportOn401(config, route.providerName, activeProvider, {
-        now: Date.now(),
-        attemptedKey: activeProvider.apiKey,
-      });
-      if (!rotated) break;
-      discard(response);
-      rebuildFor(rotated);
-      response = await send("key-401");
-    }
     const retryPolicy = oauthBinding ? undefined : rateLimitRetryPolicyFor(activeProvider);
     let retries = 0;
-    // A refusal this proxy synthesized for a reset replay is not a provider rate limit.
-    while (
-      response.status === 429
-      && !isNonReplayableResponse(response)
-      && retryPolicy
-      && retries < retryPolicy.attempts
-      && transientSendAvailable()
-    ) {
-      retries += 1;
-      for await (const _ of prepareSameTarget429Wait({
-        body: response.body,
-        signal: upstream.signal,
-        delayMs: rateLimitRetryDelayMs(retryPolicy, response.headers.get("retry-after"), Date.now()),
-      })) { /* pre-stream wait */ }
-      if (upstream.signal.aborted) throw upstream.signal.reason;
-      response = await send("rate-limit-429");
-    }
-    while (response.status === 429 && !isNonReplayableResponse(response) && hasKeyPoolFailover(activeProvider)) {
-      const rotated = rotateProviderTransportOn429(config, route.providerName, activeProvider, {
-        retryAfter: response.headers.get("retry-after"),
-        now: Date.now(),
-        attemptedKey: activeProvider.apiKey,
-        attemptedSelection: activeProvider._apiKeyAttempt,
-      });
-      if (!rotated) break;
-      // Rotation already recorded the cooldown; keep the terminal 429 when no send remains.
-      if (!transientSendAvailable()) break;
-      discard(response);
-      rebuildFor(rotated);
-      response = await send("key-429");
+    let billingRecoveryActive = false;
+    const keySendAvailable = () => transientSendAvailable()
+      && (!billingRecoveryActive || Math.max(physicalSendsUsed, physicalBudget.used) < physicalBudget.policy.maxTotalModelSends);
+    for (;;) {
+      const priorResponse = response;
+      // A credential-scoped 401 on a static key pool says nothing about the sibling keys.
+      while (response.status === 401 && hasKeyPoolFailover(activeProvider) && keySendAvailable()) {
+        const rotated = rotateProviderTransportOn401(config, route.providerName, activeProvider, {
+          now: Date.now(),
+          attemptedKey: activeProvider.apiKey,
+        });
+        if (!rotated) break;
+        discard(response);
+        rebuildFor(rotated);
+        response = await send("key-401");
+      }
+      while ((response.status === 400 || response.status === 402) && hasKeyPoolFailover(activeProvider)) {
+        const rotated = await rotateAnthropicBillingKeyOnResponse(response, config, route.providerName, activeProvider, { signal: upstream.signal });
+        if (!rotated) break;
+        billingRecoveryActive = true;
+        if (!keySendAvailable()) break;
+        discard(response);
+        rebuildFor(rotated);
+        response = await send("key-401");
+      }
+      // A refusal this proxy synthesized for a reset replay is not a provider rate limit.
+      while (
+        response.status === 429
+        && !isNonReplayableResponse(response)
+        && retryPolicy
+        && retries < retryPolicy.attempts
+        && keySendAvailable()
+      ) {
+        retries += 1;
+        for await (const _ of prepareSameTarget429Wait({
+          body: response.body,
+          signal: upstream.signal,
+          delayMs: rateLimitRetryDelayMs(retryPolicy, response.headers.get("retry-after"), Date.now()),
+        })) { /* pre-stream wait */ }
+        if (upstream.signal.aborted) throw upstream.signal.reason;
+        response = await send("rate-limit-429");
+      }
+      while (response.status === 429 && !isNonReplayableResponse(response) && hasKeyPoolFailover(activeProvider)) {
+        const rotated = rotateProviderTransportOn429(config, route.providerName, activeProvider, {
+          retryAfter: response.headers.get("retry-after"),
+          now: Date.now(),
+          attemptedKey: activeProvider.apiKey,
+          attemptedSelection: activeProvider._apiKeyAttempt,
+        });
+        if (!rotated) break;
+        // Rotation already recorded the cooldown; keep the terminal 429 when no send remains.
+        if (!keySendAvailable()) break;
+        discard(response);
+        rebuildFor(rotated);
+        response = await send("key-429");
+      }
+      // A sibling's next refusal may change class; the same counters survive that transition.
+      if (response !== priorResponse && (
+        (billingRecoveryActive && [401, 429].includes(response.status))
+        || (activeProvider.adapter === "anthropic" && hasKeyPoolFailover(activeProvider) && [400, 402].includes(response.status))
+      )) continue;
+      break;
     }
     const oauthRetryKey = {};
     const triedAccountIds = new Set<string>();

package/src/server/relay-eager.ts

@@ -338,6 +338,8 @@ export function relaySseEagerBounded(
                 upstreamError,
                 terminalBoundary.upstreamRefusalCode(),
                 opts?.maskCredential,
+                terminalBoundary.upstreamErrorType(),
+                terminalBoundary.upstreamErrorCode(),
               );
             queuedBytes += upstreamErrorFrame.byteLength + terminalSentinel.byteLength;
             try {
@@ -478,6 +480,8 @@ export function relaySseEagerBounded(
         }
       }
     } finally {
+      upstream.signal.removeEventListener("abort", wakeUp);
+      upstream.signal.removeEventListener("abort", wakeParkedRead);
       // Release any retained rewrite-buffer bytes on every teardown path
       // (error, cancel, upstream abort) — consumption/EOF release alone
       // leaves them charged.

package/src/server/relay.ts

@@ -6,13 +6,14 @@ import {
   isCyberPolicyCode,
   isCyberPolicyMessage,
   isTerminalRefusalCode,
+  recognizedUpstreamError,
   safetyRefusalCodeFromMessage,
   terminalRefusalFallbackMessage,
   upstreamErrorMessageFromPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
-import { carryReplayRefusal } from "../lib/upstream-retry";
+import { carryReplayRefusal, isReplayRefusalResponse } from "../lib/upstream-retry";
 import { isUsageDebugEnabled } from "../usage/debug";
 import {
   addRequestLog,
@@ -168,25 +169,28 @@ export function failedTailFrame(encoder: TextEncoder, err: unknown, maskCredenti
  * classifies this terminal by `error.code` alone and retries everything outside
  * its fatal set (codex-rs/codex-api/src/sse/responses.rs:423-450), so stamping
  * `upstream_server_error` on a refusal delivered it as a retryable disconnect
- * and drove the reconnect loop in #5176. Without a refusal code the terminal is
- * unchanged: a genuine transport failure stays retryable, which is what it is.
+ * and drove the reconnect loop in #5176. Without a refusal code the terminal
+ * carries only recognized rate-limit/overload classes; unknown codes stay generic.
  */
 export function upstreamErrorTailFrame(
   encoder: TextEncoder,
   message: string,
   refusalCode?: string,
   maskCredential?: (text: string) => string,
+  errorType?: string,
+  errorCode?: string,
 ): Uint8Array {
   return encoder.encode(
-    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode, maskCredential)}\n\n`,
+    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode, maskCredential, errorType, errorCode)}\n\n`,
   );
 }
 
-function upstreamErrorFailedPayload(message: string, refusalCode?: string, maskCredential?: (text: string) => string): string {
+function upstreamErrorFailedPayload(message: string, refusalCode?: string, maskCredential?: (text: string) => string, errorType?: string, errorCode?: string): string {
   const diagnostic = redactSecretString(message);
+  const recognized = recognizedUpstreamError({ type: errorType, code: errorCode });
   const error = {
-    type: refusalCode === undefined ? "upstream_error" : "invalid_request_error",
-    code: refusalCode === undefined ? "upstream_server_error" : (maskCredential?.(refusalCode) ?? refusalCode),
+    type: refusalCode === undefined ? (recognized?.type ?? "upstream_error") : "invalid_request_error",
+    code: refusalCode === undefined ? (recognized?.code ?? "upstream_server_error") : (maskCredential?.(refusalCode) ?? refusalCode),
     message: (maskCredential?.(diagnostic) ?? diagnostic).slice(0, MAX_TAIL_ERROR_MESSAGE_CHARS),
   };
   return JSON.stringify({
@@ -549,6 +553,8 @@ export function relaySseWithFailedTail(
                   upstreamError,
                   terminalBoundary.upstreamRefusalCode(),
                   opts?.maskCredential,
+                  terminalBoundary.upstreamErrorType(),
+                  terminalBoundary.upstreamErrorCode(),
                 ));
               controller.enqueue(doneFrame(encoder));
             }
@@ -898,6 +904,11 @@ export function responseWithDeferredRequestLog(
   logCtx: RequestLogContext,
   addLog: (entry: RequestLogEntry) => void = addRequestLog,
 ): Response {
+  // A synthetic 429 is a transport verdict, not evidence that the provider declined the turn.
+  if (isReplayRefusalResponse(response)) {
+    logCtx.causeHint = "transport-ambiguous";
+    logCtx.terminalSource = "synthetic";
+  }
   const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
   if (isUsageDebugEnabled() && !logCtx.usageDebugContentType && contentType) {
     logCtx.usageDebugContentType = contentType;

package/src/server/request-log-failure-attribution.ts

@@ -21,6 +21,8 @@ export interface FinalRequestAttributionFacts {
   readonly closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow" | undefined;
   readonly transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse" | undefined;
   readonly terminalSource?: "upstream" | "synthetic" | undefined;
+  /** A failure cause proved by the transport's in-process verdict. */
+  readonly causeHint?: RequestFailureCause | undefined;
   /** The REQUEST's first-output observation, not the final attempt's. See below. */
   readonly outputObserved: boolean;
   readonly locallyAnswered: boolean;
@@ -53,6 +55,7 @@ export function attributeFinalRequest(facts: FinalRequestAttributionFacts): Stam
     ...(facts.closeReason ? { closeReason: facts.closeReason } : {}),
     ...(facts.transportPhase ? { transportPhase: facts.transportPhase } : {}),
     ...(facts.terminalSource ? { terminalSource: facts.terminalSource } : {}),
+    ...(facts.causeHint ? { causeHint: facts.causeHint } : {}),
     ...(facts.attempt?.streamAborted === true ? { streamAborted: true } : {}),
     outputObserved: facts.outputObserved,
     // The one fact that can raise a stage above `semantic-output`, and the reason it is counted

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

@@ -52,7 +52,7 @@ export function queryRequestLogs(
     for (const entry of logs) {
       if (provider && entry.provider !== provider && !entry.attempts?.some(attempt => attempt.provider === provider)) continue;
       if (conversationId && !matchesLogConversationId(entry.conversationId, conversationId)) continue;
-      if (model && entry.model !== model && !entry.attempts?.some(attempt => attempt.model === model)) continue;
+      if (model && !matchesModel(entry, model) && !entry.attempts?.some(attempt => matchesModel(attempt, model))) continue;
       if (account && entry.accountLogLabel !== account && !entry.attempts?.some(attempt => attempt.accountLogLabel === account)) continue;
       if (protocolMode && !matchesProtocolMode(entry, protocolMode)) continue;
       if (status && (statusClass === undefined ? String(entry.status) !== status : Math.floor(entry.status / 100) !== statusClass)) continue;
@@ -91,3 +91,8 @@ export function filterRequestLogs(logs: RequestLogEntry[], params: URLSearchPara
 export function filteredRequestLogCount(logs: RequestLogEntry[], params: URLSearchParams): number {
   return queryRequestLogs(logs, params).total;
 }
+
+/** A bare ID may itself contain slashes; compare against each observed destination as a whole. */
+function matchesModel(row: { provider?: string; model?: string }, model: string): boolean {
+  return row.model === model || (row.provider !== undefined && row.model !== undefined && `${row.provider}/${row.model}` === model);
+}

package/src/server/request-log-terminal-status.ts

@@ -0,0 +1,243 @@
+import {
+  CYBER_POLICY_ERROR_CODE,
+  httpStatusFromTerminalError,
+  isCyberPolicyCode,
+  isCyberPolicyMessage,
+  isRateLimitOrQuotaFailureMessage,
+  recognizedUpstreamError,
+} from "../lib/errors";
+import { redactSecretString } from "../lib/redact";
+import { outboundCredentials, type OutboundCredentialRegistry } from "../lib/outbound-credential-registry";
+import { configuredCredentials, type ConfiguredCredentials } from "./configured-credentials";
+import { codexWsWrapperStatus } from "./responses/codex-ws-wire";
+
+/** First bounded upstream diagnostics shared by request contexts and final rows. */
+export interface UpstreamErrorDiagnostics {
+  upstreamErrorCode?: string;
+  upstreamErrorType?: string;
+  upstreamRequestId?: string;
+}
+
+interface TerminalStatusContext extends UpstreamErrorDiagnostics {
+  terminalHttpStatus?: number;
+  terminalErrorCode?: typeof CYBER_POLICY_ERROR_CODE;
+}
+
+export interface UpstreamErrorPayload {
+  type?: unknown;
+  code?: unknown;
+  message?: unknown;
+  /** Codex WebSocket wrapper status (`status_code` is its alias); read only on bare `error` events. */
+  status?: unknown;
+  status_code?: unknown;
+  error?: { type?: unknown; code?: unknown; message?: unknown };
+  last_error?: { type?: unknown; code?: unknown; message?: unknown };
+  response?: {
+    error?: { type?: unknown; code?: unknown; message?: unknown };
+    incomplete_details?: { code?: unknown; message?: unknown; reason?: unknown };
+  };
+}
+
+// Bare error evidence is provisional: only a genuine terminal owns account-health status.
+const provisionalStatuses = new WeakMap<TerminalStatusContext, number>();
+const genuineTerminals = new WeakSet<TerminalStatusContext>();
+
+const UPSTREAM_DIAGNOSTIC_TOKEN = /^[A-Za-z0-9_.:-]{1,128}$/;
+
+/**
+ * Upstream diagnostics are provider-controlled. The token alphabet alone also admits
+ * credential formats (an echoed `sk-...` key fits it), so a value the shared redactor
+ * would change is dropped rather than recorded, warned, or projected into log rows.
+ */
+function isSafeDiagnosticToken(value: unknown): value is string {
+  return typeof value === "string" && UPSTREAM_DIAGNOSTIC_TOKEN.test(value) && redactSecretString(value) === value;
+}
+
+/**
+ * Error classes published by the supported provider APIs (OpenAI/Responses, Anthropic, Gemini).
+ * The type is diagnostic only, so the vocabulary is closed: a gateway can echo anything in
+ * `error.type`, including a configured credential whose format no redactor recognizes, and a
+ * value outside this set is simply not recorded, which is what 2.82.0 did for every type.
+ */
+const KNOWN_UPSTREAM_ERROR_TYPES: ReadonlySet<string> = new Set([
+  "api_error", "authentication_error", "billing_error", "insufficient_quota", "invalid_request_error",
+  "not_found_error", "overloaded_error", "permission_error", "rate_limit_error", "request_too_large",
+  "requests", "server_error", "timeout_error", "tokens",
+  "INVALID_ARGUMENT", "FAILED_PRECONDITION", "PERMISSION_DENIED", "UNAUTHENTICATED", "NOT_FOUND",
+  "RESOURCE_EXHAUSTED", "INTERNAL", "UNAVAILABLE", "DEADLINE_EXCEEDED",
+]);
+
+/** Bare top-level error codes worth keeping: the classes recognizedUpstreamError maps, plus server_error. */
+const KNOWN_BARE_ERROR_CODES: ReadonlySet<string> = new Set([
+  "rate_limit_exceeded", "rate_limit_error", "server_is_overloaded", "overloaded_error", "server_error",
+]);
+
+function noteBoundedDiagnostic(
+  logCtx: TerminalStatusContext,
+  field: "upstreamErrorCode" | "upstreamErrorType" | "upstreamRequestId",
+  value: unknown,
+): void {
+  if (logCtx[field] !== undefined) return;
+  if (!isSafeDiagnosticToken(value)) return;
+  if (field === "upstreamErrorType" && !KNOWN_UPSTREAM_ERROR_TYPES.has(value)) return;
+  if (!diagnosticValueAllowed(value)) return;
+  logCtx[field] = value;
+  const status = logCtx.terminalHttpStatus;
+  if (status === undefined || status >= 500) {
+    const { upstreamErrorCode: code, upstreamRequestId: requestId } = upstreamDiagnosticLogFields(logCtx);
+    console.warn(`[opencodex] upstream failure${status ? ` status=${status}` : ""}${code ? ` code=${code}` : ""}${requestId ? ` request_id=${requestId}` : ""}`);
+  }
+}
+
+/**
+ * A diagnostic must not repeat a configured credential or a credential this process sent upstream
+ * (an echo). All three fields fail closed while either source cannot vouch for complete coverage:
+ * a closed type vocabulary does not prove a member is not also a credential. Applied at capture,
+ * again for every retained value interpolated into a warning, and at projection, because a
+ * credential can be configured or sent after the value was captured.
+ */
+export function diagnosticValueAllowed(
+  value: string,
+  registry: OutboundCredentialRegistry = outboundCredentials(),
+  configured: ConfiguredCredentials = configuredCredentials(),
+): boolean {
+  if (!registry.complete() || !configured.complete) return false;
+  return !registry.matches(value) && !configured.matches(value);
+}
+
+export function noteUpstreamRequestId(logCtx: TerminalStatusContext, headers: Headers): void {
+  noteBoundedDiagnostic(logCtx, "upstreamRequestId", headers.get("openai-request-id") ?? headers.get("x-request-id"));
+}
+
+export function captureUpstreamTerminalDiagnostics(logCtx: TerminalStatusContext, json: UpstreamErrorPayload): void {
+  captureTerminalHttpStatus(logCtx, json);
+  noteBoundedDiagnostic(logCtx, "upstreamErrorCode",
+    json.error?.code ?? json.last_error?.code ?? json.response?.error?.code
+      // A bare top-level code (new in 2.83.0) has no envelope contract, so only a known class is kept.
+      ?? (typeof json.code === "string" && KNOWN_BARE_ERROR_CODES.has(json.code) ? json.code : undefined));
+  noteBoundedDiagnostic(logCtx, "upstreamErrorType",
+    json.error?.type ?? json.last_error?.type ?? json.response?.error?.type);
+}
+
+export function upstreamDiagnosticLogFields(logCtx: UpstreamErrorDiagnostics): UpstreamErrorDiagnostics {
+  // One verification per projection: the three fields are checked at the same instant, so they
+  // share one snapshot of each source, taken only once a field is actually populated (a row with
+  // no upstream diagnostic reads no credential store).
+  let sources: { registry: OutboundCredentialRegistry; configured: ConfiguredCredentials } | undefined;
+  const allowed = (field: keyof UpstreamErrorDiagnostics): string | undefined => {
+    const value = logCtx[field];
+    if (!value) return undefined;
+    sources ??= { registry: outboundCredentials(), configured: configuredCredentials() };
+    return diagnosticValueAllowed(value, sources.registry, sources.configured) ? value : undefined;
+  };
+  const code = allowed("upstreamErrorCode");
+  const type = allowed("upstreamErrorType");
+  const requestId = allowed("upstreamRequestId");
+  return {
+    ...(code ? { upstreamErrorCode: code } : {}),
+    ...(type ? { upstreamErrorType: type } : {}),
+    ...(requestId ? { upstreamRequestId: requestId } : {}),
+  };
+}
+
+/**
+ * The server status a Codex WebSocket `error` frame states on its wrapper ({@link codexWsWrapperStatus}),
+ * or undefined. Only 5xx is returned. Every 5xx is the same transient class for account health, so
+ * this changes what a row says, not where the next turn goes; a wrapper 4xx would move quota and
+ * credential routing and is left to its own review (#6740).
+ */
+export function wrappedServerErrorStatus(json: UpstreamErrorPayload): number | undefined {
+  const status = codexWsWrapperStatus(json as Record<string, unknown>);
+  return status !== undefined && status >= 500 ? status : undefined;
+}
+
+function captureTerminalHttpStatus(
+  logCtx: TerminalStatusContext,
+  json: UpstreamErrorPayload,
+): void {
+  const type = json.type;
+  const terminal = type === "response.failed" || type === "response.completed" || type === "response.incomplete";
+  if (!terminal && type !== "error") return;
+  if (terminal && provisionalStatuses.has(logCtx)) {
+    const provisional = provisionalStatuses.get(logCtx);
+    provisionalStatuses.delete(logCtx);
+    if (logCtx.terminalHttpStatus === provisional) {
+      delete logCtx.terminalHttpStatus;
+      delete logCtx.terminalErrorCode;
+    }
+  }
+  if (logCtx.terminalHttpStatus !== undefined || (type === "error" && genuineTerminals.has(logCtx))) return;
+  if (terminal) genuineTerminals.add(logCtx);
+  const noteStatus = (status: number): void => {
+    logCtx.terminalHttpStatus = status;
+    if (type === "error") provisionalStatuses.set(logCtx, status);
+  };
+  // A completed terminal only retires provisional bare-error evidence; it records no status.
+  if (type === "response.completed") return;
+  const responseError = json.response?.error;
+  const responseDetails = json.response?.incomplete_details;
+  const candidates: Array<{ type?: unknown; code?: unknown; message?: unknown } | undefined> = [
+    json.error, json.last_error, responseError, responseDetails, json,
+  ];
+  const policy = candidates.some(candidate => (
+    candidate?.code === null || typeof candidate?.code === "string"
+  ) && isCyberPolicyCode(candidate.code as string | null | undefined))
+    || candidates.some(candidate => (
+      typeof candidate?.message === "string"
+      && candidate.message.trim().length > 0
+      && isCyberPolicyMessage(candidate.message)
+    ));
+  if (policy) {
+    logCtx.terminalErrorCode = CYBER_POLICY_ERROR_CODE;
+    noteStatus(400);
+    return;
+  }
+  // A quota terminal can carry only a structured reason, without an error message.
+  // Keep this separate from normal output limits and from the policy precedence above.
+  const quotaTag = (value: unknown): boolean => value === "usage_limit_reached"
+    || value === "rate_limit_exceeded" || value === "insufficient_quota";
+  const structuredRefusal = candidates.some(candidate => [400, 401, 403, 499].includes(
+    httpStatusFromTerminalError({
+      type: typeof candidate?.type === "string" ? candidate.type : undefined,
+      code: typeof candidate?.code === "string" ? candidate.code : undefined,
+    }),
+  ));
+  const ordinaryIncompleteReason = typeof responseDetails?.reason === "string"
+    && ["max_output_tokens", "content_filter", "steered", "upstream_stall_timeout", "adapter_eof"].includes(responseDetails.reason);
+  if (type === "response.incomplete" && !structuredRefusal && (quotaTag(responseDetails?.reason) || candidates.some(candidate =>
+    quotaTag(candidate?.code)
+    || quotaTag(candidate?.type) || candidate?.type === "rate_limit_error"
+    || (!ordinaryIncompleteReason && typeof candidate?.message === "string" && isRateLimitOrQuotaFailureMessage(candidate.message))
+  ))) {
+    // The shared quota classifier also accepts a numeric HTTP status as its message.
+    // Preserve explicit payment-required evidence rather than relabeling it as 429.
+    noteStatus(candidates.some(candidate => typeof candidate?.message === "string"
+      && Number(candidate.message.trim()) === 402) ? 402 : 429);
+    return;
+  }
+  if (type === "error") {
+    const structured = recognizedUpstreamError({
+      code: candidates.find(candidate => typeof candidate?.code === "string")?.code,
+      type: candidates.slice(0, -1).find(candidate => typeof candidate?.type === "string")?.type,
+    });
+    if (structured) {
+      noteStatus(structured.httpStatus);
+      return;
+    }
+    // An unrecognized class keeps only the status the upstream itself stated on the WebSocket
+    // wrapper. Nothing is invented here: with no wrapper status the row stays the synthetic 502, and
+    // combo preflight still reads its wider set of explicit event fields after this one.
+    const wrapped = wrappedServerErrorStatus(json);
+    if (wrapped !== undefined) noteStatus(wrapped);
+    return;
+  }
+  if (type !== "response.failed" || !responseError || typeof responseError !== "object") return;
+  const responseCode = responseError.code === null || typeof responseError.code === "string"
+    ? responseError.code
+    : undefined;
+  noteStatus(httpStatusFromTerminalError({
+    type: typeof responseError.type === "string" ? responseError.type : undefined,
+    code: responseCode,
+    message: typeof responseError.message === "string" ? responseError.message : undefined,
+  }));
+}