fix(mcp): clamp expired-token expires_in to -1 and add proactive refresh timer

[diegokolling]

Summary

MCP OAuth servers (Notion, Todoist, etc.) force a full browser re-authentication on every Hermes restart. Two independent latent bugs combine to cause this:

1. Dead-token misdetection — expired tokens are re-classified as valid, causing the SDK to ship a stale bearer token (401 → browser OAuth, skipping silent refresh entirely).
2. No proactive refresh — if the token is valid at startup but expires shortly after, the next tool call triggers browser OAuth during background discovery, which must not open a browser.

Both are fixed without new environment variables, without new model tools, and without touching the core tool schema. Fix B reuses the SDK's existing _refresh_token() / _handle_refresh_response() internal methods.

Root Cause Analysis

Fix A — Dead-token misdetection (tools/mcp_oauth.py)

HermesTokenStorage.get_tokens() clamps the recomputed expires_in to a minimum of 0 using int(max(..., 0)). For an expired token this produces expires_in = 0. The SDK stores token_expiry_time = time.time() + 0, making is_token_valid() evaluate time.time() <= time.time() — True due to float granularity. The SDK ships the stale token, gets a 401, and falls through to browser OAuth instead of silent refresh.

Fix: clamp to -1 instead of 0 — calculate_token_expiry(-1) yields time.time() - 1, making is_token_valid() return False, routing to the refresh_token grant.

Fix B — No proactive refresh (tools/mcp_oauth_manager.py)

The SDK only refreshes reactively (on 401). If the token expires 5 min after startup and the next call is background discovery, the SDK opens a browser in a non-interactive context. Fix: schedule a loop.call_later timer that silently refreshes 5 min before expiry (capped at 55 min), chains on success, retries in 60s on failure. Reuses the SDK's existing _refresh_token() + _handle_refresh_response() — no hand-rolled HTTP.

Reproduction Steps

1. Configure an MCP OAuth server (Notion/Todoist), complete browser OAuth.
2. Force-expiry by setting expires_at in ~/.hermes/mcp-tokens/<server>.json to a past timestamp.
3. Start gateway/desktop. Without Fix A: browser tabs open immediately. Without Fix B (but with A): refreshed only on first tool call — if background discovery, browser still opens. With both: refresh runs silently before any tool call.

Production evidence:

2026-07-09 11:06:18,065 WARNING tools.mcp_oauth_manager: MCP OAuth 'notion': proactive refresh failed (400), retry in 60s

Test Plan

Fix A: test_get_tokens_expired_clamped_to_neg1, test_get_tokens_expired_implied_expiry, test_get_tokens_valid_token_unchanged

Fix B: test_proactive_refresh_scheduled_on_init, test_proactive_refresh_skip_if_no_refresh_token, test_proactive_refresh_skip_if_no_expiry, test_proactive_refresh_delay_capped_at_55min, test_proactive_refresh_retries_on_failure, test_proactive_refresh_chains_on_success

All follow existing patterns: tmp_path + monkeypatch, MagicMock, no network I/O.

Relationship to existing issues

• Headless MCP OAuth reconnect hangs on a no-refresh-token credential and surfaces no needs_reauth state (distinct from #18165's transport recovery) #56673 — complementary: covers the headless no-refresh-token hang case. This PR fixes the more common case where a refresh_token exists but the token was misdetectd as valid, and adds proactive refresh so the token never goes stale while a process is alive.
• fix(mcp): consolidate OAuth handling, pick up external token refreshes #11383 — prior OAuth consolidation that picked up external token refreshes; this PR adds the proactive scheduling that PR did not include.

Attributed to: Diego Kolling + Hermes

[teknium1]

Thanks for the focused MCP OAuth work. Current main already has a cold-load expiry path: tools/mcp_oauth.py:313-347 reconstructs TTL, tools/mcp_oauth_manager.py:179-182 seeds SDK expiry, and tests/tools/test_mcp_oauth_cold_load_expiry.py:283-350 verifies an expired persisted token is invalid and refreshable.

Problems

• The proposed timer is not cancelled before replacement. Main can reinitialize a provider after disk invalidation (tools/mcp_oauth_manager.py:599-606), while remove() only drops the entry/files (:559-569), so duplicate or orphaned callbacks can race refresh-token rotation.
• The proposed retry is ineffective after an HTTP refresh failure: MCP 1.26.0 clears current_tokens in _handle_refresh_response on non-200 (venv/lib/python3.11/site-packages/mcp/client/auth/oauth2.py:445-464); the next callback's can_refresh_token() check then returns false.
• The PR diff contains no tests, although the description lists timer and expiry tests.

Suggested changes

• Make timer replacement/cancellation part of the provider-entry lifecycle, including eviction and repeated initialization.
• Preserve a retryable refresh state only for explicitly transient failures, and add deterministic tests for duplicate scheduling, eviction, failure retry, and successful chaining.

Automated hermes-sweeper review.

[diegokolling]

Thanks for the review — all three points are addressed in the force-pushed tip (8d2032c).

1. Timer cancellation / lifecycle

• Added _cancel_proactive_refresh() and made _schedule_proactive_refresh() always cancel any previous asyncio.TimerHandle before installing a new one.
• _initialize cancels first, then schedules — so disk-invalidation re-init cannot leave an orphaned callback racing a new provider entry.
• MCPOAuthProviderManager.remove() now pops the entry and cancels the provider's timer before deleting on-disk tokens/client files.

2. Retry only for transient failures

MCP 1.26.0 clears current_tokens inside _handle_refresh_response on non-200, which makes a naive “retry next minute” ineffective (can_refresh_token() then returns false).

New policy in _do_proactive_refresh:

• Success (HTTP 200 + valid payload) → chain the next proactive schedule.
• Transient (transport/timeouts, 408/425/429, 5xx) → retry once after 60s only if can_refresh_token() still holds.
• Permanent 4xx / invalid payload → stop. We deliberately do not call _handle_refresh_response on non-200, so permanent HTTP failures don't wipe refreshability as a side effect of our timer path; recovery remains the normal re-auth path.

3. Deterministic tests

New file tests/tools/test_mcp_oauth_proactive_refresh.py covers:

• duplicate schedule cancels the previous handle
• re-_initialize cancels the orphan
• manager remove() cancels on eviction
• success chains the next schedule
• permanent failure does not reschedule
• transient failure reschedules only while still refreshable

Also updated tests/tools/test_mcp_oauth_cold_load_expiry.py assertions for the expires_in=-1 clamp (why: SDK calculate_token_expiry(0) + is_token_valid treats now as still valid under float granularity).

Verification

Local: 27 passed across cold-load + proactive-refresh + bidirectional + integration OAuth suites, rebased onto current main.

—Diego Kolling (@diegokolling) + Hermes Agent (team)