fix(tui): surface classified turn-error detail instead of bare request failed

[AnalogHubris]

Summary

When a turn fails, TUI/desktop frames often showed a bare request failed while the classified detail (provider, model, base_url, HTTP status, failure_reason, fallback chain) only reached logs/agent.log.

Changes

• New _classify_turn_error_message(error, agent) — prefers agent._summarize_api_error, keeps failure_reason, decorates with live route facts
• _fail_inflight_turn uses the classifier (so resume snapshots carry the same detail)
• Returned-error path in _run_prompt_submit passes the full result dict and aligns visible Error: … text with the classified message
• compute_host turn.error frames use the same classifier

Observer-side framing only — no delivery-path mutation. Composes with:

• feat(plugins): turn_failed hook — observe non-clean turn exits #56720 turn_failed (carry classified payload out)
• feat(plugins): transform_api_error_classification hook so provider plugins own their error quirks #58524 classify_api_error (plugin owns enrichment)

Test plan

• tests/tui_gateway/test_classified_turn_error.py (3)
• tests/tui_gateway/test_failed_turn_retention.py still green (8)

Related

• Tracking: Plugin Interface Expansion — community ideas, July 2026 #64182 item 3 · maintainer reply accepted the compose path
• Production-fork evidence on the tracker comment

[webdevtodayjason]

Reviewed since this builds on the compose split from the #64182 thread, and the boundary claim holds up in the code. I checked for it specifically: no classify_api_error calls, no reason derivation, the helper only surfaces facts that already exist (result fields, the agent's _summarize_api_error formatter, route attrs). Enrichment stays in the classifier where #58524 puts the plugin seam, and this composes with it for free: anything a plugin classifier adds to the summary shows up in these frames with no changes here.

The never-raises property also holds, which matters since _fail_inflight_turn calls this bare inside error handling. Whole body wrapped with a double fallback that survives even a throwing str. Good.

One small naming ask: _classify_turn_error_message doesn't classify, and that's its best property. A name like _summarize_turn_error_message keeps the seam legible to the next reader, so nobody later "fixes" it by making it classify.

One forward-looking note, not a blocker: content-wise this is a privacy improvement over bare str(exc), which dumped the whole raw error. But once this payload gets persisted or carried into a turn_failed hook (#56720), the Privacy: docstring convention from the taxonomy draft should travel with it, since error text can still carry a provider dump.

Ran tests/tui_gateway/test_classified_turn_error.py on this head locally: 3 passed.

[spfcraze]

This was generated by AI during triage.

Summary:
_classify_turn_error_message interpolates the fallback chain as a raw Python list-of-dicts, so the TUI/desktop error frame shows fallback=[{'provider': ...}] where agent/agent_init.py:1420 already formats the same structure as a readable chain.

Problems:

• tui_gateway/server.py:7217 appends f"fallback={chain}" with chain = agent._fallback_chain, a list of provider/model dicts built at agent/agent_init.py:1402-1409 — the frame shows the list repr.
• agent/agent_init.py:1420 already renders that structure as "model (provider) → model (provider)".

Solution:
Reuse the existing expression: "fallback=" + " → ".join(f"{f['model']} ({f['provider']})" for f in chain).

---

Checked against 6da9532 — the tip of fix/tui-classified-turn-error-frames when this was written — and 6564f31, main at the same moment.

[AnalogHubris]

Addressed both review notes on this head (14043de4e, rebased onto current main):

1. webdevtodayjason — renamed _classify_turn_error_message → _summarize_turn_error_message (and the two compute_host call sites). Helper still only surfaces existing facts; the name now matches that.
2. AI triage — fallback chain now renders as model (provider) → model (provider) via _format_fallback_chain, same expression as agent/agent_init.py. Added a regression test so a list-of-dicts repr cannot sneak back.

tests/tui_gateway/test_classified_turn_error.py: 4 passed.