Clear stale addresses on retarget and stop loopback Online latches

Removing or changing wifi.use_address left the ping sweep pinging the
RAM addresses resolved from the old value, latching the device Online
off whatever host answered there. An address change now drops the
resolved set (unless mDNS/MQTT owns the name) before waking the sweep.
Loopback joins unspecified as an unusable address across the liveness
paths, and an out-of-band edit that moves a network block schedules a
StorageJSON regenerate so the effective address tracks the YAML.

Author: bdraco

CLAUDE.md

@@ -624,6 +624,27 @@ against legacy behaviour before assuming the simpler version suffices.
     has no browser `Removed` counterpart, so it locks out `should_ping` and
     latches the device ONLINE forever (#1776). The `ping`-source result
     (priority 1) stays sweep-eligible so a dead entry demotes.
+  - **Configured-address changes drop the ping-learned RAM addresses**
+    (`DeviceStateMonitor.address_retargeted`, #2486). The sweep stores
+    what it resolved from `device.address` into
+    `runtime_state.ip_addresses` and falls back to that set when the
+    address stops resolving — so a `wifi.use_address` edit/removal
+    would keep pinging whatever answered at the *old* address and
+    re-latch ONLINE forever. The scan-change address branch clears the
+    resolved set (skipped while mDNS/MQTT owns the name — their
+    evidence is identity-carrying and address-independent) before
+    waking the sweep. Relatedly, loopback counts as unusable wherever
+    unspecified does (`helpers/ip.py`), and `_resolve_and_ping` filters
+    its final target list, so `use_address: 127.0.0.1` applies OFFLINE
+    instead of latching ONLINE off the dashboard host — while the DNS
+    cache still returns literal loopback verbatim, keeping SSH-tunnel
+    OTA workflows working. Out-of-band edits (git pull, external
+    editor) that move a top-level network, `substitutions:`, or
+    `packages:` block schedule a StorageJSON regen via the off-wire
+    `Device.network_fingerprint` change detector (API-path writes
+    already regen on every save). An edit to a referenced package
+    *file* stays uncovered — it changes no device YAML, so no scan
+    event fires.
   - **`_http._tcp` identity fallback** (`MdnsSource._on_http_service_state_change`,
     for a configured device without `api:`). Such a device never publishes
     `_esphomelib._tcp` (behind `USE_API`); its broadcast is the `_http._tcp`

esphome_device_builder/controllers/_device_mqtt_monitor.py

@@ -662,8 +662,8 @@ def _extract_ip(data: dict[str, Any]) -> str:
     Pull the first usable IP field from a discovery payload.
 
     ESPHome devices expose their addresses as ``ip``, ``ip0``, ``ip1``,
-    ... — returns the first value that parses as a real, non-unspecified
-    IP (the payload is untrusted), or empty string when none qualify.
+    ... — returns the first value that parses as a real, usable IP
+    (the payload is untrusted), or empty string when none qualify.
     """
     for key in ("ip", "ip0", "ip1", "ip2"):
         value = data.get(key)

esphome_device_builder/controllers/_device_state_monitor/controller.py

@@ -29,7 +29,7 @@
 from typing import Any, Protocol
 
 from ...helpers.async_ import create_eager_task, drain_tasks, log_task_exit
-from ...helpers.ip import drop_unspecified_addresses, is_unspecified_address
+from ...helpers.ip import drop_unusable_addresses, is_unusable_address
 from ...helpers.subscriber_presence import SubscriberPresence
 from ...models import (
     RUNTIME_STATE_FIELD_NAMES,
@@ -50,7 +50,7 @@
 from .importable import ImportableDiscovery
 from .mdns import MdnsSource
 from .ping import PingSource
-from .shared import _SOURCE_PRIORITY, should_ping
+from .shared import _SOURCE_PRIORITY, identity_source_owns, should_ping
 
 _LOGGER = logging.getLogger(__name__)
 # Cap on draining the ping / API-info / resolve tasks at shutdown.
@@ -412,7 +412,7 @@ def apply_ip(self, name: str, ip: str) -> bool:
         """
         if not ip:
             raise ValueError("empty ip; use clear_resolved_addresses")
-        if is_unspecified_address(ip):
+        if is_unusable_address(ip):
             return False
         devices = self._get_devices_by_name(name)
         if not devices:
@@ -435,7 +435,7 @@ def apply_ip_addresses(self, name: str, addresses: list[str]) -> bool:
         """
         if not addresses:
             raise ValueError("empty addresses; use clear_resolved_addresses")
-        usable = drop_unspecified_addresses(addresses)
+        usable = drop_unusable_addresses(addresses)
         if not usable:
             return False
         return self._dispatch_ip(name, _pick_ipv4(usable), usable)
@@ -634,6 +634,14 @@ def invalidate_persisted_ip(self, name: str, stale_ip: str) -> None:
         if self._on_persisted_ip_invalidated is not None:
             self._on_persisted_ip_invalidated(name, stale_ip)
 
+    def address_retargeted(self, name: str) -> None:
+        """Drop stale resolved IPs and wake the sweep after *name*'s configured address changed."""
+        # mDNS / MQTT evidence is identity-carrying and address-
+        # independent, so their resolved set survives the retarget.
+        if not identity_source_owns(self, name):
+            self.clear_resolved_addresses(name)
+        self.probe_device_ping(name)
+
     def probe_device_ping(self, device_name: str) -> None:
         """
         Wake the ICMP sweep loop when *device_name* warrants a probe.

esphome_device_builder/controllers/_device_state_monitor/mdns.py

@@ -31,7 +31,7 @@
 
 from ...helpers.async_ import drain_tasks, log_task_exit
 from ...helpers.hostname import normalize_hostname
-from ...helpers.ip import drop_unspecified_addresses
+from ...helpers.ip import drop_unusable_addresses
 from ...models import DeviceState
 from .._reachability_tracker import MdnsCacheInfo
 from .helpers import (
@@ -304,7 +304,7 @@ def get_cached_addresses(self, host_name: str) -> list[str] | None:
         if not info.load_from_cache(self._zeroconf.zeroconf):
             return None
         addresses = info.parsed_scoped_addresses(IPVersion.All)
-        return drop_unspecified_addresses(addresses) or None
+        return drop_unusable_addresses(addresses) or None
 
     def reconcile_from_cache(self, device_name: str) -> None:
         """
@@ -542,7 +542,7 @@ def _apply_service_info(self, device_name: str, info: AsyncServiceInfo) -> None:
         announce never claims.
         """
         monitor = self._monitor
-        # Claimed before the apply-path unspecified-address filter, unlike
+        # Claimed before the apply-path unusable-address filter, unlike
         # the active-resolve path: a resolved service is liveness evidence
         # on its own (already claimed even when addressless), and the
         # browser's ``Removed`` lifecycle withdraws the claim so ping

esphome_device_builder/controllers/_device_state_monitor/ping.py

@@ -10,6 +10,7 @@
 from icmplib.exceptions import ICMPLibError
 
 from ...helpers.hostname import is_local_hostname
+from ...helpers.ip import drop_unusable_addresses
 from ...models import Device, DeviceState
 from . import shared
 from ._sweep_source import SweepSource
@@ -230,6 +231,11 @@ async def _resolve_and_ping(self, device: Device) -> None:
                 # prior MQTT/DNS observation left a usable IP. Ping that so
                 # ping can confirm a device the network won't resolve.
                 addresses = list(device.runtime_state.ip_addresses)
+            # A literal loopback ``use_address`` rides the DNS cache's
+            # literal short-circuit past every apply-side filter; pinging
+            # it would latch the device ONLINE off the dashboard host
+            # itself (#2486).
+            addresses = drop_unusable_addresses(addresses)
             if not addresses:
                 shared.apply_ping_result(monitor, device.name, None)
                 return

esphome_device_builder/controllers/_device_state_monitor/shared.py

@@ -12,7 +12,7 @@
 from typing import TYPE_CHECKING
 
 from ...helpers.hostname import is_local_hostname
-from ...helpers.ip import drop_unspecified_addresses
+from ...helpers.ip import drop_unusable_addresses
 from ...models import Device, DeviceState, ReachabilitySource
 
 if TYPE_CHECKING:
@@ -56,8 +56,12 @@ def should_ping(monitor: DeviceStateMonitor, device: Device) -> bool:
     """
     if device.runtime_state.state != DeviceState.ONLINE:
         return True
-    source = monitor.state.state_source.get(device.name, ReachabilitySource.UNKNOWN)
-    return _SOURCE_PRIORITY.get(source, 0) <= _SOURCE_PRIORITY[ReachabilitySource.PING]
+    return not identity_source_owns(monitor, device.name)
+
+
+def identity_source_owns(monitor: DeviceStateMonitor, name: str) -> bool:
+    """Return True when a higher-than-ping source (mDNS / MQTT) owns *name*."""
+    return _SOURCE_PRIORITY[monitor.priority_for(name)] > _SOURCE_PRIORITY[ReachabilitySource.PING]
 
 
 def apply_ping_result(monitor: DeviceStateMonitor, name: str, rtt_ms: float | None) -> None:
@@ -103,9 +107,9 @@ def apply_resolved_addresses(
     """
     if not isinstance(addresses, list):
         return
-    # Filter before the ONLINE claim — an all-unspecified answer must
+    # Filter before the ONLINE claim — an all-unusable answer must
     # not latch the device ONLINE while the apply refuses the IPs.
-    usable = drop_unspecified_addresses(addresses)
+    usable = drop_unusable_addresses(addresses)
     if not usable:
         return
     # The claim rides the live anchor PTR, whose ``Removed``

esphome_device_builder/controllers/_dns_cache.py

@@ -26,7 +26,7 @@
 from icmplib import NameLookupError, async_resolve
 
 from ..helpers.hostname import normalize_hostname
-from ..helpers.ip import drop_unspecified_addresses
+from ..helpers.ip import drop_unusable_addresses
 
 _DEFAULT_TTL_SECONDS = 120
 _RESOLVE_TIMEOUT_SECONDS = 3.0
@@ -147,6 +147,7 @@ async def _try_resolve(hostname: str) -> list[str] | None:
                 addresses = cast("list[str]", await async_resolve(hostname))
         except _RESOLVE_EXCEPTIONS:
             return None
-        # A sinkhole resolver answers with 0.0.0.0 / ::; an
-        # all-unspecified reply is a failed lookup, not a result.
-        return drop_unspecified_addresses(addresses) or None
+        # A sinkhole resolver answers with 0.0.0.0 / :: (or 127.0.0.1,
+        # Pi-hole style); an all-unusable reply is a failed lookup, not
+        # a result.
+        return drop_unusable_addresses(addresses) or None

esphome_device_builder/controllers/devices/metadata.py

@@ -11,7 +11,7 @@
 from ...helpers.build_size import coerce_sidecar_int
 from ...helpers.config_hash import read_build_info_hash
 from ...helpers.device_yaml import parse_platform_from_yaml
-from ...helpers.ip import is_unspecified_address
+from ...helpers.ip import is_unusable_address
 from .._device_builder_base import DeviceBuilderBase
 from .._device_scanner import DeviceFileMetadata
 from ..config import metadata_transaction
@@ -97,7 +97,7 @@ def _resolve_device_metadata(self, config_dir: Path, filename: str) -> DeviceFil
         store_md = self._metadata_store.get(filename)
         shared_md = self._shared_sidecar.get_sync(filename)
         ip = str(store_md.get("ip", ""))
-        if ip and is_unspecified_address(ip):
+        if ip and is_unusable_address(ip):
             # A persisted sidecar can hold a poisoned IP the runtime
             # filters never saw.
             ip = ""

esphome_device_builder/controllers/devices/scan_change.py

@@ -55,15 +55,27 @@ def on_scan_change(
     ):
         # The change swapped in a new address (a ``wifi.use_address``
         # edit, or the post-regen StorageJSON replacing the
-        # ``<file>.local`` fallback); without the wake the new address
-        # waits out the remainder of the periodic sweep interval.
-        controller._state_monitor.probe_device_ping(device.name)
+        # ``<file>.local`` fallback); without the retarget the sweep
+        # keeps pinging addresses resolved from the old one (#2486) or
+        # waits out the remainder of the periodic interval.
+        controller._state_monitor.address_retargeted(device.name)
     if kind in (ScanChange.UPDATED, ScanChange.RELOADED, ScanChange.REMOVED):
         # YAML cache key changed (or a reload re-read it); clear any
         # prior failure marker so the next edit gets a fresh chance at
         # ``--only-generate`` (and re-creating a deleted file
         # later doesn't inherit the old failure).
         controller.state.regenerate_failed.discard(device.configuration)
+    if (
+        kind is ScanChange.UPDATED
+        and previous is not None
+        and previous.network_fingerprint != device.network_fingerprint
+    ):
+        # An out-of-band edit (git pull, external editor) moved a
+        # network block; without a regen ``StorageJSON.address`` keeps
+        # the old ``use_address`` and the sweep pings a stale host
+        # (#2486). API-path writes regen unconditionally in
+        # ``_persist_yaml_mutation`` and surface here as RELOADED.
+        controller._schedule_storage_regenerate(device.configuration)
     # First-sight devices with no compile output carry the
     # ``<filename>.local`` address fallback and an empty
     # ``loaded_integrations`` list. Schedule a background

esphome_device_builder/helpers/device_yaml/_loading.py

@@ -29,6 +29,7 @@
     extract_esphome_meta_from_config,
     extract_logger_baud_rate,
     extract_logger_interface,
+    extract_network_address_fingerprint,
     extract_ota_partition_access,
     get_api_encryption_block,
     has_top_level_block,
@@ -318,6 +319,7 @@ def load_device_from_storage(
         # this on the next compile if the device picks a different
         # ``esphome.address``.
         address=(storage.address if storage and storage.address else f"{fallback_name}.local"),
+        network_fingerprint=extract_network_address_fingerprint(yaml_content),
         ip=ip,
         web_port=storage.web_port if storage else None,
         current_version=const.__version__,