Skip to content

The agent that grows with you

fix(sessions): reconcile declarative drift during explicit repair

funky-xamarin49b42a8b2f72
diff --git a/hermes_cli/sessions_cmd.py b/hermes_cli/sessions_cmd.py
index 25b4dc8fa7a..27a9ffb88d3 100644
--- a/hermes_cli/sessions_cmd.py
+++ b/hermes_cli/sessions_cmd.py
@@ -105,7 +105,16 @@ def _cmd_repair(args):
if not db_path.exists():
print(f"No session database at {db_path} (nothing to repair).")
return
+ from hermes_state_reconcile import repair_declarative_schema, schema_drift_reason
reason = _db_opens_cleanly(db_path)
+ repair = repair_state_db_schema
+ if reason is None:
+ try:
+ reason = schema_drift_reason(db_path)
+ except (sqlite3.Error, OSError) as exc:
+ print(f"✗ Could not check session schema: {exc}")
+ return 1
+ repair = repair_declarative_schema
if reason is None:
print(f"✓ {db_path} opens cleanly — no repair needed.")
return
@@ -113,19 +122,23 @@ def _cmd_repair(args):
if getattr(args, "check_only", False):
return 1
print("Repairing (a backup copy is made first)…")
- report = repair_state_db_schema(db_path, backup=not getattr(args, "no_backup", False))
+ report = repair(db_path, backup=not getattr(args, "no_backup", False))
if report.get("repaired"):
if report.get("backup_path"):
print(f" backup: {report['backup_path']}")
print(f" strategy: {report.get('strategy')}")
try:
- with SessionDB() as _repair_db:
+ with SessionDB(db_path=db_path, read_only=repair is repair_declarative_schema) as _repair_db:
n = _repair_db._conn.execute("SELECT COUNT(*) FROM sessions").fetchone()[0]
print(f"✓ Repaired — {n} sessions recovered.")
except Exception:
print("✓ Repaired.")
return
print(f"✗ Repair failed: {report.get('error')}")
+ if repair is repair_declarative_schema:
+ if report.get('backup_path'):
+ print(f" A backup is preserved at: {report['backup_path']}")
+ return 1
if report.get("backup_path"):
print(f" A backup is preserved at: {report['backup_path']}")
# Without this pointer the user is at a dead end; lead with --inspect-only before writing.
diff --git a/hermes_state_reconcile.py b/hermes_state_reconcile.py
new file mode 100644
index 00000000000..88bfe0ce5e8
--- /dev/null
+++ b/hermes_state_reconcile.py
@@ -0,0 +1,96 @@
+"""Explicit offline repair of additive state.db schema drift.
+
+Browsing stays read-only. Reconcile a protected snapshot so failed DDL never
+leaves the user's store partly upgraded or escalates into FTS surgery.
+"""
+import sqlite3
+from contextlib import closing
+from pathlib import Path
+
+
+def schema_drift_reason(path: Path):
+ """Return a missing declared table/column, not a corruption diagnosis."""
+ from hermes_state_schema import schema_read_probe_statements
+ from hermes_cli.sqlite_safe_read import connect_tracked
+
+ with closing(connect_tracked(path.resolve().as_uri() + '?mode=ro', uri=True, tracking_path=path)) as conn:
+ try:
+ for statement in schema_read_probe_statements():
+ conn.execute(statement).fetchone()
+ except sqlite3.OperationalError as exc:
+ from hermes_state_repair import _schema_not_built
+ if _schema_not_built(exc):
+ return str(exc)
+ raise
+ return None
+
+
+def _reconcile_snapshot(path, guard):
+ from hermes_state_repair import (
+ _copy_database_snapshot, _db_opens_cleanly, _repair_conn,
+ _repair_scratch_space_error, _unlink_db_triple,
+ )
+ from hermes_state_schema import reconcile_state_schema
+
+ scratch = path.with_name(path.name + '.reconcile-scratch')
+ if error := _repair_scratch_space_error(path):
+ raise RuntimeError(error)
+ if error := _unlink_db_triple(scratch):
+ raise RuntimeError(error)
+ try:
+ _copy_database_snapshot(path, scratch, source_connection=guard)
+ with _repair_conn(scratch) as conn:
+ reconcile_state_schema(conn)
+ conn.commit()
+ if reason := schema_drift_reason(scratch):
+ raise RuntimeError(f'schema reconciliation incomplete: {reason}')
+ if reason := _db_opens_cleanly(scratch):
+ raise RuntimeError(f'reconciled snapshot is unhealthy: {reason}')
+ _copy_database_snapshot(scratch, path, destination_connection=guard)
+ finally:
+ if error := _unlink_db_triple(scratch):
+ import logging
+ logging.getLogger(__name__).warning('Could not remove reconciliation snapshot: %s', error)
+
+
+def _reconcile_locked(path, backup, report):
+ from hermes_state_repair import (
+ _backup_db_file, _db_opens_cleanly, _exclusive_repair_db_guard,
+ _live_writer_holds_db,
+ )
+
+ if _live_writer_holds_db(path):
+ raise RuntimeError('a live writer still holds state.db; stop it and retry')
+ if schema_drift_reason(path) is None:
+ report.update(repaired=True, strategy='already_healthy')
+ return
+ # Additive repair is not a substitute for corruption recovery.
+ if reason := _db_opens_cleanly(path):
+ raise RuntimeError(reason)
+ if backup:
+ bpath, error = _backup_db_file(path)
+ if bpath is None:
+ raise RuntimeError(f'pre-repair backup refused: {error}')
+ report['backup_path'] = str(bpath)
+ with _exclusive_repair_db_guard(path) as (guard, error):
+ if guard is None:
+ raise RuntimeError(f'could not acquire exclusive state.db repair ownership: {error}')
+ _reconcile_snapshot(path, guard)
+ report.update(repaired=True, strategy='reconcile_declarative_schema')
+
+
+def repair_declarative_schema(path: Path, *, backup: bool = True):
+ """Reuse repair's snapshot/SQLite exclusion beneath the runtime owner lock."""
+ from gateway.runtime_ownership import OwnershipConflict, exclusive_maintenance
+ from hermes_state_repair import _cross_process_repair_lock
+
+ report = {'repaired': False, 'strategy': None, 'backup_path': None, 'error': None}
+ try:
+ with exclusive_maintenance([path.parent]):
+ with _cross_process_repair_lock(path) as holding:
+ if not holding:
+ raise RuntimeError('could not obtain the state.db repair lock')
+ _reconcile_locked(path, backup, report)
+ except (OwnershipConflict, OSError, sqlite3.Error, RuntimeError, TimeoutError) as exc:
+ report['error'] = str(exc)
+ return report
diff --git a/tests/hermes_cli/test_sessions_repair_declarative.py b/tests/hermes_cli/test_sessions_repair_declarative.py
new file mode 100644
index 00000000000..563e29826fe
--- /dev/null
+++ b/tests/hermes_cli/test_sessions_repair_declarative.py
@@ -0,0 +1,94 @@
+"""Explicit repair must restore browsing after additive schema drift (#140315)."""
+import sqlite3
+from contextlib import closing
+from types import SimpleNamespace
+
+import pytest
+
+from hermes_state import SessionDB
+from hermes_state_common import SCHEMA_VERSION
+from hermes_cli import sessions_cmd
+from hermes_cli.web_server_sessions import _open_session_db_at_path
+from fastapi import HTTPException
+
+
+def _legacy_store(tmp_path, monkeypatch):
+ path = tmp_path / 'state.db'
+ with SessionDB(db_path=path) as db:
+ db.create_session('retained', source='cli')
+ db.append_message('retained', role='user', content='history survives')
+ with closing(sqlite3.connect(path)) as conn:
+ conn.execute('ALTER TABLE sessions DROP COLUMN runtime_generation')
+ conn.execute('ALTER TABLE sessions DROP COLUMN runtime_revision')
+ conn.execute('ALTER TABLE async_delegations DROP COLUMN owner_execution_id')
+ for table in ('worker_receipts', 'worker_executions', 'session_admissions', 'runtime_epoch'):
+ conn.execute(f'DROP TABLE {table}')
+ conn.commit()
+ assert conn.execute('SELECT version FROM schema_version').fetchone()[0] == SCHEMA_VERSION
+ monkeypatch.setattr('hermes_state.DEFAULT_DB_PATH', path)
+ monkeypatch.setattr(sessions_cmd, 'get_hermes_home', lambda: tmp_path)
+ return path
+
+
+def test_check_only_reports_drift_without_mutation(tmp_path, monkeypatch):
+ path = _legacy_store(tmp_path, monkeypatch)
+ before = path.read_bytes()
+ with pytest.raises(HTTPException) as exc:
+ _open_session_db_at_path(path, read_only=True)
+ assert exc.value.status_code == 503
+ assert sessions_cmd._cmd_repair(SimpleNamespace(check_only=True)) == 1
+ assert path.read_bytes() == before
+
+
[email protected]('blocker', ['owner', 'ddl', 'incomplete', 'backup'])
+def test_refused_reconciliation_preserves_original(tmp_path, monkeypatch, blocker):
+ from gateway.runtime_ownership import ProfileOwnership
+ import hermes_state_repair as repair
+ import hermes_state_schema as schema
+
+ path = _legacy_store(tmp_path, monkeypatch)
+ before = path.read_bytes()
+ owner = ProfileOwnership()
+ if blocker == 'owner':
+ owner.reserve([tmp_path])
+ elif blocker == 'ddl':
+ def fail(conn):
+ conn.execute('CREATE TABLE only_in_scratch (id INTEGER)')
+ raise sqlite3.OperationalError('injected DDL refusal')
+ monkeypatch.setattr(schema, 'reconcile_state_schema', fail)
+ elif blocker == 'incomplete':
+ monkeypatch.setattr(schema, 'reconcile_state_schema', lambda conn: None)
+ else:
+ monkeypatch.setattr(repair, '_backup_db_file', lambda path: (None, 'injected backup refusal'))
+ try:
+ assert sessions_cmd._cmd_repair(SimpleNamespace(check_only=False, no_backup=False)) == 1
+ finally:
+ owner.close()
+ assert path.read_bytes() == before
+ assert not path.with_name(path.name + '.reconcile-scratch').exists()
+
+
[email protected]('with_history', [True, False])
+def test_canonical_store_is_unchanged(tmp_path, monkeypatch, with_history):
+ path = tmp_path / 'state.db'
+ with SessionDB(db_path=path) as db:
+ if with_history:
+ db.create_session('normal', source='cli')
+ db.append_message('normal', role='user', content='normal')
+ monkeypatch.setattr('hermes_state.DEFAULT_DB_PATH', path)
+ before = path.read_bytes()
+ assert sessions_cmd._cmd_repair(SimpleNamespace(check_only=False)) in (None, 0)
+ assert path.read_bytes() == before
+
+
[email protected]('backup', [True, False])
+def test_explicit_repair_restores_readonly_history(tmp_path, monkeypatch, backup):
+ path = _legacy_store(tmp_path, monkeypatch)
+ assert sessions_cmd._cmd_repair(SimpleNamespace(check_only=False, no_backup=not backup)) in (None, 0)
+ backups = list(tmp_path.glob('state.db.malformed-backup-*'))
+ assert bool(backups) is backup
+ with _open_session_db_at_path(path, read_only=True) as db:
+ assert [row['content'] for row in db.get_messages('retained')] == ['history survives']
+ assert db.session_count() == 1
+ assert db._conn.execute('SELECT version FROM schema_version').fetchone()[0] == SCHEMA_VERSION
+ assert sessions_cmd._cmd_repair(SimpleNamespace(check_only=True)) in (None, 0)