From bbb7bcbc39f7930c83ddbd94c239eed48041513e Mon Sep 17 00:00:00 2001
From: banteg <4562643+banteg@users.noreply.github.com>
Date: Mon, 29 Dec 2025 18:01:58 +0400
Subject: [PATCH] docs: clarify single instance per bot

---
 developing.md |  3 +++
 readme.md     | 12 ++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/developing.md b/developing.md
index e2e0fba..0bdce6d 100644
--- a/developing.md
+++ b/developing.md
@@ -25,6 +25,9 @@ The orchestrator module containing:
 - `asyncio.TaskGroup` manages per-message tasks
 - Progress edits are throttled to ~2s intervals
 - Subprocess stderr is drained to a bounded deque for error reporting
+- `poll_updates()` uses Telegram `getUpdates` long-polling with a single server-side updates
+  queue per bot token; updates are confirmed when a client requests a higher `offset`, so
+  multiple instances with the same token will race (duplicates and/or missed updates)
 
 ### `telegram_client.py` — Telegram Bot API
 
diff --git a/readme.md b/readme.md
index 2ead861..5fcb491 100644
--- a/readme.md
+++ b/readme.md
@@ -104,6 +104,18 @@ resume: `019b66fc-64c2-7a71-81cd-081c504cfeb2`
 - **Notifications**: Codex's built-in notify is disabled (bridge handles it)
 - **Filtering**: Only accepts messages where chat ID equals sender ID and matches `chat_id`
 
+## Operational Notes
+
+### Single consumer: do not run multiple instances per bot token
+
+Run exactly one instance per bot token.
+
+This bridge uses Telegram's `getUpdates` long-polling. Telegram stores incoming updates in a
+single queue per bot and considers an update confirmed once a client calls `getUpdates` with an
+`offset` higher than the update's `update_id` (see the [Telegram Bot API](https://core.telegram.org/bots/api)).
+Running two bridge processes with the same bot token will cause them to compete for updates
+(duplicates and/or missed messages).
+
 ## Development
 
 See [`developing.md`](developing.md) for architecture details.