import { existsSync, readFileSync } from "node:fs";
import { randomBytes } from "node:crypto";
import { normalizeRecordedClient, type UsageClient } from "../usage/client";
import { anthropicAccountTagField, stampApiKeyAccountLabel, usesApiKeyAccount } from "../providers/label";
import { finalizeProviderCacheAffinity } from "./request-log-cache-affinity";
import { aggregateAttemptUsage } from "./request-log-attempt-usage";
export { aggregateAttemptUsage } from "./request-log-attempt-usage";

import { attemptAccountChanged, sealRequestAttemptIdentity } from "./request-log-account-rotation";
export { sealRequestAttemptIdentity };
import { credentialRecoveryStatus, retainRefusedAccount, sealedCredentialRefusals } from "./request-log-attempt-recovery";
export { noteAttemptRecoveryWithheld } from "./request-log-attempt-recovery";
import { bareVerdictRowErrorCode, captureUpstreamTerminalDiagnostics, guardedRowCopy, linkLogField, notifyLinkTurnFinal, upstreamDiagnosticLogFields, type LinkRequestLogCarrier, type UpstreamErrorDiagnostics, type UpstreamErrorPayload } from "./request-log-terminal-status";
export { noteUpstreamRequestId } from "./request-log-terminal-status";
import type { ResponsesTerminalStatus } from "../bridge";
import {
  classifyError,
  CYBER_POLICY_ERROR_CODE,
  httpStatusFromTerminalError as httpStatusFromClassifiedTerminalError,
  isClientClosedMessage,
  isCyberPolicyCode,
  isUpstreamResetReplayRefusedMessage,
  responsesCompletionError,
  upstreamErrorMessageFromPayload,
} from "../lib/errors";
import { CODEX_CONFIG_PATH, readRootTomlString } from "../codex/paths";
import type { CodexAffinityMove, CodexAffinityReason } from "../codex/routing";
import type { CodexAuthContext } from "../codex/auth-context";
import { readCodexCatalogPath } from "../codex/catalog";
import type { AttemptTierOutcome, CacheAffinityLogReason, CacheAffinityOutcome, OcxProviderConfig, OcxUsage } from "../types";
import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
import { parseProtocolTraceV1, type ProtocolTraceV1 } from "../protocols/dto";
import { protocolTraceForRequest } from "../protocols/trace";
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";
export { registerCommittedTerminalCooldownHandler } from "./request-log-committed-terminal";
import { reportCommittedTerminalCooldown, type CommittedComboLogFields } from "./request-log-committed-terminal";
import type { UpstreamCondition } from "../lib/upstream-condition";
import { boundedServiceTier, errorDetailFor, projectErrorDetail } from "../usage/error-detail";
import { incompleteReasonDetail, upstreamErrorIsLocal, type FailureDetail } from "./request-log-failure-detail";
import {
  appendUsageEntry,
  classifyCacheTelemetryProvenance,
  isKnownAdmissionKind,
  isKnownAffinityMove,
  isKnownAffinityReason,
  isKnownCacheAffinity,
  isKnownCacheAffinityReason,
  isKnownCacheTelemetryProvenance,
  isKnownInboundProtocol,
  isKnownTerminalSource,
  isKnownTransportPhase,
  isKnownUsageSurface,
  isCodexUsageAccountLogLabel,
  isAnthropicAccountTag,
  isLogicalRequestId,
  isValidReasoningWireValue,
  normalizeClaudeCompatibilityUsageLog,
  normalizeRequestFailureAttribution,
  normalizeRequestSpend,
  normalizedAttempts,
  readRecentUsageEntries,
  modelIdentityLogFields, recordObservedServedModel,
  usageForFinalLog,
  usageStatusForFinalLog,
  usageTotalTokens,
  type AttemptRecoveryKind,
  type CacheTelemetryProvenance,
  type PersistedRequestSpend,
  type PersistedUsageAttempt,
  type PersistedUsageEntry,
  type PersistedClaudeCompatibilityLog,
  type RequestFailureCause,
  type RequestFailureStage,
  type UsageStatus,
} from "../usage/log";
import type { RequestExecutionBudget } from "../lib/request-execution-budget";
import type { WorkflowSpendDenialDetail } from "../lib/workflow-budget";
import { attributeFinalRequest, attributePhysicalAttempt, attributeSealedAttempt } from "./request-log-failure-attribution";
import { debugAttemptDeliverySummary } from "../lib/debug";
import {
  appendUsageDebug,
  isUsageDebugEnabled,
  truncateForDebug,
  USAGE_DEBUG_BODY_SAMPLE_BYTES,
  type UsageDebugBodyKind,
} from "../usage/debug";
import { MAX_LOG_SIZE } from "./request-log-filter";
export { filterRequestLogs, filteredRequestLogCount, queryRequestLogs } from "./request-log-filter";
import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
import { capEstimateAtContextWindow } from "../lib/token-estimate";
import { inferCursorContextWindow } from "../adapters/cursor/discovery";
import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
import { kiroObservedContextWindow } from "../providers/kiro-model-catalog";
import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
import { modelRecordValue } from "../reasoning-effort";
import {
  normalizePersistedJevDecision,
  type PersistedJevDecisionV1,
} from "../usage/jev-stats";
import { generationWindowFields, recordGenerationEvent } from "./request-log-generation-window";
import type { RequestMetricsRecorder } from "./request-metrics";
import { requestBodyField, requestBodyLogField, type RequestBodyEntryField, type RequestBodyLogContext } from "./request-body-facts";
import type {
  CacheDiagnosticDraft,
  CacheDiagnosticFinalFacts,
  PromptCacheKeySource,
} from "../usage/cache-diagnostic";

const CACHE_DIAGNOSTIC_HOOK = Symbol.for("opencodex.cache-diagnostic.v1");
interface CacheDiagnosticHooks {
  /** Whether inbound bodies are actually recorded; the hook is registered at import either way. */
  enabled(): boolean;
  observeInbound(body: unknown, headers: Headers, source: PromptCacheKeySource, admissionPrincipal?: string): 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];
}

/** Whether the cache diagnostic recorder will record inbound bodies (`OPENCODEX_CACHE_DEBUG=1`). */
export function cacheDiagnosticsObserving(): boolean {
  return cacheDiagnosticHooks()?.enabled() === true;
}

export interface RequestLogContext extends UpstreamErrorDiagnostics, LinkRequestLogCarrier, RequestBodyLogContext, CommittedComboLogFields {
  model: string;
  provider: string;
  client?: UsageClient;
  /** 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
   * snapshot taken before the recovery legs that the row is meant to explain.
   */
  executionBudget?: RequestExecutionBudget;
  /**
   * True once usage counts were taken from a response wire rather than reported raw by the
   * adapter. It decides cache provenance: the normalizer writes zero-default token-detail
   * objects, so an all-zero cache detail from a parsed wire is not a measured cache miss.
   */
  usageWireParsed?: boolean;
  /**
   * Every affinity reason recorded for this request, in order. `affinityReason` keeps the final
   * one for the existing row shape; a request that moved twice has two causes and losing the
   * first one loses the more expensive half of the story.
   */
  affinityMoveReasons?: CodexAffinityReason[];
  /** TTFT: ms from request start to the first non-empty model output delta (WP4, devlog 040). */
  firstOutputMs?: number;
  /** Epoch ms of the first output item and of the last output delta; see request-log-generation-window.ts. */
  generationStartedAt?: number;
  lastOutputAt?: number;
  /** Best-effort chat/session correlation for Logs grouping (#330). Opaque; omit when unknown. */
  conversationId?: string;
  /** In-memory only: conversationId holds the log-only Hermes digest, which a native id replaces. */
  conversationIdIsHermesFallback?: boolean;
  surface?: "claude" | "claude-desktop" | "grok";
  /** The matched configured key's id. Set ONLY for admissionKind "configured" —
   *  never a sentinel, so a hand-edited entry whose id happens to be "loopback"
   *  cannot absorb unrelated traffic. */
  apiKeyId?: string;
  /** Which kind of admission opened this request. Carries no secret. */
  admissionKind?: "configured" | "environment" | "loopback";
  /** Which inbound wire was used. Orthogonal to `surface`, which names the client
   *  product: widening that enum would merge Responses and Chat Completions,
   *  since both leave it undefined. */
  inboundProtocol?: "responses" | "chat" | "messages";
  /**
   * Set when an adapter answered the turn locally and no upstream request was made
   * (`ProviderAdapter.localTerminal`). A fixed identifier naming the code path, never
   * conversation-derived: it exists so a request log showing zero sends is explainable
   * rather than looking like a lost request.
   */
  localTerminalReason?: string;
  /** Stable non-PII Codex Pool account identity for durable usage attribution. */
  accountLogLabel?: string;
  requestedModel?: string;
  /** User-facing alias selector when routing resolved one; native model remains `model`. */
  requestedAlias?: string;
  /** Original bare helper model when the opt-in shadow-call route rewrote this request. */
  shadowCallRewrittenFrom?: string;
  /** Internal structural combo identity; omitted from RequestLogEntry/JSONL. */
  comboId?: string;
  requestedEffort?: string;
  effectiveEffort?: string;
  reasoningWireField?: string;
  reasoningWireValue?: string | number | boolean;
  callerServiceTier?: string;
  requestedServiceTier?: string;
  requestedSpeedLabel?: string;
  configuredServiceTier?: string;
  configuredSpeedLabel?: string;
  modelSupportsServiceTier?: boolean;
  responseServiceTier?: string;
  /** Final-attempt tier summary; attempt rows remain the accounting source of truth. */
  tierOutcome?: AttemptTierOutcome;
  resolvedModel?: string;
  /** Upstream served model, retained beside resolvedModel so an upstream reroute stays visible. */
  servedModel?: string;
  /** The exact model id sent upstream; recorded when a route/virtual rewrite makes it differ
   * from the client-facing `model`, so a served-model mismatch can be judged against the wire. */
  wireModel?: string;
  /** Internal: client-facing response metadata must not replace the physical routed model. */
  preserveResolvedModelFromRoute?: boolean;
  /** Internal: client-facing selector written into response.model; never an upstream observation. */
  responseModelEcho?: string;
  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;
  /** Pre-send input estimate reserved for spend only; unlike usageLogInputTokens it never enters usage. */
  spendInputEstimateTokens?: number;
  /** Canonical provider-pool spend identity; independent of mutable, account-specific log labels. */
  spendPoolId?: string;
  /** Internal safe refusal detail for a request whose ceiling includes unidentified old pool spend. */
  spendRefusalDetail?: WorkflowSpendDenialDetail;
  /** Settles this request's durable spend entries from `addFinalRequestLog`. */
  spendTracker?: RequestSpendSettlement;
  attempts?: PersistedUsageAttempt[];
  /** Internal mutable final attempt; omitted from RequestLogEntry/JSONL. */
  activeAttempt?: PersistedUsageAttempt;
  /** Internal wall-clock origin for the committed final attempt; never persisted. */
  activeAttemptStartedAt?: number;
  /** Internal adapter response observer paired with activeAttempt.tierOutcome. */
  activeTierMetadata?: AdapterTierMetadata;
  usageDebugBodyKind?: UsageDebugBodyKind;
  usageDebugBodySample?: string;
  usageDebugContentType?: string;
  /** Route adapter type ("cursor"/"kiro"/"anthropic"/…): drives estimated-usage detection
   *  independent of the user-chosen provider NAME (devlog 130 B2). */
  providerAdapter?: string;
  /** Set when the bridge reported raw adapter usage via onUsage: the bridged wire now always
   *  carries synthetic zero-default token-detail objects (strict-client normalization, see
   *  responsesUsage in src/bridge.ts), so SSE/JSON re-parsing must not overwrite the raw
   *  provenance — a synthetic cached_tokens:0 is NOT a measured cache read. */
  usageFromBridge?: boolean;
  /** Process-owned provenance when a later parse of the client body must skip its usage.
   *  The original provider usage, when present, is already recorded on this context. */
  clientResponseUsage?: "estimated" | "synthetic";
  /** A committed keepalive's native child owns raw usage; only the outer client-body log tap skips it. */
  clientSseUsageAlreadyInspected?: boolean;
  /** Secret-redacted upstream error reason (e.g. the granular Cursor "rate limit exceeded…"
   * message) extracted from a `response.failed` SSE payload or non-streaming error body, so the
   * request log / GUI shows the actual upstream failure rather than only the HTTP-mapped code. */
  upstreamError?: string;
  failureDetail?: FailureDetail; // closed code + bounded params (src/lib/failure-detail.ts)
  upstreamCondition?: UpstreamCondition; // classified at capture where the evidence is not kept on the context
  /** HTTP status derived from a terminal `response.failed` SSE payload (429/401/503/etc.). */
  terminalHttpStatus?: number;
  /** Status of an upstream `error` event that ended a 200 Messages stream; the row stays 200, a combo child reads it. */
  streamErrorStatus?: number;
  /** Bytes other than a ping followed that upstream `error` event, so a retry would repeat output. */
  streamErrorFollowed?: true;
  /** Recognized structured terminal code whose exact identity must survive status mapping. */
  terminalErrorCode?: typeof CYBER_POLICY_ERROR_CODE;
  /**
   * Proxy-owned error code for a request OpenCodex terminated locally, before or instead of an
   * upstream send. Status-derived classification cannot name these: there is no upstream
   * message to classify, and the status alone would read as a provider failure.
   */
  errorCode?: string;
  /** Structured reason from `response.incomplete`; internal-only input to log classification. */
  terminalIncompleteReason?: string;
  affinity?: CodexAffinityMove;
  /** Why the binding was kept, moved, or released (#4546). */
  affinityReason?: CodexAffinityReason;
  /**
   * Set when this request dropped account-bound continuation because the serving
   * Codex pool account was not the issuer. Never an account identifier.
   */
  conversationStateScrub?: "account-change";
  /** Explicit session lane for provider cache affinity; internal only, never persisted raw. */
  affinityLane?: string;
  affinityKeyEntryId?: string;
  /** Configured provider owning the serving entry, independent of combo display labels. */
  affinityProviderName?: string;
  /** Whether provider cache affinity applies to this request's provider at all. */
  cacheAffinityApplicable?: boolean;
  /** Entry the consult kept this request on, when it did; rotation may still move it. */
  affinityKeptEntryId?: string;
  /** Model identity affinity consults with; recording reuses it so virtual models match. */
  affinityModel?: string;
  /** Provider cache-affinity outcome for this request (bounded enum, persisted on the entry). */
  cacheAffinity?: CacheAffinityOutcome;
  cacheAffinityReason?: CacheAffinityLogReason;
  transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse";
  terminalSource?: "upstream" | "synthetic";
  /** Closed failure evidence supplied by the transport, never inferred from provider text. */
  causeHint?: RequestFailureCause;
  /** Bounded route-decision trace (RI-01); never contains secrets. */
  routeDecision?: RouteDecisionTraceV1;
  /** Full eligible provider/model membership from a policy route; never logged. */
  policyEligibility?: ReadonlySet<string>;
  /** Privacy-bounded JEV selection metadata; downstream usage is recorded on attempts[]. */
  jevDecision?: PersistedJevDecisionV1;
  /** Opt-in shadow evidence, normalized again at the logging boundary. */
  claudeCompatibility?: PersistedClaudeCompatibilityLog;
}

