@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/server/relay.ts

@@ -5,10 +5,14 @@ import {
   CYBER_POLICY_FALLBACK_MESSAGE,
   isCyberPolicyCode,
   isCyberPolicyMessage,
+  isTerminalRefusalCode,
+  safetyRefusalCodeFromMessage,
+  terminalRefusalFallbackMessage,
   upstreamErrorMessageFromPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
+import { carryReplayRefusal } from "../lib/upstream-retry";
 import { isUsageDebugEnabled } from "../usage/debug";
 import {
   addRequestLog,
@@ -150,16 +154,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 {
@@ -169,12 +218,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;
 };
 
@@ -197,6 +291,7 @@ 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"]>,
@@ -210,8 +305,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;
@@ -278,6 +376,7 @@ export function createSseTerminalOutputBoundary(
     terminalSeen: () => terminal,
     doneSeen: () => done,
     upstreamError: () => upstreamError,
+    upstreamRefusalCode: () => upstreamRefusalCode,
     dispose() {
       if (disposed) return;
       disposed = true;
@@ -349,7 +448,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();
@@ -378,7 +481,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 */ }
@@ -720,15 +827,21 @@ 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);
         },
       });
-      return new Response(body, {
+      // Logging re-wraps the response, and an in-process verdict does not survive a re-wrap on
+      // its own. A replay refusal that lost it here would read to a later quota recorder or
+      // Retry-After synthesizer as a 429 some upstream produced.
+      return carryReplayRefusal(response, new Response(body, {
         status: response.status,
         statusText: response.statusText,
         headers: response.headers,
-      });
+      }));
     }
     if (isUsageDebugEnabled() && logCtx.usageDebugBodyKind === undefined) {
       logCtx.usageDebugBodyKind = response.body ? "other" : "none";
@@ -880,6 +993,14 @@ export type SseInspectorHandlers = {
    * with an empty `output`.
    */
   onParsedPayload?: (payload: unknown) => void;
+  /**
+   * A complete data payload that did not parse as a JSON event, `[DONE]` included.
+   *
+   * An inspector that only hears about parsed events cannot tell "nothing has been emitted"
+   * from "something was emitted that I could not read", and a replay decision needs that
+   * difference: an unreadable payload is a payload the caller may already have seen.
+   */
+  onOpaquePayload?: () => void;
   onFirstOutput?: () => void;
   /**
    * Provider-scoped compatibility: persist the completed snapshot under the
@@ -1068,6 +1189,11 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
     if (handlers.onParsedPayload && parsed !== undefined) {
       try { handlers.onParsedPayload(parsed); } catch { /* inspection must never throw into the pump */ }
     }
+    // The other half of the same observation. A payload that did not parse still reached the
+    // caller, so a consumer deciding whether anything has been emitted has to hear about it.
+    if (handlers.onOpaquePayload && parsed === undefined) {
+      try { handlers.onOpaquePayload(); } catch { /* inspection must never throw into the pump */ }
+    }
     reportFirstOutput.parsed(parsed);
     const status = terminalStatusFromParsed(parsed);
     const policyTerminal = status === "failed"

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

