Loop dies silently when OAuth token expires in non-interactive mode

[awilkening]

Description

When using Ralph with Claude Code authenticated via OAuth (e.g., Claude Max subscription), the OAuth access token expires after ~10-15 minutes. Claude Code fails to refresh the token when invoked non-interactively via -p with --output-format stream-json, causing a 401 error that kills the loop.

Ralph treats this as a successful completion (the process exits cleanly with error text in the output), so the loop either stops or moves on without realizing auth failed.

Reproduction

1. Authenticate Claude Code with claude /login (OAuth)
2. Start a Ralph loop
3. After 2-3 loops (~15-20 min), Claude Code returns:

   authentication_error: OAuth token has expired. Please obtain a new token or refresh your existing token.
   

4. Ralph logs show successful completion, but no actual work was done

Expected behavior

• Ralph should detect auth failures and either retry after prompting for re-auth, or clearly surface the error as a loop halt reason (not "completed successfully")
• Ideally, Ralph could detect the authentication_failed error in the stream output and set an appropriate exit reason

Actual behavior

• The loop appears to complete normally from Ralph's perspective
• status.json shows "status": "running" / "last_action": "executing" with no indication of auth failure
• .exit_signals shows no done signals
• The auth error is only visible buried in the raw stream log

Relevant log output

{"type":"result","subtype":"success","is_error":true,...,"error":"authentication_failed"}

Note "subtype":"success" combined with "is_error":true — Ralph may be keying on subtype and missing the error.

Upstream issue

This is partially a Claude Code bug — the CLI should refresh OAuth tokens in non-interactive mode. Filed upstream: anthropics/claude-code#28827

Environment

• Ralph version: latest (from ~/.ralph/ralph_loop.sh)
• Claude Code version: 2.1.59
• macOS (Darwin 25.2.0)
• Auth: OAuth (Claude Max subscription)

[coderabbitai]

🔗 Related PRs

#90 - fix(loop): respect Claude's EXIT_SIGNAL when checking completion indicators [merged]
#142 - feat(exit): detect permission denials and halt loop (Issue #101) [merged]
#179 - fix(loop): prevent silent script death on Claude timeout [merged]
#184 - fix(loop): prevent timeout from being misidentified as API 5-hour limit [merged]
#191 - feat(loop): validate Claude Code CLI command at startup (#97) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Triage: Bug 🐛

This is a confirmed bug. Ralph's response analyzer is keying on "subtype":"success" in the stream-json output while missing the accompanying "is_error":true and "error":"authentication_failed" fields — causing silent auth failures to be treated as successful completions.

