firmwareloop 0.7.1__tar.gz → 0.7.3__tar.gz

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.7.1
+Version: 0.7.3
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -18,7 +18,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyvisa>=1.14.0
-Requires-Dist: pyvisa-py>=0.7.1
+Requires-Dist: pyvisa-py>=0.7.3
 Requires-Dist: pyserial>=3.5
 Requires-Dist: pytest>=8.0.0
 Requires-Dist: pyocd>=0.36.0
@@ -383,7 +383,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.7.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.7.3)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -393,7 +393,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.7.1）
+## 能力验证状态（v0.7.3）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`
@@ -416,7 +416,9 @@ claude mcp remove --scope user agentic-hil
 | 自动修复闭环（M6 载体） | Simulator Validated -> Real Hardware Validated 待 DUT |
 | NdtBox 数据采集/调试（fw_ndtdbg_status / fw_ndtdbg_measure, ChipSea Fxx IIC） | Implemented（无硬件 Fail-Closed 已验证）-> Real Hardware Validated 待 NdtBox |
 | NdtBox 目标断电复位（fw_ndtdbg_power_cycle, 仅 io10 断电复位, 无写闸门） | Implemented（单测覆盖时序/探针缺失指引）-> Real Hardware Validated 待 NdtBox |
-| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass；双闸门 Fail-Closed）+ v0.7.1 **差分 boot 判据**（真机实测: 擦除后读 0x0000 = 00 00 00 00, 旧"全 FF"判据在该 ROM 上永久误判 → 已改为"仅同一条非平凡应答才熔断", 并提供 `boot_judge: off` 关闭开关） |
+| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass; 2026-09-11 同批文件桥内单体 flash 6/6 pass；双闸门 Fail-Closed）。**v0.7.2 起默认引擎 = 桥内单体 flash**（逐笔 serve 路径现场实测"擦除生效但页写不落地"，保留 `flash_engine: serve` 供 A/B）；差分 boot 判据 + `boot_judge: off` 逃生开关见 0.7.1；**待验收声明：默认引擎路径（Python 组 plan → Popen 桥 → 解析信封）尚待真机验收** |
+| 烧后冷启动冒烟（fw_ndtdbg_flash 默认开, `cold_boot_check`） | Implemented（单测覆盖通过/全 FF/期望不符/关闭；`COLD_BOOT_VERIFY_FAILED` 错误类）-> Real Hardware Validated 待真机 |
+| 串口占用取证（`port_probe` 试开硬结论 + `holder_candidates` 候选名单） | Implemented（试开结论可复现；候选按 cmdline/name 标注置信度） |
 | 抓开机日志（fw_serial_capture + power_cycle_off_ms, 窗口内断电复位） | Implemented（simulator 验证窗口与复位串联）-> Real Hardware Validated 待 NdtBox + DUT |
 
 ---
@@ -434,6 +436,12 @@ claude mcp remove --scope user agentic-hil
 | `fw_ndtdbg_flash` 报 `TARGET_MISMATCH: 烧录校验失败 @0x....` | 校验是**权威判据**（不是探测启发式）。信封带 `stage_timings`/`probe_before_hex`/`probe_hex`/`boot_evidence`/`first_mismatch_*`：`boot_evidence=erase_effective` 说明擦除生效 → 看失配偏移是否恒定（恒定=页写未落地）；`inconclusive` 说明探测无区分度（擦除后读回全 00/全 FF）→ 需人工确认是否真进了 boot；整片重写次数由 `rewrite_times` 控制（默认 3） |
 | 串口 `SERIAL_PORT_ERROR: ... PermissionError(13)` | 端口被 GUI 上位机独占（NDT Debug Tool / STDataCollection.exe、串口助手）→ 关闭占用方后 `fw_serial_open`；残留会话用 `fw_serial_close`（已自动等待/强杀进程，端口释放可验证） |
 | `fw_serial_status` 的 `error_class` 为 `UART_BUSY` | 会话未打开或已被占用 → 先 `fw_serial_open`；残留会话 `fw_serial_close` 清理 |
+| `fw_serial_*` 报 `PermissionError(13)` / `rx_bytes: 0` | 串口被独占：**退出 NDT Debug Tool GUI（STDataCollection.exe）**——它打开时会同时占住 Box 串口与 USB-IIC 通道；失败信封/`fw_serial_status` 的 `suspected_holders` 会直接列出嫌疑进程（注意别杀 MCP server 的 python） |
+| 烧录"擦除生效（probe 从非 00 变 00）但校验读回全 FF"、`pages_written` 已发出 | v0.7.1 及更早的逐笔 serve 路径问题 → v0.7.3 起默认走 `flash_engine: bridge`（桥内单体，与 GUI 同进程模型）；要复现/排查旧行为用 `flash_engine: "serve"` |
+| 长调用（capture/measure）客户端超时 | MCP stdio 循环是**单线程**的：长调用会让同会话其它调用排队（含 3s 的小调用）→ 缩短窗口，或用 `fw_ndtdbg_stream_start` job 模式 |
+| 烧录报 `INCOMPLETE_FLASH` | 桥内 flash 连续 30s 无进度（疑似卡在写入中途）→ **芯片处于半擦写态，勿直接使用，必须重新完整烧录**；信封带 `chip_state: partially_erased` 与 `post_kill_power_cycle`（已尝试复位） |
+| 烧录报 `COLD_BOOT_VERIFY_FAILED` | **Flash 字节已通过逐窗校验，但断电重上电后目标没有有效应答/与期望不符**（现场 `.18` 类问题：GUI 报成功、当场可读，冷启动 `Fw_ver = -1`）→ 按固件冷启动路径排查（看门狗/时钟/外设初始化）；或用 `cold_boot_expect` 指定期望值、`cold_boot_check: false` 关闭 |
+| `fw_serial_status` 的 `port_probe.openable = false` | 端口当前**无法独占打开**（硬结论）→ 看 `holder_candidates`（`source: cmdline` 比 `name` 准，候选≠持有者）确认占用方 |
 
 完整速查表与手工部署细节见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
 

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/README.md

@@ -355,7 +355,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.7.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.7.3)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -365,7 +365,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.7.1）
+## 能力验证状态（v0.7.3）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`
@@ -388,7 +388,9 @@ claude mcp remove --scope user agentic-hil
 | 自动修复闭环（M6 载体） | Simulator Validated -> Real Hardware Validated 待 DUT |
 | NdtBox 数据采集/调试（fw_ndtdbg_status / fw_ndtdbg_measure, ChipSea Fxx IIC） | Implemented（无硬件 Fail-Closed 已验证）-> Real Hardware Validated 待 NdtBox |
 | NdtBox 目标断电复位（fw_ndtdbg_power_cycle, 仅 io10 断电复位, 无写闸门） | Implemented（单测覆盖时序/探针缺失指引）-> Real Hardware Validated 待 NdtBox |
-| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass；双闸门 Fail-Closed）+ v0.7.1 **差分 boot 判据**（真机实测: 擦除后读 0x0000 = 00 00 00 00, 旧"全 FF"判据在该 ROM 上永久误判 → 已改为"仅同一条非平凡应答才熔断", 并提供 `boot_judge: off` 关闭开关） |
+| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass; 2026-09-11 同批文件桥内单体 flash 6/6 pass；双闸门 Fail-Closed）。**v0.7.2 起默认引擎 = 桥内单体 flash**（逐笔 serve 路径现场实测"擦除生效但页写不落地"，保留 `flash_engine: serve` 供 A/B）；差分 boot 判据 + `boot_judge: off` 逃生开关见 0.7.1；**待验收声明：默认引擎路径（Python 组 plan → Popen 桥 → 解析信封）尚待真机验收** |
+| 烧后冷启动冒烟（fw_ndtdbg_flash 默认开, `cold_boot_check`） | Implemented（单测覆盖通过/全 FF/期望不符/关闭；`COLD_BOOT_VERIFY_FAILED` 错误类）-> Real Hardware Validated 待真机 |
+| 串口占用取证（`port_probe` 试开硬结论 + `holder_candidates` 候选名单） | Implemented（试开结论可复现；候选按 cmdline/name 标注置信度） |
 | 抓开机日志（fw_serial_capture + power_cycle_off_ms, 窗口内断电复位） | Implemented（simulator 验证窗口与复位串联）-> Real Hardware Validated 待 NdtBox + DUT |
 
 ---
@@ -406,6 +408,12 @@ claude mcp remove --scope user agentic-hil
 | `fw_ndtdbg_flash` 报 `TARGET_MISMATCH: 烧录校验失败 @0x....` | 校验是**权威判据**（不是探测启发式）。信封带 `stage_timings`/`probe_before_hex`/`probe_hex`/`boot_evidence`/`first_mismatch_*`：`boot_evidence=erase_effective` 说明擦除生效 → 看失配偏移是否恒定（恒定=页写未落地）；`inconclusive` 说明探测无区分度（擦除后读回全 00/全 FF）→ 需人工确认是否真进了 boot；整片重写次数由 `rewrite_times` 控制（默认 3） |
 | 串口 `SERIAL_PORT_ERROR: ... PermissionError(13)` | 端口被 GUI 上位机独占（NDT Debug Tool / STDataCollection.exe、串口助手）→ 关闭占用方后 `fw_serial_open`；残留会话用 `fw_serial_close`（已自动等待/强杀进程，端口释放可验证） |
 | `fw_serial_status` 的 `error_class` 为 `UART_BUSY` | 会话未打开或已被占用 → 先 `fw_serial_open`；残留会话 `fw_serial_close` 清理 |
