agent-guide: an elevated device-node restart turns the S3 wedge into a click, and the whole flash cycle needs no hands

Author: bdbarnett

docs/agent-guide.md

@@ -384,11 +384,33 @@ failed as "busy or locked", and no process held the handle.
 asking for the same replug you were trying to avoid, having also lost the
 program that was running.
 
-So: **on a native-USB S3, never try to reach download mode in software.** Ask
-for the physical BOOT-and-plug. The network is the useful discriminator if you
-do end up guessing — a board that answers HTTP is running your firmware, and a
-board that answers nothing while its COM port refuses to open is in ROM mode
-behind a stale USB node.
+The stale node is repairable, and that changes the whole procedure. Restart
+the device node with elevation and Windows enumerates what the chip is
+actually presenting:
+
+```bash
+powershell.exe -NoProfile -Command "Start-Process pnputil -Verb RunAs \
+  -ArgumentList '/restart-device','USB\VID_303A&PID_4001\<serial>' -Wait"
+```
+
+That pops one UAC prompt, grants nothing that outlives it, and needs a human
+to click Yes — but it is a click, not a walk to the bench. On the T-Embed
+(2026-09-16, 17:34) the board went straight from the stale `303A:4001` node to
+`303A:1001` on a new COM number, esptool flashed it there, and it rebooted
+into the new firmware **without a button press** — the whole flash cycle with
+no hands on the hardware. `tools/windows/restart-esp-usb.ps1` in this repo
+does the same for whatever Espressif board is attached.
+
+So the order to try is: `machine.bootloader()` over `exec`, then the elevated
+device-node restart, then flash the `1001` port. Fall back to the physical
+BOOT-and-plug only if nobody is there to click. The network is the
+discriminator while you are guessing — a board that answers HTTP is running
+your firmware, and a board that answers nothing while its COM port refuses to
+open is in ROM mode behind a stale USB node.
+
+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.
 
 ### Ctrl-C is not an interrupt inside `atexit`
 

tools/windows/restart-esp-usb.ps1

@@ -0,0 +1,42 @@
+# Restart the USB device node of any attached Espressif board (VID 303A).
+#
+# This is the repair for the ESP32-S3 native-USB wedge described in
+# docs/agent-guide.md: after `mpftp bootloader` or a direct
+# `machine.bootloader()`, Windows goes on reporting a healthy device while
+# every attempt to open its COM port fails as "busy or locked", with no
+# process holding the handle. Restarting the device node makes Windows
+# enumerate what the chip is really presenting -- a board sitting in ROM
+# download mode then appears as 303A:1001 on a new COM number.
+#
+# Needs elevation. From an ordinary shell (WSL included), this pops one UAC
+# prompt and grants nothing that outlives it:
+#
+#   powershell.exe -NoProfile -Command "Start-Process powershell -Verb RunAs `
+#     -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File','<this file>'"
+#
+[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 }
+if (-not $devices) {
+    Write-Output "no device matching $Match is attached"
+    exit 1
+}
+foreach ($d in $devices) {
+    Write-Output ("restarting {0}  [{1}]" -f $d.InstanceId, $d.Status)
+    try {
+        Restart-PnpDevice -InstanceId $d.InstanceId -Confirm:$false -ErrorAction Stop
+        Write-Output "  ok"
+    } catch {
+        Write-Output ("  failed: {0}" -f $_.Exception.Message)
+    }
+}
+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