@caddis/cli 0.4.56 → 0.4.57

package/bundles/antigravity-plugin/hooks.json

@@ -9,7 +9,8 @@
             "command": "python guard_agy.py",
             "windows": "python guard_agy.py",
             "linux": "python3 guard_agy.py",
-            "osx": "python3 guard_agy.py"
+            "osx": "python3 guard_agy.py",
+            "timeout": 30
           }
         ]
       }

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.142",
+  "version": "1.3.143",
   "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_checkout_guard.py

@@ -3,6 +3,11 @@
 `shared` (handoff-integrity Phase 5, the design of fleet-handoff Phase 2): a checkout is shared when its root
 `AGENTS.md` says `Shared checkout: yes`, or when `git status` lists a path this session did not change. In a
 shared checkout handoff writes no tracked file there; it uses `caddis_docs_pr.py` instead.
+
+`checkout_is_shared` and `foreign_changes` (robustness #11) are the two halves of that test. `caddis_lanes.py accept`
+calls them before it fast-forwards the session checkout, and the commands that switch, rebase or pull run
+`shared` first (pr-merge, ship-pr, ship-merge, cloud-phases). A linked worktree is never shared: AGENTS.md is
+tracked, so a worktree carries the line too, but the worktree is the safe place the rule sends the work to.
 """
 
 from __future__ import annotations
@@ -79,28 +84,74 @@ def _norm(path: str) -> str:
     return path.strip().replace("\\", "/")
 
 
-def is_shared_checkout(root: Path, own_files: set[str]) -> tuple[bool, str]:
-    """(True, reason) when handoff must not write tracked files in `root`; else (False, "").
+class CheckoutStatusError(OSError):
+    """`git status` could not run in the checkout, so foreign changes cannot be ruled out."""
 
-    `Shared checkout: no` in AGENTS.md never hides a change this session did not make. When git status cannot
-    run, the checkout counts as shared: a wrong "no" could commit another session's files.
-    """
-    agents = Path(root) / "AGENTS.md"
+
+def _repo_top(start: Path) -> Path:
+    """The nearest folder at or above `start` that holds `.git` (a folder or a gitfile); `start` when none does."""
+    here = Path(start).resolve()
+    for folder in (here, *here.parents):
+        if (folder / ".git").exists():
+            return folder
+    return here
+
+
+def is_linked_worktree(top: Path) -> bool:
+    """True when `top/.git` is a gitfile that points into `<repo>/.git/worktrees/` (a `git worktree add` tree)."""
+    gitfile = Path(top) / ".git"
+    if not gitfile.is_file():
+        return False
     try:
-        text = agents.read_text(encoding="utf-8", errors="replace") if agents.is_file() else ""
+        line = gitfile.read_text(encoding="utf-8", errors="replace").strip()
     except OSError:
-        text = ""
-    if SHARED_RE.search(text):
-        return True, "AGENTS.md says Shared checkout: yes"
+        return False
+    return line.lower().startswith("gitdir:") and "/worktrees/" in line.replace("\\", "/").lower()
+
+
+def checkout_is_shared(root: Path) -> bool:
+    """True when the repo that holds `root` says `Shared checkout: yes` in its top `AGENTS.md` (any case).
+
+    A linked worktree is never shared (see the module note). A missing or unreadable AGENTS.md means no."""
+    top = _repo_top(Path(root))
+    if is_linked_worktree(top):
+        return False
+    try:
+        text = (top / "AGENTS.md").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+    return bool(SHARED_RE.search(text))
+
+
+def foreign_changes(root: Path, own_files: set[str] | None = None) -> list[str]:
+    """The dirty paths in `root` that are not in `own_files`, in `git status` order. A rename counts both paths.
+
+    Without session tracking (`own_files` None or empty), every dirty path counts. Raises CheckoutStatusError
+    when `git status` fails: the caller must then treat the checkout as unsafe."""
     ret, lines = get_porcelain_lines(Path(root))
     if ret != 0:
-        return True, "git status failed, so changes by other sessions cannot be ruled out"
-    own = {_norm(p) for p in own_files}
+        raise CheckoutStatusError(f"git status failed in {root}")
+    own = {_norm(p) for p in (own_files or set())}
     foreign: list[str] = []
     for entry in lines:
         for path in entry_paths(entry):
             if _norm(path) not in own and path not in foreign:
                 foreign.append(path)
+    return foreign
+
+
+def is_shared_checkout(root: Path, own_files: set[str]) -> tuple[bool, str]:
+    """(True, reason) when handoff must not write tracked files in `root`; else (False, "").
+
+    `Shared checkout: no` in AGENTS.md never hides a change this session did not make. When git status cannot
+    run, the checkout counts as shared: a wrong "no" could commit another session's files.
+    """
+    if checkout_is_shared(Path(root)):
+        return True, "AGENTS.md says Shared checkout: yes"
+    try:
+        foreign = foreign_changes(Path(root), own_files)
+    except CheckoutStatusError:
+        return True, "git status failed, so changes by other sessions cannot be ruled out"
     if foreign:
         return True, "changes not made by this session: " + ", ".join(foreign[:3])
     return False, ""

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

@@ -602,7 +602,26 @@ def is_test_file(path: str) -> bool:
     return False
 
 
+_STEERING_FILENAMES = {"conftest.py", "pytest.ini", "pyproject.toml", "setup.cfg", "tox.ini"}
+
+
+def is_review_steering_file(path: str) -> bool:
+    """True for config that steers reviews, merges or tests: never tier 0, and never a 0-reviewer "1-small".
+
+    `.caddis/*.toml` (review/implement routing, merge-chain checks, spend cap), any `conftest.py`, the pytest and
+    packaging config, and `.github/workflows/**`. A fix diff that changes these can turn a gate off, so it is reviewed.
+    """
+    norm = path.replace("\\", "/").lower().removeprefix("./")
+    if norm.startswith(".caddis/") and norm.endswith(".toml"):
+        return True
+    if norm.startswith(".github/workflows/"):
+        return True
+    return norm.rsplit("/", 1)[-1] in _STEERING_FILENAMES
+
+
 def is_tier0_file(path: str) -> bool:
+    if is_review_steering_file(path):
+        return False
     norm = path.replace("\\", "/").lower()
     if norm.startswith("./"):
         norm = norm[2:]
@@ -685,6 +704,8 @@ def review_tier(files: list[tuple[str, int]], plan_risk: str = "normal") -> str:
     non_tier0_lines = sum(lines for _, lines in non_tier0)
     if review_triggers(non_tier0_paths, non_tier0_lines):
         return "2"
+    if any(is_review_steering_file(p) for p in non_tier0_paths):
+        return "1"
     has_test = any(is_test_file(p) for p, _ in files)
     if non_tier0_lines <= 40 and has_test:
         return "1-small"

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

@@ -33,6 +33,7 @@ except ModuleNotFoundError as exc:
     import caddis_exit
     from caddis_heavy_slot import HeavySlotBusy, heavy_slot
 
+import caddis_checkout_guard
 import caddis_routing
 import caddis_redact
 import caddis_spend
@@ -2165,6 +2166,28 @@ def _printable(value: object) -> str:
     return _CONTROL_CHARS.sub("", text)
 
 
+# Accept fast-forwards the SESSION checkout. In a checkout a dev service serves from, or one that holds a peer's
+# uncommitted edits, that moves files under them (robustness #11). The lane's own scaffolding is not a peer's change.
+_LANE_OWN_PREFIX = ".caddis/orchestrator/"
+
+
+def shared_checkout_reason(repo: Path) -> str:
+    """Why accept must not fast-forward `repo`, or ''. Shared (AGENTS.md) and/or foreign changes (git status):
+    every reason that holds, joined with "; ", so an --allow-shared audit records all of them."""
+    reasons = []
+    if caddis_checkout_guard.checkout_is_shared(repo):
+        reasons.append("AGENTS.md says Shared checkout: yes")
+    try:
+        dirty = caddis_checkout_guard.foreign_changes(repo)
+    except caddis_checkout_guard.CheckoutStatusError:
+        reasons.append("git status failed, so changes by other sessions cannot be ruled out")
+        dirty = []
+    foreign = [path for path in dirty if not path.replace("\\", "/").startswith(_LANE_OWN_PREFIX)]
+    if foreign:
+        reasons.append("changes not made by this lane: " + ", ".join(foreign[:3]))
+    return "; ".join(reasons)
+
+
 def _accept_command(
     args,
     repo: Path,
@@ -2221,6 +2244,16 @@ def _accept_command(
             or packet["worktree_digest"] != worktree_digest(wt.path, files)):
         print("refusing: worktree changed since check")
         return EXIT_FAIL
+    unsafe = shared_checkout_reason(repo)
+    if unsafe and not getattr(args, "allow_shared", False):
+        print(f"refusing: the session checkout is not safe to fast-forward ({_printable(unsafe)}). "
+              "Run the programme from a worktree of origin/<default> under %TEMP% (git worktree add), "
+              "or pass --allow-shared to fast-forward here anyway")
+        return EXIT_USAGE
+    if unsafe:
+        packet["allow_shared"] = unsafe
+        write_packet(packet_path, packet)
+        print(f"ALLOW SHARED: {_printable(unsafe)}")
     if args.override_review is not None:
         packet["override_review"] = args.override_review
         write_packet(packet_path, packet)
@@ -2458,6 +2491,8 @@ def main(argv: list[str] | None = None) -> int:
     _add_phase_arguments(accept)
     accept.add_argument("--message", required=True)
     accept.add_argument("--override-review")
+    accept.add_argument("--allow-shared", action="store_true",
+                        help="fast-forward a shared checkout or one with foreign changes anyway (recorded)")
     abandon = subparsers.add_parser("abandon")
     _add_phase_arguments(abandon)
     finish = subparsers.add_parser("finish")

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

@@ -1,14 +1,16 @@
 """Merge pull requests one at a time, from green CI to a verified deploy, and stop the line at the first problem.
 
 For each PR (design section 11): when BEHIND, update the branch and cancel the old head's runs (force-cancel after
-2 minutes); a cancelled run on the head is re-run, never merged on; "no checks reported" waits; a failed check stops;
-no merge while a push run is in progress on the default branch; squash merge with --match-head-commit; then the merge
-SHA must get a push run, and `caddis_prod_check.py` must pass before the next PR starts. A STOP file is checked before
-each update-branch and each merge. --dry-run makes read-only `gh` calls and prints what it would do.
+2 minutes); a cancelled run on the head is re-run, never merged on; "checks green" is ci-watch's verdict on the
+`statusCheckRollup` of the PR's `headRefOid` (never the `gh pr checks` table, which can show an older head); "no
+checks reported" waits, then stops; every check skipped stops (no job ran), both unless --allow-no-checks; a failed
+check stops; no merge while a push run is in progress on the default branch; squash merge with --match-head-commit;
+then the merge SHA must get a push run, and `caddis_prod_check.py` must pass before the next PR starts. A STOP file is
+checked before each update-branch and each merge. --dry-run makes read-only `gh` calls and prints what it would do.
 
 Exit 0 when every PR merged and verified; 1 at the first stop; 3 when the profile cannot be read.
 