+| `fw_serial_*` 报 `PermissionError(13)` / `rx_bytes: 0` | 串口被独占：**退出 NDT Debug Tool GUI（STDataCollection.exe）**——它打开时会同时占住 Box 串口与 USB-IIC 通道；失败信封/`fw_serial_status` 的 `suspected_holders` 会直接列出嫌疑进程（注意别杀 MCP server 的 python） |
+| 烧录"擦除生效（probe 从非 00 变 00）但校验读回全 FF"、`pages_written` 已发出 | v0.7.1 及更早的逐笔 serve 路径问题 → v0.7.3 起默认走 `flash_engine: bridge`（桥内单体，与 GUI 同进程模型）；要复现/排查旧行为用 `flash_engine: "serve"` |
+| 长调用（capture/measure）客户端超时 | MCP stdio 循环是**单线程**的：长调用会让同会话其它调用排队（含 3s 的小调用）→ 缩短窗口，或用 `fw_ndtdbg_stream_start` job 模式 |
+| 烧录报 `INCOMPLETE_FLASH` | 桥内 flash 连续 30s 无进度（疑似卡在写入中途）→ **芯片处于半擦写态，勿直接使用，必须重新完整烧录**；信封带 `chip_state: partially_erased` 与 `post_kill_power_cycle`（已尝试复位） |
+| 烧录报 `COLD_BOOT_VERIFY_FAILED` | **Flash 字节已通过逐窗校验，但断电重上电后目标没有有效应答/与期望不符**（现场 `.18` 类问题：GUI 报成功、当场可读，冷启动 `Fw_ver = -1`）→ 按固件冷启动路径排查（看门狗/时钟/外设初始化）；或用 `cold_boot_expect` 指定期望值、`cold_boot_check: false` 关闭 |
+| `fw_serial_status` 的 `port_probe.openable = false` | 端口当前**无法独占打开**（硬结论）→ 看 `holder_candidates`（`source: cmdline` 比 `name` 准，候选≠持有者）确认占用方 |
 
 完整速查表与手工部署细节见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
 

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/firmwareloop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.7.1
+Version: 0.7.3
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -18,7 +18,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyvisa>=1.14.0
-Requires-Dist: pyvisa-py>=0.7.1
+Requires-Dist: pyvisa-py>=0.7.3
 Requires-Dist: pyserial>=3.5
 Requires-Dist: pytest>=8.0.0
 Requires-Dist: pyocd>=0.36.0
@@ -383,7 +383,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.7.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.7.3)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -393,7 +393,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.7.1）
+## 能力验证状态（v0.7.3）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`
@@ -416,7 +416,9 @@ claude mcp remove --scope user agentic-hil
 | 自动修复闭环（M6 载体） | Simulator Validated -> Real Hardware Validated 待 DUT |
 | NdtBox 数据采集/调试（fw_ndtdbg_status / fw_ndtdbg_measure, ChipSea Fxx IIC） | Implemented（无硬件 Fail-Closed 已验证）-> Real Hardware Validated 待 NdtBox |
 | NdtBox 目标断电复位（fw_ndtdbg_power_cycle, 仅 io10 断电复位, 无写闸门） | Implemented（单测覆盖时序/探针缺失指引）-> Real Hardware Validated 待 NdtBox |
-| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass；双闸门 Fail-Closed）+ v0.7.1 **差分 boot 判据**（真机实测: 擦除后读 0x0000 = 00 00 00 00, 旧"全 FF"判据在该 ROM 上永久误判 → 已改为"仅同一条非平凡应答才熔断", 并提供 `boot_judge: off` 关闭开关） |
+| NdtBox IIC 固件烧录（fw_ndtdbg_flash, .bin/.nfw 整片擦写, 芯海 Fxx） | Real Hardware Validated（84.87.1.1 / 84.87.1.2 真机整片擦写 verify pass; 2026-09-11 同批文件桥内单体 flash 6/6 pass；双闸门 Fail-Closed）。**v0.7.2 起默认引擎 = 桥内单体 flash**（逐笔 serve 路径现场实测"擦除生效但页写不落地"，保留 `flash_engine: serve` 供 A/B）；差分 boot 判据 + `boot_judge: off` 逃生开关见 0.7.1；**待验收声明：默认引擎路径（Python 组 plan → Popen 桥 → 解析信封）尚待真机验收** |
+| 烧后冷启动冒烟（fw_ndtdbg_flash 默认开, `cold_boot_check`） | Implemented（单测覆盖通过/全 FF/期望不符/关闭；`COLD_BOOT_VERIFY_FAILED` 错误类）-> Real Hardware Validated 待真机 |
+| 串口占用取证（`port_probe` 试开硬结论 + `holder_candidates` 候选名单） | Implemented（试开结论可复现；候选按 cmdline/name 标注置信度） |
 | 抓开机日志（fw_serial_capture + power_cycle_off_ms, 窗口内断电复位） | Implemented（simulator 验证窗口与复位串联）-> Real Hardware Validated 待 NdtBox + DUT |
 
 ---
@@ -434,6 +436,12 @@ claude mcp remove --scope user agentic-hil
 | `fw_ndtdbg_flash` 报 `TARGET_MISMATCH: 烧录校验失败 @0x....` | 校验是**权威判据**（不是探测启发式）。信封带 `stage_timings`/`probe_before_hex`/`probe_hex`/`boot_evidence`/`first_mismatch_*`：`boot_evidence=erase_effective` 说明擦除生效 → 看失配偏移是否恒定（恒定=页写未落地）；`inconclusive` 说明探测无区分度（擦除后读回全 00/全 FF）→ 需人工确认是否真进了 boot；整片重写次数由 `rewrite_times` 控制（默认 3） |
 | 串口 `SERIAL_PORT_ERROR: ... PermissionError(13)` | 端口被 GUI 上位机独占（NDT Debug Tool / STDataCollection.exe、串口助手）→ 关闭占用方后 `fw_serial_open`；残留会话用 `fw_serial_close`（已自动等待/强杀进程，端口释放可验证） |
 | `fw_serial_status` 的 `error_class` 为 `UART_BUSY` | 会话未打开或已被占用 → 先 `fw_serial_open`；残留会话 `fw_serial_close` 清理 |
+| `fw_serial_*` 报 `PermissionError(13)` / `rx_bytes: 0` | 串口被独占：**退出 NDT Debug Tool GUI（STDataCollection.exe）**——它打开时会同时占住 Box 串口与 USB-IIC 通道；失败信封/`fw_serial_status` 的 `suspected_holders` 会直接列出嫌疑进程（注意别杀 MCP server 的 python） |
+| 烧录"擦除生效（probe 从非 00 变 00）但校验读回全 FF"、`pages_written` 已发出 | v0.7.1 及更早的逐笔 serve 路径问题 → v0.7.3 起默认走 `flash_engine: bridge`（桥内单体，与 GUI 同进程模型）；要复现/排查旧行为用 `flash_engine: "serve"` |
+| 长调用（capture/measure）客户端超时 | MCP stdio 循环是**单线程**的：长调用会让同会话其它调用排队（含 3s 的小调用）→ 缩短窗口，或用 `fw_ndtdbg_stream_start` job 模式 |
+| 烧录报 `INCOMPLETE_FLASH` | 桥内 flash 连续 30s 无进度（疑似卡在写入中途）→ **芯片处于半擦写态，勿直接使用，必须重新完整烧录**；信封带 `chip_state: partially_erased` 与 `post_kill_power_cycle`（已尝试复位） |
+| 烧录报 `COLD_BOOT_VERIFY_FAILED` | **Flash 字节已通过逐窗校验，但断电重上电后目标没有有效应答/与期望不符**（现场 `.18` 类问题：GUI 报成功、当场可读，冷启动 `Fw_ver = -1`）→ 按固件冷启动路径排查（看门狗/时钟/外设初始化）；或用 `cold_boot_expect` 指定期望值、`cold_boot_check: false` 关闭 |
+| `fw_serial_status` 的 `port_probe.openable = false` | 端口当前**无法独占打开**（硬结论）→ 看 `holder_candidates`（`source: cmdline` 比 `name` 准，候选≠持有者）确认占用方 |
 
 完整速查表与手工部署细节见 [`Fwloop_setup_pack/README.md`](Fwloop_setup_pack/README.md)。
 

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/firmwareloop.egg-info/requires.txt

@@ -1,5 +1,5 @@
 pyvisa>=1.14.0
