claude-code - 💡(How to fix) Fix Auto-compaction deletes main session JSONL before verifying summary completion, causing data loss

Bug Description

The auto-compaction (automatic summarization) process appears to delete/truncate the main session JSONL file before confirming that the summary subagent has successfully completed. When the summary API call fails, the original conversation data is permanently lost, making --resume impossible.

Steps to Reproduce

1. Start a long Claude Code session with heavy use of MCP Puppeteer (many screenshots accumulate as base64 images in the conversation)
2. Continue the session until auto-compaction triggers multiple times
3. If the compaction subagent hits an API error (e.g., image dimension limits), the main session JSONL is deleted with no recovery

Evidence from Affected Session

Session ID: d9414fd5-97f6-417d-a761-8ed30ebf671f

Directory state after the incident:

d9414fd5-97f6-417d-a761-8ed30ebf671f/
  subagents/
    agent-ab84155.jsonl          (106KB, research subagent - completed)
    agent-af9453f.jsonl          (29KB, research subagent - completed)
    agent-ad1f74c.jsonl          (500KB, research subagent - completed)
    agent-acompact-f5ecdb.jsonl  (484KB, 1st compaction - SUCCESS)
    agent-acompact-435c8f.jsonl  (314KB, 2nd compaction - FAILED)

No main d9414fd5-...jsonl file exists. The directory and subagents remain, but the parent conversation is gone.

Timeline:

The API error that killed the session:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages.67.content.6.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"
  }
}

The compaction subagent tried to send the full conversation (including accumulated Puppeteer screenshot base64 data) to the API for summarization. The API rejected it due to image dimension limits on multi-image requests.

Comparison with a working session:

Session 88a2c168-c2b4-4a61-8c3c-da768be1c3fc also had 3 compaction cycles but all succeeded. Its main JSONL (75MB) is intact. This confirms the issue is specifically triggered when compaction fails.

Expected Behavior

• The main session JSONL should never be deleted until the compaction summary is confirmed successful
• If compaction fails, the original JSONL should be preserved (the session may be large, but at least --resume still works)
• Ideally, a backup of the original JSONL should be kept until the new compacted version is verified

Actual Behavior

• The main JSONL is deleted/truncated as part of the compaction process
• When the compaction API call fails, the original data is already gone
• The session becomes unresumable (--resume <id> fails)
• Only subagent logs survive (they contain delegated tasks, not the parent conversation)

Environment

• OS: macOS (Darwin 21.6.0)
• Claude Code: CLI
• Date of incident: 2026-03-31
• Session characteristics: Heavy MCP Puppeteer usage (15+ page navigations with screenshots), 11 user-provided PNG images, multiple research subagents

Suggested Fix

1. Atomic replacement: Write the compacted JSONL to a temp file first, then atomically rename it to replace the original only after success
2. Backup before compaction: Keep <session>.jsonl.bak until the new version is verified
3. Strip images before compaction: Remove or downsample base64 image data before sending to the summary API to avoid hitting image limits
4. Graceful degradation: If compaction fails, log a warning and continue with the original (large) conversation intact