feat(windows): recover RP2040 phantom/BOOTSEL USB state through scoped admin PnP flow

[zackees]

Context\n\nThe Windows recovery design is incomplete in practice. The elevated helper from #1148 is merged, but no deployment path creates a UsbRecoveryRequest, launches the helper, consumes its result, rescans, or retries deployment. Consequently fbuild detects the problem but cannot recover this attached RP2040 without asking the user to manipulate BOOTSEL.\n\nObserved on the attached board:\n\n- runtime identity: 2E8A:000A, serial 5303284720C4641C;\n- build port scan reports historical COM12 as health=phantom selectable=no;\n- the stock ROM is already in BOOTSEL: the mounted RPI-RP2 volume is G:;\n- fbuild's stock UF2 path receives Windows error 1006 (ERROR_FILE_INVALID) while writing G:\NEW.UF2;\n- managed picotool sees an RP2040 BOOTSEL device at bus 1/address 12 but cannot connect because its Windows interface/driver is unavailable;\n- the current candidate correctly rejects explicit COM12 as an unusable phantom before any serial touch. That protects the board but does not unwind Windows.\n\nThe user explicitly does not want a BOOTSEL button sequence as the normal recovery path. The objective is to use least-privilege, explicit UAC-backed host recovery to force a fresh Windows enumeration and resume fbuild deployment when that is possible.\n\n## Existing foundation\n\n#1148 / PR #1151 already provides the secure primitives:\n\n- typed UsbRecoveryRequest / UsbRecoveryResult and policy types in build-core;\n- strict identity revalidation and allowlisted ReenumerateParent / RestartTarget operations in build-serial::usb_recovery;\n- a one-shot UAC helper, private nonce-protected rendezvous files, and --admin / --no-admin policy plumbing in build-cli.\n\nWhat is missing is orchestration. The daemon never returns a typed recovery request, and normal CLI deployment never invokes launch_once_for_typed_request or performs the mandatory fresh post-helper scan/openability gate.\n\n## Proposal\n\nImplement the Windows recovery-only deployment flow for RP2040:\n\n1. When the exact RP2040 identity is known-unhealthy (phantom or present/problem), the daemon constructs a typed request from the currently scanned instance ID, parent, VID/PID, serial, class, health/problem code, and operation ID. Diagnostic visibility remains separate from selection eligibility.\n2. With default policy, fail closed and print the normal non-privileged guidance. With build deploy --admin, return/consume only that typed request and launch the existing one-shot elevated helper. Do not elevate or restart the long-lived daemon.\n3. After helper completion, discard all prior port/volume facts. Perform bounded fresh scans of both runtime CDC and RP2040 BOOTSEL transports, require health eligibility plus a bounded openability probe for CDC, then retry the original deployment at most once without rebuilding.\n4. For the observed BOOTSEL ERROR_FILE_INVALID case, use the same exact-device/verified-parent re-enumeration path before a single fresh stock-transport attempt. Never retry an old G: handle and never use a stale COM12.\n5. If the Windows driver binding still prevents PICOBOOT access after re-enumeration, report the exact interface/driver state and a safe, actionable next step. Do not silently install third-party drivers, change global USB policy, reset all hubs, or claim recovery succeeded.\n6. Preserve the daemon's normal privilege and cache boundaries. A non-admin invocation after helper completion must work normally and must not inherit privileged daemon state.\n\n## Acceptance criteria\n\n- [ ] A phantom COM12 for the attached serial 5303284720C4641C yields a typed exact-device recovery request; default and --no-admin do not elevate or touch it.\n- [ ] build deploy --admin prompts through the existing one-shot helper only; it never elevates/restarts the daemon and never exposes a generic privileged command surface.\n- [ ] The helper revalidates the exact target and parent before acting; unrelated, missing, changed-class, changed-VID/PID, or changed-serial devices are rejected.\n- [ ] After recovery, fbuild discards stale COM/volume facts, rescans, and attempts deployment once only through a fresh eligible/openable endpoint or newly enumerated BOOTSEL transport.\n- [ ] The exact observed state—phantom runtime CDC plus BOOTSEL G: error 1006 and inaccessible PICOBOOT—either recovers without pressing BOOTSEL or produces a precise driver/interface diagnosis. It must not ask for BOOTSEL button use before attempting the permitted PnP recovery.\n- [ ] No stale FBUILD_DEPLOY_PORT, COM name, or mounted-volume handle is returned or retried.\n- [ ] Unit tests fake PnP state transitions, helper result validation, re-enumeration timeout, stale-state discard, one-retry limit, default/no-admin behavior, and the non-admin-after-admin cache/daemon boundary.\n- [ ] Windows hardware proof uses only build port scan and �ash autoresearch rp2040 --rpc-smoke --timeout 120s --skip-lint, with a unique five-digit FBUILD_DAEMON_PORT. Record pre/post health, PnP operation, fresh transport identity, deploy result, and RPC result.\n- [ ] The issue is not closed from static/unit evidence alone while this board remains attached.\n\n## Non-goals\n\n- No raw pyserial, picotool, direct file-copy, Device Manager scripting, Zadig automation, or broad

