@caddis/cli 0.4.72 → 0.4.73

package/bundles/antigravity-plugin/plugin.json

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

@@ -23,12 +23,12 @@ from collections.abc import Callable
 from pathlib import Path
 
 try:
-    from caddis_file_lock import atomic_write, locked_path, retry_denied
+    from caddis_file_lock import _try_lock, _unlock, atomic_write, locked_path, retry_denied
 except ModuleNotFoundError as exc:
     if exc.name != "caddis_file_lock":
         raise
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
-    from caddis_file_lock import atomic_write, locked_path, retry_denied
+    from caddis_file_lock import _try_lock, _unlock, atomic_write, locked_path, retry_denied
 
 
 _TIMEOUT = 10
@@ -132,6 +132,14 @@ def _lock_path(rid: str) -> Path:
     return _repo_dir(rid) / "coordinator.lock.json"
 
 
+def _watcher_lock_path(rid: str) -> Path:
+    return _repo_dir(rid) / "watcher.lock"
+
+
+def _watcher_stop_path(rid: str) -> Path:
+    return _repo_dir(rid) / "watcher.stop"
+
+
 def read_state(rid: str) -> dict | None:
     """Return the last good parse of `coordinator.json`; None when it is missing or was never good.
 
@@ -367,6 +375,17 @@ def acquire_lock(rid: str, pid: int, session_id: str, name: str) -> tuple[bool,
         return True, None
 
 
+def lock_holder(rid: str) -> dict | None:
+    """Return the lock holder with its `alive` flag, or None when no holder. Never takes or changes the lock.
+
+    Raise OSError when the lock file cannot be read (the caller fails closed)."""
+    holder = _read_holder(_lock_path(rid))
+    if holder is None:
+        return None
+    return {"pid": holder["pid"], "sessionId": holder.get("sessionId"), "name": holder.get("name"),
+            "started_at": holder.get("started_at"), "alive": _holder_alive(holder)}
+
+
 def release_lock(rid: str, pid: int) -> None:
     """Remove the lock if `pid` holds it; do nothing otherwise."""
     with locked_path(_lock_path(rid)) as path:
@@ -943,6 +962,7 @@ def session_lookup(sessions: list[dict], *, session_id: str | None = None, name:
 
 CONFIG_KEYS = ("schema", "default_branch", "merge_method", "required_checks", "not_required", "docs_only",
                "main_workflow", "reviews", "peer_ack", "deploy", "owner_reserved", "stall", "quiet")
+OPTIONAL_CONFIG_KEYS = ("relay",)  # the coordinator's own relay: `.caddis/relay/<relay>.md`
 CONFIG_SCHEMA = 1
 _PLACEHOLDER = "<fill:"
 _FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)")  # a Markdown code fence and its info string
@@ -998,7 +1018,8 @@ 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."""
+    `schema` is not 1, a value is still a `<fill: ...>` placeholder, or the optional `relay` is not a plain
+    workstream name (`caddis_workstreams.is_plain_name`: lower case `a-z0-9_-`, no Windows device name)."""
     path = config_path(repo_root)
     try:
         text = path.read_text(encoding="utf-8")
@@ -1016,9 +1037,24 @@ def load_config(repo_root: Path) -> dict:
     unfilled = _placeholders(config)
     if unfilled:
         raise ValueError(f"the config still has {_PLACEHOLDER} placeholders at: {', '.join(unfilled)}")
+    if "relay" in config and not _plain_workstream_name(config["relay"]):
+        raise ValueError(f"the config relay must be a plain workstream name such as coordinator, "
+                         f"not {config['relay']!r}")
     return config
 
 
+def _plain_workstream_name(value: object) -> bool:
+    """The relay name rule of `caddis_workstreams` (one rule, so a relay that loads here can also be read there)."""
+    try:
+        import caddis_workstreams
+    except ModuleNotFoundError as exc:
+        if exc.name != "caddis_workstreams":
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import caddis_workstreams
+    return caddis_workstreams.is_plain_name(value)
+
+
 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)
@@ -1078,10 +1114,79 @@ def watch_cycle(rid: str, pid: int, now: datetime.datetime, head_of: Callable[[i
     return {"stop": None, "results": results, "error": None}
 
 
-def watch(rid: str, pid: int, interval: float, max_cycles: int | None = None) -> int:
+_TAKEOVER_MAX_S = 150.0  # the longest a `--takeover` waits for the old watcher
+_TAKEOVER_POLL_S = 0.2
+
+
+def _print_line(value: dict) -> None:
+    print(json.dumps(value, separators=(",", ":")), flush=True)
+
+
+def _takeover_wait(interval: float) -> float:
+    """The old watcher checks the stop file right after each sleep, and one cycle can run long (gh calls): wait one
+    interval plus 30 s, at most `_TAKEOVER_MAX_S`."""
+    return min(interval + 30, _TAKEOVER_MAX_S)
+
+
+def _remove_stop_file(rid: str) -> None:
+    retry_denied(lambda: _watcher_stop_path(rid).unlink(missing_ok=True))
+
+
+def _remove_own_stop_file(rid: str) -> None:
+    """Remove the stop file only when this process wrote it: a newer takeover's request stays."""
+    try:
+        owner = json.loads(_watcher_stop_path(rid).read_text(encoding="utf-8")).get("pid")
+    except (OSError, ValueError, AttributeError):
+        return
+    if owner == os.getpid():
+        _remove_stop_file(rid)
+
+
+def watch(rid: str, pid: int, interval: float, max_cycles: int | None = None, takeover: bool = False) -> 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."""
+    repeated error. Return 0 on a stop or after `max_cycles` cycles.
+
+    One watcher per repo: the loop holds the OS lock on `<hub>/repos/<rid>/watcher.lock` for its whole life (the OS
+    frees it when the process dies). When another watcher holds it:
+    - without `takeover`, print `{"stop": "another watcher is running"}` and return 0 at once;
+    - with `takeover`, write `<hub>/repos/<rid>/watcher.stop` and wait (`_takeover_wait`) for the lock. The old
+      watcher sees the stop file right after its next sleep, prints `{"stop": "takeover requested"}` and ends.
+      A `finally` removes this process's own stop file (on success, timeout or an exception; a newer takeover's
+      file stays). When the lock does not come in time, print `{"stop": "old watcher did not stop"}` and
+      return 1. After a `/clear` the old watcher runs on in the same process, but its output belongs to the old
+      conversation: takeover gives the new conversation a watcher whose output it can read.
+    The watcher that gets the lock removes any stop file before its first cycle. When the repo folder does not
+    exist, no lock or stop file is made: the first cycle then stops (it never recreates the folder)."""
+    path = _watcher_lock_path(rid)
+    if not path.parent.is_dir():
+        return _watch_loop(rid, pid, interval, max_cycles)
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    with os.fdopen(os.open(path, flags, 0o666), "r+b") as handle:
+        held = _try_lock(handle)
+        if not held and not takeover:
+            _print_line({"stop": "another watcher is running"})
+            return EXIT_OK
+        if not held:
+            try:
+                atomic_write(_watcher_stop_path(rid), json.dumps({"pid": os.getpid(), "at": _now()}) + "\n")
+                deadline = time.monotonic() + _takeover_wait(interval)
+                while not held and time.monotonic() < deadline:
+                    time.sleep(_TAKEOVER_POLL_S)
+                    held = _try_lock(handle)
+            finally:  # on success, on timeout and on an exception: never leave this process's request behind
+                _remove_own_stop_file(rid)
+            if not held:
+                _print_line({"stop": "old watcher did not stop"})
+                return EXIT_ERROR
+        try:
+            _remove_stop_file(rid)
+            return _watch_loop(rid, pid, interval, max_cycles)
+        finally:
+            _unlock(handle)
+
+
+def _watch_loop(rid: str, pid: int, interval: float, max_cycles: int | None) -> int:
     head_of = _gh_head_of(rid)
     cycles = 0
     last_error: str | None = None
