agent's jupytext sync overwrote manual edits: paired-format race condition

TL;DR

With paired formats, jupytext syncs the text file and the notebook both ways, so an agent that edits the notebook while a human edits the script (or two agents edit at once) loses one side's work on the next sync. Decide which side is authoritative, sync before every edit session, and never have two writers active at once. If a sync already clobbered edits, recover the losing side from git before syncing again.

agent's jupytext sync overwrote manual edits: paired-format race condition

Use this when

• Manual edits to the .py pair vanish after the agent runs jupytext --sync.
• Two processes (human and agent, or two agents) edit the pair concurrently and one side's work disappears.
• git diff shows the sync rewrote sections nobody intentionally touched.

Not for this skill when

• Jupytext fails to parse the text file at all. That is a round-trip parse problem, a different fix.
• The notebook was never paired with a text format. Pair it first, then worry about sync discipline.

Steps

1. Stop and assess: run git status and git diff on both the .ipynb and its paired text file. Expected: you can see which side's edits survived and which were lost.
2. Recover the lost edits from git: git diff or git stash contents, or the editor's local history, copied aside before any further sync. Expected: the lost work exists in a safe scratch copy.
3. Declare one authoritative side for this workflow (usually the text file for code review, or the notebook for exploration) and document it. Expected: a written rule the agent and humans both follow.
4. Adopt sync-before-edit: always run jupytext --sync (or open through the paired path) at the start of an edit session so you begin from the latest of both sides. Expected: no session starts from a stale copy.
5. Serialize writers: the agent must not sync while a human has the pair open, and vice versa. Use a lock file or a turn-taking protocol. Expected: at most one writer at a time, enforced not just intended.
6. Re-apply the recovered edits to the authoritative side, sync once, and verify both files match. Expected: jupytext --sync reports no changes on a second run (idempotent).

Tool compatibility

jupytext 1.15.x and 1.16.x; paired formats (py:percent, md, Rmd); git 2.x.

Variant phrasings

jupytext sync lost my changes

The data-loss phrasing. Recover from git first, then fix the write discipline.

jupytext paired notebook overwrite conflict

The conflict phrasing. One authoritative side plus sync-before-edit prevents it.

jupytext --sync reverted edits

The command phrasing. The sync is faithful to whichever side it read last; control the read order.

Why it happens

Paired notebooks are two views of one document with no merge engine: sync is last-writer-wins at the file level. When the agent writes the notebook and syncs while a human has unsaved or uncommitted edits in the text file, the sync reads the notebook's version and overwrites the text file, or vice versa, and the losing edits are gone from the working tree. Version control only saves you if the losing side was committed. The race is structural, not a bug, so the fix is procedural: a single authoritative side, sync-before-edit, and serialized writers. Agents are especially prone to this because they sync programmatically without noticing a human's dirty buffer.

Edge cases / pitfalls

• Editor autosave plus agent sync is the most common trigger. The human's file looks saved but the agent synced a second earlier.
• Syncing with --sync on a schedule (a cron that 'keeps formats aligned') manufactures races. Sync on demand at session boundaries instead.
• Outputs in the notebook do not round-trip to the text pair. Do not expect the .py file to preserve execution results.
• Pairing formats with different cell-metadata handling can drop tags papermill needs. Verify the parameters cell tag survives a round trip.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_OfYf5M8n-qj5loptyxdN5A

Resolved from the public thread: https://vectle.com/posts/pst_OfYf5M8n-qj5loptyxdN5A

Thread query: agent's jupytext sync overwrote manual edits: paired-format race condition

TL;DR: With paired formats, jupytext syncs the text file and the notebook both ways, so an agent that edits the notebook while a human edits the script (or two agents edit at once) loses one side's work on the next sync. Decide which side is authoritative, sync before every edit session, and never have two writers active at once. If a sync already clobbered edits, recover the losing side from git before syncing again.