agent-toggle 0.1.0__py3-none-any.whl

agent_toggle/cost.py

@@ -0,0 +1,299 @@
+"""Startup token estimates for every togglable item (read-only, stdlib only).
+
+Formula (documented +-25 %; `cost --json` carries it as `formula`):
+
+    tokens = ceil(chars / 4)                      -- the tokenizer-free rule of thumb
+
+    skill    chars of frontmatter `name` + `description` (body loads on invocation)
+    agent    chars of frontmatter `name` + `description` + `tools`
+    command  chars of the name + frontmatter `description` + `argument-hint`
+    rule     chars of the WHOLE file (rules are injected in full)
+    mcp      tools x per-tool weight; the tool count comes from the server entry's
+             tool list / `[mcp_servers.X.tools.*]` tables when present, else a flat
+             default. Harnesses that defer schemas (claude) load tool NAMES only:
+             10 tok per tool, flat 20 tok per server when the count is unknown.
+             Others: 300 tok per tool, flat 5 tools (1500 tok) when unknown.
+    plugin   sum of its bundled skills/agents/commands/.mcp.json under `installPath`
+
+A missing `name` falls back to the file/dir name. Frontmatter is read once, only the
+head of the file up to the closing `---` (HEAD_CAP bytes at most); there is no cache.
+Only the static, always-loaded text is estimated -- measured numbers come from the
+harness. A parked item costs 0 now and reports `would_save`, the tokens it would load
+if restored.
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from . import fs
+from .backends.mcp_json import ProjectMcpError, read_project_mcp
+from .backends.plugin_cli import claude_bin, run_cli
+from .mechanisms import _valid_name, dir_view, live_mcp, live_names, resolve_item
+
+CHARS_PER_TOKEN = 4
+HEAD_CAP = 16 * 1024          # bytes read per frontmatter block
+RULE_CAP = 1024 * 1024        # bytes read per whole-file rule
+MCP_TOKENS_PER_TOOL = {"full": 300, "deferred": 10}
+MCP_FLAT = {"full": 5 * 300, "deferred": 20}      # per server, tool count unknown
+DEFERS_SCHEMAS = frozenset({"claude"})            # loads MCP schemas on demand
+FIELDS = {"skill": ("name", "description"),
+          "agent": ("name", "description", "tools"),
+          "command": ("description", "argument-hint")}
+
+FORMULA = {
+    "tokens": "ceil(chars / 4)", "accuracy": "+-25%", "chars_per_token": CHARS_PER_TOKEN,
+    "counted": {**{t: "+".join(f) for t, f in FIELDS.items()}, "rule": "whole file",
+                "plugin": "sum of bundled skills, agents, commands, mcp servers"},
+    "mcp_tokens_per_tool": MCP_TOKENS_PER_TOOL, "mcp_flat_per_server": MCP_FLAT,
+    "mcp_deferring_harnesses": sorted(DEFERS_SCHEMAS),
+}
+TOOL_SECTION = re.compile(r"^\[mcp_servers\.([^.\]\s]+)\.tools\.[^\]]+\]", re.M)
+
+Estimate = tuple[int, "int | None", str]          # tokens, chars, basis
+
+
+@dataclass
+class Item:
+    harness: str                  # the owning harness for a shared dir
+    type: str
+    name: str
+    enabled: bool
+    tokens: int                   # cost now: 0 when parked
+    would_save: int               # parked: what restoring it would load
+    chars: int | None
+    basis: str
+    shared_with: tuple[str, ...] = ()
+
+
+def tokens_of(chars: int) -> int:
+    return -(-chars // CHARS_PER_TOKEN)
+
+
+def read_head(path: Path, cap: int) -> str:
+    with open(path, "rb") as f:
+        return f.read(cap).decode("utf-8", "replace")
+
+
+def parse_frontmatter(head: str) -> dict[str, str]:
+    """Top-level `key: value` pairs of a leading `---` block; indented lines continue
+    the previous key (folded / literal scalars). Not a YAML parser."""
+    lines = head.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    out: dict[str, str] = {}
+    key = None
+    for ln in lines[1:]:
+        if ln.strip() == "---":
+            break
+        if ln[:1] in (" ", "\t") and key:
+            out[key] = f"{out[key]} {ln.strip()}".strip()
+        elif ":" in ln and not ln.lstrip().startswith("#"):
+            k, _, v = ln.partition(":")
+            key, v = k.strip(), v.strip()
+            out[key] = "" if v in (">", "|", ">-", "|-") else v.strip("\"'")
+    return out
+
+
+def file_estimate(type_: str, name: str, path: Path | None) -> Estimate:
+    """skill / agent / command / rule from one file (a skill dir -> its SKILL.md)."""
+    if path is None:
+        return 0, None, "file not found"
+    if type_ == "skill" and path.is_dir():
+        path = path / "SKILL.md"
+    try:
+        if type_ == "rule":
+            chars = len(read_head(path, RULE_CAP))
+            return tokens_of(chars), chars, f"whole file {chars} chars"
+        fm = parse_frontmatter(read_head(path, HEAD_CAP))
+    except OSError as e:
+        return 0, None, f"unreadable: {e.strerror or e}"
+    vals = {f: fm.get(f, "") for f in FIELDS[type_]}
+    if not vals.get("name"):
+        vals["name"] = name
+    chars = sum(map(len, vals.values()))
+    parts = "+".join(f for f, v in vals.items() if v)
+    return tokens_of(chars), chars, f"{parts} {chars} chars" + ("" if fm else " (no frontmatter)")
+
+
+def mcp_estimate(harness: str, tools: int | None) -> Estimate:
+    mode = "deferred" if harness in DEFERS_SCHEMAS else "full"
+    note = " (names only, deferred)" if mode == "deferred" else ""
+    if not tools:
+        return MCP_FLAT[mode], None, f"tool count unknown: {MCP_FLAT[mode]} tok flat{note}"
+    per = MCP_TOKENS_PER_TOOL[mode]
+    return tools * per, None, f"{tools} tools x {per}{note}"
+
+
+def _entry_tools(entry) -> int | None:
+    tools = entry.get("tools") if isinstance(entry, dict) else None
+    if tools == ["*"]:                  # "all tools": a wildcard, not a count (flat estimate)
+        return None
+    return len(tools) if isinstance(tools, (list, dict)) and tools else None
+
+
+def mcp_tool_counts(h) -> dict[str, int]:
+    """name -> tool count for the live servers whose config lists their tools."""
+    if h.backend == "toml":
+        try:
+            return dict(Counter(TOOL_SECTION.findall((h.home / "config.toml").read_text(encoding="utf-8"))))
+        except OSError:
+            return {}
+    if h.backend == "claude-json":
+        try:
+            cfg = json.loads(fs.claude_json().read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        servers = dict(cfg.get("mcpServers") or {})
+        for pdata in (cfg.get("projects") or {}).values():
+            if isinstance(pdata, dict):
+                for n, e in (pdata.get("mcpServers") or {}).items():
+                    servers.setdefault(n, e)
+        return {n: c for n, e in servers.items() if (c := _entry_tools(e))}
+    if h.backend == "json":
+        try:
+            servers = read_project_mcp(h.mcp.file)[1]["mcpServers"]
+        except ProjectMcpError:
+            return {}
+        return {n: c for n, e in servers.items() if (c := _entry_tools(e))}
+    return {}
+
+
+def flag_names(h, type_: str) -> list[str]:
+    """Names of the live items a flag-mechanism type keeps in the harness config: the
+    object keys under the pointer's `<name>` slot whose own flag is `true`. An entry with
+    no flag (disable would refuse: a key is never invented) or `false` by hand (enable
+    would refuse: no state entry) is not something this tool can toggle, so not listed."""
+    rel, pointer = h.flags[type_]
+    prefix = pointer[:pointer.index("<name>")] if "<name>" in pointer else pointer[:-1]
+    try:
+        node = json.loads((h.home / rel).read_text(encoding="utf-8").removeprefix("\ufeff"))
+    except (OSError, ValueError):
+        return []
+    for k in prefix:
+        node = node.get(k) if isinstance(node, dict) else None
+    if not isinstance(node, dict):
+        return []
+    return sorted(n for n, v in node.items()
+                  if isinstance(v, dict) and v.get("enabled") is True and _valid_name(n))
+
+
+def backup_tools(entry: dict) -> int | None:
+    """Tool count of a parked MCP server, from its verbatim backup."""
+    try:
+        raw = json.loads(Path(entry["backup"]).read_text(encoding="utf-8"))
+    except (KeyError, OSError, ValueError, TypeError):
+        return None
+    if isinstance(raw, dict) and isinstance(raw.get("json"), dict):   # json-backend payload
+        return _entry_tools(raw["json"].get("entry"))
+    if isinstance(raw, dict) and "toml" in raw:
+        return len(TOOL_SECTION.findall(str(raw["toml"]))) or None
+    return _entry_tools(raw)
+
+
+def plugin_estimate(root: Path) -> Estimate:
+    """A plugin bundle: sum of what it ships, read from its install path."""
+    parts = [("skill", d.name, d / "SKILL.md") for d in sorted((root / "skills").glob("*"))
+             if (d / "SKILL.md").is_file()]
+    parts += [("agent", p.stem, p) for p in sorted((root / "agents").rglob("*.md"))]
+    parts += [("command", p.stem, p) for p in sorted((root / "commands").rglob("*.md"))]
+    ests = [file_estimate(*p) for p in parts]
+    servers = 0
+    try:
+        data = json.loads((root / ".mcp.json").read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            servers = len(data.get("mcpServers", data))
+    except (OSError, ValueError):
+        pass
+    tokens = sum(e[0] for e in ests) + servers * mcp_estimate("claude", None)[0]
+    chars = sum(e[1] or 0 for e in ests)
+    counts = Counter(p[0] for p in parts)
+    basis = ", ".join(f"{counts[t]} {t}s" for t in ("skill", "agent", "command") if counts[t])
+    basis += f"{', ' if basis else ''}{servers} mcp" if servers else ""
+    return tokens, chars, basis or "empty bundle"
+
+
+def list_plugins(warn: Callable[[str], None]) -> list[dict]:
+    """`claude plugin list --json` through the injectable runner; [] when unavailable."""
+    exe = claude_bin()
+    if not exe:
+        return []
+    ok, text = run_cli(exe, ["plugin", "list", "--json"])
+    try:       # run_cli merges stderr into the text: skip any notice before the array
+        data = json.JSONDecoder().raw_decode(text, max(text.find("["), 0))[0] if ok else None
+    except ValueError:
+        data = None
+    if not isinstance(data, list):
+        warn("could not read `claude plugin list --json`; plugin rows come from state only")
+        return []
+    return [p for p in data if isinstance(p, dict) and isinstance(p.get("id"), str)]
+
+
+def inventory(state: dict, table: dict, warn: Callable[[str], None] = lambda m: None,
+              plugins: bool = True) -> list[Item]:
+    """Every togglable item once: live, then parked-only. A dir shared by several
+    harnesses is ONE item under its owner with the others in `shared_with`."""
+    items: list[Item] = []
+    seen: set[tuple[str, str, str]] = set()
+    # flag-disabled items stay in place (the config flag is off), so a live listing alone
+    # would call them enabled: the state entry is what says they are off.
+    flagged = {(e.get("harness"), e.get("type"), e.get("name"))
+               for e in state.get("disabled", {}).values()
+               if isinstance(e, dict) and e.get("mechanism") == "flag"}
+
+    def add(h: str, t: str, n: str, enabled: bool, est: Estimate, shared=()) -> None:
+        enabled = enabled and (h, t, n) not in flagged
+        if (h, t, n) not in seen:
+            seen.add((h, t, n))
+            items.append(Item(h, t, n, enabled, est[0] if enabled else 0,
+                              0 if enabled else est[0], est[1], est[2], tuple(shared)))
+
+    for hname, h in table.items():
+        if not h.home.is_dir():
+            continue
+        for type_ in h.types:
+            if type_ in h.dirs:
+                for sub in h.dirs[type_]:
+                    v = dir_view(table, hname, type_, h.home, sub)
+                    if v.owner != hname:
+                        continue
+                    shared = [s for s in v.sharers if s != hname]
+                    for name in live_names(v.live, type_):
+                        add(hname, type_, name, True,
+                            file_estimate(type_, name, resolve_item(v.live, name)), shared)
+            elif type_ in h.flags:
+                for name in flag_names(h, type_):
+                    add(hname, type_, name, True, mcp_estimate(hname, None) if type_ == "mcp"
+                        else (0, None, "flag entry; size unknown"))
+            elif type_ == "mcp":
+                counts = mcp_tool_counts(h)
+                for name in live_mcp(h.home, h.backend):
+                    add(hname, type_, name, True, mcp_estimate(hname, counts.get(name)))
+
+    claude = table.get("claude")
+    if plugins and claude and claude.home.is_dir() and "plugin" in claude.types:
+        for p in list_plugins(warn):
+            root = p.get("installPath")
+            add("claude", "plugin", p["id"], p.get("enabled", True) is not False,
+                plugin_estimate(Path(root)) if isinstance(root, str)
+                else (0, None, "no installPath"))
+
+    for e in state.get("disabled", {}).values():
+        h, t, n = e.get("harness", "claude"), e.get("type"), e.get("name")
+        if not all(isinstance(x, str) and x for x in (h, t, n)):
+            continue                      # hand-edited entry: doctor reports it
+        if t == "mcp":
+            est = mcp_estimate(h, backup_tools(e))
+        elif t == "plugin":
+            est = (0, None, "not in plugin list")
+        else:
+            parked = e.get("parked_at")
+            est = file_estimate(t, n, Path(parked) if isinstance(parked, str) and parked else None)
+        shared = e.get("shared_with")
+        add(h, t, n, False, est,
+            [x for x in shared if isinstance(x, str)] if isinstance(shared, list) else ())
+    return items

agent_toggle/doctor.py

@@ -0,0 +1,285 @@
+"""doctor: a read-only health check (DESIGN s6 "Harness drift").
+
+Compares each installed harness's live layout with its table row, then
+cross-checks state.json against disk. It takes no lock, never writes state, log,
+backups or modes, and never shells out (no claude CLI). Every problem row names
+the command that fixes it; nothing is deleted for you.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from . import fs, store
+from .harnesses import Harness, harnesses
+from .mechanisms import _refusal, dir_view
+from .output import CliError, Result
+from .store import load_state
+
+STYLE = {"ok": "green", "error": "red", "warn": "yellow",
+         "absent": "dim", "note": "dim", "unverified": "dim"}
+TAG = {"ok": "v", "absent": "-", "note": "i", "unverified": "?", "warn": "!", "error": "x"}
+NEED = {"move": ("parked_at", "origin"), "remove_backup": ("backup",)}
+# strings (kept) | comments | trailing commas: what makes strict JSON into JSONC
+_JSONC = re.compile(r'"(?:\\.|[^"\\])*"|//[^\n]*|/\*.*?\*/|,(?=\s*[}\]])', re.S)
+
+
+def _row(out: Result, harness, type_, name, status: str, detail: str, **extra) -> None:
+    out.row(harness, type_, name, "doctor", status, detail, show=False, **extra)
+    what = " ".join(x for x in (harness, type_, name) if x)
+    out.say(f"  {TAG[status]} {what}: {detail}", warn=status == "warn", style=STYLE[status])
+
+
+def _read_json(file: Path) -> tuple[object, str, str]:
+    """(data, kind, why); kind is ok | missing | jsonc | broken."""
+    try:
+        text = file.read_bytes().decode("utf-8").removeprefix("\ufeff")
+    except FileNotFoundError:
+        return None, "missing", "is missing"
+    except (OSError, UnicodeDecodeError) as e:
+        return None, "broken", f"cannot be read ({e})"
+    try:
+        return json.loads(text), "ok", ""
+    except ValueError as e:
+        try:                                    # parses once comments/commas are gone: JSONC
+            json.loads(_JSONC.sub(lambda m: m[0] if m[0][0] == '"' else "", text))
+            return None, "jsonc", ""
+        except ValueError:
+            return None, "broken", f"is not valid JSON ({e})"
+
+
+def _walk(data: object, path) -> tuple[bool, object]:
+    for k in path:
+        if not isinstance(data, dict) or k not in data:
+            return False, None
+        data = data[k]
+    return True, data
+
+
+def _file_row(out: Result, hname, type_, name, file: Path, kind: str, why: str, lead: str,
+              jsonc_ok: bool = True) -> None:
+    """The row for a JSON file that did not load as strict JSON."""
+    if kind == "jsonc" and jsonc_ok:     # JSONC/JSON5 is the harness's own format, not corruption
+        _row(out, hname, type_, name, "note", f"unsupported format: {file} has comments or trailing "
+             f"commas (JSONC/JSON5); agent-toggle will not edit it, doctor cannot check it")
+    else:
+        _row(out, hname, type_, name, "error", f"{lead}{file} " + (why or "is not valid JSON"))
+
+
+def _json_at(out: Result, hname, type_, name, file: Path, path, lead: str, jsonc_ok: bool = True,
+             absent_ok: bool = False):
+    """The value at `path` in a strict-JSON `file`, or None after emitting the row.
+    `absent_ok` (layout checks): a missing file / key is `absent`, not an error --
+    a harness that never configured it is fine; a recorded state entry is not."""
+    data, kind, why = _read_json(file)
+    if kind == "missing" and absent_ok:
+        _row(out, hname, type_, name, "absent", f"{file} does not exist (nothing to check)")
+        return None
+    if kind != "ok":
+        _file_row(out, hname, type_, name, file, kind, why, lead, jsonc_ok)
+        return None
+    found, value = _walk(data, path)
+    if found:
+        return value
+    _row(out, hname, type_, name, "absent" if absent_ok else "error",
+         f"{'.'.join(path)} not in {file} (nothing to check)" if absent_ok
+         else f"{lead}{'.'.join(path)} not found in {file}")
+    return None
+
+
+def _check_layout(out: Result, h: Harness, table: dict) -> None:
+    start = len(out.rows)
+    for type_, subs in h.dirs.items():
+        views = [dir_view(table, h.name, type_, h.home, s) for s in subs]
+        cands = [p for s, v in zip(subs, views) for c in (h.home / s, v.live)
+                 for p in (c, c.with_name(c.name + "-disabled"))]
+        if not any(p.exists() or p.is_symlink() for p in cands):
+            _row(out, h.name, type_, None, "absent",
+                 f"no {' / '.join(subs)} dir (or *-disabled park dir) under {h.home}")
+        if others := sorted({x for v in views for x in v.sharers} - {h.name}):
+            _row(out, h.name, type_, None, "note", f"dir shared with {', '.join(others)} "
+                 f"(disable here also affects them)")
+    if h.mcp:
+        spec, lead = h.mcp, "layout changed: "
+        if spec.backend == "toml":
+            toml = fs._tomllib()
+            if toml is None:
+                state = "unverified" if spec.file.is_file() else "absent"
+                _row(out, h.name, "mcp", None, state, f"{spec.file}: no tomllib, not parsed"
+                     if state == "unverified" else f"{spec.file} does not exist (nothing to check)")
+            else:
+                try:
+                    data = toml.loads(spec.file.read_text(encoding="utf-8"))
+                except FileNotFoundError:
+                    _row(out, h.name, "mcp", None, "absent",
+                         f"{spec.file} does not exist (nothing to check)")
+                except (OSError, ValueError) as e:
+                    _row(out, h.name, "mcp", None, "error", f"{lead}{spec.file} does not parse ({e})")
+                else:
+                    if not _walk(data, spec.key_path)[0]:
+                        _row(out, h.name, "mcp", None, "absent",
+                             f"[{'.'.join(spec.key_path)}] not in {spec.file} (nothing to check)")
+        else:
+            _json_at(out, h.name, "mcp", None, spec.file, spec.key_path, lead, jsonc_ok=False,
+                     absent_ok=True)
+    loaded: dict[str, tuple] = {}        # one read + one row per flag file, not per flag type
+    for type_, (rel, pointer) in h.flags.items():
+        prefix = pointer[:pointer.index("<name>")] if "<name>" in pointer else pointer[:-1]
+        file = h.home / rel
+        if rel not in loaded:
+            loaded[rel] = _read_json(file)
+            if loaded[rel][1] == "missing":
+                _row(out, h.name, type_, None, "absent", f"{file} does not exist (nothing to check)")
+            elif loaded[rel][1] != "ok":
+                _file_row(out, h.name, type_, None, file, *loaded[rel][1:], "layout changed: ")
+        data, kind, _ = loaded[rel]
+        if kind == "ok" and not _walk(data, prefix)[0]:
+            _row(out, h.name, type_, None, "absent",
+                 f"{'.'.join(prefix)} not in {file} (nothing to check)")
+    if not any(r["status"] == "error" for r in out.rows[start:]):
+        _row(out, h.name, None, None, "ok", "layout matches the table row")
+
+
+def _check_entry(out: Result, key: str, e: dict, table: dict) -> None:
+    sf = fs.state_file()
+    try:
+        hname, digest, type_, name = store.parse_key(key)
+    except ValueError as ex:
+        _row(out, None, None, None, "error", f"{ex}; fix: remove it from {sf} by hand")
+        return
+    ident = (hname, type_, name)
+    mech = e.get("mechanism") if isinstance(e, dict) else None
+    mech = mech if isinstance(mech, str) else None
+    if not e or not isinstance(e, dict):         # _refusal treats an empty entry as "nothing"
+        why = "entry is empty" if isinstance(e, dict) else "entry is not an object"
+    else:
+        why = _refusal(e, table, key, NEED.get(mech, ()))
+    if why:
+        _row(out, *ident, "error", f"{why}; entry fails the tamper checks, fix: inspect {sf} "
+             f"and remove the entry by hand if it is not yours")
+        return
+    enable = f"agent-toggle enable {type_} {name}"
+    project = e.get("project") if digest else None
+    if project and not Path(project).is_dir():
+        _row(out, *ident, "error", f"project dir gone: {project}; fix: recreate it, then "
+             f"`agent-toggle enable --all --project {project}` (items stay parked under "
+             f"{fs.parked_dir() / digest})")
+        return
+    flag = e.get("flag") if mech == "flag" and not e.get("connector") else None
+    if mech == "move":
+        if not Path(e["parked_at"]).exists() and not Path(e["parked_at"]).is_symlink():
+            _row(out, *ident, "error", f"parked item missing: {e['parked_at']}; fix: put it back "
+                 f"there and run `{enable}`, or remove the entry from {sf}")
+        elif not Path(e["origin"]).parent.is_dir():
+            _row(out, *ident, "error", f"origin dir gone: {Path(e['origin']).parent}; "
+                 f"fix: recreate it, then `{enable}`")
+    elif mech == "remove_backup" and not Path(e["backup"]).is_file():
+        _row(out, *ident, "error", f"backup missing: {e['backup']}; the saved config is lost -- "
+             f"re-add the server by hand, then remove the entry from {sf}")
+    elif flag:
+        value = _json_at(out, *ident, Path(flag["file"]), flag["pointer"], "")
+        if isinstance(value, bool) and value == flag["was"]:
+            _row(out, *ident, "error", f"{'.'.join(flag['pointer'])} is {str(value).lower()} in "
+                 f"{flag['file']} but the item is recorded as disabled (changed outside this "
+                 f"tool); fix: `{enable}` clears the entry")
+
+
+def _untracked(root: Path, tracked: set[str]) -> list[Path]:
+    """Items under a park dir that no state entry points at (descending into groups)."""
+    found = []
+    try:
+        children = sorted(root.iterdir())
+    except OSError:
+        return found
+    for c in children:
+        if c.name.startswith(".") or str(c) in tracked:       # .DS_Store and friends
+            continue
+        if c.is_dir() and not c.is_symlink() and any(t.startswith(str(c) + "/") or
+                                                       t.startswith(str(c) + "\\") for t in tracked):
+            found += _untracked(c, tracked)
+        else:
+            found.append(c)
+    return found
+
+
+def _check_orphans(out: Result, state: dict, table: dict, only: str | None) -> None:
+    entries = state["disabled"].values()
+    tracked = {e["parked_at"] for e in entries
+               if isinstance(e, dict) and isinstance(e.get("parked_at"), str)}
+    seen: set[Path] = set()
+    for h in table.values():
+        if (only and h.name != only) or not h.home.is_dir():
+            continue
+        for type_, subs in h.dirs.items():
+            for sub in subs:
+                parked = dir_view(table, h.name, type_, h.home, sub).parked
+                if parked in seen:
+                    continue
+                seen.add(parked)
+                for p in _untracked(parked, tracked):
+                    _row(out, h.name, type_, p.name, "warn", f"{p} is parked but has no state "
+                         f"entry (parked outside this tool); fix: move it back by hand")
+    if only:
+        return
+    digests = set()
+    for k in state["disabled"]:
+        try:
+            digests.add(store.parse_key(k)[1])
+        except ValueError:
+            pass
+    root = fs.parked_dir()
+    for d in sorted(root.iterdir()) if root.is_dir() else ():
+        if d.name.startswith("."):
+            continue
+        if d.name not in digests:
+            if d.is_dir() and not d.is_symlink() and not any(
+                    p.is_symlink() or not p.is_dir() for p in d.rglob("*")):
+                continue                # only empty dirs: what a project enable leaves behind
+            _row(out, None, None, d.name, "warn", f"{d} holds parked project items with no state "
+                 f"entry; fix: move what you want back by hand, then delete the dir")
+            continue
+        for sub in sorted(d.iterdir()) if d.is_dir() else ():
+            for p in _untracked(sub, tracked):
+                _row(out, None, None, p.name, "warn", f"{p} is parked but has no state entry; "
+                     f"fix: move it back by hand")
+    used = {Path(e["backup"]).name for e in entries
+            if isinstance(e, dict) and isinstance(e.get("backup"), str)}
+    bdir = fs.backup_dir()
+    for b in sorted(bdir.glob("*.json")) if bdir.is_dir() else ():
+        if b.name not in used:    # enable keeps the backup, so this is a note, not a fault
+            _row(out, None, None, b.name, "note", f"{b} has no state entry (kept after enable); "
+                 f"delete it yourself once the server is confirmed restored")
+
+
+def _check_modes(out: Result) -> None:
+    for p in (fs.state_file(), *fs.backup_dir().glob("*.json")):
+        if fs.too_open(p, 0o077):
+            _row(out, None, None, p.name, "warn", f"{p} is looser than 0600; fix: chmod 600 {p}")
+    if fs.too_open(fs.state_dir()):
+        _row(out, None, None, None, "warn", f"{fs.state_dir()} is group/world readable; "
+             f"fix: chmod 700 {fs.state_dir()}")
+
+
+def cmd_doctor(harness: str | None, out: Result) -> None:
+    table = harnesses()
+    installed = [h for n, h in table.items() if (not harness or n == harness) and h.home.is_dir()]
+    if harness and not installed:
+        _row(out, harness, None, None, "note", f"not installed ({table[harness].home} does not exist)")
+    for h in installed:
+        _check_layout(out, h, table)
+    try:
+        state = load_state(write_back=False, check_entries=False)    # bad entries get rows
+    except CliError as e:
+        _row(out, None, None, None, "error", f"{e.msg}; fix: repair or move aside {fs.state_file()}")
+    else:
+        for key, e in state["disabled"].items():
+            if harness and not (isinstance(e, dict) and harness in (e.get("harness"),
+                                                                    *(e.get("shared_with") or ()))):
+                continue
+            _check_entry(out, key, e, table)
+        _check_orphans(out, state, table, harness)
+    if not harness:
+        _check_modes(out)
+    errors = sum(r["status"] == "error" for r in out.rows)
+    out.say(f"\ndoctor: {errors} problem(s), {len(out.warnings)} warning(s)")