Add checkpoint and rollback functionality

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2026-01-11
+
+### Features
+
+- **Checkpoint and rollback**: Automatically create checkpoints before session execution, enabling rollback to restore files to their pre-execution state
+  - Original file content stored as blob files in `~/.local/share/shannot/sessions/{id}/checkpoint/`
+  - Conflict detection via post-exec hash comparison (bypass with `--force`)
+  - Support for both local and remote (SSH) rollback
+  - Large directory handling with limits (100 files / 50MB) and partial checkpoint warnings
+  - New session status: `rolled_back`
+
+### CLI
+
+- Add `shannot rollback <session_id>` command with `--force` and `--dry-run` options
+- Add `shannot checkpoint list` to list sessions with available checkpoints
+- Add `shannot checkpoint show <session_id>` to display checkpoint details
+
 ## [0.10.3] - 2026-01-07
 
 ### Bug Fixes

README.md

@@ -69,6 +69,11 @@ shannot approve
 - Always-deny destructive patterns (rm -rf /)
 - Everything else requires human review
 
+**Checkpoint and Rollback**
+- Automatic checkpoint before execution
+- Restore files to pre-execution state with `shannot rollback`
+- Conflict detection prevents accidental overwrites
+
 ## Installation
 
 ```bash
@@ -112,6 +117,11 @@ shannot setup mcp install     # Claude Desktop integration
 
 # Status
 shannot status                # Runtime, config, pending sessions
+
+# Rollback
+shannot rollback <session_id> # Restore files to pre-execution state
+shannot checkpoint list       # List sessions with checkpoints
+shannot checkpoint show <id>  # Show checkpoint details
 ```
 
 ## Configuration

docs/reference/cli.md

@@ -96,6 +96,53 @@ shannot setup mcp install                         # Install for Claude Desktop
 shannot setup mcp install --client claude-code    # Install for Claude Code
 ```
 
+### shannot rollback
+
+Rollback session changes to pre-execution state.
+
+```bash
+shannot rollback <session_id>           # Rollback with conflict check
+shannot rollback <session_id> --force   # Skip conflict detection
+shannot rollback <session_id> --dry-run # Preview without making changes
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `session_id` | Session ID to rollback |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--force`, `-f` | Skip conflict detection |
+| `--dry-run`, `-n` | Preview without making changes |
+
+**Exit Codes:**
+
+| Code | Meaning |
+|------|---------|
+| 0 | Rollback successful |
+| 1 | Conflict detected (use --force to override) |
+| 2 | Session not found or no checkpoint |
+
+### shannot checkpoint
+
+Manage session checkpoints.
+
+```bash
+shannot checkpoint list           # List sessions with checkpoints
+shannot checkpoint show <id>      # Show checkpoint details
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List sessions with available checkpoints |
+| `show <session_id>` | Show checkpoint details for a session |
+
 ## See Also
 
 - [Usage Guide](../usage.md) - Comprehensive examples

docs/reference/execution.md

@@ -12,7 +12,9 @@ Shannot v0.4.0+ uses a session-based approval workflow instead of direct executo
 |-------|-------------|
 | Dry-run | Script runs in sandbox, operations captured |
 | Review | User reviews captured operations via TUI |
+| Checkpoint | Original file content saved before changes |
 | Execute | Approved operations run on host system |
+| Rollback | (Optional) Restore files to pre-execution state |
 
 ## Session Workflow
 
@@ -47,9 +49,38 @@ The remote receives the session data and executes in its own PyPy sandbox.
 |--------|---------|
 | `run_session.py` | Session execution orchestration |
 | `session.py` | Session data structures |
+| `checkpoint.py` | Checkpoint and rollback logic |
 | `deploy.py` | Remote deployment |
 | `ssh.py` | Zero-dependency SSH client |
 
