flashgate 0.7.0__tar.gz → 0.7.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashgate
-Version: 0.7.0
+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
@@ -164,6 +173,29 @@ and per-check verdicts equal; `artifact_sha256` differs by design — it
 identifies the BUILD, which embeds its timestamp, while the tree
 fingerprint identifies the SOURCE).
 
+**Deployment notes** (from the first real cross-host test, wired host
++ Wi-Fi laptop, 2026-09-15):
+
+- Multicast discovery does not cross all wired↔wireless routers. If
+  discovery finds nothing across machines but `ping` works, switch to
+  unicast: on the bench host set `ZENOH_LISTEN=tcp/0.0.0.0:7447` before
+  `bench-serve`; on the client set `MESSAGING_URLS=tcp/<host-ip>:7447`.
+- Open UDP 7446 (multicast scouting) or TCP 7447 (unicast) inbound on
+  the host's firewall; a Wi-Fi client set to "Public network" blocks the
+  announcements it needs to receive.
+- **One bench-serve per bench**: a second instance for the same
+  firmware dir is refused at startup (a loopback lock socket, released
+  automatically when the process dies). Before the lock existed, two
+  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.
@@ -225,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
 
@@ -251,6 +285,10 @@ flashgate 回答一个很具体的问题：刚编译出来的固件，烧到板
 - 版本身份带 `-dirty` 语义，验证通过意味着板上跑的就是当前工作区
 - 探针下真命令、断言硬件寄存器读回值；响应报的是实际状态不是回声，
   静默失效的设置第一步就会露馅
+- 每次验证（无论成败）都留一份证据记录：逐项检查结论、板子的原话、
+  产物哈希——事后可审计"当时验证的是什么、板子说了什么"
+- `bench-serve` 可以把整个台架挂上局域网：远程 agent 用 device-connect
+  协议发现它、请求真机验证、拿回带证据的结论（跨机实测通过）
 - Stop hook 挂进 Claude Code：agent 改了固件没过真机验证就说"完成"，
   会被拦下并收到板子的失败证词；同一棵坏树最多拦两次，之后放行但
   打警告，会话不会被卡死

{flashgate-0.7.0 → 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
@@ -143,6 +152,29 @@ and per-check verdicts equal; `artifact_sha256` differs by design — it
 identifies the BUILD, which embeds its timestamp, while the tree
 fingerprint identifies the SOURCE).
 
+**Deployment notes** (from the first real cross-host test, wired host
++ Wi-Fi laptop, 2026-09-15):
+
+- Multicast discovery does not cross all wired↔wireless routers. If
+  discovery finds nothing across machines but `ping` works, switch to
+  unicast: on the bench host set `ZENOH_LISTEN=tcp/0.0.0.0:7447` before
+  `bench-serve`; on the client set `MESSAGING_URLS=tcp/<host-ip>:7447`.
+- Open UDP 7446 (multicast scouting) or TCP 7447 (unicast) inbound on
+  the host's firewall; a Wi-Fi client set to "Public network" blocks the
+  announcements it needs to receive.
+- **One bench-serve per bench**: a second instance for the same
+  firmware dir is refused at startup (a loopback lock socket, released
+  automatically when the process dies). Before the lock existed, two
+  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.
@@ -204,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
 
@@ -230,6 +264,10 @@ flashgate 回答一个很具体的问题：刚编译出来的固件，烧到板
 - 版本身份带 `-dirty` 语义，验证通过意味着板上跑的就是当前工作区
 - 探针下真命令、断言硬件寄存器读回值；响应报的是实际状态不是回声，
   静默失效的设置第一步就会露馅
+- 每次验证（无论成败）都留一份证据记录：逐项检查结论、板子的原话、
+  产物哈希——事后可审计"当时验证的是什么、板子说了什么"
+- `bench-serve` 可以把整个台架挂上局域网：远程 agent 用 device-connect
+  协议发现它、请求真机验证、拿回带证据的结论（跨机实测通过）
 - Stop hook 挂进 Claude Code：agent 改了固件没过真机验证就说"完成"，
   会被拦下并收到板子的失败证词；同一棵坏树最多拦两次，之后放行但
   打警告，会话不会被卡死

