@caddis/cli 0.4.66 → 0.4.67

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.152",
+  "version": "1.3.153",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/scripts/caddis_created.py

@@ -0,0 +1,191 @@
+"""What a session CREATED and must clean up: worktrees and scratch folders, recorded per session.
+
+Why a file of its own. The Stop hook rewrites `.caddis/session-state/<id>.md` every turn, so a record kept there is
+lost. A session also often makes worktrees in OTHER repos. So the record lives outside every repo:
+
+    ~/.caddis/sessions/<session-id>.created.jsonl        (append-only; one JSON object per line)
+
+(`~` is `$CADDIS_HOME` when set, else the user's home folder; the `home` argument beats both. The folder also holds
+other code's `<session-id>.json` files; this module never touches those.)
+
+A line is one fact about one path:
+
+    {"path", "kind": "worktree"|"scratch", "created": <ISO UTC>, "purpose", "pr": str|null, "repo": str|null,
+     "branch": str|null, "status": "created"|"removed", "by": "helper"|"lanes"|"roadmap-run"|"docs-pr"|
+     "transcript"|"cli"}
+
+`read` FOLDS the lines by normalised path (case-insensitive on Windows): `created` keeps the first value and every
+other field takes the latest non-null value. So "record again with the PR number" and "mark removed" are just new
+lines. One exception, which is a safety rule: a `created` line for a path whose last status was `removed` starts a
+NEW entry. A path that is used again (a roadmap worktree has a fixed name) must not inherit the old PR.
+
+This module only RECORDS. It deletes nothing; `cleanup` hands off to `caddis_own_cleanup.py`, which does.
+
+    session_id(explicit=None)  -> a safe session id, or None
+    record(path, kind, purpose, *, pr, repo, branch, status, by, session_id, home) -> bool   (never raises)
+    read(session_id, home=None) -> list[dict]       (folded; oldest first; bad lines skipped)
+
+CLI (exit 0 on success; `record` with no session id warns on stderr and still exits 0, so a caller never breaks;
+exit 2 on bad arguments):
+    python caddis_created.py record --path P --kind worktree --purpose "why" [--pr N] [--repo R] [--branch B]
+                                    [--status removed] [--by cli] [--session-id S]
+    python caddis_created.py list [--session-id S] [--json]
+    python caddis_created.py cleanup [--session-id S] [--apply] [--json]   (dry run by default; always exit 0)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+SESSION_ENV_VARS = ("CADDIS_SESSION_ID", "CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")  # as caddis_adhoc.session_key
+KINDS = ("worktree", "scratch")
+STATUSES = ("created", "removed")
+BYS = ("helper", "lanes", "roadmap-run", "docs-pr", "transcript", "cli")
+_SAFE_ID = re.compile(r"[A-Za-z0-9_-]{1,100}")  # no separator, drive colon or dots: a plain file-name stem
+_FIELDS = ("purpose", "pr", "repo", "branch", "by")
+
+
+def _sid(explicit: str | None = None) -> str | None:
+    """`explicit` (even "", which gives None), else the first non-blank session env var. None when there is none or not a safe file
+    name (a bad explicit id does NOT fall back to the environment: that would record under the wrong session)."""
+    candidates = [explicit] if explicit is not None else [os.environ.get(name) for name in SESSION_ENV_VARS]
+    for raw in candidates:
+        value = (raw or "").strip()
+        if value:
+            return value if _SAFE_ID.fullmatch(value) else None
+    return None
+
+
+def session_id(explicit: str | None = None) -> str | None:
+    """The session id to record under: see `_sid`."""
+    return _sid(explicit)
+
+
+def _file(sid: str, home: Path | str | None) -> Path:
+    root = Path(home) if home else Path(os.environ.get("CADDIS_HOME") or Path.home())
+    return root / ".caddis" / "sessions" / f"{sid}.created.jsonl"
+
+
+def _normalise(path: str | os.PathLike) -> str:
+    """Absolute, `..` collapsed. Not resolved: resolving would follow a link, and the record names the path as made."""
+    return os.path.abspath(os.fspath(path))
+
+
+def _key(path: str) -> str:
+    return os.path.normcase(path)  # lower-case and backslashes on Windows; unchanged elsewhere
+
+
+def record(path: str | os.PathLike, kind: str, purpose: str = "", *, pr: str | int | None = None,
+           repo: str | os.PathLike | None = None, branch: str | None = None, status: str = "created",
+           by: str = "cli", session_id: str | None = None, home: Path | str | None = None) -> bool:
+    """Append one line. False, and nothing written, with no usable session id, an unknown kind or status, or any I/O
+    error. Never raises: callers are hooks and runners."""
+    try:
+        sid = _sid(session_id)
+        if not sid or kind not in KINDS or status not in STATUSES or not str(path).strip():
+            return False
+        line = {
+            "path": _normalise(path), "kind": kind,
+            "created": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "purpose": str(purpose or ""), "pr": None if pr is None or str(pr) == "" else str(pr),
+            "repo": _normalise(repo) if repo else None, "branch": branch or None, "status": status, "by": by,
+        }
+        target = _file(sid, home)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with open(target, "a", encoding="utf-8", newline="\n") as handle:
+            handle.write(json.dumps(line, ensure_ascii=False) + "\n")  # one write call: appends do not interleave
+        return True
+    except Exception:  # noqa: BLE001 - a recording failure must never break the caller
+        return False
+
+
+def read(session_id: str, home: Path | str | None = None) -> list[dict]:
+    """The session's entries, folded by path, oldest `created` first. [] when there is no file; bad lines are skipped."""
+    try:
+        sid = session_id if _SAFE_ID.fullmatch(session_id or "") else None  # strict: no env fallback when reading
+        if not sid:
+            return []
+        text = _file(sid, home).read_text(encoding="utf-8", errors="replace")
+    except Exception:  # noqa: BLE001
+        return []
+    folded: dict[str, dict] = {}
+    for raw in text.splitlines():
+        try:
+            line = json.loads(raw)
+        except ValueError:
+            continue
+        if not (isinstance(line, dict) and isinstance(line.get("path"), str) and line["path"]
+                and line.get("kind") in KINDS and line.get("status") in STATUSES):
+            continue
+        key = _key(line["path"])
+        entry = folded.get(key)
+        if entry is None or (entry["status"] == "removed" and line["status"] == "created"):
+            folded[key] = {"path": line["path"], "kind": line["kind"], "created": str(line.get("created") or ""),
+                           "status": line["status"], **{name: line.get(name) for name in _FIELDS}}
+            continue
+        entry["status"] = line["status"]
+        entry["kind"] = line["kind"]
+        for name in _FIELDS:
+            if line.get(name) is not None and not (name == "purpose" and line[name] == ""):
+                entry[name] = line[name]
+    return sorted(folded.values(), key=lambda e: e["created"])  # stable: equal stamps keep file order
+
+
+def _summary(entry: dict) -> str:
+    text = f"{entry['path']} | {entry['kind']} | {entry['status']} | {entry.get('purpose') or ''}"
+    return text + (f" | PR {entry['pr']}" if entry.get("pr") else "")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Record or list what this session created (worktrees, scratch folders).")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    rec = sub.add_parser("record", help="append one line for a path")
+    rec.add_argument("--path", required=True)
+    rec.add_argument("--kind", required=True, choices=KINDS)
+    rec.add_argument("--purpose", default="")
+    rec.add_argument("--pr", default=None)
+    rec.add_argument("--repo", default=None)
+    rec.add_argument("--branch", default=None)
+    rec.add_argument("--status", default="created", choices=STATUSES)
+    rec.add_argument("--by", default="cli", choices=BYS)
+    rec.add_argument("--session-id", default=None)
+    lst = sub.add_parser("list", help="print the folded entries")
+    lst.add_argument("--session-id", default=None)
+    lst.add_argument("--json", action="store_true")
+    cln = sub.add_parser("cleanup", help="remove this session's merged, clean worktrees and scratch folders")
+    cln.add_argument("--session-id", default=None)
+    cln.add_argument("--apply", action="store_true", help="act; without it, only list (the default)")
+    cln.add_argument("--json", action="store_true")
+    try:
+        args = ap.parse_args(argv)
+    except SystemExit as exc:
+        return int(exc.code) if isinstance(exc.code, int) else 2
+    sid = session_id(args.session_id)
+    if args.cmd == "record":
+        if not record(args.path, args.kind, args.purpose, pr=args.pr, repo=args.repo, branch=args.branch,
+                      status=args.status, by=args.by, session_id=args.session_id):
+            why = "no usable session id" if not sid else "the record could not be written"
+            print(f"caddis_created: not recorded ({why}): {args.path}", file=sys.stderr)
+        return 0
+    if args.cmd == "cleanup":
+        import caddis_own_cleanup  # it deletes, so it lives apart from this record-only module (and imports it)
+        return caddis_own_cleanup.run(sid, args.apply, args.json)
+    if not sid:
+        print("caddis_created: no usable session id; nothing to list", file=sys.stderr)
+    entries = read(sid) if sid else []
+    if args.json:
+        print(json.dumps(entries, indent=2, ensure_ascii=False))
+    else:
+        for entry in entries:
+            print(_summary(entry))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundles/antigravity-plugin/scripts/caddis_docs_pr.py

