docs/ci: implement yay 13 SIGSEGV workaround and update docs

AGENTS.md

@@ -112,6 +112,7 @@ whitespace.
 - **quickshell pin / Qt 6.12**: end-4 pins quickshell to `41651d7` (Sep 25), which predates upstream fix `5d5d498` (Oct 3, *"use MOC includes instead of opaque pointer definitions — … Qt 6.12 compatibility"*). Arch shipped qt6 6.12.0 on Oct 8 and the old pin died with `Meta Types must be fully defined` in the moc build of quickshell-hyprland-ipc (failed CI run 137). `customize_airootfs.sh` therefore rewrites end-4's `_commit` to `11ca60be` after cloning — but **only** while it still matches `^_commit='41651d7`, so once end-4 bumps their own pin the guard goes inert and theirs wins. `localrepo/check-quickshell-pin.sh` (weekly `pin-check.yaml` job) fails CI if either pin goes stale or loses the fix; it warns instead of failing when end-4's known-stale pin is covered by the override.
 - **MicroTeX flags**: the image's `makepkg.conf` is CachyOS's (`-march=native -O3`, LTO). GCC 16.2 hit an internal compiler error (segfault) on MicroTeX's `gtkmm_main.cpp` with it (failed CI run 155; not reproducible locally), so `customize_airootfs.sh` patches end-4's `illogical-impulse-microtex-git` PKGBUILD to `options=(!lto)` + `-O2` (our `localrepo/end4-pkgbuilds/microtex-git` carries the same).
 - **CAP_SETFCAP on the runner**: without it pacstrap drops `security.capability` xattrs (newuidmap/newgidmap, snap-confine, dumpcap, kwin_wayland, ...) from the live ISO with only a warning. `build-iso.yaml` fails the job early if the runner lacks it — fix the runner, don't remove the check.
+- **yay SIGSEGV on exit**: yay 13 (libalpm via purego/`dyalpm`) can segfault in `alpm_release()` *after* a finished transaction (failed CI run at end-4's `illogical-impulse-kde` step), which aborted `install-deps`. `customize_airootfs.sh` puts a temporary `yay` shim first on the builder's `PATH`: a failed plain `yay -S <pkgs>` counts as success only if `pacman -T` confirms every target is installed (it logs `[yay-shim]`). Every other failure keeps yay's exit code.
 - mono's `cert-sync` runs before `ca-certificates.crt` exists during pacstrap, so `customize_airootfs.sh` (live) and `install_pacstrap` (target) re-run it.
 - `/etc/skel/.zshrc` is owned by `grml-zsh-config`, so ours is staged as `airootfs/root/.zshrc-skel` and installed by `customize_airootfs.sh` after pacstrap — never add files under `airootfs/` at paths a package owns, or pacstrap aborts with "exists in filesystem".
 - `packages.x86_64` is sorted alphabetically. Keep it sorted when adding/removing entries.

airootfs/root/customize_airootfs.sh

@@ -172,6 +172,36 @@ chmod 440 /etc/sudoers.d/99-ii-builder
 # so the tree must be owned by the account that runs it.
 chown -R "${BUILD_USER}:${BUILD_USER}" "${DOTS_REPO}"
 
+# yay 13 (libalpm via purego/dyalpm) can SIGSEGV in alpm_release() at exit,
+# *after* the transaction and its hooks completed (failed CI run: crash in
+# dyalpm handle.Release). end-4 sees exit 2 and aborts. This shim, put first
+# on PATH for the install-deps run only, turns a failed plain `yay -S <pkgs>`
+# into success when every target is installed afterwards (pacman -T); any
+# other failure keeps yay's exit code. It lives in /tmp and is removed after.
+YAY_SHIM_DIR="$(mktemp -d /tmp/ii-yay-shim.XXXXXX)"
+cat > "${YAY_SHIM_DIR}/yay" <<'EOF'
+#!/bin/bash
+"${YAY_SHIM_REAL:-/usr/bin/yay}" "$@"
+rc=$?
+(( rc == 0 )) && exit 0
+sync=0
+targets=()
+for a in "$@"; do
+  case "$a" in
+    -S|--sync) sync=1 ;;
+    -S*) exit "$rc" ;;  # -Ss/-Si/-Syu/...: not a plain install
+    -*) ;;
+    *) targets+=("$a") ;;
+  esac
+done
+if (( sync && ${#targets[@]} )) && pacman -T -- "${targets[@]}" >/dev/null; then
+  echo "[yay-shim] yay exited ${rc}, but all ${#targets[@]} targets are installed - continuing" >&2
+  exit 0
+fi
+exit "$rc"
+EOF
+chmod 755 "${YAY_SHIM_DIR}" "${YAY_SHIM_DIR}/yay"
+
 # -f: never prompt (ask=false); -s: skip "pacman -Syu";
 # --skip-plasmaintg: optional Firefox widget that pulls 410 pkgs / 526 MiB of
 #                    KDE packages onto a non-KDE system;
@@ -180,11 +210,14 @@ chown -R "${BUILD_USER}:${BUILD_USER}" "${DOTS_REPO}"
 # shellcheck disable=SC2024  # the redirect is meant for the child, not sudo
 if ! sudo -u "${BUILD_USER}" env HOME="/home/${BUILD_USER}" \
     GIT_TERMINAL_PROMPT=0 \
+    PATH="${YAY_SHIM_DIR}:/usr/local/sbin:/usr/local/bin:/usr/bin" \
     bash -c "cd ${DOTS_REPO} && ./setup install-deps -f -s --skip-plasmaintg" \
     < <(yes e); then
+  rm -rf "${YAY_SHIM_DIR}"
   echo "[customize] end-4 ./setup install-deps failed" >&2
   exit 1
 fi
+rm -rf "${YAY_SHIM_DIR}"
 
 # ── Harvest the packages install-deps just built into the in-image local repo ─
 # The live /etc/pacman.conf points [local-aur] at /opt/localrepo; without the