kojee-mcp 0.7.5-staging.2 → 0.7.5-staging.21

package/dist/doctor-hermes-KMHM27Y3.js

@@ -0,0 +1,597 @@
+import {
+  HERMES_INSTANCE_KEY,
+  HERMES_MCP_SERVER_NAME
+} from "./chunk-GEGUWQYT.js";
+import {
+  buildFlapDoctorCheck
+} from "./chunk-P64UR3SE.js";
+import "./chunk-SQL56SEB.js";
+
+// src/doctor-hermes.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+import { execFileSync } from "child_process";
+import { parse } from "yaml";
+
+// src/reconcile/index.ts
+var FindingCollector = class {
+  items = [];
+  /** Append a pre-built Finding. */
+  add(finding) {
+    this.items.push(finding);
+  }
+  /** Append a Finding from its parts (the common call site). */
+  push(id, severity, detail) {
+    this.items.push({ id, severity, detail });
+  }
+  /** The findings in insertion order (read-only view). */
+  get findings() {
+    return this.items;
+  }
+  /**
+   * Roll the findings up into the doctor verdict: any `broken` ⇒ broken; else any
+   * `warn` ⇒ degraded; else healthy. `unknown` never fails the verdict (it is an
+   * "I couldn't determine this" signal, same as the doctor's `?` marks).
+   */
+  verdict() {
+    if (this.items.some((f) => f.severity === "broken")) return "broken";
+    if (this.items.some((f) => f.severity === "warn")) return "degraded";
+    return "healthy";
+  }
+};
+
+// src/doctor-hermes.ts
+var WIZARD_RERUN = "re-run `kojee-mcp init --runtime hermes`";
+var DEFAULT_LISTEN_HOST = "127.0.0.1";
+var DEFAULT_LISTEN_PORT = "8645";
+var DEFAULT_LISTEN_PATH = "/kojee-tandem";
+function serviceUnitPath(homeDir, platform) {
+  if (platform === "darwin") {
+    return path.join(homeDir, "Library", "LaunchAgents", "net.kojee.kojee-hermes.plist");
+  }
+  return path.join(homeDir, ".config", "systemd", "user", "kojee-hermes.service");
+}
+function hermesEnvPathFor(homeDir) {
+  return path.join(homeDir, ".kojee", "hermes.env");
+}
+function hermesArtifactsPresent(deps = {}) {
+  const homeDir = deps.homeDir ?? os.homedir();
+  const platform = deps.platform ?? process.platform;
+  const exists = deps.exists ?? ((p) => fs.existsSync(p));
+  return exists(hermesEnvPathFor(homeDir)) || exists(serviceUnitPath(homeDir, platform));
+}
+function unquoteEnvValue(raw) {
+  let v = raw.trim();
+  if (v.length >= 2 && (v.startsWith("'") && v.endsWith("'") || v.startsWith('"') && v.endsWith('"'))) {
+    v = v.slice(1, -1);
+  }
+  return v.replace(/'\\''/g, "'");
+}
+function parseEnvFile(text) {
+  const vars = /* @__PURE__ */ new Map();
+  const exportKeys = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const m = line.match(/^(export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!m) continue;
+    const key = m[2];
+    if (m[1] !== void 0) exportKeys.push(key);
+    vars.set(key, unquoteEnvValue(m[3]));
+  }
+  return { vars, exportKeys };
+}
+function readChildEnv(configText) {
+  if (configText === null) return null;
+  let doc;
+  try {
+    doc = parse(configText);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object") return null;
+  const servers = doc["mcp_servers"];
+  if (!servers || typeof servers !== "object") return null;
+  const kojee = servers[HERMES_MCP_SERVER_NAME];
+  if (!kojee || typeof kojee !== "object") return null;
+  const env = kojee["env"];
+  if (!env || typeof env !== "object") return null;
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+function sha256(value) {
+  return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+function readPluginEnabled(configText) {
+  if (configText === null) return null;
+  let doc;
+  try {
+    doc = parse(configText);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object") return null;
+  const plugins = doc["plugins"];
+  if (!plugins || typeof plugins !== "object") return false;
+  const enabled = plugins["enabled"];
+  if (!Array.isArray(enabled)) return false;
+  return enabled.includes("kojee-tandem");
+}
+function parseExecTargets(unitText) {
+  if (unitText === null) return null;
+  const m = unitText.match(/exec\s+([^'"\n<]+)/);
+  if (!m) return null;
+  return m[1].trim().split(/\s+/).filter((tok) => tok.startsWith("/"));
+}
+function defaultReadText(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function defaultProbeService(platform) {
+  return () => {
+    try {
+      if (platform === "darwin") {
+        const out2 = execFileSync("launchctl", ["list"], { encoding: "utf8" });
+        return { active: out2.includes("net.kojee.kojee-hermes") };
+      }
+      const out = execFileSync("systemctl", ["--user", "is-active", "kojee-hermes"], {
+        encoding: "utf8"
+      }).trim();
+      return { active: out === "active" };
+    } catch (err) {
+      const stdout = err.stdout;
+      if (stdout !== void 0) {
+        const s = (typeof stdout === "string" ? stdout : stdout.toString()).trim();
+        if (s.length > 0) return { active: s === "active" };
+      }
+      return null;
+    }
+  };
+}
+function defaultProbeReceiver(platform) {
+  return (_host, port) => {
+    try {
+      if (platform === "darwin") {
+        try {
+          execFileSync("lsof", [`-iTCP:${port}`, "-sTCP:LISTEN", "-n", "-P"], { encoding: "utf8" });
+          return true;
+        } catch (err) {
+          if (err.status === 1) return false;
+          return null;
+        }
+      }
+      const out = execFileSync("ss", ["-ltnH"], { encoding: "utf8" });
+      const re = new RegExp(`:${port}(\\s|$)`);
+      return out.split("\n").some((l) => re.test(l));
+    } catch {
+      return null;
+    }
+  };
+}
+function defaultReadDaemonEnv(platform) {
+  return () => {
+    if (platform !== "linux") return null;
+    try {
+      const pidStr = execFileSync(
+        "systemctl",
+        ["--user", "show", "-p", "MainPID", "--value", "kojee-hermes"],
+        { encoding: "utf8" }
+      ).trim();
+      const pid = Number.parseInt(pidStr, 10);
+      if (!Number.isFinite(pid) || pid <= 0) return null;
+      const raw = fs.readFileSync(`/proc/${pid}/environ`, "utf8");
+      const out = {};
+      for (const pair of raw.split("\0")) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0) continue;
+        out[pair.slice(0, eq)] = pair.slice(eq + 1);
+      }
+      return out;
+    } catch {
+      return null;
+    }
+  };
+}
+function okFromSeverity(sev) {
+  return sev === "ok" ? true : sev === "warn" ? "warn" : sev === "broken" ? false : "unknown";
+}
+function emit(checks, collector, id, severity, detail) {
+  checks.push({ name: id, ok: okFromSeverity(severity), detail });
+  collector.push(id, severity, detail);
+}
+function collectHermesDoctorReport(deps = {}) {
+  const homeDir = deps.homeDir ?? os.homedir();
+  const platform = deps.platform ?? process.platform;
+  const readText = deps.readText ?? defaultReadText;
+  const exists = deps.exists ?? ((p) => fs.existsSync(p));
+  const probeService = deps.probeService ?? defaultProbeService(platform);
+  const probeReceiver = deps.probeReceiver ?? defaultProbeReceiver(platform);
+  const readDaemonEnv = deps.readDaemonEnv ?? defaultReadDaemonEnv(platform);
+  const hermesEnvPath = hermesEnvPathFor(homeDir);
+  const adapterEnvPath = path.join(homeDir, ".hermes", ".env");
+  const configYamlPath = path.join(homeDir, ".hermes", "config.yaml");
+  const unitPath = serviceUnitPath(homeDir, platform);
+  const daemonEnvText = readText(hermesEnvPath);
+  const adapterEnvText = readText(adapterEnvPath);
+  const unitText = readText(unitPath);
+  const configText = readText(configYamlPath);
+  const daemonEnv = daemonEnvText !== null ? parseEnvFile(daemonEnvText) : null;
+  const adapterEnv = adapterEnvText !== null ? parseEnvFile(adapterEnvText) : null;
+  const childEnv = readChildEnv(configText);
+  const pluginEnabled = readPluginEnabled(configText);
+  const checks = [];
+  const collector = new FindingCollector();
+  if (daemonEnv === null) {
+    emit(checks, collector, "webhook.env-format", "unknown", `hermes.env unreadable at ${hermesEnvPath}`);
+  } else if (daemonEnv.exportKeys.length > 0) {
+    const unitUsesEnvFile = unitText !== null && /^\s*EnvironmentFile=/m.test(unitText);
+    const keys = daemonEnv.exportKeys.join(", ");
+    if (unitUsesEnvFile) {
+      emit(
+        checks,
+        collector,
+        "webhook.env-format",
+        "broken",
+        `hermes.env has export-prefixed line(s) [${keys}] AND the service unit uses EnvironmentFile= \u2014 systemd DROPS them, so the daemon boots with those vars UNSET (silent webhook-off + seat churn). ${WIZARD_RERUN} to rewrite the unit (source wrapper) + env (bare).`
+      );
+    } else {
+      emit(
+        checks,
+        collector,
+        "webhook.env-format",
+        "warn",
+        `hermes.env has legacy export-prefixed line(s) [${keys}] \u2014 harmless under the source-wrapper unit (set -a exports them) but ${WIZARD_RERUN} to normalize to bare form.`
+      );
+    }
+  } else {
+    emit(
+      checks,
+      collector,
+      "webhook.env-format",
+      "ok",
+      "hermes.env is bare single-quoted (no export-prefixed lines) \u2014 sources cleanly."
+    );
+  }
+  const daemonUrl = (daemonEnv?.vars.get("KOJEE_WEBHOOK_URL") ?? "").trim();
+  const listenHost = adapterEnv?.vars.get("KOJEE_TANDEM_LISTEN_HOST") ?? DEFAULT_LISTEN_HOST;
+  const listenPort = adapterEnv?.vars.get("KOJEE_TANDEM_LISTEN_PORT") ?? DEFAULT_LISTEN_PORT;
+  const listenPath = adapterEnv?.vars.get("KOJEE_TANDEM_LISTEN_PATH") ?? DEFAULT_LISTEN_PATH;
+  if (!daemonUrl) {
+    emit(
+      checks,
+      collector,
+      "webhook.url-receiver-align",
+      "broken",
+      `daemon KOJEE_WEBHOOK_URL is EMPTY \u2014 no event stream (null delivery); the daemon will not POST wakes. Set the receiver URL: ${WIZARD_RERUN}.`
+    );
+  } else {
+    let parsed = null;
+    try {
+      parsed = new URL(daemonUrl);
+    } catch {
+      parsed = null;
+    }
+    if (parsed === null) {
+      emit(
+        checks,
+        collector,
+        "webhook.url-receiver-align",
+        "broken",
+        `daemon KOJEE_WEBHOOK_URL is not a valid URL \u2014 ${WIZARD_RERUN}.`
+      );
+    } else {
+      const urlPort = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
+      const aligned = parsed.hostname === listenHost && urlPort === listenPort && parsed.pathname === listenPath;
+      emit(
+        checks,
+        collector,
+        "webhook.url-receiver-align",
+        aligned ? "ok" : "broken",
+        aligned ? `daemon URL host/port/path aligns with the receiver bind (${listenHost}:${listenPort}${listenPath}).` : `daemon URL (${parsed.hostname}:${urlPort}${parsed.pathname}) != receiver bind (${listenHost}:${listenPort}${listenPath}) \u2014 POSTs miss the listener. Align them.`
+      );
+    }
+  }
+  const daemonSecret = daemonEnv?.vars.get("KOJEE_WEBHOOK_SECRET");
+  const adapterSecret = adapterEnv?.vars.get("KOJEE_WEBHOOK_SECRET");
+  if (!daemonSecret || !adapterSecret) {
+    const which = [!daemonSecret ? "daemon (hermes.env)" : null, !adapterSecret ? "adapter (~/.hermes/.env)" : null].filter((s) => s !== null).join(" and ");
+    emit(
+      checks,
+      collector,
+      "webhook.secret-match",
+      "broken",
+      `KOJEE_WEBHOOK_SECRET missing on ${which} \u2014 the receiver can't verify signed POSTs (401). ${WIZARD_RERUN}.`
+    );
+  } else {
+    const same = sha256(daemonSecret) === sha256(adapterSecret);
+    emit(
+      checks,
+      collector,
+      "webhook.secret-match",
+      same ? "ok" : "broken",
+      same ? "daemon + adapter secrets match (compared by sha256; values never printed)." : `daemon vs adapter KOJEE_WEBHOOK_SECRET DIFFER (compared by sha256; values never printed) \u2014 every POST is rejected 401. Resync one side: ${WIZARD_RERUN} (writes one secret both sides).`
+    );
+  }
+  const execTargets = parseExecTargets(unitText);
+  if (unitText === null) {
+    emit(checks, collector, "webhook.daemon-bin", "unknown", `service unit unreadable at ${unitPath}.`);
+  } else if (execTargets === null || execTargets.length === 0) {
+    emit(
+      checks,
+      collector,
+      "webhook.daemon-bin",
+      "warn",
+      "could not parse the ExecStart exec target from the unit \u2014 cannot verify the daemon binary."
+    );
+  } else {
+    const missing = execTargets.filter((p) => !exists(p));
+    const ephemeral = execTargets.find((p) => /[\\/]_npx[\\/]/.test(p));
+    if (missing.length > 0) {
+      emit(
+        checks,
+        collector,
+        "webhook.daemon-bin",
+        "broken",
+        `daemon ExecStart points at ${missing.join(", ")} which does NOT exist \u2014 the service fails to start (exit 127) and crash-loops. Install globally + ${WIZARD_RERUN}: \`npm i -g kojee-mcp && kojee-mcp init --runtime hermes\`.`
+      );
+    } else if (ephemeral) {
+      emit(
+        checks,
+        collector,
+        "webhook.daemon-bin",
+        "warn",
+        `daemon ExecStart runs from an EPHEMERAL npx cache (${ephemeral}) \u2014 it works now but npx will eventually delete it, then the daemon dies (exit 127). For durability: \`npm i -g kojee-mcp && kojee-mcp init --runtime hermes\`.`
+      );
+    } else {
+      emit(
+        checks,
+        collector,
+        "webhook.daemon-bin",
+        "ok",
+        `daemon ExecStart targets exist (${execTargets.join(" ")}) \u2014 node + CLI resolve without PATH.`
+      );
+    }
+  }
+  const svc = probeService();
+  if (svc === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.pusher-up",
+      "unknown",
+      "could not determine kojee-hermes service state (systemctl/launchctl unavailable)."
+    );
+  } else if (svc.active) {
+    emit(checks, collector, "webhook.pusher-up", "ok", "kojee-hermes service is active.");
+  } else {
+    const why = execTargets && execTargets.some((p) => !exists(p)) ? " (likely the missing ExecStart binary above \u2014 exit 127)" : "";
+    emit(
+      checks,
+      collector,
+      "webhook.pusher-up",
+      "broken",
+      `kojee-hermes service is NOT active${why} \u2014 no wakes are being pushed. Enable+start it (\`systemctl --user enable --now kojee-hermes\`) \u2014 shared infra, so the principal's call.`
+    );
+  }
+  if (pluginEnabled === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.plugin-enabled",
+      "unknown",
+      "could not read plugins.enabled from ~/.hermes/config.yaml."
+    );
+  } else if (pluginEnabled) {
+    emit(
+      checks,
+      collector,
+      "webhook.plugin-enabled",
+      "ok",
+      "kojee-tandem receiver plugin is enabled in Hermes (plugins.enabled)."
+    );
+  } else {
+    emit(
+      checks,
+      collector,
+      "webhook.plugin-enabled",
+      "broken",
+      "kojee-tandem receiver plugin is NOT enabled \u2014 the gateway loads no receiver, so wakes never arrive (a gateway restart alone can't fix this). Enable it, then restart the gateway: `hermes plugins enable kojee-tandem && hermes gateway restart`."
+    );
+  }
+  const receiver = probeReceiver(listenHost, Number.parseInt(listenPort, 10));
+  if (receiver === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.receiver-up",
+      "unknown",
+      `could not probe the receiver bind ${listenHost}:${listenPort} (ss/lsof unavailable).`
+    );
+  } else if (receiver) {
+    emit(
+      checks,
+      collector,
+      "webhook.receiver-up",
+      "ok",
+      `receiver is listening on ${listenHost}:${listenPort}.`
+    );
+  } else {
+    const fix = pluginEnabled === false ? "the kojee-tandem plugin is DISABLED (see webhook.plugin-enabled) \u2014 enable it, then restart the gateway" : "the Hermes gateway (kojee-tandem plugin) receiver is down \u2014 restart the gateway to load the plugin";
+    emit(
+      checks,
+      collector,
+      "webhook.receiver-up",
+      "warn",
+      `nothing is listening on ${listenHost}:${listenPort} \u2014 ${fix}.`
+    );
+  }
+  if (childEnv === null) {
+    emit(
+      checks,
+      collector,
+      "webhook.no-duplicate",
+      "unknown",
+      `could not read mcp_servers.${HERMES_MCP_SERVER_NAME}.env from ~/.hermes/config.yaml.`
+    );
+  } else {
+    const childUrl = (childEnv["KOJEE_WEBHOOK_URL"] ?? "").trim();
+    emit(
+      checks,
+      collector,
+      "webhook.no-duplicate",
+      childUrl === "" ? "ok" : "broken",
+      childUrl === "" ? "mcp child KOJEE_WEBHOOK_URL is empty (hard-off) \u2014 no duplicate delivery." : `mcp_servers.${HERMES_MCP_SERVER_NAME} has a NON-EMPTY KOJEE_WEBHOOK_URL \u2014 the tools-only child would DOUBLE-DELIVER wakes for the seat. Clear it (keep the empty hard-off).`
+    );
+  }
+  const daemonInstance = (daemonEnv?.vars.get("KOJEE_INSTANCE") ?? "").trim();
+  const childInstance = (childEnv?.["KOJEE_INSTANCE"] ?? "").trim();
+  if (!daemonInstance) {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "broken",
+      `daemon KOJEE_INSTANCE is unset \u2014 daemon + MCP child may resolve to DIFFERENT sessions (split-brain seat). Expected '${HERMES_INSTANCE_KEY}'. ${WIZARD_RERUN}.`
+    );
+  } else if (childInstance && daemonInstance !== childInstance) {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "broken",
+      `daemon KOJEE_INSTANCE='${daemonInstance}' != mcp child KOJEE_INSTANCE='${childInstance}' \u2014 split-brain: a tandem_send from the agent lands on a different seat than the daemon streams wakes for. ${WIZARD_RERUN}.`
+    );
+  } else if (daemonInstance !== HERMES_INSTANCE_KEY) {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "warn",
+      `daemon KOJEE_INSTANCE='${daemonInstance}' != expected '${HERMES_INSTANCE_KEY}' (non-standard but self-consistent with the child).`
+    );
+  } else {
+    emit(
+      checks,
+      collector,
+      "webhook.instance-align",
+      "ok",
+      `daemon + mcp child share KOJEE_INSTANCE='${HERMES_INSTANCE_KEY}' \u2014 one backend seat.`
+    );
+  }
+  if (platform !== "linux") {
+    emit(
+      checks,
+      collector,
+      "webhook.env-reaches-daemon",
+      "unknown",
+      "n/a \u2014 reads /proc/<pid>/environ (Linux only)."
+    );
+  } else {
+    const liveEnv = readDaemonEnv();
+    if (liveEnv === null) {
+      emit(
+        checks,
+        collector,
+        "webhook.env-reaches-daemon",
+        "unknown",
+        "daemon not running (no MainPID) or its /proc environ is unreadable."
+      );
+    } else {
+      const missing = ["KOJEE_WEBHOOK_URL", "KOJEE_WEBHOOK_SECRET", "KOJEE_INSTANCE"].filter(
+        (k) => !((liveEnv[k] ?? "").length > 0)
+      );
+      emit(
+        checks,
+        collector,
+        "webhook.env-reaches-daemon",
+        missing.length === 0 ? "ok" : "broken",
+        missing.length === 0 ? "live daemon env carries KOJEE_WEBHOOK_URL/SECRET/INSTANCE (injection reached the process; secret value never read)." : `live daemon env is MISSING ${missing.join(", ")} \u2014 env injection did NOT reach the running daemon (source wrapper not applied / stale unit). ${WIZARD_RERUN}, then restart the service.`
+      );
+    }
+  }
+  const flapCheck = buildFlapDoctorCheck({
+    name: "webhook.daemon-flapping",
+    // hermes namespaces every check `webhook.*`
+    ...deps.readFlaps ? { readFlaps: deps.readFlaps } : {},
+    ...deps.now ? { now: deps.now } : {}
+  });
+  emit(
+    checks,
+    collector,
+    flapCheck.name,
+    flapCheck.ok === "warn" ? "warn" : "ok",
+    flapCheck.detail
+  );
+  return { checks, findings: collector.findings, verdict: collector.verdict() };
+}
+var CHECK_GROUP = {
+  "webhook.env-format": "Config",
+  "webhook.url-receiver-align": "Config",
+  "webhook.secret-match": "Config",
+  "webhook.no-duplicate": "Config",
+  "webhook.instance-align": "Config",
+  "webhook.plugin-enabled": "Receiver",
+  "webhook.receiver-up": "Receiver",
+  "webhook.daemon-bin": "Pusher",
+  "webhook.pusher-up": "Pusher",
+  "webhook.env-reaches-daemon": "Pusher"
+};
+function formatHermesDoctorReport(report) {
+  const mark = (ok) => ok === true ? "\u2713" : ok === "warn" ? "\u26A0" : ok === "unknown" ? "?" : "\u2717";
+  const shortName = (name) => name.replace(/^webhook\./, "");
+  const nOk = report.checks.filter((c) => c.ok === true).length;
+  const nWarn = report.checks.filter((c) => c.ok === "warn").length;
+  const nBad = report.checks.filter((c) => c.ok === false).length;
+  const nUnknown = report.checks.filter((c) => c.ok === "unknown").length;
+  const verdictMark = report.verdict === "healthy" ? "\u2713" : report.verdict === "degraded" ? "\u26A0" : "\u2717";
+  const lines = [];
+  lines.push(`kojee-mcp doctor \xB7 hermes wake-path \xB7 ${verdictMark} ${report.verdict.toUpperCase()}`);
+  const tally = [
+    `${nOk} ok`,
+    nWarn ? `${nWarn} warning${nWarn > 1 ? "s" : ""}` : null,
+    nBad ? `${nBad} problem${nBad > 1 ? "s" : ""}` : null,
+    nUnknown ? `${nUnknown} unknown` : null
+  ].filter(Boolean).join(", ");
+  lines.push(`  ${tally}`);
+  lines.push("  path: daemon (SSE \u2192 HMAC POST) \u2192 :8645 receiver plugin \u2192 wakes the agent");
+  lines.push("");
+  for (const group of ["Config", "Receiver", "Pusher"]) {
+    const groupChecks = report.checks.filter((c) => CHECK_GROUP[c.name] === group);
+    if (groupChecks.length === 0) continue;
+    lines.push(`  ${group}:`);
+    for (const c of groupChecks) {
+      lines.push(`    ${mark(c.ok)} ${shortName(c.name)}: ${c.detail}`);
+    }
+    lines.push("");
+  }
+  const actionable = [
+    ...report.checks.filter((c) => c.ok === false),
+    ...report.checks.filter((c) => c.ok === "warn")
+  ];
+  if (actionable.length === 0) {
+    lines.push("\u2192 Wake-path is healthy. Nothing to do.");
+  } else {
+    lines.push("\u2192 Next steps (in order):");
+    actionable.forEach((c, i) => {
+      lines.push(`   ${i + 1}. [${shortName(c.name)}] ${c.detail}`);
+    });
+  }
+  lines.push("");
+  lines.push(
+    "  (read-only. Enabling/restarting the daemon, plugin, or gateway is an owner step \u2014 shared infra needs the principal's word.)"
+  );
+  return lines.join("\n");
+}
+export {
+  collectHermesDoctorReport,
+  formatHermesDoctorReport,
+  hermesArtifactsPresent
+};

package/dist/{doctor-openclaw-LL6NSPLC.js → doctor-openclaw-B5KADVHD.js}

@@ -5,7 +5,10 @@ import {
 import "./chunk-D6JKFJ6A.js";
 import {
   resolveOpenclawWakeTarget
-} from "./chunk-NE2F5CKS.js";
+} from "./chunk-LKGKDZSO.js";
+import {
+  buildFlapDoctorCheck
+} from "./chunk-P64UR3SE.js";
 import "./chunk-SQL56SEB.js";
 import {
   loadPairedConfig,
@@ -60,6 +63,7 @@ function collectOpenclawDoctorReport(deps = {}) {
     ok: paired !== null,
     detail: paired ? `resolves \u2014 source: ${paired.source} paired slot (token value never printed)` : `NONE resolves (no ~/.kojee/agents/openclaw/config.json or ~/.kojee/config.json token) \u2014 ${WIZARD_RERUN}`
   });
+  checks.push(buildFlapDoctorCheck({ ...deps.readFlaps ? { readFlaps: deps.readFlaps } : {}, ...deps.now ? { now: deps.now } : {} }));
   const verdict = checks.some((c) => c.ok === false) ? "broken" : checks.some((c) => c.ok === "warn") ? "degraded" : "healthy";
   return { checks, verdict };
 }

