# Phase 3: Heartbeat Telemetry Overhaul - Context

**Gathered:** 2026-03-21
**Status:** Ready for planning

<domain>
## Phase Boundary

Enhance heartbeat telemetry to continuously validate the fixes from Phases 1 and 2. Unified per-symbol Stathera checks (no intra-day vs midnight-boundary split), yesterday completion status via crossover trade ID, junction telemetry after sidecar restarts, and LOUD alerts on any new Stathera gap in today's bars.

</domain>

<decisions>
## Implementation Decisions

### Infrastructure Phase

All implementation choices are at Claude's discretion — monitoring/telemetry phase.

Key constraints:

- Heartbeat runs every 5 min via systemd timer on bigblack
- Existing modular structure: `scripts/heartbeat/checks/stathera.py`, `formatter.py`, `telegram.py`
- TELEM-01: Unify `stathera_gaps` and `stathera_overlaps` into a single per-symbol check — remove `adjacent_day_gaps` classification
- TELEM-02: Query yesterday's orphan bar and compare with midnight crossover trade ID (reuse `_get_midnight_crossover_tid` concept from Phase 2)
- TELEM-03: Read junction telemetry from sidecar logs or state — committed_floors, REST/WS trade IDs, forming bar state
- TELEM-04: Separate "today's gaps" check with LOUD Telegram alert (persistent, not ephemeral) including exact (symbol, threshold, tid_delta, trade ID range)

</decisions>

<code_context>

## Existing Code Insights

### Reusable Assets

- `scripts/heartbeat/checks/stathera.py` — existing Stathera gap/overlap checks with `lagInFrame()` queries
- `scripts/heartbeat/checks/sidecar.py` — existing sidecar health check
- `scripts/heartbeat/formatter.py` — message formatting with healthy/unhealthy sections
- `scripts/heartbeat/telegram.py` — LOUD (persistent) and ephemeral message sending
- `python/opendeviationbar/sidecar.py` — `_get_midnight_crossover_tid()` from Phase 2

### Established Patterns

- `results["check_name"] = True/False` for health checks
- `results["check_detail"] = str(value)` for telemetry data
- LOUD alerts: persistent Telegram messages, never auto-deleted
- Ephemeral: auto-deleted after 15 min

### Integration Points

- `scripts/heartbeat/checks/stathera.py` — modify existing checks (TELEM-01, TELEM-04)
- New check module for yesterday completion (TELEM-02)
- New check module or enhancement for junction telemetry (TELEM-03)
- `scripts/heartbeat/formatter.py` — add new sections to heartbeat message

</code_context>

<specifics>
## Specific Ideas

No specific requirements — infrastructure phase.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>
