Exponential backoff counter never auto-resets when server becomes reachable again

[Ishannaik]

Environment

• OS: Windows 11 (10.0.22621)
• Platform: amd64
• wakatime-cli version: v1.139.4
• API server: Wakapi (self-hosted at wakapi.dev)
• Integration: claude-code-wakatime v3.0.5 (Claude Code hook)

Description

The exponential backoff mechanism accumulates retries indefinitely and never auto-resets when the API server becomes reachable again. Once the counter reaches a high value, the CLI effectively stops sending heartbeats permanently until the user manually resets ~/.wakatime/wakatime-internal.cfg.

Steps to Reproduce

1. Configure wakatime-cli with an API server (Wakapi or WakaTime cloud)
2. Let the server become temporarily unreachable (PC sleep, server restart, brief network outage)
3. CLI enters exponential backoff (expected)
4. Server comes back online
5. CLI remains in backoff — never attempts a fresh connection

What Happened

After a brief server outage, wakatime-internal.cfg showed:

[internal]
backoff_at      = 2026-03-23T09:38:19+05:30
backoff_retries = 2839

With 2,839 retries, the backoff window is so large that every heartbeat call returns exit code 1 immediately without attempting to reach the API. The CLI is effectively dead.

When used as a Claude Code hook, this produces PreToolUse hook error on every tool call — hundreds of errors per session.

What I Expected

The backoff counter should auto-reset after:

• A maximum retry count (e.g., cap at 10, then try fresh)
• A maximum backoff duration (e.g., max 1 hour between attempts)
• A time-based reset (e.g., if backoff_at is older than 24 hours, reset)
• Or: attempt a real health check every N minutes regardless of backoff state, reset on success

Workaround

Manually resetting the internal config fixes it immediately:

sed -i 's/backoff_retries.*=.*/backoff_retries           = 0/' ~/.wakatime/wakatime-internal.cfg
sed -i 's/backoff_at.*=.*/backoff_at                = /' ~/.wakatime/wakatime-internal.cfg

Logs

Debug output from wakatime-cli --log-to-stdout --verbose after the backoff accumulated:

{"level":"debug","message":"params: api params: (backoff at: '2026-03-23T09:38:19+05:30', backoff retries: 2839, ...)"}

The CLI checks the backoff state, sees it's within the backoff window, and exits without trying.

(Note: the troubleshooting docs say to delete wakatime-internal.cfg and filter out backoff errors — but in this case the backoff itself IS the bug, not a symptom of another error.)

Related Issues

• Exit code 112, working offline #785 (Exit code 112, working offline)
• Seperate file for waketime.cfg/[settings] from [internal] #535 (Separate file for internal config)
• Wakatime working offline... coding activity will sync next time we are online vscode-wakatime#257 ("working offline" stuck state)
• pushing 1 heartbeat(s) to queue after error: won't send heartbeat due to backoff without proxy vscode-wakatime#430 ("won't send heartbeat due to backoff")