@offline-protocol/mesh-sdk 0.2.1 → 0.2.3

package/android/src/main/java/com/offlineprotocol/BleManager.kt

@@ -71,16 +71,21 @@ class BleManager(
         private const val FRAGMENT_POLL_INTERVAL_MS = 100L // 100ms
         private const val MAX_FRAGMENT_SIZE = 185
         private const val CONNECTION_TIMEOUT_MS = 10000L
-        private const val SCAN_WATCHDOG_INTERVAL_MS = 20000L
+        private const val SCAN_WATCHDOG_INTERVAL_MS = 30000L // Match iOS timing
         private const val SCAN_WATCHDOG_HEARTBEAT_MS = 10000L
         private const val MAX_CONNECTIONS_PER_DEVICE = 4
         private const val ADVERTISE_RESTART_MIN_MS = 200L
         private const val ADVERTISE_RESTART_MAX_MS = 1200L
         private const val MIN_ADVERTISE_INTERVAL_MS = 1500L
+        private const val MIN_RECONNECT_INTERVAL_MS = 5_000L // Match iOS timing
+        private const val MAX_RECONNECT_INTERVAL_MS = 60_000L
+        private const val MAX_CONNECTION_RETRIES = 5
         
         // Adaptive Scan Configuration
-        /** Minimum RSSI to consider for connection (filter weak signals early) */
+        /** Minimum RSSI to consider for connection (filter weak signals early) - matches iOS */
         private const val ADAPTIVE_MIN_RSSI = -85
+        /** Absolute minimum RSSI below which we refuse to connect - matches iOS */
+        private const val MINIMUM_RSSI_TO_CONNECT = -90
         /** Peer count threshold below which we process all advertisements */
         private const val ADAPTIVE_LOW_DENSITY_THRESHOLD = 10
         /** Peer count threshold above which we apply maximum throttling */
@@ -91,6 +96,24 @@ class BleManager(
         private const val ADAPTIVE_COOLDOWN_PER_DEVICE_MS = 30_000L
         /** Interval for updating visible peer count estimate (ms) */
         private const val ADAPTIVE_PEER_COUNT_WINDOW_MS = 5_000L
+        /** Rate limit for unknown device GATT verification attempts (ms) */
+        private const val UNKNOWN_DEVICE_RATE_LIMIT_MS = 5_000L // More aggressive for cross-platform discovery
+        /** Minimum RSSI for unknown device to be considered for GATT verification */
+        private const val UNKNOWN_DEVICE_MIN_RSSI = -80 // More lenient for cross-platform discovery
+        /** Maximum unknown device verification attempts per minute */
+        private const val MAX_UNKNOWN_DEVICE_ATTEMPTS_PER_MINUTE = 10
+        /** Proactive scan refresh interval even when discoveries are occurring (ms) */
+        private const val PROACTIVE_SCAN_REFRESH_MS = 60_000L
+        /** Force a complete BLE stack refresh periodically even when things seem healthy (ms) */
+        private const val FORCED_BLE_REFRESH_MS = 120_000L
+        /** Maximum consecutive scan restarts before resetting BLE adapter */
+        private const val MAX_CONSECUTIVE_SCAN_RESTARTS = 3
+        /** Backoff period after resetting BLE adapter (ms) */
+        private const val ADAPTER_RESET_BACKOFF_MS = 45_000L
+        /** Connection monitor interval for periodic reconnection attempts (ms) */
+        private const val CONNECTION_MONITOR_INTERVAL_MS = 5_000L
+        /** Initial aggressive discovery phase duration (ms) - more frequent scanning initially */
+        private const val AGGRESSIVE_DISCOVERY_PHASE_MS = 30_000L
     }
     
     // MARK: - Properties
@@ -129,6 +152,7 @@ class BleManager(
     private data class MeshObservation(val advertisement: MeshAdvertisementData, val rssi: Int?, val timestamp: Long)
     private val pendingFragments = ConcurrentHashMap<String, MutableList<PendingFragment>>()
     private val PENDING_FRAGMENT_TIMEOUT_MS = 5000L
+    private val connectionRetryCount = ConcurrentHashMap<String, Int>()
     private val LOAD_SATURATION_COUNT = 20
     private val MESH_OBSERVATION_TTL_MS = 120_000L
     private val deviceIdResolutionAttempts = ConcurrentHashMap<String, Long>()
@@ -147,6 +171,23 @@ class BleManager(
     /** Last time we updated the peer count estimate */
     @Volatile private var lastPeerCountUpdate: Long = 0L
     @Volatile private var lastMeshAdvertisement: MeshAdvertisementData? = null
+    /** Rate limiting for unknown connectable devices that need GATT verification */
+    private val unknownDeviceAttempts = ConcurrentHashMap<String, Long>()
+    /** Last time we proactively refreshed the scan */
+    @Volatile private var lastProactiveScanRefresh: Long = 0L
+    /** Last time we performed a forced BLE refresh */
+    @Volatile private var lastForcedBleRefresh: Long = 0L
+    /** Tracks recently seen advertisements to avoid duplicate processing (hash, timestamp) */
+    private data class AdvertisementCacheEntry(val hash: Int, val timestamp: Long)
+    private val recentAdvertisementHashes = ConcurrentHashMap<String, AdvertisementCacheEntry>()
+    /** Tracks connected centrals (devices that connected to our GATT server) for connection count */
+    private val connectedCentrals = ConcurrentHashMap<String, Long>()
+    /** Counter for consecutive scan restarts without discoveries */
+    @Volatile private var scanRestartCount = 0
+    /** Last time we reset the BLE adapter */
+    @Volatile private var lastAdapterReset: Long = 0L
+    /** Connection monitor runnable for periodic reconnection attempts */
+    private var connectionMonitorRunnable: Runnable? = null
     
     // Fragment polling
     private val mainHandler = Handler(Looper.getMainLooper())
@@ -214,13 +255,58 @@ class BleManager(
                     Log.w(TAG, "Restarting BLE scan after ${idleMs}ms of inactivity")
                     emitDiagnostic("warning", "Restarting BLE scan due to inactivity", mapOf("idleMs" to idleMs))
                 }
+                scanRestartCount++
                 restartScanning("watchdog")
+                evaluateBleHealthAfterRestart()
                 return
             }
             mainHandler.postDelayed(this, SCAN_WATCHDOG_HEARTBEAT_MS)
         }
     }
     
+    /**
+     * Evaluates BLE stack health after consecutive restarts and resets adapter if needed.
+     * This mirrors iOS's evaluateCentralHealthAfterRestart mechanism.
+     */
+    private fun evaluateBleHealthAfterRestart() {
+        if (scanRestartCount < MAX_CONSECUTIVE_SCAN_RESTARTS) {
+            return
+        }
+        
+        val now = System.currentTimeMillis()
+        if (lastAdapterReset > 0 && now - lastAdapterReset < ADAPTER_RESET_BACKOFF_MS) {
+            return
+        }
+        
+        Log.w(TAG, "Resetting BLE stack due to repeated scan stalls (restartCount=$scanRestartCount)")
+        emitDiagnostic("warning", "Resetting BLE stack due to repeated scan stalls", mapOf(
+            "restartCount" to scanRestartCount
+        ))
+        
+        lastAdapterReset = now
+        scanRestartCount = 0
+        
+        // Force stop and restart everything
+        mainHandler.post {
+            if (state == TransportState.RUNNING) {
+                stopScanning("ble_reset")
+                stopAdvertising()
+                
+                // Re-initialize scanner and advertiser
+                bluetoothLeScanner = bluetoothAdapter?.bluetoothLeScanner
+                bluetoothLeAdvertiser = bluetoothAdapter?.bluetoothLeAdvertiser
+                
+                // Restart after a brief delay
+                mainHandler.postDelayed({
+                    if (state == TransportState.RUNNING) {
+                        startScanning("ble_reset")
+                        startAdvertising("ble_reset")
+                    }
+                }, 1000)
+            }
+        }
+    }
+    
     // Metrics
     private var bytesSent: Long = 0
     private var bytesReceived: Long = 0
