feat(matrix): add configurable graceful sync shutdown

nanobot/channels/matrix.py

@@ -49,9 +49,28 @@ class MatrixChannel(BaseChannel):
         self._sync_task = asyncio.create_task(self._sync_loop())
 
     async def stop(self) -> None:
+        """Stop the Matrix channel with graceful sync shutdown."""
         self._running = False
+
+        if self.client:
+            # Request sync_forever loop to exit cleanly.
+            self.client.stop_sync_forever()
+
         if self._sync_task:
-            self._sync_task.cancel()
+            try:
+                await asyncio.wait_for(
+                    asyncio.shield(self._sync_task),
+                    timeout=self.config.sync_stop_grace_seconds,
+                )
+            except asyncio.TimeoutError:
+                self._sync_task.cancel()
+                try:
+                    await self._sync_task
+                except asyncio.CancelledError:
+                    pass
+            except asyncio.CancelledError:
+                pass
+
         if self.client:
             await self.client.close()
 

nanobot/config/schema.py

@@ -1,6 +1,7 @@
 """Configuration schema using Pydantic."""
 
 from pathlib import Path
+
 from pydantic import BaseModel, Field
 from pydantic_settings import BaseSettings
 
@@ -53,6 +54,8 @@ class MatrixConfig(BaseModel):
     access_token: str = ""
     user_id: str = ""  # @bot:matrix.org
     device_id: str = ""
+    # Max seconds to wait for sync_forever to stop gracefully before cancellation fallback.
+    sync_stop_grace_seconds: int = 2
     allow_from: list[str] = Field(default_factory=list)
 
 class ChannelsConfig(BaseModel):