@@ -1098,6 +1203,9 @@ def watch(rid: str, pid: int, interval: float, max_cycles: int | None = None) ->
             if max_cycles is not None and cycles >= max_cycles:
                 return EXIT_OK
             time.sleep(interval)
+            if _watcher_stop_path(rid).exists():  # right after the sleep: a newer watcher asked for the lock
+                _print_line({"stop": "takeover requested"})
+                return EXIT_OK
     except KeyboardInterrupt:
         return EXIT_OK
 
@@ -1405,6 +1513,7 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument("--name", required=True)
     p = command("release", lock)
     p.add_argument("--pid", type=int, required=True)
+    command("holder", lock)
 
     command("heartbeat")
     command("intake")
@@ -1412,6 +1521,8 @@ def _parser() -> argparse.ArgumentParser:
     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)")
+    p.add_argument("--takeover", action="store_true",
+                   help="ask a running watcher of this repo to stop, then take its place (after a /clear)")
     command("state")
 
     queue = sub.add_parser("queue").add_subparsers(dest="queue_command", required=True, parser_class=_Parser)
@@ -1491,6 +1602,12 @@ def _dispatch(args: argparse.Namespace) -> int:
             _claim_state(rid, {"name": args.name, "sessionId": args.session_id, "pid": args.pid})
             _emit(args, {"acquired": True, "holder": None}, "acquired")
             return EXIT_OK
