@merittdev/horus 0.7.0 → 0.8.1

package/dist/index.cjs

@@ -65880,8 +65880,8 @@ init_cjs_shims();
 
 // ../../packages/core/src/version.ts
 init_cjs_shims();
-var HORUS_VERSION = true ? "0.7.0" : "dev";
-var PINNED_SOURCE_VERSION = "1.0.7";
+var HORUS_VERSION = true ? "0.8.1" : "dev";
+var PINNED_SOURCE_VERSION = "1.4.0";
 
 // ../../packages/core/src/evidence.ts
 init_cjs_shims();
@@ -70979,6 +70979,24 @@ async function getSourceVersion() {
     return null;
   }
 }
+var SourceVersionMismatchError = class extends Error {
+  constructor(installed, pinned) {
+    super(
+      `horus-source ${installed} is installed but Horus is pinned to ${pinned}. A drifted backend builds a graph this CLI cannot map and can corrupt the index (e.g. duplicate-primary-key failures during "Running initial index"). Install the pinned version: pip install 'horus-source==${pinned}'`
+    );
+    this.installed = installed;
+    this.pinned = pinned;
+    this.name = "SourceVersionMismatchError";
+  }
+  installed;
+  pinned;
+};
+async function assertSourceVersionPinned() {
+  const installed = await getSourceVersion();
+  if (installed !== null && installed !== PINNED_SOURCE_VERSION) {
+    throw new SourceVersionMismatchError(installed, PINNED_SOURCE_VERSION);
+  }
+}
 function isAnalyzed(root) {
   return (0, import_node_fs3.existsSync)((0, import_node_path3.join)(root, ".horus", "source"));
 }
@@ -71001,6 +71019,21 @@ function readSourceHostUrl(root) {
     return null;
   }
 }
