fix(mcp): correct monitor forecast pagination, coupling parity, and notes (TG-1092)

Addresses review findings on the forecast work:

- Render the forecast only on the first page — it is forward-looking and
  page-independent, but its anchor (the latest event) was read from the current
  page, producing a stale forecast on page >= 2.
- Match the dashboard's coupled-forecast precondition: a freshness-coupled
  Volume/Metric monitor with no configured tolerance has no band on either
  surface (it was entering the coupled path on the coupling flag alone).
- Resolve schedule holidays only after the next-update-window guards pass,
  restoring the dashboard's short-circuit (no calendar work for non-Prediction
  monitors); next_update_window now takes the test suite.
- Exclude Error-status freshness events from the next-update anchor, matching
  the dashboard.
- Use an accurate note when a forecast is absent for a non-training reason
  (elapsed window / no baseline) instead of telling a trained monitor to keep
  training.
- Fix the dashboard unit test that imported the relocated forecast helper
  (this broke the Python Tests CI job), and add coverage for the
  coupled-without-tolerance case.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aarthy-dk

testgen/common/monitor_forecast.py

@@ -41,8 +41,7 @@ def next_update_window(
     freshness_definition: MonitorDefinition | None,
     last_detection_time: datetime | None,
     *,
-    exclude_weekends: bool,
-    holiday_dates: set[date] | None,
+    test_suite: TestSuite,
     cron_tz: str | None,
 ) -> dict | None:
     """Predicted next-update window as ``{"start", "end"}`` epoch-ms, or ``None``.
@@ -63,6 +62,8 @@ def next_update_window(
         return None
 
     tz = cron_tz or "UTC"
+    exclude_weekends = test_suite.predict_exclude_weekends
+    holiday_dates = resolve_suite_holiday_dates(test_suite)
     sched = get_schedule_params(freshness_definition.prediction)
 
     window_end = add_business_minutes(

testgen/mcp/tools/monitors.py

@@ -31,7 +31,6 @@
     forecast_band_points,
     gated_forecast_prediction,
     next_update_window,
-    resolve_suite_holiday_dates,
 )
 from testgen.common.monitor_service import disable_monitoring, enable_monitoring, update_monitoring
 from testgen.mcp.exceptions import MCPUserError
@@ -61,6 +60,11 @@
     "have trained on enough history._"
 )
 
+# Used where a forecast can be absent for reasons other than training (e.g. the
+# predicted next-update window has already passed, or no baseline is stored), so
+# the message must not claim the model still needs to train.
+_FORECAST_UNAVAILABLE_NOTE = "_No forecast available for this monitor right now._"
+
 _MONITOR_LABEL: dict[MonitorType, str] = {
     MonitorType.FRESHNESS: "Freshness",
     MonitorType.VOLUME: "Volume",
@@ -623,7 +627,7 @@ def list_monitor_events(
         table_name: Table name exactly as stored in TestGen (case-sensitive).
         monitor_type: One of ``freshness`` / ``volume`` / ``schema`` / ``metric``.
         monitor_id: Required for ``monitor_type="metric"``, rejected for other types. Get it from ``list_monitors``.
-        include_predictions: When True, append the monitor's forecast after the historical events, if available.
+        include_predictions: When True, append the monitor's forecast, if available (shown on the first page only).
         limit: Page size (default 20, max 100).
         page: Page number starting at 1 (default 1).
     """
