clembot-doorman 0.1.0

package/doorman/cli/cost.mjs

@@ -0,0 +1,119 @@
+/**
+ * What an eval can cost, before it costs it.
+ *
+ * The first version of this harness had `MAX_TURNS = 24` and nothing else. That
+ * bounds TURNS, not tokens, and the two are not the same by a wide margin,
+ * because an agent loop resends the whole conversation every turn. Cost grows
+ * with the SQUARE of the turn count, not linearly, and a 24-turn cap quietly
+ * authorises far more spend than it looks like it does.
+ *
+ * Worked, for one run at the defaults:
+ *
+ *   input at turn k   = prompt + (k-1) x (max_tokens + tool_result_cap)
+ *   total input       = T x prompt + (max_tokens + cap) x T(T-1)/2
+ *   T=24, cap=5000    = 24 x 1000 + 9096 x 276 = ~2.53M input tokens
+ *   total output      = 24 x 4096 = ~98k
+ *
+ * On Sonnet that is about **$9 for ONE run**, so a 3-run A/B is six runs and
+ * roughly **$54**. On Haiku, about $18. Those are the numbers that justify a
+ * ceiling rather than a promise to be careful.
+ *
+ * Typical is far lower, because most runs end in three to six turns. But
+ * "typical" is not what you need a limit for.
+ *
+ * The ceiling reuses `src/budget.mjs`, the same permit machinery the doorman
+ * already uses to stop itself overspending outward. Same rule pointed at our
+ * own bill: reserve the WORST case before the run, settle the actual after.
+ * Reserving the expected cost would be a limit that only holds when nothing
+ * goes wrong, which is the opposite of a limit.
+ */
+
+/** USD per million tokens. A model absent here has no price and cannot be capped. */
+export const PRICES = {
+  'claude-opus-5': { in: 15, out: 75 },
+  'claude-sonnet-5': { in: 3, out: 15 },
+  'claude-haiku-4-5-20251001': { in: 1, out: 5 },
+  // Local models are free at the margin. Not zero-effort, but zero-billing.
+  'ollama': { in: 0, out: 0 },
+};
+
+export const DEFAULTS = {
+  maxTurns: 24,
+  maxTokens: 4096,
+  toolResultCap: 5000,   // 20000 chars, roughly
+  promptTokens: 1000,
+};
+
+export function priceFor(model) {
+  if (PRICES[model]) return PRICES[model];
+  if (String(model).startsWith('ollama/')) return PRICES.ollama;
+  return null;
+}
+
+/** The most one run can possibly cost. Used for the reservation, not for display alone. */
+export function worstCaseRunUsd(model, o = {}) {
+  const p = priceFor(model);
+  if (!p) return null;
+  const { maxTurns, maxTokens, toolResultCap, promptTokens } = { ...DEFAULTS, ...o };
+  const perTurnGrowth = maxTokens + toolResultCap;
+  const inputTokens = maxTurns * promptTokens + perTurnGrowth * (maxTurns * (maxTurns - 1)) / 2;
+  const outputTokens = maxTurns * maxTokens;
+  return round4((inputTokens / 1e6) * p.in + (outputTokens / 1e6) * p.out);
+}
+
+/**
+ * A rough typical run, for the estimate line only.
+ *
+ * Labelled clearly wherever it is shown. It is an expectation, and an
+ * expectation is not a bound: nothing is ever reserved against this number.
+ */
+export function typicalRunUsd(model, o = {}) {
+  return worstCaseRunUsd(model, { ...o, maxTurns: 5 });
+}
+
+export function estimateEval({ model, runs, ...o }) {
+  const perRunWorst = worstCaseRunUsd(model, o);
+  const perRunTypical = typicalRunUsd(model, o);
+  const totalRuns = runs * 2;                  // two arms
+  return {
+    model,
+    runs_per_arm: runs,
+    total_runs: totalRuns,
+    priced: perRunWorst !== null,
+    per_run_worst_usd: perRunWorst,
+    per_run_typical_usd: perRunTypical,
+    worst_case_usd: perRunWorst === null ? null : round4(perRunWorst * totalRuns),
+    typical_usd: perRunTypical === null ? null : round4(perRunTypical * totalRuns),
+  };
+}
+
+function round4(n) { return Math.round(n * 1e4) / 1e4; }
+
+/**
+ * Render the estimate for a human about to spend money.
+ *
+ * Leads with the worst case, because that is the number the decision needs. A
+ * cost warning that leads with the typical figure is an advert.
+ */
+export function renderEstimate(e) {
+  if (!e.priced) {
+    return [
+      `Model "${e.model}" has no price in the table, so no ceiling can be enforced.`,
+      'Refusing to guess: an unknown price is not a free one.',
+      'Add it to PRICES in cli/cost.mjs. A local-model backend is designed but not built.',
+    ].join('\n');
+  }
+  if (e.worst_case_usd === 0) {
+    return `Local model (${e.model}): $0.00. Nothing is billed. ${e.total_runs} run(s) total.`;
+  }
+  return [
+    `Model ${e.model} · ${e.runs_per_arm} run(s) per arm · ${e.total_runs} runs total`,
+    '',
+    `  WORST CASE   $${e.worst_case_usd.toFixed(2)}   ($${e.per_run_worst_usd.toFixed(2)} per run)`,
+    `  typical      $${e.typical_usd.toFixed(2)}   ($${e.per_run_typical_usd.toFixed(2)} per run)`,
+    '',
+    'The worst case is what gets reserved before each run. It assumes every run',
+    'hits the turn cap with a full tool result every turn. Most do not, and the',
+    'unused reservation is released, so you are billed the actual, not the bound.',
+  ].join('\n');
+}

