Summary

• updates.backup_keep: 0 (or negative) silently deletes the freshly-created pre-update backup, leaving the user with no recovery point even though Saved: <path> was printed.
• Floor the keep parameter to a minimum of 1 inside _prune_pre_update_backups so the just-written zip is always preserved.
• Three regression tests + clarifying comment on the config default.

The bug

_prune_pre_update_backups(backup_dir, keep) only clamps keep < 0 up to 0:

if keep < 0:
    keep = 0
...
backups = sorted(..., reverse=True)   # newest-first, includes the just-written zip
for p in backups[keep:]:               # backups[0:] = ALL of them
    p.unlink()

The function is called from create_pre_update_backup() immediately after the new zip is written. So with keep=0:

1. The zip is written to <HERMES_HOME>/backups/pre-update-<ts>.zip.
2. _prune_pre_update_backups(..., keep=0) lists every pre-update-*.zip (one entry — the new one) and deletes it.
3. The wrapper in main.py calls out_path.stat().st_size, which raises OSError (file missing) — caught and silently degraded to size_bytes = 0.
4. The user sees Saved: ~/.hermes/backups/pre-update-….zip (0 B, 1.2s) and believes they have a recovery point.

This is exactly the kind of footgun config systems trigger because some apps treat 0 as "unlimited" / "no rotation". Here it does the opposite — every backup is destroyed right after creation, with no warning.

Reproduced locally:

>>> from hermes_cli.backup import create_pre_update_backup
>>> out = create_pre_update_backup(hermes_home=Path('/tmp/hh'), keep=0)
>>> out.exists()
False

The fix

Clamp keep to a minimum of 1 inside _prune_pre_update_backups:

if keep < 1:
    keep = 1

The pruner is only ever invoked immediately after a fresh backup is written, so the smallest sensible retention is 1 — anything below that means "throw away the file we just paid disk + CPU to produce." Operators who genuinely want no backups should set updates.pre_update_backup: false (which gates creation entirely) rather than relying on backup_keep: 0. The config docstring is updated to spell this out.

The floor only protects the just-created backup; older zips are still rotated out as before. test_keep_zero_still_prunes_older_backups proves this.

Test plan

• Before (on 8ed599dc0, the merge commit of feat(update): auto-backup HERMES_HOME before hermes update #16539): the three new tests fail with keep=0 deleting the freshly-created backup.
• After: 9/9 TestPreUpdateBackup tests pass; full tests/hermes_cli/test_backup.py suite green (84 tests).
• Regression guard: temporarily reverted hermes_cli/backup.py → 3 new tests fail with "keep=0 silently deleted the freshly-created backup" / "Floor must preserve the new backup". Restored → all pass.
• Behavior for the existing default (keep=5) is unchanged.

Tests added (parametrized in spirit by covering both 0 and negative):

• test_keep_zero_does_not_delete_freshly_created_backup
• test_keep_negative_does_not_delete_freshly_created_backup
• test_keep_zero_still_prunes_older_backups — proves the floor doesn't regress rotation for older files

Related

• Follow-up to feat(update): auto-backup HERMES_HOME before hermes update #16539 (feat(update): auto-backup HERMES_HOME before hermes update) — the new auto-backup feature merged earlier today (8ed599d).
• No competing PRs found (gh search prs ... pre_update_backup / backup_keep / _prune_pre_update_backups / create_pre_update_backup all clean as of 2026-04-27 13:30Z).

🤖 Generated with Claude Code