feat(gateway): add gateway.persist_model_override flag (opt-out for sticky session /model overrides)

gateway/config.py

@@ -851,6 +851,22 @@ class GatewayConfig:
     # tooling and downgrade safety; set gateway.write_sessions_json: false in
     # config.yaml to stop producing the file.
     write_sessions_json: bool = True
+
+    # Whether an in-chat /model switch is persisted per-session and survives
+    # a gateway restart. Default True preserves existing behavior: /model
+    # writes {model, provider, base_url} to the session store, and the
+    # override is rehydrated on the next restart, permanently outranking
+    # config.yaml's model.default/model.provider for that session until
+    # cleared (e.g. by /new or another /model call).
+    #
+    # Set gateway.persist_model_override: false for the opposite contract:
+    # /model still switches the model for the remainder of the current
+    # process lifetime, but the switch is never written to disk and never
+    # rehydrated after a restart. Sessions always fall back to
+    # model.default/model.provider on the next gateway boot, so operators
+    # who manage models exclusively via config.yaml / `hermes model` (SSH)
+    # never get silently pinned to a stale in-chat override again.
+    persist_model_override: bool = True
 
     # Delivery settings
     always_log_local: bool = True  # Always save cron outputs to local files
@@ -1007,6 +1023,7 @@ def to_dict(self) -> Dict[str, Any]:
             "quick_commands": self.quick_commands,
             "sessions_dir": str(self.sessions_dir),
             "write_sessions_json": self.write_sessions_json,
+            "persist_model_override": self.persist_model_override,
             "always_log_local": self.always_log_local,
             "filter_silence_narration": self.filter_silence_narration,
             "stt_enabled": self.stt_enabled,
@@ -1137,6 +1154,7 @@ def from_dict(cls, data: Dict[str, Any]) -> "GatewayConfig":
             quick_commands=quick_commands,
             sessions_dir=sessions_dir,
             write_sessions_json=_coerce_bool(data.get("write_sessions_json"), True),
