Module auto_push_single_flight 

Single-flight push coordination per branch: owner lock, record joins and the push itself. What: Single-flight auto-push per branch: one owner lock serializes the pushes of a branch, and the last-pushed record names the most recent attempt. Why: A commit that a recorded successful push already covers finishes without pushing, and a commit that waits behind a live pusher joins the push it waited for, so concurrent landings on one branch cost fewer pushes than commits. The incumbent’s src/auto-push-single-flight.ts decides these joins, and the lock and record paths must match its paths byte for byte.

In TS you’d write (pseudocode):

await runSingleFlightPush({ gitPath, cwd, branchRef, landedOid, push, onWait });

Structs

PushAttempt

What: One push this invocation ran itself. Why: output is Git’s interleaved output with one trailing line break removed, as the incumbent’s nano-spawn output is; a successful push’s output is never recorded.

PushCoordinationPaths

What: Paths of one branch’s coordination files. Why: The lock and the record live beside each other under the common Git directory.

PushGit

What: The real Git a coordinator runs, where, and with which environment. Why: The incumbent’s coordination inherits the wrapper’s whole environment plus the child-environment overlay, so the caller passes that complete environment in (environment_with_overlay) and nothing is read from the process environment here.

SingleFlightOutcome

What: How a landed commit’s auto-push finished, with the deciding push’s facts. Why: The caller prints the output and the uncovered note from these fields alone.

Enums

SingleFlightError

What: Why a single-flight push could not finish. Why: Every variant is a coordination failure, which the caller reports and keeps the commit for.

SingleFlightKind

What: How a landed commit’s auto-push finished. Why: The four kinds keep “this invocation pushed” apart from “another invocation’s push decided”, because only the owner of a failed push prints its full output.

Functions

git_command

What: Build a real Git command with the given arguments, directory and environment. Why: Every coordination query and push starts Git this way, so none re-enters the wrapper.

git_output

What: Run a read-only Git query and return its trimmed standard output. Result<A, B> is either the output or a failure. Why: Any failed query is a coordination failure; it is never read as an answer.

resolve_push_coordination_paths

What: Resolve one branch’s coordination file paths under the common Git directory and create that directory. Why: Linked worktrees share one common directory, so every worktree of a repository coordinates on one lock.

run_query

What: Run a read-only Git query with its own deadline and capture its streams separately. Why: A query that never returns would hold the caller, and the push lock behind it, for good.

run_single_flight_push

What: Finish auto-push of one landed commit: join a push that covers it, or push the branch tip itself. Why: Three joins are possible, and each keeps the commit from pushing twice: an early join on a recorded covering success, a join after waiting for the lock, and the rule that a failed record joins only when a push finished after the first read. The record is written before the lock is released, so the next waiter reads this attempt.

tip_contains

What: Whether a commit is the given tip or one of its ancestors. Result<A, B> is “answer or failure”. Why: Only Git’s “not an ancestor” status answers no; every other failure stops the caller.