fix: invalidate model cache on auth-store drift

[Michaelyklam]

Thinking Path

• /api/models is the source of truth for the WebUI composer model picker and configured PRIMARY badges.
• The existing cache knew about WebUI version/schema drift and config mtime changes, but not external auth.json changes made by terminal hermes setup.
• That left both the in-process cache and STATE_DIR/models_cache.json able to serve a previous active provider for up to the 24h TTL.
• The fix is to stamp and validate the cache against non-secret source fingerprints for both config.yaml and auth.json, then rebuild when either changes outside WebUI.

What Changed

• Added a non-secret /api/models cache source fingerprint covering config.yaml and auth.json path, mtime, and size.
• Stamped the disk cache with _source_fingerprint and bumped the disk cache schema to reject older cache files cleanly.
• Tracked the same source fingerprint for the in-memory TTL cache so external auth-store writes invalidate without requiring a WebUI-originated provider edit.
• Reused a shared auth-store path helper in the model discovery cold path.
• Added regression coverage for:
  • stale in-memory cache bypass after external auth.json active-provider change;
  • stale disk cache bypass after external auth.json active-provider change;
  • fresh disk cache reuse when config/auth sources are unchanged.

Why It Matters

Users who switch primary providers from the Hermes CLI should see the WebUI picker follow that source of truth after refresh, without clearing browser state or waiting for cache TTL expiry. This keeps the WebUI in sync with terminal hermes setup and prevents stale PRIMARY badges such as OpenRouter/MiniMax lingering after switching to OpenCode Go.

Verification

• python -m pytest tests/test_issue1699_model_cache_source_fingerprint.py -q — 3 passed (RED first: two stale-cache tests failed before the fix).
• /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_issue1699_model_cache_source_fingerprint.py tests/test_issue1633_models_cache_version_stamp.py -q — 22 passed after the CI-portability/test-state follow-ups.
• HERMES_WEBUI_TEST_STATE_DIR=/tmp/hermes-webui-kanban/t_0cdf52fe/full-suite-state-1997a48 HERMES_WEBUI_TEST_PORT=29583 env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/ -q — 4480 passed, 2 skipped, 1 xfailed, 2 xpassed, 1 warning, 8 subtests passed in 435.69s.
• GitHub Actions on head a358400 — pending immediately after the final test-state follow-up; previous head 94d0b78 was green on Python 3.11, 3.12, and 3.13.
• git diff --check — passed.
• Browser QA on an isolated temp WebUI server: started with auth.json active provider openrouter, loaded /api/models, edited auth.json externally to opencode-go, reloaded the same browser tab without clearing cookies/localStorage, and confirmed /api/models/picker data reported active_provider: opencode-go, PRIMARY (OPENCODE-GO), provider group opencode-go, and no stale OpenRouter group.

Evidence / UI media

Raw media verified HTTP 200 (150269 bytes).

Risks / Follow-ups

• The source fingerprint intentionally uses only file path, mtime, and size — never auth/config contents — so it is safe for cache metadata but depends on normal filesystem mtime updates for external writes.
• The disk cache schema bump forces one rebuild after upgrade, which is expected for the new required _source_fingerprint metadata.

Model Used

OpenAI Codex gpt-5.5 via Hermes, with terminal/file/browser tooling.

Closes #1699

[nesquena-hermes]

Closed by the v0.51.4 release in PR #1707 (merged at 4daa238, deployed to production).

Live on production: https://github.com/nesquena/hermes-webui/releases/tag/v0.51.4

🚀