The S3 USB-wedge repair never ran: there is no Restart-PnpDevice, so pnputil does it

Found mid flash cycle on 2026-09-17. The helper and the scheduled task wrapping
it both called a cmdlet Windows PowerShell does not have, failed on every
device, and looked exactly like a board that would not come back. The script
uses pnputil /restart-device now, falls back to Disable+Enable, restarts the
composite parent rather than its MI_ children, and says when it is not
elevated. The guide says how to read the task's real result.

Author: bdbarnett

docs/agent-guide.md

@@ -412,6 +412,21 @@ To lose the prompt as well, an administrator can register a scheduled task
 that runs the restart with SYSTEM privileges and let ordinary accounts start
 it; an agent must not create that task itself.
 
+**Check what that task actually runs, because there is no `Restart-PnpDevice`.**
+Windows PowerShell's PnpDevice module ships Get-, Enable- and Disable-PnpDevice
+and nothing else, so the obvious-looking one-liner fails with
+`CommandNotFoundException` on every device. The task then completes, reports
+`LastTaskResult 1`, and from the outside is indistinguishable from a board that
+refused to come back — which is how the 2026-09-17 pin-move run spent its S3
+half on a repair that had never worked. `schtasks /run` returns SUCCESS for
+*starting* the task, never for what it did: read
+`Get-ScheduledTaskInfo -TaskName <name> | Select LastTaskResult` instead.
+`pnputil /restart-device <instance-id>` is the mechanism that works;
+`tools/windows/restart-esp-usb.ps1` uses it now, with Disable+Enable as the
+fallback, and says so when it is not elevated rather than blaming the board.
+The task registered on this machine still carries the old one-liner and needs
+re-registering by hand.
+
 ### Ctrl-C is not an interrupt inside `atexit`
 
 CircuitPython does not arm Ctrl-C as an interrupt character while an `atexit`

tools/windows/restart-esp-usb.ps1

@@ -14,29 +14,61 @@
 #   powershell.exe -NoProfile -Command "Start-Process powershell -Verb RunAs `
 #     -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File','<this file>'"
 #
+# **There is no `Restart-PnpDevice`.** Windows PowerShell's PnpDevice module
+# ships Get-, Enable- and Disable-PnpDevice and nothing else, so a script that
+# calls Restart-PnpDevice fails with CommandNotFoundException on every device
+# and exits 1 -- while a scheduled task wrapping it reports LastTaskResult 1
+# and looks, from the outside, exactly like a board that refused to restart.
+# Found the expensive way on 2026-09-17, mid flash cycle. `pnputil
+# /restart-device` is the real mechanism; Disable+Enable is the fallback for a
+# Windows older than 2004.
 [CmdletBinding()]
 param(
     # Espressif's vendor ID. Narrow it (e.g. 'USB\VID_303A&PID_4001*') when two
     # boards are attached and only one should be restarted.
     [string]$Match = 'USB\VID_303A*'
 )
 
-$devices = Get-PnpDevice -PresentOnly | Where-Object { $_.InstanceId -like $Match }
+$identity = [Security.Principal.WindowsIdentity]::GetCurrent()
+$principal = New-Object Security.Principal.WindowsPrincipal($identity)
+if (-not $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+    Write-Output "not elevated -- every restart below will fail with Access is denied"
+}
+
+# Restart the composite parent, not its MI_ children: re-enumerating the
+# parent brings the interfaces with it, and a child whose parent is about to
+# vanish reports a confusing failure of its own.
+$devices = Get-PnpDevice -PresentOnly |
+    Where-Object { $_.InstanceId -like $Match -and $_.InstanceId -notmatch '&MI_' }
 if (-not $devices) {
     Write-Output "no device matching $Match is attached"
     exit 1
 }
+
+$failed = 0
 foreach ($d in $devices) {
     Write-Output ("restarting {0}  [{1}]" -f $d.InstanceId, $d.Status)
+    $out = & pnputil.exe /restart-device $d.InstanceId 2>&1
+    if ($LASTEXITCODE -eq 0 -and ($out -join ' ') -notmatch 'Failed to restart') {
+        Write-Output "  ok (pnputil)"
+        continue
+    }
+    Write-Output ("  pnputil: {0}" -f (($out | Where-Object { $_ -match '\S' }) -join '; '))
     try {
-        Restart-PnpDevice -InstanceId $d.InstanceId -Confirm:$false -ErrorAction Stop
-        Write-Output "  ok"
+        Disable-PnpDevice -InstanceId $d.InstanceId -Confirm:$false -ErrorAction Stop
+        Start-Sleep -Milliseconds 700
+        Enable-PnpDevice -InstanceId $d.InstanceId -Confirm:$false -ErrorAction Stop
+        Write-Output "  ok (disable/enable)"
     } catch {
         Write-Output ("  failed: {0}" -f $_.Exception.Message)
+        $failed++
     }
 }
+
 Start-Sleep -Seconds 3
 Get-PnpDevice -PresentOnly |
     Where-Object { $_.InstanceId -like 'USB\VID_303A*' } |
     Select-Object Status, InstanceId |
     Format-Table -AutoSize | Out-String | Write-Output
+
+exit $(if ($failed) { 1 } else { 0 })