@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/server/management/route-registry.ts

@@ -38,8 +38,17 @@ export type ExemptionReason =
   | "test-seam"
   /** The CLI reaches the same data through a local transport instead of HTTP. */
   | "local-transport"
+  /** Machine scrape target whose HTTP exposition is the operator contract. */
+  | "scrape-target"
   /** Older clients use this alias; the current CLI drives its declared replacement. */
   | "compatibility-alias"
+  /**
+   * A read-only POST whose purpose is to bind an interactive confirmation to the mutation that
+   * immediately follows it. There is no standalone thing for a CLI to do with one: the plan is
+   * only meaningful to the caller that is about to commit it, and a scripted caller drives the
+   * mutation directly.
+   */
+  | "interactive-preview"
   /** Unreachable in the live dispatch order; delete rather than expose. */
   | "dead"
   /**
@@ -159,6 +168,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
   { method: "DELETE", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside history deletion uses the dashboard journal cleanup; the CLI has history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
+  { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/preview", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode", exempt: { reason: "interactive-preview", why: "Plans one Aside profile's change so a dashboard confirmation can show what would change and bind to it. Read-only, and useful only to the caller about to commit; a scripted caller drives the profile toggle or restore directly." } },
   { method: "DELETE", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside profile history deletion uses the dashboard journal cleanup; the CLI has scoped history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/restore", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode" },
   // server/management/codex-prompt-routes
@@ -197,6 +207,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: false },
   { method: "DELETE", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Retiring one rollback row is a dashboard-local cleanup; the CLI verb that would drive it is owed by a later work-phase and is not implemented here.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/restore", module: "server/management/integration-routes", mutates: true },
+  { method: "POST", path: "/api/client-integrations/preview", module: "server/management/integration-routes", mutates: false, exempt: { reason: "interactive-preview", why: "Plans an apply, overwrite or disable so a dashboard confirmation can show what would change and bind to it. Read-only, and useful only to the caller about to commit; a scripted caller drives PUT /api/client-integrations/{clientId} directly." } },
+  { method: "POST", path: "/api/client-integrations/restore/preview", module: "server/management/integration-routes", mutates: false, exempt: { reason: "interactive-preview", why: "Plans an undo so drift is shown before a restore rather than discovered by a rejected mutation. Read-only, and useful only to the caller about to commit; a scripted caller drives POST /api/client-integrations/restore directly." } },
   // server/management/lab-automation-routes
   { method: "GET", path: "/api/lab/automation", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
   { method: "GET", path: "/api/lab/automation/runs", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
@@ -234,6 +246,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/storage/trash/restore", module: "server/management/logs-usage-routes", mutates: true },
   { method: "PUT", path: "/api/debug", module: "server/management/logs-usage-routes", mutates: true },
   { method: "PUT", path: "/api/storage/cleanup-policy", module: "server/management/logs-usage-routes", mutates: true },
+  // server/management/metrics-routes
+  { method: "GET", path: "/api/metrics", module: "server/management/metrics-routes", mutates: false, exempt: { reason: "scrape-target", why: "This machine scrape target exposes authenticated text exposition for monitoring systems; a CLI JSON verb would be a different contract." } },
   // server/management/model-routes
   { method: "GET", path: "/api/aliases", module: "server/management/model-routes", mutates: false },
   { method: "GET", path: "/api/catalog", module: "server/management/model-routes", mutates: false },

package/src/server/management/shared.ts

@@ -245,12 +245,19 @@ export function requestLogDto(
  * share the same fetch, the same per-provider cache (dedups Codex's frequent /v1/models polling),
  * and the same stale fallback when a provider blips, instead of a parallel uncached copy.
  */
