plenum-failure-archaeology

name

plenum-failure-archaeology

description

The chronicle of every settled battle in Plenum (smart-thermostat-with-vents) — major investigations, dead ends, rejected approaches, and reverts, each as symptom → root cause → evidence → fix → status. Load when you suspect a bug was seen before, when someone proposes re-fixing or weakening something (deadband in at-target, frontend toStorage on payloads, default-mapped MCP port, per-selector screenshot masks), when you need the incident behind a guard/test name, or before filing an issue that might duplicate #26–#369 history. NOT for live triage of a new symptom (use plenum-debugging-playbook) or for the invariant statements themselves (plenum-architecture-contract).

Plenum Failure Archaeology

Every major battle this project has fought, organized by campaign, chronological within each. Purpose: nobody re-fights a settled war, and nobody "fixes" something that is a deliberate decision. Each entry is symptom → root cause → evidence → fix → status, with the guard or test that now pins the behavior named exactly as it exists in the repo (verified 2026-07-04, v0.22.1).

When NOT to use this skill:

• You have a live symptom to diagnose now → plenum-debugging-playbook.
• You want the invariant/contract itself (°F storage, write boundary) → plenum-architecture-contract (the #231 contract is owned there; only the incident story lives here).
• You are about to make a change and need the gates → plenum-change-control.
• You need the HVAC physics behind a guard (short-cycling, dead-heading, delta math) → hvac-zoning-reference.

Reading a status tag:

• Settled — do not reopen: root-caused, fixed, and pinned by a named guard/test. Re-proposing the rejected alternative is a regression, not an idea.
• Partially addressed — see #N: the acute bug is fixed; a broader follow-up is tracked in an open issue.

Jargon used once: golden = committed reference screenshot for visual regression; hold = the min-runtime phase where a finished cycle is kept running to satisfy min_cycle_runtime_min; write boundary = the backend POST/PUT/PATCH handlers where display-unit temps become °F.

---

Campaign 1 — Early engine correctness era (v0.4–v0.7, issues #26–#86)

The engine's first months in a real house. Theme: control decisions derived from live HA state at the wrong moment instead of from persisted intent.

#26 — vents never closed on heat_cool thermostats. Symptom: 2–3 h cycles, zero close_cover calls, rooms blowing past target. Root cause: _read_hvac_mode() fell back to "heating" when hvac_action="idle" — and the HVAC goes idle exactly when the room reaches target, so the at-target comparison inverted at the only moment it mattered. Fix: cycle direction is locked at cycle start (_cycle_mode), never re-read mid-cycle from hvac_action. Same issue: UTC timestamps rendered as local (frontend now appends "Z" and converts). Settled — do not reopen.

#29 — heat/cool oscillation at cycle boundaries. After #26's fix made cycles terminate, each new cycle picked its direction from live hvac_action, which reflects post-termination drift → cool cycle, heat cycle, cool cycle, forever. Fix: _infer_mode_from_room_temps() — direction comes from room temps vs targets; all-rooms-in-deadband returns "off" (no cycle). Settled — never derive cycle direction from hvac_action.

#32 — full engine audit #1. Decisions that still stand: every vent decision writes to the event log regardless of dev mode; setpoint calls pass hvac_mode explicitly (the heat_cool inference path was eliminated); cycles end by setting setpoint = ambient in the cycle's own mode; min_setpoint/max_setpoint were repurposed from setpoint-clamps into the comfort-envelope bounds (clamping ambient resets had prevented HVAC from stopping). Settled.

#38 — engine heated a 74 °F room toward a 72 °F target. Root causes: rooms with unavailable sensors were silently skipped from the mode vote, and nothing cross-checked the vote against the thermostat's own ambient. Fix: thermostat-ambient fallback when room sensors are unreadable + an ambient sanity check on the inferred mode. Settled.

#48 — full engine audit #2. Three fixes: (1) setpoint anchored to thermostat ambient (min(setpoint, ambient − overshoot) for cooling) so a hallway probe cooler than the bedrooms can't make the HVAC think it's already satisfied; (2) explicit mode guard — unexpected hvac_mode values log an error instead of silently defaulting to heat; (3) mixed heat/cool votes no longer drag losing-side rooms into the wrong cycle (_filter_rooms_for_mode). Settled.

#51 — cycles stuck "Active" after system stop. _abort_cycle cleared in-memory state even when db.close_cycle_log failed, orphaning ended_at IS NULL rows. Fix: close-ordering hardened + safety nets (close_open_cycle_logs at cycle start, on restore, and in the scheduler's _reset_and_reevaluate). Settled.

#54 — dev-mode cycles lingered ACTIVE across toggles. Only set_system_enabled(False) cleaned up; the other three system/dev transitions did nothing (engine gate is system_enabled OR dev_mode, so a fast dev-off→system-on flip was never observed disabled). Fix: all four transitions run Scheduler._reset_and_reevaluate() (force-abort every engine, close orphans, immediate re-tick) — see scheduler.py calls at the enabled/dev-mode setters. Related: #35 made system-off abort immediate rather than waiting ≤60 s for the next tick. Settled.

#67 — idle-room vents left open when a new cycle starts. _terminate_cycle re-opens ALL zone vents (correct idle state); the next cycle only opened active-room vents and never closed the rest. Fix: _close_idle_room_vents() at fresh cycle start; pinned by tests/integration/test_idle_room_vents_closed_on_cycle_start.py and test_idle_vents_closed_on_restore.py. Settled.

#70 — cycles ended at the deadband boundary (72 °F target "reached" at 73 °F). Deliberate design decision, not a bug fix: _is_at_target is a pure target comparison — no deadband. Deadband gates cycle start/join only. Do not "optimize" by re-adding deadband to the completion check; that re-introduces #70. Settled — do not reopen.

#82 — "Closed idle room X vents" logged, vents physically still open. Two call sites bypassed the control_method dispatcher and called close_cover directly — a no-op for set_position/set_tilt_position/ toggle vents (Flair's common config, introduced by #57). Fix: all close paths route through VentController._invoke_close; reconciler also watches idle-room vents during RUNNING. Pinned by tests/integration/test_idle_vent_close_dispatch.py and test_vent_types.py. Settled — never call ha.close_cover directly.

#86 — cycle never terminated after all rooms reached target. After a vent closes, the room drifts back past target; the elif not at_target branch in _monitor_rooms had no vent_closed_at guard, so post-closure drift blocked all_at_target forever (48 min of all-vents-closed runtime observed). Fix: a room whose vent is already closed is "served" — its drift cannot block termination (vent_closed_at is None guards throughout _monitor_rooms). Settled.

Also from this era: #65 — datetime.now() (local) in room_manager mixed with utcnow() everywhere else shifted presence-holdover display; everything is naive-UTC now. Settled.

---

Campaign 2 — The unit-system saga (#123 → #231 → parity system)

The project's costliest bug class. The invariant that resulted (°F-only storage, conversion at exactly one boundary) is stated in plenum-architecture-contract; this is how it was learned.

#123 — the feature. All temps stored °F at 2 dp (no migration); unit priority: TEMPERATURE_UNIT env → HA /api/config → last-known DB value; unit changes require restart + UnitChangeBanner ack. Settled design.

#231 — the double conversion (landmark). Symptom: typing 16 °C for min_setpoint stored 141.44 °F (16→60.8→141.44). Root cause: frontend called toStorage() on the outgoing payload AND the backend's _to_f() converted again. Both sides' tests passed because each asserted its own (contradictory) contract — the frontend test expected a pre-converted body, the backend test expected a display-unit body. Fix: conversion belongs to the backend only; frontend forms hold display units and POST them raw. Guards created: the 3-file TEMPERATURE_FIELDS parity system (backend/api/routes.py dict ↔ e2e/tests/temperature-fields.ts ↔ // @covers: tags in e2e/tests/temperature-units.spec.ts) enforced by backend/tests/test_temperature_field_parity.py, plus the dual-unit (F/C) round-trip E2E matrix — the only test that would have caught it. Settled — do not reopen; never call toStorage/toStorageDelta on an outgoing payload.

The °C sibling bugs (pre-launch audit, all HIGH/MEDIUM):

• #280 — the engine read climate-entity temps raw and sent °F setpoints to metric HA (which reads them as °C → clamps to ~35 °C = runaway heating hazard). Tests masked it by mocking pre-converted values. Fix: HAClient._setpoint_to_native() converts outgoing setpoints/ranges; climate reads normalized like sensors (ha_client.py, comments cite "Issue #280"). Settled.
• #281 — auto-detect could never return Celsius: HA returns unit_system as an object ({"temperature": "°C", ...}), the code compared == "metric"; AND run.sh defaulted blank to "F" which the scheduler treats as a hard override lock. Both fixed (ha_client.py reads unit_system["temperature"]; run.sh defaults blank → auto). Unit-test fixtures had mocked the wrong shape — lesson: mock the real payload shape. Settled.
• #284 — MCP write tools bypassed the write-boundary conversion entirely ("set the bedroom to 21" in a °C home stored 21 °F ≈ −6 °C). Fix: MCP tools convert via the shared helpers (mcp_tools/_units.py, units.to_f). Settled.
• #288 — banner dismiss was undone every 60 s tick; and the banner stuck after the restart that applied the change. Fix: ack_unit_change records the acknowledged HA unit; startup clears the flag when units match. Settled.
• #291/#292 — charts applied the absolute °F→°C conversion to deltas: a 2 °F overshoot rendered "-16.7 °C"; degree-minutes were mislabeled ×1.8. This is CLAUDE.md pitfall #4 exactly (absolute conversion subtracts 32; deltas must not). Fixed in commit e3a9473. Settled.
• #293 — buildUnitContext(unit) rebuilt every render → new function identities → form-reset effects fired on unrelated re-renders, discarding edits and even regressing saved values. Fix: useMemo(() => buildUnitContext(unit), [unit]) (App.tsx). Settled.

Consolidation (#251): the four helpers moved from routes.py into smart_vent/backend/units.py (to_f, delta_to_f, from_f, from_f_delta), also used by HA ingest and MCP. (CLAUDE.md said routes.py until corrected on 2026-07-05 — trust units.py.)

Sentinel lesson (.jules/sentinel.md, 2026-05): setpoint bounds validation must run on the normalized °F value (40–90 °F), not the raw display input — bounds on an unknown-unit raw value are meaningless. Pinned by tests/integration/test_sentinel_validation.py. Settled.

---

Campaign 3 — Safety hardening wave (#208–#213, #267, #367)

A deliberate pre-launch review: "which protective interlocks are missing or untested?" Every guard below is a one-way ratchet — never weaken one to fix a comfort complaint (inferred house rule; consistent with every fix in this campaign).

#208 — no short-cycle protection. Grep for min_runtime|lockout|compressor returned zero hits; cycles could start/stop within one tick. Fix: ThermostatConfig.min_cycle_runtime_min / min_cycle_offtime_min — hold a finished cycle open until minimum runtime; refuse restarts during off-time lockout. Pinned by tests/integration/test_short_cycle_protection.py. Follow-up #215: the "trigger changed" teardown tore down a healthy cycle for a same-direction target change (68→72 mid-heat = full furnace stop/start, then the new lockout blocked reheat). Fix: update in place when direction is unchanged; teardown reserved for direction flips (see the #215 in-place update comments in cycle_engine.py, pinned by test_trigger_change_characterization.py). Settled.

#209 — AC could run in cold weather. Outdoor temp was plumbed but used only for diagnostics; a mixed-vote tie ("ties go to cooling") could start a compressor at 40 °F outside (coil icing / slugging). Fix: cooling_lockout_below_f (nullable), enforced at mode-inference; pinned by tests/integration/test_outdoor_cooling_lockout.py. Settled.

#210 — the last-vent bypass could dead-head the air handler. The deliberate min_open_vents bypass for the final closing vent must always be paired with immediate termination + reopen. Fix/pin: min_open_vents_fraction (default 0.333 of zone vents) and tests/integration/test_airflow_floor_bypass.py (ordered close→reopen assertions). Settled.

#211 — stale sensors drove control. Battery Zigbee sensors drop off the mesh but keep their last numeric state; a 3-h-old "70 °F" closed vents on a 80 °F room. Fix: get_numeric_state freshness check against last_updated (missing timestamp = infinitely stale), stale-sensor warning events + StaleSensorsBanner; pinned by tests/integration/test_sensor_staleness.py. Settled.

#212 — the cycle timeout had no end-to-end test. "A protective interlock with no test is one that can silently regress." Fixed with tests/integration/test_cycle_timeout.py (over-timeout terminates with ended_reason="timeout", under-timeout does not). Settled.

#213 — unsafe defaults. max_vent_closed_min=0 and reconciliation_interval_min=0 shipped OFF. Principle adopted: defaults must be thermodynamically sound; don't rely on the user. Defaults now non-zero in models.py and pinned by tests. Settled.

#267 — unavailable thermostat suspended ALL safety monitoring. _do_tick returned early on unavailability, skipping timeout, the closed-vent watchdog, and reconciliation — HVAC running, vents closed, forever. The docstring claimed an unavailability abort existed; the code path didn't (_abort_cycle(safe_close=True) was dead code). Fix: tolerate transient blips, abort after unavailable_abort_after_min (default 5) consecutive unavailable ticks, reopen vents (cover entities are independent of the climate entity). Pinned by tests/integration/test_thermostat_health.py. Settled.

#367/#368 — comfort envelope not enforced with zero active rooms (production incident, 2026-06-28). After a vacation hold expired with no room demand, the upstairs zone sat at 81 °F against a 77 °F max_setpoint for 2+ hours: the cap lived only in _suppression_vote(), reachable only from the active-room path, and _do_tick exits early on active_rooms=0. Fix is two-layer: _add_safety_rooms pulls any sensor-breaching room into the cycle with source="safety" (target one deadband inside the bound, for hysteresis), plus a thermostat-ambient backstop for zones with no readable room sensor. Pinned by tests/integration/test_safety_room_protection.py and test_safety_setpoint_backstop.py. Settled.

---

Campaign 4 — Min-runtime hold / overflow conditioning arc (#237 → #305)

#237 — vent thrashing during the hold (+ the overflow idea). When rooms hit target before minimum runtime, _enter_min_runtime_hold() re-opened vents once — but the next _monitor_rooms tick had no idea a hold was in progress and closed them again: open→close→open against a running compressor. Fix: the hold became persisted state (CycleLog.in_min_runtime_hold, models.py) that gates the close loop. Same issue birthed overflow conditioning: surplus runtime is dumped into non-active rooms via three candidate tiers — full design in docs/overflow-conditioning.md (the doc of record; don't re-derive tiers from code). Settled.

#254 — overflow rooms were invisible in cycle history. Their temps were buried in vent-event reason strings. Fix: room_cycle_states.role discriminator ('active' | 'overflow'; note 'safety' is a source on ActiveRoom, not a role — cycle_engine.py:3013), one collapsed row per overflow room, surfaced in the Logs cycle detail. Settled.

#268 — the anti-thrash gate had zero real coverage (test-quality lesson). test_hold_gate_skips_close_loop passed via the wrong branch — its setup triggered hold-entry, so the continuation gate never executed; coverage was green while the #237 guard was unguarded. Fix: a test where a room drifts off target during the hold. Lesson: verify which branch a safety test actually executes (coverage line data, not test names). Companion #269 covered the untested in-tick system-disabled/vacation abort backstops. Settled.

#300 — ON CONFLICT dropped role/joined_at. An overflow room promoted to active silently kept role='overflow' (excluded from metrics, mislabeled in UI); the restore path leaked _overflow_room_states into the next cycle. Fix: upsert sets role=excluded.role, joined_at=COALESCE(existing, excluded) (db.py); pinned by tests/test_room_cycle_state_upsert.py. Settled.

#305 — overflow candidate selection ignored deadband_override (the per-room deadband from #277). Fix: _effective_deadband(room, tc.deadband) applied inside the candidate loop (room_manager.py). Settled.

---

Campaign 5 — The pre-launch audit wave (#280–#305, ~25 latent bugs)

One systematic front-end + back-end logic audit (2026-06) filed ~25 issues in a week; all are fixed. The °C ones (#280/#281/#284/#288/#291/#292/#293) are in Campaign 2; #300/#305 in Campaign 4. The rest, one line each — all settled unless noted:

#	Symptom → fix (guard)
#282	MCP server crashed at startup: @server.tool() doesn't exist on the low-level mcp.server.Server; coverage exclusions meant no test ever imported it → rewritten on FastMCP (mcp_server.py), smoke-tested by tests/test_mcp_server.py. Lesson: a coverage-excluded module is an untested module.
#283	connectWS reconnected after intentional close → zombie sockets, N+1 duplicated feed handlers → liveness flag in the closure (api.ts, let closed = false).
#285	Deleting a thermostat's last room dropped the engine mid-cycle, leaving HVAC at the overshoot setpoint forever → force_abort(reason="thermostat removed") + close logs before del (scheduler.py).
#286	_tick_engine pre-tick DB calls sat outside the try; a locked DB silently killed a zone with zero log output → whole body inside try.
#287	Presence was edge-triggered only; mmWave sensors holding continuous on lost their holdover and the occupied room went idle → holdover refreshed from current sensor state each tick (tests/integration/test_presence_holdover_refresh.py).
#289	Per-room time-to-target averaged cycles outside the date range (filter in LEFT JOIN ON, CASE didn't gate on join success) → cl.id IS NOT NULL gate (db.py).
#290	Overshoot histogram mixed thermostat-level samples into every room's extremes → per-(cycle,room) fallback only when no room-level samples.
#294	Vacation modal datetime-local min computed in UTC blocked valid times west of UTC → local-component string via toDatetimeLocalString (VacationModeModal.tsx).
#295	Several numeric config fields stored unvalidated (a string cycle_timeout_hours then crashed every tick — silently, per #286) → _validate_thermostat_numeric() in routes.py. Note: @request_schema decorators remain documentation-only by design; handlers self-validate.
#296	Idle in-deadband engine re-sent setpoint=ambient every 60 s (cloud-thermostat rate-limit hazard) → skip within _SETPOINT_DRIFT_TOLERANCE_F (tests/integration/test_idle_setpoint_churn.py).
#297	HA WS client busy-looped on clean close and could hang forever in an unguarded handshake → min reconnect delay, heartbeat=, wait_for on handshake (ha_client.py).
#298	/api/backup leaked a full DB temp copy on every download (disk + data exposure) → temp file unlinked on the success path too (routes.py).
#299	event_log trim off-by-one deleted the oldest row even under the cap (id <= → id <), pinned by tests/test_event_log_trim.py.
#301	Vent timeline printed naive-UTC verbatim → localized (commit 6a81447).
#302	Offset pagination duplicated feed rows as new events arrived → de-dupe by seen ids on merge (Logs.tsx).
#303	Dev-mode "Clear" repopulated 3 s later → cleared-before-id watermark (DevMode.tsx).
#304	Fire-and-forget startup tasks held only by weak refs (GC could eat unit resolution) → Scheduler._bg_tasks strong-ref set with done-callback discard.

Meta-lesson from this wave: the audit found bugs precisely where tests mocked the convenient shape (#280, #281, #282) or where coverage was excluded/green-but-wrong (#268, #282). When auditing, start from "what does the real payload/state look like."

---

Campaign 6 — E2E / visual-regression campaign (#175 → #182 → #369)

#175 introduced Playwright + docker-compose visual regression with goldens committed to git. It promptly proved flaky beyond rescue by masking (#182): live temps, countdowns, engine feeds, and Recharts float jitter differed between the update pass and the verify pass; per-selector masks were whack-a-mole. The suite was disabled (PR #180) for months — the dead end to remember. The rescue (these became the project's hard E2E rules, since restated in CLAUDE.md and superseded in mechanism by #366 below):

• Determinism by construction: isCI (VITE_APP_VERSION === "CI") + <Frozen> in frontend/src/ci.tsx — freeze anything that changes between two renders of the same fixture; never freeze static fixture values. One import.meta.env branch, tested both ways in ci.test.tsx.
• The 158 °F golden bug: HA YAML with no unit_system defaults to metric, so a target_temp: 70 fixture was 70 °C and Plenum's correct normalization displayed 158 °F. Fix: the HA fixture pins unit_system: us_customary; the matrix varies only Plenum's display unit. Dual-unit goldens (-Fahrenheit-/-Celsius- filenames) catch conversion regressions in both directions.
• Golden auto-commit needed max-parallel: 1 (legs pushed to the same ref) and a forced checkout — until #366 replaced that design with parallel legs
  • a single fan-in commit job; high-DPI mobile needs a per-spec maxDiffPixels bump (metrics: 800) instead of masks.

#329 — a distinct flake: global-setup.ts room-creation clicks raced a list re-render ("element detached from the DOM"), reddening unrelated PRs (#315/#324/#326). Fixed alongside the #330-wave CI work (commit fbe9801). Lesson: not every red E2E is #182 — check where it failed first.

#366 moved the visual-regression suite into container-ci.yml (parallel goldens-F/goldens-C legs + a commit-goldens fan-in job) and deleted e2e.yml. (CLAUDE.md referenced the standalone e2e.yml until corrected on 2026-07-05 — the suite lives in container-ci.yml.)

#369 — the fan-in job couldn't push regenerated goldens: actions/checkout leaves detached HEAD, so git push origin "$BRANCH" had no local refspec after the rebase. Fix: git push origin HEAD:"$BRANCH" (commit c26d395). Settled — if golden commits fail with "src refspec … does not match any", this is it; don't re-invent the checkout dance.

---

Campaign 7 — CI build-once consolidation (#5, #43, #141, #330–#337)

#5 (early): PR builds and GHCR pushes split into separate jobs so PR runs have no packages: write at all — structural enforcement over a runtime if:. Settled principle: permissions, not conditionals.

#43: release-PR contributor lookup leaked a GitHub 422 JSON error body verbatim into CHANGELOG/PR bodies — a three-bug chain (+/[ in bot emails; gh api writes 4xx to stdout; $(A || B) captures A's stdout anyway). Fix in release-pr.yml: skip bot emails, gate on exit code with if RAW=$(...), jq '// empty'. Settled — reuse that exact pattern for any gh api in a workflow.

#141: nine releases in one day (v0.9.4–v0.9.12) from a merge→break→hotfix-direct-to-main loop. Outcome: branch protection, /api/healthz + real smoke test, single-source deps in pyproject.toml, RELEASE.md. (The validate-release.yml manual dry-run workflow was also added at the time, but was removed 2026-07 once container-ci.yml grew its own required, automatic checks on release PRs — everything the dry-run caught was already caught there.) Settled process (details owned by plenum-ci-and-release).

#330–#333 → #334: the same image was built ~4× per PR (one under QEMU arm64) with no shared cache. Consolidated into container-ci.yml's single build job pushing ghcr.io/<repo>:ci-<sha>, reused by smoke, round-trip F/C, and (post-#366) the visual legs. #337 follow-ups: fork-PR artifact handoff (docker save/load — fork tokens can't push), nightly ci-* tag pruning (.github/workflows/ci-image-cleanup.yml), and release PRs building the real :<version> once in container-ci (required check is now Build (PR validation), not the old docker.yml job). Settled.

---

Campaign 8 — Infra & security

Security alert #4 — CWE-209 exception detail in API responses. Route handlers embedded str(exc) in error bodies. Rule (now in CLAUDE.md, and the top of every reviewer's checklist): log.exception("…context…") then a generic error("Failed to <action>", status=5xx) — never {exc} in a response. tests/integration/test_security.py exists; grep before merging any new except in routes.py. Settled — this is a hard rule, not a style preference.

#298 / #295 (see Campaign 5 table) were the other security-adjacent audit finds: backup temp-file data left on disk, and unvalidated numeric config inputs.

MCP (#372/#375, shipped v0.22.0): MCP now runs over HTTP on port 9099 behind a settings toggle (503 until enabled). Its earlier failures (#282 startup crash, #284 unit bypass) are settled above. Authentication for the web UI and MCP endpoint is the big open problem — see open issue #373 and plenum-auth-campaign. Partially addressed.

---

Campaign 9 — Notable reverts

Commit c65d35d — "Revert MCP port to null" (#387, reverting #385, 2026-07-01). #385 had default-mapped 9099/tcp: 9099 in config.yaml because the port row wasn't appearing in existing installs' HA Configuration → Network section. The revert's finding: the row was missing only because HA Supervisor re-reads an add-on's config.yaml (including ports) when the version changes on Update — no default mapping needed; a null mapping still shows an empty, fillable row after the next version bump. So the port is back to null (unpublished by default) and docs/mcp.md documents the update-to-see-the-row behavior. Given the MCP endpoint is unauthenticated (open #373), not auto-publishing it is also the safer default (that rationale is inferred; the documented one is the Supervisor behavior). Settled — do not re-add a default host mapping for 9099/tcp; if a user reports "no 9099/tcp row", the answer is "update the add-on", not a config.yaml change.

Honorable mention: min_setpoint/max_setpoint's original meaning (overshoot-setpoint clamps) was deliberately abandoned in #32 and the fields repurposed as the comfort envelope — any proposal to clamp the commanded setpoint with them again is re-fighting #32.

---

Campaign 10 — Platform mishaps (Home Assistant quirks)

#74 — blank screen under HA ingress. Ingress serves at /api/hassio_ingress/<TOKEN>/; React Router had no basename, so no route matched. api.ts already computed the ingress base — the router didn't. Fix: same regex feeds <BrowserRouter basename=…> (main.tsx). Settled — any new absolute frontend path must survive the ingress prefix.

#92 — add-on data "missing" on HAOS. Docs pointed at paths that don't exist; the real bind mount is /mnt/data/supervisor/addons/data/<repo_id>_<slug>/, invisible to the Samba addon_configs share because the manifest only mapped data. Fix: config.yaml adds addon_config:rw with DATA_DIR=/config (config.yaml:43, run.sh:82) + a one-shot run.sh migration; docs corrected with docker inspect recipes (docs/backup-restore.md). Settled.

#89 — rename to Plenum. DB migrated flair.db → app.db via one-shot startup rename; the add-on slug stayed flair_replacement on purpose (changing it orphans every install's data dir) and the GitHub repo name stayed. Settled — do not "clean up" the slug.

---

Provenance and maintenance

Mined 2026-07-04 from the closed-issue corpus (48 bug + 58 feature bodies), the git log, repo CLAUDE.md, and direct code verification at v0.22.1. Guard/test names above were verified to exist on disk on that date. Volatile facts and how to re-check them:

• Guard tests still present: ls smart_vent/backend/tests/{test_temperature_field_parity.py,test_event_log_trim.py,test_room_cycle_state_upsert.py} smart_vent/backend/tests/integration/{test_short_cycle_protection.py,test_cycle_timeout.py,test_sensor_staleness.py,test_thermostat_health.py,test_safety_room_protection.py,test_safety_setpoint_backstop.py,test_airflow_floor_bypass.py,test_outdoor_cooling_lockout.py,test_presence_holdover_refresh.py,test_sentinel_validation.py,test_idle_setpoint_churn.py}
• Conversion helpers live in smart_vent/backend/units.py (post-#251): grep -n "def to_f" smart_vent/backend/units.py
• Visual-regression E2E lives inside .github/workflows/container-ci.yml (post-#366; no e2e.yml): ls .github/workflows/
• MCP port default is 9099/tcp: null (post-c65d35d): grep -n "9099" smart_vent/config.yaml
• #367 backstop still wired: grep -n "_add_safety_rooms" smart_vent/backend/engine/cycle_engine.py
• Open issues referenced as "partially addressed": #373 (auth), #21 (versioned DB migrations), #23, #25, #173 — re-check with gh issue list --state open before citing them as still open.
• The local clone is shallow (~51 commits as of 2026-07-04); hashes cited (c65d35d, c26d395, e3a9473, 6a81447, fbe9801, bd560de, a0e9d04) are within it; older incidents are cited by issue number only.