Catch the staleness the bundle guard could not see (#391)

The Stop-hook guard rebuilt web_ui/dist/app whenever the bundle was older
than web_ui/src. That solves one staleness problem and is silent, by
construction, about a second one.

If the CHECKOUT is behind the branch work lands on, merged code is not in
the working tree at all - so the bundle is perfectly consistent with the
source, the mtime walk finds nothing newer, and the guard correctly says
nothing while the running app is missing features that already shipped. A
canvas went on spawning placeholder nodes on double-click for hours after
the commit removing that gesture had merged, because the checkout sat five
commits behind origin/main and every local file legitimately matched the
bundle built from it.

Two additions:

- The bundle records the commit it was built from
  (dist/app/.built-from-commit) and is rebuilt when HEAD no longer matches
  it. A pull or branch switch that happens to leave mtimes alone is
  invisible to an mtime walk; a recorded HEAD is not.
- When HEAD is behind origin/main the hook says so, naming the branch and
  the commit count, whether or not it also rebuilt. Reported, never
  auto-merged - the working tree belongs to the developer, and a Stop hook
  has no business rewriting it. It reads only already-fetched refs, so it
  never blocks on the network.

Co-authored-by: Claude <noreply@anthropic.com>

Author: dovvnloading

tools/rebuild-spa-if-stale.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# Rebuild the SPA bundle whenever it is older than the source it is built
-# from.
+# Keep web_ui/dist/app honest: rebuild it whenever it no longer reflects the
+# checkout, and say so loudly when the CHECKOUT itself is behind.
 #
 # WHY THIS EXISTS. The app does not run the source tree. Both the desktop
 # shell (graphlink_desktop.py) and the FastAPI backend (backend/app.py,
@@ -12,29 +12,49 @@
 # work looked like it had never landed.
 #
 # dist/ is gitignored, so CI cannot catch this - it is a local-state problem
-# and needs a local guard. This runs from a Stop hook (.claude/settings.json)
-# and rebuilds only when the bundle is actually behind, so a turn that
-# touched no frontend source costs one `find`.
+# and needs a local guard. This runs from a Stop hook (.claude/settings.json).
 #
-# It deliberately does NOT gate on git state. The bundle's job is to reflect
-# the working tree, which is what the developer is looking at.
+# TWO DIFFERENT STALENESS PROBLEMS, and the first version only solved one:
+#
+#   1. The bundle is older than the source it is built from. Caught by the
+#      mtime walk below, and rebuilt.
+#
+#   2. The CHECKOUT is behind the branch the work is landing on. Merged work
+#      is not in this working tree at all, so the bundle can be perfectly
+#      consistent with the source and the running app still misses features
+#      that shipped. The mtime walk is silent here BY CONSTRUCTION - there is
+#      nothing newer to find - which is exactly how a canvas went on spawning
+#      placeholder nodes after the commit removing them had already merged.
+#      Reported below, never auto-merged: the working tree is the developer's,
+#      and this hook has no business rewriting it.
+#
+# It deliberately does NOT gate the rebuild on git state. The bundle's job is
+# to reflect the working tree, which is what the developer is looking at.
 
 set -u
 
 root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 src="$root/web_ui/src"
-stamp="$root/web_ui/dist/app/index.html"
+dist="$root/web_ui/dist/app"
+stamp="$dist/index.html"
+# Records the commit the bundle was built from. A pull or a branch switch
+# that happens to leave mtimes alone is invisible to the walk below; the
+# recorded HEAD is not.
+head_stamp="$dist/.built-from-commit"
 
 # Nothing to do outside a checkout that has the frontend.
 [ -d "$src" ] || exit 0
 
 emit() { printf '{"systemMessage":%s}\n' "$1"; }
 
-# Inputs that change what the bundle contains. index.html lives under
-# src/app/, so it is already covered by the tree walk.
-newest="$(
-  find "$src" -type f -newer "$stamp" -print -quit 2>/dev/null
-)"
+head_sha=""
+if command -v git >/dev/null 2>&1; then
+  head_sha="$(git -C "$root" rev-parse HEAD 2>/dev/null || true)"
+fi
+
+# -- 1. Does the bundle still match the working tree? -----------------------
+
+newest="$(find "$src" -type f -newer "$stamp" -print -quit 2>/dev/null)"
 if [ ! -f "$stamp" ]; then
   newest="(no bundle yet)"
 elif [ -z "$newest" ]; then
@@ -43,11 +63,53 @@ elif [ -z "$newest" ]; then
   done
 fi
 
-[ -n "$newest" ] || exit 0
+# A bundle built from a different commit is stale even when every mtime says
+# otherwise - see problem 2 in this file's own header.
+if [ -z "$newest" ] && [ -n "$head_sha" ]; then
+  built_from="$(cat "$head_stamp" 2>/dev/null || true)"
+  [ "$built_from" = "$head_sha" ] || newest="(built from a different commit)"
+fi
 
-if (cd "$root/web_ui" && npm run build >/tmp/graphlink-spa-build.log 2>&1); then
-  emit '"web_ui/dist/app rebuilt - the desktop app and :8765 now serve the current source."'
-else
-  emit '"web_ui/dist/app is STALE: npm run build failed. See /tmp/graphlink-spa-build.log. The desktop app and :8765 are still serving the previous bundle."'
+rebuilt=""
+if [ -n "$newest" ]; then
+  if (cd "$root/web_ui" && npm run build >/tmp/graphlink-spa-build.log 2>&1); then
+    [ -n "$head_sha" ] && printf '%s' "$head_sha" > "$head_stamp" 2>/dev/null
+    rebuilt="ok"
+  else
+    emit '"web_ui/dist/app is STALE: npm run build failed. See /tmp/graphlink-spa-build.log. The desktop app and :8765 are still serving the previous bundle."'
+    exit 0
+  fi
 fi
+
+# -- 2. Is the checkout itself behind what has already merged? --------------
+#
+# Reported, never acted on. Reads only refs already fetched - no network, so
+# a Stop hook never blocks on one.
+
+behind=""
+if [ -n "$head_sha" ]; then
+  upstream=""
+  for candidate in origin/main origin/master; do
+    if git -C "$root" rev-parse --verify --quiet "$candidate" >/dev/null 2>&1; then
+      upstream="$candidate"
+      break
+    fi
+  done
+  if [ -n "$upstream" ]; then
+    count="$(git -C "$root" rev-list --count "HEAD..$upstream" 2>/dev/null || echo 0)"
+    [ "$count" -gt 0 ] 2>/dev/null && behind="$count"
+  fi
+fi
+
+if [ -n "$behind" ]; then
+  branch="$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '?')"
+  if [ -n "$rebuilt" ]; then
+    emit "\"web_ui/dist/app rebuilt. BUT this checkout ($branch) is $behind commit(s) behind origin/main, so the running app is still missing work that has already merged - the bundle can only ever be as current as the source it is built from. Merge or rebase when your working tree allows it.\""
+  else
+    emit "\"web_ui/dist/app matches this source, but the checkout ($branch) is $behind commit(s) behind origin/main - the running app is missing work that has already merged. Merge or rebase when your working tree allows it.\""
+  fi
+  exit 0
+fi
+
+[ -n "$rebuilt" ] && emit '"web_ui/dist/app rebuilt - the desktop app and :8765 now serve the current source."'
 exit 0