fix(checkpoints): never auto-delete orphans on unattended startup sweep

Builds on this PR's diagnosis by @Frowtek: a missing workdir is
ambiguous (deleted project vs. an unmounted external volume / network
share / VPN not yet up), so it's not safe evidence for a destructive
GC sweep — especially one that runs unattended at startup.

- cli.py / gateway/run.py: the startup auto-maintenance sweep now
  always passes delete_orphans=False to maybe_auto_prune_checkpoints().
  It still prunes by retention_days, size cap, and legacy archives —
  none of which require guessing whether a project was deleted or is
  just temporarily unreachable.
- hermes_cli/config.py: drop the now-unused delete_orphans default.
- hermes_cli/checkpoints.py: `hermes checkpoints prune` (the explicit,
  human-invoked path) now previews the orphan project list and asks
  for confirmation before deleting, unless -f/--force is passed.
- Docs updated (EN + zh-Hans) to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
joaomarcos 2026-07-22 03:11:12 -03:00 committed by Teknium
parent 3960315af7
commit cd3f653b4e
6 changed files with 64 additions and 18 deletions

View file

@ -94,12 +94,15 @@ checkpoints:
max_file_size_mb: 10 # skip any single file larger than this
# Auto-maintenance (on by default): sweep ~/.hermes/checkpoints/ at startup
# and delete project entries whose working directory no longer exists
# (orphans) or whose last_touch is older than retention_days. Runs at most
# once per min_interval_hours, tracked via a .last_prune marker.
# and delete project entries whose last_touch is older than retention_days.
# Runs at most once per min_interval_hours, tracked via a .last_prune
# marker. This sweep never deletes "orphan" entries (working directory not
# found) — a missing workdir at startup is ambiguous (deleted project vs.
# an unmounted external volume / network share / VPN not yet up), so
# orphan cleanup is only ever done via the explicit
# `hermes checkpoints prune` command below, with a confirmation prompt.
auto_prune: true
retention_days: 7
delete_orphans: true
min_interval_hours: 24
```

View file

@ -94,12 +94,14 @@ checkpoints:
max_file_size_mb: 10 # 跳过大于此值的单个文件
# 自动维护(默认开启):启动时扫描 ~/.hermes/checkpoints/
# 删除工作目录已不存在的项目条目(孤立项)或 last_touch 超过
# retention_days 的条目。通过 .last_prune 标记控制,
# 最多每 min_interval_hours 运行一次。
# 删除 last_touch 超过 retention_days 的条目。通过 .last_prune
# 标记控制,最多每 min_interval_hours 运行一次。此扫描不会删除
# “孤立”条目(工作目录未找到)——启动时工作目录缺失含义模糊
# (项目被删除,还是外部卷/网络共享/VPN 尚未挂载),因此孤立项
# 清理只能通过下方的 `hermes checkpoints prune` 命令显式触发,
# 并会要求确认。
auto_prune: true
retention_days: 7
delete_orphans: true
min_interval_hours: 24
```