@caddis/cli 0.4.71 → 0.4.72

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.157",
+  "version": "1.3.158",
   "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_coordinate.py

@@ -15,8 +15,10 @@ import hashlib
 import json
 import os
 import re
+import shutil
 import subprocess
 import sys
+import time
 from collections.abc import Callable
 from pathlib import Path
 
@@ -43,10 +45,10 @@ _URL = re.compile(
 )
 
 
-def _run(args: list[str], cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
+def _run(args: list[str], cwd: Path | None = None, timeout: float = _TIMEOUT) -> subprocess.CompletedProcess[str]:
     # utf-8 explicitly: the Windows default code page garbles non-ASCII paths and titles.
     return subprocess.run(args, cwd=cwd, capture_output=True, text=True, encoding="utf-8", errors="replace",
-                          timeout=_TIMEOUT, creationflags=_NO_WINDOW)
+                          timeout=timeout, creationflags=_NO_WINDOW)
 
 
 def repo_id(remote_name_with_owner: str | None, is_fork_of: str | None, git_root: Path) -> str:
@@ -815,8 +817,8 @@ def queue_merged(rid: str, pr: int, merge_sha: str) -> bool:
 
 
 def deploy_check_set(rid: str, pr: int, *, deploy_run: int | None = None, health: str | None = None) -> None:
-    """Set the deploy run and/or health of the newest deploy check for a PR. Raises ValueError for a health not in
-    `DEPLOY_HEALTH`, a run that is not an integer, or a PR with no deploy check."""
+    """Set the deploy run and/or health of the newest deploy check for a PR; a health also sets `at` to now.
+    Raises ValueError for a health not in `DEPLOY_HEALTH`, a run that is not an integer, or a PR with no deploy check."""
     if health is not None and health not in DEPLOY_HEALTH:
         raise ValueError(f"unknown deploy health: {health!r}")
     if deploy_run is not None and (isinstance(deploy_run, bool) or not isinstance(deploy_run, int)):
