@caddis/cli 0.4.74 → 0.4.75

package/bundles/antigravity-plugin/plugin.json

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

@@ -962,7 +962,10 @@ 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`
+OPTIONAL_CONFIG_KEYS = ("relay", "start_mode")  # relay: `.caddis/relay/<relay>.md`; start_mode: see START_MODES
+# The merge mode a start begins in. "target" in the reviewed, merged config is the owner's standing consent
+# for the coordinator to run `gh pr merge` (command section 2). Missing means "interim".
+START_MODES = ("interim", "target")
 CONFIG_SCHEMA = 1
 _PLACEHOLDER = "<fill:"
 _FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})[ \t]*([^\s`]*)")  # a Markdown code fence and its info string
@@ -1018,8 +1021,9 @@ 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, 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)."""
+    `schema` is not 1, a value is still a `<fill: ...>` placeholder, the optional `relay` is not a plain
+    workstream name (`caddis_workstreams.is_plain_name`: lower case `a-z0-9_-`, no Windows device name), or the
+    optional `start_mode` is not one of START_MODES."""
     path = config_path(repo_root)
     try:
         text = path.read_text(encoding="utf-8")
@@ -1040,9 +1044,92 @@ def load_config(repo_root: Path) -> dict:
     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}")
+    if "start_mode" in config and config["start_mode"] not in START_MODES:
+        raise ValueError(f"the config start_mode must be one of {', '.join(START_MODES)}, "
+                         f"not {config['start_mode']!r}")
     return config
 
 
+_CONFIG_REL = ".caddis/coordinator.md"
+
+
+def _start_mode_at(repo_root: Path, rev: str) -> str | None:
+    """`start_mode` in the config at `rev`: a mode, None (no file or no key) or "invalid"."""
+    shown = _run(["git", "-C", str(repo_root), "show", f"{rev}:{_CONFIG_REL}"])
+    if shown.returncode != 0:
+        return None
+    try:
+        block = _config_block(shown.stdout)
+    except ValueError:
+        return "invalid"
+    if not isinstance(block, dict):
+        return "invalid"
+    if "start_mode" not in block:
+        return None
+    return block["start_mode"] if block["start_mode"] in START_MODES else "invalid"
+
+
+def _origin_default_branch(repo_root: Path) -> str | None:
+    """The default branch from `refs/remotes/origin/HEAD`, never from the work tree (review, 24 Oct 2026)."""
+    out = _run(["git", "-C", str(repo_root), "symbolic-ref", "--short", "refs/remotes/origin/HEAD"])
+    ref = out.stdout.strip() if out.returncode == 0 else ""
+    return ref[len("origin/"):] if ref.startswith("origin/") and len(ref) > len("origin/") else None
+
+
+def _set_target_commit(repo_root: Path, ref: str) -> tuple[str | None, str | None]:
+    """The commit on `ref` where `start_mode` last became "target" (newest first: the oldest commit of the newest
+    unbroken run of target versions). The ledger cites it as the owner's consent."""
+    out = _run(["git", "-C", str(repo_root), "log", "--format=%H%x09%s", ref, "--", _CONFIG_REL])
+    if out.returncode != 0:
+        return None, None
+    found: tuple[str | None, str | None] = (None, None)
+    for line in out.stdout.splitlines():
+        sha, _, subject = line.partition("\t")
+        if _start_mode_at(repo_root, sha) != "target":
+            break
+        found = (sha, subject)
+    return found
+
+
+def config_mode(repo_root: Path) -> dict:
+    """The merge mode a start begins in. Target only when origin's default branch AND the work tree both say
+    `"start_mode": "target"`: the work tree of a shared checkout can hold an uncommitted edit that no owner
+    approved (review, 24 Oct 2026). The branch comes from `origin/HEAD`, not from the work-tree config; a work
+    tree whose `default_branch` differs is a mismatch. Returns mode, work_tree, origin, mismatch, set_by (the
+    commit that set target) and set_by_subject. Fetch first; a stale origin ref gives a stale answer."""
+    work = load_config(repo_root)
+    branch = _origin_default_branch(repo_root)
+    origin = _start_mode_at(repo_root, f"origin/{branch}") if branch else "invalid"
+    work_mode = work.get("start_mode")
+    set_by = set_by_subject = None
+    if origin == "target":
+        set_by, set_by_subject = _set_target_commit(repo_root, f"origin/{branch}")
+
+    def effective(value: str | None) -> str:  # missing means interim
+        return value or "interim"
+    mismatch = (origin == "invalid" or branch != work["default_branch"]
+                or effective(work_mode) != effective(origin))
+    mode = "target" if not mismatch and effective(origin) == "target" else "interim"
+    return {"mode": mode, "work_tree": work_mode, "origin": origin, "mismatch": mismatch,
+            "set_by": set_by, "set_by_subject": set_by_subject}
+
+
+def config_changed(diff: str) -> bool:
+    """True when a unified diff touches .caddis/coordinator.md in any way: add, delete, rename to or from it,
+    edit, binary or mode-only change. That file holds the coordinator's own rules (start_mode, required checks,
+    owner_reserved), so such a PR is owner-only (R4) in every mode. File-level on purpose: a text match on keys
+    can be dodged with JSON escapes (review, 24 Oct 2026)."""
+    marks = (f"+++ b/{_CONFIG_REL}", f"--- a/{_CONFIG_REL}", f"rename from {_CONFIG_REL}", f"rename to {_CONFIG_REL}",
+             f"copy from {_CONFIG_REL}", f"copy to {_CONFIG_REL}")
+    for line in diff.splitlines():
+        if line in marks:
+            return True
+        if line.startswith("diff --git ") and (line.startswith(f"diff --git a/{_CONFIG_REL} ")
+                                               or line.endswith(f" b/{_CONFIG_REL}")):
+            return True
+    return False
+
+
 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:
