docs: clarify single instance per bot

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
 

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.