fix: restriction race conditions, permanent dead-state, event-loop lock bug

Critical fixes from 4-agent parallel review of feat/guest-bot-block:

- guest_bot.py: revert threshold check to < (not !=) and drop the
  increment-on-failure. != combined with the increment permanently wedged
  a caller into delete-only mode after one failed restrict_chat_member
  call. < without incrementing on failure pins the count at threshold, so
  the next guest message retries restriction instead of drifting past it
  forever or looping tightly.

- captcha_recovery.py: serialize the pending-captcha read + remove inside
  restriction_lock and check remove_pending_captcha's return value. The
  timeout path previously read/removed outside the lock, racing the
  captcha callback and leaving is_restricted=True in DB for an already
  unrestricted-on-Telegram user.

- message.py, scheduler.py: in-lock recheck now verifies the fresh
  warning row is the SAME row that reached the threshold/expired
  (fresh.id != record.id), not just that some active row exists. Fixes
  restricting a brand-new low-count row on the strength of a stale one.

- restriction_lock.py: scope the lock cache per running event loop via a
  WeakKeyDictionary instead of a flat process-global dict. asyncio.Lock
  binds to the event loop of its first contended acquire; reusing a key
  across event loops (e.g. per-test loops) previously raised RuntimeError.

- verify.py: widen the unrestrict except clause to TelegramError (was a
  narrow tuple missing RetryAfter/ChatMigrated), matching the bare
  Exception catch already used by the sibling unrestrict_user_in_group.

- guest_bot.py: drop the outer except TelegramError around the lock body
  — nothing inside can raise TelegramError past the inner handler, so it
  was dead code that obscured control flow.

- tests/test_scheduler.py: fix a test mock that always returned the same
  warning row regardless of user_id, which the new row-identity check
  correctly rejected for the second user.

- tests/test_restriction_lock.py: update for the loop-scoped lock storage.

- AGENTS.md, README.md: correct guest_bot_block handler_group (1 -> 0),
  stale Code Map line counts, test count (1,064 -> 1,075), mermaid guest
  gate label and missing whitelisted-passthrough edge, and the dispatch
  rationale (no GROUPS & ~COMMAND handler exists at group 0).

All 1075 tests passing, ruff/mypy clean.

Author: rezhajulio

AGENTS.md

@@ -81,7 +81,7 @@ PythonID/
 │   │   └── admin_cache.py       # Admin ID cache + refresh
 │   └── database/
 │       ├── models.py     # SQLModel schemas (5 tables: UserWarning, PhotoVerificationWhitelist, PendingCaptchaValidation, NewUserProbation, TrustedUser)
-│       └── service.py    # DatabaseService singleton (645 lines)
+│       └── service.py    # DatabaseService singleton (958 lines)
 ├── tests/                # pytest-asyncio + Hypothesis (30+ files)
 │   ├── test_properties.py # Property-based tests for pure functions
 │   └── test_warn.py      # /warn command tests (23 tests)
@@ -102,33 +102,33 @@ PythonID/
 | Add Telegram whitelist | `constants.py` → `WHITELISTED_TELEGRAM_PATHS` | Lowercase, exact path match |
 | Multi-group config | `group_config.py` | GroupConfig model, GroupRegistry, groups.json loading |
 | Warn a member | `handlers/warn.py` + `plugins/builtin/commands.py` | Admin `/warn` by reply or user ID; registered as `warn_command` |
-| Block guest bots | `handlers/guest_bot.py` + `plugins/builtin/spam.py` | `guest_bot_block` plugin (group=1); whitelist via `GUEST_BOT_WHITELIST` env or `guest_bot_whitelist` per-group JSON |
+| Block guest bots | `handlers/guest_bot.py` + `plugins/builtin/spam.py` | `guest_bot_block` plugin (group=0); whitelist via `GUEST_BOT_WHITELIST` env or `guest_bot_whitelist` per-group JSON |
 
 ## Code Map (Key Files)
 
 | File | Lines | Role |
 |------|-------|------|
-| `database/service.py` | 850 | **Complexity hotspot** - handles warnings, captcha, probation state |
+| `database/service.py` | 958 | **Complexity hotspot** - handles warnings, captcha, probation state |
 | `constants.py` | 724 | Templates + massive whitelists (Indonesian tech community) |
 | `handlers/anti_spam.py` | 494 | Anti-spam: contact cards, inline keyboards, probation enforcement |
 | `handlers/bio_bait.py` | 441 | Bio-bait spam: obfuscated bait phrases + suspicious profile bio links |
