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

[rodboev]

Thinking Path

• Confirmed that print_startup_config() already prints state dir : {STATE_DIR} at line 590 of api/config.py, so the path is visible � but there is no signal when it points to the wrong directory.
• The maintainer's diagnosis in WebUI projects vanish after restart — session store empty, projects recoverable from session data #3915 is correct: no data is lost; the server reads an empty sibling directory because HERMES_WEBUI_STATE_DIR was not preserved across restart methods.
• Adding a _warn_state_dir_divergence() helper that checks for empty SESSION_DIR + populated sibling gives users a clear actionable message without changing any data-access paths.

What Changed

• api/config.py: added _warn_state_dir_divergence() helper that scans siblings of STATE_DIR for session data when the active session store is empty; called from print_startup_config() wrapped in try/except so filesystem errors never block startup

Why It Matters

Users who accidentally start the server with a different STATE_DIR (common when switching between bootstrap.py, ./ctl.sh, and systemd) now see an immediate, actionable startup warning that names the likely correct directory, eliminating the "projects vanished" confusion.

Verification

$env:PYTHONUTF8 = '1'; $env:BROWSER = 'echo'
..\hermes-agent\venv\Scripts\python.exe -m pytest tests/test_config.py -v --timeout=60
..\hermes-agent\venv\Scripts\python.exe -m pytest tests/ -v --timeout=60

Risks / Follow-ups

• The sibling-scan heuristic only finds the first match; if multiple sibling state dirs exist it could name the wrong one (uncommon scenario)
• A follow-up could compare session counts across siblings and pick the most-populated one for a stronger hint

Model Used

Claude Opus 4.6 via Claude Code CLI

[greptile-apps]

Greptile Summary

Adds a _warn_state_dir_divergence() helper to api/config.py that fires at startup when the active session store is empty but a sibling state directory contains session files, giving users a clear actionable message when HERMES_WEBUI_STATE_DIR diverges across launch methods.

• _warn_state_dir_divergence() checks SESSION_DIR and SESSION_INDEX_FILE for emptiness, then scans STATE_DIR.parent siblings for a sessions/ subtree with non-index JSON files; prints a recovery hint naming the likely correct directory.
• The helper is called from print_startup_config() inside a try/except (in addition to its own internal guard), so filesystem errors can never block startup.
• A comprehensive 11-case test file covers detection, false-positive guards, and exception resilience.

Confidence Score: 5/5

Safe to merge — the change is purely additive diagnostic output with no data-access path changes, and all failure modes are silently swallowed.

The new code never mutates state, writes files, or alters any existing code path. The double try/except wrapping ensures filesystem errors cannot block startup. The only finding is the unquoted path in the suggested shell command, which is a display issue in a warning message and does not affect correctness.

No files require special attention.

Important Files Changed

Filename	Overview
api/config.py	Adds _warn_state_dir_divergence() helper that scans sibling directories for session data when the active session store is empty; called from print_startup_config() with double try/except safety. One minor issue: the suggested shell export command is unquoted.
tests/test_issue3915_state_dir_warning.py	New test suite with 11 cases covering the divergence warning: positive detection, false-positive guards (index file content, no siblings), exception handling (missing dir, PermissionError, glob errors). Coverage is thorough for the added helper.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[print_startup_config] --> B[_warn_state_dir_divergence]
    B --> C{SESSION_DIR exists?}
    C -- No --> D[session_dir_empty = True]
    C -- Yes --> E{Any *.json besides _index.json?}
    E -- Yes --> F[session_dir_empty = False]
    E -- No --> D
    D --> G{SESSION_INDEX_FILE exists?}
    F --> G
    G -- No --> H[index_file_empty = True]
    G -- Yes --> I{Content is empty or null or curly or array}
    I -- Yes --> H
    I -- No --> J[index_file_empty = False]
    H --> K{Both empty?}
    J --> L[No warning - return]
    K -- No --> L
    K -- Yes --> M[Iterate STATE_DIR.parent siblings]
    M --> N{Sibling has sessions JSON besides _index.json?}
    N -- No --> O[Next sibling]
    O --> N
    N -- Yes --> P[Print divergence warning with export suggestion]
    P --> Q[return]

Loading

_{Reviews (3): Last reviewed commit: "fix(config): filter _index.json from sib..." | Re-trigger Greptile}

[nesquena-hermes]

Absorbed and shipped in v0.51.352 (Release LP, deployed live) via the batched release #3948 — rebased onto fresh master with attribution, content verified, full-suite (8570) + Codex + Opus gated. Closes #3915.

Thanks @rodboev! 🙏