feat(bpod): serial-safe live-command injection into a running trial

[larsrollik]

Adds a serial-safe way to issue a live command (an extra reward / valve pulse) into a running Bpod trial, without corrupting the serial stream.

Why

The Bpod serial connection is owned by the task thread inside pybpodapi's run_state_machine poll loop. Issuing a manual_override from any other thread races that loop's own I/O and wedges the connection. The only serial-safe injection point is inside the loop, on the same thread — which is exactly what MATLAB does (single-threaded cooperative injection).

What

• BpodFactory.add_loop_handler(fn) — register callbacks that run once per iteration of the run loop, routed through a dispatch registry that isolates handler errors so one bad handler can't break the loop. This is the serial-safe seam.
• LiveInjector + CommandPolicy (hardware/bpod/injection.py):
  • submit(cmd) — callable from any thread. Validates the command against a rig-local safety envelope (CommandPolicy: action + valve allowlist, max reward duration, rate limit) and enqueues it. Never touches hardware.
  • drain() — registered as a loop handler, runs on the task thread. Applies commands non-blocking: open the valve now, close it on a later iteration when the pulse has elapsed, so the poll loop never stalls for a pulse.
  • flush_pending() — force-closes any still-open timed valve (between trials / on teardown).
  • Applied overrides are emitted to an audit callback: an override does not appear in the trial's Events/States, so recording it is a data-completeness requirement (reward accounting), not only security.
• The rate-limit check-and-set is lock-guarded so the envelope still holds when submit() is called concurrently from multiple threads.

Safety envelope

CommandPolicy is enforced locally by the rig — a compromised or buggy caller cannot deliver an unbounded reward or drive an unlisted valve. Defaults deny everything except an explicitly allowlisted reward valve within a bounded duration and rate.

Tests

tests/test_bpod_injection.py (SimBpod, no hardware) covers the policy envelope, the submit/drain split (nothing applied until drain runs on the task thread), the non-blocking timed valve action, concurrent-submitter rate-limit safety, audit emit, and the loop-handler registry. tests/test_bpod_override.py covers the underlying override API + action driver.

The mechanism has also been exercised end-to-end on real hardware (Bpod fw22) during a live sequence session: extra rewards submitted from an external thread were applied mid-trial by the run loop with no serial corruption, and out-of-envelope commands were rejected.