-pyvisa-py>=0.7.1
+pyvisa-py>=0.7.3
 pyserial>=3.5
 pytest>=8.0.0
 pyocd>=0.36.0

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firmwareloop"
-version = "0.7.1"
+version = "0.7.3"
 description = "AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)"
 readme = "README.md"
 authors = [
@@ -14,7 +14,7 @@ license = { text = "MIT" }
 requires-python = ">=3.10"
 dependencies = [
     "pyvisa>=1.14.0",
-    "pyvisa-py>=0.7.1",
+    "pyvisa-py>=0.7.3",
     "pyserial>=3.5",
     "pytest>=8.0.0",
     "pyocd>=0.36.0",

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/tools/__init__.py

@@ -2,4 +2,4 @@
 FirmwareLoop - AI Agent Firmware Development and Lab Automation Platform.
 """
 
-__version__ = "0.7.1"
+__version__ = "0.7.3"

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/tools/fw_mcp_server.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.7.1).
+fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.7.3).
 
 Exposes high-level firmware engineering and hardware management tools to AI Coding
 Agents (Antigravity CLI, Claude Code CLI, Qoder IDE, CodeBuddy IDE, Cursor) via the Model Context
@@ -332,7 +332,7 @@ def handle_fw_ndtdbg_write_reg(args: Dict[str, Any]) -> Dict[str, Any]:
 def handle_fw_ndtdbg_flash(args: Dict[str, Any]) -> Dict[str, Any]:
     """Erase + flash a .bin/.nfw image onto the NdtBox target chip (ChipSea Fxx) over IIC.
 
-    P1-3 (0.7.1): 去掉按签名重试 —— "TARGET_MISMATCH @0x0000" 正是"根本没进 boot"的
+    P1-3 (0.7.3): 去掉按签名重试 —— "TARGET_MISMATCH @0x0000" 正是"根本没进 boot"的
     特征签名 (旧 boot 判据假阳的同一条错误路径), 盲目重试只会重复同一失败路径。
     整片重写 (<= rewrite_times) 现由 flash_exec 内部完成, 结果带 rewrite_count;
     BOOT_NOT_ENTERED 直接返回指引 (需断电重启, 重试无意义)。
@@ -346,6 +346,15 @@ def handle_fw_ndtdbg_flash(args: Dict[str, Any]) -> Dict[str, Any]:
         cmd.extend(["--rewrite-times", str(max(0, int(args["rewrite_times"])))])
     if args.get("boot_judge"):
         cmd.extend(["--boot-judge", str(args["boot_judge"])])
+    if args.get("flash_engine"):
+        cmd.extend(["--flash-engine", str(args["flash_engine"])])
+    # 冷启动冒烟 (评审 §4): 默认开 -> CLI 默认即开, 仅显式 false 时加关闭旗标
+    if args.get("cold_boot_check") is False:
+        cmd.append("--no-cold-boot-check")
+    if args.get("cold_boot_reg") is not None:
+        cmd.extend(["--cold-boot-reg", str(int(args["cold_boot_reg"]))])
+    if args.get("cold_boot_expect"):
+        cmd.extend(["--cold-boot-expect", str(args["cold_boot_expect"])])
     if args.get("confirm"):
         cmd.append("--confirm")
     _ndtdbg_reg_args(args, cmd)
@@ -1679,7 +1688,7 @@ TOOLS_REGISTRY = {
         "handler": handle_fw_ndtdbg_status,
     },
     "fw_ndtdbg_measure": {
-        "description": "Poll NdtBox IIC debug data stream (ChipSea Fxx) for N seconds: frame count, checksum errors, channel samples. Read-only; firmware upgrade is a separate future capability.",
+        "description": "Poll NdtBox IIC debug data stream (ChipSea Fxx) for N seconds: frame count, checksum errors, channel samples. Read-only. NOTE: the MCP stdio loop is single-threaded, so a long call blocks every other call in the same session (a concurrent short call just waits and may time out client-side) - keep duration_seconds small; use fw_ndtdbg_stream_start for long captures.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -1772,7 +1781,7 @@ TOOLS_REGISTRY = {
         "handler": handle_fw_ndtdbg_write_reg,
     },
     "fw_ndtdbg_flash": {
-        "description": "Erase and flash a .bin/.nfw firmware image onto the NdtBox target chip (ChipSea Fxx) over IIC via NdtDebugTool (power-cycle reset into boot -> erase magic AA 55 A5 5A -> differential BOOT JUDGEMENT: 0x0000 is sampled once BEFORE the power cycle and once AFTER the erase; only an identical NON-TRIVIAL reading (the same App answering before and after a command only the boot ROM executes) raises BOOT_NOT_ENTERED - all-00/all-FF/no-ACK are inconclusive and proceed, because a real ROM may answer 0x0000 with 00 00 00 00 after erase -> 128B page writes -> 256B read-back verify = the authoritative criterion, whole-chip rewrite on mismatch -> finish 'PASs'). DESTRUCTIVE full-chip erase: requires lab.yaml ndtdbg.write_allowed: true AND confirm: true, otherwise PERMISSION_DENIED.",
+        "description": "Erase and flash a .bin/.nfw firmware image onto the NdtBox target chip (ChipSea Fxx) over IIC via NdtDebugTool. Default engine 'bridge' runs the whole UpdateFW sequence in ONE 32-bit process holding both the IIC and power-rail handles (power-cycle into boot -> erase magic AA 55 A5 5A -> 128B page writes -> 256B read-back verify per window = the authoritative criterion -> finish 'PASs'), which is the path validated 6/6 on real hardware; engine 'serve' drives one raw transaction per page from Python (kept for A/B reproduction - field evidence showed it can report erase-effective but write nothing on the same frames). DESTRUCTIVE full-chip erase: requires lab.yaml ndtdbg.write_allowed: true AND confirm: true, otherwise PERMISSION_DENIED.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -1806,7 +1815,26 @@ TOOLS_REGISTRY = {
                 "boot_judge": {
                     "type": "string",
                     "enum": ["diff", "off"],
-                    "description": "Boot-probe criterion. 'diff' (default): compare 0x0000 before the power cycle vs after the erase, and raise BOOT_NOT_ENTERED only when both reads are identical NON-TRIVIAL data (proof the same running App answered the erase magic). 'off': only record probe evidence (probe_before_hex/probe_hex/boot_evidence) and never block - the 256B read-back verify stays the sole criterion, i.e. exactly the bridge/GUI behaviour. Use 'off' if a target ROM reports an unexpected 0x0000 signature",
+                    "description": "Boot-probe criterion (serve engine only). 'diff' (default): compare 0x0000 before the power cycle vs after the erase, and raise BOOT_NOT_ENTERED only when both reads are identical NON-TRIVIAL data (proof the same running App answered the erase magic). 'off': only record probe evidence (probe_before_hex/probe_hex/boot_evidence) and never block - the 256B read-back verify stays the sole criterion, i.e. exactly the bridge/GUI behaviour. Use 'off' if a target ROM reports an unexpected 0x0000 signature",
+                },
+                "flash_engine": {
+                    "type": "string",
+                    "enum": ["bridge", "serve"],
+                    "description": "Flash transport. 'bridge' (default): whole sequence inside one 32-bit process, frames passed once via stdin, both device handles held - real-hardware validated (6/6). 'serve': one raw I2C transaction per page driven from Python (kept for A/B; field evidence: same frames reported 'erase effective' yet wrote nothing). Use 'serve' only to reproduce/diagnose that case",
+                },
+                "cold_boot_check": {
+                    "type": "boolean",
+                    "description": "Post-flash cold-boot smoke test (default true, recommended): power-cycle the target, then read cold_boot_reg and decide whether the firmware actually runs. Byte-level read-back verification cannot catch 'image flashed OK but the device is dead after power-up' (field case: GUI said Success and read back fine, but Fw_ver = -1 after a real power cycle). Returns COLD_BOOT_VERIFY_FAILED with the raw bytes read vs expected - the flash itself is already verified, so decide whether the failure is expected (e.g. a bootloader-only image or a register that legitimately has no content). Set false to skip",
+                    "default": True,
+                },
+                "cold_boot_reg": {
+                    "type": "integer",
+                    "description": "Register read for the cold-boot check (default 0x10 = firmware version)",
+                    "default": 16,
+                },
+                "cold_boot_expect": {
+                    "type": "string",
+                    "description": "Optional expected hex for cold-boot verification (e.g. '51 17 64 11'); when omitted the check only requires a meaningful (non-all-00/FF) answer",
                 },
                 "dll_dir": {
                     "type": "string",
@@ -2242,7 +2270,7 @@ TOOLS_REGISTRY = {
         "handler": handle_fw_serial_parse,
     },
     "fw_serial_capture": {
-        "description": "Serial assistant: synchronous window capture - record the RX stream for duration_ms into a timestamped CSV (t_rel_ms, dir, hex, printable) for offline analysis/plotting (real-time-curve equivalent; plotting happens in your tools/Agent from the CSV). Pass power_cycle_off_ms to fire an NdtBox power-cycle inside the window and capture boot-time prints (port is opened first). duration_ms <= 90000; long background captures (job mode) are a planned follow-up.",
+        "description": "Serial assistant: synchronous window capture - record the RX stream for duration_ms into a timestamped CSV (t_rel_ms, dir, hex, printable) for offline analysis/plotting (real-time-curve equivalent; plotting happens in your tools/Agent from the CSV). Pass power_cycle_off_ms to fire an NdtBox power-cycle inside the window and capture boot-time prints (port is opened first). duration_ms <= 90000; long background captures (job mode) are a planned follow-up. NOTE: the MCP stdio loop is single-threaded, so this call blocks every other call in the same session for the whole window (your client may time out first) - prefer windows of a few seconds and call it when nothing else needs the box.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -2307,7 +2335,7 @@ def process_request(req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
                 },
                 "serverInfo": {
                     "name": "firmwareloop",
-                    "version": "0.7.1"
+                    "version": "0.7.3"
                 }
             }
         }
@@ -2442,7 +2470,7 @@ def _settle_stashed_entrypoints(stashed) -> None:
 def handle_cli_update() -> int:
     """Handle `firmwareloop update` command."""
     print("============================================================")
-    print("  FirmwareLoop Auto-Updater (v0.7.1)")
+    print("  FirmwareLoop Auto-Updater (v0.7.3)")
     print("============================================================")
 
     is_git_repo = os.path.exists(os.path.join(REPO_ROOT, ".git"))
@@ -2873,7 +2901,7 @@ def set_ndtdbg_dlldir(dll_path: str) -> str:
 def handle_cli_setup() -> int:
     """Handle `firmwareloop setup` command: simultaneously configure Antigravity CLI, Claude Code CLI, Qoder IDE, and CodeBuddy IDE."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.7.1)")
+    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.7.3)")
     print("============================================================")
     print("")
 
@@ -2998,7 +3026,7 @@ def handle_cli_setup() -> int:
 def handle_cli_init(chip: Optional[str] = None, upgrade: bool = False) -> int:
     """Handle `firmwareloop init [target_chip]` command."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Project Initializer (v0.7.1)")
+    print("  FirmwareLoop Multi-Agent Project Initializer (v0.7.3)")
     print("============================================================")
     cwd = os.getcwd()
     print(f"[*] Initializing multi-agent guidelines & bench config in:\n    {cwd}\n")
@@ -3031,7 +3059,7 @@ def handle_cli_init(chip: Optional[str] = None, upgrade: bool = False) -> int:
 
 
 def print_cli_help() -> None:
-    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.7.1)
+    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.7.3)
 
 Usage:
   fwloop [command]   (or: firmwareloop [command])
