perf(cli): cut hermes startup 63% — flip head-to-head vs codex (#31968)

* perf(bitwarden): persist secret-fetch cache across CLI invocations

Every `hermes` invocation paid a ~380ms tax for `bws secret list` to
Bitwarden Secrets Manager because the existing cache was in-process only.
Back-to-back `hermes chat -q`, gateway-spawned agents, and cron-launched
runs all re-fetched.

Adds a disk-persisted L2 cache at `<hermes_home>/cache/bws_cache.json`
(mode 0600, never contains the access token — only the SHA-256
fingerprint prefix). Same TTL as the in-process cache. Read on miss,
write on bws success, ignored on key mismatch / corruption / expiry.

Measured on a startup profile:
  load_hermes_dotenv() cold: 372ms → warm (disk cache hit): 20ms

End-to-end `hermes --version` cold→warm: 666ms → ~295ms.

In a hermes-vs-codex benchmark across 11 single- and multi-turn tasks
(framework overhead = wall − llm − tool_exec, median over 3 trials):

  cohort               before    after    saved
  single-turn (median)  2.96s    2.31s   -0.65s
  multi-turn  (5-turn)  9.40s    8.95s   -0.45s (≈0.3s/turn)

Hermes now wins head-to-head on 6/11 tasks vs codex (was 4/11 before).
The remaining ~0.6s single-turn delta is mostly Python's own import
cost in hermes_cli.main, which is a separate optimization.

* perf(cli): lazy-load model catalog + dedupe config.yaml reads at startup

Two import-time wins on top of the bws disk-cache fix:

1. Lazy-load `hermes_cli.models._PROVIDER_MODELS` via PEP 562
   module-level `__getattr__`. The catalog is ~55ms of work that was
   eagerly imported on every CLI invocation (line 4557 `if not
   _is_termux_startup_environment(): from hermes_cli.models import
   _PROVIDER_MODELS`). Audit showed every internal call site already
   does its own function-local import; only test code reads
   `hermes_cli.main._PROVIDER_MODELS` as a module attribute, and
   __getattr__ keeps that working transparently. First access triggers
   the import once and caches the result on the module via
   `globals()[name] = ...`, so subsequent reads are dict lookups.

2. Dedupe the double config.yaml read in the top-of-module bootstrap.
   Previously: one raw yaml.safe_load for the `security.redact_secrets`
   bridge, then a separate full `load_config()` (with deep-merge) for
   `network.force_ipv4`. Both keys come from the same file. Merged
   into one raw yaml load.

Combined with the bws cache fix in the previous commit:

  hermes --version wall time:
    original (cold):           666 ms
    after bws fix (warm):      295 ms
    after lazy-load + dedupe:  228 ms   (-67 ms additional, -66% from original)

Tests:
  - tests/hermes_cli/test_api_key_providers.py: 173/173 pass
    (lazy __getattr__ correctly handles
     `from hermes_cli.main import _PROVIDER_MODELS`)
  - tests/test_ipv4_preference.py + tests/hermes_cli/test_redact_config_bridge.py +
    tests/agent/test_redact.py: 93/93 pass (dedupe preserves both bridges)
  - tests/test_bitwarden_secrets.py + env_loader tests: 49/49 pass

agent/secret_sources/bitwarden.py

@@ -73,6 +73,102 @@ _BWS_RUN_TIMEOUT = 30
 _CacheKey = Tuple[str, str, str]  # (access_token_fingerprint, project_id, server_url)
 _CACHE: Dict[_CacheKey, "_CachedFetch"] = {}
 
+# Disk-persisted cache so back-to-back CLI invocations (e.g. `hermes chat -q ...`
+# called from scripts, cron, the gateway forking new agents) don't each pay the
+# ~380ms `bws secret list` tax. The in-process _CACHE above only saves repeated
+# fetches WITHIN one process; this saves repeated fetches ACROSS processes.
+#
+# Layout: one JSON object per cache key, written atomically with mode 0600 in
+# <hermes_home>/cache/bws_cache.json. The file holds only the secret VALUES,
+# never the access token. It's plaintext-equivalent to ~/.hermes/.env (which
+# we already accept) but kept out of the .env file so users editing it won't
+# accidentally commit BSM-sourced secrets.
+_DISK_CACHE_BASENAME = "bws_cache.json"
+
+
+def _disk_cache_path(home_path: Optional[Path] = None) -> Path:
+    """Return the disk cache path under hermes_home/cache/.
+
+    `home_path` is what `load_hermes_dotenv()` already resolved; falling back
+    to `$HERMES_HOME` / `~/.hermes` keeps direct callers working too.
+    """
+    if home_path is None:
+        home_path = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+    return home_path / "cache" / _DISK_CACHE_BASENAME
+
+
+def _cache_key_str(cache_key: _CacheKey) -> str:
+    """Serialize a cache key to a stable string for JSON storage."""
+    token_fp, project_id, server_url = cache_key
+    return f"{token_fp}|{project_id}|{server_url}"
+
+
+def _read_disk_cache(cache_key: _CacheKey, ttl_seconds: float,
+                     home_path: Optional[Path] = None) -> Optional["_CachedFetch"]:
+    """Return a cached entry from disk if fresh, else None.
+
+    Best-effort: any I/O or parse error returns None and we re-fetch.
+    """
+    if ttl_seconds <= 0:
+        return None
+    path = _disk_cache_path(home_path)
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            payload = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    if payload.get("key") != _cache_key_str(cache_key):
+        return None
+    secrets = payload.get("secrets")
+    fetched_at = payload.get("fetched_at")
+    if not isinstance(secrets, dict) or not isinstance(fetched_at, (int, float)):
+        return None
+    # Coerce all values to strings — JSON allows numbers but env vars need strings
+    typed_secrets: Dict[str, str] = {
+        k: v for k, v in secrets.items() if isinstance(k, str) and isinstance(v, str)
+    }
+    entry = _CachedFetch(secrets=typed_secrets, fetched_at=float(fetched_at))
+    if not entry.is_fresh(ttl_seconds):
+        return None
+    return entry
+
+
+def _write_disk_cache(cache_key: _CacheKey, entry: "_CachedFetch",
+                      home_path: Optional[Path] = None) -> None:
+    """Persist a cache entry to disk atomically with mode 0600.
+
+    Best-effort: any I/O error is swallowed (the next invocation will just
+    re-fetch). We never want disk cache failures to break startup.
+    """
+    path = _disk_cache_path(home_path)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "key": _cache_key_str(cache_key),
+            "secrets": entry.secrets,
+            "fetched_at": entry.fetched_at,
+        }
+        # Write to a temp file in the same directory and atomic-rename.
+        # tempfile honors os.umask, so we explicitly chmod 0600 before rename.
+        fd, tmp = tempfile.mkstemp(
+            prefix=".bws_cache_", suffix=".tmp", dir=str(path.parent)
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(payload, f)
+            os.chmod(tmp, 0o600)
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except OSError:
+        pass  # best-effort — disk cache miss on next invocation is fine
+
 
 @dataclass
 class _CachedFetch:
@@ -318,6 +414,7 @@ def fetch_bitwarden_secrets(
     cache_ttl_seconds: float = 300,
     use_cache: bool = True,
     server_url: str = "",
+    home_path: Optional[Path] = None,
 ) -> Tuple[Dict[str, str], List[str]]:
     """Pull the secrets for ``project_id`` from Bitwarden Secrets Manager.
 
@@ -329,6 +426,13 @@ def fetch_bitwarden_secrets(
     (``https://vault.bitwarden.com``, US Cloud).  This is plumbed into
     the subprocess as ``BWS_SERVER_URL``.
 
+    Caching is a two-layer LRU: an in-process dict (for hot-reload paths
+    inside one process) and a disk-persisted JSON file under
+    ``<hermes_home>/cache/bws_cache.json`` (for back-to-back CLI invocations).
+    Both share the same TTL.  Pass ``home_path`` so disk cache lookups find
+    the right directory in tests / non-standard installs; otherwise we fall
+    back to ``$HERMES_HOME`` / ``~/.hermes``.
+
     Raises :class:`RuntimeError` for fatal conditions (missing binary,
     auth failure, unparseable output).  Callers in the env_loader path
     catch this and emit a single warning; callers in the user-facing
@@ -344,6 +448,13 @@ def fetch_bitwarden_secrets(
         cached = _CACHE.get(cache_key)
         if cached and cached.is_fresh(cache_ttl_seconds):
             return cached.secrets, []
+        # L2: disk cache. ~5ms on cache hit vs ~380ms for `bws secret list`.
+        disk_cached = _read_disk_cache(cache_key, cache_ttl_seconds, home_path)
+        if disk_cached is not None:
+            # Promote into in-process cache so subsequent fetches in the
+            # same process skip the disk read too.
+            _CACHE[cache_key] = disk_cached
+            return disk_cached.secrets, []
 
     bws = binary or find_bws(install_if_missing=True)
     if bws is None:
@@ -355,7 +466,10 @@ def fetch_bitwarden_secrets(
         )
 
     secrets, warnings = _run_bws_list(bws, access_token, project_id, server_url)
-    _CACHE[cache_key] = _CachedFetch(secrets=secrets, fetched_at=time.time())
+    entry = _CachedFetch(secrets=secrets, fetched_at=time.time())
+    _CACHE[cache_key] = entry
+    if use_cache:
+        _write_disk_cache(cache_key, entry, home_path)
     return secrets, warnings
 
 
@@ -452,6 +566,7 @@ def apply_bitwarden_secrets(
     cache_ttl_seconds: float = 300,
     auto_install: bool = True,
     server_url: str = "",
+    home_path: Optional[Path] = None,
 ) -> FetchResult:
     """Pull secrets from BSM and set them on ``os.environ``.
 
@@ -502,6 +617,7 @@ def apply_bitwarden_secrets(
             binary=binary,
             cache_ttl_seconds=cache_ttl_seconds,
             server_url=server_url,
+            home_path=home_path,
         )
     except RuntimeError as exc:
         result.error = str(exc)
@@ -531,5 +647,15 @@ def apply_bitwarden_secrets(
 # ---------------------------------------------------------------------------
 
 
-def _reset_cache_for_tests() -> None:
+def _reset_cache_for_tests(home_path: Optional[Path] = None) -> None:
+    """Clear in-process AND disk caches.
+
+    Tests can pass ``home_path`` to scope the disk cleanup to a tmpdir.
+    Without it we fall back to the same default resolution as the cache
+    writer itself.
+    """
     _CACHE.clear()
+    try:
+        _disk_cache_path(home_path).unlink()
+    except (FileNotFoundError, OSError):
+        pass