@caddis/cli 0.4.39 → 0.4.41

package/bundles/antigravity-plugin/plugin.json

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

@@ -23,9 +23,21 @@ import shutil
 import subprocess
 import sys
 import time
+from collections.abc import Callable, Mapping
 from datetime import datetime, timezone
 from pathlib import Path
 
+FIX_HINTS: dict[str, str] = {
+    "python-missing": "install Python 3.11 or later; on Linux also run: sudo apt install python-is-python3",
+    "python-store-alias": "this is the Microsoft Store alias; install Python from python.org or with winget, then turn off the alias in Settings > Apps > App execution aliases",
+    "python-old": "install Python 3.11 or later and make it the first python on PATH",
+    "git-missing": "install git (Windows: winget install Git.Git; Linux: sudo apt install git)",
+    "keys-none": "optional: run caddis keys to add GLM or DeepSeek keys",
+    "deny-rules": "run /caddis:setup-project-ai to add the missing deny rules",
+    "gitignore": "run /caddis:setup-project-ai to add the missing .caddis ignore entries",
+    "misfiled": "move the file into a caddis document folder, or delete it",
+}
+
 # Probed contract versions (docs/analysis/*-contract.md). WARN when the installed binary drifts past
 # these — the recorded schemas may be stale and want a re-probe.
 PROBED_VERSIONS = {"codex": "0.137", "agy": "1.1.5"}
@@ -36,6 +48,29 @@ AGENTS_MD_BUDGET = 200  # always-loaded rules file line budget (mirrors check_do
 ARTIFACT_DIRS = (".caddis",)
 ENV_PREFIX = "CADDIS"
 
+# Known top-level document and working artifact folders under .caddis/
+KNOWN_CADDIS_DIRS: set[str] = {
+    "plans",
+    "prd",
+    "kb",
+    "rca",
+    "decisions",
+    "parking-lot",
+    "reviews",
+    "todo-list",
+    "comms",
+    "handoffs",
+    "prompts",
+    "relay",
+    "session-state",
+    "advisory-hub-reports",
+    "orchestrator",
+    "spawn-session",
+    "metrics",
+    "agent-docs",
+    "backlog",
+}
+
 
 def _home() -> Path:
     return Path(os.environ.get(f"{ENV_PREFIX}_FAKE_HOME") or Path.home())
@@ -288,7 +323,7 @@ def _file_signals(dest: Path) -> list[str]:
         signals.append(f"{len(dangling)} dangling DOC-MAP link(s) — run /caddis:kb")
     days = days_since_last_doctor()
     if days is not None and days >= 30:
-        signals.append(f"{days} days since last caddis doctor — run caddis-init --doctor")
+        signals.append(f"{days} days since last caddis doctor — run caddis doctor")
     # Listed LAST but it is the most dangerous signal here: the others degrade a session's quality,
     # this one silently runs old code and reports success. It is cheap (a file compare) and almost
     # always empty, so it costs nothing to carry.
@@ -312,19 +347,30 @@ def nudge_line(dest: Path) -> str | None:
     return f"[caddis] {head}{more}"
 
 
+def _load_sibling(name: str, fallback_dir: Path | str | None = None):
+    """Load a helper module by filename/module name: sibling first, then fallback_dir."""
+    scripts = Path(__file__).resolve().parent
+    file_name = name if name.endswith(".py") else f"{name}.py"
+    mod_name = name[:-3] if name.endswith(".py") else name
+    path = scripts / file_name
+    if not path.is_file() and fallback_dir:
+        path = Path(fallback_dir) / file_name
+    if not path.is_file():
+        return None
+    spec = importlib.util.spec_from_file_location(f"caddis_{mod_name}", path)
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
 def hook_errors(dest: Path) -> str:
     """Recent hook failures, counted by hook. Empty when the ledger is clean."""
     scripts = Path(__file__).resolve().parent
-    hook_log_path = scripts / "hook_log.py"
-    if not hook_log_path.is_file():  # source checkout; installed copies are siblings
-        hook_log_path = scripts.parent / "claude-harness" / "scripts" / "hook_log.py"
     try:
-        spec = importlib.util.spec_from_file_location("caddis_hook_log", hook_log_path)
-        if spec is None or spec.loader is None:
-            return ""
-        hook_log = importlib.util.module_from_spec(spec)
-        spec.loader.exec_module(hook_log)
-        if not hook_log.summarise(str(dest), days=7):
+        hook_log = _load_sibling("hook_log.py", scripts.parent / "claude-harness" / "scripts")
+        if hook_log is None or not hook_log.summarise(str(dest), days=7):
             return ""
         cutoff = time.strftime("%Y-%m-%d", time.localtime(time.time() - 7 * 86400))
         counts: dict[str, int] = {}
@@ -342,6 +388,182 @@ def hook_errors(dest: Path) -> str:
         return ""  # a damaged ledger must not break the doctor
 
 
+def machine_findings(which: Callable[[str], str | None] | None = None,
+                     version: Callable[[str], str | None] | None = None) -> list[tuple[str, str]]:
+    """Machine faults that stop caddis on a new laptop. Levels: OK, INFO, FAIL (never raises)."""
+    which = which or shutil.which  # resolved at call time, so a test can patch shutil.which
+    version = version or _binary_version
+
+    out: list[tuple[str, str]] = []
+
+    # python
+    py_path = which("python")
+    if py_path is None:
+        out.append(("FAIL", f"python (on PATH): not found — {FIX_HINTS['python-missing']}"))
+    elif "windowsapps" in py_path.lower() or "WindowsApps" in py_path:
+        out.append(("FAIL", f"python (on PATH): [{py_path}] — {FIX_HINTS['python-store-alias']}"))
+    else:
+        ver_str = None
+        try:
+            ver_str = version(py_path)
+        except Exception:
+            ver_str = None
+
+        m = re.search(r"(\d+)\.(\d+)(?:\.(\d+))?", ver_str or "")
+        if not m:
+            out.append(("INFO", "python (on PATH): could not read its version"))
+        else:
+            major, minor = int(m.group(1)), int(m.group(2))
+            ver_display = (ver_str or "").strip()
+            if ver_display.startswith("Python "):
+                ver_display = ver_display[7:].strip()
+            if (major, minor) < (3, 11):
+                out.append(("FAIL", f"python (on PATH): {ver_display} [{py_path}] — {FIX_HINTS['python-old']}"))
+            else:
+                out.append(("OK", f"python (on PATH): {ver_display} [{py_path}]"))
+
+    # git
+    git_path = which("git")
+    if git_path is None:
+        out.append(("FAIL", f"git: not found — {FIX_HINTS['git-missing']}"))
+    else:
+        out.append(("OK", f"git: [{git_path}]"))
+
+    return out
+
+
+def keys_line(env: Mapping[str, str]) -> tuple[str, str]:
+    scripts = Path(__file__).resolve().parent
+    try:
+        oss_model = _load_sibling("oss_model.py", scripts.parent / "claude-harness" / "scripts")
+        if oss_model is None:
+            return ("INFO", "keys: could not check")
+
+        env_dict = dict(env)
+        fake_home = env_dict.get(f"{ENV_PREFIX}_FAKE_HOME") or os.environ.get(f"{ENV_PREFIX}_FAKE_HOME")
+        if fake_home and "CADDIS_KEYS_FILE" not in env_dict:
+            env_dict["CADDIS_KEYS_FILE"] = str(Path(fake_home) / ".caddis" / "keys.env")
+
+        providers = oss_model.configured_providers(env_dict)
+        if providers:
+            return ("OK", f"keys: {', '.join(providers)}")
+        return ("INFO", f"keys: none — {FIX_HINTS['keys-none']}")
+    except Exception:
+        return ("INFO", "keys: could not check")
+
+
+# ── project checks (read-only — WARN or INFO, never FAIL) ─────────────────────
+def deny_rule_findings(dest: Path) -> list[tuple[str, str]]:
+    dest = Path(dest)
+    if _is_caddis_source(dest):
+        return []
+
+    scripts = Path(__file__).resolve().parent
+    tmpl_path = scripts.parent / "settings.template.json"
+    if not tmpl_path.is_file():
+        tmpl_path = scripts.parent / "claude-harness" / "settings.template.json"
+    if not tmpl_path.is_file():
+        return []
+
+    settings_path = dest / ".claude" / "settings.json"
+    if not settings_path.is_file():
+        return [("INFO", "no .claude/settings.json")]
+
+    try:
+        tmpl = json.loads(tmpl_path.read_text(encoding="utf-8"))
+        required_deny = tmpl.get("permissions", {}).get("deny", [])
+    except Exception:
+        return []
+
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        dest_deny = set(settings.get("permissions", {}).get("deny", []))
+    except Exception:
+        dest_deny = set()
+
+    missing = [r for r in required_deny if r not in dest_deny]
+    if missing:
+        return [("WARN", f"deny rules: {len(missing)} missing — {FIX_HINTS['deny-rules']}")]
+    return []
+
+
+def gitignore_findings(dest: Path) -> list[tuple[str, str]]:
+    dest = Path(dest)
+    if _is_caddis_source(dest):
+        return []
+    if not (dest / ".caddis").is_dir():
+        return []
+
+    scripts = Path(__file__).resolve().parent
+    try:
+        setup_mod = _load_sibling("setup_project_ai.py", scripts.parent / "scripts")
+        if setup_mod is None:
+            return [("INFO", "gitignore: could not check")]
+        artifact_gitignore = getattr(setup_mod, "ARTIFACT_GITIGNORE", None)
+        if not artifact_gitignore:
+            return [("INFO", "gitignore: could not check")]
+
+        entries = [
+            line.strip()
+            for line in artifact_gitignore.splitlines()
+            if line.strip() and not line.strip().startswith("#")
+        ]
+
+        caddis_ignore = dest / ".caddis" / ".gitignore"
+        caddis_lines: set[str] = set()
+        if caddis_ignore.is_file():
+            try:
+                caddis_lines = {line.strip() for line in caddis_ignore.read_text(encoding="utf-8", errors="replace").splitlines()}
+            except OSError:
+                pass
+
+        root_ignore = dest / ".gitignore"
+        root_lines: set[str] = set()
+        if root_ignore.is_file():
+            try:
+                root_lines = {line.strip() for line in root_ignore.read_text(encoding="utf-8", errors="replace").splitlines()}
+            except OSError:
+                pass
+
+        missing: list[str] = []
+        for entry in entries:
+            if entry in caddis_lines or f".caddis/{entry}" in root_lines:
+                continue
+            missing.append(entry)
+
+        if missing:
+            first_three = ", ".join(missing[:3])
+            return [("WARN", f"gitignore: {len(missing)} missing ({first_three}) — {FIX_HINTS['gitignore']}")]
+        return []
+    except Exception:
+        return [("INFO", "gitignore: could not check")]
+
+
+def misfiled_findings(dest: Path) -> list[tuple[str, str]]:
+    dest = Path(dest)
+    if _is_caddis_source(dest):
+        return []
+
+    caddis_dir = dest / ".caddis"
+    if not caddis_dir.is_dir():
+        return []
+
+    out: list[tuple[str, str]] = []
+    try:
+        subdirs = sorted(p for p in caddis_dir.iterdir() if p.is_dir())
+    except OSError:
+        return []
+
+    for top_dir in subdirs:
+        if top_dir.name in _SKIP_DIRS:
+            continue
+        if top_dir.name not in KNOWN_CADDIS_DIRS:
+            md_files = list(top_dir.rglob("*.md"))
+            if md_files:
+                out.append(("WARN", f".caddis/{top_dir.name}/ is not a caddis folder ({len(md_files)} file(s)) — {FIX_HINTS['misfiled']}"))
+    return out
+
+
 # ── report ───────────────────────────────────────────────────────────────────
 def run(dest: Path, quiet: bool) -> int:
     if quiet:  # SessionStart mode: only the nudge, never non-zero
@@ -352,7 +574,7 @@ def run(dest: Path, quiet: bool) -> int:
 
     hard = 0
     print(f"=== caddis doctor — {dest} ===")
-    print(f"python: {sys.version.split()[0]}  ({sys.executable})")
+    print(f"python (running this check): {sys.version.split()[0]}  ({sys.executable})")
     for name in ("codex", "agy", "claude"):
         path = _which(name)
         if path:
@@ -361,6 +583,26 @@ def run(dest: Path, quiet: bool) -> int:
         else:
             print(f"  {name:7} not found on PATH (install, or open a new terminal so PATH refreshes)")
 
+    print("-- machine")
+    for level, text in machine_findings():
+        if level == "FAIL":
+            hard = 1
+        print(f"  {level:4} {text}")
+    k_level, k_text = keys_line(os.environ)
+    if k_level == "FAIL":
+        hard = 1
+    print(f"  {k_level:4} {k_text}")
+
+    print("-- project")
+    proj_findings = deny_rule_findings(dest) + gitignore_findings(dest) + misfiled_findings(dest)
+    if proj_findings:
+        for level, text in proj_findings:
+            if level == "FAIL":
+                hard = 1
+            print(f"  {level:4} {text}")
+    else:
+        print("  OK   deny rules, gitignore entries and document folders clean")
+
     print("-- rules integrity")
     findings = rules_findings(dest)
     if findings:

package/bundles/antigravity-plugin/settings.template.json

@@ -0,0 +1,37 @@
+{
+  "$comment": "Base harness settings deployed by setup-project-ai: permissions + a status line. The generator adds stack-specific Bash allow entries (pytest/npm/etc.) based on detection. HOOKS ARE NOT DEFINED HERE: the harness loop hooks (relay.md resume on SessionStart/PreCompact, end-of-session nudge + usage digest on Stop, auto-lint on Edit/Write) ship with the caddis plugin via plugin/hooks/hooks.json and auto-activate on install — defining them here too would double-fire and re-introduce machine-specific paths. The default loop is just a plan file + relay.md; there is no opt-in pipeline/MCP power-mode.",
+  "$comment_permissions": "IMPORTANT: any entry in `ask` overrides bypassPermissions (yolo) mode and forces a prompt every time, even when the user has opted into no-prompts. Keep `ask` empty (or as minimal as possible) so bypassPermissions actually bypasses. `Bash(git push:*)` was moved out of `ask` into `allow` for exactly this reason — it was forcing a push prompt on every /ship under bypassPermissions.",
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Bash(git status)",
+      "Bash(git diff:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git log:*)",
+      "Bash(git push:*)"
+    ],
+    "ask": [],
+    "deny": [
+      "Read(**/.env)",
+      "Read(**/.env.local)",
+      "Read(**/.env.*.local)",
+      "Read(**/.env.production)",
+      "Read(**/.env.development)",
+      "Edit(**/.env)",
+      "Edit(**/.env.local)",
+      "Edit(**/.env.*.local)",
+      "Edit(**/.env.production)",
+      "Edit(**/.env.development)",
+      "Write(**/.env)",
+      "Write(**/.env.local)",
+      "Write(**/.env.*.local)",
+      "Write(**/.env.production)",
+      "Write(**/.env.development)"
+    ]
+  }
+}

package/bundles/manifest.json

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

package/dist/cli.js

@@ -1209,7 +1209,7 @@ var require_command = __commonJS({
     "use strict";
     var EventEmitter = __require("events").EventEmitter;
     var childProcess = __require("child_process");
-    var path5 = __require("path");
+    var path6 = __require("path");
     var fs = __require("fs");
     var process3 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
@@ -2222,9 +2222,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path5.resolve(baseDir, baseName);
+          const localBin = path6.resolve(baseDir, baseName);
           if (fs.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path5.extname(baseName))) return void 0;
+          if (sourceExt.includes(path6.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
             (ext) => fs.existsSync(`${localBin}${ext}`)
           );
@@ -2242,17 +2242,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path5.resolve(
-            path5.dirname(resolvedScriptPath),
+          executableDir = path6.resolve(
+            path6.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path5.basename(
+            const legacyName = path6.basename(
               this._scriptPath,
-              path5.extname(this._scriptPath)
+              path6.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -2263,7 +2263,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path5.extname(executableFile));
+        launchWithNode = sourceExt.includes(path6.extname(executableFile));
         let proc;
         if (process3.platform !== "win32") {
           if (launchWithNode) {
@@ -3178,7 +3178,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path5.basename(filename, path5.extname(filename));
+        this._name = path6.basename(filename, path6.extname(filename));
         return this;
       }
       /**
@@ -3192,9 +3192,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path6) {
-        if (path6 === void 0) return this._executableDir;
-        this._executableDir = path6;
+      executableDir(path7) {
+        if (path7 === void 0) return this._executableDir;
+        this._executableDir = path7;
         return this;
       }
       /**
@@ -3731,6 +3731,23 @@ var require_lib = __commonJS({
   }
 });
 
+// src/util/which.ts
+async function findBin(name) {
+  try {
+    const found = await (0, import_which.default)(name, { nothrow: true });
+    return found ?? null;
+  } catch {
+    return null;
+  }
+}
+var import_which;
+var init_which = __esm({
+  "src/util/which.ts"() {
+    "use strict";
+    import_which = __toESM(require_lib(), 1);
+  }
+});
+
 // src/util/pkg.ts
 import { readFileSync, existsSync } from "fs";
 import { fileURLToPath } from "url";
@@ -4843,7 +4860,7 @@ var init_init = __esm({
 });
 
 // src/providers/resolve.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { homedir } from "os";
 import { isAbsolute, join } from "path";
 function expandHome(p2) {
@@ -4856,10 +4873,10 @@ function keysFilePath(env) {
   const expanded = expandHome(configured);
   return isAbsolute(expanded) ? expanded : expanded;
 }
-function parseKeysFile(path5) {
+function parseKeysFile(path6) {
   let text;
   try {
-    text = readFileSync4(path5, "utf8");
+    text = readFileSync3(path6, "utf8");
   } catch {
     return {};
   }
@@ -4917,7 +4934,7 @@ __export(keys_exports, {
   probeKey: () => probeKey,
   upsertKeyLines: () => upsertKeyLines
 });
-import { chmodSync, mkdirSync as mkdirSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { chmodSync, mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
 import { dirname } from "path";
 async function probeKey(baseUrl, model, apiKey) {
   if (!baseUrl) return { ok: false, rejected: false, detail: "no endpoint for this provider" };
@@ -4971,18 +4988,18 @@ function upsertKeyLines(existing, updates) {
   if (!text.endsWith("\n")) text += "\n";
   return text;
 }
-function restrictPermissions(path5) {
+function restrictPermissions(path6) {
   if (process.platform === "win32") return null;
   try {
-    chmodSync(path5, 384);
+    chmodSync(path6, 384);
     return null;
   } catch (error) {
     return error instanceof Error ? error.message : String(error);
   }
 }
 async function keys(options = {}) {
-  const path5 = keysFilePath(process.env);
-  const fileKeys = parseKeysFile(path5);
+  const path6 = keysFilePath(process.env);
+  const fileKeys = parseKeysFile(path6);
   const names = Object.keys(PROVIDERS).sort();
   const current = names.map((name) => {
     const preset = PROVIDERS[name];
@@ -4998,7 +5015,7 @@ async function keys(options = {}) {
   if (options.check) {
     const configured = current.filter((entry) => entry.value);
     if (!configured.length) {
-      process.stdout.write(`no provider keys configured (looked in $ENV and ${path5})
+      process.stdout.write(`no provider keys configured (looked in $ENV and ${path6})
 `);
       return 1;
     }
@@ -5013,7 +5030,7 @@ async function keys(options = {}) {
     return bad ? 1 : 0;
   }
   Ie("caddis keys");
-  process.stdout.write(`  keys file: ${path5}
+  process.stdout.write(`  keys file: ${path6}
 
 `);
   for (const entry of current) {
@@ -5073,20 +5090,20 @@ async function keys(options = {}) {
     return 0;
   }
   if (options.dryRun) {
-    Se(`dry run \u2014 would write ${Object.keys(collected).join(", ")} to ${path5}`);
+    Se(`dry run \u2014 would write ${Object.keys(collected).join(", ")} to ${path6}`);
     return 0;
   }
   let existing = "";
   try {
-    existing = readFileSync5(path5, "utf8");
+    existing = readFileSync4(path6, "utf8");
   } catch {
     existing = "";
   }
-  mkdirSync2(dirname(path5), { recursive: true });
-  writeFileSync2(path5, upsertKeyLines(existing, collected), { encoding: "utf8" });
-  const permWarning = restrictPermissions(path5);
+  mkdirSync(dirname(path6), { recursive: true });
+  writeFileSync(path6, upsertKeyLines(existing, collected), { encoding: "utf8" });
+  const permWarning = restrictPermissions(path6);
   process.stdout.write(`
-  wrote ${Object.keys(collected).join(", ")} to ${path5}
+  wrote ${Object.keys(collected).join(", ")} to ${path6}
 `);
   if (permWarning) process.stdout.write(color.yellow(`  could not set 0600 on the keys file: ${permWarning}
 `));
@@ -5160,18 +5177,22 @@ var doctor_exports = {};
 __export(doctor_exports, {
   doctor: () => doctor
 });
+import { existsSync as existsSync5 } from "fs";
 import os3 from "os";
 import process2 from "process";
+import path5 from "path";
 async function doctor(options) {
   const report = await gather(options.adapters, { checkCliUpdate: true });
   const findings = [];
   if (options.json) {
-    line(JSON.stringify(toJson(report), null, 2));
+    const project = await renderProject(findings, { quiet: true });
+    line(JSON.stringify(toJson(report, project), null, 2));
     return 0;
   }
   renderBanner({ cliVersion: report.cliVersion, poolVersion: report.poolVersion });
   renderEnvironment(report, findings);
   renderAgents(report, findings);
+  await renderProject(findings);
   renderSummary(report, findings);
   return options.strict && findings.some((f) => f.kind === "problem") ? 1 : 0;
 }
@@ -5236,6 +5257,57 @@ function renderAgents(report, problems) {
     }
   }
 }
+async function renderProject(problems, options) {
+  const quiet = options?.quiet ?? false;
+  const python = await findBin("python");
+  if (!python) {
+    if (!quiet) {
+      heading("Project");
+      item("fail", "python not on PATH");
+    }
+    problems.push({
+      kind: "problem",
+      text: "python not on PATH",
+      fix: "install Python 3.11 or later (see docs/ONBOARDING.md)"
+    });
+    return { ran: false, exitCode: null };
+  }
+  const bundle = bundlePath("antigravity-plugin", { requireManifest: false });
+  const script = bundle ? path5.join(bundle, "scripts", "claudster_doctor.py") : null;
+  if (!script || !existsSync5(script)) {
+    if (!quiet) {
+      heading("Project");
+      item("fail", "claudster_doctor.py missing");
+    }
+    problems.push({
+      kind: "problem",
+      text: "claudster_doctor.py missing from antigravity-plugin bundle",
+      fix: "reinstall: npm i -g @caddis/cli"
+    });
+    return { ran: false, exitCode: null };
+  }
+  if (!quiet) {
+    heading("Project");
+  }
+  const result = await run(python, [script, "--dest", process2.cwd()], { timeout: 6e4 });
+  if (!quiet && result.stdout) {
+    const lines = result.stdout.replace(/\r\n/g, "\n").split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+      lines.pop();
+    }
+    for (const l2 of lines) {
+      line(l2 ? `    ${l2}` : "");
+    }
+  }
+  if (result.code === 1 || !result.ok) {
+    problems.push({
+      kind: "problem",
+      text: "project health check failed",
+      fix: "read the FAIL lines above"
+    });
+  }
+  return { ran: true, exitCode: result.code };
+}
 function renderSummary(report, findings) {
   heading("Summary");
   const counts = report.agents.reduce(
@@ -5368,7 +5440,7 @@ function problemFor(entry, poolVersion) {
       return null;
   }
 }
-function toJson(report) {
+function toJson(report, project) {
   return {
     cliVersion: report.cliVersion,
     cliUpdate: report.cliUpdate ?? null,
@@ -5389,7 +5461,8 @@ function toJson(report) {
       extrasVersion: entry.status.extras?.version ?? null,
       extrasDrift: entry.extrasDrift ?? null,
       note: entry.status.note ?? entry.detection.note ?? null
-    }))
+    })),
+    project: project ?? { ran: false, exitCode: null }
   };
 }
 var REQUIRED_NODE_MAJOR, REQUIRED_NODE_MINOR;
@@ -5397,7 +5470,9 @@ var init_doctor = __esm({
   "src/commands/doctor.ts"() {
     "use strict";
     init_log();
+    init_exec();
     init_pkg();
+    init_which();
     init_report();
     REQUIRED_NODE_MAJOR = 20;
     REQUIRED_NODE_MINOR = 19;
@@ -5544,19 +5619,7 @@ var {
 
 // src/agents/claude.ts
 init_exec();
-
-// src/util/which.ts
-var import_which = __toESM(require_lib(), 1);
-async function findBin(name) {
-  try {
-    const found = await (0, import_which.default)(name, { nothrow: true });
-    return found ?? null;
-  } catch {
-    return null;
-  }
-}
-
-// src/agents/claude.ts
+init_which();
 var BIN = "claude";
 var MARKETPLACE = "caddis";
 var PLUGIN = "caddis@caddis";
@@ -5592,14 +5655,14 @@ function* pluginBlocks(stdout) {
   if (current) yield current;
 }
 async function detect() {
-  const path5 = await findBin(BIN);
-  if (!path5) {
+  const path6 = await findBin(BIN);
+  if (!path6) {
     return { present: false, note: "no `claude` binary on PATH" };
   }
   const version = await run(BIN, ["--version"], { timeout: 2e4 });
   return {
     present: true,
-    path: path5,
+    path: path6,
     agentVersion: version.ok ? version.stdout.trim().split(/\s+/)[0] || void 0 : void 0,
     note: version.ok ? void 0 : "binary found but `claude --version` failed"
   };
@@ -5630,6 +5693,7 @@ async function status() {
 function steps(action) {
   if (action === "install") {
     return [
+      { cmd: BIN, args: ["plugin", "marketplace", "add", "saajunaid/caddis-plugin"] },
       { cmd: BIN, args: ["plugin", "marketplace", "update", MARKETPLACE] },
       { cmd: BIN, args: ["plugin", "install", PLUGIN] }
     ];
@@ -5657,13 +5721,25 @@ async function drive(action, options) {
   for (const step of planned) {
     const command = formatCommand(step.cmd, step.args);
     const result = await run(step.cmd, step.args);
+    const isMarketplaceAdd = step.args[1] === "marketplace" && step.args[2] === "add";
+    const isMarketplaceUpdate = step.args[1] === "marketplace" && step.args[2] === "update";
+    let ok = result.ok;
+    let code = result.code;
+    if (!ok && isMarketplaceAdd) {
+      const output = `${result.stdout}
+${result.stderr}`;
+      if (/already (exists|added|configured|installed|on disk)/i.test(output)) {
+        ok = true;
+        code = 0;
+      }
+    }
     results.push({
       command,
-      ok: result.ok,
-      code: result.code,
-      output: result.ok ? void 0 : tail(result.stderr || result.stdout || result.failure || "")
+      ok,
+      code,
+      output: ok ? void 0 : tail(result.stderr || result.stdout || result.failure || "")
     });
-    if (!result.ok && step.args[1] !== "marketplace") {
+    if (!ok && !isMarketplaceUpdate) {
       return { ok: false, skipped: false, steps: results, message: `\`${command}\` failed` };
     }
   }
@@ -5684,10 +5760,11 @@ var claudeAdapter = {
 
 // src/agents/agy.ts
 init_exec();
+init_which();
+init_pkg();
 import { readFileSync as readFileSync2, existsSync as existsSync2, mkdtempSync, cpSync, rmSync } from "fs";
 import os from "os";
 import path2 from "path";
-init_pkg();
 var BIN2 = "agy";
 var BUNDLE = "antigravity-plugin";
 var PLUGIN2 = "caddis";
@@ -5815,24 +5892,24 @@ async function drive2(_action, options) {
   }
   const cleanups = [];
   try {
-    const steps2 = [];
+    const steps3 = [];
     for (const step of planned) {
       const command = formatCommand(step.cmd, step.args);
       const staged = stageForAgy(step.bundleDir);
       cleanups.push(staged.cleanup);
       const execArgs = [...step.args.slice(0, -1), staged.installPath];
       const result = await run(step.cmd, execArgs);
-      steps2.push({
+      steps3.push({
         command,
         ok: result.ok,
         code: result.code,
         output: result.ok ? void 0 : (result.stderr || result.stdout || result.failure || "").trim().split(/\r?\n/).slice(-3).join("\n")
       });
       if (!result.ok) {
-        return { ok: false, skipped: false, steps: steps2, message: `\`${command}\` failed` };
+        return { ok: false, skipped: false, steps: steps3, message: `\`${command}\` failed` };
       }
     }
-    return { ok: true, skipped: false, steps: steps2 };
+    return { ok: true, skipped: false, steps: steps3 };
   } finally {
     cleanups.forEach((fn) => fn());
   }
@@ -5849,12 +5926,14 @@ var agyAdapter = {
 
 // src/agents/codex.ts
 init_exec();
-import { cpSync as cpSync2, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, rmSync as rmSync2, writeFileSync } from "fs";
+init_which();
+import { existsSync as existsSync3, rmSync as rmSync2 } from "fs";
 import os2 from "os";
 import path3 from "path";
-init_pkg();
 var BIN3 = "codex";
-var BUNDLE2 = "codex";
+var MARKETPLACE_URL = "https://github.com/saajunaid/caddis-plugin";
+var MARKETPLACE2 = "caddis";
+var PLUGIN3 = "caddis-codex@caddis";
 function caddisSkillsDir(home = os2.homedir()) {
   return path3.join(home, ".codex", "skills", "caddis");
 }
@@ -5874,7 +5953,6 @@ async function detect3() {
   return {
     present: true,
     path: binPath,
-    // `codex --version` prints "codex-cli 0.150.1"; take the trailing token.
     agentVersion: version.ok ? version.stdout.trim().split(/\s+/).pop() || void 0 : void 0,
     note: version.ok ? void 0 : "binary found but `codex --version` failed"
   };
@@ -5883,104 +5961,146 @@ function shortenHome2(target) {
   const home = os2.homedir();
   return target.startsWith(home) ? path3.join("~", target.slice(home.length)) : target;
 }
-function statusFromHome2(home) {
-  const marker = versionFile(home);
-  const dir = caddisSkillsDir(home);
-  if (existsSync3(marker)) {
-    try {
-      const version = readFileSync3(marker, "utf8").trim();
-      if (version) return { installed: true, version, source: shortenHome2(marker) };
-    } catch {
+function parseCodexPluginList(stdout, plugin = PLUGIN3) {
+  const wanted = plugin.toLowerCase();
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const line2 = rawLine.trim();
+    if (!line2.toLowerCase().startsWith(wanted)) continue;
+    const rest = line2.slice(wanted.length).trim();
+    if (/^not installed/i.test(rest)) {
+      return { installed: false };
+    }
+    const match = rest.match(/^installed,\s*(enabled|disabled)(?:\s+([^\s]+))?/i);
+    if (match) {
+      return {
+        installed: true,
+        disabled: match[1]?.toLowerCase() === "disabled",
+        version: match[2]
+      };
+    }
+    const simpleMatch = rest.match(/^installed(?:\s+([^\s]+))?/i);
+    if (simpleMatch) {
+      return {
+        installed: true,
+        disabled: false,
+        version: simpleMatch[1]
+      };
     }
-    return { installed: true, source: shortenHome2(marker), note: "version marker present but unreadable" };
-  }
-  if (existsSync3(dir)) {
-    return {
-      installed: true,
-      source: shortenHome2(dir),
-      note: "skills present but no version marker \u2014 installed by hand, or by a caddis older than this one"
-    };
   }
-  return { installed: false, source: shortenHome2(dir), note: "caddis skills not installed into codex" };
+  return null;
 }
 async function status3() {
   const detected = await detect3();
   if (!detected.present) return { installed: false, note: "agent not installed" };
-  return statusFromHome2(os2.homedir());
+  const listed = await run(BIN3, ["plugin", "list"], { timeout: 6e4 });
+  if (!listed.ok) {
+    return {
+      installed: false,
+      source: "`codex plugin list`",
+      note: `could not read plugin list (${listed.failure ?? `exit ${listed.code}`})`
+    };
+  }
+  const entry = parseCodexPluginList(listed.stdout);
+  if (!entry || !entry.installed) {
+    return { installed: false, source: "`codex plugin list`", note: "caddis-codex plugin not installed" };
+  }
+  return {
+    installed: true,
+    version: entry.version,
+    disabled: entry.disabled,
+    source: "`codex plugin list`",
+    note: entry.version ? void 0 : "installed but the version is not reported"
+  };
+}
+function steps2(action) {
+  if (action === "install") {
+    return [
+      { cmd: BIN3, args: ["plugin", "marketplace", "add", MARKETPLACE_URL] },
+      { cmd: BIN3, args: ["plugin", "add", PLUGIN3] }
+    ];
+  }
+  return [
+    { cmd: BIN3, args: ["plugin", "marketplace", "upgrade", MARKETPLACE2] },
+    { cmd: BIN3, args: ["plugin", "add", PLUGIN3] }
+  ];
 }
 async function drive3(action, options) {
   const detected = await detect3();
   if (!detected.present) {
     return { ok: true, skipped: true, steps: [], message: "codex not installed \u2014 skipped" };
   }
-  const bundle = bundlePath(BUNDLE2, { requireManifest: false });
-  if (!bundle) {
-    return {
-      ok: false,
-      skipped: false,
-      steps: [],
-      message: `the ${BUNDLE2} bundle is missing from this package \u2014 reinstall @caddis/cli`
-    };
-  }
-  const source = path3.join(bundle, ".codex", "skills");
-  if (!existsSync3(source)) {
-    return {
-      ok: false,
-      skipped: false,
-      steps: [],
-      message: `the ${BUNDLE2} bundle has no .codex/skills directory \u2014 the export shape changed`
-    };
-  }
   const home = os2.homedir();
-  const dest = caddisSkillsDir(home);
-  const version = bundleManifest().poolVersion || "unknown";
-  const label = `copy ${BUNDLE2} skills -> ${shortenHome2(dest)}`;
-  const steps2 = [];
+  const legacyDir = caddisSkillsDir(home);
+  const legacyMarker = versionFile(home);
+  const hasLegacyMarker = existsSync3(legacyMarker);
+  const planned = steps2(action);
+  const removalCommand = `remove legacy ${shortenHome2(legacyDir)}`;
   if (options.dryRun) {
-    return {
-      ok: true,
-      skipped: true,
-      steps: [{ command: label, ok: true, code: 0 }],
-      message: `dry run \u2014 would ${action} caddis ${version} into ${shortenHome2(dest)}`
-    };
+    const plannedSteps = planned.map((step) => ({ command: formatCommand(step.cmd, step.args), ok: true, code: null }));
+    if (hasLegacyMarker) {
+      plannedSteps.push({ command: removalCommand, ok: true, code: null });
+    }
+    return { ok: true, skipped: true, steps: plannedSteps, message: "dry run \u2014 nothing executed" };
   }
-  try {
-    if (existsSync3(dest)) rmSync2(dest, { recursive: true, force: true });
-    mkdirSync(path3.dirname(dest), { recursive: true });
-    cpSync2(source, dest, { recursive: true });
-    writeFileSync(versionFile(home), `${version}
-`, "utf8");
-    steps2.push({ command: label, ok: true, code: 0 });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    steps2.push({ command: label, ok: false, code: null, output: message });
-    return { ok: false, skipped: false, steps: steps2, message: `could not install into codex: ${message}` };
+  const results = [];
+  for (const step of planned) {
+    const command = formatCommand(step.cmd, step.args);
+    const result = await run(step.cmd, step.args);
+    const isMarketplaceAdd = step.args[1] === "marketplace" && step.args[2] === "add";
+    const isMarketplaceUpgrade = step.args[1] === "marketplace" && step.args[2] === "upgrade";
+    let ok = result.ok;
+    let code = result.code;
+    if (!ok && isMarketplaceAdd) {
+      const output = `${result.stdout}
+${result.stderr}`;
+      if (/already (exists|added|configured|installed)/i.test(output)) {
+        ok = true;
+        code = 0;
+      }
+    }
+    results.push({
+      command,
+      ok,
+      code,
+      output: ok ? void 0 : tail2(result.stderr || result.stdout || result.failure || "")
+    });
+    if (!ok && !isMarketplaceUpgrade) {
+      return { ok: false, skipped: false, steps: results, message: `\`${command}\` failed` };
+    }
   }
-  const notes = [];
-  for (const asset of ["AGENTS.md", path3.join(".codex", "config.toml.example")]) {
-    const from = path3.join(bundle, asset);
-    if (!existsSync3(from)) continue;
-    const to = path3.join(dest, `caddis-${path3.basename(asset)}`);
+  if (hasLegacyMarker) {
     try {
-      cpSync2(from, to);
-      notes.push(path3.basename(to));
-    } catch {
+      rmSync2(legacyDir, { recursive: true, force: true });
+      results.push({ command: removalCommand, ok: true, code: 0 });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      results.push({ command: removalCommand, ok: false, code: null, output: message });
     }
   }
-  const extrasNote = options.extras ? " (--extras has no codex bundle yet; core only)" : "";
-  const referenceNote = notes.length ? ` Reference copies beside it: ${notes.join(", ")} \u2014 config.toml is NEVER merged for you.` : "";
+  const notes = [];
+  if (!hasLegacyMarker && existsSync3(legacyDir)) {
+    notes.push(
+      `${shortenHome2(legacyDir)} exists but caddis did not write it (no version marker), so it was left in place; Codex may list the same skills twice. Remove it by hand if you do not need it.`
+    );
+  }
+  if (options.extras) {
+    notes.push("--extras has no Codex plugin; core only");
+  }
   return {
     ok: true,
     skipped: false,
-    steps: steps2,
-    message: `caddis ${version} ${action === "install" ? "installed" : "updated"} in ${shortenHome2(dest)}.${referenceNote}${extrasNote}`
+    steps: results,
+    ...notes.length ? { message: notes.join(" ") } : {}
   };
 }
+function tail2(text, lines = 3) {
+  return text.trim().split(/\r?\n/).slice(-lines).join("\n");
+}
 var codexAdapter = {
   id: "codex",
   name: "Codex",
   supported: true,
-  summary: "copy the caddis skill pool into ~/.codex/skills/caddis/ (config.toml never merged)",
+  summary: "install the caddis-codex plugin from the caddis marketplace (config.toml never merged)",
   detect: detect3,
   drive: drive3,
   status: status3
@@ -5990,6 +6110,7 @@ var codexAdapter = {
 import path4 from "path";
 
 // src/agents/stub.ts
+init_which();
 import { existsSync as existsSync4 } from "fs";
 var NOT_YET_SUPPORTED = "not yet supported (v0.2)";
 function createStubAdapter(spec) {

package/package.json

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