/rewind — Session Checkpoint Recovery

You help the user recover to a previous checkpoint in the current session.

Checkpoints are created automatically by hooks/checkpoint.sh during implementer sessions:

• Every 5 file writes (threshold-based)
• On the first modification of any new file in the session

Each checkpoint is a git ref at refs/checkpoints/<branch>/<N> pointing to a commit object that snapshots the working directory state at that moment, without affecting HEAD or the branch pointer.

Protocol

Step 1 — List checkpoints for the current branch

BRANCH=$(git branch --show-current)
git for-each-ref "refs/checkpoints/${BRANCH}/" \
  --format='%(refname:short) %(subject)' \
  --sort=version:refname

Step 2 — Present checkpoints to the user

Format each checkpoint as:

[N] <timestamp> — before modifying <filename>
    ref: checkpoints/<branch>/<N>
    SHA: <sha>

Extract from the subject line checkpoint:EPOCH:before:FILENAME:

• EPOCH → convert to human-readable time (date -r EPOCH or date -d @EPOCH)
• FILENAME → the file that was about to be modified

If no checkpoints exist, inform the user:

No checkpoints found for branch <branch>. Checkpoints are created automatically during implementer sessions — every 5 writes or on the first modification of a new file.

Step 3 — On user selection, restore the checkpoint

# Get the checkpoint SHA
SHA=$(git rev-parse "refs/checkpoints/${BRANCH}/<N>")

# Show what will change before restoring
git diff HEAD "$SHA" --stat

# Show untracked files that will be REMOVED by the restore
echo ""
echo "--- Untracked files that will be removed ---"
git clean -fdn

Warning: Rewind removes untracked files that did not exist at the checkpoint. Show both the diff stat and the untracked file list to the user, then ask for confirmation:

This will restore N files to checkpoint state and remove M untracked files. HEAD stays at its current commit. Proceed?

After user confirmation, restore with both git checkout (tracked files) and git clean (untracked files):

# Restore tracked files to checkpoint state (does NOT move HEAD)
git checkout "$SHA" -- .

# Remove untracked files created after the checkpoint,
# but preserve .claude/ session state files
git clean -fd -e .claude/

Step 4 — Log the rewind event

source ~/.claude/hooks/context-lib.sh
PROJECT_ROOT=$(detect_project_root)
append_session_event "rewind" \
  "{\"ref\":\"refs/checkpoints/${BRANCH}/<N>\",\"target\":\"${SHA}\"}" \
  "$PROJECT_ROOT"

Step 5 — Report what changed

git diff --stat HEAD

Show the user:

• Which files were restored
• What the diff looks like (git diff HEAD for key files)
• Next steps: "You're now at checkpoint N. The agent's recent changes have been reverted. You can continue from this state."

Important Notes

• Checkpoints are READ-ONLY snapshots. Restoring does NOT change HEAD or the branch pointer. Only working-tree files are affected via git checkout SHA -- .
• Only checkpoints for the CURRENT branch are shown. Refs are scoped to refs/checkpoints/<branch>/.
• Checkpoint refs survive garbage collection because they are named refs (not loose objects).
• After merge, checkpoint refs for the merged branch are cleaned up by Guardian as part of the merge process.
• Counter state: The checkpoint counter is stored in .claude/.checkpoint-counter and is reset when a new implementer session starts.