@merittdev/horus 0.3.1 → 0.4.1

package/dist/index.cjs

@@ -57239,7 +57239,7 @@ init_cjs_shims();
 
 // ../../packages/core/src/version.ts
 init_cjs_shims();
-var HORUS_VERSION = true ? "0.3.1" : "dev";
+var HORUS_VERSION = true ? "0.4.1" : "dev";
 var PINNED_SOURCE_VERSION = "1.1.1";
 
 // ../../packages/core/src/evidence.ts
@@ -63804,6 +63804,11 @@ init_cjs_shims();
 function classifyAnomaly(kind, cmp, opts) {
   const spike = opts?.spike ?? 1.5;
   const drop = opts?.drop ?? 0.67;
+  const NEAR_ZERO = 1e-9;
+  if (cmp.baselineAvg <= NEAR_ZERO && cmp.currentAvg > 0) {
+    const floor2 = kind === "queue" ? 1 : kind === "latency" ? 0.05 : kind === "error-rate" ? 5e-3 : 0;
+    if (cmp.currentAvg < floor2) return "none";
+  }
   if (kind === "latency" && cmp.ratio >= spike) return "latency-spike";
   if (kind === "queue" && (cmp.ratio >= spike || cmp.currentAvg > cmp.baselineAvg) && cmp.delta > 0) {
     return "queue-growth";
@@ -63947,10 +63952,10 @@ var GrafanaMetricsProvider = class {
     const queryPanels = async (panels) => {
       const results = [];
       for (const panel of panels) {
-        signal?.throwIfAborted();
+        if (signal?.aborted) return results;
         const panelMatchSrc = hint !== void 0 && hint !== "" ? findMatchSource(panel, hint) : null;
         for (const rawExpr of panel.exprs) {
-          signal?.throwIfAborted();
+          if (signal?.aborted) return results;
           const expr = sanitizeExpr(rawExpr);
           if (expr === null) continue;
           try {
@@ -63976,7 +63981,7 @@ var GrafanaMetricsProvider = class {
             ).map((f) => ({ ...f, matchSource: panelMatchSrc }));
             results.push(...findings2);
           } catch (err) {
-            if (signal?.aborted) throw signal.reason ?? err;
+            if (signal?.aborted) return results;
             continue;
           }
         }
@@ -76655,6 +76660,16 @@ function correlate(evidence2) {
 init_cjs_shims();
 var PREFER = /resolver|controller|\bservice\b|route|router|handler|gateway|processor|worker|consumer|repository|usecase|use-case|endpoint/i;
 var DEMOTE = /\butil|helper|\bscript|backfill|legacy|migration|seeder|fixture|\bmock\b|\btest\b|\bspec\b/i;
+var TYPE_SUFFIX = /(Result|Input|Response|Payload|Args|Dto|Props|Edge|Connection)$/;
+var INTERFACE_PREFIX = /^I(?=[A-Z][a-z])/;
+var TYPE_LIKE_NAME = new RegExp(`(?:${TYPE_SUFFIX.source})|(?:${INTERFACE_PREFIX.source})`);
+function isTypeLikeName(name) {
+  return TYPE_LIKE_NAME.test(name);
+}
+function executableBaseName(name) {
+  const stripped = name.replace(TYPE_SUFFIX, "").replace(INTERFACE_PREFIX, "");
+  return stripped !== name && stripped.length >= 4 ? stripped : null;
+}
 function seedRole(s) {
   const hay = `${s.name} ${s.filePath}`;
   if (/\.resolver\.|resolver/i.test(hay)) return "resolver";
@@ -76667,11 +76682,16 @@ function seedRole(s) {
   if (/util|helper/i.test(hay)) return "util";
   return "code";
 }
-function scoreSeed(s, index2, hintTokens) {
+function scoreSeed(s, index2, hintTokens, changedFiles) {
   const hay = `${s.name} ${s.filePath}`.toLowerCase();
   let score = 0;
   if (PREFER.test(hay)) score += 3;
   if (DEMOTE.test(hay)) score -= 3;
+  if (isTypeLikeName(s.name)) score -= 4;
+  if (s.startLine !== void 0 && s.endLine !== void 0 && s.endLine - s.startLine <= 3) {
+    score -= 3;
+  }
+  if (changedFiles !== void 0 && changedFiles.has(s.filePath)) score += 5;
   if (/\.(resolver|controller|service)\.[jt]sx?$/i.test(s.filePath)) score += 2;
   if (/(^|\/)scripts?\//i.test(s.filePath)) score -= 2;
   score += Math.max(0, 5 - index2) * 0.1;
@@ -76687,8 +76707,13 @@ function scoreSeed(s, index2, hintTokens) {
   }
   return score;
 }
-function rankSeeds(seeds, hintTokens) {
-  return seeds.map((symbol, i) => ({ symbol, score: scoreSeed(symbol, i, hintTokens), role: seedRole(symbol), i })).sort((a, b2) => b2.score === a.score ? a.i - b2.i : b2.score - a.score).map(({ symbol, score, role }) => ({ symbol, score, role }));
+function rankSeeds(seeds, hintTokens, changedFiles) {
+  return seeds.map((symbol, i) => ({
+    symbol,
+    score: scoreSeed(symbol, i, hintTokens, changedFiles),
+    role: seedRole(symbol),
+    i
+  })).sort((a, b2) => b2.score === a.score ? a.i - b2.i : b2.score - a.score).map(({ symbol, score, role }) => ({ symbol, score, role }));
 }
 
 // ../../packages/engine/src/normalize.ts
@@ -76984,6 +77009,17 @@ function clamp015(n) {
   if (n > 1) return 1;
   return n;
 }
+function confidenceCeilingForCause(score) {
+  const s = clamp015(score);
+  if (s < 0.2) return 0.6;
+  if (s < 0.5) {
+    return 0.6 + (s - 0.2) / (0.5 - 0.2) * (0.78 - 0.6);
+  }
+  if (s < 0.85) {
+    return 0.78 + (s - 0.5) / (0.85 - 0.5) * (1 - 0.78);
+  }
+  return 1;
+}
 function relevanceForKind(kind) {
   switch (kind) {
     case "symbol":
@@ -77022,13 +77058,36 @@ function logWindowFrom(since) {
   return new Date(now - 7 * 864e5).toISOString();
 }
 function classifyLogRelevance(sigKey, sigServices, seedTerms, inputService) {
-  if (seedTerms.length === 0) {
-    return { relevanceClass: "direct", relevanceReason: "no seed context \u2014 included by default" };
+  const GENERIC_TERMS = /* @__PURE__ */ new Set([
+    "error",
+    "errors",
+    "err",
+    "fail",
+    "failed",
+    "failing",
+    "failure",
+    "exception",
+    "exceptions",
+    "crash",
+    "crashing",
+    "issue",
+    "problem",
+    "slow",
+    "timeout",
+    "broken",
+    "down",
+    "production",
+    "prod",
+    "staging"
+  ]);
+  const domainTerms = seedTerms.filter((t) => !GENERIC_TERMS.has(t));
+  if (domainTerms.length === 0) {
+    return { relevanceClass: "direct", relevanceReason: "no specific seed context \u2014 included by default" };
   }
   const keyTokens = tokenize(sigKey);
   const serviceTokens = sigServices.flatMap((s) => tokenize(s));
   const combined = [...keyTokens, ...serviceTokens];
-  const matchingTerms = seedTerms.filter(
+  const matchingTerms = domainTerms.filter(
     (t) => combined.some((c) => c.includes(t) || t.includes(c))
   );
   if (matchingTerms.length > 0) {
@@ -77108,6 +77167,40 @@ function looksDiffable(since) {
   if (/^\d+[smhd]$/i.test(s)) return false;
   return /^[A-Za-z0-9._/~^-]+$/.test(s);
 }
+function looksExplanatory(hint) {
+  const h = hint.trim();
+  if (h.length === 0) return false;
+  if (/\b(how|what|why|when|where)\b.*\b(work|works|working|do|does|done|happen|happens|flow|flows|behave|called|invoked|triggered|used)\b/i.test(h)) {
+    return true;
+  }
+  if (/^\s*(how|what|why|when|where|explain|describe|walk\s+me\s+through|tell\s+me\s+(?:about|how))\b/i.test(h)) {
+    return true;
+  }
+  return false;
+}
+function formatRegressionCitation(recentChanges, changes) {
+  const commits = (recentChanges?.commits ?? []).slice(0, 2);
+  const commitParts = commits.map((c) => {
+    const sha = c.shortSha || c.sha.slice(0, 7);
+    const subject = (c.subject ?? "").replace(/\s+/g, " ").trim();
+    return subject ? `${sha} "${subject.slice(0, 50)}"` : sha;
+  });
+  const commitClause = commitParts.length > 0 ? ` (${commitParts.join(", ")})` : "";
+  const modified = changes?.modified ?? [];
+  const symbolNames = [];
+  for (const m of modified) {
+    const name = m.after?.name ?? m.before?.name;
+    if (name && !symbolNames.includes(name)) symbolNames.push(name);
+    if (symbolNames.length >= 3) break;
+  }
+  let symbolClause = "";
+  if (symbolNames.length > 0) {
+    const shown = symbolNames.join(", ");
+    const more = modified.length > symbolNames.length ? ", \u2026" : "";
+    symbolClause = ` touched ${shown}${more}`;
+  }
+  return { commitClause, symbolClause };
+}
 async function investigate(input, deps) {
   const { code, db } = deps;
   const hint = input.hint.trim();
@@ -77129,11 +77222,31 @@ async function investigate(input, deps) {
     return ev;
   }
   const degradedNoSource = !code;
+  let recentChanges;
+  if (deps.repoPath && input.since) {
+    try {
+      recentChanges = await collectGitChanges({ repoPath: deps.repoPath, since: input.since });
+    } catch {
+    }
+  }
+  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);
+  const ranked = rankSeeds(rawSeeds, hintTokens, changedFilePaths);
   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(
+        (r) => !isTypeLikeName(r.symbol.name)
+      )?.symbol;
+      if (altTop && altTop.id !== top.id) {
+        seeds = [altTop, ...seeds.filter((s) => s.id !== altTop.id)];
+        top = altTop;
+      }
+    }
+  }
   let logReseed = null;
   if (!top && !degradedNoSource) {
     logReseed = await reseedFromLogs(hint, input, deps);
@@ -77142,6 +77255,50 @@ async function investigate(input, deps) {
       top = seeds[0];
     }
   }
+  const seedHay = top ? `${top.name} ${top.filePath}`.toLowerCase() : "";
+  const GENERIC_HINT_TOKENS = /* @__PURE__ */ new Set([
+    "service",
+    "services",
+    "controller",
+    "controllers",
+    "resolver",
+    "resolvers",
+    "worker",
+    "workers",
+    "repository",
+    "provider",
+    "module",
+    "manager",
+    "util",
+    "utils",
+    "helper",
+    "handler",
+    "error",
+    "errors",
+    "exception",
+    "exceptions",
+    "fail",
+    "failed",
+    "failing",
+    "failure",
+    "throw",
+    "throwing",
+    "thrown",
+    "fatal",
+    "crash",
+    "crashing",
+    "timeout",
+    "production",
+    "prod",
+    "staging",
+    "application",
+    "issue",
+    "problem",
+    "broken",
+    "slow"
+  ]);
+  const meaningfulHintTokens = hintTokens.filter((t) => !GENERIC_HINT_TOKENS.has(t));
+  const seedIsLowConfidence = top !== void 0 && logReseed === null && meaningfulHintTokens.length > 0 && !meaningfulHintTokens.some((t) => seedHay.includes(t));
   if (!top && !degradedNoSource) {
     const report2 = {
       id: globalThis.crypto.randomUUID(),
@@ -77166,13 +77323,6 @@ async function investigate(input, deps) {
     if (persistedId2) report2.id = persistedId2;
     return report2;
   }
-  let recentChanges;
-  if (deps.repoPath && input.since) {
-    try {
-      recentChanges = await collectGitChanges({ repoPath: deps.repoPath, since: input.since });
-    } catch {
-    }
-  }
   let label = input.service ?? hint;
   let seedLoc = "";
   let ctx = null;
@@ -77284,6 +77434,7 @@ async function investigate(input, deps) {
   const logEvIds = [];
   const directLogEvIds = [];
   const ambientLogEvIds = [];
+  const directSignatures = [];
   const entityEvIds = [];
   const entitySummaries = [];
   let logsCollected = false;
@@ -77319,11 +77470,12 @@ async function investigate(input, deps) {
           }
           const svc = s.services.length > 0 ? ` \xB7 ${s.services.slice(0, 3).join(", ")}` : "";
           const tagStr = tags.length > 0 ? ` [${tags.join(", ")}]` : "";
+          const msgStr = s.sampleMessage ? ` \u2014 "${s.sampleMessage.replace(/\s+/g, " ").trim().slice(0, 90)}"` : "";
           const ev = mkEv(
             "log",
-            `Error ${s.key}: ${s.count}x (first ${shortTs(s.firstSeen)}, last ${shortTs(s.lastSeen)})${svc}${tagStr}`.slice(
+            `Error ${s.key}: ${s.count}x (first ${shortTs(s.firstSeen)}, last ${shortTs(s.lastSeen)})${svc}${tagStr}${msgStr}`.slice(
               0,
-              180
+              220
             ),
             {
               signature: s.key,
@@ -77346,8 +77498,10 @@ async function investigate(input, deps) {
           if (s.isNew) ev.isNew = s.isNew;
           if (typeof s.ratio === "number" && Number.isFinite(s.ratio)) ev.ratio = s.ratio;
           logEvIds.push(ev.id);
-          if (relevanceClass === "direct") directLogEvIds.push(ev.id);
-          else ambientLogEvIds.push(ev.id);
+          if (relevanceClass === "direct") {
+            directLogEvIds.push(ev.id);
+            directSignatures.push({ key: s.key, count: s.count, message: s.sampleMessage ?? "" });
+          } else ambientLogEvIds.push(ev.id);
         }
         if (typeof deps.logs.aggregateErrors === "function") {
           const sigForEntities = analysis.signatures.find(
@@ -77400,6 +77554,8 @@ async function investigate(input, deps) {
   let stateAnalysis = null;
   const stateEvIds = [];
   const stateCollections = /* @__PURE__ */ new Set();
+  const dataAnomalyEvIds = [];
+  const dataAnomalyCollections = [];
   if (deps.mongo) {
     try {
       stateAnalysis = await deps.mongo.analyzeState();
@@ -77408,6 +77564,10 @@ async function investigate(input, deps) {
         const ev = mkEv("state", s.title, s.payload, {}, s.timestamp, s.relevance);
         stateEvIds.push(ev.id);
         stateCollections.add(s.collection);
+        if (s.kind === "anomaly") {
+          dataAnomalyEvIds.push(ev.id);
+          dataAnomalyCollections.push(s.collection);
+        }
       }
     } catch {
       stateAnalysis = null;
@@ -77434,6 +77594,7 @@ async function investigate(input, deps) {
   const queueRuntimeEvIdsByQueue = /* @__PURE__ */ new Map();
   const queueBacklogEvIdsByQueue = /* @__PURE__ */ new Map();
   const queueStarvationEvIdsByQueue = /* @__PURE__ */ new Map();
+  const queueFailureSignals = [];
   if (deps.queue) {
     try {
       const staticNames = [...new Set(queueHits.map((e) => e.queueName))];
@@ -77457,6 +77618,18 @@ async function investigate(input, deps) {
           st.push(ev.id);
           queueStarvationEvIdsByQueue.set(s.queueName, st);
         }
+        if (s.kind === "failed-breakdown") {
+          const p = s.payload;
+          if (typeof p.topReason === "string") {
+            queueFailureSignals.push({
+              reason: p.topReason,
+              queueName: s.queueName,
+              evId: ev.id,
+              count: typeof p.topCount === "number" ? p.topCount : 0,
+              stale: p.topStale === true
+            });
+          }
+        }
       }
     } catch {
       queueRuntimeState = null;
@@ -77507,8 +77680,14 @@ async function investigate(input, deps) {
         const panelLower = f.panelTitle.toLowerCase();
         const labelVals = Object.values(f.labels).map((v) => v.toLowerCase());
         if (f.anomaly === "latency-spike" || f.anomaly === "error-rate-change") {
-          const relevant = serviceFilter.length > 0 && (panelLower.includes(serviceFilter) || labelVals.some((v) => v.includes(serviceFilter)));
-          if (relevant) latencyMetricEvIds.push(ev.id);
+          const matchesService = serviceFilter.length > 0 && (panelLower.includes(serviceFilter) || labelVals.some((v) => v.includes(serviceFilter)));
+          const hintIsPerf = /\b(latenc|slow|spike|perf|throughput|duration|p9[5-9]|timeout|response\s*time|degrad)/i.test(
+            hint
+          );
+          const matchesHint = serviceFilter.length === 0 && hintIsPerf && hintTokens.some(
+            (t) => t.length >= 4 && (panelLower.includes(t) || labelVals.some((v) => v.includes(t)))
+          );
+          if (matchesService || matchesHint) latencyMetricEvIds.push(ev.id);
         } else if (f.anomaly === "queue-growth") {
           const panelNorm = f.panelTitle.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
           const labelNorms = Object.values(f.labels).map(
@@ -77806,19 +77985,21 @@ async function investigate(input, deps) {
     const gitChangedFiles = recentChanges?.changedFiles ?? [];
     const seedFile = top?.filePath;
     const seedInChanges = seedFile !== void 0 && gitChangedFiles.length > 0 && gitChangedFiles.some((f) => f === seedFile || seedFile.endsWith(f) || f.endsWith(seedFile));
+    const citation = formatRegressionCitation(recentChanges, changes);
     causeInputs.push({
       id: "cause:deployment-regression",
-      title: top ? `Recent change to ${top.name} in ${input.since}..HEAD may have introduced the regression` : `Recent changes in ${input.since}..HEAD may have introduced the regression`,
+      title: top ? `Recent change${citation.commitClause} to ${top.name}${citation.symbolClause} in ${input.since}..HEAD may have introduced the regression` : `Recent change${citation.commitClause}${citation.symbolClause} in ${input.since}..HEAD may have introduced the regression`,
       category: "deployment-regression",
       sourceEvidenceIds: [changeEvId, ...seedEv ? [seedEv.id] : []],
       baseScore: clamp015((seedInChanges ? 0.45 : 0.25) + (queueHits.length > 0 ? 0.05 : 0)),
       metadata: { blastRadius }
     });
   }
-  if (top && impactEv && seedEv && impact && impact.affected > 0) {
+  const MIN_FANOUT_FOR_CAUSE = 3;
+  if (top && impactEv && seedEv && impact && impact.affected >= MIN_FANOUT_FOR_CAUSE) {
     causeInputs.push({
       id: "cause:blast-radius",
-      title: `${top.name} sits on a high-fan-out path (${impact.affected} affected) and may propagate the fault`,
+      title: `${top.name} has wide code reach (${impact.affected} dependent symbols) and may propagate the fault`,
       category: "blast-radius",
       sourceEvidenceIds: [impactEv.id, seedEv.id],
       baseScore: clamp015(0.15 + (queueHits.length > 0 ? 0.05 : 0)),
@@ -77828,16 +78009,62 @@ async function investigate(input, deps) {
   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";
-    const topSig = analysis.signatures[0];
+    const directTotal = directSignatures.reduce((sum, d) => sum + d.count, 0);
+    const directTop = directSignatures[0];
     causeInputs.push({
       id: "cause:error-correlation",
-      title: `Runtime errors (${analysis.totalErrors}${topSig ? `, top ${topSig.key}` : ""}) correlate with the implicated queue path ${queueLabel}`,
+      title: `Runtime errors (${directTotal}${directTop ? `, top ${directTop.key}` : ""}) directly linked to the implicated queue path ${queueLabel}`,
       category: "error-correlation",
       sourceEvidenceIds: directLogEvIds.slice(0, 3),
       baseScore: 0.3,
       metadata: { blastRadius }
     });
   }
+  const INFRA_RE = /\b(ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ECONNRESET|getaddrinfo|socket hang up|connection (?:refused|reset|timed out)|network (?:error|timeout)|DNS)\b/i;
+  const infraSig = directSignatures.find((d) => INFRA_RE.test(d.message));
+  const queueHitNames = new Set(queueHits.map((e) => e.queueName.toLowerCase()));
+  const infraQueue = queueFailureSignals.find((q) => {
+    if (!INFRA_RE.test(q.reason)) return false;
+    if (queueHitNames.has(q.queueName.toLowerCase())) return true;
+    const qTokens = new Set(tokenize(q.queueName));
+    return hintTokens.some((t) => t.length >= 3 && qTokens.has(t));
+  });
+  if (infraSig) {
+    causeInputs.push({
+      id: "cause:dependency-failure",
+      title: `Dependency/network failure: ${infraSig.count}x ${infraSig.key} \u2014 "${infraSig.message.replace(/\s+/g, " ").trim().slice(0, 100)}"`,
+      category: "infrastructure",
+      sourceEvidenceIds: directLogEvIds.slice(0, 3),
+      baseScore: 0.5,
+      metadata: { blastRadius }
+    });
+  } else if (infraQueue) {
+    causeInputs.push({
+      id: "cause:dependency-failure",
+      title: `Dependency/network failure on queue ${infraQueue.queueName}: ${infraQueue.count} failed job(s) \u2014 "${infraQueue.reason.replace(/\s+/g, " ").trim().slice(0, 100)}"${infraQueue.stale ? " (stale \u2014 reflects a past run)" : ""}`,
+      category: "infrastructure",
+      sourceEvidenceIds: [infraQueue.evId],
+      // A stale-only queue failure is weaker than a live error, but still the best
+      // explanation — and far better than a co-occurring stale-collection guess.
+      baseScore: infraQueue.stale ? 0.34 : 0.5,
+      metadata: { blastRadius }
+    });
+  }
+  if (dataAnomalyEvIds.length > 0) {
+    const collections = [...new Set(dataAnomalyCollections)];
+    const example = collections[0];
+    causeInputs.push({
+      id: "cause:data-state-anomaly",
+      // Co-occurring, NOT asserted as the root cause: the stale collection is selected by
+      // hint relevance, not proven reachable from the seed's call graph, so claiming it is
+      // the cause mislead on e.g. a Shopify-fulfillment error citing unrelated gaia sync logs.
+      title: `Data-state anomaly (co-occurring): ${collections.length} collection(s) hold records in a failed/stale state${example ? ` (e.g. ${example})` : ""} \u2014 verify whether it relates to this failure`,
+      category: "data-state-anomaly",
+      sourceEvidenceIds: dataAnomalyEvIds.slice(0, 3),
+      baseScore: 0.22,
+      metadata: { blastRadius }
+    });
+  }
   if (latencyMetricEvIds.length > 0) {
     causeInputs.push({
       id: "cause:metric-latency",
@@ -77876,20 +78103,34 @@ async function investigate(input, deps) {
     evidence2,
     ambientLogEvIds.length > 0 ? new Set(ambientLogEvIds) : void 0
   );
-  const seedResolved = seeds.length > 0 ? 1 : 0;
+  const seedResolved = seeds.length === 0 ? 0 : seedIsLowConfidence ? 0.3 : 1;
   const confidence = clamp015(0.5 * evidenceConfidence + 0.5 * seedResolved);
   const area = ctx?.community?.name ?? top?.filePath ?? (input.service ?? "runtime evidence");
   const topCause = rankedCauses[0];
+  const headlineCause = topCause && topCause.finalScore >= 0.2 ? topCause : void 0;
   const banner2 = degradedNoSource ? "Runtime-only (source intelligence unavailable). " : "";
   const scope = top ? `resolved to ${label} (${area})` : `over runtime evidence (${area})`;
-  const summary = topCause ? `${banner2}Investigation of "${hint}" ${scope}. Top suspected cause: ${topCause.title}.` : `${banner2}Investigation of "${hint}" ${scope}. No dominant suspected cause emerged from the available ${degradedNoSource ? "runtime" : "structural"} evidence.`;
+  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 ? `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. Top suspected cause: ${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((f) => f.kind === "anomaly") || headlineCause !== void 0;
+  const explanatoryHint = looksExplanatory(hint) && !hasIncidentSignal;
+  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.`;
+  }
   const nextActions = buildNextActions(top, ctx, impact, queueHits, changes, input);
+  if (explanatoryHint) {
+    const explainTarget = top?.name ?? input.service ?? hint;
+    nextActions.unshift(
+      `This looks like a behavioral question \u2014 run \`horus explain ${explainTarget}\` for a focused walkthrough of how it works.`
+    );
+  }
   if (degradedNoSource) {
     nextActions.unshift(
       "Source intelligence was unavailable \u2014 run `horus index` to enable code-aware analysis, then re-run for a full investigation."
     );
   }
-  if (ownershipEstimate?.likelyMaintainer) {
+  if (ownershipEstimate?.likelyMaintainer && !seedIsLowConfidence) {
     nextActions.unshift(
       `Route to likely maintainer: ${ownershipEstimate.likelyMaintainer} (${Math.round(ownershipEstimate.maintainerShare * 100)}% of commits to ${ownershipEstimate.file ?? top?.filePath ?? "the implicated file"})`
     );
@@ -77939,6 +78180,9 @@ async function investigate(input, deps) {
   const gapAnalysis = detectMissingEvidence(report, connectorFlags);
   report.gapAnalysis = gapAnalysis;
   report.confidence = Math.min(report.confidence, gapAnalysis.confidenceCeiling);
+  if (seedIsLowConfidence) report.confidence = Math.min(report.confidence, 0.45);
+  const topCauseScore = report.suspectedCauses[0]?.finalScore ?? 0;
+  report.confidence = Math.min(report.confidence, confidenceCeilingForCause(topCauseScore));
   report.nextActions.push(...gapNextActions(gapAnalysis.gaps));
   report.sourceStatus = buildRuntimeSourceStatus(evidence2, connectorFlags);
   const persistedId = await persist(db, input, report);
@@ -79289,14 +79533,17 @@ function refineInvestigation(r, directive) {
       }
     }
     const recognizedList = ALL_TOPICS.join(", ");
-    const note2 = "No specific topic directive recognized. Recognized topics: " + recognizedList + '. Example usage: "focus on queue behavior", "ignore deployment changes".';
+    const looksLikeQuestion = /\?|\b(where|which|what|how|why|when|does|do|is|are|can|should)\b/i.test(
+      directive
+    );
+    const note2 = looksLikeQuestion ? `This question can't be answered from the saved evidence \u2014 \`horus ask\` reuses the report and does not run a new source/runtime lookup. For a fresh answer run:  horus investigate "${directive.slice(0, 80)}". (To filter the saved evidence instead, use a topic: ${recognizedList}.)` : "No specific topic directive recognized. Recognized topics: " + recognizedList + '. Example usage: "focus on queue behavior", "ignore deployment changes".';
     return {
       directive,
       mode: "none",
       topics,
       hypotheses: r.hypotheses,
       suspectedCauses: r.suspectedCauses,
-      evidence: r.evidence,
+      evidence: looksLikeQuestion ? [] : r.evidence,
       note: note2
     };
   }
@@ -81012,24 +81259,98 @@ var PROCESSOR_RE = /@Processor\(\s*['"]([^'"]+)['"][^)]*\)\s*(?:@\w+[^\n]*\s*)*e
 var CONST_DECL_RE = /(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*['"]([^'"]+)['"]/g;
 var NEW_BULL_RE = /(?:(\w+)\s*[:=]\s*)?new\s+(Queue|Worker)\s*(?:<[^>]*>)?\s*\(\s*(['"][^'"]+['"]|[A-Za-z_$][\w$.]*)/g;
 var QUEUE_NAME_CONST_RE = /(?:export\s+)?const\s+([A-Za-z_$][\w$]*(?:QUEUE|Queue)[\w$]*)\s*=\s*['"]([^'"]+)['"]/g;
+var ENUM_DECL_RE = /(?:export\s+)?(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)\s*\{([^}]*)\}/g;
+var ENUM_MEMBER_RE = /([A-Za-z_$][\w$]*)\s*(?:=\s*(['"])([^'"]*)\2)?/g;
+var OBJECT_VALUES_LOOP_RE = /for\s*\(\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s+of\s+Object\.values\(\s*([A-Za-z_$][\w$]*)\s*\)/g;
+var DISPATCH_ENTRY_RE = /\[\s*([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)\s*\]\s*:\s*([^,}]+)/g;
 function baseName(filePath) {
   const parts = filePath.split("/");
   const last = parts[parts.length - 1] ?? filePath;
   return last.replace(/\.[jt]sx?$/, "");
 }
-function resolveArg(raw, constMap) {
+function buildEnumMap(contents) {
+  const enums = /* @__PURE__ */ new Map();
+  for (const content of contents) {
+    for (const decl of content.matchAll(ENUM_DECL_RE)) {
+      const enumName = decl[1];
+      const body = decl[2] ?? "";
+      if (!enumName || enums.has(enumName)) continue;
+      const members = [];
+      for (const m of body.matchAll(ENUM_MEMBER_RE)) {
+        const member = m[1];
+        if (!member) continue;
+        const value = m[3] !== void 0 ? m[3] : member;
+        members.push({ member, value });
+      }
+      if (members.length) enums.set(enumName, members);
+    }
+  }
+  return enums;
+}
+function resolveEnumMember(ref, enums) {
+  const dot = ref.indexOf(".");
+  if (dot < 0) return null;
+  const enumName = ref.slice(0, dot);
+  const member = ref.slice(dot + 1);
+  const members = enums.get(enumName);
+  if (!members) return null;
+  return members.find((e) => e.member === member)?.value ?? null;
+}
+function resolveArg(raw, constMap, enums, loopVarEnums) {
   const arg = raw.trim();
   if (arg.startsWith('"') || arg.startsWith("'")) {
-    return arg.slice(1, -1);
+    return [arg.slice(1, -1)];
+  }
+  if (arg.includes(".")) {
+    const value = resolveEnumMember(arg, enums);
+    return value !== null ? [value] : [];
+  }
+  const loopEnum = loopVarEnums.get(arg);
+  if (loopEnum) {
+    const members = enums.get(loopEnum);
+    if (members) return members.map((e) => e.value);
+  }
+  const constValue = constMap.get(arg);
+  return constValue !== void 0 ? [constValue] : [];
+}
+function loopVarEnumsFor(content) {
+  const map2 = /* @__PURE__ */ new Map();
+  for (const m of content.matchAll(OBJECT_VALUES_LOOP_RE)) {
+    const loopVar = m[1];
+    const enumName = m[2];
+    if (loopVar && enumName) map2.set(loopVar, enumName);
   }
-  return constMap.get(arg) ?? null;
+  return map2;
+}
+function extractDispatchHandlers(content, enums) {
+  const out = [];
+  for (const m of content.matchAll(DISPATCH_ENTRY_RE)) {
+    const enumName = m[1];
+    const member = m[2];
+    const rhs = (m[3] ?? "").trim();
+    if (!enumName || !member) continue;
+    const value = resolveEnumMember(`${enumName}.${member}`, enums);
+    if (value === null) continue;
+    const handler = handlerSymbolFromExpr(rhs);
+    if (handler) out.push({ value, handler });
+  }
+  return out;
+}
+function handlerSymbolFromExpr(expr) {
+  const call = expr.match(/([A-Za-z_$][\w$]*)\s*\(/);
+  if (call?.[1]) return call[1];
+  const member = expr.match(/(?:[A-Za-z_$][\w$]*\.)+([A-Za-z_$][\w$]*)/);
+  if (member?.[1]) return member[1];
+  const ident = expr.match(/^([A-Za-z_$][\w$]*)$/);
+  if (ident?.[1]) return ident[1];
+  return null;
 }
 function extractQueueGraph(input) {
-  const constMap = /* @__PURE__ */ new Map();
   const allContent = [
     ...input.producerClasses.map((p) => p.content),
     ...input.workerFiles.map((w) => w.content)
   ];
+  const constMap = /* @__PURE__ */ new Map();
   for (const content of allContent) {
     for (const m of content.matchAll(CONST_DECL_RE)) {
       const ident = m[1];
@@ -81037,17 +81358,30 @@ function extractQueueGraph(input) {
       if (ident && value && !constMap.has(ident)) constMap.set(ident, value);
     }
   }
+  const enums = buildEnumMap(allContent);
+  const dispatchHandlers = [];
+  for (const unit of [...input.producerClasses, ...input.workerFiles]) {
+    const file = "filePath" in unit ? unit.filePath : "";
+    for (const h of extractDispatchHandlers(unit.content, enums)) {
+      dispatchHandlers.push({ value: h.value, handler: h.handler, file });
+    }
+  }
   const producers = [];
   for (const pc47 of input.producerClasses) {
+    const loopVarEnums = loopVarEnumsFor(pc47.content);
     for (const m of pc47.content.matchAll(INJECT_QUEUE_RE)) {
       const queue = m[1] ?? "";
       if (queue) producers.push({ queue, symbol: pc47.name, file: pc47.filePath });
     }
     for (const m of pc47.content.matchAll(NEW_BULL_RE)) {
       if (m[2] !== "Queue") continue;
-      const queue = resolveArg(m[3] ?? "", constMap);
-      if (queue) {
-        producers.push({ queue, symbol: (m[1] ?? pc47.name) || baseName(pc47.filePath), file: pc47.filePath });
+      const queues2 = resolveArg(m[3] ?? "", constMap, enums, loopVarEnums);
+      for (const queue of queues2) {
+        producers.push({
+          queue,
+          symbol: (m[1] ?? pc47.name) || baseName(pc47.filePath),
+          file: pc47.filePath
+        });
       }
     }
     for (const m of pc47.content.matchAll(QUEUE_NAME_CONST_RE)) {
@@ -81058,6 +81392,7 @@ function extractQueueGraph(input) {
   }
   const workers = [];
   for (const wf of input.workerFiles) {
+    const loopVarEnums = loopVarEnumsFor(wf.content);
     for (const m of wf.content.matchAll(PROCESSOR_RE)) {
       const queue = m[1] ?? "";
       const className = m[2] ?? "";
@@ -81065,17 +81400,24 @@ function extractQueueGraph(input) {
     }
     for (const m of wf.content.matchAll(NEW_BULL_RE)) {
       if (m[2] !== "Worker") continue;
-      const queue = resolveArg(m[3] ?? "", constMap);
-      if (queue) {
-        workers.push({ queue, symbol: m[1] ?? baseName(wf.filePath), file: wf.filePath });
+      const queues2 = resolveArg(m[3] ?? "", constMap, enums, loopVarEnums);
+      for (const queue of queues2) {
+        workers.push({
+          queue,
+          symbol: m[1] ?? baseName(wf.filePath),
+          file: wf.filePath
+        });
       }
     }
   }
+  for (const h of dispatchHandlers) {
+    workers.push({ queue: h.value, symbol: h.handler, file: h.file });
+  }
   const queues = [...new Set([...producers, ...workers].map((r) => r.queue))].sort();
   const edges = [];
   for (const q of queues) {
-    const P = dedupeByFile(producers.filter((p) => p.queue === q));
-    const W = dedupeByFile(workers.filter((w) => w.queue === q));
+    const P = dedupeBySymbolFile(producers.filter((p) => p.queue === q));
+    const W = dedupeBySymbolFile(workers.filter((w) => w.queue === q));
     if (P.length && W.length) {
       for (const p of P) {
         for (const w of W) {
@@ -81112,12 +81454,13 @@ function extractQueueGraph(input) {
   }
   return { queues, producers, workers, edges };
 }
-function dedupeByFile(rows) {
+function dedupeBySymbolFile(rows) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const r of rows) {
-    if (seen.has(r.file)) continue;
-    seen.add(r.file);
+    const key = `${r.symbol}\0${r.file}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
     out.push(r);
   }
   return out;
@@ -81128,7 +81471,7 @@ init_cjs_shims();
 async function stitch(client, db, opts = {}) {
   const producerRows = (await client.cypher(
     // "new Queue" (no paren) so generic-typed `new Queue<T>(...)` also matches.
-    'MATCH (n) WHERE n.content CONTAINS "@InjectQueue(" OR n.content CONTAINS "new Queue" OR n.content CONTAINS "QUEUE_NAME" OR n.content CONTAINS "QueueName" RETURN n.name, n.file_path, n.content'
+    'MATCH (n) WHERE n.content CONTAINS "@InjectQueue(" OR n.content CONTAINS "new Queue" OR n.content CONTAINS "QUEUE_NAME" OR n.content CONTAINS "QueueName" OR n.content CONTAINS "enum " OR n.content CONTAINS "Object.values(" OR n.content CONTAINS "]: (" RETURN n.name, n.file_path, n.content'
   )).rows;
   const producerClasses = producerRows.map((r) => ({
     name: String(r[0] ?? ""),
@@ -93528,10 +93871,11 @@ async function runQueues(name, opts) {
         }
       }
       const rows = await listQueueEdges(db, { project, queueName: name });
+      const showLive = opts.live || name !== void 0 && rows.length === 0;
       if (opts.json) {
         const topology = topologyToJson(buildQueueMap(rows));
         const out = { project: project ?? null, topology };
-        if (opts.live) out["live"] = await gatherLiveState(config2, rows, name);
+        if (showLive) out["live"] = await gatherLiveState(config2, rows, name);
         console.log(JSON.stringify(out, null, 2));
         return 0;
       }
@@ -93540,13 +93884,15 @@ async function runQueues(name, opts) {
       );
       console.log("");
       if (rows.length === 0) {
-        console.log(import_picocolors7.default.dim("  No queue edges indexed. Run: horus index"));
+        console.log(
+          name !== void 0 ? import_picocolors7.default.dim(`  No static topology for "${name}" \u2014 it may be dynamically registered; showing live state below.`) : import_picocolors7.default.dim("  No queue edges indexed. Run: horus index")
+        );
       } else {
         const byQueue = buildQueueMap(rows);
         printTopology(byQueue);
       }
       console.log("");
-      if (opts.live) {
+      if (showLive) {
         await runLiveMode(config2, rows, name, opts.ai ? {
           config: opts.config,
           aiModel: opts.aiModel,
@@ -94513,7 +94859,9 @@ async function runInvestigate(hint, opts) {
       if (cloudActive && cloudSession && cloudCfg) {
         try {
           const refs = await uploadInvestigationToCloud(cloudSession.client, cloudCfg, report);
-          console.log(import_picocolors9.default.dim(`[cloud] investigation saved: ${refs.investigationId}`));
+          const cloudNote = import_picocolors9.default.dim(`[cloud] investigation saved: ${refs.investigationId}`);
+          if (format === "json") console.error(cloudNote);
+          else console.log(cloudNote);
         } catch (err) {
           return reportCloudError(err);
         }

package/package.json

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