Skip to content

The agent that grows with you

fix(pm): reclaim dependency state of missing checkouts after 14 days unused

Tekniumba48bbcd8be1
diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py
index 8ac69a3c86a..5efe57fa761 100644
--- a/hermes_cli/config_defaults.py
+++ b/hermes_cli/config_defaults.py
@@ -482,8 +482,7 @@ DEFAULT_CONFIG = {
# and merged are removed; dirty or unpushed ones are archived to refs/hermes/archive/<tree>
# first (`hermes worktree restore <name>`). Live trees and Kanban t_<hex> trees are never touched.
"worktrees": {
- # false = never remove a dirty/unpushed tree (the pre-archive behaviour, exactly).
- "archive_dirty": True,
+ "archive_dirty": True, # false = never remove a dirty/unpushed tree (the pre-archive behaviour)
# Untracked files larger than this (MB) are not archived, so a tree holding one is kept.
"archive_max_file_mb": 50,
# The sweep deletes archive refs older than this many days. 0 keeps them forever.
@@ -491,6 +490,7 @@ DEFAULT_CONFIG = {
# Optional size budget (GB) for idle trees: past it the oldest idle trees are archived and
# removed first. Live, young and Kanban trees are never counted or touched. 0 = off.
"max_total_gb": 0,
+ "install_state_retention_days": 14, # installs/<key> of a missing checkout, unused this long, goes; 0 = never
},
# Filesystem checkpoints: snapshot the working directory once per turn (on the first
# write_file/patch call); restore with /rollback. Opt-in via `hermes chat --checkpoints` or
diff --git a/pm/install_states.py b/pm/install_states.py
index ffa363ae764..2e2b85f2581 100644
--- a/pm/install_states.py
+++ b/pm/install_states.py
@@ -14,6 +14,13 @@ checkout sat where this process can see that it was deleted -- under the data ro
``installs/`` (scratch clones, the runtime checkout) or directly in a ``.worktrees/`` dir that
still exists. Removal still fails closed on anything a live process could hold: the install
lock, or a dependency / PM runtime generation lease.
+
+A checkout elsewhere (``~/.cache/review-1/head``, a scratch clone outside the data root) can never
+be proved deleted, so its missing checkout alone would keep the state forever. It is reclaimed
+once the state has also gone unused for ``worktrees.install_state_retention_days``: every sync
+recreates ``inputs/`` and every launch takes a generation lease (moving its
+``.leases`` dir), so a checkout that still exists behind a mount boundary and is used at all keeps
+its state. One unused for longer is rebuilt by ``hermes pm repair`` / the next activation.
"""
from __future__ import annotations
@@ -22,6 +29,7 @@ import contextlib
import logging
import os
import shutil
+import time
from pathlib import Path
logger = logging.getLogger(__name__)
@@ -33,11 +41,35 @@ def _provably_deleted(root: Path, data_root: Path) -> bool:
return root.is_relative_to(data_root) or (root.parent.name == ".worktrees" and root.parent.is_dir())
+def _last_used(state: Path) -> float:
+ """Newest mtime among what a sync (``inputs/`` is recreated, ``facts.json`` rewritten) or a
+ launch (a generation's ``.leases`` dir) moves. Not the state dir itself: a part-way removal
+ moves it, and that must not restart the clock for the retry."""
+ paths = [state / "inputs", state / "facts.json"]
+ for generations in (state / "environments", state / "pm-runtime" / "generations"):
+ if generations.is_dir():
+ paths += [generation / ".leases" for generation in generations.iterdir()]
+ mtimes = [0.0]
+ for path in paths:
+ with contextlib.suppress(OSError):
+ mtimes.append(path.lstat().st_mtime)
+ return max(mtimes)
+
+
+def _retention_seconds() -> float | None:
+ from hermes_cli.config import cfg_get, load_config_readonly
+
+ days = cfg_get(load_config_readonly(), "worktrees", "install_state_retention_days", default=14)
+ return days * 86400 if isinstance(days, (int, float)) and days > 0 else None
+
+
def orphan_install_states(installs: Path) -> list[Path]:
- """State dirs whose recorded checkout is provably deleted. Dirs without a record are left alone."""
+ """State dirs whose recorded checkout is provably deleted, or missing and unused past the
+ retention period. Dirs without a record, and dirs whose checkout exists, are left alone."""
if not installs.is_dir():
return []
data_root = installs.resolve().parent
+ retention = _retention_seconds()
orphans: list[Path] = []
for state in sorted(installs.iterdir()):
record = state / "inputs" / ".project-root"
@@ -47,7 +79,10 @@ def orphan_install_states(installs: Path) -> list[Path]:
root = record.read_text(encoding="utf-8-sig").strip()
except OSError:
continue
- if root and _provably_deleted(Path(root), data_root):
+ if not root or Path(root).exists():
+ continue
+ if _provably_deleted(Path(root), data_root) or (
+ retention is not None and time.time() - _last_used(state) > retention):
orphans.append(state)
return orphans
diff --git a/tests/pm/test_install_states_gc.py b/tests/pm/test_install_states_gc.py
index ea9f3a3b3a2..ddc91d5d24f 100644
--- a/tests/pm/test_install_states_gc.py
+++ b/tests/pm/test_install_states_gc.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import os
import subprocess
+import time
import pm.environments
import pytest
@@ -83,3 +84,26 @@ def test_partly_removed_orphan_keeps_its_record_until_retried(tmp_path):
finally:
stuck.chmod(0o700)
assert collect_orphan_install_states(installs) == [state] and not state.exists()
+
+
+def test_unprovable_missing_checkout_is_reclaimed_once_unused_past_retention(tmp_path):
+ installs = tmp_path / "home" / "installs"
+ present_root = tmp_path / "review" / "present"
+ present_root.mkdir(parents=True)
+ fresh = _state(installs, "aaaa", tmp_path / "review" / "fresh")
+ idle = _state(installs, "bbbb", tmp_path / "review" / "idle")
+ leased = _state(installs, "cccc", tmp_path / "review" / "leased")
+ present = _state(installs, "dddd", present_root)
+ lease_dir = leased / "environments" / "gen" / ".leases"
+ lease_dir.mkdir()
+ fd = os.open(lease_dir / "reader", os.O_CREAT | os.O_RDWR, 0o600)
+ assert lock_fd(fd, wait=False)
+ month_ago = time.time() - 30 * 86400
+ for state in (idle, leased, present):
+ for path in sorted(state.rglob("*"), reverse=True) + [state]:
+ os.utime(path, (month_ago, month_ago), follow_symlinks=False)
+ try:
+ assert collect_orphan_install_states(installs) == [idle]
+ finally:
+ os.close(fd)
+ assert all(p.is_dir() for p in (fresh, leased, present)) and not idle.exists()
diff --git a/website/docs/reference/package-management.md b/website/docs/reference/package-management.md
index 2a47b33bdcb..0d8585cb1a0 100644
--- a/website/docs/reference/package-management.md
+++ b/website/docs/reference/package-management.md
@@ -542,7 +542,7 @@ hermes pm install chromium
| `pm doctor` | Check installed tool identities, files, and digests against the lock. |
| `pm repair` | Rebuild the recorded Python dependency set in a new generation, validate it, then select it. Does not update pins, features, or plugin configuration. |
| `pm status` | Print the latest sync/update receipt as JSON, or report that no receipt exists. |
-| `pm gc` | Remove unreferenced tool-store entries, eligible download partials, unused lease-managed Python generations, and the `installs/INSTALL_KEY/` state of deleted checkouts (a worktree removed from a `.worktrees/` dir that still exists, or a clone under the data root; checkouts this process cannot see, such as a host install viewed from a container sharing the data root, are kept, as is any state whose install lock or generation lease is still held). The worktree pruner that runs at startup reclaims those orphaned state dirs too. |
+| `pm gc` | Remove unreferenced tool-store entries, eligible download partials, unused lease-managed Python generations, and the `installs/INSTALL_KEY/` state of deleted checkouts (a worktree removed from a `.worktrees/` dir that still exists, or a clone under the data root; a missing checkout anywhere else, such as a host install viewed from a container sharing the data root, is kept until its state has gone unused, with no sync and no launch, for `worktrees.install_state_retention_days` (default 14, 0 = forever); state whose install lock or generation lease is still held is always kept). The worktree pruner that runs at startup reclaims those orphaned state dirs too. |
`pm env` excludes inherited process variables, including credentials. Its
output can still reveal local installation paths; review it before sharing.
diff --git a/website/docs/user-guide/git-worktrees.md b/website/docs/user-guide/git-worktrees.md
index 675f677f8f6..08d0bab6b28 100644
--- a/website/docs/user-guide/git-worktrees.md
+++ b/website/docs/user-guide/git-worktrees.md
@@ -258,6 +258,8 @@ worktrees:
archive_max_file_mb: 50 # untracked files above this are not archived; their tree is kept
archive_retention_days: 30 # 0 keeps archives forever
max_total_gb: 0 # optional budget for idle trees; oldest are archived + removed first
+ install_state_retention_days: 14 # dependency state of a missing checkout outside .worktrees/ and
+ # the data root, unused this long, is reclaimed; 0 keeps it forever
```
There is no limit on how many trees may exist: hundreds of parallel subagents