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

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, 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 (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 (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 (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) 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

// 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

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

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: Defines session-sidecar paths, including SessionCheckpointDir for checkpoint storage locations
• internal/checkpoint/checkpoint.go: Core data structures (FileSnap, Checkpoint) and serialization logic for snapshots (lines 33-41 and 65-78)
• internal/checkpoint/store.go: In-memory and on-disk checkpoint store; handles loading, persisting, and transaction management (lines 40-48)
• internal/control/rewind.go: Controller-level API implementing PrepareRewind, CommitRewind, and UndoRewind (lines 31-120)
• 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), 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}