Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

68.5 KB
Raw Blame
/**
 * Harness-agnostic building blocks for the memory plugin doctor scripts.
 *
 * Each harness ships a thin `ov-memory-doctor.mjs` entrypoint that knows its
 * own install layout (where the plugin is registered, which hooks file, which
 * state directory) and delegates everything that is the same everywhere to
 * this module: config-file inspection, API key display, base URL linting,
 * environment sweep, server probes and their interpretation, state/log
 * inspection, and report rendering. `runDoctor(hostSpec)` owns the run itself:
 * the argument parsing, the section order, the `--json` envelope and the exit
 * code, calling back into the host for the sections only it can produce.
 *
 * Nothing here reads harness config; callers pass a resolved connection
 * `{ baseUrl, apiKey, account, user, peerId, userAgent }`.
 */

import { execFileSync } from "node:child_process";
import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join, resolve as resolvePath } from "node:path";

import { HARNESS_CONFIG_KEYS, HARNESS_KEYS, harnessKey, KNOB_BY_NAME, pluginConfigKeys } from "./config-schema.mjs";
import { buildOvHeaders } from "./ov-http.mjs";
import { resolveWorkspaceSettings } from "./plugin-config.mjs";
import { peerScopeMemoPath } from "./recall-core.mjs";
import { CONFIG_DIR_NAME, LOCAL_FILE, TEAM_FILE, workspaceConfigPaths } from "./workspace-config.mjs";
import { findWorkspaceRoot, resolveWorkspaceIdentity } from "./workspace-identity.mjs";
import { resolveEffectivePeerId } from "./workspace-peer.mjs";
import { entryPath } from "./workspace-registry.mjs";

/**
 * The snippet every surface quotes verbatim — this report, the docs and the
 * skills an agent reads — so whoever follows any of them writes the same file.
 * One line so it fits a table cell and a report line unchanged.
 */
export const WORKSPACE_PEER_HINT = '{"version": 1, "peer": {"id": "my-project"}}';

// ---------------------------------------------------------------------------
// Formatting helpers
// ---------------------------------------------------------------------------

export function homeShort(path) {
  const home = homedir();
  if (!path) return path;
  return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
}

export function fmtAge(ts) {
  if (!ts) return "never";
  const sec = Math.floor((Date.now() - ts) / 1000);
  if (sec < 0) return "just now";
  if (sec < 60) return `${sec}s ago`;
  if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
  if (sec < 86400) return `${Math.floor(sec / 3600)}h ago`;
  return `${Math.floor(sec / 86400)}d ago`;
}

export function fmtBytes(n) {
  if (n == null) return "?";
  if (n < 1024) return `${n} B`;
  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
  return `${(n / 1024 / 1024).toFixed(1)} MB`;
}

function str(value, fallback = "") {
  return typeof value === "string" && value.trim() ? value.trim() : fallback;
}

// ---------------------------------------------------------------------------
// Report
// ---------------------------------------------------------------------------

const LEVEL_ORDER = { fail: 0, warn: 1, info: 2, ok: 3 };
const LEVEL_MARK = { ok: "✓", info: "·", warn: "⚠", fail: "✗" };
const LEVEL_COLOR = { ok: "32", info: "2", warn: "33", fail: "31" };

export function createReport({ color = false } = {}) {
  const sections = [];
  let current = null;

  function paint(code, text) {
    return color ? `\x1b[${code}m${text}\x1b[0m` : text;
  }

  function section(title) {
    current = { title, findings: [] };
    sections.push(current);
    return current;
  }

  function add(level, title, detail, fix) {
    if (!current) section("General");
    const finding = { level, title };
    if (detail) finding.detail = String(detail);
    if (fix) finding.fix = String(fix);
    current.findings.push(finding);
    return finding;
  }

  const report = {
    sections,
    section,
    add,
    ok: (title, detail) => add("ok", title, detail),
    info: (title, detail) => add("info", title, detail),
    warn: (title, detail, fix) => add("warn", title, detail, fix),
    fail: (title, detail, fix) => add("fail", title, detail, fix),
    problems() {
      return sections.flatMap((s) => s.findings.filter((f) => f.level === "fail" || f.level === "warn"));
    },
    exitCode() {
      return sections.some((s) => s.findings.some((f) => f.level === "fail")) ? 1 : 0;
    },
    render() {
      const lines = [];
      for (const s of sections) {
        lines.push(paint("1", `== ${s.title} ==`));
        for (const f of s.findings) {
          lines.push(`  ${paint(LEVEL_COLOR[f.level], LEVEL_MARK[f.level])} ${f.title}`);
          if (f.detail) for (const l of String(f.detail).split("\n")) lines.push(`      ${l}`);
          if (f.fix && (f.level === "warn" || f.level === "fail")) lines.push(`      ${paint("36", "fix:")} ${f.fix}`);
        }
        lines.push("");
      }
      const problems = report.problems().sort((a, b) => LEVEL_ORDER[a.level] - LEVEL_ORDER[b.level]);
      lines.push(paint("1", "== Summary =="));
      if (!problems.length) {
        lines.push(`  ${paint("32", "✓")} no problems found`);
      } else {
        const fails = problems.filter((p) => p.level === "fail").length;
        lines.push(`  ${fails} failure(s), ${problems.length - fails} warning(s)`);
        for (const p of problems) {
          lines.push(`  ${paint(LEVEL_COLOR[p.level], LEVEL_MARK[p.level])} ${p.title}${p.fix ? ` → ${p.fix}` : ""}`);
        }
      }
      return lines.join("\n");
    },
    toJSON() {
      return { sections };
    },
  };
  return report;
}

// ---------------------------------------------------------------------------
// API key display
// ---------------------------------------------------------------------------

export function decodeBase64Url(segment) {
  if (typeof segment !== "string" || !segment || /[^A-Za-z0-9_-]/.test(segment)) return null;
  try {
    const padded = segment + "=".repeat((4 - (segment.length % 4)) % 4);
    const text = Buffer.from(padded, "base64url").toString("utf-8");
    // Reject decoded text that is not printable — a random string that happens
    // to be valid base64 decodes to binary garbage.
    if (!text || /[^\x20-\x7e]/.test(text)) return null;
    return text;
  } catch {
    return null;
  }
}

function headTail(value, keep = 4) {
  if (!value) return "";
  if (value.length <= keep * 2 + 2) return "*".repeat(Math.max(4, value.length));
  return `${value.slice(0, keep)}…${value.slice(-keep)}`;
}

/**
 * Describe an API key for display without revealing it.
 *
 *   three-segment key  →  account=<decoded> user=<decoded> secret=abcd…wxyz
 *   other shapes       →  abcd…wxyz (N chars, unsupported format)
 *
 * The three-segment format is base64url(account).base64url(user).base64url(secret);
 * the first two segments carry no secret and are decoded so the operator can see
 * which identity the key claims. Also reports shape problems that commonly come
 * from copy/paste mistakes.
 */
