@a11ign/screenreader-fleet 0.0.0-reserved.0 → 0.2.0

package/src/provisioning/set-display-mode.ps1

@@ -0,0 +1,411 @@
+# Pin the display mode (width x height) the fleet's capture window holds, and prove it landed.
+#
+# #1567/#1819: originally a `win_powershell` task, run directly over the SSH connection Ansible uses.
+# EnumDisplaySettings failed there -- `ok=0` even as the console-session `witness` account, not only under
+# `become`/SYSTEM -- because an OpenSSH-spawned PowerShell child does not attach to the interactive window
+# station the console session's desktop uses, the same "SSH has no interactive desktop" fact
+# `tasks/run-interactive.yml`'s header already names for `SystemParametersInfo` and guidepup. That move
+# was NECESSARY and it stands; this script is still called through the interactive one-shot task.
+#
+# ## #1955: it was necessary and it was not SUFFICIENT, and this is the part that was missing
+#
+# Run through `run-interactive.yml` against the real fleet on 2026-09-22 it failed identically on 10 of 10
+# workers. Measured on a11y-worker-2 (orchestrator, 2026-09-22T18:58Z), the interactive route is provably
+# doing its job -- `sessionId=1`, `windowStation='WinSta0'`, `desktop='Default'`, and
+# `GetSystemMetrics` reporting `screen=1024x768 monitors=1`. The desktop has a display. The call still
+# failed. So the fault was never the session, and #1833 did not miss.
+#
+# The fault is THE DEVICE ARGUMENT. Measured on the same box, in the same interactive task, seconds apart:
+#
+#     EnumDisplaySettingsW($null,         ENUM_CURRENT_SETTINGS) -> False,  mode 0x0
+#     EnumDisplaySettingsW('\\.\DISPLAY1', ENUM_CURRENT_SETTINGS) -> True,   mode 1024x768
+#     EnumDisplayDevicesA($null, 0) -> False        EnumDisplayDevicesW($null, 0) -> False
+#     GetDC(null) + GetDeviceCaps      -> HORZRES=1024 VERTRES=768 BITSPIXEL=32
+#     Screen.AllScreens                -> '\\.\DISPLAY1' 1024x768 primary
+#
+# THOSE FIVE READINGS, AND NO MORE THAN THOSE FIVE -- and READ WHAT `$null` IN THEM ACTUALLY SENT, because
+# it is not what it says. PowerShell converts `$null` to `[string]::Empty` when it binds a `string`
+# parameter; only `[NullString]::Value` sends a genuine NULL. Measured under pwsh 7.6.6 against a C#
+# `s == null` probe, not reasoned: literal `$null` and a variable holding `$null` both arrive as
+# "not-null, length 0", and `[NullString]::Value` arrives as NULL. So every line above that reads `$null`
+# passed a device NAMED `""` -- and no display device is called that, on this fleet or anywhere else.
+#
+# WHICH MAKES THE CHEAPER EXPLANATION THE RIGHT ONE, and #1968's first telling of this file got it wrong.
+# The ten-host failure was `EnumDisplaySettings($null, ...)` in this script's previous version: a
+# PowerShell binding trap, refused by any Windows box, not a property of these workers. What the readings
+# above do establish is narrower and still enough to act on: an EMPTY-named call refuses and a call naming
+# `\\.\DISPLAY1` answers. They establish NOTHING about a real NULL device, because no call in the list
+# ever passed one.
+#
+# THE FIX IS THEREFORE TO STOP ASKING FOR "the default device" AND TO NAME ONE -- unchanged by the above,
+# and the reading that shows it working (worker-7, below) is unaffected. The primary display's device name
+# comes from `MonitorFromPoint` + `GetMonitorInfoW`, and it is passed to `EnumDisplaySettingsW` and
+# `ChangeDisplaySettingsExW`. `ChangeDisplaySettings` (no `Ex`) cannot take a device name at all, which is
+# why it is gone.
+#
+# The diagnostic's own nameless arm now passes `[NullString]::Value`, so the NEXT fleet run is the first
+# reading that has ever actually asked the NULL question. Until one comes back, this file claims the
+# empty-name finding and no more.
+#
+# That the lookup path runs here is a READING too, not an assumption. With this script in place on
+# a11y-worker-7 (orchestrator, 2026-09-22T19:07Z) it printed
+# `context: current mode reads 640 x 480 on '\\.\DISPLAY1'`, and the name in that line is precisely what
+# `MonitorFromPoint` + `GetMonitorInfoW` returned -- so both ran and both answered. Neither of them takes a
+# device name, so neither is evidence about NULL-versus-named; they are the way OUT of that question.
+#
+# ## Why the context block prints on every run
+#
+# The failure this row exists for returned ONE sentence -- `EnumDisplaySettings could not read the current
+# display mode` -- and that sentence could not tell apart (1) the task landed in session 0 after all,
+# (2) it landed in session 1 but on a desktop with no display, and (3) it reached the right desktop and
+# the call refused anyway. Three causes, three files, one sentence: a fleet play that cannot separate them
+# buys nothing, and today's cost a full ten-host run for exactly that. The block prints on success too,
+# because a passing reading and a failing one are only comparable if they report the same fields.
+#
+# `SetLastError = true` is on the P/Invokes, but READ THE ERROR CODES WITH SUSPICION and the script says so
+# where it prints them: none of these functions is documented to call SetLastError on failure, and measured
+# here `203` (ERROR_ENVVAR_NOT_FOUND) came back from the FAILING calls and from the SUCCEEDING one alike.
+# It is a stale value from an unrelated call, which makes it exactly the shape of evidence this repo is
+# most wary of -- a number that looks like a finding and is not.
+#
+# Config comes from the environment rather than param(), matching diagnose-nvda-worker.ps1's reasoning --
+# the caller is a single templated Ansible string either way, and an env assignment ahead of the call
+# avoids one more layer of quoting inside `run-interactive.yml`'s already-quoted -Command string:
+#   A11Y_DISPLAY_WIDTH, A11Y_DISPLAY_HEIGHT
+#
+# Losing check-mode support is the real trade here: the old `win_powershell` task honoured
+# `ansible-playbook --check`; a scheduled task run through `run-interactive.yml` does not, the same as
+# every other interactive step in this role (`provision.yml`'s call into provision-nvda-worker.ps1).
+
+$ErrorActionPreference = 'Stop'
+
+$Width = [int] $env:A11Y_DISPLAY_WIDTH
+$Height = [int] $env:A11Y_DISPLAY_HEIGHT
+if ($Width -le 0 -or $Height -le 0) {
+  Write-Output "A11Y_DISPLAY_WIDTH/A11Y_DISPLAY_HEIGHT must both be positive integers, got $Width x $Height"
+  exit 1
+}
+
+if (-not ('A11yDisplay.NativeMethods' -as [type])) {
+  Add-Type -TypeDefinition '
+    using System;
+    using System.Runtime.InteropServices;
+    using System.Text;
+    namespace A11yDisplay {
+      // DEVMODEW. The Unicode form is deliberate: the measured working call on the fleet is
+      // EnumDisplaySettingsW with a named device, so the whole path is W rather than a mix.
+      [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+      public struct DEVMODE {
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string dmDeviceName;
+        public short dmSpecVersion;
+        public short dmDriverVersion;
+        public short dmSize;
+        public short dmDriverExtra;
+        public int dmFields;
+        public int dmPositionX;
+        public int dmPositionY;
+        public int dmDisplayOrientation;
+        public int dmDisplayFixedOutput;
+        public short dmColor;
+        public short dmDuplex;
+        public short dmYResolution;
+        public short dmTTOption;
+        public short dmCollate;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string dmFormName;
+        public short dmLogPixels;
+        public int dmBitsPerPel;
+        public int dmPelsWidth;
+        public int dmPelsHeight;
+        public int dmDisplayFlags;
+        public int dmDisplayFrequency;
+        public int dmICMMethod;
+        public int dmICMIntent;
+        public int dmMediaType;
+        public int dmDitherType;
+        public int dmReserved1;
+        public int dmReserved2;
+        public int dmPanningWidth;
+        public int dmPanningHeight;
+      }
+      [StructLayout(LayoutKind.Sequential)]
+      public struct RECT { public int left; public int top; public int right; public int bottom; }
+      [StructLayout(LayoutKind.Sequential)]
+      public struct POINT { public int x; public int y; }
+      // MONITORINFOEXW: MONITORINFO plus szDevice, the `\\.\DISPLAYn` name this script exists to obtain.
+      [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+      public struct MONITORINFOEX {
+        public int cbSize;
+        public RECT rcMonitor;
+        public RECT rcWork;
+        public int dwFlags;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string szDevice;
+      }
+      [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+      public struct DISPLAY_DEVICE {
+        public int cb;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string DeviceName;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 128)] public string DeviceString;
+        public int StateFlags;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 128)] public string DeviceID;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 128)] public string DeviceKey;
+      }
+      public class NativeMethods {
+        [DllImport("user32.dll", EntryPoint = "EnumDisplaySettingsW", SetLastError = true, CharSet = CharSet.Unicode)]
+        public static extern bool EnumDisplaySettings(string deviceName, int modeNum, ref DEVMODE devMode);
+        [DllImport("user32.dll", EntryPoint = "ChangeDisplaySettingsExW", SetLastError = true, CharSet = CharSet.Unicode)]
+        public static extern int ChangeDisplaySettingsEx(string deviceName, ref DEVMODE devMode, IntPtr window, int flags, IntPtr param);
+        [DllImport("user32.dll", EntryPoint = "EnumDisplayDevicesW", SetLastError = true, CharSet = CharSet.Unicode)]
+        public static extern bool EnumDisplayDevices(string device, int devNum, ref DISPLAY_DEVICE info, int flags);
+        [DllImport("user32.dll", SetLastError = true)]
+        public static extern IntPtr MonitorFromPoint(POINT pt, int flags);
+        [DllImport("user32.dll", EntryPoint = "GetMonitorInfoW", SetLastError = true, CharSet = CharSet.Unicode)]
+        public static extern bool GetMonitorInfo(IntPtr monitor, ref MONITORINFOEX info);
+        [DllImport("user32.dll", SetLastError = true)]
+        public static extern IntPtr GetProcessWindowStation();
+        [DllImport("user32.dll", SetLastError = true)]
+        public static extern IntPtr GetThreadDesktop(int threadId);
+        [DllImport("user32.dll", SetLastError = true)]
+        public static extern bool GetUserObjectInformation(IntPtr handle, int index, StringBuilder info, int length, out int lengthNeeded);
+        [DllImport("user32.dll", SetLastError = true)]
+        public static extern int GetSystemMetrics(int index);
+        [DllImport("kernel32.dll")]
+        public static extern int GetCurrentThreadId();
+      }
+    }
+  '
+}
+
+$ENUM_CURRENT_SETTINGS = -1
+$DM_PELSWIDTH = 0x00080000
+$DM_PELSHEIGHT = 0x00100000
+$CDS_UPDATEREGISTRY = 0x01
+$DISP_CHANGE_SUCCESSFUL = 0
+$MONITOR_DEFAULTTOPRIMARY = 1
+$UOI_NAME = 2
+$USER_OBJECT_NAME_CHARS = 256
+$SM_CXSCREEN = 0
+$SM_CYSCREEN = 1
+$SM_CMONITORS = 80
+
+# Printed beside every result and trusted by nobody -- see this file's header on why `203` came back from
+# the failing calls and the succeeding one alike.
+function Get-LastWin32Error {
+  [System.Runtime.InteropServices.Marshal]::GetLastWin32Error()
+}
+
+# The NAME of a window station or desktop HANDLE. Reported rather than inferred: "is this the interactive
+# desktop" is one of the three cases the old one-line failure could not answer, and `WinSta0` + `Default`
+# is what rules it out.
+function Get-UserObjectName {
+  param([IntPtr] $Handle)
+  if ($Handle -eq [IntPtr]::Zero) {
+    return "(null handle, Win32 $(Get-LastWin32Error))"
+  }
+  $name = New-Object System.Text.StringBuilder $USER_OBJECT_NAME_CHARS
+  $needed = 0
+  if ([A11yDisplay.NativeMethods]::GetUserObjectInformation(
+      $Handle, $UOI_NAME, $name, $name.Capacity, [ref] $needed)) {
+    return $name.ToString()
+  }
+  return "(unreadable, Win32 $(Get-LastWin32Error))"
+}
+
+# THE FIX, and the one line in this script that had to change. `$null` was MEANT to say "whatever the
+# system considers the default display device" and never did: PowerShell binds it to a `string` parameter
+# as `[string]::Empty`, so the call asked for a device NAMED `""`, which any Windows box refuses. See this
+# file's header for the measurement. MonitorFromPoint(0,0, DEFAULTTOPRIMARY) names the primary monitor and
+# GetMonitorInfoW reads its `\\.\DISPLAYn` back, which is a question that has an answer.
+#
+# Returns $null on failure rather than throwing, so the caller can print the whole context block before
+# giving up -- a refusal that reports nothing is what made the previous failure unrepeatable.
+#
+# IT PRINTS NOTHING, and says why it failed through `[ref] $Reason` instead. In PowerShell everything a
+# function writes JOINS ITS RETURN VALUE, so an earlier draft's `Write-Output` on the failure path came
+# back to the caller AS the device name: `$deviceName` held the diagnostic sentence, `-not $deviceName`
+# was false, the script never took its own failure branch, and the message was never printed either. A
+# function that both reports and returns can do neither here.
+function Get-PrimaryDisplayName {
+  param([ref] $Reason)
+  $origin = New-Object A11yDisplay.POINT
+  $origin.x = 0
+  $origin.y = 0
+  $monitor = [A11yDisplay.NativeMethods]::MonitorFromPoint($origin, $MONITOR_DEFAULTTOPRIMARY)
+  if ($monitor -eq [IntPtr]::Zero) {
+    $Reason.Value = "MonitorFromPoint found no primary monitor, last Win32 $(Get-LastWin32Error) -- unreliable"
+    return $null
+  }
+  $info = New-Object A11yDisplay.MONITORINFOEX
+  $info.cbSize = [System.Runtime.InteropServices.Marshal]::SizeOf($info)
+  if (-not [A11yDisplay.NativeMethods]::GetMonitorInfo($monitor, [ref] $info)) {
+    $Reason.Value = "GetMonitorInfo refused for monitor $monitor, last Win32 $(Get-LastWin32Error) -- unreliable"
+    return $null
+  }
+  return $info.szDevice
+}
+
+# One pass of `EnumDisplayDevices` over `$Device`. A NULL device enumerates the ADAPTERS on this desktop;
+# a `\\.\DISPLAYn` name enumerates the MONITORS on that adapter.
+#
+# The formatted lines come back through `[ref] $Lines` and THE COUNT IS THE RETURN VALUE, an int. Both
+# halves of that shape are reviewer-2's blocker on #1968 at `a58c7e44`, and the defect it replaces was
+# worse than the report: this function used to `return ,$lines` while the caller counted
+# `@(Get-EnumeratedDevices ...)`. PowerShell's unary comma deliberately emits the collection as ONE
+# pipeline object, `@()` collects that single object, and `.Count` was therefore **1 for every
+# population**. Measured under pwsh 7.6.6, not reasoned: 0 lines -> 1, 1 line -> 1, 3 lines -> 1. So the
+# caller's `if ($adapters.Count -gt 0)` was taken on every run, the named same-API control NEVER
+# executed, and an empty enumeration reported `enumerated 1 adapter(s)` -- a count of the wrapper,
+# printed as a count of devices, in exactly the case the control exists to separate.
+#
+# A COUNT MUST NOT CROSS A FUNCTION BOUNDARY AS A COLLECTION. An int cannot be unrolled, re-wrapped or
+# collected, so the shape that produced this defect cannot be spelled here again; the lines take the
+# `[ref]` route `Get-PrimaryDisplayName` already uses for the same PowerShell reason. `display-mode.test.ts`
+# runs this pair under a real PowerShell against a stubbed API and reads the count off the output, because
+# no assertion over the script's TEXT can tell "the control is written" from "the control ran".
+#
+# `$Device` is deliberately untyped, AND THAT IS NOT ENOUGH ON ITS OWN. `[string] $Device` would coerce
+# `$null` to the empty string at the PowerShell parameter -- but so does the .NET method binding one line
+# further down, whatever this parameter is declared as, which is the trap this file's header now records.
+# The caller therefore hands in `[NullString]::Value` rather than `$null`, and it survives an untyped
+# parameter unchanged (measured, same probe). `""` is a different argument to this API than NULL, and
+# telling the two apart is the one distinction this whole script turns on.
+function Get-EnumeratedDevices {
+  param($Device, [string] $Label, [ref] $Lines)
+  $found = @()
+  $info = New-Object A11yDisplay.DISPLAY_DEVICE
+  $index = 0
+  while ($true) {
+    $info.cb = [System.Runtime.InteropServices.Marshal]::SizeOf($info)
+    if (-not [A11yDisplay.NativeMethods]::EnumDisplayDevices($Device, $index, [ref] $info, 0)) {
+      break
+    }
+    $flags = '0x{0:X8}' -f $info.StateFlags
+    $found += "context: $Label[$index] name='$($info.DeviceName)' adapter='$($info.DeviceString)' stateFlags=$flags (cb=$($info.cb))"
+    $index++
+  }
+  $Lines.Value = $found
+  return $found.Count
+}
+
+# Every display DEVICE this process can enumerate -- and, when that comes back empty, THE SAME API ASKED
+# AGAIN WITH A NAME. Kept although nothing depends on it any more: it is the block that measures whether
+# a nameless call works on this fleet, a question no reading has actually answered yet (every earlier one
+# asked about `""`), and a future run where it starts answering is a real change this is the only thing
+# that would show.
+#
+# THE CONTROL IS THE POINT, and it is reviewer-2's blocker on #1968. `EnumDisplayDevices(NULL, 0)`
+# returning False at index 0 is TWO findings wearing one face -- "this desktop has no display adapters"
+# and "this function refuses a nameless call here" (a thing no reading has shown yet -- the
+# EnumDisplaySettings refusals were all EMPTY-named, see this file's header) -- and an
+# empty population that cannot tell them apart is the shape this repository refuses everywhere else.
+# `Screen.AllScreens` and the named `EnumDisplaySettingsW` are a DIFFERENT API answering a different
+# question, so neither settles it. The control therefore has to be THIS function with a device name: if it
+# answers, the empty NULL population is about the ARGUMENT; if it refuses too, the reading is about the
+# function instead, and the script says so rather than claiming the stronger of the two.
+#
+# The two counts below are the ints `Get-EnumeratedDevices` returns, cast with `[int]` at the assignment:
+# that cast is the thing that makes a stray extra output object fail LOUDLY here rather than turn the
+# count into a collection again, which is how the count stopped being the count in the first place.
+function Write-DisplayDevices {
+  param($PrimaryDevice)
+  $adapterLines = @()
+  [int] $adapters = Get-EnumeratedDevices -Device ([NullString]::Value) -Label 'device' -Lines ([ref] $adapterLines)
+  $adapterLines | ForEach-Object { Write-Output $_ }
+  if ($adapters -gt 0) {
+    Write-Output "context: EnumDisplayDevices(NULL) enumerated $adapters adapter(s)"
+    return
+  }
+  if (-not $PrimaryDevice) {
+    Write-Output ("context: EnumDisplayDevices(NULL, 0) enumerated NOTHING and no NAMED control could be run" +
+      " (no primary device name), so this reading cannot tell an absent display from a refused nameless call")
+    return
+  }
+  $monitorLines = @()
+  [int] $monitors = Get-EnumeratedDevices -Device $PrimaryDevice -Label 'monitor' -Lines ([ref] $monitorLines)
+  $monitorLines | ForEach-Object { Write-Output $_ }
+  if ($monitors -gt 0) {
+    Write-Output ("context: EnumDisplayDevices(NULL, 0) enumerated NOTHING while the same call NAMED" +
+      " '$PrimaryDevice' enumerated $monitors monitor(s) -- the function answers here, and it is" +
+      " the NULL device that is refused")
+  } else {
+    Write-Output ("context: EnumDisplayDevices enumerated NOTHING for NULL AND for the NAMED control" +
+      " '$PrimaryDevice' -- the control refused too, so this says nothing about the NULL device in" +
+      " particular (last Win32 $(Get-LastWin32Error) -- unreliable)")
+  }
+}
+
+# What the SESSION's desktop itself thinks it has, read through a call that takes no device name at all.
+# This is the line that separates "this desktop has no display" from "this desktop has one and the call
+# refused": on 2026-09-22 it reported a real screen while the enumeration reported none, and that
+# disagreement is what pointed at the argument rather than at the environment.
+function Write-ScreenMetrics {
+  $width = [A11yDisplay.NativeMethods]::GetSystemMetrics($SM_CXSCREEN)
+  $height = [A11yDisplay.NativeMethods]::GetSystemMetrics($SM_CYSCREEN)
+  $monitors = [A11yDisplay.NativeMethods]::GetSystemMetrics($SM_CMONITORS)
+  Write-Output "context: GetSystemMetrics screen=${width}x${height} monitors=$monitors"
+}
+
+function Write-DisplayContext {
+  param($PrimaryDevice)
+  $process = [System.Diagnostics.Process]::GetCurrentProcess()
+  $identity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
+  Write-Output "context: sessionId=$($process.SessionId) pid=$($process.Id) user=$($identity.Name)"
+  $station = [A11yDisplay.NativeMethods]::GetProcessWindowStation()
+  $threadId = [A11yDisplay.NativeMethods]::GetCurrentThreadId()
+  $desktop = [A11yDisplay.NativeMethods]::GetThreadDesktop($threadId)
+  Write-Output "context: windowStation='$(Get-UserObjectName $station)' desktop='$(Get-UserObjectName $desktop)'"
+  Write-ScreenMetrics
+  Write-DisplayDevices -PrimaryDevice $PrimaryDevice
+}
+
+# The name is resolved BEFORE the context block rather than after it, because the block's device
+# enumeration needs it for its control. Resolution prints nothing of its own, so a failure here still
+# reports through the same block below, in the same order, on a failing run and a passing one alike.
+$nameRefusal = $null
+$deviceName = Get-PrimaryDisplayName -Reason ([ref] $nameRefusal)
+if ($nameRefusal) {
+  Write-Output "context: $nameRefusal"
+}
+Write-DisplayContext -PrimaryDevice $deviceName
+
+if (-not $deviceName) {
+  Write-Output 'no primary display device could be named, so there is nothing to set the mode on'
+  exit 1
+}
+Write-Output "context: primary display device='$deviceName' wanted=$Width x $Height"
+
+$mode = New-Object A11yDisplay.DEVMODE
+$mode.dmSize = [System.Runtime.InteropServices.Marshal]::SizeOf($mode)
+if (-not [A11yDisplay.NativeMethods]::EnumDisplaySettings($deviceName, $ENUM_CURRENT_SETTINGS, [ref] $mode)) {
+  Write-Output "EnumDisplaySettings could not read the current display mode of '$deviceName' (dmSize $($mode.dmSize), last Win32 $(Get-LastWin32Error) -- unreliable)"
+  exit 1
+}
+
+Write-Output "context: current mode reads $($mode.dmPelsWidth) x $($mode.dmPelsHeight) on '$deviceName'"
+
+if ($mode.dmPelsWidth -eq $Width -and $mode.dmPelsHeight -eq $Height) {
+  Write-Output "already $Width x $Height"
+  exit 0
+}
+
+$mode.dmPelsWidth = $Width
+$mode.dmPelsHeight = $Height
+$mode.dmFields = $DM_PELSWIDTH -bor $DM_PELSHEIGHT
+$result = [A11yDisplay.NativeMethods]::ChangeDisplaySettingsEx(
+  $deviceName, [ref] $mode, [IntPtr]::Zero, $CDS_UPDATEREGISTRY, [IntPtr]::Zero)
+if ($result -ne $DISP_CHANGE_SUCCESSFUL) {
+  Write-Output "ChangeDisplaySettingsEx returned $result (wanted $DISP_CHANGE_SUCCESSFUL) setting $Width x $Height on '$deviceName'"
+  exit 1
+}
+
+# PROVE IT, IN THE SAME PROCESS THAT JUST WROTE IT -- the same "read back or it didn't happen" rule
+# policy.yml's own trailing verify task follows.
+$after = New-Object A11yDisplay.DEVMODE
+$after.dmSize = [System.Runtime.InteropServices.Marshal]::SizeOf($after)
+[void][A11yDisplay.NativeMethods]::EnumDisplaySettings($deviceName, $ENUM_CURRENT_SETTINGS, [ref] $after)
+if ($after.dmPelsWidth -ne $Width -or $after.dmPelsHeight -ne $Height) {
+  Write-Output "ChangeDisplaySettingsEx reported success but the mode reads $($after.dmPelsWidth) x $($after.dmPelsHeight) back, not $Width x $Height"
+  exit 1
+}
+
+Write-Output "set to $Width x $Height"
+exit 0

