Manual timezone is the single source of local-time truth (task 7e173881) (#285)

Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>
Co-committed-by: dev_agent <dev_agent@cubecraftlabs.com>

api/host_zone.py

@@ -0,0 +1,62 @@
+"""The API's effective application timezone (task 7e173881).
+
+The admin-stored ``timezone`` setting is the single source of local-time
+truth; stored empty, the API reads its clock in the API host's local
+time.  :func:`effective_timezone` names the zone the API actually uses —
+the stored zone, or else the host's own IANA zone — so the panel cards
+and the admin app format local time in exactly the API's zone instead of
+guessing with Home Assistant's or the browser's.  ``""`` only when the
+host's zone genuinely cannot be named.
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+def _valid_zone(name: str) -> str:
+    """Return ``name`` if it is a loadable IANA zone key, else ``""``."""
+    name = name.strip().removeprefix(":")
+    if not name:
+        return ""
+    try:
+        ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError):
+        return ""
+    return name
+
+
+def host_timezone(
+    environ: Mapping[str, str] = os.environ,
+    timezone_file: Path = Path("/etc/timezone"),
+    localtime: Path = Path("/etc/localtime"),
+) -> str:
+    """Name the API host's local zone as an IANA key, or ``""``.
+
+    In the order the C library honours them: the ``TZ`` environment
+    variable, then the ``/etc/localtime`` zoneinfo link (with Debian's
+    ``/etc/timezone`` naming it when the link is a copy).  A host with
+    none of them configured runs UTC.  A setting that names no IANA
+    zone (a POSIX rule string, a copied file) is ``""``.
+    """
+    configured = environ.get("TZ")
+    if configured is not None:
+        # An empty TZ is UTC to the C library.
+        return _valid_zone(configured) if configured.strip() else "UTC"
+    if localtime.is_symlink():
+        target = str(localtime.resolve())
+        marker = "/zoneinfo/"
+        if marker in target:
+            return _valid_zone(target.split(marker, 1)[1])
+    if timezone_file.is_file():
+        return _valid_zone(timezone_file.read_text(encoding="utf-8"))
+    if not localtime.exists():
+        return "UTC"
+    return ""
+
+
+def effective_timezone(stored: str) -> str:
+    """The zone the API reads its clock in: ``stored``, else the host's."""
+    return stored or host_timezone()

api/routes_admin.py

@@ -170,7 +170,10 @@ are deliberately not unified here:
   notify target, the three notification times, the four enable
   toggles, and the ``timezone`` — the IANA household zone the
   household-local dates derive from, empty meaning host local; only an
-  admin's ``PATCH`` ever sets it) — the defaults on a fresh database.
+  admin's ``PATCH`` ever sets it) — the defaults on a fresh database —
+  plus the read-only ``effective_timezone`` (:mod:`api.host_zone`): the
+  zone the API actually reads its clock in, which the admin app formats
+  local time in.
 - ``PATCH /settings`` updates ONLY the supplied fields: the body is a
   JSON object of settings field names to new values, passed STRAIGHT
   to :func:`nestquest_core.settings_store.update_settings` — the
@@ -349,6 +352,7 @@ from pydantic import (
     model_validator,
 )
 
+from api import host_zone
 from api import transitions as api_transitions
 from api.auth import require_admin
 from api.database import DatabaseState
@@ -920,9 +924,14 @@ class AdminSettingsResponse(BaseModel):
     afternoon_reminder_enabled: bool
     end_of_day_report_enabled: bool
     celebration_enabled: bool
-    #: The household IANA time zone the API reads its clock in; ``""``
-    #: means the API host's local time.
+    #: The household IANA time zone the admin stored; ``""`` means the
+    #: API host's local time.
     timezone: str
+    #: The zone the API actually reads its clock in — ``timezone``, or
+    #: the API host's own zone when that is ``""`` (``""`` only when the
+    #: host's zone cannot be named).  Read-only; the admin app formats
+    #: local time in it.
+    effective_timezone: str
 
 
 class AdminMissedSweepResponse(BaseModel):
@@ -2179,8 +2188,9 @@ def _settings_response(
     """Serialize one core NestQuestSettings into the documented payload.
 
     Explicit field-by-field (not ``dataclasses.asdict``) so the payload
-    stays pinned to the eleven documented fields even if the core
-    dataclass later grows another one.
+    stays pinned to the eleven documented fields (plus the read-only
+    ``effective_timezone``) even if the core dataclass later grows
+    another one.
     """
     return AdminSettingsResponse(
         horizon_days=settings.horizon_days,
@@ -2194,6 +2204,7 @@ def _settings_response(
         end_of_day_report_enabled=settings.end_of_day_report_enabled,
         celebration_enabled=settings.celebration_enabled,
         timezone=settings.timezone,
+        effective_timezone=host_zone.effective_timezone(settings.timezone),
     )
 
 
@@ -2330,12 +2341,25 @@ async def admin_update_settings(
     every value has validated — so a rejected update never changes the
     stored settings.  Every core ``ValueError`` is 422
     (:func:`_raise_settings_error`); anything else re-raises.
+
+    The write holds the missed-sweep scheduler's ``settings_lock`` and
+    then tells it (:meth:`~api.scheduler.MissedSweepScheduler.settings_changed`),
+    so a saved ``timezone`` or ``day_rollover_time`` re-plans a sleeping
+    scheduler (an app without one — no lifespan — just writes).
     """
     state: DatabaseState = request.app.state.db
+    scheduler = getattr(request.app.state, "sweep_scheduler", None)
     try:
-        settings = await core_settings_store.update_settings(
-            state.database, changes
-        )
+        if scheduler is None:
+            settings = await core_settings_store.update_settings(
+                state.database, changes
+            )
+        else:
+            async with scheduler.settings_lock:
+                settings = await core_settings_store.update_settings(
+                    state.database, changes
+                )
+                scheduler.settings_changed(settings)
     except ValueError as error:
         _raise_settings_error(error)
     return _settings_response(settings)

api/routes_panel.py

@@ -21,6 +21,7 @@ panel payload), and returns the documented JSON shape:
     {
       "today_iso": "2026-09-22",
       "cycle_day": 2,
+      "timezone": "Pacific/Auckland",
       "children": [
         {
           "child_id": 1,
@@ -45,7 +46,11 @@ panel payload), and returns the documented JSON shape:
 active children ``ORDER BY sort_order, id``); ``state`` is the
 documented panel spelling ``open`` | ``completed`` (§1 of
 design/ENTITIES-AND-SERVICES.md); ``cycle_day`` is today's 1-based day
-in the first scheduled child's custody cycle (0 when no child has one).
+in the first scheduled child's custody cycle (0 when no child has one);
+``timezone`` is the effective application timezone — the zone the admin
+stored, or the API host's own zone when none is (``""`` only when the
+host's zone cannot be named; :mod:`api.host_zone`) — which the panel
+cards format their visible date and clock in.
 The same :class:`PanelSnapshotResponse` Pydantic model is the route's
 ``response_model``, so the OpenAPI document carries the shape too.
 """
@@ -66,6 +71,7 @@ from api.nestquest_core import (
     core_settings_store,
     core_snapshot,
 )
+from api import host_zone
 from api import transitions as api_transitions
 from api.sse import transition_event_stream
 
@@ -126,12 +132,14 @@ class PanelSnapshotResponse(BaseModel):
 
     ``today_iso`` anchors the payload's day; ``cycle_day`` is today's
     1-based day in the first scheduled child's custody cycle (0 when no
-    child has a schedule); ``children`` is in the household's sort
-    order.
+    child has a schedule); ``timezone`` is the effective application
+    timezone (:func:`api.host_zone.effective_timezone`); ``children`` is
+    in the household's sort order.
     """
 
     today_iso: str
     cycle_day: int
+    timezone: str
     children: list[PanelChildPayload]
 
 
@@ -218,6 +226,7 @@ async def panel_snapshot(request: Request) -> PanelSnapshotResponse:
     return PanelSnapshotResponse(
         today_iso=snapshot.today_iso,
         cycle_day=snapshot.cycle_day,
+        timezone=host_zone.effective_timezone(snapshot.timezone),
         children=[
             PanelChildPayload(
                 child_id=child.child_id,

api/scheduler.py

@@ -22,7 +22,8 @@ it planned with has moved, and the loop re-reads the settings before
 sweeping and re-plans instead if they no longer match its plan.
 
 Guarantee: no sweep runs for a plan a committed settings write has
-replaced.  A settings writer holds :attr:`MissedSweepScheduler.settings_lock`
+replaced.  The settings writer — the admin ``PATCH /api/v1/admin/settings``
+route, the only one — holds :attr:`MissedSweepScheduler.settings_lock`
 across its write AND its :meth:`~MissedSweepScheduler.settings_changed`
 call; the loop holds the same lock across its plan read (read, record
 the plan, clear the wake flag) and across the pre-sweep re-read plus