@@ -829,8 +831,9 @@ def deploy_check_set(rid: str, pr: int, *, deploy_run: int | None = None, health
             raise ValueError(f"no deploy check for PR {pr}")
         if deploy_run is not None:
             check["deploy_run"] = deploy_run
-        if health is not None:
+        if health is not None:  # stamp `at`, so the newest entry by `at` is the newest health (freeze rule)
             check["health"] = health
+            check["at"] = _now()
     _mutate_state(rid, change)
 
 
@@ -886,6 +889,20 @@ def _gh_head_of(rid: str) -> Callable[[int], str | None]:
     return head_of
 
 
+def _gh_title(rid: str, pr: int) -> str:
+    """The PR title from gh, so the model never puts free text on a command line; `PR #<n>` on any failure."""
+    fallback = f"PR #{pr}"
+    if rid.startswith("local__") or "__" not in rid:
+        return fallback
+    owner, name = rid.split("__", 1)
+    try:
+        result = _run(["gh", "pr", "view", str(pr), "-R", f"{owner}/{name}", "--json", "title", "-q", ".title"])
+    except (OSError, subprocess.SubprocessError):
+        return fallback
+    title = result.stdout.strip() if result.returncode == 0 else ""
+    return title or fallback
+
+
 def _claim_state(rid: str, session: dict) -> None:
     """After the lock is taken: create `coordinator.json`, or record the new coordinator session in it."""
     with locked_path(state_path(rid)) as path:
@@ -899,6 +916,445 @@ def _claim_state(rid: str, session: dict) -> None:
         _write_state_unlocked(path, state)
 
 
+def session_lookup(sessions: list[dict], *, session_id: str | None = None, name: str | None = None) -> dict:
+    """Return `{"pid", "sessionId", "name"}` of the ONE interactive session with this sessionId or name.
+
+    Background entries are ignored: their pid is not a long-lived Claude Code session (ruling R12)."""
+    if (session_id is None) == (name is None):
+        raise ValueError("session_lookup takes exactly one of session_id or name")
+    key, wanted = ("sessionId", session_id) if session_id is not None else ("name", name)
+    hits = [s for s in sessions if isinstance(s, dict) and s.get("kind") == "interactive" and s.get(key) == wanted]
+    if not hits:
+        raise ValueError(f"no such session: {key} {wanted!r}")
+    if len(hits) > 1:
+        pids = ", ".join(str(s.get("pid")) for s in hits)
+        raise ValueError(f"two interactive sessions share {key} {wanted!r}: pids {pids}")
+    hit = hits[0]
+    pid = hit.get("pid")
+    if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
+        raise ValueError(f"session {key} {wanted!r} has no valid pid: {pid!r}")
+    for field in ("sessionId", "name"):
+        if not isinstance(hit.get(field), str) or not hit[field]:
+            raise ValueError(f"session {key} {wanted!r} has no {field}")
+    return {"pid": pid, "sessionId": hit["sessionId"], "name": hit["name"]}
+
+
+# --- the per-repo config `.caddis/coordinator.md` (C2.2, ruling R10: one fenced json block) --------------------
+
+CONFIG_KEYS = ("schema", "default_branch", "merge_method", "required_checks", "not_required", "docs_only",
+               "main_workflow", "reviews", "peer_ack", "deploy", "owner_reserved", "stall", "quiet")
+CONFIG_SCHEMA = 1
+_PLACEHOLDER = "<fill:"
+_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)")  # a Markdown code fence and its info string
+_TEMPLATE_PATH = Path(__file__).resolve().parent / "templates" / "coordinator.md"
+
+
+def config_path(repo_root: Path) -> Path:
+    return Path(repo_root) / ".caddis" / "coordinator.md"
+
+
+def _closes(line: str, fence: str) -> bool:
+    """True when `line` closes a block opened by `fence`: same character, at least as long, nothing after it."""
+    closed = re.match(r"^ {0,3}(`{3,}|~{3,})[ \t]*$", line)
+    return bool(closed) and closed.group(1)[0] == fence[0] and len(closed.group(1)) >= len(fence)
+
+
+def _config_block(text: str) -> object:
+    """Parse the FIRST fenced block whose info string is `json`. Raise ValueError when there is none."""
+    lines = text.splitlines()
+    i = 0
+    while i < len(lines):
+        opened = _FENCE.match(lines[i])
+        if not opened:
+            i += 1
+            continue
+        fence, info = opened.group(1), opened.group(2).lower()
+        body: list[str] = []
+        i += 1
+        while i < len(lines) and not _closes(lines[i], fence):
+            body.append(lines[i])
+            i += 1
+        i += 1
+        if info == "json":
+            try:
+                return json.loads("\n".join(body))
+            except ValueError as exc:
+                raise ValueError(f"the json block in the config does not parse: {exc}") from exc
+    raise ValueError("the config has no fenced json block")
+
+
+def _placeholders(value: object, where: str = "") -> list[str]:
+    """Every key path (at any depth) whose value is a string that starts with `<fill:`."""
+    if isinstance(value, str):
+        return [where] if value.startswith(_PLACEHOLDER) else []
+    if isinstance(value, dict):
+        return [hit for k, v in value.items() for hit in _placeholders(v, f"{where}.{k}" if where else str(k))]
+    if isinstance(value, list):
+        return [hit for n, v in enumerate(value) for hit in _placeholders(v, f"{where}[{n}]")]
+    return []
+
+
+def load_config(repo_root: Path) -> dict:
+    """Read `<repo_root>/.caddis/coordinator.md` and return its json block.
+
+    Raise FileNotFoundError when the file is missing, ValueError when there is no json block, a key is missing,
+    `schema` is not 1, or a value is still a `<fill: ...>` placeholder."""
+    path = config_path(repo_root)
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise FileNotFoundError(f"no coordinator config at {path} (run: caddis_coordinate.py config init)") from exc
+    config = _config_block(text)
+    if not isinstance(config, dict):
+        raise ValueError("the config json block must be one JSON object")
+    missing = [key for key in CONFIG_KEYS if key not in config]
+    if missing:
+        raise ValueError(f"the config is missing keys: {', '.join(missing)}")
+    schema = config["schema"]
+    if not isinstance(schema, int) or isinstance(schema, bool) or schema != CONFIG_SCHEMA:
+        raise ValueError(f"the config schema must be {CONFIG_SCHEMA}, not {schema!r}")
+    unfilled = _placeholders(config)
+    if unfilled:
+        raise ValueError(f"the config still has {_PLACEHOLDER} placeholders at: {', '.join(unfilled)}")
+    return config
+
+
+def init_config(repo_root: Path) -> Path:
+    """Copy the template to `<repo_root>/.caddis/coordinator.md` when it is absent. Never overwrite."""
+    path = config_path(repo_root)
+    template = _TEMPLATE_PATH.read_text(encoding="utf-8")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with open(path, "x", encoding="utf-8", newline="") as handle:  # "x": fails if the file exists, no race
+            handle.write(template)
+    except FileExistsError:
+        pass
+    return path
+
+
+# --- the watcher loop (C2.3) --------------------------------------------------------------------------------------
+
+
+def _say(exc: BaseException) -> str:
+    return " ".join(str(exc).split()) or type(exc).__name__
+
+
+def watch_cycle(rid: str, pid: int, now: datetime.datetime, head_of: Callable[[int], str | None]) -> dict:
+    """One watcher cycle: check the lock still names `pid` and that session is alive, then heartbeat and intake.
+
+    Returns `{"stop": "lock lost" | "session gone" | "state gone"}` when the watcher must end, else
+    `{"stop": None, "results": [...], "error": str | None}`. A transient failure (a lock file or state file that
+    cannot be read now, a lock timeout) goes into `error` and is never raised: the next cycle retries. The watcher
+    never takes the lock and changes the queue only through `intake`. The pid check is local (no `claude agents`).
+    """
+    def failed(message: str) -> dict:
+        return {"stop": None, "results": [], "error": message}
+
+    try:
+        holder = _read_holder(_lock_path(rid))
+    except OSError as exc:  # fail closed: it may still name us, so retry next tick rather than stop
+        if not _pid_alive(pid):  # ... unless our own session is dead: then nothing is left to watch for
+            return {"stop": "session gone"}
+        return failed(f"lock file unreadable: {_say(exc)}")
+    if holder is None or holder["pid"] != pid:
+        return {"stop": "lock lost"}
+    if not _holder_alive(holder):  # the pid is dead, or now belongs to a newer process (pid reuse)
+        return {"stop": "session gone"}
+    if not state_path(rid).exists():  # checked first: heartbeat must never recreate the repo folder
+        return {"stop": "state gone"}
+    try:
+        heartbeat(rid)
+        results = intake(rid, now, head_of)
+    except FileNotFoundError:
+        return {"stop": "state gone"}
+    except ValueError as exc:
+        if not state_path(rid).exists():
+            return {"stop": "state gone"}
+        return failed(_say(exc))
+    except OSError as exc:  # sharing error, lock timeout (TimeoutError): retry next tick
+        return failed(_say(exc))
+    except Exception as exc:  # e.g. a hand-edited state file: report it, keep watching
+        return failed(f"unexpected {type(exc).__name__}: {_say(exc)}")
+    return {"stop": None, "results": results, "error": None}
+
+
+def watch(rid: str, pid: int, interval: float, max_cycles: int | None = None) -> int:
+    """Run `watch_cycle` every `interval` seconds. Print one JSON line (flushed) for each cycle with results or a
+    stop, and for an error that differs from the previous cycle's error; print nothing for a quiet cycle or a
+    repeated error. Return 0 on a stop or after `max_cycles` cycles."""
+    head_of = _gh_head_of(rid)
+    cycles = 0
+    last_error: str | None = None
+    try:
+        while True:
+            out = watch_cycle(rid, pid, datetime.datetime.now(datetime.timezone.utc), head_of)
+            error = out.get("error")
+            if out.get("stop") or out.get("results") or (error and error != last_error):
+                print(json.dumps(out, separators=(",", ":")), flush=True)
+            last_error = error
+            if out.get("stop"):
+                return EXIT_OK
+            cycles += 1
+            if max_cycles is not None and cycles >= max_cycles:
+                return EXIT_OK
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        return EXIT_OK
+
+
+# --- deploy check D1-D5 by script (C2.4, ruling R11) -------------------------------------------------------------
+
+DEPLOY_CHECKS = ("D1", "D2", "D3", "D4", "D5")
+_DEPLOY_TIMEOUT = 60  # one subprocess: `git fetch --tags`, or curl with its own --max-time 20
+_CURL_MAX_TIME = "20"
+
+
+def _deploy_run(args: list[str]) -> subprocess.CompletedProcess[str]:
+    """The default runner of `deploy_verify`: `_run` with a timeout longer than curl's own `--max-time`."""
+    return _run(args, timeout=_DEPLOY_TIMEOUT)
+
+
+def _curl() -> str:
+    """Windows: System32 curl.exe under %SystemRoot%, by full path, when it exists (a bare name lets CreateProcess
+    pick a curl.exe from the current folder first), else `curl.exe` on PATH. Elsewhere: `curl` on PATH."""
+    if os.name != "nt":
+        return "curl"
+    system = Path(os.environ.get("SystemRoot") or "") / "System32" / "curl.exe"
+    return str(system) if os.environ.get("SystemRoot") and system.is_file() else "curl.exe"
+
+
+def _plain_path(path: object) -> str:
+    """A URL path compared for `never_health_path`: lowercased, no query string or fragment, no trailing slash."""
+    return re.split(r"[?#]", str(path), maxsplit=1)[0].rstrip("/").lower()
+
+
+def _unset(value: object) -> bool:
+    return value is None or (isinstance(value, str) and value.strip().lower() in ("", "none", "null"))
+
+
+def _checks_summary(checks: dict, docs_only: bool) -> str:
+    """`passed: D1, D2, D5; skipped: D3, D4`, from the checks dict, with a `docs-only: ` prefix."""
+    parts = []
+    for label, mark in (("passed", "pass"), ("skipped", "skip")):
+        names = [name for name, value in checks.items() if value == mark]
+        if names:
+            parts.append(f"{label}: {', '.join(names)}")
+    return ("docs-only: " if docs_only else "") + "; ".join(parts)
+
+
+class _CheckFailed(Exception):
+    def __init__(self, reason: str, health: str = "failed") -> None:
+        super().__init__(reason)
+        self.health = health
+
+
+def _call(runner: Callable[[list[str]], subprocess.CompletedProcess[str]], argv: list[str],
+          what: str) -> subprocess.CompletedProcess[str]:
+    """Run one command; a missing tool, a timeout or a non-zero exit is a check failure, never a crash."""
+    try:
+        result = runner(argv)
+    except subprocess.TimeoutExpired:
+        raise _CheckFailed(f"{what} timed out") from None
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise _CheckFailed(f"{what} could not run ({Path(argv[0]).name}): {_say(exc)}") from None
+    if result.returncode != 0:
+        detail = " ".join((result.stderr or result.stdout or "").split()) or f"exit {result.returncode}"
+        raise _CheckFailed(f"{what} failed: {detail}")
+    return result
+
+
+def deploy_verify(rid: str, cfg: dict, pr: int, merge_sha: str, *, docs_only: bool,
+                  runner: Callable[[list[str]], subprocess.CompletedProcess[str]] | None = None,
+                  env=os.environ, repo_root: Path | None = None) -> dict:
+    """Run deploy checks D1-D5 for a merged PR, record the result with `deploy_check_set`, and return
+    `{"checks": {"D1".."D5": "pass|fail|skip"}, "run": int | None, "health": "ok|failed|pending", "reason": str}`.
+
+    Checks run in order and stop at the first failure (the rest are `skip`). D2 does not wait: the model waits
+    with `caddis_lanes.py ci-watch --run` first. Docs-only runs D1, D2 and D5 only, and D2 fails when the run
+    contradicts the flag (a job named `deploy...` succeeded, or `deploy.jobs` jobs succeeded). A non-docs run needs
+    `deploy.jobs` successful jobs, and every job when it has more. `deploy.never_health_path` is never requested.
+    `GH_TOKEN` comes from the inherited environment only. `repo_root` is where the git commands of D3 run.
+    A run still in progress at D2 records health `pending`, not `failed`.
+    Raises ValueError, before any network call and with nothing recorded, for a merge SHA that is not a full SHA,
+    a PR with no deploy check, or a merge SHA that differs from the one in the PR's newest deploy check."""
+    if not isinstance(merge_sha, str) or not _SHA.fullmatch(merge_sha):
+        raise ValueError(f"the merge SHA must be a full 40-character SHA: {merge_sha!r}")
+    state = read_state(rid)
+    check = next((c for c in reversed((state or {}).get("deploy_checks") or [])
+                  if isinstance(c, dict) and c.get("pr") == pr), None)
+    if check is None:
+        raise ValueError(f"no deploy check for PR {pr} (run queue merged first)")
+    if str(check.get("merge_sha", "")).lower() != merge_sha.lower():
+        raise ValueError(f"merge SHA {merge_sha[:12]} is not the recorded merge SHA "
+                         f"{str(check.get('merge_sha'))[:12]} of PR {pr}")
+    runner = runner or _deploy_run
+    deploy = cfg.get("deploy") if isinstance(cfg.get("deploy"), dict) else {}
+    sha = merge_sha.lower()
+    checks = {name: "skip" for name in DEPLOY_CHECKS}
+    found: dict = {"run": None}
+
+    def curl(path: str, *extra: str) -> list[str]:
+        auth = deploy.get("auth")
+        if _unset(auth):
+            auth_args: list[str] = []
+        elif auth == "ntlm":
+            auth_args = ["--ntlm", "-u", ":"]
+        else:
+            raise _CheckFailed(f"unknown deploy.auth {auth!r} (known: ntlm, none)")
+        name = deploy.get("base_url_env")
+        if _unset(name):
+            raise _CheckFailed("deploy.base_url_env is not set in the config")
+        base = env.get(name)
+        if not base:
+            raise _CheckFailed(f"base URL env {name} not set")
+        if not isinstance(path, str) or not path.startswith("/"):
+            raise _CheckFailed(f"a deploy path must start with '/': {path!r}")
+        never = deploy.get("never_health_path")
+        if not _unset(never) and _plain_path(path) == _plain_path(never):
+            raise _CheckFailed(f"refused: {path} is deploy.never_health_path")
+        return [_curl(), "-s", "--max-time", _CURL_MAX_TIME, *auth_args, *extra, base.rstrip("/") + path]
+
+    def d1() -> None:
+        if rid.startswith("local__") or "__" not in rid:
+            raise _CheckFailed(f"repo {rid} has no GitHub repository")
+        owner, name = rid.split("__", 1)
+        branch, workflow = cfg.get("default_branch"), cfg.get("main_workflow")
+        event = deploy.get("event") or "push"
+        if _unset(workflow) or not isinstance(workflow, str):
+            raise _CheckFailed("main_workflow is not set in the config")
+        out = _call(runner, ["gh", "run", "list", "-R", f"{owner}/{name}", "--branch", str(branch),
+                             "--event", str(event), "--workflow", workflow, "--limit", "50",
+                             "--json", "databaseId,headSha,status,conclusion"], "gh run list")
+        try:
+            runs = json.loads(out.stdout)
+        except ValueError:
+            raise _CheckFailed("gh run list did not print JSON") from None
+        hits = [r for r in runs if isinstance(r, dict) and str(r.get("headSha", "")).lower() == sha] \
+            if isinstance(runs, list) else []
+        if not hits:
+            raise _CheckFailed(f"no {event} run of {workflow} on {branch} for {merge_sha[:12]}")
+        found["run"] = hits[0]  # gh lists newest first
+        run_id = hits[0].get("databaseId")
+        found["id"] = run_id if isinstance(run_id, int) and not isinstance(run_id, bool) else None
+
+    def d2() -> None:
+        run = found["run"]
+        status, conclusion = run.get("status"), run.get("conclusion")
+        if status != "completed":
+            raise _CheckFailed(f"run {found['id']} still running: wait for it with ci-watch --run first", "pending")
+        if conclusion != "success":
+            raise _CheckFailed(f"run {found['id']} concluded {conclusion}")
+        want = deploy.get("jobs")
+        want_ok = isinstance(want, int) and not isinstance(want, bool) and want >= 1
+        if not docs_only and not want_ok:
+            raise _CheckFailed(f"deploy.jobs must be a job count of 1 or more, not {want!r}")
+        if found["id"] is None:
+            raise _CheckFailed("the push run has no databaseId")
+        owner, name = rid.split("__", 1)
+        out = _call(runner, ["gh", "run", "view", str(found["id"]), "-R", f"{owner}/{name}", "--json", "jobs"],
+                    "gh run view")
+        try:
+            jobs = json.loads(out.stdout).get("jobs")
+        except (ValueError, AttributeError):
+            jobs = None
+        if not isinstance(jobs, list):
+            raise _CheckFailed("gh run view did not print a jobs list")
+        succeeded = [j for j in jobs if isinstance(j, dict) and j.get("conclusion") == "success"]
+        done = len(succeeded)
+        if docs_only:  # a docs-only push deploys nothing: a run that deployed contradicts the flag
+            deployed = any("deploy" in str(j.get("name", "")).lower() for j in succeeded)
+            if deployed or (want_ok and done >= want):
+                raise _CheckFailed(f"docs-only flag contradicts the run: {done} jobs succeeded")
+            return
+        others = ", ".join(f"{j.get('name')}={j.get('conclusion')}" for j in jobs
+                           if isinstance(j, dict) and j.get("conclusion") != "success")
+        detail = f" ({others})" if others else ""
+        if done < want:
+            raise _CheckFailed(f"run {found['id']}: {done} of {want} jobs succeeded{detail}")
+        if len(jobs) != want and done != len(jobs):  # extra jobs: every one must succeed
+            raise _CheckFailed(f"run {found['id']}: {len(jobs)} jobs, not {want}, and not all succeeded{detail}")
+
+    def d3() -> None:
+        git = ["git", "-C", str(repo_root)] if repo_root is not None else ["git"]
+        _call(runner, [*git, "fetch", "--tags"], "git fetch --tags")
+        out = _call(runner, [*git, "tag", "--points-at", merge_sha], "git tag --points-at")
+        if not out.stdout.strip():
+            raise _CheckFailed(f"no release tag points at {merge_sha[:12]}")
+
+    def d4() -> None:
+        path = deploy.get("version_path")
+        out = _call(runner, curl(path), f"curl {path}")
+        try:
+            body = json.loads(out.stdout)
+        except ValueError:
+            raise _CheckFailed(f"{path} did not return JSON") from None
+        reported = body.get("sha") if isinstance(body, dict) else None
+        if not isinstance(reported, str) or not reported.lower().startswith(sha):
+            raise _CheckFailed(f"{path} reports sha {reported!r}, not {merge_sha[:12]}")
+
+    def d5() -> None:
+        path = deploy.get("health_path")
+        if _unset(path):
+            raise _CheckFailed("deploy.health_path is not set in the config")
+        null = "NUL" if os.name == "nt" else "/dev/null"
+        out = _call(runner, curl(path, "-o", null, "-w", "%{http_code}"), f"curl {path}")
+        code = out.stdout.strip()
+        if code != "200":
+            raise _CheckFailed(f"{path} returned HTTP {code or 'nothing'}, not 200")
+
+    steps = [("D1", d1, True), ("D2", d2, True),
+             ("D3", d3, not docs_only and not _unset(deploy.get("tag"))),
+             ("D4", d4, not docs_only and not _unset(deploy.get("version_path"))),
+             ("D5", d5, True)]
+    health, reason = "ok", ""
+    for name, step, applies in steps:
+        if not applies:
+            continue
+        try:
+            step()
+        except _CheckFailed as exc:
+            checks[name], health, reason = "fail", exc.health, str(exc)
+            break
+        checks[name] = "pass"
+    if health == "ok":
+        reason = _checks_summary(checks, docs_only)
+    run_id = found.get("id")
+    deploy_check_set(rid, pr, deploy_run=run_id, health=health)
+    return {"checks": checks, "run": run_id, "health": health, "reason": reason}
+
+
+def _deploy_root(config_path_arg: str) -> Path:
+    """`--config-path` names the config file or the repo root; return the repo root."""
+    given = Path(config_path_arg)
+    if given.is_dir():
+        return given
+    root = given.resolve().parent.parent
+    if config_path(root).resolve() != given.resolve():
+        raise ValueError(f"--config-path must be a repo root or its .caddis/coordinator.md: {given}")
+    return root
+
+
+def _claude_agents() -> list[dict]:
+    """Run `claude agents --json` and return its list. Raise OSError or ValueError on failure."""
+    claude = shutil.which("claude")  # on Windows this finds claude.CMD
+    if not claude:
+        raise OSError("claude not found on PATH")
+    try:
+        result = _run([claude, "agents", "--json"])
+    except subprocess.TimeoutExpired as exc:
+        raise OSError(f"claude agents --json timed out after {_TIMEOUT} s") from exc
+    if result.returncode != 0:
+        detail = " ".join((result.stderr or result.stdout or "").split()) or f"exit {result.returncode}"
+        raise OSError(f"claude agents --json failed: {detail}")
+    try:
+        value = json.loads(result.stdout)
+    except ValueError as exc:
+        raise ValueError("claude agents --json did not print JSON") from exc
+    if not isinstance(value, list):
+        raise ValueError("claude agents --json did not print a JSON list")
+    return value
+
+
 def _waits_on(text: str) -> list[dict]:
     try:
         value = json.loads(text)