+function readSourceHostPid(root) {
+  const p5 = (0, import_node_path3.join)(root, ".horus", "source", "host.json");
+  if (!(0, import_node_fs3.existsSync)(p5)) return null;
+  try {
+    const j3 = JSON.parse((0, import_node_fs3.readFileSync)(p5, "utf8"));
+    if (typeof j3.pid !== "number" || !Number.isInteger(j3.pid) || j3.pid <= 0) return null;
+    return {
+      pid: j3.pid,
+      port: typeof j3.port === "number" ? j3.port : NaN,
+      repoPath: typeof j3.repo_path === "string" ? j3.repo_path : ""
+    };
+  } catch {
+    return null;
+  }
+}
 async function isHostHealthy(hostUrl) {
   try {
     const res = await fetch(`${hostUrl}/api/health`, {
@@ -71139,7 +71172,9 @@ var SourceCodeProvider = class {
     const exactSymbols = exactRows.map((row) => ({
       id: String(row[0] ?? ""),
       name: String(row[1] ?? ""),
-      filePath: String(row[2] ?? "")
+      filePath: String(row[2] ?? ""),
+      score: 1
+      // an exact-name Cypher hit is authoritative
     }));
     const exactIds = new Set(exactSymbols.map((s5) => s5.id));
     const ql = query.toLowerCase();
@@ -71154,7 +71189,7 @@ var SourceCodeProvider = class {
     semantic.sort((a2, b5) => b5.rank - a2.rank || b5.r.score - a2.r.score);
     const combined = [
       ...exactSymbols,
-      ...semantic.map(({ r }) => ({ id: r.nodeId, name: r.name, filePath: r.filePath }))
+      ...semantic.map(({ r }) => ({ id: r.nodeId, name: r.name, filePath: r.filePath, score: r.score }))
     ];
     return this.hydrateLines(combined.slice(0, limit));
   }
@@ -71210,6 +71245,7 @@ var SourceCodeProvider = class {
     const isDead = Boolean(node?.[8]);
     const content = node?.[9];
     const snippet = typeof content === "string" ? content.slice(0, 600) : void 0;
+    const sourceBody = typeof content === "string" ? content.slice(0, 2e4) : void 0;
     const callees = calleeRows.map((row) => this.cypherRowToSymbol(row, 0, 1, 2, 3, 4));
     const callers = callerRows.map((row) => this.cypherRowToSymbol(row, 0, 1, 2, 3, 4));
     const usesType = usesTypeRows.map((row) => this.cypherRowToSymbol(row, 0, 1, 2, 3));
@@ -71236,6 +71272,7 @@ var SourceCodeProvider = class {
     return {
       symbol,
       snippet,
+      ...sourceBody !== void 0 ? { sourceBody } : {},
       callers,
       callees,
       imports,
@@ -71780,8 +71817,12 @@ function shortTs(iso) {
 }
 function buildErrorAnalysisBody(q2, field = "event_code", mapping = MERITT_FIELD_MAPPING) {
   const filters = [];
-  const minLevel = q2.level !== void 0 && levelToValue(q2.level) > 50 ? q2.level : "error";
-  filters.push(buildLevelFilter(mapping, minLevel));
+  if (q2.eventCode === void 0) {
+    const minLevel = q2.level !== void 0 && levelToValue(q2.level) > 50 ? q2.level : "error";
+    filters.push(buildLevelFilter(mapping, minLevel));
+  } else if (q2.level !== void 0 && levelToValue(q2.level) > 50) {
+    filters.push(buildLevelFilter(mapping, q2.level));
+  }
   if (q2.from !== void 0 || q2.to !== void 0) {
     const rangeClause = {};
     if (q2.from !== void 0) rangeClause["gte"] = q2.from;
@@ -89233,18 +89274,58 @@ async function createLocalDb(opts) {
   } catch {
   }
   assertEmbeddedAssetsPresent();
-  const client = new Ve3(dataDir);
-  await client.waitReady;
-  await applyEmbeddedMigrations(client);
-  const db = drizzle2(client, { schema: schema_exports });
-  return {
-    db,
-    sql: {
-      end: async () => {
-        await client.close();
+  const releaseLock = await acquireDbLock(dataDir);
+  try {
+    const client = new Ve3(dataDir);
+    await client.waitReady;
+    await applyEmbeddedMigrations(client);
+    const db = drizzle2(client, { schema: schema_exports });
+    return {
+      db,
+      sql: {
+        end: async () => {
+          await client.close();
+          releaseLock();
+        }
       }
-    }
+    };
+  } catch (e) {
+    releaseLock();
+    throw e;
+  }
+}
+async function acquireDbLock(dataDir) {
+  const lockPath = `${dataDir}.lock`;
+  const STALE_MS = 6e4;
+  const TIMEOUT_MS = 3e4;
+  const start2 = Date.now();
+  const noop3 = () => {
   };
+  for (; ; ) {
+    try {
+      const fd = (0, import_node_fs4.openSync)(lockPath, "wx");
+      (0, import_node_fs4.writeSync)(fd, `${process.pid} ${Date.now()}`);
+      (0, import_node_fs4.closeSync)(fd);
+      return () => {
+        try {
+          (0, import_node_fs4.unlinkSync)(lockPath);
+        } catch {
+        }
+      };
+    } catch (e) {
+      if (e.code !== "EEXIST") return noop3;
+      try {
+        if (Date.now() - (0, import_node_fs4.statSync)(lockPath).mtimeMs > STALE_MS) {
+          (0, import_node_fs4.unlinkSync)(lockPath);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - start2 > TIMEOUT_MS) return noop3;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
 }
 var EMBEDDED_PGLITE_ASSETS = ["pglite.wasm", "pglite.data", "initdb.wasm"];
 function assertEmbeddedAssetsPresent() {
@@ -89841,6 +89922,34 @@ function renderReport(r) {
   if (r.input.repo) lines.push(`Repo: ${r.input.repo}`);
   if (r.input.service) lines.push(`Service: ${r.input.service}`);
   if (r.input.since) lines.push(`Since: ${r.input.since}`);
+  if (r.behavioral) {
+    lines.push("");
+    lines.push("## Summary");
+    lines.push(r.summary);
+    lines.push("");
+    lines.push(`## Flow${r.behavioral.entry ? ` \u2014 ${r.behavioral.entry.name}` : ""}`);
+    if (r.behavioral.steps.length === 0) {
+      lines.push("(no execution flow could be reconstructed from the source graph)");
+    } else {
+      r.behavioral.steps.slice(0, 20).forEach((s5, i3) => {
+        lines.push(`  ${i3 + 1}. ${s5.name} (${formatSymbolLocation(s5.filePath, s5.startLine, s5.endLine)})`);
+      });
+      if (r.behavioral.steps.length > 20) lines.push(`  \u2026 and ${r.behavioral.steps.length - 20} more`);
+    }
+    if (r.behavioral.externalCalls.length > 0 || r.behavioral.persistence.length > 0) lines.push("");
+    if (r.behavioral.externalCalls.length > 0) lines.push(`External calls: ${r.behavioral.externalCalls.join(", ")}`);
+    if (r.behavioral.persistence.length > 0) lines.push(`Persistence: ${r.behavioral.persistence.join(", ")}`);
+    lines.push("");
+    if (r.nextActions.length > 0) {
+      lines.push("## Next actions");
+      for (const a2 of r.nextActions) lines.push(`- ${a2}`);
+      lines.push("");
+    }
+    lines.push(
+      '\u2014 Behavioral walkthrough, not a fault hunt. Phrase it as a symptom (e.g. "X failing") for an incident investigation.'
+    );
+    return lines.join("\n");
+  }
   lines.push(`Confidence: ${r.confidence.toFixed(2)}`);
   const caveat = runtimeSourceCaveat(r);
   if (caveat) lines.push(`  \u21B3 ${caveat}`);
@@ -91795,19 +91904,21 @@ function seedRole(s5) {
   if (/util|helper/i.test(hay)) return "util";
   return "code";
 }
-function scoreSeed(s5, index2, hintTokens, changedFiles) {
+function scoreSeed(s5, index2, hintTokens, changedFiles, hintHasCode) {
   const hay = `${s5.name} ${s5.filePath}`.toLowerCase();
   let score = 0;
-  if (PREFER.test(hay)) score += 3;
+  if (PREFER.test(hay)) score += hintHasCode ? 0 : 3;
   if (DEMOTE.test(hay)) score -= 3;
   if (isTypeLikeName(s5.name)) score -= 4;
   if (s5.startLine !== void 0 && s5.endLine !== void 0 && s5.endLine - s5.startLine <= 3) {
     score -= 3;
   }
   if (changedFiles !== void 0 && changedFiles.has(s5.filePath)) score += 5;
-  if (/\.(resolver|controller|service)\.[jt]sx?$/i.test(s5.filePath)) score += 2;
+  if (/\.(resolver|controller|service)\.[jt]sx?$/i.test(s5.filePath)) score += hintHasCode ? 0 : 2;
   if (/(^|\/)scripts?\//i.test(s5.filePath)) score -= 2;
-  score += Math.max(0, 5 - index2) * 0.1;
+  score += Math.max(0, 5 - index2) * (hintHasCode ? 0.8 : 0.1);
+  if (s5.score !== void 0) score += s5.score * (hintHasCode ? 8 : 1.5);
+  if (/\.[jt]sx?$/i.test(s5.name)) score -= 5;
   if (hintTokens !== void 0 && hintTokens.length > 0) {
     let hintBoost = 0;
     for (const tok of hintTokens) {
@@ -91820,10 +91931,10 @@ function scoreSeed(s5, index2, hintTokens, changedFiles) {
   }
   return score;
 }
-function rankSeeds(seeds, hintTokens, changedFiles) {
+function rankSeeds(seeds, hintTokens, changedFiles, hintHasCode) {
   return seeds.map((symbol, i3) => ({
     symbol,
-    score: scoreSeed(symbol, i3, hintTokens, changedFiles),
+    score: scoreSeed(symbol, i3, hintTokens, changedFiles, hintHasCode),
     role: seedRole(symbol),
     i: i3
   })).sort((a2, b5) => b5.score === a2.score ? a2.i - b5.i : b5.score - a2.score).map(({ symbol, score, role }) => ({ symbol, score, role }));
@@ -92307,6 +92418,51 @@ function looksExplanatory(hint) {
   }
   return false;
 }
+function looksPerformance(hint) {
+  return /\b(slow|slowness|sluggish|laggy|\blag\b|latency|perf|performance|throughput|degraded|degradation|response\s*time|p9[59])\b/i.test(
+    hint
+  );
+}
+function buildBehavioralWalkthrough(hint, top, ctx, flows) {
+  const shortFile = (f5) => f5.replace(/^.*?((?:src|app|lib|packages)\/.*)$/, "$1");
+  const isNoise = (s5) => /logger|logging|\.log\b|telemetry/i.test(s5.filePath) || /^(forcontext|getlogger|child|debug|info|warn|error|log|trace|tracer)$/i.test(s5.name);
+  const flow = flows.slice().sort((a2, b5) => b5.steps.length - a2.steps.length)[0];
+  const rawSteps = flow && flow.steps.length > 1 ? flow.steps : top ? [top, ...ctx?.callees ?? []] : ctx?.callees ?? [];
+  const steps = rawSteps.filter((s5) => !isNoise(s5));
+  const entry2 = steps[0] ?? top ?? null;
+  const dedup = (xs) => {
+    const seen = /* @__PURE__ */ new Set();
+    return xs.filter((s5) => {
+      const k3 = `${s5.name}:${s5.filePath}`;
+      if (seen.has(k3)) return false;
+      seen.add(k3);
+      return true;
+    });
+  };
+  const PERSIST_RE = /(^|[._])(save|insert|upsert|persist|bulkwrite|find|findone|findmany|aggregate|delete|remove)\b|repositor|\brepo\b|\.model|entity|prisma|mongoose|typeorm|knex|\bdao\b|datasource/i;
+  const EXTERNAL_RE = /(^|[._])(request|publish|enqueue|dispatch|emit|notify)\b|http|axios|\bapi\b|webhook|\bqueue\b|processor|producer|gateway|\.client\b/i;
+  const pool = dedup([...steps, ...ctx?.callees ?? []]).filter((s5) => !isNoise(s5));
+  const persistence = dedup(pool.filter((s5) => PERSIST_RE.test(s5.name) || PERSIST_RE.test(s5.filePath))).slice(0, 6).map((s5) => `${s5.name} (${shortFile(s5.filePath)})`);
+  const persistNames = new Set(persistence.map((p5) => p5.split(" (")[0]));
+  const externalCalls = dedup(
+    pool.filter((s5) => (EXTERNAL_RE.test(s5.name) || EXTERNAL_RE.test(s5.filePath)) && !persistNames.has(s5.name))
+  ).slice(0, 6).map((s5) => `${s5.name} (${shortFile(s5.filePath)})`);
+  const lines = [];
+  if (entry2) {
+    const loc = entry2.startLine ? `${shortFile(entry2.filePath)}:${entry2.startLine}` : shortFile(entry2.filePath);
+    lines.push(`Entry point: \`${entry2.name}\` (${loc}).`);
+  }
+  if (steps.length > 1) {
+    const chain = steps.slice(0, 12).map((s5) => s5.name).join(" \u2192 ");
+    lines.push(`Flow: ${chain}${steps.length > 12 ? " \u2192 \u2026" : ""}${flow ? ` (${flow.steps.length} steps)` : ""}.`);
+  } else if (entry2) {
+    lines.push(`No multi-step execution flow was indexed for \`${entry2.name}\` \u2014 showing its direct calls.`);
+  }
+  if (externalCalls.length > 0) lines.push(`Calls out to: ${externalCalls.join(", ")}.`);
+  if (persistence.length > 0) lines.push(`Persists via: ${persistence.join(", ")}.`);
+  if (lines.length === 0) lines.push("No execution flow could be reconstructed for this query from the source graph.");
+  return { question: hint, entry: entry2, steps, externalCalls, persistence, narrative: lines.join("\n") };
+}
 function formatRegressionCitation(recentChanges, changes, seedFile) {
   const matchesSeed = (f5) => seedFile === void 0 || f5 === seedFile || seedFile.endsWith(f5) || f5.endsWith(seedFile);
   const all = recentChanges?.commits ?? [];
@@ -92366,13 +92522,14 @@ async function investigate(input, deps) {
   const changedFilePaths = recentChanges && recentChanges.changedFiles.length > 0 ? new Set(recentChanges.changedFiles) : void 0;
   const rawSeeds = code ? await code.searchSymbols(hint, 5) : [];
   const hintTokens = [...new Set(tokenize(hint))];
-  const ranked = rankSeeds(rawSeeds, hintTokens, changedFilePaths);
+  const hintHasCode = /\b(?=[A-Z0-9_]*[0-9_])[A-Z][A-Z0-9_]{3,}\b/.test(hint);
+  const ranked = rankSeeds(rawSeeds, hintTokens, changedFilePaths, hintHasCode);
   let seeds = ranked.map((r) => r.symbol);
   let top = seeds[0];
   if (top && code && isTypeLikeName(top.name)) {
     const base2 = executableBaseName(top.name);
     if (base2) {
-      const altTop = rankSeeds(await code.searchSymbols(base2, 5), hintTokens).find(
+      const altTop = rankSeeds(await code.searchSymbols(base2, 5), hintTokens, void 0, hintHasCode).find(
         (r) => !isTypeLikeName(r.symbol.name)
       )?.symbol;
       if (altTop && altTop.id !== top.id) {
@@ -92432,7 +92589,8 @@ async function investigate(input, deps) {
     "slow"
   ]);
   const meaningfulHintTokens = hintTokens.filter((t2) => !GENERIC_HINT_TOKENS.has(t2));
-  const seedIsLowConfidence = top !== void 0 && logReseed === null && meaningfulHintTokens.length > 0 && !meaningfulHintTokens.some((t2) => seedHay.includes(t2));
+  const seedIsLowConfidence = top !== void 0 && logReseed === null && (top.score ?? 0) < 0.5 && // a strong exact-content/colocated source match is authoritative (gap 6)
+  meaningfulHintTokens.length > 0 && !meaningfulHintTokens.some((t2) => seedHay.includes(t2));
   if (!top && !degradedNoSource) {
     const report2 = {
       id: globalThis.crypto.randomUUID(),
@@ -92569,6 +92727,8 @@ async function investigate(input, deps) {
   const directLogEvIds = [];
   const ambientLogEvIds = [];
   const directSignatures = [];
+  const directEvIdByKey = /* @__PURE__ */ new Map();
+  const seedEmittedJoins = [];
   const entityEvIds = [];
   const entitySummaries = [];
   let logsCollected = false;
@@ -92643,13 +92803,17 @@ async function investigate(input, deps) {
           if (relevanceClass === "direct") {
             directLogEvIds.push(ev.id);
             directSignatures.push({ key: s5.key, count: s5.count, message: s5.sampleMessage ?? "" });
+            if (!directEvIdByKey.has(s5.key)) directEvIdByKey.set(s5.key, ev.id);
           } else ambientLogEvIds.push(ev.id);
         }
-        const seedSnippet = ctx?.snippet !== void 0 && ctx.snippet !== null ? ctx.snippet : void 0;
+        const seedSnippet = (ctx?.sourceBody !== void 0 && ctx.sourceBody !== null ? ctx.sourceBody : void 0) ?? (ctx?.snippet !== void 0 && ctx.snippet !== null ? ctx.snippet : void 0);
         const sourceCodes = extractEventCodes(input.hint, top?.name, seedSnippet);
+        const seedEmittedCodes = new Set(
+          seedSnippet !== void 0 ? extractEventCodes(seedSnippet) : []
+        );
         const joinedCodes = new Set(directSignatures.map((d3) => d3.key));
         for (const code2 of sourceCodes) {
-          if (joinedCodes.has(code2)) continue;
+          const alreadyJoined = joinedCodes.has(code2);
           joinedCodes.add(code2);
           try {
             const codeAnalysis = await deps.logs.analyzeErrors({
@@ -92659,6 +92823,21 @@ async function investigate(input, deps) {
             });
             const sig = codeAnalysis.signatures.find((s5) => s5.key === code2);
             if (sig === void 0 || sig.count <= 0) continue;
+            if (alreadyJoined) {
+              if (seedEmittedCodes.has(code2)) {
+                const existingEvId = directEvIdByKey.get(code2);
+                if (existingEvId !== void 0) {
+                  seedEmittedJoins.push({
+                    code: code2,
+                    count: sig.count,
+                    message: sig.sampleMessage ?? "",
+                    evId: existingEvId,
+                    isNew: sig.isNew ?? false
+                  });
+                }
+              }
+              continue;
+            }
             const links = top !== void 0 ? top.startLine !== void 0 && top.startLine > 0 ? { symbolId: top.id, file: top.filePath, line: top.startLine } : { symbolId: top.id, file: top.filePath } : {};
             const ev = mkEv(
               "log",
@@ -92677,7 +92856,8 @@ async function investigate(input, deps) {
                 sampleMessage: sig.sampleMessage ?? null,
                 relevanceClass: "direct",
                 relevanceReason: `exact event_code match to the source signal (${code2})`,
-                crossSignalJoin: true
+                crossSignalJoin: true,
+                seedEmitted: seedEmittedCodes.has(code2)
               },
               links,
               sig.lastSeen || void 0,
@@ -92692,6 +92872,16 @@ async function investigate(input, deps) {
               count: sig.count,
               message: sig.sampleMessage ?? ""
             });
+            if (!directEvIdByKey.has(code2)) directEvIdByKey.set(code2, ev.id);
+            if (seedEmittedCodes.has(code2)) {
+              seedEmittedJoins.push({
+                code: code2,
+                count: sig.count,
+                message: sig.sampleMessage ?? "",
+                evId: ev.id,
+                isNew: sig.isNew ?? false
+              });
+            }
           } catch {
           }
         }
@@ -93277,6 +93467,29 @@ async function investigate(input, deps) {
       metadata: { blastRadius }
     });
   }
+  if (seedEmittedJoins.length > 0 && top && seedEv) {
+    const ordered = [...seedEmittedJoins].sort((a2, b5) => b5.count - a2.count);
+    const lead = ordered[0];
+    if (lead !== void 0) {
+      const sourceEvidenceIds = [
+        .../* @__PURE__ */ new Set([...ordered.map((j3) => j3.evId), seedEv.id])
+      ];
+      const volumeBoost = Math.min(0.1, Math.log10(Math.max(1, lead.count)) * 0.025);
+      const baseScore = clamp015(0.6 + volumeBoost);
+      const msgClause = lead.message ? ` \u2014 "${lead.message.replace(/\s+/g, " ").trim().slice(0, 90)}"` : "";
+      causeInputs.push({
+        id: "cause:seed-emitted-error",
+        title: `Runtime error ${lead.code} (${lead.count}x in Elasticsearch) is raised by ${top.name} \u2014 the likely failure${msgClause}`.slice(
+          0,
+          220
+        ),
+        category: "error-correlation",
+        sourceEvidenceIds,
+        baseScore,
+        metadata: { blastRadius, seedEmitted: true, code: lead.code, count: lead.count }
+      });
+    }
+  }
   if (analysis !== null && analysis.signatures.length > 0 && queueHits.length > 0 && directLogEvIds.length > 0) {
     const firstQueue = queueHits[0];
     const queueLabel = firstQueue !== void 0 ? `"${firstQueue.queueName}" (${firstQueue.producerSymbol ?? "unknown"} -> ${firstQueue.workerSymbol ?? "unknown"})` : "the queue path";
@@ -93395,16 +93608,34 @@ async function investigate(input, deps) {
   const seedDisclaimer = seedIsLowConfidence && top ? `\u26A0 No symbol closely matched "${hint}" \u2014 "${top.name}" is a low-confidence closest match (semantic). Refine with an exact symbol or error code to target precisely. ` : "";
   let summary = headlineCause ? headlineLinked ? `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. Top suspected cause: ${headlineCause.title}.` : `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. No cause is structurally linked to the seed; the strongest co-occurring signal (a lead to verify, not a diagnosis) is: ${headlineCause.title}.` : `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. No dominant suspected cause emerged from the available ${degradedNoSource ? "runtime" : "structural"} evidence.`;
   const hasIncidentSignal = directLogEvIds.length > 0 || latencyMetricEvIds.length > 0 || queueMetricEvIds.length > 0 || dataAnomalyEvIds.length > 0 || queueFailureSignals.length > 0 || findings2.some((f5) => f5.kind === "anomaly") || headlineCause !== void 0;
-  const explanatoryHint = looksExplanatory(hint) && !hasIncidentSignal;
+  const explanatoryHint = looksExplanatory(hint);
+  let behavioral;
   if (explanatoryHint) {
-    const explainTarget = top?.name ?? input.service ?? hint;
-    summary = `${seedDisclaimer}${banner2}"${hint}" reads as a "how does it work" question and no incident signal was found (no error signatures, anomalies, or failing queues). For a focused answer, run \`horus explain ${explainTarget}\`. ${top ? `Investigated ${label} (${area}); the` : "The"} incident sections below are empty by design \u2014 this is not a fault hunt.`;
+    let flowPool = flows;
+    const richestSeedFlow = flows.slice().sort((a2, b5) => b5.steps.length - a2.steps.length)[0];
+    if (code && (richestSeedFlow === void 0 || richestSeedFlow.steps.length <= 1) && ctx?.callers?.length) {
+      const ENTRY_RE = /controller|resolver|route|handler|command|consumer|listener|gateway|cron|scheduler|webhook|middleware/i;
+      const entryCallers = ctx.callers.filter((c4) => ENTRY_RE.test(c4.name) || ENTRY_RE.test(c4.filePath)).slice(0, 3);
+      for (const c4 of entryCallers) {
+        try {
+          flowPool = flowPool.concat(await code.flowsFor(c4.id));
+        } catch {
+        }
+      }
+    }
+    behavioral = buildBehavioralWalkthrough(hint, top, ctx ?? void 0, flowPool);
+    const noisy = hasIncidentSignal ? ' (note: live error signals also exist in this codebase \u2014 rephrase as a symptom like "X failing" for a fault hunt)' : "";
+    summary = `${seedDisclaimer}${banner2}"${hint}" reads as a "how does it work" question \u2014 here is the code path${noisy}:
+
+` + behavioral.narrative;
+  }
+  if (!explanatoryHint && looksPerformance(hint) && deps.metrics == null && seedIsLowConfidence) {
+    summary = `${banner2}"${hint}" reads as a latency/performance question, but no metrics connector (Grafana) is configured \u2014 response-time and error-rate trends can't be assessed from source structure alone${top ? ` (the closest structural match, ${top.name}, is a low-confidence guess, not a diagnosis)` : ""}. Connect a metrics source (\`horus connect grafana\`) and re-run, or name the specific slow operation.`;
   }
   const nextActions = buildNextActions(top, ctx, impact, queueHits, changes, input);
-  if (explanatoryHint) {
-    const explainTarget = top?.name ?? input.service ?? hint;
+  if (explanatoryHint && behavioral?.entry) {
     nextActions.unshift(
-      `This looks like a behavioral question \u2014 run \`horus explain ${explainTarget}\` for a focused walkthrough of how it works.`
+      `Trace the full call graph of the entry point: \`horus explain ${behavioral.entry.name}\`.`
     );
   }
   if (degradedNoSource) {
@@ -93436,6 +93667,7 @@ async function investigate(input, deps) {
     ownership: ownershipEstimate,
     causeChains: causeChains.length > 0 ? causeChains : void 0,
     ...recentChanges !== void 0 ? { recentChanges } : {},
+    ...behavioral !== void 0 ? { behavioral } : {},
     ...degradedNoSource ? { degraded: { sourceIntelligence: false, reason: "source-intelligence host unreachable" } } : {}
   };
   const connectorFlags = deps.connectors ? {
@@ -96906,6 +97138,12 @@ async function runIndex(opts) {
         console.error(import_picocolors3.default.red("horus-source not found on PATH. Install it: pip install horus-source"));
         return 1;
       }
+      try {
+        await assertSourceVersionPinned();
+      } catch (err2) {
+        console.error(import_picocolors3.default.red(`  ${err2.message}`));
+        return 1;
+      }
       if (!isAnalyzed(root)) {
         console.log(import_picocolors3.default.dim("  analyzing with source-intelligence backend (first time \u2014 this can take a while)\u2026"));
         try {
@@ -109867,6 +110105,8 @@ function ensureHostReasonHint(reason) {
   switch (reason) {
     case "source-unavailable":
       return "horus-source is not installed \u2014 install it: pip install horus-source";
+    case "version-mismatch":
+      return "the installed horus-source backend does not match the version Horus is pinned to \u2014 reinstall the pinned version (run `horus status` to see it)";
     case "not-analyzed":
       return "this repo has not been indexed yet \u2014 run: horus index";
     case "bad-url":
@@ -109878,6 +110118,11 @@ function ensureHostReasonHint(reason) {
 async function ensureSourceHost(root, hostUrl, opts = {}) {
   if (await isHostHealthy(hostUrl)) return { ok: true, hostUrl };
   if (!await sourceAvailable()) return { ok: false, reason: "source-unavailable" };
+  try {
+    await assertSourceVersionPinned();
+  } catch {
+    return { ok: false, reason: "version-mismatch" };
+  }
   if (!isAnalyzed(root)) return { ok: false, reason: "not-analyzed" };
   const port = parseHostPort(hostUrl);
   if (port === null) return { ok: false, reason: "bad-url" };
@@ -113331,16 +113576,28 @@ async function runStop(opts) {
   }
 }
 async function stopHost(root, hostUrl) {
-  const alive = await isHostHealthy(hostUrl);
-  if (!alive) {
-    console.log(import_picocolors36.default.dim(`Host ${hostUrl} is already stopped.`));
-    return 0;
-  }
   const port = extractPort(hostUrl);
   if (port === null) {
     console.error(import_picocolors36.default.red(`Cannot determine port from host URL: ${hostUrl}`));
     return 1;
   }
+  const healthy = await isHostHealthy(hostUrl);
+  if (!healthy) {
+    const owned = readSpawnedHost(root);
+    const wrapperAlive = owned !== null && await getProcessInfo(owned.pid) !== null;
+    if (!wrapperAlive) {
+      const res = await stopBackendServerPid(root, port);
+      if (res === "failed") return 1;
+      if (res !== "stopped") console.log(import_picocolors36.default.dim(`Host ${hostUrl} is already stopped.`));
+      await cleanupSpawnedRecord(root);
+      return 0;
+    }
+    console.log(
+      import_picocolors36.default.dim(
+        `Host ${hostUrl} is unreachable but pid ${owned.pid} is still running \u2014 terminating a stuck host.`
+      )
+    );
+  }
   const spawned = readSpawnedHost(root);
   if (spawned === null) {
     console.error(
@@ -113373,21 +113630,18 @@ async function stopHost(root, hostUrl) {
   }
   const info2 = await getProcessInfo(spawned.pid);
   if (info2 === null) {
-    console.log(import_picocolors36.default.dim(`Process pid ${spawned.pid} is no longer running \u2014 already stopped.`));
-    try {
-      await unlinkAsync((0, import_node_path18.join)(root, HORUS_DIR, SPAWNED_HOST_FILE2));
-    } catch {
+    const res = await stopBackendServerPid(root, port);
+    if (res === "failed") return 1;
+    if (res !== "stopped") {
+      console.log(import_picocolors36.default.dim(`Process pid ${spawned.pid} is no longer running \u2014 already stopped.`));
     }
+    await cleanupSpawnedRecord(root);
     return 0;
   }
-  const portStr = String(port);
-  const hostPortRe = new RegExp(
-    `(?:^|\\s)(?:\\S*/)?horus-source\\s+host\\s+--port(?:=|\\s+)${portStr}(?=\\s|$)`
-  );
-  if (!hostPortRe.test(info2.args)) {
+  if (!hostArgvRegex(port).test(info2.args)) {
     console.error(
       import_picocolors36.default.red(
-        `Pid ${spawned.pid} args do not match "horus-source host --port ${portStr}". Got: "${info2.args.slice(0, 120)}". Aborting for safety.`
+        `Pid ${spawned.pid} args do not match "horus-source host --port ${port}". Got: "${info2.args.slice(0, 120)}". Aborting for safety.`
       )
     );
     return 1;
@@ -113440,11 +113694,57 @@ async function stopHost(root, hostUrl) {
       `${import_picocolors36.default.green("\u2713")} Stopped source-intelligence host ` + import_picocolors36.default.dim(`(pid ${spawned.pid}, port ${port})`) + ` for ${root}`
     );
   }
+  if (await stopBackendServerPid(root, port) === "failed") return 1;
+  await cleanupSpawnedRecord(root);
+  return 0;
+}
+function hostArgvRegex(port) {
+  return new RegExp(
+    `(?:^|\\s)(?:\\S*/)?horus-source\\s+host\\s+--port(?:=|\\s+)${String(port)}(?=\\s|$)`
+  );
+}
+async function cleanupSpawnedRecord(root) {
   try {
     await unlinkAsync((0, import_node_path18.join)(root, HORUS_DIR, SPAWNED_HOST_FILE2));
   } catch {
   }
-  return 0;
+}
+async function stopBackendServerPid(root, port) {
+  const rec = readSourceHostPid(root);
+  if (!rec) return "none";
+  if (Number.isFinite(rec.port) && rec.port !== port) return "none";
+  if (rec.repoPath && rec.repoPath !== root) return "none";
+  const info2 = await getProcessInfo(rec.pid);
+  if (info2 === null) return "none";
+  if (!hostArgvRegex(port).test(info2.args)) {
+    console.error(
+      import_picocolors36.default.red(
+        `Backend host pid ${rec.pid} args do not match "horus-source host --port ${port}". Not signalling \u2014 possible stale source/host.json or PID reuse.`
+      )
+    );
+    return "failed";
+  }
+  try {
+    process.kill(rec.pid, "SIGTERM");
+  } catch (err2) {
+    if (err2.code === "ESRCH") return "stopped";
+    console.error(import_picocolors36.default.red(`Failed to signal pid ${rec.pid}: ${err2.message}`));
+    return "failed";
+  }
+  const deadline = Date.now() + STOP_WAIT_MS;
+  while (Date.now() < deadline) {
+    await sleep(STOP_POLL_MS);
+    if (await getProcessInfo(rec.pid) === null) {
+      console.log(
+        `${import_picocolors36.default.green("\u2713")} Stopped source-intelligence host ` + import_picocolors36.default.dim(`(pid ${rec.pid}, port ${port})`) + ` for ${root}`
+      );
+      return "stopped";
+    }
+  }
+  console.error(
+    import_picocolors36.default.red(`Host pid ${rec.pid} did not exit within ${STOP_WAIT_MS / 1e3}s after SIGTERM.`)
+  );
+  return "failed";
 }
 async function stopAll() {
   const registry2 = readRegistry();
@@ -113458,8 +113758,10 @@ async function stopAll() {
   for (const [name2, entry2] of projects2) {
     const hostUrl = readSourceHostUrl(entry2.root);
     if (!hostUrl) continue;
-    const alive = await isHostHealthy(hostUrl);
-    if (!alive) continue;
+    const healthy = await isHostHealthy(hostUrl);
+    if (!healthy && readSpawnedHost(entry2.root) === null && readSourceHostPid(entry2.root) === null) {
+      continue;
+    }
     console.log(`  Stopping ${import_picocolors36.default.bold(name2)} ${import_picocolors36.default.dim(`(${hostUrl})`)}`);
     const code = await stopHost(entry2.root, hostUrl);
     if (code === 0) stopped++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merittdev/horus",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Local-first, source-aware production-incident investigation engine",
   "type": "module",
   "bin": {