fix(model): refresh cached model catalogs

[helix4u]

What does this PR do?

Fixes stale hosted model catalogs after hermes update and adds an explicit hermes model --refresh recovery path.

The remote model catalog is cached under the resolved Hermes home, but update previously refreshed the repo without invalidating that user-local cache. Users could update Hermes and still see an old OpenRouter/Nous curated model list until the 24 hour TTL expired. This change makes update semantics match user expectation: after update, the next model picker sees fresh remote catalog data or falls back to the newly bundled snapshot.

The implementation uses Hermes path resolvers instead of hardcoded Windows or Unix home paths, so AppData installs, custom HERMES_HOME, Docker, and profile homes follow the same runtime lookup.

Related Issue

N/A

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• hermes_cli/main.py: add hermes model --refresh, clear the model catalog cache before opening the picker, and invalidate model catalog caches during hermes update, including already-up-to-date and ZIP update paths.
• hermes_cli/model_catalog.py: add force-refresh plumbing for provider accessors, clear both in-process and disk cache through the resolved Hermes home, and avoid reusing stale disk cache on explicit refresh failure.
• hermes_cli/models.py: thread force_refresh into OpenRouter and Nous hosted catalog lookups.
• tests/hermes_cli/test_model_catalog.py: cover stale-cache fallback, force-refresh behavior, resolved-home cache deletion, and provider accessor refresh propagation.
• tests/hermes_cli/test_models.py: cover OpenRouter and Nous force-refresh propagation into hosted catalog lookups.
• tests/hermes_cli/test_update_check.py: cover update invalidation of model catalog caches across default and profile homes.

How to Test

1. Run python -m pytest -n 0 tests/hermes_cli/test_model_catalog.py tests/hermes_cli/test_models.py tests/hermes_cli/test_update_check.py -q.
2. Run python -m py_compile hermes_cli/main.py hermes_cli/model_catalog.py hermes_cli/models.py.
3. Run python -m hermes_cli.main model --help and confirm --refresh is listed.
4. Run scripts/run_tests.sh for the full non-integration suite.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate. Checked [codex] Use live model catalogs for real provider picker #19005 and feat(nous): drive model picker from Portal recommended-models endpoint #14936; neither covers update-time invalidation of cache/model_catalog.json.
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: WSL/Linux

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

N/A

Screenshots / Logs

Targeted validation before opening the draft:

• python -m pytest -n 0 tests/hermes_cli/test_model_catalog.py tests/hermes_cli/test_models.py tests/hermes_cli/test_update_check.py -q
  • Result: 94 passed in 3.21s
• python -m py_compile hermes_cli/main.py hermes_cli/model_catalog.py hermes_cli/models.py
  • Result: passed
• python -m hermes_cli.main model --help
  • Result: --refresh is listed

Full-suite validation after opening the draft:

• scripts/run_tests.sh
  • Result: failed locally with 63 failed, 22124 passed, 59 skipped, 236 warnings, 19 errors in 622.55s (0:10:22).
  • The run used the project runner's pinned 4 workers.
  • HERMES_HOME was empty before the run and empty after the run.
  • The failure set is broad and includes existing environment/dependency/process-test failures such as missing ruamel, missing psutil, Dingtalk async mock comparison failures, browser supervisor runtime errors, and process-timeout/zombie cleanup tests. The targeted tests for this PR passed.

[ether-btc]

Review: Solid cache invalidation fix with good UX

The hermes model --refresh flag and the clear_disk_cache() function are the right solution to the stale catalog problem. Clearing cache/model_catalog.json during hermes update is exactly what users expect semantically.

Implementation quality

• Uses get_hermes_home() via _cache_path() — correctly handles Windows AppData, custom HERMES_HOME, Docker, and profile homes
• reset_cache() + _cache_path().unlink(missing_ok=True) is the right idempotent pattern
• force_refresh behavior change (skip stale disk cache on explicit refresh) is correct — explicit refresh should not silently fall back to stale data

Non-blocking notes

• Test coverage is comprehensive: test_force_refresh_failure_ignores_stale_disk_cache, test_clear_disk_cache_uses_resolved_hermes_home, etc.
• The combined test failure (63 failed, 22124 passed) needs triage — ruamel and psutil errors are likely environmental, not from this PR
• Full suite run against main branch should confirm these failures are pre-existing

[pefontana]

main now reseeds stale catalogs on update (seed_cache_from_checkout) and already ships hermes model --refresh, so this is covered.