@caddis/cli 0.4.51 → 0.4.53

package/bundles/antigravity-plugin/CADDIS-GLOSSARY.md

@@ -126,6 +126,7 @@ plain word gets them wrong. Usage counts were measured across 444 markdown files
 | model lane | A named provider route reached by its own binary — `claude-oss`, `claude-glm`, `claude-deepseek` — all speaking the Anthropic protocol. A lane is a route, not a model. | provider, backend, endpoint |
 | core / extras | The two shipping tiers. Core is an EXPLICIT allowlist in `.github/runtime-targets.json`; anything not named there lands in extras. A skill defaults to extras, so placement is a decision, never an accident. | tier 1 / tier 2, full / lite |
 | harness | The agent runtime that loads caddis — Claude Code, agy, Codex, Copilot. caddis is agent-agnostic; "the harness" without a name means whichever one is running. *(135 uses)* | client, IDE, platform |
+| card | One full unit of work handed to a lane or a reviewer: scope, files and pass criteria, kept in a roadmap's cards/ folder. | task file, ticket |
 
 ## Flagged ambiguities
 

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.137",
+  "version": "1.3.139",
   "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/repo_freshness.py

@@ -24,10 +24,22 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import subprocess
 import sys
 import time
 
+try:
+    _cfg_scripts = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts")
+    if _cfg_scripts not in sys.path:
+        sys.path.insert(0, _cfg_scripts)
+    from claudster_config import ARTIFACT_DIRS, artifact_root  # noqa: E402
+except Exception:  # pragma: no cover — defensive; a hook must never crash a session start
+    ARTIFACT_DIRS = (".caddis",)
+
+    def artifact_root(root):
+        return os.path.join(str(root), ARTIFACT_DIRS[0])
+
 # A narrow Windows console (cp1252) must not raise on a branch name with any Unicode in it.
 _reconfig = getattr(sys.stdout, "reconfigure", None)
 if _reconfig:
@@ -38,6 +50,7 @@ if _reconfig:
 
 FETCH_TIMEOUT_S = 15        # ceiling: a slow or unreachable remote must not stall a session
 FETCH_MAX_AGE_S = 600       # a restart within 10 minutes reuses the last fetch
+PEER_FRESH_S = 1800         # live peer session-state threshold (30 minutes, matches inject_relay)
 STAMP_NAME = "caddis-freshness-stamp"
 
 
@@ -83,7 +96,112 @@ def _count(cwd: str, rev_range: str) -> int:
     return int(out) if code == 0 and out.isdigit() else 0
 
 
