From 662051ecde66c5d4f9501df1e816ae5136a408cb Mon Sep 17 00:00:00 2001
From: Ryan Hughes <ryan@heyoodle.com>
Date: Tue, 15 Sep 2026 00:06:17 -0400
Subject: [PATCH 1/2] Install matching kernel headers for every DKMS setup

---
 bin/omarchy-install-gaming-xbox-controllers   |  3 +-
 bin/omarchy-pkg-add-kernel-headers            | 13 +++
 install/hardware/apple/fix-spi-keyboard.sh    |  1 +
 install/hardware/fix-bcm43xx.sh               |  3 +-
 install/hardware/fix-elgato-camlink-4k.sh     |  4 +-
 install/hardware/fix-tuxedo-backlight.sh      |  3 +-
 .../hardware/fix-yt6801-ethernet-adapter.sh   |  3 +-
 install/hardware/intel/ipu7-camera.sh         |  1 +
 install/hardware/nvidia.sh                    |  5 +-
 install/omarchy-other.packages                |  2 -
 migrations/1789444024.sh                      |  8 ++
 test/acceptance.d/system-test.sh              | 16 +++-
 test/shell.d/kernel-headers-test.sh           | 89 +++++++++++++++++++
 13 files changed, 138 insertions(+), 13 deletions(-)
 create mode 100755 bin/omarchy-pkg-add-kernel-headers
 create mode 100644 migrations/1789444024.sh
 create mode 100755 test/shell.d/kernel-headers-test.sh

diff --git a/bin/omarchy-install-gaming-xbox-controllers b/bin/omarchy-install-gaming-xbox-controllers
index f4134f76..8f7bdf28 100755
--- a/bin/omarchy-install-gaming-xbox-controllers
+++ b/bin/omarchy-install-gaming-xbox-controllers
@@ -10,7 +10,8 @@ set -e
 echo "Installing Xbox controller Bluetooth support..."
 
 # Install xpadneo to ensure controllers work out of the box
-omarchy-pkg-add linux-headers xpadneo-dkms
+omarchy-pkg-add-kernel-headers
+omarchy-pkg-add xpadneo-dkms
 
 # Prevent xpad/xpadneo driver conflict
 echo blacklist xpad | sudo tee /etc/modprobe.d/blacklist-xpad.conf >/dev/null
diff --git a/bin/omarchy-pkg-add-kernel-headers b/bin/omarchy-pkg-add-kernel-headers
new file mode 100755
index 00000000..28590b36
--- /dev/null
+++ b/bin/omarchy-pkg-add-kernel-headers
@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# omarchy:summary=Install headers for the supported system kernel
+# omarchy:hidden=true
+# omarchy:requires-sudo=true
+
+# Inspect the target's packages: uname reports the live ISO kernel in a chroot.
+# A retained stock kernel must not take precedence over the Omarchy kernel.
+if omarchy-pkg-present linux-t2; then
+  omarchy-pkg-add linux-t2-headers
+else
+  omarchy-pkg-add linux-omarchy-headers
+fi
diff --git a/install/hardware/apple/fix-spi-keyboard.sh b/install/hardware/apple/fix-spi-keyboard.sh
index 330081b7..fd5d8e45 100644
--- a/install/hardware/apple/fix-spi-keyboard.sh
+++ b/install/hardware/apple/fix-spi-keyboard.sh
@@ -3,6 +3,7 @@ product_name="$(cat /sys/class/dmi/id/product_name 2>/dev/null)"
 if [[ $product_name =~ MacBook[89],1|MacBook1[02],1|MacBookPro13,[123]|MacBookPro14,[123] ]]; then
   echo "Detected MacBook with SPI keyboard"
 
+  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add macbook12-spi-driver-dkms
   sudo mkdir -p /etc/mkinitcpio.conf.d
   if [[ $product_name == "MacBook8,1" ]]; then
diff --git a/install/hardware/fix-bcm43xx.sh b/install/hardware/fix-bcm43xx.sh
index 94fd16e6..f829749e 100644
--- a/install/hardware/fix-bcm43xx.sh
+++ b/install/hardware/fix-bcm43xx.sh
@@ -6,5 +6,6 @@ pci_info=$(lspci -nn)
 
 if (echo "$pci_info" | grep -q "14e4:43a0" || echo "$pci_info" | grep -q "14e4:4331"); then
   echo "BCM4360 / BCM4331 detected"
