Verify end-to-end JSONL restore against a real deleted session (Alpha #2)

[djdarcy]

Verify end-to-end JSONL restore against a real deleted session (Alpha #2)

Epic

One of four alpha-release criteria. csb restore <id> was implemented in v0.1.1 but has never been tested end-to-end against a real session deletion. This issue tracks the verification procedure and any fixes discovered along the way.

Why

Backup without proven restore is just "hopeful storage." We need to demonstrate that:

1. A JSONL can be committed to git by csb backup
2. The same JSONL can be deleted from ~/.claude/projects/
3. csb restore <id> recovers it from git history
4. Claude Code sees the restored session and can claude --resume <id> it successfully

Currently we have #1 (verified 1343+ jsonls tracked in git) and the code for #3 exists, but #2, #3 (in practice), and #4 are untested.

Approach

Step 1: Create a throwaway session

Start a new Claude Code session specifically for this test. Send a few messages, get responses, close the session. Note its UUID.

Step 2: Confirm it's in git

csb backup  # commit the new session to git
git -C ~/.claude log --oneline -- "projects/<project>/<uuid>.jsonl"

Step 3: Delete it from disk

# Capture mtime and size before delete, for later comparison
stat ~/.claude/projects/<project>/<uuid>.jsonl
rm ~/.claude/projects/<project>/<uuid>.jsonl

Step 4: Verify csb detects the deletion

csb backup --no-commit  # rescans, should mark the session as deleted_at
csb list --deleted      # should show the deleted session

Step 5: Restore

csb restore <uuid>      # should find the file in git history and write it back
ls -la ~/.claude/projects/<project>/<uuid>.jsonl  # exists again

Step 6: Verify Claude Code can resume

claude --resume <full-uuid>
# Should load the session without errors
# Send a test message to verify the session context is intact

Step 7: Document the procedure

Add a "Recovery" section to README.md with the tested steps. Note any quirks discovered.

Possible issues to fix

Things that might go wrong and need patches:

• Mtime not preserved: When git show writes the file back, mtime is "now" not the original timestamp. Claude Code might not care, but csb's purge countdown will be wrong until next backup cycle.
• Subagent data not restored: The <uuid>/subagents/ and <uuid>/tool-results/ directories alongside the JSONL may also need restoration. Current csb restore only restores the JSONL, not the subdirectory contents.
• Session-states file: The session-state JSON in ~/.claude/session-states/<uuid>.json might need to be restored too for Claude Code to recognize the session.
• Windows line endings: git might change LF to CRLF on Windows checkouts, which could corrupt JSONL parsing.

Acceptance criteria

• Test procedure documented in README.md or docs/RECOVERY.md
• End-to-end test performed at least once, with the result recorded (success or specific failures)
• Integration test in tests/test_restore.py that simulates deletion+restore against mock_claude_dir fixture
• Any fixes discovered during testing are committed with tests
• If subagent/tool-results restoration is needed, it's implemented or scoped to a follow-up issue
• Session-states file restoration is handled (or scoped to follow-up)
• Mtime preservation is either fixed or explicitly documented as a known limitation

Related

• Alpha release criterion Todos / Notes / Quick Ideas / Brainstorming #2 -- blocks v0.3.0-alpha
• csb restore: recover sessions from external backup directories #8 (recover from external backup dirs) -- different restore path but shares validation concerns
• Design note: notes/ideas/2026-04-10__21-58-00__both_initial-release-criteria-and-repokit-common-question.md