Summary

• Problem: Telegram fetch sticky fallback only promoted from primary to IPv4/pinned-IP transports and never returned to primary.
• Why it matters: transient Telegram egress failures could leave a gateway on degraded transport until restart.
• What changed: after repeated successful sticky fallback requests, Telegram fetch performs one primary recovery probe and resets/demotes sticky state only on successful transport recovery.
• What did NOT change (scope boundary): no config knobs, fallback IP changes, dispatcher pool changes, or Telegram send/polling API changes.

Change Type

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope

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

Linked Issue/PR

• Closes [Bug/Design]: Telegram fetch stickyAttemptIndex is monotonic — gateway never recovers from transient network failures without restart #77088
• Related #N/A
• This PR fixes a bug or regression

Root Cause

• Root cause: stickyAttemptIndex was monotonic and had no success-path recovery logic.
• Missing detection / guardrail: existing tests asserted sticky promotion but not recovery after transient failure.
• Contributing context (if known): Telegram transport fallback is useful for persistent IPv6/DNS issues, but needed a bounded recovery path.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/telegram/src/fetch.test.ts
• Scenario the test should lock in: sticky IPv4 and pinned-IP fallback recover to primary after repeated successes, while a failed primary probe keeps fallback sticky.
• Why this is the smallest reliable guardrail: it tests the transport state machine directly with mocked fetch dispatchers.
• Existing test that already covers this (if any): existing sticky fallback tests covered promotion only.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Telegram transport can recover from sticky IPv4/pinned-IP fallback without restarting the gateway after the primary path becomes healthy again.

Diagram

Before:
primary failure -> sticky fallback -> remains degraded until restart

After:
primary failure -> sticky fallback -> recovery probe -> primary restored when healthy

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: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 24.13.0
• Model/provider: N/A
• Integration/channel (if any): Telegram
• Relevant config (redacted): default Telegram fetch transport with fallback enabled

Steps

1. Simulate a transient primary Telegram fetch failure.
2. Observe sticky fallback promotion to IPv4 or pinned-IP dispatcher.
3. Let fallback requests succeed enough to trigger recovery probing.
4. Simulate primary recovery.

Expected

• Sticky fallback resets to primary after a successful primary recovery probe.

Actual

• Before this fix, sticky fallback remained degraded until process restart.

Evidence

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

pnpm test extensions/telegram/src/fetch.test.ts
pnpm test extensions/telegram/src/polling-transport-state.test.ts extensions/telegram/src/polling-session.test.ts
pnpm test extensions/telegram/src/send.test.ts
pnpm check:changed

Human Verification

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

• Verified scenarios: IPv4 sticky fallback recovery, pinned-IP sticky fallback recovery, failed primary recovery probe retaining fallback.
• Edge cases checked: caller-provided dispatchers do not advance recovery state; all-attempt failure still leaves armed fallback sticky.
• What you did not verify: live overnight flaky-network saturation behind GFW.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

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

Risks and Mitigations

• Risk: Primary transport could still be unhealthy when probed.
  • Mitigation: the probe is bounded to one normal request after repeated sticky successes; if primary fails, the same request falls back and sticky fallback remains active.

Real behavior proof

• Behavior addressed: Telegram fetch sticky fallback now recovers from IPv4/pinned-IP fallback to the primary transport after repeated successful fallback requests, instead of staying degraded until gateway restart.
• Real environment tested: Local OpenClaw checkout on Linux with Node 24.13.0, exercising the Telegram fetch transport state machine after this patch. No live Telegram bot token was used because the reported outage requires a flaky GFW-style egress path, but the runtime transport behavior is covered directly.
• Exact steps or command run after this patch:

pnpm test extensions/telegram/src/fetch.test.ts

• Evidence after fix:

extensions/telegram/src/fetch.test.ts passed locally on Node 24.13.0.
The after-fix output covered the sticky IPv4 fallback recovery path, the sticky pinned-IP fallback recovery path, and the failed-primary-probe path that keeps fallback sticky.

• Observed result after fix: After repeated successful fallback requests, the next recovery probe can use the primary transport again; when the primary probe fails, the request still falls back and sticky fallback remains active.
• What was not tested: A live overnight Telegram bot run behind the same flaky GFW/DC4 blackhole environment from [Bug/Design]: Telegram fetch stickyAttemptIndex is monotonic — gateway never recovers from transient network failures without restart #77088; that environment-dependent saturation path was not available locally.