fix(coding-agent): trust structured auth classification; explicit model switch clears stale auth

[snimu]

Deletes the session-layer 401/403 message-text auth sniffing and gives users an explicit recovery path from stale-auth lockouts (Linear: RES-1271; discussion evidence: #1501, #1777, #1611-diagnosability).

Stacked on #2045: it relies on every provider recording structured provider_stream_failure diagnostics (added there for openai-completions and codex).

Why

• _isConcreteProviderAuthFailure matched any error containing 401/403 plus keywords (status code, forbidden, token, credential, ...). Regional service-availability errors, org-policy blocks, and model-access denials are commonly 403s, so one non-auth 403 on one model marked the WHOLE provider auth-stale ([Bug] Cannot switch to another OpenCode Go model after a regional availability error #1501).
• The stale flag is in-memory and sticky: a transient auth-shaped incident overnight poisoned the running process; /model then failed with the misleading Model not found because stale providers' models are excluded from the available list, while a fresh process worked fine ([Bug] Could not restore model anthropic/claude-opus-5. Using prime-inference/z-ai/glm-5.2 #1777).
• classifyStreamFailure mapped bare status === 403 to auth, so even the structured path over-classified.

What

Deletion:

• Both regex branches in _isConcreteProviderAuthFailure (and the now-unused _getProviderStreamFailureAuthStatus); auth-stale marking now requires structured kind auth.
• status === 403 removed from the auth classification; a 403 is auth only with an explicit authentication/permission error type. Bare 403 becomes a normal request error (bounded visible retries, no provider lockout).

Recovery:

• modelRegistry.clearProviderAuthStale(provider) clears both the request-config and auth-storage stale maps.
• Explicit model selection calls it: AgentSession.setModel plus the in-process and daemon set_model lookups (the lookups must clear before refreshAvailableModels, otherwise the stale provider's models stay excluded and the switch fails with Model not found). A structured auth failure on the next request re-marks the provider.

Not changed: the interactive-mode /model flow additionally offers a login prompt when it sees an unconfigured/stale provider; that path already recovers via re-login and is untouched.

Size

Total src: +102/−65 (net +37); tests: +190/−43 (net +147).
Net src LOC: +32/−37 (net negative; the additions are the clear method and three one-line call sites). Tests: 2 new pins (registry clear restores availability; explicit setModel clears a lockout), 1 new negative pin (unstructured 401 text no longer marks stale), 2 reworked (bare-401 pins converted to structured), 2 classify-table rows.

Validation

• Sandbox: root tsgo clean; packages/ai + packages/agent suites pass; packages/coding-agent matches the 82-test/14-file environmental baseline exactly.
• Targeted local: 4491, model-registry, agent-session-retry-events, stream-failure all pass.

Linear: RES-1271

---

Note

Medium Risk
Changes how auth failures are detected and when providers are marked stale, which affects retries, credential UX, and model availability; mistakes could leave bad keys unflagged or skip legitimate recovery.

Overview
Provider stream failures now distinguish bad credentials from access denials: bare HTTP 403 and permission-shaped errors map to a new permission kind (permanent, no retry) instead of auth, and extractStreamFailureInfo no longer infers auth/permission from error message text alone—only structured provider error types or status codes (401/403) decide.

Coding-agent stale-auth behavior stops treating regex-matched 401/403 text or structured permission failures as reason to mark a whole provider auth-stale; only structured diagnostics with kind auth trigger lockout. Explicit model selection can recover: when the only blocker is staleness, setModel validates with assumeAuthConfigured, then clearProviderAuthStale commits; failed model lookups or entitlement checks leave the lockout intact. Daemon/in-process set_model can resolve models hidden from the “available” list while stale. Prime private-model entitlements are preserved across stale-auth refreshes (same team, serialized refresh) so re-selection can validate against cached authorization.

^{Reviewed by Cursor Bugbot for commit 567dba4. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Trust structured auth classification and clear stale auth on explicit model switch

• classifyStreamFailure now requires structured evidence (status 401 or auth/unauthorized type) to classify a failure as auth; 403 and permission-type errors classify as permission.
• Unstructured error message text alone no longer establishes auth or permission verdicts; only status codes do when no structured provider error type exists.
• Adds permission as a non-retryable stream failure kind in isPermanentProviderFailureKind.
• _isConcreteProviderAuthFailure returns true only for structured auth failures, removing status-code and message heuristics from stale-auth decisions.
• Explicit model selection from a stale provider validates auth before clearing stale state via clearProviderAuthStale; failed lookups leave the provider locked out.
• Entitlement refresh is serialized through runSerializedEntitlementRefresh, and same-team Prime inference entitlements are preserved across stale-auth refreshes.
• Risk: Providers that previously triggered stale-auth on bare 401/403 text will no longer be marked stale; any out-of-tree callers relying on classifyStreamFailure or _isConcreteProviderAuthFailure treating 403 as auth must update.

^{Macroscope summarized 567dba4.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit eee8f74. Configure here.}