@caddis/cli 0.4.41 → 0.4.42

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.127",
+  "version": "1.3.128",
   "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_governor.py

@@ -406,6 +406,19 @@ def job_process_ids(job: int) -> list[int]:
     return [int(lst.ProcessIdList[i]) for i in range(lst.NumberOfProcessIdsInList)]
 
 
+def query_named_job(name: str) -> tuple[float, list[int]]:
+    """Read a named job from a separate process using query access only."""
+    if sys.platform != "win32" or not name:
+        raise GovernorError("a Windows job name is required")
+    job = kernel32.OpenJobObjectW(JOB_OBJECT_QUERY, False, name)
+    if not job:
+        raise _winerr("OpenJobObjectW(query)")
+    try:
+        return job_cpu_seconds(job), job_process_ids(job)
+    finally:
+        close_job(job)
+
+
 def close_job(job: int) -> None:
     """Close a job handle. Never call it on the last handle of a job the calling process belongs to."""
     kernel32.CloseHandle(job)
@@ -451,7 +464,8 @@ def _host_kind() -> str:
 
 
 def exec_governed(argv: list[str], scope: str, budget: Path | None = None,
-                  machine_budget: Path | None = None, allow_uncapped: bool = False) -> int:
+                  machine_budget: Path | None = None, allow_uncapped: bool = False,
+                  job_name: str | None = None) -> int:
     """Run `argv` under the scope's limits and return its exit code.
 
     On Windows this puts the CURRENT process into the job for the rest of its life, so it is only
@@ -470,7 +484,7 @@ def exec_governed(argv: list[str], scope: str, budget: Path | None = None,
             parent = verified_parent_percent(os.environ)
             rate = effective_cpu_rate(limits, parent)
             machine_pct = effective_machine_percent(limits, parent)
-            name = new_job_name()
+            name = job_name or new_job_name()
             job = create_job(limits, rate, name)
             try:
                 assign_current_process(job)
@@ -518,6 +532,7 @@ def main(argv: list[str] | None = None) -> int:
     p_exec.add_argument("--scope", choices=SCOPES, required=True)
     p_exec.add_argument("--budget", type=Path)
     p_exec.add_argument("--machine-budget", type=Path, help=argparse.SUPPRESS)  # additional ceiling only
+    p_exec.add_argument("--job-name", help=argparse.SUPPRESS)
     p_exec.add_argument("--allow-uncapped", action="store_true",
                         help="where no cap can be applied (no systemd-run, macOS), run at lower priority anyway")
     p_show = sub.add_parser("show", help="print the effective limits")
@@ -538,7 +553,8 @@ def main(argv: list[str] | None = None) -> int:
     if not command:
         sys.stderr.write("usage: caddis_governor.py exec --scope session|lane [--budget PATH] -- <command...>\n")
         return EXIT_USAGE
-    return exec_governed(command, args.scope, args.budget, args.machine_budget, args.allow_uncapped)
+    return exec_governed(command, args.scope, args.budget, args.machine_budget,
+                         args.allow_uncapped, args.job_name)
 
 
 if __name__ == "__main__":

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

@@ -0,0 +1,227 @@
+"""Heavy-run slot manager.
+
+Limits concurrent test-heavy runs (test suites, gates) using non-blocking OS byte locks.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import errno
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import BinaryIO, Callable, Iterator
+
+if os.name == "nt":
+    import msvcrt
+else:
+    import fcntl
+
+
+class HeavySlotBusy(Exception):
+    """Raised when all heavy-run slots remain busy after the wait budget expires."""
+
+    def __init__(self, holder: str | None = None) -> None:
+        self.holder = holder
+        message = f"heavy-run slot busy: {holder}" if holder else "heavy-run slot busy"
+        super().__init__(message)
+
+
+def _try_lock(handle: BinaryIO) -> bool:
+    try:
+        if os.name == "nt":
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+        else:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return True
+    except OSError as exc:
+        if exc.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+            raise
+        return False
+
+
+def _unlock(handle: BinaryIO) -> None:
+    try:
+        if os.name == "nt":
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+    except OSError:
+        pass
+
+
+def _read_holder(slot_path: Path) -> str | None:
+    try:
+        flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
+        fd = os.open(slot_path, flags)
+        with os.fdopen(fd, "rb") as f:
+            if os.name == "nt":
+                # On Windows, byte 0 is locked by the holder process, so reading byte 0
+                # raises PermissionError. Seeking to 1 reads the remainder of the payload.
+                f.seek(1)
+            raw = f.read()
+            text = raw.decode("utf-8", errors="replace").strip()
+            return text or None
+    except Exception:
+        return None
+
+
+def _resolve_slots(slots: int | None) -> int:
+    if slots is not None:
+        try:
+            val = int(slots)
+            if val < 0:
+                sys.stderr.write(f"CADDIS_HEAVY_SLOTS: invalid value {slots!r}; defaulting to 1\n")
+                return 1
+            return val
+        except (ValueError, TypeError):
+            sys.stderr.write(f"CADDIS_HEAVY_SLOTS: invalid value {slots!r}; defaulting to 1\n")
+            return 1
+
+    raw = os.environ.get("CADDIS_HEAVY_SLOTS")
+    if raw is None:
+        return 1
+
+    try:
+        val = int(raw.strip())
+        if val < 0:
+            sys.stderr.write(f"CADDIS_HEAVY_SLOTS: invalid value {raw!r}; defaulting to 1\n")
+            return 1
+        return val
+    except ValueError:
+        sys.stderr.write(f"CADDIS_HEAVY_SLOTS: invalid value {raw!r}; defaulting to 1\n")
+        return 1
+
+
+def _resolve_wait_s(wait_s: float | None) -> float:
+    if wait_s is not None:
+        try:
+            return max(0.0, float(wait_s))
+        except (ValueError, TypeError):
+            return 1200.0
+
+    raw = os.environ.get("CADDIS_HEAVY_WAIT_S")
+    if raw is None:
+        return 1200.0
+
+    try:
+        return max(0.0, float(raw.strip()))
+    except ValueError:
+        return 1200.0
+
+
+@contextlib.contextmanager
+def heavy_slot(
+    kind: str,
+    wait_s: float | None = None,
+    *,
+    slots: int | None = None,
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+    root: Path | str | None = None,
+) -> Iterator[None]:
+    """Acquire an OS-level byte-locked heavy execution slot.
+
+    Limits parallel test-heavy commands across processes and sessions.
+    """
+    if os.environ.get("CADDIS_HEAVY_SLOT_HELD") == "1":
+        yield
+        return
+
+    num_slots = _resolve_slots(slots)
+    if num_slots == 0:
+        yield
+        return
+
+    timeout_s = _resolve_wait_s(wait_s)
+    if root is not None:
+        slot_dir = Path(root)
+    else:
+        # Windows %TEMP% is already per user. On POSIX /tmp is shared, and the first user to create a
+        # shared folder would lock every other user out (they would see "busy" for ever), so each
+        # user gets their own folder: the limit is per account, as the guide says.
+        suffix = f"-{os.getuid()}" if hasattr(os, "getuid") else ""
+        slot_dir = Path(tempfile.gettempdir()) / f"caddis-heavy{suffix}"
+    slot_dir.mkdir(parents=True, exist_ok=True)
+
+    deadline = clock() + timeout_s
+    acquired_handle: BinaryIO | None = None
+    last_holder: str | None = None
+
+    while True:
+        holders: list[str] = []
+        for i in range(num_slots):
+            slot_file = slot_dir / f"slot-{i}"
+            flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0)
+            handle = None
+            try:
+                fd = os.open(slot_file, flags, 0o666)
+                handle = os.fdopen(fd, "r+b")
+                if _try_lock(handle):
+                    acquired_handle = handle
+                    break
+                else:
+                    h = _read_holder(slot_file)
+                    if h:
+                        holders.append(h)
+                    handle.close()
+                    handle = None
+            except OSError:
+                if handle is not None:
+                    try:
+                        handle.close()
+                    except OSError:
+                        pass
+                handle = None
+
+        if acquired_handle is not None:
+            break
+
+        if holders:
+            last_holder = ", ".join(holders)
+
+        now = clock()
+        remaining = deadline - now
+        if remaining <= 0:
+            raise HeavySlotBusy(last_holder)
+
+        sleep(min(2.0, remaining))
+
+    now_iso = datetime.datetime.now(datetime.timezone.utc).isoformat()
+    holder_text = f"{os.getpid()} {kind} {now_iso}"
+    payload = f"\n{holder_text}\n".encode("utf-8")
+    acquired_handle.seek(0)
+    acquired_handle.write(payload)
+    acquired_handle.truncate(len(payload))
+    acquired_handle.flush()
+
+    prev_held = os.environ.get("CADDIS_HEAVY_SLOT_HELD")
+    os.environ["CADDIS_HEAVY_SLOT_HELD"] = "1"
+
+    try:
+        yield
+    finally:
+        if prev_held is None:
+            os.environ.pop("CADDIS_HEAVY_SLOT_HELD", None)
+        else:
+            os.environ["CADDIS_HEAVY_SLOT_HELD"] = prev_held
+
+        try:
+            acquired_handle.seek(0)
+            acquired_handle.truncate(0)
+            acquired_handle.flush()
+        except OSError:
+            pass
+        finally:
+            try:
+                _unlock(acquired_handle)
+            finally:
+                try:
+                    acquired_handle.close()
+                except OSError:
+                    pass

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

