fix: v2.5.1 — stale 'SKIPPED: Nighttime' on Solar Surplus diagnostic + self-diagnosable astral times (issue #34)

- _start_timer runs an immediate check after registering the interval timer
  so the diagnostic sensor reflects real day/night state right after setup
  instead of carrying a stale (e.g. previous night's) value until the first
  tick. Wrapped in try/except so a first-check failure never blocks setup.
- New _build_nighttime_debug_attributes attaches now/sunrise_today/sunset_today
  to SKIPPED: Nighttime (+ profile mismatch) events so users can tell a
  location/timezone misconfig from a stale value at a glance.
- Detection/robustness only; is_nighttime() and charging control untouched.
  Entity counts unchanged (67/53).
- Tests: test_nighttime_skip_exposes_astral_times, test_start_timer_runs_initial_check.

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

Author: Antonio ...

CLAUDE.md

@@ -757,6 +757,21 @@ async def _set_amperage(self, target_amperage: int):
 
 ## Version History
 
+### v2.5.1 (2026-06-04)
+**FIX: Stale "SKIPPED: Nighttime" on the Solar Surplus diagnostic + self-diagnosable astral times ([issue #34](https://github.com/antbald/ha-ev-smart-charger/issues/34), xion2000)**
+
+**Problem**: a user (no overnight charging, no hybrid inverter, no forecast) saw the `evsc_solar_surplus_diagnostic` sensor stuck on `SKIPPED: Nighttime` in the middle of the day, then it "fixed itself at ~14:38" — an hour with no astronomical meaning. His `sun.sun` data (UK/BST: sunrise 04:33, sunset 21:33 local, `elevation 22.71`, `above_horizon`) proved the location/timezone were **correct**, and `is_nighttime()` ([astral_time_service.py:122](custom_components/ev_smart_charger/utils/astral_time_service.py#L122)) would have correctly returned "day" all afternoon. So this was **not** an astral-logic bug — the diagnostic sensor was simply **stale** (carrying the previous night's value), almost certainly because the post-update file swap (2.2.2 → 2.4.0) left the running instance in a partial state until a clean HA restart around 14:38 re-ran the loop.
+
+**Two real weaknesses fixed (detection/robustness only — no charging-control change)**:
+1. **No immediate first check.** `_start_timer` ([solar_surplus.py](custom_components/ev_smart_charger/solar_surplus.py)) registered `async_track_time_interval` (which does **not** fire an initial tick), so the sensor kept whatever value it had until the first interval elapsed. Now `_start_timer` runs one `await self._async_periodic_check(ignore_rate_limit=True)` right after registering the timer, wrapped in try/except so a first-check failure never blocks setup. The sensor reflects the true day/night state seconds after setup.
+2. **`SKIPPED: Nighttime` was not self-diagnosable.** The event exposed no astral context. New `_build_nighttime_debug_attributes(now)` attaches `now` / `sunrise_today` / `sunset_today` to both `SKIPPED: Nighttime` and `SKIPPED: Nighttime (profile mismatch)` events. A user can now tell at a glance: wrong sunrise/sunset → HA location/timezone misconfig; correct times but daytime → stale value (and the immediate-tick fix removes that window).
+
+**Scope / safety**: no entity/config-flow/schema change, entity counts unchanged (67/53), `is_nighttime()` untouched. Tests ([tests/test_solar_surplus.py](tests/test_solar_surplus.py)): `test_nighttime_skip_exposes_astral_times`, `test_start_timer_runs_initial_check`. Full suite green except the pre-existing environment-only baseline failures (grid-import / surplus-stability timing tests, identical on clean master). `VERSION = "2.5.1"`.
+
+**Upgrade priority**: 🟢 RECOMMENDED if you ever see a stale `SKIPPED: Nighttime` in daytime — the sensor now self-corrects on setup and exposes the sunrise/sunset it computed. ⚪ NO-OP otherwise.
+
+---
+
 ### v2.5.0 (2026-06-04)
 **FEATURE: Surface the silent "Priority Balancer disabled" battery-protection bypass ([issue #35](https://github.com/antbald/ha-ev-smart-charger/issues/35), DJm00n)**
 

custom_components/ev_smart_charger/const.py

@@ -2,7 +2,7 @@
 
 # ========== INTEGRATION METADATA ==========
 DOMAIN = "ev_smart_charger"
-VERSION = "2.5.0"
+VERSION = "2.5.1"
 DEFAULT_NAME = "EV Smart Charger"
 FRONTEND_URL_BASE = "/api/ev_smart_charger/frontend"
 FRONTEND_CARD_FILENAME = "ev-smart-charger-dashboard.js"

custom_components/ev_smart_charger/manifest.json

@@ -11,5 +11,5 @@
   "iot_class": "local_push",
   "issue_tracker": "https://github.com/antbald/ha-ev-smart-charger/issues",
   "requirements": [],
-  "version": "2.5.0"
+  "version": "2.5.1"
 }

custom_components/ev_smart_charger/solar_surplus.py

@@ -446,6 +446,15 @@ async def _start_timer(self) -> None:
 
         self.logger.info(f"Timer started with {interval_minutes} minute interval")
 
+        # Run one check immediately so the diagnostic sensor reflects the
+        # current day/night state right after setup instead of carrying a
+        # stale value (e.g. last night's "SKIPPED: Nighttime") until the
+        # first timer tick fires `interval_minutes` later (issue #34).
+        try:
+            await self._async_periodic_check(ignore_rate_limit=True)
+        except Exception as err:  # noqa: BLE001 - never block setup on first check
+            self.logger.warning(f"Initial periodic check failed: {err}")
+
     @callback
     async def _async_home_battery_soc_changed(self, event) -> None:
         """Handle home battery SOC state changes for immediate battery protection.
@@ -1132,9 +1141,25 @@ async def _enforce_ev_target_hard_cap(self, context: str, charger_is_on: bool |
         )
         return True
 
+    def _build_nighttime_debug_attributes(self, now: datetime) -> dict:
+        """Expose the astral times behind a nighttime decision.
+
+        Lets users self-diagnose a "SKIPPED: Nighttime" shown in daytime:
+        if these sunrise/sunset times look wrong, the HA location/timezone is
+        misconfigured; if they look right, the value is stale (issue #34).
+        """
+        sunset = self._astral_service.get_sunset(now)
+        sunrise = self._astral_service.get_sunrise(now)
+        return {
+            "now": now.isoformat(),
+            "sunrise_today": sunrise.isoformat() if sunrise else None,
+            "sunset_today": sunset.isoformat() if sunset else None,
+        }
+
     async def _handle_nighttime_transition(self, now: datetime, current_profile: str | None) -> None:
         """Handle sunset transition when Solar Surplus is no longer allowed to run."""
         charger_is_on = await self.charger_controller.is_charging()
+        nighttime_debug = self._build_nighttime_debug_attributes(now)
 
         if not charger_is_on:
             if self._has_control():
@@ -1143,7 +1168,11 @@ async def _handle_nighttime_transition(self, now: datetime, current_profile: str
             self.logger.skip("Nighttime - Solar Surplus only operates during daytime (sunrise to sunset)")
             await self._update_diagnostic_sensor(
                 "SKIPPED: Nighttime",
-                {"reason": "Solar production unavailable at night", "last_check": dt_util.now().isoformat()},
+                {
+                    "reason": "Solar production unavailable at night",
+                    "last_check": dt_util.now().isoformat(),
+                    **nighttime_debug,
+                },
             )
             return
 
@@ -1157,6 +1186,7 @@ async def _handle_nighttime_transition(self, now: datetime, current_profile: str
                     "reason": "Charger active but profile is not solar_surplus",
                     "profile": current_profile,
                     "last_check": dt_util.now().isoformat(),
+                    **nighttime_debug,
                 },
             )
             return

tests/test_solar_surplus.py

@@ -503,3 +503,46 @@ async def test_balancer_clear_after_warn_resets_guard(hass, automation):
     await automation._clear_balancer_disabled_warning()
     automation._notification_service.dismiss.assert_awaited_once()
     assert automation._balancer_disabled_warned_date is None
+
+
+async def test_nighttime_skip_exposes_astral_times(hass, automation):
+    """SKIPPED: Nighttime must expose now/sunrise/sunset for self-diagnosis (issue #34)."""
+    hass.states.async_set("switch.force", "off")
+    hass.states.async_set("select.profile", "manual")
+
+    automation._astral_service.is_nighttime.return_value = True
+    automation.charger_controller.is_charging.return_value = False
+
+    sunrise = datetime(2026, 6, 4, 4, 33)
+    sunset = datetime(2026, 6, 4, 21, 33)
+    automation._astral_service.get_sunrise.return_value = sunrise
+    automation._astral_service.get_sunset.return_value = sunset
+
+    captured = {}
+
+    async def _capture(state, attributes):
+        captured["state"] = state
+        captured["attributes"] = attributes
+
+    automation._update_diagnostic_sensor = _capture
+
+    await automation._async_periodic_check()
+
+    assert captured["state"] == "SKIPPED: Nighttime"
+    attrs = captured["attributes"]
+    assert attrs["sunrise_today"] == sunrise.isoformat()
+    assert attrs["sunset_today"] == sunset.isoformat()
+    assert "now" in attrs
+
+
+async def test_start_timer_runs_initial_check(hass, automation):
+    """_start_timer must run one immediate check so the sensor is never stale (issue #34)."""
+    automation._async_periodic_check = AsyncMock()
+
+    with patch(
+        "custom_components.ev_smart_charger.solar_surplus.async_track_time_interval"
+    ) as mock_track:
+        mock_track.return_value = MagicMock()
+        await automation._start_timer()
+
+    automation._async_periodic_check.assert_awaited_once_with(ignore_rate_limit=True)