+        if args.lock_command == "holder":
+            holder = lock_holder(rid)
+            _emit(args, holder or {"holder": None}, "no holder" if holder is None else
+                  f"pid {holder['pid']} ({holder['name']}, session {holder['sessionId']}, "
+                  f"{'alive' if holder['alive'] else 'not alive'})")
+            return EXIT_OK
         release_lock(rid, args.pid)
         _emit(args, {"released": True}, "released")
         return EXIT_OK
@@ -1501,7 +1618,7 @@ def _dispatch(args: argparse.Namespace) -> int:
         _emit(args, {"ok": True}, "ok")
         return EXIT_OK
     if args.command == "watch":
-        return watch(rid, args.pid, args.interval, args.max_cycles)
+        return watch(rid, args.pid, args.interval, args.max_cycles, takeover=args.takeover)
     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]

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

@@ -482,6 +482,17 @@ def render_resume(session: str, session_id: str, workstream: str, prompt: str, r
             f"{_fenced(shown)}\n{start}\n")
 
 
+def render_coordinator_resume(session: str, session_id: str, workstream: str) -> str:
+    """The resume block for the repo's coordinator: three lines to type, no prompt and no start line.
+
+    `/caddis:coordinate start` reads the coordinator's relay and tasks itself, so a pasted prompt would only race it."""
+    return (f"=== RESUME ===\nSession: {session} ({session_id})\nWorkstream: {workstream}\n"
+            "This session is the repo's coordinator. To resume, type these three lines in this window, one at a time:\n"
+            "/clear\n/rename coordinator\n/caddis:coordinate start\n"
+            f"Do not paste a resume prompt; /caddis:coordinate start reads .caddis/relay/{workstream}.md "
+            "and its tasks itself.\n")
+
+
 # ---- CLI --------------------------------------------------------------------------------------
 
 def _load_acks(fleet_dir: Path) -> list[Ack]:
@@ -491,6 +502,28 @@ def _load_acks(fleet_dir: Path) -> list[Ack]:
     return [parse_ack(p.read_text(encoding="utf-8")) for p in sorted(acks_dir.glob("*.md"))]
 
 
+def _coordinator_relay_problem(root: Path, name: str) -> str | None:
+    """None when `<root>/.caddis/coordinator.md` loads and its `relay` is `name`, else one line that says why not.
+
+    The coordinator block says `/caddis:coordinate start` reads `.caddis/relay/<name>.md` itself; start reads the
+    config's `relay`, so the block is true only when the two are the same name."""
+    try:
+        import caddis_coordinate
+    except ModuleNotFoundError as exc:
+        if exc.name != "caddis_coordinate":
+            raise
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import caddis_coordinate
+    try:
+        relay = caddis_coordinate.load_config(root).get("relay")
+    except (OSError, ValueError) as exc:  # FileNotFoundError is an OSError
+        return f"--coordinator needs a valid .caddis/coordinator.md with relay {name!r}: {' '.join(str(exc).split())}"
+    if relay != name:
+        return (f"--coordinator: --name {name!r} is not the coordinator config relay {relay!r}"
+                if relay else f"--coordinator: .caddis/coordinator.md has no relay (needs relay {name!r})")
+    return None
+
+
 def _resume_block_cli(args: argparse.Namespace) -> int:
     try:
         import caddis_workstreams
@@ -500,15 +533,23 @@ def _resume_block_cli(args: argparse.Namespace) -> int:
         sys.path.insert(0, str(Path(__file__).resolve().parent))
         import caddis_workstreams
     root = args.root.resolve()
+    if args.coordinator:
+        problem = _coordinator_relay_problem(root, args.name)
+        if problem:
+            sys.stderr.write(f"resume-block failed: {problem}\n")
+            return caddis_exit.BLOCKED
     try:
         text, digest = caddis_workstreams.read_relay(root, args.name)
         if digest is None:
             raise ResumeError(f"relay {args.name!r} not found")
-        prompt = resume_prompt(text)
+        prompt = "" if args.coordinator else resume_prompt(text)
     except (ValueError, OSError) as exc:  # ResumeError is a ValueError; a bad relay name is one too
         sys.stderr.write(f"resume-block failed: {exc}\n")
         return caddis_exit.BLOCKED
     session, known = session_name(args.session_id, root)
+    if args.coordinator:
+        print(render_coordinator_resume(session, args.session_id, args.name), end="")
+        return caddis_exit.CLEAN
     role = args.role or (role_of(session) if known else args.name)
     if not _SAFE_NAME.match(role):  # the role goes unquoted into the start line
         sys.stderr.write(f"resume-block failed: bad role {role!r}\n")
@@ -553,7 +594,11 @@ def main(argv: list[str] | None = None) -> int:
     p.add_argument("--root", default=".", type=Path)
     p.add_argument("--role", help="role for the new session's name (default: the session name's role, else the relay name)")
     p.add_argument("--fleet", action="store_true", help="fleet close: print no start line (the restart sheet has it)")
+    p.add_argument("--coordinator", action="store_true",
+                   help="this session holds the repo's coordinator lock: print the three restart lines, no prompt")
     args = parser.parse_args(argv)
+    if args.cmd == "resume-block" and args.coordinator and args.role:
+        parser.error("resume-block: --role cannot go with --coordinator (the coordinator keeps its name)")
 
     if args.cmd == "role-of":
         print(role_of(args.name))

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

@@ -46,6 +46,15 @@ def _name(value: str) -> str:
     return value
 
 
+def is_plain_name(value: object) -> bool:
+    """True for a plain workstream name as typed (no lower-casing, no `branch.` namespace), e.g. `coordinator`."""
+    try:
+        _name(value)  # type: ignore[arg-type]
+    except ValueError:
+        return False
+    return bool(_PLAIN_NAME.fullmatch(value))  # type: ignore[arg-type]
+
+
 def _plain_name(value: str) -> str:
     if not isinstance(value, str):
         raise TypeError("plan or suggestion must be text")

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

@@ -7,7 +7,8 @@ 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.
+- Keep every key. A missing key also stops the coordinator. Only `relay` is optional: delete its line if the
+  coordinator has no relay.
 - Put no host names and no secrets here. The production base URL comes from the environment variable that
   `deploy.base_url_env` names.
 
@@ -42,6 +43,7 @@ What the keys mean:
 | `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. |
+| `relay` | The workstream name of the coordinator's relay (optional; the coordinator reads `.caddis/relay/<relay>.md` and its tasks file at start). |
 
 ```json
 {
@@ -86,6 +88,7 @@ What the keys mean:
   "quiet": {
     "coordination": "none",
     "timing_checks": "<fill: when timing checks may run, for example quiet window only>"
-  }
+  },
+  "relay": "<fill: workstream name of the coordinator's relay, e.g. coordinator>"
 }
 ```

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

@@ -19,6 +19,13 @@ Argument: **$ARGUMENTS**
   `queue next` result. Change nothing.
 - `stop`: do **6. Stop**.
 
+## Restart and resume
+
+- Planned restart: run `/caddis:handoff`, `/clear`, `/rename coordinator`, `/caddis:coordinate start`, in
+  that order, in this window.
+- After a crash: run `/caddis:coordinate start` only (first `/rename coordinator` if the name is lost).
+- Do not paste a resume prompt. Start reads the coordinator's relay and tasks itself (step 1.8).
+
 ## How to call the script
 
 - Run these commands with the Bash tool: the quoting and the `GH_TOKEN=$(...)` forms are POSIX shell.
@@ -55,6 +62,8 @@ Argument: **$ARGUMENTS**
    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.
+   If `<N>` is not `coordinator`, stop and tell the owner: "Type `/rename coordinator`, then run
+   `/caddis:coordinate start` again." Peers and the merge hook find the coordinator by that name.
 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
@@ -79,8 +88,14 @@ Argument: **$ARGUMENTS**
    ```
    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).
