Drop frequency of contact sync task, make standard polling opt-in only

app/AGENTS.md

@@ -87,7 +87,8 @@ app/
 - `RadioManager.post_connect_setup()` delegates to `services/radio_lifecycle.py`.
 - Routers, startup/lifespan code, fanout helpers, and `radio_sync.py` should reach radio state through `services/radio_runtime.py`, not by importing `app.radio.radio_manager` directly.
 - Shared reconnect/setup helpers in `services/radio_lifecycle.py` are used by startup, the monitor, and manual reconnect/reboot flows before broadcasting healthy state.
-- Setup still includes handler registration, key export, time sync, contact/channel sync, polling/advert tasks.
+- Setup still includes handler registration, key export, time sync, contact/channel sync, and advertisement tasks. Fallback message polling starts only when `MESHCORE_ENABLE_MESSAGE_POLL_FALLBACK=true`.
+- Post-connect setup is timeout-bounded. If initial radio offload/setup hangs too long, the backend logs the failure and broadcasts an `error` toast telling the operator to reboot the radio and restart the server.
 
 ## Important Behaviors
 
@@ -230,7 +231,7 @@ app/
 - `contact_deleted` — contact removed from database (payload: `{ public_key }`)
 - `channel` — single channel upsert/update (payload: full `Channel`)
 - `channel_deleted` — channel removed from database (payload: `{ key }`)
-- `error` — toast notification (reconnect failure, missing private key, etc.)
+- `error` — toast notification (reconnect failure, missing private key, stuck radio startup, etc.)
 - `success` — toast notification (historical decrypt complete, etc.)
 
 Backend WS sends go through typed serialization in `events.py`. Initial WS connect sends `health` only. Contacts/channels are loaded by REST.
@@ -250,6 +251,8 @@ Main tables:
 
 Repository writes should prefer typed models such as `ContactUpsert` over ad hoc dict payloads when adding or updating schema-coupled data.
 
+`max_radio_contacts` now controls how many favorite contacts are kept loaded on the radio for ACK support. The app no longer rotates recent non-favorite contacts onto the radio during normal background maintenance.
+
 `app_settings` fields in active model:
 - `max_radio_contacts`
 - `favorites`

app/config.py

@@ -18,6 +18,7 @@ class Settings(BaseSettings):
     log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
     database_path: str = "data/meshcore.db"
     disable_bots: bool = False
+    enable_message_poll_fallback: bool = False
 
     @model_validator(mode="after")
     def validate_transport_exclusivity(self) -> "Settings":

app/migrations.py

@@ -778,7 +778,7 @@ async def _migrate_009_create_app_settings_table(conn: aiosqlite.Connection) ->
     Create app_settings table for persistent application preferences.
 
     This table stores:
-    - max_radio_contacts: Max non-repeater contacts to keep on radio for DM ACKs
+    - max_radio_contacts: Max favorite contacts to keep on radio for DM ACKs
     - favorites: JSON array of favorite conversations [{type, id}, ...]
     - auto_decrypt_dm_on_advert: Whether to attempt historical DM decryption on new contact
     - sidebar_sort_order: 'recent' or 'alpha' for sidebar sorting

app/models.py

