The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.pyindex 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 Nonedef 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.pyindex 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: floaif 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})")+ continueif lock_state == "dead":_git_quiet(["worktree", "unlock", str(entry)], repo_root,diff --git a/hermes_cli/worktree_sweep.py b/hermes_cli/worktree_sweep.pyindex 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 archivworking state to ``refs/hermes/archive/<tree>`` (``worktree_archive``); a failed archive keepsthe 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 theclassic 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_REASONreturn "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", whyelse: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_untrackedRaises ``ArchiveError`` (tree untouched) when the snapshot fails. Right after the snapshot thetree 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 branchsurvives 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_removalfrom hermes_cli._subprocess_compat import noninteractive_git_envstarted = 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 captureif busy:logger.warning("Archived %s to %s but keeping it: %s", path, arc.ref, busy)return arc.ref, None, Falsediff --git a/tests/hermes_cli/test_worktree_snapshot_prune.py b/tests/hermes_cli/test_worktree_snapshot_prune.pyindex 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_sweepfrom hermes_cli.worktree_archive import ArchiveError, snapshot_worktreesub_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.pyindex 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) -> dif prune and payload["commits"] == 0 and not payload["dirty"]:cwd = info.get("repo_root", "") or pathtry:- 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 payloadrelease_lsp_clients(path) # the child ran in-process: its language servers are oursremoved = _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.mdindex 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 thetree's `HEAD`, staged changes, unstaged changes and untracked files (files your