feat(vision): rehearse a closed loop from a recording

[gbradham]

Stacked on #138 (retarget to main once that lands — it carries the plugin-registry test fixes this branch needs).

Camera → Live behavior → Rehearse from video… plays a recording through the live path instead of the camera. The classifier runs, the nodes fire, and the hardware is driven for real, on footage where you already know what the animal did.

⚠️ The stimulator actually fires. That is the point — a rehearsal that faked the output would not tell you the hardware works. Don't rehearse with an animal connected.

It needed almost nothing new downstream

_handle_frame_input is a single funnel every frame already passes through:

camera loop ─┐
             ├→ _frame_received → _handle_frame_input ─┬→ behavior worker → bus → nodes → hardware
video pump  ─┘                                          └→ CV worker → tracking + overlay

So a pump emitting _frame_received with the camera's (frame, timestamp) shape — same wall-clock time.time() — gets the entire live path unchanged. It emits that signal rather than calling _on_frame, deliberately skipping its _preview_active guard: a rehearsal must not require an open camera, since most machines running one have none.

Frames are never skipped

compute_features computes velocity and acceleration over unit frame spacing. A dropped frame doubles the apparent displacement across the gap and inflates exactly the kinematics the behavior model keys on — a pump that skipped to keep up would produce confident, wrong behavior.

So it reports its worst lag instead, which is the number worth reading: a run that ends a second behind will miss stimulus timing on a live animal by the same margin.

Both speeds classify identically

Same reason — unit frame spacing means playback rate cannot change what the model sees. They answer different questions:

Mode	Answers
Real time	Does inference keep up, and what is the latency from behavior onset to stimulus?
As fast as possible	Is any of this wired up? Same answer, sooner.

Offering only the first would make the wiring check needlessly slow; only the second would make the latency question unanswerable.

Tests — 20 new

test_video_pump.py (16) — every frame delivered in order; no frame skipped even when the consumer is slow; lag reported rather than caught up by skipping; no lag reported when unpaced; wall-clock timestamps matching the camera; real-time pacing actually taking the clip's length; unpaced being much faster; stop taking effect mid-clip (it drives hardware, so stop must mean stop); unreadable file failing to start; double-start refused; stop-before-start safe; a raising consumer ending the run rather than gapping it; source released.

test_camera_panel_rehearsal.py (4) — a rehearsal frame goes down the camera funnel, not a side channel; the frame is copied (the decoder reuses buffers); it works with no camera open; and a recorded freeze drives a real GATT write end to end, with only pose/behavior inference and bleak faked.

Docs

docs-site/camera-behavior/rehearsal.md — how to run one, how to read the lag number, and an explicit what it does and doesn't prove: it won't validate camera setup or lighting, and inference speed only transfers if the clip was recorded on the same camera at the same settings.

Verification

PYTHONPATH=src QT_QPA_PLATFORM=offscreen pytest tests/ — 3627 passed, 4 skipped, ruff and black clean.