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