@@ -0,0 +1,99 @@
+/**
+ * Where a request's failure attribution is derived and stamped.
+ *
+ * A sibling of `request-log.ts` rather than a section inside it. That file carries the whole
+ * request-logging surface and sits against the 2,000-line repository ceiling, which only ever
+ * moves down; this is the extraction that rule asks for, not a cap that was negotiated.
+ *
+ * It holds the two places a stage and cause are decided and written. Both read the recorder's
+ * own closed facts and neither reads `errorCode` or `upstreamError`, which are assembled partly
+ * from upstream text.
+ */
+import { deriveRequestFailureAttribution } from "../lib/request-failure-attribution";
+import { causeForRecoveryKind } from "../lib/request-failure-model";
+import type { AttemptRecoveryKind, PersistedUsageAttempt, RequestFailureCause, RequestFailureStage } from "../usage/log";
+import type { ResponsesTerminalStatus } from "../bridge";
+
+/** The subset of the log context this derivation may see. Narrow on purpose. */
+export interface FinalRequestAttributionFacts {
+  readonly status: number;
+  readonly terminalStatus?: ResponsesTerminalStatus | undefined;
+  readonly closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow" | undefined;
+  readonly transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse" | undefined;
+  readonly terminalSource?: "upstream" | "synthetic" | undefined;
+  /** The REQUEST's first-output observation, not the final attempt's. See below. */
+  readonly outputObserved: boolean;
+  readonly locallyAnswered: boolean;
+  readonly attempt?: PersistedUsageAttempt | undefined;
+}
+
+export interface StampedAttribution {
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
+}
+
+/**
+ * Derive the attribution for a finished logical request and stamp the attempt that ended it.
+ *
+ * Called from the one seam every request passes exactly once, and BEFORE the attempt snapshot,
+ * so the row that reaches disk and the live attempt object carry the same pair. Deriving it at
+ * each transport's own exit would give the same request a different attribution per transport,
+ * which is the disagreement the shared terminal classifier already removed once.
+ *
+ * `outputObserved` is the request's observation rather than the final attempt's. A request that
+ * relayed output on its first attempt and then failed over has committed that output to the
+ * caller whatever the last attempt saw, so the logical row and the attempt that ended it carry
+ * the same answer. Reading the attempt-local value would produce a MORE permissive resend verdict
+ * for exactly that case, and a permission decision has to fail in the safe direction.
+ */
+export function attributeFinalRequest(facts: FinalRequestAttributionFacts): StampedAttribution {
+  const attribution = deriveRequestFailureAttribution({
+    status: facts.status,
+    ...(facts.terminalStatus ? { terminalStatus: facts.terminalStatus } : {}),
+    ...(facts.closeReason ? { closeReason: facts.closeReason } : {}),
+    ...(facts.transportPhase ? { transportPhase: facts.transportPhase } : {}),
+    ...(facts.terminalSource ? { terminalSource: facts.terminalSource } : {}),
+    ...(facts.attempt?.streamAborted === true ? { streamAborted: true } : {}),
+    outputObserved: facts.outputObserved,
+    // The one fact that can raise a stage above `semantic-output`, and the reason it is counted
+    // at the transport rather than at the adapter: an emitted tool call the client never
+    // received has committed nothing, and a resend for it is still safe (#3983).
+    sideEffectObserved: (facts.attempt?.deliverySummary?.sideEffectEvents ?? 0) > 0,
+    locallyAnswered: facts.locallyAnswered,
+    recoveryKinds: facts.attempt?.recoveryKinds ?? [],
+  });
+  // The final row and the attempt that ended it describe the same exchange, so they carry the
+  // same pair rather than each deriving one from a different slice of the facts.
+  if (facts.attempt) {
+    if (attribution?.stage) facts.attempt.failureStage = attribution.stage;
+    else delete facts.attempt.failureStage;
+    if (attribution?.cause) facts.attempt.failureCause = attribution.cause;
+    else delete facts.attempt.failureCause;
+  }
+  return {
+    ...(attribution?.stage ? { failureStage: attribution.stage } : {}),
+    ...(attribution?.cause ? { failureCause: attribution.cause } : {}),
+  };
+}
+
+/**
+ * Attribute an attempt being sealed because a named recovery rejected it.
+ *
+ * The recovery kind is direct evidence here rather than an inference from history: this attempt
+ * is ending precisely because that recovery was needed. Without it the sealed attempt would reach
+ * the ledger with no attribution at all, because the finalization seam only ever sees the last
+ * attempt of a request.
+ */
+export function attributeSealedAttempt(
+  attempt: PersistedUsageAttempt,
+  recovery: AttemptRecoveryKind | undefined,
+): void {
+  const attribution = deriveRequestFailureAttribution({
+    status: attempt.status,
+    outputObserved: attempt.firstOutputMs !== undefined,
+    sideEffectObserved: (attempt.deliverySummary?.sideEffectEvents ?? 0) > 0,
+    ...(recovery ? { causeHint: causeForRecoveryKind(recovery) } : {}),
+  });
+  if (attribution?.stage) attempt.failureStage = attribution.stage;
+  if (attribution?.cause) attempt.failureCause = attribution.cause;
+}

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,
@@ -38,6 +40,7 @@ import {
   isLogicalRequestId,
   isValidReasoningWireValue,
   normalizeClaudeCompatibilityUsageLog,
+  normalizeRequestFailureAttribution,
   normalizeRequestSpend,
   readRecentUsageEntries,
   usageForFinalLog,
@@ -50,9 +53,13 @@ import {
   type PersistedUsageAttempt,
   type PersistedUsageEntry,
   type PersistedClaudeCompatibilityLog,
+  type RequestFailureCause,
+  type RequestFailureStage,
   type UsageStatus,
 } from "../usage/log";
 import type { RequestExecutionBudget } from "../lib/request-execution-budget";
+import { attributeFinalRequest, attributeSealedAttempt } from "./request-log-failure-attribution";
+import { debugAttemptDeliverySummary } from "../lib/debug";
 import {
   appendUsageDebug,
   isUsageDebugEnabled,
@@ -67,15 +74,37 @@ 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";
+import type {
+  CacheDiagnosticDraft,
+  CacheDiagnosticFinalFacts,
+  PromptCacheKeySource,
+} from "../usage/cache-diagnostic";
+
+const CACHE_DIAGNOSTIC_HOOK = Symbol.for("opencodex.cache-diagnostic.v1");
+interface CacheDiagnosticHooks {
+  observeInbound(body: unknown, headers: Headers, source: PromptCacheKeySource): CacheDiagnosticDraft;
+  rebind(body: unknown, draft: CacheDiagnosticDraft | undefined): void;
+  finalize(facts: CacheDiagnosticFinalFacts): void;
+}
+function cacheDiagnosticHooks(): CacheDiagnosticHooks | undefined {
+  return (globalThis as Record<symbol, CacheDiagnosticHooks | undefined>)[CACHE_DIAGNOSTIC_HOOK];
+}
 
 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.
    */
   logicalRequestId?: string;
+  /** Process-local privacy-bounded cache diagnostic; never persisted with request logs. */
+  cacheDiagnosticDraft?: CacheDiagnosticDraft;
   /**
    * Internal live reference to this request's execution budget; omitted from RequestLogEntry and
    * JSONL. Read at final-log time so the row reports the budget's FINAL state rather than a
@@ -202,6 +231,24 @@ export interface RequestLogContext {
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
 }
 
+export function observeCacheDiagnosticInbound(
+  logCtx: RequestLogContext,
+  body: unknown,
+  headers: Headers,
+  source: PromptCacheKeySource,
+): void {
+  const draft = cacheDiagnosticHooks()?.observeInbound(body, headers, source);
+  if (draft) logCtx.cacheDiagnosticDraft = draft;
+}
+
+/** Alias a rebuilt form of the request body to the request's diagnostic draft. */
+export function rebindCacheDiagnosticBody(
+  body: unknown,
+  draft: CacheDiagnosticDraft | undefined,
+): void {
+  cacheDiagnosticHooks()?.rebind(body, draft);
+}
+
 export interface RequestLogEntry {
   requestId: string;
   /** The logical request this row belongs to (#4546); absent on rows written without a budget. */
@@ -288,9 +335,17 @@ export interface RequestLogEntry {
   routeDecision?: RouteDecisionTraceV1;
   /** Closed Claude protocol codes; no request or header values. */
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
+  /**
+   * How far this request got and why it failed, in the shared stage and cause vocabulary
+   * (#2366). Derived once at the single finalization seam and carried on the row so the
+   * dashboard, the durable ledger and the exporter read one answer instead of three.
+   */
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
 }
 
 const requestLog: RequestLogEntry[] = [];
+const requestLogObserversForTests = new Set<(entry: RequestLogEntry) => void>();
 const MAX_LOG_SIZE = 2000;
 const requestLogEntryBytes = new WeakMap<RequestLogEntry, number>();
 let requestLogBytes = 0;
@@ -412,6 +467,7 @@ export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): R
     ...(entry.conversationStateScrub === "account-change"
       ? { conversationStateScrub: "account-change" }
       : {}),
+    ...normalizeRequestFailureAttribution(entry),
   };
 }
 
