@caddis/cli 0.4.69 → 0.4.71

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

@@ -1,29 +1,32 @@
-"""Locked, local to-do lists and a read-only view of active plan work."""
+"""The active plan and the plan Tracker reader, for commands, tidy and the gates.
+
+3-store model (owner decision, 21 Oct 2026): the session task list (`.caddis/relay/<name>.tasks.md`), the
+parking lot and the roadmap with the plan Tracker. The `.caddis/todo-list/` store and the open-work view
+are retired, with the `add`, `done`, `list` and `open-work` sub-commands. `reconcile` stays one more
+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
 import sys
-import uuid
 from pathlib import Path
 
 try:
     import caddis_exit
-    from caddis_file_lock import atomic_write, locked_path, retry_denied
-    from caddis_frontmatter import parse, split_document
+    from caddis_frontmatter import parse
     from caddis_workstreams import _artifact, _name
 except ModuleNotFoundError as exc:
     if exc.name not in {"caddis_exit", "caddis_file_lock", "caddis_frontmatter", "caddis_workstreams"}:
         raise
+    # caddis_tidy imports caddis_file_lock after this module: these two folders stay on the path.
     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_file_lock import atomic_write, locked_path, retry_denied
-    from caddis_frontmatter import parse, split_document
+    from caddis_frontmatter import parse
     from caddis_workstreams import _artifact, _name
 
 
@@ -31,81 +34,9 @@ except ModuleNotFoundError as exc:
 # have no console). Inline, not scripts/no_window.py: in the source tree this file does not sit beside it.
 _NO_WINDOW = 0x08000000 if os.name == "nt" else 0
 
-_ITEM = re.compile(r'^- \[([ x])\] (.+?) <!-- caddis: (\{.*\}) -->$')
 _PHASE = re.compile(r'^\|\s*(\d+)\s*\|', re.M)
-_WORD = re.compile(r'[a-z0-9]{3,}')
 _PLAN_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,150}")
-# Trailing status markers on phase headings: arrows/clocks (U+2300-U+27BF), emoji, VS16.
-_STATUS_MARKER = re.compile("[\\s\u2300-\u27bf\U0001f300-\U0001faff\ufe0f]+$")
-
-
-def _path(root: Path, workstream: str | None) -> tuple[Path, Path]:
-    artifact = _artifact(root)
-    name = _name(workstream) if workstream is not None else "inbox"
-    folder = artifact / "todo-list"
-    # Only a folder that EXISTS can point elsewhere. Resolving one that does not exist yet raced a concurrent
-    # writer creating it: on Windows the two paths could resolve differently (a short 8.3 name on one side), and a
-    # safe add failed with this error (main CI, 20 Oct 2026, test_concurrent_inbox_add_loses_no_item).
-    if folder.is_symlink() or (folder.exists() and not folder.resolve().is_relative_to(artifact.resolve())):
-        raise ValueError("todo-list path escapes artifact root")
-    path = folder / f"{name}.md"
-    # Reads are unlocked, so refuse here as well as in locked_path. On Windows a writer replacing the file
-    # makes this probe (and the read below) fail with PermissionError for an instant, so both retry.
-    if retry_denied(path.is_symlink):
-        raise ValueError("to-do file may not be a symlink")
-    return artifact, path
-
-
-def _read(path: Path, workstream: str | None) -> list[dict]:
-    if not retry_denied(path.exists):
-        return []
-    text = retry_denied(lambda: path.read_text(encoding="utf-8"))
-    header, body = split_document(text)
-    name = workstream or "inbox"
-    if header.get("type") != "todo" or header.get("workstream") != name or header.get("status") not in {"current", "done"}:
-        raise ValueError(f"invalid to-do header: {path}")
-    items = []
-    for line in body.splitlines():
-        if not line.strip() or line == "# To-dos":
-            continue
-        match = _ITEM.fullmatch(line)
-        if not match:
-            raise ValueError(f"invalid to-do row: {path}")
-        data = json.loads(match.group(3))
-        if not isinstance(data, dict) or not isinstance(data.get("id"), str):
-            raise ValueError(f"invalid to-do item: {path}")
-        uuid.UUID(data["id"])
-        if "resolves" in data:
-            _resolves_path(path.parents[2], data["resolves"])
-        items.append({"id": data["id"], "title": match.group(2), "done": match.group(1) == "x",
-                      **{key: data[key] for key in ("resolves", "partial") if key in data}})
-    if len({item["id"] for item in items}) != len(items):
-        raise ValueError(f"duplicate to-do id: {path}")
-    expected = "done" if workstream not in (None, "inbox") and items and all(item["done"] for item in items) else "current"
-    if header["status"] != expected:
-        raise ValueError(f"to-do status mismatch: {path}")
-    return items
-
-
-def _write(path: Path, root: Path, workstream: str | None, items: list[dict]) -> None:
-    status = "done" if workstream not in (None, "inbox") and items and all(item["done"] for item in items) else "current"
-    lines = ["---", "type: todo", f"status: {status}", f"workstream: {workstream or 'inbox'}",
-             "---", "", "# To-dos", ""]
-    for item in items:
-        metadata = {"id": item["id"]}
-        for key in ("resolves", "partial"):
-            if key in item:
-                metadata[key] = item[key]
-        box = "x" if item["done"] else " "
-        lines.append(f'- [{box}] {item["title"]} <!-- caddis: {json.dumps(metadata, sort_keys=True)} -->')
-    atomic_write(path, "\n".join(lines) + "\n", root=root)
-
-
-def _title(value: str) -> str:
-    title = " ".join(value.split())
-    if not title or len(title) > 300 or "<!--" in title or "-->" in title:
-        raise ValueError("to-do text must be one plain line (1-300 characters)")
-    return title
+RECONCILE_RETIRED = "caddis_todo: reconcile is retired (3-store model); nothing to do"
 
 
 def _resolves_path(root: Path, value: str) -> Path:
@@ -123,58 +54,6 @@ def _resolves_path(root: Path, value: str) -> Path:
     return target
 
 
-def _suggest(root: Path, title: str) -> list[str]:
-    parking = _artifact(root) / "parking-lot"
-    if not parking.is_dir() or parking.is_symlink():
-        return []
-    words = set(_WORD.findall(title.lower()))
-    found = []
-    for path in sorted(parking.glob("*.md")):
-        if path.is_symlink() or path.name == "README.md":
-            continue
-        if words & set(_WORD.findall(path.stem.lower())) or path.name.lower() in title.lower():
-            found.append(f"parking-lot/{path.name}")
-    return found
-
-
-def add(root: Path, title: str, workstream: str | None = None, *, resolves: str | None = None,
-        partial: bool = False) -> dict:
-    title = _title(title)
-    artifact, path = _path(root, workstream)
-    if partial and not resolves:
-        raise ValueError("--partial requires --resolves")
-    linked = f"parking-lot/{_resolves_path(root, resolves).name}" if resolves else None
-    with locked_path(path, root=artifact):
-        items = _read(path, workstream)
-        item = {"id": str(uuid.uuid4()), "title": title, "done": False}
-        if linked:
-            item["resolves"] = linked
-            if partial:
-                item["partial"] = True
-        items.append(item)
-        _write(path, artifact, workstream, items)
-    return item
-
-
-def done(root: Path, item_id: str, workstream: str) -> dict:
-    artifact, path = _path(root, workstream)
-    with locked_path(path, root=artifact):
-        items = _read(path, workstream)
-        matches = [item for item in items if item["id"] == item_id]
-        if not matches:
-            raise ValueError("unknown to-do id")
-        item = matches[0]
-        if not item["done"]:
-            item["done"] = True
-            _write(path, artifact, workstream, items)
-        return item
-
-
-def list_items(root: Path, workstream: str | None = None) -> list[dict]:
-    _, path = _path(root, workstream)
-    return [item for item in _read(path, workstream) if not item["done"]]
-
-
 def _is_done(status: str) -> bool:
     """A Tracker status cell that means done: "done", "done (note)" or a leading check mark.
     A cell that says work is still pending is not done (owner decision 2026-09-27)."""
@@ -276,7 +155,7 @@ def tracker_table(text: str) -> tuple[list[str], list[str]] | None:
 
     None when there is no Tracker heading line, no `| Phase |` header or no Status column. The
     lines are every line of the section except the header; callers pick the rows they trust.
-    One reader, so the open-work view and caddis_tidy never disagree about the same table.
+    One reader, so caddis_tidy and any later caller never disagree about the same table.
     """
     # A real heading line only: plan prose may mention "## Tracker" inline before the section.
     heading = re.search(r"^## Tracker\b.*$", text, re.M)
