launcher/scripts/flare-upstream-watch.sh

#!/usr/bin/env bash
# Watch NVIDIA/spark-local-inference upstream (renamed from
# `flare-local-inference` on 2026-11-03; the old name redirects, so an older
# clone keeps working).
#
# OUR RUNTIME PIN is not just the upstream HEAD: the prod lanes build
# `main` + PR #184 ("Run parallel Engram disk workers on Linux with io_uring
# lanes") — branch `pr184-on-main`, which is what the agent binary on the
# nodes runs. When bumping the pin, rebase that branch onto the new HEAD,
# rebuild, and reinstall on EVERY rank node (a mixed set fails at rendezvous
# with "incompatible protocol"). Why that patch exists:
# specs/tech-architecture/flare-roce-poison.md.
#
# FLARE moves several times a day (12+ commits in one night), and our clones,
# the per-host agent binaries and the prepared packages all have to agree with
# it: the RoCE proxy ABI is pinned in the repo, the model recipes change, and a
# package prepared with one revision can be refused by another.
#
#   scripts/flare-upstream-watch.sh           # what changed since the pin
#   scripts/flare-upstream-watch.sh --bump    # move the pin to current HEAD
#
# The pin lives next to this file's spec (specs/tech-architecture/
# flare-upstream.pin) as a single line: <sha> <committer-date>.
set -euo pipefail

REPO="NVIDIA/spark-local-inference"
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PIN_FILE="$ROOT/specs/tech-architecture/flare-upstream.pin"
API="https://api.github.com/repos/$REPO"

pin_sha=""
pin_date=""
if [[ -f "$PIN_FILE" ]]; then
  read -r pin_sha pin_date <"$PIN_FILE" || true
fi

json="$(curl -fsSL -m25 "$API/commits?per_page=100")"
head_sha="$(printf '%s' "$json" | python3 -c 'import json,sys; print(json.load(sys.stdin)[0]["sha"])')"
head_date="$(printf '%s' "$json" | python3 -c 'import json,sys; d=json.load(sys.stdin)[0]["commit"]["committer"]; print(d["date"][:16])')"

echo "upstream: $REPO"
echo "  HEAD   ${head_sha:0:10}  $head_date"
echo "  pinned ${pin_sha:0:10}  ${pin_date:-never}"

if [[ "${1:-}" == "--bump" ]]; then
  printf '%s %s\n' "$head_sha" "$head_date" >"$PIN_FILE"
  echo "  pin moved to ${head_sha:0:10}"
  exit 0
fi

if [[ -z "$pin_sha" ]]; then
  echo "  no pin recorded — run with --bump after reviewing"
  exit 0
fi

if [[ "$pin_sha" == "$head_sha" ]]; then
  echo "  up to date"
  exit 0
fi

echo
echo "new commits since the pin:"
TMP_JSON="$(mktemp)"
trap 'rm -f "$TMP_JSON"' EXIT
printf '%s' "$json" >"$TMP_JSON"
python3 - "$pin_sha" "$TMP_JSON" <<'PY'
import json, re, sys

pin = sys.argv[1]
commits = json.load(open(sys.argv[2]))
SIGNIFICANT = re.compile(
    r"roce|abi|flashinfer pin|speculat|dspark|dflash|mtp|recipe|deepseek|glm"
    r"|mimo|qwen|kimi|package|prepare|export|agent|orbit",
    re.I,
)

stopped = False
for c in commits:
    sha = c["sha"]
    if sha == pin:
        stopped = True
        break
    msg = c["commit"]["message"].splitlines()[0]
    date = c["commit"]["committer"]["date"][:16]
    flag = "  ⚠" if SIGNIFICANT.search(msg) else "   "
    print(f"{flag} {sha[:10]} {date} {msg[:110]}")
if not stopped:
    print("(pin is older than the 40 commits listed — fetch more)")
PY

cat <<'EOF'

Before re-running a FLARE experiment, pull and rebuild BOTH sides — the
per-host `flare` agent binaries and the prepared packages must come from the
same revision, or the runtime refuses (see the "proxy ABI" row in
specs/tech-architecture/flare-bringup.md).
EOF