The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix: worktree sweep keeps any tree holding work an archive cannot restore
Tekniumab1c29d8bbd0
diff --git a/cli-config.yaml.example b/cli-config.yaml.exampleindex bbb132c0b94..0a1fe3d98c1 100644--- a/cli-config.yaml.example+++ b/cli-config.yaml.example@@ -397,7 +397,7 @@ model:# refs/hermes/archive/<tree> and removed; `hermes worktree restore <name>` brings one back.# worktrees:# archive_dirty: true # false = never remove dirty/unpushed trees (old behaviour)-# archive_max_file_mb: 50 # untracked files above this are listed, not archived+# archive_max_file_mb: 50 # untracked files above this are not archived; their tree is kept# archive_retention_days: 30 # archive refs older than this are deleted (0 = keep)# max_total_gb: 0 # optional budget for idle trees; oldest evicted firstdiff --git a/cli.py b/cli.pyindex d6afbd3f052..ee6bc1f2d34 100644--- a/cli.py+++ b/cli.py@@ -577,6 +577,12 @@ def _cleanup_worktree(info: dict[str, str] | None = None) -> None:print(f" {_t('cli.worktree.clean_up_manually', path=wt_path)}")return+ from hermes_cli.worktree_ops import removal_blocked+ blocked = removal_blocked(wt_path) # an embedded repo, private ref or ignored file dies with it+ if blocked:+ _cprint(f"\n\033[33m{_t('cli.worktree.kept_reason', path=wt_path, reason=blocked[1])}\033[0m")+ return+# Release the tree's language servers while the path still exists, then unlock so `remove`# isn't blocked by the lock placed at creation. Fail-soft.release_lsp_clients(wt_path)diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.pyindex 203517890d8..42e1787c44c 100644--- a/hermes_cli/config_defaults.py+++ b/hermes_cli/config_defaults.py@@ -500,7 +500,7 @@ DEFAULT_CONFIG = {"worktrees": {# false = never remove a dirty/unpushed tree (the pre-archive behaviour, exactly)."archive_dirty": True,- # Untracked files larger than this (MB) are left out of the archive and listed in it.+ # 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."archive_retention_days": 30,diff --git a/hermes_cli/worktree_archive.py b/hermes_cli/worktree_archive.pyindex 89ef372f0c7..2ebcc5eda92 100644--- a/hermes_cli/worktree_archive.py+++ b/hermes_cli/worktree_archive.py@@ -11,8 +11,10 @@ Bytes are stored raw: every tracked/untracked regular file is re-hashed with``hash-object --no-filters`` and restored by writing the blob bytes directly, so no attributesource (``.gitattributes``, ``$GIT_COMMON_DIR/info/attributes``, ``core.attributesFile``) and noclean/smudge/eol conversion can change them; a restore writes back exactly the archived bytes. Untracked files over a size cap are skipped and listed-(so ``.git`` never balloons with build artefacts the ignore rules missed); an untracked embedded-repository cannot be captured at all and fails the snapshot, which keeps the tree.+(so ``.git`` never balloons with build artefacts the ignore rules missed), and a tree with a+skipped file is never removed; an untracked embedded repository cannot be captured at all and+fails the snapshot, which keeps the tree. Ignored files are not captured: removal is allowed only+when every one is reproducible (``worktree_retention``)."""from __future__ import annotations@@ -213,16 +215,17 @@ def _digest_index(wt: Path, env) -> str:return hashlib.sha256(_ok(["ls-files", "--stage", "-z"], wt, env).encode("utf-8", "surrogateescape")).hexdigest()-def archive_preflight(wt_path) -> Optional[str]:- """Why *wt_path* cannot be snapshotted losslessly, or None. Read-only."""+def archive_preflight(wt_path, max_untracked_mb: float = 50) -> Optional[tuple[str, str]]:+ """``(keep-action, reason)`` when archiving and removing *wt_path* would lose something+ (``worktree_retention.removal_blocker``: submodule, embedded repository, per-worktree ref,+ an untracked file over the size cap, a non-reproducible ignored file), else None. Read-only."""+ from hermes_cli.worktree_retention import KEEP_UNARCHIVABLE, removal_blockertry:wt = Path(wt_path)- embedded = [p for p in _untracked(wt, _env(wt)) if p.endswith("/")]- if not embedded:- return submodule_work(wt)+ skipped = _split_oversized(wt, _untracked(wt, _env(wt)), max_untracked_mb)except (ArchiveError, OSError, subprocess.SubprocessError) as exc:- return str(exc)- return f"untracked embedded repository {embedded[0].rstrip('/')} cannot be archived"+ return KEEP_UNARCHIVABLE, str(exc)+ return removal_blocker(wt, skipped=skipped, gitlinks=True)def _split_oversized(wt: Path, untracked: list[str], max_mb: float) -> list[dict]:diff --git a/hermes_cli/worktree_cmd.py b/hermes_cli/worktree_cmd.pyindex 71017e046cf..37100b945dd 100644--- a/hermes_cli/worktree_cmd.py+++ b/hermes_cli/worktree_cmd.py@@ -95,8 +95,9 @@ def _sweep(repo_root: str, dry_run: bool, older_than: Optional[float] = None) ->from hermes_cli.worktree_archive import prune_expired_archivesexpired = prune_expired_archives(repo_root, settings["archive_retention_days"])from agent.i18n import t- saved = [t("cli.worktree.sweep_archived_removed" if removed else "cli.worktree.sweep_archived_kept", ref=ref)- for ref, removed in archived]+ saved = [t("cli.worktree.sweep_archived_removed", ref=ref) if removed+ else t("cli.worktree.sweep_archived_kept", ref=ref, reason=why or "?")+ for ref, removed, why in archived]return plan, saved + [f"deleted expired archive {r}" for r in expired]diff --git a/hermes_cli/worktree_exit.py b/hermes_cli/worktree_exit.pyindex be63c0eaa9b..dcd31d6f7ed 100644--- a/hermes_cli/worktree_exit.py+++ b/hermes_cli/worktree_exit.py@@ -94,14 +94,17 @@ def apply_exit_choice(info: dict, echo) -> bool:from hermes_cli.worktree_sweep import archive_then_remove, sweep_settingsecho(t("cli.worktree.archiving", path=path))try:- ref, _kept, removed = archive_then_remove(+ ref, _kept, removed, why = archive_then_remove(repo_root, path, reason="session exit", unlock=True, exclude_pids=(os.getpid(),),max_untracked_mb=sweep_settings()["archive_max_file_mb"])except (ArchiveError, OSError, subprocess.SubprocessError, KeyboardInterrupt) as exc:echo(f"\033[31m{t('cli.worktree.archive_failed', path=path, error=str(exc) or 'interrupted')}\033[0m")return Truename = ref.rsplit("/", 1)[-1]- echo(f"\033[32m{t('cli.worktree.archived' if removed else 'cli.worktree.archived_kept', path=path, ref=ref)}\033[0m")+ if removed:+ echo(f"\033[32m{t('cli.worktree.archived', path=path, ref=ref)}\033[0m")+ else:+ echo(f"\033[33m{t('cli.worktree.archived_kept', path=path, ref=ref, reason=why or '?')}\033[0m")echo(f" {t('cli.worktree.restore_hint', name=name)}")return Truefrom hermes_cli._subprocess_compat import noninteractive_git_envdiff --git a/hermes_cli/worktree_gc.py b/hermes_cli/worktree_gc.pyindex 0ea4b6df90e..8fdfe8458c9 100644--- a/hermes_cli/worktree_gc.py+++ b/hermes_cli/worktree_gc.py@@ -97,11 +97,15 @@ def _tree_size_mb(path: Path, timeout: int = 30) -> Optional[int]:def _dirty_split(path: str) -> tuple[bool, list[str]]:"""(has_tracked_modifications, untracked_paths) — tracked = real work, untracked = archivable."""try:- result = _git(["status", "--porcelain"], cwd=path, timeout=10)+ result = _git(["status", "--porcelain", "--untracked-files=normal"], cwd=path, timeout=10)if result.returncode != 0:return True, [] # fail safe: treat as real worklines = [line for line in result.stdout.splitlines() if line.strip()]untracked = [line[3:].strip() for line in lines if line.startswith("??")]+ if len(untracked) == len(lines):+ from hermes_cli.worktree_retention import hidden_index_edits+ if hidden_index_edits(path): # skip-worktree / assume-unchanged edits+ return True, []return len(untracked) != len(lines), untrackedexcept Exception:return True, []@@ -146,9 +150,15 @@ def _classify_tree(_ops, repo_root: str, entry: Path, merge_cache, remote_heads)# as unpushed forever. A head EXACTLY matching the remote branch has nothing origin lacks.if not _ops._worktree_branch_pushed_exact(path, remote_heads, timeout=10):return "keep", "unpushed commits not found upstream", []+ blocked = _ops.removal_blocked(path)+ if blocked:+ return "keep", blocked[1], []if untracked:return "reap-keep-branch", f"pushed to origin (open-PR lane); branch kept; {archive_note}", untrackedreturn "reap-keep-branch", "pushed to origin (open-PR lane); branch kept", []+ blocked = _ops.removal_blocked(path)+ if blocked:+ return "keep", blocked[1], []if untracked:return "reap-archive", f"merged/pushed; {archive_note}", untrackedreturn "reap", "clean and fully merged/pushed", []diff --git a/hermes_cli/worktree_ops.py b/hermes_cli/worktree_ops.pyindex 9781934a3bf..e338d3ee47d 100644--- a/hermes_cli/worktree_ops.py+++ b/hermes_cli/worktree_ops.py@@ -558,7 +558,9 @@ def _worktree_is_dirty(worktree_path: str, repo_root, timeout: int = 10) -> boolUntracked ``.worktreeinclude`` directory symlinks back to the main checkout *repo_root* areignored: they are our own scaffolding, and counting them would keep every worktree of such a- repo forever.+ repo forever. ``status.showUntrackedFiles=no`` is overridden (it would hide new files), and+ skip-worktree / assume-unchanged files whose bytes differ from the index count as changes+ (``git status`` trusts both flags)."""from hermes_cli._subprocess_compat import noninteractive_repo_git_envtry:@@ -566,13 +568,14 @@ def _worktree_is_dirty(worktree_path: str, repo_root, timeout: int = 10) -> boolenv = noninteractive_repo_git_env(worktree_path)if env is None:return True- result = _git(["status", "--porcelain", "-z"], worktree_path, timeout=timeout,- stdin=subprocess.DEVNULL, env=env)+ result = _git(["status", "--porcelain", "-z", "--untracked-files=normal"], worktree_path,+ timeout=timeout, stdin=subprocess.DEVNULL, env=env)if result.returncode != 0:return Trueentries = [e for e in result.stdout.split("\0") if e]if not entries:- return False+ from hermes_cli.worktree_retention import hidden_index_edits+ return bool(hidden_index_edits(worktree_path))if any(not e.startswith("?? ") for e in entries):return Trueinclude_links = _include_symlink_paths(worktree_path, repo_root)@@ -1013,14 +1016,13 @@ 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 removal_blocked(path: str) -> Optional[tuple[str, str]]:+ """``(keep-action, reason)`` when deleting the clean tree at *path* would lose something no+ branch holds (``worktree_retention.removal_blocker``: a checked-out submodule, an embedded+ repository, a per-worktree ref, an ignored file that is not reproducible); unverifiable+ counts as blocked."""+ from hermes_cli.worktree_retention import removal_blocker+ return removal_blocker(path)def _reap_prune_verdicts(repo_root: str, verdicts: list, stale_work_cutoff: float) -> tuple[list, set]:@@ -1040,9 +1042,9 @@ 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})")+ blocked = removal_blocked(str(entry))+ if blocked:+ preserved_stale.append(f"{entry.name} ({blocked[1]})")continueif lock_state == "dead":diff --git a/hermes_cli/worktree_retention.py b/hermes_cli/worktree_retention.pynew file mode 100644index 00000000000..2f231635913--- /dev/null+++ b/hermes_cli/worktree_retention.py@@ -0,0 +1,246 @@+"""What a worktree holds that neither git nor an archive can bring back.++Every path that deletes a tree (the sweep, the classic clean-tree pruner, exit-time Archive,+subagent finalization, the attended ``hermes worktree prune``) asks :func:`removal_blocker`+first; anything it names keeps the tree. The rule: a tree may only be removed when everything+that is not reproducible is in git or in the archive. Not reproducible:++* an embedded repository anywhere below the tree, ignored or not (``build/tool/.git``, a nested+ worktree): its private commits live only on disk (``keep-unarchivable``);+* a commit held only by a per-worktree ref (``refs/worktree/*``, ``refs/bisect/*``,+ ``refs/rewritten/*``), which dies with the tree's admin dir (``keep-worktree-refs``);+* an untracked file the snapshot skipped for size (``keep-large-untracked``);+* an ignored file, unless it lies under a well-known regenerable directory+ (:data:`REGENERABLE_DIRS`) or is a byte-identical copy of the same path in the main checkout+ (what ``.worktreeinclude`` copies, e.g. ``.env``) (``keep-ignored-work``).++:func:`hidden_index_edits` finds skip-worktree / assume-unchanged files whose bytes differ from+the index: ``git status`` never reports them, so dirty checks must add them.+"""++from __future__ import annotations++import filecmp+import os+import subprocess+from dataclasses import dataclass, field+from pathlib import Path+from typing import Optional++# Ignored content under these directory names is regenerated by a build/install/test run.+REGENERABLE_DIRS = frozenset({+ "node_modules", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",+ ".tox", "dist", "build", "target", ".next", ".turbo", ".cache", "coverage", ".gradle",+})+# Dependency stores and caches: never descended, not even to look for an embedded repository.+_OPAQUE_DIRS = frozenset({+ "node_modules", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",+ ".tox", ".next", ".turbo", ".cache", ".gradle",+})+_PER_WORKTREE_REFS = ("refs/worktree/", "refs/bisect/", "refs/rewritten/")+_MAX_ENTRIES = 200_000 # per tree; past this the ignored content is unverifiable -> keep+_NAMED = 5 # offenders named in a reason++KEEP_UNARCHIVABLE = "keep-unarchivable"+KEEP_WORKTREE_REFS = "keep-worktree-refs"+KEEP_LARGE_UNTRACKED = "keep-large-untracked"+KEEP_IGNORED_WORK = "keep-ignored-work"+KEEP_SUBMODULE_WORK = "keep-submodule-work"+++def _regenerable(rel: str) -> bool:+ return any(part in REGENERABLE_DIRS or part.endswith(".egg-info") for part in rel.split("/"))+++def _env(wt: Path) -> dict:+ from hermes_cli.worktree_archive import _env as archive_env+ return {**archive_env(wt), "GIT_OPTIONAL_LOCKS": "0"}+++def _git(args, wt: Path, env, timeout: float = 120) -> str:+ from hermes_cli.worktree_archive import _ok+ return _ok(args, wt, env, timeout=timeout)+++def main_checkout(wt: Path, env) -> Optional[Path]:+ """The repository's main working tree (``<common-dir>/..``), or None for a bare repo."""+ common = Path(_git(["rev-parse", "--path-format=absolute", "--git-common-dir"], wt, env).strip())+ return common.parent if common.name == ".git" and common.parent.is_dir() else None+++def _same_as_main(path: Path, rel: str, main: Optional[Path]) -> bool:+ """*path* is byte-identical to (or a symlink equal to / pointing at) *rel* in *main*."""+ if main is None:+ return False+ twin = main / rel+ try:+ if path.is_symlink():+ if twin.is_symlink() and os.readlink(path) == os.readlink(twin):+ return True+ return path.resolve() == twin.resolve() # a .worktreeinclude link back to the main checkout+ return twin.is_file() and not twin.is_symlink() and filecmp.cmp(path, twin, shallow=False)+ except OSError:+ return False+++@dataclass+class _Scan:+ embedded: list = field(default_factory=list)+ ignored: list = field(default_factory=list)+ entries: int = 0+ truncated: bool = False+++def _walk(scan: _Scan, wt: Path, rel_dir: str, main: Optional[Path], *, files: bool) -> None:+ """Below ignored *rel_dir*: record nested ``.git`` entries and (when *files*) every file+ that is neither regenerable nor identical to the main checkout. Symlinks are not followed."""+ stack = [rel_dir]+ while stack and not scan.truncated:+ rel = stack.pop()+ try:+ entries = list(os.scandir(wt / rel))+ except OSError:+ continue+ for entry in entries:+ scan.entries += 1+ if scan.entries > _MAX_ENTRIES:+ scan.truncated = True+ return+ child = f"{rel}/{entry.name}"+ if entry.name == ".git":+ scan.embedded.append(rel)+ continue+ if entry.is_dir(follow_symlinks=False):+ if entry.name not in _OPAQUE_DIRS:+ stack.append(child)+ elif files and not _regenerable(child) and not _same_as_main(Path(entry.path), child, main):+ scan.ignored.append(child)+++def scan_tree(wt_path) -> _Scan:+ """Embedded repositories and non-reproducible ignored files of *wt_path*. Read-only.++ Untracked non-ignored repositories are reported by ``ls-files`` itself (``dir/``); ignored+ ones hide inside collapsed ignored directories, so those are walked (bounded; dependency+ stores are never descended). Raises ``ArchiveError`` when git fails.+ """+ wt = Path(wt_path)+ env = _env(wt)+ scan = _Scan()+ # Without --directory git descends untracked dirs and lists each embedded repository as "dir/".+ untracked = _git(["ls-files", "--others", "--exclude-standard", "-z"], wt, env)+ scan.embedded += [p.rstrip("/") for p in untracked.split("\0") if p.endswith("/")]+ out = _git(["ls-files", "--others", "--ignored", "--exclude-standard", "--directory",+ "--no-empty-directory", "-z"], wt, env)+ main = main_checkout(wt, env)+ for rel in (p for p in out.split("\0") if p):+ rel_clean = rel.rstrip("/")+ path = wt / rel_clean+ if rel.endswith("/") and not path.is_symlink():+ if rel_clean.rsplit("/", 1)[-1] in _OPAQUE_DIRS:+ continue+ if (path / ".git").exists():+ scan.embedded.append(rel_clean)+ continue+ _walk(scan, wt, rel_clean, main, files=not _regenerable(rel_clean))+ elif not _regenerable(rel_clean) and not _same_as_main(path, rel_clean, main):+ scan.ignored.append(rel_clean)+ if scan.truncated:+ break+ return scan+++def hidden_index_edits(wt_path, env=None) -> list[str]:+ """Skip-worktree / assume-unchanged paths whose disk state differs from the index.++ ``git status`` trusts both flags and reports nothing. A skip-worktree file missing from disk+ is a sparse checkout, not an edit; a missing assume-unchanged file is a deletion. Raises+ ``ArchiveError`` when git fails.+ """+ wt = Path(wt_path)+ env = env or _env(wt)+ flagged = []+ for record in _git(["ls-files", "-v", "-s", "-z"], wt, env).split("\0"):+ meta, _, rel = record.partition("\t")+ parts = meta.split()+ if not rel or len(parts) != 4 or not (parts[0] == "S" or parts[0].islower()):+ continue+ path = wt / rel+ if not os.path.lexists(path):+ if parts[0] != "S":+ flagged.append(rel) # assume-unchanged file deleted+ continue+ flagged.append((rel, parts[1], parts[2]))+ edits = [f for f in flagged if isinstance(f, str)]+ for rel, mode, sha in (f for f in flagged if not isinstance(f, str)):+ path = wt / rel+ if mode == "120000":+ data = os.readlink(path).encode("utf-8", "surrogateescape") if path.is_symlink() else None+ else:+ data = None if path.is_symlink() or not path.is_file() else path.read_bytes()+ if data is None:+ edits.append(rel) # type changed+ continue+ if _hash(wt, env, data, rel, raw=True) != sha and _hash(wt, env, data, rel, raw=False) != sha:+ edits.append(rel)+ return edits+++def _hash(wt: Path, env, data: bytes, rel: str, *, raw: bool) -> str:+ args = ["hash-object", "--stdin"] + (["--no-filters"] if raw else [f"--path={rel}"])+ result = subprocess.run(["git", *args], cwd=str(wt), env=env, input=data, capture_output=True,+ timeout=60, check=False)+ return result.stdout.decode("ascii", "replace").strip() if result.returncode == 0 else ""+++def private_worktree_refs(wt_path, env=None) -> list[str]:+ """Per-worktree refs of *wt_path* holding commits no branch, tag, remote or archive reaches.++ They live in the tree's admin dir and vanish with it. Raises ``ArchiveError`` when git fails.+ """+ wt = Path(wt_path)+ env = env or _env(wt)+ out = _git(["for-each-ref", "--format=%(refname)%00%(objectname)", *_PER_WORKTREE_REFS], wt, env)+ private = []+ for line in out.splitlines():+ name, _, sha = line.partition("\0")+ if sha and _git(["rev-list", "--max-count=1", sha, "--not", "--branches", "--tags", "--remotes",+ "--glob=refs/hermes/archive/*"], wt, env).strip():+ private.append(name)+ return private+++def _named(paths: list, more: bool = False) -> str:+ extra = len(paths) - _NAMED+ tail = f" (+{extra} more)" if extra > 0 else (" (+more)" if more else "")+ return ", ".join(paths[:_NAMED]) + tail+++def removal_blocker(wt_path, *, skipped: Optional[list] = None, gitlinks: bool = False+ ) -> Optional[tuple[str, str]]:+ """``(keep-action, reason)`` when removing *wt_path* would lose something, else None.++ *skipped* is the snapshot's ``skipped_untracked`` list (or the oversize files a preflight+ would skip). *gitlinks* refuses any submodule (archive paths); without it only a checked-out+ or retained module repository blocks. Any failure to verify blocks. Read-only.+ """+ from hermes_cli.worktree_archive import ArchiveError, submodule_work+ try:+ why = submodule_work(wt_path, gitlinks=gitlinks)+ if why:+ return KEEP_SUBMODULE_WORK, why+ scan = scan_tree(wt_path)+ if scan.embedded:+ return KEEP_UNARCHIVABLE, f"embedded repository {scan.embedded[0]} cannot be archived"+ refs = private_worktree_refs(wt_path)+ if refs:+ return KEEP_WORKTREE_REFS, f"per-worktree ref {_named(refs)} holds commits no branch has"+ if skipped:+ return KEEP_LARGE_UNTRACKED, f"untracked file(s) over the archive size cap: {_named([s['path'] for s in skipped])}"+ if scan.truncated:+ return KEEP_IGNORED_WORK, f"over {_MAX_ENTRIES} ignored entries; cannot verify they are reproducible"+ if scan.ignored:+ return KEEP_IGNORED_WORK, f"ignored file(s) not reproducible: {_named(scan.ignored)}"+ except (ArchiveError, OSError, subprocess.SubprocessError) as exc:+ return KEEP_UNARCHIVABLE, f"could not verify the tree is safe to remove: {exc}"+ return Nonediff --git a/hermes_cli/worktree_sweep.py b/hermes_cli/worktree_sweep.pyindex 39972f228b4..35c45835e2a 100644--- a/hermes_cli/worktree_sweep.py+++ b/hermes_cli/worktree_sweep.py@@ -6,9 +6,10 @@ 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 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.+ref activity younger than their tier, and trees holding anything an archive cannot carry+(``worktree_retention.removal_blocker``: a submodule, an embedded repository, a per-worktree ref,+an untracked file over the size cap, an ignored file that is not reproducible). 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``applies a frozen plan.@@ -196,12 +197,6 @@ def _tier_hours(name: str, max_age_hours: float) -> float:return prune_tier_hours(name, max_age_hours)-def _unarchivable_action(why: str) -> str:- """``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"--def _plan_survivor(repo_root: str, entry: Path, verdict: str, lock_state, settings: dict,tier_hours: float, now: float) -> tuple[str, str, Optional[str], Optional[float]]:"""(action, reason, lock_state, last_activity) for a dirty/unpushed tree past its tier."""@@ -216,13 +211,13 @@ def _plan_survivor(repo_root: str, entry: Path, verdict: str, lock_state, settinreturn "skip-young", f"{what}; last activity {(now - active) / 3600:.1f}h ago", lock_state, activeif not settings["archive_dirty"]:return f"keep-{verdict}", what, lock_state, active # idle: only the size budget may evict it- unsafe = archive_preflight(str(entry))+ unsafe = archive_preflight(str(entry), settings["archive_max_file_mb"])if unsafe:- return _unarchivable_action(unsafe), unsafe, lock_state, active+ return unsafe[0], unsafe[1], lock_state, activereturn "archive-remove", what, lock_state, active-def _apply_budget(decisions: list[Decision], max_total_gb: float) -> None:+def _apply_budget(decisions: list[Decision], max_total_gb: float, max_file_mb: float = 50) -> None:"""Evict the oldest idle kept trees (archive first) until they fit *max_total_gb*.Only idle past-tier trees count or move; live, young and kanban trees are invisible here.@@ -237,9 +232,9 @@ def _apply_budget(decisions: list[Decision], max_total_gb: float) -> None:for d in sorted(eligible, key=lambda x: x.mtime):if total <= budget_mb:break- unsafe = archive_preflight(d.path)+ unsafe = archive_preflight(d.path, max_file_mb)if unsafe:- d.action, d.reason = _unarchivable_action(unsafe), unsafe+ d.action, d.reason = unsafecontinued.action, d.reason = "archive-remove", f"{d.reason}; over worktrees.max_total_gb={max_total_gb:g}"total -= d.size_mb or 0@@ -294,14 +289,14 @@ 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+ elif blocked := ops.removal_blocked(str(entry)):+ d.action, d.reason = blockedelse: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"decisions.append(d)if settings["max_total_gb"]:- _apply_budget(decisions, settings["max_total_gb"])+ _apply_budget(decisions, settings["max_total_gb"], settings["archive_max_file_mb"])if older_than_days is not None:for d in decisions:if d.action in _DESTRUCTIVE and d.age_hours < older_than_days * 24:@@ -355,45 +350,49 @@ def _index_moved(path: str, captured: str) -> Optional[str]:def archive_then_remove(repo_root: str, path: str, *, reason: str, max_untracked_mb: float,unlock: bool, remote_heads_fn=None, keep_branch: bool = False,exclude_pids=(),- ) -> tuple[str, Optional[str], bool]:- """Snapshot *path*, then remove it -> ``(archive_ref, kept_branch, removed)``.+ ) -> tuple[str, Optional[str], bool, Optional[str]]:+ """Snapshot *path*, then remove it -> ``(archive_ref, kept_branch, removed, why_kept)``.Raises ``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, staged entries that differ from the captured index, or a submodule- that appeared meanwhile keep the tree (``removed`` False; the archive stays). The branch+ made while the snapshot ran, staged entries that differ from the captured index, or anything+ the archive does not hold (``worktree_retention.removal_blocker``: a file the snapshot skipped+ for size, an embedded repository, a per-worktree ref, a non-reproducible ignored file, a+ submodule) keep the tree (``removed`` False, *why_kept* says why; 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, submodule_blocks_removal+ from hermes_cli.worktree_ops import _git, _git_quiet, release_lsp_clients+ from hermes_cli.worktree_retention import removal_blockerfrom hermes_cli._subprocess_compat import noninteractive_git_envstarted = time.time()arc = snapshot_worktree(repo_root, path, reason=reason, max_untracked_mb=max_untracked_mb)+ blocked = removal_blocker(path, skipped=arc.meta.get("skipped_untracked"), gitlinks=True)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+ or (blocked and blocked[1]))if busy:logger.warning("Archived %s to %s but keeping it: %s", path, arc.ref, busy)- return arc.ref, None, False+ return arc.ref, None, False, busyrelease_lsp_clients(path)if unlock:_git_quiet(["worktree", "unlock", path], repo_root, log=f"unlock {path}")removed = _git(["worktree", "remove", "--force", path], repo_root, timeout=60)if removed.returncode != 0:logger.warning("Archived %s to %s but could not remove it: %s", path, arc.ref, removed.stderr.strip())- return arc.ref, None, False+ return arc.ref, None, False, removed.stderr.strip() or "git worktree remove failed"branch = arc.meta.get("branch")if not branch or keep_branch or branch in _PROTECTED_BRANCHES:- return arc.ref, branch, True+ return arc.ref, branch, True, Noneif remote_heads_fn is None:from hermes_cli.worktree_ops import _fetch_remote_branch_headsheads = _fetch_remote_branch_heads(repo_root, timeout=10)else:heads = remote_heads_fn()if _branch_published(repo_root, branch, heads):- return arc.ref, branch, True+ return arc.ref, branch, True, None_git(["branch", "-D", branch], repo_root, stdin=subprocess.DEVNULL, env=noninteractive_git_env())- return arc.ref, None, True+ return arc.ref, None, True, Nonedef _recheck(repo_root: str, d: Decision) -> tuple[Optional[str], Optional[str]]:@@ -418,10 +417,10 @@ def _recheck(repo_root: str, d: Decision) -> tuple[Optional[str], Optional[str]]def execute_plan(repo_root: str, plan: list[Decision], settings: dict- ) -> tuple[list[str], set, list[tuple[str, bool]]]:- """Apply a frozen plan -> ``(preserved_stale, kept_branches, [(archive_ref, removed)])``. Each- tree is re-gated (lock, live process, fresh activity) right before it is archived or removed;- ``removed`` is False when the archive was saved but the tree was kept (changed meanwhile)."""+ ) -> tuple[list[str], set, list[tuple[str, bool, Optional[str]]]]:+ """Apply a frozen plan -> ``(preserved_stale, kept_branches, [(archive_ref, removed, why_kept)])``.+ Each tree is re-gated (lock, live process, fresh activity) right before it is archived or+ removed; ``removed`` is False when the archive was saved but the tree was kept (*why_kept*)."""from hermes_cli import worktree_ops as opsfrom hermes_cli.worktree_archive import ArchiveErrormemo: dict = {}@@ -432,7 +431,7 @@ def execute_plan(repo_root: str, plan: list[Decision], settings: dictreturn memo["heads"]kept_branches: set = set()- archived: list[tuple[str, bool]] = []+ archived: list[tuple[str, bool, Optional[str]]] = []preserved: list[str] = [f"{d.name} ({d.reason})" for d in plan if d.action.startswith("keep-")]for d in (d for d in plan if d.action in _DESTRUCTIVE):why_keep, lock_state = _recheck(repo_root, d)@@ -445,16 +444,16 @@ def execute_plan(repo_root: str, plan: list[Decision], settings: dictkept_branches |= keptcontinuetry:- ref, kept, removed = archive_then_remove(+ ref, kept, removed, why = archive_then_remove(repo_root, d.path, reason=f"sweep: {d.reason}", max_untracked_mb=settings["archive_max_file_mb"],unlock=lock_state == "dead", remote_heads_fn=remote_heads)except (ArchiveError, OSError, subprocess.SubprocessError) as exc:logger.warning("Keeping worktree %s: archive failed (%s)", d.name, exc)preserved.append(f"{d.name} (archive failed)")continue- archived.append((ref, removed))+ archived.append((ref, removed, why))if not removed:- preserved.append(f"{d.name} (archived to {ref}, kept: changed during the sweep)")+ preserved.append(f"{d.name} (archived to {ref}, kept: {why})")if kept:kept_branches.add(kept)return preserved, kept_branches, archived@@ -466,7 +465,7 @@ def run_sweep(repo_root: str, max_age_hours: int, settings: dict) -> None:from hermes_cli.worktree_archive import prune_expired_archivesplan = plan_sweep(repo_root, max_age_hours, settings)preserved, kept_branches, archived = execute_plan(repo_root, plan, settings)- removed = [ref for ref, gone in archived if gone]+ removed = [ref for ref, gone, _why in archived if gone]if removed:logger.warning("Archived and removed %d idle worktree(s) with unmerged work; restore any with ""`hermes worktree restore <name>` (`hermes worktree list` shows archives).", len(removed))diff --git a/locales/af.yaml b/locales/af.yamlindex 9c0d6ef5680..c83eee703f8 100644--- a/locales/af.yaml+++ b/locales/af.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "Die volgende `hermes -w`-sessie verdiep die kloon en snoei saamgevoegde werkbome outomaties."unpushed_keeping: "⚠ Werkboom het ongestootte commits, word behou: {path}"uncommitted_keeping: "⚠ Werkboom het ongecommitte veranderinge, word behou: {path}"+ kept_reason: "⚠ Werkboom word behou ({reason}): {path}"clean_up_manually: "Om met die hand op te ruim: git worktree remove --force {path}"cleaned_up: "✓ Werkboom opgeruim: {path}"exit_question_dirty: "Hierdie werkboom het ongecommitte veranderinge: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Werkboom geargiveer na {ref} en verwyder: {path}"restore_hint: "Herstel dit met: hermes worktree restore {name}"archive_failed: "✗ Kon nie {path} argiveer nie, word behou: {error}"- archived_kept: "✓ Werkboom geargiveer na {ref} maar behou (dit het verander, is in gebruik, of kon nie verwyder word nie): {path}"+ archived_kept: "✓ Werkboom geargiveer na {ref} maar behou ({reason}): {path}"sweep_archived_removed: "geargiveer + verwyder → {ref}"- sweep_archived_kept: "geargiveer, behou (verander tydens die opruiming) → {ref}"+ sweep_archived_kept: "geargiveer, behou ({reason}) → {ref}"discarded: "Werkboom verwyder en sy veranderinge weggegooi: {path}"display:verb:diff --git a/locales/ar.yaml b/locales/ar.yamlindex f17953a663f..0ba1fc9f198 100644--- a/locales/ar.yaml+++ b/locales/ar.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "جلسة `hermes -w` التالية تعمّق الاستنساخ وتحذف worktrees المدمجة تلقائيًا."unpushed_keeping: "⚠ يحتوي worktree على إيداعات غير مدفوعة، سيُحتفظ به: {path}"uncommitted_keeping: "⚠ يحتوي worktree على تغييرات غير مودعة، سيُحتفظ به: {path}"+ kept_reason: "⚠ سيُحتفظ بالـ worktree ({reason}): {path}"clean_up_manually: "للتنظيف يدويًا: git worktree remove --force {path}"cleaned_up: "✓ تم تنظيف worktree: {path}"exit_question_dirty: "يحتوي هذا الـ worktree على تغييرات غير مودعة: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ تمت أرشفة الـ worktree في {ref} وإزالته: {path}"restore_hint: "لاستعادته: hermes worktree restore {name}"archive_failed: "✗ تعذّرت أرشفة {path}، سيُحتفظ به: {error}"- archived_kept: "✓ تمت أرشفة الـ worktree في {ref} لكن احتُفظ به (تغيّر، أو قيد الاستخدام، أو تعذّرت إزالته): {path}"+ archived_kept: "✓ تمت أرشفة الـ worktree في {ref} لكن احتُفظ به ({reason}): {path}"sweep_archived_removed: "أُرشف + أُزيل → {ref}"- sweep_archived_kept: "أُرشف، واحتُفظ به (تغيّر أثناء التنظيف) → {ref}"+ sweep_archived_kept: "أُرشف، واحتُفظ به ({reason}) → {ref}"discarded: "تمت إزالة الـ worktree وتجاهل تغييراته: {path}"display:verb:diff --git a/locales/de.yaml b/locales/de.yamlindex fd4690f38c1..96a2f9bf105 100644--- a/locales/de.yaml+++ b/locales/de.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "Die nächste `hermes -w`-Sitzung vertieft den Klon und entfernt gemergte Worktrees automatisch."unpushed_keeping: "⚠ Worktree hat nicht gepushte Commits, wird behalten: {path}"uncommitted_keeping: "⚠ Worktree hat nicht committete Änderungen, wird behalten: {path}"+ kept_reason: "⚠ Worktree wird behalten ({reason}): {path}"clean_up_manually: "Manuell aufräumen mit: git worktree remove --force {path}"cleaned_up: "✓ Worktree aufgeräumt: {path}"exit_question_dirty: "Dieser Worktree hat nicht committete Änderungen: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Worktree nach {ref} archiviert und entfernt: {path}"restore_hint: "Wiederherstellen mit: hermes worktree restore {name}"archive_failed: "✗ {path} konnte nicht archiviert werden, wird behalten: {error}"- archived_kept: "✓ Worktree nach {ref} archiviert, aber behalten (geändert, in Benutzung oder nicht entfernbar): {path}"+ archived_kept: "✓ Worktree nach {ref} archiviert, aber behalten ({reason}): {path}"sweep_archived_removed: "archiviert + entfernt → {ref}"- sweep_archived_kept: "archiviert, behalten (während der Bereinigung geändert) → {ref}"+ sweep_archived_kept: "archiviert, behalten ({reason}) → {ref}"discarded: "Worktree entfernt und Änderungen verworfen: {path}"display:verb:diff --git a/locales/en.yaml b/locales/en.yamlindex d98d2a07bb6..1a773037e49 100644--- a/locales/en.yaml+++ b/locales/en.yaml@@ -3398,6 +3398,7 @@ cli:next_session_deepens: "The next `hermes -w` session deepens the clone and prunes merged worktrees automatically."unpushed_keeping: "⚠ Worktree has unpushed commits, keeping: {path}"uncommitted_keeping: "⚠ Worktree has uncommitted changes, keeping: {path}"+ kept_reason: "⚠ Keeping worktree ({reason}): {path}"clean_up_manually: "To clean up manually: git worktree remove --force {path}"cleaned_up: "✓ Worktree cleaned up: {path}"exit_question_dirty: "This worktree has uncommitted changes: {path}"@@ -3409,9 +3410,9 @@ cli:archived: "✓ Worktree archived to {ref} and removed: {path}"restore_hint: "Restore it with: hermes worktree restore {name}"archive_failed: "✗ Could not archive {path}, keeping it: {error}"- archived_kept: "✓ Worktree archived to {ref} but kept (it changed, is in use, or could not be removed): {path}"+ archived_kept: "✓ Worktree archived to {ref} but kept ({reason}): {path}"sweep_archived_removed: "archived + removed → {ref}"- sweep_archived_kept: "archived, kept (changed during the sweep) → {ref}"+ sweep_archived_kept: "archived, kept ({reason}) → {ref}"discarded: "Worktree removed and its changes discarded: {path}"display:diff --git a/locales/es.yaml b/locales/es.yamlindex 1ee37f4a4a4..25835352ec1 100644--- a/locales/es.yaml+++ b/locales/es.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "La próxima sesión `hermes -w` profundiza el clon y elimina automáticamente los worktrees fusionados."unpushed_keeping: "⚠ El worktree tiene commits sin push, se conserva: {path}"uncommitted_keeping: "⚠ El worktree tiene cambios sin commit, se conserva: {path}"+ kept_reason: "⚠ Se conserva el worktree ({reason}): {path}"clean_up_manually: "Para limpiar manualmente: git worktree remove --force {path}"cleaned_up: "✓ Worktree limpiado: {path}"exit_question_dirty: "Este worktree tiene cambios sin commit: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Worktree archivado en {ref} y eliminado: {path}"restore_hint: "Restáuralo con: hermes worktree restore {name}"archive_failed: "✗ No se pudo archivar {path}, se conserva: {error}"- archived_kept: "✓ Worktree archivado en {ref} pero conservado (cambió, está en uso o no se pudo eliminar): {path}"+ archived_kept: "✓ Worktree archivado en {ref} pero conservado ({reason}): {path}"sweep_archived_removed: "archivado + eliminado → {ref}"- sweep_archived_kept: "archivado, conservado (cambió durante la limpieza) → {ref}"+ sweep_archived_kept: "archivado, conservado ({reason}) → {ref}"discarded: "Worktree eliminado y cambios descartados: {path}"display:verb:diff --git a/locales/fr.yaml b/locales/fr.yamlindex a458e4ef744..13b40dd9455 100644--- a/locales/fr.yaml+++ b/locales/fr.yaml@@ -3614,6 +3614,7 @@ cli:next_session_deepens: "La prochaine session `hermes -w` approfondira le clone et supprimera automatiquement les worktrees fusionnés."unpushed_keeping: "⚠ Le worktree a des commits non poussés, conservé : {path}"uncommitted_keeping: "⚠ Le worktree a des modifications non commitées, conservé : {path}"+ kept_reason: "⚠ Worktree conservé ({reason}) : {path}"clean_up_manually: "Pour nettoyer manuellement : git worktree remove --force {path}"cleaned_up: "✓ Worktree nettoyé : {path}"exit_question_dirty: "Ce worktree contient des modifications non commitées : {path}"@@ -3625,9 +3626,9 @@ cli:archived: "✓ Worktree archivé dans {ref} et supprimé : {path}"restore_hint: "Pour le restaurer : hermes worktree restore {name}"archive_failed: "✗ Impossible d'archiver {path}, conservé : {error}"- archived_kept: "✓ Worktree archivé dans {ref} mais conservé (modifié, en cours d'utilisation ou impossible à supprimer) : {path}"+ archived_kept: "✓ Worktree archivé dans {ref} mais conservé ({reason}) : {path}"sweep_archived_removed: "archivé + supprimé → {ref}"- sweep_archived_kept: "archivé, conservé (modifié pendant le nettoyage) → {ref}"+ sweep_archived_kept: "archivé, conservé ({reason}) → {ref}"discarded: "Worktree supprimé et modifications abandonnées : {path}"display:verb:diff --git a/locales/ga.yaml b/locales/ga.yamlindex 461f547b75f..85f5164f5c2 100644--- a/locales/ga.yaml+++ b/locales/ga.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "Déanann an chéad seisiún `hermes -w` eile an clón a dhoimhniú agus bearrann sé worktrees cumaiscthe go huathoibríoch."unpushed_keeping: "⚠ Tá tiomantais gan bhrú sa worktree, á choinneáil: {path}"uncommitted_keeping: "⚠ Tá athruithe gan tiomantas sa worktree, á choinneáil: {path}"+ kept_reason: "⚠ Worktree á choinneáil ({reason}): {path}"clean_up_manually: "Chun glanadh de láimh: git worktree remove --force {path}"cleaned_up: "✓ Worktree glanta: {path}"exit_question_dirty: "Tá athruithe gan tiomantas sa worktree seo: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Worktree cartlannaithe go {ref} agus bainte: {path}"restore_hint: "Athchóirigh é le: hermes worktree restore {name}"archive_failed: "✗ Níorbh fhéidir {path} a chartlannú, á choinneáil: {error}"- archived_kept: "✓ Worktree cartlannaithe go {ref} ach coinnithe (athraíodh é, tá sé in úsáid, nó níorbh fhéidir é a bhaint): {path}"+ archived_kept: "✓ Worktree cartlannaithe go {ref} ach coinnithe ({reason}): {path}"sweep_archived_removed: "cartlannaithe + bainte → {ref}"- sweep_archived_kept: "cartlannaithe, coinnithe (athraithe le linn an scuabtha) → {ref}"+ sweep_archived_kept: "cartlannaithe, coinnithe ({reason}) → {ref}"discarded: "Worktree bainte agus a athruithe caite uait: {path}"display:verb:diff --git a/locales/hu.yaml b/locales/hu.yamlindex 38c619094ad..d73ed002d51 100644--- a/locales/hu.yaml+++ b/locales/hu.yaml@@ -3314,6 +3314,7 @@ cli:next_session_deepens: "A következő `hermes -w` munkamenet mélyíti a klónt, és automatikusan eltávolítja a beolvasztott worktree-ket."unpushed_keeping: "⚠ A worktree-ben feltöltetlen commitok vannak, megtartva: {path}"uncommitted_keeping: "⚠ A worktree-ben nem commitolt változások vannak, megtartva: {path}"+ kept_reason: "⚠ Worktree megtartva ({reason}): {path}"clean_up_manually: "Kézi takarításhoz: git worktree remove --force {path}"cleaned_up: "✓ Worktree eltakarítva: {path}"exit_question_dirty: "Ebben a worktree-ben nem commitolt változások vannak: {path}"@@ -3325,9 +3326,9 @@ cli:archived: "✓ Worktree archiválva ide: {ref}, és eltávolítva: {path}"restore_hint: "Visszaállítás: hermes worktree restore {name}"archive_failed: "✗ {path} archiválása sikertelen, megtartva: {error}"- archived_kept: "✓ Worktree archiválva ide: {ref}, de megtartva (változott, használatban van, vagy nem távolítható el): {path}"+ archived_kept: "✓ Worktree archiválva ide: {ref}, de megtartva ({reason}): {path}"sweep_archived_removed: "archiválva + eltávolítva → {ref}"- sweep_archived_kept: "archiválva, megtartva (a takarítás közben változott) → {ref}"+ sweep_archived_kept: "archiválva, megtartva ({reason}) → {ref}"discarded: "Worktree eltávolítva, változásai elvetve: {path}"display:verb:diff --git a/locales/it.yaml b/locales/it.yamlindex 706ad4a5e7a..23ed9d57f78 100644--- a/locales/it.yaml+++ b/locales/it.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "La prossima sessione `hermes -w` approfondisce il clone ed elimina automaticamente i worktree già uniti."unpushed_keeping: "⚠ Il worktree ha commit non inviati, mantengo: {path}"uncommitted_keeping: "⚠ Il worktree ha modifiche non committate, mantengo: {path}"+ kept_reason: "⚠ Worktree mantenuto ({reason}): {path}"clean_up_manually: "Per pulire manualmente: git worktree remove --force {path}"cleaned_up: "✓ Worktree pulito: {path}"exit_question_dirty: "Questo worktree ha modifiche non committate: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Worktree archiviato in {ref} e rimosso: {path}"restore_hint: "Ripristinalo con: hermes worktree restore {name}"archive_failed: "✗ Impossibile archiviare {path}, lo mantengo: {error}"- archived_kept: "✓ Worktree archiviato in {ref} ma mantenuto (modificato, in uso o non rimovibile): {path}"+ archived_kept: "✓ Worktree archiviato in {ref} ma mantenuto ({reason}): {path}"sweep_archived_removed: "archiviato + rimosso → {ref}"- sweep_archived_kept: "archiviato, mantenuto (modificato durante la pulizia) → {ref}"+ sweep_archived_kept: "archiviato, mantenuto ({reason}) → {ref}"discarded: "Worktree rimosso e modifiche scartate: {path}"display:verb:diff --git a/locales/ja.yaml b/locales/ja.yamlindex 6576d5a6247..992246f9d74 100644--- a/locales/ja.yaml+++ b/locales/ja.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "次回の `hermes -w` セッションでクローンを深化し、マージ済みのワークツリーを自動的に削除します。"unpushed_keeping: "⚠ ワークツリーに未プッシュのコミットがあるため保持します: {path}"uncommitted_keeping: "⚠ ワークツリーに未コミットの変更があるため保持します: {path}"+ kept_reason: "⚠ ワークツリーを保持します ({reason}): {path}"clean_up_manually: "手動でクリーンアップするには: git worktree remove --force {path}"cleaned_up: "✓ ワークツリーをクリーンアップしました: {path}"exit_question_dirty: "このワークツリーには未コミットの変更があります: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ ワークツリーを {ref} にアーカイブして削除しました: {path}"restore_hint: "復元するには: hermes worktree restore {name}"archive_failed: "✗ {path} をアーカイブできなかったため保持します: {error}"- archived_kept: "✓ ワークツリーを {ref} にアーカイブしましたが保持しました (変更された、使用中、または削除できませんでした): {path}"+ archived_kept: "✓ ワークツリーを {ref} にアーカイブしましたが保持しました ({reason}): {path}"sweep_archived_removed: "アーカイブして削除 → {ref}"- sweep_archived_kept: "アーカイブ済み、保持 (掃除中に変更されました) → {ref}"+ sweep_archived_kept: "アーカイブ済み、保持 ({reason}) → {ref}"discarded: "ワークツリーを削除し、変更を破棄しました: {path}"display:verb:diff --git a/locales/ko.yaml b/locales/ko.yamlindex 6ba95338f5b..a76da7f4ff2 100644--- a/locales/ko.yaml+++ b/locales/ko.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "다음 `hermes -w` 세션에서 클론을 깊게 만들고 병합된 워크트리를 자동으로 정리해요."unpushed_keeping: "⚠ 워크트리에 푸시되지 않은 커밋이 있어 유지해요: {path}"uncommitted_keeping: "⚠ 워크트리에 커밋되지 않은 변경 사항이 있어 유지해요: {path}"+ kept_reason: "⚠ 워크트리를 유지해요 ({reason}): {path}"clean_up_manually: "직접 정리하려면: git worktree remove --force {path}"cleaned_up: "✓ 워크트리를 정리했어요: {path}"exit_question_dirty: "이 워크트리에 커밋되지 않은 변경 사항이 있어요: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ 워크트리를 {ref}에 보관하고 제거했어요: {path}"restore_hint: "복원하려면: hermes worktree restore {name}"archive_failed: "✗ {path}을(를) 보관하지 못해 유지해요: {error}"- archived_kept: "✓ 워크트리를 {ref}에 보관했지만 유지했어요 (변경됐거나, 사용 중이거나, 제거할 수 없음): {path}"+ archived_kept: "✓ 워크트리를 {ref}에 보관했지만 유지했어요 ({reason}): {path}"sweep_archived_removed: "보관 후 제거 → {ref}"- sweep_archived_kept: "보관됨, 유지 (정리 중 변경됨) → {ref}"+ sweep_archived_kept: "보관됨, 유지 ({reason}) → {ref}"discarded: "워크트리를 제거하고 변경 사항을 버렸어요: {path}"display:verb:diff --git a/locales/pt.yaml b/locales/pt.yamlindex c209b3a1347..0656f7b0b41 100644--- a/locales/pt.yaml+++ b/locales/pt.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "A próxima sessão `hermes -w` aprofunda o clone e remove worktrees já mescladas automaticamente."unpushed_keeping: "⚠ A worktree tem commits não enviados (push); mantendo: {path}"uncommitted_keeping: "⚠ A worktree tem alterações não commitadas; mantendo: {path}"+ kept_reason: "⚠ Mantendo a worktree ({reason}): {path}"clean_up_manually: "Para limpar manualmente: git worktree remove --force {path}"cleaned_up: "✓ Worktree limpa: {path}"exit_question_dirty: "Esta worktree tem alterações não commitadas: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Worktree arquivada em {ref} e removida: {path}"restore_hint: "Restaure com: hermes worktree restore {name}"archive_failed: "✗ Não foi possível arquivar {path}; mantendo: {error}"- archived_kept: "✓ Worktree arquivada em {ref}, mas mantida (foi alterada, está em uso ou não pôde ser removida): {path}"+ archived_kept: "✓ Worktree arquivada em {ref}, mas mantida ({reason}): {path}"sweep_archived_removed: "arquivada + removida → {ref}"- sweep_archived_kept: "arquivada, mantida (alterada durante a limpeza) → {ref}"+ sweep_archived_kept: "arquivada, mantida ({reason}) → {ref}"discarded: "Worktree removida e alterações descartadas: {path}"display:verb:diff --git a/locales/ru.yaml b/locales/ru.yamlindex c6bb64ed5d2..8002a2140f5 100644--- a/locales/ru.yaml+++ b/locales/ru.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "Следующий сеанс `hermes -w` углубит клон и автоматически удалит слитые worktree."unpushed_keeping: "⚠ В worktree есть неотправленные коммиты, оставляю: {path}"uncommitted_keeping: "⚠ В worktree есть незакоммиченные изменения, оставляю: {path}"+ kept_reason: "⚠ Worktree сохранён ({reason}): {path}"clean_up_manually: "Чтобы очистить вручную: git worktree remove --force {path}"cleaned_up: "✓ Worktree очищен: {path}"exit_question_dirty: "В этом worktree есть незакоммиченные изменения: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Worktree заархивирован в {ref} и удалён: {path}"restore_hint: "Восстановить: hermes worktree restore {name}"archive_failed: "✗ Не удалось заархивировать {path}, оставляю: {error}"- archived_kept: "✓ Worktree заархивирован в {ref}, но сохранён (изменился, используется или не удалось удалить): {path}"+ archived_kept: "✓ Worktree заархивирован в {ref}, но сохранён ({reason}): {path}"sweep_archived_removed: "заархивирован + удалён → {ref}"- sweep_archived_kept: "заархивирован, сохранён (изменился во время очистки) → {ref}"+ sweep_archived_kept: "заархивирован, сохранён ({reason}) → {ref}"discarded: "Worktree удалён, изменения отброшены: {path}"display:verb:diff --git a/locales/tr.yaml b/locales/tr.yamlindex b43311086c1..6a6473c7429 100644--- a/locales/tr.yaml+++ b/locales/tr.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "Bir sonraki `hermes -w` oturumu klonu derinleştirir ve birleştirilmiş worktree'leri otomatik olarak temizler."unpushed_keeping: "⚠ Worktree'de push edilmemiş commit'ler var, korunuyor: {path}"uncommitted_keeping: "⚠ Worktree'de commit edilmemiş değişiklikler var, korunuyor: {path}"+ kept_reason: "⚠ Worktree tutuluyor ({reason}): {path}"clean_up_manually: "Elle temizlemek için: git worktree remove --force {path}"cleaned_up: "✓ Worktree temizlendi: {path}"exit_question_dirty: "Bu worktree'de commit edilmemiş değişiklikler var: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Worktree {ref} konumuna arşivlendi ve kaldırıldı: {path}"restore_hint: "Geri yüklemek için: hermes worktree restore {name}"archive_failed: "✗ {path} arşivlenemedi, korunuyor: {error}"- archived_kept: "✓ Worktree {ref} konumuna arşivlendi ama tutuldu (değişti, kullanımda veya kaldırılamadı): {path}"+ archived_kept: "✓ Worktree {ref} konumuna arşivlendi ama tutuldu ({reason}): {path}"sweep_archived_removed: "arşivlendi + kaldırıldı → {ref}"- sweep_archived_kept: "arşivlendi, tutuldu (temizlik sırasında değişti) → {ref}"+ sweep_archived_kept: "arşivlendi, tutuldu ({reason}) → {ref}"discarded: "Worktree kaldırıldı ve değişiklikleri atıldı: {path}"display:verb:diff --git a/locales/uk.yaml b/locales/uk.yamlindex 6c431541925..da3207f340b 100644--- a/locales/uk.yaml+++ b/locales/uk.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "Наступний сеанс `hermes -w` поглибить клон і автоматично видалить злиті робочі дерева."unpushed_keeping: "⚠ У робочому дереві є невідправлені коміти, залишаємо: {path}"uncommitted_keeping: "⚠ У робочому дереві є незафіксовані зміни, залишаємо: {path}"+ kept_reason: "⚠ Робоче дерево збережено ({reason}): {path}"clean_up_manually: "Щоб очистити вручну: git worktree remove --force {path}"cleaned_up: "✓ Робоче дерево очищено: {path}"exit_question_dirty: "У цьому робочому дереві є незафіксовані зміни: {path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ Робоче дерево заархівовано в {ref} і видалено: {path}"restore_hint: "Відновити: hermes worktree restore {name}"archive_failed: "✗ Не вдалося заархівувати {path}, залишаємо: {error}"- archived_kept: "✓ Робоче дерево заархівовано в {ref}, але збережено (змінилося, використовується або не вдалося видалити): {path}"+ archived_kept: "✓ Робоче дерево заархівовано в {ref}, але збережено ({reason}): {path}"sweep_archived_removed: "заархівовано + видалено → {ref}"- sweep_archived_kept: "заархівовано, збережено (змінилося під час очищення) → {ref}"+ sweep_archived_kept: "заархівовано, збережено ({reason}) → {ref}"discarded: "Робоче дерево видалено, зміни відкинуто: {path}"display:verb:diff --git a/locales/zh-hant.yaml b/locales/zh-hant.yamlindex b6d9ff2b9f2..d2409716139 100644--- a/locales/zh-hant.yaml+++ b/locales/zh-hant.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "下一次 `hermes -w` 工作階段會加深複製並自動清理已合併的工作樹。"unpushed_keeping: "⚠ 工作樹有未推送的提交,保留:{path}"uncommitted_keeping: "⚠ 工作樹有未提交的變更,保留:{path}"+ kept_reason: "⚠ 保留工作樹({reason}):{path}"clean_up_manually: "手動清理方式:git worktree remove --force {path}"cleaned_up: "✓ 工作樹已清理:{path}"exit_question_dirty: "此工作樹有未提交的變更:{path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ 工作樹已封存至 {ref} 並移除:{path}"restore_hint: "還原方式:hermes worktree restore {name}"archive_failed: "✗ 無法封存 {path},保留:{error}"- archived_kept: "✓ 工作樹已封存至 {ref},但已保留(有變更、使用中或無法移除):{path}"+ archived_kept: "✓ 工作樹已封存至 {ref},但已保留({reason}):{path}"sweep_archived_removed: "已封存並移除 → {ref}"- sweep_archived_kept: "已封存,保留(清理期間有變更)→ {ref}"+ sweep_archived_kept: "已封存,保留({reason})→ {ref}"discarded: "工作樹已移除,變更已捨棄:{path}"display:verb:diff --git a/locales/zh.yaml b/locales/zh.yamlindex c4cf597bb1e..ecb2348e2cf 100644--- a/locales/zh.yaml+++ b/locales/zh.yaml@@ -3297,6 +3297,7 @@ cli:next_session_deepens: "下一次 `hermes -w` 会话会自动加深克隆并清理已合并的工作树。"unpushed_keeping: "⚠ 工作树有未推送的提交,保留:{path}"uncommitted_keeping: "⚠ 工作树有未提交的更改,保留:{path}"+ kept_reason: "⚠ 保留工作树({reason}):{path}"clean_up_manually: "手动清理:git worktree remove --force {path}"cleaned_up: "✓ 工作树已清理:{path}"exit_question_dirty: "此工作树有未提交的更改:{path}"@@ -3308,9 +3309,9 @@ cli:archived: "✓ 工作树已归档到 {ref} 并移除:{path}"restore_hint: "恢复方式:hermes worktree restore {name}"archive_failed: "✗ 无法归档 {path},保留:{error}"- archived_kept: "✓ 工作树已归档到 {ref},但已保留(有变更、使用中或无法移除):{path}"+ archived_kept: "✓ 工作树已归档到 {ref},但已保留({reason}):{path}"sweep_archived_removed: "已归档并移除 → {ref}"- sweep_archived_kept: "已归档,保留(清理期间有变更)→ {ref}"+ sweep_archived_kept: "已归档,保留({reason})→ {ref}"discarded: "工作树已移除,更改已丢弃:{path}"display:verb:diff --git a/tests/hermes_cli/test_worktree_snapshot_prune.py b/tests/hermes_cli/test_worktree_snapshot_prune.pyindex 595b6b5ba29..ed3bf6e71c2 100644--- a/tests/hermes_cli/test_worktree_snapshot_prune.py+++ b/tests/hermes_cli/test_worktree_snapshot_prune.py@@ -8,6 +8,7 @@ visits the repos the ACTIVE profile registered (I7); a non-interactive exit neveimport hashlibimport os+import shutilimport subprocessimport sysimport time@@ -202,8 +203,8 @@ def test_a_tree_resumed_mid_sweep_is_never_removed(repo, monkeypatch, capsys):assert second.exists() and (second / "notes.md").read_text(encoding="utf-8-sig") == "uncommitted\n"assert staged.exists() and _git(["show", ":b.py"], staged) == "NEW STAGED CONTENT"assert sorted(ref.rsplit("/", 1)[-1] for ref in _archives(repo)) == ["lane-a", "lane-staged"]- assert sorted(actions) == ["archived, kept (changed during the sweep) → refs/hermes/archive/lane-a",- "archived, kept (changed during the sweep) → refs/hermes/archive/lane-staged"]+ assert sorted(actions) == ["archived, kept (changed 0s ago) → refs/hermes/archive/lane-a",+ "archived, kept (staged changes since the snapshot) → refs/hermes/archive/lane-staged"]def test_dirty_submodule_work_is_never_archived_away(repo, tmp_path, monkeypatch):@@ -266,6 +267,113 @@ def test_dirty_submodule_work_is_never_archived_away(repo, tmp_path, monkeypatchsnapshot_worktree(str(repo), tree, reason="session exit")+def _big(path, mb=2):+ with open(path, "wb") as f:+ f.truncate(mb * 1024 * 1024)+ f.seek(0)+ f.write(b"UNIQUE BYTES")+++def _private_commit(repo_dir):+ _git(["init", "-q", "-b", "main", str(repo_dir)], repo_dir.parent)+ (repo_dir / "x").write_text("PRIVATE\n", encoding="utf-8")+ _git(["add", "-A"], repo_dir)+ _git(["commit", "-qm", "private"], repo_dir)+ return _git(["rev-parse", "HEAD"], repo_dir)+++def _case_large(repo, wt):+ (wt / "notes.md").write_text("dirty\n", encoding="utf-8")+ _big(wt / "dataset.bin")+ return {"dataset.bin": None}, None+++def _case_ignored_repo(repo, wt):+ (wt / "notes.md").write_text("dirty\n", encoding="utf-8")+ return {}, (wt / "build" / "tool", _private_commit(_mkdirs(wt / "build" / "tool")))+++def _case_ignored_files(repo, wt):+ (wt / "notes.md").write_text("dirty\n", encoding="utf-8")+ (wt / "prod.secret").write_text("API KEY WORK\n", encoding="utf-8")+ (wt / ".env").write_text("LOCAL ONLY=1\n", encoding="utf-8") # differs from the main checkout+ return {"prod.secret": b"API KEY WORK\n", ".env": b"LOCAL ONLY=1\n"}, None+++def _case_untracked_hidden(repo, wt):+ _git(["config", "status.showUntrackedFiles", "no"], repo)+ (wt / "new_work.py").write_text("UNTRACKED WORK\n", encoding="utf-8")+ return {"new_work.py": b"UNTRACKED WORK\n"}, None+++def _case_skip_worktree(repo, wt):+ _git(["update-index", "--skip-worktree", "b.py"], wt)+ _git(["update-index", "--assume-unchanged", "a.txt"], wt)+ (wt / "b.py").write_bytes(b"SKIP-WORKTREE EDIT\n")+ return {"b.py": b"SKIP-WORKTREE EDIT\n"}, None+++def _case_worktree_ref(repo, wt):+ (wt / "b.py").write_text("private\n", encoding="utf-8")+ _git(["commit", "-qam", "private"], wt)+ sha = _git(["rev-parse", "HEAD"], wt)+ _git(["update-ref", "refs/worktree/keep", sha], wt)+ _git(["update-ref", "refs/bisect/bad", sha], wt)+ _git(["reset", "-q", "--hard", "origin/main"], wt)+ return {}, (repo, sha)+++def _mkdirs(path):+ path.mkdir(parents=True)+ return path++[email protected]("mode", ["archive", "classic"])[email protected]("setup", [_case_large, _case_ignored_repo, _case_ignored_files, _case_untracked_hidden,+ _case_skip_worktree, _case_worktree_ref], ids=lambda f: f.__name__[6:])+def test_the_pruner_removes_a_tree_only_when_everything_irreproducible_is_archived(repo, mode, setup):+ """R2: through the real pruner, every byte and commit that git cannot regenerate survives,+ in the tree or in its archive: an untracked file over the size cap, a gitignored embedded+ repository, ignored files that are not reproducible, untracked files hidden by+ ``status.showUntrackedFiles=no``, skip-worktree / assume-unchanged edits, and commits held+ only by per-worktree refs. Regenerable ignored content (``node_modules``, ``__pycache__``) and+ ``.worktreeinclude`` copies identical to the main checkout never hold a tree back."""+ if mode == "classic":+ _set_worktrees_config("worktrees:\n archive_dirty: false\n")+ else:+ _set_worktrees_config("worktrees:\n archive_max_file_mb: 1\n")+ (repo / ".git" / "info").mkdir(exist_ok=True)+ (repo / ".git" / "info" / "exclude").write_text("build/\n*.secret\n.env\n__pycache__/\n", encoding="utf-8")+ (repo / ".env").write_text("SHARED=1\n", encoding="utf-8")+ wt, regen = _tree(repo, "lane-case"), _tree(repo, "lane-regen", dirty=True)+ for tree in (wt, regen):+ shutil.copy2(repo / ".env", tree / ".env") # what .worktreeinclude copies+ (_mkdirs(tree / "node_modules" / "dep") / "index.js").write_text("x\n", encoding="utf-8")+ (_mkdirs(tree / "pkg" / "__pycache__") / "m.pyc").write_bytes(b"\0")+ precious, commit = setup(repo, wt)+ sizes = {rel: (wt / rel).read_bytes() for rel, data in precious.items() if data is None}+ precious = {**precious, **sizes}+ for tree in (wt, regen):+ _idle(tree)++ worktree_ops._prune_stale_worktrees(str(repo))++ archives = _archives(repo)+ for rel, data in precious.items():+ in_tree = (wt / rel).is_file() and (wt / rel).read_bytes() == data+ in_archive = any(subprocess.run(["git", "cat-file", "blob", f"{ref}:{rel}"], cwd=repo, capture_output=True,+ check=False)+ .stdout == data for ref in archives if ref.endswith("/lane-case"))+ assert in_tree or in_archive, f"{rel} lost"+ if commit:+ where, sha = commit+ assert where.exists() and _git(["cat-file", "-t", sha], where) == "commit"+ if where == repo:+ assert wt.exists()+ if mode == "archive":+ assert not regen.exists(), "regenerable / main-identical ignored files must not hold a tree back"++def test_prune_older_than_bounds_what_the_sweep_removes(repo, capsys):"""`hermes worktree prune --older-than N` never archives or removes a tree idle < N days."""import argparsediff --git a/tools/subagent_worktree.py b/tools/subagent_worktree.pyindex 378b0e8c1f9..77cc201558f 100644--- a/tools/subagent_worktree.py+++ b/tools/subagent_worktree.py@@ -164,7 +164,7 @@ def finalize_subagent_worktree(info: dict[str, str], *, prune: bool = True) -> dfailed, unmeasured = [], []probes = (("commits", "rev-list", ["rev-list", "--count", f"{base_commit}..HEAD"],lambda s: int(s or 0)),- ("dirty", "status", ["status", "--porcelain"], bool))+ ("dirty", "status", ["status", "--porcelain", "--untracked-files=normal"], bool))try:for field, label, args, parse in probes:res = _run_git(args, cwd=path, env=probe_env)@@ -180,13 +180,23 @@ def finalize_subagent_worktree(info: dict[str, str], *, prune: bool = True) -> dif failed:# Destructive cleanup requires affirmative proof; defaults prove nothing.return mark_worktree_payload_unproven(payload, "; ".join(failed), unmeasured="/".join(unmeasured))+ if not payload["dirty"]:+ # status trusts skip-worktree / assume-unchanged: edits behind them are invisible to it.+ from hermes_cli.worktree_archive import ArchiveError+ from hermes_cli.worktree_retention import hidden_index_edits+ try:+ payload["dirty"] = bool(hidden_index_edits(path))+ except (ArchiveError, OSError, subprocess.SubprocessError) as exc:+ return mark_worktree_payload_unproven(payload, f"index flag probe failed: {exc}", unmeasured="dirty")if prune and (payload["commits"] or payload["dirty"]):return _archive_finished_worktree(info, payload)if 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, submodule_blocks_removal- if submodule_blocks_removal(path): # a module repository dies with the tree+ from hermes_cli.worktree_ops import release_lsp_clients, removal_blocked+ blocked = removal_blocked(path) # an embedded repo / ignored file / ref dies with the tree+ if blocked:+ payload["note"] = f"Worktree kept at {path}: {blocked[1]}."return payloadrelease_lsp_clients(path) # the child ran in-process: its language servers are oursremoved = _run_git(["worktree", "remove", "--force", path], cwd=cwd)@@ -218,7 +228,7 @@ def _archive_finished_worktree(info: dict[str, str], payload: dict[str, Any]) ->logger.info("subagent worktree: a live process works in %s; keeping it", path)return payloadtry:- ref, _kept, removed = archive_then_remove(+ ref, _kept, removed, why = archive_then_remove(info.get("repo_root", "") or path, path, reason="subagent finished",max_untracked_mb=settings["archive_max_file_mb"], unlock=False, keep_branch=True,exclude_pids=(os.getpid(),))@@ -232,8 +242,8 @@ def _archive_finished_worktree(info: dict[str, str], payload: dict[str, Any]) ->f"Restore the full tree (including uncommitted edits) with "f"`hermes worktree restore {ref.rsplit('/', 1)[-1]}`.")else:- payload["note"] = (f"Worktree archived to {ref} but kept at {path} (it changed after the snapshot "- f"or could not be removed); branch {info.get('branch')} kept.")+ payload["note"] = (f"Worktree archived to {ref} but kept at {path} ({why}); "+ f"branch {info.get('branch')} kept.")return payloaddiff --git a/website/docs/user-guide/cli.md b/website/docs/user-guide/cli.mdindex 0577ae53853..c4ca994202e 100644--- a/website/docs/user-guide/cli.md+++ b/website/docs/user-guide/cli.md@@ -121,6 +121,13 @@ Safety guarantees (all modes, any age):- **Untracked-only scratch** (PR body drafts, notes) is archived to`~/.hermes/archive/worktree-prune/` before its tree is removed — neverdestroyed.+- **Nothing irreproducible is deleted unarchived**: a tree is kept when it holds+ an embedded repository (even a gitignored one), a commit only a per-worktree+ ref (`refs/worktree/*`, `refs/bisect/*`) reaches, an untracked file over the+ archive size cap, or an ignored file that is neither under a build/dependency+ directory (`node_modules`, `.venv`, `__pycache__`, `dist`, `build`, …) nor a+ byte-identical copy of the main checkout's file (`.worktreeinclude`'s `.env`).+ See [ignored files](./git-worktrees.md#stale-worktree-sweep-and-restore).- Branch deletion is content-gated, not name-gated: any local branch whosecommits are all on upstream is safe to delete; branches with unique work,checked-out branches, and `main`/`master`/`develop` are always kept.diff --git a/website/docs/user-guide/git-worktrees.md b/website/docs/user-guide/git-worktrees.mdindex b175d86a634..7c9e8b12f83 100644--- a/website/docs/user-guide/git-worktrees.md+++ b/website/docs/user-guide/git-worktrees.md@@ -214,6 +214,30 @@ repositories' `.worktrees/`:| 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) || 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 embedded repository anywhere inside, gitignored or not (e.g. `build/tool/.git`) | kept (`keep-unarchivable`) |+| A commit held only by a per-worktree ref (`refs/worktree/*`, `refs/bisect/*`, `refs/rewritten/*`) | kept (`keep-worktree-refs`: those refs are deleted with the tree) |+| An untracked file larger than `worktrees.archive_max_file_mb` | kept (`keep-large-untracked`) |+| An ignored file that is not reproducible (see below) | kept (`keep-ignored-work`; `--dry-run` names the files) |++**Ignored files.** An archive does not capture files your ignore rules+(`.gitignore`, `.git/info/exclude`, `core.excludesFile`) exclude, so a tree is+removed only when every ignored file in it can be regenerated:++- it lies under a build or dependency directory: `node_modules`, `.venv`,+ `venv`, `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.tox`,+ `dist`, `build`, `target`, `.next`, `.turbo`, `.cache`, `coverage`, `.gradle`,+ `*.egg-info`; or+- it is a byte-identical copy of the same path in the main checkout (what+ `.worktreeinclude` copies, such as `.env`).++Any other ignored file (a local `.env` edit, `*.secret`, notes excluded in+`info/exclude`, test output) keeps the tree, on every path: the sweep, exit+**Archive** and subagent cleanup. Commit, move or delete the file and the next+sweep reclaims the tree.++The same checks run on clean merged trees, and every dirty check counts files+that `status.showUntrackedFiles=no` would hide and skip-worktree /+assume-unchanged files whose bytes differ from the index.An archive is a commit stored at `refs/hermes/archive/<tree>` holding thetree's `HEAD`, staged changes, unstaged changes and untracked files (files your@@ -224,7 +248,8 @@ staged changes move (`git add`, `git apply --cached`) while the archive isbeing built, the archive is saved and the tree is kept too. File bytes are stored andrestored exactly: no `.gitattributes`, `info/attributes`, `core.attributesFile`line-ending or filter rule is applied. Untracked files larger than-`worktrees.archive_max_file_mb` are left out and listed in the archive. A+`worktrees.archive_max_file_mb` are left out and listed in the archive, and the+tree is then kept: exit **Archive** and the subagent result say so. Abranch that exists on a remote (an open PR) is kept; otherwise the archiveholds its commits and the local branch is deleted.@@ -243,7 +268,7 @@ sweep.```yamlworktrees:archive_dirty: true # false = never remove dirty/unpushed trees (the old behaviour)- archive_max_file_mb: 50 # untracked files above this are listed, not archived+ archive_max_file_mb: 50 # untracked files above this are not archived; their tree is keptarchive_retention_days: 30 # 0 keeps archives forevermax_total_gb: 0 # optional budget for idle trees; oldest are archived + removed first```