telegram-listener: Known Failure Modes

telegram-listener is the pipeline entry point. It receives Telegram webhook updates and routes them.

FAILURE MODES:

1. Gate 5 engagement verdict timeout — channel-engagement-pipeline-runner call times out (15s). All DMs gate-drop silently. Check channel-engagement health first when DMs stop being processed.

2. RabbitMQ disconnect — event publishing fails. Messages are still received from Telegram but request.received events stop appearing in system_event_log. Check rabbitmq consumer count on the normalize.request queue.

3. agent-gateway HTTP failure — deep-path POST fails (5s timeout). Message is logged as received but never dispatched. System shows request.received with no request.dispatched following it.

4. Config service unreachable on startup — service fails to boot; all webhook callbacks return 500. Check config-service health.

5. MongoDB write errors — zoey_raw_messages insert fails but pipeline continues (non-fatal). Watch for error logs containing zoey_raw_messages.

6. Redis session cache miss — causes repeated context lookups. Performance degradation, not a hard failure.

FIRST CHECKS:

• Is request.received appearing in system_event_log? If not, telegram-listener is not receiving updates.
• Is request.dispatched appearing? If received but no dispatched, check gate logic and channel-engagement-pipeline-runner health.
• Check container logs for "gate drop" or "engagement unreachable" messages.
• RabbitMQ: check consumer count on normalize.request queue — should be 1 (agent-tools consumer).

DEPLOY TYPE: image-copy. Changes require rebuild + up -d.