Skip to content

Official Codebase of 3DCodeVerse

Python

doctor: the environment checks move out of cli/ to codeverse/doctor.py

gaoypengb99691f0ab41
diff --git a/harness/codeverse/cli/doctor.py b/harness/codeverse/cli/doctor.py
index 4bcd3215..a4e6486b 100644
--- a/harness/codeverse/cli/doctor.py
+++ b/harness/codeverse/cli/doctor.py
@@ -1,314 +1,17 @@
-"""``3dcv doctor`` — environment checks (deps, Blender, node/three/chrome, keys, CLIs, MCP)."""
+"""``3dcv doctor`` — the typer shim over :mod:`codeverse.doctor`."""
from __future__ import annotations
-import importlib
import json
-import shutil
-import subprocess
-from pathlib import Path
from typing import Annotated
import typer
from codeverse.cli._common import console, doctor_table
-from codeverse.config import get_settings
+from codeverse.doctor import run_doctor
doctor_app = typer.Typer(invoke_without_command=True)
-Row = tuple[str, str, str]
-_PY_DEPS = ("pydantic", "pydantic_settings", "typer", "rich", "jinja2", "yaml", "numpy", "trimesh", "fcl", "PIL", "pyarrow",
- "scipy", "shapely", "networkx", "manifold3d", "google.genai", "anthropic", "openai",
- "yourdfpy", "mcp", "moderngl", "cadquery")
-#: modules that come from an OPTIONAL extra: missing means one track is unavailable, not a
-#: broken install, so they are a WARN naming the extra to install. `moderngl` and `cadquery`
-#: were absent from the list entirely until 2026-08-24, so an environment installed without
-#: [graphics] passed doctor "21/21 importable" and then failed in the graphics track with
-#: "no usable OpenGL context: No module named 'moderngl'" — a missing pip package reported
-#: as a GPU/driver problem (docs/INSTALL.md §4 promises every extra is listed here).
-#: EVERY module of every extra must be here, or the base install misreports itself: the
-#: map was missing scipy/networkx/pyarrow, so a fresh clone installed exactly as
-#: docs/INSTALL.md §1 documents (no extras) got `python deps FAIL 14/23` — "your install
-#: is broken" for an install that is correct — and a remedy that named four of the five
-#: extras and could not clear the row. Verified on a 3.13 clean clone, 2026-08-24.
-_OPTIONAL_DEPS = {"manifold3d": "mesh", "shapely": "mesh", "networkx": "mesh",
- "yourdfpy": "urdf", "scipy": "urdf", "mcp": "mcp",
- "moderngl": "graphics", "cadquery": "cad", "pyarrow": "flywheel"}
-_CLI_TIMEOUT = 25
-
-
-def _ver(cmd: list[str], timeout: int = _CLI_TIMEOUT) -> tuple[bool, str]:
- if not shutil.which(cmd[0]) and not Path(cmd[0]).is_file():
- return False, "not found"
- try:
- p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
- except subprocess.TimeoutExpired:
- return False, f"timed out after {timeout}s"
- except OSError as e:
- return False, str(e)
- out = (p.stdout or p.stderr).strip().splitlines()
- first = out[0].strip() if out else ""
- return p.returncode == 0, first[:100] or f"exit {p.returncode}"
-
-
-def check_python_deps() -> list[Row]:
- missing, present = [], []
- for mod in _PY_DEPS:
- try:
- importlib.import_module(mod)
- present.append(mod)
- except Exception: # ImportError or a broken native lib
- missing.append(mod)
- import sys
-
- rows: list[Row] = [("python", "OK", sys.version.split()[0] + f" ({sys.executable})")]
- status = "OK" if not missing else ("WARN" if set(missing) <= set(_OPTIONAL_DEPS) else "FAIL")
- detail = f"{len(present)}/{len(_PY_DEPS)} importable" + (f"; missing: {', '.join(missing)}" if missing else "")
- extras = sorted({_OPTIONAL_DEPS[m] for m in missing if m in _OPTIONAL_DEPS})
- if extras: # name the fix, not just the symptom
- detail += f"; fix: pip install -e 'harness[{','.join(extras)}]'"
- rows.append(("python deps", status, detail))
- return rows
-
-
-def check_blender() -> list[Row]:
- s = get_settings()
- b = s.resolve_blender()
- if not b:
- return [("blender", "FAIL", "no binary (set CV3D_BINARIES__BLENDER or put blender-5.0 on PATH)")]
- okk, v = _ver([b, "--version"], timeout=60)
- return [("blender", "OK" if okk else "FAIL", f"{v} @ {b}")]
-
-
-def check_node() -> list[Row]:
- from codeverse.spatial.node import NODE_MIN_STR, node_version_error, parse_node_version
-
- s = get_settings()
- rows: list[Row] = []
- okk, v = _ver([s.binaries.node, "--version"])
- too_old = node_version_error(parse_node_version(v)) if okk else ""
- if too_old:
- rows.append(("node", "FAIL", f"{v} — too old, need >= {NODE_MIN_STR} (nvm install --lts)"))
- else:
- rows.append(("node", "OK" if okk else "FAIL", v if okk else f"{v} (need >= {NODE_MIN_STR})"))
- try:
- rj = s.runtime_js_dir()
- except RuntimeError as e: # non-editable install without CV3D_RUNTIME_JS
- rows.append(("runtime_js", "FAIL", str(e)))
- return rows
- three = rj / "node_modules" / "three" / "package.json"
- pup = rj / "node_modules" / "puppeteer" / "package.json"
- if three.is_file():
- rows.append(("three", "OK", json.loads(three.read_text()).get("version", "?") + f" ({rj / 'node_modules'})"))
- else:
- rows.append(("three", "FAIL", f"runtime_js/node_modules/three missing — run `npm install` in {rj}"))
- if pup.is_file():
- cache = Path.home() / ".cache" / "puppeteer"
- chrome = any(cache.rglob("chrome")) if cache.is_dir() else False
- rows.append(("puppeteer", "OK" if chrome else "WARN",
- f"v{json.loads(pup.read_text()).get('version', '?')}; chrome cache {'found' if chrome else 'missing'} ({cache})"))
- else:
- rows.append(("puppeteer", "FAIL", "not installed in runtime_js"))
- return rows
-
-
-_PROBE_JS = (
- "const {launchBrowser}=require(process.argv[1]);"
- "launchBrowser({gpu:'auto'}).then(async r=>{console.log(JSON.stringify({gpu:r.gpu,renderer:r.renderer}));"
- "await r.browser.close();process.exit(0)}).catch(e=>{console.log(JSON.stringify({error:String(e&&e.message||e)}));process.exit(1)})"
-)
-
-
-def check_gpu_probe(timeout_s: int = 120) -> list[Row]:
- """Launch headless Chrome through runtime_js/gpu_launch.cjs and report the WebGL renderer."""
- from codeverse.proc import run_subprocess
-
- s = get_settings()
- try:
- rj = s.runtime_js_dir()
- except RuntimeError as e:
- return [("chrome webgl", "FAIL", str(e))]
- launcher = rj / "gpu_launch.cjs"
- if not launcher.is_file():
- return [("chrome webgl", "SKIP", f"{launcher} missing (spatial render package not installed yet)")]
- cmd = [s.binaries.node, "-e", _PROBE_JS, str(launcher)]
- try:
- proc = run_subprocess(cmd, cwd=rj, timeout_s=timeout_s)
- except OSError as e:
- return [("chrome webgl", "FAIL", str(e))]
- if proc.timed_out:
- return [("chrome webgl", "FAIL", f"probe timed out after {timeout_s}s")]
- line = next((ln for ln in reversed(proc.stdout.strip().splitlines()) if ln.startswith("{")), "")
- try:
- res = json.loads(line) if line else {}
- except ValueError:
- res = {}
- if "error" in res or proc.returncode != 0:
- detail = str(res.get("error") or (proc.stderr.strip().splitlines() or ["unknown error"])[-1])
- return [("chrome webgl", "FAIL", detail[:160])]
- renderer = str(res.get("renderer", "?"))
- return [("chrome webgl", "OK" if res.get("gpu") else "WARN",
- f"{'GPU' if res.get('gpu') else 'CPU/software'}: {renderer[:120]}")]
-
-
-def check_pool(live: bool) -> list[Row]:
- """The key pool's live scheduling picture: quota, headroom, storm counters.
-
- Only meaningful once something has used the pool this process, so it is part
- of ``--live`` (``check_keys`` makes one call just before)."""
- from codeverse.models.gemini import shared_pool
- from codeverse.models.retry import all_gates
-
- s = get_settings()
- if not s.gemini_api_keys:
- return []
- r = s.rate
- pool = shared_pool(list(s.gemini_api_keys))
- st = pool.stats()
- rows: list[Row] = [(
- "gemini quota", "OK",
- f"{st['n_keys']} keys x {r.rpm_per_key} RPM / {r.tpm_per_key:,} TPM "
- f"= {st['rpm_capacity']:,} RPM / {st['tpm_capacity']:,} TPM pool-wide"
- f"; max_in_flight={r.max_in_flight or 'off'}",
- )]
- if live:
- used_rpm = 100 * (1 - st["rpm_headroom"])
- used_tpm = "n/a" if st["tpm_headroom"] is None else f"{100 * (1 - st['tpm_headroom']):.1f}%"
- bad = st["429"] + st["5xx"] + st["dead"]
- rows.append((
- "gemini pool", "WARN" if st["n_dead"] else "OK",
- f"in-flight {st['in_flight']} (peak {st['peak_in_flight']}) · "
- f"RPM used {used_rpm:.1f}% · TPM used {used_tpm} · "
- f"{st['acquired']} acquired, {st['ok']} ok, {st['429']} x429, {st['5xx']} x5xx, "
- f"{st['n_dead']} dead, {st['n_cooling']} cooling"
- + ("" if not bad else " (this process)"),
- ))
- for gate in all_gates():
- g = gate.snapshot()
- rows.append((
- f"storm gate {g['name'].split(':')[-1]}"[:24],
- "WARN" if g["storming"] else "OK",
- f"{g['storms']} storm(s), {g['hits']} x503, {g['probes']} probes, "
- f"{g['parked_s']}s parked"
- + (f" — CLOSED for {g['closed_for_s']}s" if g["storming"] else ""),
- ))
- return rows
-
-
-def _rate_cap() -> int:
- from codeverse.config import get_settings
-
- return int(getattr(get_settings().rate, "max_in_flight", 0) or 0)
-
-
-def check_keys(live: bool) -> list[Row]:
- s = get_settings()
- n = len(s.gemini_api_keys)
- rows: list[Row] = [("gemini keys", "OK" if n else "FAIL", f"{n} key(s)")]
- if n:
- from codeverse.models.health import pool_budget
-
- pb = pool_budget()
- cap = _rate_cap()
- rows.append((
- "pool sharing",
- "OK" if pb.fits(cap) else "WARN",
- (f"{pb}; this process at {cap} {'fits' if pb.fits(cap) else 'does NOT fit'} "
- f"(docs/COST.md §23: keep the SUM at or under {pb.knee}"
- + ("" if pb.fits(cap) else f" — set CV3D_MAX_IN_FLIGHT={max(1, pb.headroom)} or wait") + ")")
- if pb.siblings else "sole harness process: max_in_flight applies as configured",
- ))
- rows.append(("anthropic key", "OK" if s.anthropic_api_key else "WARN", "set" if s.anthropic_api_key else "not set (anthropic:* backends unavailable)"))
- rows.append(("openai key", "OK" if s.openai_api_key else "WARN", "set" if s.openai_api_key else "not set (openai:* backends unavailable)"))
- if live and n:
- try:
- from codeverse.contracts.chat import ChatMessage, ChatRequest
- from codeverse.models import get_chat_model
-
- m = get_chat_model("gemini:gemini-3.7-flash")
- r = m.generate(ChatRequest(messages=[ChatMessage.user("Reply with the single word: pong")],
- # 256, not 16: gemini-3.x spends output tokens on thoughts even
- # with thinking="off", and a 16-token budget comes back empty
- temperature=0.0, max_output_tokens=256, thinking="off", label="doctor"))
- rows.append(("gemini live call", "OK" if "pong" in r.text.lower() else "WARN",
- f"{r.text.strip()[:40]!r} cost=${r.usage.cost_usd:.5f}"))
- except Exception as e:
- rows.append(("gemini live call", "FAIL", f"{type(e).__name__}: {str(e)[:120]}"))
- return rows
-
-
-def check_clis() -> list[Row]:
- s = get_settings()
- rows: list[Row] = []
- for name, binary in (("gemini-cli", s.binaries.gemini_cli), ("claude", s.binaries.claude_cli),
- ("codex", s.binaries.codex_cli), ("agy", s.binaries.agy_cli)):
- okk, v = _ver([binary, "--version"])
- rows.append((name, "OK" if okk else "WARN", v if okk else f"{v} (backend {name} unavailable)"))
- okk, v = _ver(["git", "--version"])
- rows.append(("git", "OK" if okk else "FAIL", v))
- okk, v = _ver([s.binaries.ffmpeg, "-version"])
- rows.append(("ffmpeg", "OK" if okk else "WARN", v if okk else "not found (turntable mp4 disabled)"))
- return rows
-
-
-def check_mcp() -> list[Row]:
- try:
- importlib.import_module("mcp")
- except ImportError:
- return [("mcp", "WARN", "python package `mcp` missing (MCP server for CLIs unavailable)")]
- try:
- importlib.import_module("codeverse.spatial.mcp_server")
- return [("mcp", "OK", "mcp + codeverse.spatial.mcp_server importable")]
- except ImportError as e:
- return [("mcp", "WARN", f"codeverse.spatial.mcp_server not importable ({e})")]
-
-
-def check_skills() -> list[Row]:
- """The static half of the live CLI smoke: is the library there, valid, and reachable?
-
- A CLI upgrade that moves its skills root ships an empty index and the run still
- passes — the failure is invisible except as a read rate of zero a battery later. So
- the wiring gets a check you can run before spending money."""
- from codeverse.agents.backends import ALLOWED_TOOLS
- from codeverse.skills import bundle_dirs, skills_dir, validate_bundle
- from codeverse.skills.config import skills_enabled
- from codeverse.skills.materialize import SKILL_ROOTS
- from codeverse.skills.registry import ROUTED_SKILLS
-
- rows: list[Row] = [("skills switch", "OK" if skills_enabled() else "WARN",
- "CV3D_SKILLS=on" if skills_enabled() else "CV3D_SKILLS is off (default): no skill is attached")]
- dirs = bundle_dirs()
- if not dirs:
- rows.append(("skills library", "WARN", f"no bundles under {skills_dir()}"))
- else:
- bad = {d.name: validate_bundle(d) for d in dirs}
- bad = {k: v for k, v in bad.items() if v}
- rows.append(("skills library", "FAIL" if bad else "OK",
- f"{len(dirs)} bundles, {len(bad)} invalid" + (f": {', '.join(bad)}" if bad else "")))
- missing = [n for n in ROUTED_SKILLS if n not in {d.name for d in dirs}]
- if missing:
- rows.append(("skills routing", "WARN", f"{len(missing)} routed skill(s) have no bundle: {', '.join(missing[:4])}…"))
- rows.append(("skills discovery", "OK", "materialised into " + " + ".join(SKILL_ROOTS)))
- rows.append(("claude-code Skill tool", "OK" if "Skill" in ALLOWED_TOOLS else "FAIL",
- "in --allowedTools" if "Skill" in ALLOWED_TOOLS else "missing: claude-code would deny skill activation"))
- return rows
-
-
-def run_doctor(*, live: bool = False, gpu: bool = True, skills: bool = False) -> list[Row]:
- rows: list[Row] = []
- rows += check_python_deps()
- rows += check_blender()
- rows += check_node()
- if gpu:
- rows += check_gpu_probe()
- rows += check_keys(live)
- rows += check_pool(live)
- rows += check_clis()
- rows += check_mcp()
- if skills:
- rows += check_skills()
- return rows
-
@doctor_app.callback(invoke_without_command=True)
def doctor(
diff --git a/harness/codeverse/doctor.py b/harness/codeverse/doctor.py
new file mode 100644
index 00000000..468179b3
--- /dev/null
+++ b/harness/codeverse/doctor.py
@@ -0,0 +1,308 @@
+"""Environment checks behind ``3dcv doctor`` — python deps, Blender, node/three/
+puppeteer, the GPU probe, keys, the pool admission numbers, the vendor CLIs, MCP
+and the skill library wiring. Moved out of ``cli/`` 2026-08-28: only the typer
+shim is a CLI concern (tests/install imports these checks as documentation facts).
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from codeverse.config import get_settings
+
+Row = tuple[str, str, str]
+_PY_DEPS = ("pydantic", "pydantic_settings", "typer", "rich", "jinja2", "yaml", "numpy", "trimesh", "fcl", "PIL", "pyarrow",
+ "scipy", "shapely", "networkx", "manifold3d", "google.genai", "anthropic", "openai",
+ "yourdfpy", "mcp", "moderngl", "cadquery")
+#: modules that come from an OPTIONAL extra: missing means one track is unavailable, not a
+#: broken install, so they are a WARN naming the extra to install. `moderngl` and `cadquery`
+#: were absent from the list entirely until 2026-08-24, so an environment installed without
+#: [graphics] passed doctor "21/21 importable" and then failed in the graphics track with
+#: "no usable OpenGL context: No module named 'moderngl'" — a missing pip package reported
+#: as a GPU/driver problem (docs/INSTALL.md §4 promises every extra is listed here).
+#: EVERY module of every extra must be here, or the base install misreports itself: the
+#: map was missing scipy/networkx/pyarrow, so a fresh clone installed exactly as
+#: docs/INSTALL.md §1 documents (no extras) got `python deps FAIL 14/23` — "your install
+#: is broken" for an install that is correct — and a remedy that named four of the five
+#: extras and could not clear the row. Verified on a 3.13 clean clone, 2026-08-24.
+_OPTIONAL_DEPS = {"manifold3d": "mesh", "shapely": "mesh", "networkx": "mesh",
+ "yourdfpy": "urdf", "scipy": "urdf", "mcp": "mcp",
+ "moderngl": "graphics", "cadquery": "cad", "pyarrow": "flywheel"}
+_CLI_TIMEOUT = 25
+
+
+def _ver(cmd: list[str], timeout: int = _CLI_TIMEOUT) -> tuple[bool, str]:
+ if not shutil.which(cmd[0]) and not Path(cmd[0]).is_file():
+ return False, "not found"
+ try:
+ p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
+ except subprocess.TimeoutExpired:
+ return False, f"timed out after {timeout}s"
+ except OSError as e:
+ return False, str(e)
+ out = (p.stdout or p.stderr).strip().splitlines()
+ first = out[0].strip() if out else ""
+ return p.returncode == 0, first[:100] or f"exit {p.returncode}"
+
+
+def check_python_deps() -> list[Row]:
+ missing, present = [], []
+ for mod in _PY_DEPS:
+ try:
+ importlib.import_module(mod)
+ present.append(mod)
+ except Exception: # ImportError or a broken native lib
+ missing.append(mod)
+ import sys
+
+ rows: list[Row] = [("python", "OK", sys.version.split()[0] + f" ({sys.executable})")]
+ status = "OK" if not missing else ("WARN" if set(missing) <= set(_OPTIONAL_DEPS) else "FAIL")
+ detail = f"{len(present)}/{len(_PY_DEPS)} importable" + (f"; missing: {', '.join(missing)}" if missing else "")
+ extras = sorted({_OPTIONAL_DEPS[m] for m in missing if m in _OPTIONAL_DEPS})
+ if extras: # name the fix, not just the symptom
+ detail += f"; fix: pip install -e 'harness[{','.join(extras)}]'"
+ rows.append(("python deps", status, detail))
+ return rows
+
+
+def check_blender() -> list[Row]:
+ s = get_settings()
+ b = s.resolve_blender()
+ if not b:
+ return [("blender", "FAIL", "no binary (set CV3D_BINARIES__BLENDER or put blender-5.0 on PATH)")]
+ okk, v = _ver([b, "--version"], timeout=60)
+ return [("blender", "OK" if okk else "FAIL", f"{v} @ {b}")]
+
+
+def check_node() -> list[Row]:
+ from codeverse.spatial.node import NODE_MIN_STR, node_version_error, parse_node_version
+
+ s = get_settings()
+ rows: list[Row] = []
+ okk, v = _ver([s.binaries.node, "--version"])
+ too_old = node_version_error(parse_node_version(v)) if okk else ""
+ if too_old:
+ rows.append(("node", "FAIL", f"{v} — too old, need >= {NODE_MIN_STR} (nvm install --lts)"))
+ else:
+ rows.append(("node", "OK" if okk else "FAIL", v if okk else f"{v} (need >= {NODE_MIN_STR})"))
+ try:
+ rj = s.runtime_js_dir()
+ except RuntimeError as e: # non-editable install without CV3D_RUNTIME_JS
+ rows.append(("runtime_js", "FAIL", str(e)))
+ return rows
+ three = rj / "node_modules" / "three" / "package.json"
+ pup = rj / "node_modules" / "puppeteer" / "package.json"
+ if three.is_file():
+ rows.append(("three", "OK", json.loads(three.read_text()).get("version", "?") + f" ({rj / 'node_modules'})"))
+ else:
+ rows.append(("three", "FAIL", f"runtime_js/node_modules/three missing — run `npm install` in {rj}"))
+ if pup.is_file():
+ cache = Path.home() / ".cache" / "puppeteer"
+ chrome = any(cache.rglob("chrome")) if cache.is_dir() else False
+ rows.append(("puppeteer", "OK" if chrome else "WARN",
+ f"v{json.loads(pup.read_text()).get('version', '?')}; chrome cache {'found' if chrome else 'missing'} ({cache})"))
+ else:
+ rows.append(("puppeteer", "FAIL", "not installed in runtime_js"))
+ return rows
+
+
+_PROBE_JS = (
+ "const {launchBrowser}=require(process.argv[1]);"
+ "launchBrowser({gpu:'auto'}).then(async r=>{console.log(JSON.stringify({gpu:r.gpu,renderer:r.renderer}));"
+ "await r.browser.close();process.exit(0)}).catch(e=>{console.log(JSON.stringify({error:String(e&&e.message||e)}));process.exit(1)})"
+)
+
+
+def check_gpu_probe(timeout_s: int = 120) -> list[Row]:
+ """Launch headless Chrome through runtime_js/gpu_launch.cjs and report the WebGL renderer."""
+ from codeverse.proc import run_subprocess
+
+ s = get_settings()
+ try:
+ rj = s.runtime_js_dir()
+ except RuntimeError as e:
+ return [("chrome webgl", "FAIL", str(e))]
+ launcher = rj / "gpu_launch.cjs"
+ if not launcher.is_file():
+ return [("chrome webgl", "SKIP", f"{launcher} missing (spatial render package not installed yet)")]
+ cmd = [s.binaries.node, "-e", _PROBE_JS, str(launcher)]
+ try:
+ proc = run_subprocess(cmd, cwd=rj, timeout_s=timeout_s)
+ except OSError as e:
+ return [("chrome webgl", "FAIL", str(e))]
+ if proc.timed_out:
+ return [("chrome webgl", "FAIL", f"probe timed out after {timeout_s}s")]
+ line = next((ln for ln in reversed(proc.stdout.strip().splitlines()) if ln.startswith("{")), "")
+ try:
+ res = json.loads(line) if line else {}
+ except ValueError:
+ res = {}
+ if "error" in res or proc.returncode != 0:
+ detail = str(res.get("error") or (proc.stderr.strip().splitlines() or ["unknown error"])[-1])
+ return [("chrome webgl", "FAIL", detail[:160])]
+ renderer = str(res.get("renderer", "?"))
+ return [("chrome webgl", "OK" if res.get("gpu") else "WARN",
+ f"{'GPU' if res.get('gpu') else 'CPU/software'}: {renderer[:120]}")]
+
+
+def check_pool(live: bool) -> list[Row]:
+ """The key pool's live scheduling picture: quota, headroom, storm counters.
+
+ Only meaningful once something has used the pool this process, so it is part
+ of ``--live`` (``check_keys`` makes one call just before)."""
+ from codeverse.models.gemini import shared_pool
+ from codeverse.models.retry import all_gates
+
+ s = get_settings()
+ if not s.gemini_api_keys:
+ return []
+ r = s.rate
+ pool = shared_pool(list(s.gemini_api_keys))
+ st = pool.stats()
+ rows: list[Row] = [(
+ "gemini quota", "OK",
+ f"{st['n_keys']} keys x {r.rpm_per_key} RPM / {r.tpm_per_key:,} TPM "
+ f"= {st['rpm_capacity']:,} RPM / {st['tpm_capacity']:,} TPM pool-wide"
+ f"; max_in_flight={r.max_in_flight or 'off'}",
+ )]
+ if live:
+ used_rpm = 100 * (1 - st["rpm_headroom"])
+ used_tpm = "n/a" if st["tpm_headroom"] is None else f"{100 * (1 - st['tpm_headroom']):.1f}%"
+ bad = st["429"] + st["5xx"] + st["dead"]
+ rows.append((
+ "gemini pool", "WARN" if st["n_dead"] else "OK",
+ f"in-flight {st['in_flight']} (peak {st['peak_in_flight']}) · "
+ f"RPM used {used_rpm:.1f}% · TPM used {used_tpm} · "
+ f"{st['acquired']} acquired, {st['ok']} ok, {st['429']} x429, {st['5xx']} x5xx, "
+ f"{st['n_dead']} dead, {st['n_cooling']} cooling"
+ + ("" if not bad else " (this process)"),
+ ))
+ for gate in all_gates():
+ g = gate.snapshot()
+ rows.append((
+ f"storm gate {g['name'].split(':')[-1]}"[:24],
+ "WARN" if g["storming"] else "OK",
+ f"{g['storms']} storm(s), {g['hits']} x503, {g['probes']} probes, "
+ f"{g['parked_s']}s parked"
+ + (f" — CLOSED for {g['closed_for_s']}s" if g["storming"] else ""),
+ ))
+ return rows
+
+
+def _rate_cap() -> int:
+ from codeverse.config import get_settings
+
+ return int(getattr(get_settings().rate, "max_in_flight", 0) or 0)
+
+
+def check_keys(live: bool) -> list[Row]:
+ s = get_settings()
+ n = len(s.gemini_api_keys)
+ rows: list[Row] = [("gemini keys", "OK" if n else "FAIL", f"{n} key(s)")]
+ if n:
+ from codeverse.models.health import pool_budget
+
+ pb = pool_budget()
+ cap = _rate_cap()
+ rows.append((
+ "pool sharing",
+ "OK" if pb.fits(cap) else "WARN",
+ (f"{pb}; this process at {cap} {'fits' if pb.fits(cap) else 'does NOT fit'} "
+ f"(docs/COST.md §23: keep the SUM at or under {pb.knee}"
+ + ("" if pb.fits(cap) else f" — set CV3D_MAX_IN_FLIGHT={max(1, pb.headroom)} or wait") + ")")
+ if pb.siblings else "sole harness process: max_in_flight applies as configured",
+ ))
+ rows.append(("anthropic key", "OK" if s.anthropic_api_key else "WARN", "set" if s.anthropic_api_key else "not set (anthropic:* backends unavailable)"))
+ rows.append(("openai key", "OK" if s.openai_api_key else "WARN", "set" if s.openai_api_key else "not set (openai:* backends unavailable)"))
+ if live and n:
+ try:
+ from codeverse.contracts.chat import ChatMessage, ChatRequest
+ from codeverse.models import get_chat_model
+
+ m = get_chat_model("gemini:gemini-3.7-flash")
+ r = m.generate(ChatRequest(messages=[ChatMessage.user("Reply with the single word: pong")],
+ # 256, not 16: gemini-3.x spends output tokens on thoughts even
+ # with thinking="off", and a 16-token budget comes back empty
+ temperature=0.0, max_output_tokens=256, thinking="off", label="doctor"))
+ rows.append(("gemini live call", "OK" if "pong" in r.text.lower() else "WARN",
+ f"{r.text.strip()[:40]!r} cost=${r.usage.cost_usd:.5f}"))
+ except Exception as e:
+ rows.append(("gemini live call", "FAIL", f"{type(e).__name__}: {str(e)[:120]}"))
+ return rows
+
+
+def check_clis() -> list[Row]:
+ s = get_settings()
+ rows: list[Row] = []
+ for name, binary in (("gemini-cli", s.binaries.gemini_cli), ("claude", s.binaries.claude_cli),
+ ("codex", s.binaries.codex_cli), ("agy", s.binaries.agy_cli)):
+ okk, v = _ver([binary, "--version"])
+ rows.append((name, "OK" if okk else "WARN", v if okk else f"{v} (backend {name} unavailable)"))
+ okk, v = _ver(["git", "--version"])
+ rows.append(("git", "OK" if okk else "FAIL", v))
+ okk, v = _ver([s.binaries.ffmpeg, "-version"])
+ rows.append(("ffmpeg", "OK" if okk else "WARN", v if okk else "not found (turntable mp4 disabled)"))
+ return rows
+
+
+def check_mcp() -> list[Row]:
+ try:
+ importlib.import_module("mcp")
+ except ImportError:
+ return [("mcp", "WARN", "python package `mcp` missing (MCP server for CLIs unavailable)")]
+ try:
+ importlib.import_module("codeverse.spatial.mcp_server")
+ return [("mcp", "OK", "mcp + codeverse.spatial.mcp_server importable")]
+ except ImportError as e:
+ return [("mcp", "WARN", f"codeverse.spatial.mcp_server not importable ({e})")]
+
+
+def check_skills() -> list[Row]:
+ """The static half of the live CLI smoke: is the library there, valid, and reachable?
+
+ A CLI upgrade that moves its skills root ships an empty index and the run still
+ passes — the failure is invisible except as a read rate of zero a battery later. So
+ the wiring gets a check you can run before spending money."""
+ from codeverse.agents.backends import ALLOWED_TOOLS
+ from codeverse.skills import bundle_dirs, skills_dir, validate_bundle
+ from codeverse.skills.config import skills_enabled
+ from codeverse.skills.materialize import SKILL_ROOTS
+ from codeverse.skills.registry import ROUTED_SKILLS
+
+ rows: list[Row] = [("skills switch", "OK" if skills_enabled() else "WARN",
+ "CV3D_SKILLS=on" if skills_enabled() else "CV3D_SKILLS is off (default): no skill is attached")]
+ dirs = bundle_dirs()
+ if not dirs:
+ rows.append(("skills library", "WARN", f"no bundles under {skills_dir()}"))
+ else:
+ bad = {d.name: validate_bundle(d) for d in dirs}
+ bad = {k: v for k, v in bad.items() if v}
+ rows.append(("skills library", "FAIL" if bad else "OK",
+ f"{len(dirs)} bundles, {len(bad)} invalid" + (f": {', '.join(bad)}" if bad else "")))
+ missing = [n for n in ROUTED_SKILLS if n not in {d.name for d in dirs}]
+ if missing:
+ rows.append(("skills routing", "WARN", f"{len(missing)} routed skill(s) have no bundle: {', '.join(missing[:4])}…"))
+ rows.append(("skills discovery", "OK", "materialised into " + " + ".join(SKILL_ROOTS)))
+ rows.append(("claude-code Skill tool", "OK" if "Skill" in ALLOWED_TOOLS else "FAIL",
+ "in --allowedTools" if "Skill" in ALLOWED_TOOLS else "missing: claude-code would deny skill activation"))
+ return rows
+
+
+def run_doctor(*, live: bool = False, gpu: bool = True, skills: bool = False) -> list[Row]:
+ rows: list[Row] = []
+ rows += check_python_deps()
+ rows += check_blender()
+ rows += check_node()
+ if gpu:
+ rows += check_gpu_probe()
+ rows += check_keys(live)
+ rows += check_pool(live)
+ rows += check_clis()
+ rows += check_mcp()
+ if skills:
+ rows += check_skills()
+ return rows
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index 8a9e97af..adc73bb1 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -78,6 +78,8 @@ codeverse/
(+ SkillsUsage/SkillRead: what was attached, what was read), chat,
agent (typed AgentJob)
workspace.py run-dir layout + git snapshots
+ doctor.py the environment checks behind `3dcv doctor` (deps, Blender,
+ node, GPU probe, keys, pool admission, vendor CLIs, MCP, skills)
proc.py stdlib-only subprocess + atomic-JSON primitives (ManagedProcess owns every
child's lifecycle: group kill on ANY exception, bounded pumps, stdin writer;
run_subprocess, kill_group, tail, write_json_atomic, scrub_secrets) and the tolerant readers/writer
diff --git a/harness/tests/core/test_config_env_aliases.py b/harness/tests/core/test_config_env_aliases.py
index 380f0da6..c72d866a 100644
--- a/harness/tests/core/test_config_env_aliases.py
+++ b/harness/tests/core/test_config_env_aliases.py
@@ -46,7 +46,7 @@ def test_doctor_prints_a_name_that_is_actually_read():
"""The `pool sharing` row tells people which env var to set; it must be one that works."""
from pathlib import Path
- src = (Path(__file__).resolve().parents[2] / "codeverse" / "cli" / "doctor.py").read_text()
+ src = (Path(__file__).resolve().parents[2] / "codeverse" / "doctor.py").read_text() # checks moved out of cli/, 2026-08-28
assert "CV3D_MAX_IN_FLIGHT=" in src
assert "CV3D_MAX_IN_FLIGHT" in Settings._FLAT_ALIASES
diff --git a/harness/tests/install/test_docs.py b/harness/tests/install/test_docs.py
index d38c4180..2d64be3b 100644
--- a/harness/tests/install/test_docs.py
+++ b/harness/tests/install/test_docs.py
@@ -210,7 +210,7 @@ def test_doctor_checks_every_module_of_every_optional_extra(monkeypatch) -> None
missing pip package reported as a GPU/driver problem."""
import importlib
- from codeverse.cli.doctor import _OPTIONAL_DEPS, _PY_DEPS, check_python_deps
+ from codeverse.doctor import _OPTIONAL_DEPS, _PY_DEPS, check_python_deps
with (HARNESS / "pyproject.toml").open("rb") as fh:
extras = tomllib.load(fh)["project"]["optional-dependencies"]
@@ -258,7 +258,7 @@ def test_doctor_checks_every_module_of_every_optional_extra(monkeypatch) -> None
def test_doctor_rows_have_troubleshooting_entries() -> None:
"""Every check `3dcv doctor` can print must appear in the INSTALL troubleshooting table."""
- from codeverse.cli import doctor as doctor_mod
+ from codeverse import doctor as doctor_mod
text = INSTALL.read_text()
names = {"python", "python deps", "blender", "node", "three", "puppeteer", "chrome webgl",