worktree-janitor 0.1.0__py3-none-any.whl

worktree_janitor/__init__.py

@@ -0,0 +1,3 @@
+"""worktree-janitor: clean up worktrees left behind by dead agent sessions."""
+
+__version__ = "0.1.0"

worktree_janitor/cli.py

@@ -0,0 +1,152 @@
+"""worktree-janitor CLI: list worktrees with claim status, prune dead ones."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .core import (
+    claim as core_claim,
+    claim_status,
+    heartbeat as core_heartbeat,
+    is_dirty,
+    is_merged,
+    list_worktrees,
+    prune as core_prune,
+    release as core_release,
+    repo_root,
+)
+
+
+def _status_table(repo: str, stale_after: float, as_json: bool) -> int:
+    root = repo_root(repo)
+    rows = []
+    for wt in list_worktrees(root):
+        status = claim_status(wt, stale_after)
+        dirty = is_dirty(wt)
+        merged = is_merged(wt)
+        rows.append(
+            {
+                "path": wt.path,
+                "branch": wt.branch or "(detached)",
+                "head": wt.head[:8],
+                "claim": status,
+                "dirty": dirty,
+                "merged": merged,
+                "main": wt.is_main,
+                "locked": wt.locked,
+            }
+        )
+    if as_json:
+        print(json.dumps(rows, indent=2))
+        return 0
+    header = f"{'PATH':<52} {'BRANCH':<18} {'CLAIM':<8} {'DIRTY':<6} {'MERGED':<7}"
+    print(header)
+    print("-" * len(header))
+    for r in rows:
+        merged = "?" if r["merged"] is None else ("yes" if r["merged"] else "no")
+        tags = []
+        if r["main"]:
+            tags.append("main")
+        if r["locked"]:
+            tags.append("locked")
+        path = r["path"] + (f" [{','.join(tags)}]" if tags else "")
+        print(
+            f"{path:<52} {r['branch']:<18} {r['claim']:<8} "
+            f"{'yes' if r['dirty'] else 'no':<6} {merged:<7}"
+        )
+    return 0
+
+
+def _prune(repo: str, dry_run: bool, yes: bool, include_unclaimed: bool,
+           stale_after: float) -> int:
+    effective_dry_run = dry_run or not yes
+    report = core_prune(
+        repo=repo,
+        dry_run=effective_dry_run,
+        include_unclaimed=include_unclaimed,
+        stale_after_minutes=stale_after,
+    )
+    if effective_dry_run:
+        print("DRY RUN -- nothing removed.")
+    for p in report["planned"]:
+        print(f"{'would remove' if effective_dry_run else 'removed'}: {p}")
+    for p in report["skipped_dirty"]:
+        print(f"SKIPPED (uncommitted changes, left alone): {p}", file=sys.stderr)
+    for p in report["skipped_active"]:
+        print(f"skipped (still claimed / unclaimed): {p}", file=sys.stderr)
+    for p in report["skipped_locked"]:
+        print(f"skipped (locked): {p}", file=sys.stderr)
+    for e in report["errors"]:
+        print(f"ERROR: {e}", file=sys.stderr)
+    return 1 if report["errors"] else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="wtj",
+        description="Janitor for git worktrees left behind by dead agent sessions.",
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    ap.add_argument("--repo", default=".",
+                    help="Path inside the repo to operate on (default: cwd).")
+    ap.add_argument("--stale-after", type=float, default=30.0,
+                    help="Minutes after which a heartbeat-less claim is dead "
+                         "(default: 30).")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_list = sub.add_parser("list", help="List worktrees with claim status.")
+    p_list.add_argument("--json", action="store_true",
+                        help="Machine-readable output.")
+
+    p_claim = sub.add_parser("claim", help="Claim a worktree for a session.")
+    p_claim.add_argument("path", help="Worktree path to claim.")
+    p_claim.add_argument("--session-id", default=None,
+                         help="Session id (default: current PID as string).")
+    p_claim.add_argument("--note", default="", help="Free-text note.")
+
+    p_release = sub.add_parser("release", help="Release a worktree claim.")
+    p_release.add_argument("path", help="Worktree path.")
+
+    p_hb = sub.add_parser("heartbeat", help="Refresh a worktree claim heartbeat.")
+    p_hb.add_argument("path", help="Worktree path.")
+
+    p_prune = sub.add_parser("prune", help="Remove dead-claim worktrees.")
+    p_prune.add_argument("--dry-run", action="store_true",
+                         help="Show what would be removed, remove nothing.")
+    p_prune.add_argument("--yes", action="store_true",
+                         help="Actually remove. Without it, acts as a dry run.")
+    p_prune.add_argument("--include-unclaimed", action="store_true",
+                         help="Also prune clean worktrees that have no claim.")
+
+    args = ap.parse_args(argv)
+
+    if args.cmd == "list":
+        return _status_table(args.repo, args.stale_after, args.json)
+    if args.cmd == "claim":
+        sid = args.session_id or f"pid:{os.getpid()}"
+        data = core_claim(args.path, sid, note=args.note)
+        print(f"claimed {os.path.realpath(args.path)} for session {data['session_id']}")
+        return 0
+    if args.cmd == "release":
+        if core_release(args.path):
+            print(f"released claim on {os.path.realpath(args.path)}")
+        else:
+            print("no claim found", file=sys.stderr)
+            return 1
+        return 0
+    if args.cmd == "heartbeat":
+        core_heartbeat(args.path)
+        print(f"heartbeat updated for {os.path.realpath(args.path)}")
+        return 0
+    if args.cmd == "prune":
+        return _prune(args.repo, args.dry_run, args.yes,
+                      args.include_unclaimed, args.stale_after)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

worktree_janitor/core.py

@@ -0,0 +1,333 @@
+"""Core logic for worktree-janitor: listing, claim detection, and pruning.
+
+A "claim" is a small JSON file written into a worktree's git admin dir
+(the `gitdir` reported by `git worktree list --porcelain`) by the agent
+session that created the worktree. It records the session id, the
+owner PID, and a heartbeat timestamp.
+
+A worktree is considered "dead" when its claim is stale:
+- the owner PID no longer exists, or
+- (when no PID is recorded) the heartbeat is older than the configured
+  staleness threshold.
+
+Dead claims are how the janitor distinguishes a worktree its session
+abandoned from one that is still in use. Worktrees with uncommitted
+changes are NEVER pruned, whatever the claim state.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+CLAIM_FILENAME = "worktree-claim.json"
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def _git(repo_path: str, *args: str, check: bool = True) -> str:
+    """Run `git -C <repo_path> ...` and return stdout."""
+    proc = subprocess.run(
+        ["git", "-C", repo_path, *args],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    if check and proc.returncode != 0:
+        raise GitError(
+            f"git {' '.join(args)} failed in {repo_path}: "
+            f"{proc.stderr.strip() or proc.stdout.strip()}"
+        )
+    return proc.stdout
+
+
+def repo_root(path: str = ".") -> str:
+    """Resolve the top-level directory of the git repo containing path."""
+    return os.path.realpath(
+        _git(path, "rev-parse", "--show-toplevel").strip()
+    )
+
+
+@dataclass
+class Worktree:
+    path: str
+    gitdir: str
+    head: str
+    branch: Optional[str]  # None when detached
+    bare: bool
+    locked: bool
+
+    @property
+    def is_main(self) -> bool:
+        # The main worktree's admin dir is <repo>/.git itself.
+        return os.path.basename(os.path.dirname(self.gitdir)) != "worktrees"
+
+
+def list_worktrees(repo: str = ".") -> list[Worktree]:
+    """Parse `git worktree list --porcelain` into Worktree records."""
+    root = repo_root(repo)
+    out = _git(root, "worktree", "list", "--porcelain")
+    worktrees: list[Worktree] = []
+    cur: dict = {}
+    for line in out.splitlines():
+        if not line.strip():
+            if cur:
+                worktrees.append(_build_worktree(cur))
+                cur = {}
+            continue
+        key, _, value = line.partition(" ")
+        if key == "worktree":
+            cur["path"] = value
+        elif key == "gitdir":
+            cur["gitdir"] = value
+        elif key == "HEAD":
+            cur["head"] = value
+        elif key == "branch":
+            cur["branch"] = value
+        elif key == "detached":
+            cur["branch"] = None
+        elif key == "bare":
+            cur["bare"] = True
+        elif key == "locked":
+            cur["locked"] = True
+    if cur:
+        worktrees.append(_build_worktree(cur))
+    return worktrees
+
+
+def _gitdir_of(path: str) -> str:
+    """Absolute git admin dir for a worktree path."""
+    try:
+        return _git(path, "rev-parse", "--absolute-git-dir").strip()
+    except GitError:
+        return ""
+
+
+def _build_worktree(cur: dict) -> Worktree:
+    path = os.path.realpath(cur.get("path", ""))
+    gitdir = cur.get("gitdir") or _gitdir_of(path)
+    return Worktree(
+        path=path,
+        gitdir=gitdir,
+        head=cur.get("head", ""),
+        branch=cur.get("branch"),
+        bare=bool(cur.get("bare", False)),
+        locked=bool(cur.get("locked", False)),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Claims
+# ---------------------------------------------------------------------------
+
+def claim_path(wt: Worktree) -> str:
+    return os.path.join(wt.gitdir, CLAIM_FILENAME)
+
+
+def read_claim(wt: Worktree) -> Optional[dict]:
+    """Return the claim dict, or None if there is no claim file."""
+    path = claim_path(wt)
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def claim(
+    worktree_path: str,
+    session_id: str,
+    note: str = "",
+    pid: Optional[int] = None,
+) -> dict:
+    """Claim a worktree for a session. Returns the claim dict."""
+    root = repo_root(worktree_path)
+    wts = [w for w in list_worktrees(root) if w.path == os.path.realpath(worktree_path)]
+    if not wts:
+        raise GitError(f"not a worktree of {root}: {worktree_path}")
+    wt = wts[0]
+    now = time.time()
+    data = {
+        "session_id": session_id,
+        "pid": pid if pid is not None else os.getpid(),
+        "created": now,
+        "heartbeat": now,
+        "note": note,
+    }
+    os.makedirs(wt.gitdir, exist_ok=True)
+    with open(claim_path(wt), "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+    return data
+
+
+def release(worktree_path: str) -> bool:
+    """Remove the claim from a worktree. Returns True if one existed."""
+    root = repo_root(worktree_path)
+    wts = [w for w in list_worktrees(root) if w.path == os.path.realpath(worktree_path)]
+    if not wts:
+        raise GitError(f"not a worktree of {root}: {worktree_path}")
+    path = claim_path(wts[0])
+    if os.path.isfile(path):
+        os.remove(path)
+        return True
+    return False
+
+
+def heartbeat(worktree_path: str) -> dict:
+    """Refresh the claim heartbeat. Raises if the worktree is unclaimed."""
+    root = repo_root(worktree_path)
+    wts = [w for w in list_worktrees(root) if w.path == os.path.realpath(worktree_path)]
+    if not wts:
+        raise GitError(f"not a worktree of {root}: {worktree_path}")
+    data = read_claim(wts[0])
+    if data is None:
+        raise GitError(f"worktree has no claim to heartbeat: {worktree_path}")
+    data["heartbeat"] = time.time()
+    with open(claim_path(wts[0]), "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+    return data
+
+
+def _pid_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
+def claim_status(wt: Worktree, stale_after_minutes: float = 30.0) -> str:
+    """Return 'active', 'dead', or 'none' for a worktree's claim."""
+    data = read_claim(wt)
+    if data is None:
+        return "none"
+    pid = data.get("pid")
+    if isinstance(pid, int) and pid > 0:
+        return "active" if _pid_alive(pid) else "dead"
+    heartbeat_ts = data.get("heartbeat", 0)
+    age = time.time() - float(heartbeat_ts or 0)
+    return "active" if age <= stale_after_minutes * 60 else "dead"
+
+
+# ---------------------------------------------------------------------------
+# Worktree state
+# ---------------------------------------------------------------------------
+
+def is_dirty(wt: Worktree) -> bool:
+    """True when the worktree has uncommitted changes or untracked files."""
+    if not os.path.isdir(wt.path):
+        return False
+    try:
+        out = _git(wt.path, "status", "--porcelain", check=False)
+    except GitError:
+        return False
+    return bool(out.strip())
+
+
+def is_merged(wt: Worktree, base_ref: Optional[str] = None) -> Optional[bool]:
+    """True when the worktree HEAD is an ancestor of the base ref.
+
+    Returns None when the check cannot be performed.
+    """
+    try:
+        if base_ref is None:
+            # Default: the HEAD of the main worktree of this repo.
+            root = repo_root(wt.path)
+            wts = list_worktrees(root)
+            mains = [w for w in wts if w.is_main and not w.bare]
+            base_ref = mains[0].head if mains else "HEAD"
+        proc = subprocess.run(
+            ["git", "-C", wt.path, "merge-base", "--is-ancestor", wt.head, base_ref],
+            capture_output=True,
+            timeout=60,
+        )
+        return proc.returncode == 0
+    except (GitError, OSError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Pruning
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PrunePlan:
+    to_remove: list[Worktree]
+    skipped_dirty: list[Worktree]
+    skipped_active: list[Worktree]
+    skipped_locked: list[Worktree]
+    skipped_main: list[Worktree]
+
+
+def plan_prune(
+    repo: str = ".",
+    include_unclaimed: bool = False,
+    stale_after_minutes: float = 30.0,
+) -> PrunePlan:
+    """Decide what a prune run would remove, without removing anything."""
+    root = repo_root(repo)
+    plan = PrunePlan([], [], [], [], [])
+    for wt in list_worktrees(root):
+        if wt.is_main or wt.bare:
+            plan.skipped_main.append(wt)
+            continue
+        if wt.locked:
+            plan.skipped_locked.append(wt)
+            continue
+        status = claim_status(wt, stale_after_minutes)
+        if status == "active":
+            plan.skipped_active.append(wt)
+            continue
+        if status == "none" and not include_unclaimed:
+            plan.skipped_active.append(wt)  # unclaimed, left alone by default
+            continue
+        if is_dirty(wt):
+            plan.skipped_dirty.append(wt)
+            continue
+        plan.to_remove.append(wt)
+    return plan
+
+
+def prune(
+    repo: str = ".",
+    dry_run: bool = True,
+    include_unclaimed: bool = False,
+    stale_after_minutes: float = 30.0,
+) -> dict:
+    """Remove dead-claim worktrees. Returns a report dict.
+
+    Actual removal only happens when dry_run is False. Worktrees with
+    uncommitted changes are never removed.
+    """
+    plan = plan_prune(repo, include_unclaimed, stale_after_minutes)
+    removed: list[str] = []
+    errors: list[str] = []
+    if not dry_run:
+        for wt in plan.to_remove:
+            try:
+                _git(repo, "worktree", "remove", wt.path)
+                removed.append(wt.path)
+            except GitError as exc:
+                errors.append(f"{wt.path}: {exc}")
+    return {
+        "dry_run": dry_run,
+        "removed": removed,
+        "errors": errors,
+        "planned": [w.path for w in plan.to_remove],
+        "skipped_dirty": [w.path for w in plan.skipped_dirty],
+        "skipped_active": [w.path for w in plan.skipped_active],
+        "skipped_locked": [w.path for w in plan.skipped_locked],
+    }

worktree_janitor-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: worktree-janitor
+Version: 0.1.0
+Summary: Clean up git worktrees left behind by dead agent sessions
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/worktree-janitor
+Project-URL: Repository, https://github.com/hahahahahahahahah6/worktree-janitor
+Project-URL: Issues, https://github.com/hahahahahahahahah6/worktree-janitor/issues
+Keywords: git,worktree,agents,cleanup,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# worktree-janitor
+
+Dead-session worktree cleanup for git. Multi-session agent fleets create
+`git worktree`s all the time -- and when a session dies, its worktrees leak:
+stale checkouts pile up, branches linger, and nobody remembers which
+worktree belongs to a live session. `worktree-janitor` is the CLI that
+finds them and prunes them, safely.
+
+```bash
+pip install worktree-janitor
+
+wtj list                          # worktrees + claim status
+wtj claim ./my-wt --session-id s1 # claim a worktree for your session
+wtj heartbeat ./my-wt             # refresh the claim while you work
+wtj prune --dry-run               # see what would go
+wtj prune --yes                   # remove dead-claim worktrees
+```
+
+## How it works
+
+A **claim** is a small JSON file (`worktree-claim.json`) stored in the
+worktree's git admin dir (the `gitdir` reported by
+`git worktree list --porcelain`), written by the session that created the
+worktree. It records the session id, the owner PID, and a heartbeat
+timestamp.
+
+A claim is **dead** when:
+- the owner PID no longer exists, or
+- (no PID recorded) the heartbeat is older than `--stale-after` minutes
+  (default 30).
+
+`wtj prune` removes worktrees whose claim is dead, and leaves everything
+else alone. The hard rule: **a worktree with uncommitted changes is never
+pruned**, no matter what. It is reported as skipped with a warning. The
+main worktree and locked worktrees are never touched either. Clean,
+unclaimed worktrees are skipped by default too; pass
+`--include-unclaimed` to prune those as well.
+
+`prune` is report-only unless you pass `--yes` (or use `--dry-run` to
+preview).
+
+## Usage
+
+```
+wtj list [--json] [--stale-after MIN]
+wtj claim <path> [--session-id ID] [--note TEXT]
+wtj heartbeat <path>
+wtj release <path>
+wtj prune [--dry-run] [--yes] [--include-unclaimed] [--stale-after MIN]
+wtj --repo /path/to/repo <command>   # operate on any repo
+```
+
+## Differentiation
+
+There are two sane shapes for worktree hygiene:
+
+- **Claim guards (interception style)**, e.g. Ben Newton's worktree claim
+  guard Mod for session-fleet: they intercept at *creation time* and stop a
+  session from touching a worktree another live session owns. Prevention.
+- **worktree-janitor (cleanup style)**: it runs *after the fact*. It does
+  not hook into your session runner or block anything -- it scans,
+  classifies, and one-shot prunes what is verifiably dead. Janitor, not
+  bouncer.
+
+The two compose: guard at creation, janitor on a cron or after a session
+fleet shuts down. This project is a sibling of `routine-sweeper` -- the
+same "session hygiene" family, but for git worktrees instead of routine
+files.
+
+## Safety model
+
+- dirty worktrees (uncommitted changes or untracked files) are never pruned
+- the main worktree and `bare` repos are never pruned
+- locked worktrees are skipped
+- active claims are skipped
+- unclaimed worktrees are skipped unless `--include-unclaimed`
+- `--yes` is required for any deletion; default is report-only
+
+## Development
+
+```bash
+python -m pytest tests/ -q   # 12 smoke tests, stdlib only
+```
+
+No dependencies -- the package is stdlib-only on purpose (it should work
+in any agent sandbox without a network install).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

worktree_janitor-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+worktree_janitor/__init__.py,sha256=-H96OgBjZpJwey5bQJd7l2gbjNEw8JD8CDTn-nEUbSM,102
+worktree_janitor/cli.py,sha256=iTKSbaTuQ81qstcn9u9TiFchu1aSEbCOUf4uRCG3HCI,5573
+worktree_janitor/core.py,sha256=5hyplmWu9MBMnnCRsTWmbXYwnF3n-l2tfFMs_uE3hYA,10400
+worktree_janitor-0.1.0.dist-info/licenses/LICENSE,sha256=OYhQDg7nxWoFtnF6J8NkFUA8NMw5TKv9a1WTXHY-fu4,1063
+worktree_janitor-0.1.0.dist-info/METADATA,sha256=g3cLNRFPQ39gbqAFOqXkOppw7kO6FFK8uC0_16odQ1o,4021
+worktree_janitor-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+worktree_janitor-0.1.0.dist-info/entry_points.txt,sha256=HYQwQzi48NtvXuc5koDKTDmLt9GkgZHh30uAQwlz4T0,50
+worktree_janitor-0.1.0.dist-info/top_level.txt,sha256=jNq5573KmT1sQyEQodW2gCPv7mq7BsHHjQPNPiusCqo,17
+worktree_janitor-0.1.0.dist-info/RECORD,,

worktree_janitor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

worktree_janitor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wtj = worktree_janitor.cli:main

worktree_janitor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

worktree_janitor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+worktree_janitor