release: qualify the 0.9.6 notes for the explicit-choice fix and legacy stored zones

Co-authored-by: Joshua <joshua@cnjmail.com>
Co-committed-by: Joshua <joshua@cnjmail.com>

RELEASE_NOTES.md

@@ -1,5 +1,66 @@
 # 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: any admin update that supplies
+  `timezone` is recorded as an explicit choice (`timezone_configured` true). 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,6 +184,11 @@ 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(
@@ -199,6 +204,10 @@ 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.5"
+  "version": "0.9.6"
 }

pyproject.toml

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

tests/test_api_household_clock.py

@@ -445,6 +445,44 @@ 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:

uv.lock

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