fix(config): warn on STATE_DIR divergence at startup when session store is empty (#3915)

api/config.py

@@ -574,6 +574,65 @@ def _discover_default_workspace() -> Path:
 
 
 # ── Startup diagnostics ───────────────────────────────────────────────────────
+def _warn_state_dir_divergence(warn_prefix: str) -> None:
+    """Check if SESSION_DIR is empty but a sibling state directory has session data.
+
+    If the session store looks empty (no *.json files besides _index.json in SESSION_DIR,
+    or SESSION_INDEX_FILE is absent/empty/contains only {}|[]|null), scan STATE_DIR.parent
+    for sibling directories with a sessions/ child that has .json files.
+
+    Prints a diagnostic warning if a divergence is detected, helping users identify when
+    they may have switched launch methods and the HERMES_WEBUI_STATE_DIR env var differs.
+    """
+    try:
+        # Check if session store is empty
+        session_dir_empty = False
+
+        # Check for .json files in SESSION_DIR (excluding _index.json)
+        if SESSION_DIR.exists():
+            json_files = [f for f in SESSION_DIR.glob("*.json") if f.name != "_index.json"]
+            session_dir_empty = len(json_files) == 0
+        else:
+            session_dir_empty = True
+
+        # Check if SESSION_INDEX_FILE is absent, empty, or contains only {}|[]|null
+        index_file_empty = True
+        if SESSION_INDEX_FILE.exists():
+            try:
+                with open(SESSION_INDEX_FILE, "r") as f:
+                    content = f.read().strip()
+                    if content and content not in ("{}", "[]", "null"):
+                        index_file_empty = False
+            except Exception:
+                pass
+
+        # If session store looks empty, scan for siblings with sessions
+        if session_dir_empty and index_file_empty:
+            state_parent = STATE_DIR.parent
+            if state_parent.exists():
+                for sibling in state_parent.iterdir():
+                    if not sibling.is_dir() or sibling == STATE_DIR:
+                        continue
+                    sibling_sessions = sibling / "sessions"
+                    if sibling_sessions.exists():
+                        json_files = [f for f in sibling_sessions.glob("*.json") if f.name != "_index.json"]
+                        if json_files:
+                            # Found a sibling with session data
+                            print(
+                                f"{warn_prefix}  STATE_DIR is empty but a sibling state directory has session data.\n"
+                                f"        Current : {STATE_DIR}\n"
+                                f"        Sibling : {sibling}\n"
+                                f"        If you switched launch methods (bootstrap.py / ctl.sh / systemd),\n"
+                                f"        the active HERMES_WEBUI_STATE_DIR env var may differ from the\n"
+                                f"        previous run. Set it explicitly to restore access:\n"
+                                f"          export HERMES_WEBUI_STATE_DIR={sibling}",
+                                flush=True,
+                            )
+                            return
+    except Exception:
+        pass
+
+
 def print_startup_config() -> None:
     """Print detected configuration at startup so the user can verify what was found."""
     ok = "\033[32m[ok]\033[0m"
@@ -595,6 +654,11 @@ def print_startup_config() -> None:
     ]
     print("\n".join(lines), flush=True)
 
+    try:
+        _warn_state_dir_divergence(warn)
+    except Exception:
+        pass
+
     if not _HERMES_FOUND:
         print(
             f"{err}  Could not find the Hermes agent directory.\n"