@caddis/cli 0.4.61 → 0.4.63

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

@@ -42,6 +42,8 @@ CLI:
         CADDIS_SPEND_RUN_TIMEOUT_S, else 3600 s) and its process tree was killed. 75 and 78 are never
         agy's own codes for a refusal, so a caller can tell "the cap refused" from "agy failed". Each
         refusal also prints a `caddis_spend:` line.
+        On Windows the command runs on a hidden desktop (caddis_hidden_desktop.py), so the console windows agy opens
+        for its tools never show; CADDIS_AGY_VISIBLE=1 runs it on the normal desktop.
 """
 
 from __future__ import annotations
@@ -50,6 +52,7 @@ import argparse
 import json
 import math
 import os
+import shutil
 import subprocess
 import sys
 import time
@@ -385,11 +388,30 @@ def _kill_tree(proc: subprocess.Popen) -> None:
         pass
 
 
+HIDDEN_DESKTOP_SCRIPT = Path(__file__).with_name("caddis_hidden_desktop.py")
+AGY_VISIBLE_VAR = "CADDIS_AGY_VISIBLE"
+
+
+def hidden_argv(argv: list[str], env: dict | None = None) -> list[str]:
+    """`argv` wrapped to run on the hidden desktop (caddis_hidden_desktop.py), so the console windows agy opens for
+    its tools never show on the owner's screen. Unchanged when: not Windows, env CADDIS_AGY_VISIBLE=1, the launcher
+    is not beside this file, or the program is not found. In the last case the caller's own start raises
+    FileNotFoundError as before; the program is resolved here, so the launcher never has to report it."""
+    env = os.environ if env is None else env
+    if os.name != "nt" or not argv or env.get(AGY_VISIBLE_VAR) == "1" or not HIDDEN_DESKTOP_SCRIPT.is_file():
+        return list(argv)
+    program = shutil.which(argv[0], path=env.get("PATH"))
+    if program is None:
+        return list(argv)
+    return [sys.executable, str(HIDDEN_DESKTOP_SCRIPT), "--", program, *argv[1:]]
+
+
 def _run_child(argv: list[str], env: dict, timeout_s: float) -> tuple[int | None, str, str]:
-    """Run `argv` with a time limit. Returns (returncode, stdout, stderr); returncode is None on a timeout, after
-    the whole process tree was killed. Raises FileNotFoundError when the program does not exist."""
+    """Run `argv` with a time limit, on the hidden desktop on Windows (hidden_argv). Returns (returncode, stdout,
+    stderr); returncode is None on a timeout, after the whole process tree was killed. Raises FileNotFoundError when
+    the program does not exist."""
     group = {} if os.name == "nt" else {"start_new_session": True}
-    proc = subprocess.Popen(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8",
+    proc = subprocess.Popen(hidden_argv(argv, env), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8",
                             errors="replace", env=env, **_NO_WINDOW_KW, **group)
     try:
         out, err = proc.communicate(timeout=timeout_s)

package/bundles/antigravity-plugin/scripts/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/scripts/caddis_todo.py

@@ -43,7 +43,10 @@ def _path(root: Path, workstream: str | None) -> tuple[Path, Path]:
     artifact = _artifact(root)
     name = _name(workstream) if workstream is not None else "inbox"
     folder = artifact / "todo-list"
-    if folder.is_symlink() or not folder.resolve().is_relative_to(artifact.resolve()):
+    # Only a folder that EXISTS can point elsewhere. Resolving one that does not exist yet raced a concurrent
+    # writer creating it: on Windows the two paths could resolve differently (a short 8.3 name on one side), and a
+    # safe add failed with this error (main CI, 20 Oct 2026, test_concurrent_inbox_add_loses_no_item).
+    if folder.is_symlink() or (folder.exists() and not folder.resolve().is_relative_to(artifact.resolve())):
         raise ValueError("todo-list path escapes artifact root")
     path = folder / f"{name}.md"
     # Reads are unlocked, so refuse here as well as in locked_path. On Windows a writer replacing the file

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

@@ -58,7 +58,9 @@ def _plain_name(value: str) -> str:
 def _artifact(root: Path) -> Path:
     project = Path(root).resolve()
     artifact = Path(root) / ".caddis"
-    if not artifact.resolve().is_relative_to(project) or artifact.is_symlink():
+    # Only an existing .caddis can point elsewhere; resolving one that does not exist yet raced a concurrent writer
+    # creating it (see caddis_todo._path, 20 Oct 2026).
+    if artifact.is_symlink() or (artifact.exists() and not artifact.resolve().is_relative_to(project)):
         raise ValueError("artifact root escapes project")
     return artifact
 

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

@@ -0,0 +1,109 @@
+"""Where a NEW git worktree goes. One rule, one place; every caller and every doc uses it.
+
+Never %TEMP%: Windows cleanup / Storage Sense can empty it and delete a worktree that holds unmerged work (owner
+decision, 20 Oct 2026). The path is
+
+    <root>/<main checkout folder name>/<short-name>
+
+where <root> is, in order:
+  1. the `root` argument (a test seam and an explicit override);
+  2. the `CADDIS_WORKTREE_ROOT` environment variable, when set and not blank;
+  3. `<parent folder of the repo's MAIN checkout>/.worktrees`. For `E:\\Projects\\<repo>` that is
+     `E:\\Projects\\.worktrees\\<repo>\\<short-name>`. No machine path is written in code. There is no %TEMP% fallback.
+
+The main checkout is the parent of `git rev-parse --git-common-dir`, so the answer is the same from the main checkout,
+from a subfolder and from any linked worktree.
+
+Only the default for a NEW worktree lives here. A worktree that already exists, or whose path a runner recorded,
+stays where it is: moving it breaks a venv, which keeps absolute paths.
+
+    worktree_root(repo, root=None)            -> the folder that holds the per-repo folders
+    worktree_path(repo, short_name, root=None) -> the path for a new worktree (nothing is created)
+    main_checkout(repo)                       -> the main checkout's folder
+
+CLI: `python caddis_worktree_root.py [--repo PATH] [--root PATH] <short-name>` prints the path. Exit 2 on a bad name
+or a folder that is not in a git repo.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ENV_VAR = "CADDIS_WORKTREE_ROOT"
+FALLBACK_DIR = ".worktrees"
+
+
+class NotARepoError(RuntimeError):
+    """The folder is not inside a git repository."""
+
+
+def _git_out(cwd: Path, *args: str) -> str | None:
+    try:
+        res = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, encoding="utf-8",
+                             errors="replace", stdin=subprocess.DEVNULL, check=False)
+    except OSError:
+        return None
+    return res.stdout.strip() if res.returncode == 0 else None
+
+
+def main_checkout(repo: Path | str) -> Path:
+    """The MAIN checkout's folder for `repo` (the main checkout, a subfolder of it or a linked worktree).
+
+    It is the parent of the git common dir. A common dir not named `.git` (a submodule's, a bare repo's) has no such
+    parent: then the work-tree top is used, or the common dir itself when there is no work tree."""
+    repo = Path(repo).absolute()
+    common = _git_out(repo, "rev-parse", "--git-common-dir") if repo.is_dir() else None
+    if not common:
+        raise NotARepoError(f"{repo} is not inside a git repository")
+    common_dir = Path(os.path.normpath(repo / common))  # relative to `repo`, or absolute already
+    if common_dir.name == ".git":
+        return common_dir.parent
+    top = _git_out(repo, "rev-parse", "--show-toplevel")
+    return Path(os.path.normpath(top)) if top else common_dir
+
+
+def _explicit_root(root: Path | str | None) -> Path | None:
+    """`root`, else `$CADDIS_WORKTREE_ROOT` when not blank, else None (the fallback needs the main checkout)."""
+    if root:
+        return Path(root)
+    env = os.environ.get(ENV_VAR, "").strip()
+    return Path(env) if env else None
+
+
+def worktree_root(repo: Path | str, root: Path | str | None = None) -> Path:
+    """The folder that holds one folder per repo: `root`, else `$CADDIS_WORKTREE_ROOT`, else
+    `<parent of the main checkout>/.worktrees`."""
+    return _explicit_root(root) or main_checkout(repo).parent / FALLBACK_DIR
+
+
+def worktree_path(repo: Path | str, short_name: str, root: Path | str | None = None) -> Path:
+    """The path for a NEW worktree of `repo`: `<root>/<main checkout folder name>/<short_name>`. Creates nothing.
+    `short_name` is one plain folder name: ValueError for an empty name, `.`, `..`, or one with a path separator or a
+    colon (a drive such as `C:foo` would replace the root on Windows)."""
+    if (not short_name or short_name in (".", "..") or any(c in short_name for c in "/\:")
+            or short_name != short_name.strip()):
+        raise ValueError(f"the short name must be one plain folder name, not {short_name!r}")
+    main = main_checkout(repo)  # one git call
+    return (_explicit_root(root) or main.parent / FALLBACK_DIR) / main.name / short_name
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Print the path for a new git worktree (never under %TEMP%).")
+    ap.add_argument("short_name", help="one folder name, e.g. fix-login")
+    ap.add_argument("--repo", default=".", help="any folder of the repo or of one of its worktrees (default: .)")
+    ap.add_argument("--root", default=None, help=f"override the root (default: ${ENV_VAR}, then <repo parent>/.worktrees)")
+    args = ap.parse_args(argv)
+    try:
+        print(worktree_path(args.repo, args.short_name, args.root))
+    except (ValueError, NotARepoError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundles/antigravity-plugin/skills/cloud-phases/SKILL.md

@@ -37,10 +37,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$TEMP/<repo>-rebase" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$TEMP/<repo>-<branch>" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -48,7 +48,9 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
     checkout has it out.
   - Remove each worktree you made when its step ends: `git worktree remove <worktree>`.
 
-`$TEMP` is `%TEMP%` (`$env:TEMP` in PowerShell). The caddis guard checks only the `Shared checkout: yes` line in
+`<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
+`$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
+cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

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

@@ -43,10 +43,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$TEMP/<repo>-rebase" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$TEMP/<repo>-<branch>" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -54,7 +54,9 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
     checkout has it out.
   - Remove each worktree you made when its step ends: `git worktree remove <worktree>`.
 
-`$TEMP` is `%TEMP%` (`$env:TEMP` in PowerShell). The caddis guard checks only the `Shared checkout: yes` line in
+`<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
+`$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
+cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

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

@@ -154,7 +154,7 @@ unattended; `-Plan <slug>` runs one plain plan instead (the two are exclusive).
    or the owner, or that has **no Lane line**, is not run (fail closed): the runner adds
    `block --type owner-gate --reason "phase <n> lane: <lane>"` (`lane: none` when there is no line) and goes on.
 3. A `todo` milestone is set `in-progress` (a docs PR). Every session of a roadmap runs in ONE dedicated worktree,
-   `%TEMP%/caddis-roadmap-<slug>-<8 hex of the repo's git common dir>`: made with `git worktree add --detach` from `origin/<default>` on the first
+   `<worktree root>/<repo>/caddis-roadmap-<slug>-<8 hex of the repo's git common dir>` (`$CADDIS_WORKTREE_ROOT`, else the `.worktrees` folder beside the main checkout, never `%TEMP%`; an existing recorded worktree stays where it is): made with `git worktree add --detach` from `origin/<default>` on the first
    session, reused on restart, recorded in the runner folder, never the `-Repo` checkout (plan mode keeps working in
    the given checkout). In that worktree the runner makes a fresh branch `caddis/roadmap/<slug>/<plan>-p<n>` from
    `origin/<default>` (it refuses a branch of that name already on origin that it did not make) and ONE session runs

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

@@ -42,10 +42,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$TEMP/<repo>-rebase" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$TEMP/<repo>-<branch>" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -53,7 +53,9 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
     checkout has it out.
   - Remove each worktree you made when its step ends: `git worktree remove <worktree>`.
 
-`$TEMP` is `%TEMP%` (`$env:TEMP` in PowerShell). The caddis guard checks only the `Shared checkout: yes` line in
+`<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
+`$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
+cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

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

@@ -41,10 +41,10 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
 
 - **On `SHARED: no`,** do the steps as written, in this checkout.
 - **On `SHARED: yes`,** never move this checkout. Leave its changes as they are, and report them. Instead:
-  - **Rebase:** `git worktree add --detach "$TEMP/<repo>-rebase" <branch>`, then
+  - **Rebase:** `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" rebase-<name>)" <branch>`, then
     `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
   - **Pull a branch to test it:** `git fetch origin`, then
-    `git worktree add --detach "$TEMP/<repo>-<branch>" origin/<branch>` (for the default branch,
+    `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name>)" origin/<branch>` (for the default branch,
     `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
   - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
     `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
