#22363: fix(telegram): isolate update offset state by bot token
channel: telegram
size: S
Cluster:
Telegram Command Fixes
## Summary
- Scope update state writes/reads to include Telegram bot token fingerprinting in src/telegram/update-offset-store.ts and pass token from polling monitor.
- Added migration-safe behavior: legacy/untagged v1 state files are ignored whenever a token is provided to avoid cross-token offset reuse.
- Added regression tests covering token-isolated offsets and legacy v1 compatibility guards in src/telegram/update-offset-store.test.ts.
## Why this fixes #22300
The previous storage format only keyed offsets by account id, so multiple Telegram tokens/accounts could reuse stale updateId checkpoints and skip messages. Binding checkpoints to token fingerprint prevents cross-token interference while preserving existing file location and cleanup behavior.
## Tests
- pnpm vitest run src/telegram/update-offset-store.test.ts src/telegram/monitor.test.ts
- pnpm test:fast src/telegram/update-offset-store.test.ts src/telegram/monitor.test.ts
## Edge cases
- If readTelegramUpdateOffset is called with token but stored file is legacy v1 (no fingerprint), it returns null and monitoring starts from fresh state.
- If token is omitted, behavior remains backward compatible with a single stored offset for that state path (legacy callers).
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR correctly solves cross-token update offset interference by introducing SHA-256 token fingerprinting in the Telegram polling state. The implementation migrates from V1 (account-scoped only) to V2 (account + token scoped) storage format.
**Key changes:**
- `update-offset-store.ts` bumped to version 2, added `tokenFingerprint` field and validation
- `monitor.ts` now passes token to read/write operations (lines 124, 135)
- Legacy V1 state files are rejected by version check, forcing fresh start on upgrade
- Atomic write pattern (write to temp + rename) ensures consistency
**Migration behavior:**
Users upgrading from V1 will have their existing offset files ignored, causing bots to start from fresh state. This is intentional to prevent cross-token contamination when V1 files lack fingerprints.
**Test coverage:**
- Token isolation verified (lines 56-71 in test file)
- V1 rejection tested (lines 73-90)
- Existing tests for no-token path continue to pass
**Note on review comments:**
Please disregard the inline comment on `update-offset-store.ts` line 46. That comment incorrectly suggests allowing V1 files to be read without token validation, which would reintroduce the cross-token offset bug this PR fixes. The current implementation correctly rejects all V1 files to ensure migration safety.
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge with minor caveats around migration behavior
- The implementation correctly solves the reported issue using well-established patterns (SHA-256 fingerprinting, atomic writes, version migration). Core logic is sound and test coverage addresses the main scenarios. Score reduced from 5 to 4 due to: (1) V1 migration causes users to lose existing offsets (acceptable but worth noting in release notes), and (2) one incorrect review comment was created during analysis that should be disregarded
- No files require special attention - all three changed files implement the solution correctly
<sub>Last reviewed commit: de0df5b</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#11347: fix: scope Telegram update offset to bot token
by anooprdawar · 2026-02-07
86.2%
#3186: fix(telegram): sanitize update offset + lock polling
by daxiong888 · 2026-01-28
80.6%
#18115: fix: prevent voice message loss during concurrent update processing
by AlekseyRodkin · 2026-02-16
79.4%
#7611: fix: migrate channels.telegram.token to botToken on config load
by luiginotmario · 2026-02-03
77.3%
#14488: Fix Telegram default account listing and CLI cache-write usage mapping
by abdulbb · 2026-02-12
77.1%
#8694: Fix Telegram routing when token override omits accountId
by codvik · 2026-02-04
76.8%
#16995: fix(telegram): record update ID before processing to prevent crash ...
by AI-Reviewer-QS · 2026-02-15
76.3%
#8166: fix(telegram): lifecycle fixes for duplicate messages and auto-reco...
by cheenu1092-oss · 2026-02-03
76.3%
#16708: fix(security): OC-17 add token redaction to error formatting, depre...
by aether-ai-agent · 2026-02-15
75.7%
#23238: fix(telegram): account named "default" silently breaks inbound polling
by anillBhoi · 2026-02-22
75.7%