export function observeCacheDiagnosticInbound(
  logCtx: RequestLogContext,
  body: unknown,
  headers: Headers,
  source: PromptCacheKeySource,
  admissionPrincipal?: string,
): void {
  const draft = cacheDiagnosticHooks()?.observeInbound(body, headers, source, admissionPrincipal);
  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 extends UpstreamErrorDiagnostics, LinkRequestLogCarrier, RequestBodyEntryField {
  requestId: string;
  client?: UsageClient;
  /** The logical request this row belongs to (#4546); absent on rows written without a budget. */
  logicalRequestId?: string;
  timestamp: number;
  model: string;
  provider: string;
  /** TTFT: ms from request start to the first non-empty model output delta; unset for non-streaming/tool-only. */
  firstOutputMs?: number;
  /** Request-relative generation window (#6309): first output item of any kind, then the last output delta. */
  genStartMs?: number;
  lastOutputMs?: number;
  surface?: "claude" | "claude-desktop" | "grok";
  /**
   * Set when the proxy answered this turn locally and sent nothing upstream. Without it a zero-send
   * row is indistinguishable from a request that vanished. A fixed adapter-supplied identifier,
   * never conversation-derived.
   */
  localTerminalReason?: string;
  /** The matched configured key's id. Set ONLY for admissionKind "configured" —
   *  never a sentinel, so a hand-edited entry whose id happens to be "loopback"
   *  cannot absorb unrelated traffic. */
  apiKeyId?: string;
  /** Which kind of admission opened this request. Carries no secret. */
  admissionKind?: "configured" | "environment" | "loopback";
  /** Which inbound wire was used. Orthogonal to `surface`, which names the client
   *  product: widening that enum would merge Responses and Chat Completions,
   *  since both leave it undefined. */
  inboundProtocol?: "responses" | "chat" | "messages";
  accountLogLabel?: string;
  /** Anthropic pool account of `provider` (#8383): its p-label, beside the unchanged `accountLogLabel`. */
  accountTag?: `p${string}`;
  /** Best-effort chat/session correlation for Logs grouping (#330). */
  conversationId?: string;
  requestedModel?: string;
  requestedAlias?: string;
  /** Original bare helper model when the opt-in shadow-call route rewrote this request. */
  shadowCallRewrittenFrom?: string;
  requestedEffort?: string;
  effectiveEffort?: string;
  reasoningWireField?: string;
  reasoningWireValue?: string | number | boolean;
  callerServiceTier?: string;
  requestedServiceTier?: string;
  requestedSpeedLabel?: string;
  configuredServiceTier?: string;
  configuredSpeedLabel?: string;
  modelSupportsServiceTier?: boolean;
  responseServiceTier?: string;
  tierOutcome?: AttemptTierOutcome;
  resolvedModel?: string;
  /** Model the upstream actually served (openai-model header or response body). */
  servedModel?: string;
  /** The exact model id sent upstream when it differs from the client-facing `model`. */
  wireModel?: string;
  status: number;
  durationMs: number;
  errorCode?: string;
  terminalStatus?: ResponsesTerminalStatus;
  closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow";
  /** Input only: addRequestLog derives the two fields below from it, then removes it. */
  upstreamError?: string;
  upstreamCondition?: UpstreamCondition; // closed enum, src/lib/upstream-condition.ts
  failureDetail?: FailureDetail; // closed code + bounded params, see request-log-failure-detail.ts
  rateLimitResetAt?: number; // provider quota window end, epoch ms, bounded
  usageStatus: UsageStatus;
  usage?: OcxUsage;
  totalTokens?: number;
  attempts?: PersistedUsageAttempt[];
  /** True when persistence normalization drops any attempt. */
  attemptNormalizationDropped?: boolean;
  /**
   * Upstream spend for the whole logical request: sends aggregated across attempts and combo
   * children, split into settled and unresolved, with the budget state and move reasons that
   * explain them. Per-attempt `sendCount` stays the accounting source; this is the total.
   */
  spend?: PersistedRequestSpend;
  /** Whether this row's cache detail was observed, synthesized for the wire, or absent. */
  cacheProvenance?: CacheTelemetryProvenance;
  /** Codex pool affinity decision for this request (diagnostics for #186). */
  affinity?: CodexAffinityMove;
  /** Why that decision was made (#4546): a move is the expensive event, so it names its cause. */
  affinityReason?: CodexAffinityReason;
  /** Provider cache-affinity outcome: kept on, newly bound to, or released from a key-pool credential. */
  cacheAffinity?: CacheAffinityOutcome;
  cacheAffinityReason?: CacheAffinityLogReason;
  /**
   * Set when this request dropped account-bound continuation after a Codex pool
   * account change. Never an account identifier.
   */
  conversationStateScrub?: "account-change";
  /** Where the upstream terminal/failure was observed. */
  transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse";
  /**
   * Whether the HTTP status and message originated upstream or were synthesized by this
   * proxy. Covers SSE tails and pre-stream JSON refusals. Management surfaces this so a
   * local refusal cannot be presented as an upstream reason.
   */
  terminalSource?: "upstream" | "synthetic";
  /** Bounded route-decision trace (RI-01); never contains secrets. */
  routeDecision?: RouteDecisionTraceV1;
  /** Privacy-bounded JEV selection metadata; downstream usage is recorded on attempts[]. */
  jevDecision?: PersistedJevDecisionV1;
  /** 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;
  /** Observed protocol path (PF-02, `src/protocols/trace.ts`); absent when nothing was observed. */
  protocolTrace?: ProtocolTraceV1;
}

const requestLog: RequestLogEntry[] = [];
const requestLogObserversForTests = new Set<(entry: RequestLogEntry) => void>();
const requestLogEntryBytes = new WeakMap<RequestLogEntry, number>();
let requestLogBytes = 0;
/** True after hydrateRequestLogsFromDisk ran once in this process. */
let requestLogsHydratedFromDisk = false;

function retainedRequestLogBytes(entry: RequestLogEntry): number {
  return Buffer.byteLength(JSON.stringify(entry), "utf8");
}

function removeOldestRequestLogEntry(): number {
  const entry = requestLog.shift();
  if (!entry) return 0;
  const bytes = requestLogEntryBytes.get(entry) ?? retainedRequestLogBytes(entry);
  requestLogEntryBytes.delete(entry);
  requestLogBytes = Math.max(0, requestLogBytes - bytes);
  return bytes;
}

function retainRequestLogEntry(entry: RequestLogEntry): void {
  const bytes = retainedRequestLogBytes(entry);
  requestLog.push(entry);
  requestLogEntryBytes.set(entry, bytes);
  requestLogBytes += bytes;
  while (requestLog.length > MAX_LOG_SIZE) removeOldestRequestLogEntry();
  enforceAppOwnedMemoryBudget();
}

export function requestLogRetainedStoreSnapshot(): RetainedStoreSnapshot {
  return {
    count: requestLog.length,
    bytes: requestLogBytes,
    evictableBytes: requestLogBytes,
    pinnedBytes: 0,
    oldestAt: requestLog[0]?.timestamp ?? null,
  };
}

export function evictOldestRequestLogForBudget(): number {
  return removeOldestRequestLogEntry();
}

function asTerminalStatus(value: string | undefined): ResponsesTerminalStatus | undefined {
  if (value === "completed" || value === "failed" || value === "incomplete") return value;
  return undefined;
}

function asCloseReason(value: string | undefined): RequestLogEntry["closeReason"] | undefined {
  switch (value) {
    case "terminal":
    case "client_cancel":
    case "non_stream":
    case "body_stall":
    case "body_overflow":
      return value;
    default:
      return undefined;
  }
}

/** Project a persisted usage.jsonl row back into the in-memory /api/logs shape. */
export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): RequestLogEntry {
  const terminalStatus = asTerminalStatus(entry.terminalStatus);
  const closeReason = asCloseReason(entry.closeReason);
  const routeDecision = normalizeRouteDecisionTraceForLog(entry.routeDecision);
  const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
  const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
  const spend = normalizeRequestSpend(entry.spend);
  const protocolTrace = parseProtocolTraceV1(entry.protocolTrace);
  // projectErrorDetail bounds the tier fields (top-level and per attempt) itself, so this stays safe
  // for a row that did not come through the disk reader; attempts are copied before it edits them.
  const attempts = Array.isArray(entry.attempts) ? entry.attempts.map(({ accountTag, ...attempt }) => ({ ...attempt,
    ...(isAnthropicAccountTag(accountTag) ? { accountTag } : {}) })) : entry.attempts;
  return projectErrorDetail({
    requestId: entry.requestId,
    ...(isLogicalRequestId(entry.logicalRequestId) ? { logicalRequestId: entry.logicalRequestId } : {}),
    timestamp: entry.timestamp,
    model: entry.model,
    provider: entry.provider,
    ...(Object.hasOwn(entry, "client") ? { client: normalizeRecordedClient(entry.client) ?? "unknown" } : {}),
    ...(entry.firstOutputMs !== undefined ? { firstOutputMs: entry.firstOutputMs } : {}),
    ...(entry.genStartMs !== undefined ? { genStartMs: entry.genStartMs } : {}),
    ...(entry.lastOutputMs !== undefined ? { lastOutputMs: entry.lastOutputMs } : {}),
    ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}), ...linkLogField(entry.link), ...requestBodyField(entry.requestBody),
    ...(entry.conversationId ? { conversationId: entry.conversationId } : {}),
    ...(isCodexUsageAccountLogLabel(entry.accountLogLabel)
      ? { accountLogLabel: entry.accountLogLabel }
      : {}),
    ...(isAnthropicAccountTag(entry.accountTag) ? { accountTag: entry.accountTag } : {}),
    ...(entry.requestedModel ? { requestedModel: entry.requestedModel } : {}),
    ...(entry.requestedAlias ? { requestedAlias: entry.requestedAlias } : {}),
    ...(entry.shadowCallRewrittenFrom
      ? { shadowCallRewrittenFrom: entry.shadowCallRewrittenFrom }
      : {}),
    ...(entry.requestedEffort ? { requestedEffort: entry.requestedEffort } : {}),
    ...(entry.effectiveEffort ? { effectiveEffort: entry.effectiveEffort } : {}),
    ...(entry.reasoningWireField ? { reasoningWireField: entry.reasoningWireField } : {}),
    ...(entry.reasoningWireValue !== undefined ? { reasoningWireValue: entry.reasoningWireValue } : {}),
    ...(entry.callerServiceTier ? { callerServiceTier: entry.callerServiceTier } : {}),
    ...(entry.requestedServiceTier ? { requestedServiceTier: entry.requestedServiceTier } : {}),
    ...(entry.requestedSpeedLabel ? { requestedSpeedLabel: entry.requestedSpeedLabel } : {}),
    ...(entry.configuredServiceTier ? { configuredServiceTier: entry.configuredServiceTier } : {}),
    ...(entry.configuredSpeedLabel ? { configuredSpeedLabel: entry.configuredSpeedLabel } : {}),
    ...(entry.modelSupportsServiceTier !== undefined
      ? { modelSupportsServiceTier: entry.modelSupportsServiceTier }
      : {}),
    ...(entry.responseServiceTier ? { responseServiceTier: entry.responseServiceTier } : {}),
    ...(entry.tierOutcome ? { tierOutcome: entry.tierOutcome } : {}),
    ...modelIdentityLogFields(entry),
    status: entry.status,
    durationMs: entry.durationMs,
    // Closed code, condition, failure detail and quota reset; legacy upstream text is read once and dropped.
    ...errorDetailFor(entry),
    ...(terminalStatus ? { terminalStatus } : {}),
    ...(closeReason ? { closeReason } : {}),
    usageStatus: entry.usageStatus,
    ...(entry.usage ? { usage: entry.usage } : {}),
    ...(entry.totalTokens !== undefined ? { totalTokens: entry.totalTokens } : {}),
    ...(attempts !== undefined ? { attempts } : {}),
    ...(entry.attemptNormalizationDropped === true
      ? { attemptNormalizationDropped: true } : {}),
    ...(spend ? { spend } : {}),
    ...(isKnownCacheTelemetryProvenance(entry.cacheProvenance)
      ? { cacheProvenance: entry.cacheProvenance }
      : {}),
    ...persistedAffinityFields(entry),
    ...persistedCacheAffinityFields(entry),
    ...(isKnownTransportPhase(entry.transportPhase) ? { transportPhase: entry.transportPhase } : {}),
    ...(isKnownTerminalSource(entry.terminalSource) ? { terminalSource: entry.terminalSource } : {}),
    ...(routeDecision ? { routeDecision } : {}),
    ...(jevDecision ? { jevDecision } : {}),
    ...(claudeCompatibility ? { claudeCompatibility } : {}),
    ...(entry.conversationStateScrub === "account-change"
      ? { conversationStateScrub: "account-change" }
      : {}),
    ...normalizeRequestFailureAttribution(entry),
    ...(protocolTrace ? { protocolTrace } : {}),
  });
}