-def report(cwd: str) -> list[str]:
+def _norm_path(raw: str) -> str:
+    """One path for comparison: no backticks, forward slashes, no leading `./`."""
+    norm = raw.strip().replace("`", "").strip().replace("\\", "/")
+    while norm.startswith("./"):
+        norm = norm[2:]
+    return norm
+
+
+def _status_entries(top: str) -> list[list[str]]:
+    """`git status --porcelain -z` at the repo top: one list of paths per entry (a rename gives two).
+    NUL-separated, so a path is never quoted. [] when git fails."""
+    try:
+        r = subprocess.run(["git", "status", "--porcelain", "-z"], cwd=top, capture_output=True, timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if r.returncode != 0:
+        return []
+    parts = (r.stdout or b"").decode("utf-8", errors="replace").split("\0")
+    entries: list[list[str]] = []
+    i = 0
+    while i < len(parts):
+        entry = parts[i]
+        i += 1
+        if len(entry) < 4:
+            continue
+        paths = [entry[3:]]
+        if ("R" in entry[:2] or "C" in entry[:2]) and i < len(parts):
+            paths.append(parts[i])
+            i += 1
+        entries.append(paths)
+    return entries
+
+
+def _parse_session_state(text: str) -> tuple[str, list[str]]:
+    m = re.search(r"\*\*Branch:\*\*\s*`?([^\s`·]+)`?", text)
+    branch = m.group(1).strip() if m else "unknown"
+    files: list[str] = []
+    in_files = False
+    for line in text.splitlines():
+        s = line.strip()
+        if s.startswith("## "):
+            in_files = (s == "## Files changed this session")
+            continue
+        if in_files and s.startswith("- "):
+            item = s[2:].strip()
+            if item and not item.startswith("_("):
+                item = _norm_path(item)
+                if item:
+                    files.append(item)
+    return branch, files
+
+
+def _dirty_owners(top: str, dirty_paths: set[str], own_session_id: str = "") -> list[str]:
+    """Live peer sessions whose recorded files are dirty here. `top` is the repo top level: the
+    session-state folder and every path are read from there, whatever the session's cwd is."""
+    try:
+        if not dirty_paths:
+            return []
+        base = os.path.join(artifact_root(top), "session-state")
+        if not os.path.isdir(base):
+            legacy = os.path.join(top, ".claudster", "session-state")
+            if os.path.isdir(legacy):
+                base = legacy
+            else:
+                return []
+        now = time.time()
+        owners: list[str] = []
+        for name in sorted(os.listdir(base)):
+            try:
+                if not name.endswith(".md"):
+                    continue
+                sid = name[:-3]
+                if own_session_id and sid == own_session_id:
+                    continue
+                path = os.path.join(base, name)
+                mtime = os.path.getmtime(path)
+                if now - mtime > PEER_FRESH_S:
+                    continue
+                ended = os.path.join(base, sid + ".ended")
+                try:
+                    if os.path.getmtime(ended) >= mtime:
+                        continue
+                except OSError:
+                    pass
+                with open(path, encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+                peer_branch, peer_files = _parse_session_state(text)
+                matched = False
+                for pf in peer_files:
+                    if pf in dirty_paths or any(
+                        dp.endswith("/") and pf.startswith(dp) for dp in dirty_paths
+                    ):
+                        matched = True
+                        break
+                if matched:
+                    label = f"owned by session {sid[:8]} (branch {peer_branch})"
+                    if label not in owners:
+                        owners.append(label)
+            except Exception:
+                continue
+        return owners
+    except Exception:
+        return []
+
+
+def report(cwd: str, own_session_id: str = "") -> list[str]:
     """The lines to print. Empty when there is nothing worth saying."""
     if _git(cwd, "rev-parse", "--is-inside-work-tree")[0] != 0:
         return []                                   # not a git repository
@@ -102,7 +220,11 @@ def report(cwd: str) -> list[str]:
             lines.append("[HARNESS] could not fetch origin - the figures below may be stale.")
 
     ref = _default_ref(cwd) if has_origin else ""
-    dirty = len([ln for ln in _git(cwd, "status", "--porcelain")[1].splitlines() if ln.strip()])
+    # The repo top level, so a session started in a subfolder still finds `.caddis/session-state`.
+    top = _git(cwd, "rev-parse", "--show-toplevel")[1] or cwd
+    entries = _status_entries(top)
+    dirty = len(entries)
+    dirty_paths = {_norm_path(p) for paths in entries for p in paths if _norm_path(p)}
     behind = _count(cwd, f"HEAD..{ref}") if ref else 0
     ahead = _count(cwd, f"{ref}..HEAD") if ref else 0
     default_branch = ref.split("/", 1)[-1] if ref else ""
@@ -112,8 +234,12 @@ def report(cwd: str) -> list[str]:
         lines.append(f"[HARNESS] branch '{branch}' | {behind} behind {ref} | {ahead} ahead "
                      f"| {dirty} uncommitted")
     if dirty:
-        lines.append("[HARNESS] There are uncommitted changes here. They may not be yours - these "
-                     "checkouts are shared. Look before you touch: git status")
+        msg = ("[HARNESS] There are uncommitted changes here. They may not be yours - these "
+               "checkouts are shared. Look before you touch: git status")
+        owners = _dirty_owners(top, dirty_paths, own_session_id=own_session_id)
+        if owners:
+            msg = f"{msg} ({'; '.join(owners)})"
+        lines.append(msg)
     # The recommendation, only when following it can lose nothing: behind, clean, and with
     # nothing of your own unpushed. Suggesting a branch switch to someone holding uncommitted
     # work in a shared checkout is how the branch-switch hazard gets triggered.
@@ -134,8 +260,9 @@ def main() -> int:
     except Exception:
         payload = {}
     cwd = (payload.get("cwd") if isinstance(payload, dict) else None) or os.getcwd()
+    session_id = (payload.get("session_id") if isinstance(payload, dict) else None) or ""
     try:
-        for line in report(cwd):
+        for line in report(cwd, own_session_id=str(session_id)):
             print(line)
     except Exception:
         pass          # fail open: a freshness report must never break a session start

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

@@ -0,0 +1,223 @@
+"""Protect a shared checkout from lanes writing into it, and tell handoff when a checkout is shared.
+
+`shared` (handoff-integrity Phase 5, the design of fleet-handoff Phase 2): a checkout is shared when its root
+`AGENTS.md` says `Shared checkout: yes`, or when `git status` lists a path this session did not change. In a
+shared checkout handoff writes no tracked file there; it uses `caddis_docs_pr.py` instead.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import re
+import subprocess
+import sys
+
+try:
+    import caddis_exit
+except ModuleNotFoundError as exc:
+    if exc.name != "caddis_exit":
+        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_exit
+
+
+def get_porcelain_lines(repo: Path) -> tuple[int, list[str]]:
+    """Run git status --porcelain=v1 --untracked-files=all -z and parse entries."""
+    proc = subprocess.run(
+        ["git", "-C", str(repo), "status", "--porcelain=v1", "--untracked-files=all", "-z"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if proc.returncode != 0:
+        return proc.returncode, []
+
+    raw = proc.stdout
+    if not raw:
+        return 0, []
+
+    parts = raw.split("\0")
+    if parts and parts[-1] == "":
+        parts.pop()
+
+    entries: list[str] = []
+    idx = 0
+    while idx < len(parts):
+        part = parts[idx]
+        # A rename or copy (X or Y is R or C) is followed by one more field: the original path.
+        if ("R" in part[:2] or "C" in part[:2]) and idx + 1 < len(parts):
+            orig_path = parts[idx + 1]
+            entries.append(f"{part} -> {orig_path}")
+            idx += 2
+        else:
+            entries.append(part)
+            idx += 1
+    return 0, entries
+
+
+SHARED_RE = re.compile(r"^Shared checkout:\s*yes\b", re.IGNORECASE | re.MULTILINE)
+
+
+def entry_paths(entry: str) -> list[str]:
+    """The paths of one `get_porcelain_lines` entry: `XY path`, or `XY new -> orig` (both count) for a rename."""
+    rest = entry[3:]
+    if ("R" in entry[:2] or "C" in entry[:2]) and " -> " in rest:
+        new, orig = rest.split(" -> ", 1)
+        return [new, orig]
+    return [rest]
+
+
+def _norm(path: str) -> str:
+    return path.strip().replace("\\", "/")
+
+
+def is_shared_checkout(root: Path, own_files: set[str]) -> tuple[bool, str]:
+    """(True, reason) when handoff must not write tracked files in `root`; else (False, "").
+
+    `Shared checkout: no` in AGENTS.md never hides a change this session did not make. When git status cannot
+    run, the checkout counts as shared: a wrong "no" could commit another session's files.
+    """
+    agents = Path(root) / "AGENTS.md"
+    try:
+        text = agents.read_text(encoding="utf-8", errors="replace") if agents.is_file() else ""
+    except OSError:
+        text = ""
+    if SHARED_RE.search(text):
+        return True, "AGENTS.md says Shared checkout: yes"
+    ret, lines = get_porcelain_lines(Path(root))
+    if ret != 0:
+        return True, "git status failed, so changes by other sessions cannot be ruled out"
+    own = {_norm(p) for p in own_files}
+    foreign: list[str] = []
+    for entry in lines:
+        for path in entry_paths(entry):
+            if _norm(path) not in own and path not in foreign:
+                foreign.append(path)
+    if foreign:
+        return True, "changes not made by this session: " + ", ".join(foreign[:3])
+    return False, ""
+
+
+def read_own_files(path: Path | None) -> set[str]:
+    """One path per line. The session-state list form `- `path`` is read too; blank lines are skipped.
+
+    A missing or unreadable file gives an empty set, so every dirty path counts as foreign (the safe side).
+    """
+    if path is None:
+        return set()
+    try:
+        raw = Path(path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return set()
+    own: set[str] = set()
+    for line in raw.splitlines():
+        item = line.strip()
+        if item.startswith("- "):
+            item = item[2:].strip()
+        if len(item) >= 2 and item.startswith("`") and item.endswith("`"):
+            item = item[1:-1]
+        if item:
+            own.add(_norm(item))
+    return own
+
+
+def shared(root: Path, own_files_path: Path | None) -> int:
+    """Print `SHARED: yes <reason>` or `SHARED: no`; always exit 0."""
+    is_shared, reason = is_shared_checkout(root, read_own_files(own_files_path))
+    print(f"SHARED: {'yes' if is_shared else 'no'} {reason}".rstrip())
+    return caddis_exit.CLEAN
+
+
+def snapshot(repo: Path, out_path: Path) -> int:
+    """Take a snapshot of current porcelain entries."""
+    ret, lines = get_porcelain_lines(repo)
+    if ret != 0:
+        sys.stderr.write(f"git status failed on {repo}\n")
+        return caddis_exit.NOT_RUN
+
+    data = {
+        "repo": str(repo),
+        "lines": lines,
+    }
+    try:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    except Exception as exc:
+        sys.stderr.write(f"failed to write snapshot to {out_path}: {exc}\n")
+        return caddis_exit.NOT_RUN
+    return caddis_exit.CLEAN
+
+
+def compare(repo: Path, snapshot_path: Path) -> int:
+    """Compare current entries to snapshot."""
+    if not snapshot_path.is_file():
+        sys.stderr.write(f"snapshot file not found: {snapshot_path}\n")
+        return caddis_exit.NOT_RUN
+
+    try:
+        data = json.loads(snapshot_path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict) or not isinstance(data.get("lines"), list):
+            raise ValueError("no 'lines' list")
+        snapshot_lines = set(data["lines"])
+    except Exception as exc:
+        sys.stderr.write(f"invalid snapshot JSON {snapshot_path}: {exc}\n")
+        return caddis_exit.NOT_RUN
+
+    ret, current_lines = get_porcelain_lines(repo)
+    if ret != 0:
+        sys.stderr.write(f"git status failed on {repo}\n")
+        return caddis_exit.NOT_RUN
+
+    new_entries = [entry for entry in current_lines if entry not in snapshot_lines]
+    if new_entries:
+        for entry in new_entries:
+            print(f"NEW {entry}")
+        return caddis_exit.BLOCKED
+    else:
+        print("checkout unchanged")
+        return caddis_exit.CLEAN
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point for caddis_checkout_guard."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(description="Shared checkout guard.")
+    subparsers = parser.add_subparsers(dest="command")
+
+    snap_parser = subparsers.add_parser("snapshot")
+    snap_parser.add_argument("--repo", required=True, type=Path, help="Repository path")
+    snap_parser.add_argument("--out", required=True, type=Path, help="Snapshot output path")
+
+    cmp_parser = subparsers.add_parser("compare")
+    cmp_parser.add_argument("--repo", required=True, type=Path, help="Repository path")
+    cmp_parser.add_argument("--snapshot", required=True, type=Path, help="Snapshot file path")
+
+    shared_parser = subparsers.add_parser("shared", help="print SHARED: yes|no <reason> for handoff")
+    shared_parser.add_argument("--root", required=True, type=Path, help="Repository root")
+    shared_parser.add_argument("--own-files", type=Path, default=None,
+                               help="File with one path per line: the files this session changed")
+
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit:
+        return caddis_exit.NOT_RUN
+
+    if args.command == "snapshot":
+        return snapshot(args.repo, args.out)
+    elif args.command == "compare":
+        return compare(args.repo, args.snapshot)
+    elif args.command == "shared":
+        return shared(args.root, args.own_files)
+    else:
+        parser.print_help(sys.stderr)
+        return caddis_exit.NOT_RUN
+
+
+if __name__ == "__main__":
+    sys.exit(main())