@@ -37,15 +37,18 @@ import tempfile
 from pathlib import Path
 
 try:
+    import caddis_created
     import caddis_exit
     import caddis_checkout_guard
     import caddis_roadmap as roadmap
     import caddis_worktree_safety
 except ModuleNotFoundError as exc:
-    if exc.name not in {"caddis_exit", "caddis_checkout_guard", "caddis_roadmap", "caddis_worktree_safety"}:
+    if exc.name not in {"caddis_created", "caddis_exit", "caddis_checkout_guard", "caddis_roadmap",
+                        "caddis_worktree_safety"}:
         raise
     sys.path.insert(0, str(Path(__file__).resolve().parent))
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
+    import caddis_created
     import caddis_exit
     import caddis_checkout_guard
     import caddis_roadmap as roadmap
@@ -87,6 +90,7 @@ def start(repo: Path, out=print) -> int:
     worktree = tmp_root / f"{DIR_PREFIX}{stamp}{suffix}"
     branch = f"{BRANCH_PREFIX}{stamp}{suffix}"
     _git(repo, "worktree", "add", "--quiet", "-b", branch, str(worktree), f"origin/{base}")
+    caddis_created.record(worktree, "worktree", "handoff docs PR", repo=repo, branch=branch, by="docs-pr")
     out(f"WORKTREE: {worktree}")
     return caddis_exit.CLEAN
 
@@ -199,7 +203,7 @@ def _save_patch(worktree: Path) -> Path:
     return Path(name)
 
 
