# DeepSeek-Reasonix Checkpoint and Rewind Feature: Complete Guide to Session Recovery

> Master DeepSeek-Reasonix checkpoint and rewind for seamless session recovery. Create turn-level snapshots to revert conversations without Git pollution. Recover any previous state easily.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: deep-dive
- Published: 2026-08-06

---

**The checkpoint and rewind feature in DeepSeek-Reasonix (Reasonix) creates turn-level snapshots of your workspace before any file edits, allowing you to recover to any previous conversation state without polluting your Git history.**

DeepSeek-Reasonix is an autonomous coding agent that requires robust safety mechanisms when executing long-duration tasks. The **checkpoint and rewind** system provides atomic session recovery by snapshotting the workspace before every edit operation, storing these fingerprints alongside the session transcript rather than in Git.

## How Checkpoint and Rewind Works in DeepSeek-Reasonix

### Session Layout and Storage Architecture

Every Reasonix session maintains a transcript file named `<id>.jsonl`. All session metadata—including checkpoints—lives in sidecar directories adjacent to this file. According to the source code in [`internal/store/session.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/store/session.go), the `SessionCheckpointDir` function returns a dedicated `<id>.ckpt` folder where all checkpoint data persists.

This architecture ensures that recovery data remains **isolated from version control**, preventing rewind operations from corrupting your repository's Git history.

### Capturing File Snapshots (FileSnap)

Before any writer tool (such as `edit_file` or `apply_patch`) modifies a file, the engine invokes `checkpoint.CapturePath` to record the file's pre-edit state. As defined in [`internal/checkpoint/checkpoint.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/checkpoint/checkpoint.go) (lines 33-41), this creates a `FileSnap` structure containing the file's fingerprint.

Multiple snapshots taken during the same autonomous turn are gathered into a **Checkpoint** object (lines 65-78) that stores:
- The turn number (`MsgIndex`)
- Timestamp
- Prompt context
- List of associated `FileSnap` objects

### The Checkpoint Store

The `Store` type in [`internal/checkpoint/store.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/checkpoint/store.go) (lines 40-48) manages checkpoint persistence. It maintains an in-memory list (`done []*Checkpoint`) and writes each turn's data as a JSON file to disk when configured. This **git-free** approach makes checkpoints fast to create, query, and delete while remaining independent of the user's repository state.

## The Rewind Workflow

### Preparing a Rewind with PrepareRewind

When a user requests recovery to a specific turn, the controller validates the operation through `PrepareRewind` in [`internal/control/rewind.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/rewind.go) (lines 95-120). This function:
- Verifies the requested checkpoint exists
- Loads its metadata
- Builds a `RewindPlan` describing restorable components (code, conversation, or both)
- Identifies any **coverage gaps** for files that couldn't be captured

If `ErrRewindCoverageConfirmationRequired` is returned, the UI must obtain explicit user confirmation before proceeding.

### Executing Rewinds with CommitRewind

