docs(codex): ground Hermes recovery steps in documented invocations

The recovery text named speculative command forms — `hermes ask
--provider openai-codex` and `codex-auth-sync` / `hermes export
codex-auth` helper scripts — none of which exist in any documented
Hermes install. An agent following the skill verbatim would run
nonexistent commands.

Rewrite both steps capability-level: smoke-test via whatever invocation
the local Hermes install documents (`hermes --help`), and repair
`~/.codex/auth.json` by locating the openai-codex provider's token
store in Hermes' own state directory, explicitly noting there is no
standard gstack helper. The diagnostic order and the split-brain
explanation are unchanged.

Refs #1542.
This commit is contained in:
0xDevNinja 2026-07-16 14:42:46 +05:30
parent 78971b8b0a
commit c651c0b293
2 changed files with 4 additions and 4 deletions

View File

@ -1500,8 +1500,8 @@ If token count is not available, display: `Tokens: unknown`
- **Auth error — `refresh_token_reused` specifically (Hermes-aware recovery):**
When stderr contains `refresh_token_reused`, do **not** go straight to `codex login`. Hermes' `openai-codex` provider can still be serving valid tokens while the standalone `~/.codex/auth.json` credential store has gone stale (split-brain auth). Sending the user to `codex login` in that state wipes a working session that downstream skills relied on.
Diagnose, then repair, in this order:
1. **Smoke-test the Hermes provider first** (if Hermes is installed). Run a trivial call through Hermes' `openai-codex` provider — e.g. `hermes ask --provider openai-codex 'ping'` or the equivalent profile-routed invocation. If it succeeds, the user's OpenAI session is still good; the failure is local to standalone `codex exec`'s credential store.
2. **If Hermes works:** repair `~/.codex/auth.json` from the Hermes-side tokens instead of forcing a re-login. The exact helper varies by Hermes version (look for a `codex-auth-sync` / `hermes export codex-auth` style script in the local Hermes install). After copying the refreshed tokens back into `~/.codex/auth.json`, `chmod 600 ~/.codex/auth.json` and rerun the original `codex exec` to verify.
1. **Smoke-test the Hermes provider first** (if Hermes is installed). Run any trivial request through Hermes' `openai-codex` provider using whatever invocation the local Hermes install documents (`hermes --help` lists its commands; a profile routed to `openai-codex` also works). If the call succeeds, the user's OpenAI session is still good; the failure is local to standalone `codex exec`'s credential store.
2. **If Hermes works:** repair `~/.codex/auth.json` from the Hermes-side tokens instead of forcing a re-login. Hermes stores its provider credentials in its own state directory — find where the `openai-codex` provider keeps its OAuth tokens (check the Hermes install's docs or config; there is no standard gstack helper for this), copy the refreshed `access_token` / `refresh_token` values into `~/.codex/auth.json`, then `chmod 600 ~/.codex/auth.json` and rerun the original `codex exec` to verify.
3. **If Hermes is not installed or the Hermes provider also fails:** that confirms the OpenAI session itself is gone; `codex login` is the right next step. Run it, then re-invoke the skill.
Tell the user which branch you're on before suggesting any action — "Hermes provider still works, repairing `~/.codex/auth.json` from Hermes tokens" vs. "Hermes provider is also down, running `codex login`" — so they know whether they're about to lose a working Hermes session or not.
- **Timeout (Bash outer gate):** If the Bash call times out (5 min for Review/Challenge, 10 min for Consult), tell the user:

View File

@ -621,8 +621,8 @@ If token count is not available, display: `Tokens: unknown`
- **Auth error — `refresh_token_reused` specifically (Hermes-aware recovery):**
When stderr contains `refresh_token_reused`, do **not** go straight to `codex login`. Hermes' `openai-codex` provider can still be serving valid tokens while the standalone `~/.codex/auth.json` credential store has gone stale (split-brain auth). Sending the user to `codex login` in that state wipes a working session that downstream skills relied on.
Diagnose, then repair, in this order:
1. **Smoke-test the Hermes provider first** (if Hermes is installed). Run a trivial call through Hermes' `openai-codex` provider — e.g. `hermes ask --provider openai-codex 'ping'` or the equivalent profile-routed invocation. If it succeeds, the user's OpenAI session is still good; the failure is local to standalone `codex exec`'s credential store.
2. **If Hermes works:** repair `~/.codex/auth.json` from the Hermes-side tokens instead of forcing a re-login. The exact helper varies by Hermes version (look for a `codex-auth-sync` / `hermes export codex-auth` style script in the local Hermes install). After copying the refreshed tokens back into `~/.codex/auth.json`, `chmod 600 ~/.codex/auth.json` and rerun the original `codex exec` to verify.
1. **Smoke-test the Hermes provider first** (if Hermes is installed). Run any trivial request through Hermes' `openai-codex` provider using whatever invocation the local Hermes install documents (`hermes --help` lists its commands; a profile routed to `openai-codex` also works). If the call succeeds, the user's OpenAI session is still good; the failure is local to standalone `codex exec`'s credential store.
2. **If Hermes works:** repair `~/.codex/auth.json` from the Hermes-side tokens instead of forcing a re-login. Hermes stores its provider credentials in its own state directory — find where the `openai-codex` provider keeps its OAuth tokens (check the Hermes install's docs or config; there is no standard gstack helper for this), copy the refreshed `access_token` / `refresh_token` values into `~/.codex/auth.json`, then `chmod 600 ~/.codex/auth.json` and rerun the original `codex exec` to verify.
3. **If Hermes is not installed or the Hermes provider also fails:** that confirms the OpenAI session itself is gone; `codex login` is the right next step. Run it, then re-invoke the skill.
Tell the user which branch you're on before suggesting any action — "Hermes provider still works, repairing `~/.codex/auth.json` from Hermes tokens" vs. "Hermes provider is also down, running `codex login`" — so they know whether they're about to lose a working Hermes session or not.
- **Timeout (Bash outer gate):** If the Bash call times out (5 min for Review/Challenge, 10 min for Consult), tell the user: