Summary

• Classify provider upstream_error / "Upstream request failed" responses as a transient server failure so the configured fallback chain is attempted.
• User-facing impact: a flaky primary provider that returns upstream_error now fails over to the next configured model instead of ending the turn with LLM request failed.

Motivation

Closes #95519.

When the primary provider returns an error payload shaped like:

{ "error": { "message": "Upstream request failed", "type": "upstream_error", "param": "", "code": null } }

the failover classifier returned null (unclassified). Unclassified failures do not enter the model-fallback path, so the run ended with stopReason: "error" and the user-facing text LLM request failed, with no model.fallback_step recorded — even when agents.defaults.model.fallbacks was configured.

The serverError matcher list already covered "upstream error" and "upstream connect error", but not the upstream_error type token nor the "Upstream request failed" message phrasing emitted by this provider. So this transient upstream failure slipped through.

The fix adds "upstream_error" and "upstream request failed" to the serverError patterns. These classify as a transient server_error (mapped to the timeout failover reason), which is the existing fallbackable transient path.

OpenClaw's own generic assistant text "LLM request failed" (GENERIC_ASSISTANT_ERROR_TEXT) is deliberately left unclassified to avoid a fallback loop on internal/non-provider failures.

Verification

• node scripts/run-vitest.mjs run src/agents/embedded-agent-helpers/failover-matches.test.ts — 30 passed (5 new)
• node scripts/run-vitest.mjs run src/agents/failover-error.test.ts src/agents/embedded-agent-helpers.isbillingerrormessage.test.ts — 234 passed
• node scripts/run-vitest.mjs run src/agents/model-fallback.test.ts src/agents/embedded-agent-helpers/provider-error-patterns.test.ts — 121 passed
• Did NOT change: the generic "LLM request failed" text classification (stays null).

Real behavior proof

• Behavior addressed: the exact {type:"upstream_error", message:"Upstream request failed"} payload from the issue was classified null → no fallback. After the fix it classifies as timeout (fallbackable transient).
• Real environment: Node v25.x, vitest 4.1.7, this branch.
• Exact commands run after the patch:

  node scripts/run-vitest.mjs run <temp test calling classifyFailoverReason on the payloads>
  

• Captured output AFTER fix:

  REASON payload = "timeout"
  REASON bare    = "timeout"
  REASON generic = null
  

  (payload = full issue JSON; bare = "Upstream request failed"; generic = OpenClaw's own "LLM request failed", correctly left unclassified.)
• Before the fix, the same three inputs all returned null (verified on upstream/main before editing).
• Regression test: src/agents/embedded-agent-helpers/failover-matches.test.ts → describe("upstream provider transient errors (#95519)"). It asserts the new classifications AND that the generic text stays null; it fails without the source change.
• What was NOT tested: end-to-end gateway fallback rotation (covered indirectly by the existing model-fallback.test.ts reason→candidate-rotation tests, which still pass); this PR is scoped to the classification gap that gates entry into that path.

What Problem This Solves

When the primary provider returns {type:"upstream_error", message:"Upstream request failed"}, the failover classifier returned null (unclassified), so the run ended with LLM request failed and never tried the configured fallback models — even with agents.defaults.model.fallbacks set. This PR classifies that payload as a transient server_error so the existing fallback path is entered.

Evidence

• node scripts/run-vitest.mjs run src/agents/embedded-agent-helpers/failover-matches.test.ts → 30 passed (5 new, including the #95519 regression describe block). Re-verified on a clean rebase onto current upstream/main: 30/30 pass.
• npx oxlint src/agents/embedded-agent-helpers/failover-matches.ts failover-matches.test.ts → 0 errors / 0 warnings.
• Behavioral proof: classifyFailoverReason() on the exact issue payload returns "timeout" (fallbackable) AFTER the fix; returned null BEFORE. OpenClaw's own generic "LLM request failed" text correctly stays null (no fallback loop on internal errors).
• Scope: classification gap only; downstream reason→candidate rotation remains covered by the existing passing model-fallback.test.ts.