-def _remove(main: Path, worktree: Path, branch: str) -> None:
+def _remove(main: Path, worktree: Path, branch: str, pr: str | None = None) -> None:
     """Remove the worktree (links first, so a junction's target survives), prune, delete the branch.
 
     Best effort, as before: the result of each step is not checked. Every caller has already saved the session's
@@ -215,6 +219,9 @@ def _remove(main: Path, worktree: Path, branch: str) -> None:
         pass
     if worktree.exists():
         caddis_worktree_safety.remove_tree(worktree)
+    if not worktree.exists():  # only a folder that is really gone is recorded as removed
+        caddis_created.record(worktree, "worktree", "", pr=pr, repo=main, branch=branch, status="removed",
+                              by="docs-pr")
 
 
 def finish(worktree: Path, title: str, body: str, out=print) -> int:
@@ -257,7 +264,8 @@ def finish(worktree: Path, title: str, body: str, out=print) -> int:
     out(f"PR: {url}")
     for path in files:
         out(f"FILE: {path}")
-    _remove(main, worktree, branch)
+    pr_number = re.search(r"/pull/(\d+)\s*$", url)
+    _remove(main, worktree, branch, pr=pr_number.group(1) if pr_number else None)
     try:
         patch.unlink()
     except OSError:

package/bundles/antigravity-plugin/scripts/caddis_lanes.py

@@ -34,6 +34,7 @@ except ModuleNotFoundError as exc:
     from caddis_heavy_slot import HeavySlotBusy, heavy_slot
 
 import caddis_checkout_guard
+import caddis_created
 import caddis_routing
 import caddis_redact
 import caddis_spend
@@ -284,6 +285,8 @@ def create_phase_worktree(
         str(path),
         base_sha,
     )
+    caddis_created.record(path, "worktree", f"lane {plan_stem} phase {phase:02d} attempt {attempt}", repo=repo_root,
+                          branch=branch, by="lanes")
     print(f"[caddis-lanes] worktree: {path}", file=sys.stderr)
     return Worktree(path=path, branch=branch, base_sha=base_sha)
 
@@ -307,6 +310,7 @@ def remove_phase_worktree(
         problem = f"worktree remove left {resolved} on disk"
     if problem:
         raise LaneConfigError(problem)
+    caddis_created.record(resolved, "worktree", "", repo=repo_root, branch=wt.branch, status="removed", by="lanes")
     if delete_branch:
         _git_output(repo_root, "branch", "-D", "--", wt.branch)
 

package/bundles/antigravity-plugin/scripts/caddis_own_cleanup.py

@@ -0,0 +1,424 @@
+"""Remove THIS session's own leftovers at handoff: merged, clean worktrees and scratch folders (tidy v2, Phase 2).
+
+Input is the session's record (`caddis_created.read`): only the paths this session made. Each entry with status
+`created` gets one decision; the first rule that matches wins. Anything in doubt is KEPT, with the reason.
+
+Worktree (in order):
+  by roadmap-run -> KEPT (the runner reuses and removes its own) | missing -> GONE | a link, the main checkout, or
+  not a registered linked worktree -> KEPT | the process cwd is in it -> KEPT | `git status` not clean (untracked
+  counts) -> KEPT | locked -> KEPT | on the default branch -> KEPT | no merged PR (no gh, gh error, no PR, PR not
+  MERGED, PR head branch differs) -> KEPT | PR head commit unknown here, or commits after it -> KEPT | a file the branch changed differs
+  from `origin/<default>` (fetched first; this is the squash-merge proof that the work landed) -> KEPT |
+  else REMOVE: `safe_remove_worktree` (links first, never --force), then the local branch (only while its tip is
+  HEAD or the PR head and no other worktree has it), then the remote branch (only while its tip is the PR head or
+  the local tip, as one compare-and-delete push).
+Scratch: missing -> GONE | a link, a root or home folder, or holds the cwd -> KEPT | inside a git checkout and
+  holds tracked files -> KEPT | a full scan (links never followed) that hits an unreadable folder -> KEPT | holds a git repo that is dirty, has commits on no remote, or is
+  a linked worktree -> KEPT | else REMOVE via `remove_tree` (links first).
+
+Dry run is the default; `apply=True` acts and records `status=removed` (GONE too). Nothing raises to the caller.
+
+    cleanup(session_id, *, apply, home, pr_lookup, cwd) -> list[{path, kind, action, reason}]
+      action: REMOVE (dry run) | REMOVED | KEPT | GONE | FAILED
+    summary(results, apply) -> "[OWN-CLEANUP] removed <n>, kept <n>, gone <n>, failed <n>"
+    run(session_id, apply, as_json) -> 0                 (the `caddis_created.py cleanup` CLI)
+
+`pr_lookup(main_repo, branch, pr) -> list[{number, state, headRefOid, headRefName}]` (newest first) is the gh
+seam; it raises PrLookupError. The default calls plain `gh` with the inherited environment (never `gh auth switch`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import caddis_created
+import caddis_worktree_safety as safety
+
+GIT_TIMEOUT = 60
+NET_TIMEOUT = 120
+_GH_FIELDS = "number,state,headRefOid,mergedAt,headRefName"
+
+
+class PrLookupError(Exception):
+    """gh is missing, failed, or the repo cannot be named."""
+
+
+def _env() -> dict[str, str]:
+    env = dict(os.environ)
+    env["GIT_TERMINAL_PROMPT"] = "0"  # a credential prompt must fail, not hang the handoff
+    return env
+
+
+def _run(cmd: list[str], cwd: Path | None = None, timeout: int = GIT_TIMEOUT) -> subprocess.CompletedProcess:
+    """Never raises: a missing program or a timeout comes back as returncode -1 with the problem in stderr."""
+    try:
+        return subprocess.run(cmd, cwd=str(cwd) if cwd else None, capture_output=True, text=True, encoding="utf-8",
+                              errors="replace", stdin=subprocess.DEVNULL, timeout=timeout, check=False, env=_env())
+    except FileNotFoundError:
+        return subprocess.CompletedProcess(cmd, -1, "", f"{cmd[0]} is not installed")
+    except subprocess.TimeoutExpired:
+        return subprocess.CompletedProcess(cmd, -1, "", f"{cmd[0]} timed out after {timeout} s")
+    except OSError as exc:
+        return subprocess.CompletedProcess(cmd, -1, "", str(exc))
+
+
+def _git(path: Path, *args: str, timeout: int = GIT_TIMEOUT) -> subprocess.CompletedProcess:
+    return _run(["git", "-c", "core.quotepath=off", "-C", str(path), *args], timeout=timeout)
+
+
+def _err(proc: subprocess.CompletedProcess) -> str:
+    text = (proc.stderr or proc.stdout or "").strip()
+    return text.splitlines()[-1] if text else f"exit {proc.returncode}"
+
+
+def _same(a: str | Path, b: str | Path) -> bool:
+    return os.path.normcase(os.path.realpath(a)) == os.path.normcase(os.path.realpath(b))
+
+
+def _inside(child: str | Path, parent: str | Path) -> bool:
+    """`child` is `parent` or under it (both resolved, case-folded on Windows)."""
+    c = os.path.normcase(os.path.realpath(child))
+    p = os.path.normcase(os.path.realpath(parent))
+    return c == p or c.startswith(p.rstrip("\\/") + os.sep)
+
+
+# -- gh ---------------------------------------------------------------------------------------------------------
+
+def _slug(main_repo: Path) -> str | None:
+    """`owner/name` from the origin URL (https, ssh or scp form), else None."""
+    proc = _git(main_repo, "remote", "get-url", "origin")
+    url = proc.stdout.strip() if proc.returncode == 0 else ""
+    if "://" not in url and "@" not in url:
+        return None  # a local path origin has no GitHub name
+    match = re.search(r"[:/]([^/:]+)/([^/]+?)(?:\.git)?/?$", url)
+    return f"{match.group(1)}/{match.group(2)}" if match else None
+
+
+def gh_pr_lookup(main_repo: Path, branch: str | None, pr: str | None) -> list[dict]:
+    slug = _slug(main_repo)
+    if not slug:
+        raise PrLookupError("cannot read owner/name from the origin URL")
+    if pr:
+        proc = _run(["gh", "pr", "view", pr, "--repo", slug, "--json", _GH_FIELDS], timeout=NET_TIMEOUT)
+    elif branch:
+        proc = _run(["gh", "pr", "list", "--repo", slug, "--head", branch, "--state", "all", "--limit", "20",
+                     "--json", _GH_FIELDS], timeout=NET_TIMEOUT)
+    else:
+        return []
+    if proc.returncode != 0:
+        raise PrLookupError(f"gh failed: {_err(proc)}")
+    try:
+        data = json.loads(proc.stdout or "null")
+    except ValueError as exc:
+        raise PrLookupError(f"gh printed bad JSON: {exc}") from exc
+    data = [data] if isinstance(data, dict) else data
+    if not isinstance(data, list):
+        raise PrLookupError("gh printed an unexpected shape")
+    return [d for d in data if isinstance(d, dict)]
+
+
+def _pr_number(value: str | None) -> str | None:
+    match = re.search(r"(\d+)\s*$", str(value or ""))
+    return match.group(1) if match else None
+
+
+def _pick_pr(prs: list[dict], branch: str | None, by_number: bool) -> tuple[dict | None, str]:
+    """(the merged PR, "") or (None, why the worktree is kept)."""
+    if not prs:
+        return None, f"no merged PR found: no PR for branch {branch}" if branch else "no merged PR found: no PR"
+    open_pr = next((p for p in prs if str(p.get("state", "")).upper() == "OPEN"), None)
+    pick = open_pr or prs[0]
+    state = str(pick.get("state", "")).upper() or "UNKNOWN"
+    if state != "MERGED":
+        return None, f"PR #{pick.get('number')} is {state}"
+    head_name = pick.get("headRefName")
+    if by_number and branch and head_name and head_name != branch:
+        return None, f"PR #{pick.get('number')} is for branch {head_name}, not {branch}"
+    return pick, ""
+
+
+# -- worktree ---------------------------------------------------------------------------------------------------
+
+def _main_repo(entry: dict, path: Path) -> Path | None:
+    """The repo to list worktrees from: the entry's `repo` when it is a git checkout, else from the path's common dir."""
+    for start in (entry.get("repo"), str(path)):
+        if not start or not os.path.isdir(start):
+            continue
+        proc = _git(Path(start), "rev-parse", "--path-format=absolute", "--git-common-dir")
+        if proc.returncode == 0 and proc.stdout.strip():
+            common = Path(proc.stdout.strip())
+            return common.parent if common.name == ".git" else Path(start)
+    return None
+
+
+def _default_branch(wt: Path) -> str:
+    proc = _git(wt, "symbolic-ref", "--short", "-q", "refs/remotes/origin/HEAD")
+    name = proc.stdout.strip() if proc.returncode == 0 else ""
+    return name.split("/", 1)[1] if name.startswith("origin/") else "main"
+
+
+def _ref(wt: Path, rev: str) -> str | None:
+    proc = _git(wt, "rev-parse", "-q", "--verify", f"{rev}^{{commit}}")
+    return proc.stdout.strip() if proc.returncode == 0 and proc.stdout.strip() else None
+
+
+def _names(wt: Path, a: str, b: str) -> set[str] | None:
+    proc = _git(wt, "diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", a, b)
+    return None if proc.returncode != 0 else {n for n in proc.stdout.split("\0") if n}
+
+
+def _check_worktree(entry: dict, path: Path, cwd: str, pr_lookup: Callable) -> tuple[str, str, dict]:
+    """("REMOVE", reason, facts) or ("KEPT"/"GONE", reason, {})."""
+    if entry.get("by") == "roadmap-run":
+        return "KEPT", "owned by the roadmap runner", {}
+    if not os.path.lexists(path):
+        return "GONE", "", {}
+    try:
+        if safety.is_link(os.lstat(path)):
+            return "KEPT", "the folder is a junction or symlink", {}
+    except OSError as exc:
+        return "KEPT", f"cannot inspect it: {exc}", {}
+    repo = _main_repo(entry, path)
+    if repo is None:
+        return "KEPT", "not a registered linked worktree (no git repo found)", {}
+    listing = _git(repo, "worktree", "list", "--porcelain")
+    if listing.returncode != 0:
+        return "KEPT", f"git worktree list failed: {_err(listing)}", {}
+    blocks = safety._worktree_blocks(listing.stdout)
+    if not blocks:
+        return "KEPT", "git listed no worktrees", {}
+    main = Path(blocks[0][0][len("worktree "):])
+    if _same(path, main):
+        return "KEPT", "it is the main checkout", {}
+    block = next((b for b in blocks[1:] if _same(path, b[0][len("worktree "):])), None)
+    if block is None:
+        return "KEPT", f"not a registered linked worktree of {main}", {}
+    if _inside(cwd, path):
+        return "KEPT", "this session is working in it", {}
+    status = _git(path, "status", "--porcelain", "--untracked-files=normal")
+    if status.returncode != 0:
+        return "KEPT", f"git status failed: {_err(status)}", {}
+    if status.stdout.strip():
+        return "KEPT", "uncommitted changes", {}
+    if any(line == "locked" or line.startswith("locked ") for line in block):
+        return "KEPT", "it is locked", {}
+    sym = _git(path, "symbolic-ref", "--short", "-q", "HEAD")
+    branch = sym.stdout.strip() if sym.returncode == 0 and sym.stdout.strip() else (entry.get("branch") or None)
+    default = _default_branch(path)
+    if branch and branch == default:
+        return "KEPT", f"it is on the default branch {default}", {}
+    pr = _pr_number(entry.get("pr"))
+    if not branch and not pr:
+        return "KEPT", "no merged PR found: no branch and no PR in the record", {}
+    try:
+        prs = pr_lookup(main, branch, pr)
+    except PrLookupError as exc:
+        return "KEPT", f"no merged PR found: {exc}", {}
+    except Exception as exc:  # noqa: BLE001 - any lookup failure keeps the worktree
+        return "KEPT", f"no merged PR found: lookup failed: {exc}", {}
+    merged, why = _pick_pr(prs, branch, by_number=bool(pr))
+    if merged is None:
+        return "KEPT", why, {}
+    number = str(merged.get("number") or pr or "?")
+    head = _ref(path, "HEAD")
+    if not head:
+        return "KEPT", "cannot read HEAD", {}
+    pr_head = str(merged.get("headRefOid") or "").strip().lower()
+    if not pr_head or not _ref(path, pr_head):  # a reused branch name: without the PR head, nothing proves HEAD landed
+        return "KEPT", f"PR #{number} head commit is not in the local repo", {}
+    after = _git(path, "rev-list", "--max-count=1", f"{pr_head}..HEAD")
+    if after.returncode != 0:
+        return "KEPT", f"git rev-list failed: {_err(after)}", {}
+    if after.stdout.strip():
+        return "KEPT", f"commits after the merged PR #{number}", {}
+    fetch = _git(path, "fetch", "--quiet", "--no-tags", "origin",
+                 f"+refs/heads/{default}:refs/remotes/origin/{default}", timeout=NET_TIMEOUT)
+    if fetch.returncode != 0:
+        return "KEPT", f"cannot fetch origin/{default}: {_err(fetch)}", {}
+    target = f"refs/remotes/origin/{default}"
+    base = _git(path, "merge-base", target, "HEAD")
+    if base.returncode != 0 or not base.stdout.strip():
+        return "KEPT", f"no merge base with origin/{default}", {}
+    changed = _names(path, base.stdout.strip(), "HEAD")
+    differ_all = _names(path, target, "HEAD")
+    if changed is None or differ_all is None:
+        return "KEPT", f"git diff against origin/{default} failed", {}
+    differ = sorted(changed & differ_all)
+    if differ:
+        return "KEPT", f"{len(differ)} file(s) differ from origin/{default}: {', '.join(differ[:3])}", {}
+    facts = {"repo": main, "branch": branch, "pr": number, "pr_head": pr_head, "head": head}
+    return "REMOVE", f"PR #{number} merged, clean, tree equals origin/{default}", facts
+
+
+def _branch_tip(repo: Path, branch: str) -> str | None:
+    proc = _git(repo, "rev-parse", "-q", "--verify", f"refs/heads/{branch}")
+    return proc.stdout.strip() if proc.returncode == 0 and proc.stdout.strip() else None
+
+
+def _remove_worktree(path: Path, facts: dict) -> tuple[str, str]:
+    repo, branch, head, pr_head = facts["repo"], facts["branch"], facts["head"], facts["pr_head"]
+    local_tip = _branch_tip(repo, branch) if branch else None
+    problem = safety.safe_remove_worktree(repo, path, force=False, env=_env())
+    if problem:
+        return "FAILED", problem
+    notes: list[str] = []
+    if branch and local_tip:
+        listing = _git(repo, "worktree", "list", "--porcelain")
+        if listing.returncode != 0 or f"branch refs/heads/{branch}" in listing.stdout.splitlines():
+            notes.append("local branch kept: another worktree has it checked out")
+        elif local_tip not in {head, pr_head}:
+            notes.append("local branch kept: its tip is not the removed HEAD or the PR head")
+        else:
+            gone = _git(repo, "branch", "-D", "--", branch)
+            notes.append("local branch deleted" if gone.returncode == 0 else f"local branch kept: {_err(gone)}")
+    if branch:
+        ls = _git(repo, "ls-remote", "--heads", "origin", f"refs/heads/{branch}", timeout=NET_TIMEOUT)
+        tips = [ln.split()[0] for ln in ls.stdout.splitlines() if ln.strip()] if ls.returncode == 0 else []
+        if ls.returncode != 0:
+            notes.append(f"remote branch kept: ls-remote failed: {_err(ls)}")
+        elif tips:
+            tip = tips[0].lower()
+            if tip in {pr_head, head.lower()} - {""}:  # only a tip this check proved landed
+                try:
+                    push = _git(repo, *safety.remote_delete_args(branch, tip), timeout=NET_TIMEOUT)
+                    notes.append("remote branch deleted" if push.returncode == 0
+                                 else f"remote branch kept: {_err(push)}")
+                except ValueError as exc:
+                    notes.append(f"remote branch kept: {exc}")
+            else:
+                notes.append("remote branch kept: its tip moved past the PR head")
+    return "REMOVED", "; ".join(notes)
+
+
+# -- scratch ----------------------------------------------------------------------------------------------------
+
+def _scan_scratch(path: Path) -> str | None:
+    """None when the folder may go, else why not. Walks every folder (links never followed); errors raise."""
+    def fail(exc: OSError) -> None:
+        raise exc
+
+    try:
+        for top, dirs, files in os.walk(path, topdown=True, onerror=fail, followlinks=False):
+            # os.walk does not see a Windows junction as a link: prune every link by lstat, so none is walked
+            dirs[:] = [d for d in dirs if not safety.is_link(os.lstat(os.path.join(top, d)))]
+            if ".git" not in dirs and ".git" not in files:
+                continue
+            repo = Path(top)
+            if os.path.isfile(repo / ".git"):
+                return f"holds a linked git worktree at {repo}; remove it as a worktree"
+            status = _git(repo, "status", "--porcelain")
+            if status.returncode != 0:
+                return f"holds a git repo at {repo} whose status failed: {_err(status)}"
+            if status.stdout.strip():
+                return f"holds a git repo with uncommitted changes at {repo}"
+            local = _git(repo, "rev-list", "--max-count=1", "--all", "--not", "--remotes")
+            if local.returncode != 0 or local.stdout.strip():
+                return f"holds a git repo with commits or a stash on no remote at {repo}"
+            dirs[:] = [d for d in dirs if d != ".git"]
+    except OSError as exc:
+        return f"cannot scan: {exc}"
+    return None
+
+
+def _check_scratch(path: Path, cwd: str) -> tuple[str, str]:
+    if not os.path.lexists(path):
+        return "GONE", ""
+    try:
+        if safety.is_link(os.lstat(path)):
+            return "KEPT", "the folder is a junction or symlink"
+    except OSError as exc:
+        return "KEPT", f"cannot inspect it: {exc}"
+    if not path.is_dir():
+        return "KEPT", "not a folder"
+    resolved = Path(os.path.realpath(path))
+    if resolved.parent == resolved or _same(resolved, Path.home()) or _inside(Path.home(), resolved):
+        return "KEPT", "a root or home folder is never scratch"
+    if _inside(cwd, path):
+        return "KEPT", "this session is working in it"
+    if not os.path.lexists(path / ".git"):  # a folder inside a checkout must not take tracked files with it
+        inside = _git(path, "rev-parse", "--is-inside-work-tree")
+        if inside.returncode == 0 and inside.stdout.strip() == "true":
+            tracked = _git(path, "ls-files", "-z", "--", ".")
+            if tracked.returncode != 0 or tracked.stdout.strip("\0"):
+                return "KEPT", "inside a git checkout and holds tracked files"
+    problem = _scan_scratch(path)
+    return ("KEPT", problem) if problem else ("REMOVE", "scratch folder of this session")
+
+
+# -- driver -----------------------------------------------------------------------------------------------------
+
+def _mark_removed(entry: dict, sid: str, home, pr: str | None = None) -> None:
+    by = entry.get("by") if entry.get("by") in caddis_created.BYS else "cli"
+    caddis_created.record(entry["path"], entry["kind"], "", pr=pr, status="removed", by=by, session_id=sid,
+                          home=home)
+
+
+def cleanup(session_id: str, *, apply: bool = False, home: Path | str | None = None,
+            pr_lookup: Callable | None = None, cwd: str | Path | None = None) -> list[dict]:
+    lookup = pr_lookup or gh_pr_lookup
+    here = str(cwd) if cwd is not None else os.getcwd()
+    results: list[dict] = []
+    for entry in caddis_created.read(session_id, home=home):
+        if entry.get("status") != "created":
+            continue
+        path = Path(entry["path"])
+        try:
+            if entry["kind"] == "worktree":
+                action, reason, facts = _check_worktree(entry, path, here, lookup)
+            else:
+                (action, reason), facts = _check_scratch(path, here), {}
+            if apply and action == "GONE":
+                _mark_removed(entry, session_id, home)
+            elif apply and action == "REMOVE":
+                if entry["kind"] == "worktree":
+                    action, notes = _remove_worktree(path, facts)
+                    if action != "REMOVED":
+                        reason = notes
+                    elif notes:
+                        reason = f"{reason}; {notes}"
+                else:
+                    problem = safety.remove_tree(path)
+                    action, reason = ("FAILED", problem) if problem else ("REMOVED", reason)
+                if action == "REMOVED":
+                    _mark_removed(entry, session_id, home, facts.get("pr"))
+        except Exception as exc:  # noqa: BLE001 - one bad entry must not stop the others
+            action, reason = "FAILED", f"unexpected error: {exc}"
+        results.append({"path": str(path), "kind": entry["kind"], "action": action, "reason": reason})
+    return results
+
+
+def line(result: dict) -> str:
+    action, path, reason = result["action"], result["path"], result["reason"]
+    if action == "GONE":
+        return f"GONE {path}"
+    if action in ("REMOVE", "REMOVED"):
+        return f"{action} {path}" + (f" ({reason})" if reason else "")
+    return f"{action} {path}: {reason}"
+
+
+def summary(results: list[dict], apply: bool) -> str:
+    count = {a: sum(1 for r in results if r["action"] == a) for a in ("REMOVE", "REMOVED", "KEPT", "GONE", "FAILED")}
+    head = f"removed {count['REMOVED']}" if apply else f"would remove {count['REMOVE']}"
+    return f"[OWN-CLEANUP] {head}, kept {count['KEPT']}, gone {count['GONE']}, failed {count['FAILED']}"
+
+
+def run(session_id: str | None, apply: bool, as_json: bool) -> int:
+    """The CLI body. Always 0: a handoff must never fail on its cleanup row."""
+    if not session_id:
+        print("caddis_created: no usable session id; nothing to clean up", file=sys.stderr)
+        results: list[dict] = []
+    else:
+        results = cleanup(session_id, apply=apply)
+    if as_json:
+        print(json.dumps(results, indent=2, ensure_ascii=False))
+        return 0
+    for result in results:
+        print(line(result))
+    print(summary(results, apply))
+    return 0

package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py

@@ -130,6 +130,7 @@ except ModuleNotFoundError as exc:
     sys.path.insert(0, str(_HERE.parent / "claude-harness" / "scripts"))
     import caddis_exit
 
+import caddis_created  # noqa: E402
 import caddis_notify  # noqa: E402
 import caddis_redact  # noqa: E402
 import caddis_review  # noqa: E402
@@ -1577,6 +1578,7 @@ def ensure_worktree(repo: Path, slug: str, default: str, root: Path | None = Non
     path.parent.mkdir(parents=True, exist_ok=True)
     if _git_out(repo, "worktree", "add", "--quiet", "--detach", str(path), f"origin/{default}") is None:
         raise _Stop(f"FAILED cannot make the roadmap worktree {path}", caddis_exit.BLOCKED)
+    caddis_created.record(path, "worktree", f"roadmap {slug} runner worktree", repo=repo, by="roadmap-run")
     _write_record(_state_file(repo, slug, "worktree"), {"path": str(path), "utc": _iso(datetime.now(timezone.utc))})
     return path
 
@@ -1606,6 +1608,7 @@ def remove_worktree_if_clean(repo: Path, slug: str, root: Path | None = None) ->
     if caddis_worktree_safety.safe_remove_worktree(repo, path) is not None:
         return f"worktree kept (remove failed): {path}"
     _state_file(repo, slug, "worktree").unlink(missing_ok=True)
+    caddis_created.record(path, "worktree", "", repo=repo, status="removed", by="roadmap-run")
     return f"worktree removed: {path}"
 
 

package/bundles/antigravity-plugin/scripts/caddis_worktree_root.py

@@ -21,8 +21,13 @@ stays where it is: moving it breaks a venv, which keeps absolute paths.
     worktree_path(repo, short_name, root=None) -> the path for a new worktree (nothing is created)
     main_checkout(repo)                       -> the main checkout's folder
 
-CLI: `python caddis_worktree_root.py [--repo PATH] [--root PATH] <short-name>` prints the path. Exit 2 on a bad name
-or a folder that is not in a git repo.
+CLI: `python caddis_worktree_root.py [--repo PATH] [--root PATH] [--record --purpose TEXT] <short-name>` prints the path.
+Exit 2 on a bad name or a folder that is not in a git repo.
+
+`--record` also appends the path to this session's created list (`caddis_created.py`, by="helper"), so `/handoff` can
+remove the worktree later. The helper creates nothing, so the path is recorded as INTENDED: run `git worktree add` on the
+path it printed. A session with no session id, or a record that cannot be written, only prints a warning on stderr: the
+path is still printed and the exit code is still 0.
 """
 
 from __future__ import annotations
@@ -96,14 +101,32 @@ def main(argv: list[str] | None = None) -> int:
     ap.add_argument("short_name", help="one folder name, e.g. fix-login")
     ap.add_argument("--repo", default=".", help="any folder of the repo or of one of its worktrees (default: .)")
     ap.add_argument("--root", default=None, help=f"override the root (default: ${ENV_VAR}, then <repo parent>/.worktrees)")
+    ap.add_argument("--record", action="store_true", help="also record the path in this session's created list")
+    ap.add_argument("--purpose", default="", help="with --record: why the worktree is made")
     args = ap.parse_args(argv)
     try:
-        print(worktree_path(args.repo, args.short_name, args.root))
+        path = worktree_path(args.repo, args.short_name, args.root)
+        repo = main_checkout(args.repo) if args.record else None
     except (ValueError, NotARepoError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+    print(path)
+    if args.record:
+        _record(path, repo, args.purpose)
     return 0
 
 
+def _record(path: Path, repo: Path | None, purpose: str) -> None:
+    """Append `path` to the session's created list. A failure only warns: the caller still has its path."""
+    try:
+        import caddis_created
+        done = caddis_created.record(path, "worktree", purpose, repo=repo, by="helper")
+    except Exception:  # noqa: BLE001 - recording must never break a command that only wants the path
+        done = False
+    if not done:
+        print(f"caddis_worktree_root: not recorded (no usable session id, or the record could not be written): {path}",
+              file=sys.stderr)
+
+
 if __name__ == "__main__":
     sys.exit(main())

package/bundles/antigravity-plugin/skills/cloud-phases/SKILL.md

@@ -37,10 +37,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name> --record --purpose "rebase <name>")" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -50,7 +50,8 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 `<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
 `$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
-cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
+cleanup can empty it. `--record --purpose "<why>"` also writes the path to this
+session's created list (`caddis_created.py`), so `/handoff` can remove the worktree later. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

package/bundles/antigravity-plugin/skills/handoff/SKILL.md

@@ -39,6 +39,8 @@ them into its commit, so check first, before Step 1.
    - Step 6: retired; nothing to skip (row 8 reports `skipped: retired (see the 3-store model)`).
    - Step 6b: skip `session_state.py prune` (report `skipped: shared checkout`).
    - Step 6c: run `--reindex` in the worktree (it edits the tracked `DOC-MAP.md`).
+   - Step 6d: runs as written. It never writes a file in this checkout; it only removes worktrees and
+     scratch folders this session recorded.
    - The relay stays in this checkout: `.caddis/relay/` is local and gitignored.
    After Step 6c, run:
    ```
@@ -51,9 +53,9 @@ them into its commit, so check first, before Step 1.
 
 ## Checklist
 The handoff is a fixed checklist. Every row ends as `done`, `skipped: <reason>` or `failed: <error>`, and
-Step 8 prints all 13 in this order. Never drop a row from the report, even when its step did not apply.
-Rows 3 and 8 are retired (the 3-store model, 21 Oct 2026): they stay in the list so the row numbers and the
-13-row report do not move for a fleet that mixes caddis versions, and each always reports
+Step 8 prints all 14 in this order. Never drop a row from the report, even when its step did not apply.
+Rows 3 and 8 are retired (the 3-store model, 21 Oct 2026): they stay in the list so the row numbers do not
+move for a fleet that mixes caddis versions, and each always reports
 `skipped: retired (see the 3-store model)`. A later release removes them with their scripts.
 
 | # | Row | What it is | Shared checkout (Step 0) |
@@ -71,6 +73,7 @@ Rows 3 and 8 are retired (the 3-store model, 21 Oct 2026): they stay in the list
 | 11 | `state-prune` | Step 6b: `session_state.py prune` | `skipped: shared checkout` |
 | 12 | `prune-list` | Step 6b: `caddis_tidy.py --prune`, list only | runs (lists, never applies) |
 | 13 | `handover-check` | Step 5 | runs |
+| 14 | `own-cleanup` | Step 6d: `caddis_created.py cleanup --apply` removes this session's merged, clean worktrees and scratch folders; lists the rest with a reason | runs (only this session's recorded worktrees and scratch) |
 
 `tidy-apply` and `state-prune` run only on `SHARED: no`. Handoff never runs
 `caddis_tidy.py --prune --apply` on its own, in any checkout; only the user can ask for it (Step 6b). In a