package/src/provisioning/stamp-provision-revision.ps1

@@ -0,0 +1,184 @@
+<#
+.SYNOPSIS
+  Write provision-revision.txt -- the stamp that keys the capture cache on what provisioning ACTUALLY did.
+
+.DESCRIPTION
+  ONE definition, called by both provisioning paths. It used to live inline at the end of
+  provision-nvda-worker.ps1, which meant the Ansible role could not stamp at all: a box provisioned or
+  RE-provisioned through `provision-role.yml` kept whatever stamp its first boot happened to write.
+
+  Measured consequence on this fleet -- four boxes, functionally identical, reporting four different
+  revisions purely because each first-booted at a different commit during one afternoon:
+
+      .107 = 5d4b877-c9d43b025889b77c
+      .59  = ae888e3-c9d43b025889b77c
+      .175 = b8b5af4-c9d43b025889b77c
+      .224 = 449a20c-c9d43b025889b77c
+
+  `fleet:status` correctly called that INCONSISTENT, and no amount of re-provisioning could converge it,
+  because nothing on the Ansible path wrote the file.
+
+  ## What is hashed, and why the role's defaults are in the list
+
+  The stamp exists so two guests with different NVDA/Edge configuration cannot share a cache entry. When
+  it was written, provisioning was the PowerShell script, so hashing three of its files described the
+  environment completely. It no longer does: `roles/worker/defaults/main.yml` is where the Edge policies,
+  the NIC power values and the quiet-desktop settings are now DEFINED, and the role applies them.
+
+  Leaving it out would have been the cosmetic version of this fix. Adding `ComponentUpdatesEnabled` to
+  that file changes what Edge does during a capture and would NOT have moved the stamp -- so captures
+  taken either side of it would have shared a cache key while describing different browsers. That is
+  precisely the failure the stamp is here to prevent.
+
+  Task files are deliberately NOT hashed. They change when the same settings are applied a different way
+  -- batching four registry writes into one call is a refactor, not an environment change -- and keying on
+  them would churn the cache for reasons that never reach a capture.
+
+.NOTES
+  Missing files THROW. The previous version filtered them out with `Where-Object { $_ }`, so when the repo
+  was restructured into packages/ all three paths vanished at once and `$combined` silently fell back to
+  'unknown' -- the stamp stopped describing anything and varied only by git SHA. A check that discards its
+  own inputs cannot report that it found nothing.
+#>
+param(
+    [Parameter(Mandatory = $true)][string] $RepoPath
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# TWO OF THE FIVE PATHS ARE NOT WRITTEN HERE (ADR 0039 item 6d, #3397). Where the worker layer lives is
+# declared in `packages/control/layers.json`, and what its launchers reach outside it in the layer's own
+# `src/launcher-reach.cmd`, which `run-capture-check.cmd` `call`s. Both are READ, so a path cannot change in
+# the launcher and stay behind in the stamp. A declaration that is absent or does not say THROWS: the stamp
+# must not fall back to a literal, because a literal that was right yesterday is the stamp describing less
+# than it claims. The VALUES are unchanged, so `provisionRevision` is too -- `layer-launchers.test.ts`
+# asserts that this row's own diff names none of the five files.
+function Get-LayerFile {
+    param([Parameter(Mandatory = $true)][string] $Layer, [Parameter(Mandatory = $true)][string] $Relative)
+    $manifest = Get-Content -Raw -LiteralPath (Join-Path $RepoPath 'packages\control\layers.json') | ConvertFrom-Json
+    "$($manifest.layers.$Layer.path)/$Relative"
+}
+
+function Get-DeclaredReach {
+    param([Parameter(Mandatory = $true)][string] $Name)
+    $declaration = Join-Path $RepoPath ((Get-LayerFile -Layer 'nvda-worker' -Relative 'src/launcher-reach.cmd') -replace '/', '\')
+    if (-not (Test-Path -LiteralPath $declaration)) {
+        throw "provision stamp: the launcher declaration $declaration is missing. Refusing to guess where the launchers reach."
+    }
+    $line = Select-String -LiteralPath $declaration -Pattern "^set `"$Name=(.+)`"\s*$" | Select-Object -First 1
+    if (-not $line) { throw "provision stamp: $declaration does not declare $Name." }
+    $line.Matches[0].Groups[1].Value -replace '\\', '/'
+}
+
+$RUN_SERVER = Get-LayerFile -Layer 'nvda-worker' -Relative 'src/run-server.cmd'
+$FOREGROUND_LOCK = Get-DeclaredReach -Name 'FLT'
+
+# The single definition. Explicit paths rather than a filename search, because `main.yml` is not unique
+# in this repo and a search would silently pick the wrong one.
+$ENVIRONMENT_FILES = @(
+    'packages/worker-fleet/src/provisioning/provision-nvda-worker.ps1'
+    $RUN_SERVER
+    $FOREGROUND_LOCK
+    'packages/control/ansible/roles/worker/defaults/main.yml'
+    # SPEECH VIEWER, added 2026-09-05, and it is the same shape as `apply-foreground-lock-timeout.ps1`
+    # above: a script that carries its own hardcoded ENVIRONMENT value rather than reading one from
+    # `defaults/main.yml`. Hashing the script is how such a value gets into the stamp at all.
+    #
+    # WHY IT MATTERS MORE THAN THE OTHERS. This module's own header calls `showSpeechViewerAtStartup`
+    # "the highest-value setting on a worker and the one that fails most quietly": with it ON, every
+    # interaction probe returns "NVDA Speech Viewer" instead of the page's response. A whole corpus
+    # would be captured, complete and wrong.
+    #
+    # AND IT IS A REMEDY THAT REACHED ONE PATH AND NOT THE OTHER -- this repo's most expensive shape,
+    # found INSIDE the mechanism built to catch it. `provision-nvda-worker.ps1` (hashed since forever)
+    # inlines the identical `showSpeechViewerAtStartup = True -> False` fix at its Step 5, and throws if
+    # it did not take. The Ansible path does the same work in this module and was hashed by nothing, so
+    # a regression there -- or a fresh box shipping guidepup's default ON -- would leave the stamp
+    # unmoved, `fleet-consistency` reading the fleet as fine, and every capture silently unusable.
+    #
+    # Checked against every other cache-key field before adding it, rather than assumed: not in
+    # `CAPTURE_SETTINGS` (which has one entry, `speech.reportLanguage`, and `getSettings()` does not
+    # touch this section of `nvda.ini`), not in `/health`, and unrelated to `browserVersion`,
+    # `guidepupVersion`, `windowsVersion`, `architecture` or `captureProtocol`. Only `/diagnostics`
+    # reports it, on demand, outside `environmentKey()` entirely. Nothing else catches it.
+    #
+    # THE STRONGER FIX IS RECORDED AND NOT DONE HERE: reading the LIVE value out of `nvda.ini` onto
+    # `/health` and folding it into `screenReaderSettings` would verify the setting is IN EFFECT rather
+    # than that provisioning INTENDED it -- this file's own distinction, and the better one. It changes
+    # `environmentKey()`, so it must ride a deliberate cache-key change rather than land mid-recapture.
+    'packages/control/ansible/collections/ansible_collections/a11y/worker/plugins/modules/a11y_speech_viewer.ps1'
+)
+
+# LINE ENDINGS ARE NORMALISED BEFORE HASHING, AND THE PREVIOUS VERSION'S OMISSION WAS A LATENT SPLIT.
+#
+# This used to be `Get-FileHash`, which hashes the file's BYTES -- so the stamp depended on how git had
+# checked the file out. Windows git converts to CRLF by default and nothing in this repo pins that: there
+# is no `.gitattributes`. Measured 2026-09-04, the same four blobs at one commit:
+#
+#     CRLF  dbb7d33409a9341d      <- what the whole fleet reported
+#     LF    1052b80ca42398c7      <- what a checkout with core.autocrlf=false would report
+#
+# `provisionRevision` is a capture cache key AND a `fleet-consistency` MUST_MATCH field, compared for
+# EQUALITY. So one box cloned with a different `core.autocrlf` would read INCONSISTENT for ever, block
+# every capture run, and -- this is the part that makes it worth fixing rather than documenting --
+# RE-PROVISIONING COULD NOT CONVERGE IT, because the box would faithfully recompute the same wrong hash.
+# It is the one drift in this fleet with no remedy at the operator's disposal.
+#
+# The header above says what the stamp is for: "two guests with different NVDA/Edge configuration cannot
+# share a cache entry". A line ending is not configuration, so hashing it is not merely risky, it is
+# measuring the wrong thing -- the same argument that already excludes the git SHA and the task files.
+#
+# Normalising costs one stamp move, paid once, and it was bundled with a move happening anyway.
+$hashes = foreach ($relative in $ENVIRONMENT_FILES) {
+    $full = Join-Path $RepoPath ($relative -replace '/', '\')
+    if (-not (Test-Path -LiteralPath $full)) {
+        throw "provision stamp: $relative is missing under $RepoPath. Refusing to write a stamp that " +
+              "describes less than it claims -- fix the path or the checkout."
+    }
+    # ReadAllText also drops a UTF-8 BOM, which is the same class of difference arriving by another door:
+    # a file re-saved by an editor that adds one would otherwise move the stamp for no reason.
+    $text = [IO.File]::ReadAllText($full) -replace "`r`n", "`n"
+    $sha  = [Security.Cryptography.SHA256]::Create()
+    ([BitConverter]::ToString($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($text))) -replace '-', '')
+}
+
+$bytes = [Text.Encoding]::UTF8.GetBytes(($hashes -join ''))
+$combined = ([BitConverter]::ToString(
+    [Security.Cryptography.SHA256]::Create().ComputeHash($bytes)) -replace '-', '').Substring(0, 16).ToLower()
+
+# THE COMMIT IS RECORDED, AND IS DELIBERATELY NOT PART OF THE STAMP.
+#
+# It used to be: the stamp read `<short sha>-<content hash>`. That made an ordinary commit -- one touching
+# none of the four files above, none of provisioning, nothing a capture can observe -- change a CAPTURE
+# CACHE KEY and a `fleet-consistency` MUST_MATCH field. The consequences are not theoretical:
+#
+#   - re-provisioning a fleet after any commit invalidates every cached capture, so a full recapture
+#     (~6 h) is the price of a documentation change that happened to land first;
+#   - a box provisioned even minutes after its peers reads INCONSISTENT and blocks every capture run;
+#   - measured 2026-08-25: a11y-worker-6 failed provisioning and could not simply be re-run, because by
+#     then HEAD had moved and re-running would have stamped it differently from the four boxes that had
+#     just succeeded. Four healthy machines faced re-provisioning for a SHA.
+#
+# This repo already made exactly this decision one field over, and wrote down why: `workerCode` is
+# deliberately OUTSIDE the capture cache key because "that hash changes when a comment changes, and
+# invalidating the WHOLE corpus over a reworded comment is how a cache becomes something people turn
+# off" (capture-cache.mjs). A git SHA changes for strictly more reasons than a code hash does.
+#
+# The content hash already answers the question the stamp exists to answer -- do two guests have different
+# NVDA/Edge configuration? -- and it answers it by describing the configuration rather than by naming a
+# moment. That is also why task files are excluded above: "batching four registry writes into one call is a
+# refactor, not an environment change". The SHA contradicted that reasoning; removing it restores it.
+#
+# The commit is still worth having, for diagnosis rather than for keying, so it goes in its own file next
+# to the stamp. `provisionRevision` is compared for EQUALITY and never parsed (capture-cache.mjs,
+# fleet-consistency.mjs), so nothing downstream reads the two halves apart.
+$gitSha = try { (git -C $RepoPath rev-parse --short HEAD 2>$null) } catch { $null }
+$commitPath = Join-Path $RepoPath 'provision-commit.txt'
+$(if ($gitSha) { $gitSha } else { 'nogit' }) | Out-File -LiteralPath $commitPath -Encoding ascii -NoNewline
+
+$stamp = $combined
+
+$stampPath = Join-Path $RepoPath 'provision-revision.txt'
+$stamp | Out-File -LiteralPath $stampPath -Encoding ascii -NoNewline
+$stamp