eset all USB command.\n- No unconditional driver installation or driver rebinding. If a standard Windows driver/binding remains the blocker, diagnose it explicitly and track any driver-install design separately.\n- No physical BOOTSEL-button sequence as the normal successful recovery path.\n- No privileged daemon, privileged cache, or persistent elevation.\n\n## Implementation map\n\n- crates/fbuild-daemon/src/handlers/operations/deploy.rs: produce a typed recovery-needed outcome only from fresh exact scan facts; keep flash/recovery phases separate.\n- crates/fbuild-daemon/src/models.rs and crates/fbuild-cli/src/daemon_client/types.rs: add a backward-compatible typed response field.\n- crates/fbuild-cli/src/cli/deploy.rs and cli/usb_recovery.rs: invoke #1148 exactly once for --admin, render result, then reissue the normal deployment/recovery flow.\n- crates/fbuild-deploy/src/rp2040.rs and
p2040_target.rs: expose only safe recovery facts; retain the health/openability gates from #1147.\n- crates/fbuild-serial/src/usb_recovery.rs: extend only if the BOOTSEL composite-interface identity requires a new narrow, revalidated operation; do not broaden the allowlist casually.\n\n## Related issues\n\n- #1149 — parent Windows USB recovery meta\n- #1148 — merged elevated helper foundation\n- #1147 — phantom CDC fail-closed state machine\n- #1081 — RP2040 BOOTSEL synthetic-volume transport failures\n

[zackees]

Parent goal/meta: #1149. This child owns the missing privileged recovery orchestration needed to close the Windows USB recovery goal.

[zackees]

Live host evidence (2026-07-22, fresh PnP query — board untouched)

The attached board is still in the exact wedged state this issue describes. Read-only Get-PnpDevice / Get-PnpDeviceProperty snapshot:

Devnode	Status	Problem	Service	Notes
USB\VID_2E8A&PID_0003\E0C9125B0D9B (BOOTSEL composite)	OK	0	usbccgp	parent USB\ROOT_HUB30\5&23f8e3f5&0&0
USB\VID_2E8A&PID_0003&MI_00\... (mass storage)	OK	0	USBSTOR	RPI-RP2 mounted at G: (134 MB synthetic FAT)
USB\VID_2E8A&PID_0003&MI_01\... (RP2 Boot / PICOBOOT)	Error	28 = CM_PROB_FAILED_INSTALL, ProblemStatus 0xC0000490	(none)	no driver bound — explains why managed picotool sees the device but cannot connect
USB\VID_2E8A&PID_000A\5303284720C4641C (runtime CDC)	Unknown, Present=False (phantom)	—	usbser	historical COM12

We are deliberately not attempting any deploy or write to G: until the new code is in place, so this live wedge remains available as the hardware-closeout reproduction required by #1149.

Hypotheses

• H1 (primary, explains UF2 ERROR_FILE_INVALID 1006): stale mounted-volume state. The BOOTSEL ROM regenerates its synthetic FAT on every enumeration; Windows' volume object for G: retains file-allocation state from before a prior partial write/re-enumeration, so a write through the stale mapping fails with 1006 ("volume … externally altered so that the opened file is no longer valid"). A device-scoped PnP re-enumeration of the composite devnode (the feat(windows): add scoped elevated USB PnP recovery helper #1148 ReenumerateParent/RestartTarget allowlisted operations) tears down and freshly remounts the volume; a single fresh UF2 attempt should then succeed.
• H2: the BOOTSEL ROM's MSC/UF2 write state machine is wedged by an earlier aborted transfer. The ROM resets that state on USB bus reset — which a PnP devnode restart performs. Unlike a descriptor-level failure, no VBUS power cycle is required, so the same remediation as H1 applies (this is precisely why the no-button --admin path is viable here).
• H3 (orthogonal): MI_01 problem code 28 means PICOBOOT simply has no driver bound. The UF2/MSC path does not need it (USBSTOR only), so recovery can succeed while MI_01 stays code 28. If re-enumeration doesn't heal the binding, we report it as an explicit diagnostic per the non-goals (no driver installs).
• H4: phantom COM12 is pure historical residue. It must never be selected (that is fix(rp2040): reject phantom CDC ports and give recoverable BOOTSEL guidance #1147's fail-closed gate); after a successful flash the runtime CDC re-enumerates — possibly under a new COM number — and must be rediscovered via a fresh scan + health + bounded openability probe.

Recovery strategy (sequenced)

1. fix(rp2040): reject phantom CDC ports and give recoverable BOOTSEL guidance #1147 first (still open): land the health-consuming RP2040 state machine so phantom/problem endpoints are excluded from selection, the 1200-baud touch, explicit --port, and post-flash reacquisition; UF2-success vs CDC-recovery split in DeploymentResult.
2. feat(windows): recover RP2040 phantom/BOOTSEL USB state through scoped admin PnP flow #1152 orchestration: daemon emits a typed UsbRecoveryRequest built only from fresh exact scan facts (instance ID, parent, VID/PID, serial, class, health/problem code, operation ID); default/--no-admin fails closed with guidance; --admin launches the merged feat(windows): add scoped elevated USB PnP recovery helper #1148 one-shot helper exactly once; afterwards all prior port/volume facts are discarded, both runtime-CDC and BOOTSEL transports are freshly rescanned with health + openability gates, and the original deployment is retried at most once without rebuilding. The observed BOOTSEL-1006 case routes through the same exact-device re-enumeration before one fresh stock-transport attempt.
3. Hardware closeout on this live wedge: editable-install the fbuild worktree into the FastLED venv, isolated five-digit FBUILD_DAEMON_PORT, capture fbuild port scan pre/post, run the --admin recovery, then bash autoresearch rp2040 --rpc-smoke --timeout 120s --skip-lint. Expected outcomes per hypothesis: H1/H2 → fresh RPI-RP2 mount, UF2 copy succeeds, healthy CDC returns (any COM number) and RPC smoke passes; H3 persists → precise driver/interface diagnosis, no silent installs; if the endpoint stays unhealthy → fail closed with physical BOOTSEL guidance and no stale port returned.

Falsifiability: if a fresh post-re-enumeration UF2 write still returns 1006 on a fresh mount, H1/H2 are wrong and the blocker is deeper in the MSC stack (e.g. filter driver) — that outcome gets recorded as a diagnostic finding, not retried in a loop.