+            persist_model_override=_coerce_bool(data.get("persist_model_override"), True),
             always_log_local=_coerce_bool(data.get("always_log_local"), True),
             filter_silence_narration=_coerce_bool(
                 data.get("filter_silence_narration"), True
@@ -1336,6 +1354,12 @@ def load_gateway_config() -> GatewayConfig:
             elif isinstance(gateway_section, dict) and "write_sessions_json" in gateway_section:
                 gw_data["write_sessions_json"] = gateway_section["write_sessions_json"]
 
+            # persist_model_override: same top-level vs nested precedence.
+            if "persist_model_override" in yaml_cfg:
+                gw_data["persist_model_override"] = yaml_cfg["persist_model_override"]
+            elif isinstance(gateway_section, dict) and "persist_model_override" in gateway_section:
+                gw_data["persist_model_override"] = gateway_section["persist_model_override"]
+
             if "filter_silence_narration" in yaml_cfg:
                 gw_data["filter_silence_narration"] = yaml_cfg[
                     "filter_silence_narration"

gateway/run.py

@@ -17482,6 +17482,11 @@ def _rehydrate_session_model_override(self, session_key: str) -> None:
         store = getattr(self, "session_store", None)
         if store is None:
             return
+        # When the operator opted out of override persistence, never
+        # rehydrate a persisted override into the in-memory map — sessions
+        # must always fall back to config.yaml's model.default/provider.
+        if not getattr(store, "_persist_model_override", True):
+            return
         try:
             persisted = store.get_model_override(session_key)
         except Exception:

gateway/session.py

@@ -1050,6 +1050,14 @@ def __init__(self, sessions_dir: Path, config: GatewayConfig,
         self._write_sessions_json = bool(
             getattr(config, "write_sessions_json", True)
         )
+        # Whether in-chat /model overrides are persisted per-session and
+        # rehydrated on the next gateway restart. Default True preserves
+        # existing behavior. Disable via gateway.persist_model_override so
+        # operators who manage models exclusively via config.yaml / SSH are
+        # never silently pinned to a stale in-chat override.
+        self._persist_model_override = bool(
+            getattr(config, "persist_model_override", True)
+        )
 
         # Initialize SQLite session database
         self._db = None
@@ -2159,12 +2167,26 @@ def set_model_override(
         are re-resolved at rehydration time via the normal runtime provider
         resolution.  Pass ``None`` (or a dict with no persistable values)
         to clear the persisted override, e.g. on /new.
+
+        No-op on the persistence side when
+        ``gateway.persist_model_override`` is false: the in-memory
+        override still applies for the current process lifetime (set
+        directly on ``_session_model_overrides`` by the caller), but it
+        is never written to the session store and therefore never
+        rehydrated after a restart. Clearing (None) is always honored so
+        existing persisted overrides can still be wiped even after the
+        flag is turned off.
         """
         with self._lock:
             self._ensure_loaded_locked()
             entry = self._entries.get(session_key)
             if entry is None:
                 return
+            if override is not None and not self._persist_model_override:
+                # Skip persistence (non-clearing write) when the operator
+                # opted out of override persistence. The in-memory map is
+                # updated by the caller; nothing to persist here.
+                return
             cleaned = sanitize_model_override(override)
             if entry.model_override == cleaned:
                 return

hermes_cli/config.py

@@ -3024,6 +3024,15 @@ def _ensure_hermes_home_managed(home: Path):
         # producing ~/.hermes/sessions/sessions.json entirely.
         "write_sessions_json": True,
 
+        # Whether an in-chat /model switch is persisted per-session and
+        # survives a gateway restart. Default True preserves existing
+        # behavior: the override outranks config.yaml's model.default until
+        # cleared (/new, another /model). Set to false so /model only
+        # applies for the current process lifetime — operators who manage
+        # models via config.yaml / `hermes model` (SSH) never get silently
+        # pinned to a stale in-chat override after a restart.
+        "persist_model_override": True,
+
         # Scale-to-zero idle detection (Phase 0). The gateway watches for idle
         # and, when an instance is opted in via the NAS "Labs" toggle (carried as
         # the HERMES_SCALE_TO_ZERO env stamp) AND messaging is relay-only/absent

tests/gateway/test_session_model_override_persist_flag.py

@@ -0,0 +1,216 @@
+"""gateway.persist_model_override: false makes /model session-only.
+
+When ``gateway.persist_model_override`` is false, an in-chat /model switch
+must still take effect for the current process lifetime (the in-memory
+``_session_model_overrides`` map is updated by the caller), but the override
+is never written to the session store and therefore never rehydrated after
+a restart. This lets operators who manage models exclusively via config.yaml
+/ `hermes model` (SSH) avoid being silently pinned to a stale in-chat
+override.
+
+Covers:
+  - set_model_override(non-None) is a no-op on disk when the flag is off
+  - set_model_override(None) (clearing) still works even with the flag off,
+    so an operator can wipe a previously-persisted override after flipping
+    the flag
+  - the runner rehydrate path skips rehydration when the store has the flag
+    off, even if a persisted override exists on disk (from before the flag
+    was flipped)
+  - default behavior (flag True) is unchanged by these tests
+"""
+from unittest.mock import patch
+
+import pytest
+
+from gateway.config import GatewayConfig, Platform
+from gateway.session import SessionEntry, SessionSource, SessionStore
+
+OVERRIDE = {
+    "model": "gpt-5o",
+    "provider": "openai",
+    "api_key": "«redacted:sk-…»",
+    "base_url": "https://api.openai.example/v1",
+    "api_mode": "responses",
+}
+
+
+def _make_source() -> SessionSource:
+    return SessionSource(
+        platform=Platform.TELEGRAM,
+        user_id="u1",
+        chat_id="c1",
+        user_name="tester",
+        chat_type="dm",
+    )
+
+
+def _no_persist_config() -> GatewayConfig:
+    cfg = GatewayConfig()
+    cfg.persist_model_override = False
+    return cfg
+
+
+@pytest.fixture
+def store_factory(tmp_path, monkeypatch):
+    """Build SessionStores over a shared sessions dir, without SQLite."""
+
+    def _raise():
+        raise RuntimeError("SQLite disabled in test")
+
+    import hermes_state
+
+    monkeypatch.setattr(hermes_state, "SessionDB", _raise)
+
+    def _make(config: GatewayConfig = None) -> SessionStore:
+        store = SessionStore(
+            sessions_dir=tmp_path,
+            config=config if config is not None else GatewayConfig(),
+        )
+        assert store._db is None
+        return store
+
+    return _make
+
+
+def test_flag_off_set_override_is_not_persisted(store_factory):
+    """With persist_model_override=False, set_model_override(non-None) is
+    skipped on the persistence side — get_model_override returns None."""
+    store = store_factory(config=_no_persist_config())
+    entry = store.get_or_create_session(_make_source())
+    session_key = entry.session_key
+
+    store.set_model_override(session_key, OVERRIDE)
+
+    assert store.get_model_override(session_key) is None
+
+
+def test_flag_off_override_does_not_survive_restart(store_factory):
+    """A second store instance (simulated restart) with the flag off must
+    not see the override that a flag-off store 'set' earlier."""
+    store = store_factory(config=_no_persist_config())
+    entry = store.get_or_create_session(_make_source())
+    session_key = entry.session_key
+    store.set_model_override(session_key, OVERRIDE)
+
+    store2 = store_factory(config=_no_persist_config())
+    assert store2.get_model_override(session_key) is None
+
+
+def test_flag_off_clear_still_works_to_wipe_prior_persisted(store_factory):
+    """An operator may flip the flag off and then clear a pre-existing
+    persisted override. set_model_override(None) must still write through
+    even when persist_model_override is False."""
+    # First: persist an override with the flag ON (default).
+    store_persist = store_factory(config=GatewayConfig())
+    entry = store_persist.get_or_create_session(_make_source())
+    session_key = entry.session_key
+    store_persist.set_model_override(session_key, OVERRIDE)
+    assert store_persist.get_model_override(session_key) is not None
+
+    # Now flip the flag off on a fresh store and clear the override.
+    store_clear = store_factory(config=_no_persist_config())
+    store_clear.set_model_override(session_key, None)
+
+    # A fresh store with the flag off must see nothing.
+    store_check = store_factory(config=_no_persist_config())
+    assert store_check.get_model_override(session_key) is None
+
+
+def test_flag_off_runner_does_not_rehydrate_persisted_override(store_factory):
+    """Even if an override was persisted to disk before the flag was flipped
+    off, the runner rehydrate path must skip it when the store has the flag
+    off — sessions fall back to config.yaml's model.default."""
+    # Persist with flag ON so something is on disk.
+    store_persist = store_factory(config=GatewayConfig())
+    entry = store_persist.get_or_create_session(_make_source())
+    session_key = entry.session_key
+    store_persist.set_model_override(session_key, OVERRIDE)
+
+    # Fresh store with flag OFF, then a runner with an empty in-memory map.
+    from gateway.run import GatewayRunner
+
+    store = store_factory(config=_no_persist_config())
+    runner = object.__new__(GatewayRunner)
+    runner._session_model_overrides = {}
+    runner.session_store = store
+
+    with patch(
+        "gateway.run._resolve_runtime_agent_kwargs_for_provider",
+        return_value={
+            "api_key": "«redacted:sk-…»",
+            "api_mode": "responses",
+            "base_url": "https://api.openai.example/v1",
+            "provider": "openai",
+        },
+    ):
+        runner._rehydrate_session_model_override(session_key)
+
+    # Nothing rehydrated — sessions will use config defaults.
+    assert runner._session_model_overrides == {}
+
+
+def test_flag_on_default_still_persists_and_rehydrates(store_factory):
+    """Sanity: default behavior (flag True) is unchanged by this feature —
+    the override persists and rehydrates as before."""
+    store = store_factory(config=GatewayConfig())
+    entry = store.get_or_create_session(_make_source())
+    session_key = entry.session_key
+    store.set_model_override(session_key, OVERRIDE)
+
+    store2 = store_factory(config=GatewayConfig())
+    persisted = store2.get_model_override(session_key)
+    assert persisted == {
+        "model": "gpt-5o",
+        "provider": "openai",
+        "base_url": "https://api.openai.example/v1",
+    }
+
+
+def test_flag_off_does_not_block_live_in_memory_override(store_factory):
+    """The feature only gates persistence + rehydration. The in-memory
+    _session_model_overrides map is owned by the caller (slash command path),
+    so a live override still applies during the current process lifetime
+    even when persistence is off. This test documents that contract by
+    showing that a manually-set in-memory override is returned by
+    _apply_session_model_override regardless of the flag."""
+    from gateway.run import GatewayRunner
+
+    store = store_factory(config=_no_persist_config())
+    entry = store.get_or_create_session(_make_source())
+    session_key = entry.session_key
+
+    runner = object.__new__(GatewayRunner)
+    runner._session_model_overrides = {}
+    runner.session_store = store
+
+    # Caller simulates the slash-command path: set in-memory directly.
+    runner._session_model_overrides[session_key] = {
+        "model": "live-model",
+        "provider": "openai",
+        "api_key": "«redacted:sk-…»",
+        "base_url": "https://api.openai.example/v1",
+        "api_mode": "responses",
+    }
+
+    base_model = "config-default-model"
+    base_kwargs = {"provider": "config-default-provider"}
+    applied_model, applied_kwargs = runner._apply_session_model_override(
+        session_key, base_model, base_kwargs
+    )
+    assert applied_model == "live-model"
+    assert applied_kwargs["provider"] == "openai"
+
+
+def test_gateway_config_round_trips_flag():
+    """to_dict / from_dict must preserve persist_model_override."""
+    cfg = GatewayConfig()
+    cfg.persist_model_override = False
+    as_dict = cfg.to_dict()
+    assert as_dict["persist_model_override"] is False
+
+    restored = GatewayConfig.from_dict(as_dict)
+    assert restored.persist_model_override is False
+
+    # Default when key absent.
+    default_restored = GatewayConfig.from_dict({})
+    assert default_restored.persist_model_override is True