homie: snapshot _nodes/_children before iteration to fix MQTT-thread race (SDK-e3k)

publish_nodes() and refresh_tree() were iterating self._nodes /
self._children live while the main thread mutated them via add_node() /
Device(parent=...) construction. On a SPAN G2 panel this crashed the
MQTT loop thread on initial broker connect:

    File ".../ebus_sdk/homie.py", line 1501, in publish_nodes
        for node in self._nodes.values():
    RuntimeError: dictionary changed size during iteration

systemd then SIGKILLed the unresponsive process; the restart recovered.

Both call sites now iterate through a list() snapshot, matching the
defensive pattern already in place in delete_all_from_mqtt() (line
1246) and delete() (line 1305). Adds two deterministic regression
tests that fail on the unfixed code and pass with the snapshot.

refresh_tree() doesn't actually crash without the fix (Python lists
don't raise on mutation-during-iteration the way dicts do), but
CPython's list iterator would pull a half-constructed child appended
mid-cascade into the current reconnect republish — so the snapshot is
the correct semantics either way.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dcj

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `ebus-sdk` are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+## [0.2.2] — 2026-06-12
+
+### Fixed
+
+- `Device.publish_nodes()` no longer crashes with `RuntimeError: dictionary changed size during iteration` when the main thread adds a node while the MQTT loop thread is publishing on initial broker connect. Iteration now goes through a `list(self._nodes.values())` snapshot — matching the defensive pattern already used in `delete_all_from_mqtt()`. Hit on a SPAN G2 panel immediately after deploy; systemd subsequently SIGKILLed the unresponsive process, restart recovered.
+- `Device.refresh_tree()` similarly snapshots `self._children` before recursing. Lists don't raise on mutation-during-iteration, but CPython's list iterator would otherwise pull a half-constructed child added mid-cascade into the current reconnect republish — matching the defensive pattern in `Device.delete()`.
+
 ## [0.2.1] — 2026-06-12
 
 ### Added
@@ -53,7 +60,8 @@ The 0.2.0 release introduces first-class parent/child device trees on both the d
 
 Initial public release on PyPI. See `git log v0.1.2` for the surface that shipped.
 
-[Unreleased]: https://github.com/electrification-bus/python-sdk/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/electrification-bus/python-sdk/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/electrification-bus/python-sdk/releases/tag/v0.2.2
 [0.2.1]: https://github.com/electrification-bus/python-sdk/releases/tag/v0.2.1
 [0.2.0]: https://github.com/electrification-bus/python-sdk/releases/tag/v0.2.0
 [0.1.7]: https://github.com/electrification-bus/python-sdk/releases/tag/v0.1.7

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ebus-sdk"
-version = "0.2.1"
+version = "0.2.2"
 description = "Python SDK for Homie MQTT Convention (eBus)"
 readme = "README.md"
 requires-python = ">=3.10"

src/ebus_sdk/__init__.py

@@ -43,7 +43,7 @@
 # MQTT client
 from ebus_mqtt_client import MqttClient
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 __all__ = [
     # Homie classes

src/ebus_sdk/homie.py

@@ -1421,7 +1421,9 @@ def refresh_tree(self) -> None:
             f"nodeCount={len(self._nodes)},childCount={len(self._children)}"
         )
         self._publish_self()
-        for child in self._children:
+        # Snapshot — main thread may construct child devices (which append
+        # to self._children) while this runs on the MQTT loop thread.
+        for child in list(self._children):
             child.refresh_tree()
 
     def publish(self, attribute: str = "", value: Optional[Any] = None) -> None:
@@ -1498,7 +1500,11 @@ def publish_description(self, republish: bool = False) -> None:
                 self.publish("$description")
 
     def publish_nodes(self) -> None:
-        for node in self._nodes.values():
+        # Snapshot — invoked from on_connect() on the MQTT loop thread while
+        # the main thread may be inside state_transition() calling add_node().
+        # Without the snapshot, dict-size-changed-during-iteration crashes the
+        # MQTT thread on initial connect.
+        for node in list(self._nodes.values()):
             node.publish()
 
     def on_connect(self) -> None:

tests/test_homie_device.py

@@ -1224,6 +1224,25 @@ def test_publish_nodes(self, mock_paho):
         device.publish_nodes()
         mock_node.publish.assert_called_once()
 
+    def test_publish_nodes_snapshots_against_concurrent_add(self, mock_paho):
+        """SDK-e3k: publish_nodes() must snapshot self._nodes so the main
+        thread adding a node mid-iteration doesn't raise
+        'dictionary changed size during iteration' on the MQTT loop thread."""
+        device, _ = _make_device(mock_paho)
+
+        # Simulate the race: while iterating, one node's publish() mutates
+        # the underlying dict (as the main thread's add_node would).
+        racing_node = MagicMock()
+
+        def mutate_during_publish():
+            device._nodes["late-arrival"] = MagicMock()
+
+        racing_node.publish.side_effect = mutate_during_publish
+        device._nodes = {"core": racing_node}
+
+        # Without the list() snapshot fix, this raises RuntimeError.
+        device.publish_nodes()
+
 
 class TestDeviceOnConnect:
     def test_initial_connection(self, mock_paho):
@@ -1358,6 +1377,33 @@ def test_refresh_tree_cascades_to_children(self, mock_paho):
             )
             assert any(f"/{device_id}/$state" in t for t in topics), f"missing $state for {device_id} in {topics}"
 
+    def test_refresh_tree_snapshots_against_concurrent_child_add(self, mock_paho):
+        """SDK-e3k: refresh_tree() must snapshot self._children so a child
+        appended by the main thread mid-cascade isn't pulled into the current
+        republish on the MQTT loop thread. (Lists don't raise on
+        mutation-during-iteration the way dicts do, but processing a
+        half-constructed child is its own correctness hazard.)"""
+        root, _ = _make_device(mock_paho, device_id="panel-1")
+        existing_child = Device(id="circuit-a", parent=root)
+        late_arrival = MagicMock(spec=Device)
+
+        original_refresh = existing_child.refresh_tree
+
+        def mutate_during_refresh():
+            # Simulate the main thread appending a new child while the MQTT
+            # thread is mid-cascade.
+            root._children.append(late_arrival)
+            original_refresh()
+
+        existing_child.refresh_tree = mutate_during_refresh
+
+        root.refresh_tree()
+
+        # Snapshot semantics: late_arrival was appended after iteration began,
+        # so it must NOT be touched by this refresh cycle. Without the
+        # list() snapshot, CPython's list iterator picks it up.
+        late_arrival.refresh_tree.assert_not_called()
+
     def test_refresh_tree_three_levels(self, mock_paho):
         """S2 + S6: grandchildren also republish on reconnect."""
         root, mock_client = _make_device(mock_paho, device_id="panel-1")