@@ -52,7 +52,9 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
     checkout has it out.
   - Remove each worktree you made when its step ends: `git worktree remove <worktree>`.
 
-`$TEMP` is `%TEMP%` (`$env:TEMP` in PowerShell). The caddis guard checks only the `Shared checkout: yes` line in
+`<name>` is the branch name with each `/` written as `-`. `caddis_worktree_root.py` prints the path of a new worktree:
+`$CADDIS_WORKTREE_ROOT/<repo>/<short-name>`, else `<parent of the main checkout>/.worktrees/<repo>/<short-name>`. Never `%TEMP%`: Windows
+cleanup can empty it. The caddis guard checks only the `Shared checkout: yes` line in
 `AGENTS.md`, not a dirty tree: with that line, it asks before a tree move, and denies it in a headless session.
 <!-- /checkout-safety -->
 

package/bundles/antigravity-plugin/skills/using-git-worktrees/SKILL.md

@@ -31,13 +31,20 @@ If none is true, stop here and use `git switch -c`.
 1. Fetch: `git fetch origin`.
 2. Find the default branch (`main` in most repos): `git symbolic-ref --short refs/remotes/origin/HEAD`.
    It prints `origin/main`. Use the part after `origin/` as `<default>`.
-3. Create the worktree from `origin/<default>`, never from the local HEAD, under `%TEMP%`:
+3. Create the worktree from `origin/<default>`, never from the local HEAD, at
+   `<worktree root>\<repo>\<short-name>`. Never under `%TEMP%`: Windows cleanup (Storage Sense) can empty it
+   and delete a worktree that holds unmerged work. The worktree root is `$env:CADDIS_WORKTREE_ROOT` when set,
+   else the `.worktrees` folder beside the main checkout (for `E:\Projects\<repo>` that is
+   `E:\Projects\.worktrees\<repo>\<short-name>`). `<repo>` is the main checkout's folder name. The caddis
+   script `caddis_worktree_root.py` prints the path; use it so the rule lives in one place:
 
 ```powershell
-git worktree add -b <branch> "$env:TEMP\<repo>-<short-name>" origin/<default>
+$wt = python "<caddis scripts>\caddis_worktree_root.py" <short-name>   # run in the repo; prints the path
+git worktree add -b <branch> $wt origin/<default>
 ```
 