@@ -293,235 +172,39 @@ def tracker_table(text: str) -> tuple[list[str], list[str]] | None:
     return columns, table[:at] + table[at + 1:]
 
 
-def _plan_rows(plan: Path | None) -> list[dict]:
-    if plan is None:
-        return []
-    text = plan.read_text(encoding="utf-8")
-    table = tracker_table(text)
-    if table is None:
-        return []
-    columns, lines = table
-    rows = []
-    for line in lines:
-        match = _PHASE.match(line)
-        if not match:
-            continue
-        cells = [cell.strip() for cell in line.strip("|").split("|")]
-        if len(cells) != len(columns) or _is_done(cells[columns.index("status")]):
-            continue
-        number = match.group(1)
-        heading = re.search(rf"^### Phase {number}\s+[-—]\s+(.+)$", text, re.M)
-        # Drop the heading's trailing status marker (🔲, ⏳, ✅ ...): status lives in the Tracker.
-        title = _STATUS_MARKER.sub("", heading.group(1)) if heading else f"Phase {number}"
-        rows.append({"id": f"phase:{number}", "kind": "phase", "title": title})
-    return rows
-
-
-def _split_cells(line: str) -> list[str]:
-    r"""Stripped cells of one table line, split on unescaped pipes only (`a \| b` is one cell)."""
-    parts = re.split(r"(?<!\\)\|", line.strip())
-    if parts and parts[0] == "":
-        parts.pop(0)
-    if parts and parts[-1] == "":
-        parts.pop(-1)
-    return [part.strip() for part in parts]
-
-
-def _open_work_rows(root: Path) -> list[dict]:
-    path = _artifact(root) / "open-work.md"
-    if path.is_symlink() or not path.is_file():
-        return []
-    text = path.read_text(encoding="utf-8", errors="replace")
-    header, body = split_document(text)
-    if header.get("type") != "open-work":
-        return []
-    rows: list[dict] = []
-    columns: list[str] | None = None
-    id_idx = status_idx = title_idx = 0
-    for raw_line in body.splitlines():
-        line = raw_line.strip()
-        if not line.startswith("|"):
-            columns = None
-            continue
-        cells = _split_cells(line)  # unescaped pipes only, as caddis_rows.split_cells
-        if not cells or all(c and set(c) <= set("-: ") and "-" in c for c in cells):
-            continue
-        if columns is None:
-            lowered = [c.lower() for c in cells]
-            if "id" in lowered and "status" in lowered:
-                columns = lowered
-                id_idx = columns.index("id")
-                status_idx = columns.index("status")
-                title_idx = next(
-                    (i for i, col in enumerate(columns) if col in {"task", "title", "item"}),
-                    id_idx + 1,
-                )
-            continue
-        if len(cells) != len(columns):
-            continue
-        status = cells[status_idx].strip().lower()
-        first = status.split(" ", 1)[0] if status else ""
-        if _is_done(status) or first in {"not-needed", "✓", "✔"}:
-            continue
-        row_id = cells[id_idx].replace("**", "").replace("__", "").replace("`", "").strip()
-        if not row_id:
-            continue
-        title = cells[title_idx] if title_idx < len(cells) else ""
-        rows.append({"id": row_id, "kind": "open-work", "title": title})
-    return rows
-
-
-def open_work(root: Path, workstream: str | None = None) -> list[dict]:
-    rows = _plan_rows(_active_plan(root, workstream))
-    for name in (None, workstream) if workstream and workstream != "inbox" else (None,):
-        rows.extend({"id": item["id"], "kind": "todo", "title": item["title"],
-                     **{key: item[key] for key in ("resolves", "partial") if key in item}}
-                    for item in list_items(root, name))
-    rows.extend(_open_work_rows(root))
-    return rows
-
-
-def _extract_completed_ids(text: str) -> set[str]:
-    """Open-work ids of the done rows in a session-state file's "## Tasks" table.
-
-    Only the marker session_state.py writes after a task's subject counts, as in
-    ``| 3 | done | Fix x <!-- caddis: {"id": "..."} --> |``. A UUID that merely appears in a
-    task's text is never trusted: "depends on <uuid>" must not close that other item.
-    """
-    ids: set[str] = set()
-    in_tasks = False
-    for line in text.splitlines():
-        row = line.strip()
-        if row.startswith("## "):
-            in_tasks = row == "## Tasks"
-            continue
-        if not in_tasks or not row.startswith("|") or row.startswith("|---"):
-            continue
-        cells = [cell.strip() for cell in row.strip("|").split("|")]
-        # Status is the second cell; a "|" inside the subject only shifts later cells.
-        if len(cells) < 3 or cells[1].lower() not in {"done", "completed"}:
-            continue
-        marker = re.search(r"<!--\s*caddis:\s*(\{.*?\})\s*-->\s*\|?$", row)
-        if not marker:
-            continue
-        try:
-            value = json.loads(marker.group(1)).get("id")
-        except (ValueError, AttributeError):
-            continue
-        if isinstance(value, str) and value:
-            ids.add(value.lower())
-    return ids
-
-
-def reconcile(root: Path, session_state: Path) -> list[str]:
-    """Reconcile completed task rows from session-state into todo-lists.
-
-    Marks ad-hoc todo items done by metadata ID.
-    Never edits the Tracker; phase rows are ignored.
-    """
-    if not session_state.is_file():
-        return []
-
-    text = session_state.read_text(encoding="utf-8", errors="replace")
-    completed_ids = _extract_completed_ids(text)
-    if not completed_ids:
-        return []
-
-    artifact = _artifact(root)
-    todo_dir = artifact / "todo-list"
-    if not todo_dir.is_dir():
-        return []
-
-    reconciled: list[str] = []
-    # Ignore phase rows — Tracker is never edited!
-    adhoc_ids = {cid for cid in completed_ids if not cid.startswith("phase:")}
-    if not adhoc_ids:
-        return []
-
-    wanted = {a.lower() for a in adhoc_ids}
-    for todo_file in todo_dir.glob("*.md"):
-        if todo_file.is_symlink() or not todo_file.is_file():
-            continue
-        workstream_name = todo_file.stem
-        try:
-            items = _read(todo_file, workstream_name)
-        except (ValueError, OSError):
-            continue  # a hand-edited file caddis cannot read; the others still reconcile
-        for item in items:
-            item_id = item.get("id")
-            if item_id and item_id.lower() in wanted and not item.get("done"):
-                done(root, item_id, workstream_name)
-                reconciled.append(item_id)
-
-    return reconciled
-
-
 def main(argv: list[str] | None = None) -> int:
