Add a repair action for unresponsive Bluetooth serial ports on macOS

[edwin-truthsearch-io]

Follows #2228, which recognizes an unresponsive Bluetooth serial port and tells the user to re-pair the machine. This adds the action that does it for them.

Why re-pairing is the only remedy

Measured on macOS 26.6.2 (Apple Silicon) with a Kaleido on Bluetooth SPP, with the port in the stale state — /dev/cu.<machine> present, open() succeeding instantly, nothing sent or received:

attempted recovery	result
reopening the port	opens in 0.00s, silent at every baud rate, passively and after a ping
Bluetooth off/on	device node survives with the same minor number
power-cycling the machine	no change
IOBluetoothDevice.closeConnection()	returns success, isConnected() stays true
IOBluetoothDevice.openConnection()	no-op, returns instantly
restarting bluetoothd	refused: Operation not permitted while System Integrity Protection is engaged
removing the pairing and pairing again	works — unpairing deletes the node, the next connect succeeds in ~2s

The pairing record owns the serial binding, and nothing an application can reach rebuilds it — except removing that pairing.

The change

artisanlib/bluetooth_macos.py performs the repair through IOBluetooth: remove the pairing, rediscover the machine by an inquiry, pair it again. The inquiry is not optional — pairing a device built from a bare address fails with error 2; the device has to be discovered first, which is what the system Bluetooth settings do as well.

Verified end to end against a real stale port: the repair completed in about 60 seconds, without any system dialog appearing, and the Kaleido transport reconnected on its own immediately afterwards.

No address or device name is configured anywhere. The machine is derived from the port the user already configured: macOS names a Bluetooth serial port after the device name (spaces and invalid characters replaced, optionally suffixed by the serial service name), so the paired devices are matched against the configured port. On a machine with 12 paired devices — keyboard, mouse, AirPods, phones — the lookup matched exactly one and returned None for a USB serial port and for /dev/cu.Bluetooth-Incoming-Port. That precision is the safety property that matters, since a mismatch would unpair the wrong hardware.

Safety

Removing a pairing cannot be undone by the application if the machine is unreachable, so the repair is:

• never automatic — only ever triggered by the user
• behind a confirmation dialog naming the port
• offered only where it applies: the button is enabled solely for a port served by a paired Bluetooth device, and the whole action is absent off macOS or without the IOBluetooth framework

The app already ships NSBluetoothAlwaysUsageDescription, which IOBluetooth requires; an unbundled process is killed by TCC without it.

Notes

• Tests cover the port-name derivation, the paired-device lookup against a faked IOBluetooth (including that a non-matching device is never unpaired), and the platform gate. The framework calls themselves cannot be unit tested and were verified manually on real hardware.
• Full suite 2397 passed / 7 skipped; ruff, pylint (10.00/10), mypy, pyright and codespell clean. The module carries scoped suppressions for the dynamically generated pyobjc bridges, which no static checker can resolve.
• Independent of Keep the machine connection alive across system standby #2225 and Hint at a stale Bluetooth serial port when the machine does not respond #2228; touches ports.py and a new module only.

🤖 Generated with Claude Code