@@ -515,10 +515,7 @@ class AppSettings(BaseModel):
 
     max_radio_contacts: int = Field(
         default=200,
-        description=(
-            "Maximum contacts to keep on radio for DM ACKs "
-            "(favorite contacts first, then recent non-repeaters)"
-        ),
+        description="Maximum favorite contacts to keep on radio for DM ACKs",
     )
     favorites: list[Favorite] = Field(
         default_factory=list, description="List of favorited conversations"

app/packet_processor.py

@@ -29,7 +29,6 @@ from app.decoder import (
 )
 from app.keystore import get_private_key, get_public_key, has_private_key
 from app.models import (
-    CONTACT_TYPE_REPEATER,
     Contact,
     ContactUpsert,
     RawPacketBroadcast,
@@ -415,7 +414,6 @@ async def _process_advertisement(
     Process an advertisement packet.
 
     Extracts contact info and updates the database/broadcasts to clients.
-    For non-repeater contacts, triggers sync of recent contacts to radio for DM ACK support.
     """
     # Parse packet to get path info if not already provided
     if packet_info is None:
@@ -533,14 +531,6 @@ async def _process_advertisement(
         if settings.auto_decrypt_dm_on_advert:
             await start_historical_dm_decryption(None, advert.public_key.lower(), advert.name)
 
-    # If this is not a repeater, trigger recent contacts sync to radio
-    # This ensures we can auto-ACK DMs from recent contacts
-    if contact_type != CONTACT_TYPE_REPEATER:
-        # Import here to avoid circular import
-        from app.radio_sync import sync_recent_contacts_to_radio
-
-        asyncio.create_task(sync_recent_contacts_to_radio())
-
 
 async def _process_direct_message(
     raw_bytes: bytes,

app/radio_sync.py

@@ -4,7 +4,7 @@ Radio sync and offload management.
 This module handles syncing contacts and channels from the radio to the database,
 then removing them from the radio to free up space for new discoveries.
 
-Also handles loading recent non-repeater contacts TO the radio for DM ACK support.
+Also handles loading favorites plus recently active contacts TO the radio for DM ACK support.
 Also handles periodic message polling as a fallback for platforms where push events
 don't work reliably.
 """
@@ -49,6 +49,26 @@ def _contact_sync_debug_fields(contact: Contact) -> dict[str, object]:
     }
 
 
+async def _reconcile_contact_messages_background(
+    public_key: str,
+    contact_name: str | None,
+) -> None:
+    """Run contact/message reconciliation outside the radio critical path."""
+    try:
+        await reconcile_contact_messages(
+            public_key=public_key,
+            contact_name=contact_name,
+            log=logger,
+        )
+    except Exception as exc:
+        logger.warning(
+            "Background contact reconciliation failed for %s: %s",
+            public_key[:12],
+            exc,
+            exc_info=True,
+        )
+
+
 async def upsert_channel_from_radio_slot(payload: dict, *, on_radio: bool) -> str | None:
     """Parse a radio channel-slot payload and upsert to the database.
 
@@ -119,8 +139,8 @@ async def pause_polling():
 # Background task handle
 _sync_task: asyncio.Task | None = None
 
-# Sync interval in seconds (5 minutes)
-SYNC_INTERVAL = 300
+# Sync interval in seconds (10 minutes)
+SYNC_INTERVAL = 600
 
 
 async def sync_and_offload_contacts(mc: MeshCore) -> dict:
@@ -157,10 +177,11 @@ async def sync_and_offload_contacts(mc: MeshCore) -> dict:
             await ContactRepository.upsert(
                 ContactUpsert.from_radio_dict(public_key, contact_data, on_radio=False)
             )
-            await reconcile_contact_messages(
-                public_key=public_key,
-                contact_name=contact_data.get("adv_name"),
-                log=logger,
+            asyncio.create_task(
+                _reconcile_contact_messages_background(
+                    public_key,
+                    contact_data.get("adv_name"),
+                )
             )
             synced += 1
 
@@ -290,10 +311,10 @@ async def sync_and_offload_all(mc: MeshCore) -> dict:
     # Ensure default channels exist
     await ensure_default_channels()
 
-    # Reload favorites and recent contacts back onto the radio immediately
-    # so favorited contacts don't stay in the on_radio=False limbo until the
-    # next advertisement arrives.  Pass mc directly since the caller already
-    # holds the radio operation lock (asyncio.Lock is not reentrant).
+    # Reload favorites back onto the radio immediately so they do not stay
+    # in on_radio=False limbo after offload. Pass mc directly since the
+    # caller already holds the radio operation lock (asyncio.Lock is not
+    # reentrant).
     reload_result = await sync_recent_contacts_to_radio(force=True, mc=mc)
 
     return {
@@ -376,10 +397,6 @@ async def _message_poll_loop():
         try:
             await asyncio.sleep(MESSAGE_POLL_INTERVAL)
 
-            # Clean up expired pending ACKs every poll cycle so they don't
-            # accumulate when no ACKs arrive (e.g. all recipients out of range).
-            cleanup_expired_acks()
-
             if radio_manager.is_connected and not is_polling_paused():
                 try:
                     async with radio_manager.radio_operation(
@@ -554,6 +571,7 @@ async def _periodic_sync_loop():
     while True:
         try:
             await asyncio.sleep(SYNC_INTERVAL)
+            cleanup_expired_acks()
             if not radio_manager.is_connected:
                 continue
 
@@ -604,8 +622,12 @@ async def _sync_contacts_to_radio_inner(mc: MeshCore) -> dict:
     """
     Core logic for loading contacts onto the radio.
 
-    Favorite contacts are prioritized first, then recent non-repeater contacts
-    fill remaining slots up to max_radio_contacts.
+    Fill order is:
+    1. Favorite contacts
+    2. Most recently interacted-with non-repeaters
+    3. Most recently advert-heard non-repeaters without interaction history
+
+    Contacts are loaded up to max_radio_contacts.
 
     Caller must hold the radio operation lock and pass a valid MeshCore instance.
     """
@@ -638,8 +660,21 @@ async def _sync_contacts_to_radio_inner(mc: MeshCore) -> dict:
             break
 
     if len(selected_contacts) < max_contacts:
-        recent_contacts = await ContactRepository.get_recent_non_repeaters(limit=max_contacts)
-        for contact in recent_contacts:
+        for contact in await ContactRepository.get_recently_contacted_non_repeaters(
+            limit=max_contacts
+        ):
+            key = contact.public_key.lower()
+            if key in selected_keys:
+                continue
+            selected_keys.add(key)
+            selected_contacts.append(contact)
+            if len(selected_contacts) >= max_contacts:
+                break
+
+    if len(selected_contacts) < max_contacts:
+        for contact in await ContactRepository.get_recently_advertised_non_repeaters(
+            limit=max_contacts
+        ):
             key = contact.public_key.lower()
             if key in selected_keys:
                 continue
@@ -649,22 +684,75 @@ async def _sync_contacts_to_radio_inner(mc: MeshCore) -> dict:
                 break
 
     logger.debug(
-        "Selected %d contacts to sync (%d favorite contacts first, limit=%d)",
+        "Selected %d contacts to sync (%d favorites, limit=%d)",
         len(selected_contacts),
         favorite_contacts_loaded,
         max_contacts,
     )
+    return await _load_contacts_to_radio(mc, selected_contacts)
 
+
+async def ensure_contact_on_radio(
+    public_key: str,
+    *,
+    force: bool = False,
+    mc: MeshCore | None = None,
+) -> dict:
+    """Ensure one contact is loaded on the radio for ACK/routing support."""
+    global _last_contact_sync
+
+    now = time.time()
+    if not force and (now - _last_contact_sync) < CONTACT_SYNC_THROTTLE_SECONDS:
+        logger.debug(
+            "Single-contact sync throttled (last sync %ds ago)",
+            int(now - _last_contact_sync),
+        )
+        return {"loaded": 0, "throttled": True}
+
+    try:
+        contact = await ContactRepository.get_by_key_or_prefix(public_key)
+    except AmbiguousPublicKeyPrefixError:
+        logger.warning("Cannot sync favorite contact '%s': ambiguous key prefix", public_key)
+        return {"loaded": 0, "error": "Ambiguous contact key prefix"}
+
+    if not contact:
+        logger.debug("Cannot sync favorite contact %s: not found", public_key[:12])
+        return {"loaded": 0, "error": "Contact not found"}
+
+    if mc is not None:
+        _last_contact_sync = now
+        return await _load_contacts_to_radio(mc, [contact])
+
+    if not radio_manager.is_connected or radio_manager.meshcore is None:
+        logger.debug("Cannot sync favorite contact to radio: not connected")
+        return {"loaded": 0, "error": "Radio not connected"}
+
+    try:
+        async with radio_manager.radio_operation(
+            "ensure_contact_on_radio",
+            blocking=False,
+        ) as mc:
+            _last_contact_sync = now
+            assert mc is not None
+            return await _load_contacts_to_radio(mc, [contact])
+    except RadioOperationBusyError:
+        logger.debug("Skipping favorite contact sync: radio busy")
+        return {"loaded": 0, "busy": True}
+    except Exception as e:
+        logger.error("Error syncing favorite contact to radio: %s", e, exc_info=True)
+        return {"loaded": 0, "error": str(e)}
+
+
+async def _load_contacts_to_radio(mc: MeshCore, contacts: list[Contact]) -> dict:
+    """Load the provided contacts onto the radio."""
     loaded = 0
     already_on_radio = 0
     failed = 0
 
-    for contact in selected_contacts:
-        # Check if already on radio
+    for contact in contacts:
         radio_contact = mc.get_contact_by_key_prefix(contact.public_key[:12])
         if radio_contact:
             already_on_radio += 1
-            # Update DB if not marked as on_radio
             if not contact.on_radio:
                 await ContactRepository.set_on_radio(contact.public_key, True)
             continue
@@ -722,8 +810,8 @@ async def sync_recent_contacts_to_radio(force: bool = False, mc: MeshCore | None
     """
     Load contacts to the radio for DM ACK support.
 
-    Favorite contacts are prioritized first, then recent non-repeater contacts
-    fill remaining slots up to max_radio_contacts.
+    Fill order is favorites, then recently contacted non-repeaters,
+    then recently advert-heard non-repeaters until max_radio_contacts.
     Only runs at most once every CONTACT_SYNC_THROTTLE_SECONDS unless forced.
 
     Args:

app/repository/contacts.py

@@ -253,17 +253,28 @@ class ContactRepository:
         return [ContactRepository._row_to_contact(row) for row in rows]
 
     @staticmethod
-    async def get_recent_non_repeaters(limit: int = 200) -> list[Contact]:
-        """Get the most recently active non-repeater contacts.
-
-        Orders by most recent activity (last_contacted or last_advert),
-        excluding repeaters (type=2).
-        """
+    async def get_recently_contacted_non_repeaters(limit: int = 200) -> list[Contact]:
+        """Get recently interacted-with non-repeater contacts."""
         cursor = await db.conn.execute(
             """
             SELECT * FROM contacts
-            WHERE type != 2
-            ORDER BY COALESCE(last_contacted, 0) DESC, COALESCE(last_advert, 0) DESC
+            WHERE type != 2 AND last_contacted IS NOT NULL
+            ORDER BY last_contacted DESC
+            LIMIT ?
+            """,
+            (limit,),
+        )
+        rows = await cursor.fetchall()
+        return [ContactRepository._row_to_contact(row) for row in rows]
+
+    @staticmethod
+    async def get_recently_advertised_non_repeaters(limit: int = 200) -> list[Contact]:
+        """Get recently advert-heard non-repeater contacts."""
+        cursor = await db.conn.execute(
+            """
+            SELECT * FROM contacts
+            WHERE type != 2 AND last_advert IS NOT NULL
+            ORDER BY last_advert DESC
             LIMIT ?
             """,
             (limit,),

app/routers/settings.py

@@ -18,9 +18,7 @@ class AppSettingsUpdate(BaseModel):
         default=None,
         ge=1,
         le=1000,
-        description=(
-            "Maximum contacts to keep on radio (favorites first, then recent non-repeaters)"
-        ),
+        description="Maximum favorite contacts to keep loaded on the radio for ACK support",
     )
     auto_decrypt_dm_on_advert: bool | None = Field(
         default=None,
@@ -161,12 +159,12 @@ async def toggle_favorite(request: FavoriteRequest) -> AppSettings:
         logger.info("Adding favorite: %s %s", request.type, request.id[:12])
         result = await AppSettingsRepository.add_favorite(request.type, request.id)
 
-    # When a contact favorite changes, sync the radio so the contact is
-    # loaded/unloaded immediately rather than waiting for the next advert.
-    if request.type == "contact":
-        from app.radio_sync import sync_recent_contacts_to_radio
+    # When a contact is newly favorited, load just that contact to the radio
+    # immediately so DM ACK support does not wait for the next maintenance cycle.
+    if request.type == "contact" and not is_favorited:
+        from app.radio_sync import ensure_contact_on_radio
 
-        asyncio.create_task(sync_recent_contacts_to_radio(force=True))
+        asyncio.create_task(ensure_contact_on_radio(request.id, force=True))
 
     return result
 

app/services/message_send.py

@@ -137,15 +137,20 @@ async def send_direct_message_to_contact(
 ) -> Any:
     """Send a direct message and persist/broadcast the outgoing row."""
     contact_data = contact.to_radio_dict()
+    contact_ensured_on_radio = False
     async with radio_manager.radio_operation("send_direct_message") as mc:
         logger.debug("Ensuring contact %s is on radio before sending", contact.public_key[:12])
         add_result = await mc.commands.add_contact(contact_data)
         if add_result.type == EventType.ERROR:
             logger.warning("Failed to add contact to radio: %s", add_result.payload)
+        else:
+            contact_ensured_on_radio = True
 
         cached_contact = mc.get_contact_by_key_prefix(contact.public_key[:12])
         if not cached_contact:
             cached_contact = contact_data
+        else:
+            contact_ensured_on_radio = True
 
         logger.info("Sending direct message to %s", contact.public_key[:12])
         now = int(now_fn())
@@ -158,6 +163,9 @@ async def send_direct_message_to_contact(
     if result.type == EventType.ERROR:
         raise HTTPException(status_code=500, detail=f"Failed to send message: {result.payload}")
 
+    if contact_ensured_on_radio and not contact.on_radio:
+        await contact_repository.set_on_radio(contact.public_key.lower(), True)
+
     message = await create_outgoing_direct_message(
         conversation_key=contact.public_key.lower(),
         text=text,

app/services/radio_lifecycle.py

@@ -1,8 +1,13 @@
 import asyncio
 import logging
 
+from app.config import settings
+
 logger = logging.getLogger(__name__)
 
+POST_CONNECT_SETUP_TIMEOUT_SECONDS = 300
+POST_CONNECT_SETUP_MAX_ATTEMPTS = 2
+
 
 async def run_post_connect_setup(radio_manager) -> None:
     """Run shared radio initialization after a transport connection succeeds."""
@@ -24,7 +29,7 @@ async def run_post_connect_setup(radio_manager) -> None:
     if radio_manager._setup_lock is None:
         radio_manager._setup_lock = asyncio.Lock()
 
-    async with radio_manager._setup_lock:
+    async def _setup_body() -> None:
         if not radio_manager.meshcore:
             return
         radio_manager._setup_in_progress = True
@@ -132,20 +137,51 @@ async def run_post_connect_setup(radio_manager) -> None:
             # These tasks acquire their own locks when they need radio access.
             start_periodic_sync()
             start_periodic_advert()
-            start_message_polling()
+            if settings.enable_message_poll_fallback:
+                start_message_polling()
+            else:
+                logger.info("Fallback message polling disabled; relying on radio events")
 
             radio_manager._setup_complete = True
         finally:
             radio_manager._setup_in_progress = False
 
+    async with radio_manager._setup_lock:
+        await asyncio.wait_for(_setup_body(), timeout=POST_CONNECT_SETUP_TIMEOUT_SECONDS)
+
     logger.info("Post-connect setup complete")
 
 
 async def prepare_connected_radio(radio_manager, *, broadcast_on_success: bool = True) -> None:
     """Finish setup for an already-connected radio and optionally broadcast health."""
-    from app.websocket import broadcast_health
+    from app.websocket import broadcast_error, broadcast_health
+
+    for attempt in range(1, POST_CONNECT_SETUP_MAX_ATTEMPTS + 1):
+        try:
+            await radio_manager.post_connect_setup()
+            break
+        except asyncio.TimeoutError as exc:
+            if attempt < POST_CONNECT_SETUP_MAX_ATTEMPTS:
+                logger.warning(
+                    "Post-connect setup timed out after %ds on attempt %d/%d; retrying once",
+                    POST_CONNECT_SETUP_TIMEOUT_SECONDS,
+                    attempt,
+                    POST_CONNECT_SETUP_MAX_ATTEMPTS,
+                )
+                continue
+
+            logger.error(
+                "Post-connect setup timed out after %ds on %d attempts. Initial radio offload "
+                "took too long; something is probably wrong.",
+                POST_CONNECT_SETUP_TIMEOUT_SECONDS,
+                POST_CONNECT_SETUP_MAX_ATTEMPTS,
+            )
+            broadcast_error(
+                "Radio startup appears stuck",
+                "Initial radio offload took too long. Reboot the radio and restart the server.",
+            )
+            raise RuntimeError("Post-connect setup timed out") from exc
 
-    await radio_manager.post_connect_setup()
     radio_manager._last_connected = True
     if broadcast_on_success:
         broadcast_health(True, radio_manager.connection_info)
@@ -197,7 +233,11 @@ async def connection_monitor_loop(radio_manager) -> None:
                 await prepare_connected_radio(radio_manager, broadcast_on_success=True)
                 consecutive_setup_failures = 0
 
-            elif current_connected and not radio_manager.is_setup_complete:
+            elif (
+                current_connected
+                and not radio_manager.is_setup_complete
+                and not radio_manager.is_setup_in_progress
+            ):
                 logger.info("Retrying post-connect setup...")
                 await prepare_connected_radio(radio_manager, broadcast_on_success=True)
                 consecutive_setup_failures = 0