[Bug]: Full pre-update backup aborts when HERMES_HOME contains a non-SQLite .db file

[akivavh]

Bug Description

On Windows, a full pre-update backup (hermes update --backup) treats every file whose suffix is .db as SQLite. If HERMES_HOME contains an unrelated non-SQLite .db file—for example, a Windows cache file copied into a Kanban workspace—sqlite3.backup() fails with file is not a database.

_write_full_zip_backup() then aborts the entire archive, deletes the partial ZIP, and returns None. The updater reports that the backup was skipped and continues. As a result, explicitly requesting a full pre-update backup can leave no full pre-update restore artifact.

The latest occurrence was reproduced on Hermes Agent v0.19.1, upstream commit e444d165, on 2026-08-01. The same causal signature was recorded locally on 2026-07-26 and 2026-07-28.

Steps to Reproduce

A minimal deterministic reproduction of the backup helper is:

from pathlib import Path
from tempfile import TemporaryDirectory

from hermes_cli.backup import _write_full_zip_backup

with TemporaryDirectory() as td:
    td = Path(td)
    home = td / "home"
    home.mkdir()
    (home / "foreign.db").write_text("not sqlite", encoding="utf-8")

    output = td / "pre-update.zip"
    result = _write_full_zip_backup(output, home)

    print(result)
    print(output.exists())

Current result:

None
False

The user-facing trigger is:

1. Have a non-SQLite file ending in .db anywhere under a non-excluded path in HERMES_HOME.
2. Have an update available.
3. Run hermes update --backup.
4. Observe file is not a database followed by Full-zip backup aborted.
5. Observe that the partial pre-update ZIP is deleted and the update continues.

Expected Behavior

The backup implementation should distinguish actual SQLite databases from unrelated files that merely use the .db suffix.

A non-SQLite .db should not invalidate the entire full backup. It should either be copied as a normal file or skipped individually with an explicit warning. Fail-closed behavior should remain for a genuine Hermes SQLite database whose consistent snapshot cannot be created.

If no full backup can be produced, the updater should clearly state that no full rollback archive exists.

Actual Behavior

Every .db suffix is routed through the SQLite backup API. A foreign non-SQLite file therefore causes the full ZIP operation to stop. The partial ZIP is deleted, create_pre_update_backup() returns None, and hermes update continues.

In the latest occurrence, the partial archive had reached approximately 4.5 GB before being deleted. No full pre-update ZIP remained. This is especially risky when the quick snapshot also omits an oversized state.db, because there may then be no current full-state restore artifact.

Affected Component

Setup / Installation

Messaging Platform (if gateway-related)

N/A (CLI only)

Debug Report

Not uploaded because the debug bundle may contain unrelated local profile/session data. This report instead includes a deterministic sanitized reproduction, exact environment/version information, and the relevant sanitized log signature below.

Operating System

Windows 11 Pro 10.0.26200 (build 26200), 64-bit

Python Version

3.11.15

Hermes Version

Hermes Agent v0.19.1 (2026.7.30), upstream e444d165, git installation, up to date

Additional Logs / Traceback (optional)

2026-08-01 00:48:57,987 WARNING hermes_cli.backup: SQLite safe copy failed for <HERMES_HOME>\kanban\boards\<board>\workspaces\<workspace>\product\%SystemDrive%\ProgramData\Microsoft\Windows\Caches\cversions.2.db: file is not a database
2026-08-01 00:48:57,987 WARNING hermes_cli.backup: Full-zip backup aborted: SQLite snapshot failed for kanban\boards\<board>\workspaces\<workspace>\product\%SystemDrive%\ProgramData\Microsoft\Windows\Caches\cversions.2.db

Same causal signature also recorded on:
- 2026-07-26 01:48:41
- 2026-07-26 02:01:38 (a second non-SQLite Windows cache .db filename)
- 2026-07-28 18:57:10

Root Cause Analysis (optional)

At commit e444d165, hermes_cli/backup.py selects the SQLite-safe-copy path solely with:

if abs_path.suffix == ".db":

_safe_copy_db() opens the source through sqlite3 and calls conn.backup(). A non-SQLite file returns False. _write_full_zip_backup() then sets sqlite_snapshot_failed, breaks the archive loop, deletes out_path, and returns None.

_run_pre_update_backup() treats that None as “no files found or write failed” and continues the update, as designed.

I searched existing issues and PRs; none matched this trigger and mechanism. Related but not duplicate:

• [Bug]: Hermes backup stages SQLite DB snapshots in /tmp, causing incomplete backups when state.db is large #35376 concerns SQLite snapshot staging in /tmp and incomplete archives when real SQLite databases are large.
• state.db zeroed (95MB of null bytes) during desktop update to v0.19.0 on Windows #68474 and fix(backup): surface quick-snapshot capture failures instead of dropping them silently #68907 concern state.db corruption and quick-snapshot capture failures.
• Improve Desktop gateway resilience, model discovery latency, and backup safety #69411 proposes atomic/single-flight backup publishing but does not address classifying arbitrary .db files as SQLite.

Proposed Fix (optional)

Route a file through _safe_copy_db() only when it is a known Hermes SQLite database or is positively identified as SQLite. Treat an arbitrary non-SQLite .db as a regular backup file (or skip that file explicitly) without discarding the whole archive.

Please preserve the existing fail-closed invariant for genuine Hermes databases. Suggested regression coverage:

1. A foreign non-SQLite foreign.db does not abort or delete the full archive.
2. A genuine SQLite database is still copied through the SQLite backup API.
3. A corrupt known Hermes database still fails closed.
4. A failed full pre-update backup reports unambiguously that no full rollback archive was created.

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR

