# Upgrade Guide — v0.21.4

<!-- bump: patch -->
<!-- Valid values: patch, minor, major -->
<!-- patch = bug fixes, refactors, test additions, doc updates -->
<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
<!-- major = breaking changes to existing APIs or behavior -->

## What Changed

### Telegram Poll Offset — Range Sanity Check (Bug Fix)

`TelegramAdapter.poll()` now detects when the stored poll offset is from a different bot token or was corrupted during a migration, and auto-corrects it.

**Why this matters**: The `telegram-poll-offset.json` file stores the last processed `update_id` so polls can resume where they left off. If this file was written by a different bot token, or corrupted during a migration from another agent instance, the stored offset could be in a completely different numeric range from the current bot's update IDs.

When `getUpdates` is called with an offset from the wrong range, Telegram may return all pending updates as if the offset were unset — causing an infinite replay loop where the same messages are re-delivered on every poll cycle.

**The fix**: After each successful `getUpdates` call, the adapter now checks if the received update IDs are more than 10 million below the stored offset. If so, it logs a warning and auto-resets the offset to the received range, stopping the replay loop immediately.

**When this triggers**: Only when the detected delta exceeds 10,000,000 — a gap that can't occur from normal polling. Agents with correct offsets are not affected.

**No configuration changes required.** The fix is automatic.

## What to Tell Your User

- **Telegram infinite replay loop fixed**: If you ever saw the same messages replaying in an endless loop after switching bot tokens or migrating your agent, this is now detected and auto-corrected. A warning will appear in your agent logs when the correction happens.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Cross-token offset corruption recovery | Automatic — no action needed |