-Usage: caddis_merge_chain.py [--repo PATH] [--gh-repo OWNER/NAME] [--docs-only] [--dry-run]
+Usage: caddis_merge_chain.py [--repo PATH] [--gh-repo OWNER/NAME] [--docs-only] [--dry-run] [--allow-no-checks]
                              [--stop-file PATH ...] <pr> [<pr> ...]
 """
 
@@ -21,13 +23,15 @@ from pathlib import Path
 
 try:
     import caddis_exit
+    import caddis_lanes
     import caddis_prod_check as prod
 except ModuleNotFoundError as exc:
-    if exc.name not in {"caddis_exit", "caddis_prod_check"}:
+    if exc.name not in {"caddis_exit", "caddis_lanes", "caddis_prod_check", "caddis_heavy_slot", "caddis_routing"}:
         raise
     sys.path.insert(0, str(Path(__file__).resolve().parent))
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
     import caddis_exit
+    import caddis_lanes
     import caddis_prod_check as prod
 
 MAX_ATTEMPTS = 8
@@ -45,6 +49,7 @@ class Stop(Exception):
 class ChainContext(prod.Context):
     stop_files: list[Path] = field(default_factory=list)
     docs_only: bool = False
+    allow_no_checks: bool = False
 
 
 def _stop_check(ctx: ChainContext, before: str) -> None:
@@ -90,26 +95,63 @@ def _head_run(ctx: ChainContext, branch: str, head: str) -> dict | None:
     return next((r for r in runs if r.get("headSha") == head), None)  # type: ignore[union-attr]
 
 
-def _wait_checks(ctx: ChainContext, pr: int) -> str:
-    """Return 'pass', 'fail' or 'cancel'. Raise Stop when no check reports in time."""
+def _rollup_state(rollup: object, allow_no_checks: bool) -> tuple[str, str]:
+    """(state, detail) from the head's `statusCheckRollup`, by ci-watch's own verdict (`caddis_lanes._rollup_verdict`).
+
+    state is 'pass', 'fail', 'cancel', 'pending', 'none' (no check reported) or 'skipped' (every check skipped).
+    A check that only SKIPPED or NEUTRAL ran no job, so a rollup with no SUCCESS proves nothing: 'skipped', unless
+    the owner passed --allow-no-checks for a repo that has no CI at all.
+    """
+    verdict = caddis_lanes._rollup_verdict(rollup)
+    if verdict is None:
+        return ("pass", "no checks reported (--allow-no-checks)") if allow_no_checks else ("none", "")
+    _green, failed, unfinished = verdict
+    if failed:
+        cancelled = {str(i.get("name") or i.get("context") or "?") for i in rollup  # type: ignore[union-attr]
+                     if isinstance(i, dict) and str(i.get("conclusion") or "").upper() == "CANCELLED"}
+        return ("cancel" if set(failed) <= cancelled else "fail"), ", ".join(failed)
+    if unfinished:
+        return "pending", ", ".join(unfinished)
+    ran = sum(1 for i in rollup if isinstance(i, dict)  # type: ignore[union-attr]
+              and str(i.get("conclusion") or i.get("state") or "").upper() == "SUCCESS")
+    if not ran:
+        return ("pass", "every check skipped (--allow-no-checks)") if allow_no_checks else ("skipped", "")
+    return "pass", ""
+
+
+def _wait_checks(ctx: ChainContext, pr: int, head: str) -> str:
+    """Return 'pass', 'fail', 'cancel' or 'moved' for the commit `head`. Raise Stop when no proof comes in time.
+
+    The verdict is ci-watch's: the `statusCheckRollup` of the PR's `headRefOid`, read in one `gh pr view`. The
+    `gh pr checks` table is never read: it can still show an older head's checks.
+    """
     deadline = ctx.clock.now() + CHECKS_WAIT_MINUTES * 60
     while True:
-        proc = ctx.gh("pr", "checks", str(pr), "--json", "name,bucket")
-        if proc.rc != 0 and not proc.out.strip() and "no checks reported" not in proc.err + proc.out:
+        proc = ctx.gh("pr", "view", "--json", "headRefOid,statusCheckRollup", str(pr))
+        if proc.rc != 0:
             # Auth or network failure: say so now instead of waiting 30 minutes as if no check had started.
-            raise Stop(f"#{pr}: gh pr checks failed: {(proc.err or proc.out).strip()[:300]}")
-        buckets: list[str] = []
+            raise Stop(f"#{pr}: gh pr view failed: {(proc.err or proc.out).strip()[:300]}")
         try:
-            buckets = [c.get("bucket", "") for c in prod.json.loads(proc.out)] if proc.out.strip() else []
+            data = prod.json.loads(proc.out) if proc.out.strip() else {}
         except ValueError:
-            buckets = []
-        if "fail" in buckets:
-            return "fail"
-        if "cancel" in buckets:
-            return "cancel"
-        if buckets and "pending" not in buckets:
+            data = {}
+        if not isinstance(data, dict):
+            data = {}
+        if data.get("headRefOid") != head:
+            ctx.out(f"  #{pr}: the head is now {str(data.get('headRefOid'))[:12]}, not {head[:12]}; reading again")
+            return "moved"
+        state, detail = _rollup_state(data.get("statusCheckRollup"), ctx.allow_no_checks)
+        if state == "pass":
+            if detail:
+                ctx.out(f"  #{pr}: WARNING: {detail} on head {head[:12]}")
             return "pass"
-        waiting = "no checks reported yet" if not buckets else "checks pending"
+        if state in ("fail", "cancel"):
+            return state
+        if state == "skipped":
+            raise Stop(f"#{pr}: every check on head {head[:12]} was skipped: no job ran, so this is not a pass. "
+                       "If this repo has no CI at all, run again with --allow-no-checks")
+        waiting = (f"checks pending ({detail})" if state == "pending" else
+                   "no checks reported yet (if this repo has no CI at all, run again with --allow-no-checks)")
         if ctx.clock.now() >= deadline:
             raise Stop(f"#{pr}: {waiting} after {CHECKS_WAIT_MINUTES} min")
         if ctx.dry_run:
@@ -159,10 +201,10 @@ def merge_one(ctx: ChainContext, pr: int) -> str | None:
                 ctx.out(f"  WARNING: re-run of {run['databaseId']} refused: {(rerun.err or rerun.out).strip()[:200]}")
             ctx.clock.sleep(60)
             continue
-        result = _wait_checks(ctx, pr)
+        result = _wait_checks(ctx, pr, head)
         if result == "fail":
             raise Stop(f"#{pr}: CI failed on head {head[:12]}")
-        if result == "cancel":
+        if result in ("cancel", "moved"):
             continue
         if ctx.dry_run:
             ctx.out(f"#{pr} ({merge_state}): checks green; would wait for idle push runs, then squash-merge {head[:12]}")
@@ -219,6 +261,8 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--profile", type=Path, help="default: <repo>/.caddis/prod-check.toml")
     parser.add_argument("--docs-only", action="store_true", help="the PRs change docs only: expect no deploy")
     parser.add_argument("--dry-run", action="store_true", help="read-only gh calls; print the steps")
+    parser.add_argument("--allow-no-checks", action="store_true",
+                        help="the repo has no CI: accept a head with no check, or with every check skipped")
     parser.add_argument("--stop-file", type=Path, action="append", default=[],
                         help="extra STOP file (~/.caddis/STOP is always checked)")
     args = parser.parse_args(argv)
@@ -229,6 +273,7 @@ def main(argv: list[str] | None = None) -> int:
         return caddis_exit.NOT_RUN
     ctx = ChainContext(run=prod.real_runner(args.repo), clock=prod.Clock(), profile=profile, repo=args.repo,
                        gh_repo=args.gh_repo, dry_run=args.dry_run, docs_only=args.docs_only,
+                       allow_no_checks=args.allow_no_checks,
                        stop_files=[Path.home() / ".caddis" / "STOP", *args.stop_file])
     return merge_chain(ctx, args.prs)
 

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

@@ -77,6 +77,33 @@ USAGE_LIMIT_RE = re.compile(
     r"Usage limit reached for|Limit Exhausted|Insufficient balance|You.ve hit your .*limit|RESOURCE_EXHAUSTED",
     re.IGNORECASE,
 )
+# A provider failure, not a review: HTTP 429, any 5xx, a rate-limit or overload error. Counts only when the run gave no
+# verdict line (a review may quote such text from the code). 18-19 Oct 2026: a GLM 429 was reported as
+# "FAILED no verdict line" = BLOCKED, which can start a fix session for nothing.
+PROVIDER_FAILURE_RE = re.compile(
+    r"API Error: (?:429|5\d\d)\b|\bHTTP (?:429|5\d\d)\b|Too Many Requests|rate_limit_error|overloaded_error"
+    r"|Service Unavailable|Bad Gateway|Gateway Time-?out|Internal Server Error",
+    re.IGNORECASE,
+)
+CARD_TIMEOUT_SECS = 30 * 60  # one card review; at the limit the launcher tree is killed and the run is NOT_RUN
+
+
+def _provider_failure(output: str, review_text: str) -> str | None:
+    """Why a run with no verdict line is a provider failure (NOT_RUN), or None when it is a real review."""
+    if _verdicts(review_text):
+        return None  # any verdict line, even two that conflict, means a model wrote a review: BLOCKED, never NOT_RUN
+    if not review_text.strip():
+        return "empty reply"
+    match = PROVIDER_FAILURE_RE.search(output)
+    if match:
+        return f"provider error ({match.group(0)})"
+    try:
+        data = _leading_json(output)
+    except ValueError:  # not JSON (JSONDecodeError is a ValueError)
+        data = None
+    if isinstance(data, dict) and data.get("is_error") is True:
+        return "the run reported is_error"
+    return None
 
 
 def _review_role(repo: Path) -> list[str]:
@@ -120,12 +147,30 @@ def launch(provider: str, prompt: str, cwd: Path) -> tuple[int, str]:
     # and the verdict is lost (seen with DeepSeek on 10 Oct 2026). claude-oss.ps1 sets this for GLM only.
     env = {**os.environ, "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS": "1"}
     # stdin closed: started from a background shell with an open stdin, the launcher hung 40 minutes (10 Oct 2026).
-    res = subprocess.run(cmd, cwd=cwd, stdin=subprocess.DEVNULL, capture_output=True, text=True, encoding="utf-8",
-                         errors="replace", env=env)
-    if res.returncode != 0 and res.stderr:
+    # Its own process group (Windows) or session (POSIX), so the timeout kills the whole tree (pwsh, claude), not only
+    # the top process. A timeout is NOT_RUN (3): the run switches provider, never BLOCKED.
+    group = ({"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} if os.name == "nt"
+             else {"start_new_session": True})
+    proc = subprocess.Popen(cmd, cwd=cwd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                            text=True, encoding="utf-8", errors="replace", env=env, **group)
+    try:
+        stdout, stderr = proc.communicate(timeout=CARD_TIMEOUT_SECS)
+    except subprocess.TimeoutExpired:
+        _kill_tree(proc)
+        try:
+            stdout, _stderr = proc.communicate(timeout=60)
+        except subprocess.TimeoutExpired:
+            stdout = ""
+        return caddis_exit.NOT_RUN, (f"caddis_review: card review timed out after {CARD_TIMEOUT_SECS} s; process tree "
+                                     f"killed\n{stdout or ''}")
+    except BaseException:
+        _kill_tree(proc)
+        raise
+    stdout, stderr = stdout or "", stderr or ""
+    if proc.returncode != 0 and stderr:
         # A limit or key message often comes on stderr; keep it for the switch decision.
-        return res.returncode, (res.stdout + "\n" + res.stderr).strip() + "\n"
-    return res.returncode, res.stdout
+        return proc.returncode, (stdout + "\n" + stderr).strip() + "\n"
+    return proc.returncode, stdout
 
 
 def _leading_json(output: str) -> object:
@@ -261,12 +306,15 @@ def run_review(
                     break
 
             # Limit text counts only when the run gave no verdict: a review may quote such text from the code.
-            has_usage_limit = bool(USAGE_LIMIT_RE.search(output)) and not (
-                code == 0 and _verdicts(_extract_review_text(output)))
-            needs_switch = (code == 3) or (code == 2) or has_usage_limit
+            extracted = _extract_review_text(output)
+            has_usage_limit = bool(USAGE_LIMIT_RE.search(output)) and not (code == 0 and _verdicts(extracted))
+            # A 429, a 5xx or an empty reply is the provider failing, not the reviewer finding nothing: switch, and
+            # NOT_RUN when no provider is left. Never "FAILED no verdict line" (BLOCKED).
+            provider_failed = _provider_failure(output, extracted)
+            needs_switch = (code == 3) or (code == 2) or has_usage_limit or provider_failed is not None
 
             # Again after the JSON decode: an escaped key form that survived in the raw JSON is plain text now.
-            review_text = caddis_redact.redact(_extract_review_text(output), masks)
+            review_text = caddis_redact.redact(extracted, masks)
             review_file = out_dir / f"{card.stem}-{provider}.txt"
             content = review_text.rstrip("\r\n") + f"\nEXIT {code} secs {duration}\n"
 
@@ -277,6 +325,8 @@ def run_review(
                     reason = "exit 2"
                 elif has_usage_limit:
                     reason = "usage limit reached"
+                elif provider_failed is not None:
+                    reason = provider_failed
                 else:
                     reason = f"exit {code}"
 

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

@@ -241,9 +241,13 @@ def default_branch(root: Path) -> str:
                        caddis_exit.NOT_RUN)
 
 
+FETCH = True  # `render --no-fetch` (the waiting hook) turns it off for one command: read the origin refs it has
+
+
 def fetch(root: Path) -> str:
     """Fetch origin and return the default branch name."""
-    _git(root, "fetch", "--quiet", "origin")
+    if FETCH:
+        _git(root, "fetch", "--quiet", "origin")
     return default_branch(root)
 
 
@@ -2218,9 +2222,93 @@ def _build_parser() -> argparse.ArgumentParser:
     which.add_argument("--all", action="store_true", help="every roadmap on origin (used by hooks and commands)")
     p.add_argument("--root", default=".")
     p.add_argument("--out", default=None, help="the HTML file (default ~/.caddis/roadmap-pages/<repo>/<slug>.html)")
+    p.add_argument("--no-fetch", action="store_true",
+                   help="use the origin refs this checkout has; no git fetch (the waiting hook's background render)")
+    p.add_argument("--delay", type=int, default=0,
+                   help="wait this many seconds (at most 60) first: the waiting hook's follow-up render")
     return parser
 
 
+RENDER_LOCK_STALE_S = 600  # a render lock older than this is left by a killed render
+PENDING_NAME = ".roadmap-render.pending"  # session_waiting.py writes it beside its debounce stamp
+
+
+def _clear(path: Path | None) -> bool:
+    """Delete `path`; True when it was there."""
+    if path is None:
+        return False
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+    except OSError:
+        return path.exists()
+
+
+def _take_render_lock(lock: Path) -> bool:
+    """One render per repo at a time (robustness #8): create `lock` with O_EXCL, never wait. A lock older than
+    RENDER_LOCK_STALE_S is taken over once. False: another render holds it."""
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    for attempt in range(2):
+        try:
+            fd = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            pass
+        except PermissionError:  # Windows: a deleted lock whose delete is still pending
+            return False
+        else:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(str(os.getpid()))
+            return True
+        try:
+            stale = time.time() - lock.stat().st_mtime > RENDER_LOCK_STALE_S
+        except FileNotFoundError:
+            stale = True  # released between the create and the stat: try again
+        except OSError:  # Windows: a lock being deleted cannot be read either
+            return False
+        if attempt or not stale:
+            return False
+        try:
+            lock.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError:
+            return False
+    return False
+
+
+def _render(root: Path, args: argparse.Namespace) -> int:
+    """`render`: the pages, the prune and the hub. The caller holds the repo's render lock."""
+    import caddis_roadmap_page
+    slugs, on_origin = list_roadmaps_checked(root) if args.all else ([args.roadmap], None)
+    failed = written = pruned = 0
+    for slug in slugs:  # --all: one bad roadmap must not stop the others
+        try:
+            path = caddis_roadmap_page.write_page(root, slug, Path(args.out) if args.out else None,
+                                                  sys.modules[__name__])
+            if path is None:  # a newer caddis owns this page: kept, and neither written nor failed
+                continue
+            written += 1
+            print(f"[ROADMAP] page written: {path.resolve()}")
+        except Exception as exc:  # --all: one roadmap must never stop the others
+            if not args.all:
+                raise
+            failed += 1
+            print(f"[ROADMAP] {slug}: page not written: {exc}", file=sys.stderr)
+    try:  # the hub is a convenience: nothing below ever fails a render or changes its exit code
+        if args.all and on_origin is not None:  # a roadmap removed from origin leaves the hub too; a listing
+            # that failed removes nothing, and a folder still on origin keeps its page even if its render failed
+            pruned = caddis_roadmap_page.prune_folder(
+                caddis_roadmap_page.default_page_path(root, "_").parent, on_origin | set(slugs))
+        hub = caddis_roadmap_page.write_hub() if not args.out and (written or pruned) else None
+        if hub is not None:  # None: a newer caddis owns the hub (write_hub said so)
+            print(f"[ROADMAP] hub written: {hub.resolve()}")
+    except Exception as exc:
+        print(f"[ROADMAP] hub not written: {exc}", file=sys.stderr)
+    return caddis_exit.BLOCKED if failed else caddis_exit.CLEAN
+
+
 def _dispatch(args: argparse.Namespace) -> int:
     root = _repo_root(args.root)
     if args.cmd == "list":
@@ -2266,29 +2354,37 @@ def _dispatch(args: argparse.Namespace) -> int:
         import caddis_roadmap_page  # the page is separate; only `render` needs it
         if args.all and args.out:
             raise RoadmapError("--out works with one --roadmap, not with --all", caddis_exit.ERROR)
-        slugs, on_origin = list_roadmaps_checked(root) if args.all else ([args.roadmap], None)
-        failed = written = pruned = 0
-        for slug in slugs:  # --all: one bad roadmap must not stop the others
-            try:
-                path = caddis_roadmap_page.write_page(root, slug, Path(args.out) if args.out else None,
-                                                      sys.modules[__name__])
-                written += 1
-                print(f"[ROADMAP] page written: {path.resolve()}")
-            except Exception as exc:  # --all: one roadmap must never stop the others
-                if not args.all:
-                    raise
-                failed += 1
-                print(f"[ROADMAP] {slug}: page not written: {exc}", file=sys.stderr)
-        try:  # the hub is a convenience: nothing below ever fails a render or changes its exit code
-            if args.all and on_origin is not None:  # a roadmap removed from origin leaves the hub too; a listing
-                # that failed removes nothing, and a folder still on origin keeps its page even if its render failed
-                pruned = caddis_roadmap_page.prune_folder(
-                    caddis_roadmap_page.default_page_path(root, "_").parent, on_origin | set(slugs))
-            if not args.out and (written or pruned):
-                print(f"[ROADMAP] hub written: {caddis_roadmap_page.write_hub().resolve()}")
-        except Exception as exc:
-            print(f"[ROADMAP] hub not written: {exc}", file=sys.stderr)
-        return caddis_exit.BLOCKED if failed else caddis_exit.CLEAN
+        if args.delay > 0:
+            time.sleep(min(args.delay, 60))
+        folder = caddis_roadmap_page.default_page_path(root, "_").parent.name
+        lock = caddis_roadmap_page.pages_root() / ".locks" / f"{folder}.lock"
+        # The waiting hook's debounce (and a render that finds the lock held) leaves PENDING_NAME: the render that
+        # holds the lock renders once more at its end, so the last mark change always reaches the page.
+        state = caddis_roadmap_page.main_checkout(root) / ".caddis" / "session-state"
+        pending = state / PENDING_NAME if args.all and not args.out else None
+        if not _take_render_lock(lock):
+            if pending is not None and state.is_dir():
+                try:
+                    pending.write_text(str(os.getpid()), encoding="utf-8")
+                except OSError:
+                    pass
+            print("[ROADMAP] another render of this repo is running; skipped")
+            return caddis_exit.CLEAN
+        global FETCH
+        FETCH = not args.no_fetch
+        try:
+            _clear(pending)  # this render reads the marks as they are now
+            code = _render(root, args)
+            if _clear(pending):  # a mark changed while it ran: once more, under the same lock
+                code = _render(root, args)
+            return code
+        finally:
+            FETCH = True
+            try:  # only our own lock: a render that ran past the stale age may have been taken over
+                if lock.read_text(encoding="utf-8").strip() == str(os.getpid()):
+                    lock.unlink()
+            except (OSError, UnicodeDecodeError):
+                pass
     return caddis_exit.ERROR