Once confirmed, `CommitRewind` (lines 31-73 in [`internal/control/rewind.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/rewind.go)) executes the restoration plan inside a **mutation barrier** for transactional safety. This operation:
- Restores files from the checkpoint's `FileSnap` collection
- Deletes files that didn't exist at the checkpoint time
- Optionally truncates the conversation to the saved `MsgIndex`
- Bumps the session's revision counter upon success

### Undo Support with UndoRewind

Reasonix implements "undo for undo" semantics through `UndoRewind` (lines 76-100). The most recent rewind transaction is retained as a **transaction manifest**, allowing `Controller.UndoRewind` to roll the session back to its pre-rewind state if the user changes their mind.

## Why Session Recovery Matters

The checkpoint system provides three critical safety guarantees for autonomous agent workflows:

- **Turn-level granularity**: Each checkpoint is tied to a specific conversation turn, enabling precise recovery to exact moments before problematic edits
- **Coverage gap handling**: When files cannot be captured (hard-links, oversized files, or paths outside the workspace), the system records a `CoverageGap` and requires explicit confirmation, preventing accidental data loss
- **Transactional safety**: The `MutationBarrier` and `TransactionManifest` ensure that rewinds either fully succeed or leave the workspace completely unchanged

## Implementation Code Examples

### Preparing a Rewind Request

```go
// Assume `c` is a *control.Controller already set up for a session.
plan, err := c.PrepareRewind(turnNumber, control.RewindBoth)
if err != nil {
    // handle missing checkpoint, partial coverage, etc.
    log.Fatal(err)
}
if control.RewindPlanRequiresConfirmation(plan) {
    // UI must ask the user to confirm before proceeding.
}

```

*`PrepareRewind` pulls the checkpoint for `turnNumber`, validates coverage gaps, and returns a `checkpoint.RewindPlan` that describes what can be restored.*

### Committing the Restoration

```go
result, err := c.CommitRewind(plan.ID)
if err != nil {
    log.Fatalf("rewind failed: %v", err)
}
if result.OK {
    fmt.Printf("Rewind succeeded: %d files restored, %d deleted\n",
        len(result.Written), len(result.Deleted))
}

```

*`CommitRewind` performs the actual file restoration and conversation truncation inside the mutation barrier.*

### Undoing the Last Rewind

```go
undoResult, err := c.UndoRewind(lastTransactionID)
if err != nil {
    log.Fatalf("undo failed: %v", err)
}
if undoResult.OK {
    fmt.Println("Undo successful – session restored to pre‑rewind state")
}

```

*The undo step reads the previously saved transaction manifest and restores the workspace back to its state before the last rewind.*

## Key Source Files

The checkpoint and rewind feature spans these critical files in the `esengine/DeepSeek-Reasonix` repository:

- **[`internal/store/session.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/store/session.go)**: Defines session-sidecar paths, including `SessionCheckpointDir` for checkpoint storage locations
- **[`internal/checkpoint/checkpoint.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/checkpoint/checkpoint.go)**: Core data structures (`FileSnap`, `Checkpoint`) and serialization logic for snapshots (lines 33-41 and 65-78)
- **[`internal/checkpoint/store.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/checkpoint/store.go)**: In-memory and on-disk checkpoint store; handles loading, persisting, and transaction management (lines 40-48)
- **[`internal/control/rewind.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/rewind.go)**: Controller-level API implementing `PrepareRewind`, `CommitRewind`, and `UndoRewind` (lines 31-120)
- **[`internal/checkpoint/capture.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/checkpoint/capture.go)**: File fingerprinting logic that creates `FileSnap` objects and identifies coverage gaps

## Summary

- **DeepSeek-Reasonix** implements session recovery through git-independent checkpointing stored in `<id>.ckpt` directories beside session transcripts
- **FileSnap** objects capture pre-edit fingerprints via `checkpoint.CapturePath` before any writer tool executes
- **PrepareRewind** validates recovery plans and identifies coverage gaps that require user confirmation
- **CommitRewind** executes atomic restoration of files and conversation state inside a mutation barrier
- **UndoRewind** provides transaction-level rollback capabilities using stored manifests

## Frequently Asked Questions

### How does DeepSeek-Reasonix handle files that cannot be checkpointed?

When `CapturePath` encounters unsupported paths (hard-links, oversized files, or external directories), it records a `CoverageGap` in the checkpoint metadata. The `PrepareRewind` function returns `ErrRewindCoverageConfirmationRequired`, forcing the UI to display a warning and obtain explicit user confirmation before proceeding with the rewind.

### Can I recover my code without losing the conversation history?

Yes. The `RewindPlan` created by `PrepareRewind` supports selective restoration modes. You can specify `RewindCodeOnly` to restore files while preserving subsequent conversation turns, or `RewindBoth` to truncate the conversation to the checkpoint's `MsgIndex`. The plan explicitly describes what will be affected before you commit.

### Where are checkpoint files stored relative to my Git repository?

Checkpoints are stored in the session's checkpoint directory (returned by `SessionCheckpointDir` in [`internal/store/session.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/store/session.go)), located at `<session-id>.ckpt` beside the transcript file. This design keeps recovery data completely outside your working tree, ensuring that rewinds never modify, delete, or interfere with Git-tracked files or history.

### What happens if a rewind operation fails halfway through?

The rewind mechanism uses a `MutationBarrier` and transactional manifests to guarantee atomicity. As implemented in [`internal/control/rewind.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/rewind.go), `CommitRewind` either fully restores all files and updates the conversation state, or leaves the workspace completely unchanged. If an error occurs during restoration, the transaction rolls back without partial file modifications.