Serialise time zone adoption with the missed-sweep scheduler

The wake flag compared an adoption only against the plan the loop last
recorded, so New York -> UTC -> New York during the re-plan read left
the scheduler sleeping on UTC midnight; and an adoption committing
between the pre-sweep check and the sweep still let the stale sweep run.

`MissedSweepScheduler.settings_lock` now serialises the panel's adoption
(write plus `settings_changed`) with the loop's plan read and with its
pre-sweep re-read plus sweep.  It is never held across the wait, and the
loop holds nothing else while acquiring it, so a panel request is at
most delayed by one settings read or one sweep.

`_sleep_unless_woken` now cancels and awaits both child tasks, and
re-raises a failed sleep inside the loop's retry block, so the backoff
runs instead of a sweep and nothing outlives `stop()`.

Tests (all four fail on bcf387d): the successive-zone race, an adoption
issued during the pre-sweep check, a failing sleep, and stop() waiting
for the sleep's cancellation cleanup.

Task: 6351b36d-0eef-4e7d-bf5a-96b754cbc883

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

RELEASE_NOTES.md

@@ -1,67 +1,5 @@
 # NestQuest Release Notes
 
-## Version 0.9.6 — 2026-09-28
-
-### Scope
-
-Patch release carrying the household time-zone fix onto `main` (PR #275, task
-6351b36d "Time zone errors"), plus its release-review correction (PR #277, task
-45243478).
-
-### Behaviour
-
-- The Home Assistant integration now reports `hass.config.time_zone` to the API
-  in an `X-NestQuest-Timezone` header on every panel request.
-- While the API's `timezone` setting has never been explicitly chosen
-  (`timezone_configured` false), the API adopts and persists the reported zone
-  (under the settings lock), so the panel's overdue/today calculation, the
-  admin plane and the missed-sweep scheduler are all household-local even when
-  the API host runs UTC. No manual setup is required.
-- The missed-sweep scheduler re-plans immediately when the adopted zone changes
-  while it is sleeping, and re-reads the stored zone before sweeping, so it no
-  longer fires at the old (UTC) rollover.
-- An admin-chosen zone — including an explicit choice of empty (API-host local)
-  — still wins over the reported zone. A timezone-only admin update is recorded
-  as an explicit choice (`timezone_configured` true); an explicitly supplied
-  `timezone_configured` value in the same update is honored as given. An invalid
-  reported zone is logged and ignored; the panel keeps serving on the stored
-  settings.
-
-### Requirements
-
-- Home Assistant floor 2024.6.0 (unchanged).
-
-### Breaking changes
-
-- None. The database schema is unchanged at version 9: no migration and no
-  database backup is required for this release.
-- Deployment note: this fix needs BOTH the API service and the HA integration
-  upgraded. The integration supplies the zone and the API adopts it; upgrading
-  only one side leaves the previous behaviour. An install that sets or clears
-  its zone on 0.9.6 or later keeps that choice; see Known limitations for a zone
-  stored by an older release.
-
-### Known limitations
-
-- A zone stored by a release before 0.9.6 without the explicit-choice marker
-  (for example through the previously documented
-  `PATCH /api/v1/admin/settings {"timezone": ...}`) is not distinguishable from
-  an automatically adopted value, so 0.9.6 adopts Home Assistant's reported zone
-  over it once. If a zone different from Home Assistant's is intended, re-save
-  it in the admin Preferences, which now records the explicit choice.
-- If `timezone` is empty and `timezone_configured` is true (an explicit
-  "host local" choice), that choice is respected and the API host's zone (UTC
-  on the standard deployment) still applies until an admin selects a zone in
-  the admin Preferences.
-- A change to Home Assistant's own `time_zone` takes effect after the
-  integration reloads or Home Assistant restarts.
-
-### Rollback
-
-- No schema change: rolling back to 0.9.5 requires no database restore. The API
-  and the integration may be rolled back independently; rolling back only the
-  integration restores the previous stored-setting-only behaviour.
-
 ## Version 0.9.5 — 2026-09-27
 
 ### Scope

custom_components/nestquest/core/settings_store.py

