Release: Task Scheduler health tools + TaskCache diagnostic (dev -> main) #5

Merged

hannah-vernon merged 4 commits from dev into main

2026-07-02 09:21:58 -05:00

hannah-vernon commented

2026-07-02 09:21:24 -05:00

Owner

What does this PR do?

Promotes dev to main for release. Included since the last main release:

Test-ScheduledTaskHealth.ps1 (#3) - offline diagnostic that reconciles the on-disk task
XML files against the TaskCache Tree and Tasks registry entries without calling the Task
Scheduler service, so it works even while the service is hung. Includes an opt-in -Repair
mode that backs up each item (native .reg export + XML copy to -BackupPath) before
removing it, gated by SupportsShouldProcess (-WhatIf / -Confirm). The registry backup
uses the .NET registry API rather than reg.exe, so it works where DisableRegistryTools
policy blocks reg.exe.
TaskCache count summary + Get-TaskCacheSummary.ps1 (#4) - Test-ScheduledTaskHealth.ps1
now emits a leading Summary record (Tree node / Tasks GUID / XML file counts plus a
per-category tally) and warns when TaskCache\Tasks holds far fewer entries than the Tree
references. The new Get-TaskCacheSummary.ps1 is a quick read-only count comparison with an
interpreted assessment and optional per-GUID spot-checks (-CheckGuid), to distinguish real
corruption from a false alarm before any destructive repair.

Net result: the repo goes from three scripts to five, with README updates for both.

Fixes #

How was this tested?

Parser validation - 0 errors for all changed .ps1 files
Both features verified against synthetic fixtures (registry under HKCU + temp Tasks
folder) covering detection, -Repair -WhatIf, a real -Repair run with backups, the Summary
record, the count assessment, and -CheckGuid spot-checks.

Checklist

I have read the Contributing Guide
Changes are focused - one logical change per PR
Comment-based help updated for any changed parameters or behavior
Documentation updated (if user-visible behavior changed)
No commented-out code or debug leftovers

## What does this PR do? Promotes `dev` to `main` for release. Included since the last `main` release: - **`Test-ScheduledTaskHealth.ps1`** (#3) - offline diagnostic that reconciles the on-disk task XML files against the `TaskCache` Tree and Tasks registry entries without calling the Task Scheduler service, so it works even while the service is hung. Includes an opt-in `-Repair` mode that backs up each item (native `.reg` export + XML copy to `-BackupPath`) before removing it, gated by `SupportsShouldProcess` (`-WhatIf` / `-Confirm`). The registry backup uses the .NET registry API rather than `reg.exe`, so it works where `DisableRegistryTools` policy blocks `reg.exe`. - **TaskCache count summary + `Get-TaskCacheSummary.ps1`** (#4) - `Test-ScheduledTaskHealth.ps1` now emits a leading `Summary` record (Tree node / Tasks GUID / XML file counts plus a per-category tally) and warns when `TaskCache\Tasks` holds far fewer entries than the Tree references. The new `Get-TaskCacheSummary.ps1` is a quick read-only count comparison with an interpreted assessment and optional per-GUID spot-checks (`-CheckGuid`), to distinguish real corruption from a false alarm before any destructive repair. Net result: the repo goes from three scripts to five, with README updates for both. Fixes # ## How was this tested? - [x] Parser validation - 0 errors for all changed `.ps1` files - [x] Both features verified against synthetic fixtures (registry under HKCU + temp Tasks folder) covering detection, `-Repair -WhatIf`, a real `-Repair` run with backups, the Summary record, the count assessment, and `-CheckGuid` spot-checks. ## Checklist - [x] I have read the [Contributing Guide](../CONTRIBUTING.md) - [x] Changes are focused - one logical change per PR - [x] Comment-based help updated for any changed parameters or behavior - [x] Documentation updated (if user-visible behavior changed) - [x] No commented-out code or debug leftovers

hannah-vernon added 4 commits

2026-07-02 09:21:24 -05:00

Add Test-ScheduledTaskHealth.ps1 offline diagnostic with -Repair e65a2520e7

Add a fourth tool that diagnoses a stalled or hung Task Scheduler without calling
the Task Scheduler service (which is what hangs). It reconciles the on-disk task
XML files against the TaskCache Tree and Tasks registry entries and reports:
orphaned Tree/Tasks entries, missing/zero-byte/malformed task XML, and (opt-in)
unresolvable principal SIDs.

With -Repair it backs up each item (native .reg export of the registry key plus a
copy of the XML file to -BackupPath) and then removes it, gated by
SupportsShouldProcess so -WhatIf/-Confirm work. The registry backup uses the .NET
registry API rather than reg.exe, so it works on hosts where DisableRegistryTools
policy blocks reg.exe. Backup precedes deletion, so a failed backup aborts the
removal and no data is lost.

Verified against a synthetic fixture covering every finding category and the full
repair path (backup files written, entries removed, healthy task untouched).

Update README with usage and the troubleshooting/-Repair guidance.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge pull request 'Add Test-ScheduledTaskHealth.ps1 offline diagnostic with -Repair' (#3 ) from feature/task-scheduler-health-diagnostic into dev a23594f66d

Reviewed-on: #3

Add TaskCache count summary and Get-TaskCacheSummary diagnostic ff735aa396

Test-ScheduledTaskHealth.ps1 now emits a leading Summary record (Category=Summary)
reporting the count of Tree task nodes, TaskCache\Tasks GUID keys, and on-disk XML
files, plus a per-category finding tally. When TaskCache\Tasks holds far fewer
entries than the Tree references (which produces a large batch of OrphanTreeEntry
findings), it raises a warning: that pattern is either severe TaskCache damage or an
incomplete enumeration, and must be verified before repairing.

Add Get-TaskCacheSummary.ps1: a quick, read-only count comparison of the three
TaskCache sources (Tree, Tasks, on-disk XML), with TreeWithoutTasks / TasksWithoutTree
totals, an interpreted Assessment, and optional per-GUID spot-checks (-CheckGuid) that
confirm directly whether a flagged orphan's Tasks key really is absent.

Motivated by an MVCTWS01 run that reported 197 OrphanTreeEntry findings (mostly built-in
Windows tasks); this tooling distinguishes real corruption from a false alarm before any
destructive repair.

Verified against a synthetic fixture (Tree deliberately larger than Tasks) covering the
counts, assessment, and spot-checks.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge pull request 'Add TaskCache count summary and Get-TaskCacheSummary diagnostic' (#4 ) from feature/taskcache-summary-diagnostic into dev 0fd51498f1