fix(claude): derive response.failed status from the classified error payload

src/adapters/cursor/cursor-errors.ts

@@ -241,6 +241,21 @@ export function classifyCursorError(message: string, sizeContext?: CursorSizeCon
     lower.includes("access denied")
   ) return "Cursor authentication failed";
 
+  // gRPC FAILED_PRECONDITION is deterministic and non-retryable (unlike UNAVAILABLE):
+  // the backend rejected the call because the account/plan state does not allow it —
+  // seen live when a plan-gated model (e.g. claude-fable-5) runs on a plan without it.
+  // Leaving it as "Cursor upstream error" (502) made clients retry it as overload.
+  //
+  // This MUST precede the overload keywords. The explicit gRPC status code is a
+  // structured signal from the backend; the keywords are inference over free text. A
+  // plan-gated rejection routinely reads "failed_precondition: model unavailable for
+  // this plan", which matched "unavailable" first and came back as a retryable
+  // overload — the exact misclassification this branch was added to stop. Checking the
+  // code first lets the deterministic signal win over the words around it.
+  if (lower.includes("failed_precondition") || lower.includes("failed precondition")) {
+    return "Cursor invalid request";
+  }
+
   if (
     lower.includes("unavailable") ||
     lower.includes("overloaded") ||

src/claude/outbound.ts

@@ -11,6 +11,7 @@
  *  - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200.
  */
 import { createHash } from "node:crypto";
+import { httpStatusFromTerminalError } from "../lib/errors";
 import { isTransientUpstreamStatus } from "../lib/upstream-retry";
 import {
   isTranslatorBudgetExceededError,
@@ -555,9 +556,19 @@ export function responsesSseToAnthropicSse(
             }
             const status = code === "translation_buffer_limit"
               ? 413
-              : typeof error.status === "number" ? error.status : 500;
-            // status-absent response.failed (relaySseWithFailedTail synthetic tail) defaults
-            // to 500, which is in the transient set — the mid-stream reset shape maps to
+              : typeof error.status === "number"
+                ? error.status
+                // Internal response.failed envelopes carry the classified {type, code, message}
+                // but no numeric status. Derive it with the same mapping /api/logs uses so a
+                // classified 429/401/400 reaches Claude Code as its real Anthropic error type
+                // instead of being masked as retryable overload.
+                : httpStatusFromTerminalError({
+                  type: typeof error.type === "string" ? error.type : undefined,
+                  code: typeof error.code === "string" ? error.code : null,
+                  message,
+                });
+            // Unclassified status-absent response.failed (relaySseWithFailedTail synthetic
+            // tail) still lands on a transient 5xx here — the mid-stream reset shape maps to
             // overloaded_error by design.
             fail(
               status,

src/lib/errors.ts

@@ -335,6 +335,12 @@ export function inferHttpStatusFromAdapterMessage(message: string): number {
   // subscription/permission wording.
   if (isAuthenticationMessage(lower)) return 401;
   if (isSubscriptionGateMessage(lower) || isPermissionMessage(lower)) return 403;
+  // Same precedence rule as classifyCursorError: an explicit gRPC FAILED_PRECONDITION is a
+  // structured, deterministic rejection, so it outranks the overload keywords that routinely
+  // appear beside it ("failed_precondition: model unavailable for this plan"). Without this,
+  // the message matched "unavailable" and returned a retryable 503, so clients kept retrying
+  // a rejection that can never succeed.
+  if (lower.includes("failed_precondition") || lower.includes("failed precondition")) return 400;
   if (
     lower.includes("unavailable") ||
     lower.includes("overloaded") ||
@@ -410,6 +416,24 @@ export function httpStatusFromTerminalError(error: {
   if (message && isClientClosedMessage(message)) return 499;
   if (error.type === "invalid_request_error") return 400;
   if (error.type === "proxy_error") return 500;
-  if (message) return inferHttpStatusFromAdapterMessage(message);
+  // A structured server class must not be downgraded to a CLIENT error by message wording.
+  // classifyError assigns `server_error` + `upstream_server_error` to every 5xx it sees, so
+  // the class is authoritative about blame: the upstream failed, the caller did not send a
+  // bad request. What it is NOT authoritative about is which server status fits — a stall is
+  // genuinely 504 and an overload genuinely 503, and flattening those to 502 discards
+  // information both the log surface and the retry policy read. So message inference still
+  // chooses the specific status, and only a client-error verdict is overridden.
+  //
+  // The override is deliberately narrowed to 400 alone. 429, 499, 401 and 403 are all
+  // actionable signals the caller routes on — retry-after, client cancellation, re-auth,
+  // entitlement — and overriding them would trade one kind of misreport for another. 400 is
+  // the single verdict that both blames the caller and stops the retry, which is the failure
+  // being fixed: an upstream 500 whose text happens to contain "malformed" or "invalid
+  // request" used to return 400, so Claude Code stopped retrying a retryable failure.
+  const structuredServerClass = error.type === "server_error" || error.code === "upstream_server_error";
+  if (message) {
+    const inferred = inferHttpStatusFromAdapterMessage(message);
+    return structuredServerClass && inferred === 400 ? 502 : inferred;
+  }
   return 502;
 }

tests/claude-outbound.test.ts

@@ -534,6 +534,111 @@ describe("claude outbound SSE", () => {
     });
   });
 
+  // Internal response.failed envelopes carry the classified {type, code, message} but no
+  // numeric status (adapterFailureFromEvent drops httpStatus at the wire boundary). The
+  // classified status must be derived the same way /api/logs derives it, or every classified
+  // failure is masked as retryable overloaded_error — a Cursor plan/quota 429 surfaced in
+  // Claude Code as "Repeated 529 Overloaded errors".
+  test("failed with classified rate_limit_error but NO numeric status -> rate_limit_error, not overloaded", async () => {
+    const upstream = [
+      sse("response.created", { response: {} }),
+      sse("response.failed", {
+        response: {
+          status: "failed",
+          error: { type: "rate_limit_error", code: "rate_limit_exceeded", message: "Cursor rate limit exceeded: quota exhausted" },
+        },
+      }),
+    ].join("");
+    const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
+    expect(events.at(-1)!.data).toEqual({
+      type: "error",
+      error: { type: "rate_limit_error", message: "Cursor rate limit exceeded: quota exhausted" },
+    });
+  });
+
+  test("failed with classified authentication_error but NO numeric status -> authentication_error, not overloaded", async () => {
+    const upstream = [
+      sse("response.created", { response: {} }),
+      sse("response.failed", {
+        response: {
+          status: "failed",
+          error: { type: "authentication_error", code: "invalid_api_key", message: "Cursor authentication failed: expired token" },
+        },
+      }),
+    ].join("");
+    const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
+    expect(events.at(-1)!.data).toEqual({
+      type: "error",
+      error: { type: "authentication_error", message: "Cursor authentication failed: expired token" },
+    });
+  });
+
+  test("failed with classified invalid_request_error but NO numeric status -> invalid_request_error, not overloaded", async () => {
+    const upstream = [
+      sse("response.created", { response: {} }),
+      sse("response.failed", {
+        response: {
+          status: "failed",
+          error: { type: "invalid_request_error", code: "context_length_exceeded", message: "Cursor context limit exceeded" },
+        },
+      }),
+    ].join("");
+    const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
+    expect(events.at(-1)!.data).toEqual({
+      type: "error",
+      error: { type: "invalid_request_error", message: "Cursor context limit exceeded" },
+    });
+  });
+
+  test("failed with classified server overload but NO numeric status -> still overloaded_error", async () => {
+    const upstream = [
+      sse("response.created", { response: {} }),
+      sse("response.failed", {
+        response: {
+          status: "failed",
+          error: { type: "server_error", code: "server_is_overloaded", message: "Cursor server overloaded: unavailable" },
+        },
+      }),
+    ].join("");
+    const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
+    expect(events.at(-1)!.data).toEqual({
+      type: "error",
+      error: { type: "overloaded_error", message: "Cursor server overloaded: unavailable" },
+    });
+  });
+
+  // Deriving the status from the classified payload is only safe if a STRUCTURED server
+  // class outranks the message heuristics. `httpStatusFromTerminalError` recognized only
+  // `server_error` + `server_is_overloaded`, so a generic `upstream_server_error` fell
+  // through to `inferHttpStatusFromAdapterMessage`. An upstream 5xx whose text happens to
+  // contain "malformed" or "invalid request" then returned 400, and Claude Code stopped
+  // retrying a genuinely retryable upstream failure — the exact inversion this PR set out
+  // to fix, reintroduced one layer down. classifyError assigns `upstream_server_error` to
+  // every 5xx it sees, so the class is authoritative over the words in the message.
+  test("generic upstream_server_error with client-sounding text stays a transient server failure", async () => {
+    const upstream = [
+      sse("response.created", { response: {} }),
+      sse("response.failed", {
+        response: {
+          status: "failed",
+          error: {
+            type: "server_error",
+            code: "upstream_server_error",
+            message: "upstream stream produced malformed tool call arguments",
+          },
+        },
+      }),
+    ].join("");
+    const events = await collectEvents(responsesSseToAnthropicSse(streamFrom(upstream), "m"));
+    expect(events.at(-1)!.data).toEqual({
+      type: "error",
+      error: {
+        type: "overloaded_error",
+        message: "upstream stream produced malformed tool call arguments",
+      },
+    });
+  });
+
   test("internal reader exception stays api_error (not promoted to overloaded)", async () => {
     const boom = new ReadableStream<Uint8Array>({
       start(controller) {

tests/cursor-errors.test.ts

@@ -5,6 +5,7 @@ import {
   isCursorInvalidArgumentError,
   safeCursorErrorMessage,
 } from "../src/adapters/cursor/cursor-errors";
+import { inferHttpStatusFromAdapterMessage } from "../src/lib/errors";
 
 describe("classifyCursorError", () => {
   test("rate limit and resource exhaustion stay distinct", () => {
@@ -59,6 +60,39 @@ describe("classifyCursorError", () => {
     expect(classifyCursorError("invalid request: malformed tool schema")).toBe("Cursor invalid request");
   });
 
+  test("failed_precondition is a deterministic non-retryable rejection, not overload", () => {
+    // Live evidence: a plan-gated model (claude-fable-5) invoked on a plan without it
+    // returns "Cursor Connect error failed_precondition: Error". gRPC FAILED_PRECONDITION
+    // is non-retryable by definition; as "Cursor upstream error" (502) clients retried it
+    // as overload, and the Claude inbound surfaced it as a misleading 529.
+    expect(classifyCursorError("Cursor Connect error failed_precondition: Error")).toBe("Cursor invalid request");
+    expect(inferHttpStatusFromAdapterMessage("Cursor invalid request: Cursor Connect error failed_precondition: Error")).toBe(400);
+  });
+
+  test("failed_precondition wins over overload keywords in the same message", () => {
+    // The original arm sat AFTER the overload keywords, so the shape this branch exists
+    // to catch slipped straight past it: a plan-gated rejection normally reads
+    // "failed_precondition: model unavailable for this plan", which matched "unavailable"
+    // first and came back "Cursor server overloaded" -> 503. Clients then retried a
+    // deterministic rejection forever. The explicit gRPC status is a structured signal
+    // from the backend; "unavailable" and "temporarily" here are just words near it.
+    expect(classifyCursorError("failed_precondition: model unavailable for this plan"))
+      .toBe("Cursor invalid request");
+    expect(classifyCursorError("failed_precondition: model temporarily gated"))
+      .toBe("Cursor invalid request");
+    expect(inferHttpStatusFromAdapterMessage("Cursor invalid request: failed_precondition: model unavailable for this plan"))
+      .toBe(400);
+
+    // A real overload with no gRPC precondition code must still be retryable.
+    expect(classifyCursorError("service temporarily unavailable")).toBe("Cursor server overloaded");
+    expect(classifyCursorError("backend overloaded, retry")).toBe("Cursor server overloaded");
+    expect(classifyCursorError("server is busy")).toBe("Cursor server overloaded");
+
+    // Authentication is checked earlier and stays authoritative over both.
+    expect(classifyCursorError("failed_precondition: unauthorized token"))
+      .toBe("Cursor authentication failed");
+  });
+
   test("timeout / deadline", () => {
     expect(classifyCursorError("Cursor transport timed out before first response")).toBe("Cursor request timed out");
     expect(classifyCursorError("deadline exceeded")).toBe("Cursor request timed out");