quilt-hp-python 0.5.3__tar.gz → 0.5.4__tar.gz

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-07-03
+
+Fixes all findings from a full architecture/code/performance/bug-hunt evaluation.
+
+### Critical
+
+- **Proto3 absence detection never fired on real protos.** Truthiness and
+  getattr-with-default checks always pass on generated messages (unset
+  sub-messages return truthy default instances), so sparse stream diffs zeroed
+  room state, IDU controls, sensor readings, and controller temperatures on
+  merge. All model parsing now uses `HasField`-based helpers, and
+  `SystemSnapshot.apply_*` preserves identity/relationship fields, controller
+  temperatures, ODU telemetry, and QSM LED state. New test suite
+  (`tests/test_models_real_proto_merge.py`) reproduces the notifier stream's
+  serialize/parse path with real generated protos.
+- **Transport UNAUTHENTICATED retry was dead code.** In `grpc.aio`, awaiting the
+  interceptor continuation returns the call object; `AioRpcError` only surfaces
+  when the call is awaited — so token refresh/retry never executed and clients
+  broke permanently ~1h after token expiry. The interceptor now awaits the call
+  and retries once. Tests updated to model real `grpc.aio` semantics.
+
+### High
+
+- Stream reconnect backoff/budget reset after a healthy connection (routine LB
+  stream recycling no longer escalates to permanent 60s delays or kills the
+  stream after N lifetime disconnects); non-gRPC failures reconnect and surface
+  via `on_error` instead of dying silently; malformed events are skipped;
+  jitter added; prompt reconnect after successful token refresh.
+- `authenticate()` no longer returns a locally-unexpired token the server just
+  rejected; rotated Cognito refresh tokens are persisted; expiry measured from
+  token receipt.
+- `grpc_call` passes `CancelledError` through untranslated (asyncio.timeout/
+  cancellation semantics restored).
+- TUI: fatal stream death now shows a disconnect indicator and auto-recovers;
+  first-time users get an OTP modal; boot failures show an error screen
+  instead of a stuck spinner.
+
+### Medium / Low
+
+- Unified error translation: all hds/user RPCs route through `grpc_call`;
+  `UNAVAILABLE`/`DEADLINE_EXCEEDED` → `QuiltConnectionError` and `NOT_FOUND` →
+  `QuiltNotFoundError` everywhere.
+- Single-flight guards on token refresh and cold snapshot fetch;
+  `get_system_id(home=...)` no longer poisons the default-system cache;
+  `close()` stops tracked streams; duplicate authorization metadata
+  eliminated.
+- Stream API: `on_connected` callback, unsubscribe handles from all `on_*`
+  registrations, `apply_software_update_info`, descriptor-derived wire-scan
+  field numbers.
+- CLI/TUI: app-owned snapshot (stacked screens no longer go stale), cursor
+  preservation, setpoint bounds, energy period validation, app-level °C/°F,
+  LED brightness restoration, 0.0 readings rendered correctly, token store
+  corruption recovery + fsync + flock, config dir 0700, dead code removal.
+- Docs: README no longer demonstrates raw-stream usage; stream/token types
+  re-exported at package top level; stale OutdoorUnit/Controller reference
+  listings corrected; contradictory proto comments fixed.
+
+Intentionally unchanged: Python >= 3.14 floor and boto3 dependency (HA 2026.3+
+runs Python 3.14).
+
 ## [0.5.3] - 2026-06-30
 
 ## [0.5.2] - 2026-06-30

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quilt-hp-python
-Version: 0.5.3
+Version: 0.5.4
 Summary: Async Python client for Quilt mini-split HVAC systems
 Project-URL: Repository, https://github.com/eman/quilt-hp-python
 Project-URL: Issues, https://github.com/eman/quilt-hp-python/issues
@@ -101,11 +101,15 @@ async def main():
         spaces = await client.list_spaces()
         await client.set_space(spaces[0].id, mode=HVACMode.COOL, cool_setpoint_c=22.0)
 
-        # Stream real-time updates
-        spaces = await client.list_spaces()
-        topics = [f"hds/space/{s.id}" for s in spaces]
-        async with client.stream(topics) as stream:
-            stream.on_space_update(lambda s: print(f"{s.name}: {s.state.ambient_temperature_c}°C"))
+        # Stream real-time updates — stream events are sparse diffs, so
+        # always merge them into a snapshot before use
+        snapshot = await client.get_snapshot()
+        async with client.stream(snapshot.stream_topics()) as stream:
+            def on_space(space):
+                merged = snapshot.apply_space(space)
+                print(f"{merged.name}: {merged.state.ambient_temperature_c}°C")
+
+            stream.on_space_update(on_space)
             await asyncio.sleep(60)
 
 asyncio.run(main())

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/README.md

