Builds on the prior commit by introducing the typed surfaces the rest of
the plugin (and `openclaw doctor`-style consumers) can reuse:
- `inspectTelegramUpdateOffset` returns a discriminated union
(`absent | valid | rotated`) so callers can act on the rotation event
without re-implementing the bot-id / fingerprint comparison.
`readTelegramUpdateOffset` is now a thin adapter over it.
- `TelegramOffsetRotationReason` is exported as a named type alias so
downstream code can switch over it exhaustively.
- New `TelegramOffsetRotationHandler` class encapsulates the
"log warning + delete stale file" side effect that the monitor needs at
startup, plus a `createTelegramOffsetRotationHandler` factory and a
pure `formatTelegramOffsetRotationMessage` helper used to keep the
wording consistent.
- `monitor.ts` now constructs the handler once per polling startup
instead of inlining the closure, and the new surfaces are re-exported
through `monitor-polling.runtime.ts`.
Unit coverage:
pnpm test extensions/telegram/src/update-offset-store.test.ts \
extensions/telegram/src/offset-rotation-handler.test.ts \
extensions/telegram/src/monitor.test.ts
Closes#80653.
Persist a non-reversible SHA-256 fingerprint of the bot token alongside the
bot id in the long-poll update offset store (version 3). On read, treat the
persisted offset as stale when the fingerprint diverges from the current
token, even when the bot id still matches. This covers the BotFather
`/revoke` case where the bot id is unchanged but the secret rotates -- the
in-process update tracker would otherwise silently skip any new updates
whose `update_id` is `<=` the restored watermark.
The legacy v2 (bot-id-only) layout still parses, and offsets are preserved
when the bot id matches so existing installs don't lose a watermark on
upgrade; the next persistence upgrades the file to v3 and enables rotation
detection going forward.
`readTelegramUpdateOffset` now reports each rotation through a new
`onRotationDetected` callback. `monitor.ts` uses it to log a clear warning
naming the previous/new bot id and the discarded offset, and to delete the
stale file rather than waiting for the first update to overwrite it.
Acceptance suites pass:
pnpm test extensions/telegram/src/update-offset-store.test.ts \
extensions/telegram/src/bot-update-tracker.test.ts \
extensions/telegram/src/monitor.test.ts \
extensions/telegram/src/bot.create-telegram-bot.test.ts \
extensions/telegram/src/token.test.ts \
extensions/telegram/src/polling-lease.test.ts