package/dist/{event-log-2NBJEIEP.js → event-log-M22X3FAI.js}

@@ -6,7 +6,7 @@ import {
   startEventLog,
   statusLogPath,
   sweepStaleEventLogs
-} from "./chunk-TNZITJAB.js";
+} from "./chunk-WVQU3QQ7.js";
 import "./chunk-67F67AQ6.js";
 import "./chunk-U5HHHRXA.js";
 export {

package/dist/{event-stream-ATKYXDBV.js → event-stream-5ZEL7FXN.js}

@@ -1,7 +1,9 @@
 import {
+  CONNECT_TIMEOUT_MS,
   LOG_HEARTBEAT_INTERVAL_MS,
   UNARMED_FALLBACK_MS,
   UNDICI_DEFAULT_BODY_TIMEOUT_MS,
+  buildStreamUrl,
   createAdaptiveWatchdog,
   createBackoffController,
   normalizeBackendEvent,
@@ -10,14 +12,16 @@ import {
   startEventStream,
   statusReason,
   undiciFetch
-} from "./chunk-CUOJHP2S.js";
+} from "./chunk-UGEBGCYU.js";
 import "./chunk-Z5LPNJQ6.js";
 import "./chunk-MIEI4PLB.js";
 export {
+  CONNECT_TIMEOUT_MS,
   LOG_HEARTBEAT_INTERVAL_MS,
   UNARMED_FALLBACK_MS,
   UNDICI_DEFAULT_BODY_TIMEOUT_MS,
   undiciFetch as _sseStreamFetch,
+  buildStreamUrl,
   createAdaptiveWatchdog,
   createBackoffController,
   normalizeBackendEvent,

package/dist/flap-log-D4KG7RK4.js

@@ -0,0 +1,23 @@
+import {
+  FLAP_WARN_COUNT,
+  FLAP_WINDOW_MS,
+  MAX_FLAP_ENTRIES,
+  buildFlapDoctorCheck,
+  defaultFlapLogPath,
+  flapRateExceeds,
+  readFlaps,
+  recentFlapCount,
+  recordFlap
+} from "./chunk-P64UR3SE.js";
+import "./chunk-SQL56SEB.js";
+export {
+  FLAP_WARN_COUNT,
+  FLAP_WINDOW_MS,
+  MAX_FLAP_ENTRIES,
+  buildFlapDoctorCheck,
+  defaultFlapLogPath,
+  flapRateExceeds,
+  readFlaps,
+  recentFlapCount,
+  recordFlap
+};

package/dist/{gateway-client-CbM2OC_w.d.ts → gateway-client-CLmQghON.d.ts}

@@ -111,6 +111,17 @@ declare class GatewayClient {
     sendRest(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<Response>;
     private trackNonce;
     private tryParseErrorBody;
+    /**
+     * Read + JSON-parse a response body, decompressing gzip EXPLICITLY. The gateway
+     * may return `Content-Encoding: gzip`; transparent decompression by the HTTP
+     * client proved unreliable in the long-lived in-session context (two undici
+     * versions in play), so we detect the gzip magic (0x1f 0x8b) on the raw bytes
+     * and gunzip ourselves. Plain (already-decompressed or identity) bodies pass
+     * through untouched — valid JSON never starts with 0x1f, so there's no false
+     * positive. Version-agnostic: correct whether or not the client transparently
+     * decompressed.
+     */
+    private readJsonBody;
 }
 
 export { GatewayClient as G, type KeystoreData as K, type LoadedKeyPair as L, type McpToolDefinition as M, type ProxyConfig as P, type ToolCallResult as T };