Skip to content

Prevent concurrent checkpoint write conflicts with compare-and-swap #196

@jcleira

Description

@jcleira

Summary

When multiple AI agent sessions are active in the same repository and commit simultaneously, their post-commit hooks race to write checkpoints to the same partio/checkpoints/v1 ref. The current implementation has no atomicity guarantee — a classic lost-update race condition where one session's checkpoint silently overwrites another's.

What to implement

Use git update-ref's compare-and-swap mode to detect when the ref has changed between read and write:

  1. Capture the current ref value before building the new commit
  2. Pass the expected old ref value to git update-ref (third positional arg)
  3. On conflict, re-read the current tree and rebuild the commit on top of the new parent
  4. Retry up to 3 times before logging a warning (don't fail the git operation)

Context

  • internal/checkpoint/write.goStore.Write() with the non-atomic read-modify-write sequence
  • internal/checkpoint/store.go — helper methods for git plumbing operations

Why

Users running multiple agent sessions in parallel (e.g., in different worktrees or terminal tabs) can silently lose checkpoint data. The lost checkpoint is never recoverable.

Inspired by: entireio/cli changelog 0.5.4 — "Multi parallel sessions causing conflicts on same shadow branch"

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions