@caddis/cli 0.4.57 → 0.4.59

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

@@ -38,8 +38,10 @@ CLI:
     python caddis_spend.py status                prints the committed spend of the last 24 h
     python caddis_spend.py run --caller X -- agy ...
         reserve, run, settle. Returns agy's own exit code, or 75 over the cap / could not lock,
-        or 78 not configured. 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.
+        or 78 not configured, or 124 when the command ran past its time limit (--timeout-s, else
+        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.
 """
 
 from __future__ import annotations
@@ -62,12 +64,51 @@ EXIT_OVER_CAP = 1          # `check` only
 EXIT_NOT_CONFIGURED = 3    # `check` only
 RUN_REFUSED = 75           # `run`: over the cap, or could not lock (EX_TEMPFAIL)
 RUN_NOT_CONFIGURED = 78    # `run`: not configured (EX_CONFIG)
+RUN_TIMEOUT = 124          # `run`: the child ran past its time limit and its process tree was killed (as timeout(1))
+DEFAULT_RUN_TIMEOUT_S = 3600.0   # one hour: a run over about 1 hour needs the owner's approval anyway
+# No console window for the child on Windows (robustness #19; see no_window.py: never DETACHED_PROCESS).
+_NO_WINDOW_KW = {"creationflags": 0x08000000} if os.name == "nt" else {}
 LOCK_TIMEOUT_S = 10.0
 NOT_CONFIGURED_MESSAGE = ("caddis_spend: spend cap not configured: set eur_per_24h, reserve_eur_per_call and both "
                           "token prices (finite, above 0) in ~/.caddis/spend-cap.toml; every agy launch is refused "
                           "until then")
 
 
+# Recursion guard on headless starts (robustness #19). Every launcher of a headless caddis session passes
+# CADDIS_HEADLESS_DEPTH one higher than it got, and refuses to launch once the depth is at the limit, so a
+# headless session that starts a headless session that starts one... ends after MAX_HEADLESS_DEPTH levels.
+# The owner may change the limit with CADDIS_HEADLESS_MAX_DEPTH. This stops accidents and loops; a hostile
+# process can reset the variable, like the cap file (see the Limits above).
+HEADLESS_DEPTH_VAR = "CADDIS_HEADLESS_DEPTH"
+MAX_HEADLESS_DEPTH = 3
+
+
+class HeadlessDepthExceeded(RuntimeError):
+    """A headless start was refused because headless sessions are already nested too deep."""
+
+
+def headless_depth(env) -> int:
+    """How many headless launches lie above this process: CADDIS_HEADLESS_DEPTH, or 0 when unset or not a count."""
+    raw = str(env.get(HEADLESS_DEPTH_VAR, "")).strip()
+    return int(raw) if raw.isdigit() else 0
+
+
+def bump_headless_depth(env) -> dict:
+    """A copy of `env` for a child headless session: CADDIS_HEADLESS=1 and the depth one higher.
+    Raises HeadlessDepthExceeded when the depth is already at the limit."""
+    limit_raw = str(env.get("CADDIS_HEADLESS_MAX_DEPTH", "")).strip()
+    limit = int(limit_raw) if limit_raw.isdigit() and int(limit_raw) > 0 else MAX_HEADLESS_DEPTH
+    depth = headless_depth(env)
+    if depth >= limit:
+        raise HeadlessDepthExceeded(
+            f"caddis: headless depth {depth} is at the limit ({limit}); not starting another headless session "
+            f"({HEADLESS_DEPTH_VAR}; the owner can raise CADDIS_HEADLESS_MAX_DEPTH)")
+    out = dict(env)
+    out[HEADLESS_DEPTH_VAR] = str(depth + 1)
+    out["CADDIS_HEADLESS"] = "1"
+    return out
+
+
 class NotConfigured(Exception):
     """The cap file is missing, unreadable, or holds a value that is not a finite number above 0."""
 
@@ -317,9 +358,67 @@ def result_text(stdout: str) -> str:
     return stdout
 
 
-def run(argv: list[str], caller: str, home: Path) -> int:
-    """Reserve, run agy, settle. Returns agy's exit code, or RUN_REFUSED (75) / RUN_NOT_CONFIGURED (78)."""
+def run_timeout_s() -> float:
+    """The wall-clock limit of one `run` child: CADDIS_SPEND_RUN_TIMEOUT_S, else DEFAULT_RUN_TIMEOUT_S.
+    A value that is not a finite number above 0 is ignored."""
+    try:
+        value = float(os.environ.get("CADDIS_SPEND_RUN_TIMEOUT_S", ""))
+    except ValueError:
+        return DEFAULT_RUN_TIMEOUT_S
+    return value if math.isfinite(value) and value > 0 else DEFAULT_RUN_TIMEOUT_S
+
+
+def _kill_tree(proc: subprocess.Popen) -> None:
+    """Kill the child and everything it started (taskkill /T on Windows, the process group on POSIX)."""
+    try:
+        if os.name == "nt":
+            subprocess.run(["taskkill", "/T", "/F", "/PID", str(proc.pid)], capture_output=True, timeout=15,
+                           **_NO_WINDOW_KW)
+        else:
+            import signal
+            os.killpg(proc.pid, signal.SIGKILL)
+    except Exception:
+        pass
+    try:
+        proc.kill()
+    except Exception:
+        pass
+
+
+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."""
+    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",
+                            errors="replace", env=env, **_NO_WINDOW_KW, **group)
+    try:
+        out, err = proc.communicate(timeout=timeout_s)
+        return proc.returncode, out or "", err or ""
+    except subprocess.TimeoutExpired:
+        _kill_tree(proc)
+        try:  # the pipes close once the tree is dead; do not wait for ever if a stray holder survives
+            out, err = proc.communicate(timeout=10)
+        except Exception:
+            out, err = "", ""
+        return None, out or "", err or ""
+    except BaseException:
+        # Ctrl-C or any other error while waiting: the child (agy, spending) must not outlive us. It runs in its
+        # own session/group, so it does not get our SIGINT. Kill the tree, then let the exception go on; run()
+        # settles the reserve in its `finally`.
+        _kill_tree(proc)
+        raise
+
+
+def run(argv: list[str], caller: str, home: Path, timeout_s: float | None = None) -> int:
+    """Reserve, run agy, settle. Returns agy's exit code, or RUN_REFUSED (75) / RUN_NOT_CONFIGURED (78) /
+    RUN_TIMEOUT (124: the child ran past `timeout_s`, default run_timeout_s(); its process tree was killed and the
+    call is booked at its reserve)."""
     now = lambda: datetime.now(timezone.utc)  # noqa: E731
+    try:
+        env = bump_headless_depth(os.environ)  # before the reserve: a refused start costs nothing
+    except HeadlessDepthExceeded as exc:
+        print(str(exc), file=sys.stderr)
+        return RUN_REFUSED
     try:
         rid = reserve(home, caller, now())
     except NotConfigured:
@@ -334,19 +433,25 @@ def run(argv: list[str], caller: str, home: Path) -> int:
     if rid is None:
         print(f"caddis_spend: over cap: agy refused ({status_line(home, now())})", file=sys.stderr)
         return RUN_REFUSED
-    env = {**os.environ, "CADDIS_HEADLESS": "1"}
     out = ""
     counts: tuple[int, int] | None = None
     started = time.monotonic()
     try:
-        done = subprocess.run(argv, capture_output=True, text=True, encoding="utf-8", errors="replace", env=env)
-        out = done.stdout or ""
+        limit = run_timeout_s() if timeout_s is None else timeout_s
+        returncode, out, err = _run_child(argv, env, limit)
+        if returncode is None:  # timed out: whatever it printed is passed on, but no token count is trusted
+            sys.stdout.write(out)
+            sys.stderr.write(err)
+            print(f"caddis_spend: {argv[0]} timed out after {limit:g}s; its process tree was killed "
+                  f"(booked at the reserve). Set CADDIS_SPEND_RUN_TIMEOUT_S or --timeout-s to change the limit.",
+                  file=sys.stderr)
+            return RUN_TIMEOUT
         # Tokens only from JSON mode: in text mode the model's own lines could pose as a usage document.
         if json_mode(argv):
             counts = tokens_from_output(out)
         sys.stdout.write(out)
-        sys.stderr.write(done.stderr or "")
-        return done.returncode
+        sys.stderr.write(err)
+        return returncode
     except FileNotFoundError:
         counts = (0, 0)  # nothing ran, nothing was spent
         print(f"caddis_spend: command not found: {argv[0]}", file=sys.stderr)
@@ -380,6 +485,9 @@ def main(argv: list[str] | None = None) -> int:
     sub.add_parser("status")
     p_run = sub.add_parser("run")
     p_run.add_argument("--caller", required=True)
+    p_run.add_argument("--timeout-s", type=float, default=None,
+                       help="kill the command's process tree after this many seconds "
+                            "(default: CADDIS_SPEND_RUN_TIMEOUT_S, else 3600)")
     args = parser.parse_args(raw)
     home = Path.home()
     now = datetime.now(timezone.utc)
@@ -408,7 +516,9 @@ def main(argv: list[str] | None = None) -> int:
         return EXIT_OK
     if not tail:
         parser.error("run needs the agy command after --")
-    return run(tail, args.caller, home)
+    if args.timeout_s is not None and not (math.isfinite(args.timeout_s) and args.timeout_s > 0):
+        parser.error("--timeout-s must be a number above 0")
+    return run(tail, args.caller, home, timeout_s=args.timeout_s)
 
 
 if __name__ == "__main__":

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

@@ -329,7 +329,12 @@ def ram_facts():
     return None
 
 
-def record_context(cwd: str, pct: float) -> None:
+def _safe_session_id(session_id) -> str:
+    """A file-name-safe form of a session id (letters, digits, - and _ only, 64 chars at most); "" when empty."""
+    return "".join(ch if (ch.isalnum() and ch.isascii()) or ch in "-_" else "_" for ch in str(session_id or ""))[:64].strip(".")
+
+
+def record_context(cwd: str, pct: float, session_id: str = "") -> None:
     """Cache the runtime context figure for tools that never see the statusline payload.
 
     Claude Code hands `context_window.used_percentage` to the statusline and to NOTHING else.
@@ -342,6 +347,11 @@ def record_context(cwd: str, pct: float) -> None:
     render. Only writes where `.caddis/` already exists, so cd-ing into an unrelated folder
     never scatters artifact dirs. Fail-open and silent: a status line must never break a
     prompt, and this is the least important thing it does.
+
+    One folder can host several sessions, so the figure is also kept per session, in
+    `.caddis/context-window/<session id>.json`; a reader that knows its session id reads that file and
+    never another session's figure. `context-window.json` stays as the shared "last writer" for a reader
+    that does not know its session (robustness #19). Per-session files older than 2 days are removed.
     """
     try:
         if not cwd:
@@ -349,20 +359,44 @@ def record_context(cwd: str, pct: float) -> None:
         art = os.path.join(cwd, ".caddis")
         if not os.path.isdir(art):
             return
-        target = os.path.join(art, "context-window.json")
         payload = {"used_percentage": round(float(pct), 1), "at": int(time.time())}
-        try:
-            with open(target, encoding="utf-8") as fh:
-                if json.load(fh).get("used_percentage") == payload["used_percentage"]:
-                    return
-        except Exception:
-            pass
-        tmp = target + ".tmp"
+        sid = _safe_session_id(session_id)
+        if sid:
+            per_dir = os.path.join(art, "context-window")
+            os.makedirs(per_dir, exist_ok=True)
+            _write_if_changed(os.path.join(per_dir, sid + ".json"), payload)
+            try:
+                cutoff = time.time() - 2 * 86400
+                for name in os.listdir(per_dir):
+                    old = os.path.join(per_dir, name)
+                    if os.path.getmtime(old) < cutoff:
+                        os.unlink(old)
+            except Exception:
+                pass
+        _write_if_changed(os.path.join(art, "context-window.json"), payload)
+    except Exception:
+        pass
+
+
+def _write_if_changed(target: str, payload: dict) -> None:
+    """Write the JSON `payload` atomically (a temp file named for this process), only when the figure changed."""
+    try:
+        with open(target, encoding="utf-8") as fh:
+            if json.load(fh).get("used_percentage") == payload["used_percentage"]:
+                return
+    except Exception:
+        pass
+    tmp = f"{target}.{os.getpid()}.tmp"
+    try:
         with open(tmp, "w", encoding="utf-8") as fh:
             json.dump(payload, fh)
         os.replace(tmp, target)
     except Exception:
-        pass
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
 
 
 def relay_present(cwd: str) -> bool:
@@ -501,7 +535,7 @@ def render_claude(data: dict, cfg: dict) -> str:
             used = as_int(cw.get("total_input_tokens"))
         max_tokens = as_int(cw.get("context_window_size"))
         pct = float(as_int(cw.get("used_percentage")))
-        record_context(cwd, pct)  # feeds /caddis:spawn-session's 95% gate; see record_context
+        record_context(cwd, pct, str(dig(data, "session_id") or ""))  # feeds /caddis:spawn-session's 95% gate; see record_context
         parts.append(context_segment(c, cfg, used, max_tokens, pct))
         loud = cached_segment(c, cfg, cached)
         if loud:

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

@@ -294,17 +294,22 @@ def close_worktree(
         # Someone pushed after the merge: that work is not in main. Keep the remote branch.
         print(f"kept origin/{branch_name}: its tip {remote_tip[:12]} is not contained in the merged PR head {str(head_ref_oid)[:12]}")
     elif remote_tip:
-        cmd_push_del = ["git", "-C", str(repo), "push", "-q", "origin", "--delete", branch_name]
+        # The check above is followed by a compare-and-delete on the server: a push that lands in between wins.
+        cmd_push_del = ["git", "-C", str(repo), *caddis_worktree_safety.remote_delete_args(branch_name, remote_tip)]
         proc = subprocess.run(cmd_push_del, capture_output=True, text=True, encoding="utf-8", errors="replace")
         if proc.returncode != 0:
-            print(f"failed command: {' '.join(cmd_push_del)}\n{proc.stderr.strip() or proc.stdout.strip()}", file=sys.stderr)
-            return caddis_exit.ERROR
-
-    cmd_prune = ["git", "-C", str(repo), "worktree", "prune"]
-    proc = subprocess.run(cmd_prune, capture_output=True, text=True, encoding="utf-8", errors="replace")
-    if proc.returncode != 0:
-        print(f"failed command: {' '.join(cmd_prune)}\n{proc.stderr.strip() or proc.stdout.strip()}", file=sys.stderr)
-        return caddis_exit.ERROR
+            # A push that landed after our check makes the server refuse the compare-and-delete. That is the same
+            # outcome as the "kept" path above, not an error: look at the remote again.
+            again = subprocess.run(cmd_ls, capture_output=True, text=True, encoding="utf-8", errors="replace")
+            new_tip = again.stdout.split()[0] if again.returncode == 0 and again.stdout.split() else ""
+            if new_tip and new_tip != remote_tip:
+                print(f"kept origin/{branch_name}: its tip moved from {remote_tip[:12]} to {new_tip[:12]} while it was being deleted")
+            else:
+                print(f"failed command: {' '.join(cmd_push_del)}\n{proc.stderr.strip() or proc.stdout.strip()}", file=sys.stderr)
+                return caddis_exit.ERROR
+
+    # No `git worktree prune`: `git worktree remove` (above) dropped this registration, and a prune would also drop
+    # the registrations of other tools whose folders are missing for the moment (robustness #19).
 
     print(f"removed {worktree} ({branch_name}); merge {merge_oid}; files compared: {files_compared}")
     return caddis_exit.CLEAN

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

@@ -129,6 +129,18 @@ def _worktree_blocks(porcelain: str) -> list[list[str]]:
     return blocks
 
 
+def remote_delete_args(branch: str, expected_tip: str, remote: str = "origin") -> tuple[str, ...]:
+    """The `git` arguments that delete `remote/<branch>` only while its tip is `expected_tip` (a full object id).
+
+    `--force-with-lease=<ref>:<oid>` makes the push a compare-and-delete in one step on the server: when someone
+    pushed more commits to the branch after we looked, git refuses and the branch stays (robustness #19). Raises
+    ValueError for anything but a 40 or 64 digit hex id, so a bad value cannot turn into a plain delete."""
+    tip = str(expected_tip or "").strip().lower()
+    if len(tip) not in (40, 64) or any(ch not in "0123456789abcdef" for ch in tip):
+        raise ValueError(f"not a full object id: {expected_tip!r}")
+    return ("push", "--quiet", f"--force-with-lease=refs/heads/{branch}:{tip}", remote, "--delete", branch)
+
+
 def safe_remove_worktree(repo: Path, worktree: Path, *, force: bool = True, force_locked: bool = False,
                          git_flags: Sequence[str] = (), env: Mapping[str, str] | None = None) -> str | None:
     """Remove the linked worktree `worktree` of `repo`: its links first, then `git worktree remove`.

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

@@ -90,8 +90,19 @@ def record(hook: str, feature: str, exc: BaseException, root: str | None = None)
             "message": emsg,
         }, ensure_ascii=False))
 