package/doorman/cli/discover.mjs

@@ -0,0 +1,265 @@
+/**
+ * `doorman discover` - find candidates in a public MCP directory.
+ *
+ * MACHINES FETCH, HUMANS CURATE. This writes a candidate file and stops. It
+ * never enqueues an audit, never spends, and never adds anything to a feed.
+ * 13,648 entries you have not looked at is not a feed, it is a backlog, and
+ * auto-promoting a directory into a grading queue would put the operator's name
+ * on verdicts nobody chose to seek.
+ *
+ * WHAT IT CAN AND CANNOT DO, and the distinction is the whole file:
+ *
+ * The Smithery registry publishes each server's TOOL DESCRIPTIONS in its detail
+ * record. So the static scan, the one that found instruction-shaped content in
+ * a shipping product, can run over the directory's own published text without
+ * calling a single server, without auth, and without spending anything.
+ *
+ * That is a SCAN, not a GRADE. A grade requires driving the server: does the
+ * agent succeed, does it recover, does it get steered. The registry cannot tell
+ * you that and neither can this command, so it reports `graded: false` on every
+ * row and never emits a letter. This is `mayBeGraded()` applied to a third
+ * source: when there is nothing to drive, say what was not measured rather than
+ * leaving a null for a reader to fill in wrongly.
+ *
+ * WHY IT DOES NOT RESOLVE AN ORIGIN. The registry only ever returns its own
+ * proxy (`<name>.run.tools`), which answers 401 without a Smithery token. The
+ * origin endpoint is not in the record. So a candidate here carries the
+ * registry identity and needs a human to supply the real endpoint before it can
+ * be graded. Pretending the proxy url is the server would grade the proxy.
+ */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { sniffInstructions } from '../src/injection.mjs';
+
+export const SMITHERY_API = 'https://registry.smithery.ai';
+export const PAGE_SIZE = 100;
+export const UA = 'clembot-doorman/0.1 (+https://clembot-doorman.wanessalabs.com)';
+
+/** The proxy host the registry hands out instead of an origin. */
+export const PROXY_SUFFIX = '.run.tools';
+
+/**
+ * Is this url something doorman could actually grade?
+ *
+ * The registry's deploymentUrl is a proxy that requires a Smithery token, so it
+ * is NOT a gradeable endpoint even though it is a valid https url. Saying so
+ * per row is the difference between a candidate list and a list of things that
+ * will 401 when somebody tries.
+ */
+export function isGradeableEndpoint(url) {
+  if (!url) return false;
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'https:') return false;
+    return !u.hostname.endsWith(PROXY_SUFFIX);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Everything a scan can see in one registry record.
+ *
+ * Tool descriptions are concatenated with their names, because a name can carry
+ * steering too and scanning descriptions alone would miss it.
+ */
+export function scannableText(detail) {
+  const parts = [];
+  if (detail.description) parts.push(String(detail.description));
+  for (const t of detail.tools ?? []) {
+    if (t?.name) parts.push(String(t.name));
+    if (t?.description) parts.push(String(t.description));
+  }
+  return parts.join('\n\n');
+}
+
+export function assess(listRow, detail) {
+  const text = scannableText(detail);
+  const scan = sniffInstructions(text, 'registry:tool-descriptions');
+  const endpoint = detail.deploymentUrl ?? (detail.connections ?? [])[0]?.deploymentUrl ?? null;
+
+  return {
+    source: 'smithery',
+    id: listRow.qualifiedName ?? detail.qualifiedName,
+    name: detail.displayName ?? listRow.displayName ?? null,
+    registry_url: `${SMITHERY_API}/servers/${encodeURIComponent(listRow.qualifiedName)}`,
+    // What the registry hands out, and whether it is any use for grading.
+    registry_endpoint: endpoint,
+    endpoint_is_proxy: endpoint ? !isGradeableEndpoint(endpoint) : null,
+    gradeable_endpoint: isGradeableEndpoint(endpoint) ? endpoint : null,
+    homepage: listRow.homepage ?? null,
+    verified: Boolean(listRow.verified),
+    use_count: listRow.useCount ?? null,
+    tools: (detail.tools ?? []).length,
+    // The registry's own words about what this does, kept so `doorman needs`
+    // can match it against a build's needs and CITE the text that matched.
+    // Capped because a sweep writes thousands of these and the file is read by
+    // a human. Tool NAMES only: the descriptions are already scanned above and
+    // storing them twice would double a candidate file for no new signal.
+    description: detail.description ? String(detail.description).slice(0, 400) : null,
+    tool_names: (detail.tools ?? []).map((t) => t?.name).filter(Boolean).slice(0, 40),
+    // The registry has a security field. On everything sampled it is null.
+    registry_security: detail.security ?? null,
+    scan: {
+      scanned_chars: scan.scanned_chars,
+      hard: scan.hard,
+      steering: scan.steering,
+      failure_modes: scan.failure_modes,
+    },
+    // Never a letter. Nothing here drove the server.
+    graded: false,
+    grade: null,
+    behavioral: 'n/a - nothing was driven, this is a scan of published text',
+  };
+}
+
+/** One page of the registry listing. */
+export async function fetchPage(page, { fetchImpl = fetch, api = SMITHERY_API } = {}) {
+  const r = await fetchImpl(`${api}/servers?pageSize=${PAGE_SIZE}&page=${page}`, {
+    headers: { 'user-agent': UA, accept: 'application/json' },
+  });
+  if (!r.ok) {
+    const e = new Error(`registry listing returned HTTP ${r.status} on page ${page}`);
+    e.code = 3;
+    throw e;
+  }
+  return r.json();
+}
+
+export async function fetchDetail(qualifiedName, { fetchImpl = fetch, api = SMITHERY_API } = {}) {
+  const r = await fetchImpl(`${api}/servers/${encodeURIComponent(qualifiedName)}`, {
+    headers: { 'user-agent': UA, accept: 'application/json' },
+  });
+  if (!r.ok) return null;                 // one bad record must not stop a sweep
+  return r.json();
+}
+
+/** Servers already graded, so a sweep does not re-propose them. Free to read. */
+export async function alreadyGraded(feedApi, { fetchImpl = fetch } = {}) {
+  const known = new Set();
+  if (!feedApi) return known;
+  try {
+    const r = await fetchImpl(`${feedApi.replace(/\/+$/, '')}/feed?limit=200`, {
+      headers: { accept: 'application/json' },
+    });
+    if (!r.ok) return known;
+    const j = await r.json();
+    for (const c of j.candidates ?? []) {
+      known.add(String(c.server_url).toLowerCase());
+      if (c.server_name) known.add(String(c.server_name).toLowerCase());
+    }
+  } catch { /* a discovery run must not fail because the feed is down */ }
+  return known;
+}
+
+export async function discover({
+  pages = 1,
+  feedApi = null,
+  fetchImpl = fetch,
+  api = SMITHERY_API,
+  onProgress = () => {},
+} = {}) {
+  const known = await alreadyGraded(feedApi, { fetchImpl });
+  const rows = [];
+  let listed = 0;
+  let detailFailed = 0;
+  let totalCount = null;
+
+  for (let page = 1; page <= pages; page++) {
+    const j = await fetchPage(page, { fetchImpl, api });
+    totalCount = j.pagination?.totalCount ?? totalCount;
+    const servers = j.servers ?? [];
+    if (!servers.length) break;
+
+    for (const s of servers) {
+      listed++;
+      const detail = await fetchDetail(s.qualifiedName, { fetchImpl, api });
+      if (!detail) { detailFailed++; continue; }
+      const row = assess(s, detail);
+      row.already_graded = known.has(String(row.id).toLowerCase()) ||
+                           (row.name ? known.has(String(row.name).toLowerCase()) : false);
+      rows.push(row);
+      onProgress(listed, rows.length);
+    }
+    if (j.pagination && page >= (j.pagination.totalPages ?? page)) break;
+  }
+
+  const flagged = rows.filter((r) => r.scan.hard > 0 || r.scan.steering > 0);
+  return {
+    source: 'smithery',
+    swept_at: new Date().toISOString(),
+    registry_total: totalCount,
+    listed,
+    assessed: rows.length,
+    detail_fetch_failed: detailFailed,
+    // The numbers that decide whether this is worth a human's time.
+    with_gradeable_endpoint: rows.filter((r) => r.gradeable_endpoint).length,
+    already_graded: rows.filter((r) => r.already_graded).length,
+    flagged_by_scan: flagged.length,
+    hard_hits: rows.reduce((n, r) => n + r.scan.hard, 0),
+    steering_hits: rows.reduce((n, r) => n + r.scan.steering, 0),
+    registry_security_present: rows.filter((r) => r.registry_security != null).length,
+    candidates: rows,
+  };
+}
+
+export function writeCandidates(file, result) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(result, null, 2) + '\n', 'utf8');
+}
+
+export function renderDiscover(r, file) {
+  const out = [];
+  out.push(`doorman discover  ${r.source}`);
+  out.push(`  registry holds   ${r.registry_total ?? 'unknown'} servers`);
+  out.push(`  swept            ${r.listed} listed, ${r.assessed} assessed` +
+           (r.detail_fetch_failed ? `, ${r.detail_fetch_failed} detail fetches failed` : ''));
+  out.push('');
+  out.push(`  already graded by this scorecard   ${r.already_graded}`);
+  out.push(`  with a gradeable endpoint          ${r.with_gradeable_endpoint} of ${r.assessed}`);
+  out.push(`  registry security field populated  ${r.registry_security_present} of ${r.assessed}`);
+  out.push('');
+  out.push(`  NEEDS A HUMAN LOOK                 ${r.flagged_by_scan}` +
+           `   (${r.hard_hits} injection-shaped, ${r.steering_hits} commercial steering)`);
+  out.push('');
+  out.push('  These are candidates for review, NOT findings, and the difference');
+  out.push('  is not pedantry. The first sweep of 100 servers flagged fifteen');
+  out.push('  and TWO survived a hand check: a Slack parameter that posts a');
+  out.push('  reply to a conversation, an LLM testing tool whose job is to');
+  out.push('  accept a system prompt, "system:" as a docstring parameter name,');
+  out.push('  and five vendors saying "use this instead of" about another tool');
+  out.push('  in their OWN server. Five patterns were tightened on 2026-09-10');
+  out.push('  and the same sweep now flags those two and nothing else.');
+  out.push('');
+  out.push('  That is thirteen strings, not a directory. Zero false positives on');
+  out.push('  a corpus that small means the KNOWN failure modes are fixed, not');
+  out.push('  that the next hundred servers hold none. Read the excerpt before');
+  out.push('  repeating any of it. See test/discover-precision.test.mjs.');
+
+  const flagged = r.candidates.filter((c) => c.scan.hard || c.scan.steering)
+    .sort((a, b) => (b.use_count ?? 0) - (a.use_count ?? 0));
+  if (flagged.length) {
+    out.push('');
+    for (const c of flagged.slice(0, 12)) {
+      const marks = [c.scan.hard ? `${c.scan.hard} hard` : null,
+                     c.scan.steering ? `${c.scan.steering} steering` : null].filter(Boolean).join(', ');
+      out.push(`  ${c.verified ? '*' : ' '} ${String(c.use_count ?? 0).padStart(7)} uses  ${c.id}`);
+      out.push(`      ${marks}${c.tools ? `, ${c.tools} tools` : ''}`);
+      if (c.scan.failure_modes[0]) out.push(`      ${c.scan.failure_modes[0].slice(0, 118)}`);
+    }
+    if (flagged.length > 12) out.push(`  ... and ${flagged.length - 12} more in the file`);
+  }
+
+  out.push('');
+  out.push(`  written to ${file}`);
+  out.push('');
+  out.push('THIS IS A SCAN, NOT A GRADE. Nothing was driven and no letter was');
+  out.push('assigned. It reads the tool descriptions the registry itself');
+  out.push('publishes, which is the same surface an agent reads before deciding');
+  out.push('what to call. A grade needs the origin endpoint, and the registry');
+  out.push('returns only its own proxy, which answers 401 without its token.');
+  out.push('');
+  out.push('Nothing has been queued and nothing has been spent. Curate the file.');
+  return out.join('\n');
+}

