How Checkpoints and Rewind Features Enable Undoing Long Autonomous Runs in Reasonix

Reasonix uses snapshot-based checkpoints written after every visible user turn, combined with an atomic rewind subsystem, to let users safely undo any portion of long autonomous agent runs without touching Git history.

The DeepSeek-Reasonix autonomous coding agent can execute hundreds of turns—each potentially editing files, running shell commands, or sending messages. To keep these extended sessions reversible, the engine implements a durable checkpointing system paired with transactional rewind operations. This article examines how these features work together, drawing directly from the Reasonix source code.

---

Checkpoint Creation: Capturing Session State After Every Turn

After each visible user turn, Reasonix writes a complete session snapshot to a checkpoint directory named <session-id>.ckpt. This checkpoint captures three critical components:

• The event log (stored as .jsonl)
• The current turn counter
• A snapshot of the file system relevant to that session

The checkpoint data structure is defined in internal/checkpoint/checkpoint.go. The controller records each checkpoint's location in SessionCheckpointDir, as implemented in internal/store/session.go at line 153.

// Checkpoint creation after a user turn (internal/control/turn_orchestrator.go)
func (o *Orchestrator) finalizeTurn(turn *Turn) error {
    // ...execute tools, update files...
    // Write a checkpoint for the visible user turn
    if err := c.session.Checkpoint(turn.ID); err != nil {
        return err
    }
    return nil
}

Checkpoints are written to disk outside of Git history, ensuring persistence even if the repository state changes dramatically during autonomous execution.

---

Checkpoint Indexing: Mapping Turns to Recoverable States

The Controller maintains a monotonic turn counter and an in-memory map from turn numbers to checkpoint IDs. This indexing enables the rewinding UI to present a chronological picker where each checkpoint is labeled with its original user prompt.

This mapping logic appears in internal/control/turn_orchestrator.go at lines 138-139. The structure allows O(1) lookup of any historical state, essential when sessions grow to hundreds of turns.

Users interact with this index through:

• The /checkpoints HTTP endpoint (served from internal/serve/serve.go, lines 1234-1235)
• A web UI picker showing timestamps and change summaries
• CLI commands for headless operation

---

Rewind Operations: Atomic Restoration of Code and Conversation

When a user triggers /rewind (or the double-Esc shortcut), the server invokes Controller.rewind from internal/control/rewind.go. This function performs transactional restoration: it validates no turn is currently executing, loads the target checkpoint, and restores both the conversation transcript and file system state atomically.

// Rewind to a specific checkpoint (internal/control/rewind.go)
func (c *Controller) Rewind(turn int, mode RewindMode) error {
    plan, err := c.prepareRewind(turn, mode)
    if err != nil { return err }
    // Apply the snapshot stored in the checkpoint
    if err := c.session.RestoreFromCheckpoint(plan.CheckpointID); err != nil {
        return c.rewindFail(err)
    }
    c.notice("rewound to turn %d", turn)
    return nil
}

Error handling is centralized in rewindFail (internal/control/controller.go, lines 3263-3268). If any restoration step fails, the operation aborts and the session remains in its pre-rewind state—no partial corruption occurs.

Rewind Modes

The RewindMode parameter supports three restoration scopes:

• Conversation only: Revert the message history while preserving file changes
• Code only: Roll back files to the checkpoint state while keeping the conversation
• Both: Full restoration of session state (default for most undo scenarios)

---

Undoing a Rewind: The Rewind Transaction Log

Reasonix treates rewinds themselves as reversible operations. After a successful rewind, the engine records a rewind transaction that can be undone via the /undo-rewind command.

The UndoRewind function (lines 179-188 in internal/control/rewind.go) re-applies the previous checkpoint, effectively moving the session forward again to its pre-rewind state. This creates a safety net: users can explore alternate timelines by rewinding, then return to their original position without losing work.

---

Persistence Across Restarts

Because checkpoints are stored on disk in dedicated directories rather than in memory or Git objects, they survive:

• Application restarts
• System crashes
• Repository rebases or branch switches

When Reasonix restarts, the UI fetches the complete checkpoint list from /checkpoints and reconstructs the turn-to-checkpoint mapping. Users can rewind to any historical turn from previous sessions, making long-running autonomous workflows genuinely recoverable.

---

CLI and UI Usage

# Rewind to turn 14, restoring both code and conversation

$ reasonix /rewind 14 both

# Undo the last rewind operation

$ reasonix /undo-rewind

# List available checkpoints

$ reasonix /checkpoints

The web UI (documented in docs/CHECKPOINTS.md) provides a visual timeline with:

• Per-turn timestamps
• Prompt summaries
• Change impact indicators
• Mode selection controls

---

Summary

• Checkpoints capture complete session snapshots after every visible user turn, stored in <session-id>.ckpt directories outside Git history.
• Indexing via monotonic turn counters and ID maps enables efficient lookup and UI presentation of historical states.
• Rewind operations execute atomically, with centralized error handling that prevents partial restoration failures.
• Rewind transactions are themselves reversible, allowing users to explore alternate paths and return safely.
• Disk persistence ensures checkpoints survive crashes and restarts, making long autonomous runs genuinely recoverable.

---

Frequently Asked Questions

How often does Reasonix create checkpoints?

Reasonix creates checkpoints after every visible user turn—not during internal agent loops. This balances granularity against performance, ensuring each user-facing interaction is recoverable without checkpointing every sub-action.

What happens if a rewind operation fails partway through?

The restoration is transactional. The rewindFail handler in internal/control/controller.go aborts the operation and leaves the session unchanged if any step fails—file system changes, conversation restoration, or metadata updates must all succeed or all roll back.

Can I rewind to a checkpoint from a previous Reasonix session?

Yes. Checkpoints persist to disk in SessionCheckpointDir and are available across restarts. The /checkpoints endpoint serves the complete history regardless of when Reasonix was last running.

Does rewinding affect Git history?

No. Checkpoints operate outside Git, storing snapshots in dedicated .ckpt directories. Rewinding modifies your working files and conversation state without creating commits, reverting commits, or changing branch history.

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