@@ -1497,9 +1584,12 @@ def _parser() -> argparse.ArgumentParser:
     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"):
+    for name in ("show", "init", "mode"):
         p = command(name, config, repo=False)
         p.add_argument("--path", default=".", help="the repo root (default: current folder)")
+    p = command("pr-check", config, repo=False)
+    p.add_argument("--pr", type=int, required=True, help="the PR whose diff to check (`gh pr diff`)")
+    p.add_argument("--gh-repo", help="owner/name for `gh pr diff -R` (default: the current folder's repo)")
 
     p = command("session", repo=False)
     which = p.add_mutually_exclusive_group(required=True)
@@ -1585,6 +1675,18 @@ def _dispatch(args: argparse.Namespace) -> int:
         if args.config_command == "init":
             path = init_config(Path(args.path))
             _emit(args, {"path": str(path)}, str(path))
+        elif args.config_command == "mode":
+            got = config_mode(Path(args.path))
+            _emit(args, got, got["mode"] + (" (work tree and origin differ)" if got["mismatch"] else ""))
+        elif args.config_command == "pr-check":
+            cmd = ["gh", "pr", "diff", str(args.pr)] + (["-R", args.gh_repo] if args.gh_repo else [])
+            out = _run(cmd)
+            if out.returncode != 0:
+                raise ValueError(f"gh pr diff {args.pr} failed: {out.stderr.strip()[:200]}")
+            changed = config_changed(out.stdout)
+            _emit(args, {"pr": args.pr, "changes_config": changed},
+                  "owner-only: the PR changes .caddis/coordinator.md" if changed else "no coordinator config change")
+            return EXIT_LOCK_REFUSED if changed else EXIT_OK
         else:
             loaded = load_config(Path(args.path))
             _emit(args, loaded, json.dumps(loaded, indent=2))

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

@@ -7,8 +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. Only `relay` is optional: delete its line if the
-  coordinator has no relay.
+- Keep every key. A missing key also stops the coordinator. Only `relay` and `start_mode` are optional: delete
+  the `relay` line if the coordinator has no relay. Without `start_mode`, every start is in interim mode.
 - Put no host names and no secrets here. The production base URL comes from the environment variable that
   `deploy.base_url_env` names.
 
@@ -44,6 +44,7 @@ What the keys mean:
 | `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). |
+| `start_mode` | The merge mode each start begins in (optional): `interim` (the PR's session merges after `go`) or `target` (the coordinator runs `gh pr merge`). `target` here is the owner's standing consent, so set it only in a PR the owner approves. Missing means `interim`. |
 
 ```json
 {
@@ -89,6 +90,7 @@ What the keys mean:
     "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>"
+  "relay": "<fill: workstream name of the coordinator's relay, e.g. coordinator>",
+  "start_mode": "interim"
 }
 ```

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

@@ -127,21 +127,45 @@ Argument: **$ARGUMENTS**
     `{"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
+11. Decide the merge mode first (section 2, step 1: with `"start_mode": "target"`, record the ledger line
+    and say "Do not merge; I merge." in this message). Then 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:
+1. Start in the config's `start_mode`; without `start_mode`, interim mode. In **interim mode** the PR's own
+   session runs `gh pr merge` after your `go`. In **target mode** you run `gh pr merge` yourself. Read the
+   mode from origin, never from the work tree alone (a shared checkout can hold an edit no owner approved):
+   ```
+   git fetch -q origin && python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config mode --path . --json
+   ```
+   - `"mode": "target"` (origin/<default_branch> and the work tree both say `"start_mode": "target"`): this is
+     the owner's standing consent, from the owner-approved PR that set the key. Record it once per start,
+     before the start message, with the commit that set it (`set_by`, `set_by_subject`):
+     ```
+     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 'start_mode target set by <set_by> (<set_by_subject>)' --json
+     ```
+     Then the start message says "Do not merge; I merge."
+   - `"mismatch": true`: start in interim mode and tell the owner. Quote `work_tree` and `origin`. A mismatch
+     also means `refs/remotes/origin/HEAD` is missing (`git remote set-head origin --auto` sets it) or the work
+     tree's `default_branch` is not origin's default branch.
+2. Without `"start_mode": "target"`, 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), and a peer cannot
+   change `start_mode`. 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 owner can step a start down to interim mode in THIS window at any time ("interim mode"). Record it
+   with `--decision decline`, and send the start message again without "I merge".
+4. A restart starts in the config's `start_mode` again.
+5. A PR that changes `.caddis/coordinator.md` (any key: `start_mode`, required checks, `owner_reserved`) is
+   owner-only (R4), in every mode: never merge it and never send `go` for it. The owner merges it, or approves it
+   by name in THIS window (the file holds your own rules). Loop step 3.3 checks it in code with `config pr-check`.
+6. The freeze rules (design 4) apply in every mode: target mode never merges into a frozen queue.
+7. 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)
 
@@ -158,7 +182,13 @@ and 7.3. While the queue is frozen (section 5 step 1), do steps 3.1 to 3.3 only.
    ```
    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:
+3. Check the ready rule R1-R6 (design 1) with `gh`, in the design's order. For R4, also run this. Exit 3
+   means the PR changes `.caddis/coordinator.md`, so it is owner-only (section 2, step 5). Any other non-zero
+   exit (for example `gh pr diff` refused a very large diff) means not ready: block the PR and tell the owner:
+   ```
+   GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config pr-check --pr <n> --gh-repo <owner/name> --json
+   ```
+   When all pass:
    ```
    python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" queue ready --repo <R> --pr <n> --json
    ```

package/bundles/manifest.json

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

package/package.json

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