diff --git a/.changeset/resolve-local-device-names.md b/.changeset/resolve-local-device-names.md
new file mode 100644
index 00000000..4120bfe2
--- /dev/null
+++ b/.changeset/resolve-local-device-names.md
@@ -0,0 +1,62 @@
+---
+"ftw": minor
+---
+
+Resolve device `.local` names, so devices can be configured by name instead of a DHCP-assigned IP.
+
+Go never resolves `.local` itself: it hands those names to libc only when cgo is
+available, and FTW builds with `CGO_ENABLED=0`, so a configured `zap.local`
+became a unicast DNS query to the site router and failed. That is true on every
+base image and every libc — shipping `libnss-mdns` changes what `getent` and
+`curl` resolve inside the container, not what this process resolves.
+
+FTW now asks the host's own mDNS responder, `avahi-daemon`, over its
+simple-protocol socket — the same daemon and the same socket
+`libnss_mdns4_minimal.so.2` uses, so a name resolves identically whether FTW
+dials it or an operator checks it from a shell in the container. Where that
+socket cannot be reached, FTW queries the LAN directly instead. The socket has
+to be bind-mounted, and under the Home Assistant Supervisor an add-on cannot
+mount arbitrary host paths at all, so the direct path is what makes the feature
+work there; it is also the default in Compose, where mounting a host runtime
+directory is left to the operator. A successful lookup logs which one answered.
+
+Every driver transport uses it — Modbus TCP, MQTT (driver and Home Assistant
+bridge), HTTP including TLS-pinned clients, WebSocket and raw TCP.
+
+Resolution happens per dial rather than once at startup, so a device that moves
+to a new DHCP lease is found again on the next reconnect without a config edit.
+Answers are cached (30–120 s, following the record TTL where there is one) so
+reconnect loops do not flood the LAN, and failures are cached briefly so a
+device that is still booting is retried soon. A failed resolution logs
+`mDNS resolution failed` and names the mechanism, instead of surfacing as a
+generic dial error.
+
+Only `.local` names take this path; literal IPs and ordinary DNS names dial
+exactly as before. Multicast still has to reach the LAN, which the Linux
+Compose topology has via `network_mode: host`. Under `docker-compose.macos.yml`
+the container is bridged, so configure devices by IP there.
+
+Direct queries use each active multicast interface. IPv4 and IPv6 are
+supported; link-local IPv6 addresses carry their interface zone and unscoped
+answers are rejected. The resolver also rejects non-response DNS packets,
+wrong answer classes or families, invalid sources, and Avahi replies whose
+interface, name, address family or address does not match the request. mDNS is
+unauthenticated, so `capabilities.allow_unverified_local: true` for a driver —
+or `homeassistant.allow_unverified_local: true` for the Home Assistant bridge —
+gates whether FTW acts on an answer it obtained itself. It gates the resolution
+path, not the connection: without it a `.local` name still goes to the system
+resolver exactly as it does today, which is what keeps working installs working
+under Home Assistant, where Supervisor answers `.local` through its own DNS
+service. Host allowlists do not prove server identity, and a TLS pin does not
+bypass the gate yet. Literal IP and ordinary DNS endpoints are unchanged.
+
+Network scanning now reports the name a device answers for itself. It used to
+ask unicast reverse DNS first and only fall back to mDNS, which meant the
+router's label for the lease — `zap-000064963cd51edc.localdomain` on a UniFi
+network — was what reached the setup wizard, and the wizard fell back to the
+raw IP because that is not a `.local` name. Both queries now run together and a
+`.local` answer wins. Reverse mDNS alone is not enough either: RFC 6762 leaves
+`in-addr.arpa` mapping optional and many responders publish a forward `A`
+record without one, so where no reverse record exists FTW re-asks the label
+forward as `<label>.local` and keeps it only when it resolves back to the same
+address. Unverified names are still shown, but only as display text.
diff --git a/config.example.yaml b/config.example.yaml
index 6ec593cf..608c9626 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -73,6 +73,9 @@ drivers:
   # - name: ambibox
   #   lua: drivers/ambibox_v2x.lua
   #   capabilities:
+  #     # Lets FTW resolve the name itself over mDNS. Without it the name is
+  #     # left to the system resolver, which answers on some platforms only.
+  #     allow_unverified_local: true
   #     mqtt:
   #       host: sid-os.local
   #       port: 1883
@@ -90,8 +93,12 @@ drivers:
   #   is_site_meter: true
   #   battery_telemetry_only: true
   #   capabilities:
+  #     # Lets FTW resolve zap.local itself. Without it the name is left to
+  #     # the system resolver — which answers under Home Assistant, but not on
+  #     # a plain Compose or Pi install.
+  #     allow_unverified_local: true
   #     http:
-  #       allowed_hosts: ["zap.local"]  # use the LAN IP if mDNS is unavailable
+  #       allowed_hosts: ["zap.local"]  # .local is resolved by FTW over mDNS
   #   config:
   #     host: zap.local
   #     # meter_serial: p1m-...          # optional; P1 is auto-selected
@@ -136,6 +143,7 @@ api:
 homeassistant:
   enabled: false
   broker: 192.168.1.1
+  # allow_unverified_local: true  # let FTW resolve broker.local over mDNS itself
   port: 1883
   username: homeems
   password: homeems
diff --git a/docker-compose.yml b/docker-compose.yml
index 414b4fab..a4c75a2e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -73,6 +73,21 @@ services:
       # here to render update progress in the UI; it never writes to it.
       - update-ipc:/run/ftw-update
       - optimizer-ipc:/run/ftw-optimizer
+      # OPTIONAL — avahi-daemon's runtime directory. Host networking shares
+      # ports, not Unix sockets, so this is the only way in.
+      #
+      # With it, FTW asks the host's mDNS responder to resolve `.local` device
+      # names (and `getent hosts zap.local` works inside the container, via
+      # libnss-mdns). Without it FTW queries the LAN itself, which needs no
+      # host software and is why this stays commented out by default.
+      #
+      # Uncomment only if the host runs avahi-daemon — the Raspberry Pi image
+      # does. Mount the DIRECTORY, not the socket inside it: if the path is
+      # missing Docker creates it, and an empty directory there is harmless,
+      # whereas a directory created where the *socket* belongs stops
+      # avahi-daemon from ever starting. Restarting avahi after the container
+      # detaches the mount, so restart FTW too if you do.
+      # - /run/avahi-daemon:/run/avahi-daemon:ro
 
   ftw-optimizer:
     image: ghcr.io/srcfl/ftw-optimizer:${FTW_OPTIMIZER_IMAGE_TAG:-latest}
diff --git a/docs/operations.md b/docs/operations.md
index 32221328..194ad3c2 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -180,30 +180,99 @@ Verify the broker address from the same network namespace as core, then inspect
 broker and driver logs. Device credentials and topic mappings belong to the
 driver configuration.
 
-### `.local` names inside the container
+### A device `.local` name does not resolve
 
-The image ships `libnss-mdns`, so ordinary glibc tools inside the container —
-`getent hosts zap.local` and `wget` — resolve `.local` the way they do on
-the host. `apt` wires `mdns4_minimal [NOTFOUND=return]` into
-`/etc/nsswitch.conf` when the package is installed; nothing else is needed at
-build time.
+FTW resolves `.local` device names itself; the OS resolver is not involved,
+because a `CGO_ENABLED=0` Go binary never consults NSS. There are two places an
+answer can come from, and the log line for a successful lookup says which:
 
-At run time that path talks to `avahi-daemon` over a Unix socket, and a socket
-is not shared by host networking the way a port is. Mount it explicitly:
+```
+resolved host over mDNS host=zap.local addr=192.168.1.42 via=avahi
+```
+
+**`via=avahi`** — the host's `avahi-daemon` answered over its socket. This is
+preferred when available: avahi already holds a record cache, and it is the
+same daemon that `getent hosts zap.local` inside the container goes through, so
+FTW and your shell cannot disagree about an address.
+
+**`via=multicast`** — FTW queried the LAN directly. This is what happens when
+the avahi socket is not mounted, which is the default, and it needs no host
+software at all.
+
+Failures log `mDNS resolution failed`, and the message names both backends when
+both were tried.
+
+Either way multicast has to reach the LAN, which the Linux Compose topology
+provides through `network_mode: host`. Under `docker-compose.macos.yml` the
+container is bridged and multicast does not reach the LAN, so configure devices
+by IP there. The direct path sends on every active, non-loopback multicast
+interface. It supports IPv4 and IPv6; a link-local IPv6 answer is used only
+with its interface zone, and an unscoped link-local answer is discarded.
+
+mDNS has no built-in authentication. Treat a `.local` name as a LAN trust
+boundary, reserve names used by control drivers, and use TLS certificate pins
+where the driver supports them. Network allowlists still check the configured
+host name and port before resolution; they do not prove that an mDNS responder
+is the intended device.
+
+That risk is not unique to names, which is why the opt-in below gates the
+resolver rather than the connection. A raw IP address is no more an identity on
+a LAN than a name is — it can be claimed by ARP, and DHCP can hand it to a
+different device with no attacker involved at all. The durable check is the
+identity a device reports once connected: make and serial, or its MAC.
+
+So by default FTW does not use *its own* mDNS answer for a `.local` name: the
+name goes to the system resolver, exactly as it did before this package
+existed, and on platforms that answer `.local` themselves — Home Assistant does,
+through Supervisor's DNS service — it simply works. Opt in per driver to let FTW
+resolve the name itself, over Avahi or the LAN:
+
+```yaml
+capabilities:
+  allow_unverified_local: true
+  modbus:
+    host: inverter.local
+    port: 502
+```
+
+For the Home Assistant bridge, set `homeassistant.allow_unverified_local: true`
+instead. It applies to every transport — HTTP, WebSocket, MQTT, Modbus and raw
+TCP — and is per driver, so a name allowlist never becomes a server identity for
+another driver. Literal IP addresses and ordinary DNS names are untouched.
+
+Without it, a `.local` dial is not refused; it is handed to the system resolver,
+and the log records why FTW's own answer was not used. That matters on a host
+where nothing else resolves `.local` — a plain Compose or Raspberry Pi install,
+whose `resolv.conf` points at the router — because there the name will simply
+not resolve until you opt in.
+
+Note the limit of the gate: where an HTTP proxy is configured, FTW never
+resolves the destination at all, so the flag has nothing to say about that path.
+A TLS pin does not bypass the gate yet.
+
+#### Letting FTW use avahi
+
+Host networking shares ports, not Unix sockets, so avahi has to be bind-mounted
+in. `docker-compose.yml` carries the line commented out:
 
 ```yaml
     volumes:
-      - /run/avahi-daemon/socket:/run/avahi-daemon/socket:ro
+      - /run/avahi-daemon:/run/avahi-daemon:ro
 ```
 
-Only add this on a host that actually runs `avahi-daemon` — the Raspberry Pi
-image does. Without the daemon Docker creates a *directory* at that path, which
-resolves nothing and is harmless but confusing; `ls -l` there is the quickest
-way to tell the two apart.
+Mount the *directory*, not the socket file inside it. If the host path is
+missing Docker creates it, and an empty directory is harmless — whereas a
+directory created where the socket belongs stops `avahi-daemon` from ever
+starting. Restarting avahi detaches the mount, so restart FTW after you do.
+
+This is an optimisation, not a requirement: device connectivity is unchanged
+without it. It lets `getent hosts zap.local`, `curl` and `wget` check the name
+from inside the container.
 
-This makes the container's own tooling agree with the host. Whether the FTW
-process itself resolves a device's `.local` name is a separate question,
-answered by `internal/mdnsresolve`.
+Under the Home Assistant add-on none of this applies: Supervisor mounts only a
+fixed set of named paths, so the socket cannot be provided and FTW always
+queries the LAN directly. The add-on runs with `host_network: true`, which is
+what makes that work.
 
 ### Configuration rejected
 
diff --git a/docs/sourceful-zap.md b/docs/sourceful-zap.md
index 75f98d60..30121f2c 100644
--- a/docs/sourceful-zap.md
+++ b/docs/sourceful-zap.md
@@ -76,6 +76,15 @@ go test ./internal/drivers -run 'Zap|zap'
 
 - not found: confirm Zap is on Wi-Fi and reachable at
   `http://zap.local/api/system` from the FTW host;
+- `.local` name does not resolve: FTW resolves `.local` itself — via the host's
+  `avahi-daemon` where its socket is mounted, otherwise by querying the LAN —
+  rather than through the OS resolver, so it needs to be on the same L2 segment
+  as the device. That is the case with the Linux Compose topology
+  (`network_mode: host`); under `docker-compose.macos.yml` the container is
+  bridged and multicast does not reach the LAN, so configure the device by IP
+  there. The log line naming the failure is `mDNS resolution failed`, and a
+  successful lookup logs `via=avahi` or `via=multicast`; see
+  [docs/operations.md](operations.md);
 - no meter: inspect Zap's `/api/devices` and pin `meter_serial` when needed;
 - duplicate PV/battery: disable the overlapping Zap DER;
 - visible battery is not controlled: expected for the telemetry-only driver.
