windowsweep 1.4.0 → 1.4.2

package/AI-INTEGRATION-GUIDE.md

@@ -133,7 +133,7 @@ answered by a script, so `--elevate` does not belong in an unattended context.
 - - **Protected paths are refused regardless of flags**: every drive root, fifteen declared roots (Windows, System32, SysWOW64, both Program Files folders, ProgramData, `C:\Users` with Default and Public, the profile root, and the AppData Roaming, Local and LocalLow folders), 66 protected subtrees, 50 path patterns and 13 file names. Two paths are declared exceptions - `%LOCALAPPDATA%\Android\Sdk\.temp` and `.downloadIntermediates` - and there are no others. No flag bypasses any of it.
 - **Junctions and symlinks are removed as links, never followed.**
 - **`--dry-run` and `--scan` write nothing** but the log and the report.
-- **Section numbers are a public contract.** 0-29 in the 1.4.0 source; a section may be retired as a no-op, and a number is
+- **Section numbers are a public contract.** 0-29 in the current source; a section may be retired as a no-op, and a number is
   never reused. Read `--list --json` rather than hard-coding the set.
 - **Zero runtime dependencies.** The package is PowerShell plus a Node launcher that uses only built-in
   modules.

package/CHANGELOG.md

@@ -9,6 +9,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.4.2] - 2026-11-05
+
+### Added
+
+- **Desktop tours.** Each main screen has **Tour this page** in the header. Its steps name the controls on that
+  screen, skip any that are hidden in your current state, and close before a run starts. **Walk through
+  windowsweep** shows the path from scan to report in seven screens captured from 1.4.1. Neither starts a
+  cleanup or spends a real-run claim.
+
+### Changed
+
+- **The desktop app installs its updates.** When the update check finds a newer build, the app downloads it in the
+  background and installs it when you close the window, so the next start is the new version. **Install and
+  restart** still installs at once. A run in progress is never interrupted for an update.
+- **An elevated run's log reaches the window as it is written.** The app watches the run folder instead of
+  re-reading it every 0.7 seconds.
+
+### Fixed
+
+- **Release notices follow the newest record.** A notice the app stored no longer outranks a newer, lower release
+  record, so a corrected release takes effect on the next check, and a record at or below the running version
+  clears the notice.
+- The command-line tool is unchanged in this release. It moves to 1.4.2 so the CLI and the desktop app stay on one
+  version.
+
+## [1.4.1] - 2026-11-03
+
+### Fixed
+
+- The desktop app now reads published release records on start, resume and reconnect. An urgent release blocks an older build immediately; a normal release is announced immediately and required from the next start. Its Update button uses the signed updater.
+- Removed the desktop updater's six-hour network timer. Release broadcasts and lifecycle events trigger the checks.
+- Corrected the package's release notes and documentation for section 19's Recycle Bin rule and section 26's permanent uninstall action.
+
+## [1.4.0] - 2026-11-03
+
 ### Added
 
 - **Section 26 - uninstall the programs you pick.** It lists the installed programs - never Windows parts,
@@ -46,7 +81,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
   any age) or old (untouched for `--days`, at any size) - each file once, with its reason, age and the timestamps
   that age came from. A folder is refused as a root when it is a drive root, your profile folder, inside Windows,
   Program Files, ProgramData or AppData, a link, or protected. Removal stays yours: exact files only, never by
-  `--yes`, the Recycle Bin by default - and a file that changed after the list was made, or is now reached through a
+  `--yes`, always the Recycle Bin - and a file that changed after the list was made, or is now reached through a
   link, is refused. File names and paths stay on your machine. `--json` candidates for section 19 add `reason`
   (`large`/`old`/`both`), `age_basis` (`write` or `write+access`), `modified`, `root` and `selectable` (with
   `skip_reason` and `index` 0 for a file that cannot be picked); the summary adds `personal_roots`.

package/README.md

@@ -18,10 +18,11 @@
 
 > [!IMPORTANT]
 > **This tool deletes files.** Most of what it removes are caches that rebuild themselves; personal files it
-> lists go to the Recycle Bin; and two sections - emptying the Recycle Bin, clearing event logs - are
-> permanent, with no undo of any kind. Those two sit behind `--i-understand-deep`, along with the hibernation
+> lists go to the Recycle Bin; emptying the Recycle Bin and clearing event logs have no undo. Those two sit
+> behind `--i-understand-deep`, along with the hibernation
 > file and disk-image compaction. Start with `npx windowsweep --scan`, which deletes nothing, then
 > `npx windowsweep --dry-run --all --yes`, which shows exactly what a real run would remove.