/**
 * Affinity survived only in memory before this: `addFinalRequestLog` set it on the row and the
 * field-by-field disk projection never named it, so the move that discarded a warm prefix was
 * gone at the next restart — the same whitelist trap #4592 hit one layer up.
 */
function persistedAffinityFields(
  entry: Pick<RequestLogEntry, "affinity" | "affinityReason">,
): Pick<PersistedUsageEntry, "affinity" | "affinityReason"> {
  if (!isKnownAffinityMove(entry.affinity)) return {};
  return {
    affinity: entry.affinity,
    ...(isKnownAffinityReason(entry.affinityReason) ? { affinityReason: entry.affinityReason } : {}),
  };
}

function persistedCacheAffinityFields(
  entry: Pick<RequestLogEntry, "cacheAffinity" | "cacheAffinityReason">,
): Pick<PersistedUsageEntry, "cacheAffinity" | "cacheAffinityReason"> {
  if (!isKnownCacheAffinity(entry.cacheAffinity)) return {};
  return {
    cacheAffinity: entry.cacheAffinity,
    ...(isKnownCacheAffinityReason(entry.cacheAffinityReason) ? { cacheAffinityReason: entry.cacheAffinityReason } : {}),
  };
}

/**
 * Hydration guard: persisted traces are re-normalized before they enter the
 * in-memory ring buffer so a hand-edited or corrupt row cannot poison the DTO.
 * A row that fails validation is dropped, never forwarded unvalidated.
 */
function normalizeRouteDecisionTraceForLog(
  entry: RouteDecisionTraceV1 | undefined,
): RouteDecisionTraceV1 | null {
  return entry ? normalizeRouteDecisionTrace(entry) : null;
}

/**
 * Seed the in-memory Logs ring buffer from usage.jsonl so GUI /api/logs survives
 * `ocx stop` / `ocx start` (process restart). Idempotent per process; no-ops when
 * the buffer already has live entries. Read failures are non-fatal (same as /api/usage).
 */
export function hydrateRequestLogsFromDisk(
  reader: () => PersistedUsageEntry[] = () => readRecentUsageEntries(MAX_LOG_SIZE),
): number {
  if (requestLogsHydratedFromDisk) return 0;
  if (requestLog.length > 0) {
    requestLogsHydratedFromDisk = true;
    return 0;
  }
  try {
    const persisted = reader();
    requestLogsHydratedFromDisk = true;
    if (persisted.length === 0) return 0;
    const slice = persisted.length > MAX_LOG_SIZE
      ? persisted.slice(persisted.length - MAX_LOG_SIZE)
      : persisted;
    for (const entry of slice) retainRequestLogEntry(requestLogEntryFromPersistedUsage(entry));
    return slice.length;
  } catch (err) {
    requestLogsHydratedFromDisk = true;
    console.warn(
      `[request-log] failed to hydrate from usage.jsonl: ${err instanceof Error ? err.message : String(err)}`,
    );
    return 0;
  }
}

