## Parent issue

[Lexus2016]

Parent issue

#466 — Telegram Gateway Unreliable

This slice

Add a session-scoped circuit-breaker around Telegram send/poll operations: after N consecutive connection failures, mark Telegram unhealthy and skip attempts for T seconds, preventing retry loops and cascading log spam.

Acceptance criteria

• Failure counter and cooldown state in Telegram adapter.
• Configurable N and T via config.yaml.
• Cooldown respected by both polling and send paths.
• Health state exposed for introspection.
• Regression tests with mocked ConnectError.

Estimated effort

Easy (< 4h)

[Lexus2016]

Child of parent issue. This slice must land before the parent can be closed.

[Da-Mikey]

Deferred — needs more detailed implementation plan

Reason: Well-scoped but the Telegram adapter (gateway/platforms/telegram.py) has complex async state with multiple code paths (poll, send, reconnect). A session-scoped circuit breaker must respect cooldown on all paths. Estimated 4h is understated for the required comprehension. Keep open as needs-split — suggest further decomposing into: (1) shared failure counter utility, (2) poll-path integration, (3) send-path integration, (4) health-exposure API.

[Da-Mikey]

Deferred at implementation: larger than estimated. The Telegram adapter (plugins/platforms/telegram/adapter.py) is ~7.4k lines; adding a session-scoped circuit breaker for send/poll operations touches both the adapter's connection lifecycle and its polling loop. Real scope confirmed at ~12h.

Proposed decomposition:

1. Standalone _FailureCounter class in a shared utility (e.g. hermes_cli/breaker.py) — configurable N failures and T cooldown, thread-safe, reset-on-success.
2. Telegram adapter integration — wrap adapter.send() with _FailureCounter, skip send during cooldown.
3. Polling loop integration — skip poll iteration during cooldown.
4. Config wiring — N and T parameters in config.yaml under telegram.circuit_breaker.
5. Health introspection — expose current state (healthy, cooldown_remaining) via adapter property.
6. Tests — mocked ConnectError regressions for each path.

Step 1 (standalone _FailureCounter) is the smallest viable slice (~2h).

[Lexus2016]

Decomposed into child issues:\n- #571 — shared utility\n- #573 — Telegram adapter send/poll circuit breaker

[Lexus2016]

Rejected by evolution-analysis: duplicate — Already decomposed into child issues #571 and #573; those children cover the remaining work.