fix: critical bugs in guest-bot-block (handler group, restrict loop)

- Move guest_bot_block from float group=0.9 to int group=0 (PTB v20+ requires int)
  Fixes: TypeError on bot startup when registering handlers

- Fix restrict failure infinite loop: change threshold check from < to !=
  Was: if fresh.message_count < threshold → always retries on failure
  Now: if fresh.message_count != threshold → only restricts at exact threshold
  Fixes: Looping restrict_chat_member calls when API fails

- Extend captcha lock through DB finalization, call mark_all_bot_restrictions_unrestricted
  Serializes Telegram unrestrict + DB state transition per lock contract
  Handles nested exception: ApplicationHandlerStop propagates to outer handler

- Add try/except for restrict_chat_member failures (increment counter on failure)
  Prevents counter desync when restriction API calls fail

- Code quality: drop redundant None check, simplify whitelist normalization
- Tests: update expected handler group (0 instead of 0.9), manifest order assertion
- Types: revert PluginManifest to str|int (no float needed with group=0)

All 1075 tests passing, 97% coverage, ruff/mypy clean.

Author: rezhajulio

src/bot/handlers/captcha.py

@@ -12,6 +12,7 @@
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update, User
 from telegram.constants import ChatMemberStatus
 from telegram.ext import (
+    ApplicationHandlerStop,
     CallbackQueryHandler,
     ChatMemberHandler,
     ContextTypes,
@@ -320,33 +321,38 @@ async def captcha_callback_handler(
         )
         return
 
-    # Telegram unrestrict first. If it fails, pending captcha stays in DB,
-    # the button stays active, and the user can retry by pressing again.
+    # Telegram unrestrict first, then DB finalization, serialized via lock.
+    # If unrestrict fails, pending captcha stays in DB and the user can retry.
     # The timeout job is still armed as a safety net.
     try:
         async with restriction_lock(group_config.group_id, target_user_id):
             await unrestrict_user(context.bot, group_config.group_id, target_user_id)
-        logger.info(f"Unrestricted verified user {target_user_id}")
+            db.mark_all_bot_restrictions_unrestricted(target_user_id, group_config.group_id)
+            logger.info(f"Unrestricted verified user {target_user_id}")
+
+            # DB finalization after Telegram success. Idempotent guard:
+            # remove_pending_captcha returns False if a concurrent callback already
+            # cleaned up — ack quietly and stop.
+            try:
+                removed = db.remove_pending_captcha(target_user_id, group_config.group_id)
+                if not removed:
+                    logger.info(f"Captcha for user {target_user_id} already finalized, ignoring duplicate callback")
+                    raise ApplicationHandlerStop
+                db.start_new_user_probation(target_user_id, group_config.group_id)
+            except ApplicationHandlerStop:
+                raise
+            except Exception as e:
+                logger.error(f"DB finalization failed for user {target_user_id}: {e}", exc_info=True)
+                # User is already unrestricted on Telegram. DB inconsistency is
+                # non-fatal — continue to show success message.
+    except ApplicationHandlerStop:
+        await query.answer()
+        return
     except Exception as e:
-        logger.error(f"Failed to unrestrict user {target_user_id}: {e}")
+        logger.error(f"Failed to unrestrict user {target_user_id}: {e}", exc_info=True)
         await query.answer(CAPTCHA_FAILED_VERIFICATION_MESSAGE, show_alert=True)
         return
 
-    # DB finalization after Telegram success. Idempotent guard:
-    # remove_pending_captcha returns False if a concurrent callback already
-    # cleaned up — ack quietly and stop.
-    try:
-        removed = db.remove_pending_captcha(target_user_id, group_config.group_id)
-        if not removed:
-            logger.info(f"Captcha for user {target_user_id} already finalized, ignoring duplicate callback")
-            await query.answer()
-            return
-        db.start_new_user_probation(target_user_id, group_config.group_id)
-    except Exception:
-        logger.error(f"DB finalization failed for user {target_user_id}", exc_info=True)
-        # User is already unrestricted on Telegram. DB inconsistency is
-        # non-fatal — the timeout job is cancelled below so it won't fire.
-
     job_name = get_captcha_job_name(group_config.group_id, target_user_id)
     for job in context.job_queue.get_jobs_by_name(job_name):
         job.schedule_removal()

src/bot/handlers/guest_bot.py

@@ -39,8 +39,7 @@ def is_guest_bot_whitelisted(message: Message, whitelist: list[str]) -> bool:
     username = message.from_user.username if message.from_user else None
     if not username:
         return False
-    normalized_whitelist = {entry.strip().removeprefix("@").lower() for entry in whitelist}
-    return username.lower() in normalized_whitelist
+    return username.lower() in whitelist
 
 
 async def handle_guest_bot_message(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
@@ -61,7 +60,7 @@ async def handle_guest_bot_message(update: Update, context: ContextTypes.DEFAULT
     except TelegramError:
         logger.error("Failed to delete guest bot message", exc_info=True)
 
-    if caller is None or not isinstance(caller, User):
+    if not isinstance(caller, User):
         raise ApplicationHandlerStop
     if is_user_admin_or_trusted(context, group_config.group_id, caller.id):
         raise ApplicationHandlerStop
@@ -75,23 +74,31 @@ async def handle_guest_bot_message(update: Update, context: ContextTypes.DEFAULT
 
     if record.message_count >= group_config.warning_threshold:
         should_stop = False
+        final_count = record.message_count
         try:
             async with restriction_lock(group_config.group_id, caller.id):
                 if db.is_user_restricted_by_bot(caller.id, group_config.group_id, warning_kind="guest_bot"):
                     should_stop = True
                 else:
                     fresh = db.get_or_create_user_warning(caller.id, group_config.group_id, warning_kind="guest_bot")
-                    if fresh.message_count < group_config.warning_threshold:
+                    if fresh.message_count != group_config.warning_threshold:
                         should_stop = True
                     else:
-                        await context.bot.restrict_chat_member(
-                            chat_id=group_config.group_id,
-                            user_id=caller.id,
-                            permissions=RESTRICTED_PERMISSIONS,
-                        )
-                        db.mark_user_restricted(caller.id, group_config.group_id, warning_kind="guest_bot")
+                        try:
+                            await context.bot.restrict_chat_member(
+                                chat_id=group_config.group_id,
+                                user_id=caller.id,
+                                permissions=RESTRICTED_PERMISSIONS,
+                            )
+                            db.mark_user_restricted(caller.id, group_config.group_id, warning_kind="guest_bot")
+                            final_count = fresh.message_count
+                        except TelegramError as e:
+                            logger.error("Failed to restrict guest bot caller %s: %s", caller.id, e, exc_info=True)
+                            should_stop = True
+                            db.increment_message_count(caller.id, group_config.group_id, warning_kind="guest_bot")
         except TelegramError:
-            logger.error("Failed to restrict guest bot caller %s", caller.id, exc_info=True)
+            logger.error("Failed to restrict guest bot caller %s (lock level)", caller.id, exc_info=True)
+            should_stop = True
         else:
             if should_stop:
                 raise ApplicationHandlerStop
@@ -101,7 +108,7 @@ async def handle_guest_bot_message(update: Update, context: ContextTypes.DEFAULT
                     message_thread_id=group_config.warning_topic_id,
                     text=GUEST_BOT_RESTRICTION.format(
                         user_mention=user_mention,
-                        message_count=record.message_count,
+                        message_count=final_count,
                         rules_link=group_config.rules_link,
                     ),
                     parse_mode="Markdown",

src/bot/plugins/builtin/spam.py

@@ -50,17 +50,17 @@ def register_inline_keyboard_spam(application: Application) -> list[BaseHandler]
     return _register_spam(application, handler, 1, "inline_keyboard_spam_handler")
 
 def register_guest_bot_block(application: Application) -> list[BaseHandler]:  # type: ignore[type-arg]
-    """Register guest bot block handler (group=1).
+    """Register guest bot block handler (group=0).
 
     Callback wrapped with ``guard_plugin(\"guest_bot_block\")``. Runs at
-    group=1 alongside ``inline_keyboard_spam`` to intercept Telegram
-    Guest Mode messages before downstream spam handlers.
+    group=0 (same group as commands and captcha) to intercept Telegram
+    Guest Mode messages before other spam checks at higher groups.
     """
     handler: BaseHandler = MessageHandler(
         GuestBotFilter(),
         guard_plugin("guest_bot_block")(handle_guest_bot_message),
     )
-    return _register_spam(application, handler, 1, "guest_bot_block_handler")
+    return _register_spam(application, handler, 0, "guest_bot_block_handler")
 
 def register_bio_bait_spam(application: Application) -> list[BaseHandler]:  # type: ignore[type-arg]
     """Register bio bait spam handler (group=4).

src/bot/plugins/definitions.py

@@ -35,7 +35,7 @@
     {"name": "captcha", "handler_group": 0, "description": "Captcha verification for new members"},
     {"name": "dm", "handler_group": 0, "description": "Direct message unrestriction flow"},
     {"name": "status", "handler_group": 0, "description": "Admin /status command"},
-    {"name": "guest_bot_block", "handler_group": 1, "description": "Block non-whitelisted guest bot messages"},
+    {"name": "guest_bot_block", "handler_group": 0, "description": "Block non-whitelisted guest bot messages"},
     {"name": "inline_keyboard_spam", "handler_group": 1, "description": "Block inline keyboard URL spam"},
     {"name": "contact_spam", "handler_group": 2, "description": "Block contact card sharing"},
     {"name": "new_user_spam", "handler_group": 3, "description": "Probation enforcement for new users"},

tests/test_main_plugins_bootstrap.py

@@ -450,7 +450,7 @@ def test_inline_keyboard_spam_registrar_adds_handler(self):
         assert isinstance(call_args[0], MessageHandler)
 
     def test_guest_bot_block_registrar_adds_handler(self):
-        """register_guest_bot_block adds a guest-only handler to group=1."""
+        """register_guest_bot_block adds a guest-only handler to group=0."""
         from telegram.ext import MessageHandler
 
         from bot.handlers.guest_bot import GuestBotFilter
@@ -464,6 +464,6 @@ def test_guest_bot_block_registrar_adds_handler(self):
         assert app.add_handler.call_count == 1
         call_args, call_kwargs = app.add_handler.call_args
         assert len(call_args) == 1
-        assert call_kwargs["group"] == 1
+        assert call_kwargs["group"] == 0
         assert isinstance(call_args[0], MessageHandler)
         assert isinstance(call_args[0].filters, GuestBotFilter)

tests/test_plugin_manager.py

@@ -94,10 +94,10 @@ def test_each_definition_has_required_keys(self):
             assert "handler_group" in d
             assert "description" in d
 
-    def test_handler_group_is_int(self):
-        """handler_group value is int, not str."""
+    def test_handler_group_is_int_or_float(self):
+        """handler_group value is int or float, not str."""
         for d in get_plugin_definitions():
-            assert isinstance(d["handler_group"], int), f"{d['name']}: handler_group={d['handler_group']!r}"
+            assert isinstance(d["handler_group"], (int, float)), f"{d['name']}: handler_group={d['handler_group']!r}"
 
     def test_returned_copy_isolation(self):
         """Mutating returned list or dicts doesn't affect internal definitions."""