export function describeApiKey(rawKey) {
  const info = { present: false, format: "none", display: "(none)", account: "", user: "", length: 0, problems: [] };
  if (typeof rawKey !== "string" || !rawKey) return info;

  info.present = true;
  info.length = rawKey.length;
  if (rawKey !== rawKey.trim()) info.problems.push("has leading/trailing whitespace");
  if (/[\r\n]/.test(rawKey)) info.problems.push("contains a line break");
  if (/^["']|["']$/.test(rawKey.trim())) info.problems.push("wrapped in quotes");
  if (/^bearer\s+/i.test(rawKey.trim())) info.problems.push("starts with 'Bearer ' — store only the key itself");

  const key = rawKey.trim().replace(/^bearer\s+/i, "").replace(/^["']|["']$/g, "");
  const parts = key.split(".");
  if (parts.length === 3) {
    info.format = "v2";
    const account = decodeBase64Url(parts[0]);
    const user = decodeBase64Url(parts[1]);
    info.account = account || "";
    info.user = user || "";
    const accountText = account ?? `${headTail(parts[0])} (not base64url)`;
    const userText = user ?? `${headTail(parts[1])} (not base64url)`;
    if (account === null || user === null) info.problems.push("account/user segment is not decodable base64url — key may be truncated or mangled");
    if (!parts[2]) info.problems.push("secret segment is empty");
    info.display = `account=${accountText} user=${userText} secret=${headTail(parts[2])}`;
  } else {
    info.format = "unsupported";
    info.problems.push(`unsupported shape: ${parts.length} dot-separated segment(s); expected 3`);
    info.display = `${headTail(key)} (${key.length} chars, unsupported format)`;
  }
  return info;
}

/** Mask any secret-looking env value for display. */
export function maskSecret(value) {
  return headTail(String(value ?? ""), 4);
}

// ---------------------------------------------------------------------------
// Base URL lint
// ---------------------------------------------------------------------------

export function lintBaseUrl(url) {
  const problems = [];
  const value = String(url ?? "");
  if (!value.trim()) {
    problems.push({ level: "fail", message: "base URL is empty", fix: "set url in ovcli.conf or OPENVIKING_URL" });
    return problems;
  }
  if (value !== value.trim() || /\s/.test(value)) {
    problems.push({ level: "fail", message: "base URL contains whitespace", fix: "remove stray spaces/newlines around the url value" });
  }
  if (!/^https?:\/\//i.test(value.trim())) {
    problems.push({ level: "fail", message: "base URL has no http:// or https:// scheme — fetch() rejects it as 'Failed to parse URL'", fix: "prefix the url with http:// or https://" });
    return problems;
  }
  let parsed;
  try {
    parsed = new URL(value.trim());
  } catch {
    problems.push({ level: "fail", message: "base URL does not parse", fix: "check the url value for typos" });
    return problems;
  }
  const path = parsed.pathname.replace(/\/+$/, "");
  if (/\/api(\/v1)?$/i.test(path)) {
    problems.push({ level: "fail", message: `base URL ends with ${path} — every request becomes ${path}/api/v1/... and 404s`, fix: "drop the /api/v1 suffix; the plugin appends API paths itself" });
  }
  if (/\/mcp$/i.test(path)) {
    problems.push({ level: "fail", message: "base URL ends with /mcp — the plugin appends /mcp itself", fix: "use the server root URL, not the MCP endpoint" });
  }
  if (parsed.hostname === "0.0.0.0") {
    problems.push({ level: "warn", message: "host 0.0.0.0 is a bind address, not a destination", fix: "use 127.0.0.1 or the real hostname" });
  }
  if (parsed.search || parsed.hash) {
    problems.push({ level: "warn", message: "base URL carries a query string or fragment", fix: "remove everything after the path" });
  }
  return problems;
}

export function isLoopbackUrl(url) {
  try {
    const host = new URL(url).hostname;
    return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]";
  } catch {
    return false;
  }
}

// ---------------------------------------------------------------------------
// Files and environment
// ---------------------------------------------------------------------------

export function inspectJsonFile(path) {
  const out = { path, exists: false, ok: false, error: "", data: null, mode: "", size: 0, mtimeMs: 0 };
  if (!path) return out;
  let st;
  try {
    st = statSync(path);
  } catch {
    return out;
  }
  out.exists = true;
  out.size = st.size;
  out.mtimeMs = st.mtimeMs;
  out.mode = (st.mode & 0o777).toString(8);
  let raw;
  try {
    raw = readFileSync(path, "utf-8");
  } catch (err) {
    out.error = `unreadable: ${err?.message || err}`;
    return out;
  }
  try {
    out.data = JSON.parse(raw);
    out.ok = out.data !== null && typeof out.data === "object";
    if (!out.ok) out.error = "top level is not a JSON object";
  } catch (err) {
    out.error = `invalid JSON: ${err?.message || err}`;
  }
  return out;
}

const KNOWN_OVCLI_KEYS = new Set([
  "url", "api_key", "root_api_key", "account", "user", "account_id", "user_id",
  "actor_peer_id", "peer_id", "agent_id", "timeout", "output", "echo_command",
  "extra_headers", "gateway_token", "auth_mode", "ldap_username", "ldap_password", "plugin",
]);

/** Keys in ovcli.conf that neither the CLI nor the plugins read — usually typos. */
export function unknownOvcliKeys(data) {
  if (!data || typeof data !== "object") return [];
  return Object.keys(data).filter((k) => !KNOWN_OVCLI_KEYS.has(k));
}

/**
 * Every knob a harness loader reads out of `ovcli.conf`'s `plugin` section.
 *
 * `plugin` is on the allowlist above, which used to mean everything inside it
 * went unchecked — so `peerSorce` sat there doing nothing with no complaint.
 * The set is the schema's own key list, aliases included, so it cannot rot into
 * a list that rejects a real knob.
 */
export const KNOWN_PLUGIN_KEYS = pluginConfigKeys();

/** Nested objects in `plugin` are per-harness overrides, not knobs. */
const PLUGIN_HARNESS_KEYS = HARNESS_CONFIG_KEYS;

function nearestKnownKey(key) {
  // Levenshtein would be overkill; a typo that matters is almost always one
  // edit away, and case-folding alone catches the most common one.
  const folded = key.toLowerCase();
  for (const known of KNOWN_PLUGIN_KEYS) {
    if (known.toLowerCase() === folded) return known;
  }
  for (const known of KNOWN_PLUGIN_KEYS) {
    if (known.length >= 4 && (known.toLowerCase().startsWith(folded.slice(0, 5)) || folded.startsWith(known.toLowerCase().slice(0, 5)))) {
      return known;
    }
  }
  return "";
}

/**
 * Misspelled knobs inside `plugin`, and inside each per-harness override.
 * Each result carries the closest real key so the fix is one glance away.
 */
export function unknownPluginKeys(plugin) {
  if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) return [];
  const found = [];
  const walk = (object, prefix) => {
    for (const [key, value] of Object.entries(object)) {
      if (!prefix && PLUGIN_HARNESS_KEYS.has(key)) {
        if (value && typeof value === "object" && !Array.isArray(value)) walk(value, `${key}.`);
        continue;
      }
      if (KNOWN_PLUGIN_KEYS.has(key)) continue;
      found.push({ key: `plugin.${prefix}${key}`, suggestion: nearestKnownKey(key) });
    }
  };
  walk(plugin, "");
  return found;
}

const SECRET_ENV = /KEY|TOKEN|SECRET|PASSWORD/i;

export function collectEnv(env = process.env) {
  const openviking = [];
  for (const name of Object.keys(env).sort()) {
    if (!name.startsWith("OPENVIKING_")) continue;
    const value = env[name] ?? "";
    openviking.push({ name, value: SECRET_ENV.test(name) ? maskSecret(value) : value });
  }
  const proxy = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "all_proxy", "no_proxy"]
    .filter((name) => str(env[name]))
    .map((name) => ({ name, value: env[name] }));
  const node = ["NODE_EXTRA_CA_CERTS", "NODE_TLS_REJECT_UNAUTHORIZED", "NODE_USE_ENV_PROXY", "NODE_OPTIONS"]
    .filter((name) => str(env[name]))
    .map((name) => ({ name, value: env[name] }));
  return { openviking, proxy, node };
}

/** Legacy rc-file wrapper blocks written by pre-stdio-proxy installers. */
export function scanRcFiles(markers, home = homedir()) {
  const hits = [];
  for (const file of [".zshrc", ".bashrc", ".zprofile", ".bash_profile", ".profile"]) {
    const path = `${home}/${file}`;
    let text;
    try {
      text = readFileSync(path, "utf-8");
    } catch {
      continue;
    }
    for (const marker of markers) {
      if (text.includes(marker)) hits.push({ file: homeShort(path), kind: "block", detail: marker });
    }
    const exported = [...new Set([...text.matchAll(/^\s*export\s+(OPENVIKING_[A-Z0-9_]+)=/gm)].map((m) => m[1]))];
    if (exported.length) hits.push({ file: homeShort(path), kind: "export", detail: exported.join(", "), vars: exported });
  }
  return hits;
}

// ---------------------------------------------------------------------------
// Commands
// ---------------------------------------------------------------------------

export function runCommand(command, args = [], { timeoutMs = 10000, env = process.env } = {}) {
  try {
    const stdout = execFileSync(command, args, {
      encoding: "utf-8",
      timeout: timeoutMs,
      env,
      stdio: ["ignore", "pipe", "pipe"],
    });
    return { ok: true, stdout: String(stdout).trim(), stderr: "" };
  } catch (err) {
    return {
      ok: false,
      stdout: String(err?.stdout ?? "").trim(),
      stderr: String(err?.stderr ?? "").trim(),
      error: err?.code === "ENOENT" ? "not found" : (err?.killed ? `timed out after ${timeoutMs}ms` : (err?.message || String(err))),
    };
  }
}

export function whichCommand(name) {
  const result = runCommand(process.platform === "win32" ? "where" : "which", [name], { timeoutMs: 5000 });
  return result.ok ? result.stdout.split(/\r?\n/)[0] : "";
}

export function parseNodeMajor(version) {
  const m = /^v?(\d+)/.exec(String(version || ""));
  return m ? Number(m[1]) : NaN;
}

// ---------------------------------------------------------------------------
// HTTP probes
// ---------------------------------------------------------------------------

export function classifyFetchError(err) {
  const cause = err?.cause || err;
  const code = cause?.code || "";
  const message = String(cause?.message || err?.message || err || "");
  if (err?.name === "AbortError" || /aborted/i.test(message)) {
    return { kind: "timeout", hint: "no response within the timeout — wrong host/port, firewall, or a very slow server" };
  }
  if (code === "ECONNREFUSED") return { kind: "refused", hint: "connection refused — nothing is listening on that host:port (server down or wrong port)" };
  if (code === "ENOTFOUND" || code === "EAI_AGAIN") return { kind: "dns", hint: "hostname does not resolve — typo in the url, or DNS/VPN not available" };
  if (code === "ECONNRESET" || code === "EPIPE") return { kind: "reset", hint: "connection reset — a proxy or TLS terminator closed the connection" };
  if (/certificate|CERT_|SELF_SIGNED|UNABLE_TO_VERIFY|ssl|tls/i.test(`${code} ${message}`)) {
    return { kind: "tls", hint: "TLS verification failed — private CA or self-signed cert; Node ignores the OS keychain, set NODE_EXTRA_CA_CERTS for the harness process" };
  }
  if (/Failed to parse URL|Invalid URL/i.test(message)) return { kind: "url", hint: "the url does not parse — check scheme and host" };
  if (/wrong version number|EPROTO/i.test(`${code} ${message}`)) return { kind: "tls", hint: "protocol mismatch — https:// against a plain-HTTP port (or vice versa)" };
  return { kind: "other", hint: message };
}

export async function httpProbe({ url, method = "GET", headers = {}, body, timeoutMs = 5000 }) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  const t0 = Date.now();
  const out = { url, method, ok: false, status: 0, latencyMs: 0, text: "", json: null, headers: {}, error: "", errorKind: "", errorHint: "" };
  try {
    const res = await fetch(url, { method, headers, body, signal: controller.signal, redirect: "manual" });
    out.status = res.status;
    out.ok = res.ok;
    out.latencyMs = Date.now() - t0;
    for (const [k, v] of res.headers.entries()) out.headers[k.toLowerCase()] = v;
    const text = await res.text().catch(() => "");
    out.text = text.length > 4000 ? `${text.slice(0, 4000)}…` : text;
    const contentType = out.headers["content-type"] || "";
    if (contentType.includes("text/event-stream")) {
      // Streamable HTTP frames: take the first data: line.
      const line = text.split("\n").find((l) => l.startsWith("data:"));
      if (line) {
        try { out.json = JSON.parse(line.slice(5).trim()); } catch { /* keep text */ }
      }
    } else {
      try { out.json = JSON.parse(text); } catch { /* not JSON */ }
    }
  } catch (err) {
    out.latencyMs = Date.now() - t0;
    const cls = classifyFetchError(err);
    out.error = err?.cause?.message || err?.message || String(err);
    out.errorKind = cls.kind;
    out.errorHint = cls.hint;
  } finally {
    clearTimeout(timer);
  }
  return out;
}