{flashgate-0.7.0 → 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.2/flashgate/bench_serve.py

@@ -0,0 +1,268 @@
+"""flashgate bench-serve: expose the local bench over device-connect (L1).
+
+A thin shell over BenchDriver (L0) — exactly four named RPCs, nothing
+else: no arbitrary shell, no path arguments, no console passthrough.
+Which board a bench serves is fixed by the --board profile the server
+was started with; remote callers cannot choose it.
+
+Requires the optional extra:
+
+    pip install "flashgate[bench]"        # -> device-connect-edge
+
+D2D mode (no broker, Zenoh multicast scouting) is the default shape for
+a bench: set DEVICE_CONNECT_ALLOW_INSECURE=true for local development
+and force DEVICE_CONNECT_DISCOVERY_MODE=d2d when no broker URLs exist.
+
+THE RED LINE for every consumer (GPT6 report §4.2): the mesh wraps a
+normally-delivered reply as success:true regardless of what the bench
+verified. Judge verification ONLY by the operation payload —
+state / exit_code / status and the embedded record's checks — never by
+transport success alone.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+import threading
+import _thread
+import zlib
+from pathlib import Path
+from typing import Optional
+
+from .bench import BenchBusyError, BenchDriver
+from .board import Board
+
+
+def _lock_port(fw_dir: Path) -> int:
+    return 17500 + (zlib.crc32(
+        str(fw_dir.resolve()).lower().encode("utf-8")) % 1000)
+
+
+def acquire_bench_lock(fw_dir: Path) -> socket.socket:
+    """OS-level single-instance lock per bench, auto-released when the
+    process dies (a bound socket cannot outlive its process).
+
+    Why: two bench-serves for the SAME firmware dir register the same
+    device_id on the mesh and split-brain every RPC — the losing process
+    races the winner for the board's serial port and surfaces as
+    access-denied (seen live in the first cross-host test, 2026-09-15).
+    Different boards (different fw dirs) lock different ports and may
+    share a host."""
+    s = socket.socket()
+    try:
+        s.bind(("127.0.0.1", _lock_port(fw_dir)))
+        s.listen(1)
+        return s
+    except OSError:
+        s.close()
+        raise RuntimeError(
+            f"another bench-serve for {fw_dir} appears to be running on "
+            f"this machine — one bench-serve per bench (the running one "
+            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, emit, rpc
+
+    class FlashGateBenchDriver(DeviceDriver):
+        device_type = "flashgate-bench"
+
+        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()
+        async def start_verify(self, probes: Optional[list] = None) -> dict:
+            """Start one hardware verify; returns the operation snapshot
+            (state=running, op_id). Single-flight: a busy bench answers
+            {"error": "busy", ...} — a transport success that must NOT be
+            read as a verification pass.
+
+            Note: Optional[list] (typing.Union), NOT `list | None` — the
+            SDK's schema converter misses PEP 604 unions and would
+            advertise probes as a STRING, steering well-behaved callers
+            into flashing the board only to die on "unknown probe 'a'"
+            (adversarial review F1)."""
+            if probes is not None and (
+                    not isinstance(probes, list)
+                    or not all(isinstance(x, str) for x in probes)):
+                # reject BEFORE any hardware is touched (F2): a malformed
+                # 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:
+                return {"error": "busy", "detail": str(exc)}
+
+        @rpc()
+        async def get_operation(self, op_id: str) -> dict:
+            """Poll an operation until state is succeeded|failed|cancelled;
+            the terminal snapshot carries exit_code/status and the run's
+            evidence record (checks + what the board actually said)."""
+            op = bench.get_operation(op_id)
+            if op is None:
+                return {"error": "unknown_operation", "op_id": op_id}
+            return op
+
+        @rpc()
+        async def cancel_operation(self, op_id: str) -> dict:
+            """True = cancelled (only before execution starts). Executing
+            operations are never torn down mid-run — the request is
+            recorded and the run completes with its REAL verdict."""
+            return {"op_id": op_id, "cancelled": bench.cancel_operation(op_id)}
+
+    return FlashGateBenchDriver
+
+
+def serve(board: Board, device_id: str | None = None) -> int:
+    """Run the bench server until Ctrl+C. Blocks forever."""
+    try:
+        from device_connect_edge import DeviceRuntime
+    except ImportError:
+        print("bench-serve needs the optional dependency: "
+              'pip install "flashgate[bench]" (device-connect-edge)')
+        return 2
+
+    try:
+        lock = acquire_bench_lock(board.firmware_dir)   # held for life
+    except RuntimeError as exc:
+        print(f"[bench-serve] {exc}")
+        return 2
+
+    _start_lock_listener(lock)
+    bench = BenchDriver(board)
+    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 or `bench-serve --stop` "
+          f"to stop")
+    try:
+        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. 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...")
+            done = bench.wait(current, timeout_s=120)
+            print(f"[bench-serve] drained: {done['state']} "
+                  f"exit={done.get('exit_code')}")
+        print("[bench-serve] stopped")
+    except Exception as exc:              # e.g. invalid device_id (F5)
+        print(f"[bench-serve] failed: {type(exc).__name__}: {exc}")
+        return 2
+    return 0

{flashgate-0.7.0 → 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.0 → 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)