flashgate 0.7.1__tar.gz → 0.7.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.7.1
+Version: 0.7.2
 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
@@ -69,6 +69,7 @@ including register readbacks (TIM3 CCR), not firmware self-reports:
 ```bash
 pip install -e .                 # Python 3.11+
 pip install -e ".[mcp]"          # optional MCP server
+pip install -e ".[bench]"        # optional remote bench (device-connect)
 
 flashgate doctor                 # ST-Link / serial / toolchain sanity
 flashgate verify --all-probes    # build → flash → evidence → sha → probes
@@ -134,6 +135,9 @@ tree+profile+tool-version identity the verdict applies to. The MCP
 firmware repo's `.gitignore` (the shipped example does), or every record
 write churns the fingerprint. A record that cannot be written is a
 warning, never a changed exit code — and a crashed run still leaves one.
+The newest ~500 records are kept (best-effort pruning). `flashgate verify
+--json` prints this run's record as pure-ASCII JSON on stdout (human logs
+move to stderr) for scripting — safe on any console codepage.
 
 ## Remote bench (device-connect, Stage 2)
 
@@ -148,11 +152,16 @@ DEVICE_CONNECT_ALLOW_INSECURE=true DEVICE_CONNECT_DISCOVERY_MODE=d2d   flashgate
 ```
 
 Remote callers discover `device_type=flashgate-bench` and use
-`describe_bench` / `start_verify` / `get_operation` / `cancel_operation`.
+`describe_bench` / `start_verify` / `get_operation` / `cancel_operation`,
+plus a `verify_completed` event per operation at its terminal state (an
+operation drained during server shutdown does not emit one — polling
+remains the authoritative contract).
 `start_verify` returns an `op_id` immediately (single verify at a time —
 a client retrying over a flaky network can never trigger a second
 flash); poll `get_operation` to the terminal snapshot, which carries the
-exit code and the run's full evidence record.
+exit code and the run's full evidence record. Stop the server without
+hunting PIDs: `flashgate --board <profile> bench-serve --stop` (it
+drains the in-flight operation, then exits).
 
 **The red line for every consumer**: the mesh wraps any normally-delivered
 reply as `success: true` — including a busy bench answering
@@ -180,6 +189,13 @@ fingerprint identifies the SOURCE).
   same-named servers split-brained the mesh and raced each other for
   the board's serial port.
 
+**Third-party licensing**: the `bench` extra depends on
+[device-connect-edge](https://github.com/arm/device-connect)
+(Apache-2.0) as a pip dependency only — flashgate stays MIT, and no
+device-connect source is vendored into this repository (fixes go
+upstream as PRs). Commercial distributions that bundle the dependency
+must include its LICENSE and NOTICE files.
+
 **Security posture, stated plainly**: D2D mode is zero-authentication —
 anyone on the same LAN can discover the bench and `start_verify`, which
 FLASHES THE BOARD. Descriptions and records also carry local paths.
@@ -241,9 +257,11 @@ full profile field reference.
 
 ## Status
 
-Boot gate, probe gate, Stop hook, MCP server, SWD signature channel — all
-implemented and validated on real hardware. Windows-first; Linux/macOS
-untested.
+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.
 
 ## License
 
@@ -267,6 +285,10 @@ flashgate 回答一个很具体的问题：刚编译出来的固件，烧到板
 - 版本身份带 `-dirty` 语义，验证通过意味着板上跑的就是当前工作区
 - 探针下真命令、断言硬件寄存器读回值；响应报的是实际状态不是回声，
   静默失效的设置第一步就会露馅
+- 每次验证（无论成败）都留一份证据记录：逐项检查结论、板子的原话、
+  产物哈希——事后可审计"当时验证的是什么、板子说了什么"
+- `bench-serve` 可以把整个台架挂上局域网：远程 agent 用 device-connect
+  协议发现它、请求真机验证、拿回带证据的结论（跨机实测通过）
 - Stop hook 挂进 Claude Code：agent 改了固件没过真机验证就说"完成"，
   会被拦下并收到板子的失败证词；同一棵坏树最多拦两次，之后放行但
   打警告，会话不会被卡死

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

@@ -48,6 +48,7 @@ including register readbacks (TIM3 CCR), not firmware self-reports:
 ```bash
 pip install -e .                 # Python 3.11+
 pip install -e ".[mcp]"          # optional MCP server
+pip install -e ".[bench]"        # optional remote bench (device-connect)
 
 flashgate doctor                 # ST-Link / serial / toolchain sanity
 flashgate verify --all-probes    # build → flash → evidence → sha → probes
@@ -113,6 +114,9 @@ tree+profile+tool-version identity the verdict applies to. The MCP
 firmware repo's `.gitignore` (the shipped example does), or every record
 write churns the fingerprint. A record that cannot be written is a
 warning, never a changed exit code — and a crashed run still leaves one.
+The newest ~500 records are kept (best-effort pruning). `flashgate verify
+--json` prints this run's record as pure-ASCII JSON on stdout (human logs
+move to stderr) for scripting — safe on any console codepage.
 
 ## Remote bench (device-connect, Stage 2)
 
@@ -127,11 +131,16 @@ DEVICE_CONNECT_ALLOW_INSECURE=true DEVICE_CONNECT_DISCOVERY_MODE=d2d   flashgate
 ```
 
 Remote callers discover `device_type=flashgate-bench` and use
-`describe_bench` / `start_verify` / `get_operation` / `cancel_operation`.
+`describe_bench` / `start_verify` / `get_operation` / `cancel_operation`,
+plus a `verify_completed` event per operation at its terminal state (an
+operation drained during server shutdown does not emit one — polling
+remains the authoritative contract).
 `start_verify` returns an `op_id` immediately (single verify at a time —
 a client retrying over a flaky network can never trigger a second
 flash); poll `get_operation` to the terminal snapshot, which carries the
-exit code and the run's full evidence record.
+exit code and the run's full evidence record. Stop the server without
+hunting PIDs: `flashgate --board <profile> bench-serve --stop` (it
+drains the in-flight operation, then exits).
 
 **The red line for every consumer**: the mesh wraps any normally-delivered
 reply as `success: true` — including a busy bench answering
@@ -159,6 +168,13 @@ fingerprint identifies the SOURCE).
   same-named servers split-brained the mesh and raced each other for
   the board's serial port.
 