@@ -716,7 +720,7 @@ def list_monitor_events(
             doc.text(f"No events on page {page} (total: {total}).")
         else:
             doc.text("_No monitor events in the active lookback window._")
-        if include_predictions:
+        if include_predictions and page == 1:
             _render_forecast_section(doc, _compute_forecast(suite, table_name, parsed_type, monitor_def, events))
         return doc.render()
 
@@ -827,8 +831,11 @@ def _compute_forecast(
     # A monitor coupled to a Freshness monitor holds at its baseline until the
     # next expected refresh, so its band is the coupled baseline-then-refresh
     # shape keyed off the freshness next-update window — not the raw per-step
-    # prediction series.
+    # prediction series. The tolerance precondition mirrors the dashboard: a
+    # coupled monitor with no configured tolerance has no band on either surface.
     if monitor_def.prediction and monitor_def.prediction.get("freshness_gated"):
+        if monitor_def.lower_tolerance is None and monitor_def.upper_tolerance is None:
+            return _Forecast(note=_FORECAST_UNAVAILABLE_NOTE)
         freshness_def = TestDefinition.get_singleton_monitor(
             suite.id, table_name, MonitorType.FRESHNESS.value
         )
@@ -838,7 +845,7 @@ def _compute_forecast(
         window = _next_update_window_for_table(suite, freshness_def, freshness_events)
         points = forecast_band_points(gated_forecast_prediction(monitor_def, window, last_run_time))
         if not points:
-            return _Forecast(note=_FORECAST_PENDING_NOTE)
+            return _Forecast(note=_FORECAST_UNAVAILABLE_NOTE)
         return _Forecast(points=points)
 
     sensitivity = suite.predict_sensitivity.value if suite.predict_sensitivity is not None else "medium"
@@ -858,7 +865,7 @@ def _next_update_window_for_table(
     last_detection = max(
         (
             e.test_time for e in freshness_events
-            if e.test_time is not None and not e.is_training and not e.is_pending
+            if e.test_time is not None and not e.is_training and not e.is_pending and not e.is_error
             and _parse_freshness_message(e.message)[0] == "Yes"
         ),
         default=None,
@@ -867,8 +874,7 @@ def _next_update_window_for_table(
     return next_update_window(
         freshness_def,
         last_detection,
-        exclude_weekends=suite.predict_exclude_weekends,
-        holiday_dates=resolve_suite_holiday_dates(suite),
+        test_suite=suite,
         cron_tz=schedule.cron_tz if schedule else None,
     )
 

testgen/ui/views/monitors_dashboard.py

@@ -21,7 +21,6 @@
 from testgen.common.monitor_forecast import (
     gated_forecast_prediction,
     next_update_window,
-    resolve_suite_holiday_dates,
 )
 from testgen.common.monitor_service import disable_monitoring, enable_monitoring, update_monitoring
 from testgen.ui.components import widgets as testgen
@@ -530,8 +529,7 @@ def _freshness_next_update_window(
     return next_update_window(
         freshness_definition,
         last_detection_time,
-        exclude_weekends=test_suite.predict_exclude_weekends,
-        holiday_dates=resolve_suite_holiday_dates(test_suite),
+        test_suite=test_suite,
         cron_tz=monitor_schedule.cron_tz if monitor_schedule else None,
     )
 

tests/unit/mcp/test_tools_monitors.py

@@ -1011,13 +1011,12 @@ def test_list_monitor_events_predictions_not_applicable_for_schema(
 
 
 @patch(f"{MODULE}.next_update_window")
-@patch(f"{MODULE}.resolve_suite_holiday_dates")
 @patch(f"{MODULE}.JobSchedule")
 @patch(f"{MODULE}.TestDefinition")
 @patch(f"{MODULE}.TestResult")
 @patch(f"{MODULE}.resolve_monitored_table_group")
 def test_list_monitor_events_freshness_prediction_shows_window(
-    mock_resolve, mock_tr_cls, mock_td_cls, mock_sched, mock_holidays, mock_window, db_session_mock,
+    mock_resolve, mock_tr_cls, mock_td_cls, mock_sched, mock_window, db_session_mock,
 ):
     """A Freshness monitor in Prediction Model mode forecasts a next-update time
     window (the same one the dashboard computes), not a value band — so the
@@ -1031,7 +1030,6 @@ def test_list_monitor_events_freshness_prediction_shows_window(
     monitor_def = MagicMock()
     monitor_def.history_calculation = "PREDICT"
     mock_td_cls.get_singleton_monitor.return_value = monitor_def
-    mock_holidays.return_value = None
     mock_sched.get_for_monitor_suite.return_value = SimpleNamespace(cron_tz="UTC")
     start_ms = int(datetime(2026, 7, 1, 9, 0, tzinfo=UTC).timestamp() * 1000)
     end_ms = int(datetime(2026, 7, 1, 17, 0, tzinfo=UTC).timestamp() * 1000)
@@ -1050,13 +1048,12 @@ def test_list_monitor_events_freshness_prediction_shows_window(
 
 
 @patch(f"{MODULE}.next_update_window")
-@patch(f"{MODULE}.resolve_suite_holiday_dates")
 @patch(f"{MODULE}.JobSchedule")
 @patch(f"{MODULE}.TestDefinition")
 @patch(f"{MODULE}.TestResult")
 @patch(f"{MODULE}.resolve_monitored_table_group")
 def test_list_monitor_events_freshness_coupled_volume_shows_gated_band(
-    mock_resolve, mock_tr_cls, mock_td_cls, mock_sched, mock_holidays, mock_window, db_session_mock,
+    mock_resolve, mock_tr_cls, mock_td_cls, mock_sched, mock_window, db_session_mock,
 ):
     """A Volume/Metric monitor coupled to a Freshness monitor holds at its
     baseline until the next expected refresh — the forecast renders that coupled
@@ -1079,7 +1076,6 @@ def test_list_monitor_events_freshness_coupled_volume_shows_gated_band(
     # list_monitor_events looks up the volume singleton; _compute_forecast then
     # looks up the table's freshness definition for the window.
     mock_td_cls.get_singleton_monitor.side_effect = [volume_def, freshness_def]
-    mock_holidays.return_value = None
     mock_sched.get_for_monitor_suite.return_value = SimpleNamespace(cron_tz="UTC")
     start_ms = int(datetime(2026, 6, 1, 18, 0, tzinfo=UTC).timestamp() * 1000)
     mock_window.return_value = {"start": start_ms, "end": end_ms}
@@ -1097,6 +1093,39 @@ def test_list_monitor_events_freshness_coupled_volume_shows_gated_band(
     assert "gated" not in out.lower()
 
 
+@patch(f"{MODULE}.TestDefinition")
+@patch(f"{MODULE}.TestResult")
+@patch(f"{MODULE}.resolve_monitored_table_group")
+def test_list_monitor_events_freshness_coupled_volume_without_tolerances_shows_note(
+    mock_resolve, mock_tr_cls, mock_td_cls, db_session_mock,
+):
+    """A coupled Volume/Metric monitor with no configured tolerance has no band on
+    the dashboard either, so the MCP shows a note (and skips the window queries),
+    rather than diverging by computing a band the UI never plots."""
+    tg = _mock_table_group()
+    mock_resolve.return_value = (tg, _mock_monitor_suite())
+    mock_tr_cls.list_monitor_events_for_table.return_value = ([_monitor_event()], 1)
+    volume_def = MagicMock()
+    volume_def.history_calculation = "PREDICT"
+    volume_def.prediction = {"freshness_gated": True, "baseline_value": 500.0}
+    volume_def.lower_tolerance = None
+    volume_def.upper_tolerance = None
+    mock_td_cls.get_singleton_monitor.return_value = volume_def
+
+    from testgen.mcp.tools.monitors import list_monitor_events
+
+    with _patch_perms():
+        out = list_monitor_events(str(tg.id), "orders", "volume", include_predictions=True)
+
+    assert "## Forecast" in out
+    assert "No forecast available for this monitor right now" in out
+    # No band, and no terminology leak.
+    assert "| Time | Predicted lower | Predicted upper |" not in out
+    assert "gated" not in out.lower()
+    # The freshness window queries are skipped when there's no tolerance to band.
+    assert mock_td_cls.get_singleton_monitor.call_count == 1  # only the volume singleton lookup
+
+
 @patch(f"{MODULE}.resolve_monitored_table_group")
 def test_list_monitor_events_not_monitored(mock_resolve, db_session_mock):
     tg = _mock_table_group(monitor_test_suite_id=None)

tests/unit/ui/test_monitors_dashboard.py

@@ -4,14 +4,14 @@
 import pandas as pd
 import pytest
 
-from testgen.ui.views.monitors_dashboard import (
-    _build_gated_forecast_prediction,
-    _freshness_next_update_window,
-)
+from testgen.common.monitor_forecast import gated_forecast_prediction
+from testgen.ui.views.monitors_dashboard import _freshness_next_update_window
 
 pytestmark = pytest.mark.unit
 
-MODULE = "testgen.ui.views.monitors_dashboard"
+# The business-time helpers live in (and are called from) the shared forecast
+# module, so patch them there even when exercising the dashboard wrapper.
+MODULE = "testgen.common.monitor_forecast"
 
 
 def _freshness_def(history_calculation="PREDICT", prediction=None, upper="1000", lower="500"):
@@ -93,7 +93,7 @@ def test_window_start_is_none_when_no_lower_tolerance(mock_abm, _mock_sched):
     assert window["end"] == int(pd.Timestamp("2026-06-23 19:00").timestamp() * 1000)
 
 
-# --- _build_gated_forecast_prediction ---
+# --- gated_forecast_prediction ---
 
 LAST_RUN = datetime(2026, 6, 23, 16, 0)
 NOW_MS = int(pd.Timestamp(LAST_RUN).timestamp() * 1000)
@@ -111,29 +111,29 @@ def _gated_def(baseline=1000.0, mean=None, lower="950", upper="1400"):
 
 
 def test_gated_prediction_none_without_window():
-    assert _build_gated_forecast_prediction(_gated_def(), None, LAST_RUN) is None
+    assert gated_forecast_prediction(_gated_def(), None, LAST_RUN) is None
 
 
 def test_gated_prediction_none_when_window_elapsed():
     window = {"start": NOW_MS - 12 * HOUR, "end": NOW_MS - HOUR}  # window_end already in the past
-    assert _build_gated_forecast_prediction(_gated_def(), window, LAST_RUN) is None
+    assert gated_forecast_prediction(_gated_def(), window, LAST_RUN) is None
 
 
 def test_gated_prediction_none_without_baseline():
     window = {"start": NOW_MS - HOUR, "end": NOW_MS + 3 * HOUR}
-    assert _build_gated_forecast_prediction(_gated_def(baseline=None), window, LAST_RUN) is None
+    assert gated_forecast_prediction(_gated_def(baseline=None), window, LAST_RUN) is None
 
 
 def test_gated_prediction_none_without_last_run():
     window = {"start": NOW_MS - HOUR, "end": NOW_MS + 3 * HOUR}
-    assert _build_gated_forecast_prediction(_gated_def(), window, None) is None
+    assert gated_forecast_prediction(_gated_def(), window, None) is None
 
 
 def test_gated_prediction_anchors_at_now_when_window_started():
     # window_start is before the latest run → anchor clamps to now (forecast never draws backward)
     window = {"start": NOW_MS - 12 * HOUR, "end": NOW_MS + 3 * HOUR}
     mean = {str(NOW_MS + 3 * HOUR): 1200.0, str(NOW_MS + 27 * HOUR): 1300.0}
-    result = _build_gated_forecast_prediction(_gated_def(mean=mean), window, LAST_RUN)
+    result = gated_forecast_prediction(_gated_def(mean=mean), window, LAST_RUN)
     assert result["method"] == "predict"
     assert result["mean"] == {NOW_MS: 1000.0, NOW_MS + 3 * HOUR: 1200.0}
     # tolerances coerced from VARCHAR to float
@@ -145,11 +145,11 @@ def test_gated_prediction_anchors_at_window_start_when_future():
     # window opens after the latest run → flat segment runs out to window_start
     window = {"start": NOW_MS + HOUR, "end": NOW_MS + 3 * HOUR}
     mean = {str(NOW_MS + 3 * HOUR): 1200.0}
-    result = _build_gated_forecast_prediction(_gated_def(mean=mean), window, LAST_RUN)
+    result = gated_forecast_prediction(_gated_def(mean=mean), window, LAST_RUN)
     assert set(result["mean"].keys()) == {NOW_MS + HOUR, NOW_MS + 3 * HOUR}
 
 
 def test_gated_prediction_next_mean_falls_back_to_baseline_without_forecast():
     window = {"start": NOW_MS - HOUR, "end": NOW_MS + 3 * HOUR}
-    result = _build_gated_forecast_prediction(_gated_def(mean=None), window, LAST_RUN)
+    result = gated_forecast_prediction(_gated_def(mean=None), window, LAST_RUN)
     assert result["mean"][NOW_MS + 3 * HOUR] == 1000.0  # baseline used as the step value