@caddis/cli 0.4.75 → 0.4.76

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.161",
+  "version": "1.3.162",
   "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_hub_collect.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Batched hub collector: every repo's roadmaps, plans and relays, plus agy spend and the guide, as one JSON object.
+
+Usage: caddis_hub_collect.py --repos PATH [PATH ...] [--only roadmaps,plans,relays,spend,guide] --json
+
+The hub runs this once per cycle. It runs in ONE Python process for all repos (hub rule R15, spawn cost L8). It
+never calls gh, claude or agy, and never runs `git fetch`: the roadmap reader sees the origin refs the repo
+already has. The parsers stay in the scripts that own each format (R14); this file only calls them.
+
+Output: {"schema": 1, "generated_at": "<UTC Z>", "repos": [{"path", "fingerprint", "roadmaps", "plans",
+"relays"}], "spend": ..., "guide": ...}. A path that is not a folder gives {"path", "error"}. A source that fails
+gives {"error": "<one line>"} in its slot. The run still exits 0. Exit 1 is for bad arguments only.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA = 1
+KINDS = ("roadmaps", "plans", "relays", "spend", "guide")
+_REPO_KINDS = ("roadmaps", "plans", "relays")
+
+
+def _sibling(name: str):
+    """A sibling script as a module. The same module object the rest of the process uses."""
+    try:
+        return importlib.import_module(name)
+    except ModuleNotFoundError as exc:
+        if exc.name != name:
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        return importlib.import_module(name)
+
+
+def _error(exc: BaseException) -> dict:
+    lines = str(exc).strip().splitlines()
+    return {"error": lines[0] if lines else type(exc).__name__}
+
+
+def _roadmaps_json(root: Path) -> dict:
+    module = _sibling("caddis_roadmap")
+    saved = module.FETCH
+    module.FETCH = False  # R15: no network git. Read the origin refs the repo already has.
+    try:
+        return module.roadmaps_json(root)
+    finally:
+        module.FETCH = saved
+
+
+def _plans_json(root: Path) -> dict:
+    return _sibling("caddis_todo").plans_json(root)
+
+
+def _relays_json(root: Path) -> dict:
+    return _sibling("caddis_workstreams").relays_json(root)
+
+
+def _spend_json() -> dict:
+    return _sibling("caddis_spend").spend_json(Path.home())
+
+
+def _guide_json() -> dict:
+    return _sibling("build_reference").guide_json()
+
+
+_REPO_COLLECTORS = {"roadmaps": _roadmaps_json, "plans": _plans_json, "relays": _relays_json}
+
+
+_REPARSE_POINT = 0x400  # FILE_ATTRIBUTE_REPARSE_POINT: a junction or a symlink on Windows
+
+
+def _is_link(path: Path) -> bool:
+    """True for a symlink or a Windows junction. Python 3.11 `is_symlink()` is False for a junction."""
+    try:
+        info = path.lstat()
+    except OSError:
+        return False  # not there: nothing to follow
+    return path.is_symlink() or bool(getattr(info, "st_file_attributes", 0) & _REPARSE_POINT)
+
+
+def _files(folder: Path, pattern: str = "*", recurse: bool = False) -> list[Path]:
+    """The plain files in `folder`. Never enter a linked folder and never list a linked file (stat only)."""
+    if not folder.is_dir() or _is_link(folder):
+        return []
+    found: list[Path] = []
+    for path in folder.iterdir():
+        if _is_link(path):
+            continue
+        if path.is_dir():
+            if recurse:
+                found.extend(_files(path, pattern, recurse))
+        elif path.is_file() and path.match(pattern):
+            found.append(path)
+    return found
+
+
+def _input_files(repo: Path) -> list[Path]:
+    """The files the repo's collectors read from the working tree."""
+    artifact = repo / ".caddis"
+    if _is_link(artifact):
+        return []
+    files = _files(artifact / "roadmaps", recurse=True)
+    plans = artifact / "plans"
+    if not plans.is_dir():
+        plans = repo / ".github" / "plans"  # the legacy folder, as caddis_todo reads it
+    files.extend(_files(plans, "*.md"))
+    files.extend(_files(artifact / "relay", "*.md"))
+    return files
+
+
+def git_common_dir(repo: Path) -> Path | None:
+    """The git common dir, found with no subprocess: a `.git` folder, or a `.git` file (a worktree) whose `gitdir:`
+    folder has a `commondir` file. None when the repo has no readable git dir."""
+    dot_git = repo / ".git"
+    if _is_link(dot_git):
+        return None
+    if dot_git.is_dir():
+        return dot_git
+    try:
+        line = dot_git.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+    if not line.startswith("gitdir:"):
+        return None
+    gitdir = Path(line[len("gitdir:"):].strip())
+    if not gitdir.is_absolute():
+        gitdir = repo / gitdir
+    try:
+        common = (gitdir / "commondir").read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return gitdir if gitdir.is_dir() else None
+    path = Path(common)
+    return path if path.is_absolute() else gitdir / path
+
+
+def _origin_ref_files(common: Path) -> list[Path]:
+    """The ref files the roadmap reader gets its data from: packed-refs, origin/HEAD, every origin branch."""
+    files = [p for p in (common / "packed-refs",) if p.is_file() and not _is_link(p)]
+    # refs/remotes/origin/HEAD sits inside refs/remotes/origin/, so the walk covers it.
+    return files + _files(common / "refs" / "remotes" / "origin", recurse=True)
+
+
+def fingerprint(repo: Path) -> str:
+    """sha256 over the sorted (name, mtime_ns, size) of every input file and origin ref file. Empty list: still a hash.
+
+    The roadmaps come from the origin refs (`git show origin/<default>:...`), so a fetch must change the hash."""
+    repo = Path(repo)
+    named = [(path.relative_to(repo).as_posix(), path) for path in _input_files(repo)]
+    common = git_common_dir(repo)
+    if common is not None:
+        named.extend((f"git:{path.relative_to(common).as_posix()}", path) for path in _origin_ref_files(common))
+    rows = []
+    for name, path in named:
+        try:
+            info = path.stat()
+        except OSError:
+            continue  # the file went away while we looked
+        rows.append((name, info.st_mtime_ns, info.st_size))
+    return hashlib.sha256(json.dumps(sorted(rows)).encode("utf-8")).hexdigest()
+
+
+def collect_repo(path: str, kinds: tuple[str, ...]) -> dict:
+    repo = Path(path)
+    if not repo.is_dir():
+        return {"path": path, "error": "not a folder"}
+    entry: dict = {"path": path}
+    try:
+        entry["fingerprint"] = fingerprint(repo)
+    except Exception as exc:  # a repo we cannot read must not stop the others
+        return {"path": path, **_error(exc)}
+    for kind in _REPO_KINDS:
+        if kind not in kinds:
+            continue
+        try:
+            entry[kind] = _REPO_COLLECTORS[kind](repo)
+        except Exception as exc:
+            entry[kind] = _error(exc)
+    return entry
+
+
+def collect(repos: list[str], kinds: tuple[str, ...]) -> dict:
+    out: dict = {"schema": SCHEMA, "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                 "repos": [collect_repo(path, kinds) for path in repos]}
+    for kind, call in (("spend", _spend_json), ("guide", _guide_json)):
+        if kind not in kinds:
+            continue
+        try:
+            out[kind] = call()
+        except Exception as exc:
+            out[kind] = _error(exc)
+    return out
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str):  # bad arguments exit 1, not argparse's 2
+        self.print_usage(sys.stderr)
+        print(f"caddis-hub-collect: {message}", file=sys.stderr)
+        raise SystemExit(1)
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    parser = _Parser(description=__doc__.splitlines()[0])
+    parser.add_argument("--repos", nargs="+", required=True, metavar="PATH")
+    parser.add_argument("--only", default=",".join(KINDS), help="comma list of: " + ", ".join(KINDS))
+    parser.add_argument("--json", action="store_true", required=True)
+    args = parser.parse_args(argv)
+    kinds = tuple(k.strip() for k in args.only.split(",") if k.strip())
+    unknown = [k for k in kinds if k not in KINDS]
+    if unknown or not kinds:
+        parser.error(f"unknown --only kind: {', '.join(unknown) or '(empty)'}; use {', '.join(KINDS)}")
+    print(json.dumps(collect(args.repos, kinds), ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -49,7 +49,8 @@ Exit codes (caddis_exit): 0 clean, 1 blocked (nothing ready, check failing, PR n
 (no origin, no roadmap, lock busy, an exit check or Exit setup that cannot run in the merged checkout), 4 error
 (malformed roadmap, unknown id, column or value, refused change).
 
-Usage: caddis_roadmap.py status --roadmap SLUG [--root DIR] [--json]
+Usage: caddis_roadmap.py list [--root DIR] [--json]
+       caddis_roadmap.py status --roadmap SLUG [--root DIR] [--json]
        caddis_roadmap.py next --roadmap SLUG [--root DIR] [--json]
        caddis_roadmap.py check --roadmap SLUG [--root DIR]
        caddis_roadmap.py set --roadmap SLUG [--root DIR] --id ID --col Status|Owner|Target --value V [--by-owner]
@@ -198,6 +199,9 @@ DROPPED_PREFIX = "dropped:"
 OLD_BLOCKER_DAYS = 14  # status lists a blocker whose row is older than this
 
 
+JSON_SCHEMA = 1  # the `schema` key of every --json output (hub rule R13)
+
+
 class RoadmapError(Exception):
     """A refused or impossible request; carries the caddis exit code."""
 
@@ -237,11 +241,21 @@ def _git(root: Path, *args: str, check: bool = True) -> subprocess.CompletedProc
 
 
 def default_branch(root: Path) -> str:
-    """origin/HEAD's branch; when it is not set locally, ask the remote (`git ls-remote --symref origin HEAD`)."""
+    """origin/HEAD's branch; when it is not set locally, ask the remote (`git ls-remote --symref origin HEAD`).
+    When FETCH is off, never ask the remote: use origin/main or origin/master if exactly one exists locally."""
     proc = _git(root, "symbolic-ref", "refs/remotes/origin/HEAD", check=False)
     ref = proc.stdout.strip()
     if proc.returncode == 0 and ref.startswith("refs/remotes/origin/"):
         return ref[len("refs/remotes/origin/"):]
+    if not FETCH:
+        # No network when fetch is off (the collector, `render --no-fetch`): use the one local origin branch.
+        found = [name for name in ("main", "master")
+                 if _git(root, "rev-parse", "--verify", "--quiet", f"refs/remotes/origin/{name}^{{commit}}",
+                         check=False).returncode == 0]
+        if len(found) == 1:
+            return found[0]
+        raise RoadmapError("cannot tell origin's default branch: origin/HEAD is not set locally; "
+                           "run: git remote set-head origin --auto", caddis_exit.NOT_RUN)
     remote = _git(root, "ls-remote", "--symref", "origin", "HEAD", check=False)
     for line in remote.stdout.splitlines():
         match = re.match(r"^ref:\s*refs/heads/(\S+)\s+HEAD$", line)
@@ -2190,6 +2204,19 @@ def list_roadmaps_checked(root: Path) -> tuple[list[str], set[str] | None]:
     return sorted(slugs), folders
 
 
+def roadmaps_json(root: Path) -> dict:
+    """The hub's roadmap list: status() of each slug, in `list` order. A roadmap whose status() raises gives
+    {"roadmap": slug, "error": "<one line>"} and the rest still list. Never prints, never exits."""
+    entries: list[dict] = []
+    for slug in list_roadmaps(Path(root)):
+        try:
+            entries.append(status(Path(root), slug))
+        except Exception as exc:  # one broken file must not hide the others
+            lines = str(exc).strip().splitlines()
+            entries.append({"roadmap": slug, "error": lines[0] if lines else type(exc).__name__})
+    return {"schema": JSON_SCHEMA, "roadmaps": entries}
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = _Parser(description=__doc__.splitlines()[0])
     sub = parser.add_subparsers(dest="cmd", required=True)
@@ -2206,6 +2233,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     p = sub.add_parser("list")
     p.add_argument("--root", default=".")
+    p.add_argument("--json", action="store_true")
     add("status", json_out=True)
     add("next", json_out=True)
     add("check")
@@ -2371,6 +2399,10 @@ def _render_site(root: Path, args: argparse.Namespace) -> int:
 
 def _dispatch(args: argparse.Namespace) -> int:
     root = _repo_root(args.root)
+    if args.cmd == "list" and args.json:
+        data = roadmaps_json(root)
+        print(json.dumps(data, indent=2))
+        return caddis_exit.CLEAN if data["roadmaps"] else caddis_exit.BLOCKED
     if args.cmd == "list":
         slugs = list_roadmaps(root)
         for slug in slugs:
@@ -2378,12 +2410,13 @@ def _dispatch(args: argparse.Namespace) -> int:
         return caddis_exit.CLEAN if slugs else caddis_exit.BLOCKED
     if args.cmd == "status":
         result = status(root, args.roadmap)
-        print(json.dumps(result, indent=2) if args.json else result["line"])
+        print(json.dumps({"schema": JSON_SCHEMA, **result}, indent=2) if args.json else result["line"])
         return caddis_exit.CLEAN
     if args.cmd == "next":
         batch, reasons = _select(load(root, args.roadmap), other_roadmap_batches(root, args.roadmap))
         if args.json:
-            print(json.dumps({"batch": batch, "skipped": [{"id": i, "reason": r} for i, r in reasons]}))
+            skipped = [{"id": i, "reason": r} for i, r in reasons]
+            print(json.dumps({"schema": JSON_SCHEMA, "batch": batch, "skipped": skipped}))
         else:
             for mid, reason in reasons:
                 print(f"{mid}: {reason}")

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

@@ -493,6 +493,19 @@ def status_line(home: Path, now: datetime) -> str:
     return f"agy: EUR {committed_last_24h(home, now):.2f} of {cap} in the last 24 h on this machine"
 
 
+def spend_json(home: Path, now: datetime | None = None) -> dict:
+    """The spend status as one JSON-ready dict. It holds no key, no prompt and no caller name."""
+    now = now or datetime.now(timezone.utc)
+    try:
+        cap = load_cap(home)
+        cap_eur, reserve_eur = float(cap.eur_per_24h), float(cap.reserve)
+    except NotConfigured:
+        cap_eur = reserve_eur = None
+    return {"schema": 1, "configured": cap_eur is not None, "cap_eur": cap_eur,
+            "committed_eur": round(committed_last_24h(home, now), 6), "reserve_eur": reserve_eur,
+            "window_h": 24}
+
+
 def main(argv: list[str] | None = None) -> int:
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")
@@ -504,7 +517,8 @@ def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="global agy spend cap (EUR per rolling 24 h, this machine)")
     sub = parser.add_subparsers(dest="cmd", required=True)
     sub.add_parser("check")
-    sub.add_parser("status")
+    p_status = sub.add_parser("status")
+    p_status.add_argument("--json", action="store_true", help="print the status as one JSON object")
     p_run = sub.add_parser("run")
     p_run.add_argument("--caller", required=True)
     p_run.add_argument("--timeout-s", type=float, default=None,
@@ -515,7 +529,7 @@ def main(argv: list[str] | None = None) -> int:
     now = datetime.now(timezone.utc)
     if args.cmd == "status":
         try:
-            print(status_line(home, now))
+            print(json.dumps(spend_json(home, now)) if args.json else status_line(home, now))
         except Exception as exc:
             print(f"caddis_spend: could not read the spend log: {exc!r}", file=sys.stderr)
             return EXIT_NOT_CONFIGURED

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

@@ -9,6 +9,7 @@ release as a no-op, because an older /handoff still calls it from its Step 6.
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import re
 import subprocess
@@ -17,7 +18,7 @@ from pathlib import Path
 
 try:
     import caddis_exit
-    from caddis_frontmatter import parse
+    from caddis_frontmatter import parse, split_document
     from caddis_workstreams import _artifact, _name
 except ModuleNotFoundError as exc:
     if exc.name not in {"caddis_exit", "caddis_file_lock", "caddis_frontmatter", "caddis_workstreams"}:
@@ -26,7 +27,7 @@ except ModuleNotFoundError as exc:
     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
-    from caddis_frontmatter import parse
+    from caddis_frontmatter import parse, split_document
     from caddis_workstreams import _artifact, _name
 
 
@@ -172,6 +173,63 @@ def tracker_table(text: str) -> tuple[list[str], list[str]] | None:
     return columns, table[:at] + table[at + 1:]
 
 
+def _plan_files(root: Path) -> list[Path]:
+    """The plan files to list: `.caddis/plans/*.md`, else the legacy `.github/plans/*.md`. Never `done/`."""
+    plans_dir = _artifact(root) / "plans"
+    if not plans_dir.is_dir():
+        plans_dir = Path(root) / ".github" / "plans"
+    if plans_dir.is_symlink() or not plans_dir.is_dir():
+        return []
+    return sorted(p for p in plans_dir.glob("*.md") if p.is_file() and not p.is_symlink())
+
+
+def _plan_entry(root: Path, path: Path) -> dict:
+    # caddis_tidy imports this module at load time, so this module imports it only here.
+    try:
+        import caddis_tidy
+    except ModuleNotFoundError as exc:
+        if exc.name != "caddis_tidy":
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import caddis_tidy
+    text = path.read_text(encoding="utf-8")
+    meta, body = split_document(text)
+    if text.lstrip("").startswith("---") and not meta:
+        raise ValueError("frontmatter is not closed or has no keys")
+    heading = re.search(r"^# (.+?)\s*$", body, re.M)
+    title = heading.group(1) if heading else meta.get("title")
+    tracker: list[dict] = []
+    table = tracker_table(text)
+    if table is not None:
+        columns, lines = table
+        status_at = columns.index("status")
+        for line in lines:
+            if not line.strip().startswith("|") or caddis_tidy._TABLE_RULE_RE.match(line.strip()):
+                continue
+            cells = caddis_tidy._row_cells(line)
+            if cells:
+                tracker.append({"phase": cells[0], "status": cells[status_at] if len(cells) > status_at else ""})
+    return {"path": path.relative_to(Path(root)).as_posix(), "title": title,
+            "status": meta.get("status"), "feature": meta.get("feature"),
+            "tracker": tracker, "open_rows": sum(1 for row in tracker if not _is_done(row["status"]))}
+
+
+def plans_json(root: Path) -> dict:
+    """Every current plan as data: `{"schema": 1, "plans": [...]}`. Never prints, never exits.
+
+    A file that does not parse gives `{"path", "error"}`; the other plans still come back.
+    """
+    root = Path(root)
+    plans: list[dict] = []
+    for path in _plan_files(root):
+        try:
+            plans.append(_plan_entry(root, path))
+        except Exception as exc:  # one bad file must not hide the others
+            rel = path.relative_to(root).as_posix()
+            plans.append({"path": rel, "error": (str(exc).splitlines() or [type(exc).__name__])[0]})
+    return {"schema": 1, "plans": plans}
+
+
 def main(argv: list[str] | None = None) -> int:
     # Plan paths may carry non-ASCII text; a Windows console defaults to a legacy code page.
     for stream in (sys.stdout, sys.stderr):
@@ -181,6 +239,10 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--root", type=Path, default=Path.cwd(), help=argparse.SUPPRESS)
     commands = parser.add_subparsers(dest="command", required=True)
     commands.add_parser("active-plan")
+    plans_p = commands.add_parser("plans", help="list the plans as JSON")
+    plans_p.add_argument("--json", action="store_true", dest="as_json")
+    # `plans --root R` works too. SUPPRESS: when absent here, the global --root (or cwd) stays.
+    plans_p.add_argument("--root", type=Path, default=argparse.SUPPRESS, help="the project folder")
     # Retired: kept one release so an older /handoff Step 6 does not fail. Takes its old flag, ignores it.
     reconcile_p = commands.add_parser("reconcile", help=argparse.SUPPRESS)
     reconcile_p.add_argument("--session-state", type=Path)
@@ -190,6 +252,15 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "reconcile":
         print(RECONCILE_RETIRED)
         return 0
+    if args.command == "plans":
+        if not args.as_json:
+            parser.error("plans needs --json")
+        try:
+            print(json.dumps(plans_json(args.root), ensure_ascii=False))
+        except (OSError, ValueError) as exc:  # a .caddis that escapes the project
+            print(f"caddis-todo: {exc}", file=sys.stderr)
+            return 1
+        return 0
     try:
         plan, candidates = active_plan(args.root)
     except (OSError, UnicodeError, ValueError) as exc:

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

@@ -259,6 +259,45 @@ def _relays(directory: Path) -> list[tuple[str, dict, str]]:
     return out
 
 
+JSON_SCHEMA = 1  # the `schema` key of every --json output (hub rule R13)
+
+
+def _relay_dir(root: Path) -> Path:
+    artifact = _artifact(root)
+    directory = artifact / "relay"
+    if directory.exists() and not directory.resolve().is_relative_to(artifact.resolve()):
+        raise ValueError("relay directory escapes artifact root")
+    return directory
+
+
+def relays_json(root: Path, now: datetime | None = None) -> dict:
+    """Return every valid relay as JSON data. A bad status line gives status INVALID."""
+    now = now or datetime.now(timezone.utc)
+    rows = []
+    for name, meta, content in _relays(_relay_dir(root)):
+        when = datetime.fromisoformat(meta["generated"]["at"].replace("Z", "+00:00"))
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=timezone.utc)
+        when = when.astimezone(timezone.utc)
+        try:
+            status, status_arg = parse_status(content)
+        except ValueError as exc:
+            status, status_arg = "INVALID", str(exc)
+        step = _next_step(content)
+        rows.append({
+            "name": name,
+            "branch": meta.get("branch"),
+            "plan": meta.get("plan"),
+            "session_id": meta.get("session_id"),
+            "updated_at": when.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "age_min": max(0, int((now - when).total_seconds()) // 60),
+            "status": status,
+            "status_arg": status_arg,
+            "next_step": None if step == "next step unrecorded" else step,
+        })
+    return {"schema": JSON_SCHEMA, "relays": sorted(rows, key=lambda r: r["name"])}
+
+
 def _item_matches(item: str, next_text: str) -> bool:
     needle = item.strip()
     if not needle:
@@ -690,6 +729,7 @@ def main(argv: list[str] | None = None) -> int:
 
     list_p = sub.add_parser("list", help="list each relay's name, branch and next step")
     list_p.add_argument("--root", type=Path, default=Path("."))
+    list_p.add_argument("--json", action="store_true")
 
     mentions_p = sub.add_parser("mentions", help="list other relays whose Next step mentions an item")
     mentions_p.add_argument("--item", required=True)
@@ -735,7 +775,7 @@ def main(argv: list[str] | None = None) -> int:
             sys.stderr.write(f"invalid relay status: {exc}\n")
             return 1
         if args.json:
-            print(json.dumps({"status": kind, "arg": arg}))
+            print(json.dumps({"schema": JSON_SCHEMA, "status": kind, "arg": arg}))
         else:
             if arg:
                 print(f"STATUS: {kind} {arg}")
@@ -788,10 +828,18 @@ def main(argv: list[str] | None = None) -> int:
             print(f"  conflict: {conflict}")
         return 0 if report.status in ("clean", "migrated") else 1
     elif args.command == "list":
-        artifact = _artifact(args.root)
-        directory = artifact / "relay"
-        if directory.exists() and not directory.resolve().is_relative_to(artifact.resolve()):
-            raise ValueError("relay directory escapes artifact root")
+        try:
+            data = relays_json(args.root) if args.json else None
+            directory = _relay_dir(args.root)
+        except ValueError as exc:  # the relay folder escapes .caddis: one error, never a traceback
+            if args.json:
+                print(json.dumps({"schema": JSON_SCHEMA, "error": str(exc)}))
+            else:
+                sys.stderr.write(f"cannot list relays: {exc}\n")
+            return 1
+        if args.json:
+            print(json.dumps(data, indent=2))
+            return 0
         for name, meta, content in _relays(directory):
             branch_label = _single_line(str(meta.get("branch", "?")), 50)
             print(f"{name}\t{branch_label}\t{_next_step(content)}")