Summary

Describe the problem and fix in 2–5 bullets:

• Problem: Telegram polling offset persistence was keyed by account only, so switching bot tokens on the same account could reuse stale offsets; polling stop paths could also race across abort/retry/finally.
• Why it matters: Stale offsets can skip or replay updates across bots, and overlapping pollers can trigger conflicts/recovery loops.
• What changed: Added bot-identity scoping to persisted Telegram offsets, pass bot token through monitor read/write paths, and unified runner stop into one awaited stop promise across abort/retry/finally.
• What did NOT change (scope boundary): No channel routing changes, no webhook behavior changes, and no new config flags.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related fix(telegram): await runner.stop() to prevent polling race condition on hot-reload #10850
• Related fix: scope Telegram update offset to bot token #11347

User-visible / Behavior Changes

• Telegram long-poll offset files are now treated as bot-specific; if a token's bot ID differs from stored state (or state is legacy/no bot ID), polling starts fresh from current stream for that token/account pairing.
• Polling restart/abort now converges on a single awaited runner stop path to reduce overlap risk.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + pnpm
• Model/provider: N/A
• Integration/channel (if any): Telegram
• Relevant config (redacted): default Telegram account in tests

Steps

1. Run pnpm test src/telegram/update-offset-store.test.ts src/telegram/monitor.test.ts.
2. Run pnpm check.
3. Inspect src/telegram/update-offset-store.ts and src/telegram/monitor.ts for token-scoped offset read/write + unified stop path.

Expected

• Telegram polling tests pass, including cross-token/legacy offset cases.
• Full check pipeline passes.

Actual

• Passed locally.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: token mismatch returns null offset; legacy v1 offset with token returns null; monitor uses one awaited stop path.
• Edge cases checked: runner.stop non-promise compatibility in tests; recoverable retry flows still pass.
• What you did not verify: live Telegram network behavior on a real bot token.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this PR commit.
• Files/config to restore: src/telegram/monitor.ts, src/telegram/update-offset-store.ts.
• Known bad symptoms reviewers should watch for: unexpected offset reset on malformed token format (falls back to account-scoped read semantics when bot ID cannot be extracted).

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: Existing legacy offset files for tokened runs are treated as stale and can replay a bounded window from current stream.
  • Mitigation: This is intentional for correctness across bot switches; behavior is explicit and covered by tests.

Additional context:

• This PR intentionally consolidates and rebases the viable parts of #10850 and #11347.
• Changelog credit is included in this branch for both contributors (@talhaorak and @anooprdawar).

Greptile Summary

Scopes Telegram polling offsets to bot identity to prevent offset reuse when switching bot tokens on the same account, and consolidates runner-stop logic to prevent overlapping pollers during restart/error recovery.

Key changes:

• Added botToken parameter to offset read/write functions and store bot ID extracted from token in offset state
• Bumped offset store version from 1 to 2 with backward-compatible legacy parsing
• Modified readTelegramUpdateOffset to return null when stored bot ID doesn't match current token or when legacy v1 offset is read with a token
• Unified runner stop into single awaited promise across abort/retry/finally paths in monitor.ts
• Added comprehensive test coverage for cross-token offset isolation and legacy offset handling

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is well-designed with proper backward compatibility handling, comprehensive test coverage for both new functionality and edge cases, and careful attention to race conditions in the runner stop logic. The bot ID extraction is defensive (returns null on malformed tokens), and the version bump with legacy support ensures existing deployments won't break.
• No files require special attention

_{Last reviewed commit: a88a34d}