-   Do not create worktrees inside the repo (no `.worktrees/`).
+   `<caddis scripts>` is the `scripts` folder of the installed caddis plugin. Do not create worktrees inside the
+   repo. An existing worktree stays where it is: moving it breaks a venv, which keeps absolute paths.
 4. State the full path of the worktree. Work only there, and do not switch branches in it.
 
 ## Install dependencies fresh

package/bundles/codex/.codex/skills/devops/using-git-worktrees/SKILL.md

@@ -31,13 +31,20 @@ If none is true, stop here and use `git switch -c`.
 1. Fetch: `git fetch origin`.
 2. Find the default branch (`main` in most repos): `git symbolic-ref --short refs/remotes/origin/HEAD`.
    It prints `origin/main`. Use the part after `origin/` as `<default>`.
-3. Create the worktree from `origin/<default>`, never from the local HEAD, under `%TEMP%`:
+3. Create the worktree from `origin/<default>`, never from the local HEAD, at
+   `<worktree root>\<repo>\<short-name>`. Never under `%TEMP%`: Windows cleanup (Storage Sense) can empty it
+   and delete a worktree that holds unmerged work. The worktree root is `$env:CADDIS_WORKTREE_ROOT` when set,
+   else the `.worktrees` folder beside the main checkout (for `E:\Projects\<repo>` that is
+   `E:\Projects\.worktrees\<repo>\<short-name>`). `<repo>` is the main checkout's folder name. The caddis
+   script `caddis_worktree_root.py` prints the path; use it so the rule lives in one place:
 
 ```powershell
-git worktree add -b <branch> "$env:TEMP\<repo>-<short-name>" origin/<default>
+$wt = python "<caddis scripts>\caddis_worktree_root.py" <short-name>   # run in the repo; prints the path
+git worktree add -b <branch> $wt origin/<default>
 ```
 