@@ -346,6 +349,27 @@ Then, when the repo has a roadmap (`.caddis/roadmaps/`), re-render its page so p
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_roadmap.py" render --all
 ```
 
+## Step 6d — remove this session's own worktrees and scratch folders
+Checklist row 14, `own-cleanup`. It runs in every checkout, a shared one too, after the Step 0 `finish`
+(falls back to `scripts/caddis_created.py` in a source checkout; if the script is missing, or exits 2 because
+it has no `cleanup`, the row is `skipped: not installed`):
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_created.py" cleanup --session-id <session-id> --apply
+```
+It reads only this session's record (`~/.caddis/sessions/<session-id>.created.jsonl`). A worktree goes only
+when its PR is merged, `git status` is clean, it has no commits after the PR head, and every file its branch
+changed equals `origin/<default>` (so a squash merge counts). Then its local and remote branch go too: each
+only while its tip is still the merged work. A scratch folder goes after a full scan, links first.
+
+It never removes: another session's worktree (it is not in this record), a roadmap runner's worktree, the
+worktree this session is working in, one with uncommitted changes (untracked files count), one whose PR is
+not merged or not found, one whose tree differs from `origin/<default>`, or anything through a
+junction or symlink (a link is removed as a link; its target stays). It prints one line per entry (`REMOVED`, `KEPT
+<path>: <reason>`, `GONE` or `FAILED <path>: <problem>`) and ends with
+`[OWN-CLEANUP] removed <n>, kept <n>, gone <n>, failed <n>`. Include that summary line and each `KEPT` and
+`FAILED` line in your report. It always exits 0: a kept or failed entry is not a failure of the row, which is
+`done` when the script ran.
+
 ## Step 7 — push prompt (interactive only)
 If this is an interactive session, ask the user every time — never reuse an earlier answer:
 `Push this note for another machine? (y/N)`