+**Third-party licensing**: the `bench` extra depends on
+[device-connect-edge](https://github.com/arm/device-connect)
+(Apache-2.0) as a pip dependency only — flashgate stays MIT, and no
+device-connect source is vendored into this repository (fixes go
+upstream as PRs). Commercial distributions that bundle the dependency
+must include its LICENSE and NOTICE files.
+
 **Security posture, stated plainly**: D2D mode is zero-authentication —
 anyone on the same LAN can discover the bench and `start_verify`, which
 FLASHES THE BOARD. Descriptions and records also carry local paths.
@@ -220,9 +236,11 @@ full profile field reference.
 
 ## Status
 
-Boot gate, probe gate, Stop hook, MCP server, SWD signature channel — all
-implemented and validated on real hardware. Windows-first; Linux/macOS
-untested.
+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.
 
 ## License
 
@@ -246,6 +264,10 @@ flashgate 回答一个很具体的问题：刚编译出来的固件，烧到板
 - 版本身份带 `-dirty` 语义，验证通过意味着板上跑的就是当前工作区
 - 探针下真命令、断言硬件寄存器读回值；响应报的是实际状态不是回声，
   静默失效的设置第一步就会露馅
+- 每次验证（无论成败）都留一份证据记录：逐项检查结论、板子的原话、
+  产物哈希——事后可审计"当时验证的是什么、板子说了什么"
+- `bench-serve` 可以把整个台架挂上局域网：远程 agent 用 device-connect
+  协议发现它、请求真机验证、拿回带证据的结论（跨机实测通过）
 - Stop hook 挂进 Claude Code：agent 改了固件没过真机验证就说"完成"，
   会被拦下并收到板子的失败证词；同一棵坏树最多拦两次，之后放行但
   打警告，会话不会被卡死

{flashgate-0.7.1 → flashgate-0.7.2}/flashgate/bench.py

@@ -110,10 +110,12 @@ class _Operation:
 class BenchDriver:
     """Single-board bench: owns one in-flight verify and its history."""
 
-    def __init__(self, board: Board, verify_fn: VerifyFn | None = None):
+    def __init__(self, board: Board, verify_fn: VerifyFn | None = None,
+                 on_complete: "Callable[[dict], None] | None" = None):
         self._board = board
         self._verify_fn = verify_fn or (
             lambda b, names: cli_mod.cmd_verify(b, names))
+        self._on_complete = on_complete    # auxiliary: see set_on_complete
         self._lock = threading.Lock()
         self._ops: dict[str, _Operation] = {}
         self._threads: dict[str, threading.Thread] = {}
@@ -128,6 +130,22 @@ class BenchDriver:
                     f"(single-flight and record association both assume it)")
             _DRIVERS[key] = self
 
+    def set_on_complete(self, cb: "Callable[[dict], None] | None") -> None:
+        """Register a best-effort completion callback: invoked once with
+        the terminal snapshot when an operation reaches succeeded/failed/
+        cancelled. Exceptions in the callback are swallowed —
+        notification must never affect the operation or the bench (the
+        RPC front-end uses this to emit verify_completed events)."""
+        self._on_complete = cb
+
+    def _notify(self, op: _Operation) -> None:
+        if self._on_complete is None:
+            return
+        try:
+            self._on_complete(op.snapshot())
+        except Exception:
+            pass
+
     # ------------------------------------------------------ describe_bench
     def describe(self) -> dict:
         probes_error = ""
@@ -200,9 +218,14 @@ class BenchDriver:
                 op.state = "cancelled"
                 op.finished_at = _iso()
                 op.summary = "cancelled before execution"
-                return True
-            op.cancel_requested = True
-            return False
+                cancelled = True
+            else:
+                cancelled = False
+                op.cancel_requested = True
+        if cancelled:
+            self._notify(op)                 # outside the lock: a custom
+            return True                      # callback may query the bench
+        return False
 
     # ------------------------------------------------------ wait (helper)
     def wait(self, op_id: str, timeout_s: float = 600.0) -> dict | None:
