@bitkyc08/opencodex 2.7.39 → 2.7.40

package/src/codex/routing.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { saveConfig } from "../config";
 import { isCodexAccountGenerationLive, readCodexAccountRecord } from "./account-store";
 import { codexAccountLogLabel } from "./account-label";
@@ -31,6 +32,29 @@ type CodexUpstreamHealth = {
   lastFailureAt?: number;
   /** Hard cooldown (quota 429). Survives a later 2xx; blocks auth + selection. */
   cooldownUntil?: number;
+  /** When the current cooldown was recorded; origin of the probe interval clock. */
+  cooldownSince?: number;
+  /**
+   * What produced the cooldown. An explicit Retry-After is a literal retry
+   * directive and is never probed; a quota resetAt only announces a window
+   * refresh, so it may be probed early (#433).
+   */
+  cooldownSource?: CodexCooldownSource;
+  /**
+   * Bumped on every cooldown write. A probe lease records the generation it was
+   * issued for so a lease cannot clear a cooldown that a later 429 replaced.
+   */
+  cooldownGeneration?: number;
+  /**
+   * Identity of the in-flight probe. A cooled-down account sends no traffic, so
+   * no organic 2xx can prove recovery; only the outcome carrying this id may
+   * clear the cooldown.
+   */
+  probeLeaseId?: string;
+  /** Cooldown generation at the moment the lease was granted. */
+  probeLeaseGeneration?: number;
+  /** Last probe grant or conclusion; paces the probe interval. */
+  lastProbeAt?: number;
   /**
    * Soft avoid after connect_error / timeout / transient 5xx. Cleared on 2xx.
    * Blocks pool selection + thread affinity reuse so a sticky session can leave a
@@ -41,6 +65,15 @@ type CodexUpstreamHealth = {
 
 const CODEX_DEFAULT_QUOTA_COOLDOWN_MS = 60_000;
 const CODEX_MAX_QUOTA_COOLDOWN_MS = 24 * 60 * 60_000;
+/**
+ * A weekly/monthly quota `resetAt` announces when the window refreshes; it is not
+ * a "come back after this" directive like Retry-After. Plan quota routinely frees
+ * up long before the advertised reset, so cap reset-derived cooldowns far below
+ * the Retry-After ceiling (#433).
+ */
+const CODEX_MAX_RESET_DERIVED_COOLDOWN_MS = 15 * 60_000;
+/** Minimum gap between probe leases for one cooled-down account. */
+export const CODEX_QUOTA_PROBE_INTERVAL_MS = 5 * 60_000;
 export const CODEX_FAILURE_WINDOW_MS = 5 * 60_000;
 /** How long a transient failure keeps the account out of pool selection. */
 export const CODEX_TRANSIENT_SOFT_AVOID_MS = 30_000;
@@ -60,12 +93,19 @@ const upstreamHealth = new Map<string, CodexUpstreamHealth>();
 
 export type CodexUpstreamOutcome = number | "connect_error" | "timeout";
 export type CodexUpstreamOutcomeClass = "success" | "credential" | "quota" | "transient" | "caller" | "unknown";
+export type CodexCooldownSource = "retry-after" | "reset-derived" | "default";
 export type CodexUpstreamOutcomeMeta = {
   retryAfter?: string | null;
   resetAt?: unknown | unknown[];
   now?: number;
   /** When set, clears affinity for this thread immediately on transient failure. */
   threadId?: string | null;
+  /**
+   * Probe lease held by this request, when it was admitted through an active
+   * quota cooldown. Only the outcome carrying the current lease may clear the
+   * cooldown (#433).
+   */
+  probeLeaseId?: string;
 };
 
 function hasConfiguredPoolAccount(config: OcxConfig, accountId: string): boolean {
@@ -159,17 +199,104 @@ export function parseResetCooldownMs(resetAt: unknown | unknown[] | undefined, n
     if (timestamp === undefined) continue;
     const delay = timestamp - now;
     if (delay <= 0) continue;
-    const clamped = clampCooldownMs(delay);
+    // A far-future reset must not pin the account for the full Retry-After
+    // ceiling: quota usually frees up well before the advertised window (#433).
+    const clamped = Math.min(clampCooldownMs(delay), CODEX_MAX_RESET_DERIVED_COOLDOWN_MS);
     if (best === undefined || clamped < best) best = clamped;
   }
   return best;
 }
 
-export function computeQuotaCooldownUntil(meta: CodexUpstreamOutcomeMeta = {}): number {
+export function computeQuotaCooldown(meta: CodexUpstreamOutcomeMeta = {}): {
+  until: number;
+  source: CodexCooldownSource;
+} {
   const now = meta.now ?? Date.now();
   const retryAfterMs = parseRetryAfterMs(meta.retryAfter, now);
-  const resetCooldownMs = retryAfterMs === undefined ? parseResetCooldownMs(meta.resetAt, now) : undefined;
-  return now + (retryAfterMs ?? resetCooldownMs ?? CODEX_DEFAULT_QUOTA_COOLDOWN_MS);
+  if (retryAfterMs !== undefined) return { until: now + retryAfterMs, source: "retry-after" };
+  const resetCooldownMs = parseResetCooldownMs(meta.resetAt, now);
+  if (resetCooldownMs !== undefined) return { until: now + resetCooldownMs, source: "reset-derived" };
+  return { until: now + CODEX_DEFAULT_QUOTA_COOLDOWN_MS, source: "default" };
+}
+
+export function computeQuotaCooldownUntil(meta: CodexUpstreamOutcomeMeta = {}): number {
+  return computeQuotaCooldown(meta).until;
+}
+
+/**
+ * Grant at most one probe lease per interval for a cooled-down account.
+ *
+ * A cooled-down account is short-circuited locally, so it never sends traffic and
+ * no organic 2xx can prove that upstream quota recovered — the cooldown can only
+ * end by expiry or a proxy restart (#433). Releasing a single probe breaks that
+ * deadlock. Explicit Retry-After cooldowns are excluded: those are literal retry
+ * directives, not window announcements.
+ *
+ * Returns the lease id, or null when no probe may go out right now.
+ */
+export function tryAcquireCodexQuotaProbeLease(accountId: string, now = Date.now()): string | null {
+  const health = upstreamHealth.get(accountId);
+  if (!health) return null;
+  const cooldownUntil = health.cooldownUntil;
+  if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return null;
+  if (health.cooldownSource === "retry-after") return null;
+  if (health.probeLeaseId !== undefined) return null;
+  const origin = health.lastProbeAt ?? health.cooldownSince ?? cooldownUntil;
+  if (now - origin < CODEX_QUOTA_PROBE_INTERVAL_MS) return null;
+  const probeLeaseId = randomUUID();
+  upstreamHealth.set(accountId, {
+    ...health,
+    probeLeaseId,
+    probeLeaseGeneration: health.cooldownGeneration ?? 0,
+    lastProbeAt: now,
+  });
+  return probeLeaseId;
+}
+
+/**
+ * Hand a probe lease back without recording an upstream outcome. Used by paths
+ * that take a lease and then fail before any request reaches upstream.
+ */
+export function releaseCodexQuotaProbeLease(accountId: string, leaseId: string, now = Date.now()): void {
+  const health = upstreamHealth.get(accountId);
+  if (!health || health.probeLeaseId !== leaseId) return;
+  upstreamHealth.set(accountId, withProbeLeaseReleased(health, now));
+}
+
+/**
+ * True when this outcome belongs to the account's in-flight probe. The
+ * undefined-id guard matters: without it an outcome carrying no lease would match
+ * an account holding no lease and be mistaken for the probe owner.
+ */
+function ownsProbeLease(health: CodexUpstreamHealth | undefined, meta: CodexUpstreamOutcomeMeta): boolean {
+  return meta.probeLeaseId !== undefined && meta.probeLeaseId === health?.probeLeaseId;
+}
+
+/**
+ * True when the owning probe may still clear the cooldown. A later 429 bumps the
+ * generation, so a probe that started under an older cooldown must not erase the
+ * newer restriction (which may carry an explicit Retry-After).
+ */
+function probeMayClearCooldown(health: CodexUpstreamHealth | undefined, meta: CodexUpstreamOutcomeMeta): boolean {
+  return ownsProbeLease(health, meta)
+    && (health!.probeLeaseGeneration ?? 0) === (health!.cooldownGeneration ?? 0);
+}
+
+/** Strip the in-flight lease while preserving every hard-cooldown field. */
+function withProbeLeaseReleased(health: CodexUpstreamHealth, now: number): CodexUpstreamHealth {
+  const { probeLeaseId: _id, probeLeaseGeneration: _gen, ...rest } = health;
+  return { ...rest, lastProbeAt: now };
+}
+
+/**
+ * Hard-cooldown bookkeeping that ordinary success/transient transitions rebuild
+ * their health object from. Dropping these would let one late unrelated response
+ * erase a Retry-After source, a cooldown generation, or someone else's live probe.
+ */
+function preservedCooldownFields(health: CodexUpstreamHealth | undefined): Partial<CodexUpstreamHealth> {
+  if (!health) return {};
+  const { consecutiveFailures: _f, consecutiveSuccesses: _s, lastFailureStatus: _st, lastFailureAt: _at, softAvoidUntil: _sa, ...cooldownFields } = health;
+  return cooldownFields;
 }
 
 export function getCodexAccountCooldownUntil(accountId: string, now = Date.now()): number | null {
@@ -459,28 +586,49 @@ export function recordCodexUpstreamOutcome(
   if (outcomeClass === "success") {
     const current = upstreamHealth.get(accountId);
     const cooldownUntil = getCodexAccountCooldownUntil(accountId, now);
+    // A leased probe that is still on its own cooldown generation proves the
+    // account recovered: clear the hard cooldown outright (#433).
+    if (cooldownUntil && probeMayClearCooldown(current, meta)) {
+      upstreamHealth.delete(accountId);
+      return;
+    }
+    // Owning probe on a stale generation: the lease is done, but a newer 429
+    // replaced the cooldown in the meantime, so only give the lease back.
+    // Non-owners keep every hard-cooldown field, including someone else's live lease.
+    const base = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
+    const preserved = preservedCooldownFields(base);
     const failoverEnabled = (config.upstreamFailoverThreshold ?? 3) > 0;
     if (failoverEnabled && current && current.consecutiveFailures >= 2) {
       const consecutiveSuccesses = (current.consecutiveSuccesses ?? 0) + 1;
       if (consecutiveSuccesses < 2) {
         upstreamHealth.set(accountId, {
-          ...current,
+          ...base!,
+          ...preserved,
           consecutiveSuccesses,
-          ...(cooldownUntil ? { cooldownUntil } : {}),
         });
         return;
       }
     }
     // Level 1 clears immediately; escalated accounts need two consecutive healthy terminals.
     // Hard quota cooldown intentionally survives either recovery path.
-    if (cooldownUntil) upstreamHealth.set(accountId, { consecutiveFailures: 0, cooldownUntil });
+    if (cooldownUntil) upstreamHealth.set(accountId, { consecutiveFailures: 0, ...preserved });
     else upstreamHealth.delete(accountId);
     return;
   }
-  if (outcomeClass === "caller") return;
+  if (outcomeClass === "caller") {
+    // A 4xx does not change account health, but it does conclude an in-flight
+    // probe — otherwise the lease would never be handed back.
+    const current = upstreamHealth.get(accountId);
+    if (ownsProbeLease(current, meta)) {
+      upstreamHealth.set(accountId, withProbeLeaseReleased(current!, now));
+    }
+    return;
+  }
 
   const lastFailureStatus = typeof outcome === "number" ? outcome : 0;
   if (outcomeClass === "credential") {
+    // 401/403 quarantines the account for reauth. That supersedes quota state
+    // entirely: a cooldown (and any probe lease) on an unusable account is moot.
     upstreamHealth.set(accountId, {
       consecutiveFailures: 1,
       lastFailureStatus,
@@ -492,11 +640,28 @@ export function recordCodexUpstreamOutcome(
   }
 
   if (outcomeClass === "quota") {
+    const prior = upstreamHealth.get(accountId);
+    const { until, source } = computeQuotaCooldown(meta);
+    // Every cooldown write bumps the generation so a probe issued against the
+    // previous cooldown can no longer clear this one (#433).
+    const cooldownGeneration = (prior?.cooldownGeneration ?? 0) + 1;
+    // A failed probe concludes its lease; an unrelated 429 leaves the live probe alone.
+    const ownsLease = ownsProbeLease(prior, meta);
     upstreamHealth.set(accountId, {
       consecutiveFailures: 0,
       lastFailureStatus,
       lastFailureAt: now,
-      cooldownUntil: computeQuotaCooldownUntil(meta),
+      cooldownUntil: until,
+      cooldownSince: now,
+      cooldownSource: source,
+      cooldownGeneration,
+      ...(ownsLease
+        ? { lastProbeAt: now }
+        : {
+          ...(prior?.probeLeaseId !== undefined ? { probeLeaseId: prior.probeLeaseId } : {}),
+          ...(prior?.probeLeaseGeneration !== undefined ? { probeLeaseGeneration: prior.probeLeaseGeneration } : {}),
+          ...(prior?.lastProbeAt !== undefined ? { lastProbeAt: prior.lastProbeAt } : {}),
+        }),
     });
     clearThreadAccountMapForAccount(accountId);
     if (config.activeCodexAccountId === accountId) {
@@ -508,6 +673,9 @@ export function recordCodexUpstreamOutcome(
 
   // transient (connect_error / timeout / 5xx)
   const current = upstreamHealth.get(accountId);
+  // A transient failure concludes an owning probe; an unrelated 5xx must not
+  // consume someone else's live lease or drop hard-cooldown bookkeeping (#433).
+  const transientBase = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
   const stale = current?.lastFailureAt ? now - current.lastFailureAt > CODEX_FAILURE_WINDOW_MS : false;
   const hardCooldownUntil = getCodexAccountCooldownUntil(accountId, now) ?? undefined;
   // Soft avoid + affinity clears are part of failover. When threshold is 0, leave
@@ -524,6 +692,7 @@ export function recordCodexUpstreamOutcome(
     )
     : undefined;
   upstreamHealth.set(accountId, {
+    ...preservedCooldownFields(transientBase),
     consecutiveFailures,
     lastFailureStatus,
     lastFailureAt: now,

package/src/config.ts

@@ -7,7 +7,14 @@ import { comboConfigIssues } from "./combos/types";
 import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
 import { providerDestinationConfigError } from "./lib/destination-policy";
 import { openRouterRoutingConfigError } from "./providers/openrouter-routing";
-import { OPENAI_PROVIDER_TIER_VERSION, type OcxConfig } from "./types";
+import {
+  isWirePinnedModel,
+  MODEL_ADAPTER_OVERRIDE_ALLOWED,
+  OPENAI_PROVIDER_TIER_VERSION,
+  type OcxConfig,
+  type OcxProviderConfig,
+} from "./types";
+import { isCanonicalOpenAiForwardProvider } from "./providers/openai-tiers";
 
 let _atomicSeq = 0;
 
@@ -434,6 +441,41 @@ export function booleanRecordConfigError(value: unknown, field: string): string
   return null;
 }
 
+/**
+ * Validate a provider's per-model wire override map (#404).
+ *
+ * Rejects, rather than silently ignoring, configurations the resolver would refuse:
+ * a value outside the allowed wires, a model the upstream pins to one wire, and any
+ * override on a canonical forward provider (where switching wires would drop the
+ * caller's forwarded credential). Silently dropping them would leave the user
+ * believing an override is in effect.
+ */
+export function modelAdapterRecordConfigError(
+  value: unknown,
+  field: string,
+  providerName: string,
+  provider: { adapter?: unknown; authMode?: unknown; baseUrl?: unknown },
+): string | null {
+  if (value === undefined) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
+  const entries = Object.entries(value);
+  if (entries.length > 0 && isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig)) {
+    return `${field} is not supported on the canonical ChatGPT forward provider`;
+  }
+  for (const [key, entry] of entries) {
+    if (!key.trim()) return `${field} keys must be nonblank model ids`;
+    if (typeof entry !== "string" || !MODEL_ADAPTER_OVERRIDE_ALLOWED.has(entry)) {
+      return `${field}.${key} must be one of: ${[...MODEL_ADAPTER_OVERRIDE_ALLOWED].join(", ")}`;
+    }
+    if (isWirePinnedModel(providerName, key.trim())) {
+      return `${field}.${key} cannot be overridden: the upstream only speaks one wire for this model`;
+    }
+  }
+  return null;
+}
+
 const configSchema = z.object({
   port: z.number().int().min(0).max(65535).default(10100),
   providers: z.record(z.string(), providerConfigSchema),
@@ -511,6 +553,19 @@ const configSchema = z.object({
         message: headersError,
       });
     }
+    const modelAdaptersError = modelAdapterRecordConfigError(
+      (provider as { modelAdapters?: unknown }).modelAdapters,
+      "modelAdapters",
+      name,
+      provider,
+    );
+    if (modelAdaptersError) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["providers", name, "modelAdapters"],
+        message: modelAdaptersError,
+      });
+    }
     const maxInputError = positiveIntegerRecordConfigError(
       (provider as { modelMaxInputTokens?: unknown }).modelMaxInputTokens,
       "modelMaxInputTokens",

package/src/providers/openai-sidecar.ts

@@ -95,7 +95,14 @@ export async function resolveFirstUsableOpenAiSidecar(
       authContext,
       headers: headersForCodexAuthContext(incomingHeaders, authContext),
       ...(authContext.kind === "pool" || authContext.kind === "main-pool"
-        ? { recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(config, authContext.accountId, outcome) }
+        ? {
+          recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
+            config,
+            authContext.accountId,
+            outcome,
+            { probeLeaseId: authContext.probeLeaseId },
+          ),
+        }
         : {}),
     };
   }

package/src/providers/openai-tiers.ts

@@ -35,6 +35,24 @@ export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): b
     && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
 }
 
+const OPENAI_API_BASE_URL = "https://api.openai.com/v1";
+
+/**
+ * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
+ * backend can, and so can the official OpenAI API — but an arbitrary gateway that
+ * merely speaks the Responses wire cannot, and calling it there fails compaction
+ * with an unhelpful error instead of falling back to a routed summary (#422).
+ */
+export function supportsNativeResponsesCompactEndpoint(
+  providerName: string,
+  provider: OcxProviderConfig,
+): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return providerName === OPENAI_API_PROVIDER_ID
+    && provider.adapter === "openai-responses"
+    && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
+}
+
 export interface OpenAiTierMigrationProjection {
   config: OcxConfig;
   changed: boolean;

package/src/server/adapter-resolve.ts

@@ -7,18 +7,32 @@ import { createMimoFreeAdapter } from "../adapters/mimo-free";
 import { createOpenAIChatAdapter } from "../adapters/openai-chat";
 import { createResponsesPassthroughAdapter } from "../adapters/openai-responses";
 import type { OcxProviderConfig } from "../types";
+import { isWirePinnedModel, MODEL_ADAPTER_OVERRIDE_ALLOWED, pinnedWireAdapter } from "../types";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
 
-/** Providers whose listed model ids must be driven over the Anthropic wire even if the provider's
- *  configured adapter is something else (the upstream only speaks Anthropic for these models). */
-const ANTHROPIC_WIRE_MODELS: Record<string, Set<string>> = {
-  "opencode-go": new Set(["minimax-m2.5", "minimax-m2.7", "minimax-m3"]),
-};
-
-/** Return a provider config whose adapter is forced to "anthropic" when the model id is wire-pinned. */
+/**
+ * Resolve the wire a single model should use: a hard pin first, then a configured
+ * per-model override, then the provider's own adapter.
+ *
+ * Safe to call more than once on its own output — the pin check does not look at the
+ * current adapter, so a second pass cannot let an override displace a pin.
+ */
 export function resolveWireProtocolOverride(providerName: string, modelId: string, providerConfig: OcxProviderConfig): OcxProviderConfig {
-  const overrideSet = ANTHROPIC_WIRE_MODELS[providerName];
-  if (overrideSet?.has(modelId) && providerConfig.adapter !== "anthropic") {
-    return { ...providerConfig, adapter: "anthropic" };
+  const pinned = pinnedWireAdapter(providerName, modelId);
+  if (pinned && providerConfig.adapter !== pinned) {
+    return { ...providerConfig, adapter: pinned };
+  }
+  // Re-check the allow-list here, not just in the config validator: the file may have
+  // been hand-edited, or written by a build that allowed more values.
+  const requested = providerConfig.modelAdapters?.[modelId];
+  if (requested
+    && MODEL_ADAPTER_OVERRIDE_ALLOWED.has(requested)
+    && requested !== providerConfig.adapter
+    && !isWirePinnedModel(providerName, modelId)
+    // A forward provider hands the caller's own credential upstream; the chat adapter
+    // only ever sends provider.apiKey, so switching wires here would drop the auth.
+    && !isCanonicalOpenAiForwardProvider(providerConfig)) {
+    return { ...providerConfig, adapter: requested };
   }
   return providerConfig;
 }

package/src/server/auth-cors.ts

@@ -2,6 +2,7 @@ import { timingSafeEqual } from "node:crypto";
 import { formatErrorResponse } from "../bridge";
 import {
   booleanRecordConfigError,
+  modelAdapterRecordConfigError,
   codexAutoStartEnabled,
   positiveIntegerConfigError,
   positiveIntegerRecordConfigError,
@@ -234,6 +235,8 @@ export function providerManagementConfigError(name: unknown, provider: unknown):
   if (maxInputError) return `provider ${name} ${maxInputError}`;
   const reasoningSummariesError = booleanRecordConfigError(raw.modelSupportsReasoningSummaries, "modelSupportsReasoningSummaries");
   if (reasoningSummariesError) return `provider ${name} ${reasoningSummariesError}`;
+  const modelAdaptersError = modelAdapterRecordConfigError(raw.modelAdapters, "modelAdapters", name, typed);
+  if (modelAdaptersError) return `provider ${name} ${modelAdaptersError}`;
   const defaultMaxOutputError = positiveIntegerConfigError(raw.defaultMaxOutputTokens, "defaultMaxOutputTokens");
   if (defaultMaxOutputError) return `provider ${name} ${defaultMaxOutputError}`;
   const maxOutputError = positiveIntegerRecordConfigError(raw.modelMaxOutputTokens, "modelMaxOutputTokens");

package/src/server/chat-completions.ts

@@ -16,6 +16,7 @@ import {
 } from "../chat/outbound";
 import { estimateTokens } from "../lib/token-estimate";
 import { routeModel } from "../router";
+import { resolveWireProtocolOverride } from "./adapter-resolve";
 import type { OcxConfig } from "../types";
 import { readJsonRequestBody } from "./request-decompress";
 import {
@@ -68,6 +69,9 @@ export async function handleChatCompletions(
   let directRoute = false;
   try {
     const route = routeModel(config, internalBody.model as string);
+    // 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);
     logCtx.model = route.modelId;
     logCtx.providerAdapter = route.provider.adapter;
     logCtx.requestedModel = requestedModel;

package/src/server/claude-messages.ts

@@ -23,6 +23,7 @@ import {
 import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { estimateTokens } from "../lib/token-estimate";
 import { routeModel } from "../router";
+import { resolveWireProtocolOverride } from "./adapter-resolve";
 import type { OcxConfig } from "../types";
 import { readJsonRequestBody } from "./request-decompress";
 import { addFinalRequestLog, httpStatusForTerminalStatus, recordFirstOutput, type RequestLogContext, type RequestLogEntry } from "./request-log";
@@ -570,6 +571,9 @@ export async function handleClaudeMessages(
   let nativeRoute = false;
   try {
     const route = routeModel(config, internalBody.model as string);
+    // Settle the wire once so the sampling decision below reads the effective
+    // adapter rather than the provider-wide default (#404).
+    route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider);
     if (route.provider.adapter === "openai-responses") {
       nativeRoute = true;
       delete internalBody.max_output_tokens;

package/src/server/index.ts

@@ -122,7 +122,7 @@ import { handleChatCompletions } from "./chat-completions";
 import { anthropicErrorResponse } from "../claude/outbound";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
 import { handleImages } from "./images";
-import { handleLive, parseLiveSidebandTarget, resolveLiveSidebandUpgrade } from "./live";
+import { handleLive, logLiveSidebandFrame, parseLiveSidebandTarget, resolveLiveSidebandUpgrade } from "./live";
 import { handleSearch } from "./search";
 import { fetchAllModels, handleManagementAPI, VERSION } from "./management-api";
 
@@ -185,6 +185,7 @@ function attachLiveSidebandUpstream(ws: ServerWebSocket<WsData>): void {
   });
   upstream.addEventListener("message", (event) => {
     try {
+      logLiveSidebandFrame("u2c", event.data);
       if (typeof event.data === "string") ws.send(event.data);
       else if (event.data instanceof ArrayBuffer) ws.send(event.data);
       else if (ArrayBuffer.isView(event.data)) {
@@ -679,6 +680,7 @@ export function startServer(port?: number) {
       },
       message(ws: ServerWebSocket<WsData>, raw: string | Buffer) {
         if (ws.data.kind === "live-sideband") {
+          logLiveSidebandFrame("c2u", raw);
           const upstream = ws.data.liveUpstream;
           if (!upstream || upstream.readyState === WebSocket.CONNECTING || !ws.data.liveOpened) {
             const pending = ws.data.livePending ?? (ws.data.livePending = []);

package/src/server/live.ts

@@ -20,6 +20,7 @@
  * - `GET /v1/realtime/calls/{callId}` — path-form join
  * - `GET /v1/realtime?call_id=` — Realtime v1/v2 join
  */
+import { appendFileSync } from "node:fs";
 import { formatErrorResponse } from "../bridge";
 import {
   CodexAccountCooldownError,
@@ -69,6 +70,61 @@ export const LIVE_CLIENT_PROTOCOL_HEADERS = [
   "x-oai-attestation",
 ] as const;
 
+/**
+ * Env-gated sideband frame forensics (diagnostic for multibyte transcript corruption).
+ *
+ * When `OCX_LIVE_FRAME_LOG` is set to a file path, every relayed sideband frame appends one
+ * JSONL record: direction, frame kind, byte length, and whether the payload contains U+FFFD.
+ * Privacy: full frame payloads are never written — only when U+FFFD is present, a short
+ * excerpt around the first replacement character is included so the corruption point can be
+ * attributed (upstream vs relay vs client). Disabled entirely when the env var is unset.
+ */
+export const LIVE_FRAME_LOG_ENV = "OCX_LIVE_FRAME_LOG";
+const LIVE_FRAME_LOG_CONTEXT_CHARS = 24;
+
+function fffdContext(text: string): string | undefined {
+  const idx = text.indexOf("\uFFFD");
+  if (idx < 0) return undefined;
+  const start = Math.max(0, idx - LIVE_FRAME_LOG_CONTEXT_CHARS);
+  const end = Math.min(text.length, idx + LIVE_FRAME_LOG_CONTEXT_CHARS);
+  return text.slice(start, end);
+}
+
+export function logLiveSidebandFrame(dir: "c2u" | "u2c", data: unknown): void {
+  const logPath = process.env[LIVE_FRAME_LOG_ENV];
+  if (!logPath) return;
+  try {
+    let kind: "text" | "binary" = "binary";
+    let bytes = 0;
+    let context: string | undefined;
+    if (typeof data === "string") {
+      kind = "text";
+      bytes = Buffer.byteLength(data);
+      context = fffdContext(data);
+    } else if (data instanceof ArrayBuffer) {
+      bytes = data.byteLength;
+      context = fffdContext(new TextDecoder().decode(new Uint8Array(data)));
+    } else if (ArrayBuffer.isView(data)) {
+      const view = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      bytes = data.byteLength;
+      context = fffdContext(new TextDecoder().decode(view));
+    } else {
+      return;
+    }
+    const record = {
+      ts: new Date().toISOString(),
+      dir,
+      kind,
+      bytes,
+      fffd: context !== undefined,
+      ...(context !== undefined ? { context } : {}),
+    };
+    appendFileSync(logPath, `${JSON.stringify(record)}\n`);
+  } catch {
+    // Frame forensics must never break the relay.
+  }
+}
+
 function clientProtocolHeaders(reqHeaders: Headers): Record<string, string> {
   const out: Record<string, string> = {};
   for (const name of LIVE_CLIENT_PROTOCOL_HEADERS) {

package/src/server/memory-watchdog.ts

@@ -39,7 +39,7 @@ const DEFAULT_INTERVAL_MS = 60_000;
 const DEFAULT_WARN_THRESHOLD_BYTES = 4 * 1024 ** 3; // 4 GiB
 const DEFAULT_RING_SIZE = 360; // ≈6h at 60s
 const WARN_INTERVAL_MS = 30 * 60_000;
-const DOCS_URL = "https://lidge-jun.github.io/opencodex/troubleshooting/windows-memory/";
+const DOCS_URL = "https://opencodex.me/troubleshooting/windows-memory/";
 
 let active: MemoryWatchdog | null = null;