[basmeerman]

Why

Retained MQTT discovery messages outlive the bridge. 2.1.1 added per-entity removals, but they are emitted per BmsRunner — so a pack dropped from bms_ids has no runner, and its ~100 entities stay in Home Assistant as dead, unavailable entries that are re-processed on every restart. Changing bms_name_prefix orphans every pack the same way.

What changes

New option, off by default:

clean_orphaned_discovery: true

On startup the bridge reads the retained configs under its own discovery_prefix, and clears those whose device id matches <bms_name_prefix>_<slave id>_device_* for a slave id no longer in bms_ids. Each cleared topic is logged, plus a summary.

Design

The decision and the I/O are split, because this repo gates at 100 % branch coverage and run() is excluded as top-level glue. Putting the logic inside the MQTT loop would have made the part that decides what to delete untestable.

• mqtt.orphan_removals(topics, *, settings) — pure, unit-tested. Leaves alone: packs still polled, other integrations, another jkbms2mqtt under a different discovery prefix, unknown components, malformed device ids, and already-cleared (empty) configs.
• app._clean_orphaned_discovery() — subscribe, collect, publish, log. Under the existing # pragma: no cover - MQTT glue.

Ordering matters. aiomqtt hands out a single shared message queue (MessagesIterator over Client._queue), so draining it while the /set topics were subscribed could swallow a user's write. The cleanup therefore runs before those subscriptions, when no command can exist yet. Ending the collect window with wait_for is safe: Queue.get() doesn't drop an item when cancelled.

Why opt-in. Two bridges can share one broker. A pack this instance doesn't poll may legitimately belong to the other one, and clearing its configs would delete that instance's entities.

Test plan

• 9 unit tests for orphan_removals (removed pack cleared; configured packs untouched; foreign integration, foreign prefix, unknown component, malformed ids all ignored; empty broker; renders as an empty retained payload)
• Option defaults to false, present in config.yaml options + schema, round-trips into Settings
• ruff, mypy, pytest — 572 passed, 100 % branch coverage
• Dashboard drift check passes; generated artifacts byte-identical (bridge-side change only)
• On a live broker: enable the option with a pack removed from bms_ids, confirm the log lists the cleared topics and the entities disappear from Home Assistant
• Confirm a second bridge under a different discovery_prefix is untouched

Closes #25

🤖 Generated with Claude Code