feat(webui): allow per-instance settings file

api/config.py

@@ -83,10 +83,19 @@ STATE_DIR = (
     .resolve()
 )
 
+
+def _resolve_settings_file(state_dir: Path) -> Path:
+    """Resolve an optional per-instance settings file without splitting session state."""
+    configured = os.getenv("HERMES_WEBUI_SETTINGS_FILE", "").strip()
+    if configured:
+        return Path(configured).expanduser().resolve()
+    return state_dir / "settings.json"
+
+
 SESSION_DIR = STATE_DIR / "sessions"
 WORKSPACES_FILE = STATE_DIR / "workspaces.json"
 SESSION_INDEX_FILE = SESSION_DIR / "_index.json"
-SETTINGS_FILE = STATE_DIR / "settings.json"
+SETTINGS_FILE = _resolve_settings_file(STATE_DIR)
 LAST_WORKSPACE_FILE = STATE_DIR / "last_workspace.txt"
 PROJECTS_FILE = STATE_DIR / "projects.json"
 

tests/test_configurable_pinned_sessions_limit.py

@@ -5,6 +5,7 @@ import pathlib
 import urllib.error
 import urllib.request
 
+from api import config as webui_config
 from tests._pytest_port import BASE
 
 ROOT = pathlib.Path(__file__).resolve().parent.parent
@@ -42,6 +43,16 @@ def make_session(created, title):
     return sid
 
 
+def test_settings_file_path_can_be_scoped_per_instance(tmp_path, monkeypatch):
+    default_state_dir = tmp_path / "default-state"
+    monkeypatch.delenv("HERMES_WEBUI_SETTINGS_FILE", raising=False)
+    assert webui_config._resolve_settings_file(default_state_dir) == default_state_dir / "settings.json"
+
+    staging_settings = tmp_path / "staging" / "settings.json"
+    monkeypatch.setenv("HERMES_WEBUI_SETTINGS_FILE", str(staging_settings))
+    assert webui_config._resolve_settings_file(default_state_dir) == staging_settings.resolve()
+
+
 def test_pin_limit_setting_is_exposed_and_wired_through_ui():
     assert '"pinned_sessions_limit": 3' in CONFIG_PY
     assert '"pinned_sessions_limit": (1, 99)' in CONFIG_PY