Resume fail loop

[ValentinFunk]

I'm not really sure what exactly happens but the tool very frequently get's into a loop for me where it tries to resume but then somehow keeps appending the session id. E.g.

Error: --resume requires a valid session ID or session title when used with --print. Usage: claude -p --resume <session-id|title>. Provided value "3617d7ce-03a5-4def-9367-209a4568d324
3617d7ce-03a5-4def-9367-209a4568d324
3617d7ce-03a5-4def-9367-209a4568d324
3617d7ce-03a5-4def-9367-209a4568d324" is not a UUID and does not match any session title.

This can happen over several thousand lines with the UUID repeating with a \n.

Manually going into .ralph/.claude_session_id and removing the 1000+ lines of duplicate UUID makes it run again

[github-actions]

Thanks for the detailed report, @ValentinFunk! 🐛

This has been triaged as a bug.

What's happening: The .ralph/.claude_session_id file is being corrupted — the session UUID is appended (rather than overwritten) on each loop iteration, resulting in a file with thousands of duplicate UUID lines separated by newlines. When Ralph then reads that file and passes the multi-line content to --resume, the Claude CLI rejects it because it's not a valid single UUID.

Root cause area: The store_session_id() function in lib/response_analyzer.sh is likely using >> (append) instead of > (overwrite) when writing the session ID, or the file isn't being truncated before writing.

Workaround (as you discovered): Manually delete or truncate .ralph/.claude_session_id:

> .ralph/.claude_session_id
# or
ralph --reset-session

Next steps for the fix:

• Ensure store_session_id() always overwrites the file (>) rather than appending
• Add a guard in get_last_session_id() to read only the first non-empty line, so even a corrupted file recovers gracefully

This will be assigned to the maintainer for a fix. Thank you for including the exact error message and the reproduction detail — very helpful!

Generated by Issue Triage Assistant for issue #254

[coderabbitai]

Coding Plan

Summary

• Apply head -1 to all jq session ID extractions to prevent multi-line capture from NDJSON streams
• Sanitize session ID on read with head -1 and length validation to handle already-corrupted files
• Unify write format to plain strings (remove JSON wrapper in store_session_id)
• Add auto-recovery that detects multi-line corruption and resets to fresh session state

Design Choices

Design Choice 1: Session ID format consistency

Options Considered:

1. Unify all writes to use plain string format
2. Unify all writes to use JSON format
3. Keep both formats but make reads handle both

Chosen Option: 1

Rationale: Plain string format is simpler, matches what Claude CLI expects, and is what init_claude_session() reads with cat. Converting store_session_id() to match avoids the JSON/string mismatch bug.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Harden Session ID Extraction and Validation

This phase addresses the root cause by ensuring all session ID extraction paths return exactly one line, and adds defensive sanitization on both read and write paths.

Task 1: Fix NDJSON Multi-Line Extraction in save_claude_session()

Ensure jq extraction returns only a single session ID even when processing NDJSON with multiple matching objects.

• In ralph_loop.sh save_claude_session() (around line 1024), pipe the jq extraction through head -1 to ensure only the first matching session ID is captured
• This prevents the scenario where stream-json output without a result line causes jq to emit one session ID per NDJSON line

Task 2: Fix Fallback Session ID Extraction

Apply the same single-line guarantee to the timeout fallback extraction path.

• In ralph_loop.sh around line 1631-1634, ensure the jq extraction for fallback_session_id from the system message uses head -1
• This is already extracting from a single JSON line, but defensive coding prevents future regressions

Task 3: Sanitize Session ID on Read

Add defensive first-line extraction when reading the session file, ensuring corrupted files don't propagate bad values.

• In ralph_loop.sh init_claude_session() (line 996), change cat "$CLAUDE_SESSION_FILE" to head -1 "$CLAUDE_SESSION_FILE" to extract only the first line
• This ensures that even if the file is somehow corrupted with multiple lines, only the first (valid) session ID is used
• Add a basic length check (session IDs are 36 characters) to detect obvious corruption and trigger file deletion/reset

Task 4: Align store_session_id() Output Format

