ai-agents push-lock.instructions.md

One Push Lock Path

Scoped to the trees that carry push recipes rather than **. The always-on .md ceiling in scripts/validation/instruction_budget.py had 998 bytes of headroom when this rule was written and a universal copy failed it at 102.7 percent, which blocks every contributor's push. Nothing is lost by the narrower scope: the binding half is scripts/validation/check_push_lock_paths.py, which pre_pr.py runs on every push whatever rules the harness loaded.

flock excludes only processes that open the same path. Two agents pushing the same branch under two different lock names run concurrently while both believe they are serialized, which is the lost ref update the lock exists to prevent.

Three schemes were live at once on 2026-08-02 (issue #4366). A ps census taken while roughly 20 push processes were running found 5 processes on the per-branch scheme, 11 on a hashed four-slot scheme, and 2 on a $HOME variant. Two of the three provided no exclusion against the other two.

The rule is one path, written the same way everywhere:

BR=$(git branch --show-current)
SLUG=$(printf '%s' "$BR" | tr '/' '-')
mkdir -p "$HOME/src/scratch/locks"
flock "$HOME/src/scratch/locks/push-lock-$SLUG.lock" git push origin "$BR"

MUST

1. Use $HOME/src/scratch/locks/push-lock-<slug>.lock and nothing else. Not /tmp, not a hashed slot, not a literal home directory, not a per-worktree filename. A recipe that names any other path is a fourth scheme, and a fourth scheme is only discoverable by ps.
2. Key the lock on the branch, with / replaced by -. A branch named fix/foo writes a lock path with a / in the filename otherwise, which the shell reads as a directory. Two distinct branches must never share a lock: git takes its own lock per ref, so unrelated branches serializing behind a 10 to 16 minute pre-push hook is pure waste. The hashed four-slot scheme collided two different branches about 25 percent of the time.
3. Create the directory in the same command. flock fails when the parent directory is missing, and a failed flock in a detached push is silent.
4. Keep the lock out of /tmp. /tmp was wiped mid-session on 2026-08-02. A wipe while a push holds the lock leaves the holder's descriptor on a deleted inode while the next push creates a new inode at the same path, so the two stop excluding each other. That is a split lock under one filename, which no amount of name agreement fixes.