@caddis/cli 0.4.62 → 0.4.64

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.148",
+  "version": "1.3.150",
   "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_lanes.py

@@ -37,6 +37,7 @@ import caddis_checkout_guard
 import caddis_routing
 import caddis_redact
 import caddis_spend
+import caddis_worktree_root
 import caddis_worktree_safety
 
 if hasattr(sys.stdout, "reconfigure"):
@@ -61,7 +62,15 @@ 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")
+# Where lane git WORKTREES live.
+# New lane worktrees go to `<worktree root>/<repo>/caddis-lane-<hash>-<plan>-p<NN>-a<K>` (`lane_worktree_path`, which asks
+# `caddis_worktree_root`: $CADDIS_WORKTREE_ROOT, else `<parent of the main checkout>/.worktrees`). Never %TEMP%: Windows
+# cleanup (Storage Sense) can empty it and delete a lane worktree that holds unmerged work (owner decision, 20 Oct 2026).
+# LANES_TMP is the OLD place, kept ONLY so lanes made before that decision keep working where they are: it is read to
+# accept, finish and abandon an old record, and is never written to. Nothing else lives under it. Lane scratch that is not
+# a worktree (packets, locks) is under `<repo>/.caddis/orchestrator/lane-runs/` (`run_dir`); it never used LANES_TMP.
 LANES_TMP = Path(tempfile.gettempdir()) / "caddis-lanes"
