@caddis/cli 0.4.61 → 0.4.63

package/bundles/antigravity-plugin/caddis_statusline.py

@@ -71,8 +71,9 @@ DEFAULT_CONFIG = {
     "bar_width": 8,
     "token_counts": True,   # ◉ 412k/1M  — off falls back to a bare ctx:41%
     "cached_tokens": True,  # ⚡38k cached — rendered LOUD, see render_claude()
-    "ram": True,            # 💻 69% (44 GB)
-    "clock": True,          # ◷ 03:41
+    "ram": False,           # 💻 69% (44 GB) - off by default (owner, 20 Oct 2026)
+    "thinking": False,      # Claude's "thinking" flag, agy's "thinking" state - off by default (20 Oct 2026)
+    "clock": False,         # ◷ 03:41 - off by default (owner, 20 Oct 2026)
     "relay": True,          # ⏺ relay  (a parked resume pointer exists)
     "rate_limits": True,    # 5h:12% 7d:40%
     "session_id": False,    # #a1b2c3d4
@@ -468,7 +469,7 @@ def cached_segment(c: C, cfg: dict, cached: int) -> str:
 
 
 def ram_segment(c: C, cfg: dict) -> str:
-    if not cfg.get("ram", True):
+    if not cfg.get("ram", False):
         return ""
     min_w = as_int(cfg.get("ram_min_width"), 0)
     if min_w and term_width() < min_w:
@@ -482,7 +483,7 @@ def ram_segment(c: C, cfg: dict) -> str:
 
 
 def clock_segment(c: C, cfg: dict) -> str:
-    if not cfg.get("clock", True):
+    if not cfg.get("clock", False):
         return ""
     return c.dim + icon(cfg, "clock") + time.strftime("%H:%M") + c.reset
 
@@ -549,7 +550,7 @@ def render_claude(data: dict, cfg: dict) -> str:
     if style and str(style).lower() != "default":
         parts.append(c.blue + "style:" + str(style) + c.reset)
 
-    if dig(data, "thinking", "enabled") is True:
+    if cfg.get("thinking", False) and dig(data, "thinking", "enabled") is True:
         parts.append(c.magenta + "thinking" + c.reset)
 
     if cfg.get("rate_limits", True):
@@ -581,7 +582,7 @@ def render_claude(data: dict, cfg: dict) -> str:
 
     session_name = dig(data, "session_name")
     if session_name:
-        parts.append(c.dim + '"' + str(session_name) + '"' + c.reset)
+        parts.append(c.bold + c.magenta + str(session_name) + c.reset)  # bright, so the session is easy to spot
 
     if cfg.get("session_id", False):
         sid = str(dig(data, "session_id") or "")
@@ -616,6 +617,8 @@ def render_agy(data: dict, cfg: dict) -> str:
         parts.append(c.white + c.bold + "agy" + c.reset)
 
     state = str(dig(data, "agent_state") or dig(data, "execution_mode") or "").lower()
+    if state == "thinking" and not cfg.get("thinking", False):
+        state = ""  # working and idle still show
     if state:
         label, col = {
             "working": (icon(cfg, "bolt") + "working", c.green),
@@ -704,6 +707,61 @@ HOST_SETTINGS = {
 }
 
 
+VERSION_STAMP = INSTALL_DIR / "statusline.version"
+
+
+def plugin_version(here: Path | None = None) -> str:
+    """The caddis version of the plugin this file ships in: `.claude-plugin/plugin.json` or a root `plugin.json`
+    one folder above `scripts/`. "" in a source checkout or when unreadable."""
+    base = Path(here or Path(__file__).resolve().parent).parent
+    for manifest in (base / ".claude-plugin" / "plugin.json", base / "plugin.json"):
+        try:
+            data = json.loads(manifest.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        if isinstance(data, dict) and str(data.get("name", "")).startswith("caddis") and data.get("version"):
+            return str(data["version"])
+    return ""
+
+
+def _version_key(text: str):
+    parts = str(text or "").strip().split(".")
+    return tuple(int(x) for x in parts) if parts and all(x.isdigit() for x in parts) else None
+
+
+def refresh_installed(src: Path | None = None, version: str | None = None) -> bool:
+    """Bring the installed renderer (`~/.caddis/statusline.py`) up to this plugin's copy.
+
+    Why (20 Oct 2026): only `--install` copied the renderer, so a caddis update never reached it. This machine
+    kept a copy whose `git` calls opened a console window each time agy drew its status line.
+    Rules: nothing happens unless the status line was installed; the copy happens only when this plugin's version
+    is newer than the one stamped at the last copy (an older session never downgrades it); a source checkout
+    (no plugin version) never copies. Returns True when it copied."""
+    src = Path(src or Path(__file__).resolve())
+    version = plugin_version() if version is None else version
+    if not INSTALLED_SCRIPT.is_file() or _version_key(version) is None:
+        return False
+    try:
+        stamped = VERSION_STAMP.read_text(encoding="utf-8").strip()
+    except OSError:
+        stamped = ""
+    old = _version_key(stamped)
+    if old is not None and old >= _version_key(version):
+        return False
+    try:
+        if src.resolve() != INSTALLED_SCRIPT.resolve() and src.read_bytes() != INSTALLED_SCRIPT.read_bytes():
+            tmp = INSTALLED_SCRIPT.with_name("%s.%d.tmp" % (INSTALLED_SCRIPT.name, os.getpid()))
+            shutil.copyfile(str(src), str(tmp))
+            os.replace(str(tmp), str(INSTALLED_SCRIPT))
+            copied = True
+        else:
+            copied = False
+        VERSION_STAMP.write_text(version + "\n", encoding="utf-8")
+        return copied
+    except OSError:
+        return False  # a session start must never fail over the status line
+
+
 def python_command() -> str:
     """The interpreter NAME to write into settings — not an absolute path.
 
@@ -726,6 +784,14 @@ def install(hosts, dry_run: bool = False) -> int:
     # because the version is in the path.
     if not dry_run and src != INSTALLED_SCRIPT.resolve():
         shutil.copyfile(str(src), str(INSTALLED_SCRIPT))
+    if not dry_run:
+        # Stamp the version, so a later --refresh from an OLDER plugin session cannot replace this copy.
+        version = plugin_version()
+        if _version_key(version) is not None:
+            try:
+                VERSION_STAMP.write_text(version + "\n", encoding="utf-8")
+            except OSError:
+                pass
     print("renderer -> %s" % INSTALLED_SCRIPT)
 
     if not CONFIG_PATH.exists():
@@ -903,8 +969,14 @@ def main(argv=None) -> int:
     parser.add_argument("--dry-run", action="store_true", help="with --install: print, write nothing")
     parser.add_argument("--no-color", action="store_true", help="render without ANSI colour")
     parser.add_argument("--title", action="store_true", help="render terminal title (agy)")
+    parser.add_argument("--refresh", action="store_true",
+                        help="copy this plugin's renderer over an older installed one (session-start hook)")
     args = parser.parse_args(argv)
 
+    if args.refresh:
+        refresh_installed()
+        return 0  # silent and never failing: it runs at every session start
+
     # The line is Unicode. On Windows the default cp1252 stdout raises on ◆/⎇/█.
     try:
         sys.stdout.reconfigure(encoding="utf-8", errors="replace")

package/bundles/antigravity-plugin/guard_agy.py

@@ -953,7 +953,8 @@ def shared_checkout_reason(command: str, root: str | None) -> str:
         if _moves_tree(sub, args, cwd) and _declares_shared(cwd):
             return (f"`git {sub.lower()}` moves the tree of a shared checkout (AGENTS.md says Shared checkout: yes; "
                     "a dev service or a peer uses it). Work in your own worktree instead: "
-                    "`git worktree add \"$TEMP/<name>\" -b <branch> origin/<default>`, and remove it when done")
+                    "`git worktree add <worktree root>/<repo>/<name> -b <branch> origin/<default>` (never under %TEMP%: "
+                    "`caddis_worktree_root.py <name>` prints the path), and remove it when done")
     return ""
 
 

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.147",
+  "version": "1.3.149",
   "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/repo_freshness.py

@@ -31,6 +31,7 @@ Ported into caddis 2026-09-12 from a personal hook that existed on one machine o
 from __future__ import annotations
 
 import json
+import math
 import os
 import re
 import signal
@@ -366,10 +367,21 @@ def _fetch(cwd: str) -> "bool | None":
         return False
 
 
+def _budget_s() -> float:
+    """TOTAL_BUDGET_S, or a larger budget from CADDIS_FRESHNESS_BUDGET_S. Only the tests set it: on a busy CI runner
+    the git calls before the fetch can use up 18 s, and the hook then rightly skips the fetch, which made tests about
+    the fetch fail at random (20 Oct 2026). An unset, empty or bad value means TOTAL_BUDGET_S."""
+    try:
+        value = float(os.environ.get("CADDIS_FRESHNESS_BUDGET_S", ""))
+    except ValueError:
+        return TOTAL_BUDGET_S
+    return value if math.isfinite(value) and value > 0 else TOTAL_BUDGET_S
+
+
 def report(cwd: str, own_session_id: str = "") -> list[str]:
     """The lines to print. Empty when there is nothing worth saying."""
     global _deadline
-    _deadline = time.monotonic() + TOTAL_BUDGET_S
+    _deadline = time.monotonic() + _budget_s()
     try:
         return _report(cwd, own_session_id)
     finally:

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

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""caddis_hidden_desktop - run a command on a separate, invisible Windows desktop.
+
+Why (20 Oct 2026, seen on the owner's screen): agy starts its own tool processes (shell commands, MCP servers) as
+visible consoles, so every agy call flashed windows on the desktop. CREATE_NO_WINDOW and SW_HIDE on agy do not
+reach those grandchildren. A process started on another desktop opens all its windows there, and its children
+inherit that desktop, so nothing appears on the owner's screen.
+
+    python caddis_hidden_desktop.py -- <program> [args...]
+
+- Creates (or opens, when it exists) the desktop "caddis-hidden" in this process's window station and starts the
+  command on it with CREATE_NO_WINDOW. The command inherits this process's stdin, stdout and stderr handles, its
+  environment and its working directory.
+- The command runs in a job object with KILL_ON_JOB_CLOSE: when this launcher ends for any reason (normal exit,
+  Ctrl-C, taskkill), the command and everything it started end too.
+- Exits with the command's exit code.
+- When the hidden desktop cannot be used, runs the command normally (CREATE_NO_WINDOW) and says so on stderr once.
+  Hiding never makes a call fail. A program that does not exist exits 127.
+- On other operating systems it just runs the command.
+
+caddis_spend.hidden_argv() builds the command line that uses this file; set CADDIS_AGY_VISIBLE=1 to opt out.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+DESKTOP_NAME = "caddis-hidden"
+CREATE_NO_WINDOW = 0x08000000
+EXIT_NOT_FOUND = 127
+EXIT_INTERRUPTED = 130
+
+
+def _signed(code: int) -> int:
+    """A DWORD exit code as the signed int sys.exit accepts on Windows (same bits for ExitProcess)."""
+    return code - (1 << 32) if code >= (1 << 31) else code
+
+
+def _fallback(argv: list[str], reason: str) -> int:
+    print(f"caddis_hidden_desktop: {reason}; running the command on the normal desktop", file=sys.stderr, flush=True)
+    return _run_plain(argv)
+
+
+def _run_plain(argv: list[str]) -> int:
+    flags = {"creationflags": CREATE_NO_WINDOW} if os.name == "nt" else {}
+    try:
+        proc = subprocess.Popen(argv, **flags)
+    except FileNotFoundError:
+        print(f"caddis_hidden_desktop: command not found: {argv[0]}", file=sys.stderr, flush=True)
+        return EXIT_NOT_FOUND
+    try:
+        return proc.wait()
+    except BaseException:
+        proc.kill()
+        raise
+
+
+def _run_hidden(argv: list[str], started: list[bool]) -> int:  # pragma: no cover - Windows only
+    """Sets started[0] once the command runs: from then on an error must never start it a second time."""
+    import ctypes
+    import ctypes.wintypes as wt
+    import _winapi
+
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    u32 = ctypes.WinDLL("user32", use_last_error=True)
+
+    class STARTUPINFOW(ctypes.Structure):
+        _fields_ = [("cb", wt.DWORD), ("lpReserved", wt.LPWSTR), ("lpDesktop", wt.LPWSTR), ("lpTitle", wt.LPWSTR),
+                    ("dwX", wt.DWORD), ("dwY", wt.DWORD), ("dwXSize", wt.DWORD), ("dwYSize", wt.DWORD),
+                    ("dwXCountChars", wt.DWORD), ("dwYCountChars", wt.DWORD), ("dwFillAttribute", wt.DWORD),
+                    ("dwFlags", wt.DWORD), ("wShowWindow", wt.WORD), ("cbReserved2", wt.WORD),
+                    ("lpReserved2", ctypes.c_void_p), ("hStdInput", wt.HANDLE), ("hStdOutput", wt.HANDLE),
+                    ("hStdError", wt.HANDLE)]
+
+    class PROCESS_INFORMATION(ctypes.Structure):
+        _fields_ = [("hProcess", wt.HANDLE), ("hThread", wt.HANDLE), ("dwProcessId", wt.DWORD),
+                    ("dwThreadId", wt.DWORD)]
+
+    class IO_COUNTERS(ctypes.Structure):
+        _fields_ = [(n, ctypes.c_ulonglong) for n in ("ReadOps", "WriteOps", "OtherOps", "ReadBytes", "WriteBytes",
+                                                     "OtherBytes")]
+
+    class JOBOBJECT_BASIC_LIMIT_INFORMATION(ctypes.Structure):
+        _fields_ = [("PerProcessUserTimeLimit", ctypes.c_longlong), ("PerJobUserTimeLimit", ctypes.c_longlong),
+                    ("LimitFlags", wt.DWORD), ("MinimumWorkingSetSize", ctypes.c_size_t),
+                    ("MaximumWorkingSetSize", ctypes.c_size_t), ("ActiveProcessLimit", wt.DWORD),
+                    ("Affinity", ctypes.c_size_t), ("PriorityClass", wt.DWORD), ("SchedulingClass", wt.DWORD)]
+
+    class JOBOBJECT_EXTENDED_LIMIT_INFORMATION(ctypes.Structure):
+        _fields_ = [("BasicLimitInformation", JOBOBJECT_BASIC_LIMIT_INFORMATION), ("IoInfo", IO_COUNTERS),
+                    ("ProcessMemoryLimit", ctypes.c_size_t), ("JobMemoryLimit", ctypes.c_size_t),
+                    ("PeakProcessMemoryUsed", ctypes.c_size_t), ("PeakJobMemoryUsed", ctypes.c_size_t)]
+
+    GENERIC_ALL = 0x10000000
+    CREATE_SUSPENDED = 0x00000004
+    STARTF_USESTDHANDLES = 0x00000100
+    UOI_NAME = 2
+    WAIT_OBJECT_0 = 0
+    JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
+    JobObjectExtendedLimitInformation = 9
+
+    u32.GetProcessWindowStation.restype = wt.HANDLE
+    u32.GetUserObjectInformationW.argtypes = [wt.HANDLE, ctypes.c_int, ctypes.c_void_p, wt.DWORD,
+                                              ctypes.POINTER(wt.DWORD)]
+    u32.CreateDesktopW.restype = wt.HANDLE
+    u32.CreateDesktopW.argtypes = [wt.LPCWSTR, wt.LPCWSTR, ctypes.c_void_p, wt.DWORD, wt.DWORD, ctypes.c_void_p]
+    u32.CloseDesktop.argtypes = [wt.HANDLE]
+    k32.CreateProcessW.argtypes = [wt.LPCWSTR, wt.LPWSTR, ctypes.c_void_p, ctypes.c_void_p, wt.BOOL, wt.DWORD,
+                                   ctypes.c_void_p, wt.LPCWSTR, ctypes.POINTER(STARTUPINFOW),
+                                   ctypes.POINTER(PROCESS_INFORMATION)]
+    k32.CreateJobObjectW.restype = wt.HANDLE
+    k32.CreateJobObjectW.argtypes = [ctypes.c_void_p, wt.LPCWSTR]
+    k32.SetInformationJobObject.argtypes = [wt.HANDLE, ctypes.c_int, ctypes.c_void_p, wt.DWORD]
+    k32.AssignProcessToJobObject.argtypes = [wt.HANDLE, wt.HANDLE]
+    k32.TerminateJobObject.argtypes = [wt.HANDLE, wt.UINT]
+    k32.ResumeThread.argtypes = [wt.HANDLE]
+    k32.WaitForSingleObject.argtypes = [wt.HANDLE, wt.DWORD]
+    k32.WaitForSingleObject.restype = wt.DWORD
+    k32.GetExitCodeProcess.argtypes = [wt.HANDLE, ctypes.POINTER(wt.DWORD)]
+    k32.CloseHandle.argtypes = [wt.HANDLE]
+
+    # The desktop must live in this process's window station (WinSta0 for a logged-on user, another one for a
+    # service); a desktop path in a station the process cannot reach makes CreateProcessW fail.
+    station = "WinSta0"
+    buf = ctypes.create_unicode_buffer(256)
+    needed = wt.DWORD()
+    hsta = u32.GetProcessWindowStation()
+    if hsta and u32.GetUserObjectInformationW(hsta, UOI_NAME, buf, ctypes.sizeof(buf), ctypes.byref(needed)):
+        station = buf.value or station
+
+    hdesk = u32.CreateDesktopW(DESKTOP_NAME, None, None, 0, GENERIC_ALL, None)  # opens it when it exists
+    if not hdesk:
+        return _fallback(argv, f"cannot create the hidden desktop (error {ctypes.get_last_error()})")
+
+    me = _winapi.GetCurrentProcess()
+    inherited: list[int] = []
+
+    def inheritable(which: int) -> int:
+        handle = _winapi.GetStdHandle(which)
+        if not handle or handle == _winapi.INVALID_HANDLE_VALUE:
+            return 0
+        try:
+            dup = _winapi.DuplicateHandle(me, handle, me, 0, True, _winapi.DUPLICATE_SAME_ACCESS)
+        except OSError:
+            return 0
+        inherited.append(dup)
+        return dup
+
+    job = None
+    pi = PROCESS_INFORMATION()
+    try:
+        si = STARTUPINFOW()
+        si.cb = ctypes.sizeof(si)
+        si.lpDesktop = f"{station}\\{DESKTOP_NAME}"
+        si.dwFlags = STARTF_USESTDHANDLES
+        si.hStdInput = inheritable(_winapi.STD_INPUT_HANDLE)
+        si.hStdOutput = inheritable(_winapi.STD_OUTPUT_HANDLE)
+        si.hStdError = inheritable(_winapi.STD_ERROR_HANDLE)
+        cmdline = ctypes.create_unicode_buffer(subprocess.list2cmdline(argv))
+        if not k32.CreateProcessW(None, cmdline, None, None, True, CREATE_NO_WINDOW | CREATE_SUSPENDED, None, None,
+                                  ctypes.byref(si), ctypes.byref(pi)):
+            error = ctypes.get_last_error()
+            if error in (2, 3):  # ERROR_FILE_NOT_FOUND, ERROR_PATH_NOT_FOUND
+                print(f"caddis_hidden_desktop: command not found: {argv[0]}", file=sys.stderr, flush=True)
+                return EXIT_NOT_FOUND
+            return _fallback(argv, f"cannot start the command on the hidden desktop (error {error})")
+        started[0] = True
+        for dup in inherited:  # the child has its own copies now
+            _winapi.CloseHandle(dup)
+        inherited.clear()
+
+        job = k32.CreateJobObjectW(None, None)
+        if job:
+            info = JOBOBJECT_EXTENDED_LIMIT_INFORMATION()
+            info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+            if not (k32.SetInformationJobObject(job, JobObjectExtendedLimitInformation, ctypes.byref(info),
+                                                ctypes.sizeof(info))
+                    and k32.AssignProcessToJobObject(job, pi.hProcess)):
+                k32.CloseHandle(job)  # the caller's taskkill /T still reaches the child through its parent id
+                job = None
+        k32.ResumeThread(pi.hThread)
+        try:
+            # Short waits so Ctrl-C gets through. Loop only on a timeout: WAIT_FAILED (a bad handle) must not spin.
+            while k32.WaitForSingleObject(pi.hProcess, 200) == 0x00000102:  # WAIT_TIMEOUT
+                pass
+        except KeyboardInterrupt:
+            if job:
+                k32.TerminateJobObject(job, EXIT_INTERRUPTED)
+            else:
+                _winapi.TerminateProcess(int(pi.hProcess), EXIT_INTERRUPTED)
+            return EXIT_INTERRUPTED
+        code = wt.DWORD()
+        k32.GetExitCodeProcess(pi.hProcess, ctypes.byref(code))
+        return _signed(code.value)
+    finally:
+        for dup in inherited:
+            _winapi.CloseHandle(dup)
+        if pi.hThread:
+            k32.CloseHandle(pi.hThread)
+        if pi.hProcess:
+            k32.CloseHandle(pi.hProcess)
+        if job:
+            k32.CloseHandle(job)  # KILL_ON_JOB_CLOSE: anything the command left running ends here
+        u32.CloseDesktop(hdesk)
+
+
+def run(argv: list[str]) -> int:
+    if not argv:
+        print("usage: caddis_hidden_desktop.py -- <program> [args...]", file=sys.stderr)
+        return 2
+    if os.name != "nt":
+        return _run_plain(argv)
+    started = [False]
+    try:
+        return _run_hidden(argv, started)
+    except Exception as exc:
+        if started[0]:  # it ran (and may have spent): never run it twice; the job already ended it
+            raise
+        return _fallback(argv, f"hidden desktop failed ({exc!r})")  # never fail a call because hiding failed
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if args[:1] == ["--"]:
+        args = args[1:]
+    return run(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -612,6 +612,7 @@ def run_lane(
         if spend_id is None:
             return _refused_run(1, "caddis_spend: over cap: agy refused ("
                                 + caddis_spend.status_line(spend_home, datetime.now(timezone.utc)) + ")")
+        argv = caddis_spend.hidden_argv(argv, env)  # agy's tool consoles open on a hidden desktop, not on screen
     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:
@@ -1081,7 +1082,7 @@ def _probe_agy_models() -> str:
         return ""
     try:
         proc = subprocess.run(
-            [agy, "models"], capture_output=True, text=True, encoding="utf-8", errors="replace",
+            caddis_spend.hidden_argv([agy, "models"]), capture_output=True, text=True, encoding="utf-8", errors="replace",
             timeout=AGY_PROBE_TIMEOUT_S, check=False, stdin=subprocess.DEVNULL,
         )
     except (OSError, subprocess.SubprocessError):
@@ -2249,7 +2250,7 @@ def _accept_command(
     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), "
+              "Run the programme from a worktree of origin/<default> (git worktree add; `caddis_worktree_root.py` prints the path, never %TEMP%), "
               "or pass --allow-shared to fast-forward here anyway")
         return EXIT_USAGE
     if unsafe:

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

@@ -2231,6 +2231,9 @@ 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("--site", default=None, metavar="DIR",
+                   help="with --all: build the shared copy (no live sessions or runners, a banner) in DIR/build and "
+                        "publish only the safe files to DIR/public (for GitHub Pages)")
     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,
@@ -2287,15 +2290,17 @@ def _take_render_lock(lock: Path) -> bool:
     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."""
+def _render(root: Path, args: argparse.Namespace, site_dir: Path | None = None) -> int:
+    """`render`: the pages, the prune and the hub. The caller holds the repo's render lock. `site_dir` (the shared
+    copy's build folder, `render --site`) replaces the pages root and takes no lock."""
     import caddis_roadmap_page
     slugs, on_origin = list_roadmaps_checked(root) if args.all else ([args.roadmap], None)
     failed = written = pruned = 0
+    site_kw = {} if site_dir is None else {"site_dir": site_dir}  # the normal calls stay exactly as they were
     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,
-                                                  _THIS_MODULE)
+                                                  _THIS_MODULE, **site_kw)
             if path is None:  # a newer caddis owns this page: kept, and neither written nor failed
                 continue
             written += 1
@@ -2309,15 +2314,57 @@ def _render(root: Path, args: argparse.Namespace) -> int:
         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
+                caddis_roadmap_page.default_page_path(root, "_", base=site_dir).parent, on_origin | set(slugs))
+        if site_dir is not None:
+            site_kw["banner"] = caddis_roadmap_page.site_banner(root)
+        hub = caddis_roadmap_page.write_hub(**site_kw) 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)
+        if site_dir is not None:  # the shared copy is published, so a hub that failed is a failed render
+            failed += 1
+    if site_dir is not None and not failed and not written:
+        print("[ROADMAP] site not rendered: no roadmap was rendered (none on origin, or the listing failed)",
+              file=sys.stderr)
+        return caddis_exit.BLOCKED
     return caddis_exit.BLOCKED if failed else caddis_exit.CLEAN
 
 
