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:
+8
-4
@@ -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
@@ -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
@@ -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"
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user