-    # Titles carry non-ASCII text; a Windows console defaults to a legacy code page.
+    # Plan paths may carry non-ASCII text; a Windows console defaults to a legacy code page.
     for stream in (sys.stdout, sys.stderr):
         if hasattr(stream, "reconfigure"):
             stream.reconfigure(encoding="utf-8", errors="replace")
-    parser = argparse.ArgumentParser(description=__doc__)
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     parser.add_argument("--root", type=Path, default=Path.cwd(), help=argparse.SUPPRESS)
     commands = parser.add_subparsers(dest="command", required=True)
-    listing = commands.add_parser("list")
-    listing.add_argument("workstream", nargs="?")
-    adding = commands.add_parser("add")
-    adding.add_argument("text")
-    adding.add_argument("--workstream")
-    adding.add_argument("--resolves")
-    adding.add_argument("--partial", action="store_true")
-    finishing = commands.add_parser("done")
-    finishing.add_argument("id")
-    finishing.add_argument("--workstream", required=True)
-    view = commands.add_parser("open-work")
-    view.add_argument("--workstream")
-    view.add_argument("--json", action="store_true")
-    reconcile_p = commands.add_parser("reconcile")
-    reconcile_p.add_argument("--session-state", type=Path, required=True)
     commands.add_parser("active-plan")
-    args = parser.parse_args(argv)
-    try:
-        if args.command == "add":
-            item = add(args.root, args.text, args.workstream, resolves=args.resolves, partial=args.partial)
-            print(item["id"])
-            if not args.resolves:
-                for suggestion in _suggest(args.root, item["title"]):
-                    print(f"Suggested parking item: {suggestion}")
-        elif args.command == "done":
-            item = done(args.root, args.id, args.workstream)
-            if "resolves" in item:
-                prefix = "Partly-Resolves-Parked" if item.get("partial") else "Resolves-Parked"
-                print(f'{prefix}: {item["resolves"]}')
-        elif args.command == "list":
-            for item in list_items(args.root, args.workstream):
-                print(f'{item["id"]} {item["title"]}')
-        elif args.command == "active-plan":
-            plan, candidates = active_plan(args.root)
-            if plan is None:
-                if candidates:
-                    print("caddis-todo: several current plans; name one:", file=sys.stderr)
-                    for candidate in candidates:
-                        print(f"  {candidate}", file=sys.stderr)
-                else:
-                    print("caddis-todo: no current plan in .caddis/plans", file=sys.stderr)
-                return caddis_exit.NOT_RUN
-            print(plan)
-        elif args.command == "reconcile":
-            reconciled = reconcile(args.root, args.session_state)
-            for rid in reconciled:
-                print(f"Reconciled: {rid}")
-        else:
-            rows = open_work(args.root, args.workstream)
-            if args.json:
-                print(json.dumps(rows, ensure_ascii=False))
-            else:
-                for row in rows:
-                    print(f'{row["id"]} [{row["kind"]}] {row["title"]}')
+    # 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)
+    args, extra = parser.parse_known_args(argv)
+    if extra and args.command != "reconcile":
+        parser.error(f"unrecognized arguments: {' '.join(extra)}")  # only the retired no-op tolerates old flags
+    if args.command == "reconcile":
+        print(RECONCILE_RETIRED)
         return 0
