chore(gate): queue behind other heavy builds on the host, not race them

.cargo-husky/hooks/pre-push

@@ -32,6 +32,11 @@ if [ "${GATE_SKIP:-0}" = "1" ]; then
     exit 0
 fi
 
+# Queue behind any other heavy build on this machine, in any project, rather than
+# race it for RAM. After the escape hatch, so a deliberate skip never waits.
+# shellcheck source=scripts/lib/host-build-lock.sh
+source "$(git rev-parse --show-toplevel)/scripts/lib/host-build-lock.sh" "pre-push"
+
 cargo fmt --all -- --check
 
 # Crates owning the changed files. Falls back to the whole workspace when the upstream ref is

scripts/gate.sh

@@ -62,6 +62,15 @@ case "${1:-}" in
     *) echo "unknown argument: $1" >&2; exit 2 ;;
 esac
 
+# Queue behind any other heavy build on this machine, in any project, before
+# anything is timed or snapshotted — so time spent waiting is not part of the run,
+# and START_HEAD below is taken after the wait. `--fingerprint` is exempt: it is
+# the seconds-long primitive and builds nothing.
+if [ "$MODE" != "fingerprint" ]; then
+    # shellcheck source=scripts/lib/host-build-lock.sh
+    source "$REPO_ROOT/scripts/lib/host-build-lock.sh" "gate"
+fi
+
 COMMIT=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
 if [ -n "$(git status --porcelain 2>/dev/null)" ]; then DIRTY="dirty"; else DIRTY="clean"; fi
 

scripts/lib/host-build-lock.sh

@@ -0,0 +1,33 @@
+# Take the HOST-WIDE heavy-build lock, held until the calling script exits.
+# Sourced, not executed: `source scripts/lib/host-build-lock.sh "<who>"`.
+#
+# Why host-wide and not per repo. Nothing coordinates two heavy cargo runs on one
+# machine. On 2026-09-25 another project's gate (fnec-rust) was OOM-killed three
+# times while this repo's `cargo test --workspace` ran alongside it, and each kill
+# read as a failure of the code under test — the same misattribution
+# `GATE: INVALID` exists to prevent, arriving by a channel the gate cannot see.
+# The lock file is shared across projects: fnec-rust's `scripts/host-build-lock.sh`
+# takes the SAME path, so the two gates queue instead of racing for RAM.
+#
+# Two rules that keep it from deadlocking:
+#   - a script takes it ONCE, near the top; nothing it calls takes it again
+#     (the pre-push hook does not call gate.sh, so each may take it);
+#   - do not wrap a script that takes it in `flock` yourself — the inner take
+#     would wait forever on the lock the outer one holds.
+#
+# Override the path with HEAVY_BUILD_LOCK (every project must agree on it). If
+# `flock` is not installed, the caller runs unlocked and says so.
+
+_hbl_who="${1:-gate}"
+_hbl_path="${HEAVY_BUILD_LOCK:-${XDG_RUNTIME_DIR:-/tmp}/heavy-build.lock}"
+
+if command -v flock >/dev/null 2>&1; then
+    exec 9>"$_hbl_path"
+    if ! flock -n 9; then
+        echo "$_hbl_who: another heavy build holds $_hbl_path — waiting for it to finish" >&2
+        flock 9
+        echo "$_hbl_who: lock acquired, continuing" >&2
+    fi
+else
+    echo "$_hbl_who: flock not installed — running WITHOUT the host-wide build lock" >&2
+fi