Skip to content

The agent that grows with you

fix: worktree sweep never archives or removes a tree with a submodule

Tekniumd413d8b1b713
diff --git a/hermes_cli/worktree_archive.py b/hermes_cli/worktree_archive.py
index ad622a0177d..89ef372f0c7 100644
--- a/hermes_cli/worktree_archive.py
+++ b/hermes_cli/worktree_archive.py
@@ -177,43 +177,24 @@ def _untracked(wt: Path, env) -> list[str]:
SUBMODULE_REASON = "submodule "
-def submodule_work(wt_path, _depth: int = 0) -> Optional[str]:
- """Why an initialized submodule of *wt_path* holds work a snapshot cannot carry, or None.
-
- A snapshot records a submodule only as its ``160000`` gitlink, and removing the worktree
- deletes the submodule checkout and its per-worktree ``modules/`` repository. So a populated
- submodule that is dirty (tracked or untracked), checked out at another commit than recorded,
- or holding any commit/stash no remote-tracking ref has, keeps the tree. Uninitialized
- submodules, and clean ones whose commits all exist on a remote, are safe. Read-only.
+def submodule_work(wt_path, *, gitlinks: bool = True) -> Optional[str]:
+ """Why a submodule keeps *wt_path*, or None. Read-only.
+
+ An archive records a submodule only as its ``160000`` gitlink, and removing the tree deletes
+ its per-worktree ``modules/`` repositories (kept by ``git submodule deinit``, private branches
+ included). Until submodules are archived recursively: no tree with a gitlink is archived
+ (*gitlinks*), and no tree whose ``modules/`` holds a repository or whose gitlink is checked out
+ is removed at all.
"""
wt = Path(wt_path)
- env = _env(wt)
- env["GIT_OPTIONAL_LOCKS"] = "0"
+ env = {**_env(wt), "GIT_OPTIONAL_LOCKS": "0"}
+ modules = Path(_ok(["rev-parse", "--absolute-git-dir"], wt, env).strip()) / "modules"
+ if modules.is_dir() and any(modules.iterdir()):
+ return f"{SUBMODULE_REASON}repository in {modules} would be deleted with the tree"
staged = _ok(["ls-files", "--stage", "-z"], wt, env)
links = [e.split("\t", 1)[1] for e in staged.split("\0") if e.startswith("160000 ") and "\t" in e]
- populated = [p for p in dict.fromkeys(links) if (wt / p / ".git").exists()]
- if not populated:
- return None
- # --ignore-submodules=none overrides diff.ignoreSubmodules/.gitmodules ignore=all; the S flags
- # (C = new commit, M = tracked changes, U = untracked files) recurse into nested submodules.
- status = _ok(["status", "--porcelain=v2", "-z", "-uno", "--no-renames", "--ignore-submodules=none"], wt, env)
- for entry in status.split("\0"):
- fields = entry.split(" ")
- if entry[:2] in ("1 ", "2 ", "u ") and len(fields) > 2 and fields[2].startswith("S") \
- and fields[2] != "S...":
- path = entry.split(" ", 10 if entry[0] == "u" else (9 if entry[0] == "2" else 8))[-1]
- return f"{SUBMODULE_REASON}{path.split(chr(9))[0]} has uncommitted work or a new commit"
- for rel in populated:
- sub = wt / rel
- senv = _env(sub)
- local_only = _ok(["rev-list", "-n1", "--all", "--not", "--remotes"], sub, senv).strip()
- if local_only:
- return f"{SUBMODULE_REASON}{rel} has commits or stashes on no remote"
- if _depth < 8:
- nested = submodule_work(sub, _depth + 1)
- if nested:
- return nested.replace(SUBMODULE_REASON, f"{SUBMODULE_REASON}{rel}/", 1)
- return None
+ kept = [p for p in links if gitlinks or (wt / p / ".git").exists()]
+ return f"{SUBMODULE_REASON}{kept[0]} cannot be archived (gitlink only)" if kept else None
def staged_state(wt_path) -> str:
@@ -276,8 +257,7 @@ def snapshot_worktree(repo_root: str, wt_path, *, reason: str, max_untracked_mb:
"""
wt = Path(wt_path)
env = _env(wt)
- # Shared refusal point (sweep, exit-time Archive, subagent finalization): a gitlink records
- # no submodule work, and removing the tree would delete it.
+ # Shared refusal point (sweep, exit-time Archive, subagent finalization).
unsafe = submodule_work(wt)
if unsafe:
raise ArchiveError(unsafe)
diff --git a/hermes_cli/worktree_ops.py b/hermes_cli/worktree_ops.py
index 3563b9cbc1e..9781934a3bf 100644
--- a/hermes_cli/worktree_ops.py
+++ b/hermes_cli/worktree_ops.py
@@ -1013,6 +1013,16 @@ def _classify_prune_candidates(repo_root: str, candidates: list) -> list:
_PRESERVE_REASONS = {"dirty": "uncommitted changes", "unpushed": "unpushed commits"}
+def submodule_blocks_removal(path: str, gitlinks: bool = False) -> Optional[str]:
+ """Why a submodule keeps the tree at *path* (``worktree_archive.submodule_work``); an
+ unreadable tree counts as blocked."""
+ from hermes_cli.worktree_archive import ArchiveError, submodule_work
+ try:
+ return submodule_work(path, gitlinks=gitlinks)
+ except (ArchiveError, OSError, subprocess.SubprocessError) as exc:
+ return f"submodule check failed: {exc}"
+
+
def _reap_prune_verdicts(repo_root: str, verdicts: list, stale_work_cutoff: float) -> tuple[list, set]:
"""Phase 3, serial unlock / remove / branch -D -> ``(preserved_stale, kept_branches)``.
@@ -1030,6 +1040,10 @@ def _reap_prune_verdicts(repo_root: str, verdicts: list, stale_work_cutoff: floa
if verdict == "locked-live":
logger.debug("Skipping live-locked worktree: %s", entry.name)
continue
+ why = submodule_blocks_removal(str(entry))
+ if why:
+ preserved_stale.append(f"{entry.name} ({why})")
+ continue
if lock_state == "dead":
_git_quiet(["worktree", "unlock", str(entry)], repo_root,
diff --git a/hermes_cli/worktree_sweep.py b/hermes_cli/worktree_sweep.py
index f2d3750635a..39972f228b4 100644
--- a/hermes_cli/worktree_sweep.py
+++ b/hermes_cli/worktree_sweep.py
@@ -6,8 +6,8 @@ tiers and classifier, then removes an idle dirty/unpushed tree only after archiv
working state to ``refs/hermes/archive/<tree>`` (``worktree_archive``); a failed archive keeps
the tree. Never touched, at any age or budget: Kanban ``t_<hex>`` trees, trees whose ``hermes``
lock owner still runs, trees any live process sits in (cwd or open file), and trees with file or
-ref activity younger than their tier, and trees whose initialized submodules hold work
-(``keep-submodule-work``: an archive records only the gitlink). With ``archive_dirty: false`` and no size budget the
+ref activity younger than their tier, and trees with a submodule (``keep-submodule-work``: an
+archive records only the gitlink; see ``worktree_archive.submodule_work``). With ``archive_dirty: false`` and no size budget the
classic pruner runs unchanged.
``plan_sweep`` is read-only (``hermes worktree prune --dry-run`` prints it); ``execute_plan``
@@ -197,8 +197,7 @@ def _tier_hours(name: str, max_age_hours: float) -> float:
def _unarchivable_action(why: str) -> str:
- """``keep-submodule-work`` for submodule edits/commits a gitlink cannot carry, else
- ``keep-unarchivable``."""
+ """``keep-submodule-work`` for a submodule a gitlink cannot carry, else ``keep-unarchivable``."""
from hermes_cli.worktree_archive import SUBMODULE_REASON
return "keep-submodule-work" if why.startswith(SUBMODULE_REASON) else "keep-unarchivable"
@@ -295,6 +294,8 @@ def plan_sweep(repo_root: str, max_age_hours: int = 24, settings: Optional[dict]
repo_root, entry, verdict, lock_state, settings, tier, now)
if active:
d.age_hours = min(d.age_hours, round((now - active) / 3600, 1))
+ elif why := ops.submodule_blocks_removal(str(entry)):
+ d.action, d.reason = "keep-submodule-work", why
else:
d.action = "remove-keep-branch" if verdict == "reap-keep-branch" else "remove"
d.reason = "pushed to origin; branch kept" if verdict == "reap-keep-branch" else "clean and merged/pushed"
@@ -359,16 +360,18 @@ def archive_then_remove(repo_root: str, path: str, *, reason: str, max_untracked
Raises ``ArchiveError`` (tree untouched) when the snapshot fails. Right after the snapshot the
tree is checked again: a process (other than *exclude_pids*) now working in it, any edit
- made while the snapshot ran, or staged entries that differ from the captured index keep the tree (``removed`` False; the archive stays). The branch
+ made while the snapshot ran, staged entries that differ from the captured index, or a submodule
+ that appeared meanwhile keep the tree (``removed`` False; the archive stays). The branch
survives when it is protected or published on a remote (an open PR may still need it);
otherwise the archive ref anchors its commits and the local branch is deleted.
"""
from hermes_cli.worktree_archive import snapshot_worktree
- from hermes_cli.worktree_ops import _git, _git_quiet, release_lsp_clients
+ from hermes_cli.worktree_ops import _git, _git_quiet, release_lsp_clients, submodule_blocks_removal
from hermes_cli._subprocess_compat import noninteractive_git_env
started = time.time()
arc = snapshot_worktree(repo_root, path, reason=reason, max_untracked_mb=max_untracked_mb)
- busy = _in_use_since(path, started, exclude=exclude_pids) or _index_moved(path, arc.staged)
+ busy = (_in_use_since(path, started, exclude=exclude_pids) or _index_moved(path, arc.staged)
+ or submodule_blocks_removal(path, gitlinks=True)) # a submodule set up during capture
if busy:
logger.warning("Archived %s to %s but keeping it: %s", path, arc.ref, busy)
return arc.ref, None, False
diff --git a/tests/hermes_cli/test_worktree_snapshot_prune.py b/tests/hermes_cli/test_worktree_snapshot_prune.py
index eed30e5b3bc..595b6b5ba29 100644
--- a/tests/hermes_cli/test_worktree_snapshot_prune.py
+++ b/tests/hermes_cli/test_worktree_snapshot_prune.py
@@ -206,11 +206,13 @@ def test_a_tree_resumed_mid_sweep_is_never_removed(repo, monkeypatch, capsys):
"archived, kept (changed during the sweep) → refs/hermes/archive/lane-staged"]
-def test_dirty_submodule_work_is_never_archived_away(repo, tmp_path):
- """C1: a snapshot records a submodule only as its gitlink, so a tree whose initialized
- submodule holds uncommitted edits survives the real sweep byte-for-byte, and the shared
- snapshot entry point (exit-time Archive, subagent finalization) refuses it too. A tree whose
- submodule is clean at the recorded commit is still archived and removed."""
+def test_dirty_submodule_work_is_never_archived_away(repo, tmp_path, monkeypatch):
+ """C1: a snapshot records a submodule only as its gitlink, and removing a tree deletes its
+ ``modules/`` repositories. So the real sweep keeps, byte-for-byte: a tree with a dirty
+ submodule; a deinitialized one whose retained module repository holds an unpushed private
+ commit; and one whose submodule file is edited right after the snapshot step. The shared
+ snapshot entry point (exit-time Archive, subagent finalization) refuses them too."""
+ from hermes_cli import worktree_archive, worktree_sweep
from hermes_cli.worktree_archive import ArchiveError, snapshot_worktree
sub_origin, sub_work = tmp_path / "sub.git", tmp_path / "subwork"
@@ -223,24 +225,45 @@ def test_dirty_submodule_work_is_never_archived_away(repo, tmp_path):
_git(["-c", "protocol.file.allow=always", "submodule", "add", "-q", str(sub_origin), "sub"], repo)
_git(["commit", "-qm", "add submodule"], repo)
trees = {}
- for name in ("lane-subdirty", "lane-subclean"):
+ for name in ("lane-subdirty", "lane-deinit", "lane-late"):
trees[name] = _tree(repo, name, dirty=True)
_git(["-c", "protocol.file.allow=always", "submodule", "update", "-q", "--init"], trees[name])
dirty_file = trees["lane-subdirty"] / "sub" / "file.txt"
dirty_file.write_bytes(b"base\nUNCOMMITTED SUBMODULE EDIT\r\n")
+ deinit_sub = trees["lane-deinit"] / "sub"
+ module_repo = Path(_git(["rev-parse", "--absolute-git-dir"], deinit_sub))
+ _git(["switch", "-qc", "private-work"], deinit_sub)
+ (deinit_sub / "file.txt").write_text("UNPUSHED\n", encoding="utf-8")
+ _git(["commit", "-qam", "private"], deinit_sub)
+ private = _git(["rev-parse", "HEAD"], deinit_sub)
+ _git(["checkout", "-q", "--detach", "origin/main"], deinit_sub)
+ _git(["submodule", "deinit", "-q", "sub"], trees["lane-deinit"])
for tree in trees.values():
_idle(tree)
- from hermes_cli import worktree_sweep
+ late_file, late_bytes = trees["lane-late"] / "sub" / "file.txt", [b"base\n"]
+ real_snapshot = worktree_archive.snapshot_worktree
+
+ def snapshot_then_submodule_edit(repo_root, wt_path, **kw):
+ try:
+ return real_snapshot(repo_root, wt_path, **kw)
+ finally:
+ if Path(wt_path).name == "lane-late":
+ late_bytes.append(b"LATE SUBMODULE EDIT\n")
+ late_file.write_bytes(late_bytes[-1])
+
+ monkeypatch.setattr(worktree_archive, "snapshot_worktree", snapshot_then_submodule_edit)
plan = {d.name: d.action for d in worktree_sweep.plan_sweep(str(repo), settings=worktree_sweep.sweep_settings())}
- assert plan == {"lane-subdirty": "keep-submodule-work", "lane-subclean": "archive-remove"}
+ assert set(plan.values()) == {"keep-submodule-work"}
worktree_ops._prune_stale_worktrees(str(repo))
assert dirty_file.read_bytes() == b"base\nUNCOMMITTED SUBMODULE EDIT\r\n"
- assert not trees["lane-subclean"].exists(), "a clean submodule at the recorded commit is archivable"
- assert [ref.rsplit("/", 1)[-1] for ref in _archives(repo)] == ["lane-subclean"]
- with pytest.raises(ArchiveError, match="submodule sub"):
- snapshot_worktree(str(repo), trees["lane-subdirty"], reason="session exit")
+ assert _git(["--git-dir", str(module_repo), "rev-parse", "private-work"], repo) == private
+ assert late_file.read_bytes() == late_bytes[-1]
+ assert _archives(repo) == []
+ for tree in trees.values():
+ with pytest.raises(ArchiveError, match="submodule"):
+ snapshot_worktree(str(repo), tree, reason="session exit")
def test_prune_older_than_bounds_what_the_sweep_removes(repo, capsys):
diff --git a/tools/subagent_worktree.py b/tools/subagent_worktree.py
index 2af985fbc6b..378b0e8c1f9 100644
--- a/tools/subagent_worktree.py
+++ b/tools/subagent_worktree.py
@@ -185,7 +185,9 @@ def finalize_subagent_worktree(info: dict[str, str], *, prune: bool = True) -> d
if prune and payload["commits"] == 0 and not payload["dirty"]:
cwd = info.get("repo_root", "") or path
try:
- from hermes_cli.worktree_ops import release_lsp_clients
+ from hermes_cli.worktree_ops import release_lsp_clients, submodule_blocks_removal
+ if submodule_blocks_removal(path): # a module repository dies with the tree
+ return payload
release_lsp_clients(path) # the child ran in-process: its language servers are ours
removed = _run_git(["worktree", "remove", "--force", path], cwd=cwd)
if removed.returncode == 0:
diff --git a/website/docs/user-guide/git-worktrees.md b/website/docs/user-guide/git-worktrees.md
index 9156bdb5b91..b175d86a634 100644
--- a/website/docs/user-guide/git-worktrees.md
+++ b/website/docs/user-guide/git-worktrees.md
@@ -213,7 +213,7 @@ repositories' `.worktrees/`:
| A live hermes lock owner, or any live process whose cwd (Linux: or an open file) is inside | never touched |
| File, `HEAD` or reflog activity younger than its tier (a deleted file counts through its folder) | never touched |
| Kanban task trees (`t_<hex>`) | never touched (the Kanban GC owns them) |
-| An initialized submodule with uncommitted edits, a different commit than recorded, or commits on no remote | kept (`keep-submodule-work`: an archive records only the submodule pointer) |
+| Any submodule: a gitlink in the index, or a submodule repository kept under the tree's `modules/` (even after `git submodule deinit`) | kept (`keep-submodule-work`: an archive records only the submodule pointer). A clean merged tree is removed only if its submodules were never initialized |
An archive is a commit stored at `refs/hermes/archive/<tree>` holding the
tree's `HEAD`, staged changes, unstaged changes and untracked files (files your