+def _render_site(root: Path, args: argparse.Namespace) -> int:
+    """`render --all --site DIR`: build the shared copy in DIR/build (no render lock, no version gate, no stamp: CI is
+    the only writer), then publish its allow-list to DIR/public. A render that failed publishes nothing."""
+    import caddis_roadmap_page
+    site = Path(args.site)
+    build, public = site / "build", site / "public"
+    global FETCH
+    FETCH = not args.no_fetch
+    try:  # a reused DIR keeps the last run's index.html: only one written by THIS run may be published
+        (build / "index.html").unlink(missing_ok=True)
+    except OSError as exc:
+        raise RoadmapError(f"site not published: the old {build / 'index.html'} cannot be removed: {exc}",
+                           caddis_exit.ERROR) from exc
+    try:
+        code = _render(root, args, site_dir=build)
+    finally:
+        FETCH = True
+    if code != caddis_exit.CLEAN:
+        print("[ROADMAP] site not published: the render did not finish clean (see above); the last public/ is kept",
+              file=sys.stderr)
+        return code
+    if not (build / "index.html").is_file():
+        print("[ROADMAP] site not published: the hub (index.html) was not written", file=sys.stderr)
+        return caddis_exit.BLOCKED
+    try:
+        paths = caddis_roadmap_page.export_site(build, public)
+    except ValueError as exc:
+        raise RoadmapError(f"site not published: {exc}", caddis_exit.ERROR) from exc
+    for rel in paths:
+        print(f"[ROADMAP] site file: {rel}")
+    print(f"[ROADMAP] site published: {len(paths)} file(s) in {public.resolve()}")
+    return caddis_exit.CLEAN
+
+
 def _dispatch(args: argparse.Namespace) -> int:
     root = _repo_root(args.root)
     if args.cmd == "list":
@@ -2361,6 +2408,16 @@ def _dispatch(args: argparse.Namespace) -> int:
         return recheck(root, args.roadmap, args.dry_run)
     if args.cmd == "render":
         import caddis_roadmap_page  # the page is separate; only `render` needs it
+        if args.site is not None:
+            if args.out:
+                raise RoadmapError("--site and --out cannot be used together: --out is one self-contained page, "
+                                   "--site is the shared copy of every roadmap", caddis_exit.ERROR)
+            if not args.all:
+                raise RoadmapError("--site works with --all, not with --roadmap", caddis_exit.ERROR)
+            if args.delay > 0:
+                raise RoadmapError("--site and --delay cannot be used together: a CI render does not wait",
+                                   caddis_exit.ERROR)
+            return _render_site(root, args)
         if args.all and args.out:
             raise RoadmapError("--out works with one --roadmap, not with --all", caddis_exit.ERROR)
         if args.delay > 0: