feat(teensy): comprehensive deployer state machine (closes #433, #432)

Replaces the bare `teensy_loader_cli` wrapper with a state machine that
addresses the wedged-Windows-host failure modes catalogued in #433:

* `soft_reboot.rs` — baud-134 trigger so a running user firmware can be
  flashed unattended (no program-button press); also fixes #432
  (`Soft reboot is not implemented for Win32`).
* `halfkay_probe.rs` — confirms the CDC port left the bus after the
  baud-134 trigger.
* `flash.rs` — bounded retry+backoff around `teensy_loader_cli` for the
  WinUSB "error writing to Teensy" quirk that fires 6/10 cycles.
* `port_discovery.rs` — pre-flash port snapshot + post-flash new-CDC-ACM
  detection; surfaces the freshly enumerated port through
  `DeploymentResult.port`.
* `first_byte_probe.rs` — advisory probe that warns when a successful
  flash produces zero serial bytes (typical `setup()`-hang signature).
* `usb_type.rs` — best-effort read of the build's `usb_type` and
  advisory when no Serial endpoint exists (`USB_RAWHID`, …).
* Two-tier timeouts (`flash_timeout_secs` vs
  `wait_for_halfkay_timeout_secs`) so first-flash button-press scenarios
  don't kill the loader at 60s.
* Env escape hatches: `FBUILD_TEENSY_FLASH_RETRIES`,
  `FBUILD_TEENSY_FIRST_BYTE_TIMEOUT_SECS`,
  `FBUILD_TEENSY_DISABLE_BAUD_134_TRIGGER`.

Daemon's `/api/deploy` now forwards `DeploymentResult.port` to the
post-deploy monitor (failure mode #7) so re-enumeration to a new COM
name doesn't leave the monitor on the dead pre-flash port.

Public API of `TeensyDeployer::new` / `from_board_config` is unchanged;
`TeensyLoaderParams` gains opt-in fields with sensible defaults so the
daemon dispatch site needs no code change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zackees

crates/fbuild-build/src/symbol_analyzer.rs

@@ -408,6 +408,7 @@ pub fn format_markdown_report(map: &FineGrainedSymbolMap, top_n: usize) -> Strin
 ///   2. `<dir>/.fbuild/build/**/firmware.elf` (fbuild native output).
 ///   3. `<dir>/.pio/build/**/firmware.elf` (PlatformIO output).
 ///   4. Any `*.elf` directly inside `<dir>`.
+///
 /// Returns the most recently-modified candidate when multiple match.
 pub fn discover_elf_in_project(project_dir: &Path) -> Option<PathBuf> {
     // 1. build_info.json

crates/fbuild-core/src/symbol_analysis/mod.rs

@@ -690,6 +690,5 @@ fn sym_type_for_synth(output_section: &str) -> char {
     }
 }
 
-
 #[cfg(test)]
 mod tests;

crates/fbuild-core/src/symbol_analysis/tests.rs

@@ -19,9 +19,8 @@ fn parse_nm_line_skips_unsized() {
 
 #[test]
 fn extract_archive_from_pio_path() {
-    let (arc, obj) = extract_archive_and_object(
-        ".pio/build/esp32s3/lib0d9/libFastLED.a(fl.channels+.cpp.o)",
-    );
+    let (arc, obj) =
+        extract_archive_and_object(".pio/build/esp32s3/lib0d9/libFastLED.a(fl.channels+.cpp.o)");
     assert_eq!(arc.as_deref(), Some("libFastLED.a"));
     assert_eq!(obj, "fl.channels+.cpp.o");
 }

crates/fbuild-daemon/src/handlers/operations/deploy.rs

@@ -684,13 +684,10 @@ pub async fn deploy(
                 Box::new(deployer)
             }
             fbuild_core::Platform::Teensy => {
-                // The TeensyDeployer in fbuild-deploy/src/teensy.rs has been
-                // fully implemented (incl. unit tests for teensy40 / teensy41
-                // board configs) but wasn't dispatched here — issue #430.
-                // Without this arm `bash autoresearch teensyXX --simd` (and
-                // every other Teensy autoresearch flag) failed at the deploy
-                // step with "deployer for Teensy not yet implemented",
-                // blocking FastLED/FastLED#2628 hardware bring-up.
+                // TeensyDeployer state machine (#433) is dispatched here.
+                // Initial wire-up was #430/#431; the deployer itself now owns
+                // baud-134 soft reboot, bounded retry, post-flash port
+                // discovery, and the optional first-byte advisory probe.
                 let board_config =
                     fbuild_config::BoardConfig::from_board_id(&board_id, &deploy_board_overrides)
                         .unwrap_or_else(|_| {
@@ -788,43 +785,44 @@ pub async fn deploy(
         }
     }
 
-    let (deploy_success, deploy_stdout, deploy_stderr, deploy_outcome) = match deploy_result {
-        Ok(Ok(r)) if r.success => (true, Some(r.stdout), Some(r.stderr), r.outcome),
-        Ok(Ok(r)) => {
-            return (
-                StatusCode::INTERNAL_SERVER_ERROR,
-                Json(OperationResponse {
-                    success: false,
-                    request_id,
-                    message: r.message,
-                    exit_code: 1,
-                    output_file: Some(reported_output_file.clone()),
-                    output_dir: reported_output_dir.clone(),
-                    launch_url: None,
-                    stdout: Some(r.stdout),
-                    stderr: Some(r.stderr),
-                }),
-            );
-        }
-        Ok(Err(e)) => {
-            return (
-                StatusCode::INTERNAL_SERVER_ERROR,
-                Json(OperationResponse::fail(
-                    request_id,
-                    format!("deploy error: {}", e),
-                )),
-            );
-        }
-        Err(e) => {
-            return (
-                StatusCode::INTERNAL_SERVER_ERROR,
-                Json(OperationResponse::fail(
-                    request_id,
-                    format!("deploy task panicked: {}", e),
-                )),
-            );
-        }
-    };
+    let (deploy_success, deploy_stdout, deploy_stderr, deploy_outcome, deploy_post_port) =
+        match deploy_result {
+            Ok(Ok(r)) if r.success => (true, Some(r.stdout), Some(r.stderr), r.outcome, r.port),
+            Ok(Ok(r)) => {
+                return (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    Json(OperationResponse {
+                        success: false,
+                        request_id,
+                        message: r.message,
+                        exit_code: 1,
+                        output_file: Some(reported_output_file.clone()),
+                        output_dir: reported_output_dir.clone(),
+                        launch_url: None,
+                        stdout: Some(r.stdout),
+                        stderr: Some(r.stderr),
+                    }),
+                );
+            }
+            Ok(Err(e)) => {
+                return (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    Json(OperationResponse::fail(
+                        request_id,
+                        format!("deploy error: {}", e),
+                    )),
+                );
+            }
+            Err(e) => {
+                return (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    Json(OperationResponse::fail(
+                        request_id,
+                        format!("deploy task panicked: {}", e),
+                    )),
+                );
+            }
+        };
     // Build the "deploy succeeded (...)" prefix used by every
     // monitor-attached and non-monitor-attached response below. Stable
     // wording — see GitHub issue #76 and the DeployOutcome::describe
@@ -834,7 +832,26 @@ pub async fn deploy(
     // Post-deploy monitoring: if monitor_after is set, open the serial port
     // and stream lines checking halt conditions (matching Python behavior).
     if deploy_success && req.monitor_after {
-        let monitor_port = deploy_port_str.unwrap_or_else(|| "/dev/ttyUSB0".to_string());
+        // Prefer the post-flash port name surfaced by the deployer (e.g. the
+        // Teensy state machine in #433 returns the freshly re-enumerated CDC
+        // ACM port, which can differ from the pre-flash `--port`). Fall back
+        // to the caller-supplied port, then to a platform default.
+        let monitor_port = deploy_post_port
+            .clone()
+            .or(deploy_port_str.clone())
+            .unwrap_or_else(|| "/dev/ttyUSB0".to_string());
+        if deploy_post_port
+            .as_deref()
+            .zip(deploy_port_str.as_deref())
+            .is_some_and(|(post, pre)| post != pre)
+        {
+            tracing::info!(
+                "device re-enumerated as {} after flash (was {}); monitor attaching to {}",
+                deploy_post_port.as_deref().unwrap_or(""),
+                deploy_port_str.as_deref().unwrap_or(""),
+                monitor_port,
+            );
+        }
         let baud_rate = 115200u32;
 
         // Open the port for monitoring

crates/fbuild-deploy/src/teensy.rs

@@ -0,0 +1,55 @@
+# Teensy deployer
+
+State machine for `fbuild deploy -e teensyXX` that takes a wedged Windows host
+back to unattended flashing without manual button presses or USB reseats.
+
+Implements the design from [issue
+#433](https://github.com/FastLED/fbuild/issues/433) (which supersedes #432). The
+old single-file `teensy.rs` shipped only the bare `teensy_loader_cli` invocation
+and inherited every failure mode the issue catalogues.
+
+## Module layout
+
+- **`mod.rs`** — `TeensyDeployer` + `TeensyLoaderParams`; orchestrates the state
+  machine below.
+- **`soft_reboot.rs`** — opens the device's CDC ACM port at **baud 134**, the
+  Teensyduino USB stack's magic-baud signal to drop into HalfKay. Replaces the
+  Windows-only `teensy_loader_cli` reboot which prints
+  `Soft reboot is not implemented for Win32`.
+- **`halfkay_probe.rs`** — confirms the CDC port vanished from
+  `serialport::available_ports()` (HalfKay proxy: the device left CDC class for
+  HID), or waits up to `wait_for_halfkay_timeout_secs` for the user to press the
+  program button.
+- **`flash.rs`** — bounded retry loop around `teensy_loader_cli`. Each attempt
+  is a fresh subprocess; stops on first success; surfaces per-attempt diagnostic
+  on the way to exhaustion.
+- **`port_discovery.rs`** — pre-flash port snapshot + post-flash detection of
+  the newly enumerated CDC ACM port. Filled into `DeploymentResult.port` so the
+  post-deploy monitor can attach to the right device.
+- **`first_byte_probe.rs`** — advisory probe that opens the post-flash port and
+  reports whether any byte arrived inside `first_byte_timeout_secs`. Silent
+  firmware is surfaced as a structured diagnostic, not a deploy failure.
+- **`usb_type.rs`** — best-effort read of `usb_type` from the build artifact
+  directory; advises the monitor when the device was built without a Serial
+  endpoint (`USB_MIDI_SERIAL`, `USB_RAWHID`).
+
+## State machine
+
+```
+pre-snapshot → (CDC at port? → baud-134 trigger) → wait-for-HalfKay
+            → flash with retry → wait-for-new-CDC → first-byte probe
+            → DeploymentResult { port: Some(new_port), … }
+```
+
+Failure at any stage returns a `DeploymentResult { success: false, message:
+<stage-specific>, stderr: <last loader output> }` — same envelope the daemon
+already propagates to the CLI verbatim.
+
+## Env escape hatches
+
+- `FBUILD_TEENSY_FLASH_RETRIES` — override `flash_retries` (default 5).
+- `FBUILD_TEENSY_FIRST_BYTE_TIMEOUT_SECS` — override
+  `first_byte_timeout_secs` (default 10, `0` disables).
+- `FBUILD_TEENSY_DISABLE_BAUD_134_TRIGGER` — opt out of the baud-134 trigger
+  (debug aid for the few hosts where `SerialPortBuilder::baud_rate(134)` is not
+  honored).