@@ -36,11 +36,15 @@ async def main():
         spaces = await client.list_spaces()
         await client.set_space(spaces[0].id, mode=HVACMode.COOL, cool_setpoint_c=22.0)
 
-        # Stream real-time updates
-        spaces = await client.list_spaces()
-        topics = [f"hds/space/{s.id}" for s in spaces]
-        async with client.stream(topics) as stream:
-            stream.on_space_update(lambda s: print(f"{s.name}: {s.state.ambient_temperature_c}°C"))
+        # Stream real-time updates — stream events are sparse diffs, so
+        # always merge them into a snapshot before use
+        snapshot = await client.get_snapshot()
+        async with client.stream(snapshot.stream_topics()) as stream:
+            def on_space(space):
+                merged = snapshot.apply_space(space)
+                print(f"{merged.name}: {merged.state.ambient_temperature_c}°C")
+
+            stream.on_space_update(on_space)
             await asyncio.sleep(60)
 
 asyncio.run(main())

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/docs/explanation/streaming-protocol.md

@@ -84,7 +84,7 @@ stateDiagram-v2
     Fatal --> [*]
 ```
 
-The back-off starts at `reconnect_delay_s` (default 1 second), doubles on each failed attempt, and caps at 60 seconds. The request queue is reset before each reconnect so the server receives a fresh subscription request with the full topic list.
+The back-off starts at `reconnect_delay_s` (default 1 second), doubles on each consecutive failed attempt with ±50% jitter, and caps at 60 seconds. Both the back-off and the `max_reconnects` budget reset once a connection stays healthy for a while, so routine server-side stream recycling never escalates reconnect latency. After a successful token refresh the stream reconnects immediately. The request queue is reset before each reconnect so the server receives a fresh subscription request with the full topic list. `on_connected` callbacks fire on every successful (re)connect — use them to re-fetch a snapshot, since events published while disconnected are lost.
 
 The `UNAUTHENTICATED` path is special: the stream refreshes the token before waiting, because reconnecting immediately with a stale token would fail again. If the refresh itself fails, the stream gives up rather than entering an infinite retry loop with an invalid token.
 

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/docs/reference/client.md

@@ -69,7 +69,7 @@ Raised when a requested resource does not exist (gRPC `NOT_FOUND`).
 ### `__version__`
 
 ```python
-__version__: str  # e.g. "0.5.3"
+__version__: str  # e.g. "0.5.4"
 ```
 
 ---
@@ -112,7 +112,7 @@ async def __aenter__(self) -> QuiltClient: ...
 async def __aexit__(self, *_: object) -> None: ...
 ```
 
-`__aexit__` calls `close()` to close the gRPC channel. Prefer the async context manager, or call `await close()` yourself when managing lifecycle manually.
+`__aexit__` calls `close()`, which stops any live `NotifierStream`s created via `stream()` and closes the gRPC channel. Prefer the async context manager, or call `await close()` yourself when managing lifecycle manually.
 
 ---
 
@@ -528,7 +528,7 @@ Creates a `NotifierStream`. It does not start the stream; call `start()`, `run_f
 
 **Parameters:**
 - `topics`: topic strings. Use `snapshot.stream_topics()` to get all topics for a system.
-- `max_reconnects`: maximum reconnect attempts per disconnect. `-1` = unlimited (default). `0` = no retries.
+- `max_reconnects`: maximum *consecutive* reconnect attempts — the counter resets after a connection stays healthy, so this bounds retries per disconnect event. `-1` = unlimited (default). `0` = no retries.
 - `reconnect_delay_s`: initial back-off in seconds. Doubles on each attempt, capped at 60 s.
 
 **Returns:** `NotifierStream` instance.

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/docs/reference/hds-entities.md

@@ -142,8 +142,8 @@ The Quilt Dial is a compact circular thermostat (58 mm diameter) that can be wal
 | `id` | `str` | Unique object ID |
 | `space_id` | `str` | Space this Dial controls |
 | `name` | `str` | Display name |
-| `ambient_temperature_c` | `float` | Temperature measured by the Dial's built-in sensor |
-| `raw_thermistor_c` | `float` | Raw uncalibrated thermistor reading |
+| `ambient_temperature_c` | `float \| None` | Temperature measured by the Dial's built-in sensor; `None` when no state reading is available |
+| `raw_thermistor_c` | `float \| None` | Raw uncalibrated thermistor reading; `None` when no state reading is available |
 | `remote_sensor_mode` | `HvacControllerType` | How the Dial's temperature reading influences the space setpoint |
 | `model_sku` | `str \| None` | Hardware model identifier |
 | `serial_number` | `str \| None` | Unit serial number |

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/docs/reference/models.md

@@ -65,7 +65,7 @@ service = UserService(channel)
 ### `NotifierStream`
 
 ```python
