feat(vision): closed-loop behavior triggering — freeze fires the Maimu

[gbradham]

Closes the loop: the animal freezes, the Maimu stimulates.

Important

Provenance. The first commit is work that was sitting uncommitted in the .claude/worktrees/behavior-trigger-node worktree — another agent session, same author. It is rebased onto current main here, unchanged apart from one conflict resolution. If that session is still live, it should stop and reset rather than continue on a stale base. The second commit is new.

What this enables

Behavior Input (freezing) ──On Enter──▶ Maimu (Pulse 500 ms / 10 s)

A stimulus delivered because of what the animal is doing, not because a timer expired.

Commit 1 — feat(vision): the missing hop

Vision produced a result per frame on a worker thread; nodes that react to it live on the asyncio loop. Nothing connected the two. ZoneInputNode carried an update method that nothing in the codebase ever called, so zone exec outputs could never fire either — this fixes that class of gap, not just the behavior case.

• LiveSignalBus (core/live_signals.py) — nodes subscribe on start and unsubscribe on stop; whoever runs inference publishes without knowing what listens. A subscriber that raises is logged and skipped, because the publisher is a vision thread whose job is not to care about the flow graph.
• BehaviorInputNode (nodes/vision/behavior_nodes.py) — Active / Behavior data outputs plus On Enter / On Exit exec outputs.

Two properties of the live signal shape the node, and both are worth reading before tuning it:

• The per-frame label is noisy: raw frame-wise macro F1 is 0.777 against 0.811 for the same frames under a 25-frame centred vote. Wiring a raw label straight to hardware means one misclassified frame fires a stimulus. Entering requires min_frames consecutive matching frames; leaving requires the same number without.
• The centred vote cannot be used here — it reads frames that have not happened yet. Legitimate offline, impossible live. Consecutive-frame confirmation is the causal equivalent, and its cost is explicit: at 30 fps a min_frames of 5 delays the trigger by ~167 ms on top of inference.

No confidence output, deliberately: the live path's LiveResult carries a label and keypoints only, so a confidence port would read zero every frame and invite gating on a number that was never measured.

Commit 2 — test(integration): proof, on the bytes

tests/integration/test_freeze_triggers_maimu.py drives all four hops at once and asserts on the GATT payload (b"500,10") reaching the peripheral, not on an intermediate signal. Only the two genuinely external ends are stubbed — the classifier (a label per frame, exactly what classify_frame yields) and bleak.

Covered	Why it matters
Confirmed freeze pulses	The headline
One stray frame does not	The failure mode min_frames exists to prevent
Sustained freeze pulses once per bout	On Enter is an edge, not a level
Leave and re-enter pulses twice	Bout detection actually resets
A stopped flow drives nothing	Stopping an experiment must stop the loop, not just the display
Empty warm-up label is a miss	The classifier emits "" until its feature buffer fills

An ordering property found while writing it

All three positive tests failed on the first run. Probing each hop rather than guessing: FlowEngine.start() schedules each continuous node's start() as a task and returns before it has run, so a node is not on the bus yet when start() returns, and frames published in that window are dropped silently.

Harmless in production — at 30 fps the next frame is 33 ms away and the start task runs on the next loop iteration — but it is undocumented and will silently break anything that publishes immediately. Documented in the test rather than papered over. Worth deciding separately whether start() should await node startup.

Verification

PYTHONPATH=src QT_QPA_PLATFORM=offscreen pytest tests/ — 3621 passed, 3 skipped, ruff and black clean. The 34 tests from commit 1 pass unchanged on top of the merged Maimu work.

Outside the code

For a real closed-loop run: the trained model needs freezing in its classes_, and live inference must be running in the camera panel. The bus only carries what the classifier actually emits.