-   Do not create worktrees inside the repo (no `.worktrees/`).
+   `<caddis scripts>` is the `scripts` folder of the installed caddis plugin. Do not create worktrees inside the
+   repo. An existing worktree stays where it is: moving it breaks a venv, which keeps absolute paths.
 4. State the full path of the worktree. Work only there, and do not switch branches in it.
 
 ## Install dependencies fresh

package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md

@@ -154,7 +154,7 @@ unattended; `-Plan <slug>` runs one plain plan instead (the two are exclusive).
    or the owner, or that has **no Lane line**, is not run (fail closed): the runner adds
    `block --type owner-gate --reason "phase <n> lane: <lane>"` (`lane: none` when there is no line) and goes on.
 3. A `todo` milestone is set `in-progress` (a docs PR). Every session of a roadmap runs in ONE dedicated worktree,
-   `%TEMP%/caddis-roadmap-<slug>-<8 hex of the repo's git common dir>`: made with `git worktree add --detach` from `origin/<default>` on the first
+   `<worktree root>/<repo>/caddis-roadmap-<slug>-<8 hex of the repo's git common dir>` (`$CADDIS_WORKTREE_ROOT`, else the `.worktrees` folder beside the main checkout, never `%TEMP%`; an existing recorded worktree stays where it is): made with `git worktree add --detach` from `origin/<default>` on the first
    session, reused on restart, recorded in the runner folder, never the `-Repo` checkout (plan mode keeps working in
    the given checkout). In that worktree the runner makes a fresh branch `caddis/roadmap/<slug>/<plan>-p<n>` from
    `origin/<default>` (it refuses a branch of that name already on origin that it did not make) and ONE session runs

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.147",
+  "poolVersion": "1.3.149",
   "bundles": {
-    "antigravity-plugin": "1.3.147",
+    "antigravity-plugin": "1.3.149",
     "antigravity-plugin-extras": "1.3.45",
     "codex": "unknown"
   }

package/package.json

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