@@ -237,6 +260,7 @@ class BenchDriver:
                     op.state = "failed"
                     op.error = ((op.error + " | ") if op.error else "") + \
                         "worker exited without a verdict"
+            self._notify(op)
 
     def _attach_record(self, op: _Operation) -> None:
         """Attach THIS run's evidence record via the in-process registry.

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

@@ -24,6 +24,8 @@ from __future__ import annotations
 
 import asyncio
 import socket
+import threading
+import _thread
 import zlib
 from pathlib import Path
 from typing import Optional
@@ -60,8 +62,68 @@ def acquire_bench_lock(fw_dir: Path) -> socket.socket:
             f"owns lock port {_lock_port(fw_dir)}; kill it first)")
 
 
+def _start_lock_listener(lock: socket.socket,
+                         interrupt=None) -> threading.Thread:
+    """Accept `stop` commands on the bench lock port. The stopper gets an
+    immediate ack; THIS process then exits through serve()'s drain path —
+    the operator never has to hunt for a PID (the pain that motivated
+    this, see v0.7.1 field notes).
+
+    `interrupt` defaults to interrupting the MAIN thread (where serve()
+    runs asyncio.run — the KeyboardInterrupt unwinds through the drain
+    path). It is injectable so tests can observe the signal without
+    receiving a real KeyboardInterrupt."""
+    if interrupt is None:
+        interrupt = _thread.interrupt_main
+    def _loop() -> None:
+        while True:
+            try:
+                conn, _ = lock.accept()
+            except OSError:
+                return                       # lock closed: server exiting
+            try:
+                conn.settimeout(2)           # a silent local connection must
+                data = conn.recv(64)         # not wedge the stop channel (R4)
+                if data.strip().lower() == b"stop":
+                    try:
+                        conn.sendall(b"ok: draining and stopping\n")
+                    except OSError:
+                        pass
+                    try:
+                        interrupt()
+                    except Exception:
+                        pass
+                    return
+                conn.sendall(b"unknown command\n")
+            except OSError:
+                pass
+            finally:
+                try:
+                    conn.close()
+                except OSError:
+                    pass
+    t = threading.Thread(target=_loop, daemon=True,
+                         name="flashgate-bench-lock")
+    t.start()
+    return t
+
+
+def stop_bench(fw_dir: Path) -> bool:
+    """Signal a running bench-serve for this firmware dir to stop.
+    True = signalled (it drains its in-flight operation, then exits);
+    False = no bench-serve is holding the lock."""
+    try:
+        with socket.create_connection(("127.0.0.1", _lock_port(fw_dir)),
+                                      timeout=3) as s:
+            s.sendall(b"stop\n")
+            reply = s.recv(128).decode("utf-8", errors="replace")
+        return reply.startswith("ok")
+    except OSError:
+        return False
+
+
 def _build_driver(bench: BenchDriver):
-    from device_connect_edge.drivers import DeviceDriver, rpc
+    from device_connect_edge.drivers import DeviceDriver, emit, rpc
 
     class FlashGateBenchDriver(DeviceDriver):
         device_type = "flashgate-bench"
@@ -69,10 +131,46 @@ def _build_driver(bench: BenchDriver):
         def __init__(self, bench: BenchDriver):
             super().__init__()          # base builds _functions_cache etc.
             self._bench = bench
+            self._loop: "asyncio.AbstractEventLoop | None" = None
+
+        @emit()
+        async def verify_completed(self, op_id: str, state: str,
+                                   exit_code: Optional[int] = None,
+                                   status: Optional[str] = None) -> None:
+            """Fires once per operation at its terminal state
+            (succeeded / failed / cancelled) — polling-free completion
+            for remote consumers. Auxiliary: polling get_operation
+            remains the authoritative contract."""
+
+        def _operation_done(self, snapshot: dict) -> None:
+            # Called from the bench worker THREAD: hop onto the runtime
+            # loop. Best-effort — an emit failure never touches the op.
+            loop = self._loop
+            if loop is None or loop.is_closed():
+                return
+            payload = {"op_id": snapshot["op_id"], "state": snapshot["state"]}
+            # Omit null fields entirely: the SDK's schema converter drops
+            # Optional's null, so emitting exit_code=None (cancelled /
+            # crashed ops) would produce payload/schema contradictions
+            # for validating consumers (adversarial review R2).
+            if snapshot.get("exit_code") is not None:
+                payload["exit_code"] = snapshot["exit_code"]
+            if snapshot.get("status") is not None:
+                payload["status"] = snapshot["status"]
+            try:
+                asyncio.run_coroutine_threadsafe(
+                    self.verify_completed(**payload), loop)
+            except Exception:
+                pass
+
+        def _remember_loop(self) -> None:
+            if self._loop is None:
+                self._loop = asyncio.get_running_loop()
 
         @rpc()
         async def describe_bench(self) -> dict:
             """Board identity, probe list, busy state of this bench."""
+            self._remember_loop()
             return bench.describe()
 
         @rpc()
@@ -94,6 +192,7 @@ def _build_driver(bench: BenchDriver):
                 # argument must not cost a build+flash cycle
                 return {"error": "invalid_argument",
                         "detail": "probes must be a list of probe names or null"}
+            self._remember_loop()
             try:
                 return bench.start_verify(probes)
             except BenchBusyError as exc:
@@ -134,18 +233,28 @@ def serve(board: Board, device_id: str | None = None) -> int:
         print(f"[bench-serve] {exc}")
         return 2
 
+    _start_lock_listener(lock)
     bench = BenchDriver(board)
-    driver_cls = _build_driver(bench)
+    driver = _build_driver(bench)(bench)
+    bench.set_on_complete(driver._operation_done)   # verify_completed events
     ident = device_id or f"flashgate-bench-{board.name}"
     print(f"[bench-serve] {ident}: {board.name} ({board.mcu}) — "
-          f"four RPCs over device-connect; Ctrl+C to stop")
+          f"four RPCs over device-connect; Ctrl+C or `bench-serve --stop` "
+          f"to stop")
     try:
-        asyncio.run(DeviceRuntime(driver=driver_cls(bench),
+        asyncio.run(DeviceRuntime(driver=driver,
                                   device_id=ident).run())
     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.
+        # 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.
+        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...")

{flashgate-0.7.1 → flashgate-0.7.2}/flashgate/cli.py

@@ -10,6 +10,9 @@ Exit-code contract (the M3 Stop hook enforces these):
 from __future__ import annotations
 
 import argparse
+import contextlib
+import io
+import json
 import os
 import re
 import shutil
@@ -648,6 +651,9 @@ def main(argv: list[str] | None = None) -> int:
                           help="run every probe defined in the board profile")
     p_verify.add_argument("--evidence", choices=["uart", "swd", "auto"],
                           help="boot-evidence channel (default: board profile evidence.mode)")
+    p_verify.add_argument("--json", action="store_true",
+                          help="print this run's evidence record as JSON on "
+                               "stdout (human logs move to stderr)")
     p_probe = sub.add_parser("probe", help="run probes against running firmware")
     p_probe.add_argument("names", nargs="*", metavar="NAME",
                          help="probe names (default: all defined in the board profile)")
@@ -656,6 +662,10 @@ def main(argv: list[str] | None = None) -> int:
         "bench-serve", help="expose this bench over device-connect (optional extra: flashgate[bench])")
     p_bench.add_argument("--device-id", default=None,
                          help="device-connect id (default: flashgate-bench-<board>)")
+    p_bench.add_argument("--stop", action="store_true",
+                         help="signal the running bench-serve for this "
+                              "board to stop (drains, then exits) instead "
+                              "of starting a new one")
 
     args = parser.parse_args(argv)
     try:
@@ -669,11 +679,35 @@ def main(argv: list[str] | None = None) -> int:
             names: list[str] | None = args.probe
             if args.all_probes:
                 names = ["all"]
+            if getattr(args, "json", False):
+                # stdout is the machine channel: human logs go to stderr
+                with contextlib.redirect_stdout(sys.stderr):
+                    rc = cmd_verify(board, names, getattr(args, "evidence", None))
+                last = records.LAST
+                if last is not None and Path(last["fw_dir"]) == board.firmware_dir:
+                    # ensure_ascii (default): the JSON must survive ANY
+                    # consumer codepage — a cp936 pipe meeting U+FFFD from
+                    # serial noise used to raise UnicodeEncodeError, wipe
+                    # stdout and exit 1, which scripts misread as BUILD
+                    # FAILED (adversarial review R1).
+                    print(json.dumps(last["record"]))
+                else:
+                    print(json.dumps({"error": "no record written",
+                                      "exit_code": rc}))
+                return rc
             return cmd_verify(board, names, getattr(args, "evidence", None))
         if args.cmd == "probe":
             return cmd_probe(board, args.names or None)
         if args.cmd == "bench-serve":
-            from .bench_serve import serve
+            from .bench_serve import serve, stop_bench
+            if args.stop:
+                if stop_bench(board.firmware_dir):
+                    print("[bench-serve] stop signalled — the server drains "
+                          "its in-flight operation, then exits")
+                    return 0
+                print("[bench-serve] no bench-serve is holding the lock for "
+                      f"{board.firmware_dir}")
+                return 2
             return serve(board, args.device_id)
         simple = {
             "doctor": cmd_doctor, "build": cmd_build,

{flashgate-0.7.1 → flashgate-0.7.2}/flashgate/records.py

@@ -30,6 +30,12 @@ if TYPE_CHECKING:                     # stdlib-only at runtime (CLI dep);
 RECORDS_SCHEMA_VERSION = "1.0"
 RECORDS_DIRNAME = ".flashgate/records"
 
+# Retention: records are small (a few KB each), but a bench left running
+# for months would grow the dir without bound (architecture doc open
+# question #2). Oldest files are pruned past the cap; the newest PASS
+# and the running audit window are always preserved well inside it.
+MAX_RECORDS = 500
+
 # In-process registry of the record written by the LAST write_record call.
 # The MCP server (which runs cmd_verify in-process) uses it to attach THIS
 # run's record — never a stale one picked blindly by mtime.
@@ -219,9 +225,42 @@ def write_record(record: dict, fw_dir: Path, fingerprint: str = "") -> Path:
                     encoding="utf-8")
     LAST = {"path": path, "record": record, "fw_dir": fw_dir,
             "at": time.monotonic()}
+    _prune(fw_dir, exempt=path)
     return path
 
 
+def _prune(fw_dir: Path, keep: int | None = None,
+           exempt: Path | None = None) -> None:
+    """Keep only the newest `keep` records (mtime order). Best-effort:
+    a file that cannot be deleted is skipped — retention must never
+    break record writing. `keep=None` resolves MAX_RECORDS at call time
+    (a plain default arg would freeze the constant at import)."""
+    if keep is None:
+        keep = MAX_RECORDS
+    directory = records_dir(fw_dir)
+    try:
+        # Secondary key = filename (its timestamp prefix): rapid writes
+        # land on the same mtime tick and a glob-order tiebreak could
+        # judge the JUST-WRITTEN file as oldest (flake found by the
+        # mutation round's baseline runs).
+        candidates = sorted(directory.glob("*.json"),
+                             key=lambda p: (p.stat().st_mtime, p.name))
+        excess = candidates[:-keep] if keep else []
+        if exempt is not None:
+            # After an NTP clock rollback every EXISTING file looks
+            # "newer" than this one — the just-written record may land in
+            # the excess list; drop it from the DELETION list only (it
+            # still counts toward the cap, so steady state stays exact).
+            excess = [f for f in excess if f != exempt]
+    except OSError:
+        return
+    for stale in excess:
+        try:
+            stale.unlink()
+        except OSError:
+            pass
+
+
 def latest_record(fw_dir: Path) -> dict | None:
     """Most recent record (by mtime), or None when none exist yet."""
     directory = records_dir(fw_dir)

{flashgate-0.7.1 → flashgate-0.7.2}/flashgate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.7.1
+Version: 0.7.2
 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
@@ -69,6 +69,7 @@ including register readbacks (TIM3 CCR), not firmware self-reports:
 ```bash
 pip install -e .                 # Python 3.11+
 pip install -e ".[mcp]"          # optional MCP server
+pip install -e ".[bench]"        # optional remote bench (device-connect)
 
 flashgate doctor                 # ST-Link / serial / toolchain sanity
 flashgate verify --all-probes    # build → flash → evidence → sha → probes
@@ -134,6 +135,9 @@ tree+profile+tool-version identity the verdict applies to. The MCP
 firmware repo's `.gitignore` (the shipped example does), or every record
 write churns the fingerprint. A record that cannot be written is a
 warning, never a changed exit code — and a crashed run still leaves one.
+The newest ~500 records are kept (best-effort pruning). `flashgate verify
+--json` prints this run's record as pure-ASCII JSON on stdout (human logs
+move to stderr) for scripting — safe on any console codepage.
 
 ## Remote bench (device-connect, Stage 2)
 
@@ -148,11 +152,16 @@ DEVICE_CONNECT_ALLOW_INSECURE=true DEVICE_CONNECT_DISCOVERY_MODE=d2d   flashgate
 ```
 
 Remote callers discover `device_type=flashgate-bench` and use
-`describe_bench` / `start_verify` / `get_operation` / `cancel_operation`.
+`describe_bench` / `start_verify` / `get_operation` / `cancel_operation`,
+plus a `verify_completed` event per operation at its terminal state (an
+operation drained during server shutdown does not emit one — polling
+remains the authoritative contract).
 `start_verify` returns an `op_id` immediately (single verify at a time —
 a client retrying over a flaky network can never trigger a second
 flash); poll `get_operation` to the terminal snapshot, which carries the
-exit code and the run's full evidence record.
+exit code and the run's full evidence record. Stop the server without
+hunting PIDs: `flashgate --board <profile> bench-serve --stop` (it
+drains the in-flight operation, then exits).
 
 **The red line for every consumer**: the mesh wraps any normally-delivered
 reply as `success: true` — including a busy bench answering
@@ -180,6 +189,13 @@ fingerprint identifies the SOURCE).
   same-named servers split-brained the mesh and raced each other for
   the board's serial port.
 
+**Third-party licensing**: the `bench` extra depends on
+[device-connect-edge](https://github.com/arm/device-connect)
+(Apache-2.0) as a pip dependency only — flashgate stays MIT, and no
+device-connect source is vendored into this repository (fixes go
+upstream as PRs). Commercial distributions that bundle the dependency
+must include its LICENSE and NOTICE files.
+
 **Security posture, stated plainly**: D2D mode is zero-authentication —
 anyone on the same LAN can discover the bench and `start_verify`, which
 FLASHES THE BOARD. Descriptions and records also carry local paths.
@@ -241,9 +257,11 @@ full profile field reference.
 
 ## Status
 
-Boot gate, probe gate, Stop hook, MCP server, SWD signature channel — all
-implemented and validated on real hardware. Windows-first; Linux/macOS
-untested.
+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.
 
 ## License
 
@@ -267,6 +285,10 @@ flashgate 回答一个很具体的问题：刚编译出来的固件，烧到板
 - 版本身份带 `-dirty` 语义，验证通过意味着板上跑的就是当前工作区
 - 探针下真命令、断言硬件寄存器读回值；响应报的是实际状态不是回声，
   静默失效的设置第一步就会露馅
+- 每次验证（无论成败）都留一份证据记录：逐项检查结论、板子的原话、
+  产物哈希——事后可审计"当时验证的是什么、板子说了什么"
+- `bench-serve` 可以把整个台架挂上局域网：远程 agent 用 device-connect
+  协议发现它、请求真机验证、拿回带证据的结论（跨机实测通过）
 - Stop hook 挂进 Claude Code：agent 改了固件没过真机验证就说"完成"，
   会被拦下并收到板子的失败证词；同一棵坏树最多拦两次，之后放行但
   打警告，会话不会被卡死

{flashgate-0.7.1 → flashgate-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flashgate"
-version = "0.7.1"
+version = "0.7.2"
 description = "Hardware-in-the-loop verification gate: your agent can't claim the firmware works until the board says so."
 readme = "README.md"
 requires-python = ">=3.11"

{flashgate-0.7.1 → flashgate-0.7.2}/tests/test_bench.py

@@ -347,3 +347,55 @@ class TestHardening:
             bench_mod.probe_mod.load_probes = orig
         assert info["probes"] == []
         assert "bad probes yaml" in info["probes_error"]
+
+
+class TestCompletionCallback:
+    def test_notified_on_success_and_failure(self, tmp_path):
+        board = make_board(tmp_path)
+        events = []
+        d = BenchDriver(board, verify_fn=lambda b, n: len(events))
+        d.set_on_complete(lambda snap: events.append((snap["op_id"], snap["state"])))
+        d.wait(d.start_verify()["op_id"], 5)
+        d.wait(d.start_verify()["op_id"], 5)
+        assert [s for _, s in events] == ["succeeded", "failed"]
+
+    def test_notified_on_pre_start_cancel(self, tmp_path):
+        from flashgate.bench import _Operation
+        board = make_board(tmp_path)
+        events = []
+        d = BenchDriver(board, verify_fn=lambda b, n: 0)
+        d.set_on_complete(lambda snap: events.append(snap["state"]))
+        with d._lock:
+            op = _Operation(op_id="op-x", created_at="now")
+            d._ops[op.op_id] = op
+            d._current = op
+        assert d.cancel_operation("op-x") is True
+        assert events == ["cancelled"]
+
+    def test_callback_exception_swallowed(self, tmp_path):
+        board = make_board(tmp_path)
+
+        def boom(snap):
+            raise RuntimeError("callback bug")
+
+        d = BenchDriver(board, verify_fn=lambda b, n: 0)
+        d.set_on_complete(boom)
+        done = d.wait(d.start_verify()["op_id"], 5)
+        assert done["state"] == "succeeded"          # bench unaffected
+
+
+class TestCallbackGuard:
+    """Mutation P5: a callback exception must not even surface as an
+    unhandled-thread-exception warning."""
+
+    @pytest.mark.filterwarnings(
+        "error::pytest.PytestUnhandledThreadExceptionWarning")
+    def test_callback_exception_no_thread_warning(self, tmp_path):
+        board = make_board(tmp_path)
+
+        def boom(snap):
+            raise RuntimeError("callback bug")
+
+        d = BenchDriver(board, verify_fn=lambda b, n: 0)
+        d.set_on_complete(boom)
+        assert d.wait(d.start_verify()["op_id"], 5)["state"] == "succeeded"

{flashgate-0.7.1 → flashgate-0.7.2}/tests/test_bench_serve.py

@@ -166,3 +166,92 @@ class TestSingleInstanceLock:
             assert "one bench-serve per bench" in capsys.readouterr().out
         finally:
             lock.close()
+
+
+class TestStopChannel:
+    def test_stop_signals_live_listener(self, tmp_path):
+        from pathlib import Path as P
+        from flashgate.bench_serve import (_start_lock_listener,
+                                           acquire_bench_lock, stop_bench)
+        signalled = []
+        # interrupt is called with NO arguments (like _thread.interrupt_main)
+        lock = acquire_bench_lock(tmp_path)
+        try:
+            thread = _start_lock_listener(
+                lock, interrupt=lambda: signalled.append("FIRED"))
+            assert stop_bench(tmp_path) is True
+            thread.join(timeout=3)
+            assert not thread.is_alive()
+            assert signalled == ["FIRED"]   # the stop signal fired once
+        finally:
+            lock.close()
+
+    def test_stop_without_holder_is_false(self, tmp_path):
+        from flashgate.bench_serve import stop_bench
+        (tmp_path / "free").mkdir(exist_ok=True)
+        assert stop_bench(tmp_path / "free") is False
+
+    def test_cli_stop_without_server_exit_2(self, tmp_path, monkeypatch, capsys):
+        from flashgate import cli
+        board = make_board(tmp_path)
+        rc = cli.main(["--board", str(board.yaml_path), "bench-serve", "--stop"])
+        assert rc == 2
+        assert "no bench-serve" in capsys.readouterr().out
+
+
+class TestCompletedEventWiring:
+    def test_operation_done_noop_without_loop(self, tmp_path):
+        board = make_board(tmp_path)
+        bench = BenchDriver(board, verify_fn=lambda b, n: 0)
+        drv = _build_driver(bench)(bench)
+        drv._operation_done({"op_id": "x", "state": "succeeded"})  # no crash
+
+    def test_loop_captured_on_first_rpc(self, tmp_path):
+        board = make_board(tmp_path)
+        bench = BenchDriver(board, verify_fn=lambda b, n: 0)
+        drv = _build_driver(bench)(bench)
+        assert drv._loop is None
+        asyncio.run(drv.describe_bench())
+        assert drv._loop is not None
+
+
+class TestEventAndStopGuards:
+    """Mutation P6/P8: the loop guard must actually skip scheduling, and
+    stop_bench must not claim success without an ok ack."""
+
+    def test_no_scheduling_without_loop(self, tmp_path, monkeypatch):
+        board = make_board(tmp_path)
+        bench = BenchDriver(board, verify_fn=lambda b, n: 0)
+        drv = _build_driver(bench)(bench)
+        calls = []
+        monkeypatch.attr_target = None
+        import flashgate.bench_serve as bs
+        monkeypatch.setattr(
+            bs.asyncio, "run_coroutine_threadsafe",
+            lambda coro, loop: calls.append(loop))
+        drv._operation_done({"op_id": "x", "state": "succeeded"})
+        assert calls == []                 # loop None: nothing scheduled
+        import threading
+        loop = asyncio.new_event_loop()
+        t = threading.Thread(target=loop.run_forever, daemon=True)
+        t.start()
+        try:
+            drv._loop = loop               # as _remember_loop would
+            drv._operation_done({"op_id": "y", "state": "failed"})
+            assert len(calls) == 1 and calls[0] is loop
+            loop.call_soon_threadsafe(loop.stop)
+        finally:
+            t.join(2)
+            loop.close()
+
+    def test_stop_bench_false_without_ok_ack(self, tmp_path):
+        import socket as pysocket
+        from flashgate.bench_serve import _lock_port, stop_bench
+        # an impostor holds the port but does not speak the protocol
+        impostor = pysocket.socket()
+        impostor.bind(("127.0.0.1", _lock_port(tmp_path)))
+        impostor.listen(1)
+        try:
+            assert stop_bench(tmp_path) is False
+        finally:
+            impostor.close()

{flashgate-0.7.1 → flashgate-0.7.2}/tests/test_cli.py

@@ -281,3 +281,77 @@ class TestUartBuildFailRecord:
         assert by_name["console"]["status"] == "passed"
         assert by_name["build"]["status"] == "failed"
         assert by_name["identity"]["status"] == "skipped"
+
+
+class TestVerifyJsonFlag:
+    def test_json_stdout_pure_record(self, tmp_path, monkeypatch, capsys):
+        from flashgate import records as rec
+        board = make_board(tmp_path)
+        monkeypatch.setattr(cli, "_console_port", lambda b: (None, "no serial"))
+        monkeypatch.setattr(cli, "_build", lambda b, j=None: cli.EXIT_BUILD)
+        rc = cli.main(["--board", str(board.yaml_path), "verify", "--json"])
+        assert rc == cli.EXIT_BUILD
+        out = capsys.readouterr()
+        import json as _json
+        payload = _json.loads(out.out.strip().splitlines()[-1])
+        assert payload["run"]["exit_code"] == 1
+        by_name = {c["name"]: c for c in payload["checks"]}
+        assert by_name["build"]["status"] == "failed"
+        assert by_name["identity"]["status"] == "skipped"
+        assert "[verify]" in out.err                  # human logs on stderr
+
+
+class TestVerifyJsonGuard:
+    """Mutation P4: a stale LAST entry from ANOTHER firmware dir must not
+    be printed as this run's record."""
+
+    def test_foreign_last_not_printed(self, tmp_path, monkeypatch, capsys):
+        import json as _json
+        from flashgate import records as rec
+        board = make_board(tmp_path)
+        rec.LAST = {"path": None, "fw_dir": "Z:/somewhere-else",
+                    "record": {"run": {"exit_code": 0}}, "at": 0.0}
+
+        def no_write(b, names, evidence=None):
+            return 7                      # fails, writes nothing
+
+        monkeypatch.setattr(cli, "cmd_verify", no_write)
+        rc = cli.main(["--board", str(board.yaml_path), "verify", "--json"])
+        assert rc == 7
+        payload = _json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+        assert payload == {"error": "no record written", "exit_code": 7}
+
+    def test_stdout_carries_no_human_logs(self, tmp_path, monkeypatch, capsys):
+        board = make_board(tmp_path)
+        monkeypatch.setattr(cli, "_console_port", lambda b: (None, "no serial"))
+        monkeypatch.setattr(cli, "_build", lambda b, j=None: cli.EXIT_BUILD)
+        cli.main(["--board", str(board.yaml_path), "verify", "--json"])
+        out = capsys.readouterr().out
+        assert "[verify]" not in out and "[build]" not in out
+
+
+class TestJsonEncodingGuard:
+    """Adversarial R1: the JSON must survive a non-UTF-8 consumer pipe —
+    U+FFFD from serial noise met cp936 and used to wipe stdout, exit 1."""
+
+    def test_json_output_is_pure_ascii(self, tmp_path, monkeypatch, capsys):
+        import json as _json
+        from flashgate import records as rec
+        board = make_board(tmp_path)
+
+        def noisy(b, names, evidence=None):
+            j = rec.VerifyJournal(["boot"], mode="uart", probe_names=names)
+            j.check("boot", "failed")
+            j.add_evidence("console-tail", "COM3",
+                           "noise \ufffd 拒绝访问 \ufffd")
+            r = j.to_record(b, 3, "timed_out", "x")
+            rec.write_record(r, b.firmware_dir, fingerprint="ee" * 32)
+            return 3
+
+        monkeypatch.setattr(cli, "cmd_verify", noisy)
+        rc = cli.main(["--board", str(board.yaml_path), "verify", "--json"])
+        assert rc == 3
+        raw = capsys.readouterr().out.strip().splitlines()[-1]
+        raw.encode("ascii")                       # must not raise
+        payload = _json.loads(raw)
+        assert "\ufffd" in str(payload)           # content survives, escaped

