Route every event marker through push_marker() / subscribe_marker()

[pellet]

Summary

Every paradigm currently hand-rolls its own marker handling: an if self.eeg: block
that re-derives the timestamp, branches on self.eeg.backend == "muselsl" to wrap the
marker in a list, and then separately calls send_triggers() for self.devices. The
same boilerplate is copy-pasted across N170, SSVEP, eoec, etc.

This PR routes marker handling through a single push_marker() method on
BaseExperiment, backed by a small subscriber list. One call fans the marker out to the
EEG board, every auxiliary device, and any optional observers under one shared
timestamp.

Net paradigm change (N170 shown):

# before — duplicated in every paradigm
if self.eeg:
    timestamp = time()
    if self.eeg.backend == "muselsl":
        marker = [self.markernames[label]]
    else:
        marker = self.markernames[label]
    self.eeg.push_sample(marker=marker, timestamp=timestamp)
if self.devices:
    self.send_triggers(self.markernames[label])

# after
self.push_marker(self.markernames[label], idx)

Motivation

1. DRY — the muselsl → wrap-in-list branch lived in every paradigm. It now lives in
   exactly one place (EEG._muse_push_sample), where the pylsl-outlet requirement
   actually belongs. Paradigm code drops to a single line.
2. Correct cross-stream timing — previously the EEG push and send_triggers() each
   minted their own time() (and send_triggers minted a fresh one per device inside
   its loop), so a single stimulus onset was stamped with several slightly different
   times across streams. push_marker() computes the timestamp once and shares it with
   every sink — important for ERP epoching and multi-device alignment.
3. Extensibility — optional observers (photodiode, flip-time telemetry, eyetracker)
   can subscribe to marker onsets without editing any paradigm.

API

push_marker(marker, trial_idx=None) -> float
    # Fans the marker out to every subscriber under one shared timestamp; returns that timestamp
    # so the caller can record the same onset in its own bookkeeping.

subscribe_marker(callback, raise_on_error=True)
    # callback is any callable(marker, timestamp, trial_idx).
    # raise_on_error=True  (default) — essential recorders; an exception aborts the run.
    # raise_on_error=False           — optional telemetry; exceptions are logged, not raised.

Two built-in essential subscribers are registered in __init__: _write_marker_to_eeg
(the board) and _write_marker_to_devices (aux devices). Paradigms can add their own — e.g. eoec
subscribes its LSL Markers outlet and, when present, the serial trigger box.

Failure handling for optional subscribers is spam- and latency-safe: a broken subscriber's
traceback is logged once, subsequent failures are counted (a dict increment, no
formatting/IO on the presentation thread), and a per-subscriber total is reported at the
end of run().

Preserved contract (no change for device authors)

• self.devices and its default are unchanged.
• The device protocol is unchanged: subscribers still call
  dev.push_sample(marker=..., timestamp=...). Existing device objects work as-is.

Behavior changes to be aware of (review these)

1. send_triggers() is removed. Its behavior is folded into the _write_marker_to_devices
   subscriber. In-repo callers (N170, SSVEP, eoec, p300) are updated. If external/downstream code calls
   send_triggers(), that's a breaking change — happy to keep a thin back-compat shim
   (send_triggers = lambda self, m: self.push_marker(m)) if preferred.
2. Timestamps are now identical across streams where they previously differed by
   µs–ms. This is the intended fix, but it does change recorded marker timestamps.
3. Two paradigms are not migrated here — auditory_oddball and pattern_reversal_vep
   still call eeg.push_sample() directly. Converting them is a mechanical follow-up.

SSVEP timing note

SSVEP now pushes the marker on the first flip of the flicker loop (guarded by a
marker_pushed flag) so the recorded onset is the true stimulus onset rather than one
frame early.

Tests

• tests/test_push_marker.py — display-free unit coverage that runs headless in CI (no
  window): shared-timestamp fan-out, optional-subscriber isolation (both directions),
  log-once-per-subscriber anti-spam, and the muse scalar→[marker] wrap/back-compat.