Consolidate background work into one job layer

AGENTS.md

@@ -174,7 +174,12 @@ When the user corrects an agent approach, add or tighten one concrete rule here
 - Import Pester 5.8.0 before running tests so `Invoke-Pester -Output Detailed -CI` does not resolve to Windows' inbox Pester 3.4.0.
 - Keep package install/uninstall process launches simple unless explicitly requested; do not add a separate stdout/stderr process logging helper for winget or Chocolatey.
 - When the active log file is owned by `Start-Transcript`, do not call `Add-Content` against that file; write to host output so the transcript captures the line in the same log file without recording a terminating-error diagnostic.
-- Keep UI helpers such as `Invoke-WPFUIThread` and `Set-WinUtilTweaksProgressIndicator` safe to call without a window; the `-Preset` and `-Config` paths run the workflows before the form is created and before PresentationCore is loaded.
+- Keep UI helpers such as `Invoke-WPFUIThread` and `Write-WinUtilJobProgress` safe to call without a window; the `-Preset` and `-Config` paths run the workflows before the form is created and before PresentationCore is loaded. Ask `Test-WinUtilUIAlive` rather than writing the `$sync.Form` / dispatcher / `HasShutdownStarted` check out by hand.
+- Put long operations on the job layer with `Start-WinUtilJob` and report from them with `Write-WinUtilJobProgress`; a job body must not set the busy flag, print its own banner, or carry its own try/catch/finally around the interface. `Invoke-WPFRunspace` directly is for fire-and-forget work that is not a job.
+- Drain interface work that nobody is waiting for through `Start-WinUtilBackgroundQueue`; do not hand-roll another dequeue-and-re-post pump.
+- Values a posted scriptblock needs travel as the dispatcher's argument or through `-Parameters`, never captured from the caller: a plain block resolves them when the dispatcher gets to it, and `GetNewClosure` binds command lookup to a copied scope. For the same reason, prefer a compiled `[action]` over `Invoke-WPFUIThread -Async` on hot re-posting paths, which marshals its body as text and recompiles it per post.
+- Diagnostic scaffolding does not ship. Measure with it, then delete it.
+- Have each Pester file load the assemblies and dot-source the functions it needs; several passed only because an earlier file in alphabetical order happened to load them.
 - Log install/uninstall package names and package-manager IDs before queuing background runspace work; do not rely on runspace host output for the package identity.
 - For Win11 Creator, start each new ISO modification in a fresh `WinUtil_Win11ISO_*` temp directory; existing-work detection is only for resuming/exporting already modified media.
 - For Win11 Creator driver injection, keep offline WIM servicing to one mount, one `/Add-Driver`, and one commit; do not export editions or run unrelated WIM cleanup, and reject damaged metadata before ISO export.

config/tweaks.json

