claude-code: stale session state causes "Session ID already in use" after workspace restart

[blinkagent]

Problem

When a workspace is terminated unexpectedly (pod killed, node drained, etc.), Claude's session state files persist on storage. On restart, the start.sh script detects the existing session file via task_session_exists + is_valid_session and uses --resume, but Claude may reject the session as conflicting if other stale metadata files are in an inconsistent state.

Additionally, if the session file exists but is in a state that passes validation yet Claude considers it "in use" (e.g. incomplete shutdown), there is no recovery path — the script has no mechanism to clean up stale session metadata and retry with a fresh session.

Root Cause

Claude CLI creates multiple files to track session state:

• ~/.claude/projects/<dir>/<session-id>.jsonl — session transcript
• ~/.claude/todos/<session-id>*.json — todo state
• ~/.claude/debug/<session-id>.txt — debug logs
• ~/.claude/session-env/<session-id> — environment state

The current start.sh script only checks for and validates the .jsonl session transcript file (task_session_exists and is_valid_session). It does not:

1. Clean up stale metadata files in ~/.claude/todos/, ~/.claude/debug/, or ~/.claude/session-env/ on startup
2. Handle the case where --resume fails (no fallback to starting a fresh session)
3. Use any form of process-level lock (e.g. flock) to distinguish between an active session and leftover files from a dead process

Suggested Fix

1. Add stale session cleanup on startup: Before attempting to resume, remove orphaned metadata files (todos, debug, session-env) for the hardcoded TASK_SESSION_ID when no Claude process is running.
2. Add fallback logic: If --resume fails, fall back to removing the stale session file and starting fresh with --session-id.
3. Consider flock-based locking: Use file locking to detect whether a session is genuinely active vs. leftover from a killed process.

Workaround

Manually remove stale session metadata before starting:

rm -f ~/.claude/projects/*/<session-id>.jsonl
rm -f ~/.claude/todos/<session-id>*.json
rm -f ~/.claude/debug/<session-id>.txt
rm -f ~/.claude/session-env/<session-id>

---

Created on behalf of @matifali