Improve error hint for Claude Code session archival failures #228
Description
Context
When Claude Code auto-archives a session between Untether resume runs, the next --resume fails with error_during_execution (rc=1, 0 turns, $0.00 cost). This was observed on staging (@hetz_lba1_bot, v0.35.0rc13) in the wpnav chat on 2026-03-26.
Related upstream issue: anthropics/claude-code#39178 — --resume fails when session JSONL was auto-archived during idle period.
What happened
Session 0a1e105b was actively used via Untether across 2 days (8 successful resumes, 138 turns, ~$38, 5.9MB/1953 lines). Claude Code auto-archived the session JSONL 29 minutes after the last successful run. The next resume attempt failed with error_during_execution.
Timeline
| Time (AEDT) | Event |
|---|---|
| Mar 24 15:30 | Session created |
| Mar 25-26 | 7 successful resumes over 2 days |
| Mar 26 14:01 | Last successful run completes |
| Mar 26 14:30 | Claude Code archives session (JSONL moved to ~/.claude/projects-archive/) |
| Mar 26 15:44 | Untether resumes → error_during_execution, rc=1, 0 turns |
Why this affects Untether more than CLI
Untether's resume pattern creates sessions that are longer-lived and larger than typical interactive CLI usage — sessions accumulate many turns across hours/days of --resume calls. Claude Code's session management likely assumes shorter-lived sessions.
Changes made
Error hint text updated (error_hints.py)
The previous hint text said "corrupted during a restart" which was misleading — the actual cause is auto-archival, not corruption.
Before: "The session failed to load — it may have been corrupted during a restart. Send /new to start a fresh session."
After: "The session could not be loaded — Claude Code may have archived or expired it. Send /new to start a fresh session."
Existing mitigations (already working)
- Auto-clear broken resume token (v0.25.3, fix: auto-recover from corrupted session resume after restart #45) — when a resumed run fails with 0 turns, the saved token is automatically cleared so the next message starts fresh
- Error hint system — shows actionable guidance to the user
Future considerations
Depending on the outcome of the upstream issue (anthropics/claude-code#39178), we may want to:
- Proactive session health check — after a successful run, verify the session JSONL still exists in the active project dir; if archived, auto-clear the resume token immediately rather than failing on the next resume
- Session age/size warnings — warn users when sessions are getting large and may be at risk of archival
- Session rotation — proactively start fresh sessions after N turns or N days (trade-off: loses conversation context)