-    except (OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
+    try:
+        plan, candidates = active_plan(args.root)
+    except (OSError, UnicodeError, ValueError) as exc:
         print(f"caddis-todo: {exc}", file=sys.stderr)
         return 1
+    if plan is None:
+        if candidates:
+            print("caddis-todo: several current plans; name one:", file=sys.stderr)
+            for candidate in candidates:
+                print(f"  {candidate}", file=sys.stderr)
+        else:
+            print("caddis-todo: no current plan in .caddis/plans", file=sys.stderr)
+        return caddis_exit.NOT_RUN
+    print(plan)
+    return 0
 
 
 if __name__ == "__main__":

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""caddis_upstream_check - say when an upstream skill that caddis borrowed ideas from has changed.
+
+Why: /caddis:feature-plan and /caddis:implement adapt ideas from obra/superpowers (writing-plans 7.0.0,
+subagent-driven-development 7.0.0, MIT). `.github/upstream-sources.json` records, per borrowed file, the
+upstream version and the sha256 of the file we read. This script compares that record with the copies
+installed in the Claude Code plugin cache (`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/<path>`),
+so caddis does not fall behind upstream without anyone seeing it. /caddis:usage-review runs it.
+
+One line per source:
+    UP-TO-DATE <id> <version>
+    DRIFT <id> recorded <v> installed <v'> (sha differs): review the upstream diff and port what fits, ...
+    NOT-INSTALLED <id>
+`NO-SOURCES <path>` means there is no record (any repo other than the caddis source repo).
+
+Advisory only: the exit code is always 0. Stdlib only.
+
+Usage:
+    python caddis_upstream_check.py [--sources <json>] [--cache-root <dir>] [--json]
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+SOURCES_REL = Path(".github") / "upstream-sources.json"
+DRIFT_ADVICE = "review the upstream diff and port what fits, then update .github/upstream-sources.json"
+
+
+def default_sources() -> Path:
+    """The record in the current repo; else the one next to this script in a source checkout."""
+    here = Path.cwd() / SOURCES_REL
+    if here.is_file():
+        return here
+    return Path(__file__).resolve().parents[1] / SOURCES_REL
+
+
+def default_cache_root() -> Path:
+    return Path.home() / ".claude" / "plugins" / "cache"
+
+
+def _version_key(version: str) -> tuple:
+    """Numeric parts compare as numbers (7.10.0 > 7.9.0); a non-numeric part sorts before any number."""
+    return tuple((1, int(p)) if p.isdigit() else (0, p) for p in version.split("."))
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def installed_copies(cache_root: Path, plugin: str, rel_path: str) -> list[tuple[str, Path]]:
+    """(version, file) for every installed copy, newest version last."""
+    if not cache_root.is_dir():
+        return []
+    found = [(f.parents[len(Path(rel_path).parts) - 1].name, f)
+             for f in cache_root.glob(f"*/{plugin}/*/{rel_path}") if f.is_file()]
+    return sorted(found, key=lambda vf: _version_key(vf[0]))
+
+
+def check_source(src: dict, cache_root: Path) -> dict:
+    sid, recorded = src["id"], src["version"]
+    plugin = sid.split(":", 1)[0]
+    copies = installed_copies(cache_root, plugin, src["path"])
+    row = {"id": sid, "status": "NOT-INSTALLED", "recorded_version": recorded, "installed_version": None,
+           "line": f"NOT-INSTALLED {sid}"}
+    if not copies:
+        return row
+    version, newest = copies[-1]
+    row["installed_version"] = version
+    if _sha256(newest) == src["sha256"]:
+        row.update(status="UP-TO-DATE", line=f"UP-TO-DATE {sid} {recorded}")
+    else:
+        row.update(status="DRIFT",
+                   line=f"DRIFT {sid} recorded {recorded} installed {version} (sha differs): {DRIFT_ADVICE}")
+    return row
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Compare borrowed upstream skills with the installed copies.")
+    ap.add_argument("--sources", type=Path, default=None, help="path to upstream-sources.json")
+    ap.add_argument("--cache-root", type=Path, default=None, help="the Claude Code plugin cache folder")
+    ap.add_argument("--json", action="store_true", help="print the rows as a JSON list")
+    args = ap.parse_args(argv)
+    sources = args.sources or default_sources()
+    cache_root = args.cache_root or default_cache_root()
+    if not sources.is_file():
+        print(f"NO-SOURCES {sources}")
+        return 0
+    try:
+        data = json.loads(sources.read_text(encoding="utf-8"))
+        rows = [check_source(src, cache_root) for src in data.get("sources", [])]
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        print(f"NO-SOURCES {sources} (unreadable: {exc})")
+        return 0
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        for row in rows:
+            print(row["line"])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundles/antigravity-plugin/scripts/schemas/coordinator.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "caddis hub coordinator state (coordinator.json)",
+  "description": "One file per repo id, written only by caddis_coordinate.py. Readers accept schema N and N-1.",
+  "type": "object",
+  "required": ["schema", "repo", "coordinator_session", "heartbeat_at", "queue", "merging_now", "deploy_checks",
+               "ledger", "processed_requests"],
+  "properties": {
+    "schema": {"type": "integer", "enum": [0, 1]},
+    "repo": {"type": "string", "minLength": 1},
+    "coordinator_session": {
+      "type": "object",
+      "required": ["name", "sessionId", "pid"],
+      "properties": {
+        "name": {"type": ["string", "null"]},
+        "sessionId": {"type": ["string", "null"]},
+        "pid": {"type": ["integer", "null"]}
+      }
+    },
+    "heartbeat_at": {"$ref": "#/$defs/utc"},
+    "queue": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["pr", "head_sha", "title", "state", "why_waiting", "waits_on", "hotfix", "held",
+                     "entered_ready_at"],
+        "properties": {
+          "pr": {"type": "integer", "minimum": 1},
+          "head_sha": {"type": "string"},
+          "title": {"type": "string"},
+          "state": {"enum": ["waiting", "ci", "ready", "merging", "blocked", "held"]},
+          "why_waiting": {"type": "string"},
+          "waits_on": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["repo", "pr"],
+              "properties": {"repo": {"type": "string"}, "pr": {"type": "integer"}}
+            }
+          },
+          "hotfix": {"type": "boolean"},
+          "held": {"type": "boolean"},
+          "entered_ready_at": {"anyOf": [{"$ref": "#/$defs/utc"}, {"type": "null"}]}
+        }
+      }
+    },
+    "merging_now": {"type": ["integer", "object", "null"]},
+    "deploy_checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["pr", "merge_sha", "deploy_run", "health", "at"],
+        "properties": {
+          "pr": {"type": "integer"},
+          "merge_sha": {"type": "string", "pattern": "^[0-9a-f]{40}$", "description": "lower-cased"},
+          "deploy_run": {"type": ["integer", "null"]},
+          "health": {"enum": ["pending", "ok", "failed"]},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    },
+    "ledger": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["what", "decision", "approved_by", "reason", "window", "request_id", "at"],
+        "properties": {
+          "what": {"type": "string", "minLength": 1},
+          "decision": {"enum": ["approve", "decline"]},
+          "approved_by": {"enum": ["owner", "coordinator"]},
+          "reason": {"type": "string", "minLength": 1},
+          "window": {"type": ["string", "null"], "description": "the session window the decision was made in; \"hub\" for an owner click"},
+          "request_id": {"type": ["string", "null"], "description": "the owner request id; null when not from a request"},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    },
+    "processed_requests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "result", "reason", "at"],
+        "properties": {
+          "id": {"type": "string"},
+          "result": {"enum": ["done", "rejected", "expired"]},
+          "reason": {"type": "string"},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    }
+  },
+  "$defs": {
+    "utc": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"}
+  }
+}