Telegram alerting (notifications-only): node/worker down + recovered (#121)

[VijitSingh97]

Closes #121.

Ships a notifications-only Telegram alerter for v1.0 — a thin notifier that pushes a small, high-value set of operational alerts to one chat. The interactive bot / command interface stays in #45.

What you get (all debounced — one message per real transition)

Alert	Source signal
🔴/🟢 Node down / recovered	NodeHealthMonitor's debounced down edge per node (#31) — consumed, not re-collected
🔴/🟢 Worker offline / back online	new flap-protected per-worker presence tracker
✅ Sync finished	the sync-gate miner_released latch flipping open (#35)

Off by default: with no telegram config nothing sends and nothing errors.

Design

Three small single-responsibility modules under build/dashboard/mining_dashboard/service/:

• telegram_notifier.py — thin sendMessage transport. Enabled only when switched on and both bot_token + chat_id are present; fails silently on offline / Tor-only hosts; never logs the bot token (not even inside an exception message, which would otherwise embed the URL).
• worker_presence.py — WorkerPresenceMonitor, the one genuinely new building block: the per-worker analogue of NodeHealthMonitor (debounce + recovery hysteresis + silent first-sight baseline).
• alert_service.py — folds the loop's existing signals into debounced alerts. evaluate() is pure (fully unit-tested); process() dispatches off-thread so a slow Telegram call can't stall the data loop. Wired into data_service.run().

Robustness: edge baselines seed silently so a dashboard restart never replays a stale alert; worker tracking resets when the proxy is intentionally stopped (sync hold / node-down failover) so expected rig absence doesn't spam "offline"; Tari node alerts fire only when Tari is required; messages are hostname-prefixed so multiple stacks can share one chat.

Plumbing

config.json telegram.* → pithead render_env → per-event env vars → config.py. The bot_token is rendered to the owner-only .env and masked in the apply preview. Injected into the dashboard container in docker-compose.yml; added to config.advanced.example.json.

Documentation

New docs/telegram.md: a first-time-user walkthrough — create a bot via BotFather, find your chat id (with a manual fallback), per-event toggles, the "one chat, two bots" pattern for sharing a chat with the Healthchecks.io monitor (#79), a Tor-only caveat, and a troubleshooting table. Cross-referenced from the docs index, the configuration reference, and the CHANGELOG.

Acceptance criteria

• telegram.enabled=false by default; when off, nothing sends and no errors
• Each enabled event fires once per transition (debounced — no flapping spam)
• Node down/recovered consume NodeHealthMonitor edges (no re-collection)
• Worker offline/back-online via a debounced per-worker tracker
• Sync-finished fires once when the sync gate opens
• bot_token never logged; lives in .env, owner-only
• Fails silently / no noise when offline or Tor-only (Dashboard: new-version warning + one-click upgrade button #59 discipline)
• Documented setup (docs/telegram.md)

Testing

• 439 pytest pass (49 new across 3 files), coverage 93.19% (gate 80%; new modules 100% / 100% / 94%)
• 103 stack tests pass — new cases for env propagation + bot-token secrecy (not leaked in .env preview)
• 27/27 frontend, shellcheck clean, docker compose config valid + hardening directives intact

Note for reviewers

known_workers / last_seen / update_known_workers in storage_service.py turned out to be dead code — table + migration + getters/setters exist but nothing in the loop populates it. The issue suggested basing worker-offline detection on last_seen; since that field is never written, the monitor is driven off the live worker list instead. Left the dead code in place (may be intended for a future feature) — flagged here as a possible follow-up cleanup.

🤖 Generated with Claude Code