Resolve the format mismatch where store_session_id() writes JSON but init_claude_session() reads plain text.

• In lib/response_analyzer.sh store_session_id() (lines 840-857), change from writing a JSON object to writing just the plain session ID string (matching save_claude_session() behavior)
• This eliminates the bug where the next iteration reads {"session_id":"abc..."} as the session ID

Task 5: Add Pre-Write Validation

Add validation before writing to catch multi-line or malformed session IDs early.

• Create a small validation helper function in ralph_loop.sh that checks: (a) single line (no embedded newlines), (b) non-empty, (c) reasonable length (30-50 chars for UUID format)
• Apply this validation in save_claude_session() before the echo write—if validation fails, log a warning and skip the write rather than persisting corrupt data
• Consider applying the same validation in store_session_id() in lib/response_analyzer.sh

🤖 Prompt for AI agents

This phase hardens the session ID extraction and write paths to prevent
multi-line corruption and format mismatches. The goal is to ensure all paths
produce and consume exactly one plain-text session ID string.

**Task 1: Fix NDJSON Multi-Line Extraction in `save_claude_session()`
(`ralph_loop.sh` ~line 1024)**
- Locate the `jq` extraction call inside `save_claude_session()`
- Pipe its output through `head -1` so only the first matching session ID is
captured, even when NDJSON contains multiple objects with session_id fields

**Task 2: Fix Fallback Session ID Extraction (`ralph_loop.sh` ~lines
1631-1634)**
- Locate the `jq` extraction for `fallback_session_id` from the system message
- Pipe its output through `head -1` for defensive single-line enforcement

**Task 3: Sanitize Session ID on Read (`ralph_loop.sh` `init_claude_session()`
~line 996)**
- Replace `cat "$CLAUDE_SESSION_FILE"` with `head -1 "$CLAUDE_SESSION_FILE"` to
only read the first line
- After reading, add a basic length check: session IDs are expected to be 36
characters; if the value fails this check, delete the file and reset (return
empty string)

**Task 4: Align `store_session_id()` Output Format (`lib/response_analyzer.sh`
~lines 840-857)**
- Change `store_session_id()` from writing a JSON object (e.g.,
`{"session_id":"..."}`) to writing only the plain session ID string
- This makes the output consistent with `save_claude_session()` and compatible
with the `cat`/`head -1` read path in `init_claude_session()`

**Task 5: Add Pre-Write Validation Helper (`ralph_loop.sh`)**
- Create a small validation helper function that checks: (a) the value is a
single line with no embedded newlines, (b) it is non-empty, (c) its length is
between 30-50 characters (UUID format)
- Call this helper in `save_claude_session()` before writing; if validation
fails, log a warning and skip the write
- Optionally apply the same validation in `store_session_id()` in
`lib/response_analyzer.sh`

Phase 2: Add Recovery for Corrupted State

This phase ensures that when corruption is detected, the system can self-heal rather than entering a permanent failure loop.

Task 1: Detect and Auto-Recover Corrupted Session Files

Add detection of multi-line session files and automatic cleanup.

• In init_claude_session(), after reading the first line, check if the file has more than one line using wc -l or similar
• If corruption is detected, log a warning, delete the corrupted file, and return empty string to start a fresh session
• This provides automatic recovery without requiring manual intervention

Task 2: Handle CLI Argument Validation Errors

Ensure Claude CLI argument errors (like invalid --resume value) properly reset session state.

• In the error handling path of execute_claude_code(), check if the error message contains patterns like "not a valid session ID" or "--resume requires"
• If detected, call reset_session() to clear the corrupted session file and allow recovery on next iteration
• This closes the loop where argument validation errors leave the corrupted file in place

🤖 Prompt for AI agents

This phase adds self-healing recovery so that when session corruption is
detected, the system resets automatically rather than entering a permanent
failure loop.

**Task 1: Detect and Auto-Recover Corrupted Session Files (`ralph_loop.sh`
`init_claude_session()`)**
- After reading the first line of `$CLAUDE_SESSION_FILE`, use `wc -l` (or
equivalent) to check if the file contains more than one line
- If more than one line is detected, log a warning message indicating corruption
was found, delete the corrupted file, and return an empty string to trigger a
fresh session

