docs(todo): close live-update guard, file the live firing test

1 files changed, 30 insertions, 2 deletions

diff --git a/todo.org b/todo.org
index 1870f08..8b4cef9 100644
--- a/todo.org
+++ b/todo.org
@@ -89,13 +89,14 @@ From the roam inbox: Zoom opens at a tiny size. Needs diagnosis (HiDPI scaling v
 :END:
 From the roam inbox: hiding a window (e.g. the org-capture popup) then unhiding it should leave the unhidden window focused, but another window typically takes focus. Also =ctrl+j/k= (layout-navigate) can't reach the unhidden window afterward — it should always reach any visible window except the waybar. Involves stash-restore + layout-navigate; needs interactive reproduction with Craig.
 
-** TODO [#B] Guard against live mesa/hyprland/wayland-runtime updates :hyprland:
+** DONE [#B] Guard against live mesa/hyprland/wayland-runtime updates :hyprland:
+CLOSED: [2026-06-28 Sun]
 :PROPERTIES:
 :LAST_REVIEWED: 2026-06-09
 :END:
 A live =pacman -Syu= that swaps mesa/hyprland/wayland runtime libs out from under a running Hyprland session can crash the compositor: the next GPU-lib call hits a now-"(deleted)" library and SIGABRTs, taking the Wayland clients down with it. Hit ratio 2026-06-07 (mesa 26.0.6 -> 26.1.2 + hyprland upgraded live; Hyprland SIGABRT took down awww/insync/emacs). Likely the driver behind ratio's high lifetime unsafe-shutdown ratio — a crashed compositor forces a hard reset.
 
-Ship a guard: an update wrapper, or a documented practice, that when a pending =-Syu= set includes mesa/hyprland/wayland runtime libs advises running it from a TTY (or after logging out of Hyprland) rather than live. Returned to archsetup from archangel 2026-06-09 — hyprland/mesa are installed and managed by archsetup, not the ISO installer.
+Shipped as a pacman PreTransaction hook rather than a wrapper, so it fires no matter how the upgrade is launched (pacman, yay, topgrade). =scripts/hypr-live-update-guard= aborts the transaction before any package is swapped when the GPU/compositor runtime set is being upgraded AND Hyprland is running, pointing the user to re-run from a TTY with the session stopped; it stays quiet when Hyprland isn't running (the safe from-a-TTY path). Override via =HYPR_ALLOW_LIVE_UPDATE=1= or by touching the sentinel file named in the abort message. archsetup installs the script to =/usr/local/bin= and the hook to =/etc/pacman.d/hooks/= in the hyprland path. Decision logic unit-tested (=tests/hypr-live-update-guard=, 9 cases). Live firing test filed under Manual testing and validation. Commits: archsetup (this session).
 
 ** TODO [#C] Pocketbook development backlog :pocketbook:
 :PROPERTIES:
@@ -757,6 +758,33 @@ Parse yay errors and provide specific, actionable fixes instead of generic error
 Enhance existing indicators to show what's happening in real-time
 
 ** TODO Manual testing and validation
+*** Live-update guard aborts a GPU/compositor upgrade while Hyprland runs
+What we're verifying: the pacman PreTransaction hook =hypr-live-update-guard= aborts a =-Syu= that swaps GPU/compositor libs while Hyprland is live, and stays quiet once the session is stopped. Unit tests cover the script's decision logic; this confirms pacman parses the hook, feeds the matched targets on stdin (=NeedsTargets=), and =AbortOnFail= actually stops the transaction. Run on a Hyprland box (ratio/velox).
+- Prereq on machines installed before this shipped: place the guard if missing (a fresh archsetup install does this in the hyprland step).
+#+begin_src sh :results output
+if [ ! -e /usr/local/bin/hypr-live-update-guard ]; then
+  sudo cp ~/code/archsetup/scripts/hypr-live-update-guard /usr/local/bin/ && sudo chmod 755 /usr/local/bin/hypr-live-update-guard
+fi
+sudo cp ~/code/archsetup/scripts/hypr-live-update-guard /usr/local/bin/  # refresh
+ls -l /usr/local/bin/hypr-live-update-guard /etc/pacman.d/hooks/hypr-live-update-guard.hook 2>&1
+#+end_src
+- Quick contract check (no pending upgrade needed): feed the script the hook's stdin contract with Hyprland running.
+#+begin_src sh :results output
+printf 'mesa\nhyprland\n' | /usr/local/bin/hypr-live-update-guard; echo "exit=$?"
+#+end_src
+Expected: exit=1, plus the BLOCKED banner naming mesa/hyprland and the from-a-TTY remedy.
+- Real firing inside pacman: with a mesa/hyprland/wayland/GPU-driver upgrade actually pending AND Hyprland running, run the upgrade.
+#+begin_src sh :results output
+sudo pacman -Syu
+#+end_src
+Expected: pacman runs the "Checking for a live Hyprland session..." hook and aborts; no packages upgraded.
+- The from-a-TTY path: the guard keys off the Hyprland *process*, so switching VTs while Hyprland still runs does NOT clear it (correct -- the session is still vulnerable). Fully log out of Hyprland (or =hyprctl dispatch exit=) so no Hyprland process remains, then from the console/display-manager run the upgrade again.
+Expected: the guard stays quiet and the upgrade completes.
+- Override while running (escape hatch):
+#+begin_src sh :results output
+sudo touch /run/archsetup-allow-live-gpu-update && echo "sentinel set"
+#+end_src
+Expected: with the sentinel present, =sudo pacman -Syu= proceeds despite Hyprland running. (The sentinel clears on reboot -- /run is tmpfs.)
 *** Wallpaper survives relogin (waypaper --restore)
 What we're verifying: the hyprland =exec-once= now runs =waypaper --restore= instead of a hardcoded =awww img=, so a wallpaper chosen via =set-wallpaper= / waypaper / dirvish persists across a relogin. The exec-once only fires at Hyprland startup, so this can't be confirmed without a real relogin. (Mechanism already verified: =waypaper --restore= applied the persisted wallpaper via the awww backend, exit 0.)
 - Set a wallpaper different from the current one (or pick one in waypaper, Super+Shift+P):