-  omarchy-pkg-add broadcom-wl-dkms linux-omarchy-headers
+  omarchy-pkg-add-kernel-headers
+  omarchy-pkg-add broadcom-wl-dkms
 fi
diff --git a/install/hardware/fix-elgato-camlink-4k.sh b/install/hardware/fix-elgato-camlink-4k.sh
index 274076ce..d12cbfe4 100644
--- a/install/hardware/fix-elgato-camlink-4k.sh
+++ b/install/hardware/fix-elgato-camlink-4k.sh
@@ -4,8 +4,8 @@
 # v4l2-relayd re-exposes it at 1280x720 under the same name.
 
 if omarchy-hw-elgato-camlink-4k; then
-  mapfile -t kernel_headers < <(pacman -Qqs '^linux(-zen|-lts|-hardened|-t2|-ptl|-omarchy(-bore|-ptl-novrr-mm)?)?$' | sed 's/$/-headers/')
-  omarchy-pkg-add "${kernel_headers[@]}" v4l2loopback-dkms v4l2loopback-utils v4l2-relayd
+  omarchy-pkg-add-kernel-headers
+  omarchy-pkg-add v4l2loopback-dkms v4l2loopback-utils v4l2-relayd
 
   sudo install -Dm644 "$OMARCHY_PATH/default/udev/elgato-camlink-4k.rules" /etc/udev/rules.d/71-elgato-camlink-4k.rules
   sudo install -Dm644 "$OMARCHY_PATH/default/v4l2-relayd/camlink.conf" /etc/v4l2-relayd.d/camlink.conf
diff --git a/install/hardware/fix-tuxedo-backlight.sh b/install/hardware/fix-tuxedo-backlight.sh
index a2d3b8c6..c40fadb8 100644
--- a/install/hardware/fix-tuxedo-backlight.sh
+++ b/install/hardware/fix-tuxedo-backlight.sh
@@ -1,7 +1,8 @@
 # Install Tuxedo drivers for keyboard backlighting on Tuxedo laptops and
 # compatible devices like the Slimbook Executive (Clevo/Tuxedo chassis).
 if cat /sys/class/dmi/id/sys_vendor 2>/dev/null | grep -qi "TUXEDO\|Slimbook"; then
-  omarchy-pkg-add linux-omarchy-headers tuxedo-drivers-nocompatcheck-dkms
+  omarchy-pkg-add-kernel-headers
+  omarchy-pkg-add tuxedo-drivers-nocompatcheck-dkms
 
   # Blacklist the legacy clevo_xsm_wmi module which conflicts with the tuxedo-drivers
   # clevo_wmi module. When clevo_xsm_wmi loads first, it grabs the Clevo WMI GUIDs,
diff --git a/install/hardware/fix-yt6801-ethernet-adapter.sh b/install/hardware/fix-yt6801-ethernet-adapter.sh
index 7c0360e6..e20cb92e 100644
--- a/install/hardware/fix-yt6801-ethernet-adapter.sh
+++ b/install/hardware/fix-yt6801-ethernet-adapter.sh
@@ -1,4 +1,5 @@
 # Install drivers for Motorcomm YT6801 ethernet adapter used by the Slimbook Executive
 if lspci | grep -i "YT6801\|Motorcomm.*Ethernet"; then
-  omarchy-pkg-add linux-omarchy-headers yt6801-dkms
+  omarchy-pkg-add-kernel-headers
+  omarchy-pkg-add yt6801-dkms
 fi
