@caddis/cli 0.4.67 → 0.4.68

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.153",
+  "version": "1.3.154",
   "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_fleet.py

@@ -11,6 +11,7 @@ import os
 import re
 import subprocess
 import sys
+import time
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
@@ -332,6 +333,78 @@ def whoami(session_id: str, name: str, root: Path) -> Path:
     return out
 
 
+# ---- live peers -------------------------------------------------------------------------------
+
+# The same rule as `inject_relay._live_peers` (the SessionStart hook cannot be imported: it runs at import).
+# test_peers_apply_the_same_liveness_rule_as_the_session_start_hook runs the hook's own source to keep them equal.
+PEER_FRESH_S = 1800
+
+
+def _slug(session_id: str) -> str:
+    return "".join(c for c in session_id if c.isalnum() or c in "-_")[:64]
+
+
+def _worktree_roots(root: Path) -> list[Path]:
+    """`root` plus every worktree of its repo: a session in a linked worktree writes its state there, not in the main
+    checkout, so a repo-wide scan reads each one. Not a git repo (or no git): just `root`."""
+    roots = [root]
+    proc = subprocess.run(["git", "-C", str(root), "worktree", "list", "--porcelain"], capture_output=True,
+                          text=True, encoding="utf-8", errors="replace")
+    if proc.returncode == 0:
+        for line in proc.stdout.splitlines():
+            if line.startswith("worktree "):
+                path = Path(line[len("worktree "):].strip())
+                if path not in roots and path.resolve() != root:
+                    roots.append(path)
+    return roots
+
+
+def _peer_name(base: Path, sid: str) -> str:
+    try:
+        return (base / f"{sid}.name").read_text(encoding="utf-8").split("\n", 1)[0].split("\t")[0].strip() or "-"
+    except (OSError, UnicodeDecodeError):
+        return "-"
+
+
+def live_peers(session_id: str, root: Path, now: float | None = None) -> list[tuple[str, str, int]]:
+    """[(name, session id, seconds since its state file was written)] for the OTHER live local sessions in this repo
+    (the checkout and its worktrees), freshest first. The name is `-` when that session never ran `whoami`.
+
+    Live: a `<sid>.md` state file written within PEER_FRESH_S, with no newer `<sid>.ended` marker (a resumed session
+    rewrites its state, which is newer than the marker). A cloud or offline session writes no state here.
+    """
+    now = time.time() if now is None else now
+    own = _slug(session_id)
+    found: dict[str, tuple[str, int]] = {}
+    for wt in _worktree_roots(root):
+        try:
+            from claudster_config import artifact_root
+            base = Path(artifact_root(str(wt))) / "session-state"
+        except Exception:
+            base = wt / ".caddis" / "session-state"
+        try:
+            names = os.listdir(base)
+        except OSError:
+            continue
+        for fname in names:
+            sid = fname[:-3]
+            if not fname.endswith(".md") or (own and sid == own):
+                continue
+            try:
+                mtime = (base / fname).stat().st_mtime
+            except OSError:
+                continue
+            age = int(now - mtime)
+            try:
+                if (base / f"{sid}.ended").stat().st_mtime >= mtime:
+                    continue
+            except OSError:
+                pass
+            if 0 <= age <= PEER_FRESH_S and (sid not in found or age < found[sid][1]):
+                found[sid] = (_peer_name(base, sid), age)
+    return sorted(((name, sid, age) for sid, (name, age) in found.items()), key=lambda p: p[2])
+
+
 # ---- resume block -----------------------------------------------------------------------------
 
 class ResumeError(ValueError):
@@ -375,15 +448,39 @@ def shell_arg(text: str) -> str:
     return "'" + one_line.replace("'", "’").replace('"', "”") + "'"
 
 
