fix(claude): close the uncoded overflow gaps left after #8128

src/claude/outbound.ts

@@ -133,7 +133,8 @@ export function isThroughputLimitText(message: string): boolean {
 }
 
 /** Codes that say nothing about the cause, so the message decides (#8127). */
-const GENERIC_FAILURE_CODES: ReadonlySet<string> = new Set(["server_error", "upstream_error", "api_error", "internal_error"]);
+/** `upstream_server_error` is what the shared classifier gives every 5xx, so it is generic too. */
+const GENERIC_FAILURE_CODES: ReadonlySet<string> = new Set(["server_error", "upstream_error", "upstream_server_error", "api_error", "internal_error"]);
 const NON_OVERFLOW_ERROR_TYPES: ReadonlySet<string> = new Set(["rate_limit_error", "authentication_error", "permission_error"]);
 const NON_OVERFLOW_STATUSES: ReadonlySet<number> = new Set([401, 403, 429]);
 /**

src/lib/upstream-retry.ts

@@ -16,6 +16,7 @@
  * the shared abort helpers from here).
  */
 import { clearableDeadline } from "./abort";
+import { isDefiniteContextOverflow } from "./context-overflow-verdict";
 import { errorDestinationLabel, errorDestinationText, type ErrorDestinationLabel } from "./error-destination";
 export { errorDestinationLabel, providerErrorDestinationLabel, errorDestinationText } from "./error-destination";
 import { redactSecretString } from "./redact";
@@ -721,6 +722,48 @@ export async function fetchWithResetRetry(
   } finally { opts.onSendsConsumed?.close?.(); }
 }
 
+/** Bytes of a 5xx body read to look for a context-overflow verdict; the verdict caps its input too. */
+const CONTEXT_OVERFLOW_PEEK_BYTES = 16_384;
+/** A body that has not arrived by then is not evidence; the peek must never stall the retry. */
+const CONTEXT_OVERFLOW_PEEK_MS = 250;
+
+/** Up to `maxBytes` of a clone of the body, or what arrived before the deadline. */
+async function peekBodyText(res: Response, maxBytes: number, deadlineMs: number): Promise<string> {
+  const reader = res.clone().body?.getReader();
+  if (!reader) return "";
+  const decoder = new TextDecoder();
+  let text = "";
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<null>(resolve => { timer = setTimeout(() => resolve(null), deadlineMs); });
+  try {
+    while (text.length < maxBytes) {
+      const chunk = await Promise.race([reader.read(), timedOut]);
+      if (!chunk || chunk.done) break;
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    return text.slice(0, maxBytes);
+  } finally {
+    clearTimeout(timer);
+    reader.cancel().catch(() => {});
+  }
+}
+
+/**
+ * True when a transient-status response's body is a definite context-overflow verdict. Peeks a
+ * clone within a byte and time bound, so the caller still receives the untouched body and a slow
+ * or endless body keeps the normal retry. "Too many tokens" alone is not enough here: a 5xx
+ * "Too many tokens, please wait" is a throttle that the retry exists for.
+ */
+async function isContextOverflowResponse(res: Response): Promise<boolean> {
+  if ((res.headers.get("content-type") ?? "").includes("text/event-stream")) return false;
+  try {
+    const text = await peekBodyText(res, CONTEXT_OVERFLOW_PEEK_BYTES, CONTEXT_OVERFLOW_PEEK_MS);
+    return text.length > 0 && isDefiniteContextOverflow(res.status, text.replace(/too many tokens/gi, ""));
+  } catch {
+    return false;
+  }
+}
+
 /**
  * fetchWithResetRetry plus the caller-selected transient-5xx policy, PRE-STREAM only.
  * A received HTTP error follows that policy; an ambiguous reset's non-replayable
@@ -782,6 +825,9 @@ export async function fetchWithTransientRetry(
     // thing about its own failure, so the ladder stops and hands the response back untouched.
     if (res.ok || !isTransientUpstreamStatus(res.status) || isNonReplayableResponse(res)
       || res.headers.get(REPLAY_REFUSAL_NO_RETRY_HEADER) === REPLAY_REFUSAL_NO_RETRY_VALUE) return res;
+    // A 5xx that says the input does not fit is deterministic: resending the same body is
+    // refused the same way, so it goes back for the caller to classify (#8127).
+    if (await isContextOverflowResponse(res)) return res;
     // Checked before cancelResponseBodyBestEffort so an already-aborted caller never receives
     // a response whose body we just cancelled.
     if (opts.abortSignal?.aborted) return res;

src/protocols/encoders/messages.ts

@@ -28,6 +28,7 @@ import {
   boundedReasoningIdentity,
   collectAnthropicMessage,
   isClaudeWebSearchToolName,
+  isContextOverflowError,
   messageSnapshot,
   sanitizeWebSearchInput,
   sseFrame,
@@ -389,8 +390,9 @@ function createAnthropicMessageWriter(
       }
       const message = typeof error.message === "string" ? error.message : "upstream request failed";
       const deterministic = error.code === UNDECLARED_TOOL_CALL_ERROR_CODE;
+      // Same overflow verdict as the translated stream, so an uncoded refusal compacts here too (#8127).
       fail(anthropicFailedStatus(error, message), message, !deterministic,
-        deterministic || error.code === "context_length_exceeded" ? error.code as string : undefined);
+        deterministic ? error.code as string : isContextOverflowError(error, message) ? "context_length_exceeded" : undefined);
     },
     overflow() {
       fail(413, "upstream translation buffer exceeded the safe limit", false, "translation_buffer_limit");

src/server/claude-messages.ts

@@ -1301,7 +1301,11 @@ async function handleClaudeMessagesWithBudget(
           || (![401, 403, 429].includes(response.status) && Boolean(nested || flat)
             && isContextOverflowError(errorObject, message));
       } catch {
-        if (text) message = `upstream error (${response.status}): ${text.slice(0, 400)}`;
+        // A plain-text gateway body carries the same verdict with no envelope to read a code from.
+        const plain = text.trim().slice(0, 400);
+        contextError = Boolean(plain) && ![401, 402, 403, 429].includes(response.status)
+          && isContextOverflowError({}, plain);
+        if (text) message = contextError ? plain : `upstream error (${response.status}): ${text.slice(0, 400)}`;
       }
     } catch { /* keep fallback message */ }
     const upstreamRetryAfter = response.headers.get("retry-after");

structure/data-planes/error-detail.md

@@ -208,7 +208,12 @@ rows to client or catalog model identities and validated provider ids, omitting
 is interpolated into those local messages. No serialized flag, code or header mints identity.
 The shared builders live in `src/combos/resolve.ts`, `src/server/admission-model-scope.ts`,
 `src/server/responses/input-admission.ts` and `src/oauth/generic-account-failover.ts`.
-`src/lib/upstream-retry.ts` owns the retry constructors.
+`src/lib/upstream-retry.ts` owns the retry constructors. `fetchWithTransientRetry` does not resend a
+transient-status response whose body is a definite context-overflow verdict
+(`isDefiniteContextOverflow`, #8127): the same input is refused the same way, so it is returned for the
+caller to classify. The check reads a clone of at most 16 KiB within 250 ms, so the caller still receives
+the untouched body, a slow, endless or event-stream body keeps the normal retry, and a throttle worded only
+as "too many tokens" is still retried.
 `InvalidSendBudgetError` displays only a finite non-negative number or `invalid`.
 `UpstreamRetryEvidenceError` uses fixed retry-evidence wording and retains the original rejection
 only as `Error.cause`. Chat request-read failures keep typed local size/encoding messages; other

structure/data-planes/protocol-paths.md

@@ -225,7 +225,7 @@ the wire-silence heartbeat and live-destination stall watchdog ([timeout policy]
 converters' own helpers, exported from `src/chat/outbound.ts` and `src/claude/outbound.ts`
 (ids, chunk and frame builders, usage mapping, `chatCompletionsStreamErrorPayload`,
 `chatCompletionsFailedResponse`, `chatCompletionsIncompleteOutcome`,
-`anthropicIncompleteOutcome`, `anthropicFailedStatus`, the message snapshot, the web-search pair),
+`anthropicIncompleteOutcome`, `anthropicFailedStatus`, `isContextOverflowError`, the message snapshot, the web-search pair),
 so the frames a client receives are the converters' frames. A fold is the encoded stream read by
 the existing collector. Only producer-marked watchdog/EOF terminals retain local Chat wording; upstream copies of their reason or message follow [client error normalization](error-detail.md#client-error-bodies-chat). Explicit incomplete reasons use the [shared normalization contract](../transports/responses-wire-shapes.md#adapter-incomplete-reasons) before the writers classify the outcome.
 

structure/runtime.md

@@ -1,6 +1,6 @@
 # Runtime
 
-The minute sweep checks persisted activation deadlines locally; only missing deadlines trigger metadata discovery. See the [quota activation contract](providers/openai-tiers.md#public-provider-contract). Codex control-plane ids are defined in the dependency-free `src/codex/control-plane-models.ts`; `src/router.ts` routes these exact ids unchanged to canonical OpenAI, retaining the existing error when no OpenAI provider is enabled. They do not widen the public native roster. Catalog requests and scheduled source refreshes follow the [nonblocking catalog observation contract](catalog.md#shared-catalog). Async runtime persistence awaits the fresh [selection admission](codex-cli-update.md#worker-realm-and-the-selection-commit-window), rechecks observed selection/epoch and caller-currentness changes after that await, and returns detached frozen results; signal cancellation makes the persistence wrapper return null without writing, while raw async resolver rejections and exceptions without signal cancellation retain their rejection behavior; bounded exec rejects promptly and releases output readers on deadline or abort, independently awaits actual child exit, and escalates SIGTERM to SIGKILL after the shared 2-second grace (Windows termination is forceful). Known Codex.app and ChatGPT.app commands at any location or alias follow the [execution trust contract](clients/chatgpt-desktop.md#codex-app-execution-trust); automatic discovery also requires matching bundle identity; the existing ChatGPT bundle trust policy (safe ownership, permissions, non-symlink paths, and OpenAI signatures for both the bundle and the exact executable) is enforced at every execution boundary in src/codex/exec-boundary.ts before the resolved canonical target is spawned, not once at selection. Version probes retain that execution's bundle classification for selection, so a bare PATH alias of an app cannot supersede a discovered persisted runtime; selection does not resolve PATH again after the probe. Stored and displayed command spelling remains unchanged, and this observation grants no trust to a later execution. Claude overflow normalization examines at most 64 Ki characters, extracts stated context/request counts in separate forward scans, retains the bounded rewritten prefix, and leaves other error classifications intact; the managed native Messages SSE route follows the same contract (`tests/claude-integration/claude-prompt-too-long.test.ts`). On the translated Messages-to-Responses lane, `isContextOverflowError` in `src/claude/outbound.ts` decides overflow for the streamed `response.failed` handler, the non-stream error branch and the failed-JSON branch: a coded `context_length_exceeded` always counts; an uncoded or generic-coded (`server_error`, `upstream_error`, `api_error`, `internal_error`) refusal counts only on wording that asserts the request exceeds a size limit, never with a 401/403/429 status, a rate-limit or credential type, throughput wording or another specific code, and then answers 400 `prompt is too long` so Claude Code compacts (#8127, `tests/claude-integration/claude-uncoded-context-overflow.test.ts`). Optional native desktop observation follows the [Codex Desktop startup gate and awaited teardown](clients/codex-desktop.md#proxy-startup-preference). Claude Code tier defaults are projected by `src/claude/model-default-settings.ts` into user settings only after explicit preview/apply, independently of launcher environment injection; see the [management contract](gui-and-management-api.md). The explicit projection pairs selected aliases with readable labels from `src/claude/context-windows.ts`, preserving custom labels and clearing only a label matching its current alias when an explicitly selected tier becomes a non-alias; unset tiers retain both settings model IDs and labels. No startup or periodic sync writes these defaults.
+The minute sweep checks persisted activation deadlines locally; only missing deadlines trigger metadata discovery. See the [quota activation contract](providers/openai-tiers.md#public-provider-contract). Codex control-plane ids are defined in the dependency-free `src/codex/control-plane-models.ts`; `src/router.ts` routes these exact ids unchanged to canonical OpenAI, retaining the existing error when no OpenAI provider is enabled. They do not widen the public native roster. Catalog requests and scheduled source refreshes follow the [nonblocking catalog observation contract](catalog.md#shared-catalog). Async runtime persistence awaits the fresh [selection admission](codex-cli-update.md#worker-realm-and-the-selection-commit-window), rechecks observed selection/epoch and caller-currentness changes after that await, and returns detached frozen results; signal cancellation makes the persistence wrapper return null without writing, while raw async resolver rejections and exceptions without signal cancellation retain their rejection behavior; bounded exec rejects promptly and releases output readers on deadline or abort, independently awaits actual child exit, and escalates SIGTERM to SIGKILL after the shared 2-second grace (Windows termination is forceful). Known Codex.app and ChatGPT.app commands at any location or alias follow the [execution trust contract](clients/chatgpt-desktop.md#codex-app-execution-trust); automatic discovery also requires matching bundle identity; the existing ChatGPT bundle trust policy (safe ownership, permissions, non-symlink paths, and OpenAI signatures for both the bundle and the exact executable) is enforced at every execution boundary in src/codex/exec-boundary.ts before the resolved canonical target is spawned, not once at selection. Version probes retain that execution's bundle classification for selection, so a bare PATH alias of an app cannot supersede a discovered persisted runtime; selection does not resolve PATH again after the probe. Stored and displayed command spelling remains unchanged, and this observation grants no trust to a later execution. Claude overflow normalization examines at most 64 Ki characters, extracts stated context/request counts in separate forward scans, retains the bounded rewritten prefix, and leaves other error classifications intact; the managed native Messages SSE route follows the same contract (`tests/claude-integration/claude-prompt-too-long.test.ts`). On the translated Messages-to-Responses lane, `isContextOverflowError` in `src/claude/outbound.ts` decides overflow for the streamed `response.failed` handler, the non-stream error branch and the failed-JSON branch: a coded `context_length_exceeded` always counts; an uncoded or generic-coded (`server_error`, `upstream_error`, `api_error`, `internal_error`) refusal counts only on wording that asserts the request exceeds a size limit, never with a 401/403/429 status, a rate-limit or credential type, throughput wording or another specific code, and then answers 400 `prompt is too long` so Claude Code compacts (#8127, `tests/claude-integration/claude-uncoded-context-overflow.test.ts`) `upstream_server_error`, the code the shared classifier gives every 5xx, is generic there too. The non-stream branch applies the same verdict to a plain-text (non-JSON) body, excluding 401/402/403/429, and answers with the upstream text as the message; the direct Messages encoder attaches `context_length_exceeded` with the same verdict. Optional native desktop observation follows the [Codex Desktop startup gate and awaited teardown](clients/codex-desktop.md#proxy-startup-preference). Claude Code tier defaults are projected by `src/claude/model-default-settings.ts` into user settings only after explicit preview/apply, independently of launcher environment injection; see the [management contract](gui-and-management-api.md). The explicit projection pairs selected aliases with readable labels from `src/claude/context-windows.ts`, preserving custom labels and clearing only a label matching its current alias when an explicitly selected tier becomes a non-alias; unset tiers retain both settings model IDs and labels. No startup or periodic sync writes these defaults.
 
 ## Bun runtime and test runner
 

tests/claude-integration/claude-uncoded-context-overflow.test.ts

@@ -88,7 +88,12 @@ async function translatedErrorFrame(error: Record<string, unknown>) {
 }
 
 describe("translated Responses stream", () => {
-  test.each([{ message: OVERFLOW }, { type: "server_error", code: "server_error", message: OVERFLOW }])(
+  test.each([
+    { message: OVERFLOW },
+    { type: "server_error", code: "server_error", message: OVERFLOW },
+    // The shared classifier's code for every 5xx is generic, not a specific cause.
+    { type: "server_error", code: "upstream_server_error", message: OVERFLOW },
+  ])(
     "an uncoded or server_error overflow ends in a prompt-too-long 400 frame: %j", async error => {
       const frame = await translatedErrorFrame(error);
       expect(frame).toMatchObject({ type: "invalid_request_error", code: "context_length_exceeded" });
@@ -141,6 +146,25 @@ describe("translated Messages route end to end", () => {
     expect(response.headers.get("retry-after")).toBeNull();
   });
 
+  test("a plain-text 500 overflow answers 400 with the upstream text", async () => {
+    const { response, text } = await send(() => new Response(OVERFLOW, { status: 500 }));
+    expect(response.status).toBe(400);
+    const error = JSON.parse(text).error;
+    expect(error).toMatchObject({ type: "invalid_request_error", code: "context_length_exceeded" });
+    expect(error.message).toContain(OVERFLOW);
+    expect(error.message).not.toContain("upstream error (500)");
+  });
+
+  test.each([402, 429])("a plain-text HTTP %i that mentions the context window keeps its status", async status => {
+    const { response } = await send(() => new Response(OVERFLOW, { status }));
+    expect(response.status).toBe(status);
+  });
+
+  test("a plain-text 500 that is not an overflow keeps its retryable class", async () => {
+    const { response } = await send(() => new Response("bad gateway", { status: 500 }));
+    expect(response.status).toBe(529);
+  });
+
   test("a 429 that mentions the context window stays a rate limit", async () => {
     const { response, text } = await send(() => Response.json({ error: { type: "rate_limit_error", message: "context window quota exhausted" } }, { status: 429 }));
     expect(response.status).toBe(429);