-| `handlers/guest_bot.py` | 118 | Guest Mode moderation: delete non-whitelisted guest bot messages + progressive restriction of the human caller |
+| `handlers/guest_bot.py` | 133 | Guest Mode moderation: delete non-whitelisted guest bot messages + progressive restriction of the human caller |
 | `handlers/check.py` | 437 | Admin /check: group selector + group-scoped action buttons |
 | `handlers/captcha.py` | 427 | New member join → restrict → verify (with profile check) → unrestrict lifecycle |
-| `handlers/verify.py` | 400 | Photo exemption + bot-owned unrestriction (group-scoped) |
+| `handlers/verify.py` | 422 | Photo exemption + bot-owned unrestriction (group-scoped) |
 | `handlers/trust.py` | 368 | /trust, /untrust, /trusted admin commands (no auto-unrestrict) |
-| `handlers/dm.py` | 250 | DM unrestriction flow with deep-link group recovery |
-| `handlers/message.py` | 208 | Profile compliance monitoring + stale warning clearing |
+| `handlers/dm.py` | 264 | DM unrestriction flow with deep-link group recovery |
+| `handlers/message.py` | 217 | Profile compliance monitoring + stale warning clearing |
 | `handlers/status.py` | 181 | Group-scoped /status (admin's groups only, Indonesian labels) |
 | `handlers/warn.py` | 170 | Admin-issued generic warning by reply or user ID; optional moderation-topic routing |
-| `services/scheduler.py` | 151 | Auto-restriction with pre-restriction profile recheck |
+| `services/scheduler.py` | 160 | Auto-restriction with pre-restriction profile recheck |
 | `group_config.py` | 255 | Multi-group config, registry, JSON loading, .env fallback |
 | `main.py` | 191 | Entry point, logging, post_init, PluginManager bootstrap |
 | `plugins/manager.py` | 188 | PluginManager — static registry + deterministic registration order |
 | `plugins/config.py` | 156 | `guard_plugin` runtime gate + toggle resolution |
 | `plugins/definitions.py` | 72 | `MANIFEST_ORDER` / `PLUGIN_NAMES` — single source of truth for plugin names + groups |
 | `plugins/builtin/commands.py` | 166 | Wraps all command + callback handlers with group-scoped patterns |
-| `plugins/builtin/spam.py` | 93 | Wraps all 5 anti-spam handlers + guest_bot_block with `guard_plugin` |
+| `plugins/builtin/spam.py` | 114 | Wraps all 5 anti-spam handlers + guest_bot_block with `guard_plugin` |
 | `plugins/builtin/captcha.py` | 43 | Wraps captcha handler + applies guard_plugin gating |
 
 ## Architecture Patterns
@@ -148,8 +148,8 @@ PythonID/
 ```python
 # Registration order comes from MANIFEST_ORDER (plugins/definitions.py), not main.py directly
 group=-1  # topic_guard: Runs FIRST
-group=0   # commands (including warn_command), callbacks, captcha, dm (18 plugins, order-independent)
-group=1   # inline_keyboard_spam + guest_bot_block: Catches inline keyboard URL spam / Guest Mode messages
+group=0   # commands (including warn_command), callbacks, captcha, dm, guest_bot_block (19 plugins; only guest_bot_block is order-sensitive, via ApplicationHandlerStop)
+group=1   # inline_keyboard_spam: Catches inline keyboard URL spam
 group=2   # contact_spam: Blocks contact card sharing
 group=3   # new_user_spam: Probation enforcement (links/forwards)
 group=4   # duplicate_spam + bio_bait_spam: Repeated messages / bio-bait detection
@@ -179,12 +179,13 @@ group=6   # JobQueue only (not a handler group): auto_restrict_job, refresh_admi
 
 ### Guest Bot Moderation
 - `handlers/guest_bot.py` blocks Telegram **Guest Mode** messages — messages posted by a bot on behalf of a user/channel via the `@` mention feature that Telegram routes through `message.guest_bot_caller_user` / `message.guest_bot_caller_chat` (PTB v22.8+)
-- A custom `GuestBotFilter` (`filters.MessageFilter`) matches only messages where either guest-bot caller field is set, so the handler is dispatched before the broad `GROUPS & ~COMMAND` filters at the same group
-- Registered as `guest_bot_block` at `handler_group=1` via `spam_mod.register_guest_bot_block` in `plugins/builtin/spam.py`, gated by `guard_plugin("guest_bot_block")`
+- A custom `GuestBotFilter` (`filters.MessageFilter`) matches only messages where either guest-bot caller field is set, so the handler only fires on actual Guest Mode updates and raises `ApplicationHandlerStop` to stop the spam handlers at groups 1-5 from also processing the message
+- Registered as `guest_bot_block` at `handler_group=0` (alongside commands/callbacks/captcha/dm) via `spam_mod.register_guest_bot_block` in `plugins/builtin/spam.py`, gated by `guard_plugin("guest_bot_block")`
 - Non-whitelisted guest bot messages are always deleted; the invoking **human caller** then receives progressive enforcement using the group's existing `warning_threshold`:
   - 1st violation → warning in the warning topic (`GUEST_BOT_WARNING`)
   - 2nd to (N-1) → silent increment
   - Nth violation → restrict + notification (`GUEST_BOT_RESTRICTION`)
+  - If `restrict_chat_member` fails (e.g. bot lacks ban rights), the strike count is NOT incremented past the threshold — the next guest message from the same caller retries the restriction instead of drifting into a permanent delete-only state
 - Admin/trusted callers have their guest message deleted but are **not** warned or restricted
 - Chat/channel-only callers (no `guest_bot_caller_user`) are delete-only — there is no human to warn
 - Already guest-bot-restricted callers do not start a fresh warning cycle (`is_user_restricted_by_bot` check)
@@ -331,7 +332,7 @@ if user.id not in admin_ids:
 - **Trust feature**: `TrustedUser` table caches user_full_name + admin_full_name at trust time so `/trusted` lists admin info without Telegram API calls. Backfill script at `scripts/backfill_trusted_names.py` for pre-existing rows
 - **Local review artifacts**: `reviews/` directory contains output from parallel reviewer subagents. Gitignored; not part of the source tree
 - **Captcha DB ordering**: The captcha callback handler calls Telegram `unrestrict_user` BEFORE DB writes (remove_pending_captcha, start_new_user_probation). If unrestrict fails, the pending captcha stays in DB and the user can retry. DB finalization is idempotent — `remove_pending_captcha` returning False means a concurrent callback already finalized
-- **Guest bot blocking**: Telegram Guest Mode lets any user `@mention` a bot and have the result posted in a chat. The `guest_bot_block` plugin (group=1) deletes non-whitelisted guest bot messages and progressively restricts the human caller (1st=warning, Nth=restrict). Admins/trusted users and channel-only callers are delete-only. Bot whitelist is case-insensitive with optional `@`. Guest strikes are tracked separately via `warning_kind="guest_bot"` and are not eligible for the DM self-service unrestriction flow
+- **Guest bot blocking**: Telegram Guest Mode lets any user `@mention` a bot and have the result posted in a chat. The `guest_bot_block` plugin (group=0) deletes non-whitelisted guest bot messages and progressively restricts the human caller (1st=warning, Nth=restrict). Admins/trusted users and channel-only callers are delete-only. Bot whitelist is case-insensitive with optional `@`. A failed restriction does not increment the strike count past the threshold, so the caller's next guest message retries the restriction. Guest strikes are tracked separately via `warning_kind="guest_bot"` and are not eligible for the DM self-service unrestriction flow
 
 ## Policy
 

README.md

@@ -212,7 +212,7 @@ uv run mypy src/bot/ tests/
 
 The project maintains comprehensive test coverage:
 - **Coverage**: 97%+ (~2,900 statements, <3% unreachable)
-- **Tests**: 1,064 total (includes 19 Hypothesis property tests)
+- **Tests**: 1,075 total (includes 19 Hypothesis property tests)
 - **Pass Rate**: 100%
 - **Property tests**: `tests/test_properties.py` exercises pure functions (format helpers, URL whitelist, name formatters) with random inputs and shrinks failing cases to minimal examples
 - **Mypy**: Pragmatic config in `pyproject.toml`. Disables error codes that are noisy from PTB / SQLModel / Pydantic v2; catches real type bugs in new code
@@ -369,8 +369,9 @@ flowchart TD
     G_TopicIsBotAdmin -->|No| G_TopicDelete[Delete Message]
     G_TopicDelete --> StopTopic2([ApplicationHandlerStop])
 
-    G_GuestGate{group=1 guest_bot_block:<br/>Guest Mode message?}
+    G_GuestGate{group=0 guest_bot_block:<br/>Guest Mode message?}
     G_GuestGate -->|No| G_InlineGate
+    G_GuestGate -->|Yes, whitelisted| G_InlineGate
     G_GuestGate -->|Yes, not whitelisted| G_GuestDelete[Delete Message]
     G_GuestDelete --> G_GuestCaller{Human caller?<br/>Admin/Trusted?}
     G_GuestCaller -->|Admin/Trusted or Channel-only| StopGuest([ApplicationHandlerStop])

src/bot/handlers/guest_bot.py

@@ -75,46 +75,43 @@ 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"):
+        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:
                     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:
+                    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)
+                        # Do not increment on failure: count stays pinned at
+                        # threshold so the next guest message retries the
+                        # restriction instead of drifting past it forever.
                         should_stop = True
-                    else:
-                        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")
+        if should_stop:
+            raise ApplicationHandlerStop
+        try:
+            await context.bot.send_message(
+                chat_id=group_config.group_id,
+                message_thread_id=group_config.warning_topic_id,
+                text=GUEST_BOT_RESTRICTION.format(
+                    user_mention=user_mention,
+                    message_count=final_count,
+                    rules_link=group_config.rules_link,
+                ),
+                parse_mode="Markdown",
+            )
         except TelegramError:
-            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
-            try:
-                await context.bot.send_message(
-                    chat_id=group_config.group_id,
-                    message_thread_id=group_config.warning_topic_id,
-                    text=GUEST_BOT_RESTRICTION.format(
-                        user_mention=user_mention,
-                        message_count=final_count,
-                        rules_link=group_config.rules_link,
-                    ),
-                    parse_mode="Markdown",
-                )
-            except TelegramError:
-                logger.error("Failed to send guest bot restriction notice for user %s", caller.id, exc_info=True)
+            logger.error("Failed to send guest bot restriction notice for user %s", caller.id, exc_info=True)
     elif record.message_count == 1:
         try:
             await context.bot.send_message(

src/bot/handlers/message.py

@@ -159,7 +159,11 @@ async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE) ->
         try:
             async with restriction_lock(group_config.group_id, user.id):
                 fresh = db.get_active_user_warning(user.id, group_config.group_id)
-                if fresh is None or fresh.is_restricted:
+                if (
+                    fresh is None
+                    or fresh.id != record.id
+                    or fresh.message_count < group_config.warning_threshold
+                ):
                     logger.info(
                         f"Skipping profile restriction for user {user.id} - "
                         f"record no longer active (group_id={group_config.group_id})"
@@ -182,13 +186,13 @@ async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE) ->
             # Send restriction notice with DM link for appeal
             restriction_message = RESTRICTION_MESSAGE_AFTER_MESSAGES.format(
                 user_mention=user_mention,
-                message_count=record.message_count,
+                message_count=fresh.message_count,
                 missing_text=missing_text,
                 rules_link=group_config.rules_link,
                 dm_link=dm_link,
             )
             logger.info(
-                f"Sending restriction notice: user_id={user.id}, user={user.full_name}, message_count={record.message_count}"
+                f"Sending restriction notice: user_id={user.id}, user={user.full_name}, message_count={fresh.message_count}"
             )
             await context.bot.send_message(
                 chat_id=group_config.group_id,
@@ -197,7 +201,7 @@ async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE) ->
                 parse_mode="Markdown",
             )
             logger.info(
-                f"Restricted user {user.id} ({user.full_name}) after {record.message_count} messages (group_id={group_config.group_id})"
+                f"Restricted user {user.id} ({user.full_name}) after {fresh.message_count} messages (group_id={group_config.group_id})"
             )
         except Exception:
             logger.error(

src/bot/handlers/verify.py

@@ -14,7 +14,7 @@
 import logging
 
 from telegram import Bot, Update
-from telegram.error import BadRequest, Forbidden, NetworkError, TimedOut
+from telegram.error import TelegramError
 from telegram.ext import ContextTypes
 
 from bot.constants import (
@@ -90,7 +90,7 @@ async def verify_user_in_group(
                 logger.info(
                     f"Unrestricted user {target_user_id} in group {group_id} during verification"
                 )
-            except (BadRequest, Forbidden, NetworkError, TimedOut, RuntimeError) as e:
+            except (TelegramError, RuntimeError) as e:
                 logger.info(
                     f"Could not unrestrict user {target_user_id} in group {group_id}: {e}"
                 )

src/bot/services/captcha_recovery.py

@@ -46,16 +46,20 @@ async def handle_captcha_expiration(
         user_full_name: The user's full name.
     """
     db = get_database()
-    pending = db.get_pending_captcha(user_id, group_id)
-    if not pending:
-        logger.info(f"No pending captcha for user {user_id}, already verified")
-        return
-
-    db.remove_pending_captcha(user_id, group_id)
 
-    # Create UserWarning to track this bot-applied restriction
-    # Allows DM handler to unrestrict user later when profile is complete
     async with restriction_lock(group_id, user_id):
+        pending = db.get_pending_captcha(user_id, group_id)
+        if not pending:
+            logger.info(f"No pending captcha for user {user_id}, already verified")
+            return
+
+        removed = db.remove_pending_captcha(user_id, group_id)
+        if not removed:
+            logger.info(f"Captcha for user {user_id} already finalized, ignoring timeout")
+            return
+
+        # Create UserWarning to track this bot-applied restriction
+        # Allows DM handler to unrestrict user later when profile is complete
         warning = db.get_or_create_user_warning(user_id, group_id)
         if not warning.is_restricted:
             db.mark_user_restricted(user_id, group_id)