@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/server/request-metrics.ts

@@ -0,0 +1,298 @@
+import type { ResponsesTerminalStatus } from "../bridge";
+import type { AttemptRecoveryKind } from "../usage/log";
+import {
+  REQUEST_FAILURE_CAUSES,
+  type RequestFailureCause,
+  causeForRecoveryKind,
+} from "../lib/request-failure-model";
+import {
+  REQUEST_OUTCOME_CLASSES,
+  classifyRequestOutcome,
+  type RequestOutcomeClass,
+} from "../usage/request-outcome";
+
+export const REQUEST_METRICS_PROTOCOLS = Object.freeze(["responses", "chat", "messages", "unknown"] as const);
+/**
+ * The exporter's result label set IS the shared outcome vocabulary, not a copy of it. Restating
+ * these four strings here is what let the exporter and the dashboard drift into disagreeing about
+ * the same request.
+ */
+export const REQUEST_METRICS_RESULTS = REQUEST_OUTCOME_CLASSES;
+/**
+ * Closed recovery classes exported as Prometheus label values.
+ *
+ * Bounded by construction: the label can only ever take one of these strings, so no user, model,
+ * account or request identifier can reach a series name. `quota`, `policy` and `ciphertext` are
+ * separate members because an operator seeing a spike needs to know which one it is -- waiting
+ * out a rate limit, changing accounts, changing the prompt and dropping stale ciphertext are
+ * four different responses, and collapsing them is what made the existing counter unactionable.
+ */
+export const REQUEST_METRICS_RECOVERY_CLASSES = Object.freeze([
+  "transient",
+  "connection",
+  "credential",
+  "rate_limit",
+  "quota",
+  "policy",
+  "ciphertext",
+  "payload",
+  "empty_completion",
+  "effort_downgrade",
+  "other",
+] as const);
+
+export const REQUEST_DURATION_BUCKETS_SECONDS = Object.freeze([0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60] as const);
+export const REQUEST_TTFT_BUCKETS_SECONDS = Object.freeze([0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30] as const);
+
+/**
+ * The failure-cause label set IS the shared dictionary, for the same reason the result label set
+ * is the shared outcome vocabulary: a restated copy is what let two surfaces drift into
+ * disagreeing about the same request.
+ *
+ * It labels a COUNTER and never a histogram. Fifteen causes across four protocols is sixty
+ * series, fixed for the lifetime of the roster, and every value comes from a frozen list, so no
+ * user, model, account or request identifier can reach a series name. A histogram labelled by
+ * cause would multiply that by its bucket count for no question anyone asks.
+ */
+export const REQUEST_METRICS_FAILURE_CAUSES = REQUEST_FAILURE_CAUSES;
+
+export type RequestMetricsProtocol = typeof REQUEST_METRICS_PROTOCOLS[number];
+export type RequestMetricsResult = RequestOutcomeClass;
+export type RequestMetricsRecoveryClass = typeof REQUEST_METRICS_RECOVERY_CLASSES[number];
+
+export interface RequestMetricFinalFact {
+  protocol?: "responses" | "chat" | "messages";
+  status: number;
+  durationMs: number;
+  firstOutputMs?: number;
+  terminalStatus?: ResponsesTerminalStatus;
+  closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow";
+  attempts?: ReadonlyArray<{
+    sendCount: number;
+    recoveryKinds: readonly AttemptRecoveryKind[];
+  }>;
+  spendSends?: number;
+  /**
+   * Why this request failed, as the recorder derived it. Absent when it did not fail, which is
+   * why the counter below cannot be reconstructed by subtracting completions from totals.
+   */
+  failureCause?: RequestFailureCause;
+}
+
+export interface RequestMetricsRecorder {
+  recordFinalRequest(fact: RequestMetricFinalFact): void;
+}
+
+export interface RequestMetricsSnapshotter {
+  snapshot(): string;
+}
+
+export interface RequestMetricsOwner extends RequestMetricsRecorder, RequestMetricsSnapshotter {
+  resetForTests(): void;
+}
+
+interface HistogramCell {
+  buckets: number[];
+  count: number;
+  sum: number;
+}
+
+const protocolCell = (value: RequestMetricsProtocol): number => REQUEST_METRICS_PROTOCOLS.indexOf(value);
+const resultCell = (value: RequestMetricsResult): number => REQUEST_METRICS_RESULTS.indexOf(value);
+const recoveryCell = (value: RequestMetricsRecoveryClass): number => REQUEST_METRICS_RECOVERY_CLASSES.indexOf(value);
+const failureCauseCell = (value: RequestFailureCause): number => REQUEST_METRICS_FAILURE_CAUSES.indexOf(value);
+
+function matrix(rows: number, columns: number): number[][] {
+  return Array.from({ length: rows }, () => Array.from({ length: columns }, () => 0));
+}
+
+function histograms(bounds: readonly number[]): HistogramCell[][] {
+  return Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => (
+    Array.from({ length: REQUEST_METRICS_RESULTS.length }, () => ({
+      buckets: Array.from({ length: bounds.length + 1 }, () => 0),
+      count: 0,
+      sum: 0,
+    }))
+  ));
+}
+
+/**
+ * Metrics class for each shared failure cause.
+ *
+ * Keyed on the cause rather than on the recovery kind so this projection and the durable log
+ * speak one vocabulary. Total by construction: the previous switch ended in `default: "other"`,
+ * which meant a recovery kind added later compiled cleanly and then disappeared into an
+ * unactionable bucket. A missing member is now a typecheck failure.
+ */
+const CAUSE_METRICS_CLASS = {
+  "transport-unsent": "connection",
+  "transport-ambiguous": "connection",
+  "upstream-declined": "transient",
+  "rate-limit": "rate_limit",
+  "quota-exhausted": "quota",
+  "credential-rejected": "credential",
+  "policy-refusal": "policy",
+  "parameter-rejected": "effort_downgrade",
+  "ciphertext-refusal": "ciphertext",
+  "payload-too-large": "payload",
+  "payload-rejected": "payload",
+  "upstream-fault": "transient",
+  "empty-output": "empty_completion",
+  "client-cancelled": "other",
+  "local-refusal": "other",
+} as const satisfies Record<RequestFailureCause, RequestMetricsRecoveryClass>;
+
+function recoveryClass(kind: AttemptRecoveryKind): RequestMetricsRecoveryClass {
+  return CAUSE_METRICS_CLASS[causeForRecoveryKind(kind)];
+}
+
+function observeHistogram(cell: HistogramCell, bounds: readonly number[], value: number): void {
+  if (!Number.isFinite(value) || value < 0) return;
+  cell.count += 1;
+  cell.sum += value;
+  for (let index = 0; index < bounds.length; index += 1) {
+    if (value <= bounds[index]!) cell.buckets[index]! += 1;
+  }
+  cell.buckets[bounds.length]! += 1;
+}
+
+function sampleLabels(protocol: RequestMetricsProtocol, result?: RequestMetricsResult): string {
+  return result === undefined
+    ? `{protocol="${protocol}"}`
+    : `{protocol="${protocol}",result="${result}"}`;
+}
+
+function appendHistogram(
+  lines: string[],
+  name: string,
+  help: string,
+  values: HistogramCell[][],
+  bounds: readonly number[],
+): void {
+  lines.push(`# HELP ${name} ${help}`, `# TYPE ${name} histogram`);
+  for (const protocol of REQUEST_METRICS_PROTOCOLS) {
+    for (const result of REQUEST_METRICS_RESULTS) {
+      const cell = values[protocolCell(protocol)]![resultCell(result)]!;
+      for (let index = 0; index < bounds.length; index += 1) {
+        lines.push(`${name}_bucket{protocol="${protocol}",result="${result}",le="${bounds[index]}"} ${cell.buckets[index]}`);
+      }
+      lines.push(`${name}_bucket{protocol="${protocol}",result="${result}",le="+Inf"} ${cell.buckets[bounds.length]}`);
+      lines.push(`${name}_sum${sampleLabels(protocol, result)} ${cell.sum}`);
+      lines.push(`${name}_count${sampleLabels(protocol, result)} ${cell.count}`);
+    }
+  }
+}
+
+export function createRequestMetricsOwner(
+  processStartTimeSeconds = Date.now() / 1000,
+): RequestMetricsOwner {
+  let logicalRequests = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
+  let physicalSends = Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => 0);
+  let recoveries = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RECOVERY_CLASSES.length);
+  let failureCauses = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_FAILURE_CAUSES.length);
+  let durations = histograms(REQUEST_DURATION_BUCKETS_SECONDS);
+  let ttft = histograms(REQUEST_TTFT_BUCKETS_SECONDS);
+  let missingTtft = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
+
+  return {
+    recordFinalRequest(fact): void {
+      const protocol: RequestMetricsProtocol = fact.protocol ?? "unknown";
+      const result = classifyRequestOutcome(fact);
+      const protocolIndex = protocolCell(protocol);
+      const resultIndex = resultCell(result);
+      logicalRequests[protocolIndex]![resultIndex]! += 1;
+
+      const attempts = fact.attempts;
+      const sends = attempts === undefined
+        ? (Number.isInteger(fact.spendSends) && fact.spendSends! >= 0 ? fact.spendSends! : 0)
+        : attempts.reduce((total, attempt) => (
+          Number.isInteger(attempt.sendCount) && attempt.sendCount >= 0 ? total + attempt.sendCount : total
+        ), 0);
+      physicalSends[protocolIndex]! += sends;
+
+      // Counted from the cause the recorder derived, not re-derived here. Two derivations of one
+      // answer is the disagreement this batch exists to remove, and the recorder is the only
+      // place that sees the transport facts a cause needs.
+      if (fact.failureCause !== undefined) {
+        failureCauses[protocolIndex]![failureCauseCell(fact.failureCause)]! += 1;
+      }
+
+      for (const attempt of attempts ?? []) {
+        for (const kind of new Set(attempt.recoveryKinds)) {
+          recoveries[protocolIndex]![recoveryCell(recoveryClass(kind))]! += 1;
+        }
+      }
+
+      observeHistogram(durations[protocolIndex]![resultIndex]!, REQUEST_DURATION_BUCKETS_SECONDS, fact.durationMs / 1000);
+      if (typeof fact.firstOutputMs === "number" && Number.isFinite(fact.firstOutputMs) && fact.firstOutputMs >= 0) {
+        observeHistogram(ttft[protocolIndex]![resultIndex]!, REQUEST_TTFT_BUCKETS_SECONDS, fact.firstOutputMs / 1000);
+      } else {
+        missingTtft[protocolIndex]![resultIndex]! += 1;
+      }
+    },
+
+    snapshot(): string {
+      const lines: string[] = [
+        "# HELP opencodex_logical_requests_total Finalized logical requests in this process.",
+        "# TYPE opencodex_logical_requests_total counter",
+      ];
+      for (const protocol of REQUEST_METRICS_PROTOCOLS) {
+        for (const result of REQUEST_METRICS_RESULTS) {
+          lines.push(`opencodex_logical_requests_total${sampleLabels(protocol, result)} ${logicalRequests[protocolCell(protocol)]![resultCell(result)]}`);
+        }
+      }
+      lines.push(
+        "# HELP opencodex_physical_sends_total Upstream sends made by finalized logical requests in this process.",
+        "# TYPE opencodex_physical_sends_total counter",
+      );
+      for (const protocol of REQUEST_METRICS_PROTOCOLS) {
+        lines.push(`opencodex_physical_sends_total${sampleLabels(protocol)} ${physicalSends[protocolCell(protocol)]}`);
+      }
+      lines.push(
+        "# HELP opencodex_recoveries_total Distinct recovery kinds observed per physical attempt in this process.",
+        "# TYPE opencodex_recoveries_total counter",
+      );
+      for (const protocol of REQUEST_METRICS_PROTOCOLS) {
+        for (const recovery of REQUEST_METRICS_RECOVERY_CLASSES) {
+          lines.push(`opencodex_recoveries_total{protocol="${protocol}",recovery="${recovery}"} ${recoveries[protocolCell(protocol)]![recoveryCell(recovery)]}`);
+        }
+      }
+      lines.push(
+        "# HELP opencodex_request_failures_total Finalized logical requests that did not deliver an answer, by derived cause.",
+        "# TYPE opencodex_request_failures_total counter",
+      );
+      for (const protocol of REQUEST_METRICS_PROTOCOLS) {
+        for (const cause of REQUEST_METRICS_FAILURE_CAUSES) {
+          lines.push(`opencodex_request_failures_total{protocol="${protocol}",cause="${cause}"} ${failureCauses[protocolCell(protocol)]![failureCauseCell(cause)]}`);
+        }
+      }
+      appendHistogram(lines, "opencodex_request_duration_seconds", "Finalized logical request duration in seconds.", durations, REQUEST_DURATION_BUCKETS_SECONDS);
+      appendHistogram(lines, "opencodex_ttft_seconds", "Observed time to first output in seconds.", ttft, REQUEST_TTFT_BUCKETS_SECONDS);
+      lines.push(
+        "# HELP opencodex_ttft_missing_total Finalized logical requests without an observed time to first output.",
+        "# TYPE opencodex_ttft_missing_total counter",
+      );
+      for (const protocol of REQUEST_METRICS_PROTOCOLS) {
+        for (const result of REQUEST_METRICS_RESULTS) {
+          lines.push(`opencodex_ttft_missing_total${sampleLabels(protocol, result)} ${missingTtft[protocolCell(protocol)]![resultCell(result)]}`);
+        }
+      }
+      lines.push(
+        "# HELP opencodex_metrics_process_start_time_seconds Unix time when this process metrics owner started.",
+        "# TYPE opencodex_metrics_process_start_time_seconds gauge",
+        `opencodex_metrics_process_start_time_seconds ${processStartTimeSeconds}`,
+      );
+      return `${lines.join("\n")}\n`;
+    },
+
+    resetForTests(): void {
+      logicalRequests = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
+      physicalSends = Array.from({ length: REQUEST_METRICS_PROTOCOLS.length }, () => 0);
+      recoveries = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RECOVERY_CLASSES.length);
+      failureCauses = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_FAILURE_CAUSES.length);
+      durations = histograms(REQUEST_DURATION_BUCKETS_SECONDS);
+      ttft = histograms(REQUEST_TTFT_BUCKETS_SECONDS);
+      missingTtft = matrix(REQUEST_METRICS_PROTOCOLS.length, REQUEST_METRICS_RESULTS.length);
+    },
+  };
+}

