@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/_cli/cmd_doctor.py

@@ -1,1669 +0,0 @@
-"""``agent-config doctor`` — install + manifest health report.
-
-Phase 4 of road-to-multi-package-coexistence (drift detection) and
-Phase 2 of road-to-surface-discipline (diagnostic hub). Read-only
-sibling to ``prune``/``validate``: walks the project manifest and the
-on-disk deploy roots, runs a battery of health checks, and produces:
-
-Drift categories (manifest ↔ filesystem):
-
-* ``missing``   — manifest entry has a ``path`` that is **not** on disk.
-* ``modified``  — manifest entry records a ``sha256`` that does not
-  match the current bytes on disk.
-* ``foreign``   — file present under one of the ``deploy_roots`` that
-  no manifest entry claims (potential neighbour-tool drift).
-* ``tag-drift`` — manifest-claimed ``.md`` file carries a frontmatter
-  ``package:`` value that disagrees with this package's identifier
-  (P5.2). Hand-edited tags or accidental cross-package writes show up
-  here; files without frontmatter are skipped (P5.1 contract).
-
-Health checks (see :data:`CHECK_IDS`):
-scope · stale-orphans · manifest-integrity · lockfile-freshness · bridge-drift ·
-mcp-mode · mcp-beta-readiness · offline-readiness · python-runtime ·
-tier-usage-readiness · council-cli · unsupported-combos ·
-wizard-state.
-Each emits a structured ``{id, status, message, remedy}`` record with
-``status`` ∈ ``ok`` / ``warn`` / ``fail`` / ``skipped`` (rendered
-``✅`` / ``⚠️`` / ``❌`` / ``⏭️``). ``--check <id>`` runs a single check.
-
-Checks are split by scope (:data:`GLOBAL_CHECK_IDS` vs
-:data:`MANIFEST_REQUIRED_CHECK_IDS`) so an ADR-020 global-only consumer
-(bridge marker present, no ``agents/installed-tools.lock``) gets a
-green-capable report instead of a hard bail: the global checks run, the
-manifest-required checks report ``skipped``, and ``bridge-drift`` returns
-a scope-aware "drift not applicable" verdict. See :func:`main` for the
-no-manifest branch and exit-code contract.
-
-Repair affordances: ``--repair wizard-state`` resets a malformed or
-orphaned ``state/wizard-state.json`` under the user-global root (the
-file the unified Setup-Wizard uses for resume continuity). Used as the
-recovery path when ``1.9``'s npm downgrade is not viable
-(road-to-global-only-install § 1.10 / A6).
-
-Exit codes: ``0`` (clean) · ``1`` (drift or any ``fail`` check) · ``2``
-(error such as "manifest missing"). Both human and ``--json`` output
-emit the drift category lists and the structured checks array. Every
-drift entry carries a one-line ``fix`` hint (P4.3).
-"""
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import os
-import re
-import shutil
-import sys
-from pathlib import Path
-from typing import Any
-
-from scripts._lib import installed_lock, installed_tools
-from scripts._lib.agent_settings import (
-    PROJECT_ROOT_ENV,
-    ROOT_OVERRIDE_ENV,
-    ProjectRootError,
-    find_project_root_with_trace,
-    project_settings_path,
-    resolve_project_root,
-)
-
-
-class _Sentinel:
-    """Tiny stand-in for a private sentinel value type."""
-
-    __slots__ = ()
-
-
-#: Returned by :func:`_read_inline_package_tag` when the file is out
-#: of scope for tag-drift detection (no ``.md`` suffix, unreadable, or
-#: no leading frontmatter block).
-NO_FRONTMATTER = _Sentinel()
-
-
-def _resolve_project_root(arg: str | None) -> tuple[Path, str]:
-    """Resolve the doctor's project root via the shared Phase-3 helper.
-
-    Returns ``(root, origin)`` where ``origin`` is one of the anchor
-    names from :mod:`scripts._lib.agent_settings` (``agents-dir``,
-    ``git``, ``agent-settings``) or one of the origin tags
-    ``root-flag`` / ``explicit`` / ``env`` / ``cwd-fallback``. The tag
-    is surfaced in both human and JSON output so subdir invocations
-    are auditable.
-    """
-    return resolve_project_root(arg)
-
-
-#: Path of the install-mode marker file (Step 8 A5). One-line file:
-#: ``minimal\n`` or ``full\n``. Written by ``install.py``; consumed by
-#: ``doctor --context`` to surface install state without re-deriving it
-#: from filesystem heuristics.
-_INSTALL_MODE_MARKER_REL = "agents/.agent-state/install-mode.txt"
-
-
-def _detect_install_mode(project_root: Path) -> tuple[str, str]:
-    """Return ``(mode, source)`` for the project install state.
-
-    Hybrid detection (Step 8 council decision Q5):
-
-    1. ``agents/.agent-state/install-mode.txt`` if present (authoritative
-       for installs since Step 8) → ``source="marker-file"``.
-    2. Filesystem heuristic for back-compat: ``AGENTS.md`` + copilot
-       bridges → ``full``; otherwise ``minimal`` → ``source="heuristic"``.
-
-    Heuristic is fragile by design — users who delete ``AGENTS.md`` but
-    keep copilot bridges get misreported. The marker file is the
-    intended source of truth for installs from Step 8 onward.
-    """
-    marker = project_root / _INSTALL_MODE_MARKER_REL
-    if marker.is_file():
-        try:
-            value = marker.read_text(encoding="utf-8").strip()
-        except OSError:
-            value = ""
-        if value in ("minimal", "full"):
-            return value, "marker-file"
-    has_agents_md = (project_root / "AGENTS.md").exists()
-    has_copilot = (project_root / ".github" / "copilot-instructions.md").exists()
-    if has_agents_md and has_copilot:
-        return "full", "heuristic"
-    return "minimal", "heuristic"
-
-
-def _settings_layer_chain(project_root: Path) -> list[str]:
-    """Return the ordered ``.agent-settings.yml`` layer files that exist.
-
-    Shallowest first (user-global → project root). Used by ``--context``
-    to surface which layers will participate in the cascade merge.
-    """
-    layers: list[str] = []
-    from scripts._lib import user_global_paths
-    user_global = user_global_paths.resolve_with_fallback("agent-settings.yml")
-    if user_global is not None and user_global.is_file():
-        layers.append(str(user_global))
-    project_settings = project_settings_path(project_root)
-    if project_settings.is_file():
-        layers.append(str(project_settings))
-    return layers
-
-
-def _detect_wrapper(project_root: Path) -> dict[str, Any]:
-    """Return ``{path, exists, embedded_root}`` for the project wrapper.
-
-    The ``./agent-config`` wrapper at the project root pins
-    ``AGENT_CONFIG_PROJECT_ROOT`` to its own ``SELF_DIR``, so the
-    "embedded root" is just the wrapper's directory. Surfaced for
-    debugging wrapper-coupling issues (Step 8 A3-coupling).
-    """
-    wrapper = project_root / "agent-config"
-    if not wrapper.exists():
-        return {"path": str(wrapper), "exists": False, "embedded_root": None}
-    return {
-        "path": str(wrapper),
-        "exists": True,
-        "embedded_root": str(project_root),
-    }
-
-
-def _emit_trace_text(
-    root: Path | None,
-    anchor: str | None,
-    trace: list[dict[str, Any]],
-    origin: str,
-) -> None:
-    """Render the discovery trace as human-readable text."""
-    print(f"  📍  start: {Path.cwd()}")
-    print(f"  📍  origin: {origin}")
-    if trace:
-        print("  trace:")
-        for record in trace:
-            hit = record["hit"]
-            symbol = "✅" if hit else "·"
-            tag = f"[{record['pass']}]"
-            anchor_str = f" → {hit}" if hit else ""
-            print(
-                f"    {symbol} {tag} {record['ancestor']}"
-                f"{anchor_str}  ({record['reason']})"
-            )
-    if root is not None:
-        print(f"  📍  resolved root: {root} (anchor: {anchor or 'n/a'})")
-    else:
-        print("  ⚠️   no anchor found in chain")
-
-
-def _emit_trace_json(
-    root: Path | None,
-    anchor: str | None,
-    trace: list[dict[str, Any]],
-    origin: str,
-) -> None:
-    """Render the discovery trace as a JSON payload."""
-    payload: dict[str, Any] = {
-        "start": str(Path.cwd()),
-        "origin": origin,
-        "resolved_root": str(root) if root is not None else None,
-        "anchor": anchor,
-        "trace": trace,
-    }
-    print(json.dumps(payload, indent=2))
-
-
-def _emit_context_text(ctx: dict[str, Any]) -> None:
-    """Render the install / discovery context as human-readable text."""
-    print(f"  📍  project_root: {ctx['project_root']}  (origin: {ctx['origin']})")
-    print(f"  📦  install_mode: {ctx['install_mode']}  (source: {ctx['install_mode_source']})")
-    env_pin = ctx.get("env_pin")
-    if env_pin:
-        marker = " (--root override)" if ctx.get("root_override") else ""
-        print(f"  🔒  env_pin: {env_pin}{marker}")
-    else:
-        print("  🔒  env_pin: (unset)")
-    layers = ctx.get("settings_layers") or []
-    if layers:
-        print(f"  📑  settings layers ({len(layers)}):")
-        for layer in layers:
-            print(f"        - {layer}")
-    else:
-        print("  📑  settings layers: (none)")
-    wrapper = ctx.get("wrapper") or {}
-    if wrapper.get("exists"):
-        print(f"  🧩  wrapper: {wrapper['path']}  (embedded root: {wrapper.get('embedded_root')})")
-    else:
-        print(f"  🧩  wrapper: (not present at {wrapper.get('path')})")
-
-
-def _resolve_path(project_root: Path, raw: str) -> Path:
-    p = Path(raw).expanduser()
-    if not p.is_absolute():
-        p = project_root / p
-    return p
-
-
-def _sha256(path: Path) -> str | None:
-    try:
-        return hashlib.sha256(path.read_bytes()).hexdigest()
-    except OSError:
-        return None
-
-
-#: Inline-tag identifier this package writes into deployed Markdown
-#: frontmatter (P5.1). Kept in sync with ``install.PACKAGE_TAG_ID``;
-#: duplicated here to keep ``cmd_doctor`` import-light (no pull on the
-#: installer module from the CLI).
-PACKAGE_TAG_ID = "event4u/agent-config"
-
-_FRONTMATTER_PACKAGE_RE = re.compile(
-    r"^package:\s*(.+?)\s*$", re.MULTILINE,
-)
-
-
-def _read_inline_package_tag(path: Path) -> str | None | _Sentinel:
-    """Extract the inline ``package:`` value from a Markdown frontmatter.
-
-    Returns ``NO_FRONTMATTER`` when ``path`` is not a Markdown file or
-    has no leading ``---`` block (P5.1: those files are out of scope).
-    Returns ``None`` when frontmatter is present but lacks a
-    ``package:`` key. Returns the string value otherwise.
-    """
-    if path.suffix != ".md":
-        return NO_FRONTMATTER
-    try:
-        text = path.read_text(encoding="utf-8")
-    except OSError:
-        return NO_FRONTMATTER
-    if not (text.startswith("---\n") or text.startswith("---\r\n")):
-        return NO_FRONTMATTER
-    lines = text.splitlines()
-    close_idx: int | None = None
-    for i in range(1, len(lines)):
-        if lines[i].rstrip() == "---":
-            close_idx = i
-            break
-    if close_idx is None:
-        return NO_FRONTMATTER
-    block = "\n".join(lines[1:close_idx])
-    m = _FRONTMATTER_PACKAGE_RE.search(block)
-    if not m:
-        return None
-    return m.group(1).strip().strip("'\"")
-
-
-def _fix_hint(category: str, kind: str | None) -> str:
-    """Return a one-line remediation hint for the surfaced item."""
-    if category == "missing":
-        return "run `./agent-config sync` to re-install"
-    if category == "modified":
-        return "commit the local change, or re-install with --force"
-    if category == "foreign":
-        return (
-            "identify owning tool, or run `./agent-config prune` "
-            "if confirmed orphan"
-        )
-    if category == "tag-drift":
-        return (
-            "re-install with --force to restore the inline tag, "
-            "or remove the file if it is no longer ours"
-        )
-    return ""
-
-
-def _collect_manifest_entries(
-    project_root: Path, manifest: dict[str, Any],
-) -> tuple[
-    list[tuple[str, Path, str, str | None]],   # (tool, abs_path, kind, sha)
-    set[Path],                                  # resolved-known set
-]:
-    """Flatten v2 ``tools[].files[]`` into per-file records.
-
-    Returns the records list and a set of resolved absolute paths so
-    the foreign-file scan can skip anything the manifest claims.
-    """
-    records: list[tuple[str, Path, str, str | None]] = []
-    known: set[Path] = set()
-    for tool in manifest.get("tools") or []:
-        if tool.get("scope") != "project":
-            continue
-        tool_id = str(tool.get("name", ""))
-        for entry in tool.get("files") or []:
-            raw = entry.get("path") or ""
-            if not raw:
-                continue
-            kind = entry.get("kind") or ""
-            target = _resolve_path(project_root, raw)
-            try:
-                resolved = target.resolve()
-            except OSError:
-                resolved = target
-            records.append((tool_id, target, kind, entry.get("sha256")))
-            known.add(resolved)
-    return records, known
-
-
-def _scan_foreign(
-    project_root: Path,
-    manifest: dict[str, Any],
-    known: set[Path],
-) -> list[Path]:
-    """Walk every declared deploy root and surface unclaimed files.
-
-    Only ``regular files`` under ``deploy_roots`` count; directories and
-    symlinks are followed but the bookkeeping is on the resolved final
-    path so a manifest claim via either path silences both surfaces.
-    Falls back to :data:`installed_tools.DEFAULT_DEPLOY_ROOTS` when the
-    manifest lacks an explicit ``deploy_roots`` list.
-    """
-    roots = manifest.get("deploy_roots") or list(
-        installed_tools.DEFAULT_DEPLOY_ROOTS,
-    )
-    foreign: list[Path] = []
-    seen: set[Path] = set()
-    for root_rel in roots:
-        root = _resolve_path(project_root, str(root_rel))
-        if not root.exists() or not root.is_dir():
-            continue
-        for child in root.rglob("*"):
-            if not child.is_file():
-                continue
-            try:
-                resolved = child.resolve()
-            except OSError:
-                resolved = child
-            if resolved in known or resolved in seen:
-                continue
-            seen.add(resolved)
-            foreign.append(child)
-    foreign.sort()
-    return foreign
-
-
-def _classify(
-    records: list[tuple[str, Path, str, str | None]],
-) -> tuple[
-    list[dict[str, Any]],
-    list[dict[str, Any]],
-    list[dict[str, Any]],
-]:
-    """Split manifest records into missing / modified / tag-drift lists.
-
-    Tag-drift inspection (P5.2) is restricted to manifest entries that
-    point at a present ``.md`` file with a frontmatter block. A file
-    that has frontmatter but whose ``package:`` value disagrees with
-    :data:`PACKAGE_TAG_ID` — or that has dropped the key entirely —
-    surfaces here. Files without frontmatter are silently ignored per
-    the P5.1 contract (we never synthesise frontmatter).
-    """
-    missing: list[dict[str, Any]] = []
-    modified: list[dict[str, Any]] = []
-    tag_drift: list[dict[str, Any]] = []
-    for tool_id, target, kind, expected in records:
-        if not target.exists():
-            missing.append({
-                "tool": tool_id, "path": str(target), "kind": kind,
-                "fix": _fix_hint("missing", kind),
-            })
-            continue
-        tag = _read_inline_package_tag(target)
-        if not isinstance(tag, _Sentinel) and tag != PACKAGE_TAG_ID:
-            tag_drift.append({
-                "tool": tool_id, "path": str(target), "kind": kind,
-                "expected": PACKAGE_TAG_ID,
-                "found": "" if tag is None else tag,
-                "fix": _fix_hint("tag-drift", kind),
-            })
-        if expected is None:
-            continue
-        actual = _sha256(target)
-        if actual is None or actual == expected:
-            continue
-        modified.append({
-            "tool": tool_id, "path": str(target), "kind": kind,
-            "fix": _fix_hint("modified", kind),
-        })
-    return missing, modified, tag_drift
-
-
-def _foreign_records(
-    project_root: Path, foreign: list[Path],
-) -> list[dict[str, Any]]:
-    out: list[dict[str, Any]] = []
-    for p in foreign:
-        try:
-            rel = p.relative_to(project_root)
-            path_str = str(rel)
-        except ValueError:
-            path_str = str(p)
-        out.append({
-            "tool": "",
-            "path": path_str,
-            "kind": "deployed",
-            "fix": _fix_hint("foreign", "deployed"),
-        })
-    return out
-
-
-# ---------------------------------------------------------------------------
-# Health checks (Phase 2 of road-to-surface-discipline).
-# ---------------------------------------------------------------------------
-
-#: Ordered registry of structured health-check identifiers. The order
-#: is preserved in text and JSON output. Adding a check requires both
-#: a runner below and an entry in :func:`_run_checks`.
-CHECK_IDS = (
-    "scope",
-    "global-binary",
-    "stale-orphans",
-    "manifest-integrity",
-    "lockfile-freshness",
-    "bridge-drift",
-    "mcp-mode",
-    "mcp-beta-readiness",
-    "offline-readiness",
-    "python-runtime",
-    "tier-usage-readiness",
-    "council-cli",
-    "unsupported-combos",
-    "wizard-state",
-)
-
-#: Checks that need only the project root (or no input at all) and run
-#: regardless of whether a project lockfile exists. Under ADR-020
-#: global-only (bridge marker present, no ``installed-tools.lock``) these
-#: still produce a real verdict. ``scope`` lives here because
-#: :func:`_check_scope` reads only ``project_root`` — the roadmap prose
-#: that grouped it with the manifest checks predates this code reality
-#: (AI council, claude-sonnet-4-5 + gpt-4o, design lens, 2026-06-02).
-GLOBAL_CHECK_IDS: frozenset[str] = frozenset({
-    "scope",
-    "global-binary",
-    "stale-orphans",
-    "mcp-mode",
-    "mcp-beta-readiness",
-    "offline-readiness",
-    "python-runtime",
-    "tier-usage-readiness",
-    "council-cli",
-    "wizard-state",
-})
-
-#: Checks that genuinely cannot run without the project manifest. Without
-#: a lockfile they report ``skipped`` rather than a misleading verdict.
-#: ``bridge-drift`` is deliberately **not** here: it is scope-aware —
-#: a manifest-derived drift roll-up when the lockfile exists, and a
-#: "drift not applicable (global-only consumer)" verdict when it does
-#: not (computed in :func:`_check_bridge_drift_no_manifest`, keeping
-#: :func:`_check_bridge_drift` a pure roll-up per the council's SRP point).
-MANIFEST_REQUIRED_CHECK_IDS: frozenset[str] = frozenset({
-    "manifest-integrity",
-    "lockfile-freshness",
-    "unsupported-combos",
-})
-
-#: Project-root-relative path of the ADR-020 global-only consumer marker.
-BRIDGE_MARKER_RELATIVE = "agents/.event4u-bridge.yml"
-
-#: Repair targets that ``--repair <id>`` accepts. Each id maps to a
-#: function in :func:`_run_repair` that resets the named artefact and
-#: returns an exit code. Additive set: introduce by adding a new id
-#: here, a runner inside :func:`_run_repair`, and (optionally) a
-#: matching health check above.
-REPAIR_IDS = ("wizard-state",)
-
-#: Six gates that govern the MCP `experimental → beta` promotion. The
-#: artefact path under each gate id mirrors `tests/test_mcp_beta_gates.py`
-#: and the contract in `docs/contracts/mcp-beta-criteria.md`.
-MCP_BETA_GATES: tuple[tuple[str, str], ...] = (
-    ("gate-1-external-client", "tests/mcp/external-clients"),
-    ("gate-2-bearer-auth", "tests/mcp/auth"),
-    ("gate-3-parity-smoke", "tests/mcp/parity"),
-    ("gate-4-healthz-load", "tests/mcp/load/healthz.k6.js"),
-    ("gate-5-rate-limit", "docs/contracts/mcp-rate-limit.md"),
-    ("gate-6-no-drift", ".github/workflows/mcp-no-drift.yml"),
-)
-
-#: Visible status → glyph map. ``warn`` keeps a trailing space so the
-#: rendered output stays in a single visual column with the other glyphs.
-STATUS_SYMBOLS = {"ok": "✅", "warn": "⚠️ ", "fail": "❌", "skipped": "⏭️ "}
-
-#: Minimum Python interpreter the CLI targets. Bumped in lockstep with
-#: ``from __future__ import annotations`` + PEP-604 syntax usage.
-MIN_PYTHON = (3, 10)
-
-
-def _check_scope(project_root: Path) -> dict[str, Any]:
-    """Distinguish a standalone project root from a monorepo workspace.
-
-    Surfaces ``warn`` when ``project_root`` looks like a monorepo root
-    so the operator knows to run ``doctor`` per-package; otherwise
-    reports the project as a standalone target.
-    """
-    for marker in ("pnpm-workspace.yaml", "lerna.json"):
-        if (project_root / marker).exists():
-            return {
-                "id": "scope", "status": "warn",
-                "message": f"monorepo root detected ({marker})",
-                "remedy": "run `agent-config doctor` from each workspace package",
-            }
-    pkg = project_root / "package.json"
-    if pkg.exists():
-        try:
-            data = json.loads(pkg.read_text(encoding="utf-8"))
-            if data.get("workspaces"):
-                return {
-                    "id": "scope", "status": "warn",
-                    "message": "package.json declares workspaces (monorepo root)",
-                    "remedy": "run `agent-config doctor` from each workspace package",
-                }
-        except (OSError, ValueError):
-            pass
-    return {
-        "id": "scope", "status": "ok",
-        "message": "standalone project root",
-        "remedy": "",
-    }
-
-
-def _check_manifest_integrity(manifest: dict[str, Any]) -> dict[str, Any]:
-    """Verify the manifest carries a writer version and a known schema."""
-    schema = manifest.get("schema_version")
-    version = manifest.get("agent_config_version")
-    if not version:
-        return {
-            "id": "manifest-integrity", "status": "warn",
-            "message": "manifest lacks `agent_config_version`",
-            "remedy": "re-run `./agent-config init` to record the writer version",
-        }
-    if schema not in installed_tools.SCHEMA_VERSIONS_SUPPORTED:
-        return {
-            "id": "manifest-integrity", "status": "warn",
-            "message": f"unknown schema_version: {schema!r}",
-            "remedy": "upgrade @event4u/agent-config to a writer that "
-                      "recognises this schema",
-        }
-    return {
-        "id": "manifest-integrity", "status": "ok",
-        "message": f"schema v{schema}, written by agent-config {version}",
-        "remedy": "",
-    }
-
-
-def _package_root() -> Path:
-    """Resolve the @event4u/agent-config package root (this repo)."""
-    return Path(__file__).resolve().parents[3]
-
-
-def _current_package_version() -> str | None:
-    """Read ``version`` from this package's ``package.json``; ``None`` on error."""
-    try:
-        data = json.loads(
-            (_package_root() / "package.json").read_text(encoding="utf-8"),
-        )
-        v = data.get("version")
-        if isinstance(v, str) and v.strip():
-            return v.strip()
-    except (OSError, ValueError):
-        pass
-    return None
-
-
-def _check_lockfile_freshness(manifest: dict[str, Any]) -> dict[str, Any]:
-    """Compare the manifest writer version against the current package."""
-    recorded = manifest.get("agent_config_version")
-    current = _current_package_version()
-    if not recorded:
-        return {
-            "id": "lockfile-freshness", "status": "warn",
-            "message": "manifest has no writer version recorded",
-            "remedy": "re-run `./agent-config init` to refresh the manifest",
-        }
-    if current is None:
-        return {
-            "id": "lockfile-freshness", "status": "warn",
-            "message": f"manifest written by {recorded}; current package version unknown",
-            "remedy": "verify the package install (package.json missing or unreadable)",
-        }
-    if recorded != current:
-        return {
-            "id": "lockfile-freshness", "status": "warn",
-            "message": f"manifest writer {recorded} != current package {current}",
-            "remedy": "re-run `./agent-config sync` to refresh the manifest "
-                     "against the current package",
-        }
-    return {
-        "id": "lockfile-freshness", "status": "ok",
-        "message": f"manifest and package both at {current}",
-        "remedy": "",
-    }
-
-
-def _check_global_binary(project_root: Path) -> dict[str, Any]:
-    """`agent-config` PATH resolution + global-install version parity.
-
-    The Claude plugin hook resolves `agent-config` from PATH (ADR-020
-    global-only); if it is missing, every PostToolUse hook fails silently —
-    this is the root cause of the "dashboard never updates" report. Version
-    drift between the binary on PATH and the global install root means the
-    plugin may emit a hook spec the installed binary predates.
-    """
-    binary = shutil.which("agent-config")
-    if not binary:
-        return {
-            "id": "global-binary", "status": "fail",
-            "message": "`agent-config` is not on PATH — Claude plugin hooks "
-                       "cannot resolve it (hooks silently no-op)",
-            "remedy": "npm install -g @event4u/agent-config, then re-run doctor",
-        }
-    lock = installed_lock.read_lockfile()
-    global_v = ""
-    if isinstance(lock, dict):
-        raw = lock.get("agent_config_version")
-        global_v = raw.strip().lstrip("v") if isinstance(raw, str) else ""
-    binary_v = (_current_package_version() or "").lstrip("v")
-    if global_v and binary_v and global_v != binary_v:
-        return {
-            "id": "global-binary", "status": "warn",
-            "message": f"version drift — binary {binary_v}, global install "
-                       f"{global_v}",
-            "remedy": "agent-config upgrade (refresh the global install + plugin)",
-        }
-    bridge = project_root / "agents" / ".event4u-bridge.yml"
-    bridge_note = "" if bridge.is_file() else " · no project bridge marker"
-    return {
-        "id": "global-binary", "status": "ok",
-        "message": f"on PATH ({binary}); version {binary_v or 'unknown'}"
-                   f"{bridge_note}",
-        "remedy": "" if not bridge_note else
-                  "agent-config refresh --project (scaffold the bridge marker)",
-    }
-
-
-def _check_bridge_drift(
-    missing: list[dict[str, Any]],
-    modified: list[dict[str, Any]],
-    foreign: list[dict[str, Any]],
-    tag_drift: list[dict[str, Any]],
-) -> dict[str, Any]:
-    """Roll the four drift category counts into a single health verdict."""
-    total = len(missing) + len(modified) + len(foreign) + len(tag_drift)
-    if total == 0:
-        return {
-            "id": "bridge-drift", "status": "ok",
-            "message": "manifest matches filesystem (no drift)",
-            "remedy": "",
-        }
-    parts = []
-    if missing:
-        parts.append(f"{len(missing)} missing")
-    if modified:
-        parts.append(f"{len(modified)} modified")
-    if foreign:
-        parts.append(f"{len(foreign)} foreign")
-    if tag_drift:
-        parts.append(f"{len(tag_drift)} tag-drift")
-    return {
-        "id": "bridge-drift", "status": "fail",
-        "message": f"{total} drift item(s): {', '.join(parts)}",
-        "remedy": "see the drift section below or run `./agent-config sync`",
-    }
-
-
-def _check_mcp_mode(project_root: Path) -> dict[str, Any]:
-    """Detect which MCP config file the project advertises, if any."""
-    candidates = (
-        (".cursor/mcp.json", "cursor"),
-        (".ai/mcp/mcp.json", "ai-mcp"),
-        ("mcp.json", "root"),
-    )
-    found: list[str] = []
-    for rel, label in candidates:
-        path = project_root / rel
-        if not path.exists():
-            continue
-        try:
-            json.loads(path.read_text(encoding="utf-8"))
-            found.append(f"{label} ({rel})")
-        except (OSError, ValueError):
-            return {
-                "id": "mcp-mode", "status": "warn",
-                "message": f"MCP config at {rel} is not valid JSON",
-                "remedy": f"fix or remove `{rel}` (see docs/architecture.md § MCP)",
-            }
-    if not found:
-        return {
-            "id": "mcp-mode", "status": "ok",
-            "message": "no MCP config present (MCP Beta off)",
-            "remedy": "",
-        }
-    return {
-        "id": "mcp-mode", "status": "ok",
-        "message": f"MCP config detected: {', '.join(found)}",
-        "remedy": "",
-    }
-
-
-def _check_offline_readiness() -> dict[str, Any]:
-    """Verify the verified-offline install entrypoint ships with the package."""
-    script = _package_root() / "src" / "scripts" / "hermetic-install.sh"
-    if not script.exists():
-        return {
-            "id": "offline-readiness", "status": "warn",
-            "message": "src/scripts/hermetic-install.sh not found in package",
-            "remedy": "reinstall @event4u/agent-config or pull missing files",
-        }
-    return {
-        "id": "offline-readiness", "status": "ok",
-        "message": "verified-offline install entrypoint present",
-        "remedy": "",
-    }
-
-
-def _check_stale_orphans() -> dict[str, Any]:
-    """Surface package-tagged files on disk that the global-deploy inventory
-    no longer tracks — leftovers from a pre-inventory installer or a
-    since-removed / renamed artefact (e.g. ``create-pr`` → ``pr/create``).
-
-    Read-only: counts candidates per recorded anchor, never deletes. The
-    remedy is a global redeploy, whose always-run tag sweep
-    (``reap_tagged_orphans``) reconciles them. Scans only the package-owned
-    subtrees the inventory recorded (not the whole anchor), and counts a
-    file only when it carries this package's ``package:`` tag — user-authored
-    files in shared anchors never register.
-    """
-    try:  # package-style import (installed package / pytest)
-        from scripts._lib import global_deploy_inventory as gdi
-    except ImportError:  # pragma: no cover — script-style sys.path fallback
-        from _lib import global_deploy_inventory as gdi  # type: ignore[no-redef]
-
-    tools = gdi.load_inventory().get("tools", {})
-    if not isinstance(tools, dict) or not tools:
-        return {
-            "id": "stale-orphans", "status": "ok",
-            "message": "no global-deploy inventory yet — nothing to reconcile",
-            "remedy": "",
-        }
-    orphan_count = 0
-    sample: list[str] = []
-    for tool_id, entry in sorted(tools.items()):
-        if not isinstance(entry, dict):
-            continue
-        anchor_raw = entry.get("anchor")
-        recorded = entry.get("files")
-        if not isinstance(anchor_raw, str) or not isinstance(recorded, list):
-            continue
-        anchor = Path(anchor_raw).expanduser()
-        if not anchor.is_dir():
-            continue
-        recorded_set = {r for r in recorded if isinstance(r, str)}
-        # Bound the scan to the top-level subtrees the package actually owns.
-        owned_roots = {r.split("/", 1)[0] for r in recorded_set if "/" in r}
-        for root_name in sorted(owned_roots):
-            root = anchor / root_name
-            if not root.is_dir():
-                continue
-            for md in root.rglob("*.md"):
-                if md.is_dir():
-                    continue
-                try:
-                    rel = md.relative_to(anchor).as_posix()
-                except ValueError:
-                    continue
-                if rel in recorded_set:
-                    continue
-                tag = _read_inline_package_tag(md)
-                if isinstance(tag, _Sentinel) or tag != PACKAGE_TAG_ID:
-                    continue
-                orphan_count += 1
-                if len(sample) < 5:
-                    sample.append(f"{tool_id}:{rel}")
-    if orphan_count == 0:
-        return {
-            "id": "stale-orphans", "status": "ok",
-            "message": "no stale package-tagged files under recorded anchors",
-            "remedy": "",
-        }
-    return {
-        "id": "stale-orphans", "status": "warn",
-        "message": (
-            f"{orphan_count} stale package-tagged file(s) not tracked by the "
-            f"deploy inventory (e.g. {', '.join(sample)})"
-        ),
-        "remedy": "run `agent-config global` to reap them "
-                  "(the tag sweep reconciles on every deploy)",
-    }
-
-
-def _check_python_runtime() -> dict[str, Any]:
-    """Confirm the interpreter is at least :data:`MIN_PYTHON`."""
-    cur = sys.version_info[:2]
-    need = MIN_PYTHON
-    if cur < need:
-        return {
-            "id": "python-runtime", "status": "fail",
-            "message": f"python {cur[0]}.{cur[1]} below required {need[0]}.{need[1]}",
-            "remedy": f"install python >= {need[0]}.{need[1]} and re-run",
-        }
-    return {
-        "id": "python-runtime", "status": "ok",
-        "message": f"python {cur[0]}.{cur[1]} meets {need[0]}.{need[1]}+ requirement",
-        "remedy": "",
-    }
-
-
-def _check_mcp_beta_readiness(project_root: Path) -> dict[str, Any]:
-    """Report the MCP `experimental → beta` promotion gate sheet.
-
-    Walks the six gates in :data:`MCP_BETA_GATES` and asks whether the
-    artefact named by each gate (test directory, k6 script, contract
-    doc, or workflow file) is present. Green when all six pass, warn
-    when any are missing — the gate stays red until evidence lands.
-    Mirrors `tests/test_mcp_beta_gates.py` so the doctor verdict and
-    the pytest sheet cannot drift.
-    """
-    pending: list[str] = []
-    for gate_id, rel in MCP_BETA_GATES:
-        if not (project_root / rel).exists():
-            pending.append(f"{gate_id} ({rel})")
-    if not pending:
-        return {
-            "id": "mcp-beta-readiness", "status": "ok",
-            "message": "all 6 MCP beta gates green — promotion authorized",
-            "remedy": "",
-        }
-    return {
-        "id": "mcp-beta-readiness", "status": "warn",
-        "message": (
-            f"{len(pending)}/6 MCP beta gate(s) pending: "
-            f"{', '.join(pending)}"
-        ),
-        "remedy": (
-            "produce the artefacts listed in "
-            "docs/contracts/mcp-beta-criteria.md (one per gate); "
-            "do not flip `experimental` wording until all 6 are green"
-        ),
-    }
-
-
-def _check_tier_usage_readiness(project_root: Path) -> dict[str, Any]:
-    """Report whether tier-usage telemetry can drive empirical retiering.
-
-    Phase 5 of road-to-surface-discipline. Three terminal states:
-
-    * **ok** — telemetry on, log present, at least one record survived
-      the privacy floor.
-    * **warn (disabled)** — telemetry off; no signal collected.
-      Default-off doctrine; user opt-in is the unlock.
-    * **warn (no data)** — telemetry on but the log is absent / empty;
-      retiering decisions still rely on operator judgement until
-      enough records accumulate.
-    * **fail (poisoned)** — every record was rejected by the privacy
-      floor; the report would refuse to render. The log needs a manual
-      inspection.
-
-    Contract: ``docs/contracts/command-clusters.md`` § tier-usage signal.
-    """
-    settings_file = project_settings_path(project_root)
-    log_path = project_root / ".agent-tier-usage.jsonl"
-    enabled = False
-    if settings_file.is_file():
-        try:
-            import yaml  # type: ignore[import-not-found]
-        except ImportError:
-            yaml = None  # type: ignore[assignment]
-        if yaml is not None:
-            try:
-                raw = yaml.safe_load(settings_file.read_text(encoding="utf-8")) or {}
-            except Exception:
-                raw = {}
-            tele = (raw.get("telemetry") if isinstance(raw, dict) else None) or {}
-            tu = tele.get("tier_usage") if isinstance(tele, dict) else None
-            if isinstance(tu, dict):
-                output = tu.get("output") if isinstance(tu.get("output"), dict) else {}
-                if isinstance(output.get("path"), str) and output["path"].strip():
-                    log_path = project_root / output["path"].strip()
-                val = tu.get("enabled")
-                enabled = bool(val) if isinstance(val, bool) else (
-                    isinstance(val, str) and val.strip().lower() in ("true", "yes", "on", "1")
-                )
-
-    if not enabled:
-        return {
-            "id": "tier-usage-readiness", "status": "warn",
-            "message": (
-                "tier-usage telemetry disabled — empirical retiering "
-                "decisions fall back to operator judgement"
-            ),
-            "remedy": (
-                "set `telemetry.tier_usage.enabled: true` in "
-                ".agent-settings.yml (default-off; opt-in)"
-            ),
-        }
-    if not log_path.exists():
-        return {
-            "id": "tier-usage-readiness", "status": "warn",
-            "message": (
-                f"tier-usage telemetry on but {log_path.name} not yet "
-                "written — no signal accumulated"
-            ),
-            "remedy": (
-                "run any tracked command to seed the log; the dispatcher "
-                "writes one record per invocation"
-            ),
-        }
-    total = 0
-    valid = 0
-    allowed_fields = {"ts_bucket", "command", "tier", "outcome", "user_hash"}
-    allowed_outcomes = {"success", "error", "blocked"}
-    try:
-        with log_path.open("r", encoding="utf-8") as fh:
-            for line in fh:
-                line = line.strip()
-                if not line:
-                    continue
-                total += 1
-                try:
-                    obj = json.loads(line)
-                except json.JSONDecodeError:
-                    continue
-                if not isinstance(obj, dict):
-                    continue
-                if not set(obj.keys()).issubset(allowed_fields):
-                    continue
-                if (
-                    isinstance(obj.get("command"), str) and obj["command"]
-                    and isinstance(obj.get("tier"), int) and obj["tier"] in (0, 1, 2, 3)
-                    and obj.get("outcome") in allowed_outcomes
-                    and isinstance(obj.get("user_hash"), str) and len(obj["user_hash"]) == 16
-                    and isinstance(obj.get("ts_bucket"), str)
-                ):
-                    valid += 1
-    except OSError as exc:
-        return {
-            "id": "tier-usage-readiness", "status": "fail",
-            "message": f"cannot read {log_path.name}: {exc}",
-            "remedy": "fix permissions on the tier-usage log",
-        }
-    if total > 0 and valid == 0:
-        return {
-            "id": "tier-usage-readiness", "status": "fail",
-            "message": (
-                f"{total} record(s) in {log_path.name} but 0 passed the "
-                "privacy floor — report would refuse to render"
-            ),
-            "remedy": (
-                "inspect the log; the dispatcher is writing records the "
-                "contract forbids (paths, argv, message bodies)"
-            ),
-        }
-    if valid == 0:
-        return {
-            "id": "tier-usage-readiness", "status": "warn",
-            "message": f"{log_path.name} present but empty — no signal yet",
-            "remedy": "run any tracked command to seed the log",
-        }
-    return {
-        "id": "tier-usage-readiness", "status": "ok",
-        "message": (
-            f"{valid} record(s) past the privacy floor in {log_path.name} "
-            "— retiering signal available"
-        ),
-        "remedy": "",
-    }
-
-
-#: Provider → (default binary, billable flag). Mirrors the
-#: ``CliClient`` subclass attributes in ``scripts/ai_council/clients.py``
-#: without importing them at module load time (keeps doctor lightweight
-#: and robust if council deps fail to load).
-_CLI_PROVIDER_META: dict[str, tuple[str, bool]] = {
-    "anthropic": ("claude", False),
-    "openai": ("codex", False),
-    "gemini": ("gemini", False),
-    "xai": ("grok", True),
-    "perplexity": ("perplexity", True),
-}
-
-
-def _check_council_cli(project_root: Path) -> dict[str, Any]:
-    """Health-probe each enabled ``mode: cli`` council member.
-
-    For every CLI member in ``agents/settings/.ai-council.yml`` reports binary
-    presence (via ``shutil.which``), billable flag, daily-quota state
-    (used/cap or used/—), and rolls up to a single status icon.
-
-    No subprocess is spawned: ``--version`` probes would defeat the
-    cheap-by-default contract and surface flaky network paths (Codex
-    talks home on first run). Binary presence + the cached
-    ``cli-calls.json`` counter cover the actionable failure modes.
-
-    Status rules:
-
-    - ``ok`` — every enabled CLI member has its binary on PATH AND
-      (when capped) usage is below ``warn_at``.
-    - ``warn`` — at least one binary is missing OR usage crosses
-      ``warn_at`` for at least one capped member.
-    - returns ``ok`` with "no council config" if no config is found in any
-      scope — user-global ``~/.event4u/agent-config/settings/.ai-council.yml``, an
-      explicit ``$AI_COUNCIL_CONFIG``, or a project-local
-      ``agents/settings/.ai-council.yml`` — e.g. the council is not set up
-      yet.
-    """
-    try:
-        from scripts.ai_council.clients import load_cli_call_counts
-        from scripts.ai_council.config import (
-            load_council_config, resolve_config_path,
-        )
-    except Exception as exc:  # noqa: BLE001 — defensive: doctor must not crash
-        return {
-            "id": "council-cli", "status": "warn",
-            "message": f"council deps unavailable ({type(exc).__name__})",
-            "remedy": "install PyYAML and ensure scripts/ai_council is importable",
-        }
-    council_path = resolve_config_path(project_root)
-    if not council_path.exists():
-        return {
-            "id": "council-cli", "status": "ok",
-            "message": f"no council config ({council_path} not present)",
-            "remedy": (
-                "create the user-global council config at "
-                f"{council_path} (see docs/contracts/ai-council-config.md)"
-            ),
-        }
-    try:
-        cfg = load_council_config(council_path)
-    except Exception as exc:  # noqa: BLE001
-        return {
-            "id": "council-cli", "status": "warn",
-            "message": f"council config invalid: {exc}",
-            "remedy": f"fix {council_path} and re-run doctor",
-        }
-    cli_members: list[tuple[str, Any]] = [
-        (name, m) for name, m in cfg.members.items()
-        if m.enabled and m.mode == "cli" and name in _CLI_PROVIDER_META
-    ]
-    if not cli_members:
-        return {
-            "id": "council-cli", "status": "ok",
-            "message": "no enabled CLI-mode members",
-            "remedy": "",
-        }
-    counts = load_cli_call_counts()
-    caps = cfg.cli_call_budget.max_calls_per_day
-    warn_at = float(cfg.cli_call_budget.warn_at)
-    missing: list[str] = []
-    over_warn: list[str] = []
-    lines: list[str] = []
-    for name, member in cli_members:
-        default_bin, billable = _CLI_PROVIDER_META[name]
-        binary_name = member.binary or default_bin
-        resolved = shutil.which(binary_name)
-        binary_glyph = "✅" if resolved else "❌"
-        if resolved is None:
-            missing.append(name)
-        used = int(counts.get(name, 0))
-        cap = caps.get(name)
-        if cap is not None:
-            ratio = used / cap if cap > 0 else 0.0
-            quota_glyph = "⚠️" if ratio >= warn_at else "✅"
-            if ratio >= warn_at:
-                over_warn.append(name)
-            quota_str = f"{used}/{cap}"
-        else:
-            quota_glyph = "—"
-            quota_str = f"{used}/—"
-        billable_str = "billable" if billable else "subscription"
-        lines.append(
-            f"{name}: binary {binary_glyph} ({binary_name}) · "
-            f"quota {quota_glyph} {quota_str} · {billable_str}"
-        )
-    detail = " | ".join(lines)
-    if missing:
-        return {
-            "id": "council-cli", "status": "warn",
-            "message": (
-                f"{len(missing)}/{len(cli_members)} CLI member(s) missing binary "
-                f"({', '.join(missing)}) · {detail}"
-            ),
-            "remedy": (
-                "install the missing CLI(s) — see `council:estimate` pre-flight "
-                "for per-provider install hints, or flip "
-                "ai_council.members.<name>.mode to 'api'"
-            ),
-        }
-    if over_warn:
-        return {
-            "id": "council-cli", "status": "warn",
-            "message": (
-                f"{len(over_warn)}/{len(cli_members)} CLI member(s) at/over "
-                f"quota warn_at={warn_at} ({', '.join(over_warn)}) · {detail}"
-            ),
-            "remedy": (
-                "wait for UTC rollover or run "
-                "`python3 scripts/council_cli.py quota --reset` to clear the counter"
-            ),
-        }
-    return {
-        "id": "council-cli", "status": "ok",
-        "message": f"{len(cli_members)} CLI member(s) healthy · {detail}",
-        "remedy": "",
-    }
-
-
-def _check_unsupported_combos(manifest: dict[str, Any]) -> dict[str, Any]:
-    """Flag tools whose ``scope`` violates the global-only or project-only rules."""
-    global_only = {"droid", "qoder"}
-    bad: list[str] = []
-    for tool in manifest.get("tools") or []:
-        name = str(tool.get("name", ""))
-        scope = tool.get("scope")
-        if name in global_only and scope != "global":
-            bad.append(f"{name} (scope={scope}, requires global)")
-    if bad:
-        return {
-            "id": "unsupported-combos", "status": "fail",
-            "message": f"{len(bad)} tool(s) with unsupported scope: {', '.join(bad)}",
-            "remedy": "re-install the listed tools with `--global --force`",
-        }
-    return {
-        "id": "unsupported-combos", "status": "ok",
-        "message": "all installed tools use supported scopes",
-        "remedy": "",
-    }
-
-
-def _wizard_state_path() -> Path:
-    """Return the on-disk location of the unified Setup-Wizard state file.
-
-    Mirrors ``STATE_REL`` in :mod:`src/server/routes/wizard.ts` — the
-    server writes ``<writeRoot>/state/wizard-state.json``. Under the
-    global-only install scope (ADR-020) ``writeRoot`` resolves to
-    :func:`user_global_paths.event4u_root` (typically
-    ``~/.event4u/agent-config/``); the ``EVENT4U_CONFIG_HOME`` override
-    is honoured implicitly so tests stay hermetic.
-    """
-    from scripts._lib.user_global_paths import event4u_root
-    return event4u_root() / "state" / "wizard-state.json"
-
-
-def _check_wizard_state() -> dict[str, Any]:
-    """Health-check the resumable Setup-Wizard state file.
-
-    Returns ``ok`` when the file is absent (no active session) or when
-    its JSON shape matches the contract from
-    :mod:`src/server/routes/wizard.ts` (``step: int``, ``partial: dict``,
-    optional ``totalSteps: int``, ``startedAt: str | null``).
-    Returns ``fail`` when the file exists but is unreadable, not valid
-    JSON, or violates the shape — ``--repair wizard-state`` resets it.
-    """
-    state_pth = _wizard_state_path()
-    if not state_pth.exists():
-        return {
-            "id": "wizard-state", "status": "ok",
-            "message": "no active wizard session",
-            "remedy": "",
-        }
-    try:
-        raw = state_pth.read_text(encoding="utf-8")
-    except OSError as exc:
-        return {
-            "id": "wizard-state", "status": "fail",
-            "message": f"unreadable wizard-state at {state_pth}: {exc}",
-            "remedy": "agent-config doctor --repair wizard-state",
-        }
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError as exc:
-        return {
-            "id": "wizard-state", "status": "fail",
-            "message": f"malformed JSON in wizard-state ({exc.msg} at line {exc.lineno})",
-            "remedy": "agent-config doctor --repair wizard-state",
-        }
-    if not isinstance(data, dict):
-        return {
-            "id": "wizard-state", "status": "fail",
-            "message": f"wizard-state root is {type(data).__name__}, expected object",
-            "remedy": "agent-config doctor --repair wizard-state",
-        }
-    step = data.get("step")
-    partial = data.get("partial", {})
-    if not isinstance(step, int) or step < 0:
-        return {
-            "id": "wizard-state", "status": "fail",
-            "message": f"wizard-state.step is {step!r}, expected non-negative integer",
-            "remedy": "agent-config doctor --repair wizard-state",
-        }
-    if not isinstance(partial, dict):
-        return {
-            "id": "wizard-state", "status": "fail",
-            "message": f"wizard-state.partial is {type(partial).__name__}, expected object",
-            "remedy": "agent-config doctor --repair wizard-state",
-        }
-    total = data.get("totalSteps")
-    if total is not None and (not isinstance(total, int) or total < 1):
-        return {
-            "id": "wizard-state", "status": "fail",
-            "message": f"wizard-state.totalSteps is {total!r}, expected positive integer or omitted",
-            "remedy": "agent-config doctor --repair wizard-state",
-        }
-    suffix = f" of {total}" if isinstance(total, int) else ""
-    return {
-        "id": "wizard-state", "status": "ok",
-        "message": f"resumable wizard session at step {step + 1}{suffix}",
-        "remedy": "",
-    }
-
-
-def _run_checks(
-    project_root: Path,
-    manifest: dict[str, Any],
-    drift: dict[str, list[dict[str, Any]]],
-    only: str | None = None,
-) -> list[dict[str, Any]]:
-    """Run the health-check registry and return ordered structured results.
-
-    ``only`` filters to a single check id; ``None`` runs the full set.
-    """
-    runners: dict[str, Any] = {
-        "scope": lambda: _check_scope(project_root),
-        "global-binary": lambda: _check_global_binary(project_root),
-        "stale-orphans": _check_stale_orphans,
-        "manifest-integrity": lambda: _check_manifest_integrity(manifest),
-        "lockfile-freshness": lambda: _check_lockfile_freshness(manifest),
-        "bridge-drift": lambda: _check_bridge_drift(
-            drift["missing"], drift["modified"],
-            drift["foreign"], drift["tag_drift"],
-        ),
-        "mcp-mode": lambda: _check_mcp_mode(project_root),
-        "mcp-beta-readiness": lambda: _check_mcp_beta_readiness(project_root),
-        "offline-readiness": lambda: _check_offline_readiness(),
-        "python-runtime": lambda: _check_python_runtime(),
-        "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
-        "council-cli": lambda: _check_council_cli(project_root),
-        "unsupported-combos": lambda: _check_unsupported_combos(manifest),
-        "wizard-state": _check_wizard_state,
-    }
-    out: list[dict[str, Any]] = []
-    for cid in CHECK_IDS:
-        if only is not None and cid != only:
-            continue
-        out.append(runners[cid]())
-    return out
-
-
-def _skipped_manifest_check(check_id: str) -> dict[str, Any]:
-    """A ``skipped`` verdict for a manifest-required check with no lockfile.
-
-    Explicit machine-readable record (not omitted, not ``null``) so the
-    ``--json`` ``checks`` array keeps a stable shape for a global-only
-    consumer — a council convergence point (2026-06-02).
-    """
-    return {
-        "id": check_id, "status": "skipped",
-        "message": "requires a project lockfile (agents/installed-tools.lock)",
-        "remedy": "run `agent-config init` to create a project lockfile, "
-                  "then re-run this check",
-    }
-
-
-def _check_bridge_drift_no_manifest(bridge_present: bool) -> dict[str, Any]:
-    """Scope-aware ``bridge-drift`` verdict when no project manifest exists.
-
-    Kept out of :func:`_check_bridge_drift` (which stays a pure
-    manifest-derived roll-up) per the council's single-responsibility
-    point. A global-only consumer has no distributed tools to drift, so
-    a bridge-present repo reports ``ok`` ("not applicable"); a repo with
-    neither lockfile nor bridge marker reports ``skipped``.
-    """
-    if bridge_present:
-        return {
-            "id": "bridge-drift", "status": "ok",
-            "message": "no project lockfile → distributed-tool drift not "
-                       "applicable (global-only consumer)",
-            "remedy": "",
-        }
-    return {
-        "id": "bridge-drift", "status": "skipped",
-        "message": "no project lockfile and no bridge marker → drift check "
-                   "not applicable",
-        "remedy": "run `agent-config init` (project install) or "
-                  "`agent-config refresh --project` (global-only consumer)",
-    }
-
-
-def _run_checks_no_manifest(
-    project_root: Path,
-    bridge_present: bool,
-    only: str | None = None,
-) -> list[dict[str, Any]]:
-    """Run the registry with no project manifest available.
-
-    Mirrors :func:`_run_checks` and preserves :data:`CHECK_IDS` order.
-    Global checks (:data:`GLOBAL_CHECK_IDS`) run unchanged; manifest-required
-    checks (:data:`MANIFEST_REQUIRED_CHECK_IDS`) report ``skipped``;
-    ``bridge-drift`` gets the scope-aware no-manifest verdict.
-    """
-    runners: dict[str, Any] = {
-        "scope": lambda: _check_scope(project_root),
-        "global-binary": lambda: _check_global_binary(project_root),
-        "stale-orphans": _check_stale_orphans,
-        "manifest-integrity": lambda: _skipped_manifest_check("manifest-integrity"),
-        "lockfile-freshness": lambda: _skipped_manifest_check("lockfile-freshness"),
-        "bridge-drift": lambda: _check_bridge_drift_no_manifest(bridge_present),
-        "mcp-mode": lambda: _check_mcp_mode(project_root),
-        "mcp-beta-readiness": lambda: _check_mcp_beta_readiness(project_root),
-        "offline-readiness": lambda: _check_offline_readiness(),
-        "python-runtime": lambda: _check_python_runtime(),
-        "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
-        "council-cli": lambda: _check_council_cli(project_root),
-        "unsupported-combos": lambda: _skipped_manifest_check("unsupported-combos"),
-        "wizard-state": _check_wizard_state,
-    }
-    out: list[dict[str, Any]] = []
-    for cid in CHECK_IDS:
-        if only is not None and cid != only:
-            continue
-        out.append(runners[cid]())
-    return out
-
-
-def _run_no_manifest(
-    opts: argparse.Namespace,
-    project_root: Path,
-    origin: str,
-    bridge_present: bool,
-) -> int:
-    """Handle the no-project-lockfile path without the old hard bail.
-
-    Exit-code contract (council-defined, 2026-06-02):
-
-    * ``0`` — bare report for a recognised global-only consumer
-      (bridge marker present), or a single global ``--check`` that passed.
-    * ``1`` — a runnable health check requested via ``--check`` failed.
-    * ``2`` — a requested ``--check`` cannot run (manifest-required check
-      with no lockfile, or ``bridge-drift`` with neither lockfile nor
-      bridge marker), or a bare report in an **uninitialised** repo
-      (neither lockfile nor bridge marker) — preserves the spirit of the
-      pre-existing "run init" signal while still printing a real report.
-    """
-    checks = _run_checks_no_manifest(project_root, bridge_present, only=opts.check)
-    fail_check = any(c["status"] == "fail" for c in checks)
-    skipped_requested = opts.check is not None and any(
-        c["id"] == opts.check and c["status"] == "skipped" for c in checks
-    )
-
-    if opts.json:
-        _emit_json(project_root, [], [], [], [], checks=checks, origin=origin)
-    elif opts.check is None:
-        print(f"  📍  project_root: {project_root} (origin: {origin})")
-        if bridge_present:
-            print("  ℹ️   global-only consumer: bridge marker present, no "
-                  "project lockfile (expected under ADR-020)")
-            print("      project-manifest checks are skipped — they apply only "
-                  "to project-local distributed tools")
-        else:
-            print("  ⚠️   no project lockfile and no bridge marker at "
-                  f"{project_root}", file=sys.stderr)
-            print("      run `agent-config init` (project install) or "
-                  "`agent-config refresh --project` (global-only consumer)",
-                  file=sys.stderr)
-        _emit_checks_text(checks)
-    else:
-        _emit_checks_text(checks)
-
-    if opts.check is not None:
-        if skipped_requested:
-            return 2
-        return 1 if fail_check else 0
-    return 0 if bridge_present else 2
-
-
-def _emit_json(
-    project_root: Path,
-    missing: list[dict[str, Any]],
-    modified: list[dict[str, Any]],
-    foreign: list[dict[str, Any]],
-    tag_drift: list[dict[str, Any]],
-    checks: list[dict[str, Any]] | None = None,
-    origin: str | None = None,
-) -> None:
-    payload: dict[str, Any] = {
-        "project_root": str(project_root),
-        "missing": missing,
-        "modified": modified,
-        "foreign": foreign,
-        "tag_drift": tag_drift,
-    }
-    if origin is not None:
-        payload["project_root_origin"] = origin
-    if checks is not None:
-        payload["checks"] = checks
-    print(json.dumps(payload, indent=2))
-
-
-def _emit_checks_text(checks: list[dict[str, Any]]) -> None:
-    """Render the health-check block above the drift section."""
-    if not checks:
-        return
-    print("checks:")
-    for c in checks:
-        sym = STATUS_SYMBOLS.get(c["status"], "?")
-        print(f"  {sym} {c['id']}: {c['message']}")
-        if c["status"] != "ok" and c.get("remedy"):
-            print(f"      fix: {c['remedy']}")
-    print("")
-
-
-def _emit_text(
-    project_root: Path,
-    missing: list[dict[str, Any]],
-    modified: list[dict[str, Any]],
-    foreign: list[dict[str, Any]],
-    tag_drift: list[dict[str, Any]],
-) -> None:
-    total = len(missing) + len(modified) + len(foreign) + len(tag_drift)
-    if total == 0:
-        print(f"✅  doctor: manifest matches filesystem under {project_root}")
-        return
-    print(f"⚠️   doctor: {total} drift item(s) under {project_root}")
-    for label, items in (
-        ("missing", missing),
-        ("modified", modified),
-        ("foreign", foreign),
-        ("tag-drift", tag_drift),
-    ):
-        if not items:
-            continue
-        print(f"\n  {label} ({len(items)}):")
-        for it in items:
-            tool = it["tool"] or "?"
-            print(f"    · [{tool}] {it['path']}")
-            if label == "tag-drift":
-                found = it.get("found") or "(missing)"
-                expected = it.get("expected", PACKAGE_TAG_ID)
-                print(f"        expected: {expected}")
-                print(f"        found:    {found}")
-            print(f"        fix: {it['fix']}")
-
-
-def _parse(argv: list[str]) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        prog="agent-config doctor",
-        description=(
-            "Manifest ↔ filesystem drift report plus install health "
-            "checks. See --check for the individual check ids."
-        ),
-    )
-    parser.add_argument("--project", default=None,
-                        help="project root (default: cwd)")
-    parser.add_argument("--json", action="store_true",
-                        help="emit a JSON report instead of human text")
-    parser.add_argument(
-        "--check", default=None, metavar="ID",
-        choices=list(CHECK_IDS),
-        help=("run a single health check by id "
-              f"({' · '.join(CHECK_IDS)})"),
-    )
-    parser.add_argument(
-        "--trace-root", action="store_true",
-        help=("print every ancestor checked during project-root discovery "
-              "plus the winning anchor; short-circuits the drift report"),
-    )
-    parser.add_argument(
-        "--context", action="store_true",
-        help=("print effective project root, anchor, env-pin, settings "
-              "layer chain, wrapper, and install-mode; short-circuits "
-              "the drift report"),
-    )
-    parser.add_argument(
-        "--repair", default=None, metavar="ID",
-        choices=list(REPAIR_IDS),
-        help=("reset a recoverable artefact and exit "
-              f"({' · '.join(REPAIR_IDS)}); short-circuits the drift "
-              "report. Idempotent — absent files report 'nothing to "
-              "repair' and exit 0."),
-    )
-    return parser.parse_args(argv)
-
-
-def _run_trace_root(opts: argparse.Namespace) -> int:
-    """Handle ``--trace-root``: discovery walk + records, no drift report."""
-    start = Path.cwd()
-    root, anchor, trace = find_project_root_with_trace(start)
-    # Determine origin label even when no anchor is found.
-    if os.environ.get(ROOT_OVERRIDE_ENV) == "1" and os.environ.get(PROJECT_ROOT_ENV):
-        origin = "root-flag"
-    elif opts.project:
-        origin = "explicit"
-    elif os.environ.get(PROJECT_ROOT_ENV):
-        origin = "env"
-    elif root is not None:
-        origin = anchor or "unknown"
-    else:
-        origin = "cwd-fallback"
-    if opts.json:
-        _emit_trace_json(root, anchor, trace, origin)
-    else:
-        _emit_trace_text(root, anchor, trace, origin)
-    return 0
-
-
-def _run_context(opts: argparse.Namespace) -> int:
-    """Handle ``--context``: install + discovery snapshot, no drift report."""
-    try:
-        project_root, origin = _resolve_project_root(opts.project)
-    except ProjectRootError as exc:
-        print(f"❌  doctor: {exc}", file=sys.stderr)
-        return 2
-    mode, mode_source = _detect_install_mode(project_root)
-    ctx: dict[str, Any] = {
-        "project_root": str(project_root),
-        "origin": origin,
-        "install_mode": mode,
-        "install_mode_source": mode_source,
-        "env_pin": os.environ.get(PROJECT_ROOT_ENV) or None,
-        "root_override": os.environ.get(ROOT_OVERRIDE_ENV) == "1",
-        "settings_layers": _settings_layer_chain(project_root),
-        "wrapper": _detect_wrapper(project_root),
-    }
-    if opts.json:
-        print(json.dumps(ctx, indent=2))
-    else:
-        _emit_context_text(ctx)
-    return 0
-
-
-def _run_repair(opts: argparse.Namespace) -> int:
-    """Handle ``--repair <id>``: reset the named artefact, no drift report.
-
-    Currently the only target is ``wizard-state`` — unlinks the
-    resumable session file so the next ``agent-config setup`` boots
-    from step 1. Absent files are a no-op (idempotent re-run).
-    """
-    target = opts.repair
-    if target == "wizard-state":
-        state_pth = _wizard_state_path()
-        payload = {
-            "id": "wizard-state",
-            "path": str(state_pth),
-            "action": "remove" if state_pth.exists() else "noop",
-        }
-        if state_pth.exists():
-            try:
-                state_pth.unlink()
-            except OSError as exc:
-                payload["action"] = "error"
-                payload["error"] = str(exc)
-                if opts.json:
-                    print(json.dumps(payload, indent=2))
-                else:
-                    print(f"❌  doctor: could not remove {state_pth}: {exc}",
-                          file=sys.stderr)
-                return 2
-        if opts.json:
-            print(json.dumps(payload, indent=2))
-        else:
-            if payload["action"] == "remove":
-                print(f"✅  doctor: reset wizard-state ({state_pth})")
-            else:
-                print(f"✅  doctor: nothing to repair (no wizard-state at {state_pth})")
-        return 0
-    # argparse `choices=` already constrains target; defensive default.
-    print(f"❌  doctor: unknown repair target {target!r}", file=sys.stderr)
-    return 2
-
-
-def main(argv: list[str] | None = None) -> int:
-    opts = _parse(list(argv) if argv is not None else sys.argv[1:])
-    if opts.repair is not None:
-        return _run_repair(opts)
-    if opts.trace_root:
-        return _run_trace_root(opts)
-    if opts.context:
-        return _run_context(opts)
-    try:
-        project_root, origin = _resolve_project_root(opts.project)
-    except ProjectRootError as exc:
-        print(f"❌  doctor: {exc}", file=sys.stderr)
-        return 2
-    manifest_pth = installed_tools.manifest_path(project_root)
-    manifest = installed_tools.read_manifest(manifest_pth)
-    if manifest is None:
-        # No project lockfile. Under ADR-020 global-only this is a
-        # legitimate state, not an error — run the lockfile-independent
-        # checks and report consumer state instead of a hard bail. The
-        # per-scope split + exit-code contract live in _run_no_manifest.
-        bridge_present = (project_root / BRIDGE_MARKER_RELATIVE).is_file()
-        return _run_no_manifest(opts, project_root, origin, bridge_present)
-
-    records, known = _collect_manifest_entries(project_root, manifest)
-    missing, modified, tag_drift = _classify(records)
-    foreign = _foreign_records(
-        project_root, _scan_foreign(project_root, manifest, known),
-    )
-    drift_groups = {
-        "missing": missing, "modified": modified,
-        "foreign": foreign, "tag_drift": tag_drift,
-    }
-    checks = _run_checks(project_root, manifest, drift_groups, only=opts.check)
-    fail_check = any(c["status"] == "fail" for c in checks)
-
-    if opts.json:
-        _emit_json(
-            project_root, missing, modified, foreign, tag_drift,
-            checks=checks, origin=origin,
-        )
-    else:
-        if opts.check is None:
-            print(f"  📍  project_root: {project_root} (origin: {origin})")
-        _emit_checks_text(checks)
-        if opts.check is None:
-            _emit_text(project_root, missing, modified, foreign, tag_drift)
-
-    # Full-suite mode: exit code reflects drift only; failing health
-    # checks are surfaced visually but do not change the rc, preserving
-    # the original drift-detection contract. ``--check <id>`` mode is
-    # explicit and propagates the single check's verdict.
-    if opts.check is not None:
-        return 1 if fail_check else 0
-    return 1 if (missing or modified or foreign or tag_drift) else 0
-
-
-if __name__ == "__main__":  # pragma: no cover
-    raise SystemExit(main())