{flashgate-0.7.1 → flashgate-0.7.2}/tests/test_records.py

@@ -6,6 +6,7 @@ record-level echo of the gate's core rule.
 """
 
 import hashlib
+import json
 from pathlib import Path
 from types import SimpleNamespace
 
@@ -233,3 +234,62 @@ class TestCrashNetAndUniqueness:
         # compare by path content, NOT latest_record's mtime order —
         # same-tick writes make that ordering flaky on some filesystems
         assert _json.loads(p2.read_text(encoding="utf-8"))["record_id"] == p2.stem
+
+
+class TestRetention:
+    """Architecture-doc open question #2: records must not grow unbounded."""
+
+    def test_prune_keeps_newest_cap(self, tmp_path, monkeypatch):
+        from flashgate import records as rec
+        monkeypatch.setattr(rec, "MAX_RECORDS", 5)
+        for i in range(8):
+            j = rec.VerifyJournal(["build"], mode="swd", probe_names=None)
+            j.check("build", "passed")
+            rec.write_record(j.to_record(_board_stub(), i % 8, "failed", "x"),
+                             tmp_path, fingerprint=f"{i:064d}")
+        files = sorted(rec.records_dir(tmp_path).glob("*.json"))
+        assert len(files) == 5
+        kept = [json.loads(f.read_text(encoding="utf-8"))["run"]["exit_code"]
+                for f in files]
+        assert kept == [3, 4, 5, 6, 7]      # the five NEWEST by mtime
+
+    def test_prune_never_breaks_writing(self, tmp_path, monkeypatch):
+        import pytest
+        from flashgate import records as rec
+        monkeypatch.setattr(rec, "MAX_RECORDS", 2)
+        for i in range(4):
+            j = rec.VerifyJournal(["build"], mode="swd", probe_names=None)
+            j.check("build", "passed")
+            path = rec.write_record(
+                j.to_record(_board_stub(), 0, "succeeded", "x"),
+                tmp_path, fingerprint=f"{i:064d}")
+            assert path.exists()
+
+
+class TestPruneGuards:
+    """Adversarial-round fixes: the just-written record survives an NTP
+    clock rollback (R3); retention stays best-effort, never fatal."""
+
+    def test_just_written_survives_clock_rollback(self, tmp_path, monkeypatch):
+        import os
+        from datetime import datetime, timedelta
+        from flashgate import records as rec
+        monkeypatch.setattr(rec, "MAX_RECORDS", 3)
+        # three records whose mtimes are ONE HOUR IN THE FUTURE
+        for i in range(3):
+            j = rec.VerifyJournal(["build"], mode="swd", probe_names=None)
+            j.check("build", "passed")
+            p = rec.write_record(j.to_record(_board_stub(), 0, "succeeded", "x"),
+                                 tmp_path, fingerprint=f"{i:064d}")
+            future = datetime.now() + timedelta(hours=1)
+            os.utime(p, (future.timestamp(), future.timestamp()))
+        # a fresh write under the rolled-back clock must survive its own prune
+        j = rec.VerifyJournal(["build"], mode="swd", probe_names=None)
+        j.check("build", "passed")
+        fresh = rec.write_record(j.to_record(_board_stub(), 7, "failed", "x"),
+                                 tmp_path, fingerprint="ff" * 32)
+        assert fresh.exists(), "the just-written record must never be pruned"
+        # (latest_record sorts by mtime, so the future-stamped files win —
+        # correct behavior under clock skew; the invariant is survival)
+        import json as _json
+        assert _json.loads(fresh.read_text(encoding="utf-8"))["record_id"] == fresh.stem