From 752a3752ad50bd98a392d7cbeb5dd1cddd74ebb0 Mon Sep 17 00:00:00 2001
From: banteg <4562643+banteg@users.noreply.github.com>
Date: Mon, 29 Dec 2025 14:17:40 +0400
Subject: [PATCH] docs: update readme and developer guide

---
 codex_telegram_bridge/developing.md | 9 ++++++---
 codex_telegram_bridge/readme.md     | 5 ++++-
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/codex_telegram_bridge/developing.md b/codex_telegram_bridge/developing.md
index 5520a2a..6389ca4 100644
--- a/codex_telegram_bridge/developing.md
+++ b/codex_telegram_bridge/developing.md
@@ -13,7 +13,8 @@ The orchestrator module containing:
 | `main()` / `run()` | CLI entry point via Typer |
 | `BridgeConfig` | Frozen dataclass holding runtime config |
 | `CodexExecRunner` | Spawns `codex exec`, streams JSONL, handles cancellation |
-| `_run_main_loop()` | Long-poll loop for Telegram updates |
+| `poll_updates()` | Async generator that drains backlog, long-polls updates, filters messages |
+| `_run_main_loop()` | TaskGroup-based main loop that spawns per-message handlers |
 | `_handle_message()` | Per-message handler with progress updates |
 | `extract_session_id()` | Parses `resume: <uuid>` from message text |
 | `truncate_for_telegram()` | Smart truncation preserving resume lines |
@@ -21,6 +22,7 @@ The orchestrator module containing:
 **Key patterns:**
 - Per-session locks prevent concurrent resumes to the same `session_id`
 - `asyncio.Semaphore` limits overall concurrency (default: 16)
+- `asyncio.TaskGroup` manages per-message tasks
 - Progress edits are throttled to ~2s intervals
 - Subprocess stderr is drained to a bounded deque for error reporting
 
@@ -96,7 +98,9 @@ def setup_logging(*, debug: bool):
 ```
 Telegram Update
     ↓
-_run_main_loop() validates chat_id, extracts text
+poll_updates() drains backlog, long-polls, filters chat_id == from_id == cfg.chat_id
+    ↓
+_run_main_loop() spawns tasks in TaskGroup
     ↓
 _handle_message() spawned as task
     ↓
@@ -132,4 +136,3 @@ Same as above, but:
 | Telegram API error | Logged, edit skipped (progress continues) |
 | Cancellation | Subprocess terminated, CancelledError re-raised |
 | No agent_message | Final shows "error" status |
-
diff --git a/codex_telegram_bridge/readme.md b/codex_telegram_bridge/readme.md
index 20c1604..f7ee877 100644
--- a/codex_telegram_bridge/readme.md
+++ b/codex_telegram_bridge/readme.md
@@ -42,6 +42,8 @@ chat_id = 123456789
 | `bot_token` | Telegram Bot API token from [@BotFather](https://t.me/BotFather) |
 | `chat_id` | Allowed chat ID (also used for startup notifications) |
 
+The bridge only accepts messages where the chat ID equals the sender ID and both match `chat_id` (i.e., private chat with that user).
+
 ### Running
 
 ```bash
@@ -81,10 +83,11 @@ resume: `019b66fc-64c2-7a71-81cd-081c504cfeb2`
 - **Startup**: Pending updates are drained (ignored) on startup
 - **Progress**: Updates are throttled to ~2s intervals, sent silently
 - **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`
 
 ## Development
 
-See [`src/codex_telegram_bridge/developing.md`](src/codex_telegram_bridge/developing.md) for architecture details.
+See [`developing.md`](developing.md) for architecture details.
 
 ```bash
 # Run tests