feat(providers): verify-only health sweep for web-cookie connections (#11488)

[oyi77]

Closes #11488.

What

The token health-check scheduler only iterated auth_type = 'oauth' rows, and its no-refresh-token branch no-opped anyway (tokenHealthCheck.ts :649/:770) — so every web-cookie connection (chatgpt-web, claude-web, grok-web, qwen-web, gemini-web, …) stayed testStatus: "active" until a live user request failed with 401/403.

This PR adds a verify-only path to the existing sweep:

• sweep() now also fetches { authType: "cookie" } rows.
• New leaf src/lib/tokenHealthCheckWebCookie.ts (same injectable-DI pattern as tokenHealthCheckKimi.ts / tokenHealthCheckCursor.ts) probes catalogued cookie providers via validateWebCookieProvider — the generic session-ping the dashboard Test button falls back to, proxy-fallback transport included.
• Result mapping is deliberately conservative:
  • valid → silent lastHealthCheckAt stamp (no per-tick log noise);
  • unambiguous AUTH_007 / SESSION_EXPIRED → terminal expired with errorCode: session_expired, lastErrorSource: webcookie;
  • network / guard-block / 5xx / unsupported → stamp only, never a state flip.
• Per-connection healthCheckInterval honored (default 60 min, 0 = off). kimi-web keeps its bespoke refresh leaf with precedence; no behavior change for OAuth rows.

The richer per-provider specialty validators are intentionally not used here: a background sweep that can terminal-state a connection must act only on an unambiguous signal.

Verification

• New unit suite tests/unit/token-health-check-webcookie.test.ts: 9/9 pass (npx tsx --test --test-force-exit tests/unit/token-health-check-webcookie.test.ts) covering all branches — candidate detection, non-cookie passthrough, valid-stamp, expired-flip field mapping, unsupported/inconclusive stamp-only, interval gate, missing credential, providerSpecificData.cookie fallback.
• Regression: tests/unit/token-health-check-kimi.test.ts 4/4 pass.
• npx tsc --noEmit -p tsconfig.json: zero diagnostics in the three touched files.
• npm run check:file-size: OK.
• ESLint: both new files clean. One pre-existing error remains in src/lib/tokenHealthCheck.ts (@/lib/localDb restricted-import barrel) — reproduced on the pristine base commit before my change, untouched here.

Changed files

• src/lib/tokenHealthCheckWebCookie.ts (new)
• src/lib/tokenHealthCheck.ts (+20 wiring lines)
• tests/unit/token-health-check-webcookie.test.ts (new)

[oyi77]

CI triage for the current red batch (Docs Gates / unit shards / Vitest / ESLint-suppressions): reproduced at today's merge ref (a179ffed5 + this branch) with none of this branch's content — check:docs-counts fails STRICT on README/AGENTS/llm.txt still saying "159 migrations" while code has 160, and tests/unit/agent-card-route.test.ts + tests/unit/providers-constants-split.test.ts fail at the tip itself. Inherited tip-drift, not introduced here.

This branch's own receipts stay green: token-health-check-webcookie.test.ts 9/9, Kimi health-check regression 4/4, tsc clean on touched files.

[diegosouzapw]

Held out of this merge batch — found a real defect while validating (reproduced 3/3 in isolation, not present on the pure release/v3.8.51 tip since this is entirely new code):

`honors the interval gate — recently checked rows are skipped silently` fails with `probed === true` (expected `false`).

Root cause: `checkWebCookieConnectionIfNeeded` (`src/lib/tokenHealthCheckWebCookie.ts:85`) gates on `Date.now() - lastCheckMs < intervalMin * 60 * 1000` — using the real wall clock — while the test fixes `NOW = "2026-08-25T12:00:00.000Z"` and derives `lastHealthCheckAt` as 5 minutes before that constant. Whenever the suite runs more than `intervalMin` away from that hardcoded timestamp (verified against real UTC just now: `2026-08-25T20:42:45Z`, an 8h42m gap vs the 60-minute interval under test), the gate never trips and the test fails — a timebomb, same class as the GLM weekly-reset test #11450 just de-timebombed.

Two ways to close it, your call:

1. Thread the injected `params.now` through the gate comparison instead of `Date.now()` — makes the function fully deterministic/testable and is probably the more correct shape given the function already takes `now` as a sweep-consistency timestamp.
2. Keep `Date.now()` in the source (arguably fine for a real background sweep) and de-timebomb the test by computing `lastHealthCheckAt` relative to `Date.now()` instead of the fixed `NOW` constant.

Everything else in the PR looks solid — 8/9 in this file, the rest of the suite (expired-flip mapping, unsupported/inconclusive stamp-only, missing-credential, providerSpecificData.cookie fallback, kimi-web regression) passes clean. Happy to take another look once this is fixed.

[oyi77]

Fixed — took your option 1: the interval gate now compares against the injected now instead of the wall clock (8c1fd1ce3, single-line change):

if (lastCheckMs > 0 && new Date(now).getTime() - lastCheckMs < intervalMin * 60 * 1000) return true;

Production semantics are unchanged — the sweep caller (tokenHealthCheck.ts:635) already passes a fresh new Date().toISOString() as now — but checkWebCookieConnectionIfNeeded is now fully deterministic under injected time, which is the right shape for a function that already takes now for stamping. (The committed diff also carries a few prettier line-wraps from the repo's pre-commit hook on pre-existing lines in this file — no behavior change.)

Receipts on 8c1fd1ce3:

• tests/unit/token-health-check-webcookie.test.ts: 9/9 pass, including honors the interval gate — recently checked rows are skipped silently. Determinism proof is inherent: that test's fixed NOW (2026-08-25T12:00Z) is >30h from real wall clock at run time, and the gate now trips correctly regardless.
• Sibling regressions: token-health-check-kimi.test.ts + token-health-check-sweep.test.ts → 7/7 pass.
• ESLint clean on the touched file; full-project tsc --noEmit produces zero diagnostics referencing tokenHealthCheckWebCookie.ts (the advisory Build check's error mass is pre-existing and unrelated).

Ready for re-review.

[oyi77]

Follow-up covering the repo's PR gates (copilot-instructions.md):

Repro test — your reported defect was encoded as a test (the failing honors the interval gate case), and the fix makes it pass deterministically. Added its complement in 4cf955ce8: stale rows are re-probed once the interval has elapsed (checked 61 min ago vs 60-min interval → probed exactly once, re-stamped) so both boundaries of the now-deterministic gate are locked.

Coverage gate (npm run test:coverage, full suite, 34,377 tests) — --check-coverage thresholds all pass globally:

Metric	Result	Floor
Statements	76.18%	60%
Branches	79.09%	60%
Functions	71.03%	60%
Lines	76.18%	60%

Touched leaf module (src/lib/tokenHealthCheckWebCookie.ts, isolated c8 over its suite): statements 100%, functions 100%, lines 100%, branches 82.75%.

The npm script exits 1 solely because of 28 suite failures that pre-date this branch's content (identical count across two independent full runs, before and after the new test; zero involve tokenHealthCheckWebCookie or the sweep wiring — those pass 10/10 and kimi+sweep 7/7). Same inherited-tip-drift class triaged in my earlier comment. Happy to produce a named-failure ledger if useful, but it needs another ~35-min instrumented run, so flagging rather than assuming you want it.

Branch tip: 4cf955ce8 (fix 8c1fd1ce3 + test 4cf955ce8).