-        with open(path, "w", encoding="utf-8", newline="\n") as fh:
-            fh.write("\n".join(lines[-_MAX_LINES:]) + "\n")
+        # Write beside the ledger, then swap in one step: a crash or a second hook mid-write
+        # leaves the old ledger whole, never a torn one. The temp name is per process.
+        tmp = f"{path}.{os.getpid()}.tmp"
+        try:
+            with open(tmp, "w", encoding="utf-8", newline="\n") as fh:
+                fh.write("\n".join(lines[-_MAX_LINES:]) + "\n")
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
     except Exception:
         return  # the ledger must never be the thing that breaks a hook
 

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

@@ -101,11 +101,15 @@ SECRET_RULES: list[tuple[str, re.Pattern]] = [
     ("npm-token", re.compile(r"\bnpm_[A-Za-z0-9]{36}\b")),
     ("slack-webhook", re.compile(r"https://hooks\.slack\.com/services/[A-Za-z0-9_/]+")),
     # user:password@host in a URL. `value` is the password; placeholders are exempted in code.
+    # Both rules below start a match only at the start of a run of the characters their first part takes (the
+    # lookbehind). A match that starts inside the run finds the same value from the run start too, and without the
+    # lookbehind each character of a long word started a new scan: quadratic, minutes on one long line.
     ("url-credentials", re.compile(
-        r"[a-z][a-z0-9+.-]*://[^/\s:@]*:(?P<value>[^/\s@]{3,})@", re.I)),
+        r"(?<![a-z0-9+.-])[0-9+.-]*[a-z][a-z0-9+.-]*://[^/\s:@]*:(?P<value>[^/\s@]{3,})@", re.I)),
     # `name = "v"`, `name: "v"`, and a quoted key: `"name": "v"`, `'name': 'v'`.
     ("assignment", re.compile(
-        r"(?i)[A-Za-z0-9_]*(password|passwd|secret|api[_-]?key|token)[A-Za-z0-9_]*['\"]?\s*[:=]\s*['\"](?P<value>[^'\"\s]{8,})['\"]"
+        r"(?i)(?<![A-Za-z0-9_])[A-Za-z0-9_]*(password|passwd|secret|api[_-]?key|token)[A-Za-z0-9_]*['\"]?\s*[:=]\s*"
+        r"['\"](?P<value>[^'\"\s]{8,})['\"]"
     )),
     ("env-assignment", re.compile(
         r"^\s*(?:export\s+)?[A-Za-z0-9_]*(?:PASSWORD|PASSWD|SECRET|API_KEY|APIKEY|TOKEN|PRIVATE_KEY)"

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

@@ -1207,6 +1207,8 @@ session-state.md
 session-state/
 context-window.json
 context-window.json.tmp
+context-window.json.*.tmp
+context-window/
 .session-state-*.tmp
 hook-errors.jsonl
 .relay-injected/
@@ -1420,6 +1422,18 @@ def _user_settings_path(home: Path | None = None) -> Path:
     return root / ".claude" / "settings.json"
 
 
+def _atomic_write_json(path: Path, data: dict) -> None:
+    """Write `data` to `path` through a temp file. The temp name is unique per process: every
+    SessionStart runs this (inject_relay.py), and two sessions starting at once must not share one."""
+    tmp = path.with_name(f"{path.name}.caddis-tmp-{os.getpid()}")
+    try:
+        tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        os.replace(tmp, path)
+    finally:
+        if tmp.exists():
+            tmp.unlink()
+
+
 def ensure_user_env(dry: bool, home: Path | None = None) -> list[str]:
     """Add `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` to the user's global settings, additively.
 
@@ -1470,9 +1484,7 @@ def ensure_user_env(dry: bool, home: Path | None = None) -> list[str]:
         # whole function exists to notice.
         if raw:
             path.with_suffix(".json.caddis-bak").write_text(raw, encoding="utf-8")
-        tmp = path.with_suffix(".json.caddis-tmp")
-        tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
-        os.replace(tmp, path)
+        _atomic_write_json(path, data)
     verb = "would add" if dry else "added"
     return [f"user env: {verb} {TODO_TOOLS_ENV_KEY}=1 to {path}"
             + ("" if not raw else " (previous version saved as settings.json.caddis-bak)")]
@@ -1513,9 +1525,7 @@ def ensure_cleanup_period(dry: bool, home: Path | None = None, days: int = CLEAN
         path.parent.mkdir(parents=True, exist_ok=True)
         if raw:
             path.with_suffix(".json.caddis-retention-bak").write_text(raw, encoding="utf-8")
-        tmp = path.with_suffix(".json.caddis-tmp")
-        tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
-        os.replace(tmp, path)
+        _atomic_write_json(path, data)
     verb = "would set" if dry else "set"
     return f"transcript retention: {verb} {CLEANUP_PERIOD_KEY}={days} in {path}"
 

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

@@ -58,6 +58,9 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_adhoc.py" "<task description>"
 - **Worktree result:** PASS commits code changes to `lane/adhoc-<slug>` and removes the worktree. FAIL keeps it. A Claude-lane `PENDING` keeps it and prints the `NEXT:` step. Gates that never ran show `Gates: not run`.
 - **No-op and gate failures:** A run with no code changes fails and keeps its worktree. A pytest gate that collects no tests also fails.
 - **Verdict Card:** Prints PASS, FAIL, or PENDING with diff stats and next actions.
+- **State per session:** The active task is saved in `.caddis/orchestrator/adhoc/latest-<session-id>.json` (session id from `CADDIS_SESSION_ID`, `CLAUDE_SESSION_ID` or `CLAUDE_CODE_SESSION_ID`). `keep`, `drop` and `status` use only your own session's task. An old un-keyed `latest.json` is adopted once by the first session that reads it.
+- **Unique slug:** The `<slug>` ends in a random 6-character suffix, so two runs on the same day and topic never share a branch or plan.
+- **No branch overwrite:** If `lane/adhoc-<slug>` already exists with commits not merged into the base (and is not this session's own recorded branch), the run fails, keeps its worktree and prints why.
 
 ### 2. Keep the Result
 ```bash

package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md

@@ -133,8 +133,9 @@ symmetric either: refusing early costs this session's remaining headroom, while
 handover costs the successor's whole session and everything built on the error.
 
 **Where the number comes from.** Claude Code hands `context_window.used_percentage` to the status
-line and to nothing else, so the caddis status line caches it per repo and `preflight` reads it
-back. **No status line on this machine?** Pass your own reading:
+line and to nothing else, so the caddis status line caches it per repo and per session (`.caddis/context-window/<session id>.json`),
+and `preflight` reads it back (your own session's file when `CLAUDE_SESSION_ID` is set, else the shared
+`context-window.json`, which another session may have written last). **No status line on this machine?** Pass your own reading:
 
 ```bash
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" preflight --context-pct 72