@caddis/cli 0.4.66 → 0.4.68

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

@@ -0,0 +1,376 @@
+"""Expire old scratchpads and caddis test leftovers in the temp folder (tidy v2, Phase 3).
+
+`caddis_tidy.py --prune --temp` calls `prune_temp`. Dry run is the default: it only lists. With `apply` it deletes.
+Two groups, each listed with its size and age:
+
+1. Scratch sessions: `<temp>/claude/<project>/<id>/` (Claude Code's session scratchpads and task logs).
+2. Test leftovers: folders directly in the temp folder whose name starts with a prefix caddis itself makes.
+
+A folder is listed only when ALL hold (anything in doubt is KEPT, and said so):
+  - the newest mtime of the folder and of everything in it is older than the age limit (7 days);
+  - scratch only: no transcript `<claude config>/projects/*/<id>.jsonl` changed within the limit, the id is not one of
+    the running session's ids, and the process cwd is not inside it;
+  - it is not a link and holds no link at any depth (kept, with the link and its target named; links are never
+    followed and never removed here);
+  - it holds no `.git` (a repo or a worktree): kept, with a note;
+  - the scan could read every folder.
+A folder with something newer than the limit inside is not listed and not mentioned: it is live or recent.
+
+Apply, per folder: scan again, rename it to `<name>.caddis-trash-<stamp>` in the same parent (atomic; it fails when a
+process holds a file in it, and the folder is then KEPT as "in use"), then `caddis_worktree_safety.remove_tree` on the
+renamed folder (links first). If that fails part-way the renamed path is reported as an error; there is no retry.
+An emptied `<project>` folder is removed with `os.rmdir` (only an empty one can go).
+
+    prune_temp(apply=False, temp_root=None, claude_config=None, now=None, env_session_ids=None, cwd=None) -> TempReport
+    format_report(report, apply) -> list of printable lines
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import caddis_worktree_safety as safety
+
+MAX_AGE_S = 7 * 86_400
+TRASH_MARK = ".caddis-trash-"
+# The running session's id, from the environment (as caddis_created.SESSION_ENV_VARS).
+SESSION_ENV_VARS = ("CADDIS_SESSION_ID", "CLAUDE_SESSION_ID", "CLAUDE_CODE_SESSION_ID")
+
+# Only folders whose name starts with one of these are test leftovers. Each prefix maps to the code that makes it.
+# Never add another tool's prefix (playwright* and the like). A new caddis prefix goes here with its maker.
+CADDIS_TEMP_PREFIXES = {
+    "caddis-roadmap-": "scripts/caddis_roadmap.py mkdtemp (also caddis-roadmap-check-)",
+    "caddis-docs-pr-": "scripts/caddis_docs_pr.py DIR_PREFIX (temp worktree of a docs PR)",
+    "caddis-review-": "scripts/caddis_review.py _add_worktree (temp review worktree)",
+    "caddis-relay-index-": "scripts/caddis_relay_git.py TemporaryDirectory",
+    "caddis-init-": "scripts/claudster_init.py TemporaryDirectory",
+    "caddis-fresh-": "scripts/fresh_install_test.ps1 probe folder",
+    "caddis-rev-": "scripts/fresh_install_test.ps1 probe folder",
+    "caddis-eval-": "evals/run_evals.py mkdtemp",
+    "caddis-agy-": "cli/src/agents/agy.ts stageForAgy, cli/test/agy.test.ts",
+    "caddis-codex-": "cli/test/codex.test.ts mkdtempSync",
+    "caddis-doctor-home-": "cli/test/doctor.test.ts mkdtempSync",
+    "caddis-doctor-sessions-": "cli/test/doctor.test.ts mkdtempSync",
+    "caddis-keys-": "cli/test/providers.test.ts mkdtempSync",
+    "caddis-sessions-": "cli/test/sessions.test.ts mkdtempSync",
+    "caddis-stub-": "cli/test/stub.test.ts mkdtempSync",
+}
+# A prefix above that can also match a folder that must stay: kept, with this reason.
+KEEP_PREFIXES = {
+    "caddis-agy-backup-": "cli/src/agents/agy.ts keeps a failed install's backup here: it may be the only whole "
+                          "copy of the agy plugin",
+}
+
+_walk = os.walk  # a seam for tests
+
+
+@dataclass
+class Found:
+    path: Path
+    size: int
+    age_days: int
+    kind: str  # "scratch" | "leftover"
+
+
+@dataclass
+class Kept:
+    path: Path
+    code: str  # link | git | unreadable | in-use | changed | backup | config
+    why: str
+
+
+@dataclass
+class TempReport:
+    temp_root: Path
+    scratch: list[Found] = field(default_factory=list)
+    leftovers: list[Found] = field(default_factory=list)
+    kept: list[Kept] = field(default_factory=list)
+    removed: list[Found] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def _env_session_ids() -> set[str]:
+    return {v.strip() for v in (os.environ.get(name) for name in SESSION_ENV_VARS) if v and v.strip()}
+
+
+def _same_or_inside(inner: Path | str, outer: Path | str) -> bool:
+    a = os.path.normcase(os.path.realpath(inner))
+    b = os.path.normcase(os.path.realpath(outer))
+    return a == b or a.startswith(b.rstrip("\\/") + os.sep)
+
+
+def _link_target(path: str) -> str:
+    try:
+        return os.readlink(path)
+    except OSError:
+        return "?"
+
+
+def _inspect(path: Path, cutoff: float) -> tuple[str, float, int, str, str]:
+    """(state, newest mtime, size, code, why). state: "young" (something inside is newer than `cutoff`),
+    "kept" (a link, a git folder or an unreadable folder: `code` and `why` say which) or "old". Links are never
+    entered: each one is found by lstat, because os.walk does not see a Windows junction as a link."""
+    try:
+        top = os.lstat(path)
+    except OSError as exc:
+        return "kept", 0.0, 0, "unreadable", f"cannot inspect {path}: {exc}"
+    if safety.is_link(top):
+        return "kept", top.st_mtime, 0, "link", f"is a link -> {_link_target(str(path))}"
+    newest = top.st_mtime
+    size = 0
+    problem: tuple[str, str] | None = None
+    if newest >= cutoff:
+        return "young", newest, size, "", ""
+
+    def fail(exc: OSError) -> None:
+        nonlocal problem
+        problem = problem or ("unreadable", f"unreadable folder {getattr(exc, 'filename', None) or path}: {exc}")
+
+    try:
+        for here, dirs, files in _walk(path, topdown=True, onerror=fail, followlinks=False):
+            descend = []
+            for name in dirs:
+                full = os.path.join(here, name)
+                st = os.lstat(full)
+                newest = max(newest, st.st_mtime)
+                if safety.is_link(st):
+                    problem = problem or ("link", f"holds a link {full} -> {_link_target(full)}")
+                elif name == ".git":
+                    problem = problem or ("git", f"holds a git repo at {here}")
+                else:
+                    descend.append(name)
+            dirs[:] = descend
+            for name in files:
+                full = os.path.join(here, name)
+                st = os.lstat(full)
+                newest = max(newest, st.st_mtime)
+                size += st.st_size
+                if safety.is_link(st):
+                    problem = problem or ("link", f"holds a link {full} -> {_link_target(full)}")
+                elif name == ".git":
+                    problem = problem or ("git", f"holds a git worktree at {here} (.git file)")
+            if newest >= cutoff:
+                return "young", newest, size, "", ""
+    except OSError as exc:
+        problem = problem or ("unreadable", f"cannot scan {path}: {exc}")
+    if problem:
+        return "kept", newest, size, problem[0], problem[1]
+    return "old", newest, size, "", ""
+
+
+def _transcript_times(config: Path) -> dict[str, float] | None:
+    """The newest mtime of every `<config>/projects/*/<id>.jsonl`, by id. None when any folder cannot be read:
+    then nobody can say which sessions are live."""
+    newest: dict[str, float] = {}
+    try:
+        with os.scandir(config / "projects") as projects:
+            for project in projects:
+                if not project.is_dir():
+                    continue
+                with os.scandir(project.path) as entries:
+                    for entry in entries:
+                        if entry.name.endswith(".jsonl") and entry.is_file():
+                            stem = entry.name[:-len(".jsonl")]
+                            newest[stem] = max(newest.get(stem, 0.0), entry.stat().st_mtime)
+    except OSError:
+        return None
+    return newest
+
+
+def _subfolders(folder: Path, cutoff: float, report: TempReport) -> list[Path]:
+    """Real sub-folders of `folder`. An old link is noted and skipped; a young one is silent."""
+    found = []
+    try:
+        with os.scandir(folder) as entries:
+            for entry in sorted(entries, key=lambda e: e.name):
+                path = Path(entry.path)
+                st = os.lstat(path)
+                if safety.is_link(st):
+                    if st.st_mtime < cutoff:
+                        report.kept.append(Kept(path, "link", f"is a link -> {_link_target(str(path))}; never followed"))
+                elif entry.is_dir(follow_symlinks=False):
+                    found.append(path)
+    except OSError as exc:
+        report.kept.append(Kept(folder, "unreadable", f"cannot list {folder}: {exc}"))
+    return found
+
+
+def _consider(report: TempReport, path: Path, kind: str, cutoff: float, now: float, cwd: Path | None) -> None:
+    if cwd is not None and _same_or_inside(cwd, path):
+        return  # the process works here
+    state, newest, size, code, why = _inspect(path, cutoff)
+    if state == "young":
+        return
+    if state == "kept":
+        report.kept.append(Kept(path, code, why))
+        return
+    lowered = path.name.lower()
+    if kind == "leftover" and any(lowered.startswith(p) for p in KEEP_PREFIXES):
+        reason = next(r for p, r in KEEP_PREFIXES.items() if lowered.startswith(p))
+        report.kept.append(Kept(path, "backup", reason))
+        return
+    found = Found(path, size, int((now - newest) // 86_400), kind)
+    (report.scratch if kind == "scratch" else report.leftovers).append(found)
+
+
+def _scan_scratch(report: TempReport, config: Path, env_ids: set[str], cwd: Path | None, cutoff: float,
+                  now: float) -> None:
+    base = report.temp_root / "claude"
+    try:
+        st = os.lstat(base)
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        report.kept.append(Kept(base, "unreadable", f"cannot inspect {base}: {exc}"))
+        return
+    if safety.is_link(st):
+        report.kept.append(Kept(base, "link", "is a link; scratch sessions were not scanned"))
+        return
+    transcripts = _transcript_times(config)
+    if transcripts is None:
+        report.kept.append(Kept(base, "config", f"cannot read the transcript folders under {config / 'projects'}, "
+                                                "so no scratch session can be called ended; none was scanned"))
+        return
+    for project in _subfolders(base, cutoff, report):
+        for session in _subfolders(project, cutoff, report):
+            if session.name in env_ids or transcripts.get(session.name, 0.0) >= cutoff:
+                continue  # a live session
+            _consider(report, session, "scratch", cutoff, now, cwd)
+
+
+def _scan_leftovers(report: TempReport, cwd: Path | None, cutoff: float, now: float) -> None:
+    prefixes = tuple(CADDIS_TEMP_PREFIXES)
+    try:
+        with os.scandir(report.temp_root) as entries:
+            names = sorted(e.name for e in entries if e.name.lower().startswith(prefixes))
+    except OSError as exc:
+        report.errors.append(f"cannot list the temp folder {report.temp_root}: {exc}")
+        return
+    for name in names:
+        path = report.temp_root / name
+        try:
+            st = os.lstat(path)
+        except OSError:
+            continue
+        if safety.is_link(st):
+            if st.st_mtime < cutoff:
+                report.kept.append(Kept(path, "link", f"is a link -> {_link_target(str(path))}; never followed"))
+            continue
+        if os.path.isdir(path):
+            _consider(report, path, "leftover", cutoff, now, cwd)
+
+
+def _remove(report: TempReport, found: Found, cutoff: float, stamp: str) -> None:
+    path = found.path
+    state = _inspect(path, cutoff)[0]
+    if state != "old":
+        report.kept.append(Kept(path, "changed", "changed since the scan (or is no longer plain old files); kept"))
+        return
+    trash = path.with_name(f"{path.name}{TRASH_MARK}{stamp}")
+    n = 1
+    while os.path.lexists(trash):
+        n += 1
+        trash = path.with_name(f"{path.name}{TRASH_MARK}{stamp}-{n}")
+    try:
+        os.rename(path, trash)  # atomic; fails cleanly when a process holds a file inside
+    except OSError as exc:
+        report.kept.append(Kept(path, "in-use", f"in use: {exc}"))
+        return
+    problem = safety.remove_tree(trash)
+    if problem:
+        report.errors.append(f"partly deleted; what is left is at {trash}: {problem}")
+        return
+    report.removed.append(found)
+
+
+def prune_temp(*, apply: bool = False, temp_root: Path | str | None = None, claude_config: Path | str | None = None,
+               now: float | None = None, env_session_ids: set[str] | None = None, cwd: Path | str | None = None,
+               max_age_s: int = MAX_AGE_S) -> TempReport:
+    """List (or, with `apply`, delete) old scratch sessions and caddis test leftovers. Never raises for a folder
+    it cannot read: that folder is kept and noted."""
+    now = time.time() if now is None else now
+    cutoff = now - max_age_s
+    root = Path(temp_root) if temp_root is not None else Path(tempfile.gettempdir())
+    if claude_config is not None:
+        config = Path(claude_config)
+    else:
+        config = Path(os.environ.get("CLAUDE_CONFIG_DIR") or (Path.home() / ".claude"))
+    env_ids = _env_session_ids() if env_session_ids is None else set(env_session_ids)
+    if cwd is not None:
+        here: Path | None = Path(cwd)
+    else:
+        try:
+            here = Path(os.getcwd())
+        except OSError:
+            here = None
+    report = TempReport(temp_root=root)
+    _scan_scratch(report, config, env_ids, here, cutoff, now)
+    _scan_leftovers(report, here, cutoff, now)
+    if apply:
+        stamp = time.strftime("%Y%m%d%H%M%S", time.gmtime(now))
+        for found in report.scratch + report.leftovers:
+            _remove(report, found, cutoff, stamp)
+        for parent in sorted({f.path.parent for f in report.removed if f.kind == "scratch"}):
+            try:
+                os.rmdir(parent)  # only an empty project folder goes
+            except OSError:
+                pass
+    return report
+
+
+def _human(n: int) -> str:
+    size = float(n)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024 or unit == "GB":
+            return f"{int(size)} B" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{n} B"
+
+
+COMPACT_LISTED = 10   # entries shown per group when not verbose (the largest)
+COMPACT_EXAMPLES = 5  # example paths shown per kept reason when not verbose
+
+
+def format_report(report: TempReport, apply: bool, verbose: bool = False) -> list[str]:
+    """The lines `caddis_tidy.py --prune --temp` prints. Compact by default, in list and apply mode alike: per group
+    one total line (count, size, age range) and the 10 largest folders; kept folders grouped by reason with a count
+    and 5 example paths. `verbose` prints every folder and every kept note."""
+    gone = {f.path for f in report.removed}
+    lines = [f"  temp folder: {report.temp_root}"]
+    for title, group in (("scratch sessions", report.scratch), ("test leftovers", report.leftovers)):
+        total = f"{len(group)} folder(s), {_human(sum(f.size for f in group))}"
+        if group:
+            ages = [f.age_days for f in group]
+            total += f", {min(ages)}-{max(ages)} days old"
+        lines.append(f"  {title}: {total}" + (" (ended sessions)" if title == "scratch sessions" else ""))
+        shown = sorted(group, key=lambda f: str(f.path)) if verbose else             sorted(group, key=lambda f: (-f.size, str(f.path)))[:COMPACT_LISTED]
+        for f in shown:
+            verb = ("deleted" if f.path in gone else "not deleted") if apply else "would delete"
+            lines.append(f"    {verb}: {f.path} ({_human(f.size)}, {f.age_days} days)")
+        if len(group) > len(shown):
+            lines.append(f"    ... {len(group) - len(shown)} more (--verbose lists all)")
+    if apply:
+        lines.append(f"  deleted: {len(report.removed)} folder(s), {_human(sum(f.size for f in report.removed))}")
+    if report.kept:
+        by_code: dict[str, list[Kept]] = {}
+        for k in report.kept:
+            by_code.setdefault(k.code, []).append(k)
+        lines.append(f"  kept: {len(report.kept)} folder(s)")
+        for code, items in sorted(by_code.items()):
+            lines.append(f"    kept ({code}): {len(items)} folder(s)")
+            shown_kept = items if verbose else items[:COMPACT_EXAMPLES]
+            for k in shown_kept:
+                lines.append(f"      {k.path}: {k.why}")
+            if len(items) > len(shown_kept):
+                lines.append(f"      ... {len(items) - len(shown_kept)} more (--verbose lists all)")
+    for message in report.errors:
+        lines.append(f"  ERROR: {message}")
+    if not apply and (report.scratch or report.leftovers):
+        lines.append("  Run `caddis_tidy.py --prune --temp --apply` to delete these. That is the user's choice.")
+    elif not (report.scratch or report.leftovers or report.kept or report.errors):
+        lines.append("  nothing to prune in the temp folder.")
+    return lines

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

@@ -53,6 +53,8 @@ Usage:
                                                  # this range changed (what /ship-pr runs)
   python scripts/caddis_tidy.py --prune          # list old local state that could be deleted
   python scripts/caddis_tidy.py --prune --apply  # delete it (the user's choice, never automatic)
+  python scripts/caddis_tidy.py --prune --temp   # also list old scratchpads and caddis test folders in the
+                                                 # temp folder (scripts/caddis_temp_prune.py); --apply deletes
 """
 
 from __future__ import annotations