+## Checkpoint Creation
+
+Before committing writes, Shannot creates a checkpoint:
+
+1. **Blob storage**: Original file content saved as `{hash[:8]}.blob`
+2. **Metadata**: Path mappings stored in `session.checkpoint`
+3. **Post-exec hashes**: Recorded after writes for conflict detection
+
+Directory structure:
+
+```
+~/.local/share/shannot/sessions/{session_id}/
+  session.json
+  checkpoint/
+    a1b2c3d4.blob
+    e5f6g7h8.blob
+```
+
+## Session Statuses
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Awaiting approval |
+| `approved` | Ready for execution |
+| `executed` | Completed successfully |
+| `rolled_back` | Restored to pre-execution state |
+| `expired` | TTL exceeded |
+
 ## See Also
 
 - [Usage Guide](../usage.md) - Session workflow details

docs/troubleshooting.md

@@ -399,6 +399,74 @@ shannot setup runtime
 shannot status
 ```
 
+## Checkpoint and Rollback Issues
+
+### "Conflict detected" during rollback
+
+**Symptoms:**
+```
+Error: Conflict detected - file was modified since execution
+```
+
+**Cause:** A file was modified after the session was executed, and the current content differs from what Shannot wrote.
+
+**Solutions:**
+
+1. Review the conflict:
+   ```bash
+   shannot checkpoint show SESSION_ID
+   ```
+
+2. Force rollback (overwrites current changes):
+   ```bash
+   shannot rollback SESSION_ID --force
+   ```
+
+3. Manually restore the file from the checkpoint blob
+
+### "Partial checkpoint" warning
+
+**Symptoms:**
+```
+Warning: Partial checkpoint - directory too large to fully checkpoint
+```
+
+**Cause:** Large directories (>100 files or >50MB) cannot be fully checkpointed.
+
+**Impact:** These directories cannot be restored via rollback.
+
+**Solutions:**
+1. Accept the limitation for large directories
+2. Manually backup large directories before execution
+3. Use smaller, more targeted scripts
+
+### "No checkpoint" error
+
+**Symptoms:**
+```
+Error: Session has no checkpoint
+```
+
+**Causes:**
+1. Session was executed before v0.11.0
+2. Checkpoint creation failed
+3. Session was created in dry-run only mode
+
+**Solutions:**
+1. Create a new session and execute it
+2. Check session details:
+   ```bash
+   shannot checkpoint show SESSION_ID
+   ```
+
+### Checkpoint not created
+
+**Symptoms:** Session executed but no checkpoint is available.
+
+**Cause:** The session may have been created before the checkpoint feature was added.
+
+**Solution:** Re-run the script to create a new session with checkpoint support.
+
 ## Getting Help
 
 If you're still stuck:

docs/usage.md

@@ -160,6 +160,47 @@ shannot approve show SESSION_ID    # Review details
 # Then press 'x' in TUI
 ```
 
+### 4. Checkpoint and Rollback
+
+Shannot automatically creates checkpoints before executing approved changes, enabling you to restore files to their pre-execution state.
+
+#### How Checkpoints Work
+
+1. Before execution, original file content is saved to blob files
+2. After execution, file hashes are recorded for conflict detection
+3. Use `shannot rollback` to restore files if needed
+
+#### Rollback Command
+
+```bash
+# Rollback a session (with conflict detection)
+shannot rollback abc123
+
+# Force rollback (skip conflict check)
+shannot rollback abc123 --force
+
+# Preview what would be restored
+shannot rollback abc123 --dry-run
+```
+
+**Conflict Detection:** If a file was modified after session execution, rollback will fail unless `--force` is used.
+
+#### Managing Checkpoints
+
+```bash
+# List all sessions with checkpoints
+shannot checkpoint list
+
+# Show checkpoint details for a session
+shannot checkpoint show abc123
+```
+
+#### Limitations
+
+- Large directory deletions (>100 files or >50MB) create partial checkpoints
+- Partial checkpoints cannot be fully restored
+- Checkpoints are tied to session lifecycle
+
 ## Approval Profiles
 
 Profiles control which commands execute automatically vs. require approval.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shannot"
-version = "0.10.3"
+version = "0.11.0"
 description = "Sandboxed system administration for LLM agents"
 readme = "README.md"
 license = {text = "Apache-2.0"}