feat(commits): Add provider-agnostic PR-iteration primitives

[vaind]

Problem

Seer is replacing its PR-iteration force-push with a lease check plus a 3-way content reconcile. Before updating a PR branch it needs to classify how the branch moved relative to the last commit it pushed (identical / ahead / behind / diverged) and append a commit only if the head has not moved underneath it.

Two primitives needed for that are missing or weak here, and without them each consumer has to special-case GitLab:

1. GitLab compare never populates behind_by. map_commit_comparison sets ahead_by = len(commits) and leaves behind_by off entirely, so a consumer can only ever see "ahead" or "identical". A branch reset to an ancestor reads as identical — the most dangerous possible answer for a lease check. GitHub populates both.
2. create_commit has no compare-and-swap contract. Callers who want "append only if the head is still X" have no way to say so, so they force-push instead.

Update: this PR originally carried a third primitive — commit account logins (author_login / committer_login) for bot detection. That change shares no code with the two above and has a very different risk profile, so it has been split out to #127 and reverted here.

Approach

Both additions are additive: new NotRequired keys and defaulted keyword-only params, no signature breaks. Existing tests pass unmodified.

1. GitLab behind_by — internal reverse compare, opt-in via include_behind

compare_commits(..., include_behind=True) issues a second, reversed compare (from=end, to=start). GitLab's compare defaults to merge-base semantics, so the reverse call's commit count is the behind count. behind_by then means exactly what it means on GitHub — a merge-base-relative commit count — and a consumer writes one classification rule for both providers.

Why not the merge_base endpoint. GET /repository/merge_base gives exact ancestry but no counts, so it cannot truthfully populate an int field: it would force either a lying sentinel (behind_by = 1 meaning "some") or a second, differently-shaped field that only exists on GitLab — which puts the provider branch right back into consumer code, the thing this library exists to remove. The reverse compare costs a cheap extra GET and gives the real number.

Why opt-in rather than unconditional. Most compare_commits callers want the diff, not the counts, and doubling every GitLab compare to serve the minority is the wrong default. GitHub accepts the flag and ignores it — it already returns both counts — so the flag reads as "make behind_by trustworthy everywhere". The reverse call is deliberately unpaginated: GitLab's compare endpoint is not paginated and its commits array is always complete, so a single call is the full count (the same basis as ahead_by); this is noted in the docstring.

2. expected_head_sha on create_commit

A lease on the destination, not a parent selector — parent_sha still chooses the parent. It cannot be combined with create_branch (no head to lease) or force (a forced update overwrites the head unconditionally and cannot honor a lease); either combination raises resource_bad_request.

• GitHub — atomic. The lease is enforced twice, and both checks earn their keep. The pre-check runs before any write, so a head that has already moved is rejected before any blob, tree, or commit object is created, and it is the only guard that catches a branch rewound to an ancestor of expected_head_sha — the ref update would accept that as a legitimate fast-forward. The fast-forward-only ref PATCH is then the atomic guard, closing the race the pre-check cannot; its 422 is mapped to the typed error (scoped to the ref update, and only when the caller opted into the lease).
• GitLab — check-then-act, not atomic. There is no server-side CAS anywhere on this path: the commits API takes no expected parent, the branches API has no update endpoint, and GraphQL's commitCreate matches REST. The strongest available implementation is: read the head, write, then verify the created commit's parent_ids. A push landing inside that window still wins, and the error is raised after the commit exists and the branch has already moved. This is documented on the action, on the provider method, and on the exception, and is covered by a test that asserts the POST already happened. Missing parent_ids fails closed.

Because GitHub cannot express a lease-guarded force (no compare-and-swap on the ref PATCH), force=True and expected_head_sha are mutually exclusive rather than a best-effort combination that silently loses a concurrent push — rejected up front on both providers so the contract is uniform.

Typed error: StaleBranchHead / stale_branch_head, a plain SCMCodedError subclass, so it registers itself, round-trips over RPC to the concrete class, and is catchable as except StaleBranchHead:. The existing test_errors.py registry/round-trip tests cover it automatically.

Testing

uv run pytest tests/, uv run ruff check src tests, and uv run mypy src are all green: 864 passed, mypy clean over 17 source files.

New coverage:

• GitLab classification — parametrized over identical / ahead / behind / diverged, asserting the counts and that the two calls swap from/to; plus the default path issuing one call with no behind_by key, and the reverse call staying unpaginated.
• expected_head_sha per provider — happy path; stale head rejected before any write (GitHub asserts the call list is a single GET); GitHub's non-fast-forward 422 mapped to stale_branch_head with the cause preserved, and the same 422 propagating unchanged without the param; GitLab's post-write parent_ids mismatch and unverifiable-parents cases; create_branch and force rejection on both.
• Action forwarding — both new params verified to reach the provider, since nothing else enforces the actions.py wrapper staying in sync.

Per AGENTS.md, both new params were threaded through all six surfaces: actions.py, both providers, BaseTestProvider, both bin/*-client CLIs (usage docstring, argparse, call site), and provider tests.

Fixes CW-1734

🤖 Generated with Claude Code

[linear-code]

CW-1734

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 1c54ece. Configure here.}

[billyvg]

Two blocking findings from a review of this branch, both verified by running the real provider code against the PR head (870 passed / mypy clean / ruff clean locally, so these are semantic, not build, issues). Non-blocking notes were left out deliberately — these two are the ones I think should be resolved before merge.

Overall: the motivation is real, the additive design is right, and the honesty about GitLab's weaker guarantee is unusually good. Both findings below are about a documented guarantee being stronger than the code delivers.

---

🤖 This review was generated by Claude (Claude Code) at the request of @billyvg. Findings were verified by execution against this branch, but please treat the reasoning as a starting point for discussion rather than a verdict.