@@ -1097,13 +1099,14 @@ def prune(root: Path, *, apply: bool = False, now: float | None = None) -> Prune
     return report
 
 
-def _print_prune(root: Path, report: PruneReport, apply: bool) -> int:
+def _print_prune(root: Path, report: PruneReport, apply: bool, temp: bool = False) -> int:
     def rel(p: Path) -> str:
         return p.relative_to(root).as_posix()
 
     print(f"[caddis_tidy] mode=PRUNE-{'APPLY' if apply else 'LIST'} root={root}")
     if report.refused:
-        print(f"  REFUSED: {report.refused} Nothing was listed or deleted.")
+        # With --temp the repo part is only one half; the caller still runs the temp part.
+        print(f"  REFUSED: {report.refused} Nothing was listed or deleted" + (" under .caddis." if temp else "."))
         return 1
     for p in (report.deleted if apply else report.delete):
         print(f"  {'deleted' if apply else 'would delete'} (session state older than 7 days): "
@@ -1120,11 +1123,12 @@ def _print_prune(root: Path, report: PruneReport, apply: bool) -> int:
         print(f"  NOTE: {note}")
     for msg in report.errors:
         print(f"  ERROR: {msg}")
+    flags = "--prune --temp --apply" if temp else "--prune --apply"
     if not apply and (report.delete or report.rotate):
-        print("  Run `caddis_tidy.py --prune --apply` to delete these. That is the user's choice.")
+        print(f"  Run `caddis_tidy.py {flags}` to delete these. That is the user's choice.")
     elif not (report.delete or report.rotate or report.old_worktrees or report.orphan_locks
               or report.notes or report.errors):
-        print("  nothing to prune.")
+        print("  nothing to prune" + (" under .caddis." if temp else "."))
     return 1 if report.errors else 0
 
 
@@ -1145,6 +1149,12 @@ def main(argv: list[str] | None = None) -> int:
                          "else is moved or stamped")
     ap.add_argument("--prune", action="store_true",
                     help="list old local state under .caddis/ (with --apply: delete it)")