@@ -932,6 +1388,16 @@ def _parser() -> argparse.ArgumentParser:
     p = command("repo-id", repo=False)
     p.add_argument("--path", default=".", help="a folder inside the checkout (default: current folder)")
 
+    config = sub.add_parser("config").add_subparsers(dest="config_command", required=True, parser_class=_Parser)
+    for name in ("show", "init"):
+        p = command(name, config, repo=False)
+        p.add_argument("--path", default=".", help="the repo root (default: current folder)")
+
+    p = command("session", repo=False)
+    which = p.add_mutually_exclusive_group(required=True)
+    which.add_argument("--session-id", help="the Claude Code sessionId to find")
+    which.add_argument("--name", help="the Claude Code session name to find")
+
     lock = sub.add_parser("lock").add_subparsers(dest="lock_command", required=True, parser_class=_Parser)
     p = command("acquire", lock)
     p.add_argument("--pid", type=int, required=True)
@@ -942,13 +1408,17 @@ def _parser() -> argparse.ArgumentParser:
 
     command("heartbeat")
     command("intake")
+    p = command("watch")
+    p.add_argument("--pid", type=int, required=True, help="the coordinator session pid that holds the lock")
+    p.add_argument("--interval", type=float, default=30.0, help="seconds between cycles (default 30)")
+    p.add_argument("--max-cycles", type=int, help="stop after this many cycles (for tests)")
     command("state")
 
     queue = sub.add_parser("queue").add_subparsers(dest="queue_command", required=True, parser_class=_Parser)
     p = command("add", queue)
     p.add_argument("--pr", type=int, required=True)
     p.add_argument("--head-sha", required=True)
