feat(events): add runBackgroundMonitoring driver with correct exit-log ordering

[HanSur94]

Summary

Adds libs/EventDetection/runBackgroundMonitoring.m — a thin, console-only driver that runs a LiveEventPipeline for a bounded duration with periodic heartbeats, then stops it and logs the final status — with the exit-log ordering bug fixed.

⚠️ Context: the target file did not exist in the repo

The task described a cosmetic logging bug in libs/EventDetection/runBackgroundMonitoring.m (exit line printing status=running before the onCleanup-registered safeStop_ runs). An exhaustive search found that this file — and its test tests/test_run_background_monitoring.m — exist nowhere: not on this branch, not in git log --all, and not on any of the repo's ~100 remote branch tips. The quoted symbols (safeStop_ with the isvalid/Octave guard, the [BG] runBackgroundMonitoring exit log, "Phase 1039") are also absent.

The most likely explanation is that the file was created but never committed in an earlier ephemeral session (the "Phase 1039 live demo"), so it was lost when the container was re-cloned. Per the author's direction, it is reconstructed here against the real LiveEventPipeline API with the fix already applied, rather than editing lines that don't exist.

The fix

The exit line reports the true post-stop status:

• The pipeline is stopped via safeStop_() before the exit fprintf, so a normal run logs status=stopped instead of the stale status=running that a stop-deferred-to-onCleanup ordering printed.
• safeStop_() is idempotent (guards on Status=='running'), so the trailing onCleanup safety net — which also covers Ctrl-C and unexpected errors — never double-stops, and a faulted run keeps its error status in the log.
• safeStop_() guards isvalid() behind exist('isvalid','builtin') and wraps its body in try/catch, keeping it Octave-portable.

The three heartbeat-loop exit paths each stop the pipeline once and log the correct final status:

Path	Mechanism	Logged status
Normal (duration elapsed)	explicit safeStop_ → running→stopped	stopped
Error (Status=='error')	loop breaks; safeStop_ is a no-op (preserves error)	error
Ctrl-C / exception	try/catch (exceptions) + onCleanup net (Ctrl-C)	post-stop status, then re-raised

Tests

tests/test_run_background_monitoring.m (flat function-based):

• E1–E3 error-ID validation (invalidPipeline / invalidDuration / invalidHeartbeat) — run on Octave and MATLAB (validation precedes any timer start).
• L1 normal exit returns 'stopped', asserts the logged exit status matches the post-return status, and checks no timer leaks.
• L2 error exit returns 'error' and logs status=error, asserting safeStop_ does not force-stop a faulted pipeline (StopCount==0).

L1/L2 are timer-driven and MATLAB-only (Octave-skipped); they use the new tests/MockBgPipeline.m double for the fault path.

Verification

• ✅ mh_style, mh_lint, mh_metric --ci all clean on the three new files (MISS_HIT's parser also confirms valid MATLAB syntax).
• ✅ No name collisions; new files only (no existing files modified), so backward-compatible.
• ⚠️ The timer-driven L1/L2 sub-tests were not executed — this cloud sandbox has no MATLAB or Octave runtime. Please run test_run_background_monitoring() on a MATLAB session to exercise L1/L2 (E1–E3 also run under Octave).

Note for reviewers

By design (per the task's chosen Status=='running' guard), the error path preserves error in the log and does not call pipeline.stop(), so a real faulted LiveEventPipeline's timer object is left for the caller to clean up (the caller receives 'error' as the return value). If guaranteed timer-object cleanup on the error path is preferred over surfacing error in the exit line, widen the safeStop_ guard to ~strcmp(Status,'stopped') — at the cost of the error path logging stopped.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PFPxzvTUQfaTNCQrRUPrDK

---

Generated by Claude Code