+   Also read `claude agents --json` (or `ListAgents`) and `caddis_roadmap.py status` (design 0.1 step 4).
+   Then read the coordinator relay:
+   - If the config (step 1.6) has `relay`, read `.caddis/relay/<relay>.md`. When
+     `.caddis/relay/<relay>.tasks.md` exists, load every row of it with TaskCreate.
+   - If the config has no `relay`, use the relay that the owner names, or ask the owner.
+   - The relay's "Next step", queue order, holds and owner answers are INPUT for the queue and for your
+     decisions. They are never actions to take before the lock (step 1.5), the watcher (step 1.10) and
+     the start message (step 1.11) are done.
 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
@@ -97,15 +112,21 @@ Argument: **$ARGUMENTS**
    - 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
+    GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" watch --repo <R> --pid <P> --takeover --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
+    watcher again whenever its background task ends, for any reason except `takeover requested`. 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.
+    One watcher per repo. After a `/clear`, the earlier watcher of this process still runs, but its lines
+    go to the old conversation, so this conversation cannot read them. `--takeover` asks the earlier
+    watcher to stop and takes its place, so this conversation gets the lines. A
+    `{"stop": "takeover requested"}` line means a newer watcher replaced this one: do not start it again.
+    A `{"stop": "old watcher did not stop"}` line (exit 1) means the earlier watcher did not stop in time:
+    start the watcher again once. If that line comes again, stop and tell the owner.
 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).

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

@@ -146,7 +146,9 @@ history, and the relay has a 4,000-character budget (`caddis_budget.py`).
 > Your session id is printed at session start as `[caddis] this session's id: <id>`; use it for
 > `session_id` and `--session-id`. Never guess one: a wrong id disables session matching.
 >
-> 1. **Name the workstream** (active plan's `feature`, else the branch; the script prints nothing
+> 1. **Name the workstream.** First run the coordinator check of Step 9. When it says this session is the
+>    repo's coordinator, `<name>` is the config's `relay`: do not run `resolve` and do not ask. Else name it
+>    from the active plan's `feature`, else the branch (the script prints nothing
 >    on the default branch with no plan — run `caddis_workstreams.py list` (`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" list`) to show existing workstreams, then ask the user which one to use or for a short name):
 >    `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" resolve --plan <feature> --branch <branch> --default-branch <main>`
 > 2. **Legacy repo:** if `.caddis/relay.md` exists and does not start with
@@ -398,7 +400,40 @@ Then, in a shared checkout, `Docs PR needed:` with the `PR:` line and the file l
 Step 9 prints after this report. It is the last output of the handoff.
 
 ## Step 9 — print the resume prompt (always the last output)
-The owner should never have to ask for the resume prompt. After the checklist report, run:
+The owner should never have to ask for the resume prompt. After the checklist report, check for a
+coordinator first.
+
+**Coordinator check.** Step 3, point 1 also uses this check. When the repo has `.caddis/coordinator.md`,
+find out if this session is the repo's coordinator:
+1. Read the config. It must have `relay`:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config show --path . --json
+   ```
+   Exit 1, or no `relay`: this session is not treated as the coordinator here. Use the normal block.
+2. Find the repo id `<R>` (`<account>` is the repo's GitHub account, from the repo's `AGENTS.md`):
+   ```
+   GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" repo-id --json
+   ```
+   Keep `repo` as `<R>`.
+3. Find this session's pid. Keep `pid`:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" session --session-id <session-id> --json
+   ```
+4. Read the lock holder. It never takes or changes the lock:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" lock holder --repo <R> --json
+   ```
+5. This session is the coordinator when the holder's `sessionId` is this session's id, OR the holder's `pid`
+   is this session's `pid` (the same coordinator process, for example after a `/clear` that never ran start).
+
+When this session is the coordinator, `<name>` is the config's `relay`, and you add `--coordinator` to the
+`resume-block` call below. The block then prints only `/clear`, `/rename coordinator` and
+`/caddis:coordinate start`, and no resume prompt: `/caddis:coordinate start` reads the relay and its tasks
+itself. `resume-block --coordinator` refuses (exit 1) a `--name` that is not the config's `relay`. In all
+other cases (no `.caddis/coordinator.md`, no `relay`, `{"holder": null}`, another holder, an exit 1), run
+`resume-block` as written.
+
+Then run:
 ```
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_fleet.py" resume-block --name <name> --session-id <session-id> --root .
 ```

package/bundles/manifest.json

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

package/package.json

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