@@ -3077,7 +3105,7 @@ def main() -> None:
                 sys.exit(2)
             sys.exit(handle_cli_ndtdebugtool(args[1]))
         elif cmd in ["version", "-v", "--version"]:
-            print("FirmwareLoop v0.7.1")
+            print("FirmwareLoop v0.7.3")
             sys.exit(0)
         elif cmd in ["help", "-h", "--help"]:
             print_cli_help()

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/tools/lib/ndtdbg.py

@@ -11,6 +11,7 @@ import contextlib
 import json
 import os
 import queue
+import re
 import subprocess
 import sys
 import threading
@@ -402,13 +403,19 @@ class NdtBoxIo:
         return self._persistent
 
     def _with_sess(self, fn):
+        """在活跃会话上执行单事务。
+
+        `with io.session():` 块内 self._persistent 已置位 ⇒ 复用同一个 32 位桥进程与
+        USB 会话 (事务延迟 = 一次管道往返); 块外为即用即关 (spawn+open+事务+close)。
+        (现场曾怀疑此处未复用导致 77ms/页——每笔新 spawn 是 ~1.5s 量级, 与 77ms 不符,
+        故复用确实生效; 该现象的真因见 flash_exec 的引擎说明。)
+        """
         sess = self._get_live_sess()
-        if self._persistent is sess:
-            return fn(sess)
         try:
             return fn(sess)
         finally:
-            sess.close()
+            if sess is not self._persistent:
+                sess.close()
 
     # -- 芯片无关原语 (对齐 IIC.cs / I2CProxy.cs) --
 
@@ -424,7 +431,18 @@ class NdtBoxIo:
         return self._with_sess(lambda s: s.read_reg(reg, length))
 
     def write_reg(self, reg: int, data: bytes) -> None:
