refactor: decompose install_btrfs into named orchestration stages

Pull the single-vs-multi-disk and LUKS-vs-no-encryption branching out
of install_btrfs() into five helpers in lib/btrfs.sh:

- btrfs_open_encryption         — LUKS open + fill devices array
- btrfs_make_filesystem         — create_btrfs_volume dispatch
- btrfs_configure_luks_target   — in-chroot LUKS config
- btrfs_install_grub            — GRUB primary + multi-disk mirror
- btrfs_close_encryption        — LUKS close (cleanup)

Helpers use namerefs (local -n) to take the caller's arrays as locals
instead of promoting them to globals. install_btrfs() drops from ~99
lines of nested if-then-else to a ~45-line flat sequence of named
stages — matching the style of install_zfs().

Behavior preserved — this is pure code movement, no new disk/LUKS
operations. No unit tests added for the new helpers: they all wrap
real LUKS/mkfs.btrfs calls that need block devices and root; VM
integration tests in scripts/test-install.sh remain the source of
truth. .shellcheckrc: disable SC2178 (nameref array heuristic) and
SC2153 (globals from sourced files) — both recurring false positives.

make test: 65/65. shellcheck clean.

3 files changed, 97 insertions, 62 deletions

diff --git a/.shellcheckrc b/.shellcheckrc
index c2d8dfd..7f7a9b1 100644
--- a/.shellcheckrc
+++ b/.shellcheckrc
@@ -17,5 +17,7 @@
 # SC2143 - Use grep -q (stylistic)
 # SC2207 - Prefer mapfile (arrays from command output)
 # SC1003 - False positive on escaped single quotes in case patterns
+# SC2178 - Nameref (local -n) tripping array-vs-string heuristic
+# SC2153 - Global vars set in other sourced files look unset to shellcheck
 
