fix: disambiguate empty service-filtered scans from adapter wedges

[torlando-tech]

What

The discovery scan is service-filtered - only devices advertising the Reticulum service UUID trigger the detection callback. At boot, no peer has started advertising yet, so the filtered scan legitimately returns zero callbacks while the peer's GATT server comes up.

The wedge detector treated 3 empty filtered scans as 'adapter corrupted / system reboot required' and fired on_error('critical') - a false positive that tore the BLE interface down in the exact window the peer was about to come online.

Symptom (observed on two Pi Zero 2 W, BCM43430)

After reboot, both Pis logged:

Scanner corruption detected: 0 callbacks after 1.0s scan (streak: 1)
... (streak: 2, 3)
CRITICAL: Bleak scanner callbacks not firing
System reboot required to restore BLE scanning
[BLE Interface] detached

...within ~15s of boot, then recovered on their own. A genuinely wedged adapter can never recover without a reboot, so the detector was misattributing 'no peer advertising yet' to 'adapter corrupted' - and the resulting on_error('critical') was detaching the interface right when the peer was coming up.

Fix

When a service-filtered scan returns zero callbacks, run a short unfiltered health scan (BleakScanner.discover(timeout=1.0), no service filter):

• if it sees any device -> adapter is alive, just waiting for a peer -> reset streak, no critical
• if it sees nothing (or the health scan raises) -> counts toward the genuine-wedge streak -> critical after 3

This is detection-logic only. It does not change scan cadence, the service filter, or connection behavior. A real wedge (adapter blind to all devices) is still detected and still reports 'reboot required'.

Tests

tests/test_adapter_health_check_wedge.py - 5 tests driving the real _perform_scan() with a mocked BleakScanner:

1. empty-filtered-but-healthy -> NOT a wedge (the RED->GREEN regression: old code fired critical here)
2. fully-blind adapter -> critical after 3
3. blind-then-healthy -> streak resets, no critical
4. health-scan exception -> counts as blind (fail closed)
5. _adapter_health_check returns correct device count

All pass locally (verified via direct event-loop run); CI will run under pytest-asyncio.

Scope

src/ble_reticulum/linux_bluetooth_driver.py (+74/-11), new test file (+183). No changes to BLEInterface.py, so no impact on Android/iOS - this is Linux driver-only wedge detection.

[codecov]

Codecov Report

❌ Patch coverage is 96.87500% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/ble_reticulum/linux_bluetooth_driver.py	96.87%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Confidence Score: 4/5

[Medium risk] Refines Bluetooth adapter health detection logic.

The PR is not yet safe to merge because a blind scanner can remain powered and still never report a critical fault.

Findings

1.  Startup scan fault stays hidden ▶

Fix with agent prompt

### Issue 1
src/ble_reticulum/linux_bluetooth_driver.py:undefined-761
If an adapter is already blind when the driver starts but both scans finish without errors, `healthy_ever` stays false. Even after many empty scans, the driver only warns and never raises the critical fault signal. A real startup fault that returns empty results can leave discovery dead without that signal. The driver needs a way to distinguish this case from a quiet room.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The Linux Bluetooth driver now checks adapter health when a service-filtered scan finds no Reticulum peers. This separates a peer that has not started advertising from signs of an adapter fault.

• Nearby BLE devices clear the empty-scan streak; repeated health-scan failures or an unpowered adapter can still trigger a critical error.
• The PR adds tests for empty scans, connection pauses, and the BlueZ power-state check.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Service-filtered scan sees no peer] --> B[Unfiltered health scan]
  B -->|Sees a device| C[Reset empty-scan streak]
  B -->|Scan fails| D[Count a fault]
  B -->|Sees no device| E[Check adapter power after three scans]
  E -->|Not powered| F[Report critical fault]
  E -->|Powered or unknown| G[Warn without critical fault]
  E -->|Query times out| G

Loading

_{Reviews (7) · Last reviewed commit: "fix: bound the _adapter_is_powered() D-B..."}

[greptile-apps]

Startup scan fault stays hidden

If an adapter is already blind when the driver starts but both scans finish without errors, healthy_ever stays false. Even after many empty scans, the driver only warns and never raises the critical fault signal. A real startup fault that returns empty results can leave discovery dead without that signal. The driver needs a way to distinguish this case from a quiet room.

Knowledge Base Used: Linux adapter recovery and error handling

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/ble_reticulum/linux_bluetooth_driver.py
Line: 761

Comment:
**Startup scan fault stays hidden**

If an adapter is already blind when the driver starts but both scans finish without errors, `healthy_ever` stays false. Even after many empty scans, the driver only warns and never raises the critical fault signal. A real startup fault that returns empty results can leave discovery dead without that signal. The driver needs a way to distinguish this case from a quiet room.

**Knowledge Base Used:** [Linux adapter recovery and error handling](https://app.greptile.com/torlando-tech/-/custom-context/knowledge-base/torlando-tech/ble-reticulum/-/docs/linux-adapter-recovery.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.