Matter bridges: commissioning a bridge with no bridged children yields no Indigo devices, and the bridged-endpoint path is unverified end to end

[simons-plugins]

Found while commissioning a Homebridge Matter child bridge on jarvis (2026-08-02/03), after #103 made test-certificate devices commissionable.

What happened

The bridge commissioned successfully into the Indigo fabric as node @1:35 — Attestation accepted, no errors. But no Indigo devices were created, and get_devices_by_type shows none belonging to it.

The reason is visible in matter-server's log — the node exposes exactly one endpoint and it has no children:

20:54:56  server-1-fff1.@1:35.ep1 ready  endpoint#: 1  type: Aggregator (0x0e, rev 2)  behaviors: ✓descriptor
20:55:01  Sending endpoint_added event for Node @1:35 endpoint 1

An Aggregator carries no device clusters, so _spec_for_endpoint correctly returns None for it, and there are no bridged child endpoints to build devices from. The plugin behaved correctly; the bridge was publishing an empty aggregator (the Homebridge plugin apparently couldn't map its one accessory to a Matter device type).

Why this is worth an issue

1. The bridged-endpoint path has never been exercised against a real bridge. The support exists — device_sync.py makes one device per endpoint, matter_model.py:139 _bridge_identity() reads BridgedDeviceBasicInformation (0x0039) for per-endpoint name/vendor/product, and protocol.py:89 handles dynamic endpoint_added/endpoint_removed. But it is unit-tested only. We should validate against a bridge that actually publishes children (a Hue bridge, or a Matterbridge instance with real accessories) before claiming bridge support.

2. Commissioning an empty bridge is silently useless. It reports success and creates nothing. A device-bearing node with no usable endpoints already gets the matterUnknown placeholder treatment; an aggregator with an empty parts list gets nothing at all and no explanation. Suggest an INFO/WARNING when a commissioned node's only endpoint is an Aggregator with no children — "this bridge is not currently exposing any devices over Matter; check its own configuration" — so the user isn't left wondering.

3. Housekeeping: node @1:35 is still in the fabric as a live pairing that can never produce devices. It should be decommissioned (Plugins ▸ Matter ▸ Decommission Matter device…). Related: matter-server's storage showed orphan session-resumption records for @1:30 and @1:33 — node IDs no longer in the node list — which is what accumulates when partial/abandoned commissioning isn't cleaned up.

Environment

matter-server 1.2.2, plugin 2026.7.10, Homebridge child bridges advertising on ports 5530 (HomeConnect) and 5531 (Homebridge iCloud).

🤖 Generated with Claude Code

[simons-plugins]

Reopened — this was closed by accident, not by decision.

PR #108 landed the diagnostic from point 2 (a warning when a commissioned node produces no devices and has an Aggregator endpoint). Its commit message deliberately said "Does NOT close #105" — but GitHub's linked-issue parser doesn't understand negation, matched the literal close #105, and closed it on merge. My wording, my mistake.

What still stands, and is why this issue must stay open:

1. The bridged-endpoint path has never been validated against a real bridge. _bridge_identity, cluster 0x0039, and dynamic endpoint_added/endpoint_removed remain unit-tested only. That needs a bridge which actually publishes children — a Hue bridge, or a Matterbridge with real accessories. feat(bridges): explain a bridge that commissions but exposes nothing #108 does not touch this.

2. Node @1:35 is still live on the fabric. Confirmed today from matter-server's storage: it is present as Homebridge iCloud (node id 53 = 0x35), one of 8 commissioned nodes, still producing zero Indigo devices. Wants decommissioning via Plugins ▸ Matter ▸ Decommission Matter device…

Only point 3's warning was addressed. Do not close this on #108 alone.

[simons-plugins]

Root cause found for the empty Homebridge aggregators

Field-tested again on 2026-08-03/04 with a second Homebridge child bridge — this one deliberately containing real accessories (a doorbell and a blind). It commissioned cleanly as node @1:36 and again produced no Indigo devices.

The cause is on the Homebridge side, and it is not a mapping or configuration problem.

Evidence

The bridge's Descriptor cluster on endpoint 1, read from matter-server storage:

"0": [{"deviceType":14,"revision":2}]   ← 0x000E Aggregator
"1": [29]                               ← 0x001D Descriptor only
"3": []                                 ← PartsList EMPTY

Only endpoints 0 and 1 ever existed; exactly one endpoint_added event, for endpoint 1, across multiple bridge restarts.

The Homebridge child-bridge log explains why:

[Matter/Accessories] No cached Matter accessories found (first run)
[Matter/Server]      Matter server started successfully on port 5533
[Matter/Server]      Plugins can now register Matter accessories via the API
Loaded 1 cached accessories from cachedAccessories.0E4E51796B0F.
[Virtual Accessories Platform] Loading accessory from cache: Blind
[Virtual Accessories Platform] Restoring existing accessory: Blind

Homebridge 2.x keeps two separate accessory registries. The HAP one loads the accessory normally. Matter exposure is opt-in per plugin, via an API the plugin must call — and homebridge-virtual-accessories v3.14.22 registers over HAP only. Homebridge therefore starts a Matter server, pairs it (commissioned: true), and publishes an aggregator with nothing in it.

What this means for this issue

1. The plugin has behaved correctly throughout. There is genuinely nothing to build devices from — the empty parts list is global to the device, so every controller (Domio, Apple Home, Indigo) sees the same empty bridge.

2. feat(bridges): explain a bridge that commissions but exposes nothing #108's warning is the correct diagnosis and works. After deploying 2026.7.15 to jarvis it fired live on both bridges on the first reconcile:

   Matter node 0x36 (Homebridge Virtual Accessories for Homebrid) is a bridge that is not currently exposing any devices over Matter: endpoint 1 is an Aggregator with no bridged children…

3. Point 1 of this issue still cannot be closed, and Homebridge cannot close it. Any Homebridge plugin that has not adopted the Matter API will produce an empty aggregator, so no Homebridge child bridge can exercise _bridge_identity / cluster 0x0039 / dynamic endpoint_added. Validating the bridged-endpoint path needs Matterbridge (which maps HomeKit accessories to Matter itself, rather than requiring per-plugin opt-in) or a Hue bridge.

Housekeeping

Both @1:35 ("Homebridge iCloud") and @1:36 ("Virtual Accessories") are confirmed permanently unable to produce devices while those plugins lack Matter registration. Both are safe to decommission — they currently occupy fabric slots for nothing.

[simons-plugins]

Reopened again — same accident, second occurrence.

PR #109 (the handover) merged at 17:37:01Z and closed this issue two seconds later, because its description documented the earlier mishap and in doing so quoted the literal keyword-plus-reference string. GitHub's linked-issue parser matches that pattern regardless of surrounding text, including text explaining that the pattern is a trap.

Rule for anyone touching this issue: never write the closing keyword immediately followed by #105 in a commit message or PR description, even when quoting or negating it. Write "addresses part of #105", or break the pattern (e.g. #-105), when you need to refer to it.

The substantive status is unchanged and is set out in the previous comment: point 3's warning shipped in #108, but point 1 (real-bridge validation of the bridged-endpoint path) remains open and cannot be satisfied by a Homebridge child bridge.