/**
 * 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) {
  // Rows keep proxy-owned error facts only; upstream error text and tokens stop here (both the
  // retained ring row and the usage.jsonl projection below read the projected entry).
  const attemptNormalizationDropped = entry.attemptNormalizationDropped === true, client = normalizeRecordedClient(entry.client) ?? "unknown";
  const clientDescriptor = Object.getOwnPropertyDescriptor(entry, "client");
  if (!Object.isFrozen(entry) || !clientDescriptor?.enumerable || !("value" in clientDescriptor) || clientDescriptor.value !== client || Object.values(Object.getOwnPropertyDescriptors(entry)).some(descriptor => !("value" in descriptor))) {
    entry = { ...entry, ...errorDetailFor(entry), client, ...(attemptNormalizationDropped ? { attemptNormalizationDropped: true } : {}) };
  }
  entry = projectErrorDetail(entry);
  if (attemptNormalizationDropped && entry.attemptNormalizationDropped !== true) entry = { ...entry, attemptNormalizationDropped: true };
  // Sanitize ONCE, at the ingress, and use that one value for both destinations.
  //
  // `addFinalRequestLog` is not the only way in: `addRequestLog` is exported and callable
  // directly, and it retained the caller's entry verbatim in the in-memory ring while only the
  // field-by-field disk projection below saw a sanitized value. That split let `/api/logs`
  // serve a raw upstream-supplied marker — a newline in it can forge a record boundary in a
  // line-oriented viewer — while `usage.jsonl` looked clean, which is the worst shape for a
  // sanitization bug because the safe surface is the one you check.
  const shadowCallRewrittenFrom = sanitizeLogMetadataString(entry.shadowCallRewrittenFrom);
  const identity = modelIdentityLogFields(entry), servedModel = identity.servedModel;
  const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
  const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
  const attempts = normalizedAttempts(entry.attempts);
  const attemptsDropped = Array.isArray(entry.attempts) && attempts.length < entry.attempts.length;
  const retained: RequestLogEntry = shadowCallRewrittenFrom === entry.shadowCallRewrittenFrom
    && servedModel === entry.servedModel && identity.resolvedModel === entry.resolvedModel
    && entry.claudeCompatibility === undefined
    && entry.jevDecision === undefined
    && !attemptsDropped
    ? entry
    : { ...entry, ...(entry.attemptNormalizationDropped === true || attemptsDropped ? { attemptNormalizationDropped: true } : {}),
      ...(shadowCallRewrittenFrom ? { shadowCallRewrittenFrom } : {}) };
  if (!shadowCallRewrittenFrom && retained !== entry) delete retained.shadowCallRewrittenFrom;
  if (retained !== entry) { if (!servedModel) delete retained.servedModel; if (!identity.resolvedModel) delete retained.resolvedModel; }
  if (claudeCompatibility) retained.claudeCompatibility = claudeCompatibility;
  else if (retained !== entry) delete retained.claudeCompatibility;
  if (jevDecision) retained.jevDecision = jevDecision;
  else if (retained !== entry) delete retained.jevDecision;
  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
    // in their existing shape; the >=400 gate deliberately includes 499 client-cancels.
    const failureDiagnostics = entry.status >= 400 || (entry.terminalStatus && entry.terminalStatus !== "completed")
      ? {
        ...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
        ...(entry.terminalStatus ? { terminalStatus: entry.terminalStatus } : {}),
        ...(entry.closeReason ? { closeReason: entry.closeReason } : {}),
        ...(entry.upstreamCondition ? { upstreamCondition: entry.upstreamCondition } : {}), ...(entry.failureDetail ? { failureDetail: entry.failureDetail } : {}),
        ...(entry.rateLimitResetAt !== undefined ? { rateLimitResetAt: entry.rateLimitResetAt } : {}),
      }
      : {};
    appendUsageEntry({
      requestId: entry.requestId,
      ...(isLogicalRequestId(entry.logicalRequestId) ? { logicalRequestId: entry.logicalRequestId } : {}),
      timestamp: entry.timestamp,
      provider: entry.provider,
      model: entry.model,
      client: entry.client ?? "unknown",
      ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
      // This function REBUILDS the persisted row field by field rather than
      // spreading it, so a field missing here reaches /api/logs and never
      // reaches usage.jsonl — which is where the per-key rollup reads from.
      ...(entry.apiKeyId ? { apiKeyId: entry.apiKeyId } : {}),
      ...(isKnownAdmissionKind(entry.admissionKind) ? { admissionKind: entry.admissionKind } : {}),
      ...(isKnownInboundProtocol(entry.inboundProtocol) ? { inboundProtocol: entry.inboundProtocol } : {}), ...linkLogField(entry.link), ...requestBodyField(entry.requestBody),
      ...(isCodexUsageAccountLogLabel(entry.accountLogLabel)
        ? { accountLogLabel: entry.accountLogLabel }
        : {}),
      ...(isAnthropicAccountTag(entry.accountTag) ? { accountTag: entry.accountTag } : {}),
      ...(entry.conversationId ? { conversationId: entry.conversationId } : {}),
      ...(entry.resolvedModel ? { resolvedModel: entry.resolvedModel } : {}),
      ...(entry.servedModel ? { servedModel: entry.servedModel } : {}),
      ...(entry.wireModel ? { wireModel: entry.wireModel } : {}),
      ...(entry.requestedModel ? { requestedModel: entry.requestedModel } : {}),
      ...(entry.requestedAlias ? { requestedAlias: entry.requestedAlias } : {}),
      ...(entry.shadowCallRewrittenFrom
        ? { shadowCallRewrittenFrom: entry.shadowCallRewrittenFrom }
        : {}),
      ...(entry.requestedEffort ? { requestedEffort: entry.requestedEffort } : {}),
      ...(entry.effectiveEffort ? { effectiveEffort: entry.effectiveEffort } : {}),
      ...(entry.reasoningWireField ? { reasoningWireField: entry.reasoningWireField } : {}),
      ...(entry.reasoningWireValue !== undefined ? { reasoningWireValue: entry.reasoningWireValue } : {}),
      ...(entry.callerServiceTier ? { callerServiceTier: entry.callerServiceTier } : {}),
      ...(entry.requestedServiceTier ? { requestedServiceTier: entry.requestedServiceTier } : {}),
      ...(entry.requestedSpeedLabel ? { requestedSpeedLabel: entry.requestedSpeedLabel } : {}),
      ...(entry.configuredServiceTier ? { configuredServiceTier: entry.configuredServiceTier } : {}),
      ...(entry.configuredSpeedLabel ? { configuredSpeedLabel: entry.configuredSpeedLabel } : {}),
      ...(entry.modelSupportsServiceTier !== undefined
        ? { modelSupportsServiceTier: entry.modelSupportsServiceTier }
        : {}),
      ...(entry.responseServiceTier ? { responseServiceTier: entry.responseServiceTier } : {}),
      ...(entry.tierOutcome ? { tierOutcome: entry.tierOutcome } : {}),
      status: entry.status,
      durationMs: entry.durationMs,
      ...(entry.firstOutputMs !== undefined ? { firstOutputMs: entry.firstOutputMs } : {}),
      ...(entry.genStartMs !== undefined ? { genStartMs: entry.genStartMs } : {}),
      ...(entry.lastOutputMs !== undefined ? { lastOutputMs: entry.lastOutputMs } : {}),
      usageStatus: entry.usageStatus,
      ...(entry.usage ? { usage: entry.usage } : {}),
      ...(entry.totalTokens !== undefined ? { totalTokens: entry.totalTokens } : {}),
      ...(entry.attempts !== undefined ? { attempts: entry.attempts } : {}),
    ...(entry.attemptNormalizationDropped === true
      ? { attemptNormalizationDropped: true } : {}),
      ...(entry.spend ? { spend: entry.spend } : {}),
      ...(isKnownCacheTelemetryProvenance(entry.cacheProvenance)
        ? { cacheProvenance: entry.cacheProvenance }
        : {}),
      ...persistedAffinityFields(entry),
      ...persistedCacheAffinityFields(entry),
      ...(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.jevDecision ? { jevDecision: entry.jevDecision } : {}),
      ...(entry.claudeCompatibility ? { claudeCompatibility: entry.claudeCompatibility } : {}),
      ...(entry.protocolTrace ? { protocolTrace: entry.protocolTrace } : {}),
      ...(entry.conversationStateScrub === "account-change"
        ? { conversationStateScrub: "account-change" }
        : {}),
    });
  } catch {
    /* request logging must never fail a user request */
  }
}

/** 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")}`;
}

/**
 * One-shot TTFT recorder (WP4). Records the first non-empty model output moment
 * relative to the request start, and — when a combo attempt is in flight —
 * relative to that attempt's start as well. Later calls are no-ops, so both the
 * bridge callback and the deferred SSE tap may fire without double-recording.
 */
export function recordFirstOutput(
  logCtx: RequestLogContext,
  requestStartedAt: number,
  now = Date.now(),
): void {
  if (!Number.isFinite(requestStartedAt) || !Number.isFinite(now)) return;
  const requestElapsed = Math.max(0, now - requestStartedAt);
  if (logCtx.firstOutputMs === undefined) logCtx.firstOutputMs = requestElapsed;
  if (logCtx.activeAttempt && !sealedCredentialRefusals.has(logCtx.activeAttempt) && logCtx.activeAttempt.firstOutputMs === undefined) {
    const attemptStartedAt = logCtx.activeAttemptStartedAt ?? requestStartedAt;
    logCtx.activeAttempt.firstOutputMs = Math.max(0, now - attemptStartedAt);
  }
}

/** Snapshot target-specific requested effort even for runTurn adapters with no AdapterRequest. */
export function recordAttemptRequestedEffort(logCtx: RequestLogContext): void {
  const attempt = logCtx.activeAttempt;
  if (!attempt || sealedCredentialRefusals.has(attempt)) return;
  delete attempt.requestedEffort;
  try {
    if (typeof logCtx.requestedEffort === "string" && logCtx.requestedEffort) {
      attempt.requestedEffort = redactSecretString(logCtx.requestedEffort).slice(0, 64);
    }
  } catch {
    // Request logging is best-effort and must not affect request delivery.
  }
}

/** Copy the adapter's exact outbound reasoning parameter into the durable request log. */
export function recordAdapterReasoning(
  logCtx: RequestLogContext,
  request: AdapterRequest,
): void {
  if (logCtx.activeAttempt && sealedCredentialRefusals.has(logCtx.activeAttempt)) return;
  delete logCtx.effectiveEffort;
  delete logCtx.reasoningWireField;
  delete logCtx.reasoningWireValue;
  const attempt = logCtx.activeAttempt;
  if (attempt) {
    delete attempt.effectiveEffort;
    delete attempt.reasoningWireField;
    delete attempt.reasoningWireValue;
  }
  recordAttemptRequestedEffort(logCtx);

  // Diagnostics must never make an otherwise valid upstream request fail. Config files
  // written by older versions (or edited by hand) can contain values that violate the
  // current TypeScript shape, so validate the runtime object before redacting strings.
  try {
    const raw: unknown = request.reasoningLog;
    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
    const reasoning = raw as Record<string, unknown>;
    if (typeof reasoning.effectiveEffort !== "string" || !reasoning.effectiveEffort
      || (reasoning.wireField !== "reasoning_effort"
        && reasoning.wireField !== "reasoning.enabled"
        && reasoning.wireField !== "reasoning.effort"
        && reasoning.wireField !== "thinking_budget"
        && reasoning.wireField !== "thinking.type")
      || !isValidReasoningWireValue(reasoning.wireField, reasoning.wireValue)) {
      return;
    }

    const effectiveEffort = redactSecretString(reasoning.effectiveEffort).slice(0, 64);
    const wireValue = typeof reasoning.wireValue === "string"
      ? redactSecretString(reasoning.wireValue).slice(0, 64)
      : reasoning.wireValue;
    logCtx.effectiveEffort = effectiveEffort;
    logCtx.reasoningWireField = reasoning.wireField;
    logCtx.reasoningWireValue = wireValue;
    if (attempt) {
      attempt.effectiveEffort = effectiveEffort;
      attempt.reasoningWireField = reasoning.wireField;
      attempt.reasoningWireValue = wireValue;
    }
  } catch {
    // Request logging is best-effort and must not affect request delivery.
  }
}

/** Attach the serializing adapter's tier observation to the active durable attempt. */
export function recordAdapterTier(
  logCtx: RequestLogContext,
  request: AdapterRequest,
): void {
  recordAdapterTierMetadata(logCtx, request.tierLog);
}

