@bitkyc08/opencodex 2.60.0 → 2.61.0

package/src/server/management/shared.ts

@@ -35,12 +35,13 @@ import { clearThreadAccountMap } from "../../codex/routing";
 import { primeCodexPoolQuotas } from "../../codex/auth-api";
 import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
 import { resolveCodexHomeDir } from "../../codex/home";
-import { readUsageEntries } from "../../usage/log";
+import { isKnownRequestFailureCause, isKnownRequestFailureStage, readUsageEntries } from "../../usage/log";
 import { getUsageDebugLogEntries } from "../../usage/debug";
 import { cacheObservationFromUsage, parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
 import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
 import { getDebugLogEntries } from "../../lib/debug-log-buffer";
+import { resendPermission } from "../../lib/request-failure-model";
 import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
 import {
   clearDebugSettings,
@@ -210,12 +211,27 @@ export function costResult(entry: MetricSource): CostResult {
  * a Logs-page metric, and widening a separate endpoint's response shape is not this change's
  * business. Flipping it on later is one argument.
  */
+
+/**
+ * Whether this proxy could have sent the row again, derived at READ time from the stage and
+ * cause the recorder stored.
+ *
+ * Deliberately not persisted. The verdict is a function of two tables that this build owns, and
+ * a row written months ago must not be able to assert a permission the current tables would
+ * refuse -- the whole point of INV-RESEND-01 is that the refusal rules are one statement, and a
+ * stored verdict would be a second one with no way to correct it.
+ */
+function resendVerdict(row: { failureStage?: string; failureCause?: string }): { resendPermission?: string } {
+  if (!isKnownRequestFailureStage(row.failureStage) || !isKnownRequestFailureCause(row.failureCause)) return {};
+  return { resendPermission: resendPermission(row.failureStage, row.failureCause) };
+}
 export function requestLogDto(
   entry: RequestLogEntry,
   { includeDecodeRate = true }: { includeDecodeRate?: boolean } = {},
 ): Record<string, unknown> {
   return {
     ...entry,
+    ...resendVerdict(entry),
     displayMetrics: {
       tokPerSecond: tokPerSecondResult(entry),
       // The parent uses the REQUEST's own TTFT. A combo parent must not borrow an attempt's,
@@ -227,6 +243,7 @@ export function requestLogDto(
       ? {
         attempts: entry.attempts.map(attempt => ({
           ...attempt,
+          ...resendVerdict(attempt),
           displayMetrics: {
             tokPerSecond: tokPerSecondResult(attempt),
             // Each attempt measures its own attempt-relative TTFT.

package/src/server/management/usage-timeline-routes.ts

@@ -0,0 +1,44 @@
+import { readUsageSnapshotForManagement } from "../../usage/log";
+import { createTimelineAccumulator, parseTimelineQuery } from "../../usage/timeline";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+const TIMELINE_CACHE_TTL_MS = 15_000;
+const cache = new Map<string, { expiresAt: number; promise: Promise<ReturnType<ReturnType<typeof createTimelineAccumulator>["finish"]>> }>();
+
+export async function handleUsageTimelineRoutes(ctx: ManagementContext): Promise<Response | undefined> {
+  const { req, url } = ctx;
+  if (url.pathname !== "/api/usage/timeline" || req.method !== "GET") return undefined;
+  const query = parseTimelineQuery(url.searchParams, Date.now());
+  if ("error" in query) return jsonResponse(query, 400, req, ctx.config);
+  const bucketMs = query.bucketMinutes * 60_000;
+  const roundedNow = Math.floor(query.now / bucketMs) * bucketMs;
+  const normalized = { ...query, now: roundedNow };
+  const key = JSON.stringify(normalized);
+  const current = Date.now();
+  const cached = cache.get(key);
+  if (cached && cached.expiresAt > current) return jsonResponse(await cached.promise, 200, req, ctx.config);
+  let promise: Promise<ReturnType<ReturnType<typeof createTimelineAccumulator>["finish"]>>;
+  promise = (async () => {
+    const accumulator = createTimelineAccumulator(normalized);
+    const snapshot = await readUsageSnapshotForManagement(ctx.config.managementUsageMaxReadBytes);
+    for (const entry of snapshot.entries) accumulator.add(entry);
+    return {
+      ...accumulator.finish(),
+      truncated: snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated,
+    };
+  })().catch(error => {
+    const entry = cache.get(key);
+    if (entry?.promise === promise) cache.delete(key);
+    throw error;
+  });
+  cache.set(key, { expiresAt: current + TIMELINE_CACHE_TTL_MS, promise });
+  try {
+    return jsonResponse(await promise, 200, req, ctx.config);
+  } finally {
+    setTimeout(() => {
+      const entry = cache.get(key);
+      if (entry?.promise === promise && entry.expiresAt <= Date.now()) cache.delete(key);
+    }, TIMELINE_CACHE_TTL_MS + 1);
+  }
+}

package/src/server/management-api.ts

@@ -1,6 +1,5 @@
 import { remoteWorkspaceEnabled } from "../remote-control/workspace-activation";
 import { randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../codex/catalog";
 import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nativeModelRows, uniqueCatalogModelsForPublicList } from "../codex/catalog";
 import {
@@ -71,6 +70,8 @@ import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
 import { handleComboRoutes } from "./management/combo-routes";
 import { handleSystemRoutes } from "./management/system-routes";
 import { handleSidebarRoutes } from "./management/sidebar-routes";
+import { handleUsageTimelineRoutes } from "./management/usage-timeline-routes";
+import { handleCompanionRoutes } from "./management/companion-routes";
 import { handleCodexPromptRoutes } from "./management/codex-prompt-routes";
 import { handleIntegrationRoutes } from "./management/integration-routes";
 import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
@@ -84,15 +85,11 @@ import type { CatalogDisposition, ConvergeCodex } from "../codex/convergence-typ
 import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
 import { managementBodyTooLargeResponse } from "./management/body";
 import { handleSessionRoutes } from "./management/session-routes";
+import { packageVersion } from "../lib/package-version";
 
 // installed npm version instead of a stale hardcode.
-export const VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string;
-  } catch {
-    return "0.0.0";
-  }
-})();
+const MANAGEMENT_VERSION_FALLBACK = "0.0.0";
+export const VERSION = packageVersion(MANAGEMENT_VERSION_FALLBACK);
 
 const managementConvergenceBindings = new WeakMap<object, Readonly<{
   factory: (config: Readonly<OcxConfig>) => ConvergeCodex;
@@ -266,7 +263,7 @@ export async function handleManagementAPI(
     } catch { /* best-effort */ }
   }
   const ctx: ManagementContext = { req, url, config, deps, version: VERSION, principal, sessionControl, convergeCodexCatalog, syncClaudeAgentDefsBestEffort };
-  let routed: Response | null;
+  let routed: Response | null | undefined;
   try {
     routed = handleSessionRoutes(ctx)
     ??     (await handleRemoteWorkspaceRoutesOnDemand(ctx))
@@ -291,6 +288,8 @@ export async function handleManagementAPI(
     ??     (await handleComboRoutes(ctx))
     ??     (await handleSystemRoutes(ctx))
     ??     (await handleLabRoutesOnDemand(ctx))
+      ?? (await handleUsageTimelineRoutes(ctx))
+      ?? (await handleCompanionRoutes(ctx))
       ?? (await handleSidebarRoutes(ctx));
   } catch (error) {
     const tooLarge = managementBodyTooLargeResponse(error, req, config);

package/src/server/proxy-liveness.ts

@@ -32,6 +32,8 @@ export interface HealthzIdentity {
   guiPairCapability?: unknown;
 }
 
+export type EndpointLiveness = "live" | "dead" | "unknown";
+
 export interface LivenessIo {
   fetchFn?: typeof fetch;
   readPidFn?: () => number | null;
@@ -85,6 +87,11 @@ export const START_OWNERSHIP_LIVENESS: Pick<LivenessIo, "timeoutMs" | "attempts"
   attempts: 3,
 };
 
+type LivenessFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
 export interface LiveProxy {
   pid: number | null;
   port: number;
@@ -148,6 +155,74 @@ export function isOpencodexHealthz(body: HealthzIdentity | null): boolean {
   return body.status === "ok" && typeof body.version === "string" && typeof body.uptime === "number";
 }
 
+/**
+ * "Nothing is listening" is narrower than "the probe failed". Only a connect-phase refusal
+ * proves the endpoint is free; a timeout, reset, or other transport failure leaves the
+ * question open.
+ */
+export function isConnectionRefused(error: unknown): boolean {
+  const visit = (current: unknown, depth: number): boolean => {
+    if (depth >= 4) return false;
+    if (current === null || (typeof current !== "object" && typeof current !== "function")) return false;
+    const record = current as { code?: unknown; cause?: unknown; errors?: unknown };
+    if (record.code === "ECONNREFUSED" || record.code === "ConnectionRefused") return true;
+    if (typeof record.code === "string" && record.code.endsWith("ECONNREFUSED")) return true;
+    if (Array.isArray(record.errors) && record.errors.length > 0) {
+      // One connect attempt fanned out over several addresses reports a single AggregateError.
+      // Only a unanimous refusal proves the endpoint is free: a bundle that mixes ECONNREFUSED
+      // with a timeout means one address answered nothing at all, and an address whose state is
+      // unreadable is unknown, not absence. Collapsing it to "refused" is how a second runtime
+      // gets started on a port that already has one.
+      return record.errors.every(error => visit(error, depth + 1));
+    }
+    return visit(record.cause, depth + 1);
+  };
+  return visit(error, 0);
+}
+
+async function classifyHealthz(
+  url: string,
+  fetchFn: LivenessFetch,
+  timeoutMs: number,
+): Promise<EndpointLiveness> {
+  try {
+    const response = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status !== 200) return "unknown";
+    const body = (await response.json().catch(() => undefined)) as HealthzIdentity | null | undefined;
+    if (body === undefined) return "unknown";
+    return isOpencodexHealthz(body) ? "live" : "dead";
+  } catch (error) {
+    return isConnectionRefused(error) ? "dead" : "unknown";
+  }
+}
+
+/**
+ * Tri-state probe of one endpoint, the in-process counterpart of
+ * `src/update/proxy-liveness-probe.mjs`. Only a connect-phase refusal or a clean 200 that is
+ * not ours proves "dead"; a timeout, reset, non-200 or unreadable body leaves the question
+ * open. Loopback endpoints are checked on both IPv4 and IPv6 because a listener may bind only
+ * one family. Runs in-process because a compiled standalone binary cannot fork `execPath -e`.
+ */
+export async function probeEndpointLiveness(
+  endpoint: { port: number; hostname?: string },
+  io: Pick<LivenessIo, "fetchFn" | "timeoutMs"> = {},
+): Promise<EndpointLiveness> {
+  if (!Number.isFinite(endpoint.port) || endpoint.port <= 0 || endpoint.port > 65535) return "dead";
+  const fetchFn = io.fetchFn ?? directLocalHttpFetch;
+  const timeoutMs = io.timeoutMs ?? 1500;
+  let sawUnknown = false;
+  for (const hostname of loopbackProbeHosts(endpoint.hostname)) {
+    const result = await classifyHealthz(
+      `http://${hostname}:${endpoint.port}/healthz`,
+      fetchFn,
+      timeoutMs,
+    );
+    if (result === "live") return "live";
+    if (result === "unknown") sawUnknown = true;
+  }
+  return sawUnknown ? "unknown" : "dead";
+}
+
 /** Identity-checked /healthz probe; null when unreachable, non-OK, or not our proxy. */
 export async function proxyIdentityAt(
   port: number,

package/src/server/relay.ts

@@ -12,6 +12,7 @@ import {
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
+import { carryReplayRefusal } from "../lib/upstream-retry";
 import { isUsageDebugEnabled } from "../usage/debug";
 import {
   addRequestLog,
@@ -833,11 +834,14 @@ export function responseWithDeferredRequestLog(
           }, addLog);
         },
       });
-      return new Response(body, {
+      // Logging re-wraps the response, and an in-process verdict does not survive a re-wrap on
+      // its own. A replay refusal that lost it here would read to a later quota recorder or
+      // Retry-After synthesizer as a 429 some upstream produced.
+      return carryReplayRefusal(response, new Response(body, {
         status: response.status,
         statusText: response.statusText,
         headers: response.headers,
-      });
+      }));
     }
     if (isUsageDebugEnabled() && logCtx.usageDebugBodyKind === undefined) {
       logCtx.usageDebugBodyKind = response.body ? "other" : "none";
@@ -989,6 +993,14 @@ export type SseInspectorHandlers = {
    * with an empty `output`.
    */
   onParsedPayload?: (payload: unknown) => void;
+  /**
+   * A complete data payload that did not parse as a JSON event, `[DONE]` included.
+   *
+   * An inspector that only hears about parsed events cannot tell "nothing has been emitted"
+   * from "something was emitted that I could not read", and a replay decision needs that
+   * difference: an unreadable payload is a payload the caller may already have seen.
+   */
+  onOpaquePayload?: () => void;
   onFirstOutput?: () => void;
   /**
    * Provider-scoped compatibility: persist the completed snapshot under the
@@ -1177,6 +1189,11 @@ export function createSseInspector(handlers: SseInspectorHandlers): SseInspector
     if (handlers.onParsedPayload && parsed !== undefined) {
       try { handlers.onParsedPayload(parsed); } catch { /* inspection must never throw into the pump */ }
     }
+    // The other half of the same observation. A payload that did not parse still reached the
+    // caller, so a consumer deciding whether anything has been emitted has to hear about it.
+    if (handlers.onOpaquePayload && parsed === undefined) {
+      try { handlers.onOpaquePayload(); } catch { /* inspection must never throw into the pump */ }
+    }
     reportFirstOutput.parsed(parsed);
     const status = terminalStatusFromParsed(parsed);
     const policyTerminal = status === "failed"

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

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

package/src/server/request-log.ts

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