@@ -409,7 +495,15 @@ class BleManager(
         pendingFragments.clear()
         pendingOutboundFragments.clear()
         lastSeenMeshAdvertisements.clear()
+        unknownDeviceAttempts.clear()
+        recentAdvertisementHashes.clear()
+        connectionRetryCount.clear()
+        connectedCentrals.clear()
+        scanRestartCount = 0
+        lastAdapterReset = 0L
         transportStartAt = 0L
+        lastProactiveScanRefresh = 0L
+        lastForcedBleRefresh = 0L
         
         // Close GATT server
         gattServer?.close()
@@ -570,9 +664,11 @@ class BleManager(
                 .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
                 .build()
             
-            val scanFilter = ScanFilter.Builder()
-                .setServiceUuid(ParcelUuid(SERVICE_UUID))
-                .build()
+            // CRITICAL FIX: Scan without service UUID filter for iOS ↔ Android interoperability
+            // iOS's CoreBluetooth has known issues recognizing 128-bit service UUIDs from Android
+            // advertisements, and vice versa. Scanning without filter and filtering in software
+            // ensures we discover all mesh devices regardless of platform quirks.
+            // We filter in handleScanResult using shouldProcessDiscoveredDevice().
             
             scanCallback = object : ScanCallback() {
                 override fun onScanResult(callbackType: Int, result: ScanResult) {
@@ -600,14 +696,28 @@ class BleManager(
                 }
             }
             
-            scanner.startScan(listOf(scanFilter), scanSettings, scanCallback)
+            // Scan without filter - we'll filter in software for cross-platform compatibility
+            scanner.startScan(null, scanSettings, scanCallback)
             isScanning = true
-            lastDiscoveryAt = System.currentTimeMillis()
+            val now = System.currentTimeMillis()
+            lastDiscoveryAt = now
+            lastProactiveScanRefresh = now
+            // Reset restart count on non-watchdog starts
+            if (reason != "restart_watchdog") {
+                scanRestartCount = 0
+            }
             scheduleScanWatchdog()
+            startConnectionMonitor()
             if (logThrottler.shouldLog("scan_started")) {
-                Log.i(TAG, "✅ BLE scanning started successfully (reason: $reason)")
-                emitDiagnostic("info", "BLE scanning started", mapOf("reason" to reason))
+                Log.i(TAG, "BLE scanning started (no filter, reason: $reason)")
+                emitDiagnostic("info", "BLE scanning started", mapOf(
+                    "reason" to reason,
+                    "filterless" to true
+                ))
             }
+            
+            // Rehydrate previously connected devices to avoid waiting for advertisements
+            rehydratePreviouslyConnectedDevices()
         } catch (e: SecurityException) {
             Log.e(TAG, "Permission denied while starting scan", e)
             emitDiagnostic("error", "Permission denied while starting scan", mapOf("exception" to e.javaClass.simpleName, "message" to (e.message ?: "unknown")))
@@ -615,6 +725,28 @@ class BleManager(
         }
     }
     
+    /**
+     * Attempts to reconnect to previously known devices without waiting for advertisements.
+     * This speeds up rediscovery after app restart or Bluetooth toggle.
+     */
+    private fun rehydratePreviouslyConnectedDevices() {
+        try {
+            val bondedDevices = bluetoothAdapter?.bondedDevices ?: return
+            for (device in bondedDevices) {
+                val address = device.address
+                // Only attempt if we previously had this device in our registry
+                if (connections.hasDeviceForAddress(address) && connections.getGatt(address) == null) {
+                    if (logThrottler.shouldLog("rehydrate_$address", intervalMs = 30_000)) {
+                        Log.d(TAG, "Rehydrating connection to bonded device: $address")
+                    }
+                    connectToDevice(device)
+                }
+            }
+        } catch (e: SecurityException) {
+            Log.w(TAG, "Cannot access bonded devices for rehydration", e)
+        }
+    }
+    
     private fun stopScanning(reason: String = "manual") {
         if (!isScanning) return
         
@@ -623,6 +755,7 @@ class BleManager(
             scanCallback = null
             isScanning = false
             cancelScanWatchdog()
+            cancelConnectionMonitor()
             lastDiscoveryAt = 0L
             discoveryLogTimestamps.clear()
             if (logThrottler.shouldLog("scan_stopped")) {
@@ -649,6 +782,94 @@ class BleManager(
         mainHandler.removeCallbacks(scanWatchdogRunnable)
     }
     
+    /**
+     * Starts the connection monitor that periodically attempts to reconnect to discovered devices.
+     * This mirrors iOS's startConnectionMonitor mechanism for more reliable discovery.
+     */
+    private fun startConnectionMonitor() {
+        cancelConnectionMonitor()
+        
+        connectionMonitorRunnable = object : Runnable {
+            override fun run() {
+                if (state != TransportState.RUNNING) {
+                    return
+                }
+                
+                val now = System.currentTimeMillis()
+                
+                // Check for discovered devices that aren't connected
+                for ((address, observation) in lastSeenMeshAdvertisements) {
+                    // Skip if already connected
+                    if (connections.getGatt(address) != null) {
+                        continue
+                    }
+                    
+                    // Skip if we've hit connection cap
+                    if (currentConnectionCount() >= MAX_CONNECTIONS_PER_DEVICE) {
+                        break
+                    }
+                    
+                    // Skip if observation is too old
+                    if (now - observation.timestamp > MESH_OBSERVATION_TTL_MS) {
+                        continue
+                    }
+                    
+                    // Skip if RSSI too weak
+                    val rssi = observation.rssi ?: continue
+                    if (rssi < MINIMUM_RSSI_TO_CONNECT) {
+                        continue
+                    }
+                    
+                    // Rate limit attempts to this device
+                    val lastAttempt = deviceConnectionAttempts[address]
+                    if (lastAttempt != null && now - lastAttempt < MIN_RECONNECT_INTERVAL_MS) {
+                        continue
+                    }
+                    
+                    // Try to connect
+                    try {
+                        val device = bluetoothAdapter?.getRemoteDevice(address) ?: continue
+                        recordConnectionAttempt(address, now)
+                        connectToDevice(device)
+                    } catch (e: Exception) {
+                        Log.w(TAG, "Connection monitor: failed to get remote device $address", e)
+                    }
+                }
+                
+                // Also check for pending fragments that need device ID resolution
+                for (address in pendingFragments.keys) {
+                    if (connections.deviceIdForAddress(address) != null) {
+                        continue
+                    }
+                    
+                    val lastAttempt = deviceIdResolutionAttempts[address]
+                    if (lastAttempt != null && now - lastAttempt < MIN_RECONNECT_INTERVAL_MS) {
+                        continue
+                    }
+                    
+                    deviceIdResolutionAttempts[address] = now
+                    try {
+                        val device = bluetoothAdapter?.getRemoteDevice(address)
+                        if (device != null && connections.getGatt(address) == null) {
+                            connectToDevice(device)
+                        }
+                    } catch (e: Exception) {
+                        Log.w(TAG, "Connection monitor: failed to resolve device ID for $address", e)
+                    }
+                }
+                
+                mainHandler.postDelayed(this, CONNECTION_MONITOR_INTERVAL_MS)
+            }
+        }
+        
+        mainHandler.postDelayed(connectionMonitorRunnable!!, CONNECTION_MONITOR_INTERVAL_MS)
+    }
+    
+    private fun cancelConnectionMonitor() {
+        connectionMonitorRunnable?.let { mainHandler.removeCallbacks(it) }
+        connectionMonitorRunnable = null
+    }
+    
     private fun startAdvertising(reason: String = "manual") {
         if (isAdvertising) return
         
@@ -674,7 +895,7 @@ class BleManager(
             
             advertiseCallback = object : AdvertiseCallback() {
                 override fun onStartSuccess(settingsInEffect: AdvertiseSettings) {
-                    Log.i(TAG, "✅ BLE advertising started successfully (reason=$reason)")
+                    Log.i(TAG, "BLE advertising started successfully (reason=$reason)")
                     isAdvertising = true
                     lastAdvertiseRestartAt = System.currentTimeMillis()
                     emitDiagnostic("info", "BLE advertising started", mapOf("reason" to reason))
@@ -698,7 +919,11 @@ class BleManager(
                 }
             }
             
-            bluetoothLeAdvertiser?.startAdvertising(settings, advertiseData, advertiseCallback)
+            // Include scan response with service UUID for iOS compatibility
+            // iOS's CoreBluetooth actively queries for scan responses and has known issues
+            // recognizing 128-bit service UUIDs from Android's main advertisement packet
+            val scanResponse = buildScanResponse()
+            bluetoothLeAdvertiser?.startAdvertising(settings, advertiseData, scanResponse, advertiseCallback)
             
             // Reduced logging
         } catch (e: SecurityException) {
@@ -762,6 +987,21 @@ class BleManager(
             .build()
     }
     
+    /**
+     * Builds the scan response data for BLE advertising.
+     * 
+     * iOS's CoreBluetooth actively queries for scan responses during BLE scanning.
+     * Including the service UUID in the scan response makes Android devices more
+     * reliably visible to iOS devices, which have known issues recognizing 128-bit
+     * service UUIDs from Android's main advertisement packet format.
+     */
+    private fun buildScanResponse(): AdvertiseData {
+        return AdvertiseData.Builder()
+            .setIncludeDeviceName(false)
+            .addServiceUuid(ParcelUuid(SERVICE_UUID))
+            .build()
+    }
+    
     private fun handleScanResult(result: ScanResult) {
         val device = result.device
         val rssi = result.rssi
@@ -769,9 +1009,42 @@ class BleManager(
         val now = System.currentTimeMillis()
         lastDiscoveryAt = now
         
+        // Duplicate advertisement detection - avoid processing identical advertisements
+        // This improves performance in dense networks
+        val advertHash = computeAdvertisementHash(result)
+        val cached = recentAdvertisementHashes[address]
+        if (cached != null && cached.hash == advertHash && now - cached.timestamp < 1000L) {
+            return // Skip duplicate advertisement
+        }
+        recentAdvertisementHashes[address] = AdvertisementCacheEntry(advertHash, now)
+        
+        // Prune old advertisement cache entries periodically
+        if (recentAdvertisementHashes.size > 100) {
+            val cutoff = now - 30_000L
+            val iterator = recentAdvertisementHashes.entries.iterator()
+            while (iterator.hasNext()) {
+                if (iterator.next().value.timestamp < cutoff) {
+                    iterator.remove()
+                }
+            }
+        }
+        
         // Adaptive scanning: track discoveries for density estimation
         recordDiscoveryForDensity(now)
         
+        // CRITICAL: Software-based filtering for iOS ↔ Android interoperability
+        // Since we scan without a service UUID filter, we filter here instead.
+        val scanRecord = result.scanRecord
+        val isConnectable = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            result.isConnectable
+        } else {
+            true // Assume connectable on older Android
+        }
+        
+        if (!shouldProcessDiscoveredDevice(address, scanRecord, rssi, isConnectable, now)) {
+            return
+        }
+        
         // Adaptive scanning: early RSSI filtering in dense networks
         if (shouldFilterByRssi(rssi)) {
             if (logThrottler.shouldLog("adaptive_rssi_filter", intervalMs = 10000)) {
@@ -786,11 +1059,6 @@ class BleManager(
         }
         
         val lastLog = discoveryLogTimestamps[address]
-        val isConnectable = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            result.isConnectable
-        } else {
-            null
-        }
         if (lastLog == null || now - lastLog > 30000) {
             discoveryLogTimestamps[address] = now
             Log.d(TAG, "Discovered device $address RSSI=$rssi (density: $estimatedVisiblePeerCount)")
@@ -800,14 +1068,13 @@ class BleManager(
                 mapOf(
                     "address" to address,
                     "rssi" to rssi,
-                    "connectable" to (isConnectable ?: true),
+                    "connectable" to isConnectable,
                     "visiblePeers" to estimatedVisiblePeerCount
                 )
             )
         }
         lastSeenRssi[address] = rssi.toShort()
 
-        val scanRecord = result.scanRecord
         val serviceData = scanRecord?.getServiceData(ParcelUuid(SERVICE_UUID))
         val meshMetadata = MeshAdvertisementData.decode(serviceData)
         meshMetadata?.let {
@@ -837,11 +1104,23 @@ class BleManager(
         }
         
         // Adaptive scanning: rate limit connection attempts
-        if (shouldThrottleConnection(address, now)) {
-            if (logThrottler.shouldLog("adaptive_throttle_$address", intervalMs = 30000)) {
-                Log.d(TAG, "Adaptive: throttling connection to $address")
+        // Skip throttling for first-time discoveries with strong signals for faster connection
+        val isFirstDiscovery = !lastSeenMeshAdvertisements.containsKey(address) && connections.getGatt(address) == null
+        val hasStrongSignal = rssi >= -70
+        
+        if (!isFirstDiscovery || !hasStrongSignal) {
+            if (shouldThrottleConnection(address, now)) {
+                if (logThrottler.shouldLog("adaptive_throttle_$address", intervalMs = 30000)) {
+                    Log.d(TAG, "Adaptive: throttling connection to $address")
+                }
+                return
             }
-            return
+        } else if (isFirstDiscovery && hasStrongSignal) {
+            Log.d(TAG, "Fast-tracking first discovery with strong signal: $address RSSI=$rssi")
+            emitDiagnostic("info", "Fast-tracking first discovery", mapOf(
+                "address" to address,
+                "rssi" to rssi
+            ))
         }
 
         if (!meshController.connectionBudgetAvailable() && decision.evictPeerId != null) {
@@ -879,19 +1158,209 @@ class BleManager(
         }
 
         maybeHandleRebalance("scan")
+        
+        // Check if we should proactively refresh the scan
+        maybeProactivelyRefreshScan(now)
+    }
+    
+    /**
+     * Determines if a discovered device should be processed.
+     * Implements smart filtering since we scan without a service UUID filter
+     * (required for iOS ↔ Android interoperability).
+     *
+     * Accepts:
+     * - Devices advertising our service UUID
+     * - Devices with our service data
+     * - Previously discovered mesh devices
+     * - Unknown connectable devices (rate-limited, verified via GATT)
+     */
+    private fun shouldProcessDiscoveredDevice(
+        address: String,
+        scanRecord: android.bluetooth.le.ScanRecord?,
+        rssi: Int,
+        isConnectable: Boolean,
+        now: Long
+    ): Boolean {
+        // 1. Check if device is advertising our service UUID
+        val serviceUuids = scanRecord?.serviceUuids
+        if (serviceUuids != null) {
+            for (uuid in serviceUuids) {
+                if (uuid.uuid == SERVICE_UUID) {
+                    return true
+                }
+            }
+        }
+        
+        // 2. Check for our service data
+        val serviceData = scanRecord?.getServiceData(ParcelUuid(SERVICE_UUID))
+        if (serviceData != null) {
+            return true
+        }
+        
+        // 3. Check if this is a previously discovered mesh device
+        if (lastSeenMeshAdvertisements.containsKey(address)) {
+            return true
+        }
+        
+        // 4. Check if we already have a device ID mapping for this device
+        if (connections.deviceIdForAddress(address) != null) {
+            return true
+        }
+        
+        // 5. Check if we have an active GATT connection to this device
+        if (connections.getGatt(address) != null) {
+            return true
+        }
+        
+        // 6. For unknown connectable devices, allow with rate limiting
+        //    These will be verified via GATT service discovery after connection
+        //    This is CRITICAL for iOS ↔ Android cross-platform discovery since
+        //    each platform may not recognize the other's service UUID format in advertisements
+        if (isConnectable) {
+            // Rate limit unknown device connection attempts
+            val lastAttempt = unknownDeviceAttempts[address]
+            if (lastAttempt != null && now - lastAttempt < UNKNOWN_DEVICE_RATE_LIMIT_MS) {
+                return false
+            }
+            
+            // Check global rate limit for unknown device attempts
+            val recentUnknownAttempts = unknownDeviceAttempts.values.count { 
+                now - it < 60_000L 
+            }
+            if (recentUnknownAttempts >= MAX_UNKNOWN_DEVICE_ATTEMPTS_PER_MINUTE) {
+                return false
+            }
+            
+            // Only process signals above minimum threshold for unknown devices
+            // Use a tiered approach: stronger signals get priority
+            val shouldAttempt = when {
+                rssi >= -70 -> true  // Strong signal - always try
+                rssi >= UNKNOWN_DEVICE_MIN_RSSI && recentUnknownAttempts < MAX_UNKNOWN_DEVICE_ATTEMPTS_PER_MINUTE / 2 -> true
+                else -> false
+            }
+            
+            if (shouldAttempt) {
+                unknownDeviceAttempts[address] = now
+                if (logThrottler.shouldLog("unknown_connectable_$address", intervalMs = 30_000)) {
+                    Log.d(TAG, "Allowing unknown connectable device for GATT verification: $address RSSI=$rssi")
+                    emitDiagnostic("debug", "Allowing unknown device for GATT verification", mapOf(
+                        "address" to address,
+                        "rssi" to rssi,
+                        "recentAttempts" to recentUnknownAttempts
+                    ))
+                }
+                return true
+            }
+        }
+        
+        // Filter out all other devices (not our mesh network)
+        return false
     }
     
+    /**
+     * Proactively refreshes the scan periodically to ensure we don't miss devices
+     * due to BLE stack issues or cached state.
+     */
+    private fun maybeProactivelyRefreshScan(now: Long) {
+        if (now - lastProactiveScanRefresh >= PROACTIVE_SCAN_REFRESH_MS) {
+            lastProactiveScanRefresh = now
+            if (logThrottler.shouldLog("proactive_scan_refresh", intervalMs = PROACTIVE_SCAN_REFRESH_MS)) {
+                Log.d(TAG, "Proactively refreshing BLE scan")
+                emitDiagnostic("info", "Proactive scan refresh")
+            }
+            restartScanning("proactive_refresh")
+        }
+        
+        // Forced complete BLE refresh - more aggressive than proactive refresh
+        // This helps recover from edge cases where the BLE stack becomes stuck
+        val lastForced = if (lastForcedBleRefresh == 0L) transportStartAt else lastForcedBleRefresh
+        if (now - lastForced >= FORCED_BLE_REFRESH_MS) {
+            lastForcedBleRefresh = now
+            if (logThrottler.shouldLog("forced_ble_refresh", intervalMs = FORCED_BLE_REFRESH_MS)) {
+                Log.i(TAG, "Performing forced BLE refresh for reliability")
+                emitDiagnostic("info", "Forced BLE refresh for reliability", mapOf(
+                    "connectedPeers" to connections.connectionCount(),
+                    "discoveredPeers" to connections.discoveredPeerCount()
+                ))
+            }
+            // Stop and restart both scanning and advertising
+            stopScanning("forced_refresh")
+            refreshAdvertising("forced_refresh")
+            mainHandler.postDelayed({
+                if (state == TransportState.RUNNING) {
+                    startScanning("forced_refresh")
+                }
+            }, 500)
+        }
+    }
+    
+    /**
+     * Computes a hash of the advertisement data for duplicate detection.
+     * Uses device address, RSSI bucket, and key advertisement data.
+     */
+    private fun computeAdvertisementHash(result: ScanResult): Int {
+        var hash = result.device.address.hashCode()
+        // Use RSSI buckets of 5 dBm to avoid hash changes from minor signal fluctuations
+        hash = 31 * hash + (result.rssi / 5)
+        
+        val scanRecord = result.scanRecord
+        if (scanRecord != null) {
+            // Include service UUIDs
+            scanRecord.serviceUuids?.forEach { uuid ->
+                hash = 31 * hash + uuid.hashCode()
+            }
+            
+            // Include service data
+            val serviceData = scanRecord.getServiceData(ParcelUuid(SERVICE_UUID))
+            if (serviceData != null) {
+                hash = 31 * hash + serviceData.contentHashCode()
+            }
+        }
+        
+        return hash
+    }
+    
+    /** Lock for atomic connection count check and connect operations */
+    private val connectionLock = Any()
+    
     private fun connectToDevice(device: BluetoothDevice) {
         try {
-            if (currentConnectionCount() >= MAX_CONNECTIONS_PER_DEVICE) {
-                if (logThrottler.shouldLog("mesh_conn_cap", intervalMs = 10000)) {
-                    Log.d(TAG, "Connection cap reached, not connecting to ${device.address}")
+            // Atomic check-and-connect to prevent race conditions
+            synchronized(connectionLock) {
+                // Check RSSI threshold - don't connect to devices with weak signals
+                val rssi = lastSeenRssi[device.address]?.toInt() ?: -60
+                if (rssi < MINIMUM_RSSI_TO_CONNECT) {
+                    if (logThrottler.shouldLog("rssi_skip_${device.address}", intervalMs = 10000)) {
+                        Log.d(TAG, "Skipping connection to ${device.address} due to weak RSSI ($rssi < $MINIMUM_RSSI_TO_CONNECT)")
+                        emitDiagnostic("debug", "Skipping BLE connect due to weak RSSI", mapOf(
+                            "address" to device.address,
+                            "rssi" to rssi,
+                            "threshold" to MINIMUM_RSSI_TO_CONNECT
+                        ))
+                    }
+                    connections.consumePendingRole(device.address)
+                    return
                 }
-                connections.consumePendingRole(device.address)
-                return
+                
+                if (currentConnectionCount() >= MAX_CONNECTIONS_PER_DEVICE) {
+                    if (logThrottler.shouldLog("mesh_conn_cap", intervalMs = 10000)) {
+                        Log.d(TAG, "Connection cap reached, not connecting to ${device.address}")
+                    }
+                    connections.consumePendingRole(device.address)
+                    return
+                }
+                
+                // Double-check we don't already have a connection to this device
+                if (connections.getGatt(device.address) != null) {
+                    if (logThrottler.shouldLog("already_connecting_${device.address}", intervalMs = 5000)) {
+                        Log.d(TAG, "Already have GATT client for ${device.address}")
+                    }
+                    return
+                }
+                
+                val gatt = device.connectGatt(context, false, gattClientCallback, BluetoothDevice.TRANSPORT_LE)
+                connections.registerGatt(device.address, gatt)
             }
-            val gatt = device.connectGatt(context, false, gattClientCallback, BluetoothDevice.TRANSPORT_LE)
-            connections.registerGatt(device.address, gatt)
             
             Log.i(TAG, "Connecting to device: ${device.address}")
             emitDiagnostic("info", "Connecting to BLE device", mapOf("address" to device.address))
@@ -902,7 +1371,7 @@ class BleManager(
         }
     }
 
-    private fun currentConnectionCount(): Int = connections.connectionCount()
+    private fun currentConnectionCount(): Int = connections.connectionCount() + connectedCentrals.size
 
     private fun refreshSelfMetrics() {
         val rssiValues = lastSeenRssi.values.map { it.toInt() }
@@ -971,6 +1440,7 @@ class BleManager(
         pendingFragments.remove(address)
         pendingOutboundFragments.remove(peerId)
         deviceIdResolutionAttempts.remove(address)
+        connectionRetryCount.remove(address)
         meshController.registerDisconnection(peerId)
         refreshSelfMetrics()
 
@@ -1362,6 +1832,13 @@ class BleManager(
     
     /** Checks if we should skip this device based on RSSI filtering. */
     private fun shouldFilterByRssi(rssi: Int): Boolean {
+        // During aggressive discovery phase, don't apply density-based filtering
+        val now = System.currentTimeMillis()
+        if (transportStartAt > 0 && now - transportStartAt < AGGRESSIVE_DISCOVERY_PHASE_MS) {
+            // Only filter out extremely weak signals during aggressive phase
+            return rssi < MINIMUM_RSSI_TO_CONNECT
+        }
+        
         // In dense networks, apply stricter RSSI filtering
         val threshold = when {
             estimatedVisiblePeerCount > ADAPTIVE_HIGH_DENSITY_THRESHOLD -> -70
@@ -1373,21 +1850,36 @@ class BleManager(
     
     /** Checks if we should throttle connection attempts based on rate limits. */
     private fun shouldThrottleConnection(address: String, now: Long): Boolean {
+        // During aggressive discovery phase, use much shorter cooldowns
+        val isAggressivePhase = transportStartAt > 0 && now - transportStartAt < AGGRESSIVE_DISCOVERY_PHASE_MS
+        
         // Prune old entries
         val oneMinuteAgo = now - 60_000L
         synchronized(globalConnectionAttempts) {
             globalConnectionAttempts.removeAll { it < oneMinuteAgo }
         }
+        
+        val effectiveCooldown = if (isAggressivePhase) 5_000L else ADAPTIVE_COOLDOWN_PER_DEVICE_MS
         deviceConnectionAttempts.entries.removeIf { 
-            now - it.value >= ADAPTIVE_COOLDOWN_PER_DEVICE_MS 
+            now - it.value >= effectiveCooldown 
         }
         
         // Check per-device cooldown
         val lastAttempt = deviceConnectionAttempts[address]
-        if (lastAttempt != null && now - lastAttempt < ADAPTIVE_COOLDOWN_PER_DEVICE_MS) {
+        if (lastAttempt != null && now - lastAttempt < effectiveCooldown) {
             return true
         }
         
+        // During aggressive phase, allow more connection attempts
+        if (isAggressivePhase) {
+            // Allow up to 3x the normal rate during aggressive phase
+            val maxAttempts = ADAPTIVE_MAX_CONNECTIONS_PER_MINUTE * 3
+            if (globalConnectionAttempts.size >= maxAttempts) {
+                return true
+            }
+            return false
+        }
+        
         // In dense networks, apply global rate limiting
         if (estimatedVisiblePeerCount > ADAPTIVE_LOW_DENSITY_THRESHOLD) {
             val currentAttempts = globalConnectionAttempts.size
@@ -1518,12 +2010,19 @@ class BleManager(
                         gattServer?.cancelConnection(device)
                         return
                     }
+                    // Check connection capacity
+                    if (currentConnectionCount() >= MAX_CONNECTIONS_PER_DEVICE) {
+                        Log.w(TAG, "Rejecting inbound connection from ${device.address}: connection cap reached")
+                        gattServer?.cancelConnection(device)
+                        return
+                    }
                     val role = when (decision.intent) {
                         ConnectionIntent.INTER_CLUSTER -> MeshRole.BRIDGE
                         ConnectionIntent.INTRA_CLUSTER, ConnectionIntent.REJECTED -> MeshRole.MEMBER
                     }
                     connections.trackServerConnection(device.address)
                     connections.setPendingRole(device.address, role)
+                    connectedCentrals[device.address] = System.currentTimeMillis()
                     Log.i(TAG, "GATT server: Device connected: ${device.address} (role=$role)")
                     emitDiagnostic("info", "Device connected to GATT server", mapOf("address" to device.address))
                 }
@@ -1531,6 +2030,7 @@ class BleManager(
                     val address = device.address
                     connections.untrackServerConnection(address)
                     connections.consumePendingRole(address)
+                    connectedCentrals.remove(address)
                     // Don't immediately remove - connection might be re-established
                     // Only remove if it's a permanent error (status != 0)
                     if (status != 0 && status != 19) { // Not normal disconnect or connection timeout
@@ -1657,7 +2157,43 @@ class BleManager(
                     
                     // Try to reconnect if we were connected and state is still running
                     if (wasConnected && state == TransportState.RUNNING) {
-                        // Attempt reconnection after a short delay
+                        // Increment retry count and calculate backoff
+                        val retryCount = (connectionRetryCount[address] ?: 0) + 1
+                        connectionRetryCount[address] = retryCount
+                        
+                        // Give up after max retries
+                        if (retryCount > MAX_CONNECTION_RETRIES) {
+                            Log.w(TAG, "Max retries ($MAX_CONNECTION_RETRIES) exceeded for $address on disconnect, giving up")
+                            emitDiagnostic("warning", "Max connection retries exceeded", mapOf(
+                                "address" to address,
+                                "retryCount" to retryCount
+                            ))
+                            connectionRetryCount.remove(address)
+                            // Notify peer lost since we're giving up
+                            connections.deviceIdForAddress(address)?.let { peerId ->
+                                protocol.removeNeighborRoutes(peerId)
+                                try {
+                                    protocol.blePeerLost(peerId)
+                                } catch (e: Exception) {
+                                    Log.e(TAG, "Error notifying peer lost", e)
+                                }
+                                meshController.registerDisconnection(peerId)
+                                refreshSelfMetrics()
+                                connections.removeIdentifiersForAddress(address)
+                                connections.removeConnectionRole(peerId)
+                                mainHandler.post {
+                                    if (state == TransportState.RUNNING) {
+                                        refreshAdvertising("disconnect_max_retries")
+                                    }
+                                }
+                                maybeHandleRebalance("disconnect_max_retries")
+                            }
+                            return@onConnectionStateChange
+                        }
+                        
+                        // Exponential backoff: 5s, 10s, 20s, 40s, 60s (capped)
+                        val backoffInterval = minOf(MAX_RECONNECT_INTERVAL_MS, MIN_RECONNECT_INTERVAL_MS * (1L shl (retryCount - 1)))
+                        
                         mainHandler.postDelayed({
                             if (state == TransportState.RUNNING && connections.hasDeviceForAddress(address)) {
                                 try {
@@ -1669,7 +2205,7 @@ class BleManager(
                                     Log.e(TAG, "Error reconnecting to device", e)
                                 }
                             }
-                        }, 1000)
+                        }, backoffInterval)
                     } else {
                         // Notify protocol of peer loss only if we're not reconnecting
                         connections.deviceIdForAddress(address)?.let { deviceId ->
@@ -1760,6 +2296,7 @@ class BleManager(
                 if (deviceIdValue != null) {
                     Log.i(TAG, "📝 Mapping ${gatt.device.address} -> $deviceIdValue")
                     connections.setDeviceIdentifier(gatt.device.address, deviceIdValue)
+                    connectionRetryCount.remove(gatt.device.address) // Reset retry count on successful connection
                     
                     val role = connections.consumePendingRole(gatt.device.address) ?: MeshRole.MEMBER
                     meshController.registerConnection(deviceIdValue, role)