fix(docker): register hw listener and match by-id paths for options-based devices

Two bugs caused a crash loop when a USB device re-enumerates to a different
minor number (e.g. ttyACM0→ttyACM1) after a HAOS reboot:

1. _hw_listener was only registered when addon.static_devices was non-empty.
   Addons that expose a device via the options schema (e.g. Z-Wave JS `device:`
   option) never had the listener registered, so add_devices_allowed was never
   called when the device reappeared at a new minor.

2. _hardware_events matched only device.path and device.sysfs against
   static_devices.  When static_devices (or the new options path) contains a
   by-id symlink, the match always failed because by-id paths live in
   device.links.

Fix: extend the listener registration condition to also cover addon.devices
(options-based), and expand the path-matching set to include device.links so
by-id paths resolve correctly.  For options-based devices, compare the incoming
Device against addon.devices (which re-evaluates options.json against the live
hardware list, picking up the new minor number automatically).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: carlossg

supervisor/docker/app.py

@@ -618,8 +618,9 @@ async def run(self) -> None:
             _LOGGER.warning("Can't update DNS for %s", self.name)
             await async_capture_exception(err)
 
-        # Hardware Access
-        if self.app.static_devices:
+        # Hardware Access — register listener for both manifest static_devices and
+        # options-based devices (e.g. Z-Wave JS `device:` option).
+        if self.app.static_devices or self.app.devices:
             self._hw_listener = self.sys_bus.register_event(
                 BusEvent.HARDWARE_NEW_DEVICE, self._hardware_events
             )
@@ -887,10 +888,16 @@ async def stop(self, remove_container: bool = True) -> None:
     )
     async def _hardware_events(self, device: Device) -> None:
         """Process Hardware events for adjust device access."""
-        if not any(
-            device_path in (device.path, device.sysfs)
-            for device_path in self.app.static_devices
-        ):
+        # Build the full set of paths this device is known by (path, sysfs, and all
+        # by-id / by-path symlinks), so we match even when static_devices stores a
+        # by-id path rather than the raw /dev/ttyACMx path.
+        device_all_paths = {device.path, device.sysfs} | set(device.links)
+        static_match = bool(device_all_paths & set(self.app.static_devices))
+        # Also check options-based devices (e.g. Z-Wave JS `device:` option).
+        # addon.devices re-evaluates from options.json against the current hardware
+        # list, so it will resolve to the newly enumerated device (e.g. ttyACM1).
+        options_match = device in self.app.devices
+        if not static_match and not options_match:
             return
 
         try:

tests/docker/test_app.py

@@ -572,3 +572,73 @@ async def test_ulimits_integration(coresys: CoreSys, install_app_ssh: App):
     assert core_limit is not None
     assert core_limit.soft == 0
     assert core_limit.hard == 0
+
+
+# --- Tests for fix: register hw listener and match by-id paths for options-based devices ---
+
+TEST_BY_ID_PATH = str(TEST_HW_DEVICE.links[0])
+
+
+@pytest.mark.usefixtures("path_extern", "tmp_supervisor_data")
+async def test_app_new_device_by_id_link(
+    coresys: CoreSys,
+    install_app_ssh: App,
+    container: MagicMock,
+    docker: DockerAPI,
+):
+    """Test hardware event matches a by-id symlink stored in static_devices."""
+    coresys.hardware.disk.get_disk_free_space = lambda x: 5000
+    # Configure the device via its by-id symlink, not the raw /dev/ttyACMx path.
+    # Before the fix, _hardware_events only checked device.path / device.sysfs and
+    # would never match a by-id path, so add_devices_allowed was never called.
+    install_app_ssh.data["devices"] = [TEST_BY_ID_PATH]
+    container.id = 123
+
+    with (
+        patch.object(App, "write_options"),
+        patch.object(OSManager, "available", new=PropertyMock(return_value=True)),
+        patch.object(
+            CGroup, "add_devices_allowed", new_callable=AsyncMock
+        ) as add_devices,
+    ):
+        await install_app_ssh.start()
+        await fire_bus_event(coresys, BusEvent.HARDWARE_NEW_DEVICE, TEST_HW_DEVICE)
+
+        add_devices.assert_called_once_with(123, "c 0:0 rwm")
+
+
+@pytest.mark.usefixtures("path_extern", "tmp_supervisor_data")
+async def test_app_options_device_hw_listener(
+    coresys: CoreSys,
+    install_app_ssh: App,
+    container: MagicMock,
+    docker: DockerAPI,
+):
+    """Test hw_listener is registered and fires for options-based devices.
+
+    Before the fix, _hw_listener was only registered when addon.static_devices
+    was non-empty. Add-ons like Z-Wave JS that configure the device via the
+    options schema (addon.devices) never had a listener, so cgroup permissions
+    were never updated after a USB re-enumeration.
+    """
+    coresys.hardware.disk.get_disk_free_space = lambda x: 5000
+    install_app_ssh.data["devices"] = []  # no static devices
+    container.id = 123
+    docker._info = replace(docker.info, cgroup="1")  # pylint: disable=protected-access
+
+    with (
+        patch.object(App, "write_options"),
+        # HAOS not available: proactive cgroup call is skipped, so add_devices is
+        # called exactly once — from the hardware event via the options listener.
+        patch.object(OSManager, "available", new=PropertyMock(return_value=False)),
+        patch.object(
+            App, "devices", new_callable=PropertyMock, return_value={TEST_HW_DEVICE}
+        ),
+        patch.object(
+            CGroup, "add_devices_allowed", new_callable=AsyncMock
+        ) as add_devices,
+    ):
+        await install_app_ssh.start()
+        await fire_bus_event(coresys, BusEvent.HARDWARE_NEW_DEVICE, TEST_HW_DEVICE)
+
+        add_devices.assert_called_once_with(123, "c 0:0 rwm")