@caddis/cli 0.4.66 → 0.4.68

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.152",
+  "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_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_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_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)