@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/server/relay-eager.ts

@@ -30,6 +30,7 @@ import {
   createSseTerminalOutputBoundary,
   doneFrame,
   failedTailFrame,
+  refusalFailedTailFrame,
   upstreamErrorTailFrame,
 } from "./relay";
 import {
@@ -127,6 +128,23 @@ export function relaySseEagerBounded(
       return null;
     }
   };
+  /**
+   * Same tail, except that a refusal the boundary already captured outranks the
+   * read failure that followed it — the upstream ended the turn before the
+   * socket did (#5176).
+   */
+  const encodeTerminalTail = (error: unknown): Uint8Array | null => {
+    const refusalCode = terminalBoundary.upstreamRefusalCode();
+    const refusalMessage = terminalBoundary.upstreamError();
+    if (refusalCode === undefined || refusalMessage === undefined) {
+      return encodeFailedTail(error);
+    }
+    try {
+      return refusalFailedTailFrame(terminalEncoder, refusalMessage, refusalCode);
+    } catch {
+      return null;
+    }
+  };
   const rewriteDecoder = activeRewrite ? new TextDecoder() : null;
   const rewriteEncoder = activeRewrite ? new TextEncoder() : null;
   const rewriteBudget = opts?.rewriteBudget;
@@ -313,7 +331,11 @@ export function relaySseEagerBounded(
             const upstreamError = terminalBoundary.upstreamError() ?? opts?.upstreamError;
             const upstreamErrorFrame = upstreamError === undefined
               ? adapterEofFrame
-              : upstreamErrorTailFrame(terminalEncoder, upstreamError);
+              : upstreamErrorTailFrame(
+                terminalEncoder,
+                upstreamError,
+                terminalBoundary.upstreamRefusalCode(),
+              );
             queuedBytes += upstreamErrorFrame.byteLength + terminalSentinel.byteLength;
             try {
               controllerRef?.enqueue(upstreamErrorFrame);
@@ -439,7 +461,7 @@ export function relaySseEagerBounded(
         // getters, toString) that re-entrantly cancel the client or abort the
         // upstream. Build the tail FIRST, then re-check eligibility before
         // committing to the synthetic terminal (adversarial review blocker).
-        const tail = encodeFailedTail(err);
+        const tail = encodeTerminalTail(err);
         if (tail && canDeliver()) {
           // Inspection and client framing have separate bounded parsers. If
           // inspection resynchronized after an oversized frame and observed a

package/src/server/relay.ts

@@ -5,6 +5,9 @@ import {
   CYBER_POLICY_FALLBACK_MESSAGE,
   isCyberPolicyCode,
   isCyberPolicyMessage,
+  isTerminalRefusalCode,
+  safetyRefusalCodeFromMessage,
+  terminalRefusalFallbackMessage,
   upstreamErrorMessageFromPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
@@ -22,10 +25,11 @@ import {
 } from "./request-log";
 import {
   BoundedSseFrameBuffer,
+  EMPTY_BYTES,
   joinSseFrameBytes,
   MAX_CLIENT_SSE_FRAME_BYTES,
 } from "./sse-frame-buffer";
-import { replaceSseDataPayload } from "./sse-payload-rewrite";
+import { replaceSseDataPayload, sseDataPayload } from "./sse-payload-rewrite";
 import { createBoundedResponseLogBody } from "./response-log-body";
 
 const nativePassthroughSseResponses = new WeakSet<Response>();
@@ -149,16 +153,61 @@ export function failedTailFrame(encoder: TextEncoder, err: unknown): Uint8Array
   return encoder.encode(`\n\nevent: response.failed\ndata: ${payload}\n\n${DONE_SSE_FRAME_TEXT}`);
 }
 
-export function upstreamErrorTailFrame(encoder: TextEncoder, message: string): Uint8Array {
+/**
+ * Close a turn the upstream ended without a Responses terminal.
+ *
+ * `refusalCode` carries the upstream's own verdict when it gave one. Codex
+ * 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.
+ */
+export function upstreamErrorTailFrame(
+  encoder: TextEncoder,
+  message: string,
+  refusalCode?: string,
+): Uint8Array {
+  return encoder.encode(
+    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode)}\n\n`,
+  );
+}
+
+function upstreamErrorFailedPayload(message: string, refusalCode?: string): string {
   const error = {
-    type: "upstream_error",
-    code: "upstream_server_error",
+    type: refusalCode === undefined ? "upstream_error" : "invalid_request_error",
+    code: refusalCode ?? "upstream_server_error",
     message: redactSecretString(message).slice(0, MAX_TAIL_ERROR_MESSAGE_CHARS),
   };
-  return encoder.encode(`event: response.failed\ndata: ${JSON.stringify({
+  return JSON.stringify({
     type: "response.failed",
-    response: { status: "failed", error, last_error: error },
-  })}\n\n`);
+    response: {
+      status: "failed",
+      error,
+      last_error: error,
+      ...(refusalCode === undefined ? {} : { retryable: false }),
+    },
+  });
+}
+
+/**
+ * Terminal for a read that failed after the upstream had already refused.
+ *
+ * Framed exactly like {@link failedTailFrame} — leading blank line to close a
+ * partial block, then the sentinel — but carrying the refusal instead of the
+ * generic reset. The refusal is the real outcome of the turn and the socket
+ * teardown that followed it is not, so reporting `upstream_reset` here would
+ * restart a turn the upstream has already ended (#5176).
+ */
+export function refusalFailedTailFrame(
+  encoder: TextEncoder,
+  message: string,
+  refusalCode: string,
+): Uint8Array {
+  const payload = upstreamErrorFailedPayload(message, refusalCode);
+  return encoder.encode(
+    `\n\nevent: response.failed\ndata: ${payload}\n\n${DONE_SSE_FRAME_TEXT}`,
+  );
 }
 
 function boundedBareUpstreamErrorMessage(payload: unknown): string | undefined {
@@ -168,12 +217,57 @@ function boundedBareUpstreamErrorMessage(payload: unknown): string | undefined {
   return message ? redactSecretString(message).slice(0, MAX_TAIL_ERROR_MESSAGE_CHARS) : undefined;
 }
 
+/**
+ * A bare upstream `error` event reduced to what the synthesized terminal needs.
+ *
+ * The structured code is authoritative whenever the upstream sent one: a code
+ * that is not a refusal means the upstream did not refuse, whatever its
+ * diagnostic text happens to quote. Recognized refusal copy is read only when
+ * no code was carried anywhere on the event, which is the shape #5176 reports.
+ * A refusal code with no message still yields a terminal, because Codex accepts
+ * that shape and supplies its own copy for it.
+ *
+ * The candidate topology mirrors {@link upstreamErrorMessageFromPayload}: code
+ * and message must be read from the same places, or an event whose message is
+ * nested under `response.error` would contribute text while its verdict went
+ * unseen.
+ */
+function boundedBareUpstreamError(payload: unknown): {
+  message: string;
+  refusalCode: string | undefined;
+} | undefined {
+  const root = asJsonRecord(payload);
+  if (!root || root.type !== "error") return undefined;
+  const message = boundedBareUpstreamErrorMessage(payload);
+  const response = asJsonRecord(root.response);
+  // Precedence is {@link upstreamErrorMessageFromPayload}'s, so the envelope
+  // that supplied the message also supplies the verdict. Taking the FIRST code
+  // rather than searching for a refusal is what stops a refusal nested below a
+  // transient one from overruling it.
+  const code = [
+    asJsonRecord(root.error),
+    asJsonRecord(root.last_error),
+    asJsonRecord(response?.error),
+    asJsonRecord(response?.incomplete_details),
+    root,
+  ]
+    .map(candidate => stringField(candidate, "code"))
+    .find(candidate => candidate !== undefined);
+  const refusalCode = code !== undefined
+    ? (isTerminalRefusalCode(code) ? code : undefined)
+    : message === undefined ? undefined : safetyRefusalCodeFromMessage(message);
+  if (message !== undefined) return { message, refusalCode };
+  if (refusalCode === undefined) return undefined;
+  return { message: terminalRefusalFallbackMessage(refusalCode), refusalCode };
+}
+
 export type SseTerminalOutputBoundary = {
   feed(chunk: Uint8Array): Uint8Array;
   finish(): Uint8Array;
   terminalSeen(): boolean;
   doneSeen(): boolean;
   upstreamError(): string | undefined;
+  upstreamRefusalCode(): string | undefined;
   dispose(): void;
 };
 
@@ -196,11 +290,12 @@ export function createSseTerminalOutputBoundary(
   let pendingDone: { block: Uint8Array; delimiter: Uint8Array } | null = null;
   let disposed = false;
   let upstreamError: string | undefined;
+  let upstreamRefusalCode: string | undefined;
 
   const processFrames = (
     frames: ReturnType<BoundedSseFrameBuffer["feed"]>,
   ): Uint8Array => {
-    if (disposed || terminal || frames.length === 0) return new Uint8Array(0);
+    if (disposed || terminal || frames.length === 0) return EMPTY_BYTES;
     const output: Uint8Array[] = [];
     let responsesTerminal = false;
     for (const frame of frames) {
@@ -209,8 +304,11 @@ export function createSseTerminalOutputBoundary(
       const parsed = payload === null ? undefined : parseSsePayload(payload);
       // Observe on the client reader itself: a tee inspection branch may lag
       // behind EOF, so its log context cannot determine the outgoing terminal.
-      const message = boundedBareUpstreamErrorMessage(parsed);
-      if (message !== undefined) upstreamError = message;
+      const bare = boundedBareUpstreamError(parsed);
+      if (bare !== undefined) {
+        upstreamError = bare.message;
+        upstreamRefusalCode = bare.refusalCode;
+      }
       const safetyBuffering = dropSafetyBuffering && parsed !== undefined
         ? codexSafetyBufferingBlockAction(parsed) : "keep";
       if (safetyBuffering === "drop") continue;
@@ -259,13 +357,13 @@ export function createSseTerminalOutputBoundary(
 
   return {
     feed(chunk) {
-      if (disposed || terminal) return new Uint8Array(0);
+      if (disposed || terminal) return EMPTY_BYTES;
       return processFrames(framer.feed(chunk));
     },
     finish() {
-      if (disposed || terminal) return new Uint8Array(0);
+      if (disposed || terminal) return EMPTY_BYTES;
       const tail = framer.finish();
-      if (tail.byteLength === 0) return new Uint8Array(0);
+      if (tail.byteLength === 0) return EMPTY_BYTES;
       // EOF may cut off the final SSE block before its blank-line delimiter.
       // Feed it through the exact same parser/rewrite/terminal path as a
       // complete frame, using a synthetic delimiter so the client receives a
@@ -277,6 +375,7 @@ export function createSseTerminalOutputBoundary(
     terminalSeen: () => terminal,
     doneSeen: () => done,
     upstreamError: () => upstreamError,
+    upstreamRefusalCode: () => upstreamRefusalCode,
     dispose() {
       if (disposed) return;
       disposed = true;
@@ -348,7 +447,11 @@ export function relaySseWithFailedTail(
               const upstreamError = terminalBoundary.upstreamError() ?? opts?.upstreamError;
               controller.enqueue(upstreamError === undefined
                 ? adapterEofIncompleteFrame(encoder)
-                : upstreamErrorTailFrame(encoder, upstreamError));
+                : upstreamErrorTailFrame(
+                  encoder,
+                  upstreamError,
+                  terminalBoundary.upstreamRefusalCode(),
+                ));
               controller.enqueue(doneFrame(encoder));
             }
             terminalBoundary.dispose();
@@ -359,7 +462,7 @@ export function relaySseWithFailedTail(
           if (result !== "buffered") return;
         }
       } catch (err) {
-        let partial: Uint8Array = new Uint8Array(0);
+        let partial: Uint8Array = EMPTY_BYTES;
         let tailTerminal = false;
         try {
           partial = terminalBoundary.finish();
@@ -377,7 +480,11 @@ export function relaySseWithFailedTail(
             if (!terminalBoundary.doneSeen()) controller.enqueue(doneFrame(encoder));
           } else {
             // Leading blank line terminates a partial SSE block so the failed frame parses cleanly.
-            controller.enqueue(failedTailFrame(encoder, err));
+            const refusalCode = terminalBoundary.upstreamRefusalCode();
+            const refusalMessage = terminalBoundary.upstreamError();
+            controller.enqueue(refusalCode !== undefined && refusalMessage !== undefined
+              ? refusalFailedTailFrame(encoder, refusalMessage, refusalCode)
+              : failedTailFrame(encoder, err));
           }
           controller.close();
         } catch { /* client already torn down */ }
@@ -403,15 +510,7 @@ export function nextSseBlock(buffer: string): { block: string; delimiter: string
   };
 }
 
-export function sseDataPayload(block: string): string | null {
-  const data: string[] = [];
-  for (const line of block.split(/\r?\n/)) {
-    if (!line.startsWith("data:")) continue;
-    const value = line.slice(5);
-    data.push(value.startsWith(" ") ? value.slice(1) : value);
-  }
-  return data.length > 0 ? data.join("\n") : null;
-}
+export { sseDataPayload } from "./sse-payload-rewrite";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -727,6 +826,9 @@ export function responseWithDeferredRequestLog(
           // 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, {
+            ...(reason === "eof" && logCtx.observedTerminalStatus
+              ? { terminalStatus: logCtx.observedTerminalStatus }
+              : {}),
             closeReason: reason === "cancel" ? "client_cancel" : "non_stream",
           }, addLog);
         },
@@ -943,8 +1045,8 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
   let reported = false;
   let sawTerminal = false;
   let disposed = false;
-  let delimiterTail: Uint8Array = new Uint8Array(0);
-  let candidate: Uint8Array = new Uint8Array(0);
+  let delimiterTail: Uint8Array = EMPTY_BYTES;
+  let candidate: Uint8Array = EMPTY_BYTES;
   let candidateBytes = 0;
   let discardingOversizedFrame = false;
   const reportFirstOutput = createFirstOutputReporter(handlers.onFirstOutput);
@@ -957,8 +1059,8 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
   let firstResponseId: string | undefined;
 
   const clearFrameState = (): void => {
-    delimiterTail = new Uint8Array(0);
-    candidate = new Uint8Array(0);
+    delimiterTail = EMPTY_BYTES;
+    candidate = EMPTY_BYTES;
     candidateBytes = 0;
     discardingOversizedFrame = false;
   };
@@ -995,9 +1097,9 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
   };
 
   const takeCandidate = (): Uint8Array => {
-    if (candidateBytes === 0) return new Uint8Array(0);
+    if (candidateBytes === 0) return EMPTY_BYTES;
     const frame = candidate.slice(0, candidateBytes);
-    candidate = new Uint8Array(0);
+    candidate = EMPTY_BYTES;
     candidateBytes = 0;
     return frame;
   };
@@ -1010,7 +1112,7 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
       Math.min(nextBytes, MAX_INSPECTION_SSE_FRAME_BYTES),
     );
     if (nextBytes > MAX_INSPECTION_SSE_FRAME_BYTES) {
-      candidate = new Uint8Array(0);
+      candidate = EMPTY_BYTES;
       candidateBytes = 0;
       discardingOversizedFrame = true;
       inspectionCounters.frameCapOverflows += 1;
@@ -1173,7 +1275,7 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
 
   const scanChunk = (chunk: Uint8Array): void => {
     const previousTail = delimiterTail;
-    delimiterTail = new Uint8Array(0);
+    delimiterTail = EMPTY_BYTES;
     const tailLength = previousTail.byteLength;
     const totalLength = tailLength + chunk.byteLength;
     const byteAt = (index: number): number => index < tailLength
@@ -1219,7 +1321,7 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
       if (disposed) return;
       try {
         retainCandidateSlice(delimiterTail);
-        delimiterTail = new Uint8Array(0);
+        delimiterTail = EMPTY_BYTES;
         if (!discardingOversizedFrame && candidateBytes > 0 && !reported) {
           const sourceBytes = candidateBytes;
           const decoded = decoder!.decode(takeCandidate());

package/src/server/request-log.ts

@@ -12,6 +12,7 @@ import {
   isCyberPolicyCode,
   isCyberPolicyMessage,
   isRateLimitOrQuotaFailureMessage,
+  isUpstreamResetReplayRefusedMessage,
   upstreamErrorMessageFromPayload,
 } from "../lib/errors";
 import { CODEX_CONFIG_PATH, readRootTomlString } from "../codex/paths";
@@ -22,6 +23,7 @@ import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routi
 import type { AdapterRequest } from "../adapters/base";
 import type { RequestSpendSettlement } from "./responses/request-spend";
 import type { AdapterTierMetadata } from "../providers/fastwire";
+import { UPSTREAM_RESET_REPLAY_REFUSED_CODE } from "../lib/upstream-retry";
 import { redactSecretString, sanitizeLogMetadataString } from "../lib/redact";
 import {
   appendUsageEntry,
@@ -44,6 +46,7 @@ import {
   usageStatusForFinalLog,
   usageTotalTokens,
   type AttemptRecoveryKind,
+  type AttemptRecoveryWithheld,
   type CacheTelemetryProvenance,
   type PersistedRequestSpend,
   type PersistedUsageAttempt,
@@ -66,10 +69,15 @@ import { inferCursorContextWindow } from "../adapters/cursor/discovery";
 import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
 import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
 import { modelRecordValue } from "../reasoning-effort";
+import type { RequestMetricsRecorder } from "./request-metrics";
 
 export interface RequestLogContext {
   model: string;
   provider: string;
+  /** Optional process-lifetime aggregate sink, injected by the server composition owner. */
+  requestMetricsRecorder?: RequestMetricsRecorder;
+  /** Bounded terminal enum observed while inspecting a buffered response body. */
+  observedTerminalStatus?: ResponsesTerminalStatus;
   /**
    * Identity of the ONE logical request this context serves (#4546). Set from the execution
    * budget minted at ingress; a retry leg, a repair refetch and a combo child share it.
@@ -290,6 +298,7 @@ export interface RequestLogEntry {
 }
 
 const requestLog: RequestLogEntry[] = [];
+const requestLogObserversForTests = new Set<(entry: RequestLogEntry) => void>();
 const MAX_LOG_SIZE = 2000;
 const requestLogEntryBytes = new WeakMap<RequestLogEntry, number>();
 let requestLogBytes = 0;
@@ -490,6 +499,9 @@ export function addRequestLog(entry: RequestLogEntry) {
   else if (retained !== entry) delete retained.claudeCompatibility;
   entry = retained;
   retainRequestLogEntry(entry);
+  for (const observer of requestLogObserversForTests) {
+    try { observer(entry); } catch { /* test observation must never fail request logging */ }
+  }
   try {
     // Failure diagnostics survive the 200-entry ring buffer by riding the persisted
     // usage entry (devlog/_plan/260716_claudecode_hardening/030). Success rows stay
@@ -565,6 +577,12 @@ export function addRequestLog(entry: RequestLogEntry) {
   }
 }
 
+/** Test-only finalized-row observation without polling the management projection. */
+export function observeRequestLogsForTests(observer: (entry: RequestLogEntry) => void): () => void {
+  requestLogObserversForTests.add(observer);
+  return () => { requestLogObserversForTests.delete(observer); };
+}
+
 export function nextRequestLogId(_timestamp = Date.now()): string {
   return `ocx-${randomBytes(16).toString("hex")}`;
 }
@@ -713,7 +731,15 @@ export function requestLogErrorCode(
     }
     return "permission_denied";
   }
-  if (status === 429) return "rate_limit_exceeded";
+  if (status === 429) {
+    // A refused ambiguous reset answers 429 by design (it must not invite a client
+    // retry that could duplicate inference); classify it by its message so the log
+    // distinguishes a proxy refusal from provider throttling.
+    if (upstreamError?.trim() && isUpstreamResetReplayRefusedMessage(upstreamError)) {
+      return UPSTREAM_RESET_REPLAY_REFUSED_CODE;
+    }
+    return "rate_limit_exceeded";
+  }
   if (status === 503) return "server_is_overloaded";
   if (status >= 500) return "upstream_server_error";
   return `http_${status}`;
@@ -765,6 +791,22 @@ export function catalogModelSupportsServiceTier(modelId: string, serviceTier: st
 
 export function applyResponseLogMetadata(logCtx: RequestLogContext, payload: unknown): void {
   if (!payload || typeof payload !== "object") return;
+  if (logCtx.observedTerminalStatus === undefined) {
+    const eventType = (payload as { type?: unknown }).type;
+    const response = (payload as { response?: unknown }).response;
+    const responseStatus = response && typeof response === "object"
+      ? (response as { status?: unknown }).status
+      : (payload as { status?: unknown }).status;
+    if (eventType === "response.completed") {
+      logCtx.observedTerminalStatus = "completed";
+    } else if (eventType === "response.failed") {
+      logCtx.observedTerminalStatus = "failed";
+    } else if (eventType === "response.incomplete") {
+      logCtx.observedTerminalStatus = "incomplete";
+    } else if (responseStatus === "completed" || responseStatus === "failed" || responseStatus === "incomplete") {
+      logCtx.observedTerminalStatus = responseStatus;
+    }
+  }
   const source = "response" in payload && typeof (payload as { response?: unknown }).response === "object"
     ? (payload as { response?: unknown }).response
     : payload;
@@ -854,7 +896,13 @@ export function usageFromResponsesPayload(usage: unknown): OcxUsage | undefined
  * Mark a refusal this proxy synthesized locally. Sets origin to `synthetic` and a
  * distinct local reason so the request log cannot be read as an upstream overload.
  */
-export function markLocalRequestLogRefusal(logCtx: RequestLogContext, reason: string): void {
+// Typed by the two fields it writes rather than by the whole context: the durable-spend tracker
+// has to mark a row from a narrow view of it, and widening that view to the full context there
+// would pull the entire log shape into a module that touches two of its fields.
+export function markLocalRequestLogRefusal(
+  logCtx: Pick<RequestLogContext, "localTerminalReason" | "terminalSource">,
+  reason: string,
+): void {
   logCtx.localTerminalReason = reason;
   logCtx.terminalSource = "synthetic";
 }
@@ -1300,6 +1348,7 @@ export function addFinalRequestLog(
   const attempts = logCtx.attempts?.map(attempt => ({
     ...attempt,
     recoveryKinds: [...attempt.recoveryKinds],
+    ...(attempt.recoveryWithheld?.length ? { recoveryWithheld: [...attempt.recoveryWithheld] } : {}),
     ...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
     ...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}),
   }));
@@ -1309,6 +1358,17 @@ export function addFinalRequestLog(
   const usageStatus = aggregate?.status ?? existing.status;
   const totalTokens = aggregate?.totalTokens ?? existing.totalTokens;
   const spend = requestSpendRecord(logCtx, attempts);
+  const durationMs = Date.now() - start;
+  logCtx.requestMetricsRecorder?.recordFinalRequest({
+    ...(logCtx.inboundProtocol ? { protocol: logCtx.inboundProtocol } : {}),
+    status: effectiveStatus,
+    durationMs,
+    ...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
+    ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
+    ...(closeReason ? { closeReason } : {}),
+    ...(attempts !== undefined ? { attempts } : {}),
+    ...(spend ? { spendSends: spend.sends } : {}),
+  });
   const cacheProvenance = classifyCacheTelemetryProvenance(loggedUsage, {
     wireParsed: logCtx.usageWireParsed === true,
   });
@@ -1356,7 +1416,7 @@ export function addFinalRequestLog(
       : {}),
     ...(logCtx.resolvedModel ? { resolvedModel: logCtx.resolvedModel } : {}),
     status: effectiveStatus,
-    durationMs: Date.now() - start,
+    durationMs,
     ...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
     ...(errorCode ? { errorCode } : {}),
     ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
@@ -1703,6 +1763,22 @@ export function noteAttemptSend(
   }
 }
 
+/**
+ * Record that a recovery this attempt was eligible for did not happen.
+ *
+ * Deliberately NOT `noteAttemptSend`: nothing was sent, so `sendCount` must not move. The two
+ * together are what make a one-send log readable — no kind and no withheld reason means nothing
+ * was eligible, a withheld reason means something was and the budget refused it (#5044).
+ */
+export function noteAttemptRecoveryWithheld(
+  attempt: PersistedUsageAttempt | undefined,
+  reason: AttemptRecoveryWithheld,
+): void {
+  if (!attempt) return;
+  if (!attempt.recoveryWithheld) attempt.recoveryWithheld = [];
+  if (!attempt.recoveryWithheld.includes(reason)) attempt.recoveryWithheld.push(reason);
+}
+
 export function finishRequestAttempt(
   attempt: PersistedUsageAttempt,
   status: number,
@@ -1785,4 +1861,5 @@ export function clearRequestLogsForTests(): void {
   requestLog.length = 0;
   requestLogBytes = 0;
   requestLogsHydratedFromDisk = false;
+  requestLogObserversForTests.clear();
 }