@bitkyc08/opencodex 2.56.0 → 2.57.0

package/src/server/index/live-sideband.ts

@@ -11,7 +11,13 @@ import {
   type WsData,
 } from "../ws-bridge";
 import type { Server, ServerWebSocket } from "bun";
-import { handleLive, logLiveSidebandFrame, parseLiveSidebandTarget, resolveLiveSidebandUpgrade } from "../live";
+import {
+  handleLive,
+  logLiveSidebandFrame,
+  logLiveSidebandStage,
+  parseLiveSidebandTarget,
+  resolveLiveSidebandUpgrade,
+} from "../live";
 import { RESPONSE_TTL_MS } from "../../responses/state";
 
 export const MAX_WS_FRAME_BYTES = 50 * 1024 * 1024;
@@ -125,8 +131,33 @@ export function sendUpstreamFrame(upstream: WebSocket, frame: string | Buffer):
   upstream.send(Uint8Array.from(frame));
 }
 
+/**
+ * Translate the close a downstream client sent into one the upstream socket can carry.
+ *
+ * The client's code is the only evidence of WHY the call ended, and the upstream needs it:
+ * a user hanging up (1001) and a protocol fault (1002/1011) are different events on the
+ * account, and collapsing both into a bare 1000 erases that at the proxy. Two bounds make
+ * the relay safe anyway. Codes a WebSocket endpoint may never send — 1005 and 1006 are
+ * status codes the local runtime synthesizes for "no status" and "abnormal", 1015 is
+ * TLS-reserved, and anything outside the registered and private ranges is undefined — become
+ * 1000, because `upstream.close` throws on them and a throw here would strand the upstream
+ * socket. The reason is truncated to the 123-byte control-frame payload limit by bytes, not
+ * characters, so a multibyte reason cannot overrun the frame.
+ */
+export function clientCloseForUpstream(code: number, reason?: string): { code: number; reason: string } {
+  const sendable = code === 1000
+    || code === 1001
+    || code === 1003
+    || (code >= 1007 && code <= 1011)
+    || (code >= 3000 && code <= 4999);
+  let text = reason ?? "";
+  while (Buffer.byteLength(text) > 123) text = text.slice(0, -1);
+  return { code: sendable ? code : 1000, reason: text };
+}
+
 function finalizeLiveSideband(ws: ServerWebSocket<WsData>, upstream?: WebSocket): void {
   if (upstream && ws.data.liveUpstream !== upstream) return;
+  logLiveSidebandStage("relay-closed");
   if (ws.data.liveCloseFallback !== undefined) {
     clearTimeout(ws.data.liveCloseFallback);
     ws.data.liveCloseFallback = undefined;
@@ -281,6 +312,7 @@ export function openLiveSidebandUpstream(
     try {
       socket = createWebSocket(url, headers);
     } catch {
+      logLiveSidebandStage("upstream-failed", { status: 502, code: "upstream_error" });
       resolve({ ok: false, status: 502, code: "upstream_error", message: "voice upstream connect failed" });
       return;
     }
@@ -297,6 +329,8 @@ export function openLiveSidebandUpstream(
       settled = true;
       clearTimeout(timer);
       removeAbortListener();
+      if (result.ok) logLiveSidebandStage("upstream-open");
+      else logLiveSidebandStage("upstream-failed", { status: result.status, code: result.code });
       resolve(result);
     };
     const timer = setTimeout(() => {
@@ -505,6 +539,7 @@ export function attachLiveSidebandUpstream(
     // session, not the connect phase.
     if (ws.data.liveConnectTimer !== undefined) clearTimeout(ws.data.liveConnectTimer);
     ws.data.liveConnectTimer = undefined;
+    logLiveSidebandStage("relay-attached");
     for (const frame of takeover.frames) {
       try {
         // Mirror the live message listener exactly: same ceiling, same diagnostic
@@ -527,6 +562,7 @@ export function attachLiveSidebandUpstream(
     ws.data.liveOpened = true;
     if (ws.data.liveConnectTimer !== undefined) clearTimeout(ws.data.liveConnectTimer);
     ws.data.liveConnectTimer = undefined;
+    logLiveSidebandStage("relay-attached");
     // An accepted transport alone does not prove inference/quota recovery.
     // Keep healthy closes neutral; explicit transport failures are recorded below.
     const pending = ws.data.livePending ?? [];

package/src/server/index/websocket-handler.ts

@@ -4,6 +4,7 @@ import {
   MAX_WS_FRAME_BYTES,
   WEBSOCKET_IDLE_TIMEOUT_SECONDS,
   attachLiveSidebandUpstream,
+  clientCloseForUpstream,
   closeLiveSideband,
   closeLiveSidebandBeforeUpgrade,
   enqueueLiveSidebandPendingFrame,
@@ -317,13 +318,16 @@ export function createWebsocketHandler(ctx: ServeOptionsContext) {
           }
         })();
       },
-      close(ws: ServerWebSocket<WsData>) {
+      close(ws: ServerWebSocket<WsData>, code: number, reason: string) {
         if (ws.data.kind === "remote-workspace-agent") {
           ws.data.remoteWorkspaceClose?.();
           return;
         }
         if (ws.data.kind === "live-sideband") {
-          closeLiveSideband(ws);
+          // Carry the client's own close through to the upstream instead of reporting every
+          // hang-up as a plain 1000.
+          const forwarded = clientCloseForUpstream(code, reason);
+          closeLiveSideband(ws, forwarded.code, forwarded.reason);
           return;
         }
         unregisterCodexWebSocket(ws);

package/src/server/index.ts

@@ -268,11 +268,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server<W
     startupOwnershipStatePaths,
     startupWindowsTaskListingCache,
   );
-  // Startup cache invalidation is best-effort and must never block the server from
-  // serving. It now takes K so it cannot race a convergence commit. Use the home
-  // paired with the ownership inspection; re-reading ambient CODEX_HOME here could
-  // invalidate a different installation after an environment or mount change.
-  if (startupCacheOwnership.ownership === "owned" && startupOwnershipHomes !== null) {
+  // Startup cache invalidation is best-effort and applies only when startup sync is enabled.
+  // Check OFF before taking K: on Windows K resolves SID + LocalAppData through PowerShell,
+  // and run 35093667426 exceeded healthy controls by 33.8 s against that 30 s child budget.
+  // The permit callback still re-reads intent under K to close a concurrent disable race.
+  if (shouldSyncCodexOnStart(config) && startupCacheOwnership.ownership === "owned" && startupOwnershipHomes !== null) {
     try {
       const startupCodexHome = startupOwnershipHomes.codexHome;
       // #1046: record whether this actually rewrote the cache. `handleStart` ORs this

package/src/server/inspection-tee.ts

@@ -0,0 +1,107 @@
+/** Read-ahead allowance, not a lifetime limit on SSE inspection or delivery. */
+export const MAX_INSPECTION_READ_AHEAD_BYTES = 32 * 1024 * 1024;
+
+export interface InspectionTeeOptions {
+  /** Release pacing so the inspection owner's existing bounded drain can run. */
+  clientGoneSignal?: AbortSignal;
+  /** Internal test seam; callers must not take this value from upstream data. */
+  maxReadAheadBytes?: number;
+}
+
+/**
+ * Keep native tee cancellation semantics while pacing the inspection branch.
+ *
+ * Inspection may lead raw client consumption by the allowance plus one source
+ * chunk (and native tee prefetch). It never stops merely because the whole turn
+ * crossed that size: terminal, usage and continuation observers retain ownership.
+ * Count raw client bytes BEFORE rewrites, which may shrink, drop or expand them.
+ * Push sources still need their own producer-side bound; this is not an RSS cap.
+ */
+export function teeWithBoundedInspection(
+  source: ReadableStream<Uint8Array>,
+  options: InspectionTeeOptions = {},
+): [ReadableStream<Uint8Array>, ReadableStream<Uint8Array>] {
+  const limit = options.maxReadAheadBytes ?? MAX_INSPECTION_READ_AHEAD_BYTES;
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new RangeError("Inspection read-ahead limit must be a positive safe integer");
+  }
+  const [client, inspection] = source.tee();
+  let leadBytes = 0;
+  let pacingReleased = false;
+  let credit: Promise<void> | undefined;
+  let wake: (() => void) | undefined;
+
+  const wakeReader = () => {
+    const resolve = wake;
+    wake = undefined;
+    credit = undefined;
+    resolve?.();
+  };
+  const releasePacing = () => {
+    pacingReleased = true;
+    wakeReader();
+  };
+  const signal = options.clientGoneSignal;
+  if (signal?.aborted) releasePacing();
+  else signal?.addEventListener("abort", releasePacing, { once: true });
+
+  const wrap = (
+    body: ReadableStream<Uint8Array>,
+    isClient: boolean,
+  ): ReadableStream<Uint8Array> => {
+    const reader = body.getReader();
+    let ended = false;
+    // An upstream error must wake an inspector waiting for credit, not remain
+    // hidden until the client happens to issue another read. One observer per
+    // reader, not a permanent Promise.race reaction attached on every chunk.
+    void reader.closed.catch(releasePacing);
+    const releaseLock = () => {
+      try { reader.releaseLock(); } catch { /* a pending read owns the lock */ }
+    };
+    const finish = () => {
+      ended = true;
+      releasePacing();
+      if (!isClient) signal?.removeEventListener("abort", releasePacing);
+    };
+    return new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        if (ended) return;
+        if (!isClient && !pacingReleased && leadBytes >= limit) {
+          credit ??= new Promise<void>(resolve => { wake = resolve; });
+          await credit;
+          if (ended) return;
+        }
+        try {
+          const result = await reader.read();
+          if (ended) return;
+          if (result.done) {
+            finish();
+            releaseLock();
+            controller.close();
+            return;
+          }
+          if (isClient) {
+            leadBytes -= result.value.byteLength;
+            if (leadBytes < limit) wakeReader();
+          } else {
+            leadBytes += result.value.byteLength;
+          }
+          controller.enqueue(result.value);
+        } catch (error) {
+          if (ended) return;
+          finish();
+          releaseLock();
+          controller.error(error);
+        }
+      },
+      cancel(reason) {
+        finish();
+        // Awaiting one tee branch's cancellation waits for the sibling. The
+        // owner must be free to finish cleanup and cancel/read that sibling.
+        void reader.cancel(reason).catch(() => undefined);
+        releaseLock();
+      },
+    }, { highWaterMark: 0 });
+  };
+  return [wrap(client, true), wrap(inspection, false)];
+}

package/src/server/live.ts

@@ -72,7 +72,17 @@ export const LIVE_SIDEBAND_API_ROOT = "https://api.openai.com/v1";
  * Client protocol headers relayed verbatim to the upstream on call-create and sideband upgrade.
  * `openai-alpha: quicksilver=v2` carries the Frameless protocol negotiation — without it the
  * ChatGPT backend validates the type-less Frameless session as v1 quicksilver and 400s
- * (openai/codex `realtime_request_headers`, core/src/realtime_conversation.rs). Auth headers
+ * (openai/codex `realtime_request_headers`, core/src/realtime_conversation.rs).
+ *
+ * `x-codex-turn-metadata` is on the same list upstream builds for the sideband upgrade and was
+ * missing here, so every realtime turn reached the model with metadata the client had attached
+ * and this proxy silently dropped. The Responses passthrough already forwards it
+ * (`src/adapters/openai-responses/passthrough.ts`); the sideband goes to the same realtime
+ * upstream the caller was addressing, so there is nothing to scope it away from. That is not
+ * true of the images sidecar, which strips it deliberately and keeps doing so.
+ *
+ * Every name here is relayed only when the caller sent it. Nothing on this list is invented,
+ * which is what keeps a caller that omits one byte-identical upstream. Auth headers
  * (`authorization`, `chatgpt-account-id`) stay proxy-owned and are never taken from this list.
  */
 export const LIVE_CLIENT_PROTOCOL_HEADERS = [
@@ -82,6 +92,7 @@ export const LIVE_CLIENT_PROTOCOL_HEADERS = [
   "thread-id",
   "originator",
   "x-oai-attestation",
+  "x-codex-turn-metadata",
 ] as const;
 
 /**
@@ -128,6 +139,40 @@ export function logLiveSidebandFrame(dir: "c2u" | "u2c", data: unknown): void {
   }
 }
 
+/**
+ * Sideband lifecycle stages, recorded in the same JSONL as the frame records.
+ *
+ * Frame forensics alone cannot separate the three realtime-voice failures reported in #4721.
+ * A join that never reached this proxy, a join whose upstream handshake was refused, and a
+ * relay that opened and then carried nothing all leave the same empty file, which is why the
+ * original report could only say "no frame log". One record per stage makes them distinct:
+ * no record at all means the client never dialed the proxy, `upstream-failed` carries the
+ * status the client was handed, and `relay-attached` with no following frame record means the
+ * transport is live and the silence is upstream of it.
+ */
+export type LiveSidebandStage = "upstream-open" | "upstream-failed" | "relay-attached" | "relay-closed";
+
+/**
+ * Append one lifecycle record. Same privacy rule as the frame records and for the same reason:
+ * no URL, no call id, no header, no frame content — only the stage and, on failure, the status
+ * and error code this proxy synthesized itself.
+ */
+export function logLiveSidebandStage(
+  stage: LiveSidebandStage,
+  detail?: { status?: number; code?: string },
+): void {
+  const logPath = process.env[LIVE_FRAME_LOG_ENV];
+  if (!logPath) return;
+  try {
+    const record: Record<string, unknown> = { ts: new Date().toISOString(), stage };
+    if (detail?.status !== undefined) record.status = detail.status;
+    if (detail?.code !== undefined) record.code = detail.code;
+    appendFileSync(logPath, JSON.stringify(record) + "\n");
+  } catch {
+    // Diagnostics 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/management/combo-routes.ts

@@ -80,17 +80,20 @@ function sparseComboConfig<T extends {
   waitForCooldownMs?: number;
   imageInput?: "auto" | "disabled";
   reasoningEffortMode?: "strict" | "adaptive";
-}>(combo: T): Omit<T, "cooldownMs" | "waitForCooldownMs" | "imageInput" | "reasoningEffortMode"> & {
+  defaultEffortMode?: "fallback" | "force";
+}>(combo: T): Omit<T, "cooldownMs" | "waitForCooldownMs" | "imageInput" | "reasoningEffortMode" | "defaultEffortMode"> & {
   cooldownMs?: number;
   waitForCooldownMs?: number;
   imageInput?: "disabled";
   reasoningEffortMode?: "adaptive";
+  defaultEffortMode?: "force";
 } {
   const {
     cooldownMs,
     waitForCooldownMs,
     imageInput,
     reasoningEffortMode,
+    defaultEffortMode,
     ...rest
   } = combo;
   return {
@@ -101,6 +104,7 @@ function sparseComboConfig<T extends {
       : {}),
     ...(imageInput === "disabled" ? { imageInput: "disabled" as const } : {}),
     ...(reasoningEffortMode === "adaptive" ? { reasoningEffortMode: "adaptive" as const } : {}),
+    ...(defaultEffortMode === "force" ? { defaultEffortMode: "force" as const } : {}),
   };
 }
 
@@ -170,6 +174,11 @@ export async function handleComboRoutes(ctx: ManagementContext): Promise<Respons
       ...(!Object.hasOwn(requestedCombo, "waitForCooldownMs") && previous?.waitForCooldownMs !== undefined
         ? { waitForCooldownMs: previous.waitForCooldownMs }
         : {}),
+      // The dashboard does not expose this advanced CLI/API policy. Preserve it when
+      // a GUI round-trip omits the field instead of silently downgrading to fallback.
+      ...(!Object.hasOwn(requestedCombo, "defaultEffortMode") && previous?.defaultEffortMode !== undefined
+        ? { defaultEffortMode: previous.defaultEffortMode }
+        : {}),
     };
     const error = comboConfigError(id, effectiveCombo, config.providers, {
       requireEnabledTarget: true,

package/src/server/relay-eager.ts

@@ -466,6 +466,8 @@ export function relaySseEagerBounded(
         else hooks.onSynthetic(syntheticKind, syntheticReason);
       }
       if (cancelled && !hooks.sawTerminal()) {
+        // Finalize transport telemetry before the cancellation hook persists its usage row.
+        upstream.abort();
         hooks.onClientCancel();
       }
       if (cancelled || upstream.signal.aborted || syntheticKind === "failed" || deliveryFallbackSent) {

package/src/server/relay.ts

@@ -26,6 +26,7 @@ import {
   MAX_CLIENT_SSE_FRAME_BYTES,
 } from "./sse-frame-buffer";
 import { replaceSseDataPayload } from "./sse-payload-rewrite";
+import { createBoundedResponseLogBody } from "./response-log-body";
 
 const nativePassthroughSseResponses = new WeakSet<Response>();
 const eagerRelaySseResponses = new WeakSet<Response>();
@@ -718,25 +719,16 @@ export function responseWithDeferredRequestLog(
   }
   if (!response.body || !contentType.includes("text/event-stream")) {
     if (response.body && (contentType.includes("application/json") || response.status >= 400)) {
-      const finalizeJsonLog = async () => {
-        const text = await response.text();
-        // Non-JSON error bodies: inspect/log only a bounded prefix (the stored
-        // upstreamError is 500 chars anyway); the FULL text is still forwarded to the
-        // client below, unchanged. JSON bodies keep full inspection (usage parsing).
-        const isJson = contentType.includes("application/json");
-        inspectResponseLogJson(logCtx, isJson ? text : text.slice(0, 8192));
-        addFinalRequestLog(requestId, start, logCtx, response.status, { closeReason: "non_stream" }, addLog);
-        return text;
-      };
-      const body = new ReadableStream<Uint8Array>({
-        async start(controller) {
-          try {
-            controller.enqueue(new TextEncoder().encode(await finalizeJsonLog()));
-            controller.close();
-          } catch (err) {
-            addFinalRequestLog(requestId, start, logCtx, 502, { closeReason: "non_stream" }, addLog);
-            try { controller.error(err); } catch { /* already torn down */ }
-          }
+      const body = createBoundedResponseLogBody(response.body, {
+        json: contentType.includes("application/json"),
+        inspect: text => inspectResponseLogJson(logCtx, text),
+        finalize: reason => {
+          // Preserve wire status; request history follows the adjacent SSE
+          // convention for a client cancellation or upstream read failure.
+          const status = reason === "cancel" ? 499 : reason === "read_error" ? 502 : response.status;
+          addFinalRequestLog(requestId, start, logCtx, status, {
+            closeReason: reason === "cancel" ? "client_cancel" : "non_stream",
+          }, addLog);
         },
       });
       return new Response(body, {
@@ -1338,6 +1330,9 @@ function startBoundedInspectionPump(options: InspectionPumpOptions): void {
     try {
       for (;;) {
         const { done, value } = await reader.read();
+        // Hard cancellation settles a pending read as EOF. Do not flush a
+        // partial terminal after the owner already finalized cancellation.
+        if (cancelled) break;
         if (clientGoneSignal?.aborted) markClientGone();
         if (drainStopped) {
           // stopDrain() cancelled the reader; the settled read is the wake-up.

package/src/server/request-log.ts

@@ -1,5 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
+import { stampApiKeyAccountLabel, usesApiKeyAccount } from "../providers/label";
+import { KEY_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
+import { readBoundedResponseBody } from "../lib/bounded-body";
 import type { ResponsesTerminalStatus } from "../bridge";
 import {
   classifyError,
@@ -17,6 +20,7 @@ import { readCodexCatalogPath } from "../codex/catalog";
 import type { AttemptTierOutcome, OcxProviderConfig, OcxUsage } from "../types";
 import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
 import type { AdapterRequest } from "../adapters/base";
+import type { RequestSpendSettlement } from "./responses/request-spend";
 import type { AdapterTierMetadata } from "../providers/fastwire";
 import { redactSecretString, sanitizeLogMetadataString } from "../lib/redact";
 import {
@@ -138,6 +142,15 @@ export interface RequestLogContext {
   preserveResolvedModelFromRoute?: boolean;
   usage?: OcxUsage;
   usageLogInputTokens?: number;
+  /**
+   * The output ceiling this request may actually spend, for the durable spend reservation
+   * (#4707). Captured from the caller's `max_output_tokens`; absent when the caller omitted it
+   * and the adapter's own provider/model default decides, in which case only the input estimate
+   * is reserved up front and settlement corrects it.
+   */
+  spendOutputCeilingTokens?: number;
+  /** Settles this request's durable spend entries from `addFinalRequestLog`. */
+  spendTracker?: RequestSpendSettlement;
   attempts?: PersistedUsageAttempt[];
   /** Internal mutable final attempt; omitted from RequestLogEntry/JSONL. */
   activeAttempt?: PersistedUsageAttempt;
@@ -772,8 +785,10 @@ export function applyResponseLogMetadata(logCtx: RequestLogContext, payload: unk
   }
   const usage = usageFromResponsesPayload((source as { usage?: unknown }).usage);
   if (usage && !logCtx.usageFromBridge) {
-    logCtx.usage = usage;
-    if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
+    if (!recordKeyWireAttemptUsage(logCtx, usage)) {
+      logCtx.usage = usage;
+      if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
+    }
     // Counts taken off a wire, not reported raw. The zero-default token-detail objects strict
     // clients require are indistinguishable here from a measured zero, so the cache detail these
     // counts carry is recorded as synthesized rather than as an observed miss.
@@ -1206,6 +1221,31 @@ export function recordNoAccountAffinityFailure(
   logCtx.errorCode ??= "codex_no_account";
   return resolved;
 }
+// Attempt identity can change in place while a combo parent retains an older context copy.
+// These objects own their usage even after a rotation to an unknown key identity.
+const keyUsageOwners = new WeakSet<PersistedUsageAttempt>();
+const keyWireUsageBaselines = new WeakMap<PersistedUsageAttempt, OcxUsage | undefined>();
+
+function cloneKeyUsage(usage: OcxUsage | undefined): OcxUsage | undefined {
+  return usage ? { ...usage } : undefined;
+}
+
+/** Replace this physical send's wire snapshot against the pre-send baseline; repeats do not sum. */
+export function recordKeyWireAttemptUsage(logCtx: RequestLogContext, usage: OcxUsage | undefined): boolean {
+  if (!usage) return false;
+  const attempt = logCtx.activeAttempt;
+  if (!attempt || !keyUsageOwners.has(attempt) || !keyWireUsageBaselines.has(attempt)) return false;
+  const baseline = keyWireUsageBaselines.get(attempt);
+  const current = { ...usage };
+  attempt.usage = baseline
+    ? aggregateAttemptUsage([
+      { ...attempt, usage: baseline, usageStatus: baseline.estimated ? "estimated" : "reported" },
+      { ...attempt, usage: current, usageStatus: current.estimated ? "estimated" : "reported" },
+    ]).usage
+    : current;
+  logCtx.usage = attempt.usage;
+  return true;
+}
 
 export function addFinalRequestLog(
   requestId: string,
@@ -1237,13 +1277,19 @@ export function addFinalRequestLog(
       logCtx.activeAttempt,
       effectiveStatus,
       Date.now() - (logCtx.activeAttemptStartedAt ?? start),
-      logCtx.usage,
+      keyUsageOwners.has(logCtx.activeAttempt)
+        ? logCtx.activeAttempt.usage
+        : logCtx.usage,
     );
     // The final row and its active physical attempt describe the same terminal. Preserve the
     // semantic code on both so detailed attempt telemetry cannot regress to a generic status code.
     if (errorCode) logCtx.activeAttempt.errorCode = errorCode;
     else delete logCtx.activeAttempt.errorCode;
   }
+  // The one seam every request passes exactly once, whatever transport served it and however
+  // it ended. The terminal usage belongs to the last send that left; the ledger resolves every
+  // earlier send of this request as unresolved spend rather than handing its tokens back.
+  logCtx.spendTracker?.settle(logCtx.usage);
   const existing = finalizedUsage(
     logCtx.providerAdapter ?? logCtx.provider,
     logCtx.usage,
@@ -1528,6 +1574,84 @@ export function sealRequestAttemptIdentity(
   attempt.provider = provider;
   attempt.adapter = adapter;
   if (isCodexUsageAccountLogLabel(accountLogLabel)) attempt.accountLogLabel = accountLogLabel;
+  else delete attempt.accountLogLabel;
+}
+
+/** Preserve metered JSON failures before key recovery consumes/cancels their body. */
+export async function recordKeyAttemptFailure(logCtx: RequestLogContext, response: Response, signal?: AbortSignal): Promise<void> {
+  const attempt = logCtx.activeAttempt;
+  if (!attempt || !KEY_ACCOUNT_LOG_LABEL_RE.test(attempt.accountLogLabel ?? "")) return;
+  attempt.status = response.status;
+  const cancelOriginal = (): void => { try { void response.body?.cancel().catch(() => {}); } catch { /* closed */ } };
+  signal?.addEventListener("abort", cancelOriginal, { once: true });
+  try {
+    if (signal?.aborted) { cancelOriginal(); return; }
+    const body = await readBoundedResponseBody(response.clone(), { signal, totalTimeoutMs: 1000, inactivityTimeoutMs: 1000 });
+    if (body.truncated || body.oversized) return;
+    const value = JSON.parse(body.text);
+    const usage = usageFromResponsesPayload(value?.usage ?? value?.response?.usage);
+    if (usage) recordKeyWireAttemptUsage(logCtx, usage);
+  } catch { /* Absent/malformed usage remains unknown; recovery still owns the response. */ }
+  finally { signal?.removeEventListener("abort", cancelOriginal); }
+}
+
+/** Add raw per-response usage before a bridge combines multiple rounds for the client. */
+export function recordKeyAttemptUsage(logCtx: RequestLogContext, usage: OcxUsage | undefined): void {
+  const attempt = logCtx.activeAttempt;
+  if (!attempt || !usage) return;
+  attempt.usage = attempt.usage
+    ? aggregateAttemptUsage([{ ...attempt, usageStatus: attempt.usage.estimated ? "estimated" : "reported" },
+      { ...attempt, usage, usageStatus: usage.estimated ? "estimated" : "reported" }]).usage
+    : { ...usage };
+  logCtx.usage = attempt.usage;
+}
+
+/** A stable active object lets combo/stream callbacks keep pointing at the final attempt.
+ * Earlier key segments are immutable, flat snapshots inserted before that active object. */
+export function noteProviderAttemptSend(
+  logCtx: RequestLogContext,
+  providerName: string,
+  provider: OcxProviderConfig,
+  inputTokenEstimate: number | undefined,
+  recovery?: AttemptRecoveryKind,
+): void {
+  const attempt = logCtx.activeAttempt;
+  const previous = attempt?.accountLogLabel;
+  stampApiKeyAccountLabel(logCtx, providerName, provider);
+  const next = logCtx.accountLogLabel;
+  if (attempt && usesApiKeyAccount(provider)) keyUsageOwners.add(attempt);
+  if (attempt && attempt.sendCount > 0 && previous !== next
+    && (KEY_ACCOUNT_LOG_LABEL_RE.test(previous ?? "") || KEY_ACCOUNT_LOG_LABEL_RE.test(next ?? ""))) {
+    // An input estimate is not evidence that a failed send used that many tokens.
+    delete attempt.inputTokenEstimate;
+    finishRequestAttempt(attempt, attempt.status >= 100 ? attempt.status
+      : recovery === "key-401" ? 401 : recovery?.includes("429") ? 429 : 502,
+    Date.now() - (logCtx.activeAttemptStartedAt ?? Date.now()), attempt.usage);
+    const completed = { ...attempt, recoveryKinds: [...attempt.recoveryKinds],
+      ...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
+      ...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}) };
+    const attempts = logCtx.attempts ??= [attempt];
+    const index = attempts.indexOf(attempt);
+    if (index >= 0) attempts.splice(index, 0, completed);
+    else attempts.push(completed, attempt);
+    const fresh = beginRequestAttempt(completed.ordinal + 1, providerName, completed.model, completed.adapter);
+    // Effort/tier metadata describes the request and is captured before the physical send.
+    for (const key of ["requestedEffort", "effectiveEffort", "reasoningWireField", "reasoningWireValue", "tierOutcome"] as const) {
+      if (completed[key] !== undefined) Object.assign(fresh, { [key]: completed[key] });
+    }
+    for (const key of Object.keys(attempt)) delete (attempt as unknown as Record<string, unknown>)[key];
+    Object.assign(attempt, fresh);
+    delete logCtx.usage;
+    logCtx.activeAttemptStartedAt = Date.now();
+  }
+  if (attempt) {
+    sealRequestAttemptIdentity(attempt, logCtx.provider, attempt.adapter, next);
+    recordAttemptCredentialSource(attempt, providerName, provider, attempt.adapter);
+  }
+  noteAttemptSend(attempt, inputTokenEstimate, recovery);
+  if (attempt && keyUsageOwners.has(attempt)) {
+    keyWireUsageBaselines.set(attempt, cloneKeyUsage(attempt.usage));
+  }
 }
 
 /** Capture only the resolved upstream route; inbound auth and today's config cannot label old usage. */