/** Attach adapter-owned metadata for transports that expose no AdapterRequest (runTurn). */
export function recordAdapterTierMetadata(
  logCtx: RequestLogContext,
  metadata: AdapterTierMetadata | undefined,
): void {
  if (logCtx.activeAttempt && sealedCredentialRefusals.has(logCtx.activeAttempt)) return;
  delete logCtx.tierOutcome;
  delete logCtx.activeTierMetadata;
  const attempt = logCtx.activeAttempt;
  if (attempt) delete attempt.tierOutcome;

  try {
    const outcome = metadata?.outcome;
    if (!metadata || !outcome) return;
    logCtx.tierOutcome = outcome;
    logCtx.activeTierMetadata = metadata;
    if (attempt) attempt.tierOutcome = outcome;
  } catch {
    // Request logging is best-effort and must not affect request delivery.
  }
}

export function requestLogErrorCode(
  status: number,
  upstreamError?: string,
  terminalErrorCode?: string,
  replayRefusal = false,
): string | undefined {
  if (status >= 200 && status < 400) return undefined;
  // A structured terminal code is authoritative even when the provider message is localized,
  // generic, or absent. Only preserve the one narrowly recognized policy code here: broadly
  // forwarding arbitrary upstream codes would change unrelated request-log taxonomy.
  if (isCyberPolicyCode(terminalErrorCode)) return CYBER_POLICY_ERROR_CODE;
  const classifiedCode = upstreamError?.trim()
    ? classifyError(status, "upstream_error", upstreamError).code
    : undefined;
  // Defense in depth: mid-stream web-search aborts used to land as 502 with this message.
  if (status === 499 || classifiedCode === "client_closed_request") {
    return "client_closed_request";
  }
  // Keep the high-confidence message fallback for runtimes/providers that stripped the
  // structured code before emitting response.failed.
  if (classifiedCode === CYBER_POLICY_ERROR_CODE) return CYBER_POLICY_ERROR_CODE;
  if (status === 400 || status === 409) return "invalid_request_error";
  if (status === 401) return "invalid_api_key";
  if (status === 403) {
    // Prefer message-aware codes (e.g. Ollama Cloud subscription gates) over a blunt
    // invalid_api_key — 403 usually means authenticated but not allowed.
    if (upstreamError?.trim()) {
      const code = classifyError(403, "upstream_error", upstreamError).code;
      if (code) return code;
    }
    return "permission_denied";
  }
  if (status === 429) {
    // Prefer transport provenance; retain the legacy message fallback for older callers.
    if (replayRefusal || (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}`;
}

export function requestLogSpeedLabel(serviceTier: string | undefined): string | undefined {
  const normalized = serviceTier?.trim().toLowerCase();
  if (normalized === "priority" || normalized === "fast") return "fast";
  // Ultra Fast is labelled even though nothing in the shipped catalog advertises it: the
  // reporter on #3429 reached it by hand-editing their own catalog, the request completed,
  // and the Logs column stayed empty because this returned undefined. A tier the proxy
  // forwarded but refuses to name is an observability hole, not a feature gate — the flag
  // decides whether the tier survives, not whether we admit to carrying it.
  if (normalized === "ultrafast") return "ultrafast";
  return undefined;
}

export function readConfiguredCodexServiceTier(): string | undefined {
  try {
    if (!existsSync(CODEX_CONFIG_PATH)) return undefined;
    return readRootTomlString(readFileSync(CODEX_CONFIG_PATH, "utf-8"), "service_tier") ?? undefined;
  } catch {
    return undefined;
  }
}

export function catalogModelSupportsServiceTier(modelId: string, serviceTier: string | undefined): boolean | undefined {
  if (!serviceTier) return undefined;
  const requestTier = serviceTier.trim().toLowerCase() === "fast" ? "priority" : serviceTier.trim();
  try {
    const catalogPath = readCodexCatalogPath();
    if (!existsSync(catalogPath)) return undefined;
    const catalog = JSON.parse(readFileSync(catalogPath, "utf-8")) as { models?: unknown };
    const models = Array.isArray(catalog.models) ? catalog.models : [];
    const entry = models.find(model => {
      if (!model || typeof model !== "object") return false;
      return (model as { slug?: unknown; id?: unknown }).slug === modelId
        || (model as { slug?: unknown; id?: unknown }).id === modelId;
    });
    if (!entry || typeof entry !== "object") return undefined;
    const tiers = (entry as { service_tiers?: unknown }).service_tiers;
    return Array.isArray(tiers) && tiers.some(tier => (
      tier && typeof tier === "object" && (tier as { id?: unknown }).id === requestTier
    ));
  } catch {
    return undefined;
  }
}

export function applyResponseLogMetadata(logCtx: RequestLogContext, payload: unknown, collectUsage = true): 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 = responsesCompletionError(payload) == null ? "completed" : "failed";
    } 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;
  if (!source || typeof source !== "object") return;
  recordObservedServedModel(logCtx, (source as { model?: unknown }).model);
  const serviceTier = (source as { service_tier?: unknown }).service_tier;
  if (typeof serviceTier === "string" && serviceTier.trim()) {
    const sanitized = boundedServiceTier(serviceTier);
    if (sanitized) logCtx.responseServiceTier = sanitized;
    logCtx.activeTierMetadata?.observeResponseServiceTier(serviceTier);
  } else if (Object.prototype.hasOwnProperty.call(source, "service_tier")) {
    logCtx.activeTierMetadata?.observeResponseServiceTier(serviceTier);
  }
  const usage = collectUsage && !logCtx.usageFromBridge && !logCtx.clientResponseUsage
    ? usageFromResponsesPayload((source as { usage?: unknown }).usage) : undefined;
  if (usage) {
    if (!recordKeyWireAttemptUsage(logCtx, usage)) {
      logCtx.usage = usage;
      if (logCtx.activeAttempt && !sealedCredentialRefusals.has(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.
    logCtx.usageWireParsed = true;
  }
}

export function usageFromResponsesPayload(usage: unknown): OcxUsage | undefined {
  if (!usage || typeof usage !== "object") return undefined;
  const raw = usage as {
    input_tokens?: unknown;
    output_tokens?: unknown;
    input_tokens_details?: { cached_tokens?: unknown; cache_write_tokens?: unknown; cache_write_1h_tokens?: unknown };
    output_tokens_details?: { reasoning_tokens?: unknown };
    total_tokens?: unknown;
    prompt_tokens?: unknown;
    completion_tokens?: unknown;
    prompt_tokens_details?: { cached_tokens?: unknown; cache_write_tokens?: unknown };
    completion_tokens_details?: { reasoning_tokens?: unknown };
  };
  if (typeof raw.input_tokens === "number" && typeof raw.output_tokens === "number") {
    return {
      inputTokens: raw.input_tokens,
      outputTokens: raw.output_tokens,
      ...(typeof raw.total_tokens === "number" ? { totalTokens: raw.total_tokens } : {}),
      ...(typeof raw.input_tokens_details?.cached_tokens === "number"
        ? {
            cachedInputTokens: raw.input_tokens_details.cached_tokens,
            cacheReadInputTokens: raw.input_tokens_details.cached_tokens,
          }
        : {}),
      ...(typeof raw.input_tokens_details?.cache_write_tokens === "number"
        ? { cacheCreationInputTokens: raw.input_tokens_details.cache_write_tokens }
        : {}),
      ...(typeof raw.input_tokens_details?.cache_write_1h_tokens === "number"
        ? { cacheCreation1hInputTokens: raw.input_tokens_details.cache_write_1h_tokens }
        : {}),
      ...(typeof raw.output_tokens_details?.reasoning_tokens === "number"
        ? { reasoningOutputTokens: raw.output_tokens_details.reasoning_tokens }
        : {}),
    };
  }
  if (typeof raw.prompt_tokens === "number" && typeof raw.completion_tokens === "number") {
    return {
      inputTokens: raw.prompt_tokens,
      outputTokens: raw.completion_tokens,
      ...(typeof raw.total_tokens === "number" ? { totalTokens: raw.total_tokens } : {}),
      ...(typeof raw.prompt_tokens_details?.cached_tokens === "number"
        ? {
            cachedInputTokens: raw.prompt_tokens_details.cached_tokens,
            cacheReadInputTokens: raw.prompt_tokens_details.cached_tokens,
          }
        : {}),
      ...(typeof raw.prompt_tokens_details?.cache_write_tokens === "number"
        ? { cacheCreationInputTokens: raw.prompt_tokens_details.cache_write_tokens }
        : {}),
      ...(typeof raw.completion_tokens_details?.reasoning_tokens === "number"
        ? { reasoningOutputTokens: raw.completion_tokens_details.reasoning_tokens }
        : {}),
    };
  }
  return 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.
 */
// 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";
}

export function inspectResponseLogJson(logCtx: RequestLogContext, text: string): void {
  try {
    applyResponseLogMetadata(logCtx, JSON.parse(text));
  } catch {
    logCtx.activeTierMetadata?.markResponseUnparseable();
    /* body may not be JSON; request log metadata is best-effort only */
  }
  captureUpstreamError(logCtx, text);
  if (isUsageDebugEnabled() && logCtx.usageDebugBodyKind === undefined) {
    logCtx.usageDebugBodyKind = "json";
    logCtx.usageDebugBodySample = truncateForDebug(text);
  }
}

export function inspectResponseLogSsePayload(logCtx: RequestLogContext, payload: string | null): void {
  if (!payload || payload.trim() === "[DONE]") return;
  let parsed: unknown | undefined;
  try {
    parsed = JSON.parse(payload);
  } catch {
    /* SSE block payload may not be JSON; metadata inspection is best-effort */
  }
  inspectResponseLogSsePayloadParsed(logCtx, payload, parsed);
}

/** Inspect an SSE payload using the caller's single best-effort JSON parse. */
export function inspectResponseLogSsePayloadParsed(
  logCtx: RequestLogContext,
  payload: string | null,
  parsed: unknown | undefined,
  collectUsage = true,
): void {
  if (!payload || payload.trim() === "[DONE]") return;
  const debugEnabled = isUsageDebugEnabled();
  const sseAlreadyMarked = logCtx.usageDebugBodyKind === "sse";
  if (parsed !== undefined) recordGenerationEvent(logCtx, (parsed as { type?: unknown } | null)?.type);
  if (parsed !== undefined) applyResponseLogMetadata(logCtx, parsed, collectUsage);
  else logCtx.activeTierMetadata?.markResponseUnparseable();
  captureUpstreamErrorParsed(logCtx, payload, parsed, true);
  if (debugEnabled) {
    if (!sseAlreadyMarked) {
      logCtx.usageDebugBodyKind = "sse";
      logCtx.usageDebugBodySample = truncateForDebug(payload);
    } else if (typeof logCtx.usageDebugBodySample === "string"
      && logCtx.usageDebugBodySample.length < USAGE_DEBUG_BODY_SAMPLE_BYTES) {
      const combined = `${logCtx.usageDebugBodySample}\n${payload}`;
      logCtx.usageDebugBodySample = truncateForDebug(combined);
    }
  }
}

/**
 * Capture the upstream error reason into the request log context. Codex/consumer surfaces only
 * see an HTTP-mapped error code (502 → upstream_server_error); the granular reason lives inside
 * a `response.failed` SSE payload's `error.message` (the adapter's redacted upstream message) or
 * a non-streaming JSON error body. We keep the FIRST non-empty reason (the original failure) and
 * run it through redactSecretString so secrets never reach /api/logs. Pure; safe on any text.
 */
function captureUpstreamError(logCtx: RequestLogContext, text: string | null): void {
  if (!text) return;
  let parsed: unknown | undefined;
  try {
    parsed = JSON.parse(text);
  } catch {
    /* retain the raw malformed payload for the bounded fallback below */
  }
  captureUpstreamErrorParsed(logCtx, text, parsed);
}

function captureUpstreamErrorParsed(
  logCtx: RequestLogContext,
  text: string,
  parsed: unknown | undefined, untypedSse = false,
): void {
  if (parsed !== undefined && parsed !== null) {
    const json = parsed as UpstreamErrorPayload;
    if (!captureUpstreamTerminalDiagnostics(logCtx, json, untypedSse)) return;
    const reason = json?.response?.incomplete_details?.reason;
    if (json.type === "response.incomplete"
      && logCtx.terminalIncompleteReason === undefined
      && typeof reason === "string"
      && reason.trim()) {
      logCtx.terminalIncompleteReason = reason.trim();
    }
    if (logCtx.upstreamError) return;
    const message = upstreamErrorMessageFromPayload(parsed);
    if (typeof message === "string" && message.trim()) {
      logCtx.upstreamError = guardedRowCopy(logCtx, message);
      return;
    }
    // No human-readable error message: fall back to the structured incomplete reason emitted by
    // the bridge on a stall-timeout or adapter EOF (response.incomplete). Maps the raw reason to a
    // reader-facing label so a generic 502 in /api/logs explains WHY the turn ended, not just the
    // mapped HTTP code.
    if (typeof reason === "string" && reason.trim()) {
      const incomplete = incompleteReasonDetail(reason.trim()); // A known reason also gets a closed row detail.
      logCtx.upstreamError = guardedRowCopy(logCtx, incomplete.text);
      if (incomplete.detail) logCtx.failureDetail = incomplete.detail;
    }
    return;
  }
  if (logCtx.upstreamError) return;
  const trimmed = text.trim();
  if (trimmed) {
    logCtx.upstreamError = guardedRowCopy(logCtx, trimmed);
  }
}

/** Map a terminal Responses error object to the HTTP status we record in /api/logs. */
export function httpStatusFromTerminalError(error: {
  type?: string;
  code?: string | null;
  message?: string;
} | undefined): number {
  return httpStatusFromClassifiedTerminalError(error);
}

export function httpStatusForTerminalStatus(status: ResponsesTerminalStatus): number {
  return status === "completed" ? 200 : 502;
}

export function httpStatusForRequestLogTerminal(
  status: ResponsesTerminalStatus,
  logCtx?: RequestLogContext,
): number {
  if (status === "incomplete" && (logCtx?.terminalHttpStatus === 429 || logCtx?.terminalHttpStatus === 402)) {
    return logCtx.terminalHttpStatus;
  }
  /**
   * [Decision Log]
   * - 목적과 의도: Keep request logs aligned with the successful HTTP/SSE contract.
   * - 기존 구현 및 제약 조건: All incomplete terminals were recorded as 502 even when the
   *   client-requested output limit was reached normally.
   * - 검토한 주요 대안: Treat every incomplete as success, or infer the reason from display text.
   * - 선택한 방식: Only structured max_output_tokens incompletes map to 200.
   * - 다른 대안 대신 이 방식을 선택한 이유: Stall, EOF, and unknown incompletes must remain
   *   visible failures, and display text is not a stable classification contract.
   * - 장점, 단점 및 영향: Logs stop reporting false upstream errors while retaining the
   *   incomplete terminal detail; native callers without a structured reason keep old behavior.
   */
  if (status === "incomplete" && logCtx?.terminalIncompleteReason === "max_output_tokens") {
    return 200;
  }
  if (status === "failed" && logCtx?.terminalHttpStatus !== undefined) {
    return logCtx.terminalHttpStatus;
  }
  return httpStatusForTerminalStatus(status);
}

/**
 * Aggregate one logical request's upstream spend from the rows that recorded it.
 *
 * Attempts are the accounting source and combo children are attempts of the same context, so a
 * sum over `logCtx.attempts` is the send count for one user turn — the number the amplification
 * in #4546 is measured in. A terminal status is what makes a send explainable, so the split is
 * drawn there rather than at success: a 502 is settled spend, an attempt abandoned in flight is
 * not. The budget's own counter is folded in as `reserved` because a leg that re-sent without
 * opening an attempt row is charged and unobserved, and that difference belongs in
 * `unresolved` rather than quietly inflating `settled`.
 */
export function requestSpendRecord(
  logCtx: Pick<RequestLogContext, "executionBudget" | "affinityMoveReasons" | "affinityReason" | "affinity">,
  attempts: readonly PersistedUsageAttempt[] | undefined,
): PersistedRequestSpend | undefined {
  const rows = attempts ?? [];
  const budget = logCtx.executionBudget;
  const reasons = [...new Set(
    (logCtx.affinityMoveReasons ?? (logCtx.affinity !== "unbound" && logCtx.affinityReason ? [logCtx.affinityReason] : []))
      .filter(isKnownAffinityReason),
  )];
  if (rows.length === 0 && !budget && reasons.length === 0) return undefined;
  const sends = rows.reduce((total, attempt) => total + attempt.sendCount, 0);
  const settled = rows.reduce(
    (total, attempt) => attempt.status >= 100 ? total + attempt.sendCount : total,
    0,
  );
  const charged = Math.max(sends, budget?.used ?? 0);
  return {
    sends,
    settled,
    unresolved: Math.max(0, charged - settled),
    ...(budget ? { reserved: budget.used, policyVersion: budget.policyVersion } : {}),
    ...(reasons.length > 0 ? { moveReasons: reasons } : {}),
  };
}

/**
 * Record an affinity decision so both the row's final answer and the sequence survive. A request
 * that moved for `quota_refusal` and then again for `transient` paid for two discarded prefixes,
 * and the single-valued field can only report the second.
 */
export function noteAffinityMove(
  logCtx: RequestLogContext,
  move: CodexAffinityMove,
  reason: CodexAffinityReason,
): void {
  logCtx.affinity = move;
  logCtx.affinityReason = reason;
  (logCtx.affinityMoveReasons ??= []).push(reason);
}

/**
 * Copy the selection's own affinity decision onto the request log. Both Pool-served kinds carry
 * one: a stored Pool account and the main login rotating as `main-pool` (#4546, #7799). A keyed
 * caller-owned main can also carry one. A move reads as an event with its cause.
 */
export function noteCodexSelectionAffinity(logCtx: RequestLogContext, authCtx: CodexAuthContext): void {
  const decision = authCtx.affinityDecision;
  if (!decision) return;
  logCtx.affinity = decision.move;
  logCtx.affinityReason = decision.reason;
}

/**
 * The affinity scope a released binding belonged to: one thread, one model lane.
 *
 * Both halves are part of the key. A thread holds a separate binding per model lane, so a
 * quota refusal on one lane and a transient streak on another are two releases; keyed by thread
 * alone the second overwrites the first and one of the two rows reports a cause that never
 * happened on it.
 */
export interface AffinityModelLane {
  model: string;
  /** Thread/conversation that owns the binding; omitted when the caller has no thread identity. */
  conversationId?: string;
}

/**
 * Release reasons waiting for the request that can report them (#4546, #4598).
 *
 * Bounded like the routing-side map it mirrors: this is a diagnostic, and an unbounded map keyed
 * by conversation is a leak.
 */
const pendingNoAccountReasons = new Map<string, CodexAffinityReason>();
const MAX_PENDING_NO_ACCOUNT_REASONS = 1024;

function affinityLaneKey(lane: AffinityModelLane): string {
  return `${lane.conversationId ?? ""}\u0000${lane.model}`;
}

export function noteNoAccountAffinityReason(lane: AffinityModelLane, reason: CodexAffinityReason): void {
  if (!isKnownAffinityReason(reason)) return;
  const key = affinityLaneKey(lane);
  if (!pendingNoAccountReasons.has(key) && pendingNoAccountReasons.size >= MAX_PENDING_NO_ACCOUNT_REASONS) {
    const oldest = pendingNoAccountReasons.keys().next();
    if (!oldest.done) pendingNoAccountReasons.delete(oldest.value);
  }
  pendingNoAccountReasons.set(key, reason);
}

/** Read and forget one lane's reason. Other lanes on the same thread keep theirs. */
export function takeNoAccountAffinityReason(lane: AffinityModelLane): CodexAffinityReason | undefined {
  const key = affinityLaneKey(lane);
  const reason = pendingNoAccountReasons.get(key);
  if (reason !== undefined) pendingNoAccountReasons.delete(key);
  return reason;
}

/** Test-only process-state reset for isolated harnesses. */
export function clearNoAccountAffinityReasonsForTests(): void {
  pendingNoAccountReasons.clear();
}

/**
 * Report a selection that produced no account, on the request that failed because of it.
 *
 * A no-account resolve reaches no auth context, so until now its cause was handed to whichever
 * later resolve happened to succeed — and a pool that stays exhausted never produces one, leaving
 * the failure permanently unexplained. Attaching the reason to THIS request's own record is what
 * makes the failure self-describing: the row is written, persisted and hydrated like any other,
 * and it survives a restart.
 *
 * Deliberately not a separate synthetic row. `/api/usage` counts one row as one request, so an
 * extra event row would report a request that never existed and skew the very cost totals this
 * work exists to make trustworthy.
 */
export function recordNoAccountAffinityFailure(
  logCtx: RequestLogContext,
  lane: AffinityModelLane,
  reason?: CodexAffinityReason,
): CodexAffinityReason | undefined {
  const resolved = isKnownAffinityReason(reason) ? reason : takeNoAccountAffinityReason(lane);
  if (resolved === undefined) return undefined;
  noteAffinityMove(logCtx, "cleared", resolved);
  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 || sealedCredentialRefusals.has(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;
}

type FinalRequestLogMetaArg = Pick<RequestLogEntry, "terminalStatus" | "closeReason">;
const finalRequestLogInterceptors = new WeakMap<RequestLogContext, (status: number, meta?: FinalRequestLogMetaArg) => void>();

/** Route inner final-log requests to an outer owner (native ingress) instead of writing them. */
export function interceptFinalRequestLog(logCtx: RequestLogContext, onRequest: (status: number, meta?: FinalRequestLogMetaArg) => void): void {
  finalRequestLogInterceptors.set(logCtx, onRequest);
}

/** The outer owner's write: request-level status from the outer outcome, the physical attempt's from the inner one. */
export function commitInterceptedFinalRequestLog(
  requestId: string, start: number, logCtx: RequestLogContext, status: number, meta: FinalRequestLogMetaArg | undefined,
  attemptStatus: number, addLog: (entry: RequestLogEntry) => void = addRequestLog,
): void {
  writeFinalRequestLog(requestId, start, logCtx, status, meta, addLog, attemptStatus);
}

export function addFinalRequestLog(
  requestId: string,
  start: number,
  logCtx: RequestLogContext,
  status: number,
  meta?: Pick<RequestLogEntry, "terminalStatus" | "closeReason">,
  addLog: (entry: RequestLogEntry) => void = addRequestLog,
): void {
  const intercept = finalRequestLogInterceptors.get(logCtx);
  if (intercept) { intercept(status, meta); return; }
  writeFinalRequestLog(requestId, start, logCtx, status, meta, addLog); notifyLinkTurnFinal(logCtx, meta?.terminalStatus);
}

function writeFinalRequestLog(
  requestId: string,
  start: number,
  logCtx: RequestLogContext,
  status: number,
  meta?: Pick<RequestLogEntry, "terminalStatus" | "closeReason">,
  addLog: (entry: RequestLogEntry) => void = addRequestLog,
  attemptStatus?: number,
): void {
  // Mid-stream web-search aborts used to emit response.failed and land as 502/upstream_server_error.
  // Prefer the client-close classification whenever the captured reason says so.
  // A coordinated (attemptStatus) write carries an authoritative outer outcome; skip the heuristic.
  const effectiveStatus = attemptStatus === undefined && status >= 500 && logCtx.upstreamError && isClientClosedMessage(logCtx.upstreamError)
    ? 499
    : status;
  // Locally assigned codes name proxy refusals that status and upstream text cannot reconstruct.
  const errorCode = logCtx.errorCode ?? bareVerdictRowErrorCode(logCtx) ?? requestLogErrorCode(
    effectiveStatus,
    logCtx.upstreamError,
    logCtx.terminalErrorCode,
    logCtx.causeHint === "transport-ambiguous" && logCtx.terminalSource === "synthetic",
  );
  // A response.failed whose classified status is 499 is still a client cancel, not an upstream
  // terminal failure — keep /api/logs closeReason aligned with that.
  const closeReason = effectiveStatus === 499
    ? "client_cancel"
    : meta?.closeReason;
  const sealedRefusal = retainRefusedAccount(logCtx);
  if (logCtx.activeAttempt && !sealedRefusal) {
    finishRequestAttempt(
      logCtx.activeAttempt,
      attemptStatus ?? effectiveStatus,
      Date.now() - (logCtx.activeAttemptStartedAt ?? start),
      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.
    const attemptErrorCode = attemptStatus === undefined ? errorCode : attemptStatus < 400 ? undefined
      : logCtx.errorCode ?? bareVerdictRowErrorCode(logCtx) ?? requestLogErrorCode(attemptStatus, logCtx.upstreamError, logCtx.terminalErrorCode, false);
    if (attemptErrorCode) logCtx.activeAttempt.errorCode = attemptErrorCode;
    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,
    ...(logCtx.causeHint ? { causeHint: logCtx.causeHint } : {}),
    locallyAnswered: logCtx.localTerminalReason !== undefined,
    // A coordinated write derives the request pair from a copy and re-derives the attempt's own.
    ...(logCtx.activeAttempt ? { attempt: attemptStatus === undefined ? logCtx.activeAttempt : { ...logCtx.activeAttempt } } : {}),
  });
  if (attemptStatus !== undefined && logCtx.activeAttempt && !sealedRefusal) attributePhysicalAttempt(logCtx.activeAttempt);
  // The one seam every request passes exactly once, whatever transport served it and however
  // it ended. The ledger gives per-send usage precedence over terminal usage and keeps unknown
  // physical spend unresolved.
  logCtx.spendTracker?.settle(logCtx.usage);
  const existing = finalizedUsage(
    logCtx.providerAdapter ?? logCtx.provider,
    logCtx.usage,
    logCtx.usageLogInputTokens,
    contextWindowForModel(logCtx.providerAdapter ?? logCtx.provider, logCtx.model),
    logCtx.localTerminalReason !== undefined,
  );
  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 } } : {}),
    // 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;
  // Rotations split usage across attempts. A detached recovery can be the only send, with no
  // active attempt or request-level usage. An ordinary single attempt keeps the row's usage.
  const aggregate = attempts?.length && (isCombo || (logCtx.localTerminalReason === undefined
    && (attempts.length > 1 || (!logCtx.activeAttempt && attempts[0]?.usage))))
    ? aggregateAttemptUsage(attempts)
    : null;
  const loggedUsage = aggregate?.usage ?? existing.usage;
  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 } : {}),
  });
  // Provider cache affinity: this is the one seam every request passes exactly
  // once with its terminal status, the credential that ultimately served (the
  // entry id captured beside the account label at each stamp, rotations
  // included), and cache usage already normalized from whichever adapter
  // answered. A success binds or refreshes the conversation on that
  // credential; a quota/auth terminal releases it so the next request is
  // placed fresh instead of re-offered a credential that just refused.
  finalizeProviderCacheAffinity(logCtx, effectiveStatus, logCtx.usage ?? loggedUsage);
  // 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
  // means a future caller cannot reintroduce the hole by forgetting to sanitize first, and
  // the in-memory /api/logs row matches what usage.jsonl already stores.
  const shadowCallRewrittenFrom = sanitizeLogMetadataString(logCtx.shadowCallRewrittenFrom);
  const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(logCtx.claudeCompatibility);
  const jevDecision = normalizePersistedJevDecision(logCtx.jevDecision);
  // Keyed by the live attempt objects, not the detached copies above.
  const protocolTrace = protocolTraceForRequest(logCtx, logCtx.attempts);
  // Projected before any writer (an injected one too): the row keeps only proxy-owned error facts.
  reportCommittedTerminalCooldown(logCtx, meta, attempts, effectiveStatus);
  addLog(projectErrorDetail({
    requestId,
    ...(isLogicalRequestId(logicalRequestId) ? { logicalRequestId } : {}),
    timestamp: start,
    model: isCombo ? logCtx.requestedModel! : logCtx.model,
    provider: isCombo ? "combo" : logCtx.provider,
    client: normalizeRecordedClient(logCtx.client) ?? "unknown",
    ...(logCtx.surface ? { surface: logCtx.surface } : {}),
    ...(logCtx.apiKeyId ? { apiKeyId: logCtx.apiKeyId } : {}),
    ...(logCtx.admissionKind ? { admissionKind: logCtx.admissionKind } : {}),
    ...(logCtx.inboundProtocol ? { inboundProtocol: logCtx.inboundProtocol } : {}), ...linkLogField(logCtx.link), ...requestBodyLogField(logCtx),
    ...(logCtx.localTerminalReason
      ? { localTerminalReason: sanitizeLogMetadataString(logCtx.localTerminalReason) }
      : {}),
    ...(isCodexUsageAccountLogLabel(logCtx.accountLogLabel)
      ? { accountLogLabel: logCtx.accountLogLabel }
      : {}),
    ...anthropicAccountTagField(isCombo ? undefined : logCtx.provider),
    ...(logCtx.conversationId ? { conversationId: logCtx.conversationId } : {}),
    ...(logCtx.requestedModel ? { requestedModel: logCtx.requestedModel } : {}),
    ...(logCtx.requestedAlias ? { requestedAlias: logCtx.requestedAlias } : {}),
    ...(shadowCallRewrittenFrom ? { shadowCallRewrittenFrom } : {}),
    ...(logCtx.requestedEffort ? { requestedEffort: logCtx.requestedEffort } : {}),
    ...(logCtx.effectiveEffort ? { effectiveEffort: logCtx.effectiveEffort } : {}),
    ...(logCtx.reasoningWireField ? { reasoningWireField: logCtx.reasoningWireField } : {}),
    ...(logCtx.reasoningWireValue !== undefined ? { reasoningWireValue: logCtx.reasoningWireValue } : {}),
    ...(logCtx.callerServiceTier ? { callerServiceTier: logCtx.callerServiceTier } : {}),
    ...(logCtx.requestedServiceTier ? { requestedServiceTier: logCtx.requestedServiceTier } : {}),
    ...(logCtx.requestedSpeedLabel ? { requestedSpeedLabel: logCtx.requestedSpeedLabel } : {}),
    ...(logCtx.configuredServiceTier ? { configuredServiceTier: logCtx.configuredServiceTier } : {}),
    ...(logCtx.configuredSpeedLabel ? { configuredSpeedLabel: logCtx.configuredSpeedLabel } : {}),
    ...(logCtx.modelSupportsServiceTier !== undefined ? { modelSupportsServiceTier: logCtx.modelSupportsServiceTier } : {}),
    ...(logCtx.responseServiceTier ? { responseServiceTier: logCtx.responseServiceTier } : {}),
    ...((attempts?.at(-1)?.tierOutcome ?? logCtx.tierOutcome)
      ? { tierOutcome: attempts?.at(-1)?.tierOutcome ?? { ...logCtx.tierOutcome! } }
      : {}),
    ...modelIdentityLogFields(logCtx),
    status: effectiveStatus,
    durationMs,
    ...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
    ...generationWindowFields(logCtx, start),
    ...(errorCode ? { errorCode } : {}),
    ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
    ...(closeReason ? { closeReason } : {}),
    ...(logCtx.upstreamError && !upstreamErrorIsLocal(logCtx) ? { upstreamError: logCtx.upstreamError } : {}), ...(logCtx.failureDetail ? { failureDetail: logCtx.failureDetail } : {}),
    ...(logCtx.upstreamCondition && !upstreamErrorIsLocal(logCtx) ? { upstreamCondition: logCtx.upstreamCondition } : {}),
    // A local verdict's failed frame is proxy-authored; its code/type are not upstream diagnostics.
    ...(upstreamErrorIsLocal(logCtx) ? {} : upstreamDiagnosticLogFields(logCtx)), usageStatus,
    ...(loggedUsage ? { usage: loggedUsage } : {}),
    ...(totalTokens !== undefined ? { totalTokens } : {}),
    ...(attempts !== undefined ? { attempts } : {}),
    ...(spend ? { spend } : {}),
    // "unknown" is recorded rather than omitted whenever usage exists: a row that reported tokens
    // with no cache detail at all is a different fact from a row with no usage, and the summary
    // has to refuse both as a hit-rate denominator.
    ...(loggedUsage || cacheProvenance !== "unknown" ? { cacheProvenance } : {}),
    ...(logCtx.affinity ? { affinity: logCtx.affinity } : {}),
    ...(logCtx.affinityReason ? { affinityReason: logCtx.affinityReason } : {}),
    ...(logCtx.cacheAffinity ? { cacheAffinity: logCtx.cacheAffinity } : {}),
    ...(logCtx.cacheAffinityReason ? { cacheAffinityReason: logCtx.cacheAffinityReason } : {}),
    ...(logCtx.conversationStateScrub === "account-change"
      ? { conversationStateScrub: "account-change" }
      : {}),
    ...(logCtx.transportPhase ? { transportPhase: logCtx.transportPhase } : {}),
    ...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
    ...(logCtx.routeDecision ? { routeDecision: logCtx.routeDecision } : {}),
    ...(jevDecision ? { jevDecision } : {}),
    ...(claudeCompatibility ? { claudeCompatibility } : {}),
    ...(protocolTrace ? { protocolTrace } : {}),
    ...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(),
      requestId,
      provider: logCtx.provider,
      model: logCtx.model,
      upstreamContentType: logCtx.usageDebugContentType ?? null,
      upstreamStatus: effectiveStatus,
      bodyKind: logCtx.usageDebugBodyKind ?? "none",
      bodySample: logCtx.usageDebugBodySample ?? "",
      extractedUsage: loggedUsage ?? null,
    });
  }
}

interface FinalizedUsageResult {
  usage?: OcxUsage;
  status: UsageStatus;
  totalTokens?: number;
}

/**
 * Context window for the routed model, used to cap the token estimate (codex-router PR #140):
 * a request the provider answered cannot have exceeded the window, so the estimate must never
 * claim it did. The family is picked by the route ADAPTER, not the model id alone, because
 * claude-family ids are shared between Kiro and Cursor with different windows. Kiro "auto" is
 * a router with no fixed window and is never guessed; unknown adapters/models stay uncapped.
 */
function contextWindowForModel(adapter: string, modelId: string | undefined): number | undefined {
  if (!modelId) return undefined;
  if (adapter === "kiro" || adapter.startsWith("kiro-")) {
    const normalized = normalizeKiroModelId(modelId);
    if (normalized === "auto") return undefined;
    return kiroObservedContextWindow(modelId)
      ?? modelRecordValue(KIRO_MODEL_CONTEXT_WINDOWS, modelId)
      ?? modelRecordValue(KIRO_MODEL_CONTEXT_WINDOWS, normalized);
  }
  if (adapter === "cursor" || adapter.startsWith("cursor-")) {
    return inferCursorContextWindow(modelId);
  }
  if (adapter === "devin") {
    return modelRecordValue(DEVIN_MODEL_CONTEXT_WINDOWS, modelId);
  }
  return undefined;
}

function finalizedUsage(
  adapter: string,
  usage: OcxUsage | undefined,
  inputTokenEstimate: number | undefined,
  contextWindow: number | undefined,
  locallyAnswered = false,
): FinalizedUsageResult {
  // The ESTIMATE itself is capped at the model's context window (codex-router PR #140). The
  // combined value below keeps its max(inputTokens, estimate) behavior — a provider-reported
  // positive count is never reduced by this cap, only the estimate that could substitute it.
  const estimate = typeof inputTokenEstimate === "number"
    && Number.isFinite(inputTokenEstimate)
    && inputTokenEstimate >= 0
    ? capEstimateAtContextWindow(inputTokenEstimate, contextWindow)
    : undefined;
  const finalUsage = usageForFinalLog(adapter, usage, locallyAnswered);
  const usageFallback = !finalUsage && estimate !== undefined
    ? { inputTokens: estimate, outputTokens: 0, estimated: true }
    : undefined;
  // The estimate is a floor under a count the adapter could only guess. A count the adapter read
  // off the upstream's own usage frame stays exact: max() against a larger local estimate would
  // replace it and mark it estimated.
  const combinedInputTokens = finalUsage && !finalUsage.upstreamReported && estimate !== undefined
    ? Math.max(finalUsage.inputTokens, estimate)
    : undefined;
  const loggedUsage = finalUsage && combinedInputTokens !== undefined
    ? {
        ...finalUsage,
        inputTokens: combinedInputTokens,
        totalTokens: combinedInputTokens + finalUsage.outputTokens,
        estimated: true,
      }
    : finalUsage
      // When the adapter alone produced an estimated count and no local estimate
      // exists, cap it at the context window — an adapter estimate above the window
      // misleads the usage dashboard.  The combined branch (above) already caps the
      // ESTIMATE via capEstimateAtContextWindow, and Math.max preserves a real
      // provider-reported count, so it needs no further reduction.
      ? (finalUsage.estimated && contextWindow !== undefined && finalUsage.inputTokens > contextWindow
          ? {
              ...finalUsage,
              inputTokens: contextWindow,
              totalTokens: contextWindow + finalUsage.outputTokens,
            }
          : finalUsage)
      : usageFallback;
  const totalTokens = usageTotalTokens(loggedUsage);
  return {
    status: usageStatusForFinalLog(loggedUsage),
    ...(loggedUsage ? { usage: loggedUsage } : {}),
    ...(totalTokens !== undefined ? { totalTokens } : {}),
  };
}

export function beginRequestAttempt(
  ordinal: number,
  provider: string,
  model: string,
  adapter: string,
): PersistedUsageAttempt {
  return {
    ordinal,
    provider,
    model,
    adapter,
    status: 0,
    durationMs: 0,
    sendCount: 0,
    recoveryKinds: [],
    usageStatus: "unreported",
  };
}

/** 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 || sealedCredentialRefusals.has(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,
  resolved?: { model: string; adapter: string },
): void {
  const attempt = logCtx.activeAttempt;
  const previous = attempt?.accountLogLabel;
  stampApiKeyAccountLabel(logCtx, providerName, provider);
  const next = logCtx.accountLogLabel;
  if (attempt && usesApiKeyAccount(provider)) keyUsageOwners.add(attempt);
  const recoveryStatus = credentialRecoveryStatus(recovery);
  if (attempt && attempt.sendCount > 0 && (sealedCredentialRefusals.has(attempt) || recoveryStatus !== undefined
    || attemptAccountChanged(previous, next, attempt.provider, logCtx.provider)
    || resolved && (attempt.model !== resolved.model || attempt.adapter !== resolved.adapter))) {
    if (!sealedCredentialRefusals.delete(attempt)) {
      delete attempt.inputTokenEstimate;
      finishRequestAttempt(attempt, attempt.status >= 100 ? attempt.status
        : recoveryStatus ?? (recovery === "rate-limit-429" ? 429 : 502),
      Date.now() - (logCtx.activeAttemptStartedAt ?? Date.now()), attempt.usage);
      // Finalization sees only the live segment, so attribute this refusal before snapshotting it.
      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);
    if (index >= 0) attempts.splice(index, 0, completed);
    else attempts.push(completed, attempt);
    const fresh = beginRequestAttempt(completed.ordinal + 1, providerName, completed.model, completed.adapter);
    if (completed.labRouteSubjectId && completed.provider === logCtx.provider
      && (!resolved || (completed.model === resolved.model && completed.adapter === resolved.adapter))) {
      fresh.labRouteSubjectId = completed.labRouteSubjectId;
    }
    // Effort/tier metadata describes the request and is captured before the physical send.
    for (const key of ["requestedEffort", "effectiveEffort", "reasoningWireField", "reasoningWireValue"] as const) {
      if (completed[key] !== undefined) Object.assign(fresh, { [key]: completed[key] });
    }
    // The response observer owns this live object; the sealed row keeps its snapshot.
    if (attempt.tierOutcome) fresh.tierOutcome = attempt.tierOutcome;
    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) {
    if (resolved) { attempt.model = resolved.model; attempt.adapter = resolved.adapter; }
    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. */
export function recordAttemptCredentialSource(
  attempt: PersistedUsageAttempt | undefined,
  providerName: string,
  provider: Pick<OcxProviderConfig, "authMode" | "baseUrl" | "adapter">,
  adapterName: string = provider.adapter,
): void {
  if (!attempt || sealedCredentialRefusals.has(attempt)) return;
  // Rebinding an attempt to an unrecognized route must not retain its previous attribution.
  delete attempt.credentialSource;
  if (providerName !== "xai"
    || !["openai-chat", "openai-responses"].includes(adapterName)) return;
  try {
    const url = new URL(provider.baseUrl ?? "");
    if (url.protocol !== "https:" || url.port || url.username || url.password
      || url.search || url.hash || !["/v1", "/v1/"].includes(url.pathname)) return;
    if (provider.authMode === "oauth" && url.hostname === "cli-chat-proxy.grok.com") {
      attempt.credentialSource = "grok-oauth";
    } else if ((provider.authMode === "key" || provider.authMode === undefined)
      && url.hostname === "api.x.ai") {
      attempt.credentialSource = "xai-api-key";
    }
  } catch {
    // Invalid/custom destinations have no known subscription provenance.
  }
}

export function noteAttemptSend(
  attempt: PersistedUsageAttempt | undefined,
  inputTokenEstimate: number | undefined,
  recovery?: AttemptRecoveryKind,
): void {
  if (!attempt || sealedCredentialRefusals.has(attempt)) return;
  attempt.sendCount += 1;
  if (typeof inputTokenEstimate === "number"
    && Number.isFinite(inputTokenEstimate)
    && inputTokenEstimate >= 0) {
    // Store the ESTIMATE field already capped at the model's window (codex-router PR #140):
    // what gets persisted, and later merged into usage, never claims a count above the window.
    attempt.inputTokenEstimate = capEstimateAtContextWindow(
      inputTokenEstimate,
      contextWindowForModel(attempt.adapter, attempt.model),
    );
  }
  if (recovery && !attempt.recoveryKinds.includes(recovery)) {
    attempt.recoveryKinds.push(recovery);
  }
}

export function finishRequestAttempt(
  attempt: PersistedUsageAttempt,
  status: number,
  durationMs: number,
  usage?: OcxUsage,
): PersistedUsageAttempt {
  if (sealedCredentialRefusals.has(attempt)) return attempt;
  const finalized = finalizedUsage(
    attempt.adapter,
    usage ?? attempt.usage,
    attempt.inputTokenEstimate,
    contextWindowForModel(attempt.adapter, attempt.model),
    attempt.locallyAnswered === true,
  );
  attempt.status = status;
  attempt.durationMs = Math.max(0, durationMs);
  attempt.usageStatus = finalized.status;
  if (finalized.usage) attempt.usage = finalized.usage;
  else delete attempt.usage;
  if (finalized.totalTokens !== undefined) attempt.totalTokens = finalized.totalTokens;
  else delete attempt.totalTokens;
  const errorCode = requestLogErrorCode(status);
  if (errorCode) attempt.errorCode = errorCode;
  else delete attempt.errorCode;
  return attempt;
}

export function getRequestLogEntries(): RequestLogEntry[] { return requestLog; }

/** Test-only process-state reset for isolated integration harnesses. */
export function clearRequestLogsForTests(): void {
  requestLog.length = 0;
  requestLogBytes = 0;
  requestLogsHydratedFromDisk = false;
  requestLogObserversForTests.clear();
}