-export async function fetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
+export async function fetchAllModels(
+  config: OcxConfig,
+  /** Filled with each provider's content revision as of the moment its rows were chosen. */
+  providerContentRevisions?: Map<string, string>,
+): Promise<CatalogModel[]> {
   const { gatherRoutedModels } = await import("../../codex/catalog");
   const baseline = captureInitialSelectionBaseline(config);
-  if (!baseline) return gatherRoutedModels(config);
+  if (!baseline) return gatherRoutedModels(config, providerContentRevisions ? { providerContentRevisions } : undefined);
   const outcomes: Array<{ provider: string; state: "authoritative" | "degraded" }> = [];
-  const models = await gatherRoutedModels(config, { providerModelOutcomes: outcomes });
+  const models = await gatherRoutedModels(config, {
+    providerModelOutcomes: outcomes,
+    ...(providerContentRevisions ? { providerContentRevisions } : {}),
+  });
   finalizeInitialModelSelection(config, baseline, uniqueCatalogModelsForPublicList(models),
     outcomes.filter(outcome => outcome.state === "authoritative").map(outcome => outcome.provider));
   return models;

package/src/server/management/system-restart.ts

@@ -36,6 +36,7 @@ import { isServiceViable } from "../../service";
 import { readRuntimePort } from "../../config/process-state";
 import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
 import { selfLaunchArgv } from "../../lib/self-launch-argv";
+import { spendLedgerRestartEnvironment } from "../../lib/spend-ledger-owner";
 import {
   MEMORY_DRAIN_RESTART_MS,
   REPLACEMENT_READY_TIMEOUT_MS,
@@ -225,8 +226,12 @@ function spawnDetachedStart(
   return new Promise<void>((resolve, reject) => {
     let child: ReturnType<typeof spawn>;
     try {
-      const env: NodeJS.ProcessEnv = { ...process.env };
-      delete env.OCX_SERVICE;
+      const sourceEnv: NodeJS.ProcessEnv = { ...process.env };
+      delete sourceEnv.OCX_SERVICE;
+      const env = spendLedgerRestartEnvironment(
+        sourceEnv,
+        waitForHealthBeforeParentExit ? undefined : process.pid,
+      );
       child = spawn(process.execPath, launchArgs, {
         detached: true,
         stdio: "ignore",

package/src/server/management/system-routes.ts

@@ -39,6 +39,7 @@ import {
 } from "../../lib/codex-restart-contract";
 import { jsonResponse } from "../auth-cors";
 import { getInspectionCounters } from "../relay";
+import { spendLedgerDiagnosticsSnapshot } from "../../lib/spend-reservation-ledger";
 import type {
   performCodexRestart,
   readCodexAppServerState,
@@ -60,6 +61,7 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
       version,
       uptime: process.uptime(),
       pid: process.pid,
+      spendLedger: spendLedgerDiagnosticsSnapshot(),
     });
   }
   if (url.pathname === "/api/system/memory" && req.method === "GET") {

package/src/server/management/usage-aggregate-cache.ts

@@ -66,6 +66,7 @@ const pinnedAggregates = new Set<RetainedUsageAggregate>();
 let baseFlight: Promise<UsageAggregateResult> | null = null;
 const filteredFlights = new Map<string, Promise<UsageAggregateResult>>();
 const retainedFilteredAggregates = new Map<string, RetainedUsageAggregate>();
+const MAX_CONCURRENT_FILTERED_AGGREGATES = 4;
 
 function currentTimeZone(): string {
   return Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -283,6 +284,9 @@ export async function getFilteredUsageAggregate(filter: {
   ]);
   const existing = filteredFlights.get(key);
   if (existing) return existing;
+  if (filteredFlights.size >= MAX_CONCURRENT_FILTERED_AGGREGATES) {
+    throw new Error("too many concurrent filtered usage aggregates");
+  }
 
   const flight = refreshFilteredAggregate(key, normalizedFilter, fixedWindow);
   filteredFlights.set(key, flight);

package/src/server/management-api.ts

@@ -63,6 +63,7 @@ import { handleLogsUsageRoutes } from "./management/logs-usage-routes";
 import { handleStorageLogGuardRoutes } from "./management/storage-log-guard-routes";
 import { handleRequestHistoryRoutes } from "./management/request-history-routes";
 import { handleRoutingAnalyticsRoutes } from "./management/routing-analytics-routes";
+import { handleMetricsRoutes } from "./management/metrics-routes";
 import { handleProviderRoutes } from "./management/provider-routes";
 import { handleModelRoutes } from "./management/model-routes";
 import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
@@ -276,6 +277,7 @@ export async function handleManagementAPI(
     ??     (await handleQuotaResetRoutesOnDemand(ctx))
     ??     (await handleWorkflowBudgetRoutesOnDemand(ctx))
     ??     (await handleGrokCouponRoutesOnDemand(ctx))
+    ??     handleMetricsRoutes(ctx)
     ??     (await handleRoutingAnalyticsRoutes(ctx))
     ??     (await handleRoutingProfileRoutesOnDemand(ctx))
     ??     (await handleProviderRoutes(ctx))

package/src/server/management-auth.ts

@@ -12,7 +12,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { adminApiTokenFilePath } from "../lib/admin-secrets";
+import { adminApiTokenFilePath, opencodeCatalogToken } from "../lib/admin-secrets";
 import {
   LOCAL_MANAGEMENT_CAPABILITY_HEADER,
   LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER,
@@ -297,6 +297,7 @@ export function createManagementSessionControl(state: ManagementAuthState): Mana
  */
 export type ManagementPrincipal =
   | "admin-token"
+  | "opencode-catalog-token"
   | "gui-session"
   | "gui-pair-capability"
   | "local-read-capability"
@@ -484,6 +485,16 @@ function requestManagementCredential(req: Request): string | null {
     || null;
 }
 
+function isOpencodeCatalogRequest(req: Request): boolean {
+  if (req.method !== "GET") return false;
+  try {
+    const url = new URL(req.url);
+    return url.pathname === "/api/models" && url.search === "";
+  } catch {
+    return false;
+  }
+}
+
 function resolveManagementAdmission(
   req: Request,
   state: ManagementAuthState,
@@ -500,6 +511,9 @@ function resolveManagementAdmission(
   else if (state.available) {
     const actual = requestManagementCredential(req);
     if (actual && equalSecret(actual, state.token)) principal = "admin-token";
+    else if (actual && isOpencodeCatalogRequest(req) && equalSecret(actual, opencodeCatalogToken(state.token))) {
+      principal = "opencode-catalog-token";
+    }
     else if (config && authorizeGuiSessionRequest(req, config, state).ok) principal = "gui-session";
   }
   if (principal) admittedManagementRequests.set(req, principal);

package/src/server/readiness.ts

@@ -3,10 +3,30 @@
  *
  * `GET /healthz` answers "is the process alive and serving HTTP?" the instant the
  * listener binds. Readiness is stricter: the proxy is "ready" only after the
- * post-startup Codex catalog/config sync (`syncModelsToCodex`) has settled with
- * `ok=true` and no catalog-sync warning. Until then the process is live (Codex can
- * open a socket) but not ready (a request would race the sync or hit a stale
- * catalog), so clients should back off.
+ * post-startup Codex catalog/config sync (`syncModelsToCodex`) has SETTLED and
+ * reported `ok=true`. Until it settles the process is live (Codex can open a
+ * socket) but not ready — a request would race the sync — so clients back off.
+ *
+ * What readiness is NOT (#5181): it is not a verdict on the local Codex client's
+ * artifacts. A nonempty `warning` used to be terminal here, which made a
+ * degradation of files written into the local Codex home permanently un-ready a
+ * proxy that was serving every other provider correctly. In a single-replica
+ * Kubernetes deployment that removed the only Service endpoint.
+ *
+ * `ok` and `warning` are separate fields in the sync result because they answer
+ * separate questions, and the gate must not conflate them. `ok` is the sync's own
+ * verdict on whether the essential work — config injection, and the write
+ * admission that precedes it — succeeded. `warning` names a degradation the sync
+ * itself decided to continue past: no catalog source so Codex keeps its native
+ * catalog, combos omitted from the catalog, a conversation-history relabel left
+ * to Codex's own writer, or a caught catalog-refresh exception after which
+ * injection still runs and still reports its own `ok`. None of those stops this
+ * process from accepting HTTP or routing to a provider, so none of them may close
+ * the gate.
+ *
+ * That boundary is not new, only extended: the Claude Code roster reconciliation
+ * in `src/cli/claude-agent-startup-sync.ts` already delays the ready transition
+ * without being allowed to fail it, on the same reasoning.
  *
  * Design contract (per P1 review):
  *  - NO module-global mutable state. Each `startServer` invocation gets its own
@@ -65,8 +85,11 @@ export interface SyncOutcomeLike {
 
 /**
  * Drive the gate from the post-startup sync. Awaits `syncFn`; the gate goes to
- * `ready` ONLY on `ok=true` with no nonempty warning. A throw, `null`, `ok=false`,
- * or a nonempty warning transitions to `failed`. Used directly by `handleStart`
+ * `ready` on `ok=true`. A throw, `null`, or `ok !== true` transitions to
+ * `failed`; a nonempty `warning` does not, because the sync that produced it
+ * still reported the essential work done (see the file header, #5181). A throw
+ * and `null` stay terminal because neither is a classified outcome: the startup
+ * path did not reach a verdict, so the gate cannot claim one. Used by `handleStart`
  * so the startup transition is unit-testable without spawning the proxy. Returns
  * the raw sync outcome so a caller that also needs the #1046 write flags (did the
  * sync actually write the catalog/cache?) can keep them without a second call.
@@ -90,10 +113,6 @@ export async function runStartupReadinessSync(
     gate.markFailed();
     return result;
   }
-  if (result.warning !== undefined && result.warning !== "") {
-    gate.markFailed();
-    return result;
-  }
   gate.markReady();
   return result;
 }

package/src/server/relay-eager.ts

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

package/src/server/relay.ts

@@ -5,6 +5,9 @@ import {
   CYBER_POLICY_FALLBACK_MESSAGE,
   isCyberPolicyCode,
   isCyberPolicyMessage,
+  isTerminalRefusalCode,
+  safetyRefusalCodeFromMessage,
+  terminalRefusalFallbackMessage,
   upstreamErrorMessageFromPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
@@ -150,16 +153,61 @@ export function failedTailFrame(encoder: TextEncoder, err: unknown): Uint8Array
   return encoder.encode(`\n\nevent: response.failed\ndata: ${payload}\n\n${DONE_SSE_FRAME_TEXT}`);
 }
 
-export function upstreamErrorTailFrame(encoder: TextEncoder, message: string): Uint8Array {
+/**
+ * Close a turn the upstream ended without a Responses terminal.
+ *
+ * `refusalCode` carries the upstream's own verdict when it gave one. Codex
+ * classifies this terminal by `error.code` alone and retries everything outside
+ * its fatal set (codex-rs/codex-api/src/sse/responses.rs:423-450), so stamping
+ * `upstream_server_error` on a refusal delivered it as a retryable disconnect
+ * and drove the reconnect loop in #5176. Without a refusal code the terminal is
+ * unchanged: a genuine transport failure stays retryable, which is what it is.
+ */
+export function upstreamErrorTailFrame(
+  encoder: TextEncoder,
+  message: string,
+  refusalCode?: string,
+): Uint8Array {
+  return encoder.encode(
+    `event: response.failed\ndata: ${upstreamErrorFailedPayload(message, refusalCode)}\n\n`,
+  );
+}
+
+function upstreamErrorFailedPayload(message: string, refusalCode?: string): string {
   const error = {
-    type: "upstream_error",
-    code: "upstream_server_error",
+    type: refusalCode === undefined ? "upstream_error" : "invalid_request_error",
+    code: refusalCode ?? "upstream_server_error",
     message: redactSecretString(message).slice(0, MAX_TAIL_ERROR_MESSAGE_CHARS),
   };
-  return encoder.encode(`event: response.failed\ndata: ${JSON.stringify({
+  return JSON.stringify({
     type: "response.failed",
-    response: { status: "failed", error, last_error: error },
-  })}\n\n`);
+    response: {
+      status: "failed",
+      error,
+      last_error: error,
+      ...(refusalCode === undefined ? {} : { retryable: false }),
+    },
+  });
+}
+
+/**
+ * Terminal for a read that failed after the upstream had already refused.
+ *
+ * Framed exactly like {@link failedTailFrame} — leading blank line to close a
+ * partial block, then the sentinel — but carrying the refusal instead of the
+ * generic reset. The refusal is the real outcome of the turn and the socket
+ * teardown that followed it is not, so reporting `upstream_reset` here would
+ * restart a turn the upstream has already ended (#5176).
+ */
+export function refusalFailedTailFrame(
+  encoder: TextEncoder,
+  message: string,
+  refusalCode: string,
+): Uint8Array {
+  const payload = upstreamErrorFailedPayload(message, refusalCode);
+  return encoder.encode(
+    `\n\nevent: response.failed\ndata: ${payload}\n\n${DONE_SSE_FRAME_TEXT}`,
+  );
 }
 
 function boundedBareUpstreamErrorMessage(payload: unknown): string | undefined {
@@ -169,12 +217,57 @@ function boundedBareUpstreamErrorMessage(payload: unknown): string | undefined {
   return message ? redactSecretString(message).slice(0, MAX_TAIL_ERROR_MESSAGE_CHARS) : undefined;
 }
 
+/**
+ * A bare upstream `error` event reduced to what the synthesized terminal needs.
+ *
+ * The structured code is authoritative whenever the upstream sent one: a code
+ * that is not a refusal means the upstream did not refuse, whatever its
+ * diagnostic text happens to quote. Recognized refusal copy is read only when
+ * no code was carried anywhere on the event, which is the shape #5176 reports.
+ * A refusal code with no message still yields a terminal, because Codex accepts
+ * that shape and supplies its own copy for it.
+ *
+ * The candidate topology mirrors {@link upstreamErrorMessageFromPayload}: code
+ * and message must be read from the same places, or an event whose message is
+ * nested under `response.error` would contribute text while its verdict went
+ * unseen.
+ */
+function boundedBareUpstreamError(payload: unknown): {
+  message: string;
+  refusalCode: string | undefined;
+} | undefined {
+  const root = asJsonRecord(payload);
+  if (!root || root.type !== "error") return undefined;
+  const message = boundedBareUpstreamErrorMessage(payload);
+  const response = asJsonRecord(root.response);
+  // Precedence is {@link upstreamErrorMessageFromPayload}'s, so the envelope
+  // that supplied the message also supplies the verdict. Taking the FIRST code
+  // rather than searching for a refusal is what stops a refusal nested below a
+  // transient one from overruling it.
+  const code = [
+    asJsonRecord(root.error),
+    asJsonRecord(root.last_error),
+    asJsonRecord(response?.error),
+    asJsonRecord(response?.incomplete_details),
+    root,
+  ]
+    .map(candidate => stringField(candidate, "code"))
+    .find(candidate => candidate !== undefined);
+  const refusalCode = code !== undefined
+    ? (isTerminalRefusalCode(code) ? code : undefined)
+    : message === undefined ? undefined : safetyRefusalCodeFromMessage(message);
+  if (message !== undefined) return { message, refusalCode };
+  if (refusalCode === undefined) return undefined;
+  return { message: terminalRefusalFallbackMessage(refusalCode), refusalCode };
+}
+
 export type SseTerminalOutputBoundary = {
   feed(chunk: Uint8Array): Uint8Array;
   finish(): Uint8Array;
   terminalSeen(): boolean;
   doneSeen(): boolean;
   upstreamError(): string | undefined;
+  upstreamRefusalCode(): string | undefined;
   dispose(): void;
 };
 
@@ -197,6 +290,7 @@ export function createSseTerminalOutputBoundary(
   let pendingDone: { block: Uint8Array; delimiter: Uint8Array } | null = null;
   let disposed = false;
   let upstreamError: string | undefined;
+  let upstreamRefusalCode: string | undefined;
 
   const processFrames = (
     frames: ReturnType<BoundedSseFrameBuffer["feed"]>,
@@ -210,8 +304,11 @@ export function createSseTerminalOutputBoundary(
       const parsed = payload === null ? undefined : parseSsePayload(payload);
       // Observe on the client reader itself: a tee inspection branch may lag
       // behind EOF, so its log context cannot determine the outgoing terminal.
-      const message = boundedBareUpstreamErrorMessage(parsed);
-      if (message !== undefined) upstreamError = message;
+      const bare = boundedBareUpstreamError(parsed);
+      if (bare !== undefined) {
+        upstreamError = bare.message;
+        upstreamRefusalCode = bare.refusalCode;
+      }
       const safetyBuffering = dropSafetyBuffering && parsed !== undefined
         ? codexSafetyBufferingBlockAction(parsed) : "keep";
       if (safetyBuffering === "drop") continue;
@@ -278,6 +375,7 @@ export function createSseTerminalOutputBoundary(
     terminalSeen: () => terminal,
     doneSeen: () => done,
     upstreamError: () => upstreamError,
+    upstreamRefusalCode: () => upstreamRefusalCode,
     dispose() {
       if (disposed) return;
       disposed = true;
@@ -349,7 +447,11 @@ export function relaySseWithFailedTail(
               const upstreamError = terminalBoundary.upstreamError() ?? opts?.upstreamError;
               controller.enqueue(upstreamError === undefined
                 ? adapterEofIncompleteFrame(encoder)
-                : upstreamErrorTailFrame(encoder, upstreamError));
+                : upstreamErrorTailFrame(
+                  encoder,
+                  upstreamError,
+                  terminalBoundary.upstreamRefusalCode(),
+                ));
               controller.enqueue(doneFrame(encoder));
             }
             terminalBoundary.dispose();
@@ -378,7 +480,11 @@ export function relaySseWithFailedTail(
             if (!terminalBoundary.doneSeen()) controller.enqueue(doneFrame(encoder));
           } else {
             // Leading blank line terminates a partial SSE block so the failed frame parses cleanly.
-            controller.enqueue(failedTailFrame(encoder, err));
+            const refusalCode = terminalBoundary.upstreamRefusalCode();
+            const refusalMessage = terminalBoundary.upstreamError();
+            controller.enqueue(refusalCode !== undefined && refusalMessage !== undefined
+              ? refusalFailedTailFrame(encoder, refusalMessage, refusalCode)
+              : failedTailFrame(encoder, err));
           }
           controller.close();
         } catch { /* client already torn down */ }
@@ -720,6 +826,9 @@ export function responseWithDeferredRequestLog(
           // convention for a client cancellation or upstream read failure.
           const status = reason === "cancel" ? 499 : reason === "read_error" ? 502 : response.status;
           addFinalRequestLog(requestId, start, logCtx, status, {
+            ...(reason === "eof" && logCtx.observedTerminalStatus
+              ? { terminalStatus: logCtx.observedTerminalStatus }
+              : {}),
             closeReason: reason === "cancel" ? "client_cancel" : "non_stream",
           }, addLog);
         },

package/src/server/request-log.ts

@@ -12,6 +12,7 @@ import {
   isCyberPolicyCode,
   isCyberPolicyMessage,
   isRateLimitOrQuotaFailureMessage,
+  isUpstreamResetReplayRefusedMessage,
   upstreamErrorMessageFromPayload,
 } from "../lib/errors";
 import { CODEX_CONFIG_PATH, readRootTomlString } from "../codex/paths";
@@ -22,6 +23,7 @@ import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routi
 import type { AdapterRequest } from "../adapters/base";
 import type { RequestSpendSettlement } from "./responses/request-spend";
 import type { AdapterTierMetadata } from "../providers/fastwire";
+import { UPSTREAM_RESET_REPLAY_REFUSED_CODE } from "../lib/upstream-retry";
 import { redactSecretString, sanitizeLogMetadataString } from "../lib/redact";
 import {
   appendUsageEntry,
@@ -67,10 +69,15 @@ import { inferCursorContextWindow } from "../adapters/cursor/discovery";
 import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
 import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
 import { modelRecordValue } from "../reasoning-effort";
+import type { RequestMetricsRecorder } from "./request-metrics";
 
 export interface RequestLogContext {
   model: string;
   provider: string;
+  /** Optional process-lifetime aggregate sink, injected by the server composition owner. */
+  requestMetricsRecorder?: RequestMetricsRecorder;
+  /** Bounded terminal enum observed while inspecting a buffered response body. */
+  observedTerminalStatus?: ResponsesTerminalStatus;
   /**
    * Identity of the ONE logical request this context serves (#4546). Set from the execution
    * budget minted at ingress; a retry leg, a repair refetch and a combo child share it.
@@ -291,6 +298,7 @@ export interface RequestLogEntry {
 }
 
 const requestLog: RequestLogEntry[] = [];
+const requestLogObserversForTests = new Set<(entry: RequestLogEntry) => void>();
 const MAX_LOG_SIZE = 2000;
 const requestLogEntryBytes = new WeakMap<RequestLogEntry, number>();
 let requestLogBytes = 0;
@@ -491,6 +499,9 @@ export function addRequestLog(entry: RequestLogEntry) {
   else if (retained !== entry) delete retained.claudeCompatibility;
   entry = retained;
   retainRequestLogEntry(entry);
+  for (const observer of requestLogObserversForTests) {
+    try { observer(entry); } catch { /* test observation must never fail request logging */ }
+  }
   try {
     // Failure diagnostics survive the 200-entry ring buffer by riding the persisted
     // usage entry (devlog/_plan/260716_claudecode_hardening/030). Success rows stay
@@ -566,6 +577,12 @@ export function addRequestLog(entry: RequestLogEntry) {
   }
 }
 
+/** Test-only finalized-row observation without polling the management projection. */
+export function observeRequestLogsForTests(observer: (entry: RequestLogEntry) => void): () => void {
+  requestLogObserversForTests.add(observer);
+  return () => { requestLogObserversForTests.delete(observer); };
+}
+
 export function nextRequestLogId(_timestamp = Date.now()): string {
   return `ocx-${randomBytes(16).toString("hex")}`;
 }
@@ -714,7 +731,15 @@ export function requestLogErrorCode(
     }
     return "permission_denied";
   }
-  if (status === 429) return "rate_limit_exceeded";
+  if (status === 429) {
+    // A refused ambiguous reset answers 429 by design (it must not invite a client
+    // retry that could duplicate inference); classify it by its message so the log
+    // distinguishes a proxy refusal from provider throttling.
+    if (upstreamError?.trim() && isUpstreamResetReplayRefusedMessage(upstreamError)) {
+      return UPSTREAM_RESET_REPLAY_REFUSED_CODE;
+    }
+    return "rate_limit_exceeded";
+  }
   if (status === 503) return "server_is_overloaded";
   if (status >= 500) return "upstream_server_error";
   return `http_${status}`;
@@ -766,6 +791,22 @@ export function catalogModelSupportsServiceTier(modelId: string, serviceTier: st
 
 export function applyResponseLogMetadata(logCtx: RequestLogContext, payload: unknown): void {
   if (!payload || typeof payload !== "object") return;
+  if (logCtx.observedTerminalStatus === undefined) {
+    const eventType = (payload as { type?: unknown }).type;
+    const response = (payload as { response?: unknown }).response;
+    const responseStatus = response && typeof response === "object"
+      ? (response as { status?: unknown }).status
+      : (payload as { status?: unknown }).status;
+    if (eventType === "response.completed") {
+      logCtx.observedTerminalStatus = "completed";
+    } else if (eventType === "response.failed") {
+      logCtx.observedTerminalStatus = "failed";
+    } else if (eventType === "response.incomplete") {
+      logCtx.observedTerminalStatus = "incomplete";
+    } else if (responseStatus === "completed" || responseStatus === "failed" || responseStatus === "incomplete") {
+      logCtx.observedTerminalStatus = responseStatus;
+    }
+  }
   const source = "response" in payload && typeof (payload as { response?: unknown }).response === "object"
     ? (payload as { response?: unknown }).response
     : payload;
@@ -1317,6 +1358,17 @@ export function addFinalRequestLog(
   const usageStatus = aggregate?.status ?? existing.status;
   const totalTokens = aggregate?.totalTokens ?? existing.totalTokens;
   const spend = requestSpendRecord(logCtx, attempts);
+  const durationMs = Date.now() - start;
+  logCtx.requestMetricsRecorder?.recordFinalRequest({
+    ...(logCtx.inboundProtocol ? { protocol: logCtx.inboundProtocol } : {}),
+    status: effectiveStatus,
+    durationMs,
+    ...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
+    ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
+    ...(closeReason ? { closeReason } : {}),
+    ...(attempts !== undefined ? { attempts } : {}),
+    ...(spend ? { spendSends: spend.sends } : {}),
+  });
   const cacheProvenance = classifyCacheTelemetryProvenance(loggedUsage, {
     wireParsed: logCtx.usageWireParsed === true,
   });
@@ -1364,7 +1416,7 @@ export function addFinalRequestLog(
       : {}),
     ...(logCtx.resolvedModel ? { resolvedModel: logCtx.resolvedModel } : {}),
     status: effectiveStatus,
-    durationMs: Date.now() - start,
+    durationMs,
     ...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
     ...(errorCode ? { errorCode } : {}),
     ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
@@ -1809,4 +1861,5 @@ export function clearRequestLogsForTests(): void {
   requestLog.length = 0;
   requestLogBytes = 0;
   requestLogsHydratedFromDisk = false;
+  requestLogObserversForTests.clear();
 }