feat(bundle): fold debug capture into support bundle (2026.6.16.2-23BD)

Switch live Picos to debug input during bundle capture, harvest packet diagnostics, and restore the original persona afterward.

Keep lower-level diagnostic commands out of normal help and support guidance. Treat RP2350 UF2 flash resets like cold boots when saved credentials exist.

Author: RealWhyKnot

bridge/src/cmd_bundle/manifest.rs

@@ -8,7 +8,7 @@ use crate::{config, logfile};
 
 use super::collect::BUNDLE_LOG_FILES_PER_PREFIX;
 
-pub(super) const BUNDLE_SCHEMA_VERSION: u8 = 19;
+pub(super) const BUNDLE_SCHEMA_VERSION: u8 = 20;
 
 #[derive(Clone, Debug, Serialize)]
 pub(super) struct ManifestPicoCapture {
@@ -175,6 +175,8 @@ pub(super) async fn build_manifest(
             "BOOTSEL drives are inventoried when present.",
             "Offline Pico boards are represented from the local diagnostic cache and saved config when available.",
             "Debug input mode uses the XInput USB shape and logs raw USB IN/OUT packet samples for adapter reverse engineering.",
+            "For each live Pico, bundle attempts an automatic debug input capture cycle: switch to debug mode, wait for USB polling, harvest GET_LOG, then restore the original persona.",
+            "If the automatic debug input cycle cannot complete, bundle-capture.txt records the failed step, duration, and reason.",
             "While debug input mode is streaming, the bridge periodically drains the Pico diag ring into retained host packet logs so later bundles can include them.",
             "When bundle finds a live Pico already in debug input mode, it performs a bundle-time GET_LOG harvest and records the harvest health in that Pico's usb-packets.txt.",
             "Retained debug packet logs include per-harvest health records for GET_LOG duration, chunks, lost bytes, packet counts, and failures.",

bridge/src/cmd_bundle/mod.rs

@@ -27,7 +27,8 @@ use zip::write::SimpleFileOptions;
 use zip::ZipWriter;
 
 use crate::{
-    cmd_run, cmd_usb_diag, config, debug_packets, journal, pico_cache, pico_state, protocol,
+    cmd_persona, cmd_run, cmd_usb_diag, config, debug_packets, journal, pico_cache, pico_mode,
+    pico_state, protocol,
 };
 
 use collect::{bundle_log_prefix, collect_crash_file_names, collect_setup_transcript_names};
@@ -50,6 +51,9 @@ use usb_packet_summary::{
 };
 
 const BUNDLE_DEBUG_PACKET_HARVEST_TIMEOUT: Duration = Duration::from_secs(2);
+const BUNDLE_DEBUG_PERSONA_WAIT: Duration = Duration::from_secs(60);
+const BUNDLE_DEBUG_USB_SETTLE: Duration = Duration::from_secs(3);
+const BUNDLE_RESTORE_PERSONA_WAIT: Duration = Duration::from_secs(60);
 
 /// Structured result of a bundle build. Returned by `build_bundle` so
 /// callers get a typed answer without
@@ -107,6 +111,12 @@ struct RetainedDebugPacketLog {
     text: String,
 }
 
+#[derive(Clone, Debug)]
+struct BundleUsbPacketCapture {
+    text: String,
+    debug_target: Option<cmd_run::PicoTarget>,
+}
+
 #[derive(Default)]
 struct CaptureLog {
     lines: Vec<String>,
@@ -763,7 +773,7 @@ async fn capture_usb_diag_text() -> UsbDiagBundle {
                      Suggested next step:\n\
                      - Make sure the Pico is powered, has joined Wi-Fi, and is still plugged into the console adapter.\n\
                      - Run `couchlink.exe bundle` again immediately after the failure.\n\
-                     - If the Pico is on Wi-Fi but broadcast discovery is blocked, run `couchlink.exe doctor` once so the last-known IP is saved.\n\n\
+                     - If the Pico is on Wi-Fi but broadcast discovery is blocked, choose `Enter Pico IP manually` from the guided menu once, then run bundle again.\n\n\
                      Diagnostic details:\n\
                      error={e:#}\n"
                 ),
@@ -1065,8 +1075,15 @@ async fn capture_one_pico(
         pico_state_status = target_pico_state_status;
         pico_diag_status = target_pico_diag_status;
         pico_diag_text = target_pico_diag_text;
-        usb_packets_text =
+        let packet_capture =
             bundle_usb_packets_for_target(&seed.uid, target, &pico_diag_text, capture_log).await;
+        if let Some(debug_target) = packet_capture.debug_target.as_ref() {
+            snapshot =
+                pico_cache::PicoStateSnapshot::from_target("bundle-debug-capture", debug_target)
+                    .with_outcome("bundle: automatic debug input capture");
+            pico_cache::record(snapshot.clone());
+        }
+        usb_packets_text = packet_capture.text;
         usb_diag_status = target_usb_diag_status;
         usb_diag_text = target_usb_diag_text;
         state_json_from_snapshot(&snapshot)
@@ -1154,11 +1171,153 @@ async fn bundle_usb_packets_for_target(
     target: &cmd_run::PicoTarget,
     fallback_diag_text: &str,
     capture_log: &mut CaptureLog,
-) -> String {
-    if target.persona != protocol::Persona::Debug {
-        return usb_packets_text_from_diag(uid, fallback_diag_text);
+) -> BundleUsbPacketCapture {
+    if target.persona == protocol::Persona::Debug {
+        return BundleUsbPacketCapture {
+            text: harvest_debug_packets_for_target(uid, target, fallback_diag_text, capture_log)
+                .await,
+            debug_target: Some(target.clone()),
+        };
+    }
+
+    let original_persona = target.persona;
+    let started = Instant::now();
+    let mut note = String::new();
+    match pico_mode::request_set_persona(target, protocol::Persona::Debug).await {
+        Ok(()) => {
+            capture_log.record(
+                format!("per_pico.{uid}.debug_cycle_request"),
+                started,
+                "sent",
+                1,
+                format!("from={} to=debug", original_persona.label()),
+            );
+        }
+        Err(e) => {
+            capture_log.record(
+                format!("per_pico.{uid}.debug_cycle_request"),
+                started,
+                "error",
+                0,
+                format!("{e:#}"),
+            );
+            let mut text = usb_packets_text_from_diag(uid, fallback_diag_text);
+            let _ = writeln!(
+                text,
+                "# bundle-debug-cycle status=request_failed from={} error={}",
+                original_persona.label(),
+                sanitize_log_field(&format!("{e:#}"))
+            );
+            return BundleUsbPacketCapture {
+                text,
+                debug_target: None,
+            };
+        }
+    }
+
+    let started = Instant::now();
+    let matched = match cmd_persona::wait_for_persona(
+        &[target.info.unique_id_short],
+        protocol::Persona::Debug,
+        BUNDLE_DEBUG_PERSONA_WAIT,
+    )
+    .await
+    {
+        Ok(matched) => matched,
+        Err(e) => {
+            capture_log.record(
+                format!("per_pico.{uid}.debug_cycle_wait"),
+                started,
+                "error",
+                0,
+                format!("{e:#}"),
+            );
+            let mut text = usb_packets_text_from_diag(uid, fallback_diag_text);
+            let _ = writeln!(
+                text,
+                "# bundle-debug-cycle status=wait_failed from={} error={}",
+                original_persona.label(),
+                sanitize_log_field(&format!("{e:#}"))
+            );
+            return BundleUsbPacketCapture {
+                text,
+                debug_target: None,
+            };
+        }
+    };
+    let observed = format_observed_personas(&matched);
+    let debug_target = matched
+        .iter()
+        .find(|pico| pico.persona == protocol::Persona::Debug)
+        .cloned();
+    capture_log.record(
+        format!("per_pico.{uid}.debug_cycle_wait"),
+        started,
+        if debug_target.is_some() {
+            "confirmed"
+        } else {
+            "not_confirmed"
+        },
+        matched.len(),
+        format!("observed={observed}"),
+    );
+
+    let Some(debug_target) = debug_target else {
+        if let Some(current) = matched.first() {
+            if current.persona != original_persona {
+                restore_persona_after_bundle(uid, current, original_persona, capture_log).await;
+            }
+        }
+        let mut text = usb_packets_text_from_diag(uid, fallback_diag_text);
+        let _ = writeln!(
+            text,
+            "# bundle-debug-cycle status=not_confirmed from={} observed={}",
+            original_persona.label(),
+            observed
+        );
+        return BundleUsbPacketCapture {
+            text,
+            debug_target: None,
+        };
+    };
+
+    capture_log.record_duration(
+        format!("per_pico.{uid}.debug_usb_settle"),
+        BUNDLE_DEBUG_USB_SETTLE.as_millis() as u64,
+        "sleep",
+        0,
+        "allow USB host to enumerate and poll debug input persona",
+    );
+    tokio::time::sleep(BUNDLE_DEBUG_USB_SETTLE).await;
+
+    let text =
+        harvest_debug_packets_for_target(uid, &debug_target, fallback_diag_text, capture_log).await;
+
+    if original_persona != protocol::Persona::Debug {
+        restore_persona_after_bundle(uid, &debug_target, original_persona, capture_log).await;
+        let _ = writeln!(
+            note,
+            "# bundle-debug-cycle restore_requested persona={}",
+            original_persona.label()
+        );
     }
 
+    let mut text = text;
+    if !note.is_empty() {
+        text.push_str(&note);
+    }
+    BundleUsbPacketCapture {
+        text,
+        debug_target: Some(debug_target),
+    }
+}
+
+async fn harvest_debug_packets_for_target(
+    uid: &str,
+    target: &cmd_run::PicoTarget,
+    fallback_diag_text: &str,
+    capture_log: &mut CaptureLog,
+) -> String {
     let started = Instant::now();
     match debug_packets::capture_run_diag_log(target.peer, BUNDLE_DEBUG_PACKET_HARVEST_TIMEOUT)
         .await
@@ -1201,6 +1360,82 @@ async fn bundle_usb_packets_for_target(
     }
 }
 
+async fn restore_persona_after_bundle(
+    uid: &str,
+    target: &cmd_run::PicoTarget,
+    persona: protocol::Persona,
+    capture_log: &mut CaptureLog,
+) {
+    let started = Instant::now();
+    match pico_mode::request_set_persona(target, persona).await {
+        Ok(()) => capture_log.record(
+            format!("per_pico.{uid}.restore_persona_request"),
+            started,
+            "sent",
+            1,
+            format!("persona={}", persona.label()),
+        ),
+        Err(e) => {
+            capture_log.record(
+                format!("per_pico.{uid}.restore_persona_request"),
+                started,
+                "error",
+                0,
+                format!("{e:#}"),
+            );
+            return;
+        }
+    }
+
+    let started = Instant::now();
+    match cmd_persona::wait_for_persona(
+        &[target.info.unique_id_short],
+        persona,
+        BUNDLE_RESTORE_PERSONA_WAIT,
+    )
+    .await
+    {
+        Ok(matched) => {
+            let restored = matched.iter().find(|pico| pico.persona == persona);
+            capture_log.record(
+                format!("per_pico.{uid}.restore_persona_wait"),
+                started,
+                if restored.is_some() {
+                    "confirmed"
+                } else {
+                    "not_confirmed"
+                },
+                matched.len(),
+                format!("observed={}", format_observed_personas(&matched)),
+            );
+            if let Some(restored) = restored {
+                pico_cache::record(
+                    pico_cache::PicoStateSnapshot::from_target("bundle-restore", restored)
+                        .with_outcome(format!("restored_{}", persona.label())),
+                );
+            }
+        }
+        Err(e) => capture_log.record(
+            format!("per_pico.{uid}.restore_persona_wait"),
+            started,
+            "error",
+            0,
+            format!("{e:#}"),
+        ),
+    }
+}
+
+fn format_observed_personas(targets: &[cmd_run::PicoTarget]) -> String {
+    if targets.is_empty() {
+        return "none".to_string();
+    }
+    targets
+        .iter()
+        .map(|target| format!("{}:{}", target.uid_hex(), target.persona.label()))
+        .collect::<Vec<_>>()
+        .join(",")
+}
+
 fn saved_picos_from_config(cfg: &config::Config) -> Vec<config::PicoIdentity> {
     let mut out = Vec::new();
     let mut seen = BTreeSet::new();
@@ -1664,13 +1899,13 @@ fn debug_capture_verdict_text(
     out.push_str("next_steps=\n");
     if summary.aggregate.packet_lines == 0 {
         out.push_str(
-            "- Switch the target Pico to debug input mode, reproduce adapter traffic, then run bundle again.\n",
+            "- Run bundle again with the Pico powered and connected to the adapter; bundle switches to debug input mode and restores the original mode automatically.\n",
         );
         out.push_str(
-            "- Keep the bridge stream running while reproducing the issue so retained debug packet harvests can write debug-packets/*.log.\n",
+            "- If bundle-capture.txt shows debug_cycle_request, debug_cycle_wait, debug_packet_harvest, or GET_LOG failures, use that row's reason as the failure point.\n",
         );
         out.push_str(
-            "- If harvest_statuses shows error, check bundle-capture.txt and debug-packets/*.log for GET_LOG failures and timing.\n",
+            "- If retained debug-packets/*.log files are present, include the whole bundle; those files contain prior stream-time harvest evidence.\n",
         );
     } else {
         out.push_str(

bridge/src/cmd_bundle/pico_diag.rs

@@ -223,8 +223,9 @@ impl DiagOutcome {
                 &[
                     "Run `couchlink setup` to provision a Pico (flash + Wi-Fi).",
                     "Or, if a Pico is already running on your LAN, run \
-                     `couchlink doctor` -- if discovery succeeds it will be \
-                     recorded in config and the next bundle can probe it.",
+                     `couchlink bundle` from the bridge PC and choose \
+                     `Enter Pico IP manually` from the menu if broadcast \
+                     discovery is blocked.",
                 ],
                 &[],
             ),
@@ -288,7 +289,7 @@ impl DiagOutcome {
                      `couchlink setup`.",
                     "If you have multiple network adapters, make sure the bridge \
                      is allowed through Windows Firewall on the active profile. \
-                     `couchlink doctor` will surface a firewall mismatch.",
+                     `couchlink bundle` includes the firewall and network snapshot.",
                 ],
                 &[("error", reason)],
             ),

bridge/src/cmd_configure_wifi.rs

@@ -148,7 +148,7 @@ async fn handle_running_picos(mut picos: Vec<cmd_run::PicoTarget>) -> Result<Opt
                 .context(
                     "the Pico did not reappear as setup-mode USB. If this firmware is older, \
                      update it with the newest ZIP first; otherwise unplug/replug the Pico and \
-                     run `couchlink doctor`.",
+                     run `couchlink bundle`.",
                 )
         }
         _ => Ok(None),
@@ -193,8 +193,10 @@ async fn print_discovered_pico_ips(before: BTreeSet<u32>) -> Result<()> {
         let now = Instant::now();
         if now >= deadline {
             println!("No Pico replied yet.");
-            println!("Run `couchlink test discover --all` after the Pico has joined Wi-Fi.");
-            println!("If your router shows its IP, run `couchlink test discover --ip <ip>`.");
+            println!("If your router shows its IP, choose `Enter Pico IP manually` from the menu.");
+            println!(
+                "If it still fails, run `couchlink bundle` and attach the zip to a bug report."
+            );
             return Ok(());
         }
         if now >= next_beat {

bridge/src/cmd_doctor.rs

@@ -46,22 +46,6 @@ pub async fn run() -> Result<()> {
     Ok(())
 }
 
-pub async fn run_interactive() -> Result<()> {
-    let summary = run_checks().await?;
-    if !summary.setup_complete && summary.fails == 0 {
-        println!("(note: setup is not complete yet; use `Update Pico firmware`, then `Set up or change Wi-Fi`.)");
-    }
-    if summary.fails > 0 {
-        println!();
-        println!("Health check found a blocking problem.");
-        println!("Use `Create support bundle` if you need to send the details.");
-    } else if summary.warns > 0 {
-        println!();
-        println!("Health check finished with warnings. Warnings do not always block streaming.");
-    }
-    Ok(())
-}
-
 async fn run_checks() -> Result<DoctorSummary> {
     tracing::info!("doctor: starting, bridge v{}", env!("CARGO_PKG_VERSION"));
     println!("couchlink doctor v{}", env!("CARGO_PKG_VERSION"));