+> Uninstalling a program you select in section 26 is permanent too.
 > **Windows only** - npm refuses to install it elsewhere.
 
 What it reclaims is the disk space that quietly disappears on a Windows machine: package-manager and build caches,
@@ -35,14 +36,14 @@ It is the Windows member of a family with [linux-cleanup](https://github.com/aon
 
 | | |
 |---|---|
-| **Version** | `1.4.0` |
+| **Version** | `1.4.2` |
 | **License** | MIT |
 | **Node** | `>=14` (launcher only) |
 | **Runtime** | Windows PowerShell 5.1 (built in) or PowerShell 7 |
 | **Platforms** | Windows 10 (1809+) and Windows 11 |
 | **Install size** | ~167 kB packed · ~560 kB unpacked · 53 files · no dependencies |
 | **Undo** | Recycle Bin for personal files; none for caches (they regenerate) |
-| **Status** | Stable · 1.4.0, released 2026-11-03 |
+| **Status** | Stable · 1.4.2, released 2026-11-05 |
 
 <a id="table-of-contents"></a>
 ## 🧭 Table of Contents&nbsp;[#](#table-of-contents)
@@ -201,7 +202,7 @@ section with `a` run / `s` skip / `q` quit and a running total.
 
 ### The sections
 
-This table describes version 1.4.0.
+This table describes version 1.4.2.
 
 **Tier** says what happens to the data: *report* deletes nothing, *rebuilds* comes back on its own, *slow*
 comes back but costs minutes, *Recycle Bin* is recoverable until you empty it (`--list` shows this tier as
@@ -458,8 +459,10 @@ More: [FAQ](https://windowsweep-docs.aoneahsan.com/faq).
 <a id="changelog"></a>
 ## 🔄 Changelog&nbsp;[#](#changelog)
 
-Latest release: **`1.4.0`** - scan Downloads and folders you add for large or old files, then choose individual
-files for the Recycle Bin. The new uninstall and leftover-folder sections also require explicit selection.
+Latest release: **`1.4.2`** - the desktop app adds page tours and a seven-step walkthrough, and installs a
+found update when you close it. The 1.4 scanner searches Downloads and folders you add for large or old files;
+you choose individual files for the Recycle Bin. The uninstall and leftover-folder sections require explicit
+selection.
 Full history: [CHANGELOG.md](https://github.com/aoneahsan/windowsweep/blob/main/CHANGELOG.md).
 
 <a id="contributing"></a>

package/VERSION

@@ -1 +1 @@
-1.4.0
+1.4.2

package/lib/actions.ps1

@@ -107,7 +107,7 @@ function Test-KnownCacheLeaf {
 }
 
 function Add-CacheLeafExceptions {
-  <# .SYNOPSIS D79 (1.4.0): lift the protected lists (lib/safety.ps1) for EXACTLY these folders, each of which must
+  <# .SYNOPSIS D79 (P9): lift the protected lists (lib/safety.ps1) for EXACTLY these folders, each of which must
      carry a declared cache folder's name - never a profile, an app root or a protected root. Returns the count. #>
   param([string[]] $Paths)
   $pr = $Script:WS_PROTECT; $n = 0

package/lib/constants.ps1

@@ -4,7 +4,7 @@
 # Single source of truth for the version is package.json: the Node launcher exports it as
 # WINDOWSWEEP_VERSION. A direct checkout falls back to this literal; the version:check script
 # asserts the two never drift.
-$Script:WS_VERSION_FALLBACK = '1.4.0'
+$Script:WS_VERSION_FALLBACK = '1.4.2'
 
 $Script:WS_NAME = 'windowsweep'
 $Script:WS_TAGLINE = 'Windows cleanup CLI: dry-run first, personal files chosen row by row, zero install via npx.'

package/lib/fs.ps1

@@ -233,7 +233,7 @@ function Get-DirectoryBytes {
 function Get-IdleDays {
   <# .SYNOPSIS Days since the path (or anything inside it) was last touched. 999999 when absent.
      Last-access counts unless Test-LastAccessLive found it carries no signal here (D82). #>
-  # -WriteOnly (1.4.0): write/creation time only - for declared scratch roots, where a scanner's partial read
+  # -WriteOnly (P9): write/creation time only - for declared scratch roots, where a scanner's partial read
   # (67-85% of a month-old test profile's files on the P52, 2026-11-03) must not count as use.
   param([string] $Path, [switch] $WriteOnly)
   $info = Get-ItemInfo $Path

package/lib/safety.ps1

@@ -26,7 +26,7 @@ function Initialize-Safety {
 
   $exact = New-Object System.Collections.Generic.HashSet[string]([StringComparer]::OrdinalIgnoreCase)
   foreach ($d in [IO.DriveInfo]::GetDrives()) { $null = $exact.Add($d.Name.TrimEnd('\')); $null = $exact.Add($d.Name) }
-  # 1.4.0: the Common Files and ProgramData\Microsoft roots - section 26 reads InstallLocation from the registry,
+  # P9: the Common Files and ProgramData\Microsoft roots - section 26 reads InstallLocation from the registry,
   # and an installer that registered one of these as its own folder must never get it offered as a leftover.
   foreach ($p in @($SR, "$SR\System32", "$SR\SysWOW64", $PF, $PF86, $PD, "$SD\Users", "$SD\Users\Default", "$SD\Users\Public", $env:PUBLIC, $U, "$U\AppData", $A, $L, $LL,
       "$PF\Common Files", "$PF86\Common Files", "$PD\Microsoft")) {

package/modules/android_avd.ps1

@@ -1,5 +1,5 @@
 # android_avd.ps1 - section 4: Android emulators (AVDs) and what they leave. Slow to recreate, so a per-AVD idle
-# gate and never in --all. 1.4.0: every AVD root (also ANDROID_AVD_HOME), pointer .ini files whose AVD is gone
+# gate and never in --all. P9: every AVD root (also ANDROID_AVD_HOME), pointer .ini files whose AVD is gone
 # (the P52's pointed into a drive that no longer existed, 2026-11-02) and system images no remaining AVD uses -
 # removed with the SDK's own sdkmanager, the emulator too once no AVD is left. ASCII only.
 

package/modules/browsers.ps1

@@ -1,5 +1,5 @@
 # browsers.ps1 - section 7: browser caches for every profile. Profile data is never touched.
-# 1.4.0: --browser-profile-roots / browserProfileRoots name folders that hold Chromium user-data directories of
+# P9: --browser-profile-roots / browserProfileRoots name folders that hold Chromium user-data directories of
 # their own - automation and test profiles (the P52 kept 2.0 GB of cache in ~\.local\share\ahsan-automation\profiles,
 # 2026-11-02). Only the declared cache folders inside them are cleared (D79), and a profile a running browser
 # holds through --user-data-dir is skipped. ASCII only.

package/modules/data_scanner.ps1

@@ -1,4 +1,4 @@
-# data_scanner.ps1 - section 19 (1.4.0 data scanner): large or old personal files. Downloads by default; folders a
+# data_scanner.ps1 - section 19 (P9 data scanner): large or old personal files. Downloads by default; folders a
 # person adds with --personal-roots / personalRoots (owner, 2026-11-03). Discovery is read-only and lists each file
 # once with its reason (large: >= --large-file-mb at any age; old: idle --days at any size; both), its age and the
 # timestamps that age came from (D82). Removal stays interactive: exact paths only, never by --yes, Recycle Bin by

package/modules/installed_programs.ps1

@@ -59,7 +59,7 @@ function ConvertFrom-PrefetchName {
 }
 
 function Get-PrefetchLastRun {
-  <# .SYNOPSIS 1.4.0: program file name -> newest run (UTC) from Windows\Prefetch, which Windows rewrites on every
+  <# .SYNOPSIS P9: program file name -> newest run (UTC) from Windows\Prefetch, which Windows rewrites on every
      run. Readable only when elevated; empty otherwise or when prefetch is off. #>
   $map = @{}
   if (-not $Script:WS.IsAdmin) { return $map }

package/modules/orphaned_appdata.ps1

@@ -78,7 +78,7 @@ function Get-InstalledProgramRows {
         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
-        # Section 26 (1.4.0) reads these; sections 23 and 24 ignore them.
+        # Section 26 (P9) reads these; sections 23 and 24 ignore them.
         KeyPath = [string]$k.Name; KeyName = [string]$k.PSChildName; Machine = ([string]$k.Name).StartsWith('HKEY_LOCAL_MACHINE', [StringComparison]::OrdinalIgnoreCase)
         QuietUninstallString = [string]$props.QuietUninstallString; WindowsInstaller = [int]0 + $props.WindowsInstaller
         ParentKeyName = [string]$props.ParentKeyName; ReleaseType = [string]$props.ReleaseType
@@ -91,7 +91,7 @@ function Get-InstalledProgramRows {
 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. #>
-  # -IgnorePaths (1.4.0, sections 26 and 27): folders being judged as leftovers, whose own names must not
+  # -IgnorePaths (P9, sections 26 and 27): folders being judged as leftovers, whose own names must not
   # count as a claim on themselves.
   param([string[]] $IgnorePaths = @())
   $P = $Script:P

package/modules/runner.ps1

@@ -64,9 +64,9 @@ function Add-JsonCandidate {
     [System.Collections.IDictionary] $Extra = $null)
   if (-not $Script:WS.JsonMode) { return }
   $c = [ordered]@{ section = $Section; index = $Index; path = $Path; bytes = $Bytes; idle_days = $IdleDays; project = $Project }
-  # 1.4.0: an optional display name - section 26's candidates are programs whose path is a registry key.
+  # P9: an optional display name - section 26's candidates are programs whose path is a registry key.
   if ($Label) { $c.label = $Label }
-  # 1.4.0: section-specific fields added after the shared ones (section 19's data scanner: reason, age basis, ...).
+  # P9: section-specific fields added after the shared ones (section 19's data scanner: reason, age basis, ...).
   if ($null -ne $Extra) { foreach ($k in $Extra.Keys) { $c[$k] = $Extra[$k] } }
   $Script:WS.Candidates += $c
 }
@@ -234,7 +234,7 @@ function Get-JsonSummary {
     refusals = @($ws.Refusals); excluded = @($ws.Excluded)
     # D82: the volumes where idle age used write/creation time because last-access was found live.
     access_live_volumes = @(Get-AccessLiveVolumes)
-    # 1.4.0: the folders section 19 scanned or refused ({path, accepted, reason}); empty unless it ran.
+    # P9: the folders section 19 scanned or refused ({path, accepted, reason}); empty unless it ran.
     personal_roots = @($ws.PersonalRootsReport)
     log_file = $ws.LogFile; report_file = $ws.ReportFile
   }

package/modules/self_test_1_4.ps1

@@ -1,4 +1,4 @@
-# self_test_1_4.ps1 - self-test group [19]: the 1.4.0 behaviour found on a real machine (P9, 2026-11-02).
+# self_test_1_4.ps1 - self-test group [19]: the P9 behaviour found on a real machine (P9, 2026-11-02).
 # Called by Invoke-SelfTestExtra with its fixture root; verdict lines only. ASCII only.
 
 function New-AgedFiles {
@@ -24,7 +24,7 @@ function Invoke-SelfTest14 {
   $root = Join-Path $Fixture 'g19'
   Reset-AccessVerdicts
   try {
-    Write-Section '[19] 1.4.0: idle basis when last-access is live (D82), one-line --json, orphan claims'
+    Write-Section '[19] P9: idle basis when last-access is live (D82), one-line --json, orphan claims'
 
     # 19a - the verdict rule itself
     $checks++
@@ -123,7 +123,7 @@ function Invoke-SelfTest21 {
   $savedDry = $ws.DryRun
   $key = 'HKCU:\Software\windowsweep-selftest-' + [guid]::NewGuid().ToString('N')
   try {
-    Write-Section '[21] 1.4.0: the Chrome on-device AI policy (section 29)'
+    Write-Section '[21] P9: the Chrome on-device AI policy (section 29)'
     # 21a - a dry-run prints the change and writes nothing
     $checks++
     $ws.DryRun = $true
@@ -156,7 +156,7 @@ function Invoke-SelfTest20 {
   $root = Join-Path $Fixture 'g20'
   $savedExclude = $Script:WS_EXCLUDE
   try {
-    Write-Section '[20] 1.4.0: superseded releases (section 28) and narrow exceptions (D79)'
+    Write-Section '[20] P9: superseded releases (section 28) and narrow exceptions (D79)'
     $rel = Join-Path $root 'codex\releases'
     foreach ($v in '0.1.0-x86_64-pc-windows-msvc', '0.2.0-x86_64-pc-windows-msvc', '0.3.0-x86_64-pc-windows-msvc', '0.4.0-x86_64-pc-windows-msvc', 'notes') { New-Item -ItemType Directory -Force -Path (Join-Path $rel $v) | Out-Null }
     $link = Join-Path $root 'codex\current'

package/modules/self_test_1_4b.ps1

@@ -1,4 +1,4 @@
-# self_test_1_4b.ps1 - self-test groups [22]-[23] for 1.4.0: uninstall programs (section 26) and the leftover
+# self_test_1_4b.ps1 - self-test groups [22]-[23] for P9: uninstall programs (section 26) and the leftover
 # finder (sections 26 and 27). Fixtures and pure logic only; nothing is uninstalled or recycled. ASCII only.
 
 function New-ProgramRow {
@@ -26,7 +26,7 @@ function Invoke-SelfTest22 {
   $root = Join-Path $Fixture 'g22'
   $saved = @{ Queue = $ws.SelectQueue; Paths = $ws.SelectPaths; Interactive = $ws.Interactive; DryRun = $ws.DryRun }
   try {
-    Write-Section '[22] 1.4.0: uninstall programs (section 26) and the folders they leave'
+    Write-Section '[22] P9: uninstall programs (section 26) and the folders they leave'
     # 22a - command lines exactly as the P52's uninstall entries wrote them (2026-11-02)
     $checks++
     $cases = @(
@@ -178,14 +178,14 @@ function Invoke-SelfTest26 {
 }
 
 function Invoke-SelfTest24 {
-  <# .SYNOPSIS Group [24]: the 1.4.0 extensions to sections 4, 7, 10 and 24. #>
+  <# .SYNOPSIS Group [24]: the P9 extensions to sections 4, 7, 10 and 24. #>
   param([string] $Fixture)
   $checks = 0; $fails = 0
   $root = Join-Path $Fixture 'g24'
   $pr = $Script:WS_PROTECT
   $savedEx = @($pr.Exceptions); $savedExP = @($pr.ExceptionPrefixes)
   try {
-    Write-Section '[24] 1.4.0: emulator leftovers (4), declared profiles (7), declared temp roots (10), last run (24)'
+    Write-Section '[24] P9: emulator leftovers (4), declared profiles (7), declared temp roots (10), last run (24)'
     # 24a - an AVD, its pointer, and a pointer to a folder that is gone (the P52's pointed into a missing drive)
     $checks++
     $avdRoot = Join-Path $root 'avd'
@@ -283,7 +283,7 @@ function Invoke-SelfTest25 {
   $savedExclude = $Script:WS_EXCLUDE
   $saved = @{ Json = $ws.JsonMode; Cands = $ws.Candidates; Permanent = $ws.Permanent }
   try {
-    Write-Section '[25] 1.4.0: the data scanner (section 19) - large or old, refusals, the change check'
+    Write-Section '[25] P9: the data scanner (section 19) - large or old, refusals, the change check'
     $d = Join-Path $root 'data'
     New-Item -ItemType Directory -Force -Path (Join-Path $d 'sub') | Out-Null
     $old = [datetime]::UtcNow.AddDays(-400)
@@ -361,7 +361,7 @@ function Invoke-SelfTest23 {
   $root = Join-Path $Fixture 'g23'
   $savedExclude = $Script:WS_EXCLUDE
   try {
-    Write-Section '[23] 1.4.0: leftover program folders (section 27)'
+    Write-Section '[23] P9: leftover program folders (section 27)'
     # 23a - registered commands as services, drivers, tasks and Run entries write them
     $checks++
     $SR = $Script:P.SR

package/modules/self_test_extra.ps1

@@ -354,7 +354,7 @@ function Invoke-SelfTestExtra {
     $contract = Invoke-SelfTestContract -Fixture $fx
     $checks += $contract.Checks; $fails += $contract.Fails
 
-    # [19] the 1.4.0 behaviour found on a real machine lives in modules/self_test_1_4.ps1 (P9).
+    # [19] the P9 behaviour found on a real machine lives in modules/self_test_1_4.ps1 (P9).
     $g19 = Invoke-SelfTest14 -Fixture $fx
     $checks += $g19.Checks; $fails += $g19.Fails
     $g20 = Invoke-SelfTest20 -Fixture $fx

package/modules/windows_user.ps1

@@ -68,7 +68,7 @@ function Get-TempRoots {
 }
 
 function Get-DeclaredTempRoots {
-  <# .SYNOPSIS 1.4.0: --temp-roots / tempRoots - folders a person uses as scratch space (C:\t on the P52, where
+  <# .SYNOPSIS P9: --temp-roots / tempRoots - folders a person uses as scratch space (C:\t on the P52, where
      test runs left one browser profile per run). Existing ones, once each, never a Windows temp root twice. #>
   $known = @(Get-TempRoots)
   $out = @()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windowsweep",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Windows cleanup CLI: dry-run first, personal files chosen row by row, zero install via npx.",
   "bin": {
     "windowsweep": "bin/windowsweep.js"