fix(healthcheck): per-provider proactive-refresh skip list (rescue short-TTL OAuth like Kimi)

[diegosouzapw]

Why

Investigated the stuck "Token Expired" Kimi-coding account on the 192.168.0.15 box (while .16/.17/.18 showed live ~4–11 min countdowns). Root cause:

• .15 has OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK=true set — the proactive token-refresh sweep is fully off (a leftover guard from the fix(sse): stop Codex multi-account family-revocation cascade on quota-sync #3019 Codex Auth0-family cascade, where the background sweep was the trigger for "adding account B invalidates account A").
• That switch is all-or-nothing. Kimi-coding issues short-TTL access tokens; with the sweep disabled they expire while idle, and only a reactive (and observed-racy) request can revive them. DB showed token_expires_at ~2.5 days stale, last_health_check_at=null, test_status=active → UI badge "Token Expired".

What

Add OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS (comma-separated, case-insensitive). checkConnection skips only the listed providers from the proactive sweep. An operator can set codex,openai to keep the rotating-cascade family reactive-only (preserving the #3019 protection) while Kimi/Claude/etc. resume proactive refresh — so .15 can drop the blunt full-disable.

Fix on .15 (operational, after merge+deploy)

Replace OMNIROUTE_DISABLE_TOKEN_HEALTHCHECK=true with OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS=codex,openai (and pm2 restart --update-env). Codex stays reactive-only; Kimi gets proactively refreshed again.

Tests (TDD — red→green verified)

• token-health-check → "skips providers listed in OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS": a listed provider triggers no proactive refresh; the same due connection is refreshed once removed from the list (control proves the skip, not token freshness, gated it). Fails on the pre-fix sweep.

typecheck:core clean; env-doc-sync updated (.env.example + ENVIRONMENT.md); full token-health-check suite 7/7.

Note on the refresh-timing question

The 5-min proactive lead (TOKEN_EXPIRY_BUFFER) is adequate for Kimi's TTL when the sweep runs — the timing wasn't the problem; the disabled sweep was. This PR restores proactive coverage for short-TTL providers without re-exposing Codex.

Companion to #3156 (OAuth quota-sync sequential+spacing). Both left open for release/v3.8.10; recommend a VPS soak before tagging.

[gemini-code-assist]

Code Review

This pull request introduces the OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS environment variable, allowing specific providers to opt out of proactive token-refresh sweeps while keeping reactive refresh paths active. This change is documented in .env.example and ENVIRONMENT.md, implemented in tokenHealthCheck.ts, and verified with a new unit test. The review feedback suggests two key improvements: caching the parsed skip-providers set to optimize performance during connection sweeps, and wrapping the unit test logic in a try...finally block to guarantee environment variable cleanup and prevent test pollution in case of assertion failures.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Accessing process.env and parsing the comma-separated skip list on every single connection check is inefficient, especially in environments with hundreds of connections. Since checkConnection is called in a loop during sweep(), we can optimize this by caching the parsed Set and only re-parsing if the raw environment variable changes (which is useful for tests).

let cachedSkipProviders: Set<string> | null = null;
let lastRawSkipProviders: string | null = null;

function getHealthCheckSkipProviders(): Set<string> {
  const raw = process.env.OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS || "";
  if (cachedSkipProviders && raw === lastRawSkipProviders) {
    return cachedSkipProviders;
  }
  const parsed = new Set(
    raw
      .split(",")
      .map((s) => s.trim().toLowerCase())
      .filter(Boolean)
  );
  cachedSkipProviders = parsed;
  lastRawSkipProviders = raw;
  return parsed;
}

[gemini-code-assist]

If any assertion fails during the test execution (e.g., assert.equal(refreshRequests.length, 0)), the test will abort immediately, and the cleanup code at the end of the test will never run. This leaks the modified process.env.OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS to subsequent tests, causing potential test pollution. Wrap the test logic in a try...finally block to guarantee the environment variable is restored.

test("checkConnection skips providers listed in OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS (#kimi-15)", async () => {
  await resetStorage();

  const providerId = "custom-oauth-skip-list";
  const refreshRequests: string[] = [];
  const prevSkip = process.env.OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS;

  try {
    await withHttpServer(
      (req, res) => {
        let body = "";
        req.setEncoding("utf8");
        req.on("data", (chunk) => {
          body += chunk;
        });
        req.on("end", () => {
          refreshRequests.push(body);
          res.writeHead(200, { "Content-Type": "application/json" });
          res.end(
            JSON.stringify({
              access_token: "should-not-be-fetched",
              refresh_token: "should-not-be-fetched",
              expires_in: 3600,
            })
          );
        });
      },
      async (tokenServer) => {
        await withPatchedProvider(
          providerId,
          {
            tokenUrl: tokenServer.url + "/token",
            clientId: "skip-client-id",
            clientSecret: "skip-client-secret",
          },
          async () => {
            const connection = await providersDb.createProviderConnection({
              provider: providerId,
              authType: "oauth",
              name: "Skip-list Account",
              email: "skip@example.com",
              accessToken: "stale-access-token",
              refreshToken: "refresh-token-skip",
              isActive: true,
            });

            // The connection is due for refresh (no known expiry, never checked).
            // With the provider listed, the proactive sweep must skip it entirely —
            // NO refresh request is made.
            process.env.OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS = "foo, " + providerId + " ,bar";
            await tokenHealthCheck.checkConnection(connection);
            assert.equal(
              refreshRequests.length,
              0,
              "listed provider must NOT trigger a proactive refresh"
            );

            // Control: with the provider no longer listed, the same due connection
            // IS refreshed — proving the skip (not token freshness) gated it.
            process.env.OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS = "some-other-provider";
            const stillStale = await providersDb.getProviderConnectionById((connection as any).id);
            await tokenHealthCheck.checkConnection(stillStale);
            assert.equal(refreshRequests.length, 1, "non-listed provider must refresh");
          }
        );
      }
    );
  } finally {
    if (prevSkip === undefined) delete process.env.OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS;
    else process.env.OMNIROUTE_HEALTHCHECK_SKIP_PROVIDERS = prevSkip;
  }
});