+    ap.add_argument("--temp", action="store_true",
+                    help="with --prune: also list scratchpads of ended sessions and caddis test folders "
+                         "in the temp folder, older than 7 days (with --apply: delete them)")
+    ap.add_argument("--verbose", action="store_true",
+                    help="with --temp: list every folder and note (default: totals, the 10 largest, "
+                         "kept notes grouped by reason)")
     args = ap.parse_args(argv)
     # A status or path the console cannot encode prints as `?`, never a crash (a cp1252 pipe).
     for stream in (sys.stdout, sys.stderr):
@@ -1154,10 +1164,27 @@ def main(argv: list[str] | None = None) -> int:
             pass
 
     repo_root = Path(args.repo_root).resolve()
+    if args.temp and not args.prune:
+        ap.error("--temp only works together with --prune")
+    if args.verbose and not args.temp:
+        ap.error("--verbose only works together with --temp")
     if args.prune:
         if args.check or args.commit_range or args.only:
             ap.error("--prune runs alone: not with --check, --commit-range or --only")
-        return _print_prune(repo_root, prune(repo_root, apply=args.apply), args.apply)
+        repo_part = prune(repo_root, apply=args.apply)
+        code = _print_prune(repo_root, repo_part, args.apply, temp=args.temp)
+        if not args.temp:
+            return code
+        # The temp folder has nothing to do with the repo: a repo that prune refuses (not a git work tree)
+        # or one with no .caddis must not block it, and a refusal here is not a failure of the temp part.
+        if repo_part.refused:
+            code = 0
+        import caddis_temp_prune  # ships beside this file
+        temp_part = caddis_temp_prune.prune_temp(apply=args.apply, max_age_s=PRUNE_MAX_AGE_S)
+        print(f"[caddis_tidy] mode=PRUNE-TEMP-{'APPLY' if args.apply else 'LIST'}")
+        for line in caddis_temp_prune.format_report(temp_part, args.apply, args.verbose):
+            print(line)
+        return 1 if (code or temp_part.errors) else 0
     if args.only and args.check:
         ap.error("--only is for --apply (or its dry run), not --check")
     report = tidy(repo_root, apply=args.apply, check=args.check, commit_range=args.commit_range,

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) |
@@ -69,11 +71,12 @@ Rows 3 and 8 are retired (the 3-store model, 21 Oct 2026): they stay in the list
 | 9 | `usage-record` | Step 6b: `session_state.py usage` | runs |
 | 10 | `tidy-apply` | Step 4: `caddis_tidy.py --apply` | `skipped: shared checkout` |
 | 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) |
