[DOCS] State Desynchronization Warning for File Checkpointing Workflow

Documentation Type

Other

Documentation Location

URL: https://platform.claude.com/docs/en/agent-sdk/file-checkpointing

Section/Topic

Section: "How checkpointing works" and "Implement checkpointing"

Current Documentation

"File rewinding restores files on disk to a previous state. It does not rewind the conversation itself. The conversation history and context remain intact after calling rewindFiles() (TypeScript) or rewind_files() (Python)."

What's Wrong or Missing?

The documentation explicitly states that the conversation history remains intact while the filesystem changes. This creates a high-severity "Split-Brain" state desynchronization scenario that is not addressed:

1. Context Contradiction: If Claude successfully edits a file (e.g., adding a new function calculate_tax()), that action is recorded in the conversation history.
2. Physical Reversal: If the user then invokes rewind_files(), the filesystem is reverted and calculate_tax() no longer exists on disk.
3. Agent Failure Loop: Claude still believes the function exists because the conversation history wasn't rewound. If Claude is then asked to "Update the logic in the tax function," it will attempt a str_replace or view on code that is physically missing. This will result in a string_not_found or file_not_found error from the text_editor tool, causing model confusion and potential infinite retry loops.

The documentation currently presents the persistent conversation history as a neutral fact, rather than a significant technical hurdle for agent reliability.

Suggested Improvement

Add a prominent Warning or Best Practices block to the "How checkpointing works" section:

---
⚠️ Warning: Context Desynchronization

Rewinding files does not remove messages from Claude's conversation history. This creates a state where Claude's internal mental model of the codebase differs from the actual files on disk.

If your workflow requires Claude to continue working on the same files after a rewind, you should:

1. Clear the session: Use a /clear command or start a new session ID to reset Claude's context.
2. Re-verify State: Instruct Claude to run a Glob or Read tool immediately after a rewind to "refresh" its understanding of the current file states.
3. Handle Tool Failures: Be prepared for Claude to attempt edits on code it thinks exists but was actually removed by the rewind, leading to string_not_found errors.

---

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: This directly impacts the [Text Editor Tool](/docs/en/agents-and-tools/tool-use/text-editor-tool#handle-errors) which relies on old_str matching exactly. If the old_str was added in a turn that was physically rewound, the tool becomes unusable for those specific lines.
• Examples from other projects: Version control systems (like Git) generally treat the "HEAD" and the "Working Directory" as linked. When an LLM acts as the operator, separating its "Memory of the HEAD" from the "Reality of the Directory" without a synchronization step is a recipe for agentic failure.