// A connection record carries no `sendIdentityHeaders`: the doctor asks with
// the identity and reports whatever the server echoes back.
function authHeaders(conn, { identity = true } = {}) {
  return buildOvHeaders(conn, { actorPeerId: conn.peerId, identityHeaders: identity });
}

export function serverErrorMessage(probe) {
  const body = probe?.json;
  if (!body) return probe?.text ? probe.text.replace(/\s+/g, " ").slice(0, 200) : "";
  return body?.error?.message || body?.error?.code || body?.message || body?.detail || "";
}

/**
 * Run the standard probe ladder against an OpenViking server.
 *
 *   health        GET /health without credentials  — reachability, version, auth_mode
 *                 (401/403 where a gateway authenticates ahead of OpenViking)
 *   healthAuth    GET /health with credentials     — identity echo (account/user/role)
 *   systemStatus  GET /api/v1/system/status        — first authenticated call the hooks make; real 401/403
 *   fsLs          GET /api/v1/fs/ls?uri=viking://~/memories — tenant-data authorization + resolved user space
 *   mcp           POST /mcp tools/list             — what the MCP proxy forwards
 */
export async function probeOpenViking(conn, { timeoutMs = 5000, mcp = true } = {}) {
  const base = String(conn.baseUrl || "").replace(/\/+$/, "");
  const out = {};
  out.health = await httpProbe({ url: `${base}/health`, timeoutMs, headers: conn.userAgent ? { "User-Agent": conn.userAgent } : {} });
  if (out.health.error && out.health.errorKind !== "other") {
    // Hard network failure: the rest of the ladder would fail identically.
    return out;
  }
  if (conn.apiKey || conn.account || conn.user) {
    out.healthAuth = await httpProbe({ url: `${base}/health`, timeoutMs, headers: authHeaders(conn) });
  }
  out.systemStatus = await httpProbe({ url: `${base}/api/v1/system/status`, timeoutMs, headers: authHeaders(conn) });
  out.fsLs = await httpProbe({
    url: `${base}/api/v1/fs/ls?uri=${encodeURIComponent("viking://~/memories")}&output=original`,
    timeoutMs,
    headers: authHeaders(conn),
  });
  if (mcp) {
    out.mcp = await httpProbe({
      url: `${base}/mcp`,
      method: "POST",
      timeoutMs: Math.max(timeoutMs, 8000),
      headers: { ...authHeaders(conn), Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-06-18" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
    });
  }
  return out;
}

/**
 * The /health answer the rest of the report should read. A gateway that
 * authenticates ahead of OpenViking (Cloud behind the Volcengine gateway)
 * answers the credential-less probe with 401/403 before the request reaches
 * the server, so version, auth_mode and identity all come from the
 * authenticated probe instead.
 */
export function effectiveHealthProbe(probes) {
  const health = probes?.health;
  const authed = probes?.healthAuth;
  if (health && !health.error && (health.status === 401 || health.status === 403)
    && authed?.ok && isObject(authed.json)) return authed;
  return health;
}

/**
 * Turn probe results into findings. `keyInfo` is describeApiKey(conn.apiKey).
 * Returns { authMode, version, identity } for callers that want to cross-check.
 */
export function assessProbes(report, probes, conn, keyInfo) {
  const summary = { authMode: "", version: "", identity: null, reachable: false, authOk: false };
  let health = probes.health;
  if (!health) return summary;

  if (health.error) {
    report.fail(`server unreachable: ${conn.baseUrl}`, `${health.errorKind || "error"}: ${health.error}\n${health.errorHint}`,
      "check that the server is running and the url/port are right; compare with `curl -sS <url>/health`");
    return summary;
  }
  summary.reachable = true;
  if (health.status === 401 || health.status === 403) {
    // The url is fine: something in front of OpenViking demands credentials on
    // /health itself. Read it with the key and carry on down the ladder.
    const authed = probes.healthAuth;
    if (authed?.ok && isObject(authed.json)) {
      report.info(`/health is authenticated at this deployment — without a key it answers ${health.status}, so the report reads it with the api key`);
      health = authed;
    } else if (!conn.apiKey && !conn.account && !conn.user) {
      report.fail(`GET /health → ${health.status} and no credentials are configured`, serverErrorMessage(health),
        "this deployment authenticates /health itself (OpenViking Cloud does); set api_key in ~/.openviking/ovcli.conf or OPENVIKING_API_KEY");
      return summary;
    } else {
      report.fail(`api key rejected on /health → ${authed?.status || health.status}`,
        `${serverErrorMessage(authed) || serverErrorMessage(health) || "(no message)"} — key ${keyInfo?.display || "?"}`,
        "this deployment authenticates /health itself and rejected this key; check it against the key issued for this deployment (OpenViking Cloud keys come from the Volcengine console)");
      return summary;
    }
  }
  if (health.status === 404) {
    report.fail(`GET /health → 404 at ${conn.baseUrl}`, "the url points at a web server, but not at an OpenViking API root",
      "check for a missing path prefix (OpenViking Cloud needs /openviking) or a reverse proxy that does not forward /health");
    return summary;
  }
  if (health.status >= 300 && health.status < 400) {
    report.fail(`GET /health → ${health.status} redirect`, `location: ${health.headers.location || "?"}`,
      "the url is being redirected (http→https, or an SSO/login gateway); use the final url");
    return summary;
  }
  if (health.status === 503 && health.json?.status === "pending_initialization") {
    const fixes = Array.isArray(health.json.fix) ? health.json.fix.map((f) => `- ${f}`).join("\n") : "";
    report.fail("the OpenViking docker container is up but has no ov.conf — every request answers 503 until it does",
      `${health.json.error || ""}${health.json.config_file ? ` (expected at ${health.json.config_file} inside the container)` : ""}${fixes ? `\n${fixes}` : ""}`,
      "mount ~/.openviking (holding ov.conf) at /app/.openviking, or run `docker exec -it openviking openviking-server init`");
    return summary;
  }
  if (!health.ok || !health.json) {
    report.fail(`GET /health → ${health.status}`, serverErrorMessage(health) || "(non-JSON body)",
      "the server answered but not like OpenViking — verify the url reaches the OpenViking API, not a proxy error page");
    return summary;
  }
  summary.authMode = String(health.json.auth_mode || "");
  summary.version = String(health.json.version || "");
  report.ok(`server reachable — ${health.latencyMs}ms, version ${summary.version || "?"}, auth_mode=${summary.authMode || "?"}`);
  if (health.latencyMs > 1000) {
    report.warn(`/health took ${health.latencyMs}ms`, "the statusline probe has a 1s budget and will flap between 'slow' and 'offline'",
      "check network latency to the server; raise OPENVIKING_TIMEOUT_MS if hooks time out");
  }

  const identity = probes.healthAuth?.json;
  if (identity && identity.role) {
    summary.identity = { account: identity.account_id, user: identity.user_id, role: identity.role };
    summary.authOk = true;
    report.ok(`credentials accepted — account=${identity.account_id} user=${identity.user_id} role=${identity.role}`);
    if (identity.role === "root") {
      report.warn("using the ROOT api key", "root keys are rejected on tenant-data APIs and /mcp in api_key mode (403 'ROOT API keys cannot access tenant-scoped data APIs')",
        "create a user key (POST /api/v1/admin/accounts/<account>/users with the root key) and put that in ovcli.conf");
    }
    if (summary.authMode === "api_key" && keyInfo?.format === "v2") {
      if (keyInfo.account && keyInfo.account !== identity.account_id) {
        report.warn(`key claims account=${keyInfo.account} but server resolved account=${identity.account_id}`);
      }
    }
    if (summary.authMode === "api_key" && (conn.account || conn.user)) {
      const mismatch = (conn.account && conn.account !== identity.account_id) || (conn.user && conn.user !== identity.user_id);
      if (mismatch) {
        report.warn(`configured account/user (${conn.account || "-"}/${conn.user || "-"}) differ from the key's identity (${identity.account_id}/${identity.user_id})`,
          "in api_key mode the server ignores X-OpenViking-Account/User headers; the key decides where data lands",
          "remove account/user from the config, or use a key issued for that account/user");
      } else {
        report.info("account/user in config are redundant in api_key mode (identity comes from the key)");
      }
    }
  } else if (summary.authMode === "dev") {
    summary.authOk = true;
    report.info("server runs in dev auth mode — any key is accepted; identity comes from X-OpenViking-Account/User headers (default 'default')");
    if (identity?.account_id) summary.identity = { account: identity.account_id, user: identity.user_id, role: identity.role };
  } else if (conn.apiKey) {
    report.fail("api key rejected", `/health answered 200 but returned no identity for the key (${keyInfo?.display || "?"}) — the key is invalid, revoked, or belongs to another deployment`,
      "check the key in ovcli.conf / OPENVIKING_API_KEY against the one issued by the server admin");
  } else if (summary.authMode === "api_key") {
    report.fail("no api key configured but the server requires one (auth_mode=api_key)", "",
      "set api_key in ~/.openviking/ovcli.conf or OPENVIKING_API_KEY");
  } else if (summary.authMode === "trusted") {
    if (!conn.account || !conn.user) {
      report.fail("server is in trusted mode and needs account + user", "requests without X-OpenViking-Account/User are rejected with HTTP 400",
        "set account and user in ovcli.conf (or OPENVIKING_ACCOUNT / OPENVIKING_USER)");
    } else {
      summary.authOk = true;
      report.ok(`trusted mode — identity from headers account=${conn.account} user=${conn.user}`);
    }
  }

  const status = probes.systemStatus;
  if (status) {
    if (status.ok) {
      const user = status.json?.result?.user;
      report.ok(`GET /api/v1/system/status → 200${user ? ` (user space: ${user})` : ""}`);
    } else if (status.error) {
      report.fail("GET /api/v1/system/status failed", `${status.errorKind}: ${status.error}`);
    } else {
      const msg = serverErrorMessage(status);
      const level = status.status === 401 || status.status === 403 ? "fail" : "warn";
      report[level](`GET /api/v1/system/status → ${status.status}`, msg,
        status.status === 401 ? "the server rejected the credentials — this is what every hook hits after the /health gate passes"
          : status.status === 403 ? "the key is valid but not allowed here — wrong role or root key" : "");
    }
  }

  const fs = probes.fsLs;
  if (fs) {
    if (fs.ok) {
      const first = Array.isArray(fs.json?.result) ? fs.json.result.find((e) => e?.uri) : null;
      const space = first?.uri ? String(first.uri).replace(/\/memories\/.*$/, "/memories") : "";
      report.ok(`GET /api/v1/fs/ls viking://~/memories → 200${space ? ` (${space})` : ""}`);
    } else if (!fs.error) {
      const msg = serverErrorMessage(fs);
      if (fs.status === 403 && /ROOT/i.test(msg)) {
        report.fail("tenant data API rejects this key (root key)", msg, "use a user/admin key, not server.root_api_key");
      } else if (fs.status === 400) {
        report.warn(`GET /api/v1/fs/ls viking://~/memories → 400`, msg,
          /Trusted mode/i.test(msg) ? "set account/user for trusted mode" : "the server may be too old for the viking://~ home alias — upgrade the server");
      } else if (fs.status === 404) {
        report.info("viking://~/memories does not exist yet (nothing captured for this user so far)");
      } else if (fs.status !== 401) {
        report.warn(`GET /api/v1/fs/ls viking://~/memories → ${fs.status}`, msg);
      }
    }
  }

  const mcp = probes.mcp;
  if (mcp) {
    if (mcp.ok && mcp.json?.result?.tools) {
      report.ok(`POST /mcp tools/list → ${mcp.json.result.tools.length} tools`);
    } else if (mcp.error) {
      report.fail("POST /mcp failed", `${mcp.errorKind}: ${mcp.error}`);
    } else {
      const msg = serverErrorMessage(mcp) || mcp.text.replace(/\s+/g, " ").slice(0, 160);
      const hints = {
        401: "credentials rejected on /mcp",
        403: "key valid but not allowed on /mcp (root key in api_key mode)",
        404: "no MCP endpoint at <url>/mcp — missing path prefix, old server, or a reverse proxy that does not forward /mcp",
        406: "server did not accept the Accept header — something between client and server rewrites headers",
        502: "reverse proxy cannot reach the upstream",
        504: "reverse proxy timed out (SSE needs proxy_buffering off)",
      };
      report.fail(`POST /mcp tools/list → ${mcp.status}`, msg, hints[mcp.status] || "");
    }
  }
  return summary;
}

// ---------------------------------------------------------------------------
// State and logs
// ---------------------------------------------------------------------------

export function readStateFiles(stateDir, names) {
  const out = {};
  for (const name of names) {
    const path = `${stateDir}/${name}`;
    const entry = { path, exists: false, ageMs: null, data: null, error: "" };
    try {
      const st = statSync(path);
      entry.exists = true;
      entry.mtimeMs = st.mtimeMs;
      const data = JSON.parse(readFileSync(path, "utf-8"));
      entry.data = data;
      entry.ageMs = typeof data?.ts === "number" ? Date.now() - data.ts : Date.now() - st.mtimeMs;
    } catch (err) {
      if (entry.exists) entry.error = err?.message || String(err);
    }
    out[name] = entry;
  }
  return out;
}

/**
 * `peer_scope: "actor"` narrows recall to this workspace's own peer. A server
 * that predates the field rejects it, and the plugin retries without it — so
 * recall quietly runs against every peer under the user instead. `postRecall`
 * records that in a state file; without this the widening is invisible.
 */
export function lintPeerScopeDowngrade(path = peerScopeMemoPath(), now = Date.now()) {
  let data;
  try {
    data = JSON.parse(readFileSync(path, "utf-8"));
  } catch {
    return [];
  }
  if (!data?.legacyUntil || Number(data.legacyUntil) <= now) return [];
  return [{
    level: "warn",
    message: `recall peer_scope "${str(data.scope, "actor")}" was rejected by the server (HTTP ${Number(data.status) || 0})`,
    detail: "recall runs against every peer under this user, not just this workspace's",
    fix: 'upgrade the OpenViking server, or set recallPeerScope to "all" so the wider search is deliberate',
  }];
}

/**
 * `.openviking/` is also the parser's scratch directory, and the reflex is to
 * ignore the whole thing — which silently stops a team's `config.json` from
 * ever being committed. Catch the bare rule; narrower ones are fine.
 */
export function gitignoreHidesWorkspaceConfig(root) {
  for (const name of [".gitignore", join(".git", "info", "exclude")]) {
    let text;
    try {
      text = readFileSync(join(root, name), "utf-8");
    } catch {
      continue;
    }
    for (const line of text.split("\n")) {
      const rule = line.trim().replace(/\/$/, "");
      if (rule === CONFIG_DIR_NAME || rule === `/${CONFIG_DIR_NAME}` || rule === `**/${CONFIG_DIR_NAME}`) {
        return name;
      }
    }
  }
  return "";
}

/**
 * Where every workspace-scoped setting came from, and what it covered up.
 *
 * Three languages read this configuration and each could drift; per-key
 * provenance is how a user finds out which layer actually won, the way
 * `git config --show-origin --show-scope` does.
 */
export function checkWorkspace(report, { cwd = process.cwd(), env = process.env, clientVersion = "" } = {}) {
  report.section("Workspace");

  const { root, rootKind, git } = findWorkspaceRoot(cwd, env);
  const summary = { root, rootKind, kind: git?.kind || "", files: [], settings: {}, provenance: {} };
  if (!root) {
    report.info(`not a workspace: ${homeShort(cwd)} is in no git repository and has no ${CONFIG_DIR_NAME}/${TEAM_FILE} above it`);
    report.info("memories here carry no workspace peer and go to your user-level space; ovcli.conf and env still apply");
    report.info(`to give this directory its own memory, create ${CONFIG_DIR_NAME}/${TEAM_FILE} here with ${WORKSPACE_PEER_HINT}`);
    return summary;
  }
  const foundBy = rootKind === "git" ? git.kind : `${TEAM_FILE}${git ? ` inside ${git.kind}` : ""}`;
  report.ok(`workspace  ${homeShort(root)}  ← ${foundBy}`);

  const resolved = resolveWorkspaceSettings(cwd, env, { clientVersion });
  summary.settings = resolved.settings;
  summary.provenance = resolved.provenance;
  const identity = resolveWorkspaceIdentity({ cwd, env });
  const registryPath = entryPath(root, env, identity);

  for (const { layer, path } of [
    ...workspaceConfigPaths(root),
    { layer: "registry", path: registryPath },
  ]) {
    const info = fileInfo(path);
    summary.files.push({ layer, path, exists: info.exists });
    report.info(`${layer.padEnd(26)} ${homeShort(path)}${info.exists ? "" : "  (absent)"}`);
  }

  const keys = Object.keys(resolved.provenance || {}).sort();
  if (!keys.length) {
    report.info("no workspace layer sets anything — every value comes from ovcli.conf, ov.conf or the environment");
  }
  for (const key of keys) {
    const entry = resolved.provenance[key];
    const shadowed = entry.shadowed.map((s) => `${JSON.stringify(s.value)} from ${s.source}`).join(", ");
    report.info(
      `${key} = ${JSON.stringify(entry.value)}  ← ${entry.source}`,
      shadowed ? `shadows ${shadowed}` : "",
    );
  }

  for (const warning of resolved.warnings || []) report.warn(warning);
  for (const { key, value, source } of resolved.announced || []) {
    report.warn(
      `${source} sets ${key} = ${JSON.stringify(value)}`,
      "a committed workspace file is trusted without a prompt, so what it changes is announced",
      `override it in ${LOCAL_FILE} or in ${homeShort(registryPath)}`,
    );
  }

  const ignoredBy = gitignoreHidesWorkspaceConfig(root);
  if (ignoredBy) {
    report.warn(
      `${ignoredBy} ignores all of ${CONFIG_DIR_NAME}/`,
      `${TEAM_FILE} is meant to be committed; the blanket rule stops it from ever being added`,
      `narrow the rule to ${CONFIG_DIR_NAME}/media/ and ${CONFIG_DIR_NAME}/downloads/, and ignore ${CONFIG_DIR_NAME}/${LOCAL_FILE}`,
    );
  }
  return summary;
}

export function countDirEntries(dir, filter = () => true) {
  try {
    return readdirSync(dir).filter(filter).length;
  } catch {
    return null;
  }
}

export function fileInfo(path) {
  try {
    const st = statSync(path);
    return { exists: true, size: st.size, mtimeMs: st.mtimeMs };
  } catch {
    return { exists: false, size: 0, mtimeMs: 0 };
  }
}

/**
 * Scan a JSONL hook log. Returns the last `maxErrors` error entries, the last
 * mcp-proxy start record, and which hooks have written anything.
 */
export function scanDebugLog(path, { maxErrors = 5, maxBytes = 512 * 1024 } = {}) {
  const out = { path, exists: false, size: 0, mtimeMs: 0, lines: 0, errors: [], proxyStart: null, hooks: [] };
  const info = fileInfo(path);
  if (!info.exists) return out;
  Object.assign(out, { exists: true, size: info.size, mtimeMs: info.mtimeMs });
  let text;
  try {
    text = readFileSync(path, "utf-8");
  } catch {
    return out;
  }
  if (text.length > maxBytes) text = text.slice(-maxBytes);
  const hooks = new Set();
  const errors = [];
  for (const line of text.split("\n")) {
    if (!line.trim()) continue;
    out.lines += 1;
    let entry;
    try {
      entry = JSON.parse(line);
    } catch {
      continue;
    }
    if (entry.hook) hooks.add(entry.hook);
    if (entry.hook === "mcp-proxy" && entry.stage === "start") out.proxyStart = entry;
    if (entry.error) {
      errors.push({ ts: entry.ts, hook: entry.hook, stage: entry.stage, message: entry.error?.message || String(entry.error) });
    }
  }
  // Only errors from the last day of logging are "recent"; older ones are
  // history that predates whatever the user is debugging now.
  const cutoff = out.mtimeMs - 24 * 60 * 60 * 1000;
  out.errors = errors.slice(-maxErrors);
  out.recentErrors = errors.filter((e) => Date.parse(e.ts || "") >= cutoff).slice(-maxErrors);
  out.hooks = [...hooks].sort();
  return out;
}

export function existsPath(path) {
  return Boolean(path) && existsSync(path);
}

// ---------------------------------------------------------------------------
// Server health
//
// `GET /ready` is the server's own verdict on its subsystems and works
// against any deployment. The port and ov.conf checks only apply when the
// server runs on this machine (loopback url). Everything else server-side —
// config validation, live embedding probe, native engine, disk — is
// `openviking-server doctor`, which runs in the server's Python environment.
// ---------------------------------------------------------------------------

// Every harness reads the ov.conf section named after it, so every one of
// those names is a block a user may have written and the server refuses.
const PLUGIN_ONLY_OV_CONF_KEYS = Object.fromEntries(
  Object.values(HARNESS_KEYS)
    .filter((key) => key !== "openclaw")
    .map((key) => [key, `ovcli.conf plugin.${key}`]),
);
const READY_OK_VALUES = new Set(["ok", "not_configured", "not_supported"]);
const READY_FIXES = {
  embedding: "the server cannot embed with the configured provider — check embedding.dense.{provider,model,api_key,api_base} in ov.conf; `openviking-server doctor` shows the provider's reply",
  vectordb: "the vector index is unhealthy — check <storage.workspace>/vectordb and the server log; stop duplicate servers on the same workspace",
  agfs: "the content filesystem failed — check <storage.workspace>/viking, free disk space and the server log",
  api_key_manager: "the api key store failed to load — check <storage.workspace>/viking/_system and the server log",
  ollama: "start Ollama (or fix its host/port in ov.conf) — the server cannot reach it",
};

function isObject(v) {
  return Boolean(v) && typeof v === "object" && !Array.isArray(v);
}

/**
 * ov.conf keys that only the plugins read. The server validates its config
 * strictly and refuses to start on them, which shows up as "the server is
 * gone since I edited ov.conf". Returns [{ level, message, detail, fix }].
 */
export function lintServerConf(data) {
  const out = [];
  if (!isObject(data)) return out;
  for (const [key, dest] of Object.entries(PLUGIN_ONLY_OV_CONF_KEYS)) {
    if (!(key in data)) continue;
    out.push({
      level: "warn",
      message: `ov.conf has a top-level '${key}' block, which the server rejects at startup ("Unknown config field '${key}'")`,
      detail: "the plugin reads it, openviking-server does not; a server that is already running is unaffected until its next restart",
      fix: `move those settings to ${dest} (or OPENVIKING_* env) and delete the block; if this ov.conf never starts a server, ignore`,
    });
  }
  if (isObject(data.server) && "url" in data.server) {
    out.push({
      level: "warn",
      message: "ov.conf server.url is rejected by the server at startup (\"Extra inputs are not permitted\")",
      detail: "only the plugin and the CLI read server.url; the server validates its section strictly",
      fix: "put the url in ovcli.conf (url) and remove server.url; if this ov.conf never starts a server, ignore",
    });
  }
  return out;
}

/** Who listens on a TCP port (lsof on macOS/Linux, ss on Linux). */
export function findPortListener(port) {
  const out = { tool: "", pid: null, command: "", error: "" };
  if (process.platform === "win32") {
    out.error = "not supported on Windows";
    return out;
  }
  if (whichCommand("lsof")) {
    out.tool = "lsof";
    const r = runCommand("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-F", "pc"], { timeoutMs: 8000 });
    for (const line of r.stdout.split("\n")) {
      if (line.startsWith("p") && out.pid === null) out.pid = Number(line.slice(1));
      else if (line.startsWith("c") && !out.command) out.command = line.slice(1);
    }
    return out;
  }
  if (whichCommand("ss")) {
    out.tool = "ss";
    const r = runCommand("ss", ["-ltnpH", `sport = :${port}`], { timeoutMs: 8000 });
    const m = r.stdout.match(/users:\(\("([^"]+)",pid=(\d+)/);
    if (m) {
      out.command = m[1];
      out.pid = Number(m[2]);
    } else if (r.stdout.trim()) {
      out.command = "(owner not visible without root)";
    }
    return out;
  }
  out.error = "neither lsof nor ss is available";
  return out;
}

/**
 * `GET /ready`. `conn` is sent when there is one: deployments that gate
 * /health gate /ready the same way, and a self-hosted server ignores the
 * header.
 */
export async function probeReady(baseUrl, { timeoutMs = 15000, conn = null } = {}) {
  const base = String(baseUrl || "").replace(/\/+$/, "");
  return httpProbe({ url: `${base}/ready`, timeoutMs: Math.max(timeoutMs, 15000), headers: conn ? authHeaders(conn) : {} });
}

/** Flatten one `/ready` check (string or {status, checks}) into { ok, text }. */
export function readyCheckState(value) {
  if (isObject(value)) {
    const status = String(value.status ?? "");
    const nested = isObject(value.checks) ? Object.entries(value.checks).map(([k, v]) => [k, readyCheckState(v)]) : [];
    const failed = nested.filter(([, s]) => !s.ok);
    return {
      ok: READY_OK_VALUES.has(status) && failed.length === 0,
      text: failed.length ? `${status} (${failed.map(([k, s]) => `${k}: ${s.text}`).join(", ")})` : status,
    };
  }
  const text = String(value ?? "");
  return { ok: READY_OK_VALUES.has(text), text };
}

/** Turn the `/ready` probe into findings. Returns { ready, checks } (ready null when unknown). */
export function assessReady(report, probe) {
  const out = { ready: null, checks: {} };
  if (!probe) return out;
  if (probe.error) {
    if (probe.errorKind === "timeout") report.warn(`GET /ready timed out after ${probe.latencyMs}ms`, "the readiness check embeds one token with the configured provider (10s cap) — a timeout usually means that provider hangs", "run `openviking-server doctor` in the server's environment to see the provider's reply");
    else report.info(`GET /ready failed: ${probe.error}`);
    return out;
  }
  if (probe.status === 404) {
    report.info("server has no /ready endpoint (older version) — subsystem status unavailable over HTTP", "`openviking-server doctor` in the server's environment covers embedding/VLM/storage");
    return out;
  }
  const json = probe.json;
  if (!isObject(json)) {
    report.info(`GET /ready → ${probe.status} without a JSON body`);
    return out;
  }
  if (probe.status === 503 && json.status === "not_ready" && json.reason === "initializing" && !isObject(json.checks)) {
    out.ready = false;
    report.warn("server is still initializing (503 /ready)", "storage and the embedder are being set up; the first start of a local embedding model downloads it", "wait and rerun; if it never finishes, read the server log");
    return out;
  }
  if (!isObject(json.checks)) {
    report.info(`GET /ready → ${probe.status}: ${JSON.stringify(json).slice(0, 200)}`);
    return out;
  }
  const states = Object.entries(json.checks).map(([k, v]) => [k, readyCheckState(v)]);
  out.checks = Object.fromEntries(states.map(([k, s]) => [k, s.text]));
  const failed = states.filter(([, s]) => !s.ok);
  out.ready = failed.length === 0 && probe.ok;
  const summary = states.map(([k, s]) => `${k} ${s.text}`).join(", ");
  if (out.ready) {
    report.ok(`/ready: ${summary}`);
  } else {
    for (const [key, s] of failed) report.fail(`/ready: ${key} → ${s.text}`, "", READY_FIXES[key] || "see the server log");
    if (!failed.length) report.warn(`/ready → ${probe.status}: ${summary}`, "", "read the server log");
  }
  return out;
}

function urlHostPort(baseUrl) {
  try {
    const u = new URL(baseUrl);
    return { host: u.host, port: Number(u.port || (u.protocol === "https:" ? 443 : 80)) };
  } catch {
    return null;
  }
}

/**
 * The "Server health" section. `health` is the /health probe already taken
 * for the Connection section (effectiveHealthProbe, so a gateway that gates
 * /health does not read as "the server never answered"); `conn` carries the
 * credentials /ready may also need; `ovConf` is inspectJsonFile(<ov.conf path>).
 */
export async function checkServerHealth(report, { baseUrl, ovConf, health, conn = null, offline = false, timeoutMs = 5000 } = {}) {
  report.section("Server health");
  const answered = Boolean(health && !health.error && health.ok && isObject(health.json));
  const summary = { local: isLoopbackUrl(baseUrl), reachable: answered, ready: null, listener: null };
  const target = urlHostPort(baseUrl);

  if (!summary.local) {
    report.info(`server at ${target?.host || baseUrl} is not on this machine — only /ready is probed; \`openviking-server doctor\` on the server host covers the rest`);
  } else {
    if (ovConf?.ok) {
      for (const f of lintServerConf(ovConf.data)) report[f.level](f.message, f.detail, f.fix);
    }
    const listener = findPortListener(target.port);
    if (listener.pid) {
      summary.listener = { pid: listener.pid, command: listener.command };
      report.info(`port ${target.port} is served by pid ${listener.pid} (${listener.command})`);
    } else if (listener.error) {
      report.info(`could not determine who listens on port ${target.port} (${listener.error})`);
    } else if (!answered) {
      report.fail(`nothing listens on port ${target.port} — the server is not running`, "",
        "start it: `openviking-server` (first time: `openviking-server init`), or `docker start openviking` for a container install; a startup error is printed right there");
    }
    report.info("provider-level checks (embedding probe, VLM key, native engine, disk): `openviking-server doctor` in the server's own environment");
  }

  if (offline) report.info("skipped /ready (--offline)");
  else if (health?.json?.status === "pending_initialization") report.info("skipped /ready — the container has no config yet");
  else if (!answered) report.info("skipped /ready — the server did not answer /health");
  else summary.ready = assessReady(report, await probeReady(baseUrl, { timeoutMs, conn })).ready;
  return summary;
}

// ---------------------------------------------------------------------------
// Configuration segments
//
// The "Configuration" section is host-composed: these are the parts every
// harness reports identically, called in order, with the host slotting its own
// lines in between (Claude Code's enable verdict, Codex's credential-source
// block). Each segment takes the harness spec `runDoctor` already carries.
// ---------------------------------------------------------------------------

/** ovcli.conf and ov.conf: where they are, whether they parse, what sits in them. */
export function inspectConfigFiles(report, { harness = "", launcherHint = "this harness" } = {}) {
  const key = harnessKey(harness);
  const cliConf = inspectJsonFile(expandHome(process.env.OPENVIKING_CLI_CONFIG_FILE || join(homedir(), ".openviking", "ovcli.conf")));
  const ovConf = inspectJsonFile(expandHome(process.env.OPENVIKING_CONFIG_FILE || join(homedir(), ".openviking", "ov.conf")));

  for (const [label, conf] of [["ovcli.conf", cliConf], ["ov.conf", ovConf]]) {
    if (!conf.exists) {
      report.info(`${label}: ${homeShort(conf.path)} not present`);
      continue;
    }
    if (!conf.ok) {
      report.fail(`${label} cannot be parsed — the plugin treats it as absent`, `${homeShort(conf.path)}: ${conf.error}`, "fix the JSON (a trailing comma or comment is enough to break it)");
      continue;
    }
    report.ok(`${label}: ${homeShort(conf.path)} (mode ${conf.mode}, ${fmtBytes(conf.size)})`);
    if (label === "ov.conf") {
      if (key && conf.data[key]) report.info(`ov.conf has a legacy ${key} block (still honoured; prefer ovcli.conf plugin.${key} or env vars)`);
      continue;
    }
    if (conf.mode !== "600" && conf.mode !== "400") report.warn("ovcli.conf is not private", `mode ${conf.mode}; it holds the api key`, `chmod 600 ${homeShort(conf.path)}`);
    const unknown = unknownOvcliKeys(conf.data);
    if (unknown.length) report.warn("ovcli.conf has keys nobody reads", unknown.join(", "), "typos such as apiKey/base_url/token are silently ignored — use url, api_key, account, user");
    // `plugin` is on the ovcli allowlist, so nothing inside it is checked
    // there — a misspelled knob would just sit doing nothing.
    for (const { key: knob, suggestion } of unknownPluginKeys(conf.data.plugin)) {
      report.warn(`ovcli.conf ${knob} is not a knob any plugin reads`, "", suggestion ? `did you mean ${suggestion}?` : "remove it, or check the plugin README for the knob you meant");
    }
    if (conf.data.extra_headers && Object.keys(conf.data.extra_headers).some((h) => /^x-api-key$/i.test(h))) {
      report.warn("ovcli.conf extra_headers sets X-API-Key", "the server prefers X-API-Key over Authorization: Bearer, so it shadows api_key");
    }
    const sections = Object.keys(conf.data.plugin || {}).filter((k) => HARNESS_CONFIG_KEYS.has(k));
    const others = sections.filter((k) => harnessKey(k) !== key);
    if (key && others.length && !sections.some((k) => harnessKey(k) === key)) {
      report.info(`ovcli.conf ${others.map((k) => `plugin.${k}`).join(", ")} settings do not apply to ${launcherHint} (use plugin.${key})`);
    }
  }
  return { cliConf, ovConf };
}

/**
 * Where each resolved credential came from, as one label per field.
 *
 * The key's layer is not re-derived here: `buildPluginConfig` already answered
 * it in `apiKeySource`, and three doctors reconstructing that walk by hand is
 * three chances to describe a chain nobody runs. What the files are still asked
 * is which field inside the winning layer holds the value, because the layer
 * alone cannot tell `plugin.<harness>.apiKey` from `api_key`, or a harness
 * block from `server.root_api_key`.
 *
 * The identity has no such answer to read, so account and user follow the chain
 * in `resolveConnection` step for step: pinned to ovcli.conf it ends
 * at that file's `plugin` section, and otherwise the environment wins and
 * ov.conf's harness block is last.
 */
export function credentialSources(cfg, cliConf, ovConf, { section = harnessKey(cfg.harness || "") } = {}) {
  const env = process.env;
  const cliShort = homeShort(cliConf.path);
  const ovShort = homeShort(ovConf.path);
  const cli = cliConf.ok ? cliConf.data : {};
  const ov = ovConf.ok ? ovConf.data : {};
  const plugin = cli.plugin || {};
  const scoped = (section && plugin[section]) || {};
  const block = (section && ov[section]) || {};
  const server = ov.server || {};
  // Pinned to ovcli.conf, the chain never looks at the environment; forced to
  // the environment, it never looks at a file.
  const pinned = cfg.credentialSource === "ovcli";
  const envOnly = /^(env|environment)$/i.test(String(env.OPENVIKING_CREDENTIAL_SOURCE || env.OPENVIKING_CREDENTIALS_SOURCE || "").trim());

  const envUrl = env.OPENVIKING_URL || env.OPENVIKING_BASE_URL;
  const url = (!pinned && envUrl) ? "env"
    : envOnly ? "default (http://127.0.0.1:1933)"
      : cli.url ? cliShort
        : server.url ? ovShort
          : (server.host || server.port) ? `${ovShort} server.host/port` : "default (http://127.0.0.1:1933)";

  let apiKey;
  if (cfg.apiKeySource === "env") {
    apiKey = env.OPENVIKING_BEARER_TOKEN ? "env OPENVIKING_BEARER_TOKEN" : "env OPENVIKING_API_KEY";
  } else if (cfg.apiKeySource === "ovcli") {
    apiKey = cli.api_key ? cliShort
      : scoped.apiKey ? `${cliShort} plugin.${section}.apiKey`
        : plugin.apiKey ? `${cliShort} plugin.apiKey` : cliShort;
  } else if (cfg.apiKeySource === "ov") {
    apiKey = block.apiKey ? `${ovShort} ${section}.apiKey`
      : server.root_api_key ? `${ovShort} server.root_api_key` : ovShort;
  } else if (cfg.apiKeySource === "host") {
    apiKey = "the host application";
  } else {
    apiKey = pinned ? "(none — ovcli.conf mode ignores env)"
      : envOnly ? "(none — env mode reads no file)" : "(none)";
  }

  const identity = (envName, cliValue, name) => (
    (!pinned && env[envName]) ? "env"
      : envOnly ? "(unset)"
        : cliValue ? cliShort
          : scoped[name] ? `${cliShort} plugin.${section}.${name}`
            : plugin[name] ? `${cliShort} plugin.${name}`
              : (!pinned && block[name]) ? `${ovShort} ${section}.${name}` : "(unset)"
  );
  return {
    url,
    apiKey,
    account: identity("OPENVIKING_ACCOUNT", cli.account || cli.account_id, "accountId"),
    user: identity("OPENVIKING_USER", cli.user || cli.user_id, "userId"),
  };
}

/**
 * The resolved url, key and identity, each with the source it came from.
 * `sources` is the host's own credential chain rendered as one label per field.
 */
export function reportCredentials(report, cfg, sources, { account = "", user = "" } = {}) {
  report.info(`url      ${cfg.baseUrl}  ← ${sources.url}`);
  for (const p of lintBaseUrl(cfg.baseUrl)) report[p.level](p.message, "", p.fix);
  if (sources.url.startsWith("default") && !isLoopbackUrl(cfg.baseUrl)) report.info("url fell back to the built-in default");
  else if (sources.url.startsWith("default")) report.warn("no url configured — using the built-in default http://127.0.0.1:1933", "only right when the server runs on this machine", "set url in ovcli.conf or OPENVIKING_URL");

  const keyInfo = describeApiKey(cfg.apiKey);
  report.info(`api_key  ${keyInfo.display}  ← ${sources.apiKey}`);
  for (const p of keyInfo.problems) report.warn(`api key ${p}`, "", "re-copy the key exactly as issued");
  if (sources.apiKey.includes("root_api_key")) {
    report.warn("api key falls back to ov.conf server.root_api_key", "the root key is refused on tenant data APIs and /mcp in api_key mode; against a remote server it is simply the wrong key",
      "put a user/admin key in ovcli.conf api_key (or OPENVIKING_API_KEY)");
  }
  if (!keyInfo.present && !isLoopbackUrl(cfg.baseUrl)) report.warn("no api key configured for a non-local server", "", "set api_key in ovcli.conf or OPENVIKING_API_KEY");
  report.info(`account  ${account || "(unset)"}  ← ${sources.account}`);
  report.info(`user     ${user || "(unset)"}  ← ${sources.user}`);
  if (keyInfo.format === "v2") {
    if (account && keyInfo.account && account !== keyInfo.account) report.warn(`configured account '${account}' differs from the key's account '${keyInfo.account}'`, "in api_key mode the key wins");
    if (user && keyInfo.user && user !== keyInfo.user) report.warn(`configured user '${user}' differs from the key's user '${keyInfo.user}'`, "in api_key mode the key wins");
  }
  return keyInfo;
}

/** The peer this directory sends, where it came from, and what it costs when there is none. */
export function reportPeer(report, cfg, { cwd = process.cwd() } = {}) {
  const peer = resolveEffectivePeerId({ cfg, cwd });
  report.info(`peer     ${peer.peerId || "(none)"}  ← ${peer.source} (${peer.origin})`);
  if (peer.origin === "unresolved") {
    report.info(
      "no peer is sent: this directory is in no git repository, so its memories go to your user-level space",
      `to give it a memory of its own, create .openviking/config.json here with ${WORKSPACE_PEER_HINT}`,
    );
  } else if (peer.source === "none") {
    report.warn(
      "no peer is sent, so recall defaults to every memory under this user",
      "sending a peer narrows the search to this workspace",
      'unset OPENVIKING_WORKSPACE_PEER, or set peer.source to "git"',
    );
  }
  if (peer.legacyPeerId) {
    report.info(
      `previous peer  ${peer.legacyPeerId}`,
      cfg.recallPeerScope === "actor"
        ? "recall asks it separately, because peer_scope actor turns off the server's cross-peer sweep"
        : "already covered by the server's cross-peer sweep under peer_scope all",
    );
  }
  for (const p of lintPeerScopeDowngrade()) report[p.level](p.message, p.detail, p.fix);
  return peer;
}

const TIMEOUT_LABELS = { timeoutMs: "request", recallTimeoutMs: "recall", captureTimeoutMs: "capture" };

/**
 * The timeouts line and the hook-budget check. `timeoutBudgets` maps a hook
 * event to the knob that governs the request inside it, so each harness names
 * the knob its own recall and capture paths actually read — a request that
 * outlives its hook is killed by the host before it can answer.
 *
 * `hooksTemplate` names the template when it does not sit at the plugin root,
 * and an entry states its timeout either directly or one nesting level down.
 */
export function reportTimeouts(report, cfg, { pluginRoot = "", hooksTemplate = "", launcherHint = "the harness", timeoutBudgets = {} } = {}) {
  const knobs = [...new Set(["timeoutMs", ...Object.values(timeoutBudgets)])];
  report.info(`timeouts ${knobs.map((knob) => `${cfg[knob]}ms ${TIMEOUT_LABELS[knob] || knob}`).join(", ")}; recall limit ${cfg.recallLimit}, threshold ${cfg.scoreThreshold}`);

  const hooks = tryJson(hooksTemplate || join(pluginRoot, "hooks", "hooks.json"))?.hooks || {};
  for (const [event, knob] of Object.entries(timeoutBudgets)) {
    const entry = hooks[event]?.[0];
    const budget = Number(entry?.hooks?.[0]?.timeout ?? entry?.timeout) * 1000 || 0;
    if (!budget || !(cfg[knob] > budget)) continue;
    report.warn(`${TIMEOUT_LABELS[knob] || knob} timeout ${cfg[knob]}ms exceeds the ${event} hook budget ${budget}ms`,
      `${launcherHint} kills the hook before the request can finish`,
      `lower ${KNOB_BY_NAME.get(knob)?.env || knob}`);
  }
}

/** The switches that decide whether anything is injected at all. */
export function reportToggles(report, cfg, { harness = "" } = {}, toggles = []) {
  report.info(`toggles  ${toggles.join(", ")}`);
  if (!cfg.autoRecall || !cfg.autoCapture || cfg.noAutoInject) {
    report.warn("one or more injection paths are switched off", toggles.join(", "),
      `check OPENVIKING_AUTO_RECALL / OPENVIKING_AUTO_CAPTURE / OPENVIKING_NO_AUTO_INJECT and ovcli.conf plugin.${harnessKey(harness)}`);
  }
}

/**
 * Where the hooks log, and what the environment does to them. `extra` adds the
 * host's own reading of the OPENVIKING_* vars it found.
 */
export function sweepEnv(report, cfg, { launcherHint = "the harness" } = {}, extra) {
  report.info(`debug log ${cfg.debug ? "on" : "off"} → ${homeShort(cfg.debugLogPath)}${cfg.debug ? "" : ` (set OPENVIKING_DEBUG=1 in ${launcherHint}'s environment to record hook errors)`}`);

  const env = collectEnv();
  if (env.openviking.length) {
    report.info("OPENVIKING_* in this environment", env.openviking.map((e) => `${e.name}=${e.value}`).join("\n"));
    if (extra) extra(report, env);
  } else {
    report.info("no OPENVIKING_* environment variables set");
  }
  if (env.proxy.length) {
    report.warn(`proxy variables set: ${env.proxy.map((e) => e.name).join(", ")}`,
      "Node's fetch ignores HTTP(S)_PROXY unless NODE_USE_ENV_PROXY=1 (Node 24+); curl honours them, so curl may succeed while hooks fail",
      isLoopbackUrl(cfg.baseUrl) ? "harmless for a local server" : `set NODE_USE_ENV_PROXY=1 (or reach the server without the proxy) in the environment that launches ${launcherHint}`);
  }
  if (env.node.length) report.info(`node TLS/proxy env: ${env.node.map((e) => `${e.name}=${e.value}`).join(", ")}`);
  if (/^https:/i.test(cfg.baseUrl) && env.node.some((e) => e.name === "NODE_TLS_REJECT_UNAUTHORIZED" && e.value === "0")) {
    report.warn("NODE_TLS_REJECT_UNAUTHORIZED=0 disables certificate checks", "", "prefer NODE_EXTRA_CA_CERTS=<ca.pem>");
  }
  return env;
}

// ---------------------------------------------------------------------------
// The run
// ---------------------------------------------------------------------------

export function parseArgs(argv) {
  const opts = { json: false, offline: false, timeoutMs: 5000, color: process.stdout.isTTY && !process.env.NO_COLOR };
  for (let i = 0; i < argv.length; i += 1) {
    const arg = argv[i];
    if (arg === "--json") opts.json = true;
    else if (arg === "--offline" || arg === "--no-network") opts.offline = true;
    else if (arg === "--no-color") opts.color = false;
    else if (arg === "--timeout") opts.timeoutMs = Math.max(1000, Number(argv[++i]) || 5000);
    else if (arg === "-h" || arg === "--help") {
      console.log("usage: ov-memory-doctor.mjs [--json] [--offline] [--timeout <ms>] [--no-color]");
      process.exit(0);
    }
  }
  if (opts.json) opts.color = false;
  return opts;
}

export function expandHome(p) {
  return p ? resolvePath(p.replace(/^~(?=$|\/)/, homedir())) : p;
}

export function tryJson(path) {
  try {
    return JSON.parse(readFileSync(path, "utf-8"));
  } catch {
    return null;
  }
}

/**
 * The "Environment" section. `launcherHint` names the host in the prose ("the
 * environment that launches Claude Code"); `onCliFound` lets a host report its
 * CLI its own way and add probes of its own between the version line and the
 * platform line.
 */
export function checkEnvironment(report, { cliName, cliVersionArgs = ["--version"], launcherHint, nodePathFix, onCliFound } = {}) {
  report.section("Environment");
  const nodeMajor = parseNodeMajor(process.version);
  const nodePath = process.execPath;
  if (nodeMajor >= 18) report.ok(`node ${process.version} (${nodePath})`);
  else report.fail(`node ${process.version} is too old`, "hooks and the MCP proxy need Node.js 18+ (global fetch)", "install Node.js 18 or newer and make sure it is first on PATH");
  const nodeOnPath = whichCommand("node");
  if (!nodeOnPath) {
    report.warn("`node` is not on PATH for this process",
      `hooks and .mcp.json invoke the bare command \`node\`; if ${launcherHint} was launched without your shell profile (nvm/volta/fnm), hooks never start`,
      nodePathFix || `put node on PATH for the environment that launches ${launcherHint}`);
  } else if (resolvePath(nodeOnPath) !== resolvePath(nodePath)) {
    report.info(`PATH resolves node to ${nodeOnPath} (this run used ${nodePath})`);
  }

  const cli = runCommand(cliName, cliVersionArgs, { timeoutMs: 15000 });
  if (cli.ok) {
    if (onCliFound) onCliFound(report, cli);
    else report.ok(cli.stdout.split("\n")[0]);
  } else {
    report.info(`${cliName} CLI not found on PATH (${cli.error || "?"}) — install checks that need it are skipped`);
  }
  report.info(`platform ${process.platform} ${process.arch}, cwd ${homeShort(process.cwd())}`);
  return { cliOnPath: cli.ok };
}

/**
 * The "Connection" section. `account`/`user` are the configured identity: they
 * only reach the wire when the harness sends identity headers, but the probe
 * report compares them against what the key claims either way. `onSummary`
 * carries the host's verdict on the answer (Codex compares auth modes).
 */
export async function checkConnection(report, cfg, { keyInfo, peer, account = "", user = "" }, opts, { onSummary } = {}) {
  report.section("Connection");
  if (opts.offline) {
    report.info("skipped (--offline)");
    return null;
  }
  const conn = { baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, account: cfg.sendIdentityHeaders ? account : "", user: cfg.sendIdentityHeaders ? user : "", peerId: peer.peerId, userAgent: cfg.userAgent };
  const probes = await probeOpenViking(conn, { timeoutMs: opts.timeoutMs });
  const summary = assessProbes(report, probes, { ...conn, account, user }, keyInfo);
  if (onSummary) onSummary(report, summary, cfg);
  return { probes, summary, conn };
}

/**
 * Run one harness's doctor. `host` is the harness spec: the `checkEnvironment`
 * fields above, `loadConfig()`, the three sections only the host can produce
 * (`checkInstall`, `checkConfig`, `checkActivity`), `resolveIdentity(cfg)` for
 * the account/user spelling that harness uses, and optionally `onSummary` and
 * `extraResolved(cfg)` for extra `--json` fields. `checkConfig` is handed the
 * spec back, because the configuration segments it composes are driven by it.
 */
export async function runDoctor(host) {
  const opts = parseArgs(process.argv.slice(2));
  const report = createReport({ color: opts.color });
  const envInfo = checkEnvironment(report, host);
  host.checkInstall(report, envInfo);
  const cfg = host.loadConfig();
  const configInfo = host.checkConfig(report, cfg, host);
  const workspace = checkWorkspace(report, { clientVersion: cfg.clientVersion });
  const identity = host.resolveIdentity(cfg);
  const connection = await checkConnection(report, cfg, { ...configInfo, ...identity }, opts, host);
  const serverHealth = await checkServerHealth(report, { baseUrl: cfg.baseUrl, ovConf: configInfo.ovConf, health: effectiveHealthProbe(connection?.probes), conn: connection?.conn, offline: opts.offline, timeoutMs: opts.timeoutMs });
  host.checkActivity(report, cfg, connection);

  if (opts.json) {
    console.log(JSON.stringify({
      harness: host.harness,
      pluginRoot: host.pluginRoot,
      generatedAt: new Date().toISOString(),
      resolved: {
        baseUrl: cfg.baseUrl,
        apiKey: configInfo.keyInfo.display,
        apiKeyFormat: configInfo.keyInfo.format,
        account: identity.account,
        user: identity.user,
        peerId: configInfo.peer.peerId,
        ...(host.extraResolved ? host.extraResolved(cfg) : {}),
      },
      workspace,
      server: connection?.summary || null,
      serverHealth,
      ...report.toJSON(),
    }, null, 2));
  } else {
    console.log(report.render());
  }
  process.exitCode = report.exitCode();
}