+ANNOUNCE_ID = "<your session id>"
+
+
+def announce_text(script: Path, name: str, folder: str) -> str:
+    """The sentence the start line adds, so the resumed session names itself and tells its live peers once.
+
+    A new session cannot expand `${CLAUDE_PLUGIN_ROOT}`, so the script path is this script's own, written out. It
+    holds no quote or double quote (`shell_arg` would change them). A peer without a name (`-`) is not messaged."""
+    py = f"python {script.as_posix()}"
+    return (f"Then announce yourself once. Run `{py} whoami --session-id {ANNOUNCE_ID} --name {name} --root .` and "
+            f"`{py} peers --session-id {ANNOUNCE_ID} --root .` (your session id is printed at session start). "
+            f"Send each peer that has a name (not `-`) one SendMessage: "
+            f"`{name} started in {folder}: <next action>. No reply needed.` Send nothing else, and do not answer "
+            f"a reply. If the script is missing or lists no peer, skip this.")
+
+
 def render_resume(session: str, session_id: str, workstream: str, prompt: str, role: str, stamp: datetime,
-                  fleet_mode: bool = False) -> str:
-    """The last output of `/caddis:handoff`. In a fleet close the restart sheet holds the only start line."""
+                  fleet_mode: bool = False, announce_script: Path | None = None, folder: str = "") -> str:
+    """The last output of `/caddis:handoff`. In a fleet close the restart sheet holds the only start line.
+
+    With `announce_script`, the start line (not the fenced block, which stays the relay's text) ends with the
+    whoami + announce sentence: the start line is what the new session receives with its name."""
+    shown = prompt  # the fenced block stays the relay text
     if fleet_mode:
         start = "Start line: from the restart sheet"
     else:
-        start = f"Start line:\nclaude --name {new_name(role, stamp)} {shell_arg(prompt)}"
+        name = new_name(role, stamp)
+        if announce_script is not None:
+            prompt = f"{prompt}\n{announce_text(announce_script, name, folder)}"
+        start = f"Start line:\nclaude --name {name} {shell_arg(prompt)}"
     return (f"=== RESUME ===\nSession: {session} ({session_id})\nWorkstream: {workstream}\n"
-            f"{_fenced(prompt)}\n{start}\n")
+            f"{_fenced(shown)}\n{start}\n")
+
 
 # ---- CLI --------------------------------------------------------------------------------------
 
@@ -416,7 +513,8 @@ def _resume_block_cli(args: argparse.Namespace) -> int:
     if not _SAFE_NAME.match(role):  # the role goes unquoted into the start line
         sys.stderr.write(f"resume-block failed: bad role {role!r}\n")
         return caddis_exit.BLOCKED
-    print(render_resume(session, args.session_id, args.name, prompt, role, datetime.now(), args.fleet), end="")
+    print(render_resume(session, args.session_id, args.name, prompt, role, datetime.now(), args.fleet,
+                        Path(__file__).resolve(), root.name), end="")
     return caddis_exit.CLEAN
 
 
@@ -446,6 +544,9 @@ def main(argv: list[str] | None = None) -> int:
     p.add_argument("--session-id", required=True)
     p.add_argument("--name", required=True)
     p.add_argument("--root", default=".", type=Path)
+    p = sub.add_parser("peers", help="the other live local sessions in this repo: <name> TAB <session id> TAB <age s>")
+    p.add_argument("--session-id", required=True, help="this session's id (never listed)")
+    p.add_argument("--root", default=".", type=Path)
     p = sub.add_parser("resume-block", help="print the session name and the relay's resume prompt (last step of handoff)")
     p.add_argument("--name", required=True, help="the relay's workstream name")
     p.add_argument("--session-id", required=True)
@@ -520,6 +621,10 @@ def main(argv: list[str] | None = None) -> int:
         return caddis_exit.CLEAN
     if args.cmd == "resume-block":
         return _resume_block_cli(args)
+    if args.cmd == "peers":
+        for peer_name, sid, age in live_peers(args.session_id, args.root.resolve()):
+            print(f"{peer_name}	{sid}	{age}")
+        return caddis_exit.CLEAN
     # whoami
     try:
         out = whoami(args.session_id, args.name, args.root.resolve())

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/skills/handoff/SKILL.md

@@ -71,12 +71,12 @@ move for a fleet that mixes caddis versions, and each always reports
 | 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)
@@ -315,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
@@ -422,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

package/bundles/manifest.json

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

package/package.json

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