Skip to content

The agent that grows with you

fix(sessions): never write browse DDL into a corrupt lagging store

Teknium42a94335bbe8
diff --git a/hermes_state_reconcile.py b/hermes_state_reconcile.py
index 88c07df7591..ac94f20e68b 100644
--- a/hermes_state_reconcile.py
+++ b/hermes_state_reconcile.py
@@ -157,12 +157,36 @@ def _apply_additive_schema(path: Path) -> None:
raise
+class CorruptStoreError(sqlite3.DatabaseError):
+ """The lagging store is also damaged: browsing must not write DDL into it. Worded like sqlite's
+ own malformed-image error so every caller maps it to the corrupt-store status (``hermes doctor``)."""
+
+ def __init__(self, detail: str):
+ super().__init__(f'database disk image is malformed (quick_check: {detail})')
+
+
+def _quick_check_problem(path: Path):
+ """``PRAGMA quick_check`` on a read-only connection: None when ``ok``, else the first problems."""
+ from hermes_cli.sqlite_safe_read import connect_tracked
+ try:
+ with closing(connect_tracked(path.resolve().as_uri() + '?mode=ro', uri=True, tracking_path=path)) as conn:
+ rows = conn.execute('PRAGMA quick_check').fetchall()
+ except sqlite3.DatabaseError as exc:
+ from hermes_state_errors import is_malformed_db_error
+ if is_malformed_db_error(exc):
+ return str(exc)
+ raise
+ problems = [str(r[0]) for r in rows if r and str(r[0]).lower() != 'ok']
+ return '; '.join(problems[:3]) or None
+
+
def reconcile_drift_for_browse(path: Path) -> bool:
"""Catch a lagging store up for a read-only browse; True when DDL ran, False when already current.
Raises :class:`DeclarativeDriftError` (``owned=True`` when a running gateway owns the store)
- with a user-facing detail naming the drift and the remedy. Never touches a store missing its
- history tables: recreating them empty would hide lost sessions."""
+ with a user-facing detail naming the drift and the remedy, and :class:`CorruptStoreError`
+ when the lagging store is also damaged. Never touches a store missing its history tables:
+ recreating them empty would hide lost sessions."""
from gateway.runtime_ownership import OwnershipConflict, exclusive_maintenance
reason = schema_drift_reason(path)
@@ -183,6 +207,10 @@ def reconcile_drift_for_browse(path: Path) -> bool:
# (or a sibling browse) may already have caught the store up.
if schema_drift_reason(path) is None:
return False
+ # A failing column probe hides damage elsewhere in the file: additive DDL is not
+ # corruption recovery, so never write into a store that is not clean.
+ if problem := _quick_check_problem(path):
+ raise CorruptStoreError(problem)
_apply_additive_schema(path)
except OwnershipConflict as exc:
raise DeclarativeDriftError(
diff --git a/tests/hermes_cli/test_browse_schema_drift.py b/tests/hermes_cli/test_browse_schema_drift.py
index 37bb6b3e613..29b833477ea 100644
--- a/tests/hermes_cli/test_browse_schema_drift.py
+++ b/tests/hermes_cli/test_browse_schema_drift.py
@@ -258,3 +258,52 @@ def test_startup_eager_reconcile_heals_only_an_unowned_stale_store(own_store_cli
web_server_lifecycle._eager_reconcile_own_session_db()
assert "last_read_at" in _session_columns(path)
+
+
+# ── Independent review round 1 ──
+
+
+def _lagging_store_with_history(home, rows=400):
+ """A real store with enough history for a multi-page ``messages`` b-tree, one column dropped."""
+ path = home / "state.db"
+ with SessionDB(db_path=path) as db:
+ db.create_session("kept", source="cli")
+ for i in range(rows):
+ db.append_message("kept", role="user", content=f"history {i} " * 40)
+ with closing(sqlite3.connect(path)) as conn:
+ conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+ conn.execute("DROP INDEX IF EXISTS idx_sessions_effective_activity")
+ conn.execute("ALTER TABLE sessions DROP COLUMN last_read_at")
+ conn.commit()
+ conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+ return path
+
+
+def _file_state(path):
+ """Main file plus WAL content (an empty sidecar a reader creates is not a write)."""
+ wal = path.with_name(path.name + "-wal")
+ return path.read_bytes(), wal.read_bytes() if wal.exists() else b""
+
+
+def test_corrupt_non_root_page_plus_drift_is_not_written(tmp_path):
+ """P1-1: the drift probe fails before any damaged page is read, so only an integrity check
+ under the lock keeps browse from running ALTER TABLE on a corrupt file."""
+ path = _lagging_store_with_history(_profile_home(tmp_path))
+ with closing(sqlite3.connect(path)) as conn:
+ page_size = conn.execute("PRAGMA page_size").fetchone()[0]
+ root = conn.execute("SELECT rootpage FROM sqlite_master WHERE name='messages'").fetchone()[0]
+ pages = conn.execute("PRAGMA page_count").fetchone()[0]
+ victim = max(root + 5, pages // 2) # a messages leaf, never page 1 / sqlite_master
+ with open(path, "r+b") as fh:
+ fh.seek((victim - 1) * page_size + 8)
+ fh.write(b"\xde\xad\xbe\xef" * ((page_size - 16) // 4))
+ with closing(sqlite3.connect(f"file:{path}?mode=ro", uri=True)) as conn:
+ assert conn.execute("PRAGMA quick_check").fetchone()[0] != "ok"
+ before = _file_state(path)
+
+ with pytest.raises(HTTPException) as caught:
+ _open_session_db_at_path(path, read_only=True).close()
+ assert caught.value.status_code == 503
+ assert caught.value.detail["error"] == "state_db_corrupt"
+ assert _file_state(path) == before
+ assert "last_read_at" not in _session_columns(path)