+| 12 | `prune-list` | Step 6b: `caddis_tidy.py --prune --temp`, 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
+`caddis_tidy.py --prune --apply` on its own, in any checkout (nor `--prune --temp --apply`); only the user can ask for it (Step 6b). In a
 shared checkout the report also lists every tracked file Step 1 changed, under `Docs PR needed:`.
 
 ## Step 1 — capture learnings FIRST (knowledge-transfer)
@@ -312,11 +315,14 @@ shared checkout (Step 0). Include the
 
 Then list old local state (falls back to `scripts/caddis_tidy.py`; skip if missing):
 ```
-python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --prune
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_tidy.py" --prune --temp
 ```
 It only lists: session-state files older than 7 days, logs over 5 MB to rotate, and (report
-only, never deleted) orphan `.lock` files and lane worktrees older than 7 days. Include its report. **Never
-add `--apply` yourself**; deleting is the user's choice. If they ask, run `--prune --apply`.
+only, never deleted) orphan `.lock` files and lane worktrees older than 7 days. `--temp` adds the temp
+folder: scratchpads under `<temp>/claude/` of ended sessions older than 7 days, and old folders that start
+with a prefix caddis itself makes (each with its size and age). A folder with a link or a `.git` in it, or one a
+live session may use, is kept and listed with the reason. Include its report. **Never add `--apply`
+yourself**; deleting is the user's choice. If they ask, run `--prune --temp --apply`.
 
 ## Step 6c — KB index and standing violations
 Both scripts fall back to `claude-harness/scripts/check_doc_coverage.py` and `scripts/caddis_tidy.py` in a