-disable=SC2034,SC2086,SC2162,SC2016,SC2317,SC2012,SC1091,SC2329,SC2011,SC2010,SC2129,SC2001,SC2059,SC2143,SC2207,SC1003
+disable=SC2034,SC2086,SC2162,SC2016,SC2317,SC2012,SC1091,SC2329,SC2011,SC2010,SC2129,SC2001,SC2059,SC2143,SC2207,SC1003,SC2178,SC2153
diff --git a/installer/archangel b/installer/archangel
index 5719d4f..f103fe9 100755
--- a/installer/archangel
+++ b/installer/archangel
@@ -1507,7 +1507,6 @@ install_zfs() {
 #############################
 
 install_btrfs() {
-    local num_disks=${#SELECTED_DISKS[@]}
     local btrfs_devices=()
     local efi_parts=()
     local root_parts=()
@@ -1518,92 +1517,46 @@ install_btrfs() {
         efi_parts+=("$(get_efi_partition "$disk")")
     done
 
-    # Partition all disks
+    # Partition and format EFI
     for disk in "${SELECTED_DISKS[@]}"; do
         partition_disk "$disk"
     done
-
-    # Format all EFI partitions
     format_efi_partitions "${SELECTED_DISKS[@]}"
 
-    # LUKS encryption (if enabled)
-    if [[ "$NO_ENCRYPT" != "yes" ]]; then
-        if [[ $num_disks -eq 1 ]]; then
-            # Single disk LUKS
-            create_luks_container "${root_parts[0]}" "$LUKS_PASSPHRASE"
-            open_luks_container "${root_parts[0]}" "$LUKS_PASSPHRASE"
-            btrfs_devices=("/dev/mapper/$LUKS_MAPPER_NAME")
-        else
-            # Multi-disk LUKS - encrypt each partition
-            create_luks_containers "$LUKS_PASSPHRASE" "${root_parts[@]}"
-            open_luks_containers "$LUKS_PASSPHRASE" "${root_parts[@]}"
-            btrfs_devices=($(get_luks_devices $num_disks))
-        fi
-    else
-        # No encryption - use raw partitions
-        btrfs_devices=("${root_parts[@]}")
-    fi
-
-    # Create btrfs filesystem
-    if [[ $num_disks -eq 1 ]]; then
-        create_btrfs_volume "${btrfs_devices[0]}"
-    else
-        create_btrfs_volume "${btrfs_devices[@]}" --raid-level "$RAID_LEVEL"
-    fi
-
-    # Create and mount subvolumes (use first device for mount)
-    create_btrfs_subvolumes "${btrfs_devices[0]}"
-    mount_btrfs_subvolumes "${btrfs_devices[0]}"
+    # LUKS (optional) fills btrfs_devices with either /dev/mapper/* or raw parts
+    btrfs_open_encryption root_parts btrfs_devices
 
-    # Mount primary EFI
+    # Btrfs filesystem + subvolumes + EFI mount
+    btrfs_make_filesystem     btrfs_devices
+    create_btrfs_subvolumes   "${btrfs_devices[0]}"
+    mount_btrfs_subvolumes    "${btrfs_devices[0]}"
     mkdir -p /mnt/efi
     mount "${efi_parts[0]}" /mnt/efi
 
-    # Install base system
+    # Base install + system config
     install_base
-
-    # Configure system
     configure_system
     configure_wifi
     configure_ssh
 
-    # Configure encryption if enabled
-    if [[ "$NO_ENCRYPT" != "yes" ]]; then
-        setup_luks_testing_keyfile "$LUKS_PASSPHRASE" "${root_parts[@]}"
-        configure_crypttab "${root_parts[@]}"
-        configure_luks_grub "${root_parts[0]}"
-        configure_luks_initramfs
-    fi
+    # LUKS config inside chroot (no-op if encryption disabled)
+    btrfs_configure_luks_target root_parts
 
     generate_btrfs_fstab "${btrfs_devices[0]}" "${efi_parts[0]}"
     configure_btrfs_initramfs
 
-    # GRUB installation
-    if [[ $num_disks -eq 1 ]]; then
-        configure_grub "${efi_parts[0]}"
-    else
-        # Multi-disk: install GRUB to all EFI partitions
-        configure_grub "${efi_parts[0]}"
-        install_grub_all_efi "${efi_parts[@]}"
-        create_grub_sync_hook "${efi_parts[@]}"
-    fi
+    # Bootloader
+    btrfs_install_grub efi_parts
 
+    # Snapshots + services
     configure_snapper
     configure_btrfs_services
     configure_btrfs_pacman_hook
-
-    # Genesis snapshot
     create_btrfs_genesis_snapshot
 
     # Cleanup
     btrfs_cleanup
-    if [[ "$NO_ENCRYPT" != "yes" ]]; then
-        if [[ $num_disks -eq 1 ]]; then
-            close_luks_container
-        else
-            close_luks_containers $num_disks
-        fi
-    fi
+    btrfs_close_encryption
     print_btrfs_summary
 }
 
diff --git a/installer/lib/btrfs.sh b/installer/lib/btrfs.sh
index 4e11e2f..f1cfaac 100644
--- a/installer/lib/btrfs.sh
+++ b/installer/lib/btrfs.sh
@@ -901,3 +901,83 @@ btrfs_cleanup() {
 
     info "Btrfs cleanup complete."
 }
+
+#############################
+# Btrfs Install Orchestration
+#############################
+# These helpers dispatch single-disk vs multi-disk branches that used
+# to live inline in install_btrfs(). They use namerefs so the caller's
+# arrays stay as locals in install_btrfs.
+
+# Open LUKS containers (if encryption enabled) and fill _devices with
+# either /dev/mapper/* names or the raw partitions.
+# Usage: btrfs_open_encryption ROOT_PARTS_VAR OUT_DEVICES_VAR
+btrfs_open_encryption() {
+    local -n _root_parts="$1"
+    local -n _devices="$2"
+    local num_disks=${#SELECTED_DISKS[@]}
+
+    if [[ "$NO_ENCRYPT" == "yes" ]]; then
+        _devices=("${_root_parts[@]}")
+        return 0
+    fi
+
+    if [[ $num_disks -eq 1 ]]; then
+        create_luks_container "${_root_parts[0]}" "$LUKS_PASSPHRASE"
+        open_luks_container   "${_root_parts[0]}" "$LUKS_PASSPHRASE"
+        _devices=("/dev/mapper/$LUKS_MAPPER_NAME")
+    else
+        create_luks_containers "$LUKS_PASSPHRASE" "${_root_parts[@]}"
+        open_luks_containers   "$LUKS_PASSPHRASE" "${_root_parts[@]}"
+        # shellcheck disable=SC2207
+        _devices=($(get_luks_devices "$num_disks"))
+    fi
+}
+
+# Create the btrfs filesystem: plain for single disk, raided for multi.
+# Usage: btrfs_make_filesystem DEVICES_VAR
+btrfs_make_filesystem() {
+    local -n _devices="$1"
+    local num_disks=${#SELECTED_DISKS[@]}
+
+    if [[ $num_disks -eq 1 ]]; then
+        create_btrfs_volume "${_devices[0]}"
+    else
+        create_btrfs_volume "${_devices[@]}" --raid-level "$RAID_LEVEL"
+    fi
+}
+
+# Run the in-chroot LUKS configuration (no-op if encryption disabled).
+# Usage: btrfs_configure_luks_target ROOT_PARTS_VAR
+btrfs_configure_luks_target() {
+    local -n _root_parts="$1"
+    [[ "$NO_ENCRYPT" == "yes" ]] && return 0
+    setup_luks_testing_keyfile "$LUKS_PASSPHRASE" "${_root_parts[@]}"
+    configure_crypttab         "${_root_parts[@]}"
+    configure_luks_grub        "${_root_parts[0]}"
+    configure_luks_initramfs
+}
+
+# Install GRUB to the first EFI partition, then mirror to any others.
+# Usage: btrfs_install_grub EFI_PARTS_VAR
+btrfs_install_grub() {
+    local -n _efi_parts="$1"
+    local num_disks=${#SELECTED_DISKS[@]}
+
+    configure_grub "${_efi_parts[0]}"
+    if [[ $num_disks -gt 1 ]]; then
+        install_grub_all_efi  "${_efi_parts[@]}"
+        create_grub_sync_hook "${_efi_parts[@]}"
+    fi
+}
+
+# Close LUKS containers opened during install (no-op if encryption disabled).
+btrfs_close_encryption() {
+    [[ "$NO_ENCRYPT" == "yes" ]] && return 0
+    local num_disks=${#SELECTED_DISKS[@]}
+    if [[ $num_disks -eq 1 ]]; then
+        close_luks_container
+    else
+        close_luks_containers "$num_disks"
+    fi
+}