diff --git a/docs/PESETUP-INTERNALS.md b/docs/PESETUP-INTERNALS.md index 7d3fbd8..511e1c0 100644 --- a/docs/PESETUP-INTERNALS.md +++ b/docs/PESETUP-INTERNALS.md @@ -12,9 +12,11 @@ its own log (`AppVersion: 4.0.0.20`). Everything in this document was verified against a 4.0.0.20 run on bay 579C144 that day: the media drive resolved to `Z:\`, `W:` was created by `PrepareDisk` and used for every copy destination, the fallback unattend at `Deploy\FlatUnattendW10.xml` was the one loaded, and driver selection -matched `win11_optiplexd13mlk7020_a09.zip` by model. The decompiled detail below has -not been re-derived from the 4.0.0.20 binary, so treat exact line-level claims as -4.0.0.17 and the observed behaviour as current. +matched `win11_optiplexd13mlk7020_a09.zip` by model. Most of the decompiled detail +below has not been re-derived from the 4.0.0.20 binary, so treat exact line-level +claims as 4.0.0.17 and the observed behaviour as current. The exception is +"The Patch Tuesday freshness gate" under GATHER DATA, which was decompiled from +4.0.0.20 on 2026-08-21 and does NOT exist in 4.0.0.17. ## How to re-derive this @@ -110,6 +112,74 @@ Four operations, all automatic: 6. Otherwise `GetDriverByModel` (below). 7. If `Control\skip.json` exists, package installation is skipped. +### The Patch Tuesday freshness gate (4.0.0.20, NOT in 4.0.0.17) + +Added after this document was first written, and it is the last thing +`GatherDataSelection` does before it succeeds. Verified against the 4.0.0.20 +binary on 2026-08-21. + +```csharp +DateTime lastPatchTuesday = MiscHelpers.GetLastPatchTuesday(); +DateTime dateTime = lastPatchTuesday.AddDays(10.0); +if (!(DateTime.Now > lastPatchTuesday) || !(DateTime.Now < dateTime)) +{ + bool flag = true; + if (!string.IsNullOrEmpty(osv.operatingSystemVersion.wim.creationDate)) { + DateTime d2 = DateTime.ParseExact(..., "yyyy-MM-dd", ...); + if (d2 > lastPatchTuesday) flag = false; + } + if (imageinfo.LastUpdate >= dateTime) flag = false; + if (flag) { + SetResult(Failed, "gatherdata_mediadrive_error_patchday"); + imageinfo.IsUpdateRequired = true; + } +} +``` + +`GetLastPatchTuesday` returns the second Tuesday of this month, or of the +previous month when today is on or before it. That makes `DateTime.Now > +lastPatchTuesday` always true, so only the `DateTime.Now >= lastPatchTuesday + +10 days` half of the guard ever fires. In effect: **from Patch Tuesday + 10 +onward, the media must prove it is at least that fresh, or imaging fails.** + +Two things can satisfy it. Neither is a package check; both are dates. + +1. `Control\OperatingSystem.json` -> `wim.creationDate`, format `yyyy-MM-dd`, + later than the last Patch Tuesday. Our OperatingSystem.json has no + `creationDate` field at all, so this branch never runs here. +2. `imageinfo.LastUpdate`, which is nothing more than the mtime of + `\Deploy\Control\Media.tag` (set in `GatherDataMediaDrive. + CheckLastWriteTime`, the same read that drives the 30-day expiry). + +So on this server the gate reduces to one question: is Media.tag's mtime on or +after the last Patch Tuesday + 10 days? + +**The midnight trap.** `/etc/cron.d/media-tag-refresh` touches Media.tag at +00:00:01 server local time. WinPE renders SMB file times about an hour behind +the server, which drops a 00:00 stamp back onto the previous day. That is +invisible for 29 days a month and fatal on exactly one: the Patch Tuesday + 10 +boundary day, when the gate compares against midnight of that very date. Hit on +2026-08-21 (PESetup log showed `Last Imaging Source Update: '2026-08-20'` +against `Last Patch Tuesday + 10 days: '2026-08-21'`), on a Dell Pro Tower Plus +QBT1250 that was otherwise fine: driver matched, secure boot on, media view +intact. It recurs every month on Patch Tuesday + 10. + +Restamp Media.tag at a mid-day hour, never at midnight. It must also stay in the +PAST relative to the bay clock: a future mtime makes `CheckLastWriteTime` set +`isBiosTimeCorrect = false` and fail with the BIOS-time error instead. + +The failure text itself is useless. `gatherdata_mediadrive_error_patchday` +renders as an empty `####ERROR:` line in the log, so the three INFO lines above +it are the only diagnosis: + +``` +Last Imaging Source Update: '' +Last Patch Tuesday: '' +Last Patch Tuesday + 10 days: '' +Imaging Source Update required: True +``` + + ### 2. SELECT OS Operator-facing. Warns when the media holds an LTSC image ("99% of the time only diff --git a/scripts/diagnostics/Capture-MclCache.ps1 b/scripts/diagnostics/Capture-MclCache.ps1 index 4a08ee0..007bfae 100644 --- a/scripts/diagnostics/Capture-MclCache.ps1 +++ b/scripts/diagnostics/Capture-MclCache.ps1 @@ -74,13 +74,31 @@ $rows | Sort-Object Path | Export-Csv -LiteralPath (Join-Path $dest "tree.csv") $copied = 0 $redacted = 0 $skippedBig = New-Object System.Collections.Generic.List[string] +$unreadable = New-Object System.Collections.Generic.List[string] foreach ($f in $all) { if ($textExt -notcontains $f.Extension.ToLower()) { continue } $rel = $f.FullName.Substring($Root.Length + 1) if ($f.Length -gt $maxCopy) { $skippedBig.Add("$rel ($($f.Length) bytes)"); continue } $target = Join-Path $filesDir $rel New-Item -ItemType Directory -Path (Split-Path $target -Parent) -Force | Out-Null - $bytes = [System.IO.File]::ReadAllBytes($f.FullName) + # Share mode lets this read the log MCL still has open. + try { + $fs = New-Object System.IO.FileStream($f.FullName, [System.IO.FileMode]::Open, + [System.IO.FileAccess]::Read, ([System.IO.FileShare]::ReadWrite -bor [System.IO.FileShare]::Delete)) + try { + $bytes = New-Object byte[] $fs.Length + $read = 0 + while ($read -lt $bytes.Length) { + $n = $fs.Read($bytes, $read, $bytes.Length - $read) + if ($n -le 0) { break } + $read += $n + } + if ($read -lt $bytes.Length) { $bytes = $bytes[0..($read - 1)] } + } finally { $fs.Dispose() } + } catch { + $unreadable.Add("$rel ($($_.Exception.InnerException.Message))") + continue + } $text = [System.Text.Encoding]::UTF8.GetString($bytes) if ($text -match $sasPattern) { $text = [regex]::Replace($text, $sasPattern, '${1}REDACTED') @@ -116,6 +134,11 @@ foreach ($g in ($rows | Group-Object { ($_.Path -split '\\')[0..1] -join '\' } | $gb = [math]::Round((($g.Group | Measure-Object Length -Sum).Sum) / 1GB, 2) $sum.Add(" $($g.Name): $($g.Count) files, $gb GB") } +if ($unreadable.Count) { + $sum.Add("") + $sum.Add("Text files that could not be read, not copied:") + foreach ($s in $unreadable) { $sum.Add(" $s") } +} if ($skippedBig.Count) { $sum.Add("") $sum.Add("Text files over 5 MB, not copied:") @@ -131,4 +154,7 @@ Write-Host "Captured $($all.Count) files ($copied text files copied)." -Foregrou if ($tags.Count -eq 0) { Write-Host "WARNING: no .tag file. MCL did not finish this run." -ForegroundColor Yellow } +if ($unreadable.Count) { + Write-Host "$($unreadable.Count) file(s) could not be read; listed in summary.txt." -ForegroundColor Yellow +} Write-Host "Send back: $zip"