Force a GC before unloading the target user hive

.github/workflows/test.yml

@@ -140,6 +140,15 @@ jobs:
             exit 1
           }
 
+      - name: Run user hive helper tests
+        shell: pwsh
+        run: |
+          $result = Invoke-Pester -Path "Tests/Unit/Test-UserHiveHelpers.ps1" -Output Detailed -PassThru
+          if ($result.FailedCount -gt 0) {
+            Write-Error "$($result.FailedCount) test(s) failed in Test-UserHiveHelpers.ps1"
+            exit 1
+          }
+
       - name: Run integration tests
         shell: pwsh
         run: |

CHANGELOG.md

@@ -6,6 +6,10 @@ Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Ve
 
 ## [Unreleased]
 
+### Fixed
+
+- Unload the target user's registry hive reliably. When a `-Sysprep` or per-user run (apply, verification, or restore-to-another-user) read or wrote the mounted hive through the registry provider, lingering .NET `RegistryKey` handles kept the hive open, so `reg unload` failed and the code only warned while the hive stayed mounted, which can lock the profile. The unload now forces a garbage collection to release those handles and retries once, and only warns if it still cannot unload.
+
 ### Added
 
 - Mutating integration tests (Windows Sandbox only) for the two paths that were previously only unit-tested with mocks: Scope B module registry rollback (`ModuleRegistryRollback.Tests.ps1`, capture and restore against the real registry with type preservation) and the update watchdog (`WatchdogEnforcement.Tests.ps1`, real install, directory lockdown, integrity check, live policy re-assertion, and tamper detection). They run under `-Mutating` and are excluded from CI.

Scripts/Helpers/UserHiveHelpers.ps1

@@ -96,6 +96,48 @@ function Resolve-LoadedTargetUserHiveContext {
         -WasLoadedByScript $false)
 }
 
+function Invoke-WinnowRegHiveUnload {
+    # Thin wrapper around `reg unload` so the retry logic in Dismount-WinnowTargetUserHive can be
+    # unit-tested; reg.exe is a native command and cannot be mocked directly. Returns the exit code.
+    param(
+        [Parameter(Mandatory)]
+        [string]$MountName
+    )
+
+    $global:LASTEXITCODE = 0
+    reg unload "HKU\$MountName" | Out-Null
+    return $LASTEXITCODE
+}
+
+function Dismount-WinnowTargetUserHive {
+    # Unloads a hive the script mounted. The registry provider and .NET RegistryKey objects keep
+    # handles open into the hive until they are finalized, and `reg unload` fails while any handle is
+    # still open, which previously left the hive mounted after a Sysprep or per-user run (the apply,
+    # verification, and restore-to-another-user paths all read or write the loaded hive). Force a
+    # garbage collection to release those handles before unloading, and retry once after a second
+    # pass, since a handle can survive the first collect. Returns $true when the hive is unloaded.
+    param(
+        [Parameter(Mandatory)]
+        [string]$MountName
+    )
+
+    [System.GC]::Collect()
+    [System.GC]::WaitForPendingFinalizers()
+    if ((Invoke-WinnowRegHiveUnload -MountName $MountName) -eq 0) {
+        return $true
+    }
+
+    Start-Sleep -Milliseconds 200
+    [System.GC]::Collect()
+    [System.GC]::WaitForPendingFinalizers()
+    if ((Invoke-WinnowRegHiveUnload -MountName $MountName) -eq 0) {
+        return $true
+    }
+
+    Write-Warning "Failed to unload registry hive 'HKU\$MountName' after a retry. It may stay mounted until the next reboot; close any tool browsing HKEY_USERS and re-run, or reboot."
+    return $false
+}
+
 function Invoke-WithTargetUserHive {
     param(
         [Parameter(Mandatory)]
@@ -141,12 +183,7 @@ function Invoke-WithTargetUserHive {
         $script:RegistryTargetHiveMountName = $previousHiveMountName
 
         if ($hiveContext -and $hiveContext.WasLoadedByScript) {
-            $global:LASTEXITCODE = 0
-            reg unload "HKU\$($hiveContext.MountName)" | Out-Null
-            $unloadExitCode = $LASTEXITCODE
-            if ($unloadExitCode -ne 0) {
-                Write-Warning "Failed to unload registry hive 'HKU\$($hiveContext.MountName)' (exit code: $unloadExitCode)"
-            }
+            $null = Dismount-WinnowTargetUserHive -MountName ([string]$hiveContext.MountName)
         }
     }
 }

Tests/Unit/Test-UserHiveHelpers.ps1

@@ -0,0 +1,45 @@
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+<#
+.SYNOPSIS
+    Unit tests for the user-hive unload retry logic.
+.DESCRIPTION
+    reg unload fails while any handle into the loaded hive is still open. Dismount-WinnowTargetUserHive
+    forces a garbage collection before unloading and retries once, so a lingering RegistryKey handle
+    does not leave the hive mounted after a Sysprep, per-user, or restore-to-another-user run. reg.exe
+    is native and cannot be mocked, so the actual unload is behind Invoke-WinnowRegHiveUnload, which
+    these tests mock.
+#>
+
+BeforeAll {
+    $repoRoot = Split-Path -Parent (Split-Path -Parent $PSScriptRoot)
+    . (Join-Path $repoRoot 'Scripts\Helpers\UserHiveHelpers.ps1')
+}
+
+Describe 'Dismount-WinnowTargetUserHive' {
+
+    It 'unloads on the first attempt when reg unload succeeds' {
+        Mock -CommandName Invoke-WinnowRegHiveUnload -MockWith { 0 }
+
+        Dismount-WinnowTargetUserHive -MountName 'Default' | Should -BeTrue
+        Should -Invoke -CommandName Invoke-WinnowRegHiveUnload -Times 1 -Exactly
+    }
+
+    It 'retries after a garbage collection and succeeds when the first unload fails' {
+        $script:unloadCalls = 0
+        Mock -CommandName Invoke-WinnowRegHiveUnload -MockWith {
+            $script:unloadCalls++
+            if ($script:unloadCalls -eq 1) { 1 } else { 0 }
+        }
+
+        Dismount-WinnowTargetUserHive -MountName 'Default' | Should -BeTrue
+        Should -Invoke -CommandName Invoke-WinnowRegHiveUnload -Times 2 -Exactly
+    }
+
+    It 'warns and reports failure when both attempts fail' {
+        Mock -CommandName Invoke-WinnowRegHiveUnload -MockWith { 1 }
+
+        $result = Dismount-WinnowTargetUserHive -MountName 'Default' -WarningAction SilentlyContinue
+        $result | Should -BeFalse
+        Should -Invoke -CommandName Invoke-WinnowRegHiveUnload -Times 2 -Exactly
+    }
+}