@@ -376,6 +400,7 @@ Print this block, every row filled with `done`, `skipped: <reason>` or `failed:
 11 state-prune         <same three forms>
 12 prune-list          <same three forms>
 13 handover-check      <same three forms>
+14 own-cleanup         <same three forms>
 Shared checkout: yes|no <reason>
 ```
 

package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md

@@ -43,10 +43,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name> --record --purpose "rebase <name>")" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -56,7 +56,8 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 `<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
 `$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
-cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
+cleanup can empty it. `--record --purpose "<why>"` also writes the path to this
+session's created list (`caddis_created.py`), so `/handoff` can remove the worktree later. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

package/bundles/antigravity-plugin/skills/ship-merge/SKILL.md

@@ -42,10 +42,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name> --record --purpose "rebase <name>")" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -55,7 +55,8 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 `<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
 `$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
-cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
+cleanup can empty it. `--record --purpose "<why>"` also writes the path to this
+session's created list (`caddis_created.py`), so `/handoff` can remove the worktree later. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md

@@ -41,10 +41,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name> --record --purpose "rebase <name>")" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -54,7 +54,8 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 `<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
 `$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
-cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
+cleanup can empty it. `--record --purpose "<why>"` also writes the path to this
+session's created list (`caddis_created.py`), so `/handoff` can remove the worktree later. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

package/bundles/antigravity-plugin/skills/using-git-worktrees/SKILL.md

@@ -39,10 +39,16 @@ If none is true, stop here and use `git switch -c`.
    script `caddis_worktree_root.py` prints the path; use it so the rule lives in one place:
 
 ```powershell
