Files
Teknium 3882113085 feat: archive stale dirty worktrees before removing them, sweep every repo, ask on dirty exit
The worktree pruner never removed a dirty or unpushed tree at any age, so leftovers of finished
lanes (stray probe files, WIP commits on closed PRs) accumulated forever: 658 trees / ~1 TB on
one machine, 553 of them named lane trees. Approved design (Teknium, 2026-10-17):

- Snapshot-then-delete: an idle tree past its tier (hermes-*/subagent-* 24h, named 72h) with
  uncommitted changes or unpushed commits is archived to refs/hermes/archive/<tree> (HEAD +
  staged + unstaged + non-ignored untracked bytes, built with a temporary index; large untracked
  files skipped and listed) and then removed. A failed archive keeps the tree. Branch kept when
  published on a remote, otherwise the archive anchors its commits.
- Never touched at any age or budget: live hermes lock owners, any live process whose cwd/open fd
  is inside the tree (/proc on Linux, psutil cwd elsewhere), trees with recent file/ref activity,
  Kanban t_<hex> trees.
- No count cap; optional worktrees.max_total_gb evicts the oldest idle trees first.
- Per-profile registry (<HERMES_HOME>/worktree_repos.json) of every repo Hermes made a worktree
  in (hermes -w, /worktree new, subagent isolation, Desktop git pane); the 6h cron sweep unions
  it with its existing sources, scoped and throttled per profile.
- Subagent worktrees with commits/edits are archived and removed at child finish (branch kept).
- Interactive `hermes -w` (CLI and --tui) exit with a dirty/unpushed tree asks Keep (default) /
  Archive & remove / Remove and discard; non-interactive exits never ask.
- `hermes worktree restore <name> [--path]`, archives in `hermes worktree list`, a full
  decision table in `hermes worktree prune --dry-run`, archive retention (30 days).
- worktrees.archive_dirty: false restores the classic never-delete-dirty pruner exactly.
2026-10-17 21:49:14 -07:00

61 lines
3.2 KiB
Python

"""``hermes worktree`` subcommand parser."""
from __future__ import annotations
def build_worktree_parser(subparsers) -> None:
"""Attach the ``worktree`` subcommand to ``subparsers``."""
worktree_parser = subparsers.add_parser(
"worktree", help="Audit and reclaim accumulated git worktrees and merged branches",
description="Audit, reclaim and restore the .worktrees/ trees Hermes sessions "
"accumulate. Idle trees with uncommitted changes or unpushed commits are "
"archived to refs/hermes/archive/<tree> before removal "
"(worktrees.archive_dirty); `restore` brings one back. In-use trees are "
"never touched. See: "
"https://hermes-agent.nousresearch.com/docs/user-guide/git-worktrees")
worktree_subparsers = worktree_parser.add_subparsers(dest="worktree_action")
worktree_list = worktree_subparsers.add_parser(
"list", aliases=["ls", "audit"],
help="Classify every tree: age, size, verdict, reason (default action)")
worktree_list.add_argument("--repo", help="Repo root (default: current repo)")
worktree_list.add_argument(
"--json", action="store_true",
help="Machine-readable audit output (trees, external trees, branches)")
worktree_list.add_argument(
"--older-than", type=float, metavar="DAYS", dest="older_than",
help="Treat reapable trees younger than DAYS as keep")
worktree_prune = worktree_subparsers.add_parser(
"prune", help="Remove safe trees and delete fully-merged local branches")
worktree_prune.add_argument("--repo", help="Repo root (default: current repo)")
worktree_prune.add_argument(
"--json", action="store_true",
help="Machine-readable result (actions taken/planned, preserved trees)")
worktree_prune.add_argument(
"--older-than", type=float, metavar="DAYS", dest="older_than",
help="Only reap trees idle for at least DAYS days (safety gates still apply)")
worktree_prune.add_argument(
"--dry-run", action="store_true", help="Show the plan without changing anything")
worktree_prune.add_argument(
"--trees-only", action="store_true",
help="Only remove worktrees; leave local branches alone")
worktree_prune.add_argument(
"--branches-only", action="store_true",
help="Only delete merged local branches; leave worktrees alone")
worktree_restore = worktree_subparsers.add_parser(
"restore", help="Recreate an archived worktree (tracked, staged and untracked files)")
worktree_restore.add_argument("name", help="Archive name or tree name (see `hermes worktree list`)")
worktree_restore.add_argument("--path", help="Restore here instead of the original path")
worktree_restore.add_argument("--repo", help="Repo root (default: current repo)")
def _dispatch_worktree(_args):
from hermes_cli.worktree_cmd import cmd_worktree
# argparse aliases set dest to the literal typed string ("ls"/"audit").
action = getattr(_args, "worktree_action", None)
if action in ("ls", "audit"):
_args.worktree_action = "list"
return cmd_worktree(_args)
worktree_parser.set_defaults(func=_dispatch_worktree)