-        self._with_sess(lambda s: s.write_reg(reg, data))
+        try:
+            self._with_sess(lambda s: s.write_reg(reg, data))
+        except NdtBoxError as exc:
+            if exc.error_class != "TARGET_MISMATCH":
+                raise
+            # P2-1: 写 NACK ≠ 从机死了 —— 现场实证"读正常但写稳定失败"
+            raise NdtBoxError(
+                exc.error_class, exc.message, exc.detail,
+                {"hint": "写事务无应答与'从机整体不应答'不同: 若紧随其后的读事务正常, 更可能是"
+                         "该寄存器不可写/写保护, 或目标固件未实现该写寄存器 (也可能是写事务"
+                         "超长/格式不符)。先用 fw_ndtdbg_read_reg 回读邻居寄存器确认链路仍活, "
+                         "再核对寄存器语义"}) from exc
 
     def raw_write_read(self, write: bytes, read_len: int = 0) -> bytes | None:
         """原始 IIC 事务 (对齐 IIC.WriteRead): 写 write 字节(不含从机地址) 再读 read_len 字节。
@@ -660,7 +678,223 @@ class NdtBoxIo:
                 return None
             raise
 
+    def _post_kill_recover(self) -> dict:
+        """kill 之后的兜底恢复 (best-effort): 断电复位一次, 让目标离开半擦写/写中途态。
+
+        失败不上抛 (本身已在错误路径上), 结果并入错误信封的 post_kill_power_cycle 字段。
+        """
+        try:
+            self.vbrt_reset(DEFAULT_OFF_MS)
+            return {"post_kill_power_cycle": "ok"}
+        except Exception as exc:  # noqa: BLE001
+            return {"post_kill_power_cycle": f"failed: {type(exc).__name__}: {exc}"}
+
+    def _bridge_plan_json(self, plan: dict) -> str:
+        """桥 flash action 的 stdin plan (只含桥认识的键)。"""
+        return json.dumps({
+            "off_ms": int(plan.get("off_ms", DEFAULT_OFF_MS)),
+            "erase_ms": int(plan.get("erase_ms", 2000)),
+            "page_gap_ms": int(plan.get("page_gap_ms", PAGE_WRITE_GAP_MS)),
+            "read_gap_ms": int(plan.get("read_gap_ms", PAGE_READ_GAP_MS)),
+            "writes": list(plan.get("writes", []) or []),
+            "windows": list(plan.get("windows", []) or []),
+        }, ensure_ascii=False)
+
+    def _bridge_flash_once(self, plan: dict) -> dict:
+        """单次桥内单体烧录 (ndtdbg_bridge.ps1 -Action flash): 返回 data dict, 失败抛 NdtBoxError。
+
+        桥侧 #progress 行转发到 stderr (agent 可见进度), 末行 JSON 为结果 / 错误信封。
+        桥自身无超时 ⇒ 本层按 plan 推预算守护, 超时 kill 并报 BUS_TIMEOUT (不留孤儿进程)。
+        """
+        import time
+        if not os.path.exists(PS32):
+            raise NdtBoxError("CONFIG_ERROR", f"32 位 PowerShell 不存在: {PS32}")
+        if not os.path.isfile(os.path.join(self.dll_dir, "USBIOX.DLL")):
+            raise NdtBoxError("CONFIG_ERROR", f"USBIOX.DLL 不存在: {self.dll_dir}",
+                              "lab.yaml 的 ndtdbg.dll_dir 指向 NdtDebugTool 的 lib 目录")
+        args = [PS32, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                "-File", self.bridge_ps1, "-Action", "flash",
+                "-DllDir", self.dll_dir, "-SlaveAddr", str(self.slave_addr),
+                "-Speed", str(self.speed)]
+        pages = len(plan.get("writes") or [])
+        windows = len(plan.get("windows") or [])
+        # 预算: 页写/回读节奏 + 擦除 + 三次断电复位 + 固定裕量; plan["budget_ms"] 可覆盖 (测试用)
+        budget_ms = int(plan.get("budget_ms") or (
+            pages * (int(plan.get("page_gap_ms", PAGE_WRITE_GAP_MS)) + 60)
+            + windows * (int(plan.get("read_gap_ms", PAGE_READ_GAP_MS)) + 40)
+            + int(plan.get("erase_ms", 2000))
+            + int(plan.get("off_ms", DEFAULT_OFF_MS)) * 3 + 30000))
+        t0 = time.monotonic()
+        proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, text=True, encoding="utf-8",
+                                errors="replace", bufsize=1)
+        lines: list = []
+        state = {"last_progress": time.monotonic()}
+
+        def _reader() -> None:
+            try:
+                for raw in proc.stdout:
+                    line = (raw or "").strip()
+                    if not line:
+                        continue
+                    if line.startswith("#progress"):
+                        state["last_progress"] = time.monotonic()   # 进度续期 (stall 守护)
+                        print(f"[flash] {line[len('#progress'):].strip()}",
+                              file=sys.stderr, flush=True)
+                        continue
+                    if line.startswith("{"):
+                        lines.append(line)
+            except Exception:
+                pass
+
+        reader = threading.Thread(target=_reader, daemon=True)
+        reader.start()
+        try:
+            try:
+                proc.stdin.write(self._bridge_plan_json(plan))
+                proc.stdin.close()
+            except Exception as exc:
+                proc.kill()
+                raise NdtBoxError("UNKNOWN_ERROR", f"向桥 flash 写入计划失败: {exc}") from exc
+            # 守护 = "无进度"判定, 而非固定总时长: 桥逐页/逐窗吐 #progress, 每次续期;
+            # 健康但慢的全片擦除 (长 erase_ms / 大镜像) 不会被误杀 (评审 3.2-①)。
+            # stall_s / hard_timeout_s 可按 plan 覆盖 (默认 30s 无进度判卡; 硬上限 3x 预算且 >=180s)
+            stall_s = max(1.0, float(plan.get("stall_s") or 30.0))
+            hard_s = float(plan.get("hard_timeout_s") or max(180.0, 3.0 * budget_ms / 1000.0))
+            hard_deadline = t0 + hard_s
+            while True:
+                if proc.poll() is not None and not reader.is_alive():
+                    break
+                now = time.monotonic()
+                if now > hard_deadline:
+                    proc.kill()
+                    raise NdtBoxError(
+                        "BUS_TIMEOUT",
+                        f"桥内 flash 超过硬上限 (预算 {budget_ms}ms, {pages} 页/{windows} 窗): "
+                        "已终止桥进程。检查目标是否卡在擦除/页写; 可先 fw_ndtdbg_power_cycle 复位",
+                        None)
+                if now - state["last_progress"] > stall_s:
+                    proc.kill()
+                    recover = self._post_kill_recover()
+                    raise NdtBoxError(
+                        "INCOMPLETE_FLASH",
+                        f"桥内 flash 连续 {int(stall_s)}s 无任何进度 ⇒ 目标疑似卡在写入中途。"
+                        "已终止桥进程并尝试复位, 但**芯片可能处于半擦写状态, 请勿直接使用, "
+                        "必须重新完整烧录**",
+                        f"最后一条桥输出: {(lines[-1] if lines else '无')[:120]}",
+                        {"engine": "bridge", "chip_state": "partially_erased",
+                         "pages_written": pages, "read_windows": windows, **recover,
+                         "hint": "重新调用 fw_ndtdbg_flash 完整烧录; 若反复卡住, 先 "
+                                 "fw_ndtdbg_power_cycle 复位再试"})
+                time.sleep(0.05)
+            elapsed_ms = round((time.monotonic() - t0) * 1000)
+            if not lines:
+                err = ""
+                try:
+                    err = (proc.stderr.read() or "")[-300:]
+                except Exception:
+                    pass
+                raise NdtBoxError("UNKNOWN_ERROR",
+                                  f"桥内 flash 未返回 JSON 结果 (exit={proc.returncode})", err or None)
+            try:
+                body = json.loads(lines[-1])
+            except ValueError as exc:
+                raise NdtBoxError("UNKNOWN_ERROR", f"桥内 flash 结果解析失败: {exc}",
+                                  lines[-1][:200]) from exc
+            if not body.get("ok"):
+                cls = body.get("error_class") or "UNKNOWN_ERROR"
+                msg = str(body.get("error") or "桥内 flash 失败")
+                detail = body.get("detail")
+                extra: dict = {"engine": "bridge"}
+                m = re.search(r"@0x([0-9A-Fa-f]{4})", msg)
+                if m:
+                    extra["first_mismatch_offset"] = int(m.group(1), 16)
+                mm = re.search(r"expect=([0-9A-Fa-f]*) got=([0-9A-Fa-f]*)", str(detail or ""))
+                if mm:
+                    extra["first_mismatch_expect"] = mm.group(1).upper()
+                    extra["first_mismatch_got"] = mm.group(2).upper()
+                raise NdtBoxError(cls, msg, detail, extra)
+            data = body.get("data") or {}
+            data["elapsed_ms"] = elapsed_ms
+            return data
+        finally:
+            try:
+                if proc.poll() is None:
+                    proc.kill()
+            except Exception:
+                pass
+
+    def _flash_exec_bridge(self, plan: dict) -> dict:
+        """桥内单体 flash 引擎 (0.7.2 起为默认): 单进程内 USBIOX(0) 与 USB2IO(1) 句柄同持,
+
+        帧经 stdin 一次性传入、全程连续无逐笔管道往返 —— 即原厂 GUI 的进程模型, 也是
+        现场 (2026-09-11 F72) 6/6 verify pass 的那条路径。校验失败 (桥报
+        TARGET_MISMATCH "烧录校验失败") 时按 rewrite_times 整片重跑, 其余错误直接上抛。
+        """
+        import time
+        rewrite_times = max(0, int(plan.get("rewrite_times", _REWRITE_TIMES)))
+        t_all = time.monotonic()
+        attempts_detail: list = []
+        for attempt in range(rewrite_times + 1):
+            try:
+                data = self._bridge_flash_once(plan)
+            except NdtBoxError as exc:
+                attempts_detail.append({
+                    "attempt": attempt + 1, "ok": False, "error_class": exc.error_class,
+                    "first_mismatch_offset": exc.extra.get("first_mismatch_offset"),
+                    "first_mismatch_expect": exc.extra.get("first_mismatch_expect"),
+                    "first_mismatch_got": exc.extra.get("first_mismatch_got")})
+                if (exc.error_class == "TARGET_MISMATCH" and "校验失败" in exc.message
+                        and attempt < rewrite_times):
+                    continue   # 整片重写 (桥内每次都是完整擦写)
+                raise NdtBoxError(
+                    exc.error_class, exc.message, exc.detail,
+                    {**exc.extra, "engine": "bridge", "attempts": attempt + 1,
+                     "attempts_detail": attempts_detail,
+                     "stage_timings": {"total_ms": round((time.monotonic() - t_all) * 1000)}})
+            attempts_detail.append({"attempt": attempt + 1, "ok": True,
+                                    "elapsed_ms": data.get("elapsed_ms"),
+                                    "verify": data.get("verify"),
+                                    "pages_written": data.get("pages_written")})
+            total_ms = round((time.monotonic() - t_all) * 1000)
+            return {
+                "verify": data.get("verify", "pass"),
+                "chip_state": "verified" if data.get("verify", "pass") == "pass" else "unknown",
+                "pages_written": data.get("pages_written"),
+                "read_windows": data.get("read_windows"),
+                "rewrite_count": attempt,
+                "attempts": attempt + 1,
+                "attempts_detail": attempts_detail,
+                "engine": "bridge",
+                "boot_judge": "n/a (bridge engine: 桥内无探测事务, 逐窗校验为唯一判据)",
+                "boot_evidence": "not_evaluated",
+                "probe_hex": None,
+                "probe_before_hex": None,
+                "off_ms": int(plan.get("off_ms", DEFAULT_OFF_MS)),
+                "stage_timings": {"total_ms": total_ms},
+                "total_ms": total_ms,
+            }
+        raise NdtBoxError("UNKNOWN_ERROR", "flash_exec(bridge) 未产出结果", None)  # pragma: no cover
+
     def flash_exec(self, plan: dict, timeout_ms: int | None = None) -> dict:
+        """烧录引擎分派: "bridge" (默认, 桥内单体 flash) / "serve" (逐笔 Python 驱动)。
+
+        现场实证 (2026-09-11, F72, 同一批固件 + 同一台设备):
+          桥内单体 flash (帧经 stdin 一次传入)      -> 6/6 {"ok":true,"verify":"pass"}
+          逐笔 serve 路径 (每页一笔 raw 事务)        -> 100% "擦除生效但页写不落地"
+            (probe FFFFFFFF -> 00000000 说明 7 字节擦除帧到达; 99 页 write_ms 7594ms
+             ≈ 77ms/页; 校验读回全 FF)
+        两条路径的**帧完全相同** (build_page_write_frame, 命令行核对无误), 故差异在
+        进程/传输模型而非帧组装 ⇒ 默认走桥内单体, serve 引擎保留供 A/B 复现与排查。
+        """
+        engine = str(plan.get("engine", "bridge") or "bridge").lower()
+        if engine == "bridge":
+            return self._flash_exec_bridge(plan)
+        if engine == "serve":
+            return self._flash_exec_serve(plan)
+        raise NdtBoxError("CONFIG_ERROR", "flash engine 非法 (bridge/serve)", engine)
+
+    def _flash_exec_serve(self, plan: dict, timeout_ms: int | None = None) -> dict:
         """Python 驱动整条 UpdateFW 序列 (0.4.0 serve 化): usb2io 断电复位进 boot +
         擦除 -> 页写 -> 回读校验 -> 完成魔数, 全部 I2C 事务经 serve 会话 (同进程同
         会话连续, 复刻原厂 GUI 进程模型)。校验 (逐窗 vs expect_hex) 在本模块完成,
@@ -1190,9 +1424,61 @@ class ChipSeaFxx:
 
     # -- 固件烧录 (对齐 ChipSea.cs UpdateFW: 仅芯海 Fxx, 整片擦写) --
 