@@ -346,6 +352,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 +403,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>
 ```
 
@@ -397,11 +425,18 @@ Session: <session name> (<session id>)
 Workstream: <name>
 <the resume prompt, in a fenced block>
 Start line:
-claude --name <role>-<MMDD>-<HH> '<the resume prompt on one line>'
+claude --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce sentence>'
 ```
+- **The announce sentence.** In a normal handoff the one-line start line also ends with a sentence that tells
+  the new session to run `caddis_fleet.py whoami` with its new name, then `caddis_fleet.py peers`, and to send
+  each named live peer in the same repo (the checkout and its worktrees) one `SendMessage`:
+  `<name> started in <folder>: <next action>. No reply needed.` The fenced block stays the relay's text. A
+  session that pastes the block, not the start line, announces nothing. The script path is written out in the
+  sentence, because a new session cannot expand `${CLAUDE_PLUGIN_ROOT}`.
 - **Fleet close.** When this handoff runs because a peer sent `FLEET CLOSE from <coordinator>`, add
   `--fleet`. The Start line is then `Start line: from the restart sheet`: the restart sheet is the only
-  start line in a fleet close. The `FLEET-ACK` reply is a separate message and does not change.
+  start line in a fleet close, and `/caddis:fleet-open` already greets the peers, so it has no announce
+  sentence. The `FLEET-ACK` reply is a separate message and does not change.
 - **Exit 1** (no `## Resume prompt` block, or no relay) prints nothing on stdout. The handoff is not
   complete: fix the relay (Step 3, point 5) and run the command again. Never write the block by hand.
 - Workstream with no `whoami` record: the new name uses the workstream name as its role. Pass