+LANE_WORKTREE_PREFIX = "caddis-lane-"
 DEFAULT_MODELS = {
     "claude": "claude-opus-5",
     "glm": "glm-5.3[1m]",
@@ -227,6 +236,32 @@ def _git_output(repo_root: Path, *args: str) -> str:
     return result.stdout.strip()
 
 
+def lane_worktree_path(repo_root: Path, plan_stem: str, phase: int, attempt: int) -> Path:
+    """The path of a NEW lane worktree: `<worktree root>/<repo>/caddis-lane-<repo hash>-<plan>-p<NN>-a<K>`.
+    Creates nothing. The hash keeps two repos with the same folder name apart."""
+    repo_hash = hashlib.sha256(str(repo_root.resolve()).encode("utf-8")).hexdigest()[:8]
+    short_name = f"{LANE_WORKTREE_PREFIX}{repo_hash}-{plan_stem}-p{phase:02d}-a{attempt}"
+    try:
+        return caddis_worktree_root.worktree_path(repo_root, short_name)
+    except (ValueError, caddis_worktree_root.NotARepoError) as exc:
+        raise LaneConfigError(str(exc)) from exc
+
+
+def is_lane_worktree_path(repo_root: Path, path: Path) -> bool:
+    """True for a folder that a lane may remove: an OLD one under LANES_TMP (any depth, as before), or a NEW one named
+    `caddis-lane-*` directly inside this repo's folder under the current worktree root."""
+    resolved = path.resolve()
+    if LANES_TMP.resolve() in resolved.parents:
+        return True
+    if not resolved.name.startswith(LANE_WORKTREE_PREFIX):
+        return False
+    try:
+        lane_dir = caddis_worktree_root.worktree_path(repo_root, resolved.name).parent
+    except (ValueError, caddis_worktree_root.NotARepoError):
+        return False
+    return resolved.parent == lane_dir.resolve()
+
+
 def create_phase_worktree(
     repo_root: Path,
     plan_stem: str,
@@ -235,14 +270,11 @@ def create_phase_worktree(
 ) -> Worktree:
     base_sha = _git_output(repo_root, "rev-parse", "HEAD")
     branch = f"lane/{plan_stem}/phase-{phase:02d}-a{attempt}"
-    repo_hash = hashlib.sha256(str(repo_root.resolve()).encode("utf-8")).hexdigest()[:8]
-    path = LANES_TMP / (
-        f"{repo_root.name}-{repo_hash}-{plan_stem}-p{phase:02d}-a{attempt}"
-    )
+    path = lane_worktree_path(repo_root, plan_stem, phase, attempt)
     if path.exists():
         raise LaneConfigError(f"worktree already exists: {path} — run abandon first")
 
-    LANES_TMP.mkdir(parents=True, exist_ok=True)
+    path.parent.mkdir(parents=True, exist_ok=True)
     _git_output(
         repo_root,
         "worktree",
@@ -262,8 +294,8 @@ def remove_phase_worktree(
     delete_branch: bool,
 ) -> None:
     resolved = wt.path.resolve()
-    if LANES_TMP.resolve() not in resolved.parents:
-        raise LaneConfigError(f"refusing to remove {resolved}: not under {LANES_TMP}")
+    if not is_lane_worktree_path(repo_root, resolved):
+        raise LaneConfigError(f"refusing to remove {resolved}: not a lane worktree (a caddis-lane-* folder under the worktree root, or an old one under {LANES_TMP})")
     if delete_branch and not wt.branch.startswith("lane/"):
         raise LaneConfigError(f"refusing to delete non-lane branch: {wt.branch}")
 
@@ -2250,7 +2282,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:
@@ -2342,8 +2374,8 @@ def _validate_packet_worktree(
 ) -> None:
     resolved = wt.path.resolve()
     expected_branch = f"lane/{plan.stem}/phase-{phase:02d}-a{attempt}"
-    if LANES_TMP.resolve() not in resolved.parents:
-        raise LaneConfigError(f"refusing packet worktree outside {LANES_TMP}: {resolved}")
+    if not is_lane_worktree_path(repo, resolved):
+        raise LaneConfigError(f"refusing packet worktree that is not a lane worktree: {resolved}")
     if wt.branch != expected_branch:
         raise LaneConfigError(
             f"refusing packet branch {wt.branch}: expected {expected_branch}"
@@ -2392,8 +2424,7 @@ def _finish_command(args) -> int:
         resolved = path.resolve()
         if resolved == main_path:
             continue
-        in_lanes_tmp = LANES_TMP.resolve() in resolved.parents
-        if not branch.startswith(prefix) or not in_lanes_tmp:
+        if not branch.startswith(prefix) or not is_lane_worktree_path(repo, resolved):
             print(f"OTHER {path} {branch or 'HEAD'}")
             continue
         if branch_is_locked(branch):

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

@@ -30,7 +30,8 @@ with new commits on that branch (still checked out, nothing under `.caddis/roadm
 persistent claim for the phase, pushes the branch, opens a PR (`gh api`) and stops `BLOCKED waiting for merge
 <plan>#<phase> <url>` (exit 1); `--last-stop` lets the recheck task restart it once the PR merged; the restart checks
 the merged origin roadmap against the hash taken at publish time, removes the claim, rolls that milestone up and goes
-on. Every roadmap runs its sessions in ONE dedicated worktree, `%TEMP%/caddis-roadmap-<slug>-<repo tag>` (made with
+on. Every roadmap runs its sessions in ONE dedicated worktree, `<worktree root>/<repo>/caddis-roadmap-<slug>-<repo tag>`
+(`$CADDIS_WORKTREE_ROOT`, else `<parent of the main checkout>/.worktrees`, never %TEMP%; `caddis_worktree_root.py`; 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); when the roadmap is finished the runner removes it if it is clean, and keeps it
 (saying so in the stop line) if not. The caps (hours, sessions, USD per session and in total) are per run, in memory. CONTINUE with the phase already merged on
@@ -111,7 +112,6 @@ import re
 import socket
 import subprocess
 import sys
-import tempfile
 import time
 import uuid
 from collections import Counter
@@ -135,6 +135,7 @@ import caddis_redact  # noqa: E402
 import caddis_review  # noqa: E402
 import caddis_roadmap  # noqa: E402
 import caddis_spend  # noqa: E402
+import caddis_worktree_root  # noqa: E402
 import caddis_worktree_safety  # noqa: E402
 import caddis_workstreams  # noqa: E402
 
@@ -1545,11 +1546,13 @@ def _registered_worktrees(repo: Path) -> set[Path]:
 
 
 def worktree_path(repo: Path, slug: str, root: Path | None = None) -> Path:
-    """The roadmap's session worktree: the recorded path, else `<root or %TEMP%>/caddis-roadmap-<slug>-<repo tag>`."""
+    """The roadmap's session worktree: the recorded path, else (a NEW one) `caddis-roadmap-<slug>-<repo tag>` under
+    `<worktree root>/<repo>/` (`caddis_worktree_root`: `root`, `$CADDIS_WORKTREE_ROOT`, else `<parent of the main
+    checkout>/.worktrees`; never %TEMP%)."""
     recorded = _read_record(_state_file(repo, slug, "worktree")).get("path")
     if isinstance(recorded, str) and recorded:
         return Path(recorded)
-    return Path(root or tempfile.gettempdir()) / f"{WORKTREE_PREFIX}{slug}-{_repo_tag(repo)}"
+    return caddis_worktree_root.worktree_path(repo, f"{WORKTREE_PREFIX}{slug}-{_repo_tag(repo)}", root)
 
 
 def _repo_tag(repo: Path) -> str:

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

@@ -118,7 +118,9 @@ def _hash(text: str) -> str:
 
 def read_relay(root: Path, name: str) -> tuple[str, str | None]:
     artifact, path = _path(root, name)
-    if not path.resolve().is_relative_to(artifact.resolve()) or path.is_symlink():
+    # Only a relay that EXISTS can point elsewhere; resolving one that does not exist yet raced a concurrent writer
+    # creating its folder (see caddis_todo._path, #103).
+    if path.is_symlink() or (path.exists() and not path.resolve().is_relative_to(artifact.resolve())):
         raise ValueError("relay path escapes artifact root")
     try:
         text = path.read_bytes().decode("utf-8")

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.148",
+  "poolVersion": "1.3.150",
   "bundles": {
-    "antigravity-plugin": "1.3.148",
+    "antigravity-plugin": "1.3.150",
     "antigravity-plugin-extras": "1.3.45",
     "codex": "unknown"
   }

package/package.json

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