+    def cold_boot_check(self, off_ms: int = DEFAULT_OFF_MS, reg: int = 0x10,
+                        expect: str | None = None) -> dict:
+        """烧后冷启动冒烟 (评审 §4): 断电重上电 -> 读已知寄存器 -> 判定固件是否真的跑起来。
+
+        只校验 Flash 字节的流程抓不到"镜像烧对了但跑不起来"——现场 `.18` 正是: GUI 报
+        `FW Upgrade Success` 且当场可读, 断电重上电后 `Fw_ver = -1`。这里 fail-closed:
+        expect 给定时逐字节比对; 未给定时判"有无效应答"(读不到或全 00/FF 都算失败)。
+        """
+        import time
+        self._io.vbrt_reset(off_ms)    # 冷启动 (真 POR 上电)
+        time.sleep(0.3)                # 让固件跑到能响应从机的程度
+        want = bytes.fromhex(str(expect).replace(" ", "")) if expect else None
+        raw: bytes | None = None
+        err: str | None = None
+        for _ in range(3):
+            try:
+                raw = self._io.read_reg(reg, len(want) if want else 4)
+                break
+            except NdtBoxError as exc:
+                err = f"{exc.error_class}: {exc.message}"
+                time.sleep(0.2)
+        out: dict = {"checked": True, "reg": f"0x{reg:02X}",
+                     "raw_hex": raw.hex().upper() if raw else None,
+                     "expect_hex": want.hex().upper() if want else None,
+                     "read_error": err}
+        if raw is None:
+            out["ok"] = False
+            out["conclusion"] = ("冷启动后该寄存器无应答: 固件可能未起振/未使能 I2C 从机 "
+                                 "—— Flash 字节已验证, 但目标跑不起来 (现场 .18 类问题的特征)")
+            return out
+        if want is not None:
+            if raw[:len(want)] != want:
+                out["ok"] = False
+                out["conclusion"] = (f"冷启动后 {out['reg']} 读回 {out['raw_hex']} "
+                                     f"!= 期望 {out['expect_hex']}")
+                return out
+            out["ok"] = True
+            out["conclusion"] = f"冷启动读回与期望一致 ({out['raw_hex']})"
+            return out
+        if all(b in (0x00, 0xFF) for b in raw):
+            out["ok"] = False
+            out["conclusion"] = (f"冷启动后 {out['reg']} 读回全 00/FF ({out['raw_hex']}): 无有效应答 "
+                                 "—— 疑似固件未起振; 若该寄存器本就不该有内容, 请用 cold_boot_expect "
+                                 "指定期望值或关闭 cold_boot_check")
+            return out
+        out["ok"] = True
+        out["conclusion"] = f"冷启动读回 {out['raw_hex']} (有有效应答)"
+        return out
+
     def flash_bin(self, file_path: str, erase_ms: int = 2000,
                   off_ms: int | None = None, rewrite_times: int | None = None,
-                  boot_judge: str | None = None, progress=None) -> dict:
+                  boot_judge: str | None = None, engine: str | None = None,
+                  cold_boot_check: bool = True, cold_boot_reg: int = 0x10,
+                  cold_boot_expect: str | None = None,
+                  progress=None) -> dict:
         """经 NdtBox IIC 烧录 .bin/.nfw 固件到芯海 Fxx (UpdateFW 语义)。
 
         时序逐行对齐 ChipSea.cs UpdateFW, 进程模型对齐原厂 STDataCollection GUI:
@@ -1221,6 +1507,7 @@ class ChipSeaFxx:
             "read_gap_ms": PAGE_READ_GAP_MS,
             "rewrite_times": _REWRITE_TIMES if rewrite_times is None else max(0, int(rewrite_times)),
             "boot_judge": str(boot_judge or "diff").lower(),
+            "engine": str(engine or "bridge").lower(),
             "writes": [build_page_write_frame(off, fw[off:off + FLASH_WRITE_PAGE]).hex()
                        for off in pages],
             "windows": [{"off": off, "expect_hex": expected_read_window(fw, off).hex()}
@@ -1229,6 +1516,22 @@ class ChipSeaFxx:
         res = self._io.flash_exec(plan)
         if progress:
             progress("verify", len(windows), len(windows))
+        # 冷启动冒烟 (评审 §4, 默认开): Flash 字节校验通过 ≠ 固件跑得起来
+        cold: dict | None = None
+        if cold_boot_check and res.get("verify", "pass") == "pass":
+            cold = self.cold_boot_check(off_ms=plan["off_ms"], reg=int(cold_boot_reg),
+                                        expect=cold_boot_expect)
+            if not cold.get("ok"):
+                raise NdtBoxError(
+                    "COLD_BOOT_VERIFY_FAILED",
+                    f"烧录逐窗校验通过, 但冷启动冒烟失败: {cold.get('conclusion')}",
+                    "Flash 字节已写入并通过回读校验; 失败发生在'断电重上电后能否工作'这一步",
+                    {"verify": "pass", "engine": res.get("engine", plan["engine"]),
+                     "pages_written": len(pages), "window_verified": True,
+                     "cold_boot": cold,
+                     "hint": "①确认目标固件在本寄存器上确有可读内容 (否则用 cold_boot_expect 指定)"
+                             "; ②按现场 .18 类问题排查冷启动路径 (看门狗/时钟/外设初始化); "
+                             "③如确不需要该校验, 用 cold_boot_check=false / --no-cold-boot-check 关闭"})
         return {
             "file": file_path,
             "file_type": fw_type,
@@ -1237,13 +1540,17 @@ class ChipSeaFxx:
             "read_windows": len(windows),
             "erase_ms": int(erase_ms),
             "off_ms": plan["off_ms"],
+            "chip_state": res.get("chip_state"),
+            "cold_boot": cold,
             "rewrite_times": plan["rewrite_times"],
-            "boot_judge": plan["boot_judge"],
+            "engine": res.get("engine", plan["engine"]),
+            "boot_judge": res.get("boot_judge", plan["boot_judge"]),
             "boot_evidence": res.get("boot_evidence"),
             "probe_hex": res.get("probe_hex"),
             "probe_before_hex": res.get("probe_before_hex"),
             "rewrite_count": res.get("rewrite_count", 0),
             "attempts": res.get("attempts", 1),
+            "attempts_detail": res.get("attempts_detail"),
             "stage_timings": res.get("stage_timings"),
             "verify": res.get("verify", "pass"),
             "duration_ms": int((time.monotonic() - started) * 1000),

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/tools/lib/serial_assistant.py

@@ -994,6 +994,122 @@ class SerialSession:
         return out
 
 
+_PORT_HOG_HINTS = ("stdatacollection", "ndtdebug", "ndt debug", "serialassistant", "sscom",
+                   "comassistant", "putty", "xshell", "securecrt", "minicom", "logic", "saleae")
+
+
+def suspected_port_holders(session_pid: int | None = None) -> list[dict]:
+    """列出可能占着串口的本机进程 (tasklist 扫描, best-effort; 失败返回空列表)。
+
+    Windows 没有便宜的"谁持有 COMx"API, 但现场 90% 的 PermissionError(13) 都是
+    NDT Debug Tool GUI (STDataCollection.exe) 或残留的 fwloop serve 会话 —— 直接给
+    出嫌疑名单比只报一句 PermissionError 更有用。session_pid 用于把"本会话 serve"
+    与"其它 python (很可能是 MCP server, 勿盲杀)"区分开。
+    """
+    out: list[dict] = []
+    if os.name != "nt":
+        return out
+    try:
+        res = subprocess.run(["tasklist", "/FO", "CSV", "/NH"], capture_output=True,
+                             text=True, timeout=15, errors="replace")
+    except Exception:  # noqa: BLE001
+        return out
+    self_pid = os.getpid()
+    for line in (res.stdout or "").splitlines():
+        cols = [c.strip().strip('"') for c in line.split('","')]
+        if len(cols) < 2:
+            continue
+        name, pid_s = cols[0], cols[1]
+        try:
+            pid = int(pid_s)
+        except ValueError:
+            continue
+        low = name.lower()
+        if any(k in low for k in _PORT_HOG_HINTS):
+            out.append({"name": name, "pid": pid,
+                        "why": "GUI/上位机软件可能独占串口 (关闭后再重试)"})
+        elif low.startswith("python") and pid not in (self_pid, session_pid):
+            out.append({"name": name, "pid": pid,
+                        "why": "python 进程 (可能是残留 serve 会话; 若为 MCP server 请勿终止)"})
+    if session_pid:
+        out = [h for h in out if h["pid"] != session_pid]
+        out.append({"name": "(本会话 serve)", "pid": session_pid, "why": "正常: fw_serial_close 会回收"})
+    return out
+
+
+def port_exclusive_probe(port: str | None, baud: int = 115200) -> dict:
+    """直接试开端口 ⇒ 给出"当前能否独占打开"的**硬结论**（评审 3.2-②）。
+
+    `tasklist` 看不到 COM 端口持有者（进程加载了模块 ≠ 打开了端口），任何进程名单都只是
+    推断；试开才是判据。返回 {port, openable, error, conclusion}。
+    """
+    if not port:
+        return {"port": None, "openable": None, "error": "未指定端口",
+                "conclusion": "无端口可探测 (未配置 serial.port)"}
+    try:
+        import serial as pyserial
+    except ImportError as exc:  # noqa: BLE001
+        return {"port": port, "openable": None, "error": f"pyserial 未安装: {exc}",
+                "conclusion": "无法探测 (缺 pyserial)"}
+    ser = None
+    try:
+        ser = pyserial.Serial(port=port, baudrate=int(baud), timeout=0.2, write_timeout=0.5)
+        return {"port": port, "openable": True, "error": None,
+                "conclusion": f"{port} 当前可被本进程独占打开 ⇒ 若会话仍读不到数据, "
+                              "原因不在端口占用 (检查波特率/接线/目标是否在输出)"}
+    except Exception as exc:  # noqa: BLE001
+        return {"port": port, "openable": False,
+                "error": f"{type(exc).__name__}: {exc}",
+                "conclusion": f"{port} 当前无法独占打开 ⇒ 被其它程序占用或设备不在位"}
+    finally:
+        try:
+            if ser is not None:
+                ser.close()
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def port_holder_candidates(port: str | None, session_pid: int | None = None) -> list[dict]:
+    """端口占用**候选名单**（需人工确认；候选 ≠ 持有者）。
+
+    两个来源, 按置信度标注:
+    - `source="cmdline"`（较准）: Win32_Process 命令行含端口名 ⇒ 该进程可能在用这个口;
+    - `source="name"`（较低）: 进程名像 GUI/上位机/残留 python serve。
+    **硬结论请看 port_exclusive_probe()。**
+    """
+    out: list[dict] = []
+    if os.name != "nt":
+        return out
+    self_pid = os.getpid()
+    if port:
+        try:
+            ps = ("Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like "
+                  f"'*{port}*' }} | Select-Object -First 12 ProcessId,Name,CommandLine | "
+                  "ConvertTo-Json -Compress")
+            res = subprocess.run(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps],
+                                 capture_output=True, text=True, timeout=30, errors="replace")
+            raw = (res.stdout or "").strip()
+            if raw:
+                data = json.loads(raw)
+                if isinstance(data, dict):
+                    data = [data]
+                for item in data:
+                    pid = int(item.get("ProcessId") or 0)
+                    if pid in (self_pid, session_pid):
+                        continue
+                    out.append({"name": item.get("Name") or "?", "pid": pid,
+                                "why": f"命令行含 {port}", "source": "cmdline",
+                                "confidence": "medium", "cmdline": (item.get("CommandLine") or "")[:200]})
+        except Exception:  # noqa: BLE001
+            pass
+    known = {h["pid"] for h in out}
+    for h in suspected_port_holders(session_pid):
+        if h["pid"] in known or h["pid"] == self_pid:
+            continue
+        out.append({**h, "source": "name", "confidence": "low"})
+    return out
+
+
 def pid_alive(pid: int | None) -> bool:
     """进程存活探测。
 

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/tools/ndtdbg_cli.py