diff --git a/install/hardware/intel/ipu7-camera.sh b/install/hardware/intel/ipu7-camera.sh
index 97e5549b..45f1aced 100644
--- a/install/hardware/intel/ipu7-camera.sh
+++ b/install/hardware/intel/ipu7-camera.sh
@@ -1,5 +1,6 @@
 # Install MIPI camera support for Intel IPU7 hardware
 
 if grep -q "OVTI08F4" /sys/bus/acpi/devices/*/hid 2>/dev/null; then
+  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add intel-ipu7-camera
 fi
diff --git a/install/hardware/nvidia.sh b/install/hardware/nvidia.sh
index 48f62cd4..3b9adc18 100644
--- a/install/hardware/nvidia.sh
+++ b/install/hardware/nvidia.sh
@@ -1,8 +1,4 @@
 if lspci | grep -qi 'nvidia'; then
-  # Check which kernel is installed and set appropriate headers package
-  KERNEL_PACKAGE=$(pacman -Qqs '^linux(-zen|-lts|-hardened|-t2|-ptl|-omarchy(-bore|-ptl-novrr-mm)?)?$' | head -1 || true)
-  [[ -n $KERNEL_PACKAGE ]] && omarchy-pkg-add "$KERNEL_PACKAGE-headers"
-
   if omarchy-hw-nvidia-gsp; then
     PACKAGES=(nvidia-open-dkms nvidia-utils lib32-nvidia-utils libva-nvidia-driver)
   elif omarchy-hw-nvidia-without-gsp; then
@@ -15,6 +11,7 @@ if lspci | grep -qi 'nvidia'; then
     exit 0
   fi
 
+  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add "${PACKAGES[@]}"
 
   # Per-session Hyprland NVIDIA env vars are handled by default/hypr/nvidia.lua.
diff --git a/install/omarchy-other.packages b/install/omarchy-other.packages
index 1f325b24..4a8b128f 100644
--- a/install/omarchy-other.packages
+++ b/install/omarchy-other.packages
@@ -20,9 +20,7 @@ libva-nvidia-driver
 limine
 limine-mkinitcpio-hook
 limine-snapper-sync
-linux
 linux-firmware
-linux-headers
 linux-omarchy
 linux-omarchy-headers
 macbook12-spi-driver-dkms
diff --git a/migrations/1789444024.sh b/migrations/1789444024.sh
new file mode 100644
index 00000000..05107342
--- /dev/null
+++ b/migrations/1789444024.sh
@@ -0,0 +1,8 @@
+echo "Install missing headers for the Omarchy or T2 kernel"
+
+# Fresh ISO installs mark earlier migrations complete, so the kernel migration
+# cannot repair headers omitted by those installers. Package installation is
+# idempotent when another user has already applied this repair.
+if omarchy-pkg-present linux-omarchy || omarchy-pkg-present linux-t2; then
+  omarchy-pkg-add-kernel-headers
+fi
diff --git a/test/acceptance.d/system-test.sh b/test/acceptance.d/system-test.sh
index 0d648e9c..af0d5204 100644
--- a/test/acceptance.d/system-test.sh
+++ b/test/acceptance.d/system-test.sh
@@ -24,6 +24,20 @@ verify_core_packages() {
   pass "all Omarchy core packages are installed (${#missing[@]} missing)"
 }
 
+verify_kernel_headers() {
+  local kernel=linux-omarchy
+  local release
+  release=$(uname -r)
+  omarchy-pkg-present linux-t2 && kernel=linux-t2
+
+  [[ $(cat "/usr/lib/modules/$release/pkgbase") == "$kernel" ]] ||
+    fail "the installed system boots the supported kernel" "$release is not $kernel"
+  omarchy-pkg-present "$kernel-headers" || fail "kernel headers are installed" "$kernel-headers is missing"
+  [[ $(cat "/usr/lib/modules/$release/build/include/config/kernel.release") == "$release" ]] ||
+    fail "headers match the running kernel" "$release has missing or mismatched headers"
+  pass "the running $kernel kernel has matching headers ($release)"
+}
+
 verify_defaults() {
   [[ $(omarchy-default-browser) == "chromium" ]] || fail "Chromium is the default browser"
   pass "Chromium is the default browser"
@@ -112,7 +126,7 @@ verify_user_setup() {
   pass "Omarchy user state and shell configuration exist"
 }
 
-for check in verify_core_packages verify_defaults verify_services verify_runtime_tools verify_user_setup; do
+for check in verify_core_packages verify_kernel_headers verify_defaults verify_services verify_runtime_tools verify_user_setup; do
   if ! ("$check"); then
     status=1
   fi
diff --git a/test/shell.d/kernel-headers-test.sh b/test/shell.d/kernel-headers-test.sh
new file mode 100755
index 00000000..51db25d0
--- /dev/null
+++ b/test/shell.d/kernel-headers-test.sh
@@ -0,0 +1,89 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+mkdir -p "$tmp_dir/bin" "$tmp_dir/etc/modprobe.d" "$tmp_dir/sys/class/dmi/id" "$tmp_dir/sys/bus/acpi/devices/camera"
+export INSTALLED_PACKAGES="$tmp_dir/installed" CALL_LOG="$tmp_dir/calls"
+export PATH="$tmp_dir/bin:$ROOT/bin:$PATH" OMARCHY_PATH="$ROOT"
+
+cat > "$tmp_dir/bin/pacman" <<'SH'
+#!/bin/bash
+[[ $1 == "-Q" ]] || exit 1
+grep -Fxq -- "$2" "$INSTALLED_PACKAGES"
+SH
+cat > "$tmp_dir/bin/omarchy-pkg-add" <<'SH'
+#!/bin/bash
+printf '%s\n' "$*" >> "$CALL_LOG"
+[[ ${FAIL_HEADERS:-0} != 1 || $* != *-headers* ]]
+SH
+cat > "$tmp_dir/bin/lspci" <<'SH'
+#!/bin/bash
+printf '%s\n' 'NVIDIA [10de:2560]' 'Broadcom [14e4:43a0]' 'Motorcomm YT6801 Ethernet'
+SH
+cat > "$tmp_dir/bin/id" <<'SH'
+#!/bin/bash
+echo input
+SH
+for command in sudo lsmod omarchy-hw-nvidia-gsp omarchy-hw-elgato-camlink-4k; do
+  printf '#!/bin/bash\nexit 0\n' > "$tmp_dir/bin/$command"
+done
+chmod +x "$tmp_dir/bin/"*
+
+for installed in linux-omarchy linux-t2 linux; do
+  echo "$installed" > "$INSTALLED_PACKAGES"
+  : > "$CALL_LOG"
+  bash -euo pipefail "$ROOT/migrations/1789444024.sh" >/dev/null
+  if [[ $installed == "linux" ]]; then
+    [[ ! -s $CALL_LOG ]] || fail "header repair skips systems without a supported kernel"
+  else
+    [[ $(cat "$CALL_LOG") == "$installed-headers" ]] || fail "header repair covers existing $installed installs"
+  fi
+done
+pass "header repair covers existing Omarchy and T2 installs"
+echo MacBook8,1 > "$tmp_dir/sys/class/dmi/id/product_name"
+echo TUXEDO > "$tmp_dir/sys/class/dmi/id/sys_vendor"
+echo OVTI08F4 > "$tmp_dir/sys/bus/acpi/devices/camera/hid"
+
+for installed in 'linux-omarchy' 'linux linux-omarchy' 'linux' 'linux-t2' 'linux linux-omarchy linux-t2'; do
+  expected=linux-omarchy-headers
+  [[ $installed == *linux-t2* ]] && expected=linux-t2-headers
+  read -ra packages <<< "$installed"
+  printf '%s\n' "${packages[@]}" > "$INSTALLED_PACKAGES"
+  : > "$CALL_LOG"
+  omarchy-pkg-add-kernel-headers
+  [[ $(cat "$CALL_LOG") == "$expected" ]] || fail "headers match supported kernel with $installed installed"
+  pass "headers match supported kernel with $installed installed"
+done
+
+# Run every DKMS installer against hardware fixtures and stub package writes.
+# Redirect absolute filesystem paths in sourced leaves into the fixture too.
+for family in linux-omarchy linux-t2; do
+  printf '%s\n' linux "$family" > "$INSTALLED_PACKAGES"
+  for script in \
+    bin/omarchy-install-gaming-xbox-controllers \
+    install/hardware/nvidia.sh \
+    install/hardware/apple/fix-spi-keyboard.sh \
+    install/hardware/intel/ipu7-camera.sh \
+    install/hardware/fix-bcm43xx.sh \
+    install/hardware/fix-tuxedo-backlight.sh \
+    install/hardware/fix-yt6801-ethernet-adapter.sh \
+    install/hardware/fix-elgato-camlink-4k.sh; do
+    sed -e "s|/etc/|$tmp_dir/etc/|g" -e "s|/sys/|$tmp_dir/sys/|g" \
+      -e "s|/lib/modules/|$tmp_dir/lib/modules/|g" "$ROOT/$script" > "$tmp_dir/installer.sh"
+    : > "$CALL_LOG"
+    bash -e "$tmp_dir/installer.sh" >/dev/null
+    [[ $(head -1 "$CALL_LOG") == "$family-headers" ]] || fail "$script installs $family headers first" "$(cat "$CALL_LOG")"
+    (( $(wc -l < "$CALL_LOG") == 2 )) || fail "$script installs its driver after the headers"
+    ! grep -wq linux-headers "$CALL_LOG" || fail "$script avoids stock headers"
+
+    : > "$CALL_LOG"
+    if FAIL_HEADERS=1 bash -e "$tmp_dir/installer.sh" >/dev/null; then
+      fail "$script stops when headers cannot be installed"
+    fi
+    [[ $(cat "$CALL_LOG") == "$family-headers" ]] || fail "$script must not install DKMS drivers without headers"
+    pass "$script uses $family headers and stops on header installation failure"
+  done
+done

From 24417bf191e09fc4d672c74c34e184449e92aeda Mon Sep 17 00:00:00 2001
From: Ryan Hughes <ryan@heyoodle.com>
Date: Tue, 15 Sep 2026 00:46:30 -0400
Subject: [PATCH 2/2] Treat matching kernel headers as a base system guarantee

---
 agents/skills/install-scripts.md              |  1 +
 bin/omarchy-install-gaming-xbox-controllers   |  1 -
 bin/omarchy-pkg-add-kernel-headers            | 13 ---
 install/hardware/apple/fix-spi-keyboard.sh    |  1 -
 install/hardware/fix-bcm43xx.sh               |  1 -
 install/hardware/fix-elgato-camlink-4k.sh     |  1 -
 install/hardware/fix-tuxedo-backlight.sh      |  1 -
 .../hardware/fix-yt6801-ethernet-adapter.sh   |  1 -
 install/hardware/intel/ipu7-camera.sh         |  1 -
 install/hardware/nvidia.sh                    |  1 -
 migrations/1789444024.sh                      |  8 +-
 test/shell.d/kernel-headers-migration-test.sh | 58 ++++++++++++
 test/shell.d/kernel-headers-test.sh           | 89 -------------------
 13 files changed, 64 insertions(+), 113 deletions(-)
 delete mode 100755 bin/omarchy-pkg-add-kernel-headers
 create mode 100755 test/shell.d/kernel-headers-migration-test.sh
 delete mode 100755 test/shell.d/kernel-headers-test.sh

diff --git a/agents/skills/install-scripts.md b/agents/skills/install-scripts.md
index 999a6e9c..aa993e5e 100644
--- a/agents/skills/install-scripts.md
+++ b/agents/skills/install-scripts.md
@@ -13,6 +13,7 @@ commands and reusable setup leaves:
 - use `$OMARCHY_INSTALL` and `$OMARCHY_PATH` instead of hard-coded Omarchy paths.
 - keep root-scoped hardware setup under `install/hardware/` and orchestrate it through `install/hardware/all.sh`.
 - keep every per-user setup leaf under `install/user/` (including `install/user/hardware/` and `install/user/first-run/`) so it is clear what must run for each user.
+- The base install supplies matching kernel headers before hardware setup. DKMS installers should install their driver packages and assume the headers exist.
 - prefer helper commands for package and command checks where available.
 
 Raw `command -v`, `pacman`, and `pacman-key` are acceptable in package-helper
diff --git a/bin/omarchy-install-gaming-xbox-controllers b/bin/omarchy-install-gaming-xbox-controllers
index 8f7bdf28..f2cda4e7 100755
--- a/bin/omarchy-install-gaming-xbox-controllers
+++ b/bin/omarchy-install-gaming-xbox-controllers
@@ -10,7 +10,6 @@ set -e
 echo "Installing Xbox controller Bluetooth support..."
 
 # Install xpadneo to ensure controllers work out of the box
-omarchy-pkg-add-kernel-headers
 omarchy-pkg-add xpadneo-dkms
 
 # Prevent xpad/xpadneo driver conflict
diff --git a/bin/omarchy-pkg-add-kernel-headers b/bin/omarchy-pkg-add-kernel-headers
deleted file mode 100755
index 28590b36..00000000
--- a/bin/omarchy-pkg-add-kernel-headers
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/bash
-
-# omarchy:summary=Install headers for the supported system kernel
-# omarchy:hidden=true
-# omarchy:requires-sudo=true
-
-# Inspect the target's packages: uname reports the live ISO kernel in a chroot.
-# A retained stock kernel must not take precedence over the Omarchy kernel.
-if omarchy-pkg-present linux-t2; then
-  omarchy-pkg-add linux-t2-headers
-else
-  omarchy-pkg-add linux-omarchy-headers
-fi
diff --git a/install/hardware/apple/fix-spi-keyboard.sh b/install/hardware/apple/fix-spi-keyboard.sh
index fd5d8e45..330081b7 100644
--- a/install/hardware/apple/fix-spi-keyboard.sh
+++ b/install/hardware/apple/fix-spi-keyboard.sh
@@ -3,7 +3,6 @@ product_name="$(cat /sys/class/dmi/id/product_name 2>/dev/null)"
 if [[ $product_name =~ MacBook[89],1|MacBook1[02],1|MacBookPro13,[123]|MacBookPro14,[123] ]]; then
   echo "Detected MacBook with SPI keyboard"
 
-  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add macbook12-spi-driver-dkms
   sudo mkdir -p /etc/mkinitcpio.conf.d
   if [[ $product_name == "MacBook8,1" ]]; then
diff --git a/install/hardware/fix-bcm43xx.sh b/install/hardware/fix-bcm43xx.sh
index f829749e..0f9cf474 100644
--- a/install/hardware/fix-bcm43xx.sh
+++ b/install/hardware/fix-bcm43xx.sh
@@ -6,6 +6,5 @@ pci_info=$(lspci -nn)
 
 if (echo "$pci_info" | grep -q "14e4:43a0" || echo "$pci_info" | grep -q "14e4:4331"); then
   echo "BCM4360 / BCM4331 detected"
-  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add broadcom-wl-dkms
 fi
diff --git a/install/hardware/fix-elgato-camlink-4k.sh b/install/hardware/fix-elgato-camlink-4k.sh
index d12cbfe4..9ae9e343 100644
--- a/install/hardware/fix-elgato-camlink-4k.sh
+++ b/install/hardware/fix-elgato-camlink-4k.sh
@@ -4,7 +4,6 @@
 # v4l2-relayd re-exposes it at 1280x720 under the same name.
 
 if omarchy-hw-elgato-camlink-4k; then
-  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add v4l2loopback-dkms v4l2loopback-utils v4l2-relayd
 
   sudo install -Dm644 "$OMARCHY_PATH/default/udev/elgato-camlink-4k.rules" /etc/udev/rules.d/71-elgato-camlink-4k.rules
diff --git a/install/hardware/fix-tuxedo-backlight.sh b/install/hardware/fix-tuxedo-backlight.sh
index c40fadb8..7fb408e0 100644
--- a/install/hardware/fix-tuxedo-backlight.sh
+++ b/install/hardware/fix-tuxedo-backlight.sh
@@ -1,7 +1,6 @@
 # Install Tuxedo drivers for keyboard backlighting on Tuxedo laptops and
 # compatible devices like the Slimbook Executive (Clevo/Tuxedo chassis).
 if cat /sys/class/dmi/id/sys_vendor 2>/dev/null | grep -qi "TUXEDO\|Slimbook"; then
-  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add tuxedo-drivers-nocompatcheck-dkms
 
   # Blacklist the legacy clevo_xsm_wmi module which conflicts with the tuxedo-drivers
diff --git a/install/hardware/fix-yt6801-ethernet-adapter.sh b/install/hardware/fix-yt6801-ethernet-adapter.sh
index e20cb92e..f88a9cec 100644
--- a/install/hardware/fix-yt6801-ethernet-adapter.sh
+++ b/install/hardware/fix-yt6801-ethernet-adapter.sh
@@ -1,5 +1,4 @@
 # Install drivers for Motorcomm YT6801 ethernet adapter used by the Slimbook Executive
 if lspci | grep -i "YT6801\|Motorcomm.*Ethernet"; then
-  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add yt6801-dkms
 fi
diff --git a/install/hardware/intel/ipu7-camera.sh b/install/hardware/intel/ipu7-camera.sh
index 45f1aced..97e5549b 100644
--- a/install/hardware/intel/ipu7-camera.sh
+++ b/install/hardware/intel/ipu7-camera.sh
@@ -1,6 +1,5 @@
 # Install MIPI camera support for Intel IPU7 hardware
 
 if grep -q "OVTI08F4" /sys/bus/acpi/devices/*/hid 2>/dev/null; then