@@ -6,9 +6,11 @@ from __future__ import annotations
 
 import importlib.util
 import hashlib
+from functools import lru_cache
 import json
 import os
 import re
+import secrets
 import shlex
 import shutil
 import signal
@@ -16,17 +18,20 @@ import subprocess
 import sys
 import tempfile
 import time
+import threading
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 
 try:
     import caddis_exit
+    from caddis_heavy_slot import HeavySlotBusy, heavy_slot
 except ModuleNotFoundError as exc:
-    if exc.name != "caddis_exit":
+    if exc.name not in {"caddis_exit", "caddis_heavy_slot"}:
         raise
     sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
     import caddis_exit
+    from caddis_heavy_slot import HeavySlotBusy, heavy_slot
 
 import caddis_routing
 
@@ -39,13 +44,17 @@ EXIT_FAIL = caddis_exit.BLOCKED
 EXIT_USAGE = caddis_exit.ERROR
 EXIT_CONFIG = caddis_exit.NOT_RUN
 EXIT_ALL_OUT = caddis_exit.NOT_RUN
+EXIT_NOT_RUN = caddis_exit.NOT_RUN
 RESULT_OK = "OK"
 RESULT_LANE_FAILED = "LANE-FAILED"
+RESULT_STALLED = "LANE-STALLED"
 RESULT_OUT_OF_BUDGET = "OUT-OF-BUDGET"
 RESULT_CONFIG_ERROR = "CONFIG-ERROR"
 RESULT_RESOURCE = "FAILED-RESOURCE"
 MAX_ATTEMPTS = 2
 DEFAULT_TIMEOUT_S = 3600
+DEFAULT_IDLE_TIMEOUT_S = 900
+IDLE_SAMPLE_S = 15
 LANE_IDS = ("claude", "glm", "codex-sol", "codex-astra", "agy")
 TASK_TYPES = ("backend", "hard", "ui", "tests", "docs")
 LANES_TMP = Path(tempfile.gettempdir()) / "caddis-lanes"
