feat(telegram): await polled handlers before advancing offset; combine incoming albums (#227)

CHANGELOG.md

@@ -303,6 +303,11 @@ Ports upstream `32687038` (vercel/chat#830, chat@4.38.1), the Google Chat part o
   - New exports from `chat_sdk.ai`: `ChatApprovalToolName`, `ReadScope`; `ToolOptions.guard`; `ChatToolsOptions.scope` / `strict_scope`.
   - **Python-specific (divergence from upstream):** link-metadata bounds count code points, not UTF-16 code units, so a field with emoji keeps up to the limit in code points and never ends on a lone surrogate. See `docs/UPSTREAM_SYNC.md`.
   - Fidelity: `ai/index.test.ts` 26 → 0 missing, `ai/messages.test.ts` 10 → 9 at `chat@4.41.1`.
+- **Telegram polling is at-least-once, and albums arrive as one message** (#227; ports vercel/chat `629e6555` #760, chat@4.37.0, and the Telegram half of `91683e52` #942, chat@4.41.0). Outbound multi-file `sendMediaGroup` (#605) is split out to #278.
+  - **Consumer-visible (polling):** the poller now waits for every handler of a batch before advancing `offset`. A handler failure no longer loses the update: it is saved in a `telegram:polling:{sha256(bot_user_id)}` state checkpoint and retried with backoff (`max(retry_delay_ms, 1000) * 2^(attempts-1)`, capped at 30 s, at least `retry_after` on rate limits), also after a restart. Handlers must tolerate redelivery: a handler that failed (or finished just before a crash) can run again. Polled updates bypass core dedupe (`WebhookOptions(deduplicate=False)`); the checkpoint deduplicates them. A batch is handled before the next `getUpdates`, so one slow handler delays the next poll. A failed startup `getMe` is retried on every poll.
+  - **Consumer-visible (albums):** the parts of an album (`media_group_id`) are buffered in state for 1 s after the newest part and reach handlers as **one** `Message` (newest part's id and raw, first non-empty text, all attachments in order, `is_mention` if any part mentions the bot), on the webhook and polling paths. Handlers that saw N messages per album now see one, about 1 s later (about 2 s when polling). An album caption starting with `/command` is the album's text, not a slash command.
+  - `TelegramAdapter.process_update` now returns the list of dispatched handler tasks; `handle_incoming_message_update`, `handle_callback_query`, `handle_message_reaction_update` and `handle_slash_command_update` return their task(s). `TelegramMessage` gains `media_group_id`.
+  - `stop_polling()` interrupts only a pending `getUpdates` or polling sleep; while handlers run it waits for them, as upstream. **Python-specific:** a handler task cancelled by `Chat.shutdown` counts as a failure, so its update stays in the checkpoint, and a stop that lands while the loop reads its checkpoint skips the ready retry batch until the next start (upstream still dispatches it). See `docs/UPSTREAM_SYNC.md`.
 - **BREAKING (Linear agent-session thread ids) — one stable thread per agent session** (#232; ports vercel/chat `3d2cb22a` #885, chat@4.40.0, and the Linear half of `fcdc1c9e` #946, chat@4.41.0).
   - **Breaking:** every agent-session message (created and prompted webhooks, fetched history, and the messages returned by `post_message` / `stream`) now uses `linear:{issueId}:s:{agentSessionId}`. It used to be `linear:{issueId}:c:{commentId}:s:{agentSessionId}`, a new thread per source comment. **Migration:** subscriptions and state stored under the old ids no longer match new events. Re-subscribe, or map each stored id by dropping its `:c:{commentId}` segment. Old-form ids still decode, so posting to a stored one still reaches its session.
   - **Consumer-visible:** a session created without a creator (for example by a Linear automation) is authored by `Author(user_id="linear-automation", user_name="Linear automation", is_bot=True, is_me=False)` and reaches your handlers. It used to be authored as the bot itself and dropped as a self-message.