fix(auth): actionable error message when Codex refresh token is reused by another client - #5612
Merged
teknium1 merged 1 commit intoApr 6, 2026
Conversation
When the Codex CLI (or VS Code extension) consumes a refresh token before Hermes can use it, Hermes previously surfaced a generic 401 error with no actionable guidance. - In `refresh_codex_oauth_pure`: detect `refresh_token_reused` from the OAuth endpoint and raise an AuthError explaining the cause and the exact steps to recover (run `codex` to refresh, then `hermes login`). - In `run_agent.py`: when provider is `openai-codex` and HTTP 401 is received, show Codex-specific recovery steps instead of the generic "check your API key" message. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
14 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When the Codex CLI or VS Code extension refreshes OAuth tokens, the shared refresh token is consumed. If Hermes then tries to refresh using the same (now-stale) token, the OpenAI OAuth endpoint returns `refresh_token_reused`. Hermes currently surfaces this as a generic 401 with advice to check your API key — which is confusing and unhelpful since the account is fine.
Changes
`hermes_cli/auth.py` — detect `refresh_token_reused` specifically in `refresh_codex_oauth_pure()` and raise an `AuthError` with an explanation and recovery steps:
`run_agent.py` — when provider is `openai-codex` and HTTP 401 is received, show Codex-specific recovery steps instead of the generic "is your API key valid?" message.
Why only these cases
The `refresh_token_reused` branch in `auth.py` is gated on the exact error code from the OAuth endpoint. The `run_agent.py` change is gated on `_provider == "openai-codex" and status_code == 401` — all other providers and status codes are unchanged.
Reproduction