@@ -249,9 +249,17 @@ def cmd_status(io: NdtBoxIo) -> None:
         # P2-1 分层判据表: 把"全 FF/无应答"的几种成因摊开, 避免一句 hint 把人带偏
         data["diagnosis_table"] = [
             {"symptom": "能读到任一已知寄存器", "likely": "从机在跑, 链路正常 (判活以此为准)"},
-            {"symptom": "读回全 FF/FE、无异常", "likely": "从机未使能 / 目标掉电 / 从机地址不符"},
+            {"symptom": "读回全 FF/FE、无异常",
+             "likely": "①目标固件未使能 I2C 从机 (最常见, 与掉电现象一致) ②目标掉电 ③从机地址不符"},
             {"symptom": "TARGET_MISMATCH: IIC 事务无应答",
              "likely": "地址未被 ACK (外设未使能/复位中/芯片未上电)"},
+            {"symptom": "只有写事务 NACK, 读事务正常",
+             "likely": "不是从机死: 该寄存器不可写/写保护, 或目标固件未实现该写寄存器 "
+                       "(此时应回读邻近寄存器确认链路仍活)"},
+            {"symptom": "目标固件刚被改动过",
+             "likely": "按序排除: ①从机是否真的使能 (初始化是否提前 return); ②冷启动 vs 热复位"
+                       "行为差异 (热复位可读、断电重上电读不到属另一类问题); ③改动静态寄存器表/"
+                       "RAM 布局后整套读取是否仍正常 (表必须按 addr 升序, 且不与 0x0000 冲突)"},
             {"symptom": "BUS_TIMEOUT", "likely": "时钟拉伸、关中断死循环 (fault handler 自旋饿死 I2C 中断)"},
         ]
     ok("status", data, log="Open + ReadFwVersion(0x10) + ReadModuleConnect(0x29)")
@@ -288,9 +296,15 @@ def cmd_read_reg(io: NdtBoxIo, reg: int, length: int, retry: int = 0) -> None:
             "io_ms": round((time.monotonic() - t0) * 1000, 1),
             "retries": attempts - 1}
     if data and all(b in (0xFF, 0xFE) for b in data):
-        # 总线无应答时上拉/悬空读回默认电平, 不能当作真实寄存器值误导调用方
-        body["warning"] = ("读回全部 0xFF/0xFE: 疑似 IIC 目标无应答 (总线悬空默认电平), "
-                           "请检查接线/上拉/供电/从机地址")
+        # 总线无应答时上拉/悬空读回默认电平, 不能当作真实寄存器值误导调用方。
+        # P2-1: 第一候选是"目标固件没使能从机"(现象与掉电完全一样), 而不是硬件掉了
+        body["warning"] = ("读回全部 0xFF/0xFE: 疑似 IIC 目标无应答。第一候选是【目标固件"
+                           "根本没使能 I2C 从机】(从机表初始化提前 return / 未注册), 现象与掉电"
+                           "完全一样; 其次才是掉电/接线/上拉/从机地址。可参考 fw_ndtdbg_status "
+                           "的 diagnosis_table 逐条排除")
+        body["candidates"] = ["目标固件未使能 I2C 从机 (最常见, 现象与掉电一致)",
+                              "目标掉电 / 复位中", "接线/上拉/供电异常",
+                              "从机地址不符 (lab.yaml ndtdbg.slave_addr)"]
     ok("read-reg", body, log=f"ReadReg(0x{reg:02X}, {length})")
 
 
@@ -505,7 +519,9 @@ def cmd_stream(io: NdtBoxIo, config: dict, specs: list, interval_ms, duration_s:
 
 def cmd_flash_bin(io: NdtBoxIo, config: dict, file_path: str, erase_ms: int, confirm: bool,
                   off_ms: int | None = None, rewrite_times: int | None = None,
-                  boot_judge: str | None = None) -> None:
+                  boot_judge: str | None = None, engine: str | None = None,
+                  cold_boot_check: bool | None = None, cold_boot_reg: int | None = None,
+                  cold_boot_expect: str | None = None) -> None:
     # 烧录 = 整片擦除 + 页写, 破坏性高于 write-reg, 同款双闸门
     ndt_cfg = config.get("ndtdbg") or {}
     allowed = ndt_cfg.get("write_allowed", False)
@@ -524,20 +540,33 @@ def cmd_flash_bin(io: NdtBoxIo, config: dict, file_path: str, erase_ms: int, con
     # 目标时, 用 off 让页写后的逐窗校验做唯一判据 —— 即桥内单体 flash 的语义)
     if boot_judge is None:
         boot_judge = flash_cfg.get("boot_judge")
+    # 0.7.2: 烧录引擎 (bridge 默认 = 桥内单体 flash; serve = 逐笔 Python 驱动, 供 A/B 复现)
+    if engine is None:
+        engine = flash_cfg.get("engine")
+    # 冷启动冒烟 (评审 §4): 默认开; lab.yaml ndtdbg.flash.cold_boot_check / reg / expect 可覆盖
+    if cold_boot_check is None:
+        cold_boot_check = flash_cfg.get("cold_boot_check", True)
+    if cold_boot_reg is None:
+        cold_boot_reg = flash_cfg.get("cold_boot_reg", 0x10)
+    if cold_boot_expect is None:
+        cold_boot_expect = flash_cfg.get("cold_boot_expect")
 
     def progress(phase: str, done: int, total: int) -> None:
         print(f"[flash-bin] {phase} {done}/{total}", file=sys.stderr, flush=True)
 
     result = ChipSeaFxx(io).flash_bin(file_path, erase_ms=erase_ms, off_ms=off_ms,
                                       rewrite_times=rewrite_times, boot_judge=boot_judge,
+                                      engine=engine, cold_boot_check=bool(cold_boot_check),
+                                      cold_boot_reg=int(cold_boot_reg),
+                                      cold_boot_expect=cold_boot_expect,
                                       progress=progress)
     result["authorization"] = {"write_allowed": True,
                                "granted_by": write_allowed_source() or "(default false)",
                                "chain": list(_CONFIG_FILES)}
     ok("flash-bin", result,
        log=f"UpdateFW({file_path}): {result['fw_len']}B, {result['pages_written']} pages, "
-           f"off_ms={result.get('off_ms')}, rewrite={result.get('rewrite_count', 0)}, "
-           f"boot_judge={result.get('boot_judge')}, verify={result['verify']}")
+           f"engine={result.get('engine')}, off_ms={result.get('off_ms')}, "
+           f"rewrite={result.get('rewrite_count', 0)}, verify={result['verify']}")
 
 
 # --------------------------------------------------------------------------- main
