@merittdev/horus 0.3.0 → 0.4.0

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.0" : "dev";
+var HORUS_VERSION = true ? "0.4.0" : "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
@@ -77022,13 +77047,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) {
@@ -77129,11 +77177,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 +77210,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 +77278,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 +77389,7 @@ async function investigate(input, deps) {
   const logEvIds = [];
   const directLogEvIds = [];
   const ambientLogEvIds = [];
+  const directSignatures = [];
   const entityEvIds = [];
   const entitySummaries = [];
   let logsCollected = false;
@@ -77319,11 +77425,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 +77453,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 +77509,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 +77519,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 +77549,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 +77573,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 +77635,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(
@@ -77815,10 +77949,11 @@ async function investigate(input, deps) {
       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 +77963,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 +78057,22 @@ 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. ` : "";
+  const 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 nextActions = buildNextActions(top, ctx, impact, queueHits, changes, input);
   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 +78122,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;
+  if (topCauseScore < 0.2) report.confidence = Math.min(report.confidence, 0.6);
   report.nextActions.push(...gapNextActions(gapAnalysis.gaps));
   report.sourceStatus = buildRuntimeSourceStatus(evidence2, connectorFlags);
   const persistedId = await persist(db, input, report);
@@ -79289,14 +79475,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
     };
   }
@@ -93528,10 +93717,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 +93730,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,
@@ -94194,7 +94386,8 @@ async function runFeedbackPrompt(investigationId, horusSeconds) {
       investigationId,
       resolved: parseResolved(a1),
       manualEstimateMinutes: parseManualEstimate(a2),
-      horusSeconds
+      horusSeconds,
+      source: "prompt"
     });
     console.log(import_picocolors8.default.dim("  Thanks \u2014 recorded."));
     return true;
@@ -94512,7 +94705,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);
         }
@@ -98330,6 +98525,27 @@ horus ask <id> "what evidence contradicts the likely root cause?"
 horus score <id>
 \`\`\`
 
+## Report whether Horus helped (close the loop)
+
+Once you have **acted on an investigation and know the outcome** \u2014 you verified
+whether Horus pointed at the real cause \u2014 record it. This is how Horus measures and
+improves its own accuracy, and without it the impact signal is blind to agent-driven
+runs (most of them).
+
+\`\`\`bash
+horus feedback <id> --resolved yes      # Horus pointed at the real cause
+horus feedback <id> --resolved partly   # useful lead, but not the whole cause
+horus feedback <id> --resolved no       # Horus missed the cause
+\`\`\`
+
+It is non-interactive and safe to run unattended. Report **once** per investigation,
+**after** you confirm the outcome \u2014 never before, and never guess. If you can estimate
+how long the same debugging would have taken you manually, add it:
+
+\`\`\`bash
+horus feedback <id> --resolved yes --manual-estimate-min 120
+\`\`\`
+
 ## Runtime evidence
 
 Use runtime commands when the question depends on live or recent runtime behavior:
@@ -99541,14 +99757,37 @@ function installCommandTelemetry(program2) {
 // ../../packages/cli/src/commands/feedback.ts
 init_cjs_shims();
 var import_picocolors46 = __toESM(require_picocolors(), 1);
-async function runFeedback(investigationId) {
-  if (!process.stdin.isTTY) {
-    console.error(import_picocolors46.default.yellow("horus feedback needs an interactive terminal."));
-    return 1;
-  }
+async function runFeedback(investigationId, opts = {}) {
   const id = investigationId?.trim();
   if (!id) {
-    console.error(import_picocolors46.default.red("Usage: horus feedback <investigationId>"));
+    console.error(import_picocolors46.default.red("Usage: horus feedback <investigationId> [--resolved yes|partly|no]"));
+    return 1;
+  }
+  if (opts.resolved !== void 0) {
+    const resolved = parseResolved(opts.resolved);
+    if (resolved === null) {
+      console.error(import_picocolors46.default.red(`Invalid --resolved "${opts.resolved}". Use: yes | partly | no.`));
+      return 1;
+    }
+    let manualEstimateMinutes = null;
+    if (opts.manualEstimateMin !== void 0) {
+      const n = Number.parseInt(opts.manualEstimateMin, 10);
+      if (!Number.isFinite(n) || n < 0) {
+        console.error(import_picocolors46.default.red(`Invalid --manual-estimate-min "${opts.manualEstimateMin}" (expect a non-negative integer).`));
+        return 1;
+      }
+      manualEstimateMinutes = n;
+    }
+    submitFeedback({ investigationId: id, resolved, manualEstimateMinutes, horusSeconds: null, source: "flag" });
+    console.log(import_picocolors46.default.dim(`Feedback recorded (${resolved}) \u2014 thanks, this helps improve Horus.`));
+    return 0;
+  }
+  if (!process.stdin.isTTY) {
+    console.error(
+      import_picocolors46.default.yellow(
+        "horus feedback needs an interactive terminal \u2014 or pass --resolved yes|partly|no for non-interactive (agent) use."
+      )
+    );
     return 1;
   }
   await runFeedbackPrompt(id, null);
@@ -99976,9 +100215,17 @@ Examples:
   horus cloud sync --dry-run     # preview what would upload
   horus cloud sync               # confirm, then upload
   horus cloud sync --yes         # upload without prompting`);
-  program2.command("feedback [investigationId]").description("Leave quick impact feedback on an investigation (helps improve Horus)").action(async (investigationId) => {
-    process.exitCode = await runFeedback(investigationId);
-  });
+  program2.command("feedback [investigationId]").description("Leave quick impact feedback on an investigation (helps improve Horus)").option(
+    "--resolved <verdict>",
+    "did Horus point at the cause? yes | partly | no \u2014 non-interactive, for agents/scripts"
+  ).option(
+    "--manual-estimate-min <minutes>",
+    "estimated minutes this would have taken manually (optional, pair with --resolved)"
+  ).action(
+    async (investigationId, opts) => {
+      process.exitCode = await runFeedback(investigationId, opts);
+    }
+  );
   const telemetry = program2.command("telemetry").description("Manage anonymous usage telemetry that helps improve Horus");
   telemetry.command("status").description("Show the effective telemetry decision, saved preferences, and install ID").action(async () => {
     process.exitCode = await runTelemetryStatus();

package/package.json

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