fix(dfu): retry dfu-util flash on macOS detach failure

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/en/api-guides/dfu.rst

@@ -161,7 +161,7 @@ Common Errors and Known Issues
 
 - The reason for ``No DFU capable USB device available`` could be that the USB driver was not properly installed on Windows (see :ref:`api_guide_dfu_flash_win`), udev rule was not setup on Linux (see :ref:`api_guide_dfu_flash_udev`) or the device is not in bootloader mode.
 
-- Flashing with ``dfu-util`` on Windows fails on the first attempt with error ``Lost device after RESET?``. Please retry the flashing and it should succeed the next time.
+- Flashing with ``dfu-util`` on Windows or macOS may fail on the first attempt with error ``Lost device after RESET?``. ``idf.py dfu-flash`` retries once automatically. If flashing still fails, run ``idf.py dfu-flash`` again manually.
 
 
 .. only:: SOC_SUPPORTS_SECURE_DL_MODE

docs/zh_CN/api-guides/dfu.rst

@@ -161,7 +161,7 @@ Zadig 工具可能会检测到 {IDF_TARGET_NAME} 的多个 USB 接口。请 **
 
 - 出现 ``No DFU capable USB device available`` 错误的原因可能是在 Windows 上没有正确安装 USB 驱动程序（请参考 :ref:`api_guide_dfu_flash_win`），或是未在 Linux 上设置 Udev 规则（请参考 :ref:`api_guide_dfu_flash_udev`），或是设备未处于引导加载程序模式。
 
-- 在 Windows 上使用 ``dfu-util`` 第一次烧录失败，并出现 ``Lost device after RESET?`` 错误信息。出现此问题时，请重新烧录一次，再次烧录应该会成功。
+- 在 Windows 或 macOS 上使用 ``dfu-util`` 第一次烧录可能失败，并出现 ``Lost device after RESET?`` 错误信息。``idf.py dfu-flash`` 会自动重试一次。如果仍然失败，请手动再次运行 ``idf.py dfu-flash``。
 
 
 .. only:: SOC_SUPPORTS_SECURE_DL_MODE

tools/cmake/run_dfu_util.cmake

@@ -23,6 +23,13 @@ endif()
 message("Command list: ${CMD}")
 execute_process(COMMAND ${CMD} RESULT_VARIABLE result)
 
+# dfu-util may fail on the first attempt while switching from runtime to DFU mode,
+# e.g. with "Lost device after RESET?" on Windows/macOS. Retry once.
+if(${result} AND NOT ${ESP_DFU_LIST})
+    message(WARNING "${TOOL} failed, retrying once...")
+    execute_process(COMMAND ${CMD} RESULT_VARIABLE result)
+endif()
+
 if(${result})
     message(FATAL_ERROR "${TOOL} failed")
 endif()