TUI: guide users through recoverable model-blocking errors

Variant

CLI / TUI

Problem

Some model-blocking errors are technically accurate, but they leave the user at a dead end in the TUI.

I hit this with a selected-model-capacity error. My first assumption was that I had run out of quota, so I stopped and checked /status. The status view showed that this was not really a quota problem. It was a capacity/context issue with the model I had selected.

At that point the useful recovery choices were manual:

• compact the conversation, then type continue
• clear the session and restate the task
• choose a different model
• inspect status/model information before deciding

The problem is that the TUI only reports the failure. It does not guide the user toward those next actions, so the user has to infer the recovery path.

This is especially painful mid-task. If Codex is already working through a multi-step change, losing the thread means the user has to manually reconstruct the previous task so Codex can verify state and continue. A better recovery flow should preserve task continuity where possible, or at least make the safest next step explicit.

Concrete cases

• ContextWindowExceeded: the conversation is too large and the user needs to decide whether to compact, clear, inspect status, or dismiss.
• Selected-model capacity errors, for example: Selected model is at capacity. Please try a different model. See #28514.

Related reports:

• #28514: selected model is repeatedly at capacity in the Codex app.
• #28303: remote compact task fails with selected model capacity.
• #27149: capacity errors interact poorly with session/context recovery.
• #23847, #22456, #22277, #19583, #19579, #19446: earlier selected-model-capacity reports.
• #22390: broader retry/backoff proposal. This issue is a smaller TUI/manual-recovery slice that can complement that work.

Proposed behavior

When a recoverable blocking model error reaches the TUI, show an interactive recovery picker instead of only rendering the error.

For context-window exhaustion, offer:

• compact conversation
• start fresh / clear
• show status
• dismiss

For selected-model capacity, offer:

• choose a different model
• show status/model info
• retry later / dismiss

Do not automatically choose a replacement model for the user. The point is to make the safe choices explicit while keeping the human in control.

Task-continuity follow-up

There is also a related workflow worth considering: when the user needs to clear or fork from an old conversation, Codex could help carry the current task forward into a new session so progress is not broken. That could be a separate follow-up if it is larger than the recovery picker itself.

Non-goals

• No backend quota, capacity, or routing changes.
• No automatic model switching.
• No full retry/backoff state machine in this issue.
• No silent context discard.

Suggested implementation shape

• Route known recoverable model-blocking errors through small TUI recovery handlers.
• Finalize the current turn and show a short history message explaining what happened.
• Open a bottom-pane picker with explicit actions.
• Reuse existing TUI mechanisms such as /compact, /model, /status, clear, and fork/new-session flows.
• Add debug-only slash commands where useful so maintainers can test the UI without spending model tokens.

Local implementation status

I have a local implementation for the ContextWindowExceeded case:

• opens a Context window full picker
• supports compact, start fresh, show status, and dismiss
• includes a debug-only /test-context-window shortcut
• includes targeted tests and an insta snapshot

Validation run locally:

• just fmt
• just test -p codex-tui context_window
• just fix -p codex-tui

Per docs/contributing.md, I am sharing the problem analysis and proposed direction here first. If the Codex team agrees this is useful and aligned, I can keep an invited PR narrowly scoped to the context-window recovery picker, with selected-model-capacity recovery as a follow-up using the same pattern.