@tangle-network/traces 0.8.13 → 0.8.15

package/dist/{chunk-PRRWLKSI.js → chunk-EOQY2RIK.js}

@@ -160,11 +160,11 @@ function serializeSpans(spans) {
 `;
 }
 async function writeOtlpFile(spans, outPath) {
-  const { mkdtemp: mkdtemp5, writeFile: writeFile6 } = await import("fs/promises");
-  const { tmpdir: tmpdir5 } = await import("os");
-  const { join: join19 } = await import("path");
-  const path = outPath ?? join19(await mkdtemp5(join19(tmpdir5(), "traces-")), "spans.otlp.jsonl");
-  await writeFile6(path, serializeSpans(spans), "utf8");
+  const { mkdtemp: mkdtemp6, writeFile: writeFile7 } = await import("fs/promises");
+  const { tmpdir: tmpdir6 } = await import("os");
+  const { join: join20 } = await import("path");
+  const path = outPath ?? join20(await mkdtemp6(join20(tmpdir6(), "traces-")), "spans.otlp.jsonl");
+  await writeFile7(path, serializeSpans(spans), "utf8");
   return path;
 }
 
@@ -2286,13 +2286,13 @@ function extractAbsolutePaths(spans) {
   let scannedChars = 0;
   for (const span2 of spans) {
     for (const value of [span2.name, span2.status.message, ...Object.values(span2.attributes)]) {
-      for (const evidence of pathsFromUnknown(value)) {
-        scannedChars += evidence.path.length;
+      for (const evidence2 of pathsFromUnknown(value)) {
+        scannedChars += evidence2.path.length;
         if (scannedChars > MAX_SPAN_TEXT_CHARS) return paths;
-        const key = `${evidence.source}:${evidence.path}`;
+        const key = `${evidence2.source}:${evidence2.path}`;
         if (seen.has(key)) continue;
         seen.add(key);
-        paths.push(evidence);
+        paths.push(evidence2);
         if (paths.length >= MAX_SPAN_PATH_CANDIDATES) return paths;
       }
     }
@@ -2346,8 +2346,8 @@ async function resolveSessionRepoAttrs(cwd, spans) {
     add(await repairDashedPath(cwd), "repaired-cwd");
     add(cwd, "ref-cwd");
   }
-  for (const evidence of extractAbsolutePaths(spans)) {
-    add(await repoCandidateForPath(evidence.path), evidence.source, evidence.weight);
+  for (const evidence2 of extractAbsolutePaths(spans)) {
+    add(await repoCandidateForPath(evidence2.path), evidence2.source, evidence2.weight);
   }
   const resolved = [];
   for (const candidate of candidates.values()) {
@@ -2531,7 +2531,7 @@ import { spawn } from "child_process";
 function runCommand(command, args = [], opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 12e4;
   const maxBuffer = opts.maxBuffer ?? 32 * 1024 * 1024;
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let child;
     try {
       child = spawn(command, [...args], { signal: opts.signal });
@@ -2569,7 +2569,7 @@ function runCommand(command, args = [], opts = {}) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (!killed) resolve({ stdout: out, stderr: err, code });
+      if (!killed) resolve2({ stdout: out, stderr: err, code });
     });
     if (opts.input !== void 0) {
       child.stdin?.on("error", () => {
@@ -3376,84 +3376,6 @@ async function writeInspectionReportFile(report, outPath) {
   return path;
 }
 
-// src/observer.ts
-var sleep = (ms, signal) => new Promise((resolve) => {
-  const onAbort = () => {
-    clearTimeout(t);
-    resolve();
-  };
-  const t = setTimeout(() => {
-    signal?.removeEventListener("abort", onAbort);
-    resolve();
-  }, ms);
-  signal?.addEventListener("abort", onAbort, { once: true });
-});
-function loopKey(sessionId, toolName2, argHash) {
-  return `${sessionId}\0${toolName2}\0${argHash}`;
-}
-async function watchSessions(opts) {
-  const windowMs = opts.windowMs ?? 30 * 6e4;
-  const intervalMs = Math.max(250, opts.intervalMs ?? 5e3);
-  const minLoop = opts.minLoopOccurrences ?? 3;
-  const seen = /* @__PURE__ */ new Map();
-  while (!opts.signal?.aborted) {
-    let sessionCount = 0;
-    for await (const { adapter, ref, spans } of scanSessions({
-      adapters: opts.adapters,
-      all: opts.all,
-      harnesses: opts.harnesses,
-      cwd: opts.cwd,
-      sinceMs: Date.now() - windowMs,
-      signal: opts.signal,
-      onError: opts.onError
-    })) {
-      let report;
-      try {
-        report = await runPipelines(spans, { minLoopOccurrences: minLoop });
-      } catch (err) {
-        opts.onError?.(err, ref);
-        continue;
-      }
-      sessionCount += 1;
-      if (opts.onReport) {
-        try {
-          await opts.onReport(ref, report);
-        } catch (err) {
-          opts.onError?.(err, ref);
-        }
-      }
-      for (const f of report.stuckLoops.findings) {
-        const key = loopKey(ref.sessionId, f.toolName, f.argHash);
-        if (f.occurrences > (seen.get(key) ?? 0)) {
-          seen.set(key, f.occurrences);
-          if (opts.onLoop) {
-            try {
-              await opts.onLoop({
-                harness: adapter.harness,
-                sessionId: ref.sessionId,
-                cwd: ref.cwd,
-                toolName: f.toolName,
-                argHash: f.argHash,
-                occurrences: f.occurrences,
-                windowMs: f.windowMs
-              });
-            } catch (err) {
-              opts.onError?.(err, ref);
-            }
-          }
-        }
-      }
-    }
-    try {
-      opts.onTick?.({ sessions: sessionCount });
-    } catch (err) {
-      opts.onError?.(err);
-    }
-    if (opts.signal?.aborted) break;
-    await sleep(intervalMs, opts.signal);
-  }
-}
-
 // src/reactions.ts
 var REACTIONS = ["correction", "frustration", "jargon", "structure", "praise"];
 function emptySignals() {
@@ -3540,10 +3462,746 @@ function analyzeReactions(spans) {
   };
 }
 
-// src/session-index.ts
-import { mkdtemp as mkdtemp4, readdir as readdir11, readFile as readFile14, stat as stat12, writeFile as writeFile4 } from "fs/promises";
+// src/report.ts
+var SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+var SEVERITY_BADGE = {
+  critical: "\u{1F534} CRITICAL",
+  high: "\u{1F7E0} HIGH",
+  medium: "\u{1F7E1} MEDIUM",
+  low: "\u{1F535} LOW",
+  info: "\u2139\uFE0F  INFO"
+};
+function deterministicSummaryText(summary) {
+  const parts = [];
+  if (summary.stuckLoops > 0) parts.push(`${summary.stuckLoops} stuck loop(s)`);
+  if (summary.reactionSignals > 0) parts.push(`${summary.reactionSignals} human reaction signal(s)`);
+  if (summary.toolErrorRuns > 0) parts.push(`${summary.toolErrorRuns} tool-error run(s)`);
+  if (parts.length === 0) return "0 deterministic signals";
+  if (parts.length === 1) return parts[0];
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+function plural(count, singular, pluralForm = `${singular}s`) {
+  return count === 1 ? singular : pluralForm;
+}
+function summarizeDeterministicSignals(pipelines, reactions) {
+  const stuckLoops = pipelines.stuckLoops.findings.length;
+  const reactionSignals = Object.values(reactions.signals).reduce((total, count) => total + count, 0);
+  const toolErrorRuns2 = pipelines.toolUse.filter((run) => run.errorRate > 0).length;
+  return {
+    stuckLoops,
+    reactionSignals,
+    toolErrorRuns: toolErrorRuns2,
+    totalSignals: stuckLoops + reactionSignals + toolErrorRuns2
+  };
+}
+function renderReport(result, meta) {
+  const lines = [];
+  const findings = [...result.findings].sort(
+    (a, b) => (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9)
+  );
+  const deterministic = meta.deterministic ?? { stuckLoops: 0, reactionSignals: 0, toolErrorRuns: 0, totalSignals: 0 };
+  const findingSummary = deterministic.totalSignals > 0 ? `${findings.length} analyst ${plural(findings.length, "finding")} + ${deterministic.totalSignals} deterministic ${plural(deterministic.totalSignals, "signal")}` : `${findings.length} ${plural(findings.length, "finding")}`;
+  lines.push(`# Trace analysis \u2014 ${meta.harness}`);
+  lines.push("");
+  lines.push(
+    `${meta.sessionCount} session(s), ${meta.spanCount} spans \u2192 **${findingSummary}** across ${result.per_analyst.length} analyst(s). Cost: $${result.total_cost_usd.toFixed(4)}.`
+  );
+  lines.push("");
+  lines.push("| Analyst | Status | Findings | Latency |");
+  lines.push("|---|---|---|---|");
+  for (const s of result.per_analyst) {
+    lines.push(`| \`${s.analyst_id}\` | ${s.status} | ${s.findings_count} | ${s.latency_ms}ms |`);
+  }
+  lines.push("");
+  if (findings.length === 0 && deterministic.totalSignals === 0) {
+    lines.push("_No findings \u2014 no behavioral inefficiencies or failure modes detected._");
+  } else if (findings.length === 0) {
+    lines.push(
+      `_No analyst findings. Deterministic checks found ${deterministicSummaryText(deterministic)}; see sections below._`
+    );
+  } else {
+    const byArea = /* @__PURE__ */ new Map();
+    for (const f of findings) {
+      const arr = byArea.get(f.area) ?? [];
+      arr.push(f);
+      byArea.set(f.area, arr);
+    }
+    for (const [area, arr] of byArea) {
+      lines.push(`## ${area} (${arr.length})`);
+      lines.push("");
+      for (const f of arr) {
+        lines.push(`### ${SEVERITY_BADGE[f.severity] ?? f.severity} \u2014 ${f.claim}`);
+        lines.push("");
+        if (f.subject) lines.push(`- **Subject:** \`${f.subject}\``);
+        lines.push(`- **Confidence:** ${f.confidence}`);
+        if (f.recommended_action) lines.push(`- **Fix:** ${f.recommended_action}`);
+        for (const ev of f.evidence_refs.slice(0, 3)) {
+          const excerpt = ev.excerpt ? ` \u2014 \`${ev.excerpt.slice(0, 200)}\`` : "";
+          lines.push(`- **Evidence:** ${ev.kind} ${ev.uri}${excerpt}`);
+        }
+        lines.push("");
+      }
+    }
+  }
+  lines.push("---");
+  lines.push(`OTLP artifact: \`${meta.otlpPath}\` \u2014 run external engines with \`traces analyze --analyzer halo\`.`);
+  lines.push("");
+  return lines.join("\n");
+}
+function renderPipelines(pr) {
+  const lines = ["## loops & waste (deterministic)", ""];
+  if (pr.stuckLoops.findings.length === 0) {
+    lines.push("- **Stuck loops:** none (no tool called \u22653\xD7 with identical args).");
+  } else {
+    lines.push(`- **Stuck loops:** ${pr.stuckLoops.findings.length} (${(pr.stuckLoops.affectedRunRatio * 100).toFixed(0)}% of runs affected)`);
+    for (const f of pr.stuckLoops.findings.sort((a, b) => b.occurrences - a.occurrences).slice(0, 10)) {
+      lines.push(`  - \u{1F501} \`${f.toolName}\` \xD7${f.occurrences} with identical args over ${(f.windowMs / 1e3).toFixed(1)}s`);
+    }
+  }
+  for (const m of pr.toolUse) {
+    if (m.totalCalls === 0) continue;
+    lines.push(
+      `- **Tool use** (${m.totalCalls} calls): ${(m.duplicateRate * 100).toFixed(0)}% duplicate, ${(m.retryRate * 100).toFixed(0)}% retry, ${(m.errorRate * 100).toFixed(0)}% error`
+    );
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+var REACTION_BADGE = {
+  correction: "correction",
+  frustration: "frustration",
+  jargon: "jargon-complaint",
+  structure: "structure-complaint",
+  praise: "praise"
+};
+function ratioStr(r) {
+  if (r === null) return "n/a (no reaction signals)";
+  if (!Number.isFinite(r)) return "\u221E (corrective with zero praise)";
+  return `${r.toFixed(2)}:1`;
+}
+function oneLine(s, n) {
+  const t = s.replace(/\s+/g, " ").trim();
+  return t.length > n ? `${t.slice(0, n)}\u2026` : t;
+}
+function renderReactions(rr) {
+  const lines = ["## user reactions (deterministic, human turns only)", ""];
+  const total = Object.values(rr.signals).reduce((a, b) => a + b, 0);
+  if (rr.humanReactionTurns === 0) {
+    lines.push("- No human turns followed an assistant turn (nothing to classify).");
+    lines.push("");
+    return lines.join("\n");
+  }
+  lines.push(
+    `- **Reaction turns:** ${rr.humanReactionTurns} human turn(s) followed an assistant turn; ${total} carried a reaction signal.`
+  );
+  lines.push(`- **Corrective-to-positive ratio:** ${ratioStr(rr.correctiveToPositiveRatio)}`);
+  lines.push("");
+  lines.push("| Signal | Count |");
+  lines.push("|---|---|");
+  for (const [k, v] of Object.entries(rr.signals)) {
+    if (v > 0) lines.push(`| ${REACTION_BADGE[k] ?? k} | ${v} |`);
+  }
+  lines.push("");
+  if (rr.triggerPairs.length > 0) {
+    lines.push("### top trigger pairs (assistant prose \u2192 human reaction)");
+    lines.push("");
+    for (const p of rr.triggerPairs) {
+      lines.push(`- **[${p.reactions.map((r) => REACTION_BADGE[r] ?? r).join(", ")}]**`);
+      lines.push(`  - assistant: \`${oneLine(p.assistant, 180)}\``);
+      lines.push(`  - human: \`${oneLine(p.human, 180)}\``);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderAdoption(ar) {
+  const lines = ["## skill & subagent adoption (deterministic)", ""];
+  lines.push(
+    `- **Skill penetration:** ${(ar.skillPenetration * 100).toFixed(0)}% (${ar.sessionsWithSkill}/${ar.sessionCount} session(s) invoked a skill explicitly)`
+  );
+  lines.push(
+    `- **Explicit skill invocations:** ${ar.totalSkillInvocations} (Skill tool spans)  \xB7  **Loop-dispatched runs:** ${ar.totalLoopDispatchedRuns} (from ${ar.skillRunFilesRead} \`.evolve/skill-runs.jsonl\` file(s))`
+  );
+  lines.push(
+    `- **Subagent spawns:** ${ar.totalSubagentSpawns} across ${ar.sessionsWithSubagent} session(s)`
+  );
+  lines.push("");
+  const skillRows = Object.entries(ar.skillInvocations).sort((a, b) => b[1] - a[1]);
+  const loopRows = Object.entries(ar.loopDispatchedRuns).sort((a, b) => b[1] - a[1]);
+  if (skillRows.length > 0 || loopRows.length > 0) {
+    lines.push("| Skill | Explicit invocations | Loop-dispatched runs |");
+    lines.push("|---|---|---|");
+    const names = [.../* @__PURE__ */ new Set([...skillRows.map((r) => r[0]), ...loopRows.map((r) => r[0])])].sort(
+      (a, b) => (ar.skillInvocations[b] ?? 0) + (ar.loopDispatchedRuns[b] ?? 0) - (ar.skillInvocations[a] ?? 0) - (ar.loopDispatchedRuns[a] ?? 0)
+    );
+    for (const n of names) {
+      lines.push(`| \`${n}\` | ${ar.skillInvocations[n] ?? 0} | ${ar.loopDispatchedRuns[n] ?? 0} |`);
+    }
+    lines.push("");
+  }
+  const agentRows = Object.entries(ar.subagentSpawns).sort((a, b) => b[1] - a[1]);
+  if (agentRows.length > 0) {
+    lines.push("| Subagent | Spawns |");
+    lines.push("|---|---|");
+    for (const [n, c] of agentRows) lines.push(`| \`${n}\` | ${c} |`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/improvement.ts
+import { access, mkdir, mkdtemp as mkdtemp4, writeFile as writeFile4 } from "fs/promises";
 import { tmpdir as tmpdir4 } from "os";
-import { dirname as dirname2, join as join16 } from "path";
+import { dirname as dirname2, join as join16, resolve } from "path";
+import { pathToFileURL } from "url";
+import {
+  AnalystRegistry,
+  buildDefaultAnalystRegistry as buildDefaultAnalystRegistry2,
+  makeFinding
+} from "@tangle-network/agent-eval/analyst";
+var severityRank2 = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  info: 4
+};
+function slug(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 72) || "item";
+}
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+function jsonl(rows) {
+  return rows.length === 0 ? "" : `${rows.map((row) => JSON.stringify(row)).join("\n")}
+`;
+}
+function evidence(kind, uri, excerpt) {
+  return excerpt ? { kind, uri, excerpt } : { kind, uri };
+}
+function totalReactionSignals(reactions) {
+  return Object.values(reactions.signals).reduce((sum, count) => sum + count, 0);
+}
+function toolErrorRuns(pipelines) {
+  return pipelines.toolUse.filter((run) => run.errorRate > 0).length;
+}
+function deterministicFindings(pipelines, reactions, adoption) {
+  const findings = [];
+  const loops = pipelines.stuckLoops.findings;
+  if (loops.length > 0) {
+    const top = [...loops].sort((a, b) => b.occurrences - a.occurrences)[0];
+    findings.push(makeFinding({
+      analyst_id: "traces-deterministic",
+      area: "tool-use",
+      claim: `${loops.length} repeated tool-call loop(s) were observed`,
+      severity: loops.length >= 10 ? "high" : "medium",
+      rationale: "Repeated identical tool calls usually mean the agent is retrying without new information or a stop rule.",
+      evidence_refs: [
+        evidence("metric", "pipelines.stuck_loop_count", `${loops.length} loop(s)`),
+        ...top ? [evidence("metric", `tool.${top.toolName}.repeated_calls`, `${top.toolName} repeated ${top.occurrences} time(s)`)] : []
+      ],
+      recommended_action: "Add a loop breaker: when the same tool and arguments fail or repeat, force a state check, alternate plan, or stop condition before retrying.",
+      validation_plan: "Rerun traces over fresh sessions and require repeated-call loops to drop to zero or explain each remaining loop with changed state.",
+      confidence: 0.95,
+      metadata: { source: "traces.pipeline.stuckLoopView", loopCount: loops.length }
+    }));
+  }
+  const erroredRuns = toolErrorRuns(pipelines);
+  if (erroredRuns > 0) {
+    findings.push(makeFinding({
+      analyst_id: "traces-deterministic",
+      area: "tool-use",
+      claim: `${erroredRuns} run(s) included tool errors`,
+      severity: erroredRuns >= 5 ? "high" : "medium",
+      rationale: "Tool errors are expensive when the agent keeps planning as if the call succeeded.",
+      evidence_refs: [evidence("metric", "pipelines.tool_error_runs", `${erroredRuns} run(s) with errorRate > 0`)],
+      recommended_action: "Fix the highest-frequency failing tool path first, then make the agent inspect failure output before retrying.",
+      validation_plan: "Rerun the same trace window and require the tool-error run count and repeated retries to decrease.",
+      confidence: 0.9,
+      metadata: { source: "traces.pipeline.computeToolUseMetrics", erroredRuns }
+    }));
+  }
+  const corrective = reactions.signals.correction + reactions.signals.frustration + reactions.signals.jargon + reactions.signals.structure;
+  if (corrective > 0) {
+    findings.push(makeFinding({
+      analyst_id: "traces-deterministic",
+      area: "communication",
+      claim: `${corrective} corrective human reaction signal(s) followed assistant turns`,
+      severity: corrective >= 10 ? "high" : "medium",
+      rationale: "Human corrections are direct product feedback: the agent either missed the task, overexplained, used unclear language, or failed to adapt.",
+      evidence_refs: reactions.triggerPairs.slice(0, 3).map((pair, index) => evidence("event", `reaction.trigger_pair.${index + 1}`, `${pair.reactions.join(", ")}: ${pair.human.slice(0, 180)}`)),
+      recommended_action: "Turn the top correction pattern into an agent profile rule or analyst skill, then rerun traces and check the corrective-to-positive ratio.",
+      validation_plan: "Rerun traces on fresh sessions and require corrective reaction signals per human reaction turn to decrease.",
+      confidence: 0.85,
+      metadata: { source: "traces.reactions", correctiveSignals: corrective, totalSignals: totalReactionSignals(reactions) }
+    }));
+  }
+  const skillRuns = adoption.totalSkillInvocations + adoption.totalLoopDispatchedRuns;
+  if (adoption.sessionCount > 0 && skillRuns === 0) {
+    findings.push(makeFinding({
+      analyst_id: "traces-deterministic",
+      area: "workflow",
+      claim: "No skill usage was observed in the selected sessions",
+      severity: "low",
+      rationale: "Repeatable work without explicit skills is harder to improve because the trace has no reusable policy boundary to patch.",
+      evidence_refs: [evidence("metric", "adoption.skill_runs", "0 explicit or loop-dispatched skill runs")],
+      recommended_action: "Create or invoke a narrow skill for the repeated workflow, then let traces compare future sessions against this baseline.",
+      validation_plan: "Rerun traces and require skill-run attribution to appear for repeated workflows.",
+      confidence: 0.75,
+      metadata: { source: "traces.adoption", sessionCount: adoption.sessionCount }
+    }));
+  }
+  return findings;
+}
+function validSeverity(value) {
+  return value === "critical" || value === "high" || value === "medium" || value === "low" || value === "info";
+}
+function validEvidenceRef(value) {
+  if (!value || typeof value !== "object") return false;
+  const row = value;
+  return (row.kind === "span" || row.kind === "event" || row.kind === "artifact" || row.kind === "finding" || row.kind === "metric") && typeof row.uri === "string" && (row.excerpt === void 0 || typeof row.excerpt === "string");
+}
+function externalRows(output) {
+  const trimmed = output.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return [];
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && typeof parsed === "object") {
+      const row = parsed;
+      if (Array.isArray(row.findings)) return row.findings;
+      if (Array.isArray(row.issues)) return row.issues;
+      if (Array.isArray(row.recommendations)) return row.recommendations;
+    }
+  } catch {
+    return [];
+  }
+  return [];
+}
+function coerceExternalFinding(analyzer, row, index) {
+  if (!row || typeof row !== "object") return null;
+  const item = row;
+  const claim = item.claim ?? item.title ?? item.issue ?? item.recommendation;
+  if (typeof claim !== "string" || claim.trim().length === 0) return null;
+  const evidenceRefs = Array.isArray(item.evidence_refs) ? item.evidence_refs.filter(validEvidenceRef) : Array.isArray(item.evidenceRefs) ? item.evidenceRefs.filter(validEvidenceRef) : [];
+  return makeFinding({
+    analyst_id: `external:${analyzer}`,
+    area: typeof item.area === "string" && item.area ? item.area : "external",
+    claim,
+    severity: validSeverity(item.severity) ? item.severity : "medium",
+    rationale: typeof item.rationale === "string" ? item.rationale : void 0,
+    evidence_refs: evidenceRefs,
+    recommended_action: typeof item.recommended_action === "string" ? item.recommended_action : typeof item.action === "string" ? item.action : void 0,
+    validation_plan: typeof item.validation_plan === "string" ? item.validation_plan : void 0,
+    confidence: typeof item.confidence === "number" && Number.isFinite(item.confidence) ? item.confidence : 0.65,
+    subject: typeof item.subject === "string" ? item.subject : void 0,
+    metadata: { source: "traces.external", analyzer, rowIndex: index }
+  });
+}
+function normalizeExternalFindings(results) {
+  const out = [];
+  for (const result of results) {
+    if (result.findings) out.push(...result.findings);
+    externalRows(result.output).forEach((row, index) => {
+      const finding = coerceExternalFinding(result.analyzer, row, index);
+      if (finding) out.push(finding);
+    });
+  }
+  return out;
+}
+function sourceOf(finding) {
+  if (finding.analyst_id.startsWith("external:")) return "external";
+  if (finding.analyst_id === "traces-deterministic") return "deterministic";
+  return "analyst";
+}
+function recommendationTitle(finding) {
+  if (finding.recommended_action) return finding.recommended_action.replace(/\.$/, "");
+  return `Investigate ${finding.area}: ${finding.claim}`.replace(/\.$/, "");
+}
+function buildRecommendations(findings) {
+  return [...findings].filter((finding) => finding.severity !== "info").sort((a, b) => severityRank2[a.severity] - severityRank2[b.severity] || b.confidence - a.confidence || a.finding_id.localeCompare(b.finding_id)).slice(0, 20).map((finding, index) => ({
+    schemaVersion: 1,
+    id: `rec-${index + 1}-${slug(finding.area)}`,
+    severity: finding.severity,
+    title: recommendationTitle(finding),
+    action: finding.recommended_action ?? `Review and fix: ${finding.claim}`,
+    rationale: finding.rationale ?? finding.claim,
+    evidenceRefs: finding.evidence_refs,
+    findingIds: [finding.finding_id],
+    validationPlan: finding.validation_plan ?? "Rerun `traces improve` on a fresh comparable session window and confirm this finding disappears or drops in severity.",
+    source: sourceOf(finding)
+  }));
+}
+function buildClaims(findings) {
+  return findings.map((finding, index) => ({
+    schemaVersion: 1,
+    id: `claim-${index + 1}-${slug(finding.area)}`,
+    severity: finding.severity,
+    text: finding.claim,
+    area: finding.area,
+    sourceFindingId: finding.finding_id,
+    evidenceRefs: finding.evidence_refs,
+    validationPlan: finding.validation_plan
+  }));
+}
+function buildEvidenceRows(findings) {
+  return findings.flatMap((finding) => finding.evidence_refs.map((ref) => ({
+    schemaVersion: 1,
+    kind: "traces.improvement_evidence",
+    findingId: finding.finding_id,
+    severity: finding.severity,
+    area: finding.area,
+    claim: finding.claim,
+    evidence: ref
+  })));
+}
+function renderRecommendations(recommendations) {
+  const lines = ["## recommendations", ""];
+  if (recommendations.length === 0) {
+    lines.push("- No recommendations emitted.");
+    lines.push("");
+    return lines.join("\n");
+  }
+  for (const rec of recommendations.slice(0, 10)) {
+    lines.push(`### ${rec.severity.toUpperCase()} \u2014 ${rec.title}`);
+    lines.push("");
+    lines.push(`- **Action:** ${rec.action}`);
+    lines.push(`- **Why:** ${rec.rationale}`);
+    lines.push(`- **Check:** ${rec.validationPlan}`);
+    for (const ref of rec.evidenceRefs.slice(0, 3)) {
+      lines.push(`- **Evidence:** ${ref.kind} ${ref.uri}${ref.excerpt ? ` \u2014 \`${ref.excerpt.slice(0, 180)}\`` : ""}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderFindingPacket(packet, title = "Trace finding packet") {
+  const lines = [`# ${title}`, ""];
+  lines.push(`${packet.findings.length} finding(s), ${packet.recommendations.length} recommendation(s), ${packet.claims.length} claim(s).`);
+  lines.push("");
+  lines.push(renderRecommendations(packet.recommendations));
+  if (packet.findings.length > 0) {
+    lines.push("## findings");
+    lines.push("");
+    for (const finding of [...packet.findings].sort((a, b) => severityRank2[a.severity] - severityRank2[b.severity] || a.area.localeCompare(b.area) || a.claim.localeCompare(b.claim))) {
+      lines.push(`### ${finding.severity.toUpperCase()} \u2014 ${finding.claim}`);
+      lines.push("");
+      lines.push(`- **Area:** ${finding.area}`);
+      lines.push(`- **Analyst:** ${finding.analyst_id}`);
+      if (finding.recommended_action) lines.push(`- **Action:** ${finding.recommended_action}`);
+      if (finding.validation_plan) lines.push(`- **Check:** ${finding.validation_plan}`);
+      for (const ref of finding.evidence_refs.slice(0, 3)) {
+        lines.push(`- **Evidence:** ${ref.kind} ${ref.uri}${ref.excerpt ? ` \u2014 \`${ref.excerpt.slice(0, 180)}\`` : ""}`);
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+function buildTraceFindingPacket(opts) {
+  const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const packet = {
+    schemaVersion: 1,
+    kind: "traces.finding_packet",
+    generatedAt,
+    source: opts.source ?? "traces",
+    findings: opts.findings,
+    recommendations: buildRecommendations(opts.findings),
+    claims: buildClaims(opts.findings)
+  };
+  return { ...packet, report: renderFindingPacket(packet, opts.title) };
+}
+function renderExternal(results) {
+  if (results.length === 0) return "";
+  const lines = ["## external analyzers", ""];
+  for (const result of results) {
+    lines.push(`### ${result.analyzer}`);
+    lines.push("");
+    lines.push(result.ok ? result.output || "(no output)" : `failed: ${result.error}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderInvestigationReport(result, analystResult) {
+  const base = `${renderReport({ ...analystResult, findings: [...result.findings] }, {
+    harness: result.harness,
+    sessionCount: result.sessionCount,
+    spanCount: result.spanCount,
+    otlpPath: result.otlpPath,
+    deterministic: summarizeDeterministicSignals(result.pipelines, result.reactions)
+  })}
+${renderRecommendations(result.recommendations)}
+${renderPipelines(result.pipelines)}
+${renderReactions(result.reactions)}
+${renderAdoption(result.adoption)}`;
+  const external = renderExternal(result.external);
+  return external ? `${base}
+${external}` : base;
+}
+function registryFromConfig(config) {
+  if (!config) return void 0;
+  if (config.registry) return config.registry;
+  if (!config.analysts || config.analysts.length === 0) return void 0;
+  const registry = new AnalystRegistry();
+  for (const analyst of config.analysts) registry.register(analyst);
+  return registry;
+}
+async function existingConfigPath(path) {
+  const candidates = path ? [path] : ["traces.config.mjs", "traces.config.js", "traces.config.cjs"];
+  for (const candidate of candidates) {
+    const resolved = resolve(candidate);
+    try {
+      await access(resolved);
+      return resolved;
+    } catch {
+      if (path) return void 0;
+    }
+  }
+  return void 0;
+}
+async function loadTracesConfig(path) {
+  const resolved = await existingConfigPath(path);
+  if (!resolved) return void 0;
+  let mod;
+  try {
+    mod = await import(pathToFileURL(resolved).href);
+  } catch (err) {
+    if (resolved.endsWith(".ts")) {
+      throw new Error(`traces config is TypeScript (${resolved}); use traces.config.mjs/js, or run the CLI through a TS loader`);
+    }
+    throw err;
+  }
+  const value = mod.default ?? mod.config;
+  if (value === void 0) return void 0;
+  if (!value || typeof value !== "object") throw new Error(`${path} must export a config object`);
+  return value;
+}
+function mergeTracesConfig(opts, config) {
+  if (!config) return opts;
+  return {
+    ...opts,
+    registry: opts.registry ?? registryFromConfig(config),
+    externalAnalyzers: [...config.externalAnalyzers ?? [], ...opts.externalAnalyzers ?? []]
+  };
+}
+async function runTraceInvestigation(opts) {
+  if (opts.spans.length === 0) throw new Error("runTraceInvestigation: no spans to analyze");
+  const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const [analysis, pipelines, reactions, adoption] = await Promise.all([
+    analyzeSpans(opts.spans, {
+      ai: opts.ai,
+      model: opts.model,
+      budgetUsd: opts.budgetUsd,
+      registry: opts.registry,
+      otlpOutPath: opts.otlpOutPath,
+      runId: `traces-investigation-${Date.parse(generatedAt) || Date.now()}`,
+      log: opts.log
+    }),
+    runPipelines(opts.spans, { minLoopOccurrences: opts.minLoopOccurrences }),
+    Promise.resolve(analyzeReactions(opts.spans)),
+    analyzeAdoption(opts.spans, { cwds: opts.cwds })
+  ]);
+  const external = opts.externalAnalyzers?.length ? await runExternalAnalyzers(analysis.otlpPath, opts.externalAnalyzers, { prompt: opts.analyzerPrompt }) : [];
+  const findings = [
+    ...analysis.result.findings,
+    ...deterministicFindings(pipelines, reactions, adoption),
+    ...normalizeExternalFindings(external)
+  ];
+  const recommendations = buildRecommendations(findings);
+  const claims = buildClaims(findings);
+  const partial = {
+    schemaVersion: 1,
+    kind: "traces.investigation",
+    generatedAt,
+    harness: opts.harness,
+    sessionCount: opts.sessionCount,
+    spanCount: opts.spans.length,
+    otlpPath: analysis.otlpPath,
+    findings,
+    recommendations,
+    claims,
+    pipelines,
+    reactions,
+    adoption,
+    external
+  };
+  const result = { ...partial, report: "" };
+  return { ...result, report: renderInvestigationReport(result, analysis.result) };
+}
+async function runTraceStoreInvestigation(opts) {
+  const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const registry = opts.registry ?? buildDefaultAnalystRegistry2({
+    ai: opts.ai,
+    model: opts.model,
+    registry: { log: opts.log }
+  });
+  const runId = opts.runId ?? `traces-store-investigation-${Date.parse(generatedAt) || Date.now()}`;
+  const analystResult = await registry.run(runId, { traceStore: opts.traceStore }, {
+    budget: opts.budgetUsd != null ? { totalUsd: opts.budgetUsd } : void 0
+  });
+  const packet = buildTraceFindingPacket({
+    findings: analystResult.findings,
+    generatedAt,
+    source: "trace-store",
+    title: "Trace store investigation"
+  });
+  return {
+    ...packet,
+    kind: "traces.store_investigation",
+    analystResult
+  };
+}
+function replayProof(result, proposals) {
+  const deterministic = summarizeDeterministicSignals(result.pipelines, result.reactions);
+  return {
+    schemaVersion: 1,
+    kind: "traces.improvement_replay",
+    generatedAt: result.generatedAt,
+    status: proposals.length > 0 ? "proposal-only" : "not-run",
+    candidateApplied: false,
+    baseline: {
+      spanCount: result.spanCount,
+      findingCount: result.findings.length,
+      recommendationCount: result.recommendations.length,
+      stuckLoops: deterministic.stuckLoops,
+      reactionSignals: deterministic.reactionSignals,
+      toolErrorRuns: deterministic.toolErrorRuns
+    },
+    proposals,
+    note: proposals.length > 0 ? "traces produced reviewable proposals only; apply one and rerun traces on a comparable window to populate after metrics." : "no proposal adapter was configured, so no candidate was applied; recommendations remain reviewable guidance."
+  };
+}
+async function writeTraceImprovementArtifacts(result, outDir) {
+  const directory = outDir ? resolve(outDir) : await mkdtemp4(join16(tmpdir4(), "traces-improvement-"));
+  await mkdir(directory, { recursive: true });
+  const paths = {
+    directory,
+    findings: join16(directory, "findings.json"),
+    recommendations: join16(directory, "recommendations.json"),
+    evidence: join16(directory, "evidence.jsonl"),
+    claims: join16(directory, "claims.json"),
+    report: join16(directory, "report.md"),
+    replay: join16(directory, "replay-before-after.json")
+  };
+  await Promise.all([
+    writeFile4(paths.findings, json(result.findings), "utf8"),
+    writeFile4(paths.recommendations, json(result.recommendations), "utf8"),
+    writeFile4(paths.evidence, jsonl(buildEvidenceRows(result.findings)), "utf8"),
+    writeFile4(paths.claims, json(result.claims), "utf8"),
+    writeFile4(paths.report, result.report, "utf8"),
+    writeFile4(paths.replay, json(result.replay), "utf8")
+  ]);
+  return paths;
+}
+async function runTraceImprovementLoop(opts) {
+  const investigation = await runTraceInvestigation(opts);
+  const proposals = opts.adapter ? await opts.adapter.propose({
+    findings: investigation.findings,
+    recommendations: investigation.recommendations,
+    claims: investigation.claims,
+    spans: opts.spans,
+    otlpPath: investigation.otlpPath
+  }) : [];
+  const replay = replayProof(investigation, proposals);
+  const result = {
+    ...investigation,
+    kind: "traces.improvement",
+    proposals,
+    replay
+  };
+  return {
+    ...result,
+    artifacts: await writeTraceImprovementArtifacts(result, opts.outDir)
+  };
+}
+async function saveReport(path, report) {
+  await mkdir(dirname2(resolve(path)), { recursive: true });
+  await writeFile4(path, report, "utf8");
+}
+
+// src/observer.ts
+var sleep = (ms, signal) => new Promise((resolve2) => {
+  const onAbort = () => {
+    clearTimeout(t);
+    resolve2();
+  };
+  const t = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve2();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+function loopKey(sessionId, toolName2, argHash) {
+  return `${sessionId}\0${toolName2}\0${argHash}`;
+}
+async function watchSessions(opts) {
+  const windowMs = opts.windowMs ?? 30 * 6e4;
+  const intervalMs = Math.max(250, opts.intervalMs ?? 5e3);
+  const minLoop = opts.minLoopOccurrences ?? 3;
+  const seen = /* @__PURE__ */ new Map();
+  while (!opts.signal?.aborted) {
+    let sessionCount = 0;
+    for await (const { adapter, ref, spans } of scanSessions({
+      adapters: opts.adapters,
+      all: opts.all,
+      harnesses: opts.harnesses,
+      cwd: opts.cwd,
+      sinceMs: Date.now() - windowMs,
+      signal: opts.signal,
+      onError: opts.onError
+    })) {
+      let report;
+      try {
+        report = await runPipelines(spans, { minLoopOccurrences: minLoop });
+      } catch (err) {
+        opts.onError?.(err, ref);
+        continue;
+      }
+      sessionCount += 1;
+      if (opts.onReport) {
+        try {
+          await opts.onReport(ref, report);
+        } catch (err) {
+          opts.onError?.(err, ref);
+        }
+      }
+      for (const f of report.stuckLoops.findings) {
+        const key = loopKey(ref.sessionId, f.toolName, f.argHash);
+        if (f.occurrences > (seen.get(key) ?? 0)) {
+          seen.set(key, f.occurrences);
+          if (opts.onLoop) {
+            try {
+              await opts.onLoop({
+                harness: adapter.harness,
+                sessionId: ref.sessionId,
+                cwd: ref.cwd,
+                toolName: f.toolName,
+                argHash: f.argHash,
+                occurrences: f.occurrences,
+                windowMs: f.windowMs
+              });
+            } catch (err) {
+              opts.onError?.(err, ref);
+            }
+          }
+        }
+      }
+    }
+    try {
+      opts.onTick?.({ sessions: sessionCount });
+    } catch (err) {
+      opts.onError?.(err);
+    }
+    if (opts.signal?.aborted) break;
+    await sleep(intervalMs, opts.signal);
+  }
+}
+
+// src/session-index.ts
+import { mkdtemp as mkdtemp5, readdir as readdir11, readFile as readFile14, stat as stat12, writeFile as writeFile5 } from "fs/promises";
+import { tmpdir as tmpdir5 } from "os";
+import { dirname as dirname3, join as join17 } from "path";
 function indexRow(record) {
   return {
     session: record.session,
@@ -3613,13 +4271,13 @@ async function findContextRoot(cwd) {
   let current = cwd;
   const s = await pathStat2(current);
   if (!s) return null;
-  if (!s.isDirectory()) current = dirname2(current);
+  if (!s.isDirectory()) current = dirname3(current);
   for (; ; ) {
-    if (await pathStat2(join16(current, ".git")) || await dirExists(join16(current, ".evolve")) || await fileExists(join16(current, "AGENTS.md")) || await fileExists(join16(current, "CLAUDE.md"))) {
+    if (await pathStat2(join17(current, ".git")) || await dirExists(join17(current, ".evolve")) || await fileExists(join17(current, "AGENTS.md")) || await fileExists(join17(current, "CLAUDE.md"))) {
       return current;
     }
-    const parent = dirname2(current);
-    if (parent === current) return s.isDirectory() ? cwd : dirname2(cwd);
+    const parent = dirname3(current);
+    if (parent === current) return s.isDirectory() ? cwd : dirname3(cwd);
     current = parent;
   }
 }
@@ -3660,12 +4318,12 @@ async function summarizeFile(path, kind) {
   try {
     const text = await readFile14(path, "utf8");
     const lines = countLines(text);
-    const jsonl = path.endsWith(".jsonl") ? summarizeJsonl(text) : void 0;
+    const jsonl2 = path.endsWith(".jsonl") ? summarizeJsonl(text) : void 0;
     return {
       ...base,
       lines,
       ...path.endsWith(".md") ? { markdown: summarizeMarkdown(text) } : {},
-      ...jsonl ? { jsonlRows: jsonl.rows, jsonl } : {}
+      ...jsonl2 ? { jsonlRows: jsonl2.rows, jsonl: jsonl2 } : {}
     };
   } catch {
     return base;
@@ -3683,7 +4341,7 @@ async function walkMarkdown(root, kind, maxFiles = 100) {
     }
     for (const entry of entries) {
       if (out.length >= maxFiles) return;
-      const path = join16(dir, entry.name);
+      const path = join17(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(path);
       } else if (entry.isFile() && entry.name.endsWith(".md")) {
@@ -3698,20 +4356,20 @@ async function walkMarkdown(root, kind, maxFiles = 100) {
 async function collectContextRoot(root) {
   const files = [];
   for (const name of ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]) {
-    const summary = await summarizeFile(join16(root, name), "instruction-doc");
+    const summary = await summarizeFile(join17(root, name), "instruction-doc");
     if (summary) files.push(summary);
   }
-  const evolve = join16(root, ".evolve");
+  const evolve = join17(root, ".evolve");
   for (const name of ["skill-runs.jsonl", "governor.jsonl", "experiments.jsonl"]) {
-    const summary = await summarizeFile(join16(evolve, name), "evolve-jsonl");
+    const summary = await summarizeFile(join17(evolve, name), "evolve-jsonl");
     if (summary) files.push(summary);
   }
   for (const name of ["scorecard.json"]) {
-    const summary = await summarizeFile(join16(evolve, name), "evolve-json");
+    const summary = await summarizeFile(join17(evolve, name), "evolve-json");
     if (summary) files.push(summary);
   }
-  files.push(...await walkMarkdown(join16(evolve, "reflections"), "reflection"));
-  files.push(...await walkMarkdown(join16(evolve, "handoffs"), "handoff"));
+  files.push(...await walkMarkdown(join17(evolve, "reflections"), "reflection"));
+  files.push(...await walkMarkdown(join17(evolve, "handoffs"), "handoff"));
   return { root, files: files.sort((a, b) => a.path.localeCompare(b.path)) };
 }
 async function collectContextIndex(records) {
@@ -3757,19 +4415,19 @@ function serializeSessionIndex(index) {
 `;
 }
 async function writeSessionIndexFile(index, outPath) {
-  const path = outPath ?? join16(await mkdtemp4(join16(tmpdir4(), "traces-index-")), "session-index.json");
-  await writeFile4(path, serializeSessionIndex(index), "utf8");
+  const path = outPath ?? join17(await mkdtemp5(join17(tmpdir5(), "traces-index-")), "session-index.json");
+  await writeFile5(path, serializeSessionIndex(index), "utf8");
   return path;
 }
 
 // src/upload-state.ts
 import { createHash as createHash2 } from "crypto";
-import { mkdir, readFile as readFile15, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir2, readFile as readFile15, writeFile as writeFile6 } from "fs/promises";
 import { homedir as homedir11 } from "os";
-import { dirname as dirname3, join as join17 } from "path";
+import { dirname as dirname4, join as join18 } from "path";
 function stateFile() {
-  const base = process.env.XDG_STATE_HOME ?? join17(homedir11(), ".local", "state");
-  return join17(base, "tangle-traces", "uploaded.json");
+  const base = process.env.XDG_STATE_HOME ?? join18(homedir11(), ".local", "state");
+  return join18(base, "tangle-traces", "uploaded.json");
 }
 function uploadKey(harness, sessionId) {
   return `${harness}:${sessionId}`;
@@ -3791,8 +4449,8 @@ async function loadState() {
 }
 async function saveState(state) {
   const f = stateFile();
-  await mkdir(dirname3(f), { recursive: true });
-  await writeFile5(f, `${JSON.stringify(state, null, 2)}
+  await mkdir2(dirname4(f), { recursive: true });
+  await writeFile6(f, `${JSON.stringify(state, null, 2)}
 `, "utf8");
 }
 function alreadyUploaded(state, harness, sessionId, hash) {
@@ -3803,7 +4461,7 @@ function alreadyUploaded(state, harness, sessionId, hash) {
 import { readFile as readFile16 } from "fs/promises";
 import { createRequire } from "module";
 import { hostname } from "os";
-import { basename as basename9, join as join18 } from "path";
+import { basename as basename9, join as join19 } from "path";
 import { hostedClientFromEnv } from "@tangle-network/agent-eval/hosted";
 import { REDACTION_VERSION } from "@tangle-network/agent-eval/traces";
 var require2 = createRequire(import.meta.url);
@@ -3827,7 +4485,7 @@ async function planUpload(opts = {}) {
 async function gitBranch(cwd) {
   if (!cwd) return void 0;
   try {
-    const head = await readFile16(join18(cwd, ".git", "HEAD"), "utf8");
+    const head = await readFile16(join19(cwd, ".git", "HEAD"), "utf8");
     const m = head.match(/^ref:\s*refs\/heads\/(.+)$/m);
     return m?.[1]?.trim();
   } catch {
@@ -4001,9 +4659,22 @@ export {
   serializeInspectionReport,
   readSessionIndexFile,
   writeInspectionReportFile,
-  watchSessions,
   REACTIONS,
   analyzeReactions,
+  summarizeDeterministicSignals,
+  renderReport,
+  renderPipelines,
+  renderReactions,
+  renderAdoption,
+  buildTraceFindingPacket,
+  loadTracesConfig,
+  mergeTracesConfig,
+  runTraceInvestigation,
+  runTraceStoreInvestigation,
+  writeTraceImprovementArtifacts,
+  runTraceImprovementLoop,
+  saveReport,
+  watchSessions,
   buildSessionIndex,
   buildSessionIndexFromRows,
   collectSessionIndex,