package/doorman/cli/doctor.mjs

@@ -0,0 +1,282 @@
+/**
+ * `doorman doctor` — L0. What is actually in YOUR build.
+ *
+ * This is the layer that costs nobody anything. No model, no container, no
+ * network: it reads the project in front of it and reports what an agent in
+ * that project can currently reach.
+ *
+ * It exists because the question "is this tool worth adopting" has no universal
+ * answer. It depends on which harness you run, which model, which servers are
+ * already installed, and what your agents actually do. A benchmark run on
+ * somebody else's stack answers their question, not yours. So doorman looks at
+ * yours first, and every later layer is scoped to what it finds here.
+ *
+ * Everything below is read-only. It opens config files, never writes one, and
+ * never sends what it read anywhere.
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const read = async (p) => {
+  try { return await readFile(p, 'utf8'); } catch { return null; }
+};
+const readJson = async (p) => {
+  const t = await read(p);
+  if (t === null) return null;
+  try { return JSON.parse(t); } catch { return { __unparseable: true }; }
+};
+
+/**
+ * Which agent harness is this project set up for.
+ *
+ * Reported as evidence, not as a guess: each hit names the file that proved it,
+ * so a wrong answer can be argued with.
+ */
+async function detectHarness(root) {
+  const found = [];
+  const probe = async (rel, name, note) => {
+    if (existsSync(path.join(root, rel))) found.push({ harness: name, evidence: rel, note });
+  };
+  await probe('.claude', 'Claude Code', 'project-scoped agents, commands, hooks');
+  await probe('CLAUDE.md', 'Claude Code', 'project instructions');
+  await probe('AGENTS.md', 'Codex / AGENTS.md convention', 'project instructions');
+  await probe('.cursor', 'Cursor', 'editor-integrated agent');
+  await probe('.windsurf', 'Windsurf', 'editor-integrated agent');
+  await probe('.github/copilot-instructions.md', 'GitHub Copilot', 'repo instructions');
+  await probe('.gemini', 'Gemini CLI', 'project config');
+
+  // Deduplicate by harness, keeping every piece of evidence.
+  const byName = new Map();
+  for (const f of found) {
+    if (!byName.has(f.harness)) byName.set(f.harness, { harness: f.harness, evidence: [], note: f.note });
+    byName.get(f.harness).evidence.push(f.evidence);
+  }
+  return [...byName.values()];
+}
+
+/** Every MCP server this project can reach, and where that was declared. */
+async function detectMcpServers(root) {
+  const servers = [];
+  const sources = [
+    '.mcp.json',
+    '.claude/settings.json',
+    '.claude/settings.local.json',
+    '.cursor/mcp.json',
+    '.vscode/mcp.json',
+  ];
+  for (const rel of sources) {
+    const j = await readJson(path.join(root, rel));
+    if (!j) continue;
+    if (j.__unparseable) {
+      servers.push({ name: '(unreadable)', source: rel, transport: null, target: null,
+                     note: 'file exists but is not valid JSON' });
+      continue;
+    }
+    const block = j.mcpServers || j.servers || {};
+    for (const [name, cfg] of Object.entries(block)) {
+      servers.push({
+        name,
+        source: rel,
+        transport: cfg?.type || (cfg?.command ? 'stdio' : cfg?.url ? 'http' : 'unknown'),
+        target: cfg?.url || cfg?.command || null,
+        args: Array.isArray(cfg?.args) ? cfg.args.length : 0,
+      });
+    }
+  }
+  return servers;
+}
+
+/** Subagents, and which of them hold MCP tools. That ratio is the exposure. */
+async function detectAgents(root) {
+  const dir = path.join(root, '.claude', 'agents');
+  if (!existsSync(dir)) return { count: 0, withMcp: [], dir: null };
+  let files = [];
+  try { files = (await readdir(dir)).filter((f) => f.endsWith('.md')); } catch { return { count: 0, withMcp: [], dir }; }
+  const withMcp = [];
+  for (const f of files) {
+    const text = (await read(path.join(dir, f))) || '';
+    // Frontmatter `tools:` naming an mcp__ tool is the thing worth counting.
+    const hits = text.match(/mcp__[a-zA-Z0-9_-]+/g);
+    if (hits) withMcp.push({ agent: f.replace(/\.md$/, ''), tools: [...new Set(hits)].length });
+  }
+  return { count: files.length, withMcp, dir: path.join('.claude', 'agents') };
+}
+
+/**
+ * Is the doorman gate installed and wired, or installed and inert?
+ *
+ * THERE ARE TWO WAYS TO INSTALL IT NOW, and this used to see only one. The
+ * plugin route puts the gate in the plugin directory and wires it through the
+ * plugin's own hooks.json, so a plugin user got told "not installed" by the one
+ * command whose entire job is answering that question, while the gate was
+ * actively blocking their calls. Reporting a control as absent when it is
+ * running is the same failure class as reporting it present when it is not.
+ *
+ * Project install is still reported first, because it is the one the operator
+ * controls per project. The plugin is reported as a second, separate source.
+ */
+async function detectGate(root, { env = process.env } = {}) {
+  const hook = path.join(root, '.claude', 'hooks', 'mcp-gate.sh');
+  const installed = existsSync(hook);
+  const settings = await read(path.join(root, '.claude', 'settings.json'));
+  const wired = Boolean(settings && settings.includes('mcp-gate.sh'));
+  const registry = existsSync(path.join(root, 'registry', 'allowlist.json'));
+
+  // A user-scope plugin gates every project, so its absence from THIS project
+  // says nothing. Detected by looking for an installed plugin that ships the
+  // hook, not by asking the harness, so this stays offline and dependency-free.
+  const plugin = detectPluginGate(env);
+
+  const anyGate = installed || plugin.present;
+  return {
+    installed,
+    wired,
+    registry,
+    plugin,
+    // The distinction that matters: a gate that is present and not wired is a
+    // gate that is not running, and it looks exactly like one that is.
+    verdict: !anyGate ? 'not installed'
+      : !installed && plugin.present ? `installed as a PLUGIN (${plugin.name}), wired by the plugin`
+      : !wired ? 'INSTALLED BUT NOT RUNNING (no hook entry in settings.json)'
+      : !registry && !plugin.present ? 'wired, but no registry/allowlist.json: it will block everything'
+      : 'installed and wired',
+  };
+}
+
+/** An installed Claude Code plugin that ships mcp-gate.sh. Read-only. */
+function detectPluginGate(env) {
+  const home = env.USERPROFILE || env.HOME;
+  if (!home) return { present: false, why: 'no home directory in the environment' };
+  const record = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+  if (!existsSync(record)) return { present: false, why: 'no installed_plugins.json' };
+  let raw;
+  try { raw = JSON.parse(readFileSync(record, 'utf8')); } catch {
+    return { present: false, why: 'installed_plugins.json did not parse' };
+  }
+  // The shape of that file is the harness's business and it has changed before,
+  // so match on content rather than on a path into it.
+  const text = JSON.stringify(raw);
+  const named = /"(clembot-doorman[^"]*)"/.exec(text);
+  if (!named) return { present: false, why: 'no clembot-doorman plugin installed' };
+  return { present: true, name: named[1], record };
+}
+
+/** What an eval could drive. Presence only: nothing is executed. */
+async function detectAgentRunners(root) {
+  const out = [];
+  const pkg = await readJson(path.join(root, 'package.json'));
+  if (pkg && !pkg.__unparseable) {
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    for (const d of Object.keys(deps)) {
+      if (/claude|anthropic|openai|langchain|langgraph|crewai|agent/i.test(d)) {
+        out.push({ kind: 'dependency', name: d, version: deps[d] });
+      }
+    }
+  }
+  return out;
+}
+
+export async function doctor(root, opts = {}) {
+  const abs = path.resolve(root);
+  let ok = true;
+  try { ok = (await stat(abs)).isDirectory(); } catch { ok = false; }
+  if (!ok) return { ok: false, why: `not a directory: ${abs}` };
+
+  const [harnesses, servers, agents, gate, runners] = await Promise.all([
+    detectHarness(abs), detectMcpServers(abs), detectAgents(abs), detectGate(abs, opts), detectAgentRunners(abs),
+  ]);
+  return { ok: true, root: abs, harnesses, servers, agents, gate, runners };
+}
+
+export function renderDoctor(d) {
+  const L = [];
+  L.push(`# Your build`);
+  L.push('');
+  L.push(`\`${d.root}\``);
+  L.push('');
+  L.push('Read-only. Nothing here was executed, sent anywhere, or billed.');
+  L.push('');
+
+  L.push('## Harness');
+  L.push('');
+  if (!d.harnesses.length) {
+    L.push('None detected. doorman can still grade a server, but an eval needs an agent');
+    L.push('to drive, so `doorman eval --agent` would have to be told what to run.');
+  } else {
+    for (const h of d.harnesses) L.push(`- **${h.harness}** (${h.evidence.join(', ')})`);
+  }
+  L.push('');
+
+  L.push('## MCP servers this project can reach');
+  L.push('');
+  if (!d.servers.length) {
+    L.push('None declared. Nothing to grade yet, and nothing to gate.');
+  } else {
+    L.push('| Server | Transport | Declared in | Target |');
+    L.push('|---|---|---|---|');
+    for (const s of d.servers) {
+      L.push(`| \`${s.name}\` | ${s.transport ?? '?'} | \`${s.source}\` | ${s.target ? '`' + String(s.target).slice(0, 60) + '`' : '-'} |`);
+    }
+    L.push('');
+    L.push(`**${d.servers.length} server(s).** Each one describes its own tools to your`);
+    L.push('agent, and your agent reads those descriptions as instructions.');
+  }
+  L.push('');
+
+  L.push('## Agents');
+  L.push('');
+  if (!d.agents.count) {
+    L.push('No `.claude/agents/` directory.');
+  } else {
+    L.push(`**${d.agents.count} subagent(s)** in \`${d.agents.dir}\`.`);
+    if (d.agents.withMcp.length) {
+      L.push('');
+      for (const a of d.agents.withMcp) L.push(`- \`${a.agent}\` references ${a.tools} MCP tool name(s)`);
+      L.push('');
+      L.push('A tool handed to every agent costs every agent: each one carries');
+      L.push('descriptions it will mostly never call, plus that many more chances to');
+      L.push('pick the wrong one.');
+    } else {
+      L.push('None of them reference an MCP tool by name.');
+    }
+  }
+  L.push('');
+
+  L.push('## The gate');
+  L.push('');
+  L.push(`**${d.gate.verdict}**`);
+  L.push('');
+  L.push(`- hook present: ${d.gate.installed ? 'yes' : 'no'}`);
+  L.push(`- wired in settings.json: ${d.gate.wired ? 'yes' : 'no'}`);
+  L.push(`- registry present: ${d.gate.registry ? 'yes' : 'no'}`);
+  L.push(`- installed as a plugin: ${d.gate.plugin?.present ? `yes (${d.gate.plugin.name})` : 'no'}`);
+  if (d.gate.plugin?.present && !d.gate.installed) {
+    L.push('');
+    L.push('> The gate is running from a user-scope PLUGIN, so it applies to every');
+    L.push('> project on this machine, not just this one. The trust list it reads is');
+    L.push('> `$CLAUDE_PROJECT_DIR/registry/allowlist.json` if this project has one,');
+    L.push('> and the plugin default otherwise. `doorman install .` gives this project');
+    L.push('> its own list, which a plugin update can never overwrite.');
+  }
+  if (d.gate.installed && !d.gate.wired) {
+    L.push('');
+    L.push('> A gate that is installed and not wired is not running, and looks exactly');
+    L.push('> like one that is. Both are quiet.');
+  }
+  L.push('');
+
+  if (d.runners.length) {
+    L.push('## Agent-ish dependencies');
+    L.push('');
+    for (const r of d.runners) L.push(`- \`${r.name}\` ${r.version}`);
+    L.push('');
+  }
+
+  L.push('---');
+  L.push('');
+  L.push('_`doorman doctor`. Static, local, free. It reports what is here; it does not');
+  L.push('say whether any of it works. That is `doorman report` and `doorman eval`._');
+  return L.join('\n') + '\n';
+}