@@ -154,6 +163,17 @@ class LaneRun:
     duration_s: float
     pid: int
     started: float
+    stalled: bool = False
+    idle_seconds: int = 0
+    processes: list[dict] | None = None
+
+
+@dataclass
+class LaneProbe:
+    mtime_ns: int
+    cpu_seconds: float | None
+    pids: frozenset[int] | None
+    processes: list[dict]
 
 
 @dataclass
@@ -320,13 +340,14 @@ def governor_path() -> Path:
     )
 
 
-def governed_argv(argv: list[str]) -> list[str]:
+def governed_argv(argv: list[str], job_name: str | None = None) -> list[str]:
     return [
         sys.executable,
         str(governor_path()),
         "exec",
         "--scope",
         "lane",
+        *(["--job-name", job_name] if job_name else []),
         "--",
         *argv,
     ]
@@ -455,6 +476,88 @@ def release_lock(lock: Path) -> None:
         _release_acquisition_guard(guard_fd)
 
 
+def newest_file_mtime(cwd: Path) -> int:
+    newest = 0
+    files = 0
+    pending = [cwd]
+    while pending and files < 20000:
+        directory = pending.pop()
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                if entry.is_dir(follow_symlinks=False):
+                    if entry.name == ".git" or (
+                        directory == cwd / ".caddis" and entry.name == "orchestrator"
+                    ):
+                        continue
+                    pending.append(Path(entry.path))
+                elif entry.is_file(follow_symlinks=False):
+                    files += 1
+                    newest = max(newest, entry.stat(follow_symlinks=False).st_mtime_ns)
+                    if files >= 20000:
+                        break
+    return newest
+
+
+def default_probe(pid: int, cwd: Path, job_name: str | None) -> LaneProbe:
+    mtime = newest_file_mtime(cwd)
+    if sys.platform == "win32":
+        governor = _governor_probe_module()
+        cpu, pids = governor.query_named_job(job_name)
+        names = _windows_process_names(pids)
+    elif sys.platform.startswith("linux"):
+        ticks = os.sysconf("SC_CLK_TCK")
+        members = []
+        for path in Path("/proc").iterdir():
+            if not path.name.isdecimal():
+                continue
+            try:
+                stat = (path / "stat").read_text(encoding="utf-8")
+                fields = stat[stat.rfind(")") + 2 :].split()
+                if int(fields[3]) == pid:
+                    members.append((int(path.name), stat[stat.find("(") + 1 : stat.rfind(")")],
+                                    (int(fields[11]) + int(fields[12])) / ticks))
+            except (OSError, ValueError, IndexError):
+                continue
+        pids = [item[0] for item in members]
+        cpu = sum(item[2] for item in members)
+        names = {item[0]: item[1] for item in members}
+    else:
+        return LaneProbe(mtime, None, None, [])
+    return LaneProbe(mtime, cpu, frozenset(pids),
+                     [{"pid": member, "name": names.get(member, "unknown")} for member in sorted(pids)])
+
+
+@lru_cache(maxsize=1)
+def _governor_probe_module():
+    return _load_file_module("_caddis_governor_probe", governor_path())
+
+
+def _windows_process_names(pids: list[int]) -> dict[int, str]:
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.windll.kernel32
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.QueryFullProcessImageNameW.argtypes = [wintypes.HANDLE, wintypes.DWORD,
+                                                    wintypes.LPWSTR, ctypes.POINTER(wintypes.DWORD)]
+    kernel32.QueryFullProcessImageNameW.restype = wintypes.BOOL
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    names = {}
+    for pid in pids:
+        handle = kernel32.OpenProcess(0x1000, False, pid)
+        if not handle:
+            continue
+        try:
+            buffer = ctypes.create_unicode_buffer(32768)
+            size = wintypes.DWORD(len(buffer))
+            if kernel32.QueryFullProcessImageNameW(handle, 0, buffer, ctypes.byref(size)):
+                names[pid] = Path(buffer.value).name
+        finally:
+            kernel32.CloseHandle(handle)
+    return names
+
+
 def run_lane(
     argv: list[str],
     cwd: Path,
@@ -462,14 +565,19 @@ def run_lane(
     stdin_prompt: bool,
     timeout_s: int,
     env: dict,
+    idle_timeout_s: int = DEFAULT_IDLE_TIMEOUT_S,
+    clock=time.monotonic,
+    sleep=time.sleep,
+    probe=default_probe,
 ) -> LaneRun:
-    full = governed_argv(argv)
+    job_name = f"Local\\caddis-governor-{os.getpid()}-{secrets.token_hex(8)}" if sys.platform == "win32" else None
+    full = governed_argv(argv, job_name)
     if not stdin_prompt:
         full.append(prompt)
     validate_codex_argv(full)
 
     started = time.time()
-    monotonic_started = time.monotonic()
+    monotonic_started = clock()
     popen_options = {}
     if sys.platform != "win32":
         popen_options["start_new_session"] = True
@@ -479,47 +587,117 @@ def run_lane(
         stdin=subprocess.PIPE if stdin_prompt else subprocess.DEVNULL,
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
         env=env,
         **popen_options,
     )
-    timed_out = False
-    output = ""
-    try:
+    timed_out = stalled = False
+    idle_seconds = 0
+    processes = None
+    chunks: list[bytes] = []
+    byte_count = [0]
+
+    def read_output() -> None:
+        assert proc.stdout is not None
         try:
-            output, _ = proc.communicate(
-                input=prompt if stdin_prompt else None,
-                timeout=timeout_s,
-            )
-        except subprocess.TimeoutExpired as first_timeout:
-            kill_governed(proc)
-            timed_out = True
+            while chunk := proc.stdout.read1(65536):
+                chunks.append(chunk)
+                byte_count[0] += len(chunk)
+        except OSError:
+            pass  # the pipe can close when the governed process is killed
+
+    reader = threading.Thread(target=read_output, daemon=True)
+    reader.start()
+    try:
+        if stdin_prompt:
+            assert proc.stdin is not None
+            stdin_pipe = proc.stdin
+
+            def write_prompt() -> None:
+                # On its own thread: a child that never reads its stdin would block this write for
+                # ever, and the wall-clock and idle limits below must still apply to it.
+                try:
+                    stdin_pipe.write(prompt.encode("utf-8"))
+                except (BrokenPipeError, OSError, ValueError):
+                    pass
+                finally:
+                    try:
+                        stdin_pipe.close()
+                    except (BrokenPipeError, OSError, ValueError):
+                        pass
+
+            threading.Thread(target=write_prompt, daemon=True).start()
+        previous = None
+        previous_bytes = byte_count[0]
+        last_active = monotonic_started
+        last_sample = monotonic_started
+        next_sample = monotonic_started + IDLE_SAMPLE_S
+        if idle_timeout_s:
             try:
-                output, _ = proc.communicate(timeout=30)
-            except subprocess.TimeoutExpired as second_timeout:
+                previous = probe(proc.pid, cwd, job_name)
+            except Exception:
+                pass
+        while proc.poll() is None:
+            now = clock()
+            if now - monotonic_started >= timeout_s:
+                timed_out = True
                 kill_governed(proc)
-                captured = second_timeout.output or first_timeout.output or ""
-                output = (
-                    captured.decode("utf-8", errors="replace")
-                    if isinstance(captured, bytes)
-                    else captured
-                )
+                break
+            until_sample = max(next_sample - now, 0) if idle_timeout_s else 0.25
+            sleep(min(0.25, until_sample, timeout_s - (now - monotonic_started)))
+            if proc.poll() is not None or not idle_timeout_s:
+                continue
+            now = clock()
+            if now < next_sample:
+                continue
+            next_sample = now + IDLE_SAMPLE_S
+            try:
+                current = probe(proc.pid, cwd, job_name)
+            except Exception:
+                current = None
+            if current is None or previous is None:
+                last_active = now  # unknown activity must not cause a false stall
+            else:
+                elapsed = max(now - last_sample, 0)
+                active = (byte_count[0] != previous_bytes or
+                          current.mtime_ns != previous.mtime_ns or
+                          current.pids != previous.pids or
+                          (current.cpu_seconds is not None and previous.cpu_seconds is not None and
+                           current.cpu_seconds - previous.cpu_seconds > elapsed / 60))
+                if active:
+                    last_active = now
+            previous, previous_bytes, last_sample = current, byte_count[0], now
+            if now - last_active >= idle_timeout_s and now - monotonic_started < timeout_s:
+                stalled = True
+                idle_seconds = int(now - last_active)
+                processes = current.processes
+                kill_governed(proc)
+                break
+        try:
+            proc.wait(timeout=30)
+        except subprocess.TimeoutExpired:
+            kill_governed(proc)
+        reader.join(timeout=30)
     except BaseException:
         kill_governed(proc)
         raise
 
     return LaneRun(
         returncode=proc.returncode,
-        output=output,
+        output=b"".join(chunks).decode("utf-8", errors="replace"),
         timed_out=timed_out,
-        duration_s=time.monotonic() - monotonic_started,
+        duration_s=clock() - monotonic_started,
         pid=proc.pid,
         started=started,
+        stalled=stalled,
+        idle_seconds=idle_seconds,
+        processes=processes,
     )
 
 
+
+# ci_watch compares its `run_agy` argument with this by identity (see the idle watchdog note there).
+_LANE_RUNNER = run_lane
+
 def gate_commands(repo_root: Path, worktree: Path, cfg: dict) -> list[list[str]]:
     configured = cfg.get("gate_cmds")
     if isinstance(configured, list) and configured:
@@ -556,43 +734,65 @@ def run_gates(
     env: dict,
     timeout_s: int = 1800,
 ) -> list[GateResult]:
-    results = []
-    for command in cmds:
-        try:
-            completed = subprocess.run(
-                governed_argv(command),
-                cwd=cwd,
-                env=env,
-                capture_output=True,
-                text=True,
-                encoding="utf-8",
-                errors="replace",
-                timeout=timeout_s,
-            )
-        except subprocess.TimeoutExpired:
-            results.append(
+    try:
+        with heavy_slot("gates"):
+            results = []
+            for command in cmds:
+                try:
+                    completed = subprocess.run(
+                        governed_argv(command),
+                        cwd=cwd,
+                        env=env,
+                        capture_output=True,
+                        text=True,
+                        encoding="utf-8",
+                        errors="replace",
+                        timeout=timeout_s,
+                    )
+                except subprocess.TimeoutExpired:
+                    results.append(
+                        GateResult(
+                            cmd=shlex.join(command),
+                            returncode=-1,
+                            passed=False,
+                            tail=f"timed out after {timeout_s}s",
+                        )
+                    )
+                    continue
+
+                output = _combined_output(completed)
+                passed = completed.returncode == 0 or (
+                    completed.returncode == 5 and "pytest" in " ".join(command)
+                )
+                results.append(
+                    GateResult(
+                        cmd=shlex.join(command),
+                        returncode=completed.returncode,
+                        passed=passed,
+                        tail=output[-2000:],
+                    )
+                )
+            return results
+    except HeavySlotBusy as exc:
+        msg = f"heavy-run slot busy: {exc.holder}" if exc.holder else "heavy-run slot busy"
+        if cmds:
+            return [
                 GateResult(
                     cmd=shlex.join(command),
-                    returncode=-1,
+                    returncode=EXIT_NOT_RUN,
                     passed=False,
-                    tail=f"timed out after {timeout_s}s",
+                    tail=msg,
                 )
-            )
-            continue
-
-        output = _combined_output(completed)
-        passed = completed.returncode == 0 or (
-            completed.returncode == 5 and "pytest" in " ".join(command)
-        )
-        results.append(
+                for command in cmds
+            ]
+        return [
             GateResult(
-                cmd=shlex.join(command),
-                returncode=completed.returncode,
-                passed=passed,
-                tail=output[-2000:],
+                cmd="",
+                returncode=EXIT_NOT_RUN,
+                passed=False,
+                tail=msg,
             )
-        )
-    return results
+        ]
 
 
 def oss_review_path() -> Path | None:
@@ -788,9 +988,17 @@ def load_lanes_config(repo_root: Path) -> dict:
     lanes = data.get("lanes", {})
     if not isinstance(lanes, dict):
         raise LaneConfigError(f"[lanes] in {config_path} is not a table")
+    idle_timeout(lanes)
     return lanes
 
 
+def idle_timeout(cfg: dict, override: int | None = None) -> int:
+    value = cfg.get("idle_timeout_s", DEFAULT_IDLE_TIMEOUT_S) if override is None else override
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise LaneConfigError(f"invalid [lanes] idle_timeout_s: {value!r}")
+    return value
+
+
 def resolve_models(cfg: dict) -> dict[str, str]:
     models = DEFAULT_MODELS.copy()
     for key, value in cfg.get("models", {}).items():
@@ -937,9 +1145,12 @@ def classify_exit(
     output: str,
     timed_out: bool,
     guard_killed: bool = False,
+    stalled: bool = False,
 ) -> str:
     if guard_killed:
         return RESULT_RESOURCE
+    if stalled:
+        return RESULT_STALLED
     if timed_out:
         return RESULT_LANE_FAILED
     if any(re.search(pattern, output, re.I) for pattern in CONFIG_PATTERNS[lane]):
@@ -1109,7 +1320,10 @@ def ci_watch(
             "--dangerously-skip-permissions", "--output-format", "text", "--print",
         ]
         try:
-            run = run_agy(agy_argv, repo, prompt, False, remaining, child_env(os.environ, "agy", model))
+            # A CI watcher legitimately sits idle while CI runs, so the idle watchdog is off for it;
+            # the wall-clock limit (`remaining`) still applies.
+            watcher = (lambda *a: run_lane(*a, idle_timeout_s=0)) if run_agy is _LANE_RUNNER else run_agy
+            run = watcher(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
@@ -1202,6 +1416,7 @@ def build_prompt(
         "- Never use --no-verify. Never read or edit .env files or any secret. Never "
         "run anything against production.\n"
         "- Do not implement any other phase.\n"
+        "- Run every command in the foreground and wait for it to finish. Start no background tasks, watchers or dev servers.\n"
         "Resource budget (enforced by the machine, not by this text):\n"
         f"- You run inside a Windows Job Object: {limits_line}. Exceeding it slows "
         "you down; it does not stop the limit.\n"
@@ -1361,11 +1576,27 @@ def _run_post_checks(
     before: dict[str, str | None],
 ) -> tuple[str, int]:
     worktree = Path(packet["worktree"])
-    gates = run_gates(
-        gate_commands(repo, worktree, cfg),
-        worktree,
-        gate_env(repo, dict(os.environ)),
-    )
+    # The heavy-run slot covers the project's own test commands only. The review is a network call and
+    # must not hold a slot that another gate is waiting for.
+    try:
+        with heavy_slot("gates"):
+            gates = run_gates(
+                gate_commands(repo, worktree, cfg),
+                worktree,
+                gate_env(repo, dict(os.environ)),
+            )
+    except HeavySlotBusy as exc:
+        msg = f"heavy-run slot busy: {exc.holder}" if exc.holder else "heavy-run slot busy"
+        packet.update(
+            {
+                "gates": [{"cmd": "gates", "returncode": EXIT_NOT_RUN, "passed": False, "tail": msg}],
+                "gates_passed": False,
+                "next": "stop",
+            }
+        )
+        packet.pop("_freeze_before", None)
+        return "stop", EXIT_NOT_RUN
+
     review = run_review(worktree, dict(os.environ))
     pythons = list(before)
     if pythons:
@@ -1411,6 +1642,7 @@ def _run_command(
     packet_path: Path,
 ) -> int:
     cfg = load_lanes_config(repo)
+    idle_timeout_s = idle_timeout(cfg, args.idle_timeout)
     block = phase_block_text(plan, args.phase)
     findings_text = ""
     if args.findings is not None:
@@ -1484,6 +1716,7 @@ def _run_command(
             prompt_via_stdin(lane),
             args.timeout,
             child_env(dict(os.environ), lane, model),
+            idle_timeout_s=idle_timeout_s,
         )
         killed = guard_killed_since(lane_run.started, {lane_run.pid})
         result = classify_exit(
@@ -1492,6 +1725,7 @@ def _run_command(
             lane_run.output,
             lane_run.timed_out,
             killed,
+            lane_run.stalled,
         )
         packet["lanes_tried"].append(
             {
@@ -1502,9 +1736,18 @@ def _run_command(
                 "returncode": lane_run.returncode,
                 "duration_s": lane_run.duration_s,
                 "timed_out": lane_run.timed_out,
+                "stalled": lane_run.stalled,
+                "idle_seconds": lane_run.idle_seconds,
             }
         )
         packet["result"] = result
+        if lane_run.stalled:
+            packet.update({
+                "stall": "idle",
+                "idle_seconds": lane_run.idle_seconds,
+                "tail": f"idle for {lane_run.idle_seconds}s; process tree before kill: "
+                        f"{json.dumps(lane_run.processes or [])}",
+            })
         if result == RESULT_RESOURCE:
             packet["next"] = "stop"
             write_packet(packet_path, packet)
@@ -1518,12 +1761,15 @@ def _run_command(
             write_packet(packet_path, packet)
             print(f"NEXT: stop (config error on {lane})")
             return EXIT_CONFIG
-        if result == RESULT_LANE_FAILED:
+        if result in (RESULT_LANE_FAILED, RESULT_STALLED):
             packet["next"] = (
                 "takeover" if args.attempt >= MAX_ATTEMPTS else "redo"
             )
             write_packet(packet_path, packet)
-            print(f"NEXT: {packet['next']}")
+            if result == RESULT_STALLED:
+                print(f"NEXT: {packet['next']} (lane idle {lane_run.idle_seconds}s; see packet)")
+            else:
+                print(f"NEXT: {packet['next']}")
             return EXIT_FAIL
         break
     else:
@@ -1840,6 +2086,7 @@ def main(argv: list[str] | None = None) -> int:
     run.add_argument("--lane")
     run.add_argument("--findings", type=Path)
     run.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT_S)
+    run.add_argument("--idle-timeout", type=int)
     run.add_argument("--allow-load", action="store_true")
 
     check = subparsers.add_parser("check")

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

@@ -36,6 +36,7 @@ FIX_HINTS: dict[str, str] = {
     "deny-rules": "run /caddis:setup-project-ai to add the missing deny rules",
     "gitignore": "run /caddis:setup-project-ai to add the missing .caddis ignore entries",
     "misfiled": "move the file into a caddis document folder, or delete it",
+    "host-guard": "see docs/guide/resource-protection.md (install-host-guard.ps1)",
 }
 
 # Probed contract versions (docs/analysis/*-contract.md). WARN when the installed binary drifts past
@@ -452,6 +453,38 @@ def keys_line(env: Mapping[str, str]) -> tuple[str, str]:
         return ("INFO", "keys: could not check")
 
 
+def host_guard_findings(
+    run: Callable[..., object] | None = None,
+    budget_path: Path | None = None,
+) -> list[tuple[str, str]]:
+    """Check host guard installation on Windows. Levels: WARN (never raises)."""
+    if sys.platform != "win32":
+        return []
+
+    run = run or subprocess.run
+    out: list[tuple[str, str]] = []
+
+    try:
+        res = run(["sc", "query", "caddis-host-guard"], capture_output=True, text=True)
+        rc = getattr(res, "returncode", 0)
+        if rc != 0:  # 1060 is "no such service"; any other failure also means "cannot confirm it runs"
+            out.append(("WARN", f"caddis-host-guard service not found — {FIX_HINTS['host-guard']}"))
+    except Exception:
+        return []
+
+    if budget_path is None:
+        prog_data = os.environ.get("ProgramData", r"C:\ProgramData")
+        budget_path = Path(prog_data) / "caddis" / "host-budget.toml"
+
+    try:
+        if not budget_path.is_file():
+            out.append(("WARN", f"{budget_path} missing — {FIX_HINTS['host-guard']}"))
+    except Exception:
+        pass
+
+    return out
+
+
 # ── project checks (read-only — WARN or INFO, never FAIL) ─────────────────────
 def deny_rule_findings(dest: Path) -> list[tuple[str, str]]:
     dest = Path(dest)
@@ -593,6 +626,12 @@ def run(dest: Path, quiet: bool) -> int:
         hard = 1
     print(f"  {k_level:4} {k_text}")
 
+    host = host_guard_findings()
+    if host:
+        print("-- host")
+        for level, text in host:
+            print(f"  {level:4} {text}")
+
     print("-- project")
     proj_findings = deny_rule_findings(dest) + gitignore_findings(dest) + misfiled_findings(dest)
     if proj_findings:

package/bundles/antigravity-plugin/scripts/install-host-guard.ps1

@@ -2,6 +2,8 @@
 param(
     [switch]$Apply,
     [string]$NssmSha256,
+    # Where the NSSM binary to copy lives. Default: the first nssm.exe on PATH, else C:\Tools\nssm\nssm.exe.
+    [string]$NssmPath,
     [ValidateSet('report', 'enforce')]
     [string]$Mode = 'report'
 )
@@ -9,7 +11,12 @@ param(
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
-$sourceNssm = 'C:\Tools\nssm\nssm.exe'
+if ($NssmPath) {
+    $sourceNssm = $NssmPath
+} else {
+    $foundNssm = Get-Command 'nssm.exe' -ErrorAction SilentlyContinue
+    if ($foundNssm) { $sourceNssm = $foundNssm.Source } else { $sourceNssm = 'C:\Tools\nssm\nssm.exe' }
+}
 $serviceName = 'caddis-host-guard'
 $programRoot = Join-Path $env:ProgramFiles 'caddis'
 $nssmDir = Join-Path $programRoot 'nssm'

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

@@ -377,6 +377,225 @@ def check_venv(target: Path, install: bool, dry: bool) -> list[str]:
     return notes
 
 
+GATE_STEP_PY = r'''#!/usr/bin/env python3
+"""caddis_gate_step.py — Per-step gate runner with timeout and process tree cleanup.
+
+Runs under the PROJECT's interpreter, which may be older than 3.11: no `tomllib` at import time
+(the config file is skipped, with one stderr line, when it is missing) and annotations are not evaluated.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:  # Python < 3.11
+    tomllib = None
+
+
+def format_elapsed(seconds: float) -> str:
+    total_s = max(0, int(round(seconds)))
+    if total_s < 60:
+        return f"{total_s}s"
+    m = total_s // 60
+    s = total_s % 60
+    return f"{m}m{s:02d}s"
+
+
+def with_faulthandler(argv: list[str], name: str, env: dict[str, str] | None = None) -> list[str]:
+    argv = list(argv)
+    if name != "pytest":
+        return argv
+    if any("faulthandler_timeout" in str(arg) for arg in argv):
+        return argv
+    env_opts = (env.get("PYTEST_ADDOPTS") if env is not None else os.environ.get("PYTEST_ADDOPTS")) or ""
+    if "faulthandler_timeout" in env_opts:
+        return argv
+    return argv + ["-o", "faulthandler_timeout=300"]
+
+
+def kill_process_tree(proc: subprocess.Popen) -> None:
+    if sys.platform == "win32":
+        try:
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                capture_output=True,
+                timeout=10,
+            )
+        except Exception:
+            pass
+        try:
+            proc.kill()
+        except Exception:
+            pass
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            pass
+    else:
+        try:
+            pgid = os.getpgid(proc.pid)
+        except Exception:
+            pgid = proc.pid
+        try:
+            os.killpg(pgid, signal.SIGTERM)
+        except Exception:
+            pass
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(pgid, signal.SIGKILL)
+            except Exception:
+                pass
+            try:
+                proc.wait(timeout=5)
+            except Exception:
+                pass
+        except Exception:
+            pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if "--" in argv:
+        sep_idx = argv.index("--")
+        runner_args = argv[:sep_idx]
+        cmd = argv[sep_idx + 1:]
+    else:
+        runner_args = argv
+        cmd = []
+
+    parser = argparse.ArgumentParser(description="caddis quality gate step runner")
+    parser.add_argument("--name", required=True, help="Step name")
+    parser.add_argument("--timeout", type=int, required=True, help="Default timeout in seconds")
+    parser.add_argument("cmd", nargs="*", help="Command to run (if -- not used)")
+
+    args = parser.parse_args(runner_args)
+    if not cmd:
+        cmd = args.cmd
+        if cmd and cmd[0] == "--":
+            cmd = cmd[1:]
+
+    if not cmd:
+        print("[gate] error: no command specified to run", file=sys.stderr)
+        return 1
+
+    name = args.name
+    timeout = args.timeout
+
+    # Config: read .caddis/config.toml in the current directory if present
+    cfg_path = Path(".caddis/config.toml")
+    gate_cfg: dict = {}
+    if cfg_path.is_file() and tomllib is None:
+        print("[gate] note: .caddis/config.toml not read (needs Python 3.11 or later)", file=sys.stderr)
+    elif cfg_path.is_file():
+        try:
+            with open(cfg_path, "rb") as f:
+                raw_cfg = tomllib.load(f)
+            if isinstance(raw_cfg, dict):
+                g = raw_cfg.get("gate", {})
+                if isinstance(g, dict):
+                    gate_cfg = g
+        except Exception as exc:
+            print(f"[gate] warning: malformed .caddis/config.toml ({exc})", file=sys.stderr)
+
+    # Section [gate]: timeout_<name> overrides --timeout for that step name
+    candidate_keys = (
+        f"timeout_{name}",
+        f"timeout_{name.replace('-', '_')}",
+        f"timeout_{name.replace('_', '-')}",
+    )
+    for k in candidate_keys:
+        if k in gate_cfg:
+            val = gate_cfg[k]
+            if isinstance(val, int) and not isinstance(val, bool) and val > 0:
+                timeout = val
+            else:
+                print(
+                    f"[gate] warning: invalid {k}={val!r} in config (must be positive integer)",
+                    file=sys.stderr,
+                )
+            break
+
+    # Env var CADDIS_GATE_TIMEOUT_<NAME upper, - replaced by _> overrides config
+    env_var_name = f"CADDIS_GATE_TIMEOUT_{name.upper().replace('-', '_')}"
+    if env_var_name in os.environ:
+        raw_val = os.environ[env_var_name].strip()
+        try:
+            env_timeout = int(raw_val)
+            if env_timeout > 0:
+                timeout = env_timeout
+            else:
+                print(
+                    f"[gate] warning: invalid {env_var_name}={raw_val!r} (must be positive integer)",
+                    file=sys.stderr,
+                )
+        except ValueError:
+            print(
+                f"[gate] warning: invalid {env_var_name}={raw_val!r} (must be integer)",
+                file=sys.stderr,
+            )
+
+    # pytest_args (list of strings) are appended to pytest command ONLY when --name is pytest
+    if name == "pytest":
+        pytest_args = gate_cfg.get("pytest_args")
+        if isinstance(pytest_args, list):
+            for pa in pytest_args:
+                if isinstance(pa, str):
+                    cmd.append(pa)
+                else:
+                    cmd.append(str(pa))
+
+    # Pytest hang dump
+    cmd = with_faulthandler(cmd, name, os.environ)
+
+    # Print start line
+    print(f"[gate] {name}: start (limit {timeout}s)", flush=True)
+
+    start_time = time.monotonic()
+    kwargs: dict = {}
+    if sys.platform == "win32":
+        kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        kwargs["start_new_session"] = True
+
+    try:
+        proc = subprocess.Popen(cmd, **kwargs)
+    except Exception as exc:
+        print(f"[gate] {name}: failed to start {cmd[0]}: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        kill_process_tree(proc)
+        print(
+            f"[gate] {name}: TIMEOUT after {timeout}s - killed the process tree",
+            file=sys.stderr,
+            flush=True,
+        )
+        return 124
+
+    elapsed = time.monotonic() - start_time
+    rc = proc.returncode
+    print(f"[gate] {name}: done in {format_elapsed(elapsed)} (exit {rc})", flush=True)
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+'''
+
+
 # Enforced "green before push" gate. Installed into .git/hooks/pre-push. Pure POSIX sh
 # so it runs under Git's bundled shell on Windows/Linux/macOS.
 #
@@ -398,6 +617,13 @@ PRE_PUSH_HOOK = r"""#!/usr/bin/env sh
 set -eu
 echo "[caddis] pre-push quality gate"
 fail=0
+if command -v dirname >/dev/null 2>&1; then
+  GATE_RUN="$(dirname "$0")/caddis_gate_step.py"
+elif [ -n "${0%/*}" ] && [ "${0%/*}" != "$0" ]; then
+  GATE_RUN="${0%/*}/caddis_gate_step.py"
+else
+  GATE_RUN="./caddis_gate_step.py"
+fi
 
 # Prefer the project's virtualenv over PATH. Checked in venv-layout order for both
 # Windows (Scripts/) and POSIX (bin/) so the same hook works on either.
@@ -424,10 +650,20 @@ py_sources_exist() {
 
 py_gate() {
   tool=$1; shift
+  timeout=300
+  case "$tool" in
+    ruff) timeout=300 ;;
+    mypy) timeout=600 ;;
+    pytest) timeout=1200 ;;
+  esac
   if py_has "$tool"; then
-    echo "[gate] $tool $*"
     rc=0
-    "$PY" -m "$tool" "$@" || rc=$?
+    if [ -f "$GATE_RUN" ]; then
+      "$PY" "$GATE_RUN" --name "$tool" --timeout "$timeout" -- "$PY" -m "$tool" "$@" || rc=$?
+    else
+      echo "[gate] $tool $*"
+      "$PY" -m "$tool" "$@" || rc=$?
+    fi
     if [ "$rc" -ne 0 ]; then
   # pytest exit 5 = "no tests collected". A repo that has not written tests yet is not a
   # failing repo, and blocking it would hit exactly the fresh-scaffold case this fix exists
@@ -457,9 +693,15 @@ if [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
   fi
 fi
 if [ -f "package.json" ] && command -v npm >/dev/null 2>&1; then
-  npm run 2>/dev/null | grep -q " lint"      && { echo "[gate] npm run lint"; npm run lint --silent || fail=1; }
-  npm run 2>/dev/null | grep -q " typecheck" && { echo "[gate] npm run typecheck"; npm run typecheck --silent || fail=1; }
-  npm run 2>/dev/null | grep -q " test"       && { echo "[gate] npm test"; npm test --silent || fail=1; }
+  if [ -f "$GATE_RUN" ] && [ -n "$PY" ]; then
+    npm run 2>/dev/null | grep -q " lint"      && { "$PY" "$GATE_RUN" --name npm-lint --timeout 600 -- npm run lint --silent || fail=1; }
+    npm run 2>/dev/null | grep -q " typecheck" && { "$PY" "$GATE_RUN" --name npm-typecheck --timeout 600 -- npm run typecheck --silent || fail=1; }
+    npm run 2>/dev/null | grep -q " test"       && { "$PY" "$GATE_RUN" --name npm-test --timeout 1200 -- npm test --silent || fail=1; }
+  else
+    npm run 2>/dev/null | grep -q " lint"      && { echo "[gate] npm run lint"; npm run lint --silent || fail=1; }
+    npm run 2>/dev/null | grep -q " typecheck" && { echo "[gate] npm run typecheck"; npm run typecheck --silent || fail=1; }
+    npm run 2>/dev/null | grep -q " test"       && { echo "[gate] npm test"; npm test --silent || fail=1; }
+  fi
 fi
 # Doc-coverage discipline (any stack). The checker exits non-zero ONLY on a hard invariant
 # (missing route / dangling doc-map link); soft signals warn without failing. Auto-skips when the
@@ -469,8 +711,12 @@ if [ -f "scripts/check_doc_coverage.py" ]; then
   DOC_PY="$PY"
   if [ -z "$DOC_PY" ]; then DOC_PY=$(command -v python || command -v python3 || true); fi
   if [ -n "$DOC_PY" ]; then
-    echo "[gate] doc coverage"
-    "$DOC_PY" scripts/check_doc_coverage.py --check || fail=1
+    if [ -f "$GATE_RUN" ]; then
+      "$DOC_PY" "$GATE_RUN" --name doc-coverage --timeout 120 -- "$DOC_PY" scripts/check_doc_coverage.py --check || fail=1
+    else
+      echo "[gate] doc coverage"
+      "$DOC_PY" scripts/check_doc_coverage.py --check || fail=1
+    fi
   fi
 fi
 if [ "$fail" -ne 0 ]; then
@@ -491,6 +737,7 @@ def install_git_hooks(target: Path, force: bool, dry: bool) -> list[str]:
         return ["pre-push gate: .git is a worktree pointer — skipped (install manually if wanted)"]
     hooks_dir = git / "hooks"
     dest = hooks_dir / "pre-push"
+    step_dest = hooks_dir / "caddis_gate_step.py"
     if dest.exists() and not force:
         _hook_txt = dest.read_text(encoding="utf-8", errors="ignore")
         managed = "caddis" in _hook_txt or "claudster" in _hook_txt  # recognise pre-rename hooks too
@@ -498,12 +745,14 @@ def install_git_hooks(target: Path, force: bool, dry: bool) -> list[str]:
     if not dry:
         hooks_dir.mkdir(parents=True, exist_ok=True)
         dest.write_text(PRE_PUSH_HOOK, encoding="utf-8", newline="\n")
+        step_dest.write_text(GATE_STEP_PY, encoding="utf-8", newline="\n")
         try:
-            import os, stat
+            import stat
             dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+            step_dest.chmod(step_dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
         except Exception:
             pass
-    notes.append("pre-push gate: installed .git/hooks/pre-push (green-before-push enforced)")
+    notes.append("pre-push gate: installed .git/hooks/pre-push and caddis_gate_step.py (green-before-push enforced)")
     return notes
 
 

package/bundles/manifest.json

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

package/package.json

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