fix(monitoring): correct cron operational signals

tests/monitoring/test_cron_health_export.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from datetime import datetime, timedelta, timezone
 
+import pytest
+
 
 def _metric(snapshot, name):
     return next(metric for metric in snapshot.metrics if metric.name == name)
@@ -106,11 +108,52 @@ def test_execution_projection_omits_duration_and_delivery_when_not_known():
     ).to_dict()
 
     assert event["status"] == "claimed"
-    assert event["source"] == "unknown"
+    assert event["source"] == "external"
     assert event["duration_ms"] is None
     assert event["delivery_outcome"] is None
 
 
+def test_external_provider_source_is_normalized_to_external():
+    from agent.monitoring.cron_health import project_execution_event
+
+    event = project_execution_event(
+        {"job_id": "private", "source": "Chronos", "status": "claimed"}
+    )
+
+    assert event.source == "external"
+
+
+@pytest.mark.parametrize("message", ["oauth refresh failed", "tokenizer crashed", "HTTP 4015"])
+def test_error_classification_avoids_auth_substring_false_positives(message):
+    from agent.monitoring.cron_health import classify_cron_error
+
+    assert classify_cron_error(message) == "unknown"
+
+
+@pytest.mark.parametrize(
+    "message",
+    ["authentication failed", "not authorized", "access token expired", "HTTP 401"],
+)
+def test_error_classification_recognizes_auth_terms_and_status_tokens(message):
+    from agent.monitoring.cron_health import classify_cron_error
+
+    assert classify_cron_error(message) == "auth_failed"
+
+
+def test_cron_snapshot_exports_catch_up_occurrence_counter(monkeypatch):
+    from agent.monitoring import cron_health
+
+    monkeypatch.setattr(cron_health, "get_ticker_heartbeat_age", lambda: None)
+    monkeypatch.setattr(cron_health, "get_ticker_success_age", lambda: None)
+    monkeypatch.setattr(cron_health, "get_running_job_ids", lambda: frozenset())
+    monkeypatch.setattr(cron_health, "load_jobs", lambda: [])
+    monkeypatch.setattr(cron_health, "get_catch_up_occurrence_count", lambda: 3)
+
+    snapshot = cron_health.build_cron_health_snapshot()
+
+    assert _metric(snapshot, "hermes.cron.scheduler.catch_up_occurrences").value == 3
+
+
 def test_terminal_execution_emission_flushes_and_failures_are_fail_open(monkeypatch):
     from agent.monitoring import cron_health, emitter
 
@@ -151,3 +194,14 @@ def test_gateway_export_includes_cron_metrics_and_only_accepted_event_planes(mon
     assert gateway_health_export._gateway_health_event({"event": "cron_execution"}) is True
     assert gateway_health_export._gateway_health_event({"event": "gateway_health"}) is True
     assert gateway_health_export._gateway_health_event({"event": "run"}) is False
+
+
+def test_monitoring_docs_distinguish_relay_health_scope_and_terminal_flush():
+    from pathlib import Path
+
+    text = Path("docs/observability/monitoring.md").read_text(encoding="utf-8")
+
+    assert "Hermes Agent-owned Relay transport health" in text
+    assert "authoritative shared connector/platform state" in text
+    assert "up to one second" in text
+    assert "terminal" in text