Codex CLI hangs indefinitely when the workspace is out of credits

• severity/high

---

Summary

When a Codex CLI session is started after the account has exhausted its credits, the TUI never surfaces the insufficient_quota error the service returns. The UI keeps showing “Processing request…” forever and the codex process never exits, so every automation that shells out to the CLI hangs until the user manually kills the job. Because this looks like a job that is still running, operators routinely wait 10–15 minutes before realizing nothing will ever complete.

Environment

• Codex CLI 0.57.0 (codex --version)
• macOS 26.0.1 (arm64, Apple Silicon)
• Invoked via non-interactive automation that shells out to codex for every /codex … invocation

Steps to Reproduce

1. Sign into Codex CLI with an organization/workspace that has zero credits remaining (easy to do after the free trial expires).
2. From any repo, run a command that spends credits, e.g.

``bash
CODex_CONFIG_ROOT=~/.codex codex run --repo . "git status"
``
(the exact subcommand does not matter; any job that reaches the Codex backend will behave the same way).

1. Watch the spinner: the UI prints repeated Processing request (elapsed …) lines forever and never emits a result or an error.

Expected Behavior

• The CLI should detect that the backend returned insufficient_quota/HTTP 402 immediately.
• Show a clear, actionable error such as “This workspace is out of credits. Visit https://github.com/settings/billing/codex to top up or switch to a funded workspace.”
• Exit with a non-zero status so scripts can detect the failure in under a second.

Actual Behavior

• The CLI keeps polling and emitting “Processing request (elapsed …)” indefinitely (I let it sit for ~12 minutes).
• No error is printed, the spinner never resolves, and the process has to be terminated manually with Ctrl+C.
• Because the dashboard captures the subprocess stream synchronously, the entire automation loop freezes; no other /codex … commands can run, and longer-running flows never finish.
• There is no final log entry because we never reach the Codex exited with code … line unless we abort by hand.

Impact

• Frontline users think Codex is still “working” and end up waiting indefinitely even though the backend rejected the run instantly.
• Every Codex-backed automation in this repo is single-threaded, so one exhausted account stalls the whole set of agents until an operator notices the lack of progress.
• CI and tmux helpers expect Codex to fail fast; with the current behavior they block tmux panes forever and the quality gate can never finish.
• The only workaround today is “remember to keep watching your billing dashboard”, which is extremely brittle for a tool that is supposed to run unattended.

Proposed Fix / Ideas

1. Treat insufficient_quota, requires_payment_method, and HTTP 402 responses as terminal states in the poller. Break out of the spinner loop and surface the backend error verbatim.
2. Exit with a unique non-zero code (for example 74) so wrappers can handle “out-of-credits” differently from other API errors (e.g., auto-swap to a backup workspace).
3. Consider issuing a pre-flight billing check before queueing work so the user sees the error instantly rather than waiting until after the job is submitted.
4. Bonus: expose a lightweight codex billing status command that prints the remaining credits so automations can gate on it before launching a burst of jobs.

Workaround

Only manual intervention: press Ctrl+C, open the Codex billing page, add credits, and re-run the command. Until the CLI itself exits with a clear error, every higher-level workflow will continue to hang whenever an agent lands on an empty account.