-  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add intel-ipu7-camera
 fi
diff --git a/install/hardware/nvidia.sh b/install/hardware/nvidia.sh
index 3b9adc18..1c36787b 100644
--- a/install/hardware/nvidia.sh
+++ b/install/hardware/nvidia.sh
@@ -11,7 +11,6 @@ if lspci | grep -qi 'nvidia'; then
     exit 0
   fi
 
-  omarchy-pkg-add-kernel-headers
   omarchy-pkg-add "${PACKAGES[@]}"
 
   # Per-session Hyprland NVIDIA env vars are handled by default/hypr/nvidia.lua.
diff --git a/migrations/1789444024.sh b/migrations/1789444024.sh
index 05107342..b5bc9149 100644
--- a/migrations/1789444024.sh
+++ b/migrations/1789444024.sh
@@ -3,6 +3,8 @@ echo "Install missing headers for the Omarchy or T2 kernel"
 # Fresh ISO installs mark earlier migrations complete, so the kernel migration
 # cannot repair headers omitted by those installers. Package installation is
 # idempotent when another user has already applied this repair.
-if omarchy-pkg-present linux-omarchy || omarchy-pkg-present linux-t2; then
-  omarchy-pkg-add-kernel-headers
-fi
+for kernel in linux-omarchy linux-t2; do
+  if omarchy-pkg-present "$kernel"; then
+    omarchy-pkg-add "$kernel-headers"
+  fi
+done
diff --git a/test/shell.d/kernel-headers-migration-test.sh b/test/shell.d/kernel-headers-migration-test.sh
new file mode 100755
index 00000000..458ea330
--- /dev/null
+++ b/test/shell.d/kernel-headers-migration-test.sh
@@ -0,0 +1,58 @@
+#!/bin/bash
+
+set -euo pipefail
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+mkdir -p "$tmp_dir/bin"
+export INSTALLED_PACKAGES="$tmp_dir/installed" CALL_LOG="$tmp_dir/calls"
+export PATH="$tmp_dir/bin:$ROOT/bin:$PATH"
+
+# Keep the real package helpers, but contain every pacman transaction here.
+cat > "$tmp_dir/bin/pacman" <<'SH'
+#!/bin/bash
+case "$1" in
+  -Q) grep -Fxq -- "$2" "$INSTALLED_PACKAGES" ;;
+  -S)
+    [[ ${FAIL_INSTALL:-0} == 0 ]] || exit 1
+    shift 3 # -S --noconfirm --needed
+    printf '%s\n' "$@" >> "$INSTALLED_PACKAGES"
+    printf '%s\n' "$@" >> "$CALL_LOG"
+    ;;
+  *) exit 1 ;;
+esac
+SH
+cat > "$tmp_dir/bin/sudo" <<'SH'
+#!/bin/bash
+[[ $1 == "pacman" ]] || exit 1
+"$@"
+SH
+chmod +x "$tmp_dir/bin/"*
+
+migration="$ROOT/migrations/1789444024.sh"
+for kernels in linux-omarchy linux-t2 'linux-omarchy linux-t2'; do
+  read -ra installed <<< "$kernels"
+  printf '%s\n' linux linux-headers "${installed[@]}" > "$INSTALLED_PACKAGES"
+  : > "$CALL_LOG"
+  bash -euo pipefail "$migration" >/dev/null
+  for kernel in "${installed[@]}"; do
+    grep -Fxq "$kernel-headers" "$INSTALLED_PACKAGES" || fail "$kernel gets its headers"
+  done
+  : > "$CALL_LOG"
+  bash -euo pipefail "$migration" >/dev/null
+  [[ ! -s $CALL_LOG ]] || fail "header repair is idempotent"
+  pass "missing headers are repaired once for $kernels"
+done
+
+printf '%s\n' linux linux-aarch64 > "$INSTALLED_PACKAGES"
+: > "$CALL_LOG"
+bash -euo pipefail "$migration" >/dev/null
+[[ ! -s $CALL_LOG ]] || fail "header repair skips unrelated kernels"
+pass "header repair skips unrelated kernels"
+
+echo linux-omarchy > "$INSTALLED_PACKAGES"
+if FAIL_INSTALL=1 bash -euo pipefail "$migration" >/dev/null; then
+  fail "a failed header installation must leave the migration pending"
+fi
+pass "header installation failure is propagated"
diff --git a/test/shell.d/kernel-headers-test.sh b/test/shell.d/kernel-headers-test.sh
deleted file mode 100755
index 51db25d0..00000000
--- a/test/shell.d/kernel-headers-test.sh
+++ /dev/null
@@ -1,89 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
-
-tmp_dir=$(mktemp -d)
-trap 'rm -rf "$tmp_dir"' EXIT
-mkdir -p "$tmp_dir/bin" "$tmp_dir/etc/modprobe.d" "$tmp_dir/sys/class/dmi/id" "$tmp_dir/sys/bus/acpi/devices/camera"
-export INSTALLED_PACKAGES="$tmp_dir/installed" CALL_LOG="$tmp_dir/calls"
-export PATH="$tmp_dir/bin:$ROOT/bin:$PATH" OMARCHY_PATH="$ROOT"
-
-cat > "$tmp_dir/bin/pacman" <<'SH'
-#!/bin/bash
-[[ $1 == "-Q" ]] || exit 1
-grep -Fxq -- "$2" "$INSTALLED_PACKAGES"
-SH
-cat > "$tmp_dir/bin/omarchy-pkg-add" <<'SH'
-#!/bin/bash
-printf '%s\n' "$*" >> "$CALL_LOG"
-[[ ${FAIL_HEADERS:-0} != 1 || $* != *-headers* ]]
-SH
-cat > "$tmp_dir/bin/lspci" <<'SH'
-#!/bin/bash
-printf '%s\n' 'NVIDIA [10de:2560]' 'Broadcom [14e4:43a0]' 'Motorcomm YT6801 Ethernet'
-SH
-cat > "$tmp_dir/bin/id" <<'SH'
-#!/bin/bash
-echo input
-SH
-for command in sudo lsmod omarchy-hw-nvidia-gsp omarchy-hw-elgato-camlink-4k; do
-  printf '#!/bin/bash\nexit 0\n' > "$tmp_dir/bin/$command"
-done
-chmod +x "$tmp_dir/bin/"*
-
-for installed in linux-omarchy linux-t2 linux; do
-  echo "$installed" > "$INSTALLED_PACKAGES"
-  : > "$CALL_LOG"
-  bash -euo pipefail "$ROOT/migrations/1789444024.sh" >/dev/null
-  if [[ $installed == "linux" ]]; then
-    [[ ! -s $CALL_LOG ]] || fail "header repair skips systems without a supported kernel"
-  else
-    [[ $(cat "$CALL_LOG") == "$installed-headers" ]] || fail "header repair covers existing $installed installs"
-  fi
-done
-pass "header repair covers existing Omarchy and T2 installs"
-echo MacBook8,1 > "$tmp_dir/sys/class/dmi/id/product_name"
-echo TUXEDO > "$tmp_dir/sys/class/dmi/id/sys_vendor"
-echo OVTI08F4 > "$tmp_dir/sys/bus/acpi/devices/camera/hid"
-
-for installed in 'linux-omarchy' 'linux linux-omarchy' 'linux' 'linux-t2' 'linux linux-omarchy linux-t2'; do
-  expected=linux-omarchy-headers
-  [[ $installed == *linux-t2* ]] && expected=linux-t2-headers
-  read -ra packages <<< "$installed"
-  printf '%s\n' "${packages[@]}" > "$INSTALLED_PACKAGES"
-  : > "$CALL_LOG"
-  omarchy-pkg-add-kernel-headers
-  [[ $(cat "$CALL_LOG") == "$expected" ]] || fail "headers match supported kernel with $installed installed"
-  pass "headers match supported kernel with $installed installed"
-done
-
-# Run every DKMS installer against hardware fixtures and stub package writes.
-# Redirect absolute filesystem paths in sourced leaves into the fixture too.
-for family in linux-omarchy linux-t2; do
-  printf '%s\n' linux "$family" > "$INSTALLED_PACKAGES"
-  for script in \
-    bin/omarchy-install-gaming-xbox-controllers \
-    install/hardware/nvidia.sh \
-    install/hardware/apple/fix-spi-keyboard.sh \
-    install/hardware/intel/ipu7-camera.sh \
-    install/hardware/fix-bcm43xx.sh \
-    install/hardware/fix-tuxedo-backlight.sh \
-    install/hardware/fix-yt6801-ethernet-adapter.sh \
-    install/hardware/fix-elgato-camlink-4k.sh; do
-    sed -e "s|/etc/|$tmp_dir/etc/|g" -e "s|/sys/|$tmp_dir/sys/|g" \
-      -e "s|/lib/modules/|$tmp_dir/lib/modules/|g" "$ROOT/$script" > "$tmp_dir/installer.sh"
-    : > "$CALL_LOG"
-    bash -e "$tmp_dir/installer.sh" >/dev/null
-    [[ $(head -1 "$CALL_LOG") == "$family-headers" ]] || fail "$script installs $family headers first" "$(cat "$CALL_LOG")"
-    (( $(wc -l < "$CALL_LOG") == 2 )) || fail "$script installs its driver after the headers"
-    ! grep -wq linux-headers "$CALL_LOG" || fail "$script avoids stock headers"
-
-    : > "$CALL_LOG"
-    if FAIL_HEADERS=1 bash -e "$tmp_dir/installer.sh" >/dev/null; then
-      fail "$script stops when headers cannot be installed"
-    fi
-    [[ $(cat "$CALL_LOG") == "$family-headers" ]] || fail "$script must not install DKMS drivers without headers"
-    pass "$script uses $family headers and stops on header installation failure"
-  done
-done