The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(sessions): reconcile declarative drift during explicit repair
funky-xamarin49b42a8b2f72
diff --git a/hermes_cli/sessions_cmd.py b/hermes_cli/sessions_cmd.pyindex 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_reasonreason = _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_schemaif 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 1print("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.")returnprint(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 1if 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.pynew file mode 100644index 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 reportdiff --git a/tests/hermes_cli/test_sessions_repair_declarative.py b/tests/hermes_cli/test_sessions_repair_declarative.pynew file mode 100644index 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)