@@ -1086,8 +1086,13 @@
     "panel": "1",
     "InvokeScript": [
       "
-      Remove-Item -Path \"$Env:Temp\\*\" -Recurse -Force
-      Remove-Item -Path \"$Env:SystemRoot\\Temp\\*\" -Recurse -Force
+      $before = @(Get-ChildItem -Path \"$Env:Temp\", \"$Env:SystemRoot\\Temp\" -Force -ErrorAction SilentlyContinue).Count
+      # A temp folder always holds files something has open, including this run's own. Those are
+      # skipped rather than reported, or every cleanup would look like a failed one.
+      Remove-Item -Path \"$Env:Temp\\*\" -Recurse -Force -ErrorAction SilentlyContinue
+      Remove-Item -Path \"$Env:SystemRoot\\Temp\\*\" -Recurse -Force -ErrorAction SilentlyContinue
+      $after = @(Get-ChildItem -Path \"$Env:Temp\", \"$Env:SystemRoot\\Temp\" -Force -ErrorAction SilentlyContinue).Count
+      Write-Host \"Removed $($before - $after) temporary item(s); $after still in use.\"
       "
     ],
     "link": "https://winutil.christitus.com/code-reference/tweaks/essential-tweaks/deletetempfiles"

docs/src/content/docs/code-reference/architecture.mdx

@@ -79,14 +79,15 @@ winutil/
 **Why**: Makes distribution easier (single file) and improves load time.
 
 #### 2. scripts/main.ps1
-**Purpose**: Entry point that initializes the GUI and event system.
+**Purpose**: Entry point that manages the run.
 
 **Responsibilities**:
-- Load XAML and create WPF window
-- Initialize form elements
-- Set up event handlers
 - Load configurations
-- Display the GUI
+- Run the headless `-Preset` and `-Config` paths
+- Start the interface on a dedicated STA runspace and wait for it
+- Report anything the interface thread failed with, then clean up
+
+The interface itself lives in `Start-WinUtilUserInterface`, not here. See [Threading Model](#threading-model).
 
 #### 3. functions/public/
 **Purpose**: User-facing functions that implement main features.
@@ -390,23 +391,68 @@ Update UI
 - `service`: Services to change
 - `OriginalValue/State`: For undo functionality
 
-## PowerShell Runspace
+## Threading Model
+
+WinUtil runs on three kinds of thread, and each has one job:
+
+| Thread | Runspace | Responsibility |
+| --- | --- | --- |
+| Main | The one the script started in | Start the interface, wait for it, surface its errors, clean up |
+| Interface | `$sync.UIRunspace`, a dedicated STA runspace | Own the window. Paint and dispatch, nothing else |
+| Workers | `$sync.runspace`, a shared pool | Run everything long: installs, tweaks, features, AppX, Win11 Creator |
 
-Winutil uses PowerShell runspaces for the GUI to remain responsive:
+All three are created from the same starting point, `New-WinUtilSessionState`, which carries
+`$sync`, the compiled script's globals, and every WinUtil function. That is what lets any
+thread call any helper without the caller injecting function definitions.
 
 ```powershell
-# Create runspace
-$sync.runspace = [runspacefactory]::CreateRunspace()
-$sync.runspace.Open()
-$sync.runspace.SessionStateProxy.SetVariable("sync", $sync)
-
-# Run code in background
-$powershell = [powershell]::Create().AddScript($scriptblock)
-$powershell.Runspace = $sync.runspace
-$handle = $powershell.BeginInvoke()
+# main.ps1 - the interface gets its own thread
+$sync.UIRunspace = [runspacefactory]::CreateRunspace($Host, (New-WinUtilSessionState))
+$sync.UIRunspace.ApartmentState = "STA"
+$sync.UIRunspace.Open()
+
+$uiShell = [powershell]::Create()
+$uiShell.Runspace = $sync.UIRunspace
+[void]$uiShell.AddScript({ Start-WinUtilUserInterface })
+$uiHandle = $uiShell.BeginInvoke()
+$uiHandle.AsyncWaitHandle.WaitOne()
 ```
 
-**Why**: Prevents UI freezing during long-running operations.
+**Why**: the window never blocks on work, and a failure on the interface thread is reported
+instead of disappearing.
+
+## Long-Running Work
+
+Every long action goes through `Start-WinUtilJob`, which owns everything a running operation
+needs: refusing to start while another job runs, the busy flag (`$sync.ActiveJob`), the progress
+bar and taskbar item, the boxed console banner, a start/finish/failure line in the log, and
+restoring the interface in a `finally` whatever happens.
+
+`Invoke-WPFButton` decides what counts as a long action. Anything that changes the system gets a
+job; anything that only changes what the interface is showing runs on the interface thread.
+That single classification is why no workflow arranges its own progress, banner or busy state.
+
+```powershell
+Start-WinUtilJob -Name "Features" -Description "Installing Windows Features" -Parameters @{
+    Features = @($sync.selectedFeatures)
+} -ScriptBlock {
+    param($Features)
+
+    $total = @($Features).Count
+    $completed = 0
+    foreach ($feature in $Features) {
+        $completed++
+        Step-WinUtilJob -Status "Installing $feature ($completed/$total)" -Percent ([int](($completed / $total) * 100))
+        Invoke-WinUtilFeatureInstall $feature
+    }
+}
+```
+
+The body only has to do the work and call `Step-WinUtilJob`. Anything it throws is
+caught, logged, and shown on the taskbar as a failure.
+
+**Values, not closures**: the body is rebuilt inside the worker from its text, so it receives
+what it needs through `-Parameters` rather than capturing the caller's variables.
 
 ## WPF Event Handling
 
@@ -452,23 +498,21 @@ if (!(Get-Command choco -ErrorAction SilentlyContinue)) {
 choco install $app.choco -y
 ```
 
-## Error Handling
+## Error Handling And Logging
 
-Winutil uses PowerShell error handling:
+A job body does not need its own error handling. `Start-WinUtilJob` catches whatever the body
+throws, logs it, and marks the run as failed on the taskbar, so a failure can never leave the
+interface stuck busy. Only catch inside a body when you have something specific to do first,
+such as cleaning up a mounted image, and then rethrow.
 
 ```powershell
-try {
-    # Attempt operation
-    Invoke-SomeOperation
-}
-catch {
-    Write-Host "Error: $_" -ForegroundColor Red
-    # Log error
-    Add-Content -Path $logfile -Value "ERROR: $_"
-}
+Write-WinUtilLog -Level "ERROR" -Component "Install" -Message "winget install failed: $($_.Exception.Message)"
 ```
 
-**Logging**: Errors and operations are logged for debugging.
+Entries go to `%LocalAppData%\winutil\logs\winutil_<timestamp>.log` from every thread, guarded
+by a named mutex. The console transcript is a separate file in the same directory, because
+`Start-Transcript` keeps its file open and only records the runspace it was started on - so
+anything a worker logged would otherwise never reach disk.
 
 ## Configuration Loading
 
@@ -486,15 +530,23 @@ $sync.configs.features = Get-Content "config/feature.json" | ConvertFrom-Json
 
 ## UI Update Pattern
 
-UI updates must happen on the UI thread:
+Controls may only be touched from the thread that owns the window, so background work reaches
+them through `Invoke-WPFUIThread`:
 
 ```powershell
-$sync.form.Dispatcher.Invoke([action]{
-    $sync.WPFStatusLabel.Content = "Installing..."
-}, "Normal")
+Invoke-WPFUIThread -Parameters @{ Count = $installed.Count } -ScriptBlock {
+    param($Count)
+    $sync.WPFselectedAppsButton.Content = "Selected Apps: $Count"
+}
 ```
 
-**Why**: WPF requires UI updates on the main thread.
+Add `-Async` to post the update instead of waiting for it. `Step-WinUtilJob` and the
+Win11 Creator status log use that so a per-item update never stalls the worker.
+
+**Values, not closures**: the body is rebuilt inside the interface runspace, so it takes what it
+needs through `-Parameters`. Handing over a scriptblock from a worker instead would keep that
+worker's session state, which loses the caller's variables on an async post and costs roughly
+twenty times as much per command - enough to turn a checkbox refresh into a visible freeze.
 
 ## Adding New Features
 

functions/private/Close-WinUtilRunspacePool.ps1

@@ -1,8 +1,39 @@
 function Close-WinUtilRunspacePool {
+    <#
+        .SYNOPSIS
+            Stops anything still running and closes the worker pool
+
+        .DESCRIPTION
+            Closing the pool with work still in it is what produced an unhandled
+            InvalidRunspaceStateException: a queued instance starts on a runspace that is already
+            closing, throws on a thread pool thread, and takes the process down. Whatever is in
+            flight is therefore asked to stop, and waited for, before the pool is closed.
+    #>
+    param(
+        [int]$StopTimeoutSeconds = 15,
+
+        # Replacing a pool that is no longer usable, rather than shutting WinUtil down. The
+        # difference matters: ShuttingDown is what makes the job layer refuse work, and nothing
+        # resets it, so recycling through the shutdown path would reject every later action for
+        # the rest of the session.
+        [switch]$Recycle
+    )
+
     if ($null -eq $sync -or -not $sync.ContainsKey("runspace") -or $null -eq $sync.runspace) {
         return
     }
 
+    # Set before stopping, so nothing that is winding down queues fresh work behind us
+    if (-not $Recycle) {
+        $sync.ShuttingDown = $true
+    }
+
+    try {
+        Stop-WinUtilActiveWork -TimeoutSeconds $StopTimeoutSeconds | Out-Null
+    } catch {
+        Write-WinUtilLog -Level "WARN" -Component "UI" -Message "Could not stop running work cleanly: $($_.Exception.Message)"
+    }
+
     try {
         if ($sync.runspace.RunspacePoolStateInfo.State -notin @(
             [System.Management.Automation.Runspaces.RunspacePoolState]::Closed,
@@ -11,8 +42,12 @@ function Close-WinUtilRunspacePool {
         )) {
             $sync.runspace.Close()
         }
+    } catch {
+        # A pool that will not close cleanly must not stop the window from closing
+        Write-WinUtilLog -Level "WARN" -Component "UI" -Message "Worker pool did not close cleanly: $($_.Exception.Message)"
     } finally {
-        $sync.runspace.Dispose()
+        try { $sync.runspace.Dispose() } catch { }
         $sync.Remove("runspace")
+        if ($sync.ActiveShells) { $sync.ActiveShells.Clear() }
     }
 }

functions/private/Complete-WinUtilPackageRun.ps1

@@ -0,0 +1,50 @@
+function Complete-WinUtilPackageRun {
+    <#
+        .SYNOPSIS
+            Reports what a package run actually did and fails the job if anything did not work
+
+        .DESCRIPTION
+            Package managers report failure through an exit code, which is easy to walk past.
+            Without this the job layer would show a green checkmark for a run in which nothing
+            installed. Throwing here is what turns a failed package into a failed job.
+
+        .PARAMETER Action
+            Install or Uninstall, used in the summary text.
+
+        .PARAMETER Results
+            The result objects produced by Install-WinUtilProgramWinget and
+            Install-WinUtilProgramChoco.
+    #>
+    param(
+        [Parameter(Mandatory)]
+        [string]$Action,
+
+        [object[]]$Results = @()
+    )
+
+    $succeeded = @($Results | Where-Object { $_.Outcome -eq "Succeeded" })
+    $skipped = @($Results | Where-Object { $_.Outcome -eq "Skipped" })
+    $failed = @($Results | Where-Object { $_.Outcome -eq "Failed" })
+
+    $summary = "$($succeeded.Count) succeeded, $($skipped.Count) skipped, $($failed.Count) failed"
+    Write-WinUtilLog -Component "Package" -Message "$Action summary: $summary"
+    Write-Host "$Action summary: $summary"
+
+    foreach ($result in $skipped) {
+        Write-Host "  skipped  $($result.Package) - $($result.Detail)"
+    }
+    foreach ($result in $failed) {
+        Write-Host "  failed   $($result.Package) - $($result.Detail)" -ForegroundColor Red
+    }
+
+    if ($failed.Count -gt 0) {
+        $names = ($failed | ForEach-Object { $_.Package }) -join ', '
+        $reasons = @($failed | ForEach-Object { $_.Detail } | Sort-Object -Unique)
+
+        # One shared reason is worth repeating; several would bury it, and they are listed above
+        if ($reasons.Count -eq 1) {
+            throw "$($failed.Count) of $($Results.Count) package(s) failed: $names. $($reasons[0])"
+        }
+        throw "$($failed.Count) of $($Results.Count) package(s) failed: $names. See the lines above for each reason."
+    }
+}

functions/private/Get-WinUtilAppEntryHandlers.ps1

@@ -0,0 +1,60 @@
+function Get-WinUtilAppEntryHandlers {
+    <#
+        .SYNOPSIS
+            The event handlers shared by every app entry on the Install tab
+
+        .DESCRIPTION
+            A scriptblock literal inside a loop is a new scriptblock every time round, and
+            building six of them per app is the single largest cost of drawing the app list:
+            measured at 2.13 ms per entry against 0.62 ms when they are made once and reused.
+
+            None of them close over anything per entry. They read the sender through $this, so
+            one instance serves every app.
+    #>
+
+    if ($null -ne $script:WinUtilAppEntryHandlers) {
+        return $script:WinUtilAppEntryHandlers
+    }
+
+    $script:WinUtilAppEntryHandlers = @{
+        BorderClick = {
+            # Resolve through $sync because the border's child is a layout Grid for FOSS entries
+            $childCheckbox = $sync.$($this.Tag)
+            $childCheckbox.IsChecked = -not $childCheckbox.IsChecked
+        }
+        MouseEnter = {
+            if (($sync.$($this.Tag).IsChecked) -eq $false) {
+                $this.SetResourceReference([Windows.Controls.Control]::BackgroundProperty, "AppInstallHighlightedColor")
+            }
+        }
+        MouseLeave = {
+            if (($sync.$($this.Tag).IsChecked) -eq $false) {
+                $this.SetResourceReference([Windows.Controls.Control]::BackgroundProperty, "AppInstallUnselectedColor")
+            }
+        }
+        RightClick = {
+            # Store the selected app in a global variable so it can be used in the popup
+            $sync.appPopupSelectedApp = $this.Tag
+            # Set the popup position to the current mouse position
+            $sync.appPopup.PlacementTarget = $this
+            $sync.appPopup.IsOpen = $true
+        }
+        # The checkbox sits inside the entry layout Grid, so the border is one level further up
+        Checked = {
+            Invoke-WPFSelectedCheckboxesUpdate -type "Add" -checkboxName $this.Tag
+            $borderElement = $this.Parent.Parent
+            $borderElement.SetResourceReference([Windows.Controls.Control]::BackgroundProperty, "AppInstallSelectedColor")
+        }
+        Unchecked = {
+            Invoke-WPFSelectedCheckboxesUpdate -type "Remove" -checkboxName $this.Tag
+            $borderElement = $this.Parent.Parent
+            $borderElement.SetResourceReference([Windows.Controls.Control]::BackgroundProperty, "AppInstallUnselectedColor")
+        }
+        ImageFailed = {
+            $this.Visibility = "Collapsed"
+            $this.Parent.Children[0].Visibility = "Visible"
+        }
+    }
+
+    return $script:WinUtilAppEntryHandlers
+}

functions/private/Get-WinUtilSelectedPackages.ps1

@@ -8,10 +8,9 @@ function Get-WinUtilSelectedPackages {
          [string] $Preference
      )
 
+    # A single package has no meaningful percentage to show
     if ($PackageList.count -eq 1) {
-        Invoke-WPFUIThread -ScriptBlock { Set-WinUtilTaskbaritem -state "Indeterminate" -value 0.01 -overlay "logo" }
-    } else {
-        Invoke-WPFUIThread -ScriptBlock { Set-WinUtilTaskbaritem -state "Normal" -value 0.01 -overlay "logo" }
+        Step-WinUtilJob -State "Indeterminate"
     }
 
     $packagesWinget = [System.Collections.ArrayList]::new()