fix(serial): preserve Windows port health through probing

[zackees]

Closes#1146

What changed

• Replaced the blessed serial enumeration result with DetectedPort, preserving Windows PnP health, canonical instance ID, and parent identity.
• Kept phantom/problem records in diagnostics while marking them selectable=no in fbuild port scan.
• Propagated health through CLI probing/monitor selection, daemon inventory, bootloader watching, and RP2040/Teensy catalogues.
• Rejected known-unhealthy endpoints from automatic or explicit monitor selection; diagnostic-only helpers still retain them.

Caller inventory

Migrated all user-device selection paths. Remaining raw serialport::available_ports() callers are tool-specific probes in probe_rs, LPC, and ESP32-native code; they do not use the blessed CDC selection path and remain outside this serial health model.

Validation

• soldr cargo test -p fbuild-serial --lib (153 passed, 1 documented ignore)
• soldr cargo test -p fbuild-serial health_tests (2 passed)
• soldr cargo test -p fbuild-deploy rp2040 (80 passed)
• soldr cargo test -p fbuild-deploy teensy (34 passed)
• soldr cargo test -p fbuild-cli port_scan (19 passed)
• soldr cargo test -p fbuild-cli monitor_selection_never_chooses_a_known_unhealthy_endpoint (1 passed)
• soldr cargo test -p fbuild-daemon device_manager (23 passed)
• soldr cargo clippy -p fbuild-serial -p fbuild-deploy -p fbuild-cli -p fbuild-daemon --all-targets -- -D warnings

soldr cargo test -p fbuild-serial additionally runs three existing boards.rs doctests against the non-test online USB-profile registry. They fail in this local worktree because no profile artifact is installed; the unchanged doctest bodies and all 153 library tests demonstrate this is unrelated to this change.

Summary by CodeRabbit

• New Features

  • Serial-port detection now reports endpoint health, problem codes, and device identity details.
  • Port listings include health annotations and clearly identify unavailable or non-selectable endpoints.
  • Deployment diagnostics provide more detailed information when compatible devices cannot be found.

• Bug Fixes

  • Automatic and explicit deployment selection no longer uses known-unhealthy ports.
  • Device discovery better preserves device identity when ports move or reconnect.
  • Bootloader and post-flash detection now avoids phantom or unhealthy endpoints and prefers valid runtime devices.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 531eed72-cbd1-4cf9-bf8c-19cdb001bd8c

📥 Commits

Reviewing files that changed from the base of the PR and between 96a128e and b9e946c.

📒 Files selected for processing (13)

• crates/fbuild-cli/src/cli/deploy.rs
• crates/fbuild-cli/src/cli/port_scan.rs
• crates/fbuild-cli/src/cli/serial_probe.rs
• crates/fbuild-daemon/src/device_manager.rs
• crates/fbuild-daemon/src/device_manager/tests.rs
• crates/fbuild-daemon/src/handlers/operations/deploy_port.rs
• crates/fbuild-deploy/src/rp2040.rs
• crates/fbuild-deploy/src/rp2040_target.rs
• crates/fbuild-deploy/src/teensy/halfkay_probe.rs
• crates/fbuild-deploy/src/teensy/port_discovery.rs
• crates/fbuild-serial/src/boards.rs
• crates/fbuild-serial/src/bootloader_watcher.rs
• crates/fbuild-serial/src/ports.rs

---

📝 Walkthrough

Walkthrough

Serial enumeration now returns DetectedPort records containing health and host identity metadata. CLI, daemon, RP2040, and Teensy paths consume these records for diagnostics, caching, selection, and deployment port reacquisition.

Changes

Serial port health model

Layer / File(s)	Summary
Detected-port health model crates/fbuild-serial/src/ports.rs	Adds PortHealth and DetectedPort, classifies Windows PnP observations, preserves instance identities, and returns enriched records from available_ports().
CLI and daemon propagation crates/fbuild-cli/src/cli/*, crates/fbuild-daemon/src/*	CLI scan and probe output health metadata and avoids known-unhealthy matches; monitor selection rejects unhealthy endpoints; daemon state preserves health and host identities.
Deployment discovery and diagnostics crates/fbuild-deploy/src/*, crates/fbuild-serial/src/boards.rs, crates/fbuild-serial/src/bootloader_watcher.rs	Deployment candidate records carry health and identity metadata, while Teensy, board, and bootloader discovery exclude known-unhealthy ports where applicable.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
participant WindowsPnP
participant available_ports
participant CLI
participant DeviceManager
participant DeploymentDiscovery
WindowsPnP->>available_ports: provide port observations and identities
available_ports->>CLI: return DetectedPort records
available_ports->>DeviceManager: return DetectedPort records
available_ports->>DeploymentDiscovery: return DetectedPort records
CLI->>CLI: render health or reject unhealthy selection
DeviceManager->>DeviceManager: cache health and identities
DeploymentDiscovery->>DeploymentDiscovery: filter unhealthy candidates

Loading

Possibly related issues

• fix(rp2040): reject phantom CDC ports and give recoverable BOOTSEL guidance #1147 — Shares the RP2040 CDC health-aware candidate handling and rejection of unhealthy endpoints.
• meta: Windows USB phantom-device detection and recoverable native-USB deployment #1149 — Covers the broader Windows phantom-device health tracking and propagation implemented across these paths.

Possibly related PRs

• FastLED/fbuild#1011 — Modifies the same Windows serial enumeration pathway and related CLI and Teensy consumers.
• FastLED/fbuild#1053 — Both changes update RP2040 CDC candidate cataloguing.
• FastLED/fbuild#1060 — Both changes modify Teensy CDC discovery and selection logic.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/1146-port-health

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}