provider capacity errors (code=resource-exhausted) surface as "Unknown error" + misleading "retry directly" guidance

What happened

With an xAI-backed model (grok-4.6 via xai-oauth, and a relayed deepseek-v4-flash via an OpenAI-compatible gateway) during high demand, turns fail at the first model call with the provider's capacity error, but the Desktop surfaces it as the generic "未知错误" (Unknown error) with the recovery hint "没有执行工具，可直接重试" (No tools ran; retry directly). Retrying within the outage window fails identically, so the conversation looks "stuck". The failure is provider-side capacity, not a conversation or runtime defect.

The underlying error is stable and machine-readable:

code=resource-exhausted: The model is currently at capacity due to high demand.
Please try again in a few minutes, or use a higher service tier for priority processing:
https://docs.x.ai/developers/advanced-api-usage/priority-processing (code=resource-exhausted)

Observed 4 times in one session (2026-08-20, 22:25 / 22:50 / 23:03 / 23:10 UTC+8), with a successful turn in between — intermittent provider capacity, not a broken conversation.

Root cause chain

1. Runtime classification gap. The provider error carries a stable code (resource-exhausted) but no parsed HTTP status, so classifyError in packages/runtime/src/provider-error-classification.ts returns Other → modelFailureKind → unknown. ModelAdapter.makeErrorEvent then omits reason (unknown is excluded) and keeps code, so the TurnRecord ends up with errorClass: 'resource-exhausted' (raw provider code). providerRetryMetadata also marks it non-retryable, so the turn fails immediately with no backoff.
2. Desktop presentation (apps/desktop/src/renderer/session-error-presentation.ts / session-status-presentation.ts): the allowlist (context_overflow, timeout, auth, provider_billing, provider_unavailable, rate_limit, network) and the prefix matching don't include resource-exhausted → falls to the catch-all "未知错误".
3. Recovery guidance (deriveFailedTurnRecovery): because the turn died before any tool ran, it correctly sees toolActivityCount == 0 and recommends direct retry — which is misleading for a capacity outage that the provider says to wait out.

How to reproduce

1. Use an xAI(-compatible) model during a high-demand window (or any provider returning code=resource-exhausted).
2. Start a turn; it fails immediately at the first model call.
3. The failed turn shows "未知错误" + "没有执行工具，可直接重试".
4. Retrying within a few minutes fails the same way; waiting a few minutes (or switching models) succeeds.

Intermittent; frequency depends on provider load.

Environment

• Maka: commit 98bdd6cf8 (current main)
• OS: macOS (arm64)
• Surface: Desktop (dev build)
• Provider: xAI (grok-4.6) and an OpenAI-compatible gateway (deepseek-v4-flash), both surfacing xAI capacity errors

Expected behavior

• Structured provider codes like resource-exhausted should map to a stable, user-facing class — ideally at the ModelAdapter/runtime boundary per #2516's direction (structured evidence → stable meaning), with Desktop/TUI/CLI consuming the same semantic result. User-facing copy should say something like "模型服务暂时满载/容量不足，请稍后重试或切换模型", not "未知错误".
• Recovery guidance for capacity/usage-limit classes must not say "retry directly"; it should suggest waiting a few minutes or switching model/connection.
• Consider whether capacity codes should be retryable with a meaningful backoff (or at least surfaced with wait guidance), since retryable: false + "可直接重试" is the worst combination for the user.

Related

• #2516 — distinguish usage limits from authentication failures (classification boundary)
• #1216 — preserve provider failure taxonomy through retries and Desktop presentation (closed)
• #3302 — desktop recoverability after rate-limit errors (lifecycle, distinct)