windowsweep 1.0.0 → 1.1.0

package/modules/orphaned_appdata.ps1

@@ -0,0 +1,189 @@
+# orphaned_appdata.ps1 - section 23: folders directly under %APPDATA% and %LOCALAPPDATA% that belong to no
+# installed program. Interactive only; selected folders go to the Recycle Bin.
+#
+# The dangerous direction here is calling something orphaned when it is not, so every test errs the other
+# way: matching is generous, the exclusion list is long, and an EMPTY program index produces ZERO candidates
+# rather than "everything is orphaned".
+
+# Windows' own folders, shared infrastructure, and vendors whose data outlives an uninstall.
+$Script:WS_ORPHAN_EXCLUDE = @(
+  'Microsoft', 'Windows', 'WindowsPowerShell', 'PowerShell', 'Packages', 'Programs', 'Temp', 'Tmp', 'Comms',
+  'ConnectedDevicesPlatform', 'D3DSCache', 'Google', 'Mozilla', 'CrashDumps', 'VirtualStore', 'PeerDistRepub',
+  'Publishers', 'History', 'IconCache', 'ElevatedDiagnostics', 'Application Data', 'Local Settings',
+  'Deployment', 'assembly', 'GroupPolicy', 'Roaming', 'Local', 'LocalLow', 'Low', 'Diagnostics',
+  'PlaceholderTileLogoFolder', 'Desktop', 'Downloads', 'Documents', 'Start Menu', 'SendTo',
+  'Recent', 'NetHood', 'PrintHood', 'Templates', 'Cookies',
+  # Platform folders that belong to Windows or .NET rather than to any one program: they look orphaned
+  # because no uninstall entry names them, and one of them holds settings a .NET app wrote.
+  'IsolatedStorage', 'ToastNotificationManagerCompat', 'AppV', 'Package Cache', 'DBG', 'CLR_v4.0', 'CLR_v4.0_32'
+)
+
+function ConvertTo-MatchToken {
+  <# .SYNOPSIS Lower-case, alphanumerics only - so "Slack Technologies, Inc." and "slack" compare equal. #>
+  param([string] $Text)
+  if ([string]::IsNullOrWhiteSpace($Text)) { return '' }
+  return ($Text.ToLowerInvariant() -replace '[^a-z0-9]', '')
+}
+
+function Add-MatchTokens {
+  <# .SYNOPSIS Add a display string to the token set: the whole thing, plus each word of 4+ characters. #>
+  param([System.Collections.Generic.HashSet[string]] $Set, [string] $Text)
+  $whole = ConvertTo-MatchToken $Text
+  if ($whole.Length -ge 3) { $null = $Set.Add($whole) }
+  foreach ($w in ($Text -split '[^A-Za-z0-9]+')) {
+    $t = ConvertTo-MatchToken $w
+    if ($t.Length -ge 4) { $null = $Set.Add($t) }
+  }
+}
+
+function Get-InstalledProgramRows {
+  <# .SYNOPSIS Raw uninstall-hive rows from all three registry views. Shared with section 24. #>
+  $rows = @()
+  $hives = @(
+    'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall',
+    'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall',
+    'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall'
+  )
+  foreach ($h in $hives) {
+    $keys = @()
+    try { $keys = @(Get-ChildItem -LiteralPath $h -ErrorAction Stop) } catch { $keys = @() }
+    foreach ($k in $keys) {
+      $props = $null
+      try { $props = Get-ItemProperty -LiteralPath $k.PSPath -ErrorAction Stop } catch { continue }
+      if (-not $props.DisplayName) { continue }
+      $rows += [pscustomobject]@{
+        DisplayName = [string]$props.DisplayName; DisplayVersion = [string]$props.DisplayVersion
+        Publisher = [string]$props.Publisher; InstallDate = [string]$props.InstallDate
+        EstimatedSizeKb = [long]0 + $props.EstimatedSize; InstallLocation = [string]$props.InstallLocation
+        UninstallString = [string]$props.UninstallString; SystemComponent = [int]0 + $props.SystemComponent
+      }
+    }
+  }
+  return $rows
+}
+
+function Get-InstalledProgramIndex {
+  <# .SYNOPSIS Everything that says "a program owns this name": uninstall entries, program folders, Store
+     package names and running processes. RegistryCount drives the fail-closed gate in section 23. #>
+  $P = $Script:P
+  $set = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::Ordinal)
+  $rows = @(Get-InstalledProgramRows)
+  foreach ($r in $rows) {
+    Add-MatchTokens -Set $set -Text $r.DisplayName
+    Add-MatchTokens -Set $set -Text $r.Publisher
+    if ($r.InstallLocation) { Add-MatchTokens -Set $set -Text (Split-Path -Leaf ($r.InstallLocation.TrimEnd('\'))) }
+  }
+  foreach ($dir in @($P.PF, $P.PF86, (Join-Path $P.L 'Programs'), (Join-Path $P.L 'Microsoft\WindowsApps'), (Join-Path $P.PD 'Microsoft\Windows\Start Menu\Programs'))) {
+    if (-not $dir -or -not (Test-DirPresent $dir)) { continue }
+    foreach ($e in (Get-ChildEntries $dir)) { Add-MatchTokens -Set $set -Text (($e.Name -split '_')[0]) }
+  }
+  foreach ($e in (Get-ChildEntries (Join-Path $P.L 'Packages'))) { Add-MatchTokens -Set $set -Text (($e.Name -split '_')[0]) }
+  try { foreach ($proc in (Get-Process -ErrorAction SilentlyContinue)) { Add-MatchTokens -Set $set -Text $proc.ProcessName } } catch { $null = $_ }
+  return [pscustomobject]@{ Tokens = $set; RegistryCount = $rows.Count; Rows = $rows }
+}
+
+function Get-OrphanExclusions {
+  <# .SYNOPSIS Folder names section 23 never offers: the fixed list plus, derived at run time, the first
+     segment under AppData of every target the tool already declares - so a vendor folder we clean can never
+     also be offered for deletion, and the list cannot drift as sections are added. #>
+  $P = $Script:P
+  $set = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
+  foreach ($n in $Script:WS_ORPHAN_EXCLUDE) { $null = $set.Add($n) }
+  $prefixes = @("$($P.A)\", "$($P.L)\")
+  foreach ($t in (Get-AllTargets)) {
+    $path = [string]$t.Path
+    foreach ($pre in $prefixes) {
+      if ($path.StartsWith($pre, [StringComparison]::OrdinalIgnoreCase)) {
+        $seg = ($path.Substring($pre.Length) -split '\\')[0]
+        if ($seg) { $null = $set.Add($seg) }
+      }
+    }
+  }
+  # ,$set - a bare `return $set` UNROLLS the HashSet into an Object[], whose .Contains is case-SENSITIVE,
+  # so a folder named "slack" would slip past the "Slack" entry. The comma keeps the set a set.
+  return , $set
+}
+
+function Test-OrphanFolderName {
+  <# .SYNOPSIS True when NOTHING installed claims this folder name. Deliberately generous in the other
+     direction: a token that merely starts with the name (or the reverse) counts as a claim. #>
+  param([string] $Name, [pscustomobject] $Index)
+  $n = ConvertTo-MatchToken $Name
+  if ($n.Length -lt 3) { return $false }
+  if ($Index.Tokens.Contains($n)) { return $false }
+  foreach ($t in $Index.Tokens) {
+    if ($t.Length -lt 4) { continue }
+    if ($t.StartsWith($n) -or $n.StartsWith($t)) { return $false }
+  }
+  return $true
+}
+
+function Find-OrphanedAppData {
+  <# .SYNOPSIS Top-level AppData folders idle N+ days that no installed program claims. Fails closed.
+     -Index is for the self-test: it proves the fail-closed gate without touching the real registry. #>
+  param([int] $Days, [pscustomobject] $Index = $null)
+  $P = $Script:P
+  $index = $Index
+  if ($null -eq $index) { $index = Get-InstalledProgramIndex }
+  if ($index.RegistryCount -eq 0) {
+    Write-Warn 'no uninstall entries could be read: refusing to call anything orphaned (fail closed).'
+    return @()
+  }
+  Write-Note "cross-checked against $($index.RegistryCount) installed-program entries"
+  $exclude = Get-OrphanExclusions
+  $out = @()
+  foreach ($root in @($P.A, $P.L)) {
+    if (-not (Test-DirPresent $root)) { continue }
+    foreach ($e in (Get-ChildEntries $root)) {
+      if (-not ($e -is [IO.DirectoryInfo]) -or (Test-ReparsePoint $e)) { continue }
+      if ($exclude.Contains($e.Name)) { continue }
+      $full = Remove-LongPrefix $e.FullName
+      if (Get-ProtectionReason $full) { continue }
+      if (-not (Test-OrphanFolderName -Name $e.Name -Index $index)) { continue }
+      $idle = Get-IdleDays $full
+      if ($idle -lt $Days) { continue }
+      $out += [pscustomobject]@{ Name = $e.Name; Path = $full; Root = (Get-FullPath $root); Idle = $idle; Bytes = [long](Get-DirectoryBytes $full) }
+    }
+  }
+  return @($out | Sort-Object Bytes -Descending | Select-Object -First 200)
+}
+
+function Get-Targets23 {
+  <# .SYNOPSIS Informational rows: the candidates are found at run time, never declared as fixed paths. #>
+  $P = $Script:P
+  $t = @()
+  foreach ($r in @($P.A, $P.L)) {
+    if (Test-DirPresent $r) { $t += (New-Target 23 'AppData root scanned for orphans' (Get-FullPath $r) -Kind cmd -Note 'top-level folders only; you pick what goes, and it lands in the Recycle Bin') }
+  }
+  return $t
+}
+
+function Invoke-Section23 {
+  $ws = $Script:WS
+  Write-SectionIntro @(
+    'Uninstalling a program usually leaves its AppData folder behind. This lists top-level folders under',
+    "Roaming and Local that no installed program, Store package or running process claims and that nothing",
+    "has touched for $($ws.Days)+ days. You pick what goes; it lands in the Recycle Bin."
+  )
+  $rows = @(Find-OrphanedAppData -Days $ws.Days)
+  if ($rows.Count -eq 0) { Write-Info 'no orphaned application data found'; return }
+  Write-UiLine ("  {0,3}  {1,10} {2,6}  {3}" -f '#', 'SIZE', 'IDLE', 'FOLDER') 'White'
+  $i = 1; $total = [long]0
+  foreach ($r in $rows) {
+    Write-UiLine ("  {0,3}  {1,10} {2,5}d  {3}" -f $i, (Format-Bytes $r.Bytes), $r.Idle, $r.Path) 'Gray'
+    Add-JsonCandidate -Section 23 -Index $i -Path $r.Path -Bytes $r.Bytes -IdleDays $r.Idle
+    $total += $r.Bytes; $i++
+  }
+  Write-Info ('total: ' + (Format-Bytes $total))
+  Write-Note 'a folder here can still hold settings or a licence for a program you plan to reinstall - read the list.'
+  $dest = 'the Recycle Bin'
+  if ($ws.Permanent) { $dest = 'PERMANENT deletion (--permanent)' }
+  Write-Note "selected folders go to $dest"
+  $picks = @(Read-MultiSelect -Total $rows.Count -NoAutoYes -Candidates @($rows | ForEach-Object { $_.Path }))
+  if ($picks.Count -eq 0) { Write-Info 'nothing selected'; return }
+  if (-not $ws.DryRun) {
+    # Orphaned app data never auto-confirms: --yes does not apply. An explicit --select / --select-file does.
+    if (-not (Confirm-Ui -Prompt "Move $($picks.Count) folder(s) to $dest ?" -Default 'n' -NoAutoYes -ScriptedOk)) { Write-Info 'skipped'; return }
+  }
+  foreach ($k in $picks) { $null = Send-ToRecycleBin -Path $rows[$k - 1].Path -Within $rows[$k - 1].Root }
+}

package/modules/personal.ps1

@@ -73,22 +73,24 @@ function Show-FileTable {
 }
 
 function Invoke-PersonalPicker {
-  param([object[]] $Rows, [string] $Prompt)
+  param([object[]] $Rows, [string] $Prompt, [int] $Section = 0)
   $ws = $Script:WS
   $Rows = @($Rows)
   if ($Rows.Count -eq 0) { Write-Info 'none found'; return }
   Show-FileTable $Rows
   $total = [long]0
-  foreach ($r in $Rows) { $total += $r.Bytes }
+  $i = 1
+  foreach ($r in $Rows) { $total += $r.Bytes; Add-JsonCandidate -Section $Section -Index $i -Path $r.Path -Bytes $r.Bytes -IdleDays $r.Idle; $i++ }
   Write-Info ("total: " + (Format-Bytes $total))
   $dest = 'the Recycle Bin'
   if ($ws.Permanent) { $dest = 'PERMANENT deletion (--permanent)' }
   Write-Note "selected files go to $dest"
-  $picks = Read-MultiSelect -Total $Rows.Count
+  $picks = @(Read-MultiSelect -Total $Rows.Count -NoAutoYes -Candidates @($Rows | ForEach-Object { $_.Path }))
   if ($picks.Count -eq 0) { Write-Info 'nothing selected'; return }
   if (-not $ws.DryRun) {
-    # Personal files never auto-confirm: --yes does not apply here.
-    if (-not (Confirm-Ui -Prompt "$Prompt ($($picks.Count) file(s))?" -Default 'n' -NoAutoYes)) { Write-Info 'skipped'; return }
+    # Personal files never auto-confirm: --yes does not apply here. An explicit --select / --select-file
+    # choice does, because it is a person naming these exact files in advance.
+    if (-not (Confirm-Ui -Prompt "$Prompt ($($picks.Count) file(s))?" -Default 'n' -NoAutoYes -ScriptedOk)) { Write-Info 'skipped'; return }
   }
   foreach ($k in $picks) { $null = Send-ToRecycleBin -Path $Rows[$k - 1].Path -Within $Rows[$k - 1].Root }
 }
@@ -99,7 +101,7 @@ function Invoke-Section18 {
     'You pick what goes; it lands in the Recycle Bin. Desktop and cloud-synced folders are never scanned.'
   )
   if (@(Get-PersonalRoots).Count -eq 0) { Write-Info 'no Downloads folder found'; return }
-  Invoke-PersonalPicker -Rows @(Get-PartialDownloads) -Prompt 'Move the selected partial downloads to the Recycle Bin'
+  Invoke-PersonalPicker -Rows @(Get-PartialDownloads) -Prompt 'Move the selected partial downloads to the Recycle Bin' -Section 18
 }
 
 function Invoke-Section19 {
@@ -109,7 +111,7 @@ function Invoke-Section19 {
     'archives you already extracted. You pick what goes; it lands in the Recycle Bin.'
   )
   if (@(Get-PersonalRoots).Count -eq 0) { Write-Info 'no Downloads folder found'; return }
-  Invoke-PersonalPicker -Rows @(Get-LargeStaleFiles) -Prompt 'Move the selected files to the Recycle Bin'
+  Invoke-PersonalPicker -Rows @(Get-LargeStaleFiles) -Prompt 'Move the selected files to the Recycle Bin' -Section 19
 }
 
 function Show-PersonalScan {

package/modules/pkg_managers.ps1

@@ -37,6 +37,10 @@ function Get-Targets01 {
     (New-Target 1 'electron-builder cache' "$($P.L)\electron-builder\Cache" -Mode prune -Dev $true)
     (New-Target 1 'node-gyp headers cache' "$($P.L)\node-gyp\Cache" -Mode prune -Dev $true)
     (New-Target 1 'Scoop installer cache' "$($P.U)\scoop\cache" -Mode prune -Dev $true)
+    # Hugging Face keeps revisions as snapshots\<rev> linking into blobs, so removing a whole snapshot orphans
+    # blobs: this prunes by the idle gate instead of keeping "the newest per model". AI agent state under
+    # ~\.cache (claude, codex, gemini, copilot) stays protected by lib/safety.ps1.
+    (New-Target 1 'Hugging Face model cache' "$($P.U)\.cache\huggingface\hub" -Mode prune -Dev $true -Note 'models are re-downloaded on next use; the idle gate keeps recent ones')
   )
 }
 

package/modules/projects.ps1

@@ -1,6 +1,10 @@
 # projects.ps1 - section 17: stale build artefacts in projects nobody has touched for N+ days. Interactive only.
 
-$Script:WS_ARTEFACT_DIRS = @('node_modules', 'dist', 'build', 'out', '.next', '.nuxt', '.turbo', '.vite', '.svelte-kit', '.astro', '.parcel-cache', 'target', 'vendor', 'coverage', '.nyc_output', '__pycache__', '.pytest_cache', '.dart_tool', '.angular')
+$Script:WS_ARTEFACT_DIRS = @('node_modules', 'dist', 'build', 'out', '.next', '.nuxt', '.turbo', '.vite', '.svelte-kit', '.astro', '.parcel-cache', 'target', 'vendor', 'coverage', '.nyc_output', '__pycache__', '.pytest_cache', '.dart_tool', '.angular', '.nx', '.mypy_cache', '.ruff_cache', '.tox', '.eggs', '.output', '.serverless')
+# Never here: .venv / venv (nobody expects an environment to vanish) and .terraform (provider binaries + lock state).
+# A name in this table is an artefact ONLY when the same folder carries one of the listed markers: a bare
+# .cache belongs to whoever made it, but beside a Gatsby or Parcel config it is a build cache.
+$Script:WS_ARTEFACT_DIRS_MARKED = @{ '.cache' = @('gatsby-config.js', 'gatsby-config.ts', 'gatsby-config.mjs', '.parcelrc', 'parcel.config.js') }
 $Script:WS_PROJECT_MARKERS = @('package.json', 'pubspec.yaml', 'composer.json', 'Cargo.toml', 'go.mod', 'build.gradle', 'build.gradle.kts', 'pom.xml', 'pyproject.toml', 'requirements.txt', 'angular.json', 'next.config.js', 'next.config.mjs', 'nuxt.config.ts', 'vite.config.ts', 'vite.config.js')
 $Script:WS_NEVER_ENTER = @('.git', 'AppData', 'node_modules', '$RECYCLE.BIN', 'System Volume Information', '.gradle', '.m2', '.nuget', '.cargo', '.vscode', '.idea')
 
@@ -37,6 +41,15 @@ function Get-Targets17 {
   return $t
 }
 
+function Test-MarkedArtefactDir {
+  <# .SYNOPSIS True when Name is a marker-gated artefact folder AND Dir carries one of its markers. #>
+  param([string] $Dir, [string] $Name)
+  if (-not $Script:WS_ARTEFACT_DIRS_MARKED.ContainsKey($Name)) { return $false }
+  $names = @(Get-ChildEntries $Dir | ForEach-Object { $_.Name })
+  foreach ($m in $Script:WS_ARTEFACT_DIRS_MARKED[$Name]) { if ($names -contains $m) { return $true } }
+  return $false
+}
+
 function Test-ProjectMarker {
   param([string] $Dir, [string] $ArtefactName)
   $entries = Get-ChildEntries $Dir
@@ -59,7 +72,7 @@ function Get-ProjectActivityDays {
       $seen++
       if (Test-ReparsePoint $e) { continue }
       if ($e -is [IO.DirectoryInfo]) {
-        if ($Script:WS_ARTEFACT_DIRS -contains $e.Name -or $Script:WS_NEVER_ENTER -contains $e.Name) { continue }
+        if ($Script:WS_ARTEFACT_DIRS -contains $e.Name -or $Script:WS_NEVER_ENTER -contains $e.Name -or (Test-MarkedArtefactDir -Dir $dir -Name $e.Name)) { continue }
         $stack.Push((Remove-LongPrefix $e.FullName)); continue
       }
       $t = Get-NewestTimestampUtc $e
@@ -88,7 +101,7 @@ function Find-StaleArtefacts {
         $skip = $false
         foreach ($x in $ws.ExcludePaths) { if ($x -and (Test-PathWithin -Path $full -Within $x)) { $skip = $true; break } }
         if ($skip) { continue }
-        if ($Script:WS_ARTEFACT_DIRS -contains $e.Name -or ($e.Name -in 'bin', 'obj')) {
+        if ($Script:WS_ARTEFACT_DIRS -contains $e.Name -or ($e.Name -in 'bin', 'obj') -or (Test-MarkedArtefactDir -Dir $dir -Name $e.Name)) {
           if (-not (Test-ProjectMarker -Dir $dir -ArtefactName $e.Name)) { continue }
           if (-not $projectAge.ContainsKey($dir)) { $projectAge[$dir] = Get-ProjectActivityDays $dir }
           $age = $projectAge[$dir]
@@ -116,24 +129,31 @@ function Invoke-Section17 {
   $found = @(Find-StaleArtefacts -Roots $roots -Days $ws.Days)
   if ($found.Count -eq 0) { Write-Info "no build artefacts in projects idle $($ws.Days)+ days"; return }
   $reportLines = @("stale build artefacts - projects idle $($ws.Days)+ days - $(Get-Date -Format 'yyyy-MM-dd HH:mm')", '')
+  # One offered list drives the table, the JSON candidates and the selection indexes: they cannot disagree.
+  $offered = @($found | Select-Object -First 200)
+  if ($found.Count -gt $offered.Count) { Write-Warn 'list truncated to 200 entries' }
   Write-UiLine ("  {0,3}  {1,10} {2,6}  {3}" -f '#', 'SIZE', 'IDLE', 'ARTEFACT') 'White'
   $i = 1; $total = [long]0
-  foreach ($f in $found) {
+  foreach ($f in $offered) {
     Write-UiLine ("  {0,3}  {1,10} {2,5}d  {3}" -f $i, (Format-Bytes $f.Bytes), $f.Age, $f.Path) 'Gray'
     $reportLines += ("{0,10} {1,5}d  {2}" -f (Format-Bytes $f.Bytes), $f.Age, $f.Path)
+    Add-JsonCandidate -Section 17 -Index $i -Path $f.Path -Bytes $f.Bytes -IdleDays $f.Age -Project $f.Project
     $total += $f.Bytes; $i++
-    if ($i -gt 200) { Write-Warn 'list truncated to 200 entries'; break }
   }
   Write-Info ("total: " + (Format-Bytes $total))
   if (-not $ws.NoReport) {
     $out = Join-Path $ws.ReportsDir ('stale-builds-' + $ws.Stamp + '.txt')
     try { [IO.File]::WriteAllLines($out, $reportLines); Write-Note "list saved: $out" } catch { $null = $_ }
   }
-  $picks = Read-MultiSelect -Total ([math]::Min($found.Count, 200))
+  $picks = @(Read-MultiSelect -Total $offered.Count -NoAutoYes -Candidates @($offered | ForEach-Object { $_.Path }))
   if ($picks.Count -eq 0) { Write-Info 'nothing selected'; return }
-  if (-not (Confirm-Section "Remove $($picks.Count) artefact folder(s)? (rebuild with the project's install/build command)" 'n')) { Write-Info 'skipped'; return }
+  if (-not $ws.DryRun) {
+    # Project artefacts never auto-confirm: --yes does not apply, and the walkthrough's step answer is not a selection.
+    # An explicit --select / --select-file choice does answer it - that is a person choosing, in advance.
+    if (-not (Confirm-Ui -Prompt "Remove $($picks.Count) artefact folder(s)? (rebuild with the project's install/build command)" -Default 'n' -NoAutoYes -ScriptedOk)) { Write-Info 'skipped'; return }
+  }
   foreach ($k in $picks) {
-    $f = $found[$k - 1]
+    $f = $offered[$k - 1]
     $r = Remove-PathSafe -Path $f.Path -Within $f.Root -Label (Split-Path -Leaf $f.Path)
     if ($r.Removed -and -not $ws.DryRun) { Write-Ok ("removed " + (Format-Bytes $r.Bytes) + "  $($f.Path)") }
   }

package/modules/release_helpers.ps1

@@ -18,6 +18,9 @@ function Show-Version {
 }
 
 function Show-SectionList {
+  # --list --json prints the catalogue and nothing else: the human table below uses Write-Host, which would
+  # break the one-line-on-stdout promise.
+  if ($Script:WS.JsonMode) { [Console]::Out.WriteLine(((Get-CatalogueJson) | ConvertTo-Json -Depth 6 -Compress)); return }
   Write-Host ''
   Write-Host ("  {0,3}  {1,-84} {2,-10} {3,-5} {4}" -f '#', 'SECTION', 'TIER', 'ADMIN', 'BATCH')
   foreach ($s in $Script:WS_SECTIONS) {
@@ -241,6 +244,12 @@ function Invoke-SelfTest {
     try { $probe = Join-Path $d ('.write-test-' + [guid]::NewGuid().ToString('N')); Set-Content -LiteralPath $probe -Value 'x'; Remove-Item -LiteralPath $probe -Force; Write-Ok "$d writable" } catch { Write-Err "$d not writable"; $fails++ }
   }
 
+  if (Get-Command Invoke-SelfTestExtra -ErrorAction SilentlyContinue) {
+    $extra = Invoke-SelfTestExtra
+    $checks += [int]$extra.Checks
+    $fails += [int]$extra.Fails
+  }
+
   Write-Separator
   if ($fails -eq 0) { Write-Ok "all $checks checks passed - $Script:WS_NAME is ready"; return $Script:WS_EXIT_OK }
   Write-Err "$fails of $checks checks FAILED"
@@ -317,11 +326,25 @@ function Get-LaunchCommand {
   return [pscustomobject]@{ Exe = "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe"; Args = @('-NoProfile', '-NoLogo', '-ExecutionPolicy', 'Bypass', '-File', "`"$($ws.ScriptPath)`"") }
 }
 
+function Test-NpxInstallerRefusal {
+  <# .SYNOPSIS Under npx the package lives in a cache npm evicts; a task or alias pointing there would break later. #>
+  param([string] $Flag)
+  if (-not $Script:WS.Npx) { return $false }
+  Write-Err "$Flag is refused under npx: it would point at the npx cache, which npm evicts."
+  Write-Plain '  Install once, then register from the global command:'
+  Write-Plain '    npm install -g windowsweep'
+  Write-Plain "    windowsweep $Flag"
+  $Script:WS.ExitCode = $Script:WS_EXIT_REFUSED
+  return $true
+}
+
 function Install-WeeklyTask {
   Write-Box 'Install weekly Scheduled Task' "$Script:WS_TASK_NAME - Sundays 03:00, safe batch, no prompts"
+  if (Test-NpxInstallerRefusal '--install-task') { return }
   if (Get-ScheduledTask -TaskName $Script:WS_TASK_NAME -ErrorAction SilentlyContinue) { Write-Info 'task already exists'; return }
   $lc = Get-LaunchCommand
-  $argLine = (@($lc.Args) + @('--all', '--yes', '--quiet', '--no-color')) -join ' '
+  # --notify is part of the task action: an unattended Sunday run that says nothing is a run nobody sees.
+  $argLine = (@($lc.Args) + @('--all', '--yes', '--quiet', '--no-color', '--notify')) -join ' '
   Write-Info "action: $($lc.Exe) $argLine"
   if ($Script:WS.DryRun) { Write-DryRun 'would register the task'; return }
   if (-not (Confirm-Ui -Prompt 'Register this task for your user account?' -Default 'y')) { Write-Info 'skipped'; return }
@@ -347,6 +370,7 @@ $Script:WS_ALIAS_MARK = '# windowsweep alias'
 
 function Install-ProfileAlias {
   Write-Box 'Install profile alias' "Adds a 'cleanup' function to your PowerShell profile"
+  if (Test-NpxInstallerRefusal '--install-alias') { return }
   $profilePath = $PROFILE.CurrentUserAllHosts
   $lc = Get-LaunchCommand
   $line = "function cleanup { & `"$($lc.Exe)`" $($lc.Args -join ' ') @args }"
@@ -388,7 +412,7 @@ function Remove-ToolData {
   $bytes = Get-DirectoryBytes $ws.Home
   Write-Info ("$($ws.Home) holds " + (Format-Bytes $bytes) + ' of logs, reports, bundles and config')
   if ($ws.DryRun) { Write-DryRun "would remove $($ws.Home)"; return }
-  if (-not (Confirm-Ui -Prompt 'Delete it all (logs, reports, your developer answer)?' -Default 'n')) { Write-Info 'skipped'; return }
+  if (-not (Confirm-Ui -Prompt 'Delete it all (logs, reports, your developer answer)?' -Default 'n' -NoAutoYes)) { Write-Info 'skipped'; return }
   $ws.LogFile = $null
   try { [IO.Directory]::Delete((Get-LongPath $ws.Home), $true); Write-Ok 'removed' } catch { Write-Err "could not remove: $($_.Exception.Message)" }
 }

package/modules/runner.ps1

@@ -42,6 +42,29 @@ function Get-RequestedSections {
   return @($ids | Sort-Object -Unique)
 }
 
+function Get-MachineProgressLine {
+  <# .SYNOPSIS The progress-line format a --json caller parses. Kept pure so the self-test can round-trip it. #>
+  param([int] $Section, [string] $Stage, [string] $Status = '', [long] $Freed = 0)
+  $line = "##$Script:WS_NAME section=$Section event=$Stage"
+  if ($Stage -eq 'end') { $line += " status=$Status freed_bytes=$Freed" }
+  return $line
+}
+
+function Write-MachineProgress {
+  <# .SYNOPSIS One machine-readable progress line on stderr, --json mode only, so a GUI need not parse the log.
+     Never on stdout: --json promises exactly one stdout line. #>
+  param([int] $Section, [string] $Stage, [string] $Status = '', [long] $Freed = 0)
+  if (-not $Script:WS.JsonMode) { return }
+  [Console]::Error.WriteLine((Get-MachineProgressLine -Section $Section -Stage $Stage -Status $Status -Freed $Freed))
+}
+
+function Add-JsonCandidate {
+  <# .SYNOPSIS Record one item an interactive section offered, so --json callers can present the same list. #>
+  param([int] $Section, [int] $Index, [string] $Path, [long] $Bytes, [int] $IdleDays, [string] $Project = '')
+  if (-not $Script:WS.JsonMode) { return }
+  $Script:WS.Candidates += [ordered]@{ section = $Section; index = $Index; path = $Path; bytes = $Bytes; idle_days = $IdleDays; project = $Project }
+}
+
 function Invoke-SectionById {
   <# .SYNOPSIS Run one section under the batch, admin and developer policies; records the report step. #>
   param([int] $Id)
@@ -50,18 +73,24 @@ function Invoke-SectionById {
   if (-not $sec) { Write-Warn "no section $Id"; return }
   $title = "[{0:00}] {1}" -f $sec.Id, $sec.Title
   Write-Box $title
+  Write-MachineProgress -Section $Id -Stage 'start'
   # Batch policy: deep and interactive-only sections never run unattended without an explicit opt-in.
   if ($ws.BatchMode -and -not $ws.DryRun) {
-    if ($sec.Batch -eq 'interactive') {
-      Write-Warn "section $Id is interactive-only: it needs a person at the keyboard. Run it from the walkthrough or the menu."
+    if ($sec.Batch -eq 'interactive' -and -not $ws.SelectActive) {
+      Write-Warn "section $Id is interactive-only: it needs a person at the keyboard, or a selection passed with --select / --select-file."
       $ws.Refusals += "section $Id (interactive-only)"
       Add-ReportStep -Section $Id -Title $sec.Title -Status 'refused' -Note 'interactive-only section in batch mode'
+      Write-MachineProgress -Section $Id -Stage 'end' -Status 'refused'
       return
     }
+    if ($sec.Batch -eq 'interactive') {
+      Write-Note "section $Id runs unattended because a selection was supplied (--select / --select-file): a person chose these."
+    }
     if ($sec.Batch -eq 'deep' -and -not $ws.Deep) {
       Write-Warn "section $Id is deep (irreversible or system-changing): refused in batch mode without --i-understand-deep."
       $ws.Refusals += "section $Id (deep, add --i-understand-deep)"
       Add-ReportStep -Section $Id -Title $sec.Title -Status 'refused' -Note 'deep section without --i-understand-deep'
+      Write-MachineProgress -Section $Id -Stage 'end' -Status 'refused'
       return
     }
   }
@@ -70,11 +99,13 @@ function Invoke-SectionById {
     Write-Note "run it elevated:  windowsweep --only $Id --yes --elevate"
     $ws.Hints += "Admin section $Id skipped: windowsweep --only $Id --yes --elevate"
     Add-ReportStep -Section $Id -Title $sec.Title -Status 'skipped' -Note 'needs Administrator'
+    Write-MachineProgress -Section $Id -Stage 'end' -Status 'skipped'
     return
   }
   if ($sec.Dev -and $ws.Developer -eq $false -and $Id -in @(4, 17, 20)) {
     Write-Info "developer mode is off - section $Id (developer-only data) skipped."
     Add-ReportStep -Section $Id -Title $sec.Title -Status 'skipped' -Note 'developer mode off'
+    Write-MachineProgress -Section $Id -Stage 'end' -Status 'skipped'
     return
   }
   $ws.SectionFreed = [long]0
@@ -86,7 +117,7 @@ function Invoke-SectionById {
   } catch {
     $status = 'failed'
     Write-Err "section $Id failed: $($_.Exception.Message)"
-    Write-Log ("section $Id error: " + $_.ScriptStackTrace)
+    Write-LogLine ("section $Id error: " + $_.ScriptStackTrace)
     $ws.ExitCode = $Script:WS_EXIT_FAIL
   }
   $after = Get-SystemDriveFree
@@ -101,6 +132,7 @@ function Invoke-SectionById {
     Write-Note 'no measurable change in this section'
   }
   Add-ReportStep -Section $Id -Title $sec.Title -Status $status -Freed $freed
+  Write-MachineProgress -Section $Id -Stage 'end' -Status $status -Freed $freed
 }
 
 function Invoke-BatchMode {
@@ -173,18 +205,35 @@ function Show-SessionSummary {
   }
   Write-UiLine '' 'Gray'
   Write-Note "$Script:WS_NAME v$(Get-ToolVersion) by $Script:WS_AUTHOR - $Script:WS_REPO"
+  Send-RunNotification
   if ($ws.JsonMode) { Write-JsonSummary }
 }
 
-function Write-JsonSummary {
-  <# .SYNOPSIS --json: the only line written to stdout. #>
+function Get-JsonSummary {
+  <# .SYNOPSIS The --json document (ordered), kept apart from the printer so the self-test can parse it. #>
   $ws = $Script:WS
-  $doc = [ordered]@{
+  return [ordered]@{
     tool = $Script:WS_NAME; version = (Get-ToolVersion); mode = $ws.Mode; dry_run = [bool]$ws.DryRun
     elevated = [bool]$ws.IsAdmin; developer = $ws.Developer
     freed_bytes = [long]$ws.TotalFreed; estimated_bytes = [long]$ws.TotalEstimated
     sections = @($ws.Report.steps | ForEach-Object { [ordered]@{ section = $_.section; status = $_.status; freed_bytes = $_.freed_bytes } })
+    # candidates and targets are ALWAYS present, empty when nothing was collected: a caller can rely on the shape.
+    candidates = @($ws.Candidates); targets = @($ws.ScanTargets)
     refusals = @($ws.Refusals); log_file = $ws.LogFile; report_file = $ws.ReportFile
   }
-  [Console]::Out.WriteLine(($doc | ConvertTo-Json -Depth 5 -Compress))
+}
+
+function Get-CatalogueJson {
+  <# .SYNOPSIS --list --json: the section catalogue, so a front end reads it instead of hard-coding it. #>
+  return [ordered]@{
+    tool = $Script:WS_NAME; version = (Get-ToolVersion)
+    sections = @($Script:WS_SECTIONS | ForEach-Object { [ordered]@{ id = $_.Id; key = $_.Key; title = $_.Title; tier = $_.Tier; admin = [bool]$_.Admin; batch = $_.Batch; dev = [bool]$_.Dev } })
+    safe_batch = @($Script:WS_SAFE_BATCH); safe_batch_admin = @($Script:WS_SAFE_BATCH_ADMIN)
+    profiles = ([ordered]@{} + $Script:WS_PROFILES); walkthrough = @($Script:WS_WALKTHROUGH); walkthrough_admin = @($Script:WS_WALKTHROUGH_ADMIN)
+  }
+}
+
+function Write-JsonSummary {
+  <# .SYNOPSIS --json: the only line written to stdout. #>
+  [Console]::Out.WriteLine(((Get-JsonSummary) | ConvertTo-Json -Depth 5 -Compress))
 }