@@ -184,11 +184,6 @@ async def update_settings(
     in one atomic upsert; the updated settings are returned.  The whole
     read → merge → write span runs inside the per-database settings
     lock, so concurrent updates queue instead of interleaving.
-
-    Supplying ``timezone`` without ``timezone_configured`` records the
-    zone as the admin's explicit choice (``timezone_configured`` is
-    persisted ``True`` in the same write); an explicitly supplied
-    ``timezone_configured`` is kept exactly as given.
     """
     if not isinstance(changes, Mapping):
         raise ValueError(
@@ -204,10 +199,6 @@ async def update_settings(
         raise ValueError(
             f"unknown settings field(s): {listed}; known fields: {known}"
         )
-    if "timezone" in changes and "timezone_configured" not in changes:
-        # An admin-supplied zone is an explicit choice, so Home
-        # Assistant's reported zone must no longer replace it.
-        changes = {**changes, "timezone_configured": True}
     async with _settings_lock(database):
         current = await load_settings(database)
         return await _write_merged(database, current, changes)

custom_components/nestquest/manifest.json

@@ -15,5 +15,5 @@
   "iot_class": "local_polling",
   "issue_tracker": "https://github.com/Maniacs-Mansion/NestQuest/issues",
   "requirements": [],
-  "version": "0.9.6"
+  "version": "0.9.5"
 }

frontend/src/cards/quest-log.ts

@@ -36,6 +36,7 @@ type PanelInstance = {
   window: string;
   due_time: string | null;
   state: string;
+  overdue: boolean;
   completed_at: string | null;
   on_time: boolean | null;
 };
@@ -153,17 +154,6 @@ function formatWallClock(value: string | null): string | null {
   return `${hour12}:${match[2]} ${suffix}`;
 }
 
-/** Minutes past midnight of a household ``HH:MM`` wall time, or null. */
-function wallClockMinutes(value: string | null): number | null {
-  const match = value ? /^(\d{1,2}):(\d{2})$/.exec(value.trim()) : null;
-  if (!match) {
-    return null;
-  }
-  const hours = Number(match[1]);
-  const minutes = Number(match[2]);
-  return hours > 23 || minutes > 59 ? null : hours * 60 + minutes;
-}
-
 function asString(value: unknown): string {
   return typeof value === "string" ? value.trim() : "";
 }
@@ -263,6 +253,7 @@ function toPanelInstance(value: unknown): PanelInstance | null {
     window: asString(row.window).toLowerCase(),
     due_time: asString(row.due_time) || null,
     state,
+    overdue: row.overdue === true,
     completed_at: asString(row.completed_at) || null,
     on_time: row.on_time === true ? true : row.on_time === false ? false : null,
   };
@@ -1758,20 +1749,6 @@ export class NestQuestQuestLogCard extends LitElement {
     `;
   }
 
-  /** Overdue by the panel's own clock: the browser runs on the
-      household's real local time, so an open quest turns overdue once its
-      ``due_time`` wall time has arrived there — whatever zone the API or
-      Home Assistant computed the API's ``overdue`` flag in.  With no due
-      time it is never overdue (the API's rule too).  ``_now`` is reactive
-      and ticks every 60 s, so the line flips on the minute it falls due. */
-  private _isOverdue(instance: PanelInstance): boolean {
-    const due = wallClockMinutes(instance.due_time);
-    if (instance.state !== "open" || due === null) {
-      return false;
-    }
-    return this._now.getHours() * 60 + this._now.getMinutes() >= due;
-  }
-
   private _timeZone(): string | undefined {
     return hassTimeZone(this.hass);
   }
@@ -1856,6 +1833,7 @@ export class NestQuestQuestLogCard extends LitElement {
         continue;
       }
       instance.state = "completed";
+      instance.overdue = false;
       instance.completed_at = stampedAt;
     }
     if (settled) {
@@ -2152,7 +2130,7 @@ export class NestQuestQuestLogCard extends LitElement {
       `;
     }
     const dueAt = formatWallClock(instance.due_time);
-    const meta = this._isOverdue(instance)
+    const meta = instance.overdue
       ? {
           text: dueAt ? `Overdue · due ${dueAt}` : "Overdue",
           late: true,

frontend/tests/render-quest-log.mjs

@@ -16,12 +16,6 @@
  * reports every hass.callService call as tap: {dialog_opened, service_calls}.
  * With tap_return: true the harness taps the header's return control and
  * reports it as returned: {rendered, label} before the final snapshot.
- * With now: <ISO instant> the card's clock is pinned there (argument-less
- * new Date() and Date.now() return it; the process TZ decides its local
- * wall time), and with advance_to: [<ISO instant>, ...] the clock moves to
- * each instant in turn and the card's own 60 s clock-tick callbacks fire,
- * one snapshot per instant reported as ticks (the top-level snapshot is
- * taken before the clock moves).
  * The Python panel tests drive this harness so the
  * assertions run against the exact bundle HACS ships.
  */
@@ -53,33 +47,6 @@ globalThis.window = dom.window;
 // jsdom Event must shadow it for the return navigation to be delivered.
 globalThis.Event = dom.window.Event;
 
-// Pin the clock: argument-less construction and Date.now() read `pinned`,
-// every other Date use is the real class.
-let pinned = spec.now !== undefined ? new Date(spec.now).getTime() : null;
-if (pinned !== null) {
-  const RealDate = Date;
-  class PinnedDate extends RealDate {
-    constructor(...args) {
-      super(...(args.length === 0 ? [pinned] : args));
-    }
-    static now() {
-      return pinned;
-    }
-  }
-  globalThis.Date = PinnedDate;
-  dom.window.Date = PinnedDate;
-}
-
-// Record the card's 60 s clock ticks so advance_to can fire them on demand.
-const clockTicks = [];
-const realSetInterval = dom.window.setInterval.bind(dom.window);
-dom.window.setInterval = (callback, ms, ...rest) => {
-  if (ms === 60000) {
-    clockTicks.push(callback);
-  }
-  return realSetInterval(callback, ms, ...rest);
-};
-
 await import(pathToFileURL(spec.bundle).href);
 
 const serviceCalls = [];
@@ -156,18 +123,6 @@ if (spec.idle_ms !== undefined) {
   await new Promise((resolve) => setTimeout(resolve, spec.idle_ms));
 }
 
-const settled = snapshot();
-let ticks = null;
-if (spec.advance_to !== undefined) {
-  ticks = [];
-  for (const instant of spec.advance_to) {
-    pinned = new Date(instant).getTime();
-    clockTicks.forEach((callback) => callback());
-    await element.updateComplete;
-    ticks.push(snapshot());
-  }
-}
-
-const payload = JSON.stringify({ ...settled, probe, tap, returned, ticks });
+const payload = JSON.stringify({ ...snapshot(), probe, tap, returned });
 await new Promise((resolve) => process.stdout.write(payload, () => resolve()));
 process.exit(0);

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nestquest"
-version = "0.9.6"
+version = "0.9.5"
 description = "NestQuest Home Assistant Integration"
 readme = "README.md"
 requires-python = ">=3.11"

tests/test_api_household_clock.py

@@ -445,44 +445,6 @@ async def test_admin_chosen_zone_wins_over_reported_zone(
     assert stored["timezone_configured"] is True
 
 
-# --- a timezone-only admin update is an explicit choice (task 45243478) ------
-
-
-@pytest.mark.parametrize("chosen", ["America/Los_Angeles", ""])
-async def test_timezone_only_admin_update_is_an_explicit_choice(
-    household: SimpleNamespace, chosen: str
-) -> None:
-    """``PATCH {"timezone": ...}`` alone marks the zone admin-chosen."""
-    await _adopt_new_york(household)
-    response = await household.client.patch(
-        "/api/v1/admin/settings",
-        json={"timezone": chosen},
-        headers=_admin_headers(),
-    )
-    assert response.status_code == 200
-    assert response.json()["timezone_configured"] is True
-    # A conflicting report is no longer adopted.
-    await _panel_pack_bag(household, "America/Chicago")
-    stored = await _stored_settings(household)
-    assert stored["timezone"] == chosen
-    assert stored["timezone_configured"] is True
-
-
-async def test_explicit_timezone_configured_false_is_respected(
-    household: SimpleNamespace,
-) -> None:
-    """A supplied ``timezone_configured`` is persisted exactly as given."""
-    response = await household.client.patch(
-        "/api/v1/admin/settings",
-        json={"timezone": "America/Chicago", "timezone_configured": False},
-        headers=_admin_headers(),
-    )
-    assert response.status_code == 200
-    assert response.json()["timezone_configured"] is False
-    await _panel_pack_bag(household, HOUSEHOLD_ZONE)
-    assert (await _stored_settings(household))["timezone"] == HOUSEHOLD_ZONE
-
-
 async def test_invalid_reported_zone_is_ignored(
     household: SimpleNamespace,
 ) -> None:

tests/test_panel_cards.py

@@ -21,7 +21,6 @@ end-to-end through the quest-log harness.
 from __future__ import annotations
 
 import json
-import os
 import re
 import subprocess
 from pathlib import Path
@@ -832,9 +831,6 @@ def _render_quest_log(
     probe_ms: int | None = None,
     tap_complete: int | None = None,
     tap_return: bool = False,
-    now: str | None = None,
-    advance_to: list[str] | None = None,
-    tz: str | None = None,
 ) -> dict:
     """Render the built bundle's quest log and report its location.
 
