@tangle-network/traces 0.8.17 → 0.8.18

package/README.md

@@ -17,6 +17,7 @@ It reads the transcripts your harness leaves on disk, reconstructs the run as sp
 - [What it finds](#what-it-finds)
 - [Supported harnesses](#supported-harnesses)
 - [CLI reference](#cli-reference)
+- [Live stream](#live-stream)
 - [Improvement engine](#improvement-engine)
 - [Session index](#session-index)
 - [Policy-mining evidence](#policy-mining-evidence)
@@ -44,6 +45,8 @@ Requires Node ≥ 22.
 ```bash
 traces analyze --harness claude-code --last 1
 traces improve --harness claude-code --last 5 --dir .traces/improvement
+traces watch --all
+traces stream --all --no-spans
 ```
 
 That's the command in the demo above. The **deterministic pass** — stuck loops, token growth, output decay, missing self-verification, tool monoculture — needs no API key and costs nothing.
@@ -100,7 +103,9 @@ traces index    --all --since 24h --out session-index.json
 traces inspect  session-index.json --out inspection-report.md
 traces evidence --harness codex --last 20 --out policy-evidence.jsonl
 traces export   policy-evidence.jsonl --out spans.openinference.jsonl
-traces watch    --all                              # live observer; notify on stuck loops
+traces watch    --all                              # live observer; loops + semantic findings
+traces stream   --all --no-spans                   # live JSONL events for dashboards/visualizers
+traces stream   spans.openinference.jsonl --format openinference --no-spans
 traces upload   --since 1h --dry-run               # redact + dedup + preview, no network
 traces upload   --since 24h                        # upload last day to the Intelligence Platform
 ```
@@ -116,14 +121,34 @@ traces upload   --since 24h                        # upload last day to the Inte
 | `--out <path>` | Write the report to a file |
 | `--dir <path>` | `improve`: write the full artifact pack to this directory |
 | `--otlp <path>` | OTLP artifact path (also evidence provenance / dry-run upload preview) |
-| `--format <kind>` | `export`: `auto`, `policy-evidence`, `sandbox-events`, or `openinference` |
+| `--format <kind>` | `export` / file `stream`: `auto`, `policy-evidence`, `sandbox-events`, or `openinference` |
 | `--llm` / `--budget <usd>` | Enable agentic analysts (needs `OPENAI_API_KEY`) / cap their spend |
 | `--config <path>` | `investigate` / `improve`: load BYO analysts, external analyzers, and proposal adapters |
-| `--interval <s>` / `--window <m>` | `watch`: poll seconds (default 5) / active-session window minutes (default 30) |
+| `--interval <s>` / `--window <m>` | `watch` / live `stream`: poll seconds (default 5) / active-session window minutes (default 30) |
 | `--min-loop <n>` | Identical repeated calls before flagging a loop (default 3) |
+| `--replay` / `--once` | `stream`: scan once, then exit |
+| `--no-spans` / `--no-findings` | `stream`: suppress raw span rows / finding rows |
 | `--no-content` | `upload`: send metadata only — strip all prompt/response text |
 | `--dry-run` / `--yes` | `upload`: preview without sending / skip the confirm prompt |
 
+## Live stream
+
+`traces watch` is the human terminal view.
+It prints repeated-tool loops and semantic findings while a coding agent is still running.
+
+`traces stream` is the machine feed.
+It emits newline-delimited JSON events that a dashboard, art visualizer, local watcher, or hosted product can consume without scraping terminal prose.
+
+```bash
+traces stream --all
+traces stream --all --no-spans
+traces stream spans.openinference.jsonl --format openinference --no-spans
+```
+
+The stream emits `session`, `span`, `analysis_batch`, `finding`, and `tick` events.
+The semantic findings currently cover repeated failing commands, verification churn without code/config changes, completion claims without later verification, and high tool-error rates.
+Use `--no-spans` when you want the low-volume meaning layer; keep spans on for real-time visualizers that need motion, timing, and tool-call texture.
+
 ## Improvement engine
 
 `traces improve` turns observed sessions into a portable improvement packet:
@@ -289,6 +314,9 @@ The CLI is a thin consumer of these exports.
 | `runTraceStoreInvestigation` | `({ traceStore }) → TraceStoreInvestigationResult` | run the same packet layer over a hosted/custom `TraceAnalysisStore` |
 | `loadTracesConfig` | `(path?) → TracesConfig \| undefined` | load BYO analysts, external analyzers, and proposal adapters |
 | `watchSessions` | `(ObserverOptions) → Promise<void>` | live observer; `onLoop` / `onReport` / `signal` / `adapters` |
+| `streamSessions` | `(TraceStreamOptions) → Promise<void>` | live JSONL-ready event stream over active sessions |
+| `traceStreamEventsFromSpans` | `(spans, opts?) → TraceStreamEvent[]` | replay an existing span list as stream events |
+| `analyzeLiveBatch` | `(spans, opts?) → TraceLiveBatch` | compute semantic online findings for one batch |
 | `collectSessionIndex` | `(ScanOptions) → TraceSessionIndex` | scan sessions and return a reusable JSON-ready catalog |
 | `inspectSessionIndex` | `(TraceSessionIndex) → TraceInspectionReport` | rank improvement findings from an index without rescanning sessions |
 | `buildPolicyEvidenceRecord` | `(ref, spans, opts?) → PolicyEvidenceRecord` | summarize one session for downstream policy mining |
@@ -303,12 +331,15 @@ The CLI is a thin consumer of these exports.
 | `ExternalAnalyzer` / `Redactor` | `haloAnalyzer` / `commandAnalyzer` / `commandRedactor` | drive engines/models you install (not bundled) |
 
 ```ts
-import { watchSessions, analyzeSpans, AnalystRegistry, makeFinding } from '@tangle-network/traces'
+import { watchSessions, streamSessions, analyzeSpans, AnalystRegistry, makeFinding } from '@tangle-network/traces'
 
 // Observe live sessions, feed findings anywhere (read-only, cancellable):
 const c = new AbortController()
 await watchSessions({ all: true, signal: c.signal, onLoop: (l) => alert(l.toolName, l.occurrences) })
 
+// Feed a visualizer or dashboard:
+await streamSessions({ all: true, signal: c.signal, includeSpans: false, onEvent: (event) => console.log(event) })
+
 // Run your own analyst instead of the built-ins:
 const registry = new AnalystRegistry()
 registry.register({

package/dist/{chunk-QM4QAG3V.js → chunk-G3OBZSWY.js}

@@ -751,10 +751,10 @@ var ClaudeAdapter = class {
     let step = main.nextStep;
     for (const f of files) {
       if (!f.endsWith(".jsonl")) continue;
-      const hash = basename2(f, ".jsonl");
+      const hash2 = basename2(f, ".jsonl");
       let meta = {};
       try {
-        meta = JSON.parse(await readFile3(join3(subDir, `${hash}.meta.json`), "utf8"));
+        meta = JSON.parse(await readFile3(join3(subDir, `${hash2}.meta.json`), "utf8"));
       } catch {
       }
       const parent = meta.toolUseId && main.toolSpanByUseId.get(meta.toolUseId)?.span_id || `root:${traceId}`;
@@ -768,7 +768,7 @@ var ClaudeAdapter = class {
         traceId,
         agent: meta.agentType ? `subagent:${meta.agentType}` : "subagent",
         startStep: step,
-        idPrefix: `${hash}:`,
+        idPrefix: `${hash2}:`,
         rootParent: parent
       });
       out.push(...parsed.spans);
@@ -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 evidence2 of pathsFromUnknown(value)) {
-        scannedChars += evidence2.path.length;
+      for (const evidence3 of pathsFromUnknown(value)) {
+        scannedChars += evidence3.path.length;
         if (scannedChars > MAX_SPAN_TEXT_CHARS) return paths;
-        const key = `${evidence2.source}:${evidence2.path}`;
+        const key = `${evidence3.source}:${evidence3.path}`;
         if (seen.has(key)) continue;
         seen.add(key);
-        paths.push(evidence2);
+        paths.push(evidence3);
         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 evidence2 of extractAbsolutePaths(spans)) {
-    add(await repoCandidateForPath(evidence2.path), evidence2.source, evidence2.weight);
+  for (const evidence3 of extractAbsolutePaths(spans)) {
+    add(await repoCandidateForPath(evidence3.path), evidence3.source, evidence3.weight);
   }
   const resolved = [];
   for (const candidate of candidates.values()) {
@@ -2492,9 +2492,9 @@ async function buildPolicyEvidenceRecord(ref, spans, opts = {}) {
     signals: {
       stuckLoopCount: loopFindings.length,
       affectedRunRatio: pipelines.stuckLoops.affectedRunRatio,
-      stuckLoops: loopFindings.slice(0, loopLimit).map((finding) => ({
-        toolName: finding.toolName,
-        occurrences: finding.occurrences
+      stuckLoops: loopFindings.slice(0, loopLimit).map((finding2) => ({
+        toolName: finding2.toolName,
+        occurrences: finding2.occurrences
       })),
       stuckLoopsOmitted: Math.max(0, loopFindings.length - loopLimit),
       toolErrorRate: toolSpans.length === 0 ? 0 : erroredToolCallCount / toolSpans.length
@@ -3235,12 +3235,12 @@ function topLoopTools(row) {
     current.maxOccurrences = Math.max(current.maxOccurrences, loop.occurrences);
     byTool.set(loop.toolName, current);
   }
-  const loops = [...byTool.entries()].sort(([, a], [, b]) => b.groups - a.groups || b.maxOccurrences - a.maxOccurrences).slice(0, 3).map(([toolName2, stats]) => `${toolName2} ${stats.groups} group(s), max x${stats.maxOccurrences}`);
+  const loops = [...byTool.entries()].sort(([, a], [, b]) => b.groups - a.groups || b.maxOccurrences - a.maxOccurrences).slice(0, 3).map(([toolName3, stats]) => `${toolName3} ${stats.groups} group(s), max x${stats.maxOccurrences}`);
   const suffix = row.signals.stuckLoopsOmitted > 0 ? `, +${row.signals.stuckLoopsOmitted} omitted` : "";
   return loops.length > 0 ? `${loops.join(", ")}${suffix}` : `${row.signals.stuckLoopCount} loop(s)`;
 }
 function sortFindings(findings) {
-  return findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity] || b.impact - a.impact || a.id.localeCompare(b.id)).map((finding) => ({ ...finding }));
+  return findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity] || b.impact - a.impact || a.id.localeCompare(b.id)).map((finding2) => ({ ...finding2 }));
 }
 function contextSourceCounts(index) {
   return { contextFiles: allContextFiles(index).length };
@@ -3435,9 +3435,9 @@ function inspectSessionIndex(index, opts = {}) {
     },
     totals: {
       findings: ranked.length,
-      high: ranked.filter((finding) => finding.severity === "high").length,
-      medium: ranked.filter((finding) => finding.severity === "medium").length,
-      low: ranked.filter((finding) => finding.severity === "low").length
+      high: ranked.filter((finding2) => finding2.severity === "high").length,
+      medium: ranked.filter((finding2) => finding2.severity === "medium").length,
+      low: ranked.filter((finding2) => finding2.severity === "low").length
     },
     findings: ranked
   };
@@ -3456,16 +3456,16 @@ function renderInspectionReport(report) {
     return `${lines.join("\n")}
 `;
   }
-  report.findings.forEach((finding, i) => {
+  report.findings.forEach((finding2, i) => {
     lines.push("");
-    lines.push(`## ${i + 1}. [${finding.severity}] ${finding.title}`);
-    lines.push(`Area: ${finding.area}  Impact: ${finding.impact}`);
+    lines.push(`## ${i + 1}. [${finding2.severity}] ${finding2.title}`);
+    lines.push(`Area: ${finding2.area}  Impact: ${finding2.impact}`);
     lines.push("Evidence:");
-    for (const item of finding.evidence) lines.push(`- ${item}`);
-    lines.push(`Next: ${finding.next}`);
-    if (finding.refs && finding.refs.length > 0) {
+    for (const item of finding2.evidence) lines.push(`- ${item}`);
+    lines.push(`Next: ${finding2.next}`);
+    if (finding2.refs && finding2.refs.length > 0) {
       lines.push("Refs:");
-      for (const ref of finding.refs.slice(0, 5)) lines.push(`- ${ref}`);
+      for (const ref of finding2.refs.slice(0, 5)) lines.push(`- ${ref}`);
     }
   });
   return `${lines.join("\n")}
@@ -3926,55 +3926,55 @@ function normalizeExternalFindings(results) {
   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);
+      const finding2 = coerceExternalFinding(result.analyzer, row, index);
+      if (finding2) out.push(finding2);
     });
   }
   return out;
 }
-function sourceOf(finding) {
-  if (finding.analyst_id.startsWith("external:")) return "external";
-  if (finding.analyst_id === "traces-deterministic") return "deterministic";
+function sourceOf(finding2) {
+  if (finding2.analyst_id.startsWith("external:")) return "external";
+  if (finding2.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 recommendationTitle(finding2) {
+  if (finding2.recommended_action) return finding2.recommended_action.replace(/\.$/, "");
+  return `Investigate ${finding2.area}: ${finding2.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) => ({
+  return [...findings].filter((finding2) => finding2.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((finding2, 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)
+    id: `rec-${index + 1}-${slug(finding2.area)}`,
+    severity: finding2.severity,
+    title: recommendationTitle(finding2),
+    action: finding2.recommended_action ?? `Review and fix: ${finding2.claim}`,
+    rationale: finding2.rationale ?? finding2.claim,
+    evidenceRefs: finding2.evidence_refs,
+    findingIds: [finding2.finding_id],
+    validationPlan: finding2.validation_plan ?? "Rerun `traces improve` on a fresh comparable session window and confirm this finding disappears or drops in severity.",
+    source: sourceOf(finding2)
   }));
 }
 function buildClaims(findings) {
-  return findings.map((finding, index) => ({
+  return findings.map((finding2, 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
+    id: `claim-${index + 1}-${slug(finding2.area)}`,
+    severity: finding2.severity,
+    text: finding2.claim,
+    area: finding2.area,
+    sourceFindingId: finding2.finding_id,
+    evidenceRefs: finding2.evidence_refs,
+    validationPlan: finding2.validation_plan
   }));
 }
 function buildEvidenceRows(findings) {
-  return findings.flatMap((finding) => finding.evidence_refs.map((ref) => ({
+  return findings.flatMap((finding2) => finding2.evidence_refs.map((ref) => ({
     schemaVersion: 1,
     kind: "traces.improvement_evidence",
-    findingId: finding.finding_id,
-    severity: finding.severity,
-    area: finding.area,
-    claim: finding.claim,
+    findingId: finding2.finding_id,
+    severity: finding2.severity,
+    area: finding2.area,
+    claim: finding2.claim,
     evidence: ref
   })));
 }
@@ -4006,14 +4006,14 @@ function renderFindingPacket(packet, title = "Trace finding packet") {
   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}`);
+    for (const finding2 of [...packet.findings].sort((a, b) => severityRank2[a.severity] - severityRank2[b.severity] || a.area.localeCompare(b.area) || a.claim.localeCompare(b.claim))) {
+      lines.push(`### ${finding2.severity.toUpperCase()} \u2014 ${finding2.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(`- **Area:** ${finding2.area}`);
+      lines.push(`- **Analyst:** ${finding2.analyst_id}`);
+      if (finding2.recommended_action) lines.push(`- **Action:** ${finding2.recommended_action}`);
+      if (finding2.validation_plan) lines.push(`- **Check:** ${finding2.validation_plan}`);
+      for (const ref of finding2.evidence_refs.slice(0, 3)) {
         lines.push(`- **Evidence:** ${ref.kind} ${ref.uri}${ref.excerpt ? ` \u2014 \`${ref.excerpt.slice(0, 180)}\`` : ""}`);
       }
       lines.push("");
@@ -4242,8 +4242,330 @@ async function saveReport(path, report) {
   await writeFile4(path, report, "utf8");
 }
 
-// src/observer.ts
+// src/live.ts
+import { createHash as createHash2 } from "crypto";
+var VERIFY_RE = /\b(test|tests|vitest|jest|pytest|go test|cargo test|tsc|typecheck|lint|biome|eslint|build|check:invariants|preflight)\b/i;
+var CHANGE_RE = /\b(apply_patch|edit|write|create|delete|rename|replace|update|git apply|sed -i|perl -pi|tee\s|cat\s+>)/i;
+var CLAIM_DONE_RE = /\b(done|fixed|complete|completed|implemented|merged|verified|all green|tests pass|ready|works now)\b/i;
 var sleep = (ms, signal) => new Promise((resolve2) => {
+  if (signal?.aborted) {
+    resolve2();
+    return;
+  }
+  const onAbort = () => {
+    clearTimeout(t);
+    resolve2();
+  };
+  const t = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve2();
+  }, ms);
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+function hash(parts) {
+  return createHash2("sha256").update(parts.join("\0")).digest("hex").slice(0, 16);
+}
+function asString(value) {
+  if (typeof value === "string" && value.trim()) return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return void 0;
+}
+function spanKind2(span2) {
+  return asString(span2.attributes["openinference.span.kind"])?.toUpperCase() ?? "SPAN";
+}
+function spanContent(span2) {
+  return asString(span2.attributes.content) ?? asString(span2.attributes["input.value"]) ?? asString(span2.attributes["llm.input"]) ?? asString(span2.attributes["gen_ai.prompt"]) ?? "";
+}
+function toolName2(span2) {
+  return asString(span2.attributes["tool.name"]) ?? span2.name.replace(/^tool\./, "");
+}
+function toolSignature(span2) {
+  const content = spanContent(span2).replace(/\s+/g, " ").trim();
+  return `${toolName2(span2)}:${content || span2.name}`;
+}
+function isTool(span2) {
+  return spanKind2(span2) === "TOOL" || span2.attributes["tool.name"] != null || span2.name.startsWith("tool.");
+}
+function isTextSpan(span2) {
+  return !isTool(span2) && spanContent(span2).length > 0;
+}
+function isVerification(span2) {
+  if (!isTool(span2)) return false;
+  return VERIFY_RE.test(`${toolName2(span2)} ${span2.name} ${spanContent(span2)}`);
+}
+function isChange(span2) {
+  if (!isTool(span2)) return false;
+  return CHANGE_RE.test(`${toolName2(span2)} ${span2.name} ${spanContent(span2)}`);
+}
+function timeOf(span2) {
+  const parsed = Date.parse(span2.start_time);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function orderSpans(spans) {
+  return [...spans].sort((a, b) => {
+    const stepA = typeof a.attributes.step === "number" ? a.attributes.step : void 0;
+    const stepB = typeof b.attributes.step === "number" ? b.attributes.step : void 0;
+    if (stepA != null && stepB != null && stepA !== stepB) return stepA - stepB;
+    return timeOf(a) - timeOf(b);
+  });
+}
+function sessionFrom(spans, opts) {
+  const first = spans[0];
+  return {
+    harness: opts.session?.harness ?? asString(first?.attributes["service.name"]) ?? "unknown",
+    sessionId: opts.session?.sessionId ?? first?.trace_id ?? "unknown",
+    cwd: opts.session?.cwd ?? asString(first?.attributes["tangle.cwd"]) ?? null,
+    ...opts.session?.path ? { path: opts.session.path } : {}
+  };
+}
+function evidence2(kind, label, value, spanIds) {
+  return { kind, label, value, ...spanIds && spanIds.length > 0 ? { spanIds } : {} };
+}
+function finding(input) {
+  const fingerprint = hash([input.ruleId, ...input.signature]);
+  return {
+    schemaVersion: 1,
+    kind: "traces.live_finding",
+    id: `live.${input.ruleId}.${fingerprint}`,
+    fingerprint,
+    ruleId: input.ruleId,
+    severity: input.severity,
+    title: input.title,
+    claim: input.claim,
+    action: input.action,
+    check: input.check,
+    evidence: input.evidence,
+    session: input.session,
+    observedAt: input.observedAt
+  };
+}
+function analyzeLiveBatch(spans, opts = {}) {
+  const ordered2 = orderSpans(spans);
+  const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const session = sessionFrom(ordered2, opts);
+  const tools = ordered2.filter(isTool);
+  const erroredTools = tools.filter((span2) => span2.status.code === "ERROR");
+  const verificationCalls = tools.filter(isVerification);
+  const changeCalls = tools.filter(isChange);
+  const findings = [];
+  const failedBySignature = /* @__PURE__ */ new Map();
+  for (const span2 of erroredTools) {
+    const signature = toolSignature(span2);
+    failedBySignature.set(signature, [...failedBySignature.get(signature) ?? [], span2]);
+  }
+  for (const [signature, rows] of failedBySignature) {
+    if (rows.length < 2) continue;
+    findings.push(finding({
+      ruleId: "same-failing-command",
+      severity: rows.length >= 3 ? "high" : "medium",
+      title: "Same failing command is repeating",
+      claim: `${rows.length} failed tool call(s) repeated the same command or arguments.`,
+      action: "Stop rerunning it; inspect the first failure, change state, or choose a different diagnostic path before another retry.",
+      check: "The next action should read the failing file, inspect the stack/output, or edit code before this command runs again.",
+      evidence: [
+        evidence2("pattern", "command", signature, rows.map((span2) => span2.span_id)),
+        evidence2("metric", "failed_repeats", String(rows.length))
+      ],
+      session,
+      observedAt: generatedAt,
+      signature: [signature, String(rows.length)]
+    }));
+  }
+  let lastChangeIndex = -1;
+  let verificationSinceChange = 0;
+  const verificationSpanIds = [];
+  for (let i = 0; i < ordered2.length; i++) {
+    const span2 = ordered2[i];
+    if (isChange(span2)) {
+      lastChangeIndex = i;
+      verificationSinceChange = 0;
+      verificationSpanIds.length = 0;
+    } else if (isVerification(span2)) {
+      verificationSinceChange += 1;
+      verificationSpanIds.push(span2.span_id);
+    }
+  }
+  if (verificationSinceChange >= 2) {
+    findings.push(finding({
+      ruleId: "verification-without-change",
+      severity: verificationSinceChange >= 3 ? "high" : "medium",
+      title: "Verification is repeating without a state change",
+      claim: `${verificationSinceChange} verification command(s) ran after the last detected code/config change.`,
+      action: "Do not spend another verification run until the agent either edits state or explains what new signal the rerun will reveal.",
+      check: "The next action should be a code/config edit, targeted file read, or a different narrow diagnostic command.",
+      evidence: [
+        evidence2("metric", "verification_calls_since_change", String(verificationSinceChange), verificationSpanIds),
+        evidence2("metric", "change_calls", String(changeCalls.length))
+      ],
+      session,
+      observedAt: generatedAt,
+      signature: [String(verificationSinceChange), verificationSpanIds.join(",")]
+    }));
+  }
+  const lastClaim = [...ordered2].reverse().find((span2) => isTextSpan(span2) && CLAIM_DONE_RE.test(spanContent(span2)));
+  if (lastClaim) {
+    const claimTime = timeOf(lastClaim);
+    const verificationAfterClaim = verificationCalls.some((span2) => timeOf(span2) > claimTime);
+    if (!verificationAfterClaim) {
+      findings.push(finding({
+        ruleId: "completion-claim-without-verification",
+        severity: "medium",
+        title: "Completion claim has no later verification",
+        claim: "The agent claimed completion, correctness, or verification without a later verification tool call in the observed trace.",
+        action: "Require a concrete check after the claim, or downgrade the claim to an unverified hypothesis.",
+        check: "A later test/build/typecheck/lint/smoke command should appear after the claim.",
+        evidence: [
+          evidence2("span", "claim_span", spanContent(lastClaim).slice(0, 240), [lastClaim.span_id]),
+          evidence2("metric", "verification_after_claim", "0")
+        ],
+        session,
+        observedAt: generatedAt,
+        signature: [lastClaim.span_id, spanContent(lastClaim).slice(0, 120)]
+      }));
+    }
+  }
+  if (tools.length >= 4 && erroredTools.length / tools.length >= 0.5) {
+    findings.push(finding({
+      ruleId: "high-tool-error-rate",
+      severity: erroredTools.length / tools.length >= 0.75 ? "high" : "medium",
+      title: "Tool calls are mostly failing",
+      claim: `${erroredTools.length}/${tools.length} tool call(s) in this live batch ended with ERROR.`,
+      action: "Switch from broad execution to diagnosis: classify the dominant error, then run one targeted command to validate the fix path.",
+      check: "The next batch should reduce the error ratio or show a new targeted diagnostic result.",
+      evidence: [
+        evidence2("metric", "errored_tool_calls", `${erroredTools.length}/${tools.length}`, erroredTools.map((span2) => span2.span_id))
+      ],
+      session,
+      observedAt: generatedAt,
+      signature: [String(erroredTools.length), String(tools.length)]
+    }));
+  }
+  return {
+    schemaVersion: 1,
+    kind: "traces.live_batch",
+    generatedAt,
+    session,
+    spanCount: ordered2.length,
+    newSpanCount: opts.newSpanCount ?? ordered2.length,
+    toolCallCount: tools.length,
+    erroredToolCallCount: erroredTools.length,
+    verificationCallCount: verificationCalls.length,
+    changeCallCount: changeCalls.length,
+    findingCount: findings.length,
+    findings
+  };
+}
+function sessionEvent(session, spans, generatedAt) {
+  const ordered2 = orderSpans(spans);
+  return {
+    schemaVersion: 1,
+    kind: "traces.stream.session",
+    event: "session",
+    generatedAt,
+    session,
+    spanCount: ordered2.length,
+    startedAt: ordered2[0]?.start_time ?? null,
+    endedAt: ordered2.at(-1)?.end_time ?? null
+  };
+}
+function traceStreamEventsFromSpans(spans, opts = {}) {
+  const generatedAt = opts.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const session = sessionFrom(spans, {
+    ...opts,
+    session: opts.ref ? { harness: opts.ref.harness, sessionId: opts.ref.sessionId, cwd: opts.ref.cwd, path: opts.ref.path } : opts.session
+  });
+  const ordered2 = orderSpans(spans);
+  const batch = analyzeLiveBatch(ordered2, { generatedAt, session, newSpanCount: ordered2.length });
+  const events = [sessionEvent(session, ordered2, generatedAt)];
+  if (opts.includeSpans !== false) {
+    for (const span2 of ordered2) {
+      events.push({ schemaVersion: 1, kind: "traces.stream.span", event: "span", generatedAt, session, span: span2 });
+    }
+  }
+  events.push({ schemaVersion: 1, kind: "traces.stream.batch", event: "analysis_batch", generatedAt, batch });
+  if (opts.includeFindings !== false) {
+    for (const liveFinding of batch.findings) {
+      events.push({ schemaVersion: 1, kind: "traces.stream.finding", event: "finding", generatedAt, finding: liveFinding });
+    }
+  }
+  return events;
+}
+function serializeTraceStreamEvent(event) {
+  return `${JSON.stringify(event)}
+`;
+}
+async function streamSessions(opts) {
+  const intervalMs = Math.max(250, opts.intervalMs ?? 5e3);
+  const windowMs = opts.windowMs ?? 30 * 6e4;
+  const includeSpans = opts.includeSpans !== false;
+  const includeFindings = opts.includeFindings !== false;
+  const includeBatches = opts.includeBatches !== false;
+  const seenSessions = /* @__PURE__ */ new Set();
+  const seenSpans = /* @__PURE__ */ new Set();
+  const seenFindings = /* @__PURE__ */ new Set();
+  while (!opts.signal?.aborted) {
+    let sessions = 0;
+    let newSpans = 0;
+    let findings = 0;
+    for await (const { adapter, ref, spans } of scanSessions({
+      ...opts,
+      sinceMs: opts.sinceMs ?? Date.now() - windowMs,
+      signal: opts.signal
+    })) {
+      const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const session = { harness: adapter.harness, sessionId: ref.sessionId, cwd: ref.cwd, path: ref.path };
+      const ordered2 = orderSpans(spans);
+      const sessionKey = `${session.harness}:${session.sessionId}`;
+      const unseen = ordered2.filter((span2) => {
+        const key = `${sessionKey}:${span2.span_id}`;
+        if (seenSpans.has(key)) return false;
+        seenSpans.add(key);
+        return true;
+      });
+      sessions += 1;
+      newSpans += unseen.length;
+      if (!seenSessions.has(sessionKey)) {
+        seenSessions.add(sessionKey);
+        await opts.onEvent(sessionEvent(session, ordered2, generatedAt));
+      }
+      if (includeSpans) {
+        for (const span2 of unseen) {
+          await opts.onEvent({ schemaVersion: 1, kind: "traces.stream.span", event: "span", generatedAt, session, span: span2 });
+        }
+      }
+      const batch = analyzeLiveBatch(ordered2, { generatedAt, session, newSpanCount: unseen.length });
+      if (includeBatches) {
+        await opts.onEvent({ schemaVersion: 1, kind: "traces.stream.batch", event: "analysis_batch", generatedAt, batch });
+      }
+      if (includeFindings) {
+        for (const liveFinding of batch.findings) {
+          if (seenFindings.has(liveFinding.id)) continue;
+          seenFindings.add(liveFinding.id);
+          findings += 1;
+          await opts.onEvent({ schemaVersion: 1, kind: "traces.stream.finding", event: "finding", generatedAt, finding: liveFinding });
+        }
+      }
+    }
+    await opts.onEvent({
+      schemaVersion: 1,
+      kind: "traces.stream.tick",
+      event: "tick",
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sessions,
+      newSpans,
+      findings
+    });
+    if (opts.once || opts.signal?.aborted) break;
+    await sleep(intervalMs, opts.signal);
+  }
+}
+
+// src/observer.ts
+var sleep2 = (ms, signal) => new Promise((resolve2) => {
+  if (signal?.aborted) {
+    resolve2();
+    return;
+  }
   const onAbort = () => {
     clearTimeout(t);
     resolve2();
@@ -4254,14 +4576,15 @@ var sleep = (ms, signal) => new Promise((resolve2) => {
   }, ms);
   signal?.addEventListener("abort", onAbort, { once: true });
 });
-function loopKey(sessionId, toolName2, argHash) {
-  return `${sessionId}\0${toolName2}\0${argHash}`;
+function loopKey(sessionId, toolName3, argHash) {
+  return `${sessionId}:${toolName3}:${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();
+  const seenFindings = /* @__PURE__ */ new Set();
   while (!opts.signal?.aborted) {
     let sessionCount = 0;
     for await (const { adapter, ref, spans } of scanSessions({
@@ -4288,6 +4611,27 @@ async function watchSessions(opts) {
           opts.onError?.(err, ref);
         }
       }
+      const batch = analyzeLiveBatch(spans, {
+        session: { harness: adapter.harness, sessionId: ref.sessionId, cwd: ref.cwd, path: ref.path }
+      });
+      if (opts.onBatch) {
+        try {
+          await opts.onBatch(ref, batch);
+        } catch (err) {
+          opts.onError?.(err, ref);
+        }
+      }
+      if (opts.onFinding) {
+        for (const finding2 of batch.findings) {
+          if (seenFindings.has(finding2.id)) continue;
+          seenFindings.add(finding2.id);
+          try {
+            await opts.onFinding(finding2);
+          } 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)) {
@@ -4316,7 +4660,7 @@ async function watchSessions(opts) {
       opts.onError?.(err);
     }
     if (opts.signal?.aborted) break;
-    await sleep(intervalMs, opts.signal);
+    await sleep2(intervalMs, opts.signal);
   }
 }
 
@@ -4543,7 +4887,7 @@ async function writeSessionIndexFile(index, outPath) {
 }
 
 // src/upload-state.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { mkdir as mkdir2, readFile as readFile15, writeFile as writeFile6 } from "fs/promises";
 import { homedir as homedir11 } from "os";
 import { dirname as dirname4, join as join18 } from "path";
@@ -4555,7 +4899,7 @@ function uploadKey(harness, sessionId) {
   return `${harness}:${sessionId}`;
 }
 function sessionHash(spans) {
-  const h = createHash2("sha256");
+  const h = createHash3("sha256");
   for (const s of spans) {
     h.update(`${s.span_id}\0${s.name}\0${s.start_time}\0${s.status.code}
 `);
@@ -4575,8 +4919,8 @@ async function saveState(state) {
   await writeFile6(f, `${JSON.stringify(state, null, 2)}
 `, "utf8");
 }
-function alreadyUploaded(state, harness, sessionId, hash) {
-  return state[uploadKey(harness, sessionId)]?.hash === hash;
+function alreadyUploaded(state, harness, sessionId, hash2) {
+  return state[uploadKey(harness, sessionId)]?.hash === hash2;
 }
 
 // src/upload.ts
@@ -4593,13 +4937,13 @@ async function planUpload(opts = {}) {
   const items = [];
   for await (const { ref, spans: raw } of scanSessions(opts)) {
     const { spans, report } = redactSpans(raw);
-    const hash = sessionHash(spans);
+    const hash2 = sessionHash(spans);
     items.push({
       ref,
       spans,
       redaction: report,
-      hash,
-      isNew: !alreadyUploaded(state, ref.harness, ref.sessionId, hash)
+      hash: hash2,
+      isNew: !alreadyUploaded(state, ref.harness, ref.sessionId, hash2)
     });
   }
   return { items, state, sinceMs: opts.sinceMs };
@@ -4796,6 +5140,10 @@ export {
   writeTraceImprovementArtifacts,
   runTraceImprovementLoop,
   saveReport,
+  analyzeLiveBatch,
+  traceStreamEventsFromSpans,
+  serializeTraceStreamEvent,
+  streamSessions,
   watchSessions,
   buildSessionIndex,
   buildSessionIndexFromRows,

package/dist/cli.js

@@ -33,18 +33,22 @@ import {
   serializePolicyEvidence,
   serializeSessionIndex,
   serializeSpans,
+  serializeTraceStreamEvent,
+  streamSessions,
   summarizeDeterministicSignals,
+  traceStreamEventsFromSpans,
   watchSessions,
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile
-} from "./chunk-QM4QAG3V.js";
+} from "./chunk-G3OBZSWY.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
 import { readFile, stat, writeFile } from "fs/promises";
+import { basename, resolve } from "path";
 function packageVersion() {
   const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   if (typeof pkg.version !== "string" || !pkg.version) throw new Error("package.json is missing version");
@@ -66,6 +70,9 @@ function parseArgs(argv) {
     yes: false,
     noContent: false,
     analyzers: [],
+    replay: false,
+    noSpans: false,
+    noFindings: false,
     attrs: []
   };
   for (let i = 1; i < argv.length; i++) {
@@ -135,6 +142,16 @@ function parseArgs(argv) {
       case "--no-content":
         a.noContent = true;
         break;
+      case "--replay":
+      case "--once":
+        a.replay = true;
+        break;
+      case "--no-spans":
+        a.noSpans = true;
+        break;
+      case "--no-findings":
+        a.noFindings = true;
+        break;
       case "--analyzer": {
         const v = next();
         if (v) a.analyzers.push(v);
@@ -486,12 +503,102 @@ async function cmdImprove(args) {
     `improvement artifacts \u2192 ${dir}  (${result.findings.length} findings, ${result.recommendations.length} recommendations, ${result.proposals.length} proposal(s), OTLP: ${result.otlpPath})`
   );
 }
+function summarizeFindingEvidence(finding) {
+  const first = finding.evidence[0];
+  if (!first) return "no evidence";
+  return `${first.label}: ${first.value}`;
+}
+function formatLiveFinding(finding) {
+  const ts = new Date(finding.observedAt).toISOString().slice(11, 19);
+  const where = `[${finding.session.harness}] ${finding.session.sessionId.slice(0, 8)}`;
+  const cwd = finding.session.cwd ? ` \xB7 ${finding.session.cwd}` : "";
+  return [
+    `${ts} ${finding.severity.toUpperCase()} ${where} \u2014 ${finding.title}${cwd}`,
+    `  evidence: ${summarizeFindingEvidence(finding)}`,
+    `  action: ${finding.action}`,
+    `  check: ${finding.check}`
+  ].join("\n");
+}
+async function streamExplicitSession(args) {
+  if (!args.session) throw new Error("streamExplicitSession needs --session");
+  const adapter = resolveAdapter(args.harness);
+  if (!adapter) throw new Error(`unknown harness "${args.harness}"`);
+  const st = await stat(args.session);
+  const ref = {
+    harness: adapter.harness,
+    sessionId: basename(args.session),
+    path: resolve(args.session),
+    cwd: args.cwd ?? null,
+    mtimeMs: st.mtimeMs
+  };
+  const spans = await parseSession(adapter, ref);
+  for (const event of traceStreamEventsFromSpans(spans, {
+    ref,
+    includeSpans: !args.noSpans,
+    includeFindings: !args.noFindings
+  })) {
+    process.stdout.write(serializeTraceStreamEvent(event));
+  }
+}
+async function cmdStream(args) {
+  if (args.input) {
+    const { spans, harness } = await collectImportedSpans(args);
+    const ref = {
+      harness,
+      sessionId: basename(args.input),
+      path: resolve(args.input),
+      cwd: args.cwd ?? null,
+      mtimeMs: Date.now()
+    };
+    for (const event of traceStreamEventsFromSpans(spans, {
+      ref,
+      includeSpans: !args.noSpans,
+      includeFindings: !args.noFindings
+    })) {
+      process.stdout.write(serializeTraceStreamEvent(event));
+    }
+    return;
+  }
+  if (args.session) {
+    await streamExplicitSession(args);
+    return;
+  }
+  const all = args.all || !args.harnessExplicit && !args.cwd;
+  const controller = new AbortController();
+  process.once("SIGINT", () => controller.abort());
+  if (!args.replay) {
+    process.stderr.write(
+      `traces stream \u2014 JSONL live feed for ${all ? "all harnesses" : args.harness}, last ${args.window}m, every ${args.interval}s. Ctrl-C to stop.
+`
+    );
+  }
+  await streamSessions({
+    all,
+    harnesses: all ? void 0 : [args.harness],
+    cwd: args.cwd,
+    last: args.last > 0 ? args.last : args.replay ? 1 : void 0,
+    windowMs: args.window * 6e4,
+    intervalMs: args.interval * 1e3,
+    once: args.replay,
+    includeSpans: !args.noSpans,
+    includeFindings: !args.noFindings,
+    signal: controller.signal,
+    onEvent: (event) => {
+      process.stdout.write(serializeTraceStreamEvent(event));
+    },
+    onError: (err, ref) => {
+      const where = ref ? ` [${ref.harness}] ${ref.sessionId}` : "";
+      process.stderr.write(`stream error${where}: ${err instanceof Error ? err.message : String(err)}
+`);
+    }
+  });
+}
 async function cmdWatch(args) {
   const all = args.all || !args.harnessExplicit && !args.cwd;
   const controller = new AbortController();
   process.once("SIGINT", () => controller.abort());
   process.stderr.write(
-    `traces watch \u2014 observing ${all ? "all harnesses" : args.harness}, sessions active in the last ${args.window}m, every ${args.interval}s. Read-only; Ctrl-C to stop.
+    `traces watch \u2014 observing ${all ? "all harnesses" : args.harness}, sessions active in the last ${args.window}m, every ${args.interval}s. Loop + semantic live findings; read-only; Ctrl-C to stop.
 `
   );
   await watchSessions({
@@ -505,9 +612,13 @@ async function cmdWatch(args) {
     onLoop: (l) => {
       const ts = (/* @__PURE__ */ new Date()).toISOString().slice(11, 19);
       process.stdout.write(
-        `\u26A0\uFE0F  ${ts} [${l.harness}] ${l.sessionId.slice(0, 8)} \u2014 \`${l.toolName}\` repeated \xD7${l.occurrences} with identical args (${(l.windowMs / 1e3).toFixed(0)}s)${l.cwd ? ` \xB7 ${l.cwd}` : ""}
+        `${ts} LOOP [${l.harness}] ${l.sessionId.slice(0, 8)} \u2014 \`${l.toolName}\` repeated \xD7${l.occurrences} with identical args (${(l.windowMs / 1e3).toFixed(0)}s)${l.cwd ? ` \xB7 ${l.cwd}` : ""}
 `
       );
+    },
+    onFinding: (finding) => {
+      process.stdout.write(`${formatLiveFinding(finding)}
+`);
     }
   });
 }
@@ -607,14 +718,15 @@ Commands:
   inspect   Read a session index and print ranked improvement findings
   export    Convert evidence/events files to OpenInference JSONL for HALO
   evidence  Emit compact session-evidence JSONL for downstream policy miners
-  watch     Online observer: tail active sessions, notify on stuck loops (read-only)
+  stream    Emit JSONL trace stream events for live visualizers or replay
+  watch     Online observer: tail active sessions, notify on loops + semantic findings
   upload    Redact + upload sessions in a time window to the Tangle Intelligence Platform
 
 Options:
   --harness <id>   Harness or alias (default: claude-code). Known: ${knownHarnesses().join(", ")}
   --all            Sweep every known harness
   --last <n>       Most-recent N sessions
-  --session <path> Analyze one explicit session file
+  --session <path> Analyze/stream one explicit harness session file
   --cwd <dir>      Filter sessions by working directory
   --since <t>      upload: window \u2014 30m / 2h / 7d or an ISO date (default 24h); analyze: ISO cutoff
   --out <path>     Write report to a file
@@ -623,6 +735,9 @@ Options:
   --format <kind>  analyze/export file: auto | policy-evidence | sandbox-events | openinference | intelligence-spans
   --metadata <json> analyze/export file: attach JSON object fields as span attributes
   --attr <k=v>     analyze/export file: attach one span attribute (repeatable)
+  --replay, --once stream: scan once and exit (default for positional input / --session)
+  --no-spans       stream: omit per-span pulse events
+  --no-findings    stream: omit semantic live-finding events
   --llm            Enable agentic RLM analysts (needs OPENAI_API_KEY / OPENAI_BASE_URL)
   --model <id>     --llm model id (e.g. a router model like glm-5.2); default is agent-eval's
   --config <path>  investigate/improve: JS config with analysts, external analyzers, or proposal adapter
@@ -685,6 +800,9 @@ async function main() {
     case "evidence":
       await cmdEvidence(args);
       break;
+    case "stream":
+      await cmdStream(args);
+      break;
     case "watch":
       await cmdWatch(args);
       break;

package/dist/index.d.ts

@@ -1276,6 +1276,115 @@ declare function writeTraceImprovementArtifacts(result: Pick<TraceImprovementRes
 declare function runTraceImprovementLoop(opts: TraceImprovementOptions): Promise<TraceImprovementResult>;
 declare function saveReport(path: string, report: string): Promise<void>;
 
+type TraceLiveSeverity = 'info' | 'low' | 'medium' | 'high';
+interface TraceLiveEvidence {
+    readonly kind: 'metric' | 'span' | 'pattern';
+    readonly label: string;
+    readonly value: string;
+    readonly spanIds?: readonly string[];
+}
+interface TraceLiveFinding {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.live_finding';
+    readonly id: string;
+    readonly ruleId: string;
+    readonly fingerprint: string;
+    readonly severity: TraceLiveSeverity;
+    readonly title: string;
+    readonly claim: string;
+    readonly action: string;
+    readonly check: string;
+    readonly evidence: readonly TraceLiveEvidence[];
+    readonly session: TraceStreamSession;
+    readonly observedAt: string;
+}
+interface TraceStreamSession {
+    readonly harness: string;
+    readonly sessionId: string;
+    readonly cwd: string | null;
+    readonly path?: string;
+}
+interface TraceLiveBatch {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.live_batch';
+    readonly generatedAt: string;
+    readonly session: TraceStreamSession;
+    readonly spanCount: number;
+    readonly newSpanCount: number;
+    readonly toolCallCount: number;
+    readonly erroredToolCallCount: number;
+    readonly verificationCallCount: number;
+    readonly changeCallCount: number;
+    readonly findingCount: number;
+    readonly findings: readonly TraceLiveFinding[];
+}
+type TraceStreamEvent = {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.stream.session';
+    readonly event: 'session';
+    readonly generatedAt: string;
+    readonly session: TraceStreamSession;
+    readonly spanCount: number;
+    readonly startedAt: string | null;
+    readonly endedAt: string | null;
+} | {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.stream.span';
+    readonly event: 'span';
+    readonly generatedAt: string;
+    readonly session: TraceStreamSession;
+    readonly span: OtlpSpan;
+} | {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.stream.batch';
+    readonly event: 'analysis_batch';
+    readonly generatedAt: string;
+    readonly batch: TraceLiveBatch;
+} | {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.stream.finding';
+    readonly event: 'finding';
+    readonly generatedAt: string;
+    readonly finding: TraceLiveFinding;
+} | {
+    readonly schemaVersion: 1;
+    readonly kind: 'traces.stream.tick';
+    readonly event: 'tick';
+    readonly generatedAt: string;
+    readonly sessions: number;
+    readonly newSpans: number;
+    readonly findings: number;
+};
+interface LiveBatchOptions {
+    readonly generatedAt?: string;
+    readonly session?: Partial<TraceStreamSession>;
+    readonly newSpanCount?: number;
+}
+interface TraceStreamReplayOptions extends LiveBatchOptions {
+    readonly ref?: SessionRef;
+    readonly includeSpans?: boolean;
+    readonly includeFindings?: boolean;
+}
+interface TraceStreamOptions extends ScanOptions {
+    /** Observe sessions active within this window. Default 30 min. */
+    readonly windowMs?: number;
+    /** Poll interval. Default 5s. */
+    readonly intervalMs?: number;
+    /** Stop after one scan, useful for replay or tests. */
+    readonly once?: boolean;
+    /** Emit one JSON event per new span. Default true. */
+    readonly includeSpans?: boolean;
+    /** Emit live semantic findings. Default true. */
+    readonly includeFindings?: boolean;
+    /** Emit session and analysis-batch events. Default true. */
+    readonly includeBatches?: boolean;
+    readonly onEvent: (event: TraceStreamEvent) => void | Promise<void>;
+}
+declare function analyzeLiveBatch(spans: readonly OtlpSpan[], opts?: LiveBatchOptions): TraceLiveBatch;
+declare function traceStreamEventsFromSpans(spans: readonly OtlpSpan[], opts?: TraceStreamReplayOptions): TraceStreamEvent[];
+declare function serializeTraceStreamEvent(event: TraceStreamEvent): string;
+declare function streamSessions(opts: TraceStreamOptions): Promise<void>;
+
 /**
  * Live trace observer — the reusable, event-driven core behind `traces watch`.
  *
@@ -1323,6 +1432,10 @@ interface ObserverOptions {
     /** Fired for every observed session each tick, with its full pipeline report
      *  (stuck loops + tool-use metrics) — react to anything, not just loops. */
     onReport?: (ref: SessionRef, report: PipelineReport) => void | Promise<void>;
+    /** Fired for every observed session each tick, after semantic live analysis. */
+    onBatch?: (ref: SessionRef, batch: TraceLiveBatch) => void | Promise<void>;
+    /** Fired once for each newly-observed live semantic finding. */
+    onFinding?: (finding: TraceLiveFinding) => void | Promise<void>;
     /** Per-session parse/pipeline error (the observer keeps going). */
     onError?: (error: unknown, ref?: SessionRef) => void;
     /** Fired after each poll cycle. */
@@ -1489,4 +1602,4 @@ interface ExecuteOptions {
 /** Send the NEW items (or, on dryRun, write the redacted OTLP that would send). */
 declare function executeUpload(plan: UploadPlan, opts?: ExecuteOptions): Promise<UploadResult>;
 
-export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, type FindingStore, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type ImprovementAdapter, type ImprovementAdapterInput, type ImprovementProposal, type InspectSessionIndexOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type RecommendationWriter, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceClaim, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceRecommendation, type TraceReplayProof, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TracesConfig, type TriggerPair, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, inspectSessionIndex, knownHarnesses, listAdapters, loadState, loadTracesConfig, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, parseIsoToEpochMs, parseSession, parseSince, planUpload, readSessionIndexFile, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovementLoop, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, sessionHash, span, stampRepoAttrs, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };
+export { ACTOR_ATTR, ATTR, type Actor, type AdoptionOptions, type AdoptionReport, AmpAdapter, type AnalyzeOptions, type AnalyzeResult, type BuildPolicyEvidenceOptions, type BuildSessionIndexOptions, type BuildTraceFindingPacketOptions, CODING_REDACTION_RULES, CONTENT_CAP, CORRECTIVE_REACTIONS, ClaudeAdapter, CodexAdapter, type CollectOptions, type CollectPolicyEvidenceOptions, type CollectSessionIndexOptions, CopilotAdapter, DEFAULT_HARNESS, type ExecuteOptions, type ExternalAnalysisResult, type ExternalAnalyzer, FactoryAdapter, type FindingStore, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, INGEST_SOURCE_CLI, type ImprovementAdapter, type ImprovementAdapterInput, type ImprovementProposal, type InspectSessionIndexOptions, type LiveBatchOptions, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, type PolicyEvidenceLoopSummary, type PolicyEvidenceRecord, type PolicyEvidenceToolSummary, QwenAdapter, REACTIONS, type Reaction, type ReactionReport, type ReactionSessionReport, type RecommendationWriter, type Redactor, type RepoAttrs, type RepoResolution, type RepoResolutionSource, type RunResult, type RuntimeTrace, type ScanOptions, type ScannedSession, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type TraceClaim, type TraceContextIndex, type TraceContextRoot, type TraceEvidenceExportOptions, type TraceEvidenceExportResult, type TraceEvidenceFormatOption, type TraceEvidenceInputFormat, type TraceEvidenceRow, type TraceFindingPacket, type TraceImprovementArtifacts, type TraceImprovementOptions, type TraceImprovementResult, type TraceIndexedFile, type TraceInspectionArea, type TraceInspectionFinding, type TraceInspectionReport, type TraceInspectionSeverity, type TraceInvestigationOptions, type TraceInvestigationResult, type TraceLiveBatch, type TraceLiveEvidence, type TraceLiveFinding, type TraceLiveSeverity, type TraceRecommendation, type TraceReplayProof, type TraceSessionIndex, type TraceSessionIndexRow, type TraceStoreInvestigationOptions, type TraceStoreInvestigationResult, type TraceStreamEvent, type TraceStreamOptions, type TraceStreamReplayOptions, type TraceStreamSession, type TracesConfig, type TriggerPair, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, type UserPromptInput, alreadyUploaded, analyzeAdoption, analyzeLiveBatch, analyzeReactions, analyzeSpans, applyRedactor, buildPolicyEvidenceRecord, buildSessionIndex, buildSessionIndexFromRows, buildTraceFindingPacket, capText, classifyReaction, claudeActor, codexActor, collectPolicyEvidence, collectSessionIndex, collectSessions, commandAnalyzer, commandRedactor, countSkillRunsJsonl, executeUpload, exportTraceEvidenceFile, exportTraceEvidenceRows, exportTraceEvidenceText, haloAnalyzer, inspectSessionIndex, knownHarnesses, listAdapters, loadState, loadTracesConfig, looksLikeAgentPrompt, mergeTracesConfig, normalizeRemote, parseIsoToEpochMs, parseSession, parseSince, planUpload, readSessionIndexFile, redactSpans, renderInspectionReport, resolveAdapter, resolveRepoAttrs, resolveSessionRepoAttrs, runCommand, runExternalAnalyzers, runPipelines, runTraceImprovementLoop, runTraceInvestigation, runTraceStoreInvestigation, saveReport, saveState, scanSessions, selectAdapters, serializeInspectionReport, serializePolicyEvidence, serializeSessionIndex, serializeSpans, serializeTraceStreamEvent, sessionHash, span, stampRepoAttrs, streamSessions, textIsSynthetic, toOpenInferenceSpan, toRuntimeStore, toTraceSpanEvents, traceStreamEventsFromSpans, uploadKey, userPromptSpan, watchSessions, writeInspectionReportFile, writeOtlpFile, writePolicyEvidenceFile, writeSessionIndexFile, writeTraceEvidenceExportFile, writeTraceImprovementArtifacts };

package/dist/index.js

@@ -20,6 +20,7 @@ import {
   TRACES_REDACTION_RULES,
   alreadyUploaded,
   analyzeAdoption,
+  analyzeLiveBatch,
   analyzeReactions,
   analyzeSpans,
   applyRedactor,
@@ -73,13 +74,16 @@ import {
   serializePolicyEvidence,
   serializeSessionIndex,
   serializeSpans,
+  serializeTraceStreamEvent,
   sessionHash,
   span,
   stampRepoAttrs,
+  streamSessions,
   textIsSynthetic,
   toOpenInferenceSpan,
   toRuntimeStore,
   toTraceSpanEvents,
+  traceStreamEventsFromSpans,
   uploadKey,
   userPromptSpan,
   watchSessions,
@@ -89,7 +93,7 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceImprovementArtifacts
-} from "./chunk-QM4QAG3V.js";
+} from "./chunk-G3OBZSWY.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {
@@ -137,6 +141,7 @@ export {
   TRACES_REDACTION_RULES,
   alreadyUploaded,
   analyzeAdoption,
+  analyzeLiveBatch,
   analyzeReactions,
   analyzeSpans,
   applyRedactor,
@@ -197,13 +202,16 @@ export {
   serializePolicyEvidence,
   serializeSessionIndex,
   serializeSpans,
+  serializeTraceStreamEvent,
   sessionHash,
   span,
   stampRepoAttrs,
+  streamSessions,
   textIsSynthetic,
   toOpenInferenceSpan,
   toRuntimeStore,
   toTraceSpanEvents,
+  traceStreamEventsFromSpans,
   uploadKey,
   userPromptSpan,
   watchSessions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.8.17",
+  "version": "0.8.18",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",