test(e2e): measure _POLL_CADENCE p50/p99 to validate or retune (closes #1389)

[Patch76]

What does this PR do?

Closes #1389.

Pre-committed measurement protocol for the post-#1384 _POLL_CADENCE = (0.1, 1.0, 4.9) shape plus the Boy-Scout retune that the decision rule landed on:

• _POLL_CADENCE retune: (0.1, 1.0, 4.9) → (0.025, 1.0, 4.975). Same 3-attempt × 6.0s budget; first-poll pulled to a 5× cushion above the measured ~4 ms HA-Core entity-registration latency. Decision rule on two E2E runs against 65e6d89: p50 ≥ 100 ms (the prior first-poll sleep was the floor of every sample) → RETUNE NEEDED.

• Production instrumentation (src/ha_mcp/client/rest_client.py): _poll_for_automation_entity captures elapsed time from function entry to the first successful get_states() match and emits entity-registration-elapsed: %.1fms (unique_id=..., entity_id=...) at DEBUG level. One time.monotonic() pair per registration.

• E2E measurement test (tests/src/e2e/workflows/automation/test_poll_cadence_measurement.py): TestPollCadenceMeasurement1389 creates N=10 automations cold-start, captures the DEBUG records via caplog.at_level, computes p50 / p90 / worst, feeds them to a record_poll_cadence_measurement() helper in the root e2e conftest. (At N=10 the 99th-percentile index collapses to p90's bucket, so the headline metric is named worst for what it actually measures.)

• Terminal-summary plumbing (tests/src/e2e/conftest.py): mirrors the readiness-gate-timings pattern — pytest_terminal_summary renders the #1389 _POLL_CADENCE measurement section with [POLL_CADENCE_1389] lines outside the per-worker capture buffer.

HAOS proxy-header flake: addressed independently on master via #1402 (merged 2026-05-21 21:43 UTC; _wait_addon_running guard in test_manage_addon_modes.py). Not duplicated in this PR — branch rebased onto master so #1402's fix is now live on the PR's CI lane.

External-only marker on the measurement test: caplog only captures DEBUG records emitted in pytest's own process; on the HAOS-inaddon tier the rest_client lives in the addon's separate process and the records never reach caplog. Marked external_only so the test skips inaddon instead of false-negative-asserting.

Report-only on percentiles: no threshold assert on the measurement itself. CI latency variance from parallel pytest-xdist workers sharing one HA testcontainer would make a strict threshold-assert flaky. The decision rule is applied to the reported numbers via PR comment — VERDICT line in the output is machine-greppable.

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

(Production-code changes: the _POLL_CADENCE retune + the one instrumentation line in _poll_for_automation_entity. Everything else is the measurement test, conftest plumbing, and the HAOS readiness guard.)

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

Local: 44 existing test_rest_client_automations.py + test_helper_classifier.py unit tests pass (3 pinned the old cadence — values updated in lockstep). Ruff + mypy clean. The new E2E test cannot be run locally (no Docker daemon in this environment) — measurement set lands in CI's E2E Validation job logs as the [POLL_CADENCE_1389] section.

Checklist

• I have updated documentation if needed

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request implements a measurement protocol to validate the effectiveness of the current _POLL_CADENCE configuration. By adding lightweight instrumentation to the automation registration process and introducing a dedicated E2E test, the changes allow for empirical analysis of registration latency. The collected data will be used to determine if the current polling strategy is optimal or if further tuning is required.

Highlights

• Production Instrumentation: Added low-overhead timing instrumentation to the _poll_for_automation_entity method in rest_client.py to capture registration latency.
• E2E Measurement Test: Introduced a new end-to-end test that performs cold-start automation creation, calculates p50/p90/p99 latency metrics, and outputs a machine-readable verdict.
• Reporting Strategy: Implemented a report-only testing approach that avoids CI flakiness by logging performance data for manual review rather than enforcing strict gate thresholds.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds latency instrumentation to the REST client and introduces a new E2E test to validate polling cadence percentiles for issue #1389. Review feedback identifies an inaccuracy in a code comment regarding ID filtering and suggests refining the percentile calculation for small sample sizes to ensure the p99 metric correctly accounts for outliers.

[Patch76]

Implementation Summary

Refs #1389. Delivers the measurement infrastructure for the pre-committed decision rule on _POLL_CADENCE = (0.1, 1.0, 4.9). The PR body covers the three components (instrumentation, test, terminal-summary plumbing); this summary captures the choices made along the way and the data that came out.

Choices Made

• Report-only test, no threshold assertion. CI latency variance from parallel pytest-xdist workers sharing one HA testcontainer would flake a strict assert p50 < 100 gate. The decision rule lives in the VERDICT line in the output, applied by the human via the PR comment / IS — not by the test.
• Three-hook pipeline at the root e2e conftest (xdist worker → workeroutput → master → terminalreporter.write_line). Initial implementation placed the hooks in a deep subdir conftest at tests/src/e2e/workflows/automation/conftest.py. The section never surfaced in CI output despite the test passing; moving the same hooks to the root e2e conftest fixed it. Empirically the root scope is the one the xdist master actually invokes for pytest_terminal_summary — same scope the existing readiness-gate-timings hooks already use. The readiness-timings pattern (refs Investigate and fix flaky E2E tests in CI workflows #366) at the same conftest is the structural origin.
• external_only marker on the test — caplog only sees records emitted in pytest's own process; on the HAOS-inaddon tier the rest_client lives in the addon's separate process, so the DEBUG records never reach caplog. Skipping on that tier avoids a false-negative No 'entity-registration-elapsed' DEBUG records captured failure that would otherwise mask the actual test outcome.
• closes → Refs #1389 in the PR body. The issue's decision rule says the PR closing [FEATURE] Measure HA Core entity-registration p50/p99 to validate _poll_for_automation_entity 0.1s floor #1389 is the one that ships the terminal action (close-as-validated or retune). This PR ships the measurement; the decision is below.

Problems Encountered

• Logger output dropped under pytest-xdist. First push surfaced no measurement data despite the test passing — pytest captures logger.info per-worker and only shows it on failure. Fixed by adding the terminal-summary hook pattern (commit fba9dbd).
• Hooks at wrong conftest scope (commit fba9dbd → 65e6d89). pytest_terminal_summary writes to the master-side terminal, and empirically the section never surfaced from a deep subdir conftest — only from the root e2e one. Moved to root e2e conftest.
• HAOS E2E Tests recurrent flake. tests/src/e2e/haos_only/test_manage_addon_modes.py::test_proxy_http_request_headers_pass_through failed 4 times today on this PR plus a prior unrelated PR — Node-RED add-on still in state: 'startup' when the test asserts the strict response shape. Wholly unrelated to this PR's diff; required-checks trio (E2E Validation ubuntu/arm + Docker) green throughout. Worth a separate wait_for_addon_state("started") fix in the affected test, not in this PR's scope.

Measurement Result

Across the two E2E Validation jobs on commit 65e6d89 (testcontainer mode, where caplog captures the production-side DEBUG records cleanly):

Job	N	p50	p90	p99	min	max	not_verified	VERDICT
E2E Validation (ubuntu-latest)	10	104.8 ms	105.1 ms	105.3 ms	104.1 ms	105.3 ms	0	RETUNE NEEDED
E2E Validation (ubuntu-24.04-arm)	10	104.1 ms	104.7 ms	105.2 ms	103.9 ms	105.2 ms	0	RETUNE NEEDED

All 20 samples land in a [103.9 ms, 105.3 ms] band — max − min ≈ 1.4 ms. The narrow spread means every automation registers on the first poll attempt (after the _POLL_CADENCE[0] = 0.1 s sleep). Subtracting the 100 ms sleep from the 104 ms elapsed leaves ~4 ms for the get_states() round-trip plus actual HA Core entity-registration latency — well below any threshold of concern. The 100 ms first-poll sleep is the rate-limiter, not HA Core.

Suggested Improvements (follow-ups, not blockers)

• [FEATURE] Measure HA Core entity-registration p50/p99 to validate _poll_for_automation_entity 0.1s floor #1389 terminal action: the decision rule fired RETUNE NEEDED (p50 ≥ 100 ms). The empirically-justified retune is _POLL_CADENCE = (0.025, 1.0, 4.975) — same 6.0 s total budget, first-poll tick pulled from 100 ms to 25 ms (5× cushion above the measured ~4 ms registration time). Ships as a separate PR with this measurement table as its empirical justification; [FEATURE] Measure HA Core entity-registration p50/p99 to validate _poll_for_automation_entity 0.1s floor #1389 closes when that lands.
• Pre-existing HAOS E2E flake on test_proxy_http_request_headers_pass_through — surfaced 4 times today across unrelated PRs (Node-RED state: 'startup' race). A wait_for_addon_state("started") guard or _wait_addon_running helper before the strict-shape assertion would close it. Out of scope here; worth its own issue if it persists.

[kingpanther13]

Measurement scaffolding is in the right shape (instrumentation + xdist-aware terminal-summary plumbing mirroring _READINESS_TIMINGS). Three blockers, four should-fix, comment subtractions.

Blocking

1. not_verified_count is dead — verdict can silently falsely report VALIDATED.

src/ha_mcp/tools/tools_config_automations.py:776 pops entity_not_verified off the result before it returns and translates it into a warnings string ("Automation was submitted to Home Assistant but the entity was not found after polling…"). So create_data.get("entity_not_verified") in test_poll_cadence_measurement.py:86 is always None, not_verified_count is always 0, no_misses is always True. A run where every cadence step exhausted would still print VERDICT=VALIDATED if the captured DEBUG records happened to be empty — and combined with #4, assert samples is the only thing catching all-misses today.

Detect a miss by scanning create_data.get("warnings", []) for the sentinel substring, or check create_data.get("entity_id") is None alongside success=True.

2. PR body says Refs #1389 — issue won't auto-close on merge.

GitHub only documents closing-keyword recognition in the body and commits on the default branch. Title closing-keywords are folklore. Replace Refs #1389. with Closes #1389. in the PR description.

3. "Suggested Improvements (follow-ups, not blockers)" defers exactly what AGENTS.md says to fold in.

The retune to _POLL_CADENCE = (0.025, 1.0, 4.975) is 3 numbers, justified by the measurement table this PR produced, and the verdict line that drove the retune was emitted by this PR's own test. Per the Boy Scout Rule, fold the retune into this PR — it then is the PR that closes #1389. The "ships as a separate PR" framing splits one logical unit across two PRs for no benefit and leaves master in a verdict=RETUNE NEEDED, cadence unchanged state if the retune PR slips.

The HAOS E2E flake item ("Out of scope here; worth its own issue if it persists") uses the exact escape-hatch phrasing AGENTS.md flags. The fix you describe is small — a wait_for_addon_state("started") guard or _wait_addon_running helper before the strict-shape assertion. That's classic Boy Scout: discovered during this PR's CI runs, trivially small, mechanical mirror of an existing pattern. Fold it in here, don't defer.

Rename the section and land both items in this PR.

Should-fix

4. assert samples only catches zero-capture; partial captures silently skew percentiles. test_poll_cadence_measurement.py:103-107

If 9 iterations succeed and 1 misses, the assert passes with n=9 and reports p50/p99 over those 9 — and combined with #1, the miss is invisible. After parsing samples, add:

assert len(samples) + not_verified_count == self.N_SAMPLES, (
    f"sample-count invariant violated: {len(samples)} samples + "
    f"{not_verified_count} misses != {self.N_SAMPLES} attempts"
)

Pair with #1 — miss-detection has to be real for this assert to be real.

5. The field labelled p99 is actually max for N=10. test_poll_cadence_measurement.py:114-118

The inline comment justifies the index-collapse, but the recorded dict key, the pytest_terminal_summary output, and the decision-rule line all call it p99. The closure-vs-retune decision rides on this number — name it for what it is. Rename to worst / p99_or_max in both writer and reader, or compute statistics.quantiles(samples, n=100, method="inclusive")[98] and surface max separately (already in the dict).

6. cleanup_tracker.track() is a no-op fixture. tests/src/e2e/conftest.py:1937-1942

The fixture's teardown only logs "Would clean up…" — there's no real delete. This test creates 10 automation.poll_cadence_measurement_1389_NN per run; on --dist loadscope they persist for the worker's lifetime. Pre-existing fixture defect, but this test is now the largest single producer. Either add an explicit try/finally in the test that calls ha_config_remove_automation per entity, or fix the fixture to actually delete — both qualify as in-scope cleanup for this PR.

7. caplog.set_level(DEBUG, logger="ha_mcp.client.rest_client") is sticky across tests on the same worker. test_poll_cadence_measurement.py:60-67

The docstring's "per-test-method-scoped" framing is correct for caplog.records but not for set_level — that mutates the worker's logger level. Every later test on the same xdist worker captures rest_client DEBUG at full volume until the worker exits. Use caplog.at_level(logging.DEBUG, logger="ha_mcp.client.rest_client") as a context manager around just the create-loop, or save/restore the prior level in a finally.

Nits

8. Comment subtractions — the PR is comment-heavy; a few earn nothing:

• test_poll_cadence_measurement.py:68-70 — duplicates the caplog.clear() rationale from lines 60-66.
• test_poll_cadence_measurement.py:124-127 — restates the decision-rule thresholds the code on the next line already says.
• conftest.py:92-98 — the xdist-conftest-loading mechanism explanation is slightly inaccurate (xdist's master loads all conftests; the real point is shared module-level state). Trim to one sentence cross-referencing _READINESS_TIMINGS.
• record_poll_cadence_measurement docstring (conftest.py:100-107) — the key list will rot on schema change; the call site is the source of truth.

9. N=10 + cadence (0.1, 1.0, 4.9) puts the decision boundary right at a cadence step. One late-sample run can flip VERDICT between VALIDATED and RETUNE for the same underlying behavior. With #5 fixed (renaming p99→worst), N=10 is fine for worst; if you keep the p99 < 1000ms rule, raise N to ~50 for boundary stability. (The retune in #3 collapses this concern anyway — at _POLL_CADENCE[0] = 0.025s the boundary moves far away from the cadence step.)

Verified clean

• Log-format migration from f-string to %-style is correct (deferred formatting); zero downstream references to the old "Found actual entity_id" text.
• pytest_testnodedown local-variable hoist is a readability win, not scope creep.
• external_only marker skip is correct — inaddon mode runs rest_client in a separate process where caplog can't reach it.
• _POLL_CADENCE_MEASUREMENTS xdist round-trip mirrors _READINESS_TIMINGS exactly.
• start_monotonic placement outside the try block is fine — failed registrations correctly produce no log line.

[Patch76]

Addressed in ab152e9. PR body updated Refs #1389 → Closes #1389 (item 2). Item-by-item below.

Blocking

1. not_verified_count dead — replaced with a warnings-substring scan. New _NOT_VERIFIED_WARNING_PREFIX module-level constant at test_poll_cadence_measurement.py:42 mirrors the literal in tools_config_automations.py:770; the per-iteration check at test_poll_cadence_measurement.py:103 reads create_data.get("warnings") or [] and matches that prefix. Pairs with item 4 below — a missed iteration now both registers in not_verified_count AND lets the sample-count invariant catch the case where the warning text drifts.

2. PR body Refs #1389 — flipped to Closes #1389. via gh api PATCH. Also folded the body's stale "ships as a separate PR" framing now that the retune is in this PR.

3. Boy-Scout fold — both items folded in.

• _POLL_CADENCE = (0.025, 1.0, 4.975) at rest_client.py:934. First-poll pulled to 25 ms, a 5× cushion above the measured ~4 ms HA-Core entity-registration latency. Same 3-attempt × 6.0 s budget. Three unit tests in test_rest_client_automations.py (lines 170, 194, 211, 239) updated in lockstep.
• HAOS flake: new _wait_for_state helper at test_manage_addon_modes.py:96 (mirrors test_addon_lifecycle.py:140 with the same _resolve_slug-style local-copy rationale). test_proxy_http_request_headers_pass_through at :278 now awaits state="started" before the strict-shape assertion. Confirmed against the failing run's log — Node-RED was in state="startup" when the proxy call hit; ha_manage_addon returned SERVICE_CALL_FAILED instead of an HTTP envelope.

Should-fix

4. Sample-count invariant — test_poll_cadence_measurement.py:127: assert len(samples) + not_verified_count == self.N_SAMPLES. With item 1's warning-scan miss-detection now real, this catches the silent-skew case directly.

5. p99 rename — went with the rename path. Variable, dict key, decision-rule, terminal-summary renderer, and log line all consistently use worst now. worst = samples[-1] at test_poll_cadence_measurement.py:140, worst_ok = worst < 1000.0 at :145, f"worst={m['worst']:.1f}ms" in the renderer at conftest.py:264. The inline comment explaining why N=10 collapses the percentile index moved into the module docstring (test_poll_cadence_measurement.py:14-19) as headline context. Test method renamed test_poll_cadence_p50_p99 → test_poll_cadence_p50_worst at :65.

6. cleanup_tracker.track() no-op — per-test try/finally cleanup at test_poll_cadence_measurement.py:202-212. Each tracked automation.poll_cadence_measurement_1389_NN gets an explicit ha_config_remove_automation call; cleanup failures log a warning rather than mask the assertion outcome. Fixture itself stays as-is (pre-existing scope, this PR was the largest producer not the only one).

7. caplog.set_level stickiness — replaced with caplog.at_level(logging.DEBUG, logger="ha_mcp.client.rest_client") context manager at test_poll_cadence_measurement.py:74, wrapping only the create-loop. Logger level saved+restored on exit; later tests on the same xdist worker no longer inherit DEBUG-on-rest_client.

Nits

8. Comment subtractions — six regions trimmed.

• Test file: caplog rationale (the old :60-67 block) collapsed to two lines explaining at_level vs set_level. The caplog.clear() duplicate-rationale comment dropped entirely. Index-collapse comment (:136-139) tightened. Decision-rule restate (:124-127) dropped — the boolean variable names now carry the rule.
• conftest: xdist explainer (:91-92) trimmed to a single two-line cross-ref to _READINESS_TIMINGS. record_poll_cadence_measurement docstring at :98-104 points at the test file as schema source.

9. N=10 boundary — resolved by 5's rename. No code change.

On the verified-clean list

Log-format %-style migration, pytest_testnodedown hoist, external_only marker, _POLL_CADENCE_MEASUREMENTS xdist round-trip, start_monotonic placement — all unchanged.

CI on ab152e9 will report fresh measurements at the new cadence — expecting p50 to land near the ~4 ms HA-Core latency plus the 25 ms first-poll sleep.

[Patch76]

Correction on the bundled reply above — withdrawing the HAOS portion of item 3.

Cross-reference audit caught that #1402 (your PR, merged 2026-05-21 21:43 UTC) had already landed the exact same fix on master: the _wait_addon_running guard in test_manage_addon_modes.py:106. That landed ~3 hours after the "fold it" review on this PR, and my fold was implemented this morning without re-checking master state — my file-overlap check at the top of the deep-dive was incomplete (mergeable: MERGEABLE covered conflict-marker absence but not line-region overlap).

Branch force-pushed to f34ea9a: HAOS additions dropped, branch rebased onto current upstream/master so #1402's _wait_addon_running is now live on this PR's CI lane. PR body updated to point at #1402 instead of claiming the HAOS work as in-scope.

Substantive changes vs the previous push: 4 files changed (rest_client.py + conftest.py + measurement test + unit-test pins). The retune and the 8 other review items remain — only the HAOS helper + the per-test guard line came out.

[kingpanther13]

Verifying f34ea9a7 against my prior review: all 8 items + retune land cleanly. Three new findings from the rewrite.

Should-fix

1. Cleanup except Exception diverges from the project's polling-helper pattern. tests/src/e2e/workflows/automation/test_poll_cadence_measurement.py:209

safe_call_tool only catches ToolError; everything else (TypeError, AttributeError, KeyError, etc.) becomes a logger.warning line and silently continues to the next iteration of the cleanup loop. AGENTS.md "Exception handling in polling helpers" and tests/src/e2e/utilities/wait_helpers.py (per #1266) establish the inverse: bugs MUST propagate out of polling loops with their stack trace, not be downgraded to warnings. Per-entity cleanup is the same shape — same "keep going past one bad iteration" intent, same risk of swallowing programmer bugs across 10 identical iterations.

Tighten to a narrow tuple analogous to _POLLING_TRANSIENT_ERRORS — something like (ToolError, OSError, TimeoutError, McpError) covering what safe_call_tool plus its transport layer would raise on a real HA-side cleanup failure (404 on already-removed entity, connection blip), not what a programmer typo would raise.

2. _NOT_VERIFIED_WARNING_PREFIX is coupled to source by comment only. test_poll_cadence_measurement.py:42

The literal lives in two places (tools_config_automations.py:770 and the test) with just an inline "Mirrors the literal" comment connecting them. If the warning copy is reworded in the source, the test silently slides to not_verified_count == 0. The sample-count invariant catches the resulting count mismatch and fails the test loud — so it's not a current silent failure — but the error ("9 samples + 0 not-verified != 10 attempts") wouldn't point at the wording drift. Lift the constant out of tools_config_automations.py (export it from the module, or put it in a shared constants location) and import it in the test — mechanical fix, makes the coupling a compile-time error instead of a test-runtime puzzle.

Nit

3. Cleanup-block comment calls cleanup_tracker "session-scoped". test_poll_cadence_measurement.py:197

The fixture is bare @pytest.fixture at tests/src/e2e/conftest.py:1951 — function-scoped, not session-scoped. The substantive point (fixture only logs, doesn't delete) is correct and load-bearing; just the scope label is wrong. Replace "session-scoped" with "logging-only" (matches the commit-message framing).

Otherwise verified clean

• Sentinel substring at tools_config_automations.py:770 matches _NOT_VERIFIED_WARNING_PREFIX exactly.
• p99 → worst rename consistent across dict key, terminal-summary writer, decision-rule check, test method name. No lingering p99 selectors.
• _POLL_CADENCE = (0.025, 1.0, 4.975) sums to 6.0; unit-test pins updated in all three sites (test_poll_cadence_shape, full-miss test, partial-attempt test).
• caplog.at_level scope is right — caplog.records survives the context-manager exit because pytest's caplog accumulates per-test, not per-block.
• Sample-count invariant placement: inside try:, after assert samples, before the finally: runs cleanup. AssertionError propagates correctly.
• ha_config_remove_automation(identifier=...) signature matches the tool definition.
• Per-test cleanup runs only on external/testcontainer tiers where the tool is registered (external_only handles inaddon).
• All 4 targeted comment subtractions from the prior review are gone.
• PR body now uses Closes #1389 ✓.
• HAOS proxy-header flake landed via merged #1402 and is on the PR's rebased base.

[Patch76]

Addressed in 4fd2852, with a format-sweep follow-up at 376467b.

Should-fix

1. Cleanup except Exception narrowed. tests/src/e2e/workflows/automation/test_poll_cadence_measurement.py:204

Imported _POLLING_TRANSIENT_ERRORS from wait_helpers.py:28 (the canonical tuple from #1266: McpError, FastMCPError, ClientError, RuntimeError, OSError, TimeoutError) and used it as the cleanup-loop catch. TypeError / AttributeError / KeyError / AssertionError now propagate with their stack trace; only transient HA-side cleanup errors (404, connection blip) get the warn-and-continue treatment. Comment block at L190-196 rewritten to call out the propagation intent explicitly.

2. NOT_VERIFIED_WARNING_PREFIX lifted to module-level constant. src/ha_mcp/tools/tools_config_automations.py:63 + tests/src/e2e/workflows/automation/test_poll_cadence_measurement.py:28

Module-level constant defined in tools_config_automations.py:63 and used in the warning construction at :807. Test imports it directly, so rewording the source warning now breaks the test import — coupling is compile-time. The "Mirrors the literal" comment in the test is gone (replaced by the import).

Nit

3. "session-scoped" → "logging-only". tests/src/e2e/workflows/automation/test_poll_cadence_measurement.py:190

Done. Matches the commit-message framing for the cleanup_tracker fixture.

Format-sweep follow-up (376467b)

Touching tools_config_automations.py for item 2 added it to the PR's changed-files set, which triggers ruff format --check whole-file per .github/workflows/pr.yml. Pre-existing master-debt on that file (line-break placement on multi-arg raise_tool_error(...) calls, dict-literal expansion) was suddenly blocking. Followed up with chore: apply ruff format (refs #1318) — mechanical only, no logic change. The 231-line diff on the source file is all ruff-format output; the 1-line change on the test file is the isinstance(w, str) and w.startswith(...) collapse from the shorter constant name.

[kingpanther13]

All three items addressed cleanly:

• _POLLING_TRANSIENT_ERRORS import is the right tuple — (McpError, FastMCPError, ClientError, RuntimeError, OSError, TimeoutError) from wait_helpers.py:28. TypeError / AttributeError / KeyError / AssertionError propagate; transient transport/HA errors get the warn-and-continue. Private-symbol import is an established pattern in this repo (also used in test_manage_addon_modes.py:56).
• NOT_VERIFIED_WARNING_PREFIX is module-level public at tools_config_automations.py:63, consumed via f-string at :781. Adjacent-string concat is byte-identical to the previous literal. Grep confirms a single emit site — no hardcoded-literal drift surface. Compile-time coupling achieved.
• "session-scoped" → "logging-only" with propagation-intent expansion. Reads correctly.

Format-sweep 376467bc: AST-identical on both files (parsed both pre/post, byte-equal). No statement/argument/default/dict-key changes — pure layout. Test-file 1-line collapse is semantically unchanged.

LGTM.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.