-    p.add_argument("--title", required=True)
+    p.add_argument("--title", help="the PR title (default: read from gh; `PR #<n>` when gh fails)")
     p = command("set", queue)
     p.add_argument("--pr", type=int, required=True)
     p.add_argument("--state", choices=QUEUE_STATES)
@@ -970,6 +1440,12 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument("--run", type=int, help="the deploy run id")
     p.add_argument("--health", choices=DEPLOY_HEALTH)
 
+    p = command("deploy-verify")
+    p.add_argument("--pr", type=int, required=True)
+    p.add_argument("--merge-sha", required=True, help="the full merge commit SHA")
+    p.add_argument("--config-path", required=True, help="the repo root, or its .caddis/coordinator.md")
+    p.add_argument("--docs-only", action="store_true", help="a docs-only merge: D1, D2 and D5 only")
+
     ledger = sub.add_parser("ledger").add_subparsers(dest="ledger_command", required=True, parser_class=_Parser)
     p = command("record", ledger)
     p.add_argument("--what", required=True)
@@ -990,6 +1466,18 @@ def _dispatch(args: argparse.Namespace) -> int:
         rid = repo_id_for(Path(args.path))
         _emit(args, {"repo": rid}, rid)
         return EXIT_OK
+    if args.command == "session":
+        found = session_lookup(_claude_agents(), session_id=args.session_id, name=args.name)
+        _emit(args, found, f"pid {found['pid']} ({found['name']})")
+        return EXIT_OK
+    if args.command == "config":
+        if args.config_command == "init":
+            path = init_config(Path(args.path))
+            _emit(args, {"path": str(path)}, str(path))
+        else:
+            loaded = load_config(Path(args.path))
+            _emit(args, loaded, json.dumps(loaded, indent=2))
+        return EXIT_OK
     rid = args.repo or repo_id_for(Path.cwd())
     _repo_dir(rid)  # refuse a bad id before anything is written
 
@@ -1012,6 +1500,8 @@ def _dispatch(args: argparse.Namespace) -> int:
         heartbeat(rid)
         _emit(args, {"ok": True}, "ok")
         return EXIT_OK
+    if args.command == "watch":
+        return watch(rid, args.pid, args.interval, args.max_cycles)
     if args.command == "intake":
         results = intake(rid, datetime.datetime.now(datetime.timezone.utc), _gh_head_of(rid))
         lines = [f"{r['id']}: {r['result']} {r['reason']}".rstrip() for r in results]
@@ -1030,13 +1520,20 @@ def _dispatch(args: argparse.Namespace) -> int:
         item = queue_next(state)
         _emit(args, {"next": item}, f"PR #{item['pr']}" if item else "none")
         return EXIT_OK
+    if args.command == "deploy-verify":
+        root = _deploy_root(args.config_path)
+        out = deploy_verify(rid, load_config(root), args.pr, args.merge_sha, docs_only=args.docs_only,
+                            runner=_deploy_run, repo_root=root)
+        marks = " ".join(f"{name}={mark}" for name, mark in out["checks"].items())
+        _emit(args, out, f"{out['health']}: {marks} ({out['reason']})")
+        return EXIT_OK if out["health"] == "ok" else EXIT_ERROR
     if args.command == "deploy-check":
         deploy_check_set(rid, args.pr, deploy_run=args.run, health=args.health)
     elif args.command == "ledger":
         ledger_record(rid, what=args.what, decision=args.decision, by=args.by, reason=args.reason,
                       window=args.window, request_id=args.request_id)
     elif args.queue_command == "add":
-        queue_add(rid, args.pr, args.head_sha, args.title)
+        queue_add(rid, args.pr, args.head_sha, args.title if args.title is not None else _gh_title(rid, args.pr))
     elif args.queue_command == "set":
         queue_set(rid, args.pr, state=args.state, head_sha=args.head_sha, why_waiting=args.why_waiting,
                   waits_on=args.waits_on)
@@ -1060,8 +1557,17 @@ def main(argv: list[str] | None = None) -> int:
         args = parser.parse_args(argv)
         if args.command == "deploy-check" and args.run is None and args.health is None:
             parser.error("deploy-check set needs --run or --health")
+        if args.command == "deploy-verify" and not _SHA.fullmatch(args.merge_sha):
+            parser.error("deploy-verify --merge-sha must be a full 40-character SHA")
         if args.command == "lock" and args.lock_command == "acquire" and args.pid <= 0:
             parser.error("lock acquire --pid must be a positive process id")
+        if args.command == "watch":
+            if args.pid <= 0:
+                parser.error("watch --pid must be a positive process id")
+            if not 1 <= args.interval <= 86400:  # also refuses NaN and inf (time.sleep(inf) raises)
+                parser.error("watch --interval must be 1 to 86400 seconds")
+            if args.max_cycles is not None and args.max_cycles <= 0:
+                parser.error("watch --max-cycles must be 1 or more")
     except _UsageError as exc:
         print(f"usage error: {exc}", file=sys.stderr)
         return EXIT_USAGE

package/bundles/antigravity-plugin/scripts/templates/coordinator.md

@@ -0,0 +1,91 @@
+# Coordinator config
+
+This file is the per-repo config for `/caddis:coordinate`. The coordinator session reads the ONE fenced
+`json` block below. The prose around it is for people.
+
+How to fill it:
+
+- Replace every `"<fill: ...>"` string with the real value. The coordinator refuses to start while any
+  `<fill:` string is left (`caddis_coordinate.py config show` lists them).
+- Keep every key. A missing key also stops the coordinator.
+- Put no host names and no secrets here. The production base URL comes from the environment variable that
+  `deploy.base_url_env` names.
+
+What the keys mean:
+
+| Key | Meaning |
+|---|---|
+| `schema` | The config format version. Keep `1`. |
+| `default_branch` | The branch that PRs merge into. |
+| `merge_method` | `squash`, `merge` or `rebase`. Match the repo's branch protection (linear history needs `squash` or `rebase`). |
+| `required_checks` | The required status checks, as branch protection names them. A fallback only: the coordinator reads branch protection first and tells the owner on a mismatch. |
+| `not_required` | Checks that may fail or skip on a PR without blocking the merge. |
+| `docs_only.signal` | The CI job that decides if a change is docs-only (the other required checks then conclude `skipped`). |
+| `docs_only.deploy_check` | The deploy checks for a docs-only merge. A docs-only push deploys nothing. |
+| `main_workflow` | The name of the CI workflow that runs on the default branch. No merge while it runs. |
+| `reviews.count` | How many reviews a PR needs before it is ready. |
+| `reviews.stop_on` | Which review findings stop a merge. `blocking`: only blocking findings. |
+| `peer_ack.warning_min` | Minutes between the merge warning and the merge. |
+| `peer_ack.ack_file` | Where each peer writes its ack: `{head, acked[], at}`. An ack older than 30 minutes does not count. |
+| `deploy.event` | The event that starts the deploy run (for example `push`). |
+| `deploy.jobs` | The number of jobs in the deploy run. |
+| `deploy.tag` | The release tag scheme. With `calver`, the tag must point at the merge SHA. |
+| `deploy.base_url_env` | The environment variable that holds the production base URL on this machine. |
+| `deploy.auth` | How the checks authenticate to production. |
+| `deploy.version_path` | The JSON endpoint whose `sha` field must equal the merge SHA after the deploy. |
+| `deploy.health_path` | The endpoint that must answer 200 after the deploy. |
+| `deploy.never_health_path` | A path that looks healthy even when the API is dead. Never used as a health check. |
+| `deploy.render_check` | How the PR's session checks a served page: 0 console errors and one value checked against its source. |
+| `deploy.wait` | How to wait for the deploy run. No fixed sleep. |
+| `owner_reserved` | Changes that only the owner may approve. |
+| `stall.busy_silent_min` | Minutes a busy session may stay silent before the coordinator asks. |
+| `stall.ready_no_ready_msg_min` | Minutes a green PR may wait for its session's ready message. |
+| `quiet.coordination` | Quiet hours for merges (`none`: no quiet hours). |
+| `quiet.timing_checks` | When timing checks may run. |
+
+```json
+{
+  "schema": 1,
+  "default_branch": "<fill: the branch that PRs merge into, for example main>",
+  "merge_method": "squash",
+  "required_checks": [
+    "<fill: one required status check as branch protection names it, for example ci / lint_and_test; one string per check>"
+  ],
+  "not_required": [
+    "<fill: one check that may fail or skip on a PR, for example notify; one string per check, or an empty list>"
+  ],
+  "docs_only": {
+    "signal": "<fill: name of the CI job that decides if a change is docs-only>",
+    "deploy_check": ["push_run", "health"]
+  },
+  "main_workflow": "<fill: name of the CI workflow that runs on the default branch>",
+  "reviews": {"count": 2, "stop_on": "blocking"},
+  "peer_ack": {
+    "warning_min": 2,
+    "ack_file": "~/.claude/merge-acks/<repo>/pr-<n>.json"
+  },
+  "deploy": {
+    "event": "push",
+    "jobs": "<fill: number of jobs in the deploy run>",
+    "tag": "<fill: release tag scheme, for example calver, or none>",
+    "base_url_env": "<fill: name of the environment variable that holds the production base URL>",
+    "auth": "<fill: how the checks authenticate to production, for example none>",
+    "version_path": "<fill: path of the JSON endpoint whose sha field is the deployed commit>",
+    "health_path": "<fill: path of the endpoint that must answer 200 after the deploy>",
+    "never_health_path": "<fill: path that looks healthy even when the API is dead, or null>",
+    "render_check": "<fill: how the PR's session checks a served page, for example a headless browser>",
+    "wait": "gh run watch"
+  },
+  "owner_reserved": [
+    "schema change or data write on prod",
+    "permission change",
+    "any open blocking review finding",
+    "<fill: a rule the owner reserved by name; one string per rule, or delete this line>"
+  ],
+  "stall": {"busy_silent_min": 45, "ready_no_ready_msg_min": 20},
+  "quiet": {
+    "coordination": "none",
+    "timing_checks": "<fill: when timing checks may run, for example quiet window only>"
+  }
+}
+```

package/bundles/antigravity-plugin/skills/_registry.md

@@ -80,6 +80,7 @@
 | Add Rules | `add-rules/` | Create canonical rules for ANY folder — write <folder>/AGENTS.md (from the folder template) + a <folder>/CLAUDE.md @import shim. For folders the stack-map generator doesn't cover. |
 | Catchup | `catchup/` | Where were we? A quick list of what this session was doing and what is still open |
 | Cloud Phases | `cloud-phases/` | Run plan phases in Claude Code cloud sessions — write one prompt per phase, push, hand out paste lines, then take the PRs back |
+| Coordinate | `coordinate/` | Run this session as the repo's coordinator — one merge queue for all sessions, one merge at a time, a deploy check after each merge, routine approvals in the ledger. |
 | Decide | `decide/` | Record a decision in one step — .caddis/decisions/<date>-<slug>.md |
 | Digress | `digress/` | Park the current workstream on the stack and switch to a new task — without losing the original |
 | Excalidraw Db | `excalidraw-db/` | Turn a SQL artifact into an Excalidraw diagram for a design review / ARB pack / slide — higher-level, drag-the-boxes format |

package/bundles/antigravity-plugin/skills/coordinate/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: coordinate
+description: Run this session as the repo's coordinator — one merge queue for all sessions, one merge at a time, a deploy check after each merge, routine approvals in the ledger.
+---
+
+# /coordinate — the coordinator session for one repo
+
+This session becomes the ONE coordinator of the current repo. It keeps the merge queue, merges one PR at
+a time, checks each deploy and approves routine gates. Other sessions send it messages; they do not merge
+on their own.
+
+The behaviour is in `.caddis/plans/caddis-coordinator.design.md` (owner-approved, 23 Oct 2026). This
+command gives the steps and names the design section for each. When this command and the design differ,
+the design is correct: stop and tell the owner.
+
+Argument: **$ARGUMENTS**
+- `start` (or empty): do **1. Start**, then **2. Merge mode**, then run **3. The loop**.
+- `status`: find `<account>` and `<R>` (steps 1.1 and 1.2), then print `state` (step 1.8) and the
+  `queue next` result. Change nothing.
+- `stop`: do **6. Stop**.
+
+## How to call the script
+
+- Run these commands with the Bash tool: the quoting and the `GH_TOKEN=$(...)` forms are POSIX shell.
+- Every queue, lock and ledger change goes through
+  `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" <subcommand> ... --json`.
+  Never edit `coordinator.json`, the lock file or the ledger by hand.
+- Exit codes: **0** ok; **1** error (one line on stderr); **2** usage error (fix the call); **3** the
+  lock is refused.
+- `<R>` is the repo id, `<P>` is this session's pid, `<N>` is this session's name, `<S>` is this
+  session's id. Step 1 finds them once. Pass `--repo <R>` to every call that takes it.
+- `<account>` is the GitHub account of this repo (step 1.1 finds it first).
+  Put `GH_TOKEN=$(gh auth token -u <account>)` in front of every command that calls GitHub: `gh`,
+  `repo-id`, `ci-watch`, `watch`, `intake`, `queue add` and `deploy-verify`. Never run `gh auth switch`.
+- Free text (`--title`, `--why-waiting`, `--reason`, `--what`): always put free text in single quotes, and
+  write each `'` inside it as `'\''`. Never use double quotes: the shell expands `$` and backticks in them.
+  Example: `--reason 'the owner'\''s words'`.
+- `<owner/name>` is the GitHub repo of `<R>` (`acme__shop` is `acme/shop`).
+
+## 1. Start (design 0.1)
+
+1. Find `<account>`, the GitHub account of this repo: the repo's `AGENTS.md` names it; else ask the
+   owner. Do this first: `repo-id` already calls GitHub.
+2. Find the repo id:
+   ```
+   GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" repo-id --json
+   ```
+   Keep `repo` as `<R>`.
+3. Find `<S>`: the session start output prints `[caddis] this session's id: <id>`. Never guess it. If
+   you cannot find that line, stop and ask the owner for the id.
+4. Find this session's pid and name:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" session --session-id <S> --json
+   ```
+   Keep `pid` as `<P>` and `name` as `<N>`. Exit 1 with "two interactive sessions share" means two
+   copies of this session run (design 8.6): stop, tell the owner both pids, and wait. Any other exit 1:
+   stop and report the line.
+5. Take the lock. This also creates or claims the repo's state:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" lock acquire --repo <R> --pid <P> --session-id <S> --name <N> --json
+   ```
+   Exit 3: another coordinator is live. Stop and tell the owner the holder's name and pid from `holder`.
+6. Read the config:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config show --path <repo root> --json
+   ```
+   Exit 1: stop the start-up and tell the owner the problem (missing keys, `<fill:` placeholders, no
+   file). With no file, offer to write the template:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config init --path <repo root> --json
+   ```
+   Release the lock (section 6 step 2) before you stop.
+7. Compare `required_checks` with branch protection (design 0.1 step 3):
+   `GH_TOKEN=$(gh auth token -u <account>) gh api repos/<owner>/<name>/branches/<default branch>/protection`.
+   On a mismatch, use the branch-protection list and tell the owner. The call can return 404 (this
+   account has no admin rights), and it does not show checks that come from rulesets. Then use the config
+   list and tell the owner.
+8. Read the state:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" state --repo <R> --json
+   ```
+   Also read the coordinator relay, `claude agents --json` (or `ListAgents`) and
+   `caddis_roadmap.py status` (design 0.1 step 4).
+9. Finish the work that a crash left (design 8.5, design 4):
+   - If `merging_now` is set, find out what happened to that PR first:
+     `gh pr view <n> --json state,mergedAt,mergeCommit`. `MERGED`: take `mergeCommit.oid` as the merge
+     SHA and do loop steps 3.15 to 3.19 for it. Not merged: first send the PR's session `hold <PR>` (a
+     `go` from before the restart is void). Then delete the ack file (path in loop step 3.13), run
+     `queue set --repo <R> --pr <n> --state ready --why-waiting 'coordinator restarted; warn again'` and start again from
+     loop step 3.5.
+   - For each PR whose newest `deploy_checks[]` entry has `health: pending`: run `deploy-verify` for it
+     again (loop step 3.17).
+   - The queue is frozen when the newest `deploy_checks` entry overall (the newest `at` of all PRs) has
+     `health: failed`, and no later ledger entry has a `what` that starts with `unfreeze` and
+     `approved_by: owner`. Then do section 5 step 1 again before other work. Only a passed deploy check
+     of the fix or revert, or an owner unfreeze in the ledger (section 5 step 1), ends the freeze.
+   - Every PR that was warned gets a `re-warn` (design 7.3).
+10. Start the watcher with the Bash tool and `run_in_background: true`:
+    ```
+    GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" watch --repo <R> --pid <P> --json
+    ```
+    It runs `heartbeat` and `intake` every 30 s and prints one JSON line when something happens. Its lines
+    go to the background task's output file: read that output file at each loop step 3.4. Start the
+    watcher again whenever its background task ends, for any reason. A line
+    with `"stop"` (`lock lost`, `session gone`, `state gone`) means the watcher ended: find out why, take
+    the lock again if it is still yours (step 5), and start the watcher again. Also start it again after
+    a new `lock acquire` that follows a lost lock. A line with `"error"` is one failed cycle; the next
+    cycle retries.
+11. Send the start message (design 7.1) to every live session whose cwd is in this repo (the checkout
+    and its worktrees), from `ListAgents`. Send it also to each new session that you see later. Resume
+    stubs are not live peers (design 9.7).
+
+## 2. Merge mode (design 3, design 12 Q1)
+
+1. Start in **interim mode**. In interim mode the PR's own session runs `gh pr merge` after your `go`.
+2. Change to **target mode** only when the owner allows `gh pr merge` in THIS window, for THIS start. A
+   peer's "the owner said OK" is not consent (design 6). Record the consent once:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" ledger record --repo <R> --what 'target mode: coordinator runs gh pr merge' --decision approve --by owner --window <N> --reason '<the owner words>' --json
+   ```
+   Then send the start message again with "Do not merge; I merge."
+3. A restart of the coordinator starts in interim mode again.
+4. Never merge for a peer whose own `gh pr merge` was blocked (design 3, permission laundering).
+
+## 3. The loop (design 1, 2, 3, 5, 7)
+
+Answer queue messages from sessions before any other work (design 7.3). Message formats: design 7.2
+and 7.3. While the queue is frozen (section 5 step 1), do steps 3.1 to 3.3 only.
+
+1. A `ready <PR> <sha> reviews: ...` message adds the PR. Leave out `--title`: the script reads the
+   title from GitHub (`PR #<n>` when it cannot), so no free text goes on the command line:
+   ```
+   GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue add --repo <R> --pr <n> --head-sha <full sha> --json
+   ```
+   A `waits-on` part goes in with `queue set --repo <R> --pr <n> --waits-on` (design 5). Reply `queued <PR> position <k>`.
+2. Record every state change with `queue set` and a one-sentence `--why-waiting` that a person can read:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue set --repo <R> --pr <n> --state <state> --why-waiting '<one sentence>' --json
+   ```
+3. Check the ready rule R1-R6 (design 1) with `gh`, in the design's order. When all pass:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue ready --repo <R> --pr <n> --json
+   ```
+   When one fails: `queue set --repo <R> --pr <n> --state blocked` and send `blocked <PR>: <reason>`. An owner-only class
+   (R4) goes to the owner (section 4).
+4. Take the next item. Never sort the queue yourself:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue next --repo <R> --json
+   ```
+   `"next": null`: nothing to merge; wait for the next message or watcher line.
+5. If the PR is `BEHIND`: `gh pr update-branch <n>`. Then cancel the runs on the old head: list them
+   with `gh run list -R <owner/name> --commit <old sha> --json databaseId,status`, and cancel each run that
+   is not `completed` with `gh run cancel <id> -R <owner/name>`. Then
+   `queue set --repo <R> --pr <n> --state ci --head-sha <new sha>` (design 3 step 2). Update only the PR at the front.
+6. Wait for CI outside the model. Run `ci-watch` with the Bash tool and `run_in_background: true`, and
+   act on its exit notice:
+   ```
+   GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --pr <n>
+   ```
+   Act only on `RESULT: pass`. The `HEAD:` line is the `<watched sha>`. Exit 1: CI is red (design 8.1;
+   one re-run for a flake, design 8.2). Exit 3: run `ci-watch` again; if it stays 3, stop and report.
+   Exit 4: a usage error; stop and report.
+7. If the item is in `ci` (after step 3.5 or a new head), check R1 and R2 again at the watched head,
+   then run `queue ready` (step 3.3). Do not warn for an item that is not `ready`.
+8. Check that the default branch is idle (M1): `gh run list -R <owner/name> --branch <default branch> --workflow '<main_workflow>' --json status,databaseId`
+   lists no `in_progress` or `queued` run. If one runs, wait for it with
+   `GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --run <id> --repo <owner/name>`,
+   in the background (`run_in_background: true`). When its `RESULT:` line comes, check M1 again.
+9. Send `merge-warning <PR> <watched sha> in 2 min. Reply ack <PR> <sha> or hold.` to every live peer
+   (design 7.3), and `queue set --repo <R> --pr <n> --state merging`. Send `re-warn <PR> <sha>` after any coordinator
+   restart and after any new head on a warned PR. Old acks do not count.
+10. Collect the acks (M2). Wait the full `peer_ack.warning_min` minutes after the warning, even when every
+    ack comes early. For that wait, run `sleep 120` (`peer_ack.warning_min` x 60 s) with the Bash tool
+    and `run_in_background: true`, or use the Monitor tool, and act on its exit notice; never a
+    foreground sleep. Answer messages while it runs. No ack after 5 min: one nudge. After 10 min: tell
+    the owner. A peer that waits on the owner cannot answer: tell the owner "ack needed from <name>; it
+    waits on you". Do not write the ack file yet (step 3.13).
+11. Check again that the default branch is idle (M1, the same `gh run list` as step 3.8), just before the
+    merge. If a run started, wait for it (step 3.8). If the warning went out more than 30 min ago, warn
+    again (step 3.9).
+12. Read the state again just before the merge, and read the item's `held` again:
+    ```
+    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" state --repo <R> --json
+    ```
+    Then check the PR itself: `gh pr view <n> --json state,headRefOid,mergeStateStatus,mergeCommit`.
+    - `state` is `MERGED` (the PR's session merged it already): take `mergeCommit.oid` as the merge SHA
+      and go straight to step 3.15.
+    - Else `headRefOid` must be the `HEAD:` of the `ci-watch` run that printed `RESULT: pass`, and
+      `mergeStateStatus` must be `CLEAN`.
+    If any check fails, do not merge now: first leave `merging`, then delete the ack file (step 3.13) if
+    it exists, then go back to step 3.4:
+    - `held: true` or a peer `hold`: `queue set --repo <R> --pr <n> --state ready --why-waiting '<who holds it and why>'`.
+    - a new head: `queue set --repo <R> --pr <n> --state ci --head-sha <new sha> --why-waiting 'new head; CI runs again'`.
+    - not `CLEAN`: `queue set --repo <R> --pr <n> --state ci --why-waiting 'merge state <mergeStateStatus>; checks run again'`.
+    If you merge now, decide docs-only (step 3.17 needs it) from evidence only, and record the evidence
+    while the item is still in the queue:
+    `queue set --repo <R> --pr <n> --why-waiting 'merging; docs-only: <yes|no> from <the evidence>'`. The evidence is the
+    `docs_only.signal` job result in the PR's CI run, or the file list from `gh pr view <n> --json files`.
+13. Write the ack file that the merge hook reads. This is the LAST action before `go` (interim mode) or
+    `gh pr merge` (target mode): after the M1 check (step 3.11) and the `held` and PR checks (step 3.12). The
+    path is `~/.claude/merge-acks/<checkout folder name>/pr-<n>.json`. The checkout folder name is the
+    last path part of the first `worktree` line of `git worktree list --porcelain` (the repo's main
+    checkout), NOT the repo id `<R>`. The content is exactly:
+    ```
+    {"pr": <n>, "head": "<full sha>", "acked": [<names>], "skipped_waiting": [<names waiting on the owner>], "at": "<UTC ISO 8601 with Z>"}
+    ```
+    `acked` lists every peer that sent `ack <PR> <sha>` for this head, by its session name. An unnamed
+    peer is listed under the first 8 characters of its session id (the hook uses the same name). A peer
+    that waits on the owner goes under `skipped_waiting`, never under `acked`. Interim mode: also put
+    your own name `<N>` in `acked` (the PR's session runs the merge, and its hook counts you as a peer).
+    Target mode: you run the merge, so `acked` must list the PR's session too. The hook refuses an ack
+    file older than 30 min.
+14. Merge the watched head (design 3 step 6), checked in step 3.12. The watched head is the `HEAD:` of the
+    `caddis_lanes.py ci-watch` run (step 3.6) that printed `RESULT: pass`; never merge without it.
+    Do only the merge or the `go`:
+    - Target mode: `GH_TOKEN=$(gh auth token -u <account>) gh pr merge <n> --<merge_method> --match-head-commit <watched sha>`.
+      The merge SHA is `mergeCommit.oid` from `gh pr view <n> --json state,mergeCommit`.
+    - Interim mode: send `go <PR> <watched sha>`; the PR's session merges with the same command. Then
+      poll with a Bash command in `run_in_background`: `gh pr view <n> --json state,mergeCommit` once a
+      minute, for at most 15 min, until `state` is `MERGED`. Take `mergeCommit.oid` as the merge SHA; the
+      session's `merged` reply only tells you to look. No merge after 15 min: ask the PR's session once.
+      After 5 more min, tell the owner, delete the ack file, and leave `merging` with
+      `queue set --repo <R> --pr <n> --state ready --why-waiting 'go sent; no merge from <session>'`.
+    If `--match-head-commit` fails, the head moved: delete the ack file,
+    `queue set --repo <R> --pr <n> --state ci --head-sha <new sha>`, and go back to step 3.6. Never add the `--admin` flag to
+    a merge.
+15. Record the merge as soon as the merge SHA is known, before any wait. This removes the item and adds
+    a `pending` deploy check:
+    ```
+    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue merged --repo <R> --pr <n> --merge-sha <full merge sha> --json
+    ```
+    Exit 0 with `already recorded` is success (a retry). Then delete the ack file: the item has left
+    `merging`.
+16. Find the push run for the merge SHA, then wait until it ends. Run each wait with the Bash tool and
+    `run_in_background: true`, and act on its exit notice.
+    - Find it once a minute, for at most 10 min:
+      `gh run list -R <owner/name> --branch <default branch> --event push --workflow '<main_workflow>' --json databaseId,headSha`,
+      and match `headSha` to the merge SHA. No push run after 10 min: go to step 3.17 now;
+      `deploy-verify` records D1 failed.
+    - Wait for it:
+      `GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --run <id> --repo <owner/name>`.
+      It prints a `RESULT:` line when the run ends (pass or fail); then go to step 3.17, which reads the
+      result itself. Exit 3: run it again. Exit 4: a usage error; stop and report.
+17. Run the deploy check D1-D5 (design 4). Add `--docs-only` only when the evidence that step 3.12
+    recorded in `--why-waiting` says docs-only: the `docs_only.signal` job result in the PR's CI run, or
+    the file list from `gh pr view <n> --json files`. Never decide it from the title or a session's word.
+    When that evidence is not available (for example after a restart), decide again from
+    `gh pr view <n> --json files`: docs-only only when every changed file ends in `.md` (or is under a docs
+    path that the config's `docs_only` block names). Say in your report that you decided it again. When in
+    doubt, do not pass `--docs-only`.
+    ```
+    GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" deploy-verify --repo <R> --pr <n> --merge-sha <full merge sha> --config-path <repo root> --json
+    ```
+    It records the result. Exit 0 (`health: ok`): pass. Exit 1 with `health: pending`: the run has not
+    ended; wait for it (step 3.16) and call it again. Exit 1 with `health: failed`: section 5 step 1.
+    Exit 1 with no JSON on stdout (an `error:` line on stderr): a usage or state problem, for example a
+    merge SHA that is not the recorded one. Stop and report the line. Exit 2: fix the call.
+18. D6 (render check) comes from the PR's session (`render-check ...`). D7 (a post-deploy data job)
+    is recorded when the job ends:
+    ```
+    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" deploy-check set --repo <R> --pr <n> --health <ok|failed> --json
+    ```
+    A failed D6 or D7: section 5 step 1.
+19. Tell the PR's session and every live peer: `merged <PR> <merge sha>`, then `deployed <PR> ok`. Tell a
+    stacked PR's session to retarget to the default branch (design 3). Go back to step 3.4.
+
+Stalls (design 7.4): one nudge for a busy, silent session that holds a queue item, and for a green,
+`CLEAN` PR with no `ready` message; tell the owner when a waiting session blocks the queue.
+
+## 4. Approvals (design 6)
+
+1. Routine gates are yours. Record each one:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" ledger record --repo <R> --what '<gate>' --decision approve --by coordinator --window <N> --reason '<why it passes>' --json
+   ```
+2. The owner-only list (design 6, plus config `owner_reserved`) goes to the owner. Never approve it
+   yourself. Send it with:
+   ```
+   recommendation: approve | hold
+   reason: <one or two sentences>
+   evidence: <cost estimate | test or CI result | risk | how to undo>
+   ```
+3. A recommendation is never an approval. Only the owner's click in the hub or the owner's own words in
+   this window approve. Record the owner's answer with `ledger record --by owner --window <N>`.
+4. Hotfix marks come only from the owner (design 2). You may recommend one.
+
+## 5. Failures (design 8) and stalls (design 7.4)
+
+1. A failed deploy check (D1-D7, design 4, design 8.4): freeze the queue. Send no merge warnings and
+   no `go`, write no ack file, and do no merges. For an item in `merging`, first run
+   `gh pr view <n> --json state,mergeCommit`. `MERGED`: do step 3.15 (`queue merged`) for it before you
+   freeze, then its deploy check (steps 3.16 and 3.17). Not merged: delete the ack file and move it to
+   `ready`. Set every item's why-waiting with
+   `queue set --repo <R> --pr <n> --why-waiting 'queue frozen: deploy check failed for #<n>'`, tell every live session
+   `frozen: <reason>`, read the per-job conclusions, and send the owner a recommendation (revert or
+   hold). The owner decides a rollback; a rollback is a revert PR through the queue. Record an incident
+   with `/caddis:rca`. Unfreeze only when the fix or revert passes its own deploy check, or the owner
+   says so. Record an owner unfreeze in the ledger (step 1.9 reads it after a restart), then send
+   `unfrozen`:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" ledger record --repo <R> --by owner --what 'unfreeze after #<n>' --decision approve --reason '<owner words>' --window <N> --json
+   ```
+2. CI red (design 8.1): `queue set --repo <R> --pr <n> --state blocked` with the failed job's name. One re-run for a flaky
+   job (`gh run rerun <id> --failed`, design 8.2).
+3. A run stuck or a runner suspected (design 8.3): check
+   `https://www.githubstatus.com/api/v2/summary.json` first. During a GitHub incident, wait. Never
+   restart a runner or a service.
+4. Duplicate copies (design 8.6) show as `session` exit 1. Tell the owner the other pid. Stop a process
+   only when the owner asks in this window, and record that in the ledger.
+5. A single exit 1 from `heartbeat` or `intake` (a watcher `"error"` line) can be transient. Act only
+   when it repeats.
+6. Pilot notes. D3 runs `git fetch --tags`, which can need git credentials in this session; then D3
+   fails. A short gh or curl failure in D1 or D5 records `failed` and freezes the queue. That is the
+   safe direction: the owner checks the deploy and unfreezes (step 5.1).
+
+## 6. Stop
+
+1. Stop the watcher: stop its background Bash task.
+2. Release the lock:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" lock release --repo <R> --pid <P> --json
+   ```
+3. Send every live session on the repo: `coordinator <N> stopped for <repo>. Do not merge until a coordinator is live again.`
+
+## 7. Rules that never bend
+
+- Merge only on `ci-watch` `RESULT: pass` at the watched head, with `--match-head-commit <full sha>`.
+  Never merge while a default-branch CI run is in progress.
+- Never write `coordinator.json` by hand; `lock acquire` creates or claims the state. Exit 3 means
+  stop. Always pass `--repo <R>`.
+- Use `queue next`; never sort the queue yourself. Read `held` again just before a merge.
+- Write the ack file last, just before `go` or `gh pr merge`. Delete it when the item leaves `merging`.
+- Free text goes in single quotes. Long waits run in the background, never a foreground sleep.
+- `queue merged` exit 0 `already recorded` is success.
+- Liveness is the lock file and `heartbeat_at`, not a peer's word.
+- Owner-only approvals go to the owner. Never self-approve them.
+- No stress tests and no load tests.
+- `GH_TOKEN=$(gh auth token -u <account>)` per repo account. Never `gh auth switch`.
+- Never add the `--admin` flag to a merge. Never force push. Never restart services.

package/bundles/manifest.json

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

package/package.json

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