@caddis/cli 0.4.35 → 0.4.36

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.122",
+  "version": "1.3.123",
   "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_gate.py

@@ -96,10 +96,11 @@ def phase_lane(block: str) -> str:
 def launch_command(block: str) -> str:
     """The literal command for a non-claude lane, if the phase names one.
 
-    Also matches a caddis_lanes.py run command for the codex, agy and glm lanes.
+    Also matches a caddis_lanes.py run command or a direct codex/agy command.
     """
     m = re.search(
-        r'`((?:claude-(?:glm|oss|deepseek)|' + _LANES_RUN + r')[^`]*)`',
+        r'`((?:claude-(?:glm|oss|deepseek)\b|' + _LANES_RUN
+        + r'\b|codex\s+exec\b|agy\b)[^`]*)`',
         block,
     )
     return m.group(1).strip() if m else ""
@@ -142,6 +143,28 @@ def gate_lane(plan: Path, phase: int) -> int:
                 f"[caddis-gate] phase {phase}'s caddis_lanes command names --phase {named.group(1)}: {cmd}\n"
                 "  The lane would run another phase's work. Refusing to run it.\n")
             return EXIT_MALFORMED
+    elif re.match(r"(?:codex\s+exec|agy)\b", cmd):
+        if "HEADLESS RUN RULES" not in cmd:
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct command has no HEADLESS RUN RULES: {cmd}\n"
+                "  The child has no headless run rules. Refusing to run it.\n")
+            return EXIT_MALFORMED
+        named = re.search(r"Implement Phase (\d+) only", cmd)
+        if not named:
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct command has no phase restriction: {cmd}\n"
+                "  The lane could run the wrong phase. Refusing to run it.\n")
+            return EXIT_MALFORMED
+        if int(named.group(1)) != phase:
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct command names Phase {named.group(1)}: {cmd}\n"
+                "  The lane would run another phase's work. Refusing to run it.\n")
+            return EXIT_MALFORMED
+        if cmd.startswith("agy") and not re.search(r"(?:^|\s)(?:-p|--print)(?:\s|$)", cmd):
+            sys.stderr.write(
+                f"[caddis-gate] phase {phase}'s direct agy command has no -p/--print: {cmd}\n"
+                "  The child would not run headless. Refusing to run it.\n")
+            return EXIT_MALFORMED
     elif not re.search(r"(?:^|\s)(?:-p|--print)(?:\s|$)", cmd):
         sys.stderr.write(
             f"[caddis-gate] phase {phase}'s launch command has no -p/--print: {cmd}\n"

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

@@ -28,6 +28,8 @@ except ModuleNotFoundError as exc:
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
     import caddis_exit
 
+import caddis_routing
+
 if hasattr(sys.stdout, "reconfigure"):
     sys.stdout.reconfigure(encoding="utf-8", errors="replace")
     sys.stderr.reconfigure(encoding="utf-8", errors="replace")
@@ -69,7 +71,17 @@ DEFAULT_CHAINS = {
     "docs": ("agy", "glm", "claude"),
 }
 BUDGET_PATTERNS: dict[str, tuple[str, ...]] = {
-    "claude": (),
+    # Claude Code 2.1.283 CLI bundle (limit-message builder and its prefix list).
+    "claude": (
+        r"You[’']ve hit your (?:session|weekly|Opus|Sonnet|Fable|usage credit) limit\b",
+        r"You[’']ve hit your (?:channel's )?monthly spend limit\b",
+        r"You[’']ve hit your team's shared budget\b",
+        r"You[’']ve reached your Fable limit\b",
+        r"You[’']re out of (?:usage credits|extra usage)\b",
+        r"Your org is out of usage\b",
+        r"Your usage allocation has been disabled by your admin\b",
+        r"Your group's usage limit is set to \$0\b",
+    ),
     # https://docs.z.ai/api-reference/api-code
     "glm": (
         r"API Error: 429.*\"type\"\s*:\s*\"(?:1113|1308|1309|1310|1316|1317)\"",
@@ -943,6 +955,216 @@ def classify_exit(
     return RESULT_LANE_FAILED
 
 
+CLAUDE_FAMILY = frozenset({"opus", "sonnet", "claude"})
+
+
+def next_lane(
+    role: str,
+    after: str,
+    *,
+    home: Path,
+    repo: Path,
+    which=shutil.which,
+) -> str | None:
+    """Find the next available model, sharing one budget across Claude models."""
+    routing = caddis_routing.resolve(home, repo, which=which)
+    chain = routing[role]
+    if role != "coding" and after not in chain and after not in CLAUDE_FAMILY:
+        # `after` came from the coding fallback (a Claude model ran out first): carry on down
+        # the coding chain, and never hand the exhausted Claude budget back.
+        coding = routing["coding"]
+        if after not in coding:
+            return None
+        rest = [model for model in coding[coding.index(after) + 1:] if model not in CLAUDE_FAMILY]
+        return rest[0] if rest else None
+    candidates = chain[chain.index(after) + 1:] if after in chain else chain
+    if after in CLAUDE_FAMILY:
+        candidates = [model for model in candidates if model not in CLAUDE_FAMILY]
+        if not candidates and role != "coding":
+            # Fall to coding models this role has not already tried. The coding chain ran before
+            # its own Claude fallback, and a role that lists agy or codex ran them before Claude;
+            # restarting either would loop.
+            candidates = [
+                model for model in routing["coding"]
+                if model not in CLAUDE_FAMILY and model not in chain
+            ]
+    return candidates[0] if candidates else None
+
+
+def _ci_watch_block(output: str) -> dict[str, str] | None:
+    """Read the last complete watch report, ignoring an echoed prompt template."""
+    fields: dict[str, str] = {}
+    reports: list[dict[str, str]] = []
+    for line in output.splitlines():
+        match = re.match(
+            r"^\s*(?:[`*]+\s*)?(RESULT|CHECKS|MERGE_STATE|FAILING)[`*]*\s*:\s*[`*]*\s*(.*?)\s*[`*]*\s*$",
+            line, re.I,
+        )
+        if not match:
+            continue
+        key, value = match.group(1).upper(), match.group(2).strip().strip("`* ")
+        if key == "RESULT":
+            if fields:
+                reports.append(fields)
+            fields = {}
+        if fields or key == "RESULT":
+            fields[key] = value
+    if fields:
+        reports.append(fields)
+    if not reports:
+        return None
+    last = reports[-1]
+    if set(last) != {"RESULT", "CHECKS", "MERGE_STATE", "FAILING"}:
+        return None
+    if last["RESULT"].lower() not in {"pass", "fail", "timeout"}:
+        return None
+    return last
+
+
+def _print_ci_watch(result: str, checks: str, merge_state: str, failing: str, watcher: str) -> None:
+    print(f"RESULT: {result}")
+    print(f"CHECKS: {checks}")
+    print(f"MERGE_STATE: {merge_state}")
+    print(f"FAILING: {failing}")
+    print(f"WATCHER: {watcher}")
+
+
+def ci_watch(
+    target_kind: str,
+    target_id: int,
+    repo_slug: str | None,
+    timeout_s: int,
+    *,
+    home: Path,
+    repo: Path,
+    which=shutil.which,
+    run_agy=run_lane,
+    run_gh=subprocess.run,
+    clock=time.monotonic,
+) -> int:
+    """Wait for CI with the resolved watcher, using one shared time budget."""
+    if target_kind not in {"pr", "run"} or target_id <= 0 or timeout_s <= 0:
+        print("[caddis-lanes] ci-watch: target and timeout must be positive", file=sys.stderr)
+        _print_ci_watch("timeout", "n/a", "n/a", "none", "gh")
+        return EXIT_CONFIG
+    if repo_slug is not None and not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repo_slug):
+        print("[caddis-lanes] ci-watch: --repo must be OWNER/NAME", file=sys.stderr)
+        _print_ci_watch("timeout", "n/a", "n/a", "none", "gh")
+        return EXIT_CONFIG
+
+    started = clock()
+    try:
+        watchers = caddis_routing.resolve(home, repo, which=which)["ci-watch"]
+    except caddis_routing.RoutingConfigError as exc:
+        print(f"[caddis-lanes] {exc}", file=sys.stderr)
+        _print_ci_watch("timeout", "n/a", "n/a", "none", "gh")
+        return EXIT_CONFIG
+
+    repo_opt = f" --repo {repo_slug}" if repo_slug else ""
+    if target_kind == "pr":
+        poll = f"gh pr checks {target_id}{repo_opt}"
+        state = f"gh pr view {target_id} --json mergeStateStatus,headRefOid{repo_opt}"
+    else:
+        poll = f"gh run view {target_id}{repo_opt}"
+        state = "n/a"
+    prompt = (
+        "Read-only CI watch. Poll with " + poll + " until every check has finished or the time runs out. "
+        + (f"For the PR, also poll {state}. " if target_kind == "pr" else "")
+        + "Never merge, push, comment, re-run, approve, close or edit anything. "
+        + "Then print exactly this block as the last thing you output, with actual values:\n"
+        "RESULT: pass|fail|timeout\n"
+        "CHECKS: <n passed>/<n total>\n"
+        "MERGE_STATE: <mergeStateStatus or n/a>\n"
+        "FAILING: <comma-separated failing check names, or none>"
+    )
+
+    for watcher in watchers:
+        if watcher == "claude":
+            break
+        if watcher != "agy":
+            print(f"[caddis-lanes] ci-watch: unsupported watcher {watcher}; skipping", file=sys.stderr)
+            continue
+        agy_path = which("agy")
+        if agy_path is None:
+            break
+        remaining = timeout_s - (clock() - started)
+        if remaining <= 0:
+            _print_ci_watch("timeout", "n/a", "n/a", "none", "agy")
+            return EXIT_CONFIG
+        try:
+            model = resolve_models(load_lanes_config(repo))["agy"]
+            effort = DEFAULT_EFFORT["agy"]
+        except LaneConfigError as exc:
+            print(f"[caddis-lanes] {exc}", file=sys.stderr)
+            _print_ci_watch("timeout", "n/a", "n/a", "none", "agy")
+            return EXIT_CONFIG
+        agy_argv = [
+            agy_path, "--model", f"{model}-{effort}",
+            "--dangerously-skip-permissions", "--output-format", "text", "--print",
+        ]
+        try:
+            run = run_agy(agy_argv, repo, prompt, False, remaining, child_env(os.environ, "agy", model))
+        except OSError as exc:
+            print(f"[caddis-lanes] ci-watch: agy could not start ({exc}); watching with gh", file=sys.stderr)
+            break
+        outcome = classify_exit("agy", run.returncode, run.output, run.timed_out)
+        if run.timed_out:
+            _print_ci_watch("timeout", "n/a", "n/a", "none", "agy")
+            return EXIT_CONFIG
+        if outcome in {RESULT_OUT_OF_BUDGET, RESULT_CONFIG_ERROR}:
+            reason = "out of budget" if outcome == RESULT_OUT_OF_BUDGET else "configuration error"
+            print(f"[caddis-lanes] ci-watch: agy {reason}; watching with gh", file=sys.stderr)
+            break
+        report = _ci_watch_block(run.output)
+        if report is not None:
+            result = report["RESULT"].lower()
+            _print_ci_watch(result, report["CHECKS"], report["MERGE_STATE"], report["FAILING"], "agy")
+            return {"pass": EXIT_OK, "fail": EXIT_FAIL, "timeout": EXIT_CONFIG}[result]
+        break
+
+    remaining = timeout_s - (clock() - started)
+    if remaining <= 0:
+        print("[caddis-lanes] ci-watch: time budget expired before gh", file=sys.stderr)
+        _print_ci_watch("timeout", "n/a", "n/a", "none", "gh")
+        return EXIT_CONFIG
+    gh_path = which("gh")
+    if gh_path is None:
+        print("[caddis-lanes] ci-watch: gh not found on PATH", file=sys.stderr)
+        _print_ci_watch("timeout", "n/a", "n/a", "none", "gh")
+        return EXIT_CONFIG
+    command = (
+        [gh_path, "pr", "checks", str(target_id), "--watch"]
+        if target_kind == "pr" else [gh_path, "run", "watch", str(target_id), "--exit-status"]
+    )
+    if repo_slug:
+        command.extend(["--repo", repo_slug])
+    try:
+        completed = run_gh(
+            command, cwd=repo, capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=remaining,
+        )
+    except subprocess.TimeoutExpired:
+        print("[caddis-lanes] ci-watch: gh timed out", file=sys.stderr)
+        _print_ci_watch("timeout", "n/a", "n/a", "none", "gh")
+        return EXIT_CONFIG
+    except OSError as exc:
+        print(f"[caddis-lanes] ci-watch: gh could not start ({exc})", file=sys.stderr)
+        _print_ci_watch("timeout", "n/a", "n/a", "none", "gh")
+        return EXIT_CONFIG
+    output = "\n".join(part for part in (completed.stdout, completed.stderr) if part)
+    if output:
+        print("\n".join(output.splitlines()[-40:]), file=sys.stderr)
+    no_checks = "no checks reported" in output.lower()
+    code = EXIT_OK if completed.returncode == 0 else (
+        EXIT_FAIL if completed.returncode == 1 and not no_checks else EXIT_CONFIG
+    )
+    _print_ci_watch(
+        "pass" if code == EXIT_OK else "fail" if code == EXIT_FAIL else "timeout",
+        "n/a", "n/a", "see gh output" if code == EXIT_FAIL else "none", "gh",
+    )
+    return code
+
+
 def load_wording_findings(text: str) -> list[str]:
     findings = []
     seen = set()
@@ -1595,6 +1817,17 @@ def main(argv: list[str] | None = None) -> int:
     show_chain.add_argument("--lane")
     show_chain.add_argument("--repo", type=Path)
 
+    next_model = subparsers.add_parser("next-lane")
+    next_model.add_argument("--role", required=True, choices=tuple(caddis_routing.DEFAULT_ROUTING))
+    next_model.add_argument("--after", required=True)
+
+    watch = subparsers.add_parser("ci-watch")
+    watch_target = watch.add_mutually_exclusive_group(required=True)
+    watch_target.add_argument("--pr", type=int)
+    watch_target.add_argument("--run", type=int)
+    watch.add_argument("--repo")
+    watch.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT_S)
+
     run = subparsers.add_parser("run")
     _add_phase_arguments(run)
     run.add_argument("--type", required=True)
@@ -1618,6 +1851,34 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     try:
+        if args.command == "next-lane":
+            if args.after not in caddis_routing.KNOWN_MODELS:
+                print(f"[caddis-lanes] next-lane: unknown model {args.after!r}", file=sys.stderr)
+                return EXIT_CONFIG
+            try:
+                candidate = next_lane(
+                    args.role, args.after, home=Path.home(), repo=Path.cwd(), which=shutil.which
+                )
+            except caddis_routing.RoutingConfigError as exc:
+                print(f"[caddis-lanes] next-lane: {exc}", file=sys.stderr)
+                return EXIT_CONFIG
+            if candidate is None:
+                print(
+                    f"[caddis-lanes] next-lane: no lane left for {args.role} after {args.after}",
+                    file=sys.stderr,
+                )
+                return EXIT_CONFIG
+            print(candidate)
+            return EXIT_OK
+        if args.command == "ci-watch":
+            return ci_watch(
+                "pr" if args.pr is not None else "run",
+                args.pr if args.pr is not None else args.run,
+                args.repo,
+                args.timeout,
+                home=Path.home(),
+                repo=Path.cwd(),
+            )
         if args.command == "show-chain":
             cfg = load_lanes_config(args.repo if args.repo is not None else Path.cwd())
             chain = resolve_chain(args.type, cfg, first_lane=args.lane)

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Resolve the local model order for each caddis role."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+import tomllib
+from pathlib import Path
+from typing import Callable, Mapping
+
+import oss_model
+
+
+DEFAULT_ROUTING: dict[str, list[str]] = {
+    "critical": ["opus"],
+    "light": ["sonnet"],
+    "coding": ["agy", "codex"],
+    "review": ["glm", "deepseek"],
+    "consult": ["agy", "glm", "codex"],
+    "ci-watch": ["agy"],
+}
+KNOWN_MODELS = frozenset({"opus", "sonnet", "agy", "codex", "glm", "deepseek", "claude"})
+
+
+class RoutingConfigError(Exception):
+    """A routing file has an invalid value or cannot be parsed."""
+
+
+def _routing_from(path: Path) -> dict[str, list[str]]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as file:
+            config = tomllib.load(file)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise RoutingConfigError(f"{path}: {exc}") from exc
+
+    routing = config.get("routing", {})
+    if not isinstance(routing, dict):
+        raise RoutingConfigError(f"{path}: [routing] must be a table")
+    for role, models in routing.items():
+        if role not in DEFAULT_ROUTING:
+            raise RoutingConfigError(f"{path}: unknown routing role {role!r}")
+        if not isinstance(models, list):
+            raise RoutingConfigError(f"{path}: routing.{role} must be a list")
+        for model in models:
+            if not isinstance(model, str) or model not in KNOWN_MODELS:
+                raise RoutingConfigError(f"{path}: unknown model {model!r} in routing.{role}")
+    return routing
+
+
+def resolve(
+    home: Path,
+    repo: Path,
+    which: Callable[[str], str | None] = shutil.which,
+    env: Mapping[str, str] | None = None,
+) -> dict[str, list[str]]:
+    """Apply user and repo overrides, then keep only locally available models."""
+    env = os.environ if env is None else env
+    configured = dict(DEFAULT_ROUTING)
+    configured.update(_routing_from(Path(home) / ".caddis" / "config.toml"))
+    configured.update(_routing_from(Path(repo) / ".caddis" / "config.toml"))
+
+    providers = set(oss_model.configured_providers(dict(env)))
+    available = {"opus", "sonnet", "claude"} | (providers & {"glm", "deepseek"})
+    for tool in ("agy", "codex"):
+        if which(tool):
+            available.add(tool)
+
+    resolved = {}
+    for role, models in configured.items():
+        resolved[role] = list(dict.fromkeys(
+            model for model in models if model != "claude" and model in available
+        )) + ["claude"]
+    return resolved
+
+
+def main(argv: list[str] | None = None, env: Mapping[str, str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    show = commands.add_parser("show", help="print the resolved routing table")
+    show.add_argument("--json", action="store_true", help="print JSON")
+    show.add_argument("--repo", type=Path, default=Path.cwd(), help="repository path")
+    args = parser.parse_args(argv)
+
+    try:
+        routing = resolve(Path.home(), args.repo, env=env)
+    except RoutingConfigError as exc:
+        print(exc, file=sys.stderr)
+        return 3
+    if args.json:
+        print(json.dumps(routing))
+    else:
+        for role, models in routing.items():
+            print(f"{role}: {', '.join(models)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -77,6 +77,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 |
 | 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/cloud-phases/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: cloud-phases
+description: Run plan phases in Claude Code cloud sessions — write one prompt per phase, push, hand out paste lines, then take the PRs back
+---
+
+# /caddis:cloud-phases — run plan phases in the cloud, then take them back
+
+Use this when a plan has phases that can run in parallel and you want them to run in Claude Code
+cloud sessions (claude.ai/code) instead of on this machine. This session stays the orchestrator:
+it writes the work orders, and it reviews and merges the results. The cloud sessions only implement.
+
+**How the code moves.** Nothing syncs between the cloud and this disk. GitHub is the only meeting
+point. This session pushes the feature branch and the prompts. Each cloud session clones from
+GitHub, works on its own branch, and opens a pull request (PR) into the feature branch. This session
+merges each PR on GitHub, then pulls. So a cloud session sees only what is committed and pushed.
+
+Arguments: `$ARGUMENTS`
+
+Two modes:
+- `/caddis:cloud-phases [plan] [phases]` — **dispatch**: Steps 1–6.
+- `/caddis:cloud-phases intake` — **intake**: Step 7, after the owner has run the sessions.
+
+With no plan argument, use the active plan (`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_todo.py" active-plan`,
+or the one `status: current` plan in `.caddis/plans/`). If there is none, or more than one, ask.
+
+## Step 1 — check the preconditions (stop on any failure)
+
+```
+git remote get-url origin
+git branch --show-current
+git status --short
+gh auth status
+```
+
+- `origin` must be a GitHub repository. Cloud sessions clone from GitHub; a repo with no GitHub
+  remote cannot use this command. Say so and stop.
+- The current branch must be the plan's feature branch, never the default branch. The cloud PRs
+  target this branch, and it goes to `main` later through the normal `/caddis:ship-pr`.
+- Tracked changes must be committed. A cloud session cannot see uncommitted work.
+- `gh` must be signed in as an account that can push to the repository and open PRs.
+
+## Step 2 — pick the phases for the cloud
+
+Take the plan's not-done Tracker rows (or the phase numbers given). Keep a phase **local** when
+any of these is true, and say why:
+- It needs a tool the cloud does not have: Codex, agy, GLM, DeepSeek, a local database, a VPN
+  host, or real data.
+- It needs a gitignored file (for example `.caddis/relay/`, `.env`, keys). The cloud clone does
+  not have them.
+- It needs the owner's go-ahead when it runs (model evals, production), or it is orchestrator
+  work (verification, measurement, release judgement).
+- It depends on a phase that has not merged yet.
+
+Then check the **Touches** lists. Two cloud phases may run at the same time only if they share no
+file. When two phases touch the same file — a shared registry or manifest is the usual case — run
+them one after the other, or keep that shared edit local and make it yourself after both merge.
+
+## Step 3 — check the facts each phase depends on (rule: think before you send)
+
+For each cloud phase, at the feature branch's current head:
+- Confirm every path, function and line number the phase names. Record what you found, with
+  line numbers and the short SHA.
+- Write the edge cases the implementer must handle.
+- Find the exact CI commands for the files it touches (read `.github/workflows/`).
+
+A cloud session cannot ask you anything mid-run. Anything you do not write down, it will guess.
+
+## Step 4 — write one prompt per phase
+
+Write `.caddis/prompts/<release-or-feature>-cloud-phase-<NN>.md`. Every prompt is self-contained,
+with these sections in this order:
+
+```markdown
+---
+type: prompt
+title: <feature> Phase <N> (cloud) — <phase goal in a few words>
+created: <YYYY-MM-DD>
+---
+
+# <feature> Phase <N> — <phase title>
+
+Suggested model: <Opus | Sonnet> (`/model <alias>`). <one line on why>
+
+## Where you are
+- Repository `<owner>/<repo>`. Start from branch `<feature branch>` at its current head.
+  Create branch `<prefix>/phase-<NN>` from it. Work only on that branch.
+- You run in a Claude cloud session. You have no Codex, agy, GLM or DeepSeek, and you cannot see
+  gitignored files. This file and the tracked repo hold everything you need.
+- Read `AGENTS.md` at the repo root first. For background only, read the "Constraints" section of
+  `<plan path>`. Where it differs, this file wins.
+
+## The phase (copied from the plan)
+<Goal, Touches, Design, TDD, Exit gate, Commit message — copied, not summarised>
+
+## Facts already checked (<date>, at <short SHA>)
+- <path:line — what is there>
+
+## Edge cases to handle
+- <edge case>
+
+## Checks to run before you open the PR (the same as CI)
+- `<exact command>`
+Report the literal result of each.
+
+## Finish
+1. Commit on `<prefix>/phase-<NN>` with the commit message above. Stage named files only.
+2. Push the branch: `git push -u origin <prefix>/phase-<NN>`.
+3. Open a PR into `<feature branch>` (never into the default branch). Put the check results in
+   the PR description.
+4. Do not merge. Do not touch other branches. Stop and report the PR link.
+```
+
+The repository may be public. A prompt is committed and pushed, so it must hold no secrets, no
+internal host names, no machine paths and no credentials.
+
+## Step 5 — commit and push, then prove GitHub has it
+
+```
+git add <each prompt file by name>
+git commit -m "docs(prompts): cloud prompts for <feature> phases <N, M>"
+git push -u origin <feature branch>
+git rev-parse HEAD
+git ls-remote origin refs/heads/<feature branch>
+```
+
+The two SHAs must match. If they do not, the cloud sessions will start from old code — stop and fix
+the push first.
+
+## Step 6 — hand the owner the paste table, then stop
+
+Print one row per cloud phase:
+
+| Phase | Model | Branch to pick | Paste this |
+|---|---|---|---|
+| <N> | <Sonnet> | `<feature branch>` | `Read .caddis/prompts/<file> and follow it exactly.` |
+
+Tell the owner, in these words: open https://claude.ai/code, choose repository `<owner>/<repo>`,
+choose branch `<feature branch>`, paste the line, and start. Phases in the table share no file, so
+they can run at the same time. Then **stop**. Record "dispatched to cloud, PR pending" in each
+phase's Tracker row. When the PRs exist, the owner runs `/caddis:cloud-phases intake`.
+
+Do not use the Agent tool with `isolation: "remote"` for this. It has run locally instead of in the
+cloud, which uses no cloud credit and leaves a worktree behind.
+
+## Step 7 — intake: review and merge each PR, then pull
+
+```
+gh pr list --base <feature branch> --state open --json number,title,headRefName,headRefOid
+```
+
+For each PR from a `<prefix>/phase-<NN>` branch, one at a time:
+1. Read the whole diff (`gh pr diff <N>`). Check it against the phase's Design and Touches. A file
+   outside Touches is a finding.
+2. Wait for CI: `gh pr checks <N> --watch` (or the ci-watch lane, if this caddis has it).
+3. Review under the three rules: one review, stop at the first CLEAN; after two blocking reviews,
+   ask the owner. A fix goes back to the same cloud session or is made locally on the PR branch.
+4. Just before merging, re-read `gh pr view <N> --json headRefOid,mergeStateStatus`. Merge only if
+   the head SHA is the one you reviewed and CI passed on it:
+   `gh pr merge <N> --squash --delete-branch`.
+5. Pull: `git pull --ff-only origin <feature branch>`.
+6. Run the phase's exit gate locally, and after the last PR, the full test suite.
+7. Update the phase's Tracker row: status, PR number, merge commit, review result. Set the prompt's
+   frontmatter `status: done` so `/caddis:handoff` tidies it.
+
+Merge in dependency order. If a later PR conflicts after an earlier merge, ask its session to
+rebase on the feature branch, or resolve it locally on that PR branch — never on the feature branch
+directly.
+
+## Running the orchestrator in the cloud too
+The orchestrator can itself be a cloud session. Nothing above needs this machine, because every
+step goes through GitHub. What changes:
+- The owner still opens each worker session by hand at claude.ai/code. An orchestrator cannot
+  start cloud sessions itself.
+- The cloud orchestrator has no Codex, agy, GLM or DeepSeek. Phases on those lanes, and
+  second-vendor reviews, stay for a local session.
+- It cannot see gitignored files, so there is no relay: `/caddis:handoff` state does not carry to
+  the next session. Put the resume state in the plan's Tracker and push it.
+- Its container ends with the session. Push before you stop, every time.
+
+## Rules
+- This command never merges into the default branch. The feature branch goes there later through
+  `/caddis:ship-pr`, and the production boundary check still applies there.
+- One phase, one prompt, one branch, one PR.
+- The orchestrator reads every diff. A green CI run proves only that the tests pass, not that the
+  phase did what its Design says.

package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md

@@ -154,6 +154,21 @@ session that is handed a phase belonging to another lane spawns that lane rather
 work; a headless one records the deviation in the Tracker. Write the launch command out in full, per
 phase — it is executed verbatim.
 
+**Choose each phase's Lane from the routing table.** Run
+`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" show --json`. A phase the orchestrator
+does itself (verification, measurement, release judgement) uses the `critical` role. A phase whose
+Implementer line says "light" uses `light`. Every other phase uses `coding`. Take the first model
+of that role and write its Lane line as follows:
+
+- `opus`: `claude — /model opus`
+- `sonnet`: `claude — /model sonnet`
+- `claude`: `claude — this session`
+- `codex`: codex — `codex exec --ephemeral --sandbox workspace-write "HEADLESS RUN RULES. Read <plan path> and its Constraints. Implement Phase N only in the current checkout. Do not switch or create branches, commit, push, or edit files outside this phase. Run its exit gate and report the literal result."`
+- `agy`: agy — `agy --mode accept-edits --dangerously-skip-permissions --add-dir . --print-timeout 20m --output-format text -p "HEADLESS RUN RULES. Read <plan path> and its Constraints. Implement Phase N only in the current checkout. Do not switch or create branches, commit, push, or edit files outside this phase. Run its exit gate and report the literal result."`
+
+Replace `<plan path>` and `N` with this plan's path and phase number. If the routing command fails
+or exits 3, use `claude — this session` and state the reason in that phase.
+
 #### A phase may take a no-escalation lane only if its exit gate would fail on a spec error
 `glm-headless` cannot escalate: it does what the phase says. So completeness is only half the test —
 the other half is whether being **wrong** would be caught. Ask literally: *"if the instruction I just

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

@@ -166,8 +166,16 @@ row, visible to any later reader without an Advisory Hub having to catch it live
     lane worktrees and branches. It reports unmerged or dirty ones. It pushes the feature branch.
     The plan is not done until it prints `LEFTOVERS: 0`. Then run `/caddis:ship-pr`. Merging and
     post-merge cleanup stay with `/caddis:ship-merge` after the owner's go.
-10. **When Claude is out of budget**, the owner opens `caddis-run codex -m gpt-6-astra` and asks it
-    to follow this same subsection.
+10. **When a dispatched Claude run is out of budget**, read the output from the subagent or
+    `claude -p`. If it holds Claude usage-limit text (for example `You've hit your session limit`
+    or `You're out of extra usage`; the full list is `BUDGET_PATTERNS["claude"]` in
+    `caddis_lanes.py`), run `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" next-lane --role <the phase's role> --after <the model that ran>`.
+    Re-dispatch the same phase prompt to the printed lane with its direct launch command:
+    `codex exec ...` or `agy ... -p "..."`, using the same form that `/feature-plan` writes.
+    An out-of-budget switch is not an attempt (item 4). Record the fallback in the Tracker
+    `Lane` column, for example `sonnet -> agy (claude out of budget)`.
+    If `next-lane` exits 3, stop and report that no lane is left. As a last resort, the owner can
+    open `caddis-run codex -m gpt-6-astra` and ask it to follow this same subsection.
 
 **Advisory-Hub mode (conditional — OFF by default).** Check whether a companion file
 `<plan-dir>/<plan-stem>-advisory-context.md` exists (e.g. plan `.caddis/plans/foo.md` → look for

package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md

@@ -94,7 +94,13 @@ what failed.
 
 Watch the PR's checks job-by-job until completion:
 - Gitea lane: poll the run for the PR's head SHA via the API (`deploy-local` skill procedure).
-- GitHub lane: `gh pr checks <pr> --watch` / `gh run watch` (`gh-cli` skill).
+- GitHub lane: first record the head you are about to watch, then wait for PR checks outside the Claude session via `ci-watch`:
+  ```bash
+  gh pr view <pr> --json headRefOid        # write down headRefOid as <watched-sha>
+  python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --pr <pr>
+  ```
+  Exit codes: **0** pass → continue; **1** fail → read `FAILING:` and the gh output, classify the cause, apply the minimum source fix, and re-push (stop before merging); **3** could not tell → stop and report, do not merge.
+  Fallback when `caddis_lanes.py` is not available: watch in-session with `gh pr checks <pr> --watch` / `gh run watch` (`gh-cli` skill).
 - If any check fails (red check): report the failure, classify the cause, and **stop before merging**.
   Do not merge a failing PR. Apply the minimum source fix and re-push.
 
@@ -115,6 +121,11 @@ cannot bypass it.
 ## Step 7 — Merge to default branch
 
 Once all required checks are **green**, there are no merge conflicts, and review requirements are satisfied:
+- Re-read PR head and merge state before merging (GitHub lane):
+  ```bash
+  gh pr view <pr> --json headRefOid,mergeStateStatus
+  ```
+  Merge only when `headRefOid` equals `<watched-sha>`, the head recorded before the watch started and `mergeStateStatus` is `CLEAN` (or `HAS_HOOKS`/`UNSTABLE` only if the repo's own rules allow it; else stop and report). The ci-watch report is a signal, not proof.
 - Use the repo's configured **merge strategy** — read it from repo settings (Gitea repo settings API /
   `gh repo view --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed`) and `AGENTS.md`;
   an explicit argument wins. Options: **squash**, **merge-commit**, rebase-merge. **Don't assume** —
@@ -128,7 +139,12 @@ Once all required checks are **green**, there are no merge conflicts, and review
 
 If the default branch triggers an automated deployment pipeline:
 - Gitea: `lint_and_test` → `deploy_prod` → `release_metadata` (`deploy-local` skill).
-- GitHub: `gh run watch <run-id> --exit-status` on the default branch. If CI-only, note that no deploy occurs.
+- GitHub: wait for the deploy run on the default branch outside the Claude session via `ci-watch`:
+  ```bash
+  python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --run <run-id>
+  ```
+  Exit codes: **0** pass → continue; **1** fail → read `FAILING:` and the gh output, classify, apply the minimum source fix; **3** could not tell → stop, report, and **skip cleanup** (Step 9).
+  Fallback when `caddis_lanes.py` is not available: watch in-session with `gh run watch <run-id> --exit-status` on the default branch (`gh-cli` skill). If CI-only, note that no deploy occurs.
 - Validate health and deployed SHA if a live service is deployed. If deploy validation fails, report
   immediately and **skip cleanup** (Step 9).
 

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

@@ -95,12 +95,17 @@ Track jobs in order: `lint_and_test` → `frontend_checks` (if present) → `dep
 `release_metadata` → `notify`. Report status as each job completes. On failure, classify it and apply
 the minimum fix (see `deploy-local` skill §6).
 
-**GitHub lane** — Watch the run the push triggered via the `gh` CLI:
-```
+**GitHub lane** — Find the run id for the pushed SHA, then wait outside the Claude session via `ci-watch`:
+```bash
 gh run list --branch <branch> --limit 1                 # find the run id for the pushed SHA
-gh run watch <run-id> --exit-status                      # stream until done; non-zero on failure
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --run <run-id>
+```
+Exit codes: **0** pass → continue; **1** fail → read `FAILING:` and the gh output, classify, apply the minimum source fix; **3** could not tell → stop and report.
+On failure, pull only the failing job logs:
+```bash
 gh run view <run-id> --log-failed                        # on failure, pull only the failing job logs
 ```
+Fallback when `caddis_lanes.py` is not available: watch in-session with `gh run watch <run-id> --exit-status` (`gh-cli` skill).
 Report each job's status as it resolves. On failure, classify it and apply the minimum source fix.
 
 **Local-only lane** — no CI; skip monitoring.

package/bundles/antigravity-plugin/skills/ship-merge/SKILL.md

@@ -64,10 +64,24 @@ future run — ask every time, even for the same PR five minutes later.
 
 ## Step 3 — Merge
 
+Re-read PR head and merge state before merging (GitHub lane):
+```bash
+gh pr view <pr> --json headRefOid,mergeStateStatus
+```
+Merge only when `headRefOid` equals `<head-sha>` (the head that Step 1 found green and Step 2's
+confirmation named) and `mergeStateStatus` is `CLEAN` (or `HAS_HOOKS`/`UNSTABLE` only if the repo's
+own rules allow it). Otherwise stop and report: a new push needs a fresh Step 1 and a fresh confirm.
+A check report is a signal, not proof.
+
 Use the repo's configured **merge strategy** — read it from repo settings (Gitea repo settings API /
 `gh repo view --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed`) and `AGENTS.md`;
-an explicit argument wins. Options: **squash**, **merge-commit**, rebase-merge. **Don't assume** —
+an explicit argument wins. Options: **squash**, **merge-commit**, **rebase-merge**. **Don't assume** —
 if detection is inconclusive, say so and use merge-commit (never silently squash someone's history).
+
+Then merge:
+- GitHub: `gh pr merge <pr>` with `--squash` (squash), `--merge` (merge-commit) or `--rebase` (rebase-merge).
+- Gitea: call the Gitea PR merge API with the chosen strategy.
+
 Record the merge SHA.
 
 ## Step 4 — Monitor the deploy
@@ -75,8 +89,12 @@ Record the merge SHA.
 The merge lands on the default branch and triggers the pipeline. Watch it via the lane's skill:
 - Gitea: `lint_and_test` → `frontend_checks` (if present) → **`deploy_prod`** → `release_metadata`
   → `notify` (`deploy-local` skill §monitoring; classify + minimum-fix on failure).
-- GitHub: `gh run watch <run-id> --exit-status` on the default branch; if the workflow has a deploy
-  job, watch it through; if CI-only, note that no deploy occurs.
+- GitHub: wait for the deploy run on the default branch outside the Claude session via `ci-watch`:
+  ```bash
+  python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --run <run-id>
+  ```
+  Exit codes: **0** pass → continue; **1** fail → read `FAILING:` and the gh output, classify, apply the minimum source fix; **3** could not tell → stop, report, and **skip cleanup** (Step 6).
+  Fallback when `caddis_lanes.py` is not available: watch in-session with `gh run watch <run-id> --exit-status` on the default branch (`gh-cli` skill). If the workflow has a deploy job, watch it through; if CI-only, note that no deploy occurs.
 
 ## Step 5 — Post-deploy validation
 

package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md

@@ -103,7 +103,12 @@ what failed.
 Watch the PR's checks job-by-job (never the deploy — PRs don't deploy here), including the
 scope-guard check when present:
 - Gitea lane: poll the run for the PR's head SHA via the API (`deploy-local` skill procedure).
-- GitHub lane: `gh pr checks <pr> --watch` / `gh run watch` (`gh-cli` skill).
+- GitHub lane: wait for PR checks outside the Claude session via `ci-watch`:
+  ```bash
+  python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_lanes.py" ci-watch --pr <pr>
+  ```
+  Exit codes: **0** pass → continue; **1** fail → read `FAILING:` and the gh output, classify, apply the minimum source fix, then re-push (through Step 4's safety if history must change); **3** could not tell → stop and report, do not merge.
+  Fallback when `caddis_lanes.py` is not available: watch in-session with `gh pr checks <pr> --watch` / `gh run watch` (`gh-cli` skill).
 On a red check, classify the failure and apply the minimum **source** fix, then re-push (through
 Step 4's safety if history must change).
 

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.122",
+  "poolVersion": "1.3.123",
   "bundles": {
-    "antigravity-plugin": "1.3.122",
+    "antigravity-plugin": "1.3.123",
     "antigravity-plugin-extras": "1.3.40",
     "codex": "unknown"
   }

package/package.json

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