@@ -844,10 +840,7 @@ def _render_quest_log(
     segment — waits the optional probe window and captures one snapshot
     of the render mid-wait, then the optional idle window, and prints
     the final pathname and rendered title (plus the probe snapshot when
-    ``probe_ms`` was given).  ``now`` pins the card's clock to an ISO
-    instant, ``advance_to`` moves it through further instants firing the
-    card's clock tick (one snapshot each, under ``ticks``), and ``tz``
-    sets the node process's ``TZ`` — the panel browser's local zone.
+    ``probe_ms`` was given).
     """
     assert BUNDLE_PATH.is_file(), "bundle missing: run cd frontend && npm run build"
     assert QUEST_LOG_HARNESS.is_file()
@@ -865,17 +858,12 @@ def _render_quest_log(
         spec["tap_complete"] = tap_complete
     if tap_return:
         spec["tap_return"] = True
-    if now is not None:
-        spec["now"] = now
-    if advance_to is not None:
-        spec["advance_to"] = advance_to
     completed = subprocess.run(
         ["node", str(QUEST_LOG_HARNESS)],
         input=json.dumps(spec),
         capture_output=True,
         text=True,
         timeout=120,
-        env={**os.environ, "TZ": tz} if tz is not None else None,
     )
     assert completed.returncode == 0, (
         f"quest-log harness failed: {completed.stderr}"
@@ -1102,13 +1090,12 @@ def test_quest_log_meta_line_keeps_its_meta_class() -> None:
     ``meta ${late ? "late" : nothing}``, Lit dropped the whole class
     attribute for every quest that was not late, leaving the due line
     unstyled. The rendered markup must carry ``class="meta"`` on time and
-    ``class="meta late"`` overdue — overdue by the panel's pinned clock
-    (07:15 local: the 07:00 quest is late, the 08:15 one is not)."""
+    ``class="meta late"`` overdue."""
     generated = _generate_dashboard(
         {}, _three_child_states(), url="http://homeassistant.local/nestquest"
     )
 
-    def quest(instance_id: int, title: str, due_time: str) -> dict:
+    def quest(instance_id: int, title: str, overdue: bool) -> dict:
         return {
             "id": instance_id,
             "definition_id": instance_id,
@@ -1116,9 +1103,9 @@ def test_quest_log_meta_line_keeps_its_meta_class() -> None:
             "title": title,
             "icon": None,
             "window": "morning",
-            "due_time": due_time,
+            "due_time": "08:15",
             "state": "open",
-            "overdue": False,
+            "overdue": overdue,
             "completed_at": None,
             "on_time": None,
         }
@@ -1131,8 +1118,8 @@ def test_quest_log_meta_line_keeps_its_meta_class() -> None:
             child_id=1,
             present=True,
             instances=[
-                quest(41, "Make Bed", "08:15"),
-                quest(42, "Brush Teeth", "07:00"),
+                quest(41, "Make Bed", overdue=False),
+                quest(42, "Brush Teeth", overdue=True),
             ],
         ),
     }
@@ -1140,8 +1127,6 @@ def test_quest_log_meta_line_keeps_its_meta_class() -> None:
         generated["views"][1]["cards"][0],
         states,
         url="http://homeassistant.local/nestquest/ada",
-        now="2026-09-29T11:15:00Z",
-        tz="America/New_York",
     )
     metas = {}
     for card in result["html"].split('data-instance-id="')[1:]:
@@ -1158,83 +1143,6 @@ def test_quest_log_meta_line_keeps_its_meta_class() -> None:
     assert metas["42"].strip() == 'class="meta late"', metas["42"]
 
 
-def _quest_metas(html: str) -> dict[str, tuple[str, str]]:
-    """Map each rendered open quest's instance id to its meta line's
-    attributes and text."""
-    metas = {}
-    for card in html.split('data-instance-id="')[1:]:
-        meta = re.search(
-            r'<span class="quest-title">.*?</span>'
-            r"\s*(?:<!--[^>]*-->\s*)*<span([^>]*)>(.*?)</span>",
-            card,
-            re.S,
-        )
-        assert meta is not None, card[:800]
-        text = " ".join(re.sub(r"<!--[^>]*-->", "", meta.group(2)).split())
-        metas[card[: card.index('"')]] = (meta.group(1).strip(), text)
-    return metas
-
-
-def test_quest_log_overdue_follows_the_panel_local_clock() -> None:
-    """Overdue is decided by the panel's own local clock, not the API's
-    ``overdue`` flag.  The owner saw 8:15 AM quests read OVERDUE at 7:15 AM
-    America/New_York: the API's flag had been computed on a UTC wall clock
-    (11:15).  Here the API still says ``overdue: true`` and Home
-    Assistant reports ``time_zone`` UTC, yet at 07:15 local the 08:15 quest
-    is due, at 08:15 (and 08:16, via the card's own clock tick) it is
-    overdue, and a quest with no due time is never overdue."""
-    generated = _generate_dashboard(
-        {}, _three_child_states(), url="http://homeassistant.local/nestquest"
-    )
-
-    def quest(instance_id: int, title: str, due_time: str | None) -> dict:
-        return {
-            "id": instance_id,
-            "definition_id": instance_id,
-            "child_id": 1,
-            "title": title,
-            "icon": None,
-            "window": "morning",
-            "due_time": due_time,
-            "state": "open",
-            "overdue": True,
-            "completed_at": None,
-            "on_time": None,
-        }
-
-    states = {
-        **_three_child_states(),
-        "sensor.nestquest_ada_quests_due_today": _state(
-            "2",
-            child_name="Ada",
-            child_id=1,
-            present=True,
-            instances=[
-                quest(42, "Brush Teeth", "08:15"),
-                quest(43, "Feed Fish", None),
-            ],
-        ),
-    }
-    result = _render_quest_log(
-        generated["views"][1]["cards"][0],
-        states,
-        url="http://homeassistant.local/nestquest/ada",
-        now="2026-09-29T11:15:00Z",
-        advance_to=["2026-09-29T12:15:00Z", "2026-09-29T12:16:00Z"],
-        tz="America/New_York",
-    )
-    due_by = ('class="meta"', "Due by 8:15 AM")
-    overdue = ('class="meta late"', "Overdue · due 8:15 AM")
-    not_due = ('class="meta"', "Due today")
-    at_0715, at_0815, at_0816 = (
-        _quest_metas(result["html"]),
-        *(_quest_metas(tick["html"]) for tick in result["ticks"]),
-    )
-    assert at_0715 == {"42": due_by, "43": not_due}, at_0715
-    assert at_0815 == {"42": overdue, "43": not_due}, at_0815
-    assert at_0816 == {"42": overdue, "43": not_due}, at_0816
-
-
 def test_quest_log_crest_matches_the_spec_geometry() -> None:
     """PANEL-SPEC §3 header crest: 96x110 shield, 4px ring of
     rgba(255,255,255,.22) around the --nq-p-crest face, 44px/700 display

uv.lock

@@ -373,7 +373,7 @@ wheels = [
 
 [[package]]
 name = "nestquest"
-version = "0.9.6"
+version = "0.9.5"
 source = { virtual = "." }
 
 [package.dev-dependencies]