-from quilt_hp.services.streaming import NotifierStream
+from quilt_hp import NotifierStream  # also importable from quilt_hp.services.streaming
 
 # metadata_provider returns gRPC call metadata (e.g. auth headers).
 # Obtain a token from your QuiltClient or token store.
@@ -84,10 +84,11 @@ stream = NotifierStream.create(
 
 See [Streaming protocol behavior](../explanation/streaming-protocol.md) for the full state machine, event types, and reconnect behavior.
 
-Callback registration methods:
+Callback registration methods (each returns an *unsubscribe* callable —
+call it to detach the callback without stopping the stream):
 
 ```python
-stream.on_space_update(callback)
+unsub = stream.on_space_update(callback)
 stream.on_indoor_unit_update(callback)
 stream.on_outdoor_unit_update(callback)
 stream.on_controller_update(callback)
@@ -95,9 +96,15 @@ stream.on_qsm_update(callback)
 stream.on_remote_sensor_update(callback)
 stream.on_controller_remote_sensor_update(callback)
 stream.on_software_update_info(callback)
-stream.on_error(callback)
+stream.on_error(callback)       # fatal stream errors
+stream.on_connected(callback)   # fired on every successful (re)connect
+unsub()                         # detach the space callback
 ```
 
+`on_connected` fires on every successful connect and reconnect. Events
+published while disconnected are lost — use it to re-fetch a snapshot and
+close the gap.
+
 Lifecycle methods:
 
 ```python
@@ -158,6 +165,7 @@ snapshot.apply_controller(controller)
 snapshot.apply_qsm(qsm)
 snapshot.apply_remote_sensor(sensor)
 snapshot.apply_controller_remote_sensor(sensor)
+snapshot.apply_software_update_info(info)
 ```
 
 ---
@@ -291,19 +299,28 @@ class IndoorUnitState:
 class OutdoorUnit:
     id: str
     system_id: str
+    space_id: str
+    hvac_state: HVACState
+    model_sku: str | None
     serial_number: str | None
-    model_name: str | None
-    state: OutdoorUnitState
+    firmware_version: str | None
+    firmware_update_info_id: str | None
+    performance_data: OutdoorUnitPerformanceData | None
 ```
 
-#### `OutdoorUnitState`
+#### `OutdoorUnitPerformanceData`
 
 ```python
 @dataclass
-class OutdoorUnitState:
-    updated_at: datetime | None
-    outdoor_temp_c: float | None
-    is_online: bool
+class OutdoorUnitPerformanceData:
+    measurement_interval_s: float
+    energy_measurement_j: float
+    compressor_frequency_hz: float
+    ambient_temperature_c: float
+    coil_temperature_c: float
+    exhaust_temperature_c: float
+    high_pressure_kpa: float
+    low_pressure_kpa: float
 ```
 
 ---
@@ -315,19 +332,31 @@ class OutdoorUnitState:
 class Controller:
     id: str
     system_id: str
+    space_id: str
+    name: str
+    raw_thermistor_c: float | None      # None when no state reading available
+    pcb_temperature_a_c: float | None
+    pcb_temperature_b_c: float | None
+    calibrated_ambient_c: float | None  # exposed as ambient_temperature_c
+    wifi_ssid: str | None
+    wifi_ip: str | None
+    wifi_signal_dbm: int | None
+    wifi_freq_mhz: int | None
+    wifi_last_seen: datetime | None
+    ap_wifi: WifiInfo | None
+    p2p_wifi: WifiInfo | None
+    remote_sensor_mode: RemoteSensorControlMode
+    software_update_info_id: str | None
+    firmware_update_info_id: str | None
     serial_number: str | None
+    model_sku: str | None
     firmware_version: str | None
-    state: ControllerState
+    state_updated_at: datetime | None
+    local_comms_health: LocalCommsHealthStatus
 ```
 
-#### `ControllerState`
-
-```python
-@dataclass
-class ControllerState:
-    updated_at: datetime | None
-    is_online: bool
-```
+Useful properties: `ambient_temperature_c` (→ `calibrated_ambient_c`, `None`
+when no state reading is available), `wifi_band`, `is_online`.
 
 ---
 

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/docs/reference/token-management.md

@@ -223,6 +223,11 @@ class TokenRefreshReason(StrEnum):
 - `TRANSPORT_UNAUTHENTICATED`: The gRPC transport interceptor received `UNAUTHENTICATED` on a unary RPC.
 - `STREAM_UNAUTHENTICATED`: The `NotifierStream` received `UNAUTHENTICATED` and is refreshing before reconnecting.
 
+For the two `*_UNAUTHENTICATED` reasons, `authenticate()` does **not** trust a
+locally-unexpired cached IdToken — the server just rejected it, so a Cognito
+refresh is forced. If the Cognito response contains a rotated `RefreshToken`,
+the new value is persisted to the token store.
+
 ---
 
 ## `RefreshFailureAction`

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/proto/cleaned/quilt_hds.proto

@@ -333,7 +333,7 @@ message IndoorUnitSettings {
 // f1,f2=absent; f3=ledColorCode(varint/uint32), f4=ledColorBrightnessPercent(float),
 // f5=fanSpeedMode(varint), f6=fanSpeedPercent(float), f7=updatedTs(Timestamp),
 // f8,f9=absent; f10=louverMode(varint), f11=louverFixedPosition(float),
-// f12=lightState(varint), f13=lightAnimation(varint).
+// f12=lightAnimation(varint), f13=lightState(varint).
 // NOTE: These are FLAT fields, NOT nested sub-messages.
 message IndoorUnitControls {
   // f1, f2 absent from wire captures
@@ -344,7 +344,7 @@ message IndoorUnitControls {
   google.protobuf.Timestamp updated_ts = 7;
   // f8, f9: uuid-string field confirmed at f9 in captures; purpose TBD
   IndoorUnitLouverMode louver_mode = 10;
-  float louver_fixed_position = 11;        // degrees, used when louver_mode=FIXED
+  float louver_fixed_position = 11;        // position fraction 0.20–1.00 (see LouverAngle.to_wire), used when louver_mode=FIXED; 0.0 = not applicable
   LightAnimation led_animation = 12;       // LED_ANIMATION_FIELD_NUMBER=12; wire-confirmed
   LightState led_state = 13;               // wire-confirmed f13: UNSPECIFIED=0,ON=1,OFF=2
                                            // sent when mobile_led_scheduling_enabled Statsig gate is on;

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quilt-hp-python"
-version = "0.5.3"
+version = "0.5.4"
 description = "Async Python client for Quilt mini-split HVAC systems"
 readme = "README.md"
 license = { file = "LICENSE" }

quilt_hp_python-0.5.4/src/quilt_hp/__init__.py

@@ -0,0 +1,46 @@
+"""quilt_hp — Async Python client for Quilt mini-split HVAC systems."""
+
+from quilt_hp.auth import OtpCallback
+from quilt_hp.client import QuiltClient
+from quilt_hp.const import Environment
+from quilt_hp.exceptions import (
+    QuiltAuthError,
+    QuiltConnectionError,
+    QuiltError,
+    QuiltNotFoundError,
+    QuiltStreamError,
+)
+from quilt_hp.services.streaming import NotifierStream, StreamEvent
+from quilt_hp.tokens import (
+    CachedTokens,
+    LegacyTokenStore,
+    RefreshFailureAction,
+    TokenRefreshContext,
+    TokenRefreshHooks,
+    TokenRefreshPolicy,
+    TokenRefreshReason,
+    TokenStore,
+)
+
+__version__ = "0.5.4"
+
+__all__ = [
+    "CachedTokens",
+    "Environment",
+    "LegacyTokenStore",
+    "NotifierStream",
+    "OtpCallback",
+    "QuiltAuthError",
+    "QuiltClient",
+    "QuiltConnectionError",
+    "QuiltError",
+    "QuiltNotFoundError",
+    "QuiltStreamError",
+    "RefreshFailureAction",
+    "StreamEvent",
+    "TokenRefreshContext",
+    "TokenRefreshHooks",
+    "TokenRefreshPolicy",
+    "TokenRefreshReason",
+    "TokenStore",
+]

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/src/quilt_hp/_paths.py

@@ -20,7 +20,11 @@ _APP = "quilt-hp"
 
 
 def app_config_dir() -> Path:
-    """Return the platform-appropriate config directory, creating if needed."""
+    """Return the platform-appropriate config directory, creating if needed.
+
+    The directory is created user-only (0o700) because it holds cached
+    authentication tokens.
+    """
     d = Path(user_config_dir(_APP))
-    d.mkdir(parents=True, exist_ok=True)
+    d.mkdir(parents=True, exist_ok=True, mode=0o700)
     return d

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/src/quilt_hp/_proto/quilt_hds_pb2.pyi

@@ -1039,7 +1039,7 @@ class IndoorUnitControls(_message.Message):
     f1,f2=absent; f3=ledColorCode(varint/uint32), f4=ledColorBrightnessPercent(float),
     f5=fanSpeedMode(varint), f6=fanSpeedPercent(float), f7=updatedTs(Timestamp),
     f8,f9=absent; f10=louverMode(varint), f11=louverFixedPosition(float),
-    f12=lightState(varint), f13=lightAnimation(varint).
+    f12=lightAnimation(varint), f13=lightState(varint).
     NOTE: These are FLAT fields, NOT nested sub-messages.
     """
 
@@ -1066,7 +1066,7 @@ class IndoorUnitControls(_message.Message):
     louver_mode: Global___IndoorUnitLouverMode.ValueType
     """f8, f9: uuid-string field confirmed at f9 in captures; purpose TBD"""
     louver_fixed_position: _builtins.float
-    """degrees, used when louver_mode=FIXED"""
+    """position fraction 0.20–1.00 (see LouverAngle.to_wire), used when louver_mode=FIXED; 0.0 = not applicable"""
     led_animation: Global___LightAnimation.ValueType
     """LED_ANIMATION_FIELD_NUMBER=12; wire-confirmed"""
     led_state: Global___LightState.ValueType

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/src/quilt_hp/auth.py

@@ -207,12 +207,20 @@ async def authenticate(
 
     Token persistence is delegated to *token_store*. Pass ``None`` for
     purely in-memory/stateless operation (caller handles caching).
+
+    When *refresh_context* indicates the server rejected the current token
+    (transport/stream ``UNAUTHENTICATED``), the locally cached IdToken is
+    not trusted even if unexpired — a refresh is forced.  Otherwise a
+    revoked-but-unexpired token would be returned right back to the caller.
     """
-    now = time.time()
     cached = await _load_tokens(token_store, email) if token_store else None
+    server_rejected_token = refresh_context is not None and refresh_context.reason in (
+        TokenRefreshReason.TRANSPORT_UNAUTHENTICATED,
+        TokenRefreshReason.STREAM_UNAUTHENTICATED,
+    )
 
     # 1. Valid cached IdToken
-    if cached is not None and not cached.is_expired:
+    if cached is not None and not cached.is_expired and not server_rejected_token:
         logger.debug("Using cached token")
         return cached.id_token
 
@@ -239,10 +247,15 @@ async def authenticate(
                 raise
             logger.warning("Refresh failed; falling back to OTP")
         else:
+            # Cognito user pools may rotate the refresh token; persist the
+            # new one or the stored token dies after first use.
+            rotated = result.get("RefreshToken")
             tokens = CachedTokens(
                 id_token=_require_str(result, "IdToken"),
-                refresh_token=cached.refresh_token,
-                expires_at=now + _expires_in_s(result),
+                refresh_token=(
+                    rotated if isinstance(rotated, str) and rotated else cached.refresh_token
+                ),
+                expires_at=time.time() + _expires_in_s(result),
             )
             if token_store:
                 await _save_tokens(token_store, email, tokens)
@@ -260,10 +273,12 @@ async def authenticate(
         )
 
     result = await _do_otp_login(email, otp_callback)
+    # Expiry is measured from token receipt — the user may take minutes to
+    # enter the OTP code.
     tokens = CachedTokens(
         id_token=_require_str(result, "IdToken"),
         refresh_token=_require_str(result, "RefreshToken") if "RefreshToken" in result else "",
-        expires_at=now + _expires_in_s(result),
+        expires_at=time.time() + _expires_in_s(result),
     )
     if token_store:
         await _save_tokens(token_store, email, tokens)

quilt_hp_python-0.5.4/src/quilt_hp/cli/constants.py

@@ -0,0 +1,25 @@
+"""Shared CLI/TUI constants.
+
+Setpoint bounds
+---------------
+Quilt uses 8.0 °C as the STANDBY heat sentinel (``STANDBY_HEAT_SENTINEL_C``
+in ``quilt_hp.models.space``), which is the lowest temperature the system
+will ever hold. 32 °C is a sensible upper bound for a user-facing comfort
+setpoint (the 40 °C STANDBY cool sentinel is a placeholder, not a real
+setpoint). User-supplied heating/cooling setpoints are validated/clamped to
+this range.
+"""
+
+from __future__ import annotations
+
+SETPOINT_MIN_C = 8.0
+SETPOINT_MAX_C = 32.0
+
+# Fallbacks used when a space has no current setpoint to step from.
+DEFAULT_HEAT_SETPOINT_C = 20.0
+DEFAULT_COOL_SETPOINT_C = 26.0
+
+
+def clamp_setpoint_c(value_c: float) -> float:
+    """Clamp a setpoint to the supported [SETPOINT_MIN_C, SETPOINT_MAX_C] range."""
+    return max(SETPOINT_MIN_C, min(SETPOINT_MAX_C, value_c))

{quilt_hp_python-0.5.3 → quilt_hp_python-0.5.4}/src/quilt_hp/cli/main.py

@@ -19,6 +19,7 @@ except ImportError:
     sys.exit(1)
 
 from quilt_hp import __version__
+from quilt_hp.cli.constants import SETPOINT_MAX_C, SETPOINT_MIN_C
 from quilt_hp.cli.settings import SettingsStore
 from quilt_hp.cli.store import FileStore
 from quilt_hp.client import QuiltClient
@@ -39,6 +40,25 @@ class OutputMode(StrEnum):
     JSON = "json"
 
 
+class EnergyPeriod(StrEnum):
+    """Reporting period for the energy command."""
+
+    DAY = "day"
+    WEEK = "week"
+    MONTH = "month"
+
+
+# User-settable HVAC modes (FALLBACK_* are device-side fallback states).
+_SETTABLE_MODES = (
+    HVACMode.COOL,
+    HVACMode.HEAT,
+    HVACMode.AUTO,
+    HVACMode.FAN,
+    HVACMode.DRY,
+    HVACMode.STANDBY,
+)
+
+
 class _EntityWithId(Protocol):
     id: str
 
@@ -415,7 +435,9 @@ def login(
                 console.print(
                     f"[yellow]✉ OTP sent to {challenge_email} — check your email.[/yellow]"
                 )
-                return cast("str", typer.prompt("Enter OTP code")).strip()
+                # typer.prompt blocks on stdin — run it off the event loop.
+                code = await asyncio.to_thread(typer.prompt, "Enter OTP code")
+                return cast("str", code).strip()
 
             await client.login(otp_callback=_prompt_for_otp)
             console.print("[green]✓ Successfully logged in![/green]")
@@ -647,8 +669,12 @@ def presets(
             console.print("\n[bold]═══ Comfort Settings ═══[/bold]")
             for cs in settings:
                 mode = cs.hvac_mode.name
-                heat = f"{cs.heating_setpoint_c:.1f}°C" if cs.heating_setpoint_c else "--"
-                cool = f"{cs.cooling_setpoint_c:.1f}°C" if cs.cooling_setpoint_c else "--"
+                heat = (
+                    f"{cs.heating_setpoint_c:.1f}°C" if cs.heating_setpoint_c is not None else "--"
+                )
+                cool = (
+                    f"{cs.cooling_setpoint_c:.1f}°C" if cs.cooling_setpoint_c is not None else "--"
+                )
                 fan = cs.fan_speed.name
                 console.print(f"\n  [cyan]{cs.name}[/cyan] ({cs.type.name})")
                 console.print(f"    Mode: {mode}  Heat: {heat}  Cool: {cool}  Fan: {fan}")
@@ -701,7 +727,10 @@ def schedules(
 def energy(
     email: str | None = typer.Option(None, envvar="QUILT_EMAIL", help="Quilt account email"),
     home: str | None = typer.Option(None, help="Specific home name to connect to"),
-    period: str = typer.Option("day", help="Time period: day, week, month"),
+    period: EnergyPeriod = typer.Option(  # noqa: B008
+        EnergyPeriod.DAY,
+        help="Time period: day, week, month",
+    ),
 ) -> None:
     """Show energy consumption metrics."""
     email, home = _resolve(email, home)
@@ -716,12 +745,12 @@ def energy(
             now = datetime.now(tz=zoneinfo.ZoneInfo(snapshot.timezone or "UTC"))
             start = now.replace(hour=0, minute=0, second=0, microsecond=0)
 
-            if period == "day":
+            if period == EnergyPeriod.DAY:
                 end = start + timedelta(days=1) - timedelta(seconds=1)
-            elif period == "week":
+            elif period == EnergyPeriod.WEEK:
                 start = start - timedelta(days=start.weekday())
                 end = start + timedelta(weeks=1) - timedelta(seconds=1)
-            else:  # month
+            else:  # EnergyPeriod.MONTH
                 start = start.replace(day=1)
                 if start.month == 12:
                     end = start.replace(year=start.year + 1, month=1) - timedelta(seconds=1)
@@ -733,7 +762,7 @@ def energy(
             console.print(f"\n  [bold][{period.upper()}][/bold] {header}\n")
             for sm in metrics:
                 name = name_by_id.get(sm.space_id, sm.space_id[:8])
-                total = getattr(sm, "total_kwh", 0)
+                total = sm.total_kwh
                 if total == 0:
                     continue
                 console.print(f"  {name:<22}  total={total:.3f} kWh")
@@ -745,14 +774,42 @@ def energy(
 def set_space(
     space_name: str = typer.Argument(..., help="Exact name of the room to update"),
     mode: str | None = typer.Option(None, help="HVAC mode: COOL, HEAT, AUTO, FAN, DRY, STANDBY"),
-    heat: float | None = typer.Option(None, help="Heating setpoint in °C"),
-    cool: float | None = typer.Option(None, help="Cooling setpoint in °C"),
+    heat: float | None = typer.Option(
+        None,
+        min=SETPOINT_MIN_C,
+        max=SETPOINT_MAX_C,
+        help=f"Heating setpoint in °C ({SETPOINT_MIN_C:.0f}–{SETPOINT_MAX_C:.0f})",
+    ),
+    cool: float | None = typer.Option(
+        None,
+        min=SETPOINT_MIN_C,
+        max=SETPOINT_MAX_C,
+        help=f"Cooling setpoint in °C ({SETPOINT_MIN_C:.0f}–{SETPOINT_MAX_C:.0f})",
+    ),
     email: str | None = typer.Option(None, envvar="QUILT_EMAIL", help="Quilt account email"),
     home: str | None = typer.Option(None, help="Specific home name to connect to"),
 ) -> None:
     """Update HVAC mode and setpoints for a room."""
+    if mode is None and heat is None and cool is None:
+        console.print(
+            "[red]Nothing to update:[/red] provide at least one of --mode, --heat, --cool."
+        )
+        raise typer.Exit(1)
+
     email, home = _resolve(email, home)
 
+    if mode:
+        try:
+            hvac_mode: HVACMode | None = HVACMode[mode.upper()]
+            if hvac_mode not in _SETTABLE_MODES:
+                raise KeyError(mode)
+        except KeyError:
+            valid = ", ".join(m.name.lower() for m in _SETTABLE_MODES)
+            console.print(f"[red]Invalid mode {mode!r}. Valid: {valid}[/red]")
+            raise typer.Exit(1) from None
+    else:
+        hvac_mode = None
+
     async def _set() -> None:
         async with _client_snapshot(email, home) as (client, snap):
             space = next(
@@ -763,16 +820,6 @@ def set_space(
                 console.print(f"[red]Room {space_name!r} not found.[/red]")
                 raise typer.Exit(1)
 
-            if mode:
-                try:
-                    hvac_mode: HVACMode | None = HVACMode[mode.upper()]
-                except KeyError:
-                    valid = ", ".join(m.name.lower() for m in HVACMode if m.value)
-                    console.print(f"[red]Invalid mode {mode!r}. Valid: {valid}[/red]")
-                    raise typer.Exit(1) from None
-            else:
-                hvac_mode = None
-
             await client.set_space(
                 space.id,
                 mode=hvac_mode,