@@ -590,7 +619,20 @@ def build_parser() -> argparse.ArgumentParser:
                    help="校验不一致时整片重写次数上限 (默认对齐 ChipSea.cs 的 3; 0=不重写)")
     f.add_argument("--boot-judge", choices=["diff", "off"], default=None,
                    help="boot 判据 (默认 diff: 只有'擦除魔数前后同一条非平凡应答'才熔断; "
-                        "off: 完全关闭探测判据, 仅记录证据, 由逐窗校验做唯一判据)")
+                        "off: 完全关闭探测判据, 仅记录证据, 由逐窗校验做唯一判据); "
+                        "仅 serve 引擎适用")
+    f.add_argument("--flash-engine", choices=["bridge", "serve"], default=None,
+                   help="烧录引擎 (默认 bridge = 桥内单体 flash: 单进程、帧经 stdin 一次传入、"
+                        "现场 6/6 verify pass; serve = 逐笔 raw 事务的 Python 驱动, 供 A/B 复现)")
+    f.add_argument("--cold-boot-check", dest="cold_boot_check", action="store_true", default=None,
+                   help="烧后冷启动冒烟 (默认开): 断电重上电 -> 读 cold-boot-reg -> 判定固件是否"
+                        "真的跑起来; 失败报 COLD_BOOT_VERIFY_FAILED (Flash 字节已通过校验)")
+    f.add_argument("--no-cold-boot-check", dest="cold_boot_check", action="store_false",
+                   help="关闭冷启动冒烟")
+    f.add_argument("--cold-boot-reg", type=lambda x: int(x, 0), default=None,
+                   help="冷启动冒烟读的寄存器 (默认 0x10 版本寄存器)")
+    f.add_argument("--cold-boot-expect", default=None,
+                   help="冷启动冒烟期望值 (hex, 如 '51 17 64 11'); 不传则只判'有无效应答'")
 
     st = sub.add_parser("stream", parents=[common],
                         help="高速连续采集寄存器组到 CSV (单会话长驻, 只读)")
@@ -651,7 +693,10 @@ def main(argv=None) -> None:
         elif args.cmd == "flash-bin":
             cmd_flash_bin(io, config, args.file, args.erase_ms, args.confirm,
                           off_ms=args.off_ms, rewrite_times=args.rewrite_times,
-                          boot_judge=args.boot_judge)
+                          boot_judge=args.boot_judge, engine=args.flash_engine,
+                          cold_boot_check=args.cold_boot_check,
+                          cold_boot_reg=args.cold_boot_reg,
+                          cold_boot_expect=args.cold_boot_expect)
         elif args.cmd == "stream":
             specs = [parse_reg_spec(s) for s in args.regs]
             cmd_stream(io, config, specs, args.interval_ms, args.duration_s,

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/tools/serial_cli.py

@@ -36,6 +36,9 @@ from lib.serial_assistant import (  # noqa: E402
     parse_hex,
     probe_session,
     to_hex,
+    port_exclusive_probe,
+    port_holder_candidates,
+    suspected_port_holders,
     wait_pid_exit,
 )
 
@@ -122,6 +125,10 @@ def cmd_status(_args: argparse.Namespace) -> None:
                     "started_at": stats.get("started_at")},
         "conclusion": f"会话存活 (port={sess.get('port') or stats.get('port')}, "
                       f"opened={alive})" if alive else "serve 进程存活但串口未打开",
+        # P1-4 / 评审 3.2-②: 先给硬结论 (端口能否独占打开), 再给需人工确认的候选名单
+        "port_probe": port_exclusive_probe(sess.get("port") or stats.get("port")),
+        "holder_candidates": port_holder_candidates(sess.get("port") or stats.get("port"),
+                                                   sess.get("pid")),
     })
 
 
@@ -149,6 +156,8 @@ def cmd_open(args: argparse.Namespace) -> None:
                 "holder_hint",
                 "端口可能被 GUI 上位机占用: NDT Debug Tool (STDataCollection.exe) 打开时会同时占用 "
                 "Box 串口与 USB-IIC 通道; 请关闭占用方后重试, 残留会话可用 fw_serial_close 清理")
+            extra.setdefault("port_probe", port_exclusive_probe(cfg.get("port")))
+            extra.setdefault("holder_candidates", port_holder_candidates(cfg.get("port")))
         fail(exc.error_class, exc.detail, extra=extra)
     data = {k: info.get(k) for k in
             ("port", "baud", "simulated", "log_path", "reused", "pid", "started_at")}
@@ -212,7 +221,7 @@ def cmd_send(args: argparse.Namespace) -> None:
                     time.sleep(delay / 1000.0)
         stats = session.stats()
     except SerialAssistantError as exc:
-        fail(exc.error_class, exc.detail, extra=exc.extra)
+        fail(exc.error_class, exc.detail, extra=_port_error_extra(exc))
     ok("send", {"frames_sent": sent, "frames_defined": len(frames),
                 "elapsed_ms": round((time.monotonic() - t0) * 1000, 2),
                 "tx_bytes": stats.get("tx_bytes"), "rx_bytes": stats.get("rx_bytes")},
@@ -229,7 +238,7 @@ def cmd_read(args: argparse.Namespace) -> None:
         else:
             result = session.read(max_bytes=RX_BUFFER_LIMIT if args.drain else args.max_bytes)
     except SerialAssistantError as exc:
-        fail(exc.error_class, exc.detail, extra=exc.extra)
+        fail(exc.error_class, exc.detail, extra=_port_error_extra(exc))
 
     if args.drain and not args.expect:
         # P2-3 (0909 提案): 单次排空整个缓冲; 大 payload 落盘而非进 MCP 响应,
@@ -321,7 +330,7 @@ def cmd_parse(args: argparse.Namespace) -> None:
         frames = parser.feed(data_bytes)
         frames += parser.finalize()
     except SerialAssistantError as exc:
-        fail(exc.error_class, exc.detail, extra=exc.extra)
+        fail(exc.error_class, exc.detail, extra=_port_error_extra(exc))
     valid_n = sum(1 for f in frames if f["valid"])
     ok("parse", {"source": src, "frames_n": len(frames), "valid_n": valid_n,
                  "invalid_n": len(frames) - valid_n, "bytes": len(data_bytes),
@@ -329,6 +338,21 @@ def cmd_parse(args: argparse.Namespace) -> None:
        log=f"SerialParse({src}): {len(frames)} frames, {valid_n} valid")
 
 
+def _port_error_extra(exc: SerialAssistantError) -> dict:
+    """串口类错误的统一附加信息 (P1-4 / 评审 3.2-②)。
+
+    顺序说明设计: **硬结论在前** (port_probe = 直接试开端口能否独占), 候选名单在后
+    (cmdline 匹配较准 → 进程名匹配较低, 都只是"需人工确认"的候选)。
+    """
+    extra = dict(exc.extra)
+    if exc.error_class in ("SERIAL_PORT_ERROR", "UART_BUSY"):
+        port = extra.get("port") or (_load_session_file() or {}).get("port")
+        extra.setdefault("port", port)
+        extra.setdefault("port_probe", port_exclusive_probe(port))
+        extra.setdefault("holder_candidates", port_holder_candidates(port))
+    return extra
+
+
 def _run_power_cycle(off_ms: int) -> dict:
     """P2-4: 触发一次 NdtBox 断电复位 (复用 ndtdbg_cli power-cycle, 同 lab.yaml 解析链)。"""
     cli = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ndtdbg_cli.py")
@@ -389,9 +413,15 @@ def cmd_capture(args: argparse.Namespace) -> None:
             result = box.get("r") or {}
         stats = session.stats()
     except SerialAssistantError as exc:
-        fail(exc.error_class, exc.detail, extra=exc.extra)
+        fail(exc.error_class, exc.detail, extra=_port_error_extra(exc))
     payload = {**result, "tx_bytes": stats.get("tx_bytes"),
                "simulated": stats.get("simulated")}
+    if args.duration_ms >= 10000:
+        # P2: MCP stdio 循环单线程 —— 长调用会让同会话的其它调用排队, 客户端可能先超时
+        payload["blocking_notice"] = (
+            f"服务端本次阻塞 {args.duration_ms}ms: MCP stdio 是单线程的, 同一会话内其它工具"
+            "调用会排在它后面 (客户端超时往往先到)。长采集建议缩短窗口, 或用 ndtdbg stream "
+            "job 模式 (fw_ndtdbg_stream_start/status/stop) 让采集不占调用通道")
     if power_off_ms is not None:
         payload["power_cycle"] = pc_result
         if not (pc_result or {}).get("ok"):
@@ -498,7 +528,7 @@ def main() -> None:
     try:
         handler(args)
     except SerialAssistantError as exc:
-        fail(exc.error_class, exc.detail, extra=exc.extra)
+        fail(exc.error_class, exc.detail, extra=_port_error_extra(exc))
 
 
 if __name__ == "__main__":

{firmwareloop-0.7.1 → firmwareloop-0.7.3}/tools/setup-agent-mcp.ps1

@@ -1,6 +1,6 @@
 <#
 .SYNOPSIS
-    Dual-Tier MCP setup and registration helper (v0.7.1).
+    Dual-Tier MCP setup and registration helper (v0.7.3).
     Inspects installed AI coding agents (Qoder, Claude Code, Antigravity, Cursor)
     and configures global MCP / skills or prints exact registration commands.
 
@@ -242,7 +242,7 @@ if ($Json) {
     Write-FwJson ([pscustomobject]$report)
 } else {
     Write-Host "============================================================" -ForegroundColor Cyan
-    Write-Host "  FirmwareLoop Dual-Tier MCP & Agent Setup Helper (v0.7.1)" -ForegroundColor Green
+    Write-Host "  FirmwareLoop Dual-Tier MCP & Agent Setup Helper (v0.7.3)" -ForegroundColor Green
     Write-Host "============================================================" -ForegroundColor Cyan
     Write-Host ""
     Write-Host "[1] Google Antigravity / Gemini CLI:" -ForegroundColor Yellow