flashgate 0.7.2__tar.gz → 0.9.0__tar.gz

{flashgate-0.7.2 → flashgate-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.7.2
+Version: 0.9.0
 Summary: Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so.
 License: MIT
 Project-URL: Homepage, https://github.com/Lion-1209/flashgate
@@ -33,6 +33,26 @@ with a non-zero exit code and a reason.
 build → flash over ST-Link → board boots → evidence → probes → exit code
 ```
 
+A remote agent driving the bench over the network (Wi-Fi laptop → wired
+bench, OpenOCD backend) — real output:
+
+```
+$ flashgate --board apollo-openocd.yaml verify --all-probes
+[verify] apollo-h743: build -> flash -> boot banner -> probes
+[build] OK in 1.3s, 0 warning(s)
+[flash] Apollo.bin @ 0x08000000 via openocd:port=SWD
+[flash] OK (written, verified, started)
+FLASHGATE-BOOT board=apollo-h743 git=e87efd8-dirty build=2026-09-16T02:48:14Z rtos=FreeRTOS
+[probe] led-demo: LED state-machine set/readback + PWM CCR sanity
+    step 1: led-demo> led0 breath
+    board: OK led0 state=BREATH
+    step 2: led-demo> led0?
+    board: OK led0 state=BREATH ccr=691          <- hardware register readback
+    ...
+[probe] led-demo: PASS (5 steps)
+[record] 20260916T024814701-0-035e45ea.json  (succeeded exit=0 [6/6 checks])
+```
+
 [中文说明](#中文说明) | [使用说明（推荐先读这份）](docs/GUIDE.md)
 
 ## How the board testifies
@@ -90,7 +110,7 @@ fresh clone verifies out of the box once wired up.
 | 2 | flash failed |
 | 3 | board stayed silent (no banner / no signature within timeout) |
 | 4 | error string seen on serial (HardFault, assertion) |
-| 5 | on-board identity ≠ repo state (git sha or board name) |
+| 5 | on-board identity ≠ repo state (git sha or board name) — or the identity evidence channel could not be reset: a failed or unconfirmed pre-start signature wipe (the wipe is read back and verified; a backend silently lying about it is caught) fails closed (exit 5, start withheld), because a surviving old-boot signature must never count as a pass |
 | 6 | environment error (no ST-Link / serial / tools) — including probes explicitly required via `--probe`/`--all-probes` but the console UART is unavailable: a check that cannot run never counts as a pass |
 | 7 | functional probe failed |
 
@@ -98,6 +118,9 @@ fresh clone verifies out of the box once wired up.
 
 Board profiles, probes, fixes and docs are welcome — see
 [CONTRIBUTING.md](CONTRIBUTING.md) for the setup and contribution terms.
+For a release gate that does not depend on the Stop hook (the board signs
+off in CI before a tag publishes), see the official GitHub Actions
+recipes in [docs/ci-recipes.md](docs/ci-recipes.md).
 
 ## The Stop hook
 
@@ -121,6 +144,17 @@ The same broken tree is blocked at most twice, then released with a loud
 warning — the session can never wedge, and a failure is never silently
 swallowed.
 
+One verify at a time per bench: concurrent verifies (a user-level and a
+session-level Stop hook firing on the same stop, or a manual run racing
+the hook) serialize on an OS-owned lock file under the firmware's
+`.flashgate/` instead of fighting over the console serial port — the
+second one waits (default 300 s, `FLASHGATE_VERIFY_LOCK_WAIT`), and a
+timed-out wait is a truthful exit 6 ("bench busy"), never a misleading
+serial error. Register the hook at ONE level only: in the common case
+stacking now just costs a redundant second verify; on a very slow bench
+it can still exhaust the hook's own subprocess timeout, so it is a
+crutch, not a supported setup.
+
 ## Verification records
 
 Every `verify` — passing or failing — leaves an evidence record at
@@ -240,14 +274,29 @@ and 2.x supported.
 
 Real-hardware recordings, indexed in [demo/](demo/README.md): doctor,
 green-path verify, boot-timeout catch, probe catching a silent no-op,
-Stop-hook escalation — plus the full session of a real Claude Code agent
-getting blocked, diagnosing the firmware↔profile contract, fixing both
-sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
+Stop-hook escalation — plus the full session of a real agent (Claude
+Code harness; recorded with GLM-5.2 behind the Anthropic-compatible
+endpoint) getting blocked, diagnosing the firmware↔profile contract,
+fixing both sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
+
+## Debug backends (Phase 2)
+
+The verify pipeline is backend-agnostic: `flash.adapter:` in the board
+profile picks the probe tool — `cubeprogrammer` (default, the original
+implementation), `openocd` (same ST-Link, no ST toolchain needed, and
+the standard route to Linux/ARM64 bench hosts like a Raspberry Pi), or
+`fake` (scripted, for tests). Validated on the same Apollo board:
+swapping to `openocd` is a one-line profile change — verify stays green
+with identical records, zero upper-layer edits, and runs slightly
+faster. OpenOCD is discovered via PATH or `$OPENOCD_BIN`; the target
+script maps from the MCU family (`STM32H7*` -> `stm32h7x`, override
+with `flash.openocd_target`).
 
 ## Board profiles
 
-One yaml per board (`boards/`): build command, artifact, flash address,
-serial adapter hints, banner template, probes, watch globs. The console-side
+One yaml per board (`boards/`): build command, artifact, flash address
+(`flash.adapter:` picks the debug backend), serial adapter hints,
+banner template, probes, watch globs. The console-side
 USB adapter is a property of your bench, not the board — port resolution
 goes explicit `serial.port` / `FLASHGATE_SERIAL_PORT`, then VID/PID hint,
 then the sole serial port, with the banner match as the final identity
@@ -258,10 +307,10 @@ full profile field reference.
 ## Status
 
 Boot gate, probe gate, Stop hook, MCP server, SWD signature channel,
-verification records (per-check evidence with artifact hashes), and the
-remote bench over device-connect — all implemented and validated on real
-hardware, the remote bench cross-host (Wi-Fi laptop driving a wired
-bench, 2026-09-15). Windows-first; Linux/macOS untested.
+verification records (per-check evidence with artifact hashes), the
+remote bench over device-connect (validated cross-host), and a second
+debug backend (OpenOCD, validated on the same board) — all on real
+hardware. Windows-first; Linux/macOS untested.
 
 ## License
 

{flashgate-0.7.2 → flashgate-0.9.0}/README.md

@@ -12,6 +12,26 @@ with a non-zero exit code and a reason.
 build → flash over ST-Link → board boots → evidence → probes → exit code
 ```
 
+A remote agent driving the bench over the network (Wi-Fi laptop → wired
+bench, OpenOCD backend) — real output:
+
+```
+$ flashgate --board apollo-openocd.yaml verify --all-probes
+[verify] apollo-h743: build -> flash -> boot banner -> probes
+[build] OK in 1.3s, 0 warning(s)
+[flash] Apollo.bin @ 0x08000000 via openocd:port=SWD
+[flash] OK (written, verified, started)
+FLASHGATE-BOOT board=apollo-h743 git=e87efd8-dirty build=2026-09-16T02:48:14Z rtos=FreeRTOS
+[probe] led-demo: LED state-machine set/readback + PWM CCR sanity
+    step 1: led-demo> led0 breath
+    board: OK led0 state=BREATH
+    step 2: led-demo> led0?
+    board: OK led0 state=BREATH ccr=691          <- hardware register readback
+    ...
+[probe] led-demo: PASS (5 steps)
+[record] 20260916T024814701-0-035e45ea.json  (succeeded exit=0 [6/6 checks])
+```
+
 [中文说明](#中文说明) | [使用说明（推荐先读这份）](docs/GUIDE.md)
 
 ## How the board testifies
@@ -69,7 +89,7 @@ fresh clone verifies out of the box once wired up.
 | 2 | flash failed |
 | 3 | board stayed silent (no banner / no signature within timeout) |
 | 4 | error string seen on serial (HardFault, assertion) |
-| 5 | on-board identity ≠ repo state (git sha or board name) |
+| 5 | on-board identity ≠ repo state (git sha or board name) — or the identity evidence channel could not be reset: a failed or unconfirmed pre-start signature wipe (the wipe is read back and verified; a backend silently lying about it is caught) fails closed (exit 5, start withheld), because a surviving old-boot signature must never count as a pass |
 | 6 | environment error (no ST-Link / serial / tools) — including probes explicitly required via `--probe`/`--all-probes` but the console UART is unavailable: a check that cannot run never counts as a pass |
 | 7 | functional probe failed |
 
@@ -77,6 +97,9 @@ fresh clone verifies out of the box once wired up.
 
 Board profiles, probes, fixes and docs are welcome — see
 [CONTRIBUTING.md](CONTRIBUTING.md) for the setup and contribution terms.
+For a release gate that does not depend on the Stop hook (the board signs
+off in CI before a tag publishes), see the official GitHub Actions
+recipes in [docs/ci-recipes.md](docs/ci-recipes.md).
 
 ## The Stop hook
 
@@ -100,6 +123,17 @@ The same broken tree is blocked at most twice, then released with a loud
 warning — the session can never wedge, and a failure is never silently
 swallowed.
 
+One verify at a time per bench: concurrent verifies (a user-level and a
+session-level Stop hook firing on the same stop, or a manual run racing
+the hook) serialize on an OS-owned lock file under the firmware's
+`.flashgate/` instead of fighting over the console serial port — the
+second one waits (default 300 s, `FLASHGATE_VERIFY_LOCK_WAIT`), and a
+timed-out wait is a truthful exit 6 ("bench busy"), never a misleading
+serial error. Register the hook at ONE level only: in the common case
+stacking now just costs a redundant second verify; on a very slow bench
+it can still exhaust the hook's own subprocess timeout, so it is a
+crutch, not a supported setup.
+
 ## Verification records
 
 Every `verify` — passing or failing — leaves an evidence record at
@@ -219,14 +253,29 @@ and 2.x supported.
 
 Real-hardware recordings, indexed in [demo/](demo/README.md): doctor,
 green-path verify, boot-timeout catch, probe catching a silent no-op,
-Stop-hook escalation — plus the full session of a real Claude Code agent
-getting blocked, diagnosing the firmware↔profile contract, fixing both
-sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
+Stop-hook escalation — plus the full session of a real agent (Claude
+Code harness; recorded with GLM-5.2 behind the Anthropic-compatible
+endpoint) getting blocked, diagnosing the firmware↔profile contract,
+fixing both sides, and passing on hardware ([24 MB GIF, release asset](https://github.com/Lion-1209/flashgate/releases/download/v0.3.0/5-agent-blocked.gif)).
+
+## Debug backends (Phase 2)
+
+The verify pipeline is backend-agnostic: `flash.adapter:` in the board
+profile picks the probe tool — `cubeprogrammer` (default, the original
+implementation), `openocd` (same ST-Link, no ST toolchain needed, and
+the standard route to Linux/ARM64 bench hosts like a Raspberry Pi), or
+`fake` (scripted, for tests). Validated on the same Apollo board:
+swapping to `openocd` is a one-line profile change — verify stays green
+with identical records, zero upper-layer edits, and runs slightly
+faster. OpenOCD is discovered via PATH or `$OPENOCD_BIN`; the target
+script maps from the MCU family (`STM32H7*` -> `stm32h7x`, override
+with `flash.openocd_target`).
 
 ## Board profiles
 
-One yaml per board (`boards/`): build command, artifact, flash address,
-serial adapter hints, banner template, probes, watch globs. The console-side
+One yaml per board (`boards/`): build command, artifact, flash address
+(`flash.adapter:` picks the debug backend), serial adapter hints,
+banner template, probes, watch globs. The console-side
 USB adapter is a property of your bench, not the board — port resolution
 goes explicit `serial.port` / `FLASHGATE_SERIAL_PORT`, then VID/PID hint,
 then the sole serial port, with the banner match as the final identity
@@ -237,10 +286,10 @@ full profile field reference.
 ## Status
 
 Boot gate, probe gate, Stop hook, MCP server, SWD signature channel,
-verification records (per-check evidence with artifact hashes), and the
-remote bench over device-connect — all implemented and validated on real
-hardware, the remote bench cross-host (Wi-Fi laptop driving a wired
-bench, 2026-09-15). Windows-first; Linux/macOS untested.
+verification records (per-check evidence with artifact hashes), the
+remote bench over device-connect (validated cross-host), and a second
+debug backend (OpenOCD, validated on the same board) — all on real
+hardware. Windows-first; Linux/macOS untested.
 
 ## License
 

flashgate-0.9.0/flashgate/backends.py

@@ -0,0 +1,329 @@
+"""Debug backends: the adapter layer between the verify pipeline and the
+physical debug probe (design doc §5.6, Phase 2).
+
+A backend owns EVERYTHING probe-specific: discovery, flashing, memory
+access. The verify pipeline — and everything above it: records, bench,
+MCP — is backend-agnostic. Swapping CubeProgrammer for OpenOCD is a
+one-line board-profile change (`flash.adapter:`) and zero upper-layer
+edits; that substitution property is the Phase 2 acceptance criterion.
+
+Semantics every backend must honor (they are the gate's, not the
+adapter's):
+- flash(start=False) writes and verifies but does NOT run: the caller
+  wipes the boot signature in between, then start_app() — so a stale
+  RAM signature from a previous boot can never lie about identity.
+- write32/read_mem are the wipe/poll primitives behind that contract.
+- The `connect` string is opaque and backend-specific (CubeProgrammer
+  syntax like "port=SWD"; ignored by OpenOCD, which targets via its own
+  config derived from the board's MCU).
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from . import flasher, swdsig
+from .sttools import augmented_env, find_cubeprogrammer
+
+# OpenOCD target scripts by MCU family prefix. Explicit override lives in
+# the board profile (`flash.openocd_target`) for anything unmapped.
+_OPENOCD_TARGETS: tuple[tuple[str, str], ...] = (
+    ("STM32H7", "stm32h7x"),
+    ("STM32F7", "stm32f7x"),
+    ("STM32F4", "stm32f4x"),
+    ("STM32F1", "stm32f1x"),
+    ("STM32L4", "stm32l4x"),
+    ("STM32G0", "stm32g0x"),
+    ("STM32G4", "stm32g4x"),
+    ("STM32U5", "stm32u5x"),
+    ("STM32WB", "stm32wbx"),
+    ("STM32WL", "stm32wlx"),
+)
+_OPENOCD_TIMEOUT_S = 60
+
+
+def openocd_target_for(mcu: str) -> str | None:
+    mcu = (mcu or "").upper()
+    for prefix, target in _OPENOCD_TARGETS:
+        if mcu.startswith(prefix):
+            return target
+    return None
+
+
+def find_openocd() -> Path | None:
+    """openocd.exe via PATH, $OPENOCD_BIN, or the xpack layout."""
+    exe = "openocd.exe" if shutil.os.name == "nt" else "openocd"
+    found = shutil.which(exe, path=augmented_env().get("PATH", ""))
+    if found:
+        return Path(found)
+    import os
+    for env_name in ("OPENOCD_BIN", "OPENOCD_HOME"):
+        base = os.environ.get(env_name)
+        if base:
+            cand = Path(base)
+            if cand.is_file():
+                return cand
+            hit = cand / "bin" / exe
+            if hit.is_file():
+                return hit
+    return None
+
+
+class DebugBackend(ABC):
+    """The probe-facing surface the verify pipeline depends on."""
+
+    name: str = "abstract"
+
+    @abstractmethod
+    def available(self) -> str | None:
+        """Usable executable path (doctor shows it), or None."""
+
+    @abstractmethod
+    def discover(self) -> str:
+        """Human-readable listing of attached probes (doctor)."""
+
+    @abstractmethod
+    def flash(self, bin_path: Path, connect: str, address: str,
+              start: bool = True) -> flasher.FlashResult: ...
+
+    @abstractmethod
+    def write32(self, connect: str, value: int, address: int) -> bool: ...
+
+    @abstractmethod
+    def start_app(self, connect: str) -> bool: ...
+
+    @abstractmethod
+    def read_mem(self, connect: str, address: int, size: int) -> bytes | None: ...
+
+    def probe_detected(self, discover_output: str) -> bool:
+        """Did discover() actually see a probe? Backend-specific markers —
+        each backend knows its own tool's output format."""
+        return bool(discover_output.strip())
+
+
+class CubeProgrammerBackend(DebugBackend):
+    """STM32CubeProgrammer CLI over ST-Link — the original implementation,
+    unchanged semantics, now behind the interface."""
+
+    name = "cubeprogrammer"
+
+    def available(self) -> str | None:
+        cli = find_cubeprogrammer()
+        return str(cli) if cli else None
+
+    def discover(self) -> str:
+        return flasher.list_stlink()
+
+    def flash(self, bin_path, connect, address, start=True):
+        return flasher.flash(bin_path, connect, address, start=start)
+
+    def write32(self, connect, value, address) -> bool:
+        return flasher.write32(connect, value, address)
+
+    def start_app(self, connect) -> bool:
+        return flasher.start_app(connect)
+
+    def read_mem(self, connect, address, size):
+        return swdsig.read_ram(connect, address, size)
+
+    def probe_detected(self, discover_output: str) -> bool:
+        return "ST-LINK SN" in discover_output
+
+
+class OpenOcdBackend(DebugBackend):
+    """OpenOCD over ST-Link (or any adapter OpenOCD speaks). The second
+    flash implementation that validates the abstraction — and the
+    standard route to Linux/ARM64 bench hosts (e.g. Raspberry Pi), where
+    CubeProgrammer is the awkward dependency.
+
+    `connect` is ignored (it carries CubeProgrammer syntax); targeting
+    comes from the board's MCU mapped to an OpenOCD target script, or an
+    explicit `flash.openocd_target` in the profile. Interface defaults
+    to ST-Link; override with `flash.openocd_interface`.
+    """
+
+    name = "openocd"
+
+    def __init__(self, mcu: str = "",
+                 interface: str = "interface/stlink-dap.cfg",
+                 target: str | None = None):
+        self._interface = interface or "interface/stlink-dap.cfg"
+        self._target = target or openocd_target_for(mcu)
+
+    def available(self) -> str | None:
+        exe = find_openocd()
+        return str(exe) if exe else None
+
+    def _run(self, commands: list[str]) -> tuple[int, str]:
+        exe = find_openocd()
+        if self._target is None:
+            return -1, ("no OpenOCD target mapping for this MCU — set "
+                        "flash.openocd_target in the board profile")
+        if exe is None:
+            return -1, "openocd not found (install it or set OPENOCD_BIN)"
+        cmd = [str(exe)]
+        # xpack layout keeps scripts outside bin/ — pass the search dir
+        # explicitly so `-f target/...` resolves regardless of build.
+        scripts = exe.parent.parent / "openocd" / "scripts"
+        if scripts.is_dir():
+            cmd += ["-s", str(scripts)]
+        # target names map into the target/ script dir; profile overrides
+        # may carry a path or extension already
+        t = self._target
+        target_cfg = t if ("/" in t or t.endswith(".cfg")) else f"target/{t}.cfg"
+        i = self._interface
+        interface_cfg = i if ("/" in i or i.endswith(".cfg")) else f"interface/{i}.cfg"
+        cmd += ["-c", "adapter speed 4000",
+                "-f", interface_cfg, "-f", target_cfg,
+                # mdw/mww/reset need an initialized session; `program`
+                # inits internally and tolerates the explicit one.
+                "-c", "init"]
+        for c in commands:
+            cmd += ["-c", c]
+        cmd += ["-c", "shutdown"]
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=_OPENOCD_TIMEOUT_S,
+                encoding="utf-8", errors="replace",
+                # Neutral cwd (F3): OpenOCD resolves relative -f paths
+                # against ITS cwd first — running from the gated repo
+                # would let a checked-in target/*.cfg shadow the stock
+                # scripts.
+                cwd=str(exe.parent),
+            )
+        except (subprocess.TimeoutExpired, OSError) as exc:
+            return -1, str(exc)
+        return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+    def discover(self) -> str:
+        rc, out = self._run(["adapter list"])
+        if rc == 0:
+            return out.strip()
+        return f"(openocd probe listing unavailable: {out[-300:]})"
+
+    def probe_detected(self, discover_output: str) -> bool:
+        # a connected ST-Link shows up as VID:PID 0483:... plus a DPIDR
+        # line once init reaches the target
+        return ("VID:PID 0483:" in discover_output
+                or "DPIDR" in discover_output)
+
+    def flash(self, bin_path: Path, connect: str, address: str,
+              start: bool = True) -> flasher.FlashResult:
+        if not Path(bin_path).is_file():
+            return flasher.FlashResult(False, f"artifact not found: {bin_path}")
+        # Tcl eats backslashes as escapes — hand OpenOCD forward slashes,
+        # braced so nothing else gets substituted. Braces have NO escape
+        # mechanism: a path containing '{' or '}' cannot be passed safely
+        # and is refused outright (F2).
+        tcl_bin = str(Path(bin_path)).replace("\\", "/")
+        if "{" in tcl_bin or "}" in tcl_bin:
+            return flasher.FlashResult(
+                False, f"artifact path contains '{{' or '}}' — cannot be "
+                f"passed to OpenOCD safely: {tcl_bin}")
+        steps = [f"program {{{tcl_bin}}} {address} verify"]
+        if start:
+            steps.append("reset run")
+        rc, out = self._run(steps)
+        # OpenOCD prints '** Programming Finished **' on success
+        ok = rc == 0 and "** Programming Finished **" in out
+        return flasher.FlashResult(ok, out.strip()[-1200:])
+
+    def write32(self, connect: str, value: int, address: int) -> bool:
+        rc, out = self._run([f"mww 0x{address:08x} 0x{value:08x}"])
+        return rc == 0
+
+    def start_app(self, connect: str) -> bool:
+        rc, out = self._run(["reset run"])
+        return rc == 0
+
+    def read_mem(self, connect: str, address: int, size: int) -> bytes | None:
+        """mdw-based read; returns None on any failure (poll semantics)."""
+        words = (size + 3) // 4
+        rc, out = self._run([f"mdw 0x{address:08x} {words}"])
+        if rc != 0:
+            return None
+        got: list[int] = []
+        # OpenOCD mdw format: "0x2001ff00: f1a5c0de 00010001 ..." —
+        # the ADDRESS carries 0x, the words do not.
+        for m in re.finditer(r"0x[0-9a-fA-F]+:\s+((?:[0-9a-fA-F]{8}\s*)+)",
+                             out):
+            for w in re.finditer(r"[0-9a-fA-F]{8}", m.group(1)):
+                got.append(int(w.group(0), 16))
+        if len(got) < words:
+            return None
+        blob = b"".join(w.to_bytes(4, "little") for w in got[:words])
+        return blob[:size]
+
+
+class FakeBackend(DebugBackend):
+    """CI adapter: no probe, no hardware — scripts decide what happens
+    (design doc §14: build fail / flash timeout / stale identity / probe
+    assertion fail, all in-process). The wipe is modeled with three
+    states: wipe_ok=False fails the write outright; wipe_lies=True
+    reports success while memory is untouched (the silent-lie class the
+    readback guard exists to catch); the default zeroes the region for
+    readbacks until start_app boots the (signing) firmware anew."""
+
+    name = "fake"
+
+    def __init__(self, *, flash_ok: bool = True, signature: bytes | None = None,
+                 wipe_ok: bool = True, wipe_lies: bool = False):
+        self.flash_ok = flash_ok
+        self.signature = signature
+        self.wipe_ok = wipe_ok
+        self.wipe_lies = wipe_lies
+        self._wiped_at: int | None = None
+        self.calls: list[str] = []
+
+    def available(self) -> str | None:
+        return "fake"
+
+    def discover(self) -> str:
+        return "(fake backend)"
+
+    def flash(self, bin_path, connect, address, start=True):
+        self.calls.append(f"flash:{bin_path}@{address}:start={start}")
+        return flasher.FlashResult(self.flash_ok, "fake flash")
+
+    def write32(self, connect, value, address):
+        self.calls.append(f"write32:{address:#x}={value:#x}")
+        if value == 0:
+            if not self.wipe_ok:
+                return False
+            if not self.wipe_lies:
+                self._wiped_at = address
+        return True
+
+    def start_app(self, connect):
+        self.calls.append("start_app")
+        self._wiped_at = None          # new boot: firmware republishes
+        return True
+
+    def read_mem(self, connect, address, size):
+        self.calls.append(f"read:{address:#x}+{size}")
+        if self._wiped_at == address:
+            return b"\x00" * size      # zeroed region while wiped
+        return self.signature[:size] if self.signature else None
+
+
+_BACKENDS: dict[str, type] = {
+    CubeProgrammerBackend.name: CubeProgrammerBackend,
+    OpenOcdBackend.name: OpenOcdBackend,
+    FakeBackend.name: FakeBackend,
+}
+
+
+def known_backends() -> list[str]:
+    return sorted(_BACKENDS)
+
+
+def get_backend(name: str, **kwargs) -> DebugBackend:
+    try:
+        return _BACKENDS[name](**kwargs)
+    except KeyError:
+        raise ValueError(
+            f"unknown debug backend {name!r}; known: {known_backends()}") from None

{flashgate-0.7.2 → flashgate-0.9.0}/flashgate/bench_serve.py

@@ -218,6 +218,50 @@ def _build_driver(bench: BenchDriver):
     return FlashGateBenchDriver
 
 
+def _drain_timeout_s() -> float:
+    """An in-flight verify may QUEUE on the bench lock (default 300 s,
+    FLASHGATE_VERIFY_LOCK_WAIT) before it even starts building, and a
+    hook-shaped verify takes up to ~480 s. A flat 120 s drain abandoned
+    exactly the queued op — no terminal snapshot for a client told a
+    verify was running (adversarial M2): the budget must cover both.
+    Residual, stated honestly: the bench-RPC path has no external cap on
+    a verify, and a worst-case LEGAL body (cold build 300 s + flash +
+    probes) can brush past 480 s — the drain then gives up and says so
+    (see _drain_current) instead of pretending it drained."""
+    from . import cli
+    return cli._verify_lock_wait() + _VERIFY_BUDGET_S
+
+
+_VERIFY_BUDGET_S = 480.0        # the Stop hook's VERIFY_TIMEOUT_S shape;
+                                # NOT a cap the bench path enforces
+
+
+def _drain_current(bench) -> None:
+    """Serve()'s exit path: wait out the in-flight operation (see
+    bench.py's deployment constraint — a daemon worker killed mid-flash
+    leaves CubeProgrammer orphaned and the run without its record).
+    A second Ctrl+C during the drain is ignored on purpose: killing
+    mid-drain recreates exactly that orphan; the printed budget tells
+    the user how long the wait can legitimately take."""
+    current = bench.describe().get("current_operation")
+    if current:
+        budget = _drain_timeout_s()
+        print(f"\n[bench-serve] draining {current} before stop "
+              f"(up to {budget:.0f}s; Ctrl+C is ignored until it "
+              "finishes)...")
+        done = bench.wait(current, timeout_s=budget)
+        state = done.get("state") if done else None
+        if state in ("succeeded", "failed", "cancelled"):
+            print(f"[bench-serve] drained: {state} "
+                  f"exit={done.get('exit_code')}")
+        else:
+            print(f"[bench-serve] drain budget exhausted after "
+                  f"{budget:.0f}s — operation still "
+                  f"{state or 'running'}; it ends here WITHOUT a "
+                  "terminal snapshot (the bench-RPC path has no "
+                  "verify cap; see _drain_timeout_s)")
+
+
 def serve(board: Board, device_id: str | None = None) -> int:
     """Run the bench server until Ctrl+C. Blocks forever."""
     try:
@@ -247,20 +291,16 @@ def serve(board: Board, device_id: str | None = None) -> int:
     except KeyboardInterrupt:
         # Drain before exit (bench.py's deployment constraint): a daemon
         # worker killed mid-flash leaves CubeProgrammer orphaned and the
-        # run without its evidence record. A SECOND interrupt during the
-        # drain would escape and kill the worker mid-flash (R6) — ignore
-        # Ctrl+C/stop re-sends until the drain completes.
+        # run without its evidence record. SIGINT is ignored while the
+        # drain runs: a second Ctrl+C killing the worker mid-flash is the
+        # exact accident the drain exists to prevent. (The lock listener
+        # thread has already returned after the first stop signal.)
         import signal
         try:
             signal.signal(signal.SIGINT, signal.SIG_IGN)
         except (ValueError, OSError):
             pass
-        current = bench.describe().get("current_operation")
-        if current:
-            print(f"\n[bench-serve] draining {current} before stop...")
-            done = bench.wait(current, timeout_s=120)
-            print(f"[bench-serve] drained: {done['state']} "
-                  f"exit={done.get('exit_code')}")
+        _drain_current(bench)
         print("[bench-serve] stopped")
     except Exception as exc:              # e.g. invalid device_id (F5)
         print(f"[bench-serve] failed: {type(exc).__name__}: {exc}")