**Task 2: Handle CLI Argument Validation Errors (`ralph_loop.sh`
`execute_claude_code()` error handling path)**
- In the error handling path of `execute_claude_code()`, inspect the error
message for patterns such as "not a valid session ID" or "--resume requires"
- If such patterns are matched, call `reset_session()` to clear the corrupted
session file
- This ensures the corrupted file is removed so the next iteration can start
fresh rather than re-encountering the same invalid `--resume` argument

Research

Ralph uses two session-related files: .ralph/.claude_session_id for the Claude API session ID and .ralph/.ralph_session for internal lifecycle tracking. The Claude session file has multiple write paths in ralph_loop.sh (save_claude_session() at line 1026, fallback at line 1634) and lib/response_analyzer.sh (store_session_id() at line 854). The read path in init_claude_session() uses cat to read the entire file. In stream-json mode, jq extracts session IDs from NDJSON without limiting to a single result, causing multi-line values when multiple stream messages contain session_id fields.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase hardens the session ID extraction and write paths to prevent
multi-line corruption and format mismatches. The goal is to ensure all paths
produce and consume exactly one plain-text session ID string.

**Task 1: Fix NDJSON Multi-Line Extraction in `save_claude_session()`
(`ralph_loop.sh` ~line 1024)**
- Locate the `jq` extraction call inside `save_claude_session()`
- Pipe its output through `head -1` so only the first matching session ID is
captured, even when NDJSON contains multiple objects with session_id fields

**Task 2: Fix Fallback Session ID Extraction (`ralph_loop.sh` ~lines
1631-1634)**
- Locate the `jq` extraction for `fallback_session_id` from the system message
- Pipe its output through `head -1` for defensive single-line enforcement

**Task 3: Sanitize Session ID on Read (`ralph_loop.sh` `init_claude_session()`
~line 996)**
- Replace `cat "$CLAUDE_SESSION_FILE"` with `head -1 "$CLAUDE_SESSION_FILE"` to
only read the first line
- After reading, add a basic length check: session IDs are expected to be 36
characters; if the value fails this check, delete the file and reset (return
empty string)

**Task 4: Align `store_session_id()` Output Format (`lib/response_analyzer.sh`
~lines 840-857)**
- Change `store_session_id()` from writing a JSON object (e.g.,
`{"session_id":"..."}`) to writing only the plain session ID string
- This makes the output consistent with `save_claude_session()` and compatible
with the `cat`/`head -1` read path in `init_claude_session()`

**Task 5: Add Pre-Write Validation Helper (`ralph_loop.sh`)**
- Create a small validation helper function that checks: (a) the value is a
single line with no embedded newlines, (b) it is non-empty, (c) its length is
between 30-50 characters (UUID format)
- Call this helper in `save_claude_session()` before writing; if validation
fails, log a warning and skip the write
- Optionally apply the same validation in `store_session_id()` in
`lib/response_analyzer.sh`
===============================================================================

Task: 2

This phase adds self-healing recovery so that when session corruption is
detected, the system resets automatically rather than entering a permanent
failure loop.

**Task 1: Detect and Auto-Recover Corrupted Session Files (`ralph_loop.sh`
`init_claude_session()`)**
- After reading the first line of `$CLAUDE_SESSION_FILE`, use `wc -l` (or
equivalent) to check if the file contains more than one line
- If more than one line is detected, log a warning message indicating corruption
was found, delete the corrupted file, and return an empty string to trigger a
fresh session

**Task 2: Handle CLI Argument Validation Errors (`ralph_loop.sh`
`execute_claude_code()` error handling path)**
- In the error handling path of `execute_claude_code()`, inspect the error
message for patterns such as "not a valid session ID" or "--resume requires"
- If such patterns are matched, call `reset_session()` to clear the corrupted
session file
- This ensures the corrupted file is removed so the next iteration can start
fresh rather than re-encountering the same invalid `--resume` argument

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[Jocho-Smith]

I have the same problem.