package/src/server/responses/adapter-continuation.ts

@@ -338,7 +338,7 @@ export function createAdapterContinuations(
           route.provider = rotated;
           invalidateSameTargetRequest();
           transportState.activeAdapter = resolveSelectionAdapter(
-            resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire),
+            resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
             config.cacheRetention,
           );
           bindRouteReasoningReplayScope({
@@ -384,7 +384,7 @@ export function createAdapterContinuations(
             invalidateSameTargetRequest();
             logCtx.provider = formatAnthropicProviderForLog("anthropic", admitted.accountId, config);
             transportState.activeAdapter = resolveSelectionAdapter(
-              resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire),
+              resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
               config.cacheRetention,
             );
             sealRequestAttemptIdentity(logCtx.activeAttempt, logCtx.provider, transportState.activeAdapter.name, logCtx.accountLogLabel);
@@ -449,7 +449,7 @@ export function createAdapterContinuations(
             if (applied) {
               invalidateSameTargetRequest();
               transportState.activeAdapter = resolveSelectionAdapter(
-                resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire),
+                resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
                 config.cacheRetention,
               );
               bindRouteReasoningReplayScope({

package/src/server/responses/adapter-dispatch.ts

@@ -246,7 +246,11 @@ export async function prepareAdapterExchange(
     return new Response(JSON.stringify(json), { headers: { "Content-Type": "application/json" } });
   }
   try {
-    initialRequest = await transportState.activeAdapter.buildRequest(parsed, { headers: requestState.selectedForwardHeaders, translatorBudget });
+    initialRequest = await transportState.activeAdapter.buildRequest(parsed, {
+      headers: requestState.selectedForwardHeaders,
+      translatorBudget,
+      abortSignal: upstream.signal,
+    });
     refreshRequestToolAliases(initialRequest);
     recordAdapterReasoning(logCtx, initialRequest);
     recordAdapterTier(logCtx, initialRequest);
@@ -405,6 +409,7 @@ export async function prepareAdapterExchange(
           retryRequest = await transportState.activeAdapter.buildRequest(parsed, {
             headers: requestState.selectedForwardHeaders,
             translatorBudget,
+            abortSignal: upstream.signal,
             ...(transportState.imageTierBias > 0 ? { imageTierBias: transportState.imageTierBias } : {}),
           });
           recordAdapterReasoning(logCtx, retryRequest);
@@ -581,7 +586,7 @@ export async function prepareAdapterExchange(
         route.provider = refreshedProvider;
         invalidateSameTargetRequest();
         transportState.activeAdapter = resolveSelectionAdapter(
-          resolveWireProtocolOverride(route.providerName, route.modelId, refreshedProvider, inboundWire),
+          resolveWireProtocolOverride(route.providerName, route.modelId, refreshedProvider, inboundWire, route.staticPolicy),
           config.cacheRetention,
         );
         bindRouteReasoningReplayScope({
@@ -614,7 +619,7 @@ export async function prepareAdapterExchange(
         route.provider = rotated;
         invalidateSameTargetRequest();
         transportState.activeAdapter = resolveSelectionAdapter(
-          resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire),
+          resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
           config.cacheRetention,
         );
         bindRouteReasoningReplayScope({
@@ -714,7 +719,7 @@ export async function prepareAdapterExchange(
         route.provider = rotated;
         invalidateSameTargetRequest();
         transportState.activeAdapter = resolveSelectionAdapter(
-          resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire),
+          resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
           config.cacheRetention,
         );
         bindRouteReasoningReplayScope({
@@ -757,7 +762,7 @@ export async function prepareAdapterExchange(
           invalidateSameTargetRequest();
           logCtx.provider = formatAnthropicProviderForLog("anthropic", admitted.accountId, config);
           transportState.activeAdapter = resolveSelectionAdapter(
-            resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire),
+            resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
             config.cacheRetention,
           );
           sealRequestAttemptIdentity(logCtx.activeAttempt, logCtx.provider, transportState.activeAdapter.name, logCtx.accountLogLabel);
@@ -832,7 +837,7 @@ export async function prepareAdapterExchange(
           }
           invalidateSameTargetRequest();
           transportState.activeAdapter = resolveSelectionAdapter(
-            resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire),
+            resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
             config.cacheRetention,
           );
           sealRequestAttemptIdentity(logCtx.activeAttempt, logCtx.provider, transportState.activeAdapter.name, logCtx.accountLogLabel);

package/src/server/responses/codex-ws-wire.ts

@@ -4,7 +4,8 @@ import {
   UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
   UPSTREAM_NO_RESPONSE_CODE,
 } from "../../lib/upstream-retry";
-import { readFileSync } from "node:fs";
+import type { RequestFailureCause, RequestFailureStage } from "../../lib/request-failure-model";
+import { packageVersion } from "../../lib/package-version";
 // If the 101 never arrives (network black hole), give SSE a chance well before
 // the caller's connect timeout (default 200s) would fire.
 export const UPGRADE_DEADLINE_MS = 10_000;
@@ -72,13 +73,7 @@ export function markCodexWsResponse(response: Response, observed: boolean): void
  * importing management-api from the transport layer would invert the
  * layering and pull the management surface into every WS exchange.
  */
-const OCX_VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8")).version as string;
-  } catch {
-    return "0.0.0";
-  }
-})();
+const OCX_VERSION = packageVersion("0.0.0");
 
 /**
  * The durable form of the stage counters, carried out of the exchange on the
@@ -210,6 +205,37 @@ export function classifyCodexWsFailure(stage: CodexWsFailureStage): CodexWsFailu
   return "no-response-event";
 }
 
+/**
+ * The same four outcomes said in the shared stage-and-cause vocabulary (#4191).
+ *
+ * A projection, not a second classifier: {@link classifyCodexWsFailure} stays the one place that
+ * reads the counters, and this only restates its answer in the words the durable log, the metrics
+ * projection and the HTTP path already use. Without it the WebSocket transport is the one surface
+ * whose failures cannot be compared with anything else, which is the reported symptom -- every
+ * such failure reached the user as one of two bare sentences.
+ *
+ * It does not relax the transport's own rule. The no-replay-after-send contract in
+ * `codex-ws-exchange.ts` holds regardless of what this returns, and the stage below is
+ * deliberately not consulted as a fallback-eligibility signal; it reports where the exchange got
+ * to, and `resendPermission` happens to agree that everything past `before-send` is refused.
+ */
+export const CODEX_WS_FAILURE_PROJECTION = {
+  /** The create frame never left, so the origin provably never saw this turn. */
+  "before-send": { stage: "pre-header", cause: "transport-unsent" },
+  /** The frame left and the socket said nothing at all. The turn may be running upstream. */
+  "no-upstream-frame": { stage: "pre-header", cause: "transport-ambiguous" },
+  /** Control frames only: the peer is alive and answered, but no Responses event arrived. */
+  "no-response-event": { stage: "protocol-prelude", cause: "transport-ambiguous" },
+  /** Events already reached the caller, so a resend would duplicate output they have seen. */
+  "after-response-started": { stage: "semantic-output", cause: "transport-ambiguous" },
+} as const satisfies Record<CodexWsFailureCause, { stage: RequestFailureStage; cause: RequestFailureCause }>;
+
+export function projectCodexWsFailure(
+  stage: CodexWsFailureStage,
+): { stage: RequestFailureStage; cause: RequestFailureCause } {
+  return CODEX_WS_FAILURE_PROJECTION[classifyCodexWsFailure(stage)];
+}
+
 /**
  * Render the stage as a suffix appended to an existing failure message.
  *

package/src/server/responses/combo-stream-preflight.ts

@@ -1,6 +1,7 @@
 import type { ResponsesTerminalStatus } from "../../bridge";
 import { comboFailureDecision } from "../../combos";
 import { httpStatusFromTerminalError } from "../../lib/errors";
+import type { RequestFailureStage } from "../../lib/request-failure-model";
 import type { RequestLogContext } from "../request-log";
 import { createSseInspector } from "../relay";
 import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
@@ -108,9 +109,48 @@ export function comboStreamPayloadCommitsOutput(payload: unknown): boolean {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return true;
   const type = (payload as { type?: unknown }).type;
   if (typeof type !== "string") return true;
+  if (type === "response.created") {
+    // A created event is a control frame only while its snapshot is empty. An origin that
+    // resumes a turn can put completed items in it, and treating that as a prelude would let
+    // a replacement re-emit output the caller already received.
+    const response = (payload as { response?: unknown }).response;
+    if (response && typeof response === "object" && !Array.isArray(response)) {
+      const output = (response as { output?: unknown }).output;
+      if (Array.isArray(output) && output.length > 0) return true;
+    }
+  }
   return !PRE_OUTPUT_CONTROL_EVENTS.has(type) && !TERMINAL_EVENTS.has(type);
 }
 
+/**
+ * How far this SSE body got, in the vocabulary of src/lib/request-failure-model.ts.
+ *
+ * The preflight cannot separate `semantic-output` from `side-effect`: it classifies any event
+ * that is not a lifecycle control frame as committing, without reading item types. Both stages
+ * refuse a resend, so the distinction would change no decision -- it is named here so a later
+ * reader does not mistake the collapse for an omission.
+ *
+ * A terminal that settled carrying no output is `protocol-prelude`, not `terminal`. That is
+ * the failure model's own rule: `terminal` means the answer was delivered, and an empty
+ * completion delivered none.
+ *
+ * Only the two nothing-observed stages actually reach a read error today: the loop below hands
+ * the body back as `accepted` the moment output commits or a terminal arrives, so a stream
+ * that committed anything never reports a stage at all. The committed branches stay because
+ * this has to be total for any other caller, and because a later change to that loop must not
+ * be able to promote a committed stream into a replaceable one by omission.
+ */
+function observedResponsesStage(state: {
+  readonly outputCommitted: boolean;
+  readonly terminalStatus: ResponsesTerminalStatus | undefined;
+  readonly responseCreated: boolean;
+}): RequestFailureStage {
+  if (state.outputCommitted) return "semantic-output";
+  if (state.terminalStatus === "completed") return "terminal";
+  if (state.responseCreated || state.terminalStatus !== undefined) return "protocol-prelude";
+  return "headers-only";
+}
+
 function replayBufferedResponse(
   response: Response,
   reader: ReadableStreamDefaultReader<Uint8Array>,
@@ -186,13 +226,22 @@ function failedTerminalResponse(
 
 export type ComboStreamPreflightResult =
   | { kind: "accepted"; response: Response }
-  | { kind: "failed"; response: Response };
+  | { kind: "failed"; response: Response }
+  /**
+   * The body errored mid-stream and `replayReadErrors` asked for the prefix back rather than
+   * a rethrow. `stage` is how far the inspection actually got; whether that permits a
+   * replacement is the resend gate's decision, not this function's. Callers that only act on
+   * a projected terminal can treat this exactly as `accepted`, which is what it was before
+   * the stage became observable.
+   */
+  | { kind: "read-error"; response: Response; error: unknown; stage: RequestFailureStage };
 
 /**
- * Buffer a combo child's downstream SSE only until the request becomes unsafe to
- * replay or reaches a terminal. This owns exactly one body reader. The aggregate
- * buffer is capped by bytes and retained chunks; hitting either cap commits the
- * current target instead of growing memory or guessing that replay is safe.
+ * Buffer a Responses SSE only until the request becomes unsafe to replay or reaches a
+ * terminal. Combo failover and native post-header reset recovery share this protocol
+ * boundary, because they are asking the same question about the same bytes. This owns exactly
+ * one body reader. The aggregate buffer is capped by bytes and retained chunks; hitting either
+ * cap commits the current target instead of growing memory or guessing that replay is safe.
  */
 export async function preflightComboStreamResponse(
   response: Response,
@@ -211,12 +260,18 @@ export async function preflightComboStreamResponse(
   const buffered: Uint8Array[] = [];
   let bufferedBytes = 0;
   let outputCommitted = false;
+  let responseCreated = false;
   let terminalStatus: ResponsesTerminalStatus | undefined;
   let retryableTerminalPayload: Record<string, unknown> | undefined;
   const inspector = createSseInspector({
     logCtx,
+    // A payload the inspector could not parse still reached this proxy, and it may be output.
+    // Committing on it is what keeps an unreadable frame from reading as an empty prelude.
+    onOpaquePayload: () => { outputCommitted = true; },
     onParsedPayload: payload => {
       if (terminalStatus !== undefined || outputCommitted || retryableTerminalPayload) return;
+      if (payload !== null && typeof payload === "object" && !Array.isArray(payload)
+        && (payload as { type?: unknown }).type === "response.created") responseCreated = true;
       const retryable = retryableTerminal(payload);
       const matchedBareError = retryable && payload !== null && typeof payload === "object"
         && !Array.isArray(payload) && (payload as { type?: unknown }).type === "error";
@@ -239,7 +294,9 @@ export async function preflightComboStreamResponse(
         // The native relay still owns post-header transport failures. Preserve
         // the bounded prefix and the errored reader; cancelling it here would
         // erase the failure before either client relay or inspection sees it.
-        return { kind: "accepted", response: replayBufferedResponse(response, reader, buffered) };
+        const replay = replayBufferedResponse(response, reader, buffered);
+        const stage = observedResponsesStage({ outputCommitted, terminalStatus, responseCreated });
+        return { kind: "read-error", response: replay, error, stage };
       }
       if (next.done) {
         inspector.finish();
@@ -277,3 +334,108 @@ export async function preflightComboStreamResponse(
     inspector.dispose();
   }
 }
+
+/** Produce a replacement body for a mid-stream failure at `stage`, or null to keep the error. */
+export type ProtocolSafeResetRecovery = (
+  error: unknown,
+  stage: RequestFailureStage,
+) => Promise<Response | null>;
+
+/**
+ * Defer protocol inspection until the downstream actually pulls the body.
+ *
+ * Direct passthrough must return response headers before the first SSE event arrives, so the
+ * inspection cannot be awaited at the dispatch site the way combo routing awaits it. Wrapping
+ * the body moves it to the first pull, which is the earliest moment the client is willing to
+ * wait anyway.
+ */
+export function deferProtocolSafeResetRecovery(
+  response: Response,
+  logCtx: RequestLogContext,
+  recover: ProtocolSafeResetRecovery,
+  options?: { allowMissingContentType?: boolean },
+): Response {
+  if (!response.body) return response;
+
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let initialization: Promise<void> | undefined;
+  let closed = false;
+
+  const cancelBody = (body: ReadableStream<Uint8Array> | null, reason?: unknown): void => {
+    try { void body?.cancel(reason).catch(() => {}); } catch { /* already locked or closed */ }
+  };
+  const initialize = async (): Promise<void> => {
+    const preflight = await preflightComboStreamResponse(
+      response,
+      logCtx,
+      () => false,
+      { allowMissingContentType: options?.allowMissingContentType === true, replayReadErrors: true },
+    );
+    let selected = preflight.response;
+    if (preflight.kind === "read-error") {
+      const replacement = await recover(preflight.error, preflight.stage);
+      if (replacement) {
+        cancelBody(selected.body, "using protocol-safe replacement stream");
+        selected = replacement;
+      }
+    }
+    if (closed) {
+      cancelBody(selected.body, "downstream cancelled before protocol preflight completed");
+      return;
+    }
+    reader = selected.body?.getReader();
+  };
+
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        initialization ??= initialize();
+        await initialization;
+        if (closed) return;
+        if (!reader) {
+          closed = true;
+          controller.close();
+          return;
+        }
+        const next = await reader.read();
+        if (closed) return;
+        if (next.done) {
+          closed = true;
+          try { reader.releaseLock(); } catch { /* already released */ }
+          reader = undefined;
+          controller.close();
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        if (closed) return;
+        closed = true;
+        try { reader?.releaseLock(); } catch { /* errored reader */ }
+        reader = undefined;
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      if (closed) return;
+      closed = true;
+      if (reader) {
+        try { void reader.cancel(reason).catch(() => {}); } catch { /* already closed */ }
+        try { reader.releaseLock(); } catch { /* already released */ }
+        reader = undefined;
+      } else if (initialization === undefined) {
+        // Nothing has read the upstream yet, so this body is still ours to cancel.
+        cancelBody(response.body, reason);
+      }
+      // A cancel while the preflight is mid-flight falls through deliberately. That body is
+      // locked by the preflight's own reader, so cancelling it here would reject and be
+      // swallowed; `initialize` sees `closed` when it settles and releases whichever body it
+      // ended up selecting, which is the one that actually has to be let go.
+    },
+  }, { highWaterMark: 0 });
+
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}