diff --git a/go/cmd/ftw/main.go b/go/cmd/ftw/main.go
index bda043da..00d8a38c 100644
--- a/go/cmd/ftw/main.go
+++ b/go/cmd/ftw/main.go
@@ -529,10 +529,10 @@ func main() {
 		}
 	}
 	reg.MQTTFactory = func(name string, c *config.MQTTConfig) (drivers.MQTTCap, error) {
-		return mqttcli.Dial(c.Host, c.Port, c.Username, c.Password, "ftw-"+name)
+		return mqttcli.DialWithOptions(c.Host, c.Port, c.Username, c.Password, "ftw-"+name, c.AllowUnverifiedLocal)
 	}
 	reg.ModbusFactory = func(name string, c *config.ModbusConfig) (drivers.ModbusCap, error) {
-		return modbuscli.Dial(c.Host, c.Port, c.UnitID)
+		return modbuscli.DialWithOptions(c.Host, c.Port, c.UnitID, c.AllowUnverifiedLocal)
 	}
 	reg.SerialFactory = func(name string, c *config.SerialConfig) (drivers.SerialCap, error) {
 		return drivers.OpenSerial(c)
diff --git a/go/internal/config/config.go b/go/internal/config/config.go
index 4e0c5f89..37ef7e8b 100644
--- a/go/internal/config/config.go
+++ b/go/internal/config/config.go
@@ -885,13 +885,17 @@ type DriverControlOptIn struct {
 
 // Capabilities explicitly scope what host resources a driver can access.
 type Capabilities struct {
-	MQTT       *MQTTConfig     `yaml:"mqtt,omitempty" json:"mqtt,omitempty"`
-	Modbus     *ModbusConfig   `yaml:"modbus,omitempty" json:"modbus,omitempty"`
-	Serial     *SerialConfig   `yaml:"serial,omitempty" json:"serial,omitempty"`
-	HTTP       *HTTPCapability `yaml:"http,omitempty" json:"http,omitempty"`
-	WebSocket  *WSCapability   `yaml:"websocket,omitempty" json:"websocket,omitempty"`
-	TCP        *TCPCapability  `yaml:"tcp,omitempty" json:"tcp,omitempty"`
-	Standalone bool            `yaml:"standalone,omitempty" json:"standalone,omitempty"`
+	// AllowUnverifiedLocal permits a driver to use an mDNS-resolved .local
+	// endpoint when the transport has no cryptographic server identity. The
+	// name allowlist is not identity, so the safe default is false.
+	AllowUnverifiedLocal bool            `yaml:"allow_unverified_local,omitempty" json:"allow_unverified_local,omitempty"`
+	MQTT                 *MQTTConfig     `yaml:"mqtt,omitempty" json:"mqtt,omitempty"`
+	Modbus               *ModbusConfig   `yaml:"modbus,omitempty" json:"modbus,omitempty"`
+	Serial               *SerialConfig   `yaml:"serial,omitempty" json:"serial,omitempty"`
+	HTTP                 *HTTPCapability `yaml:"http,omitempty" json:"http,omitempty"`
+	WebSocket            *WSCapability   `yaml:"websocket,omitempty" json:"websocket,omitempty"`
+	TCP                  *TCPCapability  `yaml:"tcp,omitempty" json:"tcp,omitempty"`
+	Standalone           bool            `yaml:"standalone,omitempty" json:"standalone,omitempty"`
 }
 
 // MQTTConfig grants access to one MQTT broker.
@@ -900,6 +904,10 @@ type MQTTConfig struct {
 	Port     int    `yaml:"port,omitempty" json:"port,omitempty"` // default 1883
 	Username string `yaml:"username,omitempty" json:"username,omitempty"`
 	Password string `yaml:"password,omitempty" json:"password,omitempty"`
+	// AllowUnverifiedLocal is copied from capabilities.allow_unverified_local
+	// by the core before this config reaches the transport factory. It is
+	// runtime-only and never comes from this nested YAML block.
+	AllowUnverifiedLocal bool `yaml:"-" json:"-"`
 }
 
 // ModbusConfig grants access to one Modbus TCP endpoint.
@@ -907,6 +915,10 @@ type ModbusConfig struct {
 	Host   string `yaml:"host" json:"host"`
 	Port   int    `yaml:"port,omitempty" json:"port,omitempty"`       // default 502
 	UnitID int    `yaml:"unit_id,omitempty" json:"unit_id,omitempty"` // default 1
+	// AllowUnverifiedLocal is copied from capabilities.allow_unverified_local
+	// by the core before this config reaches the transport factory. It is
+	// runtime-only and never comes from this nested YAML block.
+	AllowUnverifiedLocal bool `yaml:"-" json:"-"`
 }
 
 // SerialConfig grants read-only access to one local serial device.
@@ -986,6 +998,9 @@ type HomeAssistant struct {
 	Username         string `yaml:"username,omitempty" json:"username,omitempty"`
 	Password         string `yaml:"password,omitempty" json:"password,omitempty"`
 	PublishIntervalS int    `yaml:"publish_interval_s,omitempty" json:"publish_interval_s,omitempty"`
+	// AllowUnverifiedLocal permits the bridge to use an mDNS-resolved broker
+	// without a verified server identity. The default is fail-closed.
+	AllowUnverifiedLocal bool `yaml:"allow_unverified_local,omitempty" json:"allow_unverified_local,omitempty"`
 }
 
 // StateConf is the persistent state DB config.
diff --git a/go/internal/config/config_test.go b/go/internal/config/config_test.go
index d407d00d..fbfb2673 100644
--- a/go/internal/config/config_test.go
+++ b/go/internal/config/config_test.go
@@ -120,6 +120,50 @@ func TestLoadMinimalYAML(t *testing.T) {
 	}
 }
 
+func TestAllowUnverifiedLocalDefaultsDenyAndParsesExplicitOptIn(t *testing.T) {
+	cfg, err := Parse([]byte(minimalYAML), "/tmp")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Drivers[0].Capabilities.AllowUnverifiedLocal {
+		t.Fatal("allow_unverified_local must default to false")
+	}
+
+	withOptIn := strings.Replace(minimalYAML,
+		"capabilities:\n      mqtt:",
+		"capabilities:\n      allow_unverified_local: true\n      mqtt:", 1)
+	optedIn, err := Parse([]byte(withOptIn), "/tmp")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !optedIn.Drivers[0].Capabilities.AllowUnverifiedLocal {
+		t.Fatal("explicit allow_unverified_local=true was not retained")
+	}
+}
+
+func TestHomeAssistantAllowUnverifiedLocalDefaultsDeny(t *testing.T) {
+	base := minimalYAML + `
+homeassistant:
+  enabled: true
+  broker: broker.local
+`
+	cfg, err := Parse([]byte(base), "/tmp")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.HomeAssistant.AllowUnverifiedLocal {
+		t.Fatal("homeassistant allow_unverified_local must default to false")
+	}
+
+	optedIn, err := Parse([]byte(base+"  allow_unverified_local: true\n"), "/tmp")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !optedIn.HomeAssistant.AllowUnverifiedLocal {
+		t.Fatal("homeassistant explicit local opt-in was not retained")
+	}
+}
+
 func TestParseIgnoresRetiredRemoteAccessKeys(t *testing.T) {
 	legacy := minimalYAML + `
 remote_access:
diff --git a/go/internal/drivers/host.go b/go/internal/drivers/host.go
index ce304ce9..3daebb79 100644
--- a/go/internal/drivers/host.go
+++ b/go/internal/drivers/host.go
@@ -86,6 +86,10 @@ type HostEnv struct {
 	// backward compat with existing drivers that didn't declare a list.
 	// Populated from driver config `capabilities.http.allowed_hosts`.
 	HTTPAllowedHosts []string
+	// AllowUnverifiedLocal permits all this driver's mDNS-resolved .local
+	// transports. The name allowlist is not server identity; core keeps this
+	// false unless the operator explicitly opts in.
+	AllowUnverifiedLocal bool
 	// HTTPTLSPinSHA256, when non-empty, pins the HTTPS leaf certificate to
 	// this SHA-256 fingerprint (hex; colons/whitespace ignored, case-
 	// insensitive — same value as `openssl x509 -fingerprint -sha256`).
@@ -492,6 +496,12 @@ func (h *HostEnv) WithHTTPAllowedHosts(hosts []string) *HostEnv {
 	return h
 }
 
+// WithAllowUnverifiedLocal permits this driver's raw .local transports.
+func (h *HostEnv) WithAllowUnverifiedLocal() *HostEnv {
+	h.AllowUnverifiedLocal = true
+	return h
+}
+
 // WithHTTPTLSPin pins the HTTPS leaf certificate this driver's http_*
 // calls will accept, by SHA-256 fingerprint. Empty string = no pin
 // (standard system-root verification). See HostEnv.HTTPTLSPinSHA256.
diff --git a/go/internal/drivers/lua.go b/go/internal/drivers/lua.go
index d8ab865a..4e7045bf 100644
--- a/go/internal/drivers/lua.go
+++ b/go/internal/drivers/lua.go
@@ -69,6 +69,8 @@ import (
 	"time"
 
 	lua "github.com/yuin/gopher-lua"
+
+	"github.com/srcfl/ftw/go/internal/mdnsresolve"
 )
 
 // LuaDriver wraps a running Lua VM bound to a HostEnv.
@@ -609,6 +611,17 @@ func luaReturnError(name string, ret lua.LValue) error {
 
 // ---- host.* API exposed to Lua ----
 
+func newLuaHTTPTransport(allowUnverifiedLocal bool, proxy func(*net_http.Request) (*net_url.URL, error)) *net_http.Transport {
+	transport := net_http.DefaultTransport.(*net_http.Transport).Clone()
+	if proxy == nil {
+		proxy = transport.Proxy
+	}
+	transport.Proxy = proxy
+	mdnsDialer := mdnsresolve.Dialer{AllowUnverifiedLocal: allowUnverifiedLocal}
+	transport.DialContext = mdnsDialer.DialContext
+	return transport
+}
+
 func registerHost(L *lua.LState, env *HostEnv) {
 	host := L.NewTable()
 
@@ -1201,8 +1214,15 @@ func registerHost(L *lua.LState, env *HostEnv) {
 		return false, fmt.Sprintf("host %q (port %s) not in allowed_hosts", host, port)
 	}
 
+	// Drivers routinely address a device by its ".local" name, which the
+	// stdlib resolver cannot answer. Clone the default transport so proxying,
+	// HTTP/2 and connection pooling are all unchanged. Guard proxy selection
+	// as well as the dial step: net/http chooses a proxy before DialContext.
+	transport := newLuaHTTPTransport(env.AllowUnverifiedLocal, nil)
+
 	httpClient := &net_http.Client{
-		Timeout: 15 * time.Second,
+		Timeout:   15 * time.Second,
+		Transport: transport,
 		CheckRedirect: func(req *net_http.Request, via []*net_http.Request) error {
 			if len(via) >= 10 {
 				return fmt.Errorf("stopped after 10 redirects")
@@ -1228,10 +1248,13 @@ func registerHost(L *lua.LState, env *HostEnv) {
 	// endpoint with a self-signed cert (a NIBE heat pump's local REST API)
 	// without the SSRF-grade hole of blanket InsecureSkipVerify: a swapped
 	// cert (MITM) is rejected at the handshake even if it chains to a real
-	// CA. Drivers WITHOUT a pin keep Go's default transport untouched, so
-	// nothing about existing HTTP drivers changes.
+	// CA. Drivers WITHOUT a pin keep standard system-root certificate
+	// verification; the shared mDNS and proxy policy still applies.
 	if pin := tlsPin; pin != "" {
-		tr := net_http.DefaultTransport.(*net_http.Transport).Clone()
+		// Clone the transport built above so the pinned client keeps the same
+		// mDNS-aware dialer — a pinned device is usually a local appliance
+		// addressed by its ".local" name, which is exactly the case that needs it.
+		tr := transport.Clone()
 		tr.TLSClientConfig = &tls.Config{
 			// We replace chain/hostname verification with our own exact
 			// fingerprint check below, so the stdlib check must be off.
diff --git a/go/internal/drivers/lua_http_test.go b/go/internal/drivers/lua_http_test.go
index 42978fb7..31f08fd5 100644
--- a/go/internal/drivers/lua_http_test.go
+++ b/go/internal/drivers/lua_http_test.go
@@ -6,6 +6,7 @@ import (
 	"encoding/hex"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -197,6 +198,65 @@ func TestHTTPTestRigSelfCheck(t *testing.T) {
 	}
 }
 
+func TestLuaHTTPProxyChecksLocalDestinationBeforeProxy(t *testing.T) {
+	var proxyHits atomic.Int32
+	proxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		proxyHits.Add(1)
+		if r.URL.Host == "" {
+			t.Errorf("proxy request lost absolute destination: %+v", r.URL)
+		}
+		_, _ = w.Write([]byte("proxy-ok"))
+	}))
+	defer proxy.Close()
+	proxyURL, err := url.Parse(proxy.URL)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	newRequest := func(method, target string) *http.Request {
+		req, err := http.NewRequest(method, target, strings.NewReader(`{"command":"start"}`))
+		if err != nil {
+			t.Fatal(err)
+		}
+		req.Header.Set("Authorization", "Basic dTpw")
+		return req
+	}
+
+	t.Run("no opt-in still goes through the proxy", func(t *testing.T) {
+		// allow_unverified_local gates *our own* mDNS answer. With a proxy
+		// configured FTW never resolves the name at all — the proxy does — so
+		// the flag has nothing to say here and a .local host must behave like
+		// any other. Refusing would break Home Assistant, where the platform
+		// resolves .local and always has.
+		proxyHits.Store(0)
+		client := &http.Client{Transport: newLuaHTTPTransport(false, http.ProxyURL(proxyURL))}
+		for _, method := range []string{http.MethodGet, http.MethodPost, http.MethodPatch} {
+			resp, err := client.Do(newRequest(method, "http://inverter.local/api"))
+			if err != nil {
+				t.Errorf("%s failed: %v", method, err)
+				continue
+			}
+			_ = resp.Body.Close()
+		}
+		if got := proxyHits.Load(); got != 3 {
+			t.Fatalf(".local requests reached proxy %d times, want 3", got)
+		}
+	})
+
+	t.Run("ordinary host still uses the proxy without opt-in", func(t *testing.T) {
+		proxyHits.Store(0)
+		client := &http.Client{Transport: newLuaHTTPTransport(false, http.ProxyURL(proxyURL))}
+		resp, err := client.Do(newRequest(http.MethodGet, "http://ordinary.example/api"))
+		if err != nil {
+			t.Fatalf("ordinary host request failed: %v", err)
+		}
+		_ = resp.Body.Close()
+		if got := proxyHits.Load(); got != 1 {
+			t.Fatalf("ordinary host reached proxy %d times, want 1", got)
+		}
+	})
+}
+
 // TLS pinning lets a driver reach a self-signed HTTPS endpoint (e.g. a
 // NIBE heat pump's local REST API) by accepting exactly one leaf cert.
 // httptest.NewTLSServer mints a self-signed cert NOT in the system root
diff --git a/go/internal/drivers/registry.go b/go/internal/drivers/registry.go
index d465e9f9..848417d9 100644
--- a/go/internal/drivers/registry.go
+++ b/go/internal/drivers/registry.go
@@ -458,29 +458,33 @@ func (r *Registry) add(ctx context.Context, cfg config.Driver, startupDefault bo
 		return r.SecretPersister(driverName, key, value)
 	}
 	if mq := cfg.EffectiveMQTT(); mq != nil && r.MQTTFactory != nil {
-		cap, err := r.MQTTFactory(cfg.Name, mq)
+		dialCfg := *mq
+		dialCfg.AllowUnverifiedLocal = cfg.Capabilities.AllowUnverifiedLocal
+		cap, err := r.MQTTFactory(cfg.Name, &dialCfg)
 		if err != nil {
 			return fmt.Errorf("mqtt capability: %w", err)
 		}
 		env.WithMQTT(cap)
-		env.SetEndpoint(fmt.Sprintf("mqtt://%s:%d", mq.Host, mq.Port))
+		env.SetEndpoint(fmt.Sprintf("mqtt://%s:%d", dialCfg.Host, dialCfg.Port))
 		// Best-effort MAC resolution. Cross-VLAN devices return ""; that's
 		// fine — device_id falls back to the endpoint.
 		if r.ARPLookup != nil {
-			if mac, ok := r.ARPLookup(mq.Host); ok {
+			if mac, ok := r.ARPLookup(dialCfg.Host); ok {
 				env.SetMAC(mac)
 			}
 		}
 	}
 	if mb := cfg.EffectiveModbus(); mb != nil && r.ModbusFactory != nil {
-		cap, err := r.ModbusFactory(cfg.Name, mb)
+		dialCfg := *mb
+		dialCfg.AllowUnverifiedLocal = cfg.Capabilities.AllowUnverifiedLocal
+		cap, err := r.ModbusFactory(cfg.Name, &dialCfg)
 		if err != nil {
 			return fmt.Errorf("modbus capability: %w", err)
 		}
 		env.WithModbus(cap)
-		env.SetEndpoint(fmt.Sprintf("modbus://%s:%d", mb.Host, mb.Port))
+		env.SetEndpoint(fmt.Sprintf("modbus://%s:%d", dialCfg.Host, dialCfg.Port))
 		if r.ARPLookup != nil {
-			if mac, ok := r.ARPLookup(mb.Host); ok {
+			if mac, ok := r.ARPLookup(dialCfg.Host); ok {
 				env.SetMAC(mac)
 			}
 		}
@@ -519,8 +523,11 @@ func (r *Registry) add(ctx context.Context, cfg config.Driver, startupDefault bo
 			}
 		}
 	}
+	if cfg.Capabilities.AllowUnverifiedLocal {
+		env.WithAllowUnverifiedLocal()
+	}
 	if cfg.Capabilities.WebSocket != nil {
-		env.WithWS(NewGorillaWS(cfg.Name))
+		env.WithWS(NewGorillaWS(cfg.Name, cfg.Capabilities.AllowUnverifiedLocal))
 		if hosts := cfg.Capabilities.WebSocket.AllowedHosts; len(hosts) > 0 {
 			env.WithWSAllowedHosts(hosts)
 		}
@@ -534,7 +541,7 @@ func (r *Registry) add(ctx context.Context, cfg config.Driver, startupDefault bo
 		// the operator can still loosen this by listing bare hosts in
 		// capabilities.tcp.allowed_hosts when they want any-port access.
 		hosts := tcpAllowedHostsFor(cfg)
-		env.WithTCP(NewNetTCP(cfg.Name, hosts))
+		env.WithTCP(NewNetTCP(cfg.Name, hosts, cfg.Capabilities.AllowUnverifiedLocal))
 		if len(hosts) > 0 {
 			env.WithTCPAllowedHosts(hosts)
 		}
@@ -1464,6 +1471,7 @@ func sameDriverConfig(a, b config.Driver) bool {
 		a.BatteryTelemetryOnly != b.BatteryTelemetryOnly ||
 		a.ObserveOnly != b.ObserveOnly ||
 		a.Disabled != b.Disabled ||
+		a.Capabilities.AllowUnverifiedLocal != b.Capabilities.AllowUnverifiedLocal ||
 		!reflect.DeepEqual(a.Control, b.Control) {
 		return false
 	}
diff --git a/go/internal/drivers/registry_restart_test.go b/go/internal/drivers/registry_restart_test.go
index ed0865f1..0db8106a 100644
--- a/go/internal/drivers/registry_restart_test.go
+++ b/go/internal/drivers/registry_restart_test.go
@@ -1138,6 +1138,65 @@ func TestReloadRestartsDriversWhenTroubleshootingModeChanges(t *testing.T) {
 	}
 }
 
+func TestReloadRestartsDriverWhenTransportHostChangesToLocalName(t *testing.T) {
+	var dials atomic.Int32
+	r := NewRegistry(telemetry.NewStore())
+	r.ModbusFactory = func(name string, cfg *config.ModbusConfig) (ModbusCap, error) {
+		dials.Add(1)
+		return &mockModbus{}, nil
+	}
+	path := writeTestDriver(t, registryRestartTestDriver)
+	cfg := config.Driver{
+		Name: "d1",
+		Lua:  path,
+		Capabilities: config.Capabilities{
+			Modbus: &config.ModbusConfig{Host: "192.168.1.20", Port: 502, UnitID: 1},
+		},
+	}
+	if err := r.Add(context.Background(), cfg); err != nil {
+		t.Fatal(err)
+	}
+	defer r.ShutdownAll()
+	if got := dials.Load(); got != 1 {
+		t.Fatalf("initial Modbus factory calls = %d, want 1", got)
+	}
+
+	updated := cfg
+	updated.Capabilities.Modbus = &config.ModbusConfig{Host: "inverter.local", Port: 502, UnitID: 1}
+	r.Reload(context.Background(), []config.Driver{updated}, false)
+	if got := dials.Load(); got != 2 {
+		t.Fatalf("Modbus factory calls after .local reload = %d, want 2", got)
+	}
+}
+
+func TestReloadRestartsDriverWhenLocalTrustPolicyChanges(t *testing.T) {
+	var seen []bool
+	r := NewRegistry(telemetry.NewStore())
+	r.ModbusFactory = func(name string, cfg *config.ModbusConfig) (ModbusCap, error) {
+		seen = append(seen, cfg.AllowUnverifiedLocal)
+		return &mockModbus{}, nil
+	}
+	path := writeTestDriver(t, registryRestartTestDriver)
+	cfg := config.Driver{
+		Name: "d1",
+		Lua:  path,
+		Capabilities: config.Capabilities{
+			Modbus: &config.ModbusConfig{Host: "192.168.1.20", Port: 502, UnitID: 1},
+		},
+	}
+	if err := r.Add(context.Background(), cfg); err != nil {
+		t.Fatal(err)
+	}
+	defer r.ShutdownAll()
+
+	updated := cfg
+	updated.Capabilities.AllowUnverifiedLocal = true
+	r.Reload(context.Background(), []config.Driver{updated}, false)
+	if len(seen) != 2 || seen[0] || !seen[1] {
+		t.Fatalf("Modbus factory trust flags after reload = %v, want [false true]", seen)
+	}
+}
+
 // runLoop should bump TickCount on every poll-return-without-error so
 // a Lua driver that is alive but hasn't emitted yet (e.g. between
 // MQTT subscribe and the first inbound message) is visibly running
diff --git a/go/internal/drivers/tcp_cap.go b/go/internal/drivers/tcp_cap.go
index 4153f3cc..9f7f17e8 100644
--- a/go/internal/drivers/tcp_cap.go
+++ b/go/internal/drivers/tcp_cap.go
@@ -6,6 +6,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/srcfl/ftw/go/internal/mdnsresolve"
 )
 
 // TCPCap is the host's raw TCP socket capability. One driver = one upstream
@@ -33,21 +35,23 @@ type TCPCap interface {
 // background read pump that appends bytes to an in-memory buffer, and a
 // non-blocking PopBytes drain. Mirrors gorillaWS's concurrency model.
 type netTCP struct {
-	driverName string
-	allowed    []string // empty = any host
-
-	mu     sync.Mutex
-	conn   net.Conn
-	open   bool
-	buf    []byte
-	stop   chan struct{}
+	driverName           string
+	allowed              []string // empty = any host
+	allowUnverifiedLocal bool
+
+	mu   sync.Mutex
+	conn net.Conn
+	open bool
+	buf  []byte
+	stop chan struct{}
 }
 
 // NewNetTCP returns a TCPCap bound to a driver name. The connection is not
 // opened until the driver calls host.tcp_open.
-func NewNetTCP(driverName string, allowedHosts []string) TCPCap {
+func NewNetTCP(driverName string, allowedHosts []string, allowUnverifiedLocal ...bool) TCPCap {
 	cp := append([]string(nil), allowedHosts...)
-	return &netTCP{driverName: driverName, allowed: cp}
+	allow := len(allowUnverifiedLocal) > 0 && allowUnverifiedLocal[0]
+	return &netTCP{driverName: driverName, allowed: cp, allowUnverifiedLocal: allow}
 }
 
 // tcpHostAllowed checks `host:port` style addresses against the allowlist.
@@ -93,7 +97,7 @@ func (n *netTCP) Open(addr string) error {
 		return fmt.Errorf("tcp: %s", reason)
 	}
 
-	conn, err := net.DialTimeout("tcp", addr, 10*time.Second)
+	conn, err := mdnsresolve.DialTimeoutWithOptions("tcp", addr, 10*time.Second, n.allowUnverifiedLocal)
 	if err != nil {
 		return fmt.Errorf("tcp dial: %w", err)
 	}
diff --git a/go/internal/drivers/tcp_cap_test.go b/go/internal/drivers/tcp_cap_test.go
index ff5794a4..01e3627f 100644
--- a/go/internal/drivers/tcp_cap_test.go
+++ b/go/internal/drivers/tcp_cap_test.go
@@ -97,6 +97,18 @@ func TestTCPCap_AllowedHosts(t *testing.T) {
 	}
 }
 
+func TestTCPAllowlistMatchesLocalNameBeforeResolution(t *testing.T) {
+	if ok, reason := tcpHostAllowed("inverter.local:502", []string{"inverter.local:502"}); !ok || reason != "" {
+		t.Fatalf("matching .local allowlist = (%v, %q), want (true, empty)", ok, reason)
+	}
+	if ok, reason := tcpHostAllowed("inverter.local:502", []string{"other.local:502"}); ok || !strings.Contains(reason, "not in allowed_hosts") {
+		t.Fatalf("different .local allowlist = (%v, %q), want a pre-resolution rejection", ok, reason)
+	}
+	if ok, reason := tcpHostAllowed("inverter.local:1883", []string{"inverter.local:502"}); ok || !strings.Contains(reason, "not in allowed_hosts") {
+		t.Fatalf("wrong port for .local allowlist = (%v, %q), want rejection", ok, reason)
+	}
+}
+
 // TestTCPCap_StalePumpDoesNotClobberLiveState exercises the readPump→Close
 // race. We open against listener A, close, open against listener B, then
 // force A's accepted connection to drop. The stale pump for A wakes from
@@ -207,11 +219,11 @@ func (f *fakeTCPCap) Close() error { f.closed = true; return nil }
 
 // Synthetic DSMR 5.0 telegram body. Values chosen so we can pin every emit:
 //
-//   import 1.234 kW, export 0.500 kW   → meter.w = +734 W
-//   per-phase voltages 230.1 / 230.2 / 230.3 V
-//   per-phase currents 5 / 3 / 7 A
-//   import T1 100.000 kWh + T2 200.000 kWh → import_wh = 300_000
-//   export T1 10.000 kWh + T2 20.000 kWh → export_wh = 30_000
+//	import 1.234 kW, export 0.500 kW   → meter.w = +734 W
+//	per-phase voltages 230.1 / 230.2 / 230.3 V
+//	per-phase currents 5 / 3 / 7 A
+//	import T1 100.000 kWh + T2 200.000 kWh → import_wh = 300_000
+//	export T1 10.000 kWh + T2 20.000 kWh → export_wh = 30_000
 //
 // CRC is computed at runtime via dsmrCRC16; tests build the full telegram
 // with dsmrWrap() so they exercise the same CRC path the live meter does.
diff --git a/go/internal/drivers/ws_cap.go b/go/internal/drivers/ws_cap.go
index 979d5685..9823481e 100644
--- a/go/internal/drivers/ws_cap.go
+++ b/go/internal/drivers/ws_cap.go
@@ -9,6 +9,8 @@ import (
 	"time"
 
 	"github.com/gorilla/websocket"
+
+	"github.com/srcfl/ftw/go/internal/mdnsresolve"
 )
 
 // gorillaWS is the production WSCap implementation. One per driver.
@@ -23,12 +25,13 @@ import (
 // net.Conn close races a graceful WS close message — either path lands
 // the goroutine on a sane stop).
 type gorillaWS struct {
-	driverName string
+	driverName           string
+	allowUnverifiedLocal bool
 
-	mu     sync.Mutex // protects conn, open, queue
-	conn   *websocket.Conn
-	open   bool
-	queue  []string
+	mu      sync.Mutex // protects conn, open, queue
+	conn    *websocket.Conn
+	open    bool
+	queue   []string
 	writeMu sync.Mutex // serializes WriteMessage calls
 	stop    chan struct{}
 }
@@ -37,8 +40,21 @@ type gorillaWS struct {
 // until Open is called by the driver — drivers commonly need to do an
 // HTTP call (e.g. resolve a Tibber homeId) before they know what to
 // subscribe to, so connecting eagerly from the registry would be wrong.
-func NewGorillaWS(driverName string) WSCap {
-	return &gorillaWS{driverName: driverName}
+func NewGorillaWS(driverName string, allowUnverifiedLocal ...bool) WSCap {
+	allow := len(allowUnverifiedLocal) > 0 && allowUnverifiedLocal[0]
+	return &gorillaWS{driverName: driverName, allowUnverifiedLocal: allow}
+}
+
+func newGorillaWSDialer(allowUnverifiedLocal bool, proxy func(*net_http.Request) (*net_url.URL, error)) websocket.Dialer {
+	dialer := *websocket.DefaultDialer
+	dialer.HandshakeTimeout = 15 * time.Second
+	if proxy == nil {
+		proxy = dialer.Proxy
+	}
+	dialer.Proxy = proxy
+	mdnsDialer := mdnsresolve.Dialer{AllowUnverifiedLocal: allowUnverifiedLocal}
+	dialer.NetDialContext = mdnsDialer.DialContext
+	return dialer
 }
 
 // Open establishes the WebSocket connection. headers go into the HTTP
@@ -71,8 +87,10 @@ func (g *gorillaWS) Open(url string, headers map[string]string) error {
 		}
 		hdr.Set(k, v)
 	}
-	dialer := *websocket.DefaultDialer
-	dialer.HandshakeTimeout = 15 * time.Second
+	// ".local" hosts need mDNS; everything else falls through to a plain dial.
+	// Guard the proxy callback too: gorilla selects a proxy before it invokes
+	// NetDialContext.
+	dialer := newGorillaWSDialer(g.allowUnverifiedLocal, nil)
 	if len(subprotocols) > 0 {
 		dialer.Subprotocols = subprotocols
 	}
diff --git a/go/internal/drivers/ws_proxy_test.go b/go/internal/drivers/ws_proxy_test.go
new file mode 100644
index 00000000..2538a215
--- /dev/null
+++ b/go/internal/drivers/ws_proxy_test.go
@@ -0,0 +1,151 @@
+package drivers
+
+import (
+	"bufio"
+	"crypto/sha1"
+	"encoding/base64"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"sync/atomic"
+	"testing"
+	"time"
+
+)
+
+const websocketGUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+type wsTestProxy struct {
+	listener net.Listener
+	hits     atomic.Int32
+	hosts    chan string
+}
+
+func newWSTestProxy(t *testing.T) *wsTestProxy {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	p := &wsTestProxy{listener: listener, hosts: make(chan string, 8)}
+	t.Cleanup(func() { _ = listener.Close() })
+	go p.serve(t)
+	return p
+}
+
+func (p *wsTestProxy) serve(t *testing.T) {
+	t.Helper()
+	for {
+		conn, err := p.listener.Accept()
+		if err != nil {
+			return
+		}
+		go p.handle(conn)
+	}
+}
+
+func (p *wsTestProxy) handle(conn net.Conn) {
+	defer conn.Close()
+	reader := bufio.NewReader(conn)
+	connectReq, err := http.ReadRequest(reader)
+	if err != nil {
+		return
+	}
+	p.hits.Add(1)
+	p.hosts <- connectReq.Host
+	if connectReq.Method != http.MethodConnect {
+		return
+	}
+	_, _ = fmt.Fprint(conn, "HTTP/1.1 200 Connection Established\r\n\r\n")
+
+	upgradeReq, err := http.ReadRequest(reader)
+	if err != nil {
+		return
+	}
+	key := upgradeReq.Header.Get("Sec-WebSocket-Key")
+	sum := sha1.Sum([]byte(key + websocketGUID))
+	accept := base64.StdEncoding.EncodeToString(sum[:])
+	_, _ = fmt.Fprintf(conn,
+		"HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: %s\r\n\r\n",
+		accept,
+	)
+	// The client closes the connection after the handshake test. Keep the
+	// tunnel open until then so Gorilla can finish Dial successfully.
+	_, _ = reader.ReadByte()
+}
+
+func (p *wsTestProxy) proxyURL(t *testing.T) *url.URL {
+	t.Helper()
+	u, err := url.Parse("http://" + p.listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return u
+}
+
+func (p *wsTestProxy) nextHost(t *testing.T) string {
+	t.Helper()
+	select {
+	case host := <-p.hosts:
+		return host
+	case <-time.After(time.Second):
+		t.Fatal("proxy did not receive CONNECT")
+		return ""
+	}
+}
+
+// allow_unverified_local gates FTW's *own* mDNS answer. With a proxy
+// configured FTW never resolves the destination — the proxy does — so a
+// ".local" WebSocket takes the same path as any other host, with or without
+// the opt-in. Denying it would break Home Assistant, where the platform
+// resolves ".local" and always has.
+func TestGorillaWSLocalDestinationTakesTheProxyLikeAnyHost(t *testing.T) {
+	proxy := newWSTestProxy(t)
+	proxyURL := proxy.proxyURL(t)
+
+	t.Run("no opt-in still reaches the proxy", func(t *testing.T) {
+		dialer := newGorillaWSDialer(false, http.ProxyURL(proxyURL))
+		conn, _, err := dialer.Dial("ws://inverter.local/v1", nil)
+		if err != nil {
+			t.Fatalf("local WebSocket without opt-in failed: %v", err)
+		}
+		_ = conn.Close()
+		if got := proxy.hits.Load(); got != 1 {
+			t.Fatalf("local WebSocket reached proxy %d times, want 1", got)
+		}
+		if host := proxy.nextHost(t); host != "inverter.local:80" {
+			t.Fatalf("proxy CONNECT host = %q, want inverter.local:80", host)
+		}
+	})
+
+	t.Run("explicit opt-in uses the configured proxy", func(t *testing.T) {
+		dialer := newGorillaWSDialer(true, http.ProxyURL(proxyURL))
+		conn, _, err := dialer.Dial("ws://inverter.local/v1", nil)
+		if err != nil {
+			t.Fatalf("opt-in WebSocket failed: %v", err)
+		}
+		_ = conn.Close()
+		if got := proxy.hits.Load(); got != 2 {
+			t.Fatalf("opt-in local WebSocket reached proxy %d times, want 2", got)
+		}
+		if host := proxy.nextHost(t); host != "inverter.local:80" {
+			t.Fatalf("proxy CONNECT host = %q, want inverter.local:80", host)
+		}
+	})
+
+	t.Run("ordinary host still uses the proxy", func(t *testing.T) {
+		dialer := newGorillaWSDialer(false, http.ProxyURL(proxyURL))
+		conn, _, err := dialer.Dial("ws://ordinary.example/v1", nil)
+		if err != nil {
+			t.Fatalf("ordinary WebSocket failed: %v", err)
+		}
+		_ = conn.Close()
+		if got := proxy.hits.Load(); got != 3 {
+			t.Fatalf("ordinary WebSocket total proxy hits = %d, want 3", got)
+		}
+		if host := proxy.nextHost(t); host != "ordinary.example:80" {
+			t.Fatalf("proxy CONNECT host = %q, want ordinary.example:80", host)
+		}
+	})
+}
diff --git a/go/internal/ha/bridge.go b/go/internal/ha/bridge.go
index 04c288c2..8dde9a0a 100644
--- a/go/internal/ha/bridge.go
+++ b/go/internal/ha/bridge.go
@@ -12,6 +12,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"log/slog"
+	"net"
+	"net/url"
 	"sort"
 	"strconv"
 	"strings"
@@ -22,6 +24,7 @@ import (
 
 	"github.com/srcfl/ftw/go/internal/config"
 	"github.com/srcfl/ftw/go/internal/control"
+	"github.com/srcfl/ftw/go/internal/mdnsresolve"
 	"github.com/srcfl/ftw/go/internal/telemetry"
 )
 
@@ -249,6 +252,16 @@ func (b *Bridge) connectAndStart(cfg *config.HomeAssistant, driverNames []string
 
 	opts := paho.NewClientOptions().
 		AddBroker(fmt.Sprintf("tcp://%s:%d", cfg.Broker, cfg.Port)).
+		// A Home Assistant broker is very often reached as homeassistant.local,
+		// which the stdlib resolver cannot answer. See internal/mqtt for why a
+		// TCP-only replacement is complete here.
+		SetCustomOpenConnectionFn(func(uri *url.URL, o paho.ClientOptions) (net.Conn, error) {
+			d := mdnsresolve.Dialer{
+				Dialer:               net.Dialer{Timeout: o.ConnectTimeout},
+				AllowUnverifiedLocal: cfg.AllowUnverifiedLocal,
+			}
+			return d.Dial("tcp", uri.Host)
+		}).
 		SetClientID("forty-two-watts-ha").
 		SetAutoReconnect(true).
 		SetConnectRetry(true).
diff --git a/go/internal/mdnsresolve/avahi.go b/go/internal/mdnsresolve/avahi.go
new file mode 100644
index 00000000..c3c7f32f
--- /dev/null
+++ b/go/internal/mdnsresolve/avahi.go
@@ -0,0 +1,208 @@
+package mdnsresolve
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"net"
+	"net/netip"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// avahiSocket is avahi-daemon's simple-protocol socket. This is not a path we
+// invented: libnss_mdns4_minimal.so.2 has the same string compiled into it, so
+// asking here is exactly what `getent hosts foo.local` does one layer down.
+//
+// A var so tests can point at a socket they control.
+var avahiSocket = "/run/avahi-daemon/socket"
+
+// avahiDial is swappable in tests.
+var avahiDial = func(ctx context.Context, path string) (net.Conn, error) {
+	var d net.Dialer
+	return d.DialContext(ctx, "unix", path)
+}
+
+// avahiTTL is how long an avahi answer is cached here. The protocol carries no
+// TTL — avahi keeps its own record cache and re-queries the LAN when its copy
+// ages out, so this number only decides how often we ask it, not how fresh the
+// answer is. It matches the floor used for a raw multicast answer.
+const avahiTTL = minTTL
+
+// avahiAvailable reports whether the socket is present and is really a socket.
+//
+// The type check earns its place: the socket has to be bind-mounted into the
+// container, and when the host path does not exist Docker helpfully creates a
+// *directory* at the mount point instead. That looks present to a bare
+// os.Stat, connects to nothing, and is the single most likely misconfiguration
+// on this path.
+// A var so tests can assert both branches without needing a real socket on
+// whatever platform `go test` is running on.
+var avahiAvailable = func() bool {
+	fi, err := os.Stat(avahiSocket)
+	return err == nil && fi.Mode()&os.ModeSocket != 0
+}
+
+// avahiInterfaceByIndex is a var so tests can provide a stable interface name
+// for link-local IPv6 answers without depending on the host's interfaces.
+var avahiInterfaceByIndex = net.InterfaceByIndex
+
+type avahiResult struct {
+	addr netip.Addr
+	err  error
+}
+
+const (
+	avahiProtocolIPv4 = 0
+	avahiProtocolIPv6 = 1
+)
+
+// avahiLookup asks avahi-daemon to resolve name, preferring IPv4.
+//
+// The two address families are asked concurrently on separate connections
+// because a name that exists in one family and not the other costs a full
+// avahi resolve timeout to answer negatively — serialising them would put that
+// wait in front of every dial to a v4-only device. IPv4 is still the answer
+// preferred when both arrive.
+func avahiLookup(ctx context.Context, name string) ([]netip.Addr, error) {
+	v4 := make(chan avahiResult, 1)
+	v6 := make(chan avahiResult, 1)
+	lookupCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	go func() { v6 <- avahiResolve(lookupCtx, "RESOLVE-HOSTNAME-IPV6", name) }()
+	go func() { v4 <- avahiResolve(lookupCtx, "RESOLVE-HOSTNAME-IPV4", name) }()
+
+	var r4, r6 avahiResult
+	got4, got6 := false, false
+	for !got4 || !got6 {
+		select {
+		case r4 = <-v4:
+			got4 = true
+			if r4.err == nil {
+				// IPv4 is preferred, but wait for the cancelled IPv6
+				// exchange before returning so no goroutine can outlive
+				// this lookup or read test hooks during cleanup.
+				cancel()
+			}
+		case r6 = <-v6:
+			got6 = true
+			// Do not cancel IPv4 here. IPv4 is the preferred answer, so
+			// let an in-flight IPv4 request finish before accepting IPv6.
+		}
+	}
+	if r4.err == nil {
+		return []netip.Addr{r4.addr}, nil
+	}
+	if r6.err == nil {
+		return []netip.Addr{r6.addr}, nil
+	}
+	return nil, fmt.Errorf("avahi: %s: %w", name, r4.err)
+}
+
+// avahiResolve runs one request/response exchange over the socket.
+//
+// The wire format is a single line each way. A success is:
+//
+//	"+ <interface> <protocol> <name> <address>"
+//
+// and a failure is "- <errno> <message>". There is no framing, no length
+// prefix and nothing to decode, which is the point of using it: no DNS wire
+// format is parsed anywhere on this path.
+func avahiResolve(ctx context.Context, command, name string) avahiResult {
+	expectedProtocol, ok := avahiProtocolForCommand(command)
+	if !ok {
+		return avahiResult{err: fmt.Errorf("unsupported resolve command %q", command)}
+	}
+	conn, err := avahiDial(ctx, avahiSocket)
+	if err != nil {
+		return avahiResult{err: fmt.Errorf("connect %s: %w", avahiSocket, err)}
+	}
+	done := make(chan struct{})
+	defer close(done)
+	defer conn.Close()
+	go func() {
+		select {
+		case <-ctx.Done():
+			_ = conn.Close()
+		case <-done:
+		}
+	}()
+
+	if deadline, ok := ctx.Deadline(); ok {
+		_ = conn.SetDeadline(deadline)
+	}
+
+	if _, err := fmt.Fprintf(conn, "%s %s\n", command, name); err != nil {
+		return avahiResult{err: fmt.Errorf("write request: %w", err)}
+	}
+
+	scanner := bufio.NewScanner(conn)
+	if !scanner.Scan() {
+		if err := scanner.Err(); err != nil {
+			return avahiResult{err: fmt.Errorf("read reply: %w", err)}
+		}
+		return avahiResult{err: fmt.Errorf("no reply")}
+	}
+	return parseAvahiReply(scanner.Text(), name, expectedProtocol)
+}
+
+func avahiProtocolForCommand(command string) (int, bool) {
+	switch command {
+	case "RESOLVE-HOSTNAME-IPV4":
+		return avahiProtocolIPv4, true
+	case "RESOLVE-HOSTNAME-IPV6":
+		return avahiProtocolIPv6, true
+	default:
+		return 0, false
+	}
+}
+
+func parseAvahiReply(line, expectedName string, expectedProtocol int) avahiResult {
+	fields := strings.Fields(line)
+	if len(fields) == 0 {
+		return avahiResult{err: fmt.Errorf("empty reply")}
+	}
+	if fields[0] != "+" {
+		// "- 15 Timeout reached" and friends. Hand the daemon's own wording
+		// back rather than inventing one, so the log says what avahi said.
+		return avahiResult{err: fmt.Errorf("%s", strings.TrimSpace(strings.TrimPrefix(line, "-")))}
+	}
+	// + <interface> <protocol> <name> <address>
+	if len(fields) < 5 {
+		return avahiResult{err: fmt.Errorf("short reply %q", line)}
+	}
+	if expectedName != "" && canonical(fields[3]) != canonical(expectedName) {
+		return avahiResult{err: fmt.Errorf("reply name %q does not match %q", fields[3], expectedName)}
+	}
+	interfaceIndex, err := strconv.Atoi(fields[1])
+	if err != nil || interfaceIndex <= 0 {
+		return avahiResult{err: fmt.Errorf("unparsable interface %q", fields[1])}
+	}
+	protocol, err := strconv.Atoi(fields[2])
+	if err != nil {
+		return avahiResult{err: fmt.Errorf("unparsable protocol %q", fields[2])}
+	}
+	if protocol != expectedProtocol {
+		return avahiResult{err: fmt.Errorf("protocol %d does not match requested protocol %d", protocol, expectedProtocol)}
+	}
+	addr, err := netip.ParseAddr(fields[4])
+	if err != nil {
+		return avahiResult{err: fmt.Errorf("unparsable address %q", fields[4])}
+	}
+	if (addr.Is4() && protocol != 0) || (addr.Is6() && protocol != 1) {
+		return avahiResult{err: fmt.Errorf("protocol %d does not match address %s", protocol, addr)}
+	}
+	iface, err := avahiInterfaceByIndex(interfaceIndex)
+	if err != nil || iface == nil || iface.Name == "" || iface.Index != interfaceIndex ||
+		iface.Flags&net.FlagUp == 0 || iface.Flags&net.FlagMulticast == 0 || iface.Flags&net.FlagLoopback != 0 {
+		if err == nil {
+			err = fmt.Errorf("interface %d is unavailable or not multicast-capable", interfaceIndex)
+		}
+		return avahiResult{err: fmt.Errorf("interface %d: %w", interfaceIndex, err)}
+	}
+	if addr.Is6() && addr.IsLinkLocalUnicast() {
+		addr = addr.WithZone(iface.Name)
+	}
+	return avahiResult{addr: addr.Unmap()}
+}
diff --git a/go/internal/mdnsresolve/avahi_test.go b/go/internal/mdnsresolve/avahi_test.go
new file mode 100644
index 00000000..d788c3f9
--- /dev/null
+++ b/go/internal/mdnsresolve/avahi_test.go
@@ -0,0 +1,229 @@
+package mdnsresolve
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"io"
+	"net"
+	"net/netip"
+	"strings"
+	"testing"
+	"time"
+
+	"golang.org/x/net/dns/dnsmessage"
+)
+
+// fakeAvahi stands in for avahi-daemon. reply is handed the command and the
+// name and returns the line the daemon would write back; returning "" makes it
+// hang up without answering.
+//
+// net.Pipe rather than a real unix socket: the protocol is what is under test,
+// and the test then runs the same way on every platform the suite runs on.
+func fakeAvahi(t *testing.T, reply func(command, name string) string) {
+	t.Helper()
+	origAvail, origDial := avahiAvailable, avahiDial
+	origInterfaceByIndex := avahiInterfaceByIndex
+	avahiAvailable = func() bool { return true }
+	avahiInterfaceByIndex = func(index int) (*net.Interface, error) {
+		return &net.Interface{Index: index, Name: "test0", Flags: net.FlagUp | net.FlagMulticast}, nil
+	}
+	avahiDial = func(ctx context.Context, path string) (net.Conn, error) {
+		client, server := net.Pipe()
+		go func() {
+			defer server.Close()
+			sc := bufio.NewScanner(server)
+			if !sc.Scan() {
+				return
+			}
+			fields := strings.Fields(sc.Text())
+			if len(fields) < 2 {
+				return
+			}
+			if out := reply(fields[0], fields[1]); out != "" {
+				_, _ = io.WriteString(server, out+"\n")
+			}
+		}()
+		return client, nil
+	}
+	t.Cleanup(func() {
+		avahiAvailable, avahiDial = origAvail, origDial
+		avahiInterfaceByIndex = origInterfaceByIndex
+		Flush()
+	})
+}
+
+func TestParseAvahiReply(t *testing.T) {
+	cases := []struct {
+		name     string
+		line     string
+		protocol int
+		want     string // empty means the reply must be rejected
+	}{
+		// The exact shape avahi-daemon returns, confirmed against the daemon.
+		{"ipv4", "+ 2 0 zap.local 192.168.1.42", 0, "192.168.1.42"},
+		{"ipv6", "+ 2 1 zap.local fe80::1", 1, "fe80::1%test0"},
+		// A v4-mapped answer must dial as plain IPv4.
+		{"v4 mapped", "+ 2 1 zap.local ::ffff:192.168.1.42", 1, "192.168.1.42"},
+		{"wrong name", "+ 2 0 other.local 192.168.1.42", 0, ""},
+		{"nonnumeric interface", "+ eth0 0 zap.local 192.168.1.42", 0, ""},
+		{"ipv6 answer to ipv4 command", "+ 2 1 zap.local fe80::1", 0, ""},
+		{"ipv4 answer to ipv6 command", "+ 2 0 zap.local 192.168.1.42", 1, ""},
+		{"failure", "- 15 Timeout reached", 0, ""},
+		{"empty", "", 0, ""},
+		{"truncated", "+ 2 0 zap.local", 0, ""},
+		{"unparsable address", "+ 2 0 zap.local not-an-address", 0, ""},
+	}
+	origInterfaceByIndex := avahiInterfaceByIndex
+	avahiInterfaceByIndex = func(index int) (*net.Interface, error) {
+		return &net.Interface{Index: index, Name: "test0", Flags: net.FlagUp | net.FlagMulticast}, nil
+	}
+	t.Cleanup(func() { avahiInterfaceByIndex = origInterfaceByIndex })
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := parseAvahiReply(c.line, "zap.local", c.protocol)
+			if c.want == "" {
+				if got.err == nil {
+					t.Fatalf("accepted %q, got %v", c.line, got.addr)
+				}
+				return
+			}
+			if got.err != nil {
+				t.Fatalf("rejected %q: %v", c.line, got.err)
+			}
+			if got.addr.String() != c.want {
+				t.Fatalf("addr = %v, want %v", got.addr, c.want)
+			}
+		})
+	}
+}
+
+// A failure line must carry avahi's own wording, so the log says what the
+// daemon said rather than something this package made up.
+func TestParseAvahiReplyKeepsDaemonWording(t *testing.T) {
+	got := parseAvahiReply("- 15 Timeout reached", "zap.local", avahiProtocolIPv4)
+	if got.err == nil {
+		t.Fatal("expected an error")
+	}
+	if !strings.Contains(got.err.Error(), "Timeout reached") {
+		t.Fatalf("error %q dropped the daemon's message", got.err)
+	}
+}
+
+func TestLookupPrefersAvahi(t *testing.T) {
+	Flush()
+	fakeAvahi(t, func(command, name string) string {
+		if command == "RESOLVE-HOSTNAME-IPV4" && name == "inverter.local" {
+			return "+ 2 0 inverter.local 192.168.1.42"
+		}
+		return "- 15 Timeout reached"
+	})
+
+	orig := listenMulticastPacket
+	listenMulticastPacket = func(network string, iface *net.Interface, group *net.UDPAddr) (*net.UDPConn, error) {
+		t.Error("queried the LAN directly even though avahi answered")
+		return nil, errors.New("should not be called")
+	}
+	t.Cleanup(func() { listenMulticastPacket = orig })
+
+	addrs, err := Lookup(context.Background(), "inverter.local")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if len(addrs) != 1 || addrs[0] != netip.MustParseAddr("192.168.1.42") {
+		t.Fatalf("addrs = %v, want [192.168.1.42]", addrs)
+	}
+}
+
+// IPv4 wins when both families answer, so the address a device is dialled on
+// does not depend on which goroutine happened to finish first.
+func TestAvahiLookupPrefersIPv4(t *testing.T) {
+	fakeAvahi(t, func(command, name string) string {
+		if command == "RESOLVE-HOSTNAME-IPV6" {
+			return "+ 2 1 dual.local fe80::1"
+		}
+		return "+ 2 0 dual.local 192.168.1.7"
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	addrs, err := avahiLookup(ctx, "dual.local")
+	if err != nil {
+		t.Fatalf("avahiLookup: %v", err)
+	}
+	if len(addrs) != 1 || addrs[0] != netip.MustParseAddr("192.168.1.7") {
+		t.Fatalf("addrs = %v, want [192.168.1.7]", addrs)
+	}
+}
+
+// A device that only advertises IPv6 still resolves.
+func TestAvahiLookupFallsBackToIPv6(t *testing.T) {
+	fakeAvahi(t, func(command, name string) string {
+		if command == "RESOLVE-HOSTNAME-IPV6" {
+			return "+ 2 1 v6only.local fe80::2"
+		}
+		return "- 15 Timeout reached"
+	})
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	addrs, err := avahiLookup(ctx, "v6only.local")
+	if err != nil {
+		t.Fatalf("avahiLookup: %v", err)
+	}
+	if len(addrs) != 1 || addrs[0].String() != "fe80::2%test0" {
+		t.Fatalf("addrs = %v, want [fe80::2%%test0]", addrs)
+	}
+}
+
+// A socket that is present but unhelpful — daemon starting, wedged, or simply
+// without the record — must not be a dead end.
+func TestLookupFallsBackToMulticastWhenAvahiFails(t *testing.T) {
+	Flush()
+	fakeAvahi(t, func(command, name string) string { return "- 15 Timeout reached" })
+	startResponder(t, []dnsmessage.Resource{aResource(t, "inverter.local.", [4]byte{10, 0, 0, 5}, 60)})
+
+	addrs, err := Lookup(context.Background(), "inverter.local")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if len(addrs) != 1 || addrs[0] != netip.MustParseAddr("10.0.0.5") {
+		t.Fatalf("addrs = %v, want [10.0.0.5]", addrs)
+	}
+}
+
+// When neither backend answers, the error has to say that avahi was asked too
+// — "there is no avahi" and "avahi said no" call for different fixes.
+func TestLookupErrorNamesBothBackends(t *testing.T) {
+	Flush()
+	fakeAvahi(t, func(command, name string) string { return "- 15 Timeout reached" })
+	startResponder(t, nil) // never answers
+
+	ctx, cancel := context.WithTimeout(context.Background(), 150*time.Millisecond)
+	defer cancel()
+	_, err := Lookup(ctx, "missing.local")
+	if err == nil {
+		t.Fatal("expected a failure")
+	}
+	if !strings.Contains(err.Error(), "avahi") {
+		t.Fatalf("error %q does not mention avahi", err)
+	}
+}
+
+// A socket that does not exist must not be dialled at all: the probe is what
+// keeps a stray connect attempt out of every lookup on a host without avahi.
+func TestAvahiSkippedWhenSocketAbsent(t *testing.T) {
+	Flush()
+	origAvail, origDial := avahiAvailable, avahiDial
+	avahiAvailable = func() bool { return false }
+	avahiDial = func(ctx context.Context, path string) (net.Conn, error) {
+		t.Error("dialled the avahi socket although it is not available")
+		return nil, errors.New("should not be called")
+	}
+	t.Cleanup(func() { avahiAvailable, avahiDial = origAvail, origDial })
+
+	startResponder(t, []dnsmessage.Resource{aResource(t, "inverter.local.", [4]byte{10, 0, 0, 6}, 60)})
+	if _, err := Lookup(context.Background(), "inverter.local"); err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+}
diff --git a/go/internal/mdnsresolve/mdnsresolve.go b/go/internal/mdnsresolve/mdnsresolve.go
new file mode 100644
index 00000000..7c339b1a
--- /dev/null
+++ b/go/internal/mdnsresolve/mdnsresolve.go
@@ -0,0 +1,302 @@
+// Package mdnsresolve resolves RFC 6762 ".local" host names for outbound
+// connections, and provides a dialer that uses it.
+//
+// Go will not do this itself. net/conf.go routes a ".local" lookup to libc
+// only when cgo is available, and every FTW build sets CGO_ENABLED=0, so the
+// pure Go resolver is always selected: it reads /etc/resolv.conf and sends a
+// *unicast* query to the site router, which has no idea what "inverter.local"
+// is. That holds on every base image and every libc, glibc included — the
+// image shipping libnss-mdns changes what `getent` and `curl` can resolve
+// inside the container, not what this process can.
+//
+// # Where the answer comes from
+//
+// First choice is to ask the machine's own mDNS responder, avahi-daemon, over
+// its simple-protocol socket. One line out, one line back, no DNS wire format
+// decoded here — and it is the same daemon over the same socket that
+// libnss_mdns4_minimal.so.2 uses, so a name resolves to the same address
+// whether FTW dials it or an operator runs `getent hosts zap.local` in the
+// container. avahi also holds a record cache, so a repeat lookup usually costs
+// no LAN traffic at all.
+//
+// Second choice, in multicast.go, is to query the LAN directly. It exists
+// because the socket cannot always be reached: it has to be bind-mounted, and
+// under the Home Assistant Supervisor an add-on cannot mount arbitrary host
+// paths at all — only a fixed set of named ones. FTW ships as an add-on, so a
+// resolver that required that socket would simply not work there. The fallback
+// also covers any Docker host that does not run avahi.
+// Direct queries bind an ephemeral socket to every active, non-loopback
+// multicast interface. IPv4 and IPv6 are queried separately; IPv6 link-local
+// answers carry the interface zone and are rejected when no zone is known.
+//
+// Only ".local" names take either path. Literal IPs and ordinary DNS names are
+// handed straight to the standard dialer.
+package mdnsresolve
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"net/netip"
+	"strings"
+	"sync"
+	"time"
+)
+
+// ErrUnverifiedLocal is returned before any mDNS query when a caller has not
+// explicitly accepted that a .local name is not a server identity.
+var ErrUnverifiedLocal = errors.New("mDNS .local resolution requires allow_unverified_local=true")
+
+// now is swappable so cache-expiry tests do not have to sleep.
+var now = time.Now
+
+const (
+	// queryTimeout bounds each backend separately, so falling back costs at
+	// most two of these rather than an unbounded wait. It is long enough for a
+	// sleepy device and short enough that a driver dial does not stall a
+	// control tick.
+	queryTimeout = 900 * time.Millisecond
+
+	// A responder's TTL is advisory here. The floor stops a device that
+	// advertises a very short TTL from turning every Modbus reconnect into a
+	// multicast storm; the ceiling keeps a DHCP move from taking effect
+	// arbitrarily late, which is the whole point of binding by name.
+	minTTL = 30 * time.Second
+	maxTTL = 120 * time.Second
+
+	// negativeTTL is deliberately short: a device that was off when we first
+	// looked should become reachable soon after it boots.
+	negativeTTL = 5 * time.Second
+)
+
+type cacheEntry struct {
+	addrs   []netip.Addr // empty means a cached negative answer
+	expires time.Time
+}
+
+var (
+	cacheMu sync.Mutex
+	cache   = map[string]cacheEntry{}
+)
+
+// IsLocal reports whether host is a ".local" name that mDNS should resolve.
+// A literal IP is never one, so a configured "192.168.1.5" keeps the plain
+// dial path and never touches the network for resolution.
+func IsLocal(host string) bool {
+	if host == "" || net.ParseIP(host) != nil {
+		return false
+	}
+	return strings.HasSuffix(strings.ToLower(strings.TrimSuffix(host, ".")), ".local")
+}
+
+// CheckLocalDestination reports whether this caller may use FTW's own mDNS
+// answer for host. It gates the resolution path, not the connection: a caller
+// that has not opted in still reaches the name through the system resolver,
+// exactly as it did before this package existed.
+//
+// The distinction matters because the two are not the same risk. An mDNS
+// answer FTW obtained itself is a new, unverified input. A name the operating
+// system resolves is the status quo on every platform FTW ships to — and under
+// Home Assistant it is the only path there is, since Supervisor answers .local
+// through its own DNS service.
+func CheckLocalDestination(host string, allowUnverifiedLocal bool) error {
+	if IsLocal(host) && !allowUnverifiedLocal {
+		return fmt.Errorf("mDNS resolution for %s denied: %w", host, ErrUnverifiedLocal)
+	}
+	return nil
+}
+
+func canonical(name string) string {
+	return strings.ToLower(strings.TrimSuffix(name, "."))
+}
+
+func cacheLookup(key string) ([]netip.Addr, bool) {
+	cacheMu.Lock()
+	defer cacheMu.Unlock()
+	entry, ok := cache[key]
+	if !ok || now().After(entry.expires) {
+		return nil, false
+	}
+	return entry.addrs, true
+}
+
+func cacheStore(key string, addrs []netip.Addr, ttl time.Duration) {
+	cacheMu.Lock()
+	defer cacheMu.Unlock()
+	cache[key] = cacheEntry{addrs: addrs, expires: now().Add(ttl)}
+}
+
+// Flush drops every cached answer. Tests use it; nothing in production does.
+func Flush() {
+	cacheMu.Lock()
+	defer cacheMu.Unlock()
+	cache = map[string]cacheEntry{}
+}
+
+// Lookup resolves a ".local" name to its advertised addresses, asking
+// avahi-daemon first and the LAN directly if that is not answerable.
+func Lookup(ctx context.Context, name string) ([]netip.Addr, error) {
+	key := canonical(name)
+	if addrs, ok := cacheLookup(key); ok {
+		if len(addrs) == 0 {
+			return nil, fmt.Errorf("no mDNS responder for %s (cached)", name)
+		}
+		return addrs, nil
+	}
+
+	addrs, ttl, via, err := resolve(ctx, key)
+	if err != nil || len(addrs) == 0 {
+		cacheStore(key, nil, negativeTTL)
+		if err == nil {
+			err = fmt.Errorf("no mDNS responder for %s", name)
+		}
+		return nil, err
+	}
+
+	cacheStore(key, addrs, ttl)
+	// Logged on a cache miss only, so this is at most one line per TTL per
+	// device rather than one per reconnect. "via" is here because the two
+	// backends fail for completely different reasons, and an operator reading
+	// a support report needs to know which one was in play.
+	slog.Info("resolved host over mDNS", "host", key, "addr", addrs[0].String(), "ttl", ttl, "via", via)
+	return addrs, nil
+}
+
+// resolve tries avahi, then a direct query. An avahi socket that is present
+// but unhelpful still falls through: a daemon that is starting up, wedged or
+// misconfigured should degrade to a slower answer, not to no answer.
+func resolve(ctx context.Context, key string) ([]netip.Addr, time.Duration, string, error) {
+	var avahiErr error
+	if avahiAvailable() {
+		actx, cancel := context.WithTimeout(ctx, queryTimeout)
+		addrs, err := avahiLookup(actx, key)
+		cancel()
+		if err == nil && len(addrs) > 0 {
+			return addrs, avahiTTL, "avahi", nil
+		}
+		avahiErr = err
+	}
+
+	addrs, ttl, err := queryAddrs(ctx, key)
+	if err != nil && avahiErr != nil {
+		// Both were tried; report both, because "avahi said no and the LAN
+		// said nothing" and "there is no avahi and the LAN said nothing" call
+		// for different fixes.
+		return nil, 0, "", fmt.Errorf("%w (avahi: %v)", err, avahiErr)
+	}
+	if err != nil {
+		return nil, 0, "", err
+	}
+	return addrs, ttl, "multicast", nil
+}
+
+// Dialer dials TCP addresses, resolving ".local" host names over mDNS first.
+// The embedded net.Dialer carries timeout and keep-alive; anything that is not
+// a ".local" name is handed straight to it.
+//
+// Resolution happens per dial, not once at startup. That is what makes binding
+// a device by name survive a DHCP lease change: callers that rebuild their
+// connection from the original address string pick up the new IP on reconnect.
+type Dialer struct {
+	net.Dialer
+	// AllowUnverifiedLocal is a per-driver/core policy. Name allowlists do not
+	// prove which LAN host answered an mDNS query, so this stays false unless
+	// the operator explicitly accepts that trust model.
+	AllowUnverifiedLocal bool
+}
+
+// DialContext resolves address if it names a ".local" host, then dials it.
+func (d *Dialer) DialContext(ctx context.Context, network, address string) (net.Conn, error) {
+	host, port, err := net.SplitHostPort(address)
+	if err != nil || !IsLocal(host) {
+		return d.Dialer.DialContext(ctx, network, address)
+	}
+	if err := CheckLocalDestination(host, d.AllowUnverifiedLocal); err != nil {
+		// Not a refusal to connect — a refusal to trust *our* mDNS answer.
+		// The name still goes to the system resolver, which is what every
+		// shipped version of FTW does with it today, and what makes it work
+		// under Home Assistant. Denying it outright would break installs that
+		// work now, and would not buy the security it appears to: a raw IP is
+		// no more an identity on a LAN than a name is.
+		return d.systemFallback(ctx, network, address, err)
+	}
+
+	addrs, err := Lookup(ctx, host)
+	if err != nil {
+		// Name the mechanism. Without this the operator sees a bare dial
+		// failure and has no way to tell that resolution was the reason.
+		slog.Warn("mDNS resolution failed, falling back to the system resolver",
+			"host", host, "err", err)
+		return d.systemFallback(ctx, network, address, err)
+	}
+
+	var firstErr error
+	for _, a := range addrs {
+		conn, err := d.Dialer.DialContext(ctx, network, net.JoinHostPort(a.String(), port))
+		if err == nil {
+			return conn, nil
+		}
+		if firstErr == nil {
+			firstErr = err
+		}
+	}
+	return nil, fmt.Errorf("dial %s over mDNS: %w", host, firstErr)
+}
+
+// systemFallback hands a ".local" name that mDNS could not resolve to the
+// stdlib resolver.
+//
+// It exists because one supported platform already resolves these names
+// without us. Under Home Assistant the app has no avahi socket to ask, but
+// Supervisor points every container at its own CoreDNS, which carries an mdns
+// plugin backed by systemd-resolved — so `zap.local` resolves there today over
+// ordinary unicast DNS, verified on a pilot install running v1.10.0-beta.1:
+//
+//	lookup ftw-no-such-device-xyz.local on 172.30.32.3:53: no such host
+//
+// Returning the mDNS error instead of trying that resolver would take a
+// working install and break it. Both errors are reported when both paths fail,
+// because "no such host" alone sends an operator looking in the wrong place.
+func (d *Dialer) systemFallback(ctx context.Context, network, address string, mdnsErr error) (net.Conn, error) {
+	conn, err := d.Dialer.DialContext(ctx, network, address)
+	if err == nil {
+		return conn, nil
+	}
+	// Both causes are wrapped, not just formatted, so a caller can test for
+	// either with errors.Is — ErrUnverifiedLocal in particular.
+	return nil, fmt.Errorf("%w (mDNS: %w)", err, mdnsErr)
+}
+
+// Dial is the context-free form, for callers that have no context to pass.
+func (d *Dialer) Dial(network, address string) (net.Conn, error) {
+	ctx := context.Background()
+	if d.Timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, d.Timeout)
+		defer cancel()
+	}
+	return d.DialContext(ctx, network, address)
+}
+
+// DialContext dials with default settings.
+func DialContext(ctx context.Context, network, address string) (net.Conn, error) {
+	var d Dialer
+	return d.DialContext(ctx, network, address)
+}
+
+// DialTimeout mirrors net.DialTimeout with mDNS resolution added.
+func DialTimeout(network, address string, timeout time.Duration) (net.Conn, error) {
+	return DialTimeoutWithOptions(network, address, timeout, false)
+}
+
+// DialTimeoutWithOptions mirrors DialTimeout and carries the core's explicit
+// mDNS trust decision to the TCP capability.
+func DialTimeoutWithOptions(network, address string, timeout time.Duration, allowUnverifiedLocal bool) (net.Conn, error) {
+	d := Dialer{
+		Dialer:               net.Dialer{Timeout: timeout},
+		AllowUnverifiedLocal: allowUnverifiedLocal,
+	}
+	return d.Dial(network, address)
+}
diff --git a/go/internal/mdnsresolve/mdnsresolve_test.go b/go/internal/mdnsresolve/mdnsresolve_test.go
new file mode 100644
index 00000000..2630373e
--- /dev/null
+++ b/go/internal/mdnsresolve/mdnsresolve_test.go
@@ -0,0 +1,745 @@
+package mdnsresolve
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/netip"
+	"strings"
+	"testing"
+	"time"
+
+	"golang.org/x/net/dns/dnsmessage"
+)
+
+func TestIsLocal(t *testing.T) {
+	cases := []struct {
+		host string
+		want bool
+	}{
+		{"inverter.local", true},
+		{"INVERTER.LOCAL", true},
+		{"inverter.local.", true},
+		{"zap.local", true},
+		// A literal address must never trigger a lookup.
+		{"192.168.1.5", false},
+		{"::1", false},
+		{"example.com", false},
+		{"localhost", false},
+		{"local", false},
+		{"notlocal", false},
+		{"", false},
+	}
+	for _, c := range cases {
+		if got := IsLocal(c.host); got != c.want {
+			t.Errorf("IsLocal(%q) = %v, want %v", c.host, got, c.want)
+		}
+	}
+}
+
+func mustDNSName(t *testing.T, s string) dnsmessage.Name {
+	t.Helper()
+	n, err := dnsmessage.NewName(s)
+	if err != nil {
+		t.Fatalf("NewName(%q): %v", s, err)
+	}
+	return n
+}
+
+func aResource(t *testing.T, name string, ip [4]byte, ttl uint32) dnsmessage.Resource {
+	t.Helper()
+	return dnsmessage.Resource{
+		Header: dnsmessage.ResourceHeader{
+			Name: mustDNSName(t, name), Type: dnsmessage.TypeA,
+			Class: dnsmessage.ClassINET, TTL: ttl,
+		},
+		Body: &dnsmessage.AResource{A: ip},
+	}
+}
+
+func aaaaResource(t *testing.T, name string, ip [16]byte, ttl uint32) dnsmessage.Resource {
+	t.Helper()
+	return dnsmessage.Resource{
+		Header: dnsmessage.ResourceHeader{
+			Name: mustDNSName(t, name), Type: dnsmessage.TypeAAAA,
+			Class: dnsmessage.ClassINET, TTL: ttl,
+		},
+		Body: &dnsmessage.AAAAResource{AAAA: ip},
+	}
+}
+
+func packAnswer(t *testing.T, qname string, answers []dnsmessage.Resource) []byte {
+	t.Helper()
+	return packDNSMessage(t, dnsmessage.Header{Response: true, Authoritative: true},
+		[]dnsmessage.Question{{Name: mustDNSName(t, qname), Type: dnsmessage.TypeA, Class: dnsmessage.ClassINET}}, answers)
+}
+
+func packDNSMessage(t *testing.T, header dnsmessage.Header, questions []dnsmessage.Question, answers []dnsmessage.Resource) []byte {
+	t.Helper()
+	msg := dnsmessage.Message{Header: header, Questions: questions, Answers: answers}
+	packet, err := msg.Pack()
+	if err != nil {
+		t.Fatalf("pack: %v", err)
+	}
+	return packet
+}
+
+func parseTestAddrAnswer(t *testing.T, packet []byte, qname, network string) ([]netip.Addr, time.Duration, bool) {
+	t.Helper()
+	var sourceIP string
+	if network == "udp6" {
+		sourceIP = "2001:db8::1"
+	} else {
+		sourceIP = "192.0.2.1"
+	}
+	return parseAddrAnswer(packet, qname, &net.UDPAddr{
+		IP:   net.ParseIP(sourceIP),
+		Port: 5353,
+	}, network, &net.Interface{
+		Index: 1,
+		Name:  "test0",
+		Flags: net.FlagUp | net.FlagMulticast,
+	})
+}
+
+func TestParseAddrAnswerRequiresResponseBitButNotQuestion(t *testing.T) {
+	qname := "inverter.local."
+	answers := []dnsmessage.Resource{aResource(t, qname, [4]byte{192, 168, 1, 42}, 60)}
+
+	withoutQuestion := packDNSMessage(t, dnsmessage.Header{Response: true, Authoritative: true}, nil, answers)
+	if _, _, ok := parseTestAddrAnswer(t, withoutQuestion, qname, "udp4"); !ok {
+		t.Fatal("rejected a valid mDNS response without an echoed question")
+	}
+
+	query := packDNSMessage(t, dnsmessage.Header{Response: false}, nil, answers)
+	if _, _, ok := parseTestAddrAnswer(t, query, qname, "udp4"); ok {
+		t.Fatal("accepted a DNS query with answer records as an mDNS response")
+	}
+}
+
+func TestParseAddrAnswer(t *testing.T) {
+	qname := "inverter.local."
+	packet := packAnswer(t, qname, []dnsmessage.Resource{aResource(t, qname, [4]byte{192, 168, 1, 42}, 60)})
+
+	addrs, ttl, ok := parseTestAddrAnswer(t, packet, qname, "udp4")
+	if !ok {
+		t.Fatal("parseAddrAnswer did not accept a valid answer")
+	}
+	if len(addrs) != 1 || addrs[0].String() != "192.168.1.42" {
+		t.Fatalf("addrs = %v, want [192.168.1.42]", addrs)
+	}
+	if ttl != 60*time.Second {
+		t.Fatalf("ttl = %v, want 60s", ttl)
+	}
+
+	// An answer for a different name must be ignored.
+	if _, _, ok := parseTestAddrAnswer(t, packet, "other.local.", "udp4"); ok {
+		t.Fatal("accepted an answer for a different name")
+	}
+	// Garbage must not panic or resolve.
+	if _, _, ok := parseTestAddrAnswer(t, []byte{1, 2, 3}, qname, "udp4"); ok {
+		t.Fatal("accepted a malformed packet")
+	}
+}
+
+// A truncated record after a good one must void the whole packet. Keeping the
+// address read before the damage would let a malformed UDP response populate
+// the cache, and the parser has already lost sync at that point.
+func TestParseAddrAnswerRejectsPacketTruncatedAfterAGoodAnswer(t *testing.T) {
+	qname := "inverter.local."
+	packet := packAnswer(t, qname, []dnsmessage.Resource{
+		aResource(t, qname, [4]byte{192, 168, 1, 42}, 60),
+		aResource(t, qname, [4]byte{192, 168, 1, 43}, 60),
+	})
+
+	// Sanity check: intact, both answers are accepted.
+	if addrs, _, ok := parseTestAddrAnswer(t, packet, qname, "udp4"); !ok || len(addrs) != 2 {
+		t.Fatalf("intact packet: addrs = %v, ok = %v, want two addresses", addrs, ok)
+	}
+
+	// Cut into the final record's rdata: its header still parses, its body
+	// does not.
+	if _, _, ok := parseTestAddrAnswer(t, packet[:len(packet)-2], qname, "udp4"); ok {
+		t.Fatal("accepted a packet whose last matching record is truncated")
+	}
+}
+
+func TestParseAddrAnswerValidatesSourceFamilyAndClass(t *testing.T) {
+	qname := "inverter.local."
+	answer := aResource(t, qname, [4]byte{192, 168, 1, 42}, 60)
+	packet := packAnswer(t, qname, []dnsmessage.Resource{answer})
+	iface := &net.Interface{Index: 1, Name: "test0", Flags: net.FlagUp | net.FlagMulticast}
+
+	for _, tc := range []struct {
+		name    string
+		source  *net.UDPAddr
+		network string
+	}{
+		{"nil source", nil, "udp4"},
+		{"wrong source port", &net.UDPAddr{IP: net.ParseIP("192.0.2.1"), Port: 5354}, "udp4"},
+		{"wrong source family", &net.UDPAddr{IP: net.ParseIP("2001:db8::1"), Port: 5353}, "udp4"},
+		{"unspecified source", &net.UDPAddr{IP: net.ParseIP("0.0.0.0"), Port: 5353}, "udp4"},
+		{"multicast source", &net.UDPAddr{IP: net.ParseIP("224.0.0.251"), Port: 5353}, "udp4"},
+		{"wrong requested family", &net.UDPAddr{IP: net.ParseIP("192.0.2.1"), Port: 5353}, "udp6"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, _, ok := parseAddrAnswer(packet, qname, tc.source, tc.network, iface); ok {
+				t.Fatalf("accepted source=%v network=%s", tc.source, tc.network)
+			}
+		})
+	}
+
+	wrongClass := answer
+	wrongClass.Header.Class = dnsmessage.ClassCHAOS
+	if _, _, ok := parseTestAddrAnswer(t, packAnswer(t, qname, []dnsmessage.Resource{wrongClass}), qname, "udp4"); ok {
+		t.Fatal("accepted an A answer from the wrong DNS class")
+	}
+
+	cacheFlush := answer
+	cacheFlush.Header.Class |= classCacheFlush
+	if _, _, ok := parseTestAddrAnswer(t, packAnswer(t, qname, []dnsmessage.Resource{cacheFlush}), qname, "udp4"); !ok {
+		t.Fatal("rejected an IN answer carrying the mDNS cache-flush bit")
+	}
+}
+
+func TestParseAddrAnswerRejectsAnswerFromWrongFamily(t *testing.T) {
+	qname := "inverter.local."
+	iface := &net.Interface{Index: 1, Name: "test0", Flags: net.FlagUp | net.FlagMulticast}
+
+	ipv6 := packDNSMessage(t, dnsmessage.Header{Response: true}, nil, []dnsmessage.Resource{
+		aaaaResource(t, qname, [16]byte{0x20, 1, 0xdb, 8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1}, 60),
+	})
+	if _, _, ok := parseAddrAnswer(ipv6, qname, &net.UDPAddr{IP: net.ParseIP("192.0.2.1"), Port: 5353}, "udp4", iface); ok {
+		t.Fatal("accepted an IPv6 answer on the IPv4 query path")
+	}
+
+	ipv4 := packAnswer(t, qname, []dnsmessage.Resource{aResource(t, qname, [4]byte{192, 168, 1, 42}, 60)})
+	if _, _, ok := parseAddrAnswer(ipv4, qname, &net.UDPAddr{IP: net.ParseIP("2001:db8::1"), Port: 5353}, "udp6", iface); ok {
+		t.Fatal("accepted an IPv4 answer on the IPv6 query path")
+	}
+}
+
+func TestParseAddrAnswerClampsTTL(t *testing.T) {
+	qname := "inverter.local."
+	for _, c := range []struct {
+		name string
+		ttl  uint32
+		want time.Duration
+	}{
+		// A device advertising a 1 s TTL must not make every Modbus reconnect
+		// re-query the LAN.
+		{"below floor", 1, minTTL},
+		// A very long TTL must not outlive a DHCP move.
+		{"above ceiling", 86400, maxTTL},
+		{"inside range", 90, 90 * time.Second},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			packet := packAnswer(t, qname, []dnsmessage.Resource{aResource(t, qname, [4]byte{10, 0, 0, 1}, c.ttl)})
+			_, ttl, ok := parseTestAddrAnswer(t, packet, qname, "udp4")
+			if !ok {
+				t.Fatal("answer rejected")
+			}
+			if ttl != c.want {
+				t.Fatalf("ttl = %v, want %v", ttl, c.want)
+			}
+		})
+	}
+}
+
+func TestParseAddrAnswerUsesSelectedInterfaceForLinkLocalIPv6(t *testing.T) {
+	qname := "inverter.local."
+	packet := packAnswer(t, qname, []dnsmessage.Resource{
+		aaaaResource(t, qname, [16]byte{0xfe, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1}, 60),
+	})
+	source := &net.UDPAddr{IP: net.ParseIP("2001:db8::1"), Port: 5353}
+	if _, _, ok := parseAddrAnswer(packet, qname, source, "udp6", &net.Interface{
+		Index: 1,
+		Flags: net.FlagUp | net.FlagMulticast,
+	}); ok {
+		t.Fatal("accepted link-local IPv6 answer without a valid selected interface")
+	}
+	addrs, _, ok := parseTestAddrAnswer(t, packet, qname, "udp6")
+	if !ok || len(addrs) != 1 || addrs[0].String() != "fe80::1%test0" {
+		t.Fatalf("zoned answer = %v, ok=%v; want [fe80::1%%test0]", addrs, ok)
+	}
+}
+
+func TestQueryIPv6UsesSelectedInterfaceForLinkLocalAnswer(t *testing.T) {
+	qname := "inverter.local"
+	qnameWire := mustDNSName(t, qname+".")
+	queryMessage := dnsmessage.Message{Questions: []dnsmessage.Question{
+		{Name: qnameWire, Type: dnsmessage.TypeAAAA, Class: classQU},
+	}}
+	query, err := queryMessage.Pack()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	responder, err := net.ListenUDP("udp6", &net.UDPAddr{IP: net.ParseIP("::1"), Port: 0})
+	if err != nil {
+		t.Skipf("IPv6 loopback unavailable: %v", err)
+	}
+	defer responder.Close()
+	responseConn, err := net.ListenUDP("udp6", &net.UDPAddr{IP: net.ParseIP("::1"), Port: mdnsPort})
+	if err != nil {
+		t.Skipf("IPv6 mDNS response port unavailable: %v", err)
+	}
+	defer responseConn.Close()
+
+	origAddr, origInterfaces, origListen := mdnsAddr6, multicastInterfaces, listenMulticastPacket
+	mdnsAddr6 = responder.LocalAddr().(*net.UDPAddr)
+	multicastInterfaces = func() ([]net.Interface, error) {
+		return []net.Interface{{Index: 7, Name: "test0", Flags: net.FlagUp | net.FlagMulticast}}, nil
+	}
+	listenMulticastPacket = func(network string, iface *net.Interface, group *net.UDPAddr) (*net.UDPConn, error) {
+		if network != "udp6" || iface.Name != "test0" {
+			t.Fatalf("query used network=%q iface=%v", network, iface)
+		}
+		return net.ListenUDP("udp6", &net.UDPAddr{IP: net.ParseIP("::1")})
+	}
+	t.Cleanup(func() {
+		mdnsAddr6, multicastInterfaces, listenMulticastPacket = origAddr, origInterfaces, origListen
+	})
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		buf := make([]byte, 1500)
+		_ = responder.SetReadDeadline(time.Now().Add(2 * time.Second))
+		n, from, err := responder.ReadFromUDP(buf)
+		if err != nil {
+			return
+		}
+		var parser dnsmessage.Parser
+		header, err := parser.Start(buf[:n])
+		if err != nil {
+			return
+		}
+		question, err := parser.Question()
+		if err != nil {
+			return
+		}
+		responseMessage := dnsmessage.Message{
+			Header:    dnsmessage.Header{ID: header.ID, Response: true, Authoritative: true},
+			Questions: []dnsmessage.Question{question},
+			Answers:   []dnsmessage.Resource{aaaaResource(t, qname+".", [16]byte{0xfe, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1}, 60)},
+		}
+		response, err := responseMessage.Pack()
+		if err == nil {
+			_, _ = responseConn.WriteToUDP(response, from)
+		}
+	}()
+
+	addrs, _, err := queryIPv6(context.Background(), query, qname)
+	if err != nil {
+		t.Fatalf("queryIPv6: %v", err)
+	}
+	<-done
+	if len(addrs) != 1 || addrs[0].String() != "fe80::1%test0" {
+		t.Fatalf("addrs = %v, want [fe80::1%%test0]", addrs)
+	}
+}
+
+func TestEligibleMulticastInterfacesRejectsUnsafeChoices(t *testing.T) {
+	orig := multicastInterfaces
+	multicastInterfaces = func() ([]net.Interface, error) {
+		return []net.Interface{
+			{Index: 1, Name: "lo", Flags: net.FlagUp | net.FlagMulticast | net.FlagLoopback},
+			{Index: 2, Name: "down0", Flags: net.FlagMulticast},
+			{Index: 3, Name: "unicast0", Flags: net.FlagUp},
+			{Index: 4, Name: "lan0", Flags: net.FlagUp | net.FlagMulticast},
+		}, nil
+	}
+	t.Cleanup(func() { multicastInterfaces = orig })
+
+	got, err := eligibleMulticastInterfaces()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || got[0].Name != "lan0" {
+		t.Fatalf("eligible interfaces = %v, want [lan0]", got)
+	}
+}
+
+// disableAvahi forces the fallback path. Without it these tests would behave
+// differently on a developer machine that happens to run avahi-daemon.
+func disableAvahi(t *testing.T) {
+	t.Helper()
+	orig := avahiAvailable
+	avahiAvailable = func() bool { return false }
+	t.Cleanup(func() { avahiAvailable = orig })
+}
+
+// startResponder points the package at a loopback UDP socket that answers one
+// query, so the real send/parse path is exercised without touching the LAN.
+func startResponder(t *testing.T, answers []dnsmessage.Resource) {
+	t.Helper()
+	rc, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 0})
+	if err != nil {
+		t.Fatalf("listen responder: %v", err)
+	}
+	responseConn, err := net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: mdnsPort})
+	if err != nil {
+		_ = rc.Close()
+		t.Skipf("mDNS response port unavailable: %v", err)
+	}
+
+	origAddr, origMulticast, origInterfaces := mdnsAddr, listenMulticastPacket, multicastInterfaces
+	mdnsAddr = rc.LocalAddr().(*net.UDPAddr)
+	multicastInterfaces = func() ([]net.Interface, error) {
+		return []net.Interface{{Index: 1, Name: "test0", Flags: net.FlagUp | net.FlagMulticast}}, nil
+	}
+	listenMulticastPacket = func(network string, iface *net.Interface, group *net.UDPAddr) (*net.UDPConn, error) {
+		if network != "udp4" {
+			return nil, errors.New("IPv6 disabled in IPv4 responder test")
+		}
+		return net.ListenUDP("udp4", &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1)})
+	}
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		buf := make([]byte, 1500)
+		_ = rc.SetReadDeadline(time.Now().Add(2 * time.Second))
+		n, from, err := rc.ReadFromUDP(buf)
+		if err != nil {
+			return
+		}
+		if answers == nil {
+			return // silent responder: exercises the negative path
+		}
+		var p dnsmessage.Parser
+		hdr, err := p.Start(buf[:n])
+		if err != nil {
+			return
+		}
+		q, err := p.Question()
+		if err != nil {
+			return
+		}
+		resp := dnsmessage.Message{
+			Header:    dnsmessage.Header{ID: hdr.ID, Response: true, Authoritative: true},
+			Questions: []dnsmessage.Question{q},
+			Answers:   answers,
+		}
+		packed, err := resp.Pack()
+		if err != nil {
+			return
+		}
+		_, _ = responseConn.WriteToUDP(packed, from)
+	}()
+
+	t.Cleanup(func() {
+		_ = rc.Close()
+		<-done
+		_ = responseConn.Close()
+		mdnsAddr = origAddr
+		listenMulticastPacket, multicastInterfaces = origMulticast, origInterfaces
+		Flush()
+	})
+}
+
+func TestLookupResolvesLocalName(t *testing.T) {
+	Flush()
+	disableAvahi(t)
+	startResponder(t, []dnsmessage.Resource{aResource(t, "inverter.local.", [4]byte{192, 168, 1, 42}, 60)})
+
+	addrs, err := Lookup(context.Background(), "inverter.local")
+	if err != nil {
+		t.Fatalf("Lookup: %v", err)
+	}
+	if len(addrs) != 1 || addrs[0] != netip.MustParseAddr("192.168.1.42") {
+		t.Fatalf("addrs = %v, want [192.168.1.42]", addrs)
+	}
+
+	// The answer must now be cached: a second call cannot need the responder,
+	// which has already stopped.
+	again, err := Lookup(context.Background(), "INVERTER.local")
+	if err != nil {
+		t.Fatalf("cached Lookup: %v", err)
+	}
+	if len(again) != 1 || again[0] != addrs[0] {
+		t.Fatalf("cached addrs = %v, want %v", again, addrs)
+	}
+}
+
+func TestLookupCachesNegativeAnswer(t *testing.T) {
+	Flush()
+	disableAvahi(t)
+	startResponder(t, nil) // never answers
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	if _, err := Lookup(ctx, "missing.local"); err == nil {
+		t.Fatal("expected a lookup failure when nothing answers")
+	}
+
+	addrs, ok := cacheLookup("missing.local")
+	if !ok {
+		t.Fatal("a failed lookup should be negatively cached")
+	}
+	if len(addrs) != 0 {
+		t.Fatalf("negative cache holds %v, want no addresses", addrs)
+	}
+}
+
+func TestCacheExpires(t *testing.T) {
+	Flush()
+	base := time.Now()
+	orig := now
+	now = func() time.Time { return base }
+	t.Cleanup(func() { now = orig; Flush() })
+
+	cacheStore("inverter.local", []netip.Addr{netip.MustParseAddr("192.168.1.9")}, 30*time.Second)
+	if _, ok := cacheLookup("inverter.local"); !ok {
+		t.Fatal("entry should be live immediately after store")
+	}
+
+	now = func() time.Time { return base.Add(31 * time.Second) }
+	if _, ok := cacheLookup("inverter.local"); ok {
+		t.Fatal("entry should have expired")
+	}
+}
+
+func TestDialerSkipsResolutionForPlainHosts(t *testing.T) {
+	origAvail, origMulticast := avahiAvailable, listenMulticastPacket
+	listenMulticastPacket = func(network string, iface *net.Interface, group *net.UDPAddr) (*net.UDPConn, error) {
+		t.Error("issued an mDNS query for a host that is not a .local name")
+		return nil, errors.New("should not be called")
+	}
+	avahiAvailable = func() bool {
+		t.Error("consulted avahi for a host that is not a .local name")
+		return false
+	}
+	t.Cleanup(func() { avahiAvailable, listenMulticastPacket = origAvail, origMulticast })
+
+	d := Dialer{Dialer: net.Dialer{Timeout: 500 * time.Millisecond}}
+	// Nothing listens on port 1; the point is that the failure comes from the
+	// dial, not from resolution.
+	if _, err := d.Dial("tcp", "127.0.0.1:1"); err == nil {
+		t.Fatal("expected the dial to fail")
+	} else if strings.Contains(err.Error(), "mDNS") {
+		t.Fatalf("plain IP dial went through mDNS: %v", err)
+	}
+}
+
+// Without the opt-in, FTW must not use its *own* mDNS answer — but it must
+// still let the system resolver try the name. Refusing outright would break
+// Home Assistant, where Supervisor's DNS answers .local and always has.
+func TestDialerWithoutOptInIgnoresOurAnswerButStillResolves(t *testing.T) {
+	Flush()
+	listener, err := net.Listen("tcp4", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer listener.Close()
+	_, port, _ := net.SplitHostPort(listener.Addr().String())
+
+	// An avahi that would happily point at the live listener. A dialer without
+	// the opt-in must never reach it.
+	fakeAvahi(t, func(command, name string) string {
+		if command == "RESOLVE-HOSTNAME-IPV4" && name == "inverter.local" {
+			return "+ 2 0 inverter.local 127.0.0.1"
+		}
+		return "- 15 Timeout reached"
+	})
+
+	consulted := make(chan struct{}, 1)
+	d := Dialer{Dialer: net.Dialer{
+		Timeout: 500 * time.Millisecond,
+		Resolver: &net.Resolver{
+			PreferGo: true,
+			Dial: func(context.Context, string, string) (net.Conn, error) {
+				select {
+				case consulted <- struct{}{}:
+				default:
+				}
+				return nil, errors.New("no nameserver in this test")
+			},
+		},
+	}}
+
+	conn, err := d.Dial("tcp", "inverter.local:"+port)
+	if err == nil {
+		conn.Close()
+		t.Fatal("dialed our own mDNS answer without allow_unverified_local")
+	}
+	select {
+	case <-consulted:
+	default:
+		t.Fatal("the system resolver was never given the name")
+	}
+	// The reason we did not use our own answer has to survive into the error,
+	// or an operator cannot tell this from a device that is simply gone.
+	if !errors.Is(err, ErrUnverifiedLocal) {
+		t.Fatalf("error %v does not carry ErrUnverifiedLocal", err)
+	}
+}
+
+// With the opt-in, our own answer is used.
+func TestDialerWithOptInUsesOurAnswer(t *testing.T) {
+	Flush()
+	listener, err := net.Listen("tcp4", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer listener.Close()
+	_, port, _ := net.SplitHostPort(listener.Addr().String())
+
+	fakeAvahi(t, func(command, name string) string {
+		if command == "RESOLVE-HOSTNAME-IPV4" && name == "inverter.local" {
+			return "+ 2 0 inverter.local 127.0.0.1"
+		}
+		return "- 15 Timeout reached"
+	})
+
+	d := Dialer{AllowUnverifiedLocal: true, Dialer: net.Dialer{Timeout: time.Second}}
+	conn, err := d.Dial("tcp", "inverter.local:"+port)
+	if err != nil {
+		t.Fatalf("dial with opt-in: %v", err)
+	}
+	conn.Close()
+}
+
+func TestDialerLeavesOrdinaryDNSAndIPUnchanged(t *testing.T) {
+	listener, err := net.Listen("tcp4", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer listener.Close()
+	_, port, err := net.SplitHostPort(listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	accepted := make(chan struct{}, 2)
+	go func() {
+		for range 2 {
+			conn, err := listener.Accept()
+			if err != nil {
+				return
+			}
+			accepted <- struct{}{}
+			_ = conn.Close()
+		}
+	}()
+
+	for _, address := range []string{"127.0.0.1:" + port, "localhost:" + port} {
+		conn, err := (&Dialer{}).Dial("tcp4", address)
+		if err != nil {
+			t.Fatalf("Dial(%q): %v", address, err)
+		}
+		_ = conn.Close()
+	}
+	for range 2 {
+		select {
+		case <-accepted:
+		case <-time.After(time.Second):
+			t.Fatal("ordinary DNS/IP dial was not accepted")
+		}
+	}
+}
+
+func TestDialerResolvesLocalNameBeforeConnecting(t *testing.T) {
+	listener, err := net.Listen("tcp4", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer listener.Close()
+	_, port, err := net.SplitHostPort(listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	accepted := make(chan struct{})
+	go func() {
+		conn, err := listener.Accept()
+		if err == nil {
+			close(accepted)
+			_ = conn.Close()
+		}
+	}()
+	fakeAvahi(t, func(command, name string) string {
+		if command == "RESOLVE-HOSTNAME-IPV4" && name == "inverter.local" {
+			return "+ 2 0 inverter.local 127.0.0.1"
+		}
+		return "- 15 Timeout reached"
+	})
+
+	d := Dialer{
+		Dialer:               net.Dialer{Timeout: time.Second},
+		AllowUnverifiedLocal: true,
+	}
+	conn, err := d.Dial("tcp", "inverter.local:"+port)
+	if err != nil {
+		t.Fatalf("Dial: %v", err)
+	}
+	_ = conn.Close()
+	select {
+	case <-accepted:
+	case <-time.After(time.Second):
+		t.Fatal("resolved TCP endpoint was not reached")
+	}
+}
+
+func TestDialerReportsResolutionFailure(t *testing.T) {
+	Flush()
+	disableAvahi(t)
+	startResponder(t, nil) // never answers
+
+	d := Dialer{Dialer: net.Dialer{Timeout: 100 * time.Millisecond}}
+	_, err := d.Dial("tcp", "missing.local:502")
+	if err == nil {
+		t.Fatal("expected a failure")
+	}
+	// The error must name the mechanism — an operator reading the log has to be
+	// able to tell resolution apart from an unreachable device.
+	if !strings.Contains(err.Error(), "mDNS") {
+		t.Fatalf("error %q does not mention mDNS", err)
+	}
+}
+
+// A ".local" name we cannot resolve must still be offered to the system
+// resolver. Home Assistant is the case that makes this mandatory: the app has
+// no avahi socket, but Supervisor's CoreDNS answers ".local" over unicast DNS,
+// so failing here would break an install that works today.
+func TestDialerFallsBackToSystemResolver(t *testing.T) {
+	Flush()
+	disableAvahi(t)
+	// No usable interface fails the multicast path immediately, without
+	// binding a socket — startResponder needs port 5353, which some hosts
+	// refuse outright.
+	origInterfaces := multicastInterfaces
+	multicastInterfaces = func() ([]net.Interface, error) { return nil, nil }
+	t.Cleanup(func() { multicastInterfaces = origInterfaces })
+
+	consulted := make(chan struct{}, 1)
+	d := Dialer{AllowUnverifiedLocal: true, Dialer: net.Dialer{
+		Timeout: 500 * time.Millisecond,
+		Resolver: &net.Resolver{
+			PreferGo: true,
+			Dial: func(context.Context, string, string) (net.Conn, error) {
+				select {
+				case consulted <- struct{}{}:
+				default:
+				}
+				return nil, errors.New("no nameserver in this test")
+			},
+		},
+	}}
+
+	_, err := d.Dial("tcp", "missing.local:502")
+	if err == nil {
+		t.Fatal("expected a failure")
+	}
+	select {
+	case <-consulted:
+	default:
+		t.Fatal("system resolver was never consulted after mDNS failed")
+	}
+	// Both failures have to survive into the message. "no such host" on its own
+	// sends an operator looking for a DNS problem that isn't there.
+	if !strings.Contains(err.Error(), "mDNS:") {
+		t.Fatalf("error %q drops the mDNS cause", err)
+	}
+}
diff --git a/go/internal/mdnsresolve/multicast.go b/go/internal/mdnsresolve/multicast.go
new file mode 100644
index 00000000..9529c8a5
--- /dev/null
+++ b/go/internal/mdnsresolve/multicast.go
@@ -0,0 +1,415 @@
+package mdnsresolve
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/netip"
+	"strings"
+	"time"
+
+	"golang.org/x/net/dns/dnsmessage"
+)
+
+// This file is the fallback described in the package comment: a direct RFC
+// 6762 query, used only where avahi-daemon's socket cannot be reached. It is
+// deliberately the second choice — see avahi.go for the first.
+
+const mdnsPort = 5353
+
+// mdnsAddr is the RFC 6762 IPv4 multicast group. A var, not a const, so tests
+// can aim a query at a loopback responder.
+var mdnsAddr = &net.UDPAddr{IP: net.IPv4(224, 0, 0, 251), Port: mdnsPort}
+
+// mdnsAddr6 is the RFC 6762 IPv6 multicast group. The interface zone is added
+// to a copy for each query because ff02::fb is link-local by definition.
+var mdnsAddr6 = &net.UDPAddr{IP: net.ParseIP("ff02::fb"), Port: mdnsPort}
+
+// multicastInterfaces and listenMulticastPacket are vars so tests can select
+// a stable interface and responder without touching the host LAN.
+var multicastInterfaces = net.Interfaces
+
+// listenMulticastPacket opens an ephemeral socket on one selected interface.
+// It deliberately does not bind port 5353: avahi-daemon may already own it,
+// and the QU bit asks responders to reply directly to this socket instead.
+var listenMulticastPacket = func(network string, iface *net.Interface, group *net.UDPAddr) (*net.UDPConn, error) {
+	return net.ListenMulticastUDP(network, iface, &net.UDPAddr{
+		IP:   group.IP,
+		Port: 0,
+		Zone: group.Zone,
+	})
+}
+
+// classQU is IN with the RFC 6762 unicast-response bit set.
+const classQU = dnsmessage.Class(0x8001)
+
+// mDNS answer classes may carry the cache-flush bit in the high bit. It is a
+// record flag, not a different DNS class.
+const classCacheFlush = dnsmessage.Class(0x8000)
+
+func queryAddrs(ctx context.Context, name string) ([]netip.Addr, time.Duration, error) {
+	qname, err := dnsmessage.NewName(name + ".")
+	if err != nil {
+		return nil, 0, fmt.Errorf("mdns: bad name %q: %w", name, err)
+	}
+	// One packet, two questions. RFC 6762 §5.2 allows it and it saves a round
+	// trip on dual-stack devices.
+	msg := dnsmessage.Message{Questions: []dnsmessage.Question{
+		{Name: qname, Type: dnsmessage.TypeA, Class: classQU},
+		{Name: qname, Type: dnsmessage.TypeAAAA, Class: classQU},
+	}}
+	packed, err := msg.Pack()
+	if err != nil {
+		return nil, 0, fmt.Errorf("mdns: pack query: %w", err)
+	}
+
+	lookupCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	type result struct {
+		family int
+		addrs  []netip.Addr
+		ttl    time.Duration
+		err    error
+	}
+	results := make(chan result, 2)
+	go func() {
+		addrs, ttl, err := queryIPv4(lookupCtx, packed, name)
+		results <- result{family: 4, addrs: addrs, ttl: ttl, err: err}
+	}()
+	go func() {
+		addrs, ttl, err := queryIPv6(lookupCtx, packed, name)
+		results <- result{family: 6, addrs: addrs, ttl: ttl, err: err}
+	}()
+
+	var v4, v6 result
+	for i := 0; i < 2; i++ {
+		got := <-results
+		if got.family == 4 {
+			v4 = got
+		} else {
+			v6 = got
+		}
+		if got.family == 4 && got.err == nil && len(got.addrs) > 0 {
+			// One family is enough to dial the device. Cancel the other
+			// family, then still collect its result before returning so no
+			// query goroutine outlives this lookup. Do not cancel on IPv6
+			// first: IPv4 remains the preferred address family.
+			cancel()
+		}
+	}
+
+	addrs := appendUnique(nil, v4.addrs...)
+	addrs = appendUnique(addrs, v6.addrs...)
+	if len(addrs) == 0 {
+		return nil, 0, fmt.Errorf("mdns: no usable answer (IPv4: %v; IPv6: %v)", v4.err, v6.err)
+	}
+	ttl := minAnswerTTL(v4.ttl, v6.ttl)
+	return addrs, ttl, nil
+}
+
+func queryIPv4(ctx context.Context, packed []byte, name string) ([]netip.Addr, time.Duration, error) {
+	ifaces, err := eligibleMulticastInterfaces()
+	if err != nil {
+		return nil, 0, fmt.Errorf("mdns: list IPv4 multicast interfaces: %w", err)
+	}
+	return queryInterfaces(ctx, packed, name, ifaces, "udp4", mdnsAddr, "")
+}
+
+func queryIPv6(ctx context.Context, packed []byte, name string) ([]netip.Addr, time.Duration, error) {
+	ifaces, err := eligibleMulticastInterfaces()
+	if err != nil {
+		return nil, 0, fmt.Errorf("mdns: list IPv6 multicast interfaces: %w", err)
+	}
+	return queryInterfaces(ctx, packed, name, ifaces, "udp6", mdnsAddr6, "interface")
+}
+
+func eligibleMulticastInterfaces() ([]net.Interface, error) {
+	ifaces, err := multicastInterfaces()
+	if err != nil {
+		return nil, err
+	}
+	eligible := make([]net.Interface, 0, len(ifaces))
+	for _, iface := range ifaces {
+		if !validMulticastInterface(&iface) {
+			continue
+		}
+		eligible = append(eligible, iface)
+	}
+	if len(eligible) == 0 {
+		return nil, fmt.Errorf("no active non-loopback multicast interface")
+	}
+	return eligible, nil
+}
+
+func validMulticastInterface(iface *net.Interface) bool {
+	return iface != nil && iface.Index > 0 && iface.Name != "" &&
+		iface.Flags&net.FlagUp != 0 && iface.Flags&net.FlagMulticast != 0 &&
+		iface.Flags&net.FlagLoopback == 0
+}
+
+func queryInterfaces(ctx context.Context, packed []byte, name string, ifaces []net.Interface, network string, group *net.UDPAddr, zoneMode string) ([]netip.Addr, time.Duration, error) {
+	if len(ifaces) == 0 {
+		return nil, 0, fmt.Errorf("no multicast interface")
+	}
+	type result struct {
+		addrs []netip.Addr
+		ttl   time.Duration
+		err   error
+	}
+	queryCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+	results := make(chan result, len(ifaces))
+	for _, iface := range ifaces {
+		iface := iface
+		go func() {
+			target := *group
+			if zoneMode == "interface" && target.IP.IsLinkLocalMulticast() {
+				target.Zone = iface.Name
+			}
+			_, _, err := exchange(queryCtx, packed, &target, func() (*net.UDPConn, error) {
+				return listenMulticastPacket(network, &iface, &target)
+			}, func(packet []byte, source *net.UDPAddr) bool {
+				got, gotTTL, ok := parseAddrAnswer(packet, name+".", source, network, &iface)
+				if !ok {
+					return false
+				}
+				results <- result{addrs: got, ttl: gotTTL}
+				return true
+			})
+			if err != nil {
+				results <- result{err: err}
+			}
+		}()
+	}
+
+	var (
+		addrs    []netip.Addr
+		ttl      time.Duration
+		firstErr error
+	)
+	for i := 0; i < len(ifaces); i++ {
+		got := <-results
+		if got.err != nil {
+			if firstErr == nil {
+				firstErr = got.err
+			}
+			continue
+		}
+		addrs = appendUnique(addrs, got.addrs...)
+		ttl = minAnswerTTL(ttl, got.ttl)
+		if len(got.addrs) > 0 {
+			cancel()
+		}
+	}
+	if len(addrs) == 0 {
+		if firstErr == nil {
+			firstErr = fmt.Errorf("no usable answer")
+		}
+		return nil, 0, firstErr
+	}
+	return addrs, ttl, nil
+}
+
+// exchange sends one multicast query and feeds every reply to handle until it
+// accepts one or the deadline passes. Closing the socket on context cancel is
+// important: a cancelled family/interface query must not linger until the
+// original read deadline.
+func exchange(ctx context.Context, packed []byte, target *net.UDPAddr, open func() (*net.UDPConn, error), handle func([]byte, *net.UDPAddr) bool) ([]netip.Addr, time.Duration, error) {
+	conn, err := open()
+	if err != nil {
+		return nil, 0, fmt.Errorf("mdns: open socket: %w", err)
+	}
+	done := make(chan struct{})
+	defer close(done)
+	defer conn.Close()
+	go func() {
+		select {
+		case <-ctx.Done():
+			_ = conn.Close()
+		case <-done:
+		}
+	}()
+
+	deadline := now().Add(queryTimeout)
+	if d, ok := ctx.Deadline(); ok && d.Before(deadline) {
+		deadline = d
+	}
+	if err := conn.SetDeadline(deadline); err != nil {
+		return nil, 0, fmt.Errorf("mdns: set deadline: %w", err)
+	}
+	if _, err := conn.WriteToUDP(packed, target); err != nil {
+		return nil, 0, fmt.Errorf("mdns: send query: %w", err)
+	}
+
+	buf := make([]byte, 1500)
+	for {
+		n, source, err := conn.ReadFromUDP(buf)
+		if err != nil {
+			return nil, 0, fmt.Errorf("mdns: no usable answer: %w", err)
+		}
+		if handle(buf[:n], source) {
+			// The callback stores the parsed answer in its closure. The
+			// caller only needs the success signal here.
+			return nil, 0, nil
+		}
+	}
+}
+
+func parseAddrAnswer(packet []byte, qname string, source *net.UDPAddr, network string, iface *net.Interface) ([]netip.Addr, time.Duration, bool) {
+	if !validMulticastInterface(iface) || !validMDNSSource(source, network, iface) {
+		return nil, 0, false
+	}
+	var p dnsmessage.Parser
+	header, err := p.Start(packet)
+	if err != nil || !header.Response || header.RCode != dnsmessage.RCodeSuccess {
+		return nil, 0, false
+	}
+	if err := p.SkipAllQuestions(); err != nil {
+		return nil, 0, false
+	}
+	var addrs []netip.Addr
+	ttl := maxTTL
+	// A malformed record abandons the whole packet rather than keeping the
+	// addresses read before it: once the parser desynchronises, nothing after
+	// that point is trustworthy, and a truncated answer must not be allowed to
+	// populate the cache. The label is only the normal end-of-section exit.
+parse:
+	for {
+		h, err := p.AnswerHeader()
+		if err != nil {
+			if err == dnsmessage.ErrSectionDone {
+				break parse
+			}
+			return nil, 0, false
+		}
+		if !strings.EqualFold(h.Name.String(), qname) ||
+			h.Class&^classCacheFlush != dnsmessage.ClassINET ||
+			!answerTypeMatchesNetwork(h.Type, network) {
+			if err := p.SkipAnswer(); err != nil {
+				return nil, 0, false
+			}
+			continue
+		}
+		switch h.Type {
+		case dnsmessage.TypeA:
+			r, err := p.AResource()
+			if err != nil {
+				return nil, 0, false
+			}
+			addrs = append(addrs, netip.AddrFrom4(r.A))
+		case dnsmessage.TypeAAAA:
+			r, err := p.AAAAResource()
+			if err != nil {
+				return nil, 0, false
+			}
+			// Unmap so a v4-mapped AAAA dials as plain IPv4.
+			addr := netip.AddrFrom16(r.AAAA).Unmap()
+			if addr.Is6() && addr.IsLinkLocalUnicast() {
+				// A link-local address without a zone is not a safe dial
+				// target: the kernel cannot know which interface to use.
+				if iface.Name == "" {
+					continue
+				}
+				addr = addr.WithZone(iface.Name)
+			}
+			addrs = append(addrs, addr)
+		default:
+			if err := p.SkipAnswer(); err != nil {
+				return nil, 0, false
+			}
+			continue
+		}
+		if d := time.Duration(h.TTL) * time.Second; d < ttl {
+			ttl = d
+		}
+	}
+	return finishAnswer(addrs, ttl)
+}
+
+func answerTypeMatchesNetwork(typ dnsmessage.Type, network string) bool {
+	switch network {
+	case "udp4":
+		return typ == dnsmessage.TypeA
+	case "udp6":
+		return typ == dnsmessage.TypeAAAA
+	default:
+		return false
+	}
+}
+
+func validMDNSSource(source *net.UDPAddr, network string, iface *net.Interface) bool {
+	// RFC 6762 requires every mDNS response to use the well-known source
+	// port, including a response sent directly to a QU query's ephemeral port.
+	if source == nil || source.Port != mdnsPort || source.IP == nil || !validMulticastInterface(iface) {
+		return false
+	}
+	ip, ok := netip.AddrFromSlice(source.IP)
+	if !ok {
+		return false
+	}
+	ip = ip.Unmap()
+	if ip.IsUnspecified() || ip.IsMulticast() {
+		return false
+	}
+	switch network {
+	case "udp4":
+		if !ip.Is4() {
+			return false
+		}
+	case "udp6":
+		if !ip.Is6() {
+			return false
+		}
+		if source.Zone != "" && source.Zone != iface.Name {
+			return false
+		}
+	default:
+		return false
+	}
+	return true
+}
+
+func finishAnswer(addrs []netip.Addr, ttl time.Duration) ([]netip.Addr, time.Duration, bool) {
+	if len(addrs) == 0 {
+		return nil, 0, false
+	}
+	switch {
+	case ttl < minTTL:
+		ttl = minTTL
+	case ttl > maxTTL:
+		ttl = maxTTL
+	}
+	return addrs, ttl, true
+}
+
+func appendUnique(dst []netip.Addr, src ...netip.Addr) []netip.Addr {
+	for _, candidate := range src {
+		seen := false
+		for _, existing := range dst {
+			if existing == candidate {
+				seen = true
+				break
+			}
+		}
+		if !seen {
+			dst = append(dst, candidate)
+		}
+	}
+	return dst
+}
+
+func minAnswerTTL(values ...time.Duration) time.Duration {
+	var min time.Duration
+	for _, value := range values {
+		if value <= 0 {
+			continue
+		}
+		if min == 0 || value < min {
+			min = value
+		}
+	}
+	if min == 0 {
+		return minTTL
+	}
+	return min
+}
diff --git a/go/internal/modbus/client.go b/go/internal/modbus/client.go
index ef461017..7b06a716 100644
--- a/go/internal/modbus/client.go
+++ b/go/internal/modbus/client.go
@@ -29,12 +29,13 @@ const (
 // single-session dongle can release its old socket without blocking the
 // driver's poll and command loop.
 type Capability struct {
-	mu             sync.Mutex
-	client         *tcpClient
-	url            string
-	addr           string
-	unitID         int
-	requestTimeout time.Duration
+	mu                   sync.Mutex
+	client               *tcpClient
+	url                  string
+	addr                 string
+	unitID               int
+	allowUnverifiedLocal bool
+	requestTimeout       time.Duration
 
 	consecutiveTransportFailures int
 	nextReconnectAt              time.Time
@@ -43,18 +44,25 @@ type Capability struct {
 
 // Dial opens a Modbus TCP connection.
 func Dial(host string, port, unitID int) (*Capability, error) {
+	return DialWithOptions(host, port, unitID, false)
+}
+
+// DialWithOptions opens a Modbus TCP connection with the core's explicit
+// policy for unauthenticated mDNS names.
+func DialWithOptions(host string, port, unitID int, allowUnverifiedLocal bool) (*Capability, error) {
 	if err := validateEndpoint(host, port, unitID); err != nil {
 		return nil, err
 	}
 	addr := net.JoinHostPort(host, strconv.Itoa(port))
 	url := "tcp://" + addr
-	cli := newTCPClient(addr, modbusRequestTimeout, modbusTCPKeepAlive)
+	cli := newTCPClientWithOptions(addr, modbusRequestTimeout, modbusTCPKeepAlive, allowUnverifiedLocal)
 	capability := &Capability{
-		url:            url,
-		addr:           addr,
-		unitID:         unitID,
-		requestTimeout: modbusRequestTimeout,
-		now:            time.Now,
+		url:                  url,
+		addr:                 addr,
+		unitID:               unitID,
+		allowUnverifiedLocal: allowUnverifiedLocal,
+		requestTimeout:       modbusRequestTimeout,
+		now:                  time.Now,
 	}
 	if err := cli.Open(); err != nil {
 		if !isRetryableDialError(err) {
@@ -330,7 +338,7 @@ func (c *Capability) reconnect() error {
 	if timeout <= 0 {
 		timeout = modbusRequestTimeout
 	}
-	cli := newTCPClient(c.addr, timeout, modbusTCPKeepAlive)
+	cli := newTCPClientWithOptions(c.addr, timeout, modbusTCPKeepAlive, c.allowUnverifiedLocal)
 	if err := cli.Open(); err != nil {
 		c.noteTransportFailure()
 		return err
diff --git a/go/internal/modbus/tcp_client.go b/go/internal/modbus/tcp_client.go
index 78b7e7ba..a95b4f38 100644
--- a/go/internal/modbus/tcp_client.go
+++ b/go/internal/modbus/tcp_client.go
@@ -7,6 +7,8 @@ import (
 	"io"
 	"net"
 	"time"
+
+	"github.com/srcfl/ftw/go/internal/mdnsresolve"
 )
 
 const (
@@ -21,28 +23,37 @@ const (
 )
 
 type tcpClient struct {
-	addr      string
-	timeout   time.Duration
-	keepAlive time.Duration
-	unitID    uint8
-	txID      uint16
-	conn      net.Conn
+	addr                 string
+	timeout              time.Duration
+	keepAlive            time.Duration
+	allowUnverifiedLocal bool
+	unitID               uint8
+	txID                 uint16
+	conn                 net.Conn
 }
 
 func newTCPClient(addr string, timeout, keepAlive time.Duration) *tcpClient {
+	return newTCPClientWithOptions(addr, timeout, keepAlive, false)
+}
+
+func newTCPClientWithOptions(addr string, timeout, keepAlive time.Duration, allowUnverifiedLocal bool) *tcpClient {
 	return &tcpClient{
-		addr:      addr,
-		timeout:   timeout,
-		keepAlive: keepAlive,
-		unitID:    1,
+		addr:                 addr,
+		timeout:              timeout,
+		keepAlive:            keepAlive,
+		allowUnverifiedLocal: allowUnverifiedLocal,
+		unitID:               1,
 	}
 }
 
 func (c *tcpClient) Open() error {
-	dialer := net.Dialer{
+	// Resolution happens here, on every Open, so a device configured by its
+	// ".local" name is found again after a DHCP lease moves it — the reconnect
+	// path rebuilds the client from c.addr and picks up the new address.
+	dialer := mdnsresolve.Dialer{Dialer: net.Dialer{
 		Timeout:   modbusDialTimeout,
 		KeepAlive: c.keepAlive,
-	}
+	}, AllowUnverifiedLocal: c.allowUnverifiedLocal}
 	conn, err := dialer.Dial("tcp", c.addr)
 	if err != nil {
 		return err
diff --git a/go/internal/mqtt/client.go b/go/internal/mqtt/client.go
index fb1ec167..226834b5 100644
--- a/go/internal/mqtt/client.go
+++ b/go/internal/mqtt/client.go
@@ -4,12 +4,15 @@ package mqtt
 import (
 	"fmt"
 	"log/slog"
+	"net"
+	"net/url"
 	"sync"
 	"time"
 
 	paho "github.com/eclipse/paho.mqtt.golang"
 
 	"github.com/srcfl/ftw/go/internal/drivers"
+	"github.com/srcfl/ftw/go/internal/mdnsresolve"
 )
 
 // Capability wraps a paho client to match drivers.MQTTCap.
@@ -46,11 +49,28 @@ type Capability struct {
 // the replay is what restores the subscription set the broker just
 // dropped.
 func Dial(host string, port int, username, password, clientID string) (*Capability, error) {
+	return DialWithOptions(host, port, username, password, clientID, false)
+}
+
+// DialWithOptions connects to an MQTT broker with the core's explicit policy
+// for unauthenticated mDNS names.
+func DialWithOptions(host string, port int, username, password, clientID string, allowUnverifiedLocal bool) (*Capability, error) {
 	cap := &Capability{
 		subs: make(map[string]struct{}),
 	}
 	opts := paho.NewClientOptions().
 		AddBroker(fmt.Sprintf("tcp://%s:%d", host, port)).
+		// paho's built-in dialer goes through the stdlib resolver, which never
+		// answers a ".local" name. Every broker URL built here is tcp://, so a
+		// TCP-only replacement is complete; non-".local" hosts fall through to
+		// a plain dial inside mdnsresolve.
+		SetCustomOpenConnectionFn(func(uri *url.URL, o paho.ClientOptions) (net.Conn, error) {
+			d := mdnsresolve.Dialer{
+				Dialer:               net.Dialer{Timeout: o.ConnectTimeout},
+				AllowUnverifiedLocal: allowUnverifiedLocal,
+			}
+			return d.Dial("tcp", uri.Host)
+		}).
 		SetClientID(clientID).
 		SetAutoReconnect(true).
 		SetConnectRetry(true).
diff --git a/go/internal/scanner/hostname_test.go b/go/internal/scanner/hostname_test.go
new file mode 100644
index 00000000..81f632b4
--- /dev/null
+++ b/go/internal/scanner/hostname_test.go
@@ -0,0 +1,141 @@
+package scanner
+
+import (
+	"context"
+	"net"
+	"testing"
+)
+
+// stubProbes replaces the three name probes for the duration of a test.
+func stubProbes(t *testing.T, reverseMDNS func(context.Context, string) string, verify func(context.Context, string, string) string, reverseDNS func(context.Context, *net.Resolver, string) string) {
+	t.Helper()
+	oldMDNS, oldVerify, oldDNS := probeReverseMDNS, probeVerifyLocal, probeReverseDNS
+	t.Cleanup(func() {
+		probeReverseMDNS, probeVerifyLocal, probeReverseDNS = oldMDNS, oldVerify, oldDNS
+	})
+	probeReverseMDNS = func(ctx context.Context, ip string) string {
+		if reverseMDNS == nil {
+			return ""
+		}
+		return reverseMDNS(ctx, ip)
+	}
+	probeVerifyLocal = func(ctx context.Context, label, ip string) string {
+		if verify == nil {
+			return ""
+		}
+		return verify(ctx, label, ip)
+	}
+	probeReverseDNS = func(ctx context.Context, r *net.Resolver, ip string) string {
+		if reverseDNS == nil {
+			return ""
+		}
+		return reverseDNS(ctx, r, ip)
+	}
+}
+
+// A name the device answers for itself wins outright — the router's label for
+// the same lease must not displace it.
+func TestLookupNamePrefersTheDeviceOwnedLocalName(t *testing.T) {
+	stubProbes(t,
+		func(context.Context, string) string { return "inverter.local" },
+		func(context.Context, string, string) string {
+			t.Fatal("forward verification should not run when reverse mDNS already answered")
+			return ""
+		},
+		func(context.Context, *net.Resolver, string) string { return "inverter.localdomain" },
+	)
+
+	if got := lookupName(context.Background(), &net.Resolver{}, "192.168.1.141"); got != "inverter.local" {
+		t.Fatalf("hostname = %q, want inverter.local", got)
+	}
+}
+
+// The Sourceful Zap's real behaviour: it publishes a forward A record and no
+// in-addr.arpa PTR at all, so only the router answers a reverse query. The
+// label still has to reach the wizard as a ".local" name.
+func TestLookupNameVerifiesTheLabelForwardWhenNoReversePTRExists(t *testing.T) {
+	var askedLabel, askedIP string
+	stubProbes(t,
+		func(context.Context, string) string { return "" }, // no reverse mDNS record
+		func(_ context.Context, label, ip string) string {
+			askedLabel, askedIP = label, ip
+			return label + ".local"
+		},
+		func(context.Context, *net.Resolver, string) string {
+			return "zap-000064963cd51edc.localdomain"
+		},
+	)
+
+	got := lookupName(context.Background(), &net.Resolver{}, "192.168.1.141")
+	if want := "zap-000064963cd51edc.local"; got != want {
+		t.Fatalf("hostname = %q, want %q", got, want)
+	}
+	if askedLabel != "zap-000064963cd51edc" {
+		t.Errorf("verified label = %q, want the first label only", askedLabel)
+	}
+	if askedIP != "192.168.1.141" {
+		t.Errorf("verified against %q, want the scanned address", askedIP)
+	}
+}
+
+// Verification failing is not a reason to invent a name. The router's label
+// is still worth showing, but it must come back unchanged so the wizard saves
+// the IP instead.
+func TestLookupNameKeepsTheDisplayNameWhenForwardVerificationFails(t *testing.T) {
+	stubProbes(t,
+		func(context.Context, string) string { return "" },
+		func(context.Context, string, string) string { return "" }, // resolves elsewhere, or not at all
+		func(context.Context, *net.Resolver, string) string { return "printer.localdomain" },
+	)
+
+	if got := lookupName(context.Background(), &net.Resolver{}, "192.168.1.9"); got != "printer.localdomain" {
+		t.Fatalf("hostname = %q, want the unverified name passed through for display", got)
+	}
+}
+
+// Nothing answered anywhere: an empty name, not a fabricated one.
+func TestLookupNameReturnsEmptyWhenNothingAnswers(t *testing.T) {
+	stubProbes(t, nil, nil, nil)
+
+	if got := lookupName(context.Background(), &net.Resolver{}, "192.168.1.9"); got != "" {
+		t.Fatalf("hostname = %q, want empty", got)
+	}
+}
+
+func TestVerifiedLocalNameRejectsAnAnswerForADifferentAddress(t *testing.T) {
+	// Lookup is not stubbed here; an unresolvable name exercises the error
+	// path without touching the LAN.
+	if got := verifiedLocalName(context.Background(), "", "192.168.1.141"); got != "" {
+		t.Fatalf("empty label produced %q", got)
+	}
+	if got := verifiedLocalName(context.Background(), "device", "not-an-ip"); got != "" {
+		t.Fatalf("malformed address produced %q", got)
+	}
+}
+
+func TestHostLabelTakesTheFirstLabelLowercased(t *testing.T) {
+	cases := map[string]string{
+		"zap-0000649.localdomain.": "zap-0000649",
+		"Inverter.Local":           "inverter",
+		"bare":                     "bare",
+		"":                         "",
+	}
+	for in, want := range cases {
+		if got := hostLabel(in); got != want {
+			t.Errorf("hostLabel(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestIsLocalName(t *testing.T) {
+	for _, name := range []string{"zap.local", "ZAP.LOCAL", "a.b.local."} {
+		if !isLocalName(name) {
+			t.Errorf("isLocalName(%q) = false", name)
+		}
+	}
+	for _, name := range []string{"zap.localdomain", "zap.lan", "", "local"} {
+		if isLocalName(name) {
+			t.Errorf("isLocalName(%q) = true", name)
+		}
+	}
+}
diff --git a/go/internal/scanner/mdns.go b/go/internal/scanner/mdns.go
index 4963ed52..f58ae8ed 100644
--- a/go/internal/scanner/mdns.go
+++ b/go/internal/scanner/mdns.go
@@ -4,10 +4,13 @@ import (
 	"context"
 	"fmt"
 	"net"
+	"net/netip"
 	"strings"
 	"time"
 
 	"golang.org/x/net/dns/dnsmessage"
+
+	"github.com/srcfl/ftw/go/internal/mdnsresolve"
 )
 
 var mdnsAddr = &net.UDPAddr{IP: net.IPv4(224, 0, 0, 251), Port: 5353}
@@ -56,6 +59,51 @@ func reverseMDNS(ctx context.Context, ip string) string {
 	}
 }
 
+// isLocalName reports whether name is an RFC 6762 ".local" name.
+func isLocalName(name string) bool {
+	return strings.HasSuffix(strings.ToLower(strings.TrimSuffix(name, ".")), ".local")
+}
+
+// hostLabel returns the first DNS label of name, lowercased.
+func hostLabel(name string) string {
+	name = strings.TrimSuffix(strings.TrimSpace(name), ".")
+	if i := strings.IndexByte(name, '.'); i >= 0 {
+		name = name[:i]
+	}
+	return strings.ToLower(name)
+}
+
+// verifiedLocalName turns a host label into a ".local" name the device has
+// confirmed is its own.
+//
+// A reverse PTR query is the obvious way to learn a device's mDNS name, and
+// an unreliable one: RFC 6762 makes in-addr.arpa mapping optional, and plenty
+// of responders publish a forward A record without ever answering a reverse
+// query. A Sourceful Zap is one — it answers "zap.local" all day and returns
+// nothing for 141.1.168.192.in-addr.arpa.
+//
+// So take the label from whatever name we do have, ask for "<label>.local"
+// forward, and keep the answer only when it resolves back to the address we
+// started from. That last check is the point of the function: without it the
+// router's naming would decide what FTW dials, on the strength of a guess.
+func verifiedLocalName(ctx context.Context, label, ip string) string {
+	want, err := netip.ParseAddr(ip)
+	if err != nil || label == "" {
+		return ""
+	}
+	candidate := label + ".local"
+	addrs, err := mdnsresolve.Lookup(ctx, candidate)
+	if err != nil {
+		return ""
+	}
+	for _, a := range addrs {
+		if a.Unmap() == want.Unmap() {
+			return candidate
+		}
+	}
+	return ""
+}
+
 func parsePTRAnswer(packet []byte, qname string) string {
 	var p dnsmessage.Parser
 	if _, err := p.Start(packet); err != nil {
diff --git a/go/internal/scanner/scanner.go b/go/internal/scanner/scanner.go
index 0d8dea31..a23571c1 100644
--- a/go/internal/scanner/scanner.go
+++ b/go/internal/scanner/scanner.go
@@ -17,6 +17,27 @@ import (
 	"time"
 )
 
+const (
+	// Name lookups are best-effort and must not stretch a scan. Both run
+	// concurrently per address, and at most one further mDNS round follows.
+	mdnsLookupTimeout    = 900 * time.Millisecond
+	unicastLookupTimeout = 800 * time.Millisecond
+)
+
+// The three name probes, swappable so the preference order can be tested
+// without a LAN, a responder or a DNS server.
+var (
+	probeReverseMDNS = reverseMDNS
+	probeVerifyLocal = verifiedLocalName
+	probeReverseDNS  = func(ctx context.Context, resolver *net.Resolver, ip string) string {
+		hosts, err := resolver.LookupAddr(ctx, ip)
+		if err != nil || len(hosts) == 0 {
+			return ""
+		}
+		return strings.TrimSuffix(hosts[0], ".")
+	}
+)
+
 // FoundDevice is one open port discovered on the local network.
 type FoundDevice struct {
 	IP        string `json:"ip"`
@@ -120,18 +141,7 @@ func resolveHostnames(ctx context.Context, devices []FoundDevice) {
 		wg.Add(1)
 		go func(ip string) {
 			defer wg.Done()
-			dnsCtx, cancel := context.WithTimeout(ctx, 800*time.Millisecond)
-			hosts, err := resolver.LookupAddr(dnsCtx, ip)
-			cancel()
-			name := ""
-			if err == nil && len(hosts) > 0 {
-				name = strings.TrimSuffix(hosts[0], ".")
-			}
-			if name == "" && ctx.Err() == nil {
-				mdnsCtx, cancel := context.WithTimeout(ctx, 900*time.Millisecond)
-				name = reverseMDNS(mdnsCtx, ip)
-				cancel()
-			}
+			name := lookupName(ctx, &resolver, ip)
 			if name != "" {
 				mu.Lock()
 				names[ip] = name
@@ -145,6 +155,64 @@ func resolveHostnames(ctx context.Context, devices []FoundDevice) {
 	}
 }
 
+// lookupName picks the best name for ip, preferring one the device answers
+// for itself.
+//
+// The preference is the whole point, and it used to run the other way round.
+// Unicast reverse DNS is answered by the router, which hands back its own
+// label for the lease — "zap-000064963cd51edc.localdomain" on a UniFi
+// network. That is a display string: it resolves only while that router is
+// the resolver, and it does not follow the device anywhere. A ".local" name
+// belongs to the device and survives a new DHCP lease, which is exactly why
+// the setup wizard offers it as the address to save. Asking unicast first
+// meant the good name was never even looked for on any network whose router
+// answers PTR, which is most of them.
+func lookupName(ctx context.Context, resolver *net.Resolver, ip string) string {
+	var mdnsName, unicastName string
+	var wg sync.WaitGroup
+	wg.Add(2)
+	// Independent queries on separate transports, so the scan waits for the
+	// slower of the two rather than for both in turn.
+	go func() {
+		defer wg.Done()
+		c, cancel := context.WithTimeout(ctx, mdnsLookupTimeout)
+		defer cancel()
+		mdnsName = probeReverseMDNS(c, ip)
+	}()
+	go func() {
+		defer wg.Done()
+		c, cancel := context.WithTimeout(ctx, unicastLookupTimeout)
+		defer cancel()
+		unicastName = probeReverseDNS(c, resolver, ip)
+	}()
+	wg.Wait()
+
+	if isLocalName(mdnsName) {
+		return mdnsName
+	}
+	// No reverse mDNS record is the common case, not a failure: try the label
+	// we did get as a forward ".local" name and let the device confirm it.
+	if label := hostLabel(firstNonEmpty(mdnsName, unicastName)); label != "" && ctx.Err() == nil {
+		c, cancel := context.WithTimeout(ctx, mdnsLookupTimeout)
+		defer cancel()
+		if verified := probeVerifyLocal(c, label, ip); verified != "" {
+			return verified
+		}
+	}
+	// Nothing the device owns. Return the router's label as a display name;
+	// the wizard knows not to save a non-".local" name as an address.
+	return firstNonEmpty(mdnsName, unicastName)
+}
+
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
 // probe tries to TCP-connect to ip:port with a 500 ms timeout.
 func probe(ctx context.Context, ip string, port int) (FoundDevice, bool) {
 	addr := fmt.Sprintf("%s:%d", ip, port)
diff --git a/scripts/test-container-boundaries.sh b/scripts/test-container-boundaries.sh
index 1b4c40d5..bc3bae61 100755
--- a/scripts/test-container-boundaries.sh
+++ b/scripts/test-container-boundaries.sh
@@ -38,4 +38,19 @@ fi
 grep -q '^  ftw-optimizer:' docker-compose.yml
 grep -q 'FTW_OPTIMIZER_SOCKET: /run/ftw-optimizer/optimizer.sock' docker-compose.yml
 
+# mDNS container contract: the static core resolves names itself, direct
+# multicast needs Linux host networking, and the optional Avahi bind is the
+# whole runtime directory. A socket-file bind is unsafe because Docker creates
+# a directory at a missing file mount point.
+grep -Eq '^    network_mode: host$' docker-compose.yml
+grep -q 'libnss-mdns' Dockerfile
+grep -q -- '# - /run/avahi-daemon:/run/avahi-daemon:ro' docker-compose.yml
+if grep -Eq '^[[:space:]]+-[[:space:]]*/run/avahi-daemon/socket' docker-compose.yml; then
+  echo "avahi must be mounted as a runtime directory, not a socket file" >&2
+  exit 1
+fi
+if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then
+  docker compose -f docker-compose.yml config --quiet
+fi
+
 echo "container module boundaries verified"