py-wlcli 0.8.0__py3-none-any.whl

wl_cli/cc/checks.py

@@ -0,0 +1,1019 @@
+"""Read-only Claude Code host checks for ``wl cc check`` (issue #222).
+
+``wl cc check --json`` answers "is this machine's Claude Code setup in the
+state wlcc expects?" and writes nothing. The envelope is the shared five-state
+one (:mod:`wl_cli.envelope`); the nested ``env`` field is produced by
+:func:`wl_cli.env_status.build_payload` in this same process -- never by
+shelling out to ``wl``.
+
+The six host sections mirror the read-only half of wlcc's
+``skills/wl-env/scripts/check.sh`` plus the statusline step of
+``wl-env-init``. The mapping is deliberate, so the parenthetical § numbers in
+the ticket cannot drift from the implementation:
+
+===========  ============================================================
+section      wlcc source
+===========  ============================================================
+plugins      §1 required plugins + §7 context-mode (optional plugin)
+mcp          §3 plugin root, version stamp and interpreter visibility
+settings     §5 gstack + §6 claude-mem (host-side configuration)
+stamps       §8 stamp registry (report only -- never delete)
+hooks        §9 dangling hook commands (read-only plan)
+statusline   wl-env-init §3 (claude-hud statusLine)
+===========  ============================================================
+
+Failure isolation is part of the contract: every section runs inside its own
+``try`` and a failure becomes ``status: unverifiable`` with a readable
+``reason`` -- it never aborts the report and never hides the other sections.
+The top-level status aggregates ``error > unverifiable > dangling > ok`` (the
+#222 ruling), and a sub-check inside ``settings`` is isolated the same way.
+``wl cc check`` never writes, so ``repaired`` cannot be a section state here.
+
+State roots are deliberately the ones wlcc uses, not one normalised root (the
+#222 ruling keeps the split):
+
+* ``${CLAUDE_CONFIG_DIR:-$HOME/.claude}`` -- plugins, skills, ``settings.json``;
+* ``$HOME/.config/wlcc`` -- wlcc stamps and ``mcp-registered-version``;
+* ``$HOME/.claude-mem`` -- claude-mem settings.
+
+The required plugin list mirrors the ``wl-required-plugins`` key block of
+wlcc's ``references/stamps.md``, which stays the owner there; an installed
+``wl`` cannot read the wlcc plugin tree at runtime, so this module carries the
+consumer-side copy. Keep both in sync when the wlcc list changes.
+
+Read-only means read-only: the module performs no ``mkdir``/``write``/
+``replace``/``unlink`` anywhere, and ``uv python find`` (the one external
+interpreter probe inherited from check.sh §3) only resolves a local path.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..env_status import build_payload
+from ..envelope import OK_STATUSES, dump, exit_code
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+
+#: Stable tool name in the envelope's ``tool`` key.
+TOOL = "cc check"
+
+#: Required plugins -- the consumer-side copy of wlcc
+#: ``references/stamps.md``'s ``wl-required-plugins`` key block (#226 there).
+#: Entries are the full ``name@marketplace`` form, so a name cannot match a
+#: plugin from the wrong marketplace.
+REQUIRED_PLUGINS: tuple[str, ...] = (
+    "superpowers@claude-plugins-official",
+    "astral@astral-sh",
+    "ecc@ecc",
+    "claude-mem@thedotmack",
+    "mattpocock-skills@mattpocock",
+    "claude-hud@claude-hud",
+)
+
+#: §7 is an *optional* dependency: its absence is reported, but it never
+#: gates the ``plugins`` section (check.sh only prompts, it never installs).
+CONTEXT_MODE_PLUGIN = "context-mode@context-mode"
+
+#: gstack pin from check.sh §5; the check only reports it, the clone belongs to
+#: the repair/init half (#223).
+GSTACK_PIN = "ad8400543cd9ce8d07641362db48d44a95417e33"
+
+#: `~/.config/wlcc` stamps registered in wlcc ``references/stamps.md``.
+KNOWN_STAMPS = frozenset(
+    {"init-done", "mcp-registered-version", "context-prompted", "token.enc"}
+)
+
+#: Retired stamps from the same registry: reported, never deleted here.
+RETIRED_STAMPS = frozenset({"gemini-key.enc", "mcp-visionary-pending"})
+
+#: MCP servers check.sh §3 registers.
+MCP_SERVERS: tuple[str, ...] = ("gitlab", "k8s-diagnose")
+
+#: Literal absolute path anchor from wlcc ``hooks-drift.py``: the dangling rule
+#: is exactly ``*/.claude/*``. Kept with the trailing slash on purpose.
+CLAUDE_SEG = "/.claude/"
+
+#: A command token is anything between whitespace, quotes, redirection and
+#: separators -- the same split wlcc's hooks-drift uses for scan and rewrite.
+_TOKEN_RE = re.compile(r"[^\s'\"<>|;&()]+")
+
+#: Command heads whose paths are not argv paths (package resolvers / JS eval).
+_NEVER_TOUCH_HEAD = ("npx", "bunx")
+_EVAL_HEAD = ("node", "nodejs", "bun", "deno")
+
+#: A cache directory name is a version only when it is all numeric segments.
+_VERSION_RE = re.compile(r"^\d+(?:\.\d+)*$")
+
+#: Statuses a section probe may report. ``repaired`` is impossible for a
+#: read-only command and is rejected rather than silently aggregated.
+_SECTION_STATUSES = frozenset({"ok", "dangling", "unverifiable", "error"})
+
+#: Aggregation priority from the #222 ruling.
+_AGGREGATE_PRIORITY = ("error", "unverifiable", "dangling", "repaired", "ok")
+
+#: Interpreter probe inherited from check.sh §3: exit 0 when >= 3.9, 7 when too
+#: old, and always print ``X.Y.Z`` so the state string can name the version.
+_VERSION_PROBE = (
+    "import sys; "
+    "sys.stdout.write('%d.%d.%d' % tuple(sys.version_info[:3])); "
+    "sys.exit(0 if sys.version_info >= (3, 9) else 7)"
+)
+
+
+@dataclass
+class HostContext:
+    """Read-only host state shared by the sections.
+
+    ``settings`` / ``installed`` are ``None`` when the file exists but cannot
+    be read or parsed; a *missing* file yields an empty object because "not
+    configured yet" is a legitimate state, not a probe failure. The error
+    strings keep the reason readable without re-raising.
+    """
+
+    config_root: Path
+    state_root: Path
+    claude_mem_settings: Path
+    settings: dict[str, Any] | None
+    settings_error: str | None
+    installed: dict[str, Any] | None
+    installed_error: str | None
+
+    @property
+    def enabled_plugins(self) -> dict[str, bool]:
+        """The authoritative enable map (``settings.json#enabledPlugins``)."""
+        if self.settings is None:
+            return {}
+        raw = self.settings.get("enabledPlugins")
+        if not isinstance(raw, dict):
+            return {}
+        return {key: value for key, value in raw.items() if isinstance(value, bool)}
+
+
+def config_root() -> Path:
+    """Return ``${CLAUDE_CONFIG_DIR:-$HOME/.claude}`` as an absolute path."""
+    raw = os.environ.get("CLAUDE_CONFIG_DIR") or "~/.claude"
+    return Path(os.path.abspath(os.path.expanduser(raw)))
+
+
+def state_root() -> Path:
+    """Return wlcc's stamp directory (``$HOME/.config/wlcc``)."""
+    return Path(os.path.expanduser("~/.config/wlcc"))
+
+
+def claude_mem_settings_path() -> Path:
+    """Return claude-mem's settings file (``$HOME/.claude-mem/settings.json``).
+
+    wlcc deliberately anchors this at ``$HOME`` rather than the Claude config
+    root; the #222 ruling keeps that split instead of normalising it.
+    """
+    return Path(os.path.expanduser("~/.claude-mem/settings.json"))
+
+
+def load_host_context() -> HostContext:
+    """Read the shared host files once, turning failures into error strings."""
+    root = config_root()
+    settings, settings_error = _read_json_object(root / "settings.json")
+    installed, installed_error = _read_installed_plugins(
+        root / "plugins" / "installed_plugins.json"
+    )
+    return HostContext(
+        config_root=root,
+        state_root=state_root(),
+        claude_mem_settings=claude_mem_settings_path(),
+        settings=settings,
+        settings_error=settings_error,
+        installed=installed,
+        installed_error=installed_error,
+    )
+
+
+def _read_json_object(path: Path) -> tuple[dict[str, Any] | None, str | None]:
+    """Return ``(object, error)``; a missing file reads as an empty object."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return {}, None
+    except OSError as exc:
+        return None, f"cannot read {path}: {exc}"
+    try:
+        data = json.loads(text)
+    except ValueError as exc:
+        return None, f"{path} is not valid JSON: {exc}"
+    if not isinstance(data, dict):
+        return None, f"{path} is not a JSON object"
+    return data, None
+
+
+def _read_installed_plugins(path: Path) -> tuple[dict[str, Any] | None, str | None]:
+    """Return the ``plugins`` map of Claude Code's install registry."""
+    data, error = _read_json_object(path)
+    if data is None:
+        return None, error
+    plugins = data.get("plugins")
+    if plugins is None:
+        return {}, None
+    if not isinstance(plugins, dict):
+        return None, f"{path}: 'plugins' is not an object"
+    return plugins, None
+
+
+def _result(status: str, reason: str | None = None, **fields: Any) -> dict[str, Any]:
+    """Build one section/sub-check result with ``status`` and ``reason`` first."""
+    return {"status": status, "reason": reason, **fields}
+
+
+def _join_reasons(*parts: str | None) -> str | None:
+    """Join the non-empty reasons with ``; ``, or return None."""
+    present = [part for part in parts if part]
+    return "; ".join(present) or None
+
+
+def _aggregate(statuses: list[str]) -> str:
+    """Return the first status in the #222 priority order."""
+    for candidate in _AGGREGATE_PRIORITY:
+        if candidate in statuses:
+            return candidate
+    return "ok"
+
+
+def _run_section(name: str, probe: Callable[[], dict[str, Any]]) -> dict[str, Any]:
+    """Run one probe, converting any failure into an isolated ``unverifiable``."""
+    try:
+        result = probe()
+    except Exception as exc:  # noqa: BLE001 - isolation is the contract
+        return _result("unverifiable", f"{name}: {exc}")
+    status = result.get("status")
+    if status not in _SECTION_STATUSES:
+        return _result(
+            "unverifiable", f"{name}: probe returned an unknown status {status!r}"
+        )
+    return result
+
+
+def _probe_env() -> dict[str, Any]:
+    """The nested ``env`` field: the same-process ``wl env check`` payload."""
+    status, reason, fields = build_payload()
+    return _result(status, reason, **fields)
+
+
+def _version_key(name: str) -> tuple[int, ...]:
+    """Sort key for numeric version directory names."""
+    return tuple(int(part) for part in name.split("."))
+
+
+def _max_version_dir(cache: Path) -> str | None:
+    """Return the highest numeric version directory under *cache*.
+
+    Raises:
+        OSError: If the directory exists but cannot be listed.
+    """
+    if not cache.is_dir():
+        return None
+    versions = [
+        entry.name
+        for entry in cache.iterdir()
+        if entry.is_dir() and _VERSION_RE.match(entry.name)
+    ]
+    if not versions:
+        return None
+    return max(versions, key=_version_key)
+
+
+def _trusted_root(cache: Path, version: str) -> tuple[Path | None, str | None]:
+    """Resolve ``cache/version`` and require it to stay inside the cache.
+
+    Both sides are resolved so a symlinked config root does not read as an
+    escape; a version directory that resolves elsewhere is rejected (the
+    ``rejected`` state of check.sh §3).
+    """
+    root = cache / version
+    try:
+        cache_real = cache.resolve(strict=True)
+        root_real = root.resolve(strict=True)
+    except OSError as exc:
+        return None, f"cannot resolve the plugin root {root}: {exc}"
+    if root_real != cache_real / version:
+        return None, f"plugin root {root} resolves outside the cache: {root_real}"
+    return root, None
+
+
+def _wlcc_cache(host: HostContext) -> Path:
+    """Return the wlcc plugin cache directory in the Claude config root."""
+    return host.config_root / "plugins" / "cache" / "wlcc" / "wlcc"
+
+
+def _locate_wlcc_root(host: HostContext) -> tuple[Path | None, str | None]:
+    """Return the trusted wlcc plugin root, or a readable failure reason."""
+    cache = _wlcc_cache(host)
+    try:
+        version = _max_version_dir(cache)
+    except OSError as exc:
+        return None, f"cannot read the wlcc plugin cache {cache}: {exc}"
+    if version is None:
+        return None, f"wlcc plugin is not installed in {cache}"
+    return _trusted_root(cache, version)
+
+
+def _read_stamp(path: Path) -> tuple[str | None, str | None]:
+    """Read a one-line stamp; a missing file is ``(None, None)``."""
+    try:
+        value = path.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        return None, None
+    except OSError as exc:
+        return None, f"cannot read {path}: {exc}"
+    return (value or None), None
+
+
+def _parse_plugin_list(text: str) -> set[str]:
+    """Extract ``name@marketplace`` entries from ``claude plugin list`` text."""
+    present: set[str] = set()
+    for line in text.splitlines():
+        if "❯" not in line:
+            continue
+        tail = line.split("❯", 1)[1].strip()
+        token = tail.split()[0] if tail else ""
+        if token:
+            present.add(token)
+    return present
+
+
+def _plugin_list_from_cli() -> tuple[set[str] | None, str | None]:
+    """Fallback for an unreadable registry: parse ``claude plugin list``.
+
+    Only presence is read here -- the CLI's output has no machine-readable
+    schema (wlcc's stamps registry says not to pin it), so enable state stays
+    unknown on this path and the ``plugins`` section never guesses.
+    """
+    claude = shutil.which("claude")
+    if not claude:
+        return None, "the claude CLI is not on PATH"
+    try:
+        proc = subprocess.run(
+            [claude, "plugin", "list"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return None, f"claude plugin list could not run: {exc}"
+    if proc.returncode != 0:
+        excerpt = " ".join((proc.stderr or proc.stdout).split())[:200]
+        return None, f"claude plugin list exited {proc.returncode}: {excerpt}"
+    return _parse_plugin_list(proc.stdout), None
+
+
+def _context_mode(host: HostContext, enabled: dict[str, bool] | None) -> dict[str, Any]:
+    """§7: report the optional context-mode plugin and its prompt stamp."""
+    fields: dict[str, Any] = {
+        "enabled": None,
+        "prompted": (host.state_root / "context-prompted").exists(),
+    }
+    if enabled is None:
+        reason = "enabled state is unavailable from the claude plugin list fallback"
+        if host.settings is None:
+            reason = f"cannot read enabled state: {host.settings_error}"
+        return _result("unverifiable", reason, **fields)
+    fields["enabled"] = enabled.get(CONTEXT_MODE_PLUGIN) is True
+    if fields["enabled"]:
+        return _result("ok", None, **fields)
+    return _result("dangling", "context-mode is not enabled", **fields)
+
+
+def probe_plugins(host: HostContext) -> dict[str, Any]:
+    """§1 + §7: required plugin presence and enable state, read-only.
+
+    Presence comes from ``installed_plugins.json`` and enable state from
+    ``settings.json#enabledPlugins`` (the two authoritative sources per the
+    #222 ruling). ``claude plugin list`` is only a fallback when the registry
+    file cannot be read; when neither source works the section is
+    ``unverifiable`` rather than guessing.
+    """
+    fields: dict[str, Any] = {
+        "required": list(REQUIRED_PLUGINS),
+        "source": None,
+        "installed": [],
+        "missing": [],
+        "disabled": [],
+        "enabled_state": "unknown",
+    }
+    if host.installed is None:
+        listed, fallback_error = _plugin_list_from_cli()
+        if listed is None:
+            reason = _join_reasons(
+                f"plugin registry unreadable: {host.installed_error}",
+                f"claude plugin list fallback failed: {fallback_error}",
+            )
+            return _result("unverifiable", reason, **fields)
+        present = listed
+        enabled: dict[str, bool] | None = None
+        fields["source"] = "claude plugin list"
+    else:
+        present = set(host.installed)
+        fields["source"] = "installed_plugins.json"
+        if host.settings is None:
+            fields["installed"] = [
+                entry for entry in REQUIRED_PLUGINS if entry in present
+            ]
+            return _result(
+                "unverifiable",
+                f"cannot read enabled state: {host.settings_error}",
+                **fields,
+            )
+        enabled = host.enabled_plugins
+
+    installed_required = [entry for entry in REQUIRED_PLUGINS if entry in present]
+    missing = [entry for entry in REQUIRED_PLUGINS if entry not in present]
+    disabled: list[str] = []
+    if enabled is not None:
+        disabled = [
+            entry for entry in installed_required if enabled.get(entry) is not True
+        ]
+        fields["enabled_state"] = "known"
+    fields.update(installed=installed_required, missing=missing, disabled=disabled)
+    fields["context_mode"] = _context_mode(host, enabled)
+
+    if missing or disabled:
+        reason = _join_reasons(
+            f"missing: {', '.join(missing)}" if missing else None,
+            f"disabled: {', '.join(disabled)}" if disabled else None,
+        )
+        return _result("dangling", reason, **fields)
+    return _result("ok", None, **fields)
+
+
+def _interpreter_state(path: str, version: str, returncode: int) -> dict[str, Any]:
+    """Classify one interpreter probe result the way check.sh §3 does."""
+    fields: dict[str, Any] = {
+        "state": "fail:unusable",
+        "path": path,
+        "version": version,
+    }
+    if not _VERSION_RE.match(version):
+        fields["state"] = "fail:probe_error"
+        fields["reason"] = f"{path} did not report a version"
+        return fields
+    if returncode == 7:
+        fields["state"] = f"too_old:{version}"
+        return fields
+    if returncode != 0:
+        fields["reason"] = f"{path} exited {returncode}"
+        return fields
+    prefix = "supplied" if os.path.isabs(path) else "ok"
+    fields["state"] = f"{prefix}:{version}"
+    return fields
+
+
+def _probe_python() -> dict[str, Any]:
+    """Resolve the interpreter MCP servers will run under (check.sh §3).
+
+    ``uv --no-cache python find 3.12`` resolves a local installation without
+    downloading and keeps its cache in a temporary directory for the duration
+    of the call -- so the probe leaves the host untouched (``--no-cache`` is
+    required: plain ``uv python find`` creates ``$HOME/.cache/uv``). The
+    interpreter itself decides the 3.9 floor, mirroring check.sh. Every
+    failure is a state value, never an exception.
+    """
+    fields: dict[str, Any] = {"state": "fail:absent", "path": None, "version": None}
+    uv = shutil.which("uv")
+    if uv is None:
+        return fields
+    try:
+        found = subprocess.run(
+            [uv, "--no-cache", "python", "find", "3.12"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        fields.update(state="fail:unusable", reason=str(exc))
+        return fields
+    lines = [line.strip() for line in found.stdout.splitlines() if line.strip()]
+    path = lines[-1] if lines else ""
+    if found.returncode != 0 or not path:
+        fields["reason"] = f"uv python find exited {found.returncode}"
+        return fields
+    try:
+        probe = subprocess.run(
+            [path, "-c", _VERSION_PROBE],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        fields.update(state="fail:unusable", path=path, reason=str(exc))
+        return fields
+    return _interpreter_state(path, probe.stdout.strip(), probe.returncode)
+
+
+def probe_mcp(host: HostContext) -> dict[str, Any]:
+    """§3: plugin-root trust, version stamp and interpreter visibility."""
+    cache = _wlcc_cache(host)
+    fields: dict[str, Any] = {
+        "cache_root": str(cache),
+        "plugin_version": None,
+        "registered_version": None,
+        "plugin_root": None,
+        "rejected": False,
+        "servers": list(MCP_SERVERS),
+        "python": _probe_python(),
+    }
+    try:
+        version = _max_version_dir(cache)
+    except OSError as exc:
+        return _result(
+            "unverifiable",
+            f"cannot read the wlcc plugin cache {cache}: {exc}",
+            **fields,
+        )
+    fields["plugin_version"] = version
+
+    registered, stamp_error = _read_stamp(host.state_root / "mcp-registered-version")
+    fields["registered_version"] = registered
+    if stamp_error:
+        return _result("unverifiable", stamp_error, **fields)
+    if version is None:
+        return _result("dangling", f"wlcc plugin is not installed in {cache}", **fields)
+
+    root, root_error = _trusted_root(cache, version)
+    if root is None:
+        fields["rejected"] = True
+        return _result("unverifiable", root_error, **fields)
+    fields["plugin_root"] = str(root)
+    server = root / ".claude" / "mcp-tools" / "server.py"
+    if server.is_symlink():
+        fields["rejected"] = True
+        return _result(
+            "unverifiable", f"MCP server script is a symlink: {server}", **fields
+        )
+    if not server.is_file():
+        fields["rejected"] = True
+        return _result(
+            "unverifiable", f"MCP server script is missing: {server}", **fields
+        )
+
+    if registered != version:
+        return _result(
+            "dangling",
+            f"MCP stamp is {registered or 'absent'}, plugin cache is {version}; "
+            "wl cc repair will re-register",
+            **fields,
+        )
+    python_state = str(fields["python"].get("state", ""))
+    if not python_state.startswith(("supplied:", "ok:")):
+        return _result(
+            "dangling", f"MCP interpreter is not usable: {python_state}", **fields
+        )
+    return _result("ok", None, **fields)
+
+
+def _probe_gstack(host: HostContext) -> dict[str, Any]:
+    """§5: report whether the pinned gstack skill is provisioned."""
+    path = host.config_root / "skills" / "gstack"
+    setup = path / "setup"
+    executable = setup.is_file() and os.access(setup, os.X_OK)
+    fields = {"path": str(path), "pin": GSTACK_PIN, "setup_executable": executable}
+    if executable:
+        return _result("ok", None, **fields)
+    if path.exists():
+        return _result(
+            "dangling", f"gstack is present but {setup} is not executable", **fields
+        )
+    return _result("dangling", f"gstack skill is not provisioned at {path}", **fields)
+
+
+def _template_model(host: HostContext) -> tuple[str | None, str | None]:
+    """Return ``CLAUDE_MEM_MODEL`` from the wlcc claude-mem template.
+
+    The template lives under the wlcc plugin root; when that root is not
+    trusted the caller must report ``unverifiable`` instead of guessing.
+    """
+    root, root_error = _locate_wlcc_root(host)
+    if root is None:
+        return None, root_error
+    template = root / "skills" / "wl-env" / "templates" / "claude-mem-settings.json"
+    if not template.exists():
+        return None, f"claude-mem template is missing: {template}"
+    data, error = _read_json_object(template)
+    if data is None:
+        return None, error
+    model = data.get("CLAUDE_MEM_MODEL")
+    if not isinstance(model, str) or not model:
+        return None, f"claude-mem template has no CLAUDE_MEM_MODEL: {template}"
+    return model, None
+
+
+def _probe_claude_mem(host: HostContext) -> dict[str, Any]:
+    """§6: compare claude-mem's applied settings with the shipped template."""
+    path = host.claude_mem_settings
+    exists = path.exists()
+    fields: dict[str, Any] = {
+        "path": str(path),
+        "exists": exists,
+        "model": None,
+        "template_model": None,
+    }
+    data, error = _read_json_object(path)
+    if data is None:
+        return _result("unverifiable", error, **fields)
+
+    template_model, template_error = _template_model(host)
+    fields["template_model"] = template_model
+    if not exists:
+        # Nothing to merge yet: the pending provisioning is visible without a
+        # template, and the template error stays in the section when relevant.
+        return _result(
+            "dangling", f"claude-mem settings are not provisioned at {path}", **fields
+        )
+
+    model = data.get("CLAUDE_MEM_MODEL")
+    fields["model"] = model if isinstance(model, str) else None
+    if template_model is None:
+        return _result(
+            "unverifiable",
+            template_error or "claude-mem template model is unavailable",
+            **fields,
+        )
+    if fields["model"] is None:
+        return _result(
+            "dangling", "claude-mem settings do not set CLAUDE_MEM_MODEL", **fields
+        )
+    if fields["model"] != template_model:
+        return _result(
+            "dangling",
+            f"claude-mem model is {fields['model']!r}, template expects "
+            f"{template_model!r}; merge manually",
+            **fields,
+        )
+    return _result("ok", None, **fields)
+
+
+def probe_settings(host: HostContext) -> dict[str, Any]:
+    """§5 + §6: the host-side configuration checks, each isolated."""
+    subchecks = {
+        "gstack": _run_section("gstack", lambda: _probe_gstack(host)),
+        "claude_mem": _run_section("claude_mem", lambda: _probe_claude_mem(host)),
+    }
+    statuses = [subcheck["status"] for subcheck in subchecks.values()]
+    status = _aggregate(statuses)
+    reason = None
+    if status != "ok":
+        reason = _join_reasons(
+            *[
+                f"{name}: {subcheck['reason']}"
+                for name, subcheck in subchecks.items()
+                if subcheck["status"] == status and subcheck.get("reason")
+            ]
+        )
+    return _result(status, reason, **subchecks)
+
+
+def probe_stamps(host: HostContext) -> dict[str, Any]:
+    """§8: report stamp drift; the check never deletes anything."""
+    root = host.state_root
+    fields: dict[str, Any] = {
+        "path": str(root),
+        "known": sorted(KNOWN_STAMPS),
+        "pruned": [],
+        "retired": [],
+        "orphans": [],
+        "retired_skill": False,
+    }
+    try:
+        entries = sorted(entry.name for entry in root.iterdir())
+    except FileNotFoundError:
+        entries = []
+    except OSError as exc:
+        return _result("unverifiable", f"cannot read {root}: {exc}", **fields)
+
+    fields["retired"] = [name for name in entries if name in RETIRED_STAMPS]
+    fields["orphans"] = [
+        name
+        for name in entries
+        if name not in KNOWN_STAMPS and name not in RETIRED_STAMPS
+    ]
+    retired_skill = host.config_root / "skills" / "visionary-cli"
+    fields["retired_skill"] = (retired_skill / ".wlcc-version").exists()
+
+    if not (fields["retired"] or fields["orphans"] or fields["retired_skill"]):
+        return _result("ok", None, **fields)
+    reason = _join_reasons(
+        (
+            "retired stamps present: " + ", ".join(fields["retired"])
+            if fields["retired"]
+            else None
+        ),
+        (
+            "unregistered entries (reported only): " + ", ".join(fields["orphans"])
+            if fields["orphans"]
+            else None
+        ),
+        (
+            "retired visionary-cli skill copy present"
+            if fields["retired_skill"]
+            else None
+        ),
+    )
+    return _result("dangling", reason, **fields)
+
+
+def _is_never_touch(command: str) -> bool:
+    """Return True for commands whose path-like tokens are not argv paths."""
+    tokens = command.split()
+    if not tokens:
+        return False
+    head = os.path.basename(tokens[0])
+    if head in _NEVER_TOUCH_HEAD:
+        return True
+    if head in _EVAL_HEAD:
+        return any(token.startswith("-") for token in tokens[1:])
+    return False
+
+
+def _scan_tokens(command: str) -> list[tuple[str, str, str]]:
+    """Classify path-like tokens as healthy / dangling / skip (hooks-drift §9)."""
+    found: list[tuple[str, str, str]] = []
+    seen: set[str] = set()
+    for token in _TOKEN_RE.findall(command):
+        if ".claude" not in token and not token.startswith("/"):
+            continue
+        if token in seen:
+            continue
+        seen.add(token)
+        if "$" in token:
+            found.append(("skip", token, "contains a variable; runtime-only"))
+        elif token.startswith("~"):
+            found.append(("skip", token, "~ form is not a literal absolute path"))
+        elif not token.startswith("/"):
+            continue
+        elif CLAUDE_SEG not in token:
+            if not os.path.exists(token):
+                found.append(
+                    ("skip", token, "dangling absolute path outside */.claude/*")
+                )
+        elif not os.path.exists(token):
+            found.append(("dangling", token, ""))
+        else:
+            found.append(("healthy", token, ""))
+    return found
+
+
+def _entry(
+    action: str,
+    source: str,
+    target: str | None,
+    reason: str,
+    event: str,
+    matcher: str | None,
+) -> dict[str, Any]:
+    """Build one hook plan entry, the same shape hooks-drift reports."""
+    return {
+        "action": action,
+        "from": source,
+        "to": target,
+        "reason": reason,
+        "event": event,
+        "matcher": matcher,
+    }
+
+
+def _rewrite_path(path: str, root: str) -> str | None:
+    """Replace a ``*/.claude`` prefix with the local config root."""
+    index = path.find(CLAUDE_SEG)
+    if index < 0:
+        return None
+    return root + path[index + len("/.claude") :]
+
+
+def _plan_hook_command(
+    command: str, root: str, event: str, matcher: str | None
+) -> tuple[str, list[dict[str, Any]]]:
+    """Read-only port of hooks-drift's rewrite-preferred-over-prune planner."""
+    if _is_never_touch(command):
+        return "keep", []
+    scanned = _scan_tokens(command)
+    dangling = [token for kind, token, _ in scanned if kind == "dangling"]
+    if not dangling:
+        return "keep", [
+            _entry("skip", token, None, reason, event, matcher)
+            for kind, token, reason in scanned
+            if kind == "skip"
+        ]
+
+    targets = {token: _rewrite_path(token, root) for token in dangling}
+    saveable = [
+        token
+        for token in dangling
+        if targets[token] is not None and os.path.exists(targets[token] or "")
+    ]
+    action = "rewrite" if saveable else "prune"
+    entries: list[dict[str, Any]] = []
+    for kind, token, reason in scanned:
+        if kind == "skip":
+            entries.append(_entry("skip", token, None, reason, event, matcher))
+        elif kind == "healthy":
+            continue
+        elif action == "prune":
+            entries.append(
+                _entry(
+                    "prune",
+                    token,
+                    None,
+                    "no local counterpart; repair would prune it",
+                    event,
+                    matcher,
+                )
+            )
+        else:
+            target = targets[token]
+            if target is not None and os.path.exists(target):
+                entries.append(
+                    _entry(
+                        "rewrite",
+                        token,
+                        target,
+                        "prefix maps to an existing local path",
+                        event,
+                        matcher,
+                    )
+                )
+            else:
+                entries.append(
+                    _entry(
+                        "skip",
+                        token,
+                        None,
+                        "no local counterpart; kept because another path is repairable",
+                        event,
+                        matcher,
+                    )
+                )
+    return action, entries
+
+
+def _iter_hook_commands(hooks: dict[str, Any]) -> Iterator[tuple[str, str | None, str]]:
+    """Yield ``(event, matcher, command)`` for every well-shaped hook."""
+    for event, groups in hooks.items():
+        if not isinstance(groups, list):
+            continue
+        for group in groups:
+            if not isinstance(group, dict):
+                continue
+            hook_list = group.get("hooks")
+            if not isinstance(hook_list, list):
+                continue
+            matcher = group.get("matcher")
+            matcher_value = matcher if isinstance(matcher, str) else None
+            for hook in hook_list:
+                command = hook.get("command") if isinstance(hook, dict) else None
+                if isinstance(command, str):
+                    yield str(event), matcher_value, command
+
+
+def probe_hooks(host: HostContext) -> dict[str, Any]:
+    """§9: plan dangling hook repairs without writing (read-only)."""
+    settings_path = host.config_root / "settings.json"
+    fields: dict[str, Any] = {
+        "settings": str(settings_path),
+        "total": 0,
+        "rewrite": 0,
+        "prune": 0,
+        "skip": 0,
+        "entries": [],
+    }
+    if host.settings is None:
+        return _result(
+            "unverifiable",
+            f"cannot read {settings_path}: {host.settings_error}",
+            **fields,
+        )
+    hooks = host.settings.get("hooks")
+    if not isinstance(hooks, dict):
+        return _result("ok", None, **fields)
+
+    entries: list[dict[str, Any]] = []
+    for event, matcher, command in _iter_hook_commands(hooks):
+        _, planned = _plan_hook_command(command, str(host.config_root), event, matcher)
+        entries.extend(planned)
+    counts = {"rewrite": 0, "prune": 0, "skip": 0}
+    for entry in entries:
+        counts[entry["action"]] += 1
+    fields.update(total=len(entries), entries=entries, **counts)
+    if not entries:
+        return _result("ok", None, **fields)
+    return _result(
+        "dangling", f"{len(entries)} hook command entries need attention", **fields
+    )
+
+
+def probe_statusline(host: HostContext) -> dict[str, Any]:
+    """wl-env-init §3: classify the configured statusline without writing."""
+    settings_path = host.config_root / "settings.json"
+    fields: dict[str, Any] = {
+        "settings": str(settings_path),
+        "action": "unverifiable",
+        "command": None,
+        "command_family": None,
+    }
+    if host.settings is None:
+        return _result(
+            "unverifiable",
+            f"cannot read {settings_path}: {host.settings_error}",
+            **fields,
+        )
+    status_line = host.settings.get("statusLine")
+    command = status_line.get("command") if isinstance(status_line, dict) else None
+    if not isinstance(command, str) or not command.strip():
+        fields["action"] = "missing"
+        return _result("dangling", "statusLine is not configured", **fields)
+    fields["command"] = command
+    if "claude-hud" not in command:
+        fields.update(action="conflict", command_family="other")
+        return _result(
+            "dangling",
+            "another statusline is configured; wl cc repair will not overwrite it",
+            **fields,
+        )
+
+    fields["command_family"] = "claude-hud"
+    cache = host.config_root / "plugins" / "cache" / "claude-hud" / "claude-hud"
+    try:
+        version = _max_version_dir(cache)
+    except OSError as exc:
+        return _result(
+            "unverifiable",
+            f"cannot read the claude-hud plugin cache {cache}: {exc}",
+            **fields,
+        )
+    if version is None:
+        fields["action"] = "missing_plugin"
+        return _result(
+            "dangling",
+            f"claude-hud statusLine is configured but {cache} has no version",
+            **fields,
+        )
+    root, root_error = _trusted_root(cache, version)
+    if root is None:
+        return _result("unverifiable", root_error, **fields)
+    fields.update(action="ok", plugin_version=version, plugin_root=str(root))
+    return _result("ok", None, **fields)
+
+
+def _reason_for(sections: dict[str, dict[str, Any]], status: str) -> str | None:
+    """Return the top-level reason: the failed sections' reasons, joined.
+
+    Section reasons raised by :func:`_run_section` already start with the
+    section name, so the prefix is only added when it is not there -- the
+    top-level reason never reads ``plugins: plugins: ...``.
+    """
+    if status not in ("error", "unverifiable"):
+        return None
+    parts: list[str] = []
+    for name, section in sections.items():
+        if section["status"] not in ("error", "unverifiable"):
+            continue
+        reason = section["reason"] or "failed"
+        parts.append(reason if reason.startswith(f"{name}:") else f"{name}: {reason}")
+    return _join_reasons(*parts)
+
+
+def build_report() -> tuple[str, str | None, dict[str, Any]]:
+    """Build the whole ``wl cc check`` report.
+
+    Returns:
+        ``(status, reason, fields)``. ``fields`` holds ``env`` plus the six
+        host sections, each carrying its own five-state ``status``/``reason``.
+        A section probe that raises is reported as ``unverifiable`` with the
+        exception text -- it never escapes this function.
+    """
+    host = load_host_context()
+    sections: dict[str, dict[str, Any]] = {
+        "env": _run_section("env", _probe_env),
+        "plugins": _run_section("plugins", lambda: probe_plugins(host)),
+        "mcp": _run_section("mcp", lambda: probe_mcp(host)),
+        "settings": _run_section("settings", lambda: probe_settings(host)),
+        "stamps": _run_section("stamps", lambda: probe_stamps(host)),
+        "hooks": _run_section("hooks", lambda: probe_hooks(host)),
+        "statusline": _run_section("statusline", lambda: probe_statusline(host)),
+    }
+    status = _aggregate([section["status"] for section in sections.values()])
+    return status, _reason_for(sections, status), sections
+
+
+def emit_check() -> int:
+    """Write the ``cc check`` envelope to stdout and return its exit code."""
+    status, reason, fields = build_report()
+    dump(status, status in OK_STATUSES, tool=TOOL, reason=reason, **fields)
+    return exit_code(status)