Root cause: In lib/response_analyzer.sh, the JSON parsing logic likely checks subtype == "success" without also verifying is_error == false. The authentication_failed error string also needs to be added to the error detection patterns in the response analyzer (similar to how permission_denied is handled per Issue #101).

Suggested fix areas:

1. lib/response_analyzer.sh — parse_json_response(): add a check for is_error: true on result objects, and treat authentication_failed as a fatal error (not a recoverable one)
2. ralph_loop.sh — add an auth_failed exit reason (similar to permission_denied) that surfaces clearly in status.json and logs
3. Optionally: detect the specific authentication_error text pattern as a fallback in the two-stage error filter

This issue has been labeled bug and assigned for follow-up. Thank you for the detailed report including the raw JSON snippet — that's exactly the right level of detail to track this down quickly.

Generated by Issue Triage Assistant for issue #199

[traycerai]

Plan

Observations

The bug is in execute_claude_code() in file:ralph_loop.sh (line 1394). Ralph gates all success/failure logic on the OS-level exit code (exit_code -eq 0). Claude Code exits with code 0 even on OAuth failure — the auth error is only visible inside the JSON payload as "is_error":true,"error":"authentication_failed". Neither parse_json_response() nor analyze_response() in file:lib/response_analyzer.sh extract is_error/error fields, so the auth failure is completely invisible to Ralph's analysis pipeline. status.json is then written as "completed"/"success" and the loop continues silently.

Approach

Add a dedicated auth-error detection layer inside execute_claude_code() that fires before the normal success path (before save_claude_session / analyze_response). This mirrors the existing API-limit detection pattern (layers 1–3 in the failure path). Propagate the new return code (4) through main() with a clear halt + user message. Additionally surface is_error/error in parse_json_response() so the analysis file carries the information for future use.

---

Implementation Steps

1. Extract is_error and error fields in parse_json_response() — file:lib/response_analyzer.sh

Inside parse_json_response(), after the permission_denials block (around line 210), extract two new fields from the result object:

• is_error — read .is_error // false from the JSON
• error_type — read .error // "" from the JSON
• Derive is_auth_error — set to true when is_error=true and error_type matches any of: authentication_failed, authentication_error, oauth, token_expired

Add these three fields to the jq -n output block (lines 259–293) alongside the existing fields.

---

2. Propagate auth-error fields through analyze_response() — file:lib/response_analyzer.sh

In the JSON parsing branch of analyze_response() (around line 333), after reading has_permission_denials, also read:

is_auth_error  ← .is_auth_error from .json_parse_result
auth_error_type ← .error_type from .json_parse_result

Add both fields to the jq -n output block that writes .ralph/.response_analysis (lines 401–437), nested under analysis.

---

3. Add auth-error detection in execute_claude_code() — file:ralph_loop.sh

Inside the if [ $exit_code -eq 0 ] branch (line 1394), before the save_claude_session call (line 1401), insert an auth-error guard:

• Use jq to check the output file for is_error == true and an error value matching auth patterns (authentication_failed, authentication_error, oauth, token.*expired)
• As a text fallback (for cases where the result line wasn't cleanly extracted), also grep the output file for the literal strings authentication_failed, authentication_error, and OAuth token has expired
• If either check matches:
  • Log a clear ERROR message: "🔐 OAuth token has expired — Claude Code authentication failed"
  • Log the raw error value for diagnostics
  • Return 4 (new exit code for auth failure)

This mirrors the existing API-limit detection pattern (layers 2 and 3 at lines 1496–1512).

---

4. Handle return code 4 in main() — file:ralph_loop.sh

In the main() loop (lines 1705–1759), add a new elif [ $exec_result -eq 4 ] branch after the existing elif [ $exec_result -eq 3 ] (circuit breaker) branch:

• Call reset_session "auth_failed" to clear stale session state
• Call update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "auth_failed" "halted" "oauth_token_expired"
• Print a prominent user-facing error block (matching the style of the permission_denied block at lines 1654–1680):
  • Title: AUTHENTICATION FAILED — Loop Halted
  • Body: explain that the OAuth token has expired
  • Recovery steps:
    1. Run claude /login to re-authenticate
    2. Then restart with ralph --monitor
• break the loop

---

5. Update CLAUDE.md documentation — file:CLAUDE.md

In the "Error Detection" section, add a note about the new auth-error detection layer. In the "Exit Conditions and Thresholds" section, document the new exit code 4 (auth_failed) alongside the existing codes (1 = generic error, 2 = API limit, 3 = circuit breaker).

---

Data Flow

sequenceDiagram
    participant Loop as main() loop
    participant Exec as execute_claude_code()
    participant Analyzer as analyze_response()
    participant Parser as parse_json_response()

    Loop->>Exec: call (loop_count)
    Exec->>Exec: run Claude Code CLI (exit_code=0)
    Note over Exec: NEW: auth-error guard fires BEFORE save_claude_session
    Exec->>Exec: grep/jq output_file for is_error+auth patterns
    alt auth error detected
        Exec-->>Loop: return 4
        Loop->>Loop: reset_session("auth_failed")
        Loop->>Loop: update_status(..., "auth_failed", "halted")
        Loop->>Loop: print user guidance + break
    else no auth error
        Exec->>Analyzer: analyze_response(output_file)
        Analyzer->>Parser: parse_json_response(output_file)
        Parser-->>Analyzer: result incl. is_auth_error, error_type
        Analyzer-->>Exec: writes .response_analysis
        Exec-->>Loop: return 0
    end

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The bug is in `execute_claude_code()` in `file:ralph_loop.sh` (line 1394). Ralph gates all success/failure logic on the OS-level exit code (`exit_code -eq 0`). Claude Code exits with code **0** even on OAuth failure — the auth error is only visible inside the JSON payload as `"is_error":true,"error":"authentication_failed"`. Neither `parse_json_response()` nor `analyze_response()` in `file:lib/response_analyzer.sh` extract `is_error`/`error` fields, so the auth failure is completely invisible to Ralph's analysis pipeline. `status.json` is then written as `"completed"/"success"` and the loop continues silently.

## Approach

Add a dedicated auth-error detection layer inside `execute_claude_code()` that fires **before** the normal success path (before `save_claude_session` / `analyze_response`). This mirrors the existing API-limit detection pattern (layers 1–3 in the failure path). Propagate the new return code (4) through `main()` with a clear halt + user message. Additionally surface `is_error`/`error` in `parse_json_response()` so the analysis file carries the information for future use.

---

## Implementation Steps

### 1. Extract `is_error` and `error` fields in `parse_json_response()` — `file:lib/response_analyzer.sh`

Inside `parse_json_response()`, after the `permission_denials` block (around line 210), extract two new fields from the result object:

- `is_error` — read `.is_error // false` from the JSON
- `error_type` — read `.error // ""` from the JSON
- Derive `is_auth_error` — set to `true` when `is_error=true` **and** `error_type` matches any of: `authentication_failed`, `authentication_error`, `oauth`, `token_expired`

Add these three fields to the `jq -n` output block (lines 259–293) alongside the existing fields.

---

### 2. Propagate auth-error fields through `analyze_response()` — `file:lib/response_analyzer.sh`

In the JSON parsing branch of `analyze_response()` (around line 333), after reading `has_permission_denials`, also read:

```
is_auth_error  ← .is_auth_error from .json_parse_result
auth_error_type ← .error_type from .json_parse_result
```

Add both fields to the `jq -n` output block that writes `.ralph/.response_analysis` (lines 401–437), nested under `analysis`.

---

### 3. Add auth-error detection in `execute_claude_code()` — `file:ralph_loop.sh`

Inside the `if [ $exit_code -eq 0 ]` branch (line 1394), **before** the `save_claude_session` call (line 1401), insert an auth-error guard:

- Use `jq` to check the output file for `is_error == true` and an `error` value matching auth patterns (`authentication_failed`, `authentication_error`, `oauth`, `token.*expired`)
- As a text fallback (for cases where the result line wasn't cleanly extracted), also `grep` the output file for the literal strings `authentication_failed`, `authentication_error`, and `OAuth token has expired`
- If either check matches:
  - Log a clear `ERROR` message: `"🔐 OAuth token has expired — Claude Code authentication failed"`
  - Log the raw error value for diagnostics
  - Return **4** (new exit code for auth failure)

This mirrors the existing API-limit detection pattern (layers 2 and 3 at lines 1496–1512).

---

### 4. Handle return code 4 in `main()` — `file:ralph_loop.sh`

In the `main()` loop (lines 1705–1759), add a new `elif [ $exec_result -eq 4 ]` branch after the existing `elif [ $exec_result -eq 3 ]` (circuit breaker) branch:

- Call `reset_session "auth_failed"` to clear stale session state
- Call `update_status "$loop_count" "$(cat "$CALL_COUNT_FILE")" "auth_failed" "halted" "oauth_token_expired"`
- Print a prominent user-facing error block (matching the style of the `permission_denied` block at lines 1654–1680):
  - Title: `AUTHENTICATION FAILED — Loop Halted`
  - Body: explain that the OAuth token has expired
  - Recovery steps:
    1. Run `claude /login` to re-authenticate
    2. Then restart with `ralph --monitor`
- `break` the loop

---

### 5. Update `CLAUDE.md` documentation — `file:CLAUDE.md`

In the **"Error Detection"** section, add a note about the new auth-error detection layer. In the **"Exit Conditions and Thresholds"** section, document the new exit code 4 (`auth_failed`) alongside the existing codes (1 = generic error, 2 = API limit, 3 = circuit breaker).

---

## Data Flow

```mermaid
sequenceDiagram
    participant Loop as main() loop
    participant Exec as execute_claude_code()
    participant Analyzer as analyze_response()
    participant Parser as parse_json_response()

    Loop->>Exec: call (loop_count)
    Exec->>Exec: run Claude Code CLI (exit_code=0)
    Note over Exec: NEW: auth-error guard fires BEFORE save_claude_session
    Exec->>Exec: grep/jq output_file for is_error+auth patterns
    alt auth error detected
        Exec-->>Loop: return 4
        Loop->>Loop: reset_session("auth_failed")
        Loop->>Loop: update_status(..., "auth_failed", "halted")
        Loop->>Loop: print user guidance + break
    else no auth error
        Exec->>Analyzer: analyze_response(output_file)
        Analyzer->>Parser: parse_json_response(output_file)
        Parser-->>Analyzer: result incl. is_auth_error, error_type
        Analyzer-->>Exec: writes .response_analysis
        Exec-->>Loop: return 0
    end
```

---

Execution Information

Branch: main
Commit: 6ff27b4

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.