[MaheshBhushan]

Opened #75728 with a fix.

Root cause is as you diagnosed: _write_full_zip_backup() dispatched on the suffix alone, so one foreign .db aborted and deleted the whole archive. A .db file now reaches the SQLite backup API only if it is one of Hermes's own databases (matched by name against _QUICK_STATE_FILES) or its header actually carries the SQLite magic; anything else is archived as a regular file with a warning. The header probe uses read_header_bytes_preopen(), which returns None both for a live connection and on OSError — both treated as SQLite, so fail-closed is never weakened by a read that could not be performed.

Your four suggested cases are all covered as tests, including the two fail-closed guards. Your repro script runs clean on this branch — I reproduced it unmodified on Linux first, since the mechanism turned out not to be Windows-specific. I also left the updater message change in (item 4).

One thing I did not fix and flagged in the PR instead: run_backup() (the manual hermes backup) has the same misclassification, but it continues rather than aborting, so a foreign .db is silently dropped from that archive instead of destroying it. Happy to fold that in if the maintainers would rather it be one change.

[GottZ]

This was generated by AI during triage.

Summary

One PR addresses #75724. #75728 fixes the suffix-only SQLite classification that caused foreign .db files to abort full pre-update backups, while preserving fail-closed handling for Hermes-owned databases and clarifying when no rollback archive was created.

Related pull requests

• fix(backup): don't treat every .db file as SQLite in full backups #75728 best fix — (+159/-2) — fixes: Replaces suffix-only dispatch with Hermes-owned filename and SQLite-header checks, so foreign .db files are archived normally instead of aborting the full ZIP. It retains fail-closed behavior for corrupt known Hermes databases and adds regression coverage for foreign, genuine SQLite, corrupt known, and nested known database cases.

Suggested consolidation

Merge #75728 as the best existing fix for #75724: its diff directly addresses the reported misclassification and archive deletion path, preserves the intended safety behavior for Hermes databases, and improves the updater warning when no full rollback archive exists. The analogous manual backup misclassification remains outside this PR's scope and can be tracked separately.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I75724(["issue #75724 (open)"])
    P75728["PR #75728 (open)"]
    P75728 -->|best fix| I75724
    class I75724 open
    class I75724 target
    class P75728 open
    class P75728 best
    click I75724 "https://github.com/NousResearch/hermes-agent/issues/75724"
    click P75728 "https://github.com/NousResearch/hermes-agent/pull/75728"

Loading

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 9 kB of PR diffs, 14 kB of issue/PR text, 1 kB of discussion (1 comments), 2 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[GottZ]

This was generated by AI during triage.

Delta since our previous triage comment

Since the previous comment, @teknium1's keep_open review identified that #75728 introduces the shared classifier only for full pre-update ZIP backups, while manual run_backup() still routes every .db file through the SQLite path and can silently omit foreign files. This extends the relevant defect scope beyond the issue's reported pre-update path and requires follow-up coverage before merge.

Changed pull requests

• fix(backup): don't treat every .db file as SQLite in full backups #75728 best fix — (+159/-2) — rework, best fix: The diff fixes [Bug]: Full pre-update backup aborts when HERMES_HOME contains a non-SQLite .db file #75724's full pre-update failure by archiving positively non-SQLite .db files normally while preserving fail-closed handling for Hermes databases, but it does not apply _use_sqlite_backup_api() to run_backup(). Consistent with @teknium1's keep_open review, reuse the classifier there and add the requested manual-backup regression test.

Suggested consolidation

Recommendation changed: keep merge-lane-eligible #75728 open as the best existing fix, address @teknium1's manual-backup review, then merge it.

Complex graph unchanged since our previous triage comment.

Cross-PR triage: Reviewed 1 pull request and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 9 kB of PR diffs, 14 kB of issue/PR text, 1 kB of discussion (1 comments), 2 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

[Railway9784]

Same root cause on Linux, distinct trigger class (docker bind-mount data under HERMES_HOME) — corroborating with live evidence from 2026-08-15.

Environment: Ubuntu, HERMES_HOME=/home/hermes/.hermes (symlinked as /opt/data), diun container bind-mounts /opt/data/diun/data → /data — diun.db is a BoltDB, not SQLite.

Log evidence (every update since the mount appeared): errors.log shows the exact abort chain, run after run:

hermes_cli.backup: SQLite safe copy failed for /home/hermes/.hermes/diun/data/diun.db: file is not a database
hermes_cli.backup: Full-zip backup aborted: SQLite snapshot failed for diun/data/diun.db
hermes_cli.backup: Full-zip backup: zip write failed: diun/data/diun.db

→ hermes update printed ⚠ Backup skipped (no files found or write failed); continuing update. on 23 consecutive runs (2026-08-04 → 2026-08-14). The quick state snapshot still ran; the full zip (the hermes import-restorable artifact) never landed.

Impact: when a uv pip install step failed transiently on 2026-08-14, there was no pre-update zip safety net — recovery depended on the quick snapshot + emergency state.db .bak files and a manual venv rebuild. This is a silent-loss failure, not just a missing convenience artifact.

Two additional observations:

1. The user-facing message (no files found or write failed) is misleading for this failure mode — files WERE found; the archive aborted on a specific entry.
2. A header-magic check (SQLite format 3) before the backup API would let non-SQLite .db files be skipped instead of aborting the entire archive.

Local workaround applied: updates.pre_update_backup: quick (state snapshot only, bypasses the full zip).