Skip to content

The agent that grows with you

fix: align FTS storage notice with collected layout

Yuan Lif364f07206f9
diff --git a/hermes_cli/doctor_state.py b/hermes_cli/doctor_state.py
index 5d8000888cb..c796add0c79 100644
--- a/hermes_cli/doctor_state.py
+++ b/hermes_cli/doctor_state.py
@@ -11,7 +11,6 @@ from hermes_cli.doctor_report import (
warn_on_error,
)
from hermes_cli.sizefmt import format_bytes as _human_bytes
-from hermes_state_common import FTS_STORAGE_VERSION
from hermes_state_holders import read_only_db_uri
@@ -94,13 +93,11 @@ def _render_state_db_stats(stats: dict, holders=None, host_note: str = "") -> li
"(stop the listed processes; the host gateway's own retry then rebuilds, or run "
"'hermes sessions optimize-storage' with every holder stopped)"))
# Oversized DB: suggest auto_prune, plus the offline optimize-storage pass when the FTS rebuild is
- # pending OR the DB predates the current trigram layout (fts_storage_version < FTS_STORAGE_VERSION).
+ # pending OR the stored FTS layout structurally needs upgrading (not just a lagging marker).
if logical is not None and logical > STATE_DB_SIZE_WARN_BYTES:
detail = "consider enabling sessions.auto_prune in config.yaml to bound growth"
- stale_trigram = (fts is not None and fts.get("messages_fts_trigram")
- and (stats.get("fts_storage_version") or 0) < FTS_STORAGE_VERSION)
structural_fts_upgrade = bool(stats.get("fts_storage_upgrade_needed"))
- if stats.get("fts_rebuild_pending") or stale_trigram or structural_fts_upgrade:
+ if stats.get("fts_rebuild_pending") or structural_fts_upgrade:
detail += "; run 'hermes sessions optimize-storage' offline (with the host gateway stopped) to compact FTS storage"
lines.append(("warn", f"state.db is large ({_human_bytes(logical)})", f"({detail})"))
# WAL runaway is deliberately NOT warned here: _state_db_wal already warns above 50 MB and offers --fix.
diff --git a/tests/hermes_cli/test_fts_optimize_notice.py b/tests/hermes_cli/test_fts_optimize_notice.py
index 4f64554a2b2..a8b8ea36c27 100644
--- a/tests/hermes_cli/test_fts_optimize_notice.py
+++ b/tests/hermes_cli/test_fts_optimize_notice.py
@@ -3,6 +3,8 @@
import sqlite3
from types import SimpleNamespace
+import pytest
+
def test_update_notice_offers_v1_trigram_tool_calls_rebuild(tmp_path, monkeypatch, capsys):
"""A deployed v1 trigram projection still receives the opt-in notice."""
@@ -52,14 +54,69 @@ def test_update_notice_offers_v1_trigram_tool_calls_rebuild(tmp_path, monkeypatc
conn.close()
-def test_doctor_notice_uses_structural_fts_upgrade_status():
- from hermes_cli.doctor_state import _render_state_db_stats
[email protected]("base_layout", ["absent", "legacy", "current"])
[email protected]("trigram_layout", ["absent", "legacy", "current"])
[email protected]("marker", [None, 1, 3])
[email protected]("large", [False, True])
+def test_doctor_collects_structural_fts_upgrade_status(
+ tmp_path, monkeypatch, base_layout, trigram_layout, marker, large,
+):
+ """Real read-only collection must ignore forged or lagging version markers."""
+ from hermes_cli import doctor_state
+ from hermes_state_dbfile import collect_state_db_stats
- rows = _render_state_db_stats({
- "logical_size_bytes": 2 * 1024 ** 3,
- "fts_tables": {"messages_fts_trigram": True},
- "fts_storage_version": 3,
- "fts_storage_upgrade_needed": True,
- })
+ db_path = tmp_path / "state.db"
+ with sqlite3.connect(db_path) as conn:
+ conn.executescript(
+ "CREATE TABLE state_meta (key TEXT PRIMARY KEY, value TEXT);"
+ "CREATE TABLE messages (content TEXT, tool_name TEXT, tool_calls TEXT);"
+ "CREATE TABLE sessions (id TEXT);"
+ )
+ if base_layout == "legacy":
+ conn.execute("CREATE VIRTUAL TABLE messages_fts USING fts5(content)")
+ elif base_layout == "current":
+ conn.execute(
+ "CREATE VIRTUAL TABLE messages_fts USING "
+ "fts5(content, tool_name, tool_calls, content='messages')"
+ )
+ if trigram_layout != "absent":
+ columns = "content, tool_name" + (", tool_calls" if trigram_layout == "legacy" else "")
+ conn.execute(f"CREATE VIRTUAL TABLE messages_fts_trigram USING fts5({columns}, tokenize='trigram')")
+ if marker is not None:
+ conn.execute("INSERT INTO state_meta VALUES ('fts_storage_version', ?)", (str(marker),))
+
+ before = db_path.read_bytes()
+ stats = collect_state_db_stats(db_path)
+ needed = base_layout == "legacy" or trigram_layout == "legacy"
+ assert stats["fts_storage_upgrade_needed"] is needed
+ assert stats["fts_storage_version"] == marker
+ assert stats["fts_rebuild_pending"] is False
+ assert stats["logical_size_bytes"] > 0
+ # Exercise the size gate without allocating a GiB database or forging collected stats.
+ monkeypatch.setattr(doctor_state, "STATE_DB_SIZE_WARN_BYTES", 0 if large else stats["logical_size_bytes"])
+ rows = doctor_state._render_state_db_stats(stats)
+ offered = any("hermes sessions optimize-storage" in detail for _, _, detail in rows)
+ assert offered is (large and needed)
+ assert db_path.read_bytes() == before
+
+
[email protected]("progress, pending", [(0, True), (10, False)])
+def test_doctor_collects_pending_rebuild_with_settled_layout(tmp_path, monkeypatch, progress, pending):
+ from hermes_cli import doctor_state
+ from hermes_state_dbfile import collect_state_db_stats
- assert "hermes sessions optimize-storage" in rows[-1][2]
+ db_path = tmp_path / "state.db"
+ with sqlite3.connect(db_path) as conn:
+ conn.executescript(
+ "CREATE TABLE state_meta (key TEXT PRIMARY KEY, value TEXT);"
+ "CREATE VIRTUAL TABLE messages_fts USING fts5(content, tool_name, tool_calls);"
+ "CREATE VIRTUAL TABLE messages_fts_trigram USING fts5(content, tool_name, tokenize='trigram');"
+ "INSERT INTO state_meta VALUES ('fts_rebuild_high_water', '10');"
+ )
+ conn.execute("INSERT INTO state_meta VALUES ('fts_rebuild_progress', ?)", (str(progress),))
+ stats = collect_state_db_stats(db_path)
+ assert stats["fts_storage_upgrade_needed"] is False
+ assert stats["fts_rebuild_pending"] is pending
+ monkeypatch.setattr(doctor_state, "STATE_DB_SIZE_WARN_BYTES", 0)
+ rows = doctor_state._render_state_db_stats(stats)
+ assert any("hermes sessions optimize-storage" in detail for _, _, detail in rows) is pending
diff --git a/tests/hermes_state/test_state_db_stats.py b/tests/hermes_state/test_state_db_stats.py
index e691f8c6ad3..0e3a0a52161 100644
--- a/tests/hermes_state/test_state_db_stats.py
+++ b/tests/hermes_state/test_state_db_stats.py
@@ -179,6 +179,7 @@ def _base_stats(**overrides):
"messages_fts_cjk": False,
},
"fts_storage_version": 1,
+ "fts_storage_upgrade_needed": False,
"fts_rebuild_pending": False,
"fts_rebuild_high_water": None,
"fts_rebuild_progress": None,
@@ -231,7 +232,7 @@ def test_render_large_db_legacy_trigram_suggests_optimize():
big = STATE_DB_SIZE_WARN_BYTES + 1
lines = _render_state_db_stats(
- _base_stats(logical_size_bytes=big, fts_storage_version=None),
+ _base_stats(logical_size_bytes=big, fts_storage_version=None, fts_storage_upgrade_needed=True),
holders=None,
)
blob = " ".join(" ".join(str(p) for p in line) for line in lines)