fix(telegram): prevent startup hang and double-log on command sync failures (504/BOT_COMMANDS_TOO_MUCH)

[Copilot]

Two startup-time failures in Telegram command sync: a 504 on deleteMyCommands caused execution to fall through to setMyCommands, doubling the ~2-minute timeout hang; a separate BOT_COMMANDS_TOO_MUCH 400 occurred because TELEGRAM_MAX_COMMANDS=100 hits Telegram's enforced ceiling. Both surfaced a double-log: withTelegramApiErrorLogging logged the error, then the outer sync().catch() logged it again.

Summary

• Problem: Three bugs in syncTelegramMenuCommands: (1) TELEGRAM_MAX_COMMANDS=100 triggers BOT_COMMANDS_TOO_MUCH; (2) a 5xx on deleteMyCommands doesn't bail early, so setMyCommands waits a full second timeout that will also fail; (3) withTelegramApiErrorLogging rethrows after logging, and the outer void sync().catch() logged the same error again.
• What changed: Cap lowered 100→99; added isTelegramServerError() to detect HTTP 5xx by GrammyError's error_code field; deleteMyCommands catch now sets a deleteServerError flag on 5xx and skips setMyCommands; inner .catch() on setMyCommands absorbs the rethrow so the outer catch never double-logs.
• What did NOT change: Command dispatch, handler registration for overflow commands, auth, any other channel.

// Before: 4-minute hang + two error lines
19:07:59 [telegram] telegram deleteMyCommands failed: ... (504: Gateway Timeout)
19:09:59 [telegram] telegram setMyCommands failed: ... (504: Gateway Timeout)
19:09:59 [telegram] command sync failed: GrammyError: ... (504: Gateway Timeout)

// After: ~2-minute wait + one error line, then bail
19:07:59 [telegram] telegram deleteMyCommands failed: ... (504: Gateway Timeout)

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

• Related #

User-visible / Behavior Changes

• Gateway no longer hangs ~4 minutes at startup when Telegram API is temporarily unreachable (504).
• Bots with ≥100 commands no longer fail sync; first 99 are registered, overflow is logged with remediation guidance.
• Single error line per command sync failure (no duplicate).

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

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22
• Model/provider: n/a
• Integration/channel: Telegram Bot API
• Relevant config: default gateway with native + plugin commands at/above limit

Steps

1. Start gateway with Telegram API unreachable or returning 504.
2. Observe that only one error line is emitted and startup resumes after one timeout.
3. Start gateway with ≥100 commands configured; verify 99 are registered and overflow is logged once.

Expected

• Single log on failure, no double-log.
• No second 2-minute wait for setMyCommands after deleteMyCommands already timed out.
• No BOT_COMMANDS_TOO_MUCH for bots with up to 99 commands.

Actual (before)

[telegram] telegram deleteMyCommands failed: ... (504)
[telegram] telegram setMyCommands failed: ... (504)     ← extra 2-min wait
[telegram] command sync failed: GrammyError: ...        ← duplicate log

Evidence

• Failing test/log before + passing after

Key tests (all 9 pass in bot-native-command-menu.test.ts):

• skips setMyCommands when deleteMyCommands fails with a 5xx server error — setMyCommands not called on 504
• still calls setMyCommands when deleteMyCommands fails with a 4xx client error — fallthrough preserved for non-5xx
• logs setMyCommands failure once without rethrowing — runtimeError called exactly once

Human Verification (required)

• Verified scenarios: 504 bail-out (setMyCommands not called); 400 passthrough (setMyCommands still called); double-log elimination; 99-cap boundary.
• Edge cases checked: deleteMyCommands absent from bot API; 500 vs 599 range; 4xx codes do not bail; exactly-99-command bots.
• What you did not verify: live Telegram API call against a real 504 on a running gateway.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert: revert src/telegram/bot-native-command-menu.ts.
• Files/config to restore: none.
• Known bad symptoms: if 99-cap drops a needed command, lower further or set channels.telegram.commands.native: false; if skip-on-5xx is too aggressive, remove the deleteServerError flag and restore .catch(() => {}).

Risks and Mitigations

• Risk: 5xx bail skips setMyCommands even if only deleteMyCommands endpoint is overloaded and setMyCommands would have succeeded.
  • Mitigation: Extremely unlikely split; the alternative (another 2-minute predictable failure) is worse. Next restart retries both calls.
• Risk: Dropping from 100→99 removes one menu slot for bots that had exactly 100 working commands.
  • Mitigation: Those bots were already failing before this fix; overflow is logged with remediation guidance.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.