PR #15822: fix(matrix): drop bridge / appservice ghost senders before pairing flow

• Repository: NousResearch/hermes-agent
• Author: bitloi
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/15822

Description (problem / solution / changelog)

What does this PR do?

Fixes the "hall of mirrors" loop reported in #15763. Matrix application-service ghost users (Telegram, IRC, Signal, … bridges) puppet remote users via MXIDs in their declared namespace and deliver system-level events (status notices, "interruption" relays) with valid-but-unauthorized MXIDs. The runner only short-circuited on source.user_id is None, so these events triggered the unauthorized-DM pairing flow; once an operator approved one, every relay re-emission of the gateway's outbound traffic was processed as a new user turn — an infinite agent-response loop with no workaround.

The fix layers two defenses, matching the issue author's "Integrated Defense" proposal:

1. Prevention — recognize bridge / appservice ghost senders by MXID prefix (default @_, the namespacing convention from the Matrix appservice spec) and an operator allowlist, and drop them before the pairing flow at both the adapter (MatrixAdapter._on_room_message) and the runner (GatewayRunner._is_system_identity). The runner check is placed before authorization so an accidentally-paired bridge user is still neutralized at runtime.
2. Robustness — the adapter keeps a bounded ring of recently-sent event IDs and drops inbound events whose ID matches one we just sent, catching relay reflections regardless of sender.

internal=True synthetic events continue to bypass both gates (regression for #6540 / cac61781).

Related Issue

Fixes #15763

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• gateway/platforms/matrix.py — module-level is_matrix_bridge_sender / _parse_bridge_prefixes / _parse_bridge_users helpers; new MATRIX_BRIDGE_PREFIXES (default @_) and MATRIX_BRIDGE_USERS env vars documented in the module docstring; MatrixAdapter parses both at init, records every outbound event_id from send() into a bounded (maxlen=512) deque + lookup set, and drops bridge senders / outbound echoes inside _on_room_message.
• gateway/run.py — new GatewayRunner._is_system_identity(source) dispatching by platform; _handle_message now drops system identities before _is_user_authorized, between the existing user_id is None short-circuit and the pairing branch.
• tests/gateway/test_matrix_bridge_filter.py — 18 cases covering helper parsing, default prefix, env-var allowlists, custom prefix overrides, case-insensitive matching, the real-user pairing regression guard, pre-paired bridge user, internal=True bypass, group-room echoes, ring eviction, idempotent recording, and empty-event-id handling.

How to Test

1. Run the new suite: pytest tests/gateway/test_matrix_bridge_filter.py -v → 18 passed.
2. Regression suite for the affected area:

   pytest tests/gateway/test_matrix_bridge_filter.py \
          tests/gateway/test_unauthorized_dm_behavior.py \
          tests/gateway/test_internal_event_bypass_pairing.py \
          tests/gateway/test_pairing.py \
          tests/gateway/test_matrix.py \
          tests/gateway/test_matrix_voice.py \
          tests/gateway/test_matrix_mention.py \
          tests/gateway/test_auth_fallback.py -q

   → 242 passed.
3. Manual reproduction of the issue scenario: with a bridge MXID (@_telegram_bridge_:matrix.org) sending a DM to the gateway, pairing_store.generate_code is not called and no pairing message is sent. Same outcome even when pairing_store.is_approved is True — covers the case where the operator already paired a bridge before this fix lands.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass (the pre-existing failures in test_discord_free_response.py and test_whatsapp_connect.py are unrelated and reproduce on main)
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu (Linux 5.15), Python 3.11.15

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — added the two new env vars to the MatrixAdapter module docstring
• I've updated cli-config.yaml.example if I added/changed config keys — N/A (env-var only, no YAML key)
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — pure stdlib (collections.deque, env vars, string ops); no platform-specific behaviour
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Changed files

• gateway/platforms/matrix.py (modified, +109/-0)
• gateway/run.py (modified, +41/-0)
• tests/gateway/test_matrix_bridge_filter.py (added, +370/-0)