@bitkyc08/opencodex 2.56.0 → 2.58.0

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/management/config-routes.ts

@@ -3,6 +3,11 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
 import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import {
+  applyCodexDesktopSwitches,
+  describeCodexDesktopSwitches,
+  type CodexDesktopSwitchApply,
+} from "../../codex/desktop-switches";
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
@@ -328,6 +333,11 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexDesktopAuthless: config.codexDesktopAuthless === true,
       // Absent keeps Design B remote compaction; true selects the dedicated provider identity.
       codexClientCompaction: config.codexClientCompaction === true,
+      codexDesktopSwitches: describeCodexDesktopSwitches(config, {
+        applied: false,
+        reason: "not_requested",
+        retryable: false,
+      }),
       startupHealth: await readStartupHealth(config),
       codexRuntime: {
         path: displayCodexRuntimePath(resolved.runtime.command),
@@ -597,15 +607,26 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       configureAppOwnedMemoryBudget(resolveAppOwnedMemoryBudgetBytes(body.appOwnedMemoryBudgetMb));
       enforceAppOwnedMemoryBudget();
     }
-    // Both Desktop compatibility switches change the injected config.toml shape, so converge now
-    // rather than waiting for the next start; the injector re-reads config and rewrites the form.
     const authlessIsEnabled = config.codexDesktopAuthless === true;
     const clientCompactionIsEnabled = config.codexClientCompaction === true;
-    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled
-      || authlessWasEnabled !== authlessIsEnabled
-      || clientCompactionWasEnabled !== clientCompactionIsEnabled
+    const desktopSwitchesChanged = authlessWasEnabled !== authlessIsEnabled
+      || clientCompactionWasEnabled !== clientCompactionIsEnabled;
+    // Catalog convergence is not config injection, and the comment that used to sit here said
+    // it was. `convergeCodexCatalog` rejects any scope but `catalog` and never reaches the
+    // injector, which is why flipping either switch left `config.toml` in its old shape until
+    // a separate `ocx sync` (#4809). Both halves are needed when a Desktop switch changes; a
+    // picker-only update still refreshes just the catalog.
+    const catalogRefresh = pickerWasEnabled !== pickerIsEnabled || desktopSwitchesChanged
       ? await convergeCodexCatalog()
       : undefined;
+    // Injection second, matching `syncModelsToCodex`: the injected `model_catalog_json` should
+    // point at a catalog that has already settled. And it runs here rather than inside the save
+    // because coordinated Codex writes acquire the Codex write lock N before the config mutation
+    // lock C — awaiting N while still holding C would invert that order.
+    const desktopSwitchApply: CodexDesktopSwitchApply = desktopSwitchesChanged
+      ? await applyCodexDesktopSwitches(config)
+      : { applied: false, reason: "not_requested", retryable: false };
+    const codexDesktopSwitches = describeCodexDesktopSwitches(config, desktopSwitchApply);
     const catalogRefreshPending = catalogRefresh
       ? catalogRefreshIsPending(catalogRefresh)
       : false;
@@ -622,6 +643,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       catalogRefreshPending,
       codexDesktopAuthless: authlessIsEnabled,
       codexClientCompaction: clientCompactionIsEnabled,
+      codexDesktopSwitches,
       codexMainAccountHardLock: config.codexMainAccountHardLock === true,
       mainAccountHardLock: getMainAccountHardLockStatus(config),
       startupHealth: await readStartupHealth(config),

package/src/server/models-capabilities.ts

@@ -10,6 +10,11 @@ import type { CursorEffortTable } from "../integrations/cursor-effort-table";
  * Completions, Responses and Anthropic Messages, streams, and accepts tool calls, so those are
  * constants; context length and vision come from catalog data when known and are omitted
  * otherwise, matching Cursor's optional-field schema.
+ *
+ * Top-level capacity metrics (`context_window`, `context_length`, `max_output_tokens`) are
+ * mirrored directly on each model row for external client discovery (e.g. pi-ai, DSH,
+ * LibreChat) that inspects flat properties rather than Cursor's nested `capabilities.*` shape.
+ * A row that gains a nested capacity value must gain the top-level mirror in the same change.
  */
 
 /**
@@ -132,6 +137,19 @@ export interface ModelCapabilityFields {
     supports_vision?: boolean;
     reasoning_effort?: string[];
   };
+  /**
+   * Mirrored top-level context window for external/legacy client discovery (e.g. pi-ai, DSH)
+   * that reads top-level context_window / context_length instead of nested capabilities.
+   */
+  context_window?: number;
+  /**
+   * Top-level context length alias matching capabilities.context_length for clients expecting context_length.
+   */
+  context_length?: number;
+  /**
+   * Mirrored top-level max output token limit for external/legacy client discovery.
+   */
+  max_output_tokens?: number;
   /**
    * Cursor reads the long-context threshold from `pricing.overrides[].min_prompt_tokens`. That
    * key sits outside its validated capability schema, so it is the one place a threshold can
@@ -153,6 +171,7 @@ export function modelCapabilityFields(input: ModelCapabilityInput): ModelCapabil
   const longContextLength = positiveInt(input.longContextWindow);
   const maxOutputTokens = positiveInt(input.maxOutputTokens);
   const hasLongTier = contextLength !== undefined && longContextLength !== undefined && longContextLength > contextLength;
+  const effectiveContextLength = hasLongTier ? longContextLength : contextLength;
   const modalities = Array.isArray(input.inputModalities)
     ? input.inputModalities.filter(modality => typeof modality === "string" && modality.length > 0)
     : undefined;
@@ -160,9 +179,7 @@ export function modelCapabilityFields(input: ModelCapabilityInput): ModelCapabil
   return {
     api_types: [...OPENCODEX_MODEL_API_TYPES],
     capabilities: {
-      ...(hasLongTier
-        ? { context_length: longContextLength }
-        : contextLength !== undefined ? { context_length: contextLength } : {}),
+      ...(effectiveContextLength !== undefined ? { context_length: effectiveContextLength } : {}),
       ...(maxOutputTokens !== undefined ? { max_output_tokens: maxOutputTokens } : {}),
       // Once a gateway advertises api_types, Cursor keeps only rows whose output_modalities
       // include "text"; omitting the key drops the row from the extended catalog.
@@ -174,6 +191,10 @@ export function modelCapabilityFields(input: ModelCapabilityInput): ModelCapabil
       ...(supportsVision !== undefined ? { supports_vision: supportsVision } : {}),
       ...(efforts.length > 0 ? { reasoning_effort: [...efforts] } : {}),
     },
+    ...(effectiveContextLength !== undefined
+      ? { context_window: effectiveContextLength, context_length: effectiveContextLength }
+      : {}),
+    ...(maxOutputTokens !== undefined ? { max_output_tokens: maxOutputTokens } : {}),
     ...(hasLongTier ? { pricing: { overrides: [{ min_prompt_tokens: contextLength }] } } : {}),
   };
 }

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. */