@@ -472,6 +528,24 @@ export function hydrateRequestLogsFromDisk(
   }
 }
 
+/**
+ * Rebuild the Logs ring after retention deleted rows from the ledger.
+ *
+ * Without this a compaction is invisible where an operator actually looks: the ring holds up to
+ * 2,000 entries independently of the file, so rows deleted from disk keep serving through
+ * /api/logs until eviction or a restart -- the dashboard showing history the ledger no longer
+ * has. Observers are deliberately not replayed; they exist to watch NEW rows arrive, and
+ * replaying a rehydration through them would announce two thousand arrivals that did not happen.
+ */
+export function rehydrateRequestLogsAfterLedgerReplacement(
+  reader: () => PersistedUsageEntry[] = () => readRecentUsageEntries(MAX_LOG_SIZE),
+): number {
+  requestLog.length = 0;
+  requestLogBytes = 0;
+  requestLogsHydratedFromDisk = false;
+  return hydrateRequestLogsFromDisk(reader);
+}
+
 export function addRequestLog(entry: RequestLogEntry) {
   // Sanitize ONCE, at the ingress, and use that one value for both destinations.
   //
@@ -491,6 +565,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
@@ -555,6 +632,10 @@ export function addRequestLog(entry: RequestLogEntry) {
       ...(isKnownTransportPhase(entry.transportPhase) ? { transportPhase: entry.transportPhase } : {}),
       ...(isKnownTerminalSource(entry.terminalSource) ? { terminalSource: entry.terminalSource } : {}),
       ...failureDiagnostics,
+      // Rebuilt explicitly, like every other field here: this function does not spread the
+      // entry, so a pair omitted at this line would reach /api/logs and never reach
+      // usage.jsonl, which is the surface the derived failure projection reads.
+      ...normalizeRequestFailureAttribution(entry),
       ...(entry.routeDecision ? { routeDecision: entry.routeDecision } : {}),
       ...(entry.claudeCompatibility ? { claudeCompatibility: entry.claudeCompatibility } : {}),
       ...(entry.conversationStateScrub === "account-change"
@@ -566,6 +647,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")}`;
 }
@@ -714,7 +801,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}`;
@@ -766,6 +861,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;
@@ -1293,6 +1404,18 @@ export function addFinalRequestLog(
     if (errorCode) logCtx.activeAttempt.errorCode = errorCode;
     else delete logCtx.activeAttempt.errorCode;
   }
+  // Derived and stamped in a sibling module, before the attempt snapshot below. Every input is
+  // a closed value; the open error strings are deliberately not among them.
+  const attribution = attributeFinalRequest({
+    status: effectiveStatus,
+    ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
+    ...(closeReason ? { closeReason } : {}),
+    ...(logCtx.transportPhase ? { transportPhase: logCtx.transportPhase } : {}),
+    ...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
+    outputObserved: logCtx.firstOutputMs !== undefined,
+    locallyAnswered: logCtx.localTerminalReason !== undefined,
+    ...(logCtx.activeAttempt ? { attempt: logCtx.activeAttempt } : {}),
+  });
   // 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.
@@ -1310,6 +1433,10 @@ export function addFinalRequestLog(
     ...(attempt.recoveryWithheld?.length ? { recoveryWithheld: [...attempt.recoveryWithheld] } : {}),
     ...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
     ...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}),
+    // Detached, like every mutable field beside it: the live summary keeps counting if the
+    // stream is still draining, and a shared reference would let a finalized row change after
+    // it was written.
+    ...(attempt.deliverySummary ? { deliverySummary: { ...attempt.deliverySummary } } : {}),
   }));
   const isCombo = logCtx.comboId !== undefined && (attempts?.length ?? 0) > 0;
   const aggregate = isCombo ? aggregateAttemptUsage(attempts ?? []) : null;
@@ -1317,10 +1444,40 @@ 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 } : {}),
+    ...(attribution.failureCause ? { failureCause: attribution.failureCause } : {}),
+  });
   const cacheProvenance = classifyCacheTelemetryProvenance(loggedUsage, {
     wireParsed: logCtx.usageWireParsed === true,
   });
   const logicalRequestId = logCtx.logicalRequestId ?? logCtx.executionBudget?.logicalRequestId;
+  const normalizedCacheValue = loggedUsage?.cacheReadInputTokens ?? loggedUsage?.cachedInputTokens;
+  cacheDiagnosticHooks()?.finalize({
+    requestId,
+    ...(isLogicalRequestId(logicalRequestId) ? { logicalRequestId } : {}),
+    protocol: logCtx.inboundProtocol ?? "responses",
+    provider: logCtx.provider,
+    model: logCtx.model,
+    ...(isCodexUsageAccountLogLabel(logCtx.accountLogLabel) ? { accountLogLabel: logCtx.accountLogLabel } : {}),
+    ...(logCtx.affinity ? { affinityMove: logCtx.affinity } : {}),
+    ...(logCtx.affinityReason ? { affinityReason: logCtx.affinityReason } : {}),
+    // loggedUsage carries the upstream cache counter by reference all the way from the
+    // adapter extraction for the native Responses route, so an undefined read here is a
+    // genuinely absent counter rather than a defaulted one.
+    ...(normalizedCacheValue !== undefined ? { rawCacheCounterValue: normalizedCacheValue } : {}),
+    ...(normalizedCacheValue !== undefined ? { normalizedCacheValue } : {}),
+    cacheProvenance,
+    ...(logCtx.cacheDiagnosticDraft ? { draft: logCtx.cacheDiagnosticDraft } : {}),
+  });
   // Sanitize at the logging layer, not only at the one call site that populates this today.
   // The value originates in an upstream-supplied model id, so an unsanitized newline would
   // let a single field forge a record boundary in any line-oriented log viewer. Doing it here
@@ -1364,7 +1521,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 } : {}),
@@ -1388,7 +1545,10 @@ export function addFinalRequestLog(
     ...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
     ...(logCtx.routeDecision ? { routeDecision: logCtx.routeDecision } : {}),
     ...(claudeCompatibility ? { claudeCompatibility } : {}),
+    ...attribution,
   });
+  // Formatted from the finalized snapshot, so the ring shows exactly what the ledger holds.
+  for (const attempt of attempts ?? []) debugAttemptDeliverySummary(requestId, attempt);
   if (isUsageDebugEnabled()) {
     appendUsageDebug({
       ts: Date.now(),
@@ -1635,8 +1795,14 @@ export function noteProviderAttemptSend(
     finishRequestAttempt(attempt, attempt.status >= 100 ? attempt.status
       : recovery === "key-401" ? 401 : recovery?.includes("429") ? 429 : 502,
     Date.now() - (logCtx.activeAttemptStartedAt ?? Date.now()), attempt.usage);
+    // This attempt is being sealed because a NAMED recovery rejected it, so the recovery kind
+    // is direct evidence here rather than an inference from history. Without this the sealed
+    // attempt would reach the ledger with no attribution at all: the finalization seam below
+    // only ever sees the last attempt of the request.
+    attributeSealedAttempt(attempt, recovery);
     const completed = { ...attempt, recoveryKinds: [...attempt.recoveryKinds],
       ...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
+      ...(attempt.deliverySummary ? { deliverySummary: { ...attempt.deliverySummary } } : {}),
       ...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}) };
     const attempts = logCtx.attempts ??= [attempt];
     const index = attempts.indexOf(attempt);
@@ -1809,4 +1975,5 @@ export function clearRequestLogsForTests(): void {
   requestLog.length = 0;
   requestLogBytes = 0;
   requestLogsHydratedFromDisk = false;
+  requestLogObserversForTests.clear();
 }