fix(flows): make a clear hold past its first encounter

What expresses a clear depends on the field's shape, and only one of the
two sites deciding it carried the qualifier. _consume_leaf_field submits
a null verbatim for a field with a "default" — omitting it there would let
voluptuous substitute that default — while _edit_mode_submission omitted
any recorded None. So a defaulted field cleared on step one had the static
default handed back on its second encounter, reporting success having
cleared nothing. Reachable by a later step redeclaring the field or a menu
loop revisiting the same one.

Both sites now share _clears_by_omission, so they cannot drift again.

Also pins the warning the optional reuse path now emits: resubmitting the
caller's value is the intended outcome there, so the note rides with it.

Found by Patch76 review on #2256.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012d29UJTiH4Uy2Pm37SBPtr

Author: kingpanther13

src/ha_mcp/tools/config_entry_flow_form.py

@@ -423,6 +423,24 @@ def _current_value_backfill(field: dict[str, Any]) -> tuple[Any, bool]:
     return step_owned, False
 
 
+def _clears_by_omission(field: dict[str, Any]) -> bool:
+    """Whether leaving this field OUT is how the caller clears it.
+
+    Only for a field that is neither required nor carrying a ``"default"``:
+    there, an absent key simply stays absent. Anything else has a value
+    voluptuous substitutes for the omission — the static default, which is a
+    different value than the caller asked for and would report success while
+    clearing nothing — so the ``None`` is submitted instead and Home Assistant
+    decides whether null is meaningful for that field.
+
+    The single source of truth for both sites that answer this question:
+    :func:`_consume_leaf_field`, where the caller's key is popped, and
+    :func:`_edit_mode_submission`, where a later encounter of the same field
+    has to reach the same verdict (Patch76 review, issue #2254).
+    """
+    return not field.get("required") and "default" not in field
+
+
 def _edit_mode_submission(
     field: dict[str, Any],
     name: str,
@@ -448,7 +466,9 @@ def _edit_mode_submission(
     if recorded is _MISSING_DEFAULT:
         return _current_value_backfill(field)
     if recorded is None:
-        return _NO_SUBMISSION
+        # The caller cleared it. Express that the same way the popping site
+        # did, or the clear stops holding at its second encounter.
+        return _NO_SUBMISSION if _clears_by_omission(field) else (None, True)
     if not reuse_state.claim_write(dotted):
         # The one reused write per (step, path) is spent — a menu loop is
         # revisiting this step. Falling back to omission would let voluptuous
@@ -569,12 +589,7 @@ def _consume_leaf_field(
     """
     if name in remaining_config:
         value = remaining_config.pop(name)
-        clearing = (
-            keep_current_values
-            and value is None
-            and not field.get("required")
-            and "default" not in field
-        )
+        clearing = keep_current_values and value is None and _clears_by_omission(field)
         form_data[name] = _CLEARED if clearing else value
         _mark_consumed(consumed_config_keys, path_prefix, name)
         if reuse_state is not None:

tests/src/unit/test_flow_options_preserve.py

@@ -607,6 +607,97 @@ def test_a_callers_value_outranks_a_later_steps_suggestion(self) -> None:
             f"The later step overwrote the caller's value: {second}"
         )
 
+    @staticmethod
+    def _defaulted_step(step_id: str) -> dict[str, Any]:
+        """One OPTIONAL field carrying a static default and no suggestion."""
+        return {
+            "type": "form",
+            "step_id": step_id,
+            "data_schema": [
+                {
+                    "name": "workdays",
+                    "required": False,
+                    "optional": True,
+                    "default": ["mon", "tue", "wed", "thu", "fri"],
+                },
+            ],
+        }
+
+    @pytest.mark.parametrize(
+        ("first_step", "second_step"),
+        [("one", "two"), ("init", "init")],
+        ids=["later-step-redeclares", "same-step-revisited"],
+    )
+    def test_a_clear_on_a_defaulted_field_survives_its_second_encounter(
+        self, first_step: str, second_step: str
+    ) -> None:
+        """What expresses a clear depends on the field's shape, at BOTH sites.
+
+        ``_consume_leaf_field`` submits the ``None`` verbatim for a field
+        carrying a ``"default"``, because omitting it there would let
+        voluptuous substitute that default. The later encounter has to reach
+        the same verdict — omitting it on encounter two hands the default back
+        and reports success having cleared nothing (Patch76 review, #2256).
+        """
+        reuse_state = _ReuseState()
+        remaining: dict[str, Any] = {"workdays": None}
+
+        first = _handle_form_step(
+            "flow-2254",
+            self._defaulted_step(first_step),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+        second = _handle_form_step(
+            "flow-2254",
+            self._defaulted_step(second_step),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+
+        assert first == {"workdays": None}
+        assert second == {"workdays": None}, (
+            "The clear stopped holding at its second encounter; omitting the "
+            f"key lets the static default back in. Got: {second}"
+        )
+
+    def test_a_redeclared_optional_field_warns_when_it_resubmits(self) -> None:
+        """Routing the optional path through claim_write emits its note.
+
+        Pinned rather than asserted-away: the mode treats resubmitting the
+        caller's value as the CORRECT outcome here, so the warning rides along
+        with it and callers see it (Patch76 review, #2256).
+        """
+        reuse_state = _ReuseState()
+        remaining: dict[str, Any] = {"province": "BY"}
+
+        _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("one"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+        _handle_form_step(
+            "flow-2254",
+            self._redeclaring_step("two"),
+            remaining,
+            None,
+            set(),
+            reuse_state,
+            keep_current_values=True,
+        )
+
+        assert reuse_state.notes == [_reuse_warning("province", "two")]
+
     def test_a_revisited_step_keeps_the_stored_value_after_the_write_is_spent(
         self,
     ) -> None: