ENG-747: read status-error codes from the shape the SDK actually stores — revives the dead model-403 card

[alecantu7]

Summary

Fixes ENG-747: the ENG-598 model-unavailable card has been dead in production since it shipped — observed live on a fully-updated free-tier machine (2026-07-13) and reproduced deterministically.

Root cause: the OpenAI SDK unwraps the error envelope before storing it (openai/_client.py:416, data = body.get("error", body)), so the gateway's 403 {"error": {"code": "model_access_denied", …}} reaches the mapper as the inner dict with code at top level. The mapper read body["error"]["code"] — a key the SDK had already peeled — so every model-403 fell to the generic "temporarily unavailable" path: no typed error, no turn error, no card.

Why 429 worked all along: the gateway's 429 is FastAPI-style ({"detail": …}, no envelope) — the SDK's unwrap is a no-op for it. The working token-limit card was load-bearing on the gateway's dialect inconsistency.

Fix

• _raise_for_status_error: read code and detail from the top level first, envelope fallback second — correct for both gateway dialects today, and the 429 card now survives a future gateway standardization onto the OpenAI envelope (previously a silent time bomb).
• Tests rebuilt on the real SDK: every APIStatusError is now constructed by the pinned SDK (openai 2.21.0) from a raw HTTP response via httpx.MockTransport — the duck-typed _FakeStatusError (which hand-built the wire shape the SDK never stores, letting the suite validate the spec against itself) is gone from the status-error path. A dedicated test_sdk_unwraps_error_envelope documents the SDK behavior so any future SDK parsing change fails loudly. Coverage: 403 envelope × both codes, 403 pre-unwrapped, 429 both dialects, 429-beats-403 precedence on the unwrapped shape, 401 JSON + 401 nginx-HTML, WAF HTML 403, code-less 403, 500.

Verification

• Mapper suite: 15 passed. Full suite: 1170 passed, 17 skipped.
• Repro chain (SDK source line, MockTransport assert-proof with the live-captured prod gateway body, field observation) documented on the ticket.
• End-to-end confirmation available: the live free-tier repro machine — fresh message on a locked model should show the ModelUnavailableCard after this ships.

Security pass

Reviewed the changed surface: no credentials or user content in error messages beyond the model alias; the HTML-body cases confirm non-JSON error pages can't inject into curated copy (fall through to the generic string); no logging added.

Notes

• No cowork-server / renderer changes — verified correct in v2.26.7.13.1; they were starved of input, not broken.
• uv.lock intentionally untouched (the rich <15 resync drift is pre-existing and already flagged on feat(prompts): move backend + HTML-dashboard contracts into built-in skills #244).

🤖 Generated with Claude Code

[alecantu7]

Adversarial self-review → hardening commit bc5b419

Ran the 8-angle adversarial review before requesting human review. The fix itself held (no caller breaks, no real-provider behavior changes — BYOK OpenAI/Anthropic/Azure error shapes verified unchanged through the real SDK; cowork-server's detection is isinstance-based, no strings touched). Three findings on my own work, all addressed:

1. The envelope fallback was pinned by nothing — and my own harness couldn't pin it. The pinned SDK always unwraps, so _sdk_error physically cannot produce an envelope-shaped exc.body; deleting the fallback clauses left the suite green. And test_unwrapped_403_shape_also_maps's comment described the opposite of what it fed. Fixed with _wire_shaped_error — a real openai.APIStatusError constructed directly with an explicit body — pinning both envelope.get("code") and envelope.get("detail"); mutation-checked (removing either clause fails exactly those tests).
2. Docstring overclaim: "survives a future 429 standardization" was false comfort — OpenAI's real quota dialect carries message, not detail, and deliberately stays generic (an upsell CTA on BYOK errors would be wrong). Replaced with an explicit known-limits paragraph, including that the SDK discards top-level siblings of error (the old precedence test's wire shape is unrecoverable from exc.body — that test had pinned a shape production never delivers).
3. 429 detail is now str-gated — a FastAPI validation-error LIST no longer renders its Python repr into user-facing copy with an upgrade CTA attached (+ regression test).

Mapper suite: 17 passed. Full suite: 1172 passed, 17 skipped. uv.lock still untouched.

🤖 Generated with Claude Code

[alecantu7]

Retargeted staging → main as a hotfix (Ale's call): the dead model-403 card affects every free-tier user in the current prod release (v2.26.7.13.1), and the fix is two files with no schema/config coupling — the definition of hotfix-shaped. staging is currently an ancestor of main, so the diff is unchanged by the retarget.

Post-merge note for whoever back-fills: staging will need these two commits too (same branch merges cleanly into staging, or a main→staging back-merge) so the next weekly promotion doesn't ship without them.

🤖 Generated with Claude Code

[pnewsam]

Approving -- will merge once we have Devops unlock main for the hotfixes