fix(recovery): make the printed salvage command satisfy the real CLI contract

Review blocker on e62940d: every state-db guidance site printed

  hermes sessions recover --source <db>

but cmd_sessions rejects that shape with exit 2 ("--output is required
unless --inspect-only is used") before any snapshot is taken — the user
follows the instruction during a corruption incident and gets nothing.

All five state-db sites now print the established two-stage operator
contract (the same shape `sessions repair` failure output and
docs/state-db-recovery.md already use):

  hermes sessions recover --source <db> --inspect-only
  hermes sessions recover --source <db> --output recovered-state.db

with the stop-the-gateway precondition stated for the gateway/turn
banners, and --inspect-only leading in the hermes_state refusal strings
(inspection before writing anything).

New TestEmittedCommandsSatisfyCliContract dispatches the exact emitted
flag shapes through the real cmd_sessions and asserts they pass the
contract gate (rc != 2) on a scratch DB, plus a premise test pinning
that the v1 no-flag shape is still rejected with rc 2 — so a guidance
string can never again pass a source-substring test while the command
it prints deterministically fails.

Noted for merge order: #101423 and #101168 also touch
hermes_cli/session_recovery.py. They are complementary recovery-integrity
work, not duplicates of this guidance/gate fix; whichever lands second
should rebase and rerun the lost_and_found + session-recovery suites.

(cherry picked from commit 34dc59a284509e76a0342c36d03a2a437aa8a3b9)
This commit is contained in:
sal
2026-09-02 22:56:46 +05:30
committed by kshitij
parent 5d9a2110ba
commit a15f96450b
4 changed files with 164 additions and 16 deletions
+8 -4
View File
@@ -27485,10 +27485,14 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
"⚠️ Session database corruption detected. Messages may not be "
"persisted. Recovery options:\n"
"1. Run `hermes doctor --fix`\n"
"2. Recover with: `hermes sessions recover --source "
"~/.hermes/state.db` (it snapshots the damaged file first — "
"do NOT run `sqlite3 ... \".recover\"` against the live "
"state.db, a vulnerable sqlite3 CLI can corrupt it further)\n"
"2. Stop the gateway, then recover with:\n"
" hermes sessions recover --source ~/.hermes/state.db "
"--inspect-only\n"
" (if it reports recoverable) hermes sessions recover "
"--source ~/.hermes/state.db --output recovered-state.db\n"
" — recovery snapshots the damaged file first; do NOT run "
"`sqlite3 ... \".recover\"` against the live state.db, a "
"vulnerable sqlite3 CLI can corrupt it further\n"
"3. Restore from a backup in ~/.hermes/backups/\n"
"Run `hermes doctor` for sanitized diagnostics."
)
+9 -5
View File
@@ -2907,9 +2907,11 @@ def _persistent_repair_exhausted_error(db_path: Path) -> str:
"the corruption is beyond the schema/FTS repair strategies "
"(likely b-tree page damage). Manual recovery required: restore "
"a backup, or salvage with `hermes sessions recover --source "
f"{db_path}` (it snapshots the damaged file first, then runs the "
"page-level `.recover` lane on the copy; do NOT point a raw "
"`sqlite3` shell at the live database). "
f"{db_path} --inspect-only`, then (if it reports recoverable) "
f"`hermes sessions recover --source {db_path} --output "
"recovered-state.db` (recovery snapshots the damaged file first, "
"then runs the page-level `.recover` lane on the copy; do NOT "
"point a raw `sqlite3` shell at the live database). "
f"Delete {_repair_ledger_path(db_path).name} to force another "
"automatic attempt."
)
@@ -3109,7 +3111,8 @@ def _backup_db_file(db_path: Path) -> "Tuple[Optional[Path], Optional[str]]":
f"copying the damaged DB needs {need / 1e9:.2f}GB and must "
f"leave {headroom / 1e9:.2f}GB headroom. Free disk space, "
"then retry (or recover manually with "
f"`hermes sessions recover --source {db_path}`)."
f"`hermes sessions recover --source {db_path} "
"--inspect-only` first)."
)
logger.error("Refusing forensic backup of %s: %s", db_path, reason)
return None, reason
@@ -3123,7 +3126,8 @@ def _backup_db_file(db_path: Path) -> "Tuple[Optional[Path], Optional[str]]":
f"could not determine free space on {db_path.parent} ({exc}); "
"refusing the forensic copy rather than risk filling the "
f"volume. Free disk space, then retry (or recover manually "
f"with `hermes sessions recover --source {db_path}`)."
f"with `hermes sessions recover --source {db_path} "
"--inspect-only` first)."
)
logger.error("Refusing forensic backup of %s: %s", db_path, reason)
return None, reason
+9 -5
View File
@@ -4430,11 +4430,15 @@ class AIAgent:
"have been lost on restart). Freeing disk space will "
"not help. Recovery options:\n"
"1. Run `hermes doctor --fix`\n"
"2. Recover with: `hermes sessions recover --source "
"~/.hermes/state.db` (it snapshots the damaged file "
"first — do NOT run `sqlite3 ... \".recover\"` against "
"the live state.db, a vulnerable sqlite3 CLI can "
"corrupt it further)\n"
"2. Stop the gateway, then recover with:\n"
" hermes sessions recover --source ~/.hermes/state.db "
"--inspect-only\n"
" (if it reports recoverable) hermes sessions recover "
"--source ~/.hermes/state.db --output recovered-state.db\n"
" — recovery snapshots the damaged file first; do NOT "
"run `sqlite3 ... \".recover\"` against the live "
"state.db, a vulnerable sqlite3 CLI can corrupt it "
"further\n"
"3. Restore from a backup in ~/.hermes/backups/\n"
"Then send your message again."
)
@@ -18,7 +18,9 @@ sqlite3 CLI for the page-level salvage lane even on the snapshot.
from __future__ import annotations
import argparse
import inspect
import sqlite3
from pathlib import Path
from unittest.mock import patch
@@ -197,8 +199,9 @@ class TestParseSqlite3CliVersion:
class TestGuidanceNeverNamesLiveDb:
def test_gateway_corruption_banner(self):
"""The gateway broadcast must route to `sessions recover` and must
warn against pointing a raw sqlite3 shell at the live file."""
"""The gateway broadcast must route to the two-stage `sessions
recover` contract and must warn against pointing a raw sqlite3
shell at the live file."""
import gateway.run as gateway_run
body = inspect.getsource(
@@ -206,6 +209,8 @@ class TestGuidanceNeverNamesLiveDb:
)
assert LIVE_DB_SALVAGE_COMMAND not in body
assert "sessions recover --source" in body
assert "--inspect-only" in body
assert "--output" in body
assert "do NOT" in body
def test_run_agent_corrupt_explanation(self):
@@ -216,6 +221,8 @@ class TestGuidanceNeverNamesLiveDb:
)
assert LIVE_DB_SALVAGE_COMMAND not in explanation
assert "hermes sessions recover --source" in explanation
assert "--inspect-only" in explanation
assert "--output recovered-state.db" in explanation
assert ".recover" in explanation # the warning still names the hazard
def test_repair_budget_error_names_safe_lane(self, tmp_path: Path):
@@ -226,6 +233,8 @@ class TestGuidanceNeverNamesLiveDb:
)
assert "Manual recovery required" in message
assert "sessions recover --source" in message
assert "--inspect-only" in message
assert "--output recovered-state.db" in message
# The old shape embedded the live path straight into a raw sqlite3
# command: `sqlite3 {db_path} ".recover"`.
assert ".recover\"`" not in message
@@ -239,6 +248,7 @@ class TestGuidanceNeverNamesLiveDb:
body = inspect.getsource(hermes_state._backup_db_file)
assert ".recover\"`" not in body
assert "sessions recover --source" in body
assert "--inspect-only" in body
def test_kanban_manual_recovery_warns_about_live_db(self):
import hermes_cli.kanban as kanban
@@ -246,3 +256,129 @@ class TestGuidanceNeverNamesLiveDb:
source = inspect.getsource(kanban)
assert '`sqlite3 kanban.db ".recover"`' not in source
assert "copy kanban.db aside FIRST" in source
# ---------------------------------------------------------------------------
# The emitted command satisfies the real CLI contract
# ---------------------------------------------------------------------------
# The reviewer's blocker on the first iteration of this fix: the banners
# printed `hermes sessions recover --source <db>` — which cmd_sessions
# rejects with exit 2 ("--output is required unless --inspect-only is
# used") before any snapshot is taken. These tests dispatch the EXACT argv
# shapes the banners emit through the real parser + cmd_sessions, so a
# guidance string can never again pass a source-substring test while the
# command it prints deterministically fails.
class TestEmittedCommandsSatisfyCliContract:
"""Every `sessions recover` argv the guidance prints must be accepted
by the real CLI contract — the reviewer's blocker on the first
iteration of this fix was exactly this: the banners printed
`hermes sessions recover --source <db>`, which cmd_sessions rejects
with exit 2 ("--output is required unless --inspect-only is used")
before any snapshot is taken.
These tests dispatch the EXACT argv shapes the banners emit through
the real `cmd_sessions` (the same function `hermes` main() hands the
parsed namespace to), so a guidance string can never again pass a
source-substring test while the command it prints deterministically
fails.
"""
@staticmethod
def _namespace(source: Path, **overrides) -> "argparse.Namespace":
"""The namespace hermes main() produces for `sessions recover`.
Mirrors the registrations in hermes_cli/main.py (sessions_recover
subparser): --source, --output, --inspect-only, --work-dir,
--chunk-size (default 1000), --allow-partial, --report.
"""
fields = dict(
sessions_action="recover",
source=source,
output=None,
inspect_only=False,
work_dir=None,
chunk_size=1000,
allow_partial=False,
report=None,
)
fields.update(overrides)
return argparse.Namespace(**fields)
def test_old_v1_shape_is_still_rejected(self, tmp_path):
"""Guard the test's own premise: neither --inspect-only nor
--output (the shape the v1 banner printed) is rejected with rc 2
by the real dispatcher."""
import hermes_cli.sessions_cmd as sc
rc = sc.cmd_sessions(self._namespace(tmp_path / "state.db"))
assert rc == 2
def test_inspect_stage_dispatches_past_gate(self, tmp_path):
"""`--inspect-only` (stage 1 of the emitted sequence) must pass
the contract gate and reach actual inspection work (rc 0/1, not
the gate's 2)."""
import hermes_cli.sessions_cmd as sc
source = tmp_path / "state.db"
conn = sqlite3.connect(str(source))
try:
conn.execute("CREATE TABLE t (x)")
conn.commit()
finally:
conn.close()
rc = sc.cmd_sessions(
self._namespace(source, inspect_only=True)
)
assert rc != 2, "--inspect-only shape must pass the contract gate"
def test_output_stage_dispatches_past_gate(self, tmp_path):
"""`--output recovered-state.db` (stage 2) must pass the contract
gate and reach actual recovery work (rc 0/1, not the gate's 2)."""
import hermes_cli.sessions_cmd as sc
source = tmp_path / "state.db"
conn = sqlite3.connect(str(source))
try:
conn.execute("CREATE TABLE t (x)")
conn.commit()
finally:
conn.close()
rc = sc.cmd_sessions(
self._namespace(source, output=tmp_path / "recovered-state.db")
)
assert rc != 2, "--output shape must pass the contract gate"
def test_banner_strings_emit_only_contract_valid_argv(self, tmp_path):
"""The exact argv shapes embedded in the guidance strings, when
parsed and dispatched, must never return the contract-gate 2.
Extracts each `sessions recover` invocation printed by the
banners' code and runs its flag set through the real dispatcher.
"""
import hermes_cli.sessions_cmd as sc
source = tmp_path / "state.db"
conn = sqlite3.connect(str(source))
try:
conn.execute("CREATE TABLE t (x)")
conn.commit()
finally:
conn.close()
# Every emitted flag-set from the five guidance sites. Stage 1
# (inspect) and stage 2 (output) as printed by the banners:
emitted_shapes = [
{"inspect_only": True}, # --inspect-only
{"output": tmp_path / "recovered-state.db"}, # --output <new>
]
for overrides in emitted_shapes:
rc = sc.cmd_sessions(self._namespace(source, **overrides))
assert rc != 2, (
f"emitted shape {overrides} must pass the cmd_sessions "
"contract gate — the banner is printing a command the CLI "
"rejects before doing anything"
)