-$wt = python "<caddis scripts>\caddis_worktree_root.py" <short-name>   # run in the repo; prints the path
+$wt = python "<caddis scripts>\caddis_worktree_root.py" <short-name> --record --purpose "<why>"   # run in the repo; prints the path
 git worktree add -b <branch> $wt origin/<default>
 ```
 
+   `--record` also writes the path to this session's created list (`caddis_created.py`), so `/handoff` can remove the
+   worktree later. Always record it, subagents most of all: their tool calls are in a separate transcript that the
+   Stop hook does not read. If you create a worktree without the helper, run
+   `python "<caddis scripts>\caddis_created.py" record --path <path> --kind worktree --purpose "<why>"` right after
+   `git worktree add`.
+
    `<caddis scripts>` is the `scripts` folder of the installed caddis plugin. Do not create worktrees inside the
    repo. An existing worktree stays where it is: moving it breaks a venv, which keeps absolute paths.
 4. State the full path of the worktree. Work only there, and do not switch branches in it.

package/bundles/codex/.codex/skills/devops/using-git-worktrees/SKILL.md

@@ -39,10 +39,16 @@ If none is true, stop here and use `git switch -c`.
    script `caddis_worktree_root.py` prints the path; use it so the rule lives in one place:
 
 ```powershell
-$wt = python "<caddis scripts>\caddis_worktree_root.py" <short-name>   # run in the repo; prints the path
+$wt = python "<caddis scripts>\caddis_worktree_root.py" <short-name> --record --purpose "<why>"   # run in the repo; prints the path
 git worktree add -b <branch> $wt origin/<default>
 ```
 
+   `--record` also writes the path to this session's created list (`caddis_created.py`), so `/handoff` can remove the
+   worktree later. Always record it, subagents most of all: their tool calls are in a separate transcript that the
+   Stop hook does not read. If you create a worktree without the helper, run
+   `python "<caddis scripts>\caddis_created.py" record --path <path> --kind worktree --purpose "<why>"` right after
+   `git worktree add`.
+
    `<caddis scripts>` is the `scripts` folder of the installed caddis plugin. Do not create worktrees inside the
    repo. An existing worktree stays where it is: moving it breaks a venv, which keeps absolute paths.
 4. State the full path of the worktree. Work only there, and do not switch branches in it.

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.152",
+  "poolVersion": "1.3.153",
   "bundles": {
-    "antigravity-plugin": "1.3.152",
+    "antigravity-plugin": "1.3.153",
     "antigravity-plugin-extras": "1.3.46",
     "codex": "unknown"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.4.66",
+  "version": "0.4.67",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",