@mmerterden/multi-agent-pipeline 16.28.0 → 16.30.0

package/pipeline/scripts/doctor.mjs

@@ -0,0 +1,758 @@
+#!/usr/bin/env node
+/**
+ * @file doctor.mjs  -  what is wrong with this install, and the one step that fixes it.
+ *
+ * WHY THIS EXISTS
+ *
+ * Every failure this reports has already reached a user, and each one arrived
+ * the same way: late, mid-run, after the pickers had been answered. A missing
+ * script fails at the call. Malformed preferences fail after Phase 0 has already
+ * asked five questions. A token in a remote URL does not fail at all - it leaks.
+ * None of it is visible beforehand, so the pipeline's own answer to "is this
+ * machine set up correctly" was to start a run and find out.
+ *
+ * So this is a gate, not a report. The exit code is the product:
+ *
+ *   0  healthy        nothing above INFO
+ *   1  degraded       at least one WARN
+ *   2  blocked        at least one BLOCK
+ *   3  usage error
+ *   4  indeterminate  the layout did not resolve, so nothing was checked
+ *
+ * 4 is the one people forget. Without it "I could not look" borrows the exit
+ * code of "I looked and it is fine", and every consumer downstream believes a
+ * broken resolver is a clean bill.
+ *
+ * BLOCK IS A CLOSED DEFINITION: a state where a run will fail or leak, never one
+ * where it will merely be worse. Five checks can produce it and the rest top out
+ * at WARN however bad they look. Without that rule "blocked" grows until nobody
+ * respects exit 2.
+ *
+ * IT RECOMMENDS, IT NEVER FIXES. A remote whose URL carries a token may be the
+ * only credential that repo has; the remote may be a mirror a script depends on
+ * verbatim; and this can run inside a checkout the user does not own. Silent
+ * repair breaks all three.
+ *
+ * Contract, every check by id, and the severity rules: multi-agent-refs/features/doctor.md
+ *
+ * Usage:
+ *   doctor.mjs [--probe] [--json] [--explain] [--task-tools=yes|no]
+ *   doctor.mjs --list-checks
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  realpathSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const HOME = homedir();
+const CLAUDE = join(HOME, ".claude");
+
+const argv = process.argv.slice(2);
+const JSON_OUT = argv.includes("--json");
+const PROBE = argv.includes("--probe");
+const EXPLAIN = argv.includes("--explain");
+const LIST = argv.includes("--list-checks");
+const taskFlag = argv.find((a) => a.startsWith("--task-tools="));
+const TASK_TOOLS = taskFlag ? taskFlag.split("=")[1] : null;
+
+// The id set. Kept here and in features/doctor.md, and smoke-doctor.sh asserts
+// the two are equal in BOTH directions: a check cannot ship without its entry,
+// and an entry cannot outlive its check.
+const CHECK_IDS = [
+  "install-present",
+  "install-version",
+  "script-surface",
+  "skill-siblings",
+  "state-writable",
+  "prefs-valid",
+  "identity",
+  "hook-coverage",
+  "credential-mapping",
+  "credential-liveness",
+  "embedded-credentials",
+  "task-tools",
+  "mcp-registration",
+  "disk-space",
+];
+
+// Only these five may return BLOCK. Enforced below, not merely documented: a
+// check that returns BLOCK without being listed here is downgraded and the
+// downgrade is reported, because an unenforced rule is a comment.
+const MAY_BLOCK = new Set([
+  "install-present",
+  "script-surface",
+  "state-writable",
+  "prefs-valid",
+  "embedded-credentials",
+]);
+
+// The step's first word. A closed list is what stops "consider reviewing your
+// configuration" from being an acceptable answer.
+const STEP_VERBS = [
+  "run",
+  "set",
+  "map",
+  "revoke",
+  "install",
+  "remove",
+  "free",
+  "export",
+  "merge",
+  "record",
+  "re-run",
+];
+
+const results = [];
+const STEP_RE = new RegExp(`^(${STEP_VERBS.join("|")})\\b`);
+
+function report(id, severity, problem, step, detail) {
+  let sev = severity;
+  if (sev === "BLOCK" && !MAY_BLOCK.has(id)) {
+    sev = "WARN";
+    problem = `${problem} (downgraded: ${id} is not a blocking check)`;
+  }
+  // The writing contract is enforced where a step is written, not only in the
+  // gate. A rule that lives solely in a test is a rule the next author will not
+  // see, and "consider reviewing your configuration" is the shape it decays to.
+  if (step && !STEP_RE.test(step)) {
+    throw new Error(
+      `doctor: the step for "${id}" must start with one of ${STEP_VERBS.join(", ")} - got "${step}"`,
+    );
+  }
+  results.push({ id, severity: sev, problem, step: step || null, detail: detail || null });
+}
+const ok = (id) => report(id, "OK", null, null);
+const skip = (id, why) => report(id, "SKIP", why, null);
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/* ---------------------------------------------------------------- checks -- */
+
+// The scope is pinned in the reinstall step on purpose. A `@mmerterden:registry=`
+// line in the user's own .npmrc outranks `--registry`, so an unpinned npx
+// resolves against whatever that file names - which on a machine configured for
+// GitHub Packages is a 404 and a process that never starts. A health check whose
+// one step silently fails is worse than no step. Rule: smoke-npm-scope-pinning.sh.
+const SUBTREES = ["commands", "multi-agent-refs", "scripts", "lib", "schemas"];
+
+function checkInstallPresent() {
+  if (!existsSync(CLAUDE)) {
+    report(
+      "install-present",
+      "BLOCK",
+      `no install at ${CLAUDE}`,
+      "run npx --@mmerterden:registry=https://registry.npmjs.org @mmerterden/multi-agent-pipeline install",
+    );
+    return false;
+  }
+  const missing = SUBTREES.filter((d) => !existsSync(join(CLAUDE, d)));
+  if (missing.length) {
+    report(
+      "install-present",
+      "BLOCK",
+      `the install is missing ${missing.join(", ")}`,
+      "run npx --@mmerterden:registry=https://registry.npmjs.org @mmerterden/multi-agent-pipeline install",
+    );
+    return false;
+  }
+  ok("install-present");
+  return true;
+}
+
+function checkInstallVersion() {
+  const stamp = join(CLAUDE, ".pipeline-version");
+  if (!existsSync(stamp)) {
+    skip("install-version", "no .pipeline-version stamp in the installed tree");
+    return;
+  }
+  const installed = readFileSync(stamp, "utf8").trim();
+  const pkgPath = join(HERE, "..", "..", "package.json");
+  const pkg = existsSync(pkgPath) ? readJson(pkgPath) : null;
+  if (!pkg?.version) {
+    skip("install-version", "no checkout resolved from here to compare against");
+    return;
+  }
+  if (installed !== pkg.version) {
+    report(
+      "install-version",
+      "WARN",
+      `installed ${installed}, this checkout is ${pkg.version}`,
+      "run /multi-agent:update",
+    );
+    return;
+  }
+  ok("install-version");
+}
+
+function checkScriptSurface() {
+  const cmdDir = join(CLAUDE, "commands", "multi-agent");
+  if (!existsSync(cmdDir)) {
+    skip("script-surface", "no installed command tree to read");
+    return;
+  }
+  const wanted = new Set();
+  for (const d of readdirSync(cmdDir)) {
+    const f = join(cmdDir, d, "SKILL.md");
+    if (!existsSync(f)) continue;
+    const text = readFileSync(f, "utf8");
+    // The path segment has to allow `/`. Without it a reference to
+    // `scripts/nested/bar.mjs` was truncated to the directory, so as long as the
+    // directory existed a missing file one level inside it passed - the check
+    // reported OK for exactly the case it exists to catch.
+    for (const m of text.matchAll(
+      /\$HOME\/\.claude\/(scripts|lib)\/([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)/g,
+    )) {
+      wanted.add(join(m[1], m[2]));
+    }
+  }
+  const missing = [...wanted].filter((rel) => !existsSync(join(CLAUDE, rel))).sort();
+  if (missing.length) {
+    report(
+      "script-surface",
+      "BLOCK",
+      `${missing.length} script(s) a command calls are not installed: ${missing.slice(0, 3).join(", ")}`,
+      "run /multi-agent:update",
+      missing,
+    );
+    return;
+  }
+  ok("script-surface");
+}
+
+function checkSkillSiblings() {
+  const sib = join(CLAUDE, "scripts", "skill-siblings.mjs");
+  if (!existsSync(sib)) {
+    skip("skill-siblings", "skill-siblings.mjs is not installed");
+    return;
+  }
+  let out;
+  try {
+    out = execFileSync("node", [sib, "--audit", "--json"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (e) {
+    report(
+      "skill-siblings",
+      "WARN",
+      `the sibling audit did not complete: ${String(e.message).split("\n")[0]}`,
+      "run /multi-agent:sync",
+    );
+    return;
+  }
+  const j = (() => {
+    try {
+      return JSON.parse(out);
+    } catch {
+      return null;
+    }
+  })();
+  if (!j) {
+    report("skill-siblings", "WARN", "the sibling audit returned no JSON", "run /multi-agent:sync");
+    return;
+  }
+  // A local-only wrapper is authored for this machine and deliberately excluded
+  // from the sync, so it is absent from Copilot and Codex by design. Counting it
+  // as unsynced told the user to run a sync that would change nothing - a health
+  // check whose one step is a no-op teaches people to ignore it.
+  const localOnly = new Set();
+  const cmdRoot = join(CLAUDE, "commands", "multi-agent");
+  if (existsSync(cmdRoot)) {
+    for (const d of readdirSync(cmdRoot)) {
+      const f = join(cmdRoot, d, "SKILL.md");
+      if (existsSync(f) && /^local-only:\s*true/m.test(readFileSync(f, "utf8"))) localOnly.add(d);
+    }
+  }
+  const unsynced = (j.rows || []).filter(
+    (r) => !localOnly.has(r.name) && (r.missingInstalled || []).length > 0,
+  ).length;
+  if (unsynced > 0) {
+    report(
+      "skill-siblings",
+      "WARN",
+      `${unsynced} of ${j.commands - localOnly.size} synced command(s) are missing from at least one installed host`,
+      "run /multi-agent:sync",
+    );
+    return;
+  }
+  ok("skill-siblings");
+}
+
+function checkStateWritable() {
+  const dir = join(CLAUDE, "logs", "multi-agent");
+  try {
+    mkdirSync(dir, { recursive: true });
+    const probe = join(dir, `.doctor-${process.pid}`);
+    writeFileSync(probe, "x");
+    rmSync(probe);
+  } catch (e) {
+    report(
+      "state-writable",
+      "BLOCK",
+      `cannot write run state under ${dir}: ${e.code || e.message}`,
+      `run chmod u+w ${dir}`,
+    );
+    return;
+  }
+  ok("state-writable");
+}
+
+function checkPrefsValid() {
+  const prefs = join(CLAUDE, "multi-agent-preferences.json");
+  if (!existsSync(prefs)) {
+    report("prefs-valid", "WARN", "no preferences file yet", "run /multi-agent:setup");
+    return;
+  }
+  const j = readJson(prefs);
+  if (!j) {
+    report(
+      "prefs-valid",
+      "BLOCK",
+      "multi-agent-preferences.json does not parse",
+      "run /multi-agent:setup",
+    );
+    return;
+  }
+  if (typeof j.global !== "object" || j.global === null) {
+    report("prefs-valid", "BLOCK", "preferences carry no global block", "run /multi-agent:setup");
+    return;
+  }
+  ok("prefs-valid");
+}
+
+function checkIdentity() {
+  // The key is `identities[]` - a list, because a machine with a work and a
+  // personal account needs both, and `platformIdentityRouting` picks per remote.
+  // Looking for a singular `identity` reported "none recorded" on a machine with
+  // two, which is the shape of wrongness a health check must not have.
+  const prefs = readJson(join(CLAUDE, "multi-agent-preferences.json"));
+  const list = prefs?.global?.identities;
+  const usable = Array.isArray(list) ? list.filter((i) => i?.name && i?.email) : [];
+  if (usable.length) {
+    ok("identity");
+    return;
+  }
+  report(
+    "identity",
+    "WARN",
+    "no git identity recorded, so a run stops at the commit phase",
+    "run /multi-agent:setup",
+  );
+}
+
+function checkHookCoverage() {
+  const tpl = join(CLAUDE, "templates", "claude-hooks.json");
+  if (!existsSync(tpl)) {
+    skip("hook-coverage", "no hooks template installed to compare against");
+    return;
+  }
+  const want = readJson(tpl);
+  const have = readJson(join(CLAUDE, "settings.json"));
+  if (!want) {
+    skip("hook-coverage", "the hooks template does not parse");
+    return;
+  }
+  const wantedCmds = new Set();
+  for (const group of Object.values(want.hooks || {})) {
+    for (const entry of group || []) {
+      for (const h of entry.hooks || []) if (h.command) wantedCmds.add(h.command);
+    }
+  }
+  const haveStr = JSON.stringify(have?.hooks || {});
+  const absent = [...wantedCmds].filter((c) => !haveStr.includes(c));
+  if (absent.length) {
+    report(
+      "hook-coverage",
+      "WARN",
+      `${absent.length} of ${wantedCmds.size} template hook(s) are not in settings.json`,
+      `merge ${tpl} into ${join(CLAUDE, "settings.json")}`,
+    );
+    return;
+  }
+  ok("hook-coverage");
+}
+
+function credentialInventory() {
+  const inv = join(CLAUDE, "lib", "credential-inventory.sh");
+  if (!existsSync(inv)) return null;
+  try {
+    const args = PROBE ? [inv, "--json", "--probe"] : [inv, "--json"];
+    return JSON.parse(
+      execFileSync("bash", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }),
+    );
+  } catch {
+    return null;
+  }
+}
+
+function checkCredentials(inv) {
+  if (!inv) {
+    skip("credential-mapping", "credential-inventory.sh did not produce an inventory");
+    skip("credential-liveness", "credential-inventory.sh did not produce an inventory");
+    return;
+  }
+  // The INFO / WARN boundary is decided in credential-inventory.sh; this only
+  // renders it. Unmapped is a capability the user chose not to enable, which is
+  // information. A mapped credential the service refused is a warning, because
+  // the configuration made a claim.
+  const malformed = (inv.credentials || []).filter((c) => c.state === "malformed");
+  const unmapped = (inv.credentials || []).filter((c) => c.state === "unmapped");
+  if (malformed.length) {
+    report(
+      "credential-mapping",
+      "WARN",
+      `${malformed.length} mapped credential(s) are malformed: ${malformed.map((c) => c.logical).join(", ")}`,
+      "run /multi-agent:setup",
+    );
+  } else if (unmapped.length) {
+    report(
+      "credential-mapping",
+      "INFO",
+      `${unmapped.length} optional capabilit${unmapped.length === 1 ? "y is" : "ies are"} not enabled: ${unmapped.map((c) => c.logical).join(", ")}`,
+      `map ${unmapped.map((c) => c.logical).join(", ")} with /multi-agent:setup`,
+    );
+  } else {
+    ok("credential-mapping");
+  }
+
+  if (!PROBE) {
+    skip("credential-liveness", "no --probe: a network check is the caller's decision to spend");
+    return;
+  }
+  // A rejected credential and an unreachable host need different actions, and
+  // credential-inventory.sh already separates them: "unreachable - no response
+  // at all - on a corporate host, almost always the VPN". Telling someone to
+  // re-onboard a token that was never the problem is the failure mode the
+  // registry's own keychain rule warns about, one layer up.
+  const rejected = [
+    ...(inv.authRejected || []).map((k) => [k, "rejected"]),
+    ...(inv.needsGrant || []).map((k) => [k, "no grant"]),
+  ];
+  const unreachable = (inv.unreachable || []).slice();
+  if (rejected.length) {
+    report(
+      "credential-liveness",
+      "WARN",
+      `${rejected.length} credential(s) were refused: ${rejected.map(([k, w]) => `${k} (${w})`).join(", ")}`,
+      "run /multi-agent:setup",
+    );
+    return;
+  }
+  if (unreachable.length) {
+    report(
+      "credential-liveness",
+      "WARN",
+      `${unreachable.length} host(s) did not answer at all: ${unreachable.join(", ")}`,
+      "run the probe again on the network those hosts are on",
+    );
+    return;
+  }
+  ok("credential-liveness");
+}
+
+function checkEmbeddedCredentials() {
+  // The value never enters a shell variable or this process's output. What is
+  // reported is the repo, the config key, the host, a shape label and a length
+  // bucket - because `ghp_` plus a length is already a fingerprint, and this
+  // line goes to a terminal that is often shared, which is why the check exists.
+  const roots = [process.cwd()];
+  const found = [];
+  for (const root of roots) {
+    const cfg = join(root, ".git", "config");
+    if (!existsSync(cfg)) continue;
+    let text;
+    try {
+      text = readFileSync(cfg, "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of text.split("\n")) {
+      const m = line.match(/^\s*(url)\s*=\s*(\S+)\s*$/);
+      if (!m) continue;
+      const cred = m[2].match(/^https?:\/\/([^@/]+)@([^/]+)/);
+      if (!cred) continue;
+      const secret = cred[1].includes(":") ? cred[1].split(":")[1] : cred[1];
+      if (!secret || secret.length < 8) continue;
+      const bucket = secret.length < 40 ? "<40" : secret.length < 100 ? "40-99" : ">=100";
+      found.push({
+        repo: root,
+        key: m[1],
+        host: cred[2],
+        shape: "userinfo-in-url",
+        length: bucket,
+      });
+    }
+  }
+  if (found.length) {
+    const f = found[0];
+    report(
+      "embedded-credentials",
+      "BLOCK",
+      `a credential is embedded in a git remote (${f.repo}, ${f.key}, host ${f.host}, ${f.shape}, length ${f.length})`,
+      `revoke that credential at ${f.host}`,
+      found,
+    );
+    return;
+  }
+  ok("embedded-credentials");
+}
+
+function checkTaskTools() {
+  if (TASK_TOOLS !== "yes" && TASK_TOOLS !== "no") {
+    // A script cannot see the model's tool list. Answering "absent" from here
+    // would be the same defect this check is about.
+    skip("task-tools", "the caller did not report its tool list (--task-tools=yes|no)");
+    return;
+  }
+  if (TASK_TOOLS === "yes") {
+    ok("task-tools");
+    return;
+  }
+  report(
+    "task-tools",
+    "INFO",
+    "this session's model does not carry TaskCreate/TaskUpdate, so the phase widget cannot render",
+    "export CLAUDE_CODE_ENABLE_TODO_TOOLS=1 before starting Claude Code",
+  );
+}
+
+function checkMcpRegistration() {
+  // Registered is not the same as working, and the difference is what the user
+  // actually hits: a half-extracted package in the npx cache left the server
+  // dying on `Cannot find module` at startup, which the client reports only as
+  // CONNECTION_CLOSED. A check that reads the registration and stops would have
+  // called that healthy. So without --probe this reports what is CONFIGURED and
+  // says so; with --probe it starts the server and counts the tools it serves.
+  let entry = null;
+  for (const p of [join(HOME, ".claude.json"), join(CLAUDE, "settings.json")]) {
+    const j = readJson(p);
+    const key = j?.mcpServers && Object.keys(j.mcpServers).find((k) => /toolkit/i.test(k));
+    if (key) {
+      entry = j.mcpServers[key];
+      break;
+    }
+  }
+  if (!entry) {
+    report(
+      "mcp-registration",
+      "INFO",
+      "multi-agent-toolkit is not registered as an MCP server, so its tools are unavailable",
+      "install it with claude mcp add multi-agent-toolkit",
+    );
+    return;
+  }
+  if (!PROBE) {
+    ok("mcp-registration");
+    return;
+  }
+  const handshake = [
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "doctor", version: "1" },
+      },
+    }),
+    JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+    JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }),
+  ].join("\n");
+  let served = 0;
+  let why = "";
+  try {
+    const out = execFileSync(entry.command, entry.args || [], {
+      input: `${handshake}\n`,
+      encoding: "utf8",
+      timeout: 240000,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...(entry.env || {}) },
+    });
+    for (const line of out.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const m = JSON.parse(line);
+        if (m.id === 2 && m.result?.tools) served = m.result.tools.length;
+      } catch {
+        /* the server may print non-JSON lines */
+      }
+    }
+  } catch (e) {
+    why =
+      String(e.stderr || e.message || "")
+        .split("\n")
+        .find((l) => /Error|error/.test(l)) || "the server did not start";
+  }
+  if (served > 0) {
+    ok("mcp-registration");
+    return;
+  }
+  report(
+    "mcp-registration",
+    "WARN",
+    `multi-agent-toolkit is registered but served no tools${why ? ` (${why.trim().slice(0, 90)})` : ""}`,
+    "remove the stale npx cache entry under ~/.npm/_npx and let it re-download",
+    why,
+  );
+}
+
+function checkDiskSpace() {
+  let freeGb = null;
+  try {
+    const out = execFileSync("df", ["-k", HOME], { encoding: "utf8" });
+    const line = out.trim().split("\n").pop();
+    const cols = line.split(/\s+/);
+    const availKb = Number(cols[3]);
+    if (Number.isFinite(availKb)) freeGb = availKb / 1024 / 1024;
+  } catch {
+    /* df is not everywhere */
+  }
+  if (freeGb === null) {
+    skip("disk-space", "df did not report a usable figure on this host");
+    return;
+  }
+  if (freeGb < 2) {
+    report(
+      "disk-space",
+      "WARN",
+      `${freeGb.toFixed(1)} GB free on the volume holding $HOME; a worktree plus a build needs more`,
+      "free space before starting a run",
+    );
+    return;
+  }
+  ok("disk-space");
+}
+
+/* ------------------------------------------------------------------ main -- */
+
+function main() {
+  if (LIST) {
+    for (const id of CHECK_IDS) process.stdout.write(`${id}\n`);
+    return;
+  }
+  const unknown = argv.filter(
+    (a) => a.startsWith("--") && !/^--(probe|json|explain|list-checks|task-tools=)/.test(a),
+  );
+  if (unknown.length) {
+    process.stderr.write(
+      `usage: doctor.mjs [--probe] [--json] [--explain] [--task-tools=yes|no] | --list-checks\n`,
+    );
+    process.exitCode = 3;
+    return;
+  }
+  if (taskFlag && TASK_TOOLS !== "yes" && TASK_TOOLS !== "no") {
+    process.stderr.write("usage: --task-tools takes yes or no\n");
+    process.exitCode = 3;
+    return;
+  }
+
+  const resolved = checkInstallPresent();
+  if (!resolved) {
+    // Indeterminate, not healthy and not merely degraded: nothing after this
+    // could be checked, and saying "blocked" would claim a verdict on checks
+    // that never ran.
+    const line = results[0];
+    if (JSON_OUT) {
+      process.stdout.write(`${JSON.stringify({ exit: 4, checks: results }, null, 2)}\n`);
+    } else {
+      process.stdout.write(`${line.severity} ${line.id}  -  ${line.problem}  -  ${line.step}\n`);
+      process.stdout.write(
+        "\n-> indeterminate: the layout did not resolve, so 13 checks did not run\n",
+      );
+    }
+    process.exitCode = 4;
+    return;
+  }
+
+  checkInstallVersion();
+  checkScriptSurface();
+  checkSkillSiblings();
+  checkStateWritable();
+  checkPrefsValid();
+  checkIdentity();
+  checkHookCoverage();
+  checkCredentials(credentialInventory());
+  checkEmbeddedCredentials();
+  checkTaskTools();
+  checkMcpRegistration();
+  checkDiskSpace();
+
+  const blocked = results.filter((r) => r.severity === "BLOCK");
+  const warned = results.filter((r) => r.severity === "WARN");
+  const skipped = results.filter((r) => r.severity === "SKIP");
+  const code = blocked.length ? 2 : warned.length ? 1 : 0;
+
+  if (JSON_OUT) {
+    process.stdout.write(`${JSON.stringify({ exit: code, checks: results }, null, 2)}\n`);
+    process.exitCode = code;
+    return;
+  }
+
+  // Every check prints, in registry order, including the ones that found
+  // nothing and the ones that were not run. A list that shows only problems
+  // cannot be told apart from a list that was never produced.
+  for (const id of CHECK_IDS) {
+    const r = results.find((x) => x.id === id);
+    if (!r) continue;
+    if (r.severity === "OK") {
+      process.stdout.write(`OK    ${id}\n`);
+    } else if (r.severity === "SKIP") {
+      process.stdout.write(`SKIP  ${id}  -  ${r.problem}\n`);
+    } else {
+      process.stdout.write(`${r.severity.padEnd(5)} ${id}  -  ${r.problem}  -  ${r.step}\n`);
+    }
+  }
+  const verdict = code === 0 ? "healthy" : code === 1 ? "degraded" : "blocked";
+  process.stdout.write(
+    `\n-> ${verdict}: ${blocked.length} blocking, ${warned.length} warning(s), ${skipped.length} not checked, ${results.length} checks\n`,
+  );
+  if (EXPLAIN) {
+    for (const r of results.filter((x) => x.detail)) {
+      process.stdout.write(`\n${r.id}:\n`);
+      for (const d of Array.isArray(r.detail) ? r.detail : [r.detail]) {
+        process.stdout.write(`  ${typeof d === "string" ? d : JSON.stringify(d)}\n`);
+      }
+    }
+  }
+  process.exitCode = code;
+}
+
+// Exported so the gate can DRIVE the engine instead of reading it. The BLOCK
+// downgrade used to be asserted with a regex over this file's own source, which
+// a comment carrying the same two substrings satisfied just as well as the code
+// did - the enforcement could be deleted outright and the gate stayed green.
+export { report, results as __results, MAY_BLOCK as __mayBlock };
+
+// realpath on both sides: `import.meta.url` is already resolved, while argv[1]
+// is whatever the caller typed. On macOS a run out of /tmp (a symlink to
+// /private/tmp) would otherwise never match, and the script would do nothing.
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  main();
+}