@tangle-network/traces 0.2.0 → 0.2.1

package/README.md

@@ -1,28 +1,44 @@
 # traces
 
-Point it at your coding-agent session traces and get **failure-mode + efficiency findings** — without instrumenting anything. It reads the logs your harness already writes to disk.
+Analyze your coding-agent session logs for failure modes — stuck loops, token bloat, dropped self-verification — with zero instrumentation. It reads the logs your harness (Claude Code, Codex, OpenCode, …) already writes to disk.
 
-Built for the recurring problem: agents loop, re-send their whole history, stop verifying their own work, and get stuck. `traces` surfaces that from the trace, deterministically.
+`traces` is a CLI and an SDK: run it ad-hoc, or build on it.
+
+## Install
 
 ```bash
-npx @tangle-network/traces analyze --harness claude-code --last 1
+npm i -g @tangle-network/traces     # the `traces` CLI
+npx @tangle-network/traces analyze  # or run without installing
+npm i @tangle-network/traces        # or use it as a library
 ```
 
-## What it does
+## Quick start
 
-1. Reads a harness's native session log (no OpenTelemetry setup required).
-2. Normalizes it to OTLP-JSONL — the shape the [`@tangle-network/agent-eval`](https://www.npmjs.com/package/@tangle-network/agent-eval) analyst suite *and* [HALO](https://github.com/context-labs/halo) consume.
-3. Runs the analysts and writes a markdown report.
+```bash
+traces analyze --harness claude-code --last 1
+```
 
-The deterministic pass (token-growth, output-decay, tool-monoculture, missing self-verification) needs **no API key and costs nothing**. Add `--llm` for the agentic RLM analysts (failure-mode / knowledge-gap / knowledge-poisoning / improvement).
+```
+# Trace report — claude-code · 1 session · 2,429 spans
+
+## Stuck loops
+- `bash` ×7 with identical args in 48s   (same git status retried, no state change)
+
+## Tool use
+- 1,204 tool calls · duplicate-call 22% · retry 6% · error 8%
+```
+
+The deterministic pass (stuck loops, token growth, tool monoculture, missing self-verification) needs no API key and costs nothing. Add `--llm` for the agentic analysts (failure-mode / knowledge-gap / knowledge-poisoning / improvement); they call OpenAI and respect `--budget`.
+
+The written OTLP-JSONL artifact also feeds [HALO](https://github.com/context-labs/halo) (`halo spans.jsonl -p "diagnose"`) — analysis is never locked to one engine.
 
 ## Supported harnesses
 
-Covers the coding-agent CLIs in the agent-dev-container nix profile. "Verified" = parser exercised against real on-disk sessions; "fixture" = parser exercised against a schema-accurate fixture (no local sessions to test); see the test suite.
+"Verified" = tested against real sessions; "fixture" = tested against schema-accurate fixtures (no real sessions available).
 
 | Harness (aliases) | Reads from | Status |
 |---|---|---|
-| `claude-code` (`claudish`, `openclaw`, `nanoclaw`) | `~/.claude/projects/<cwd>/*.jsonl` (+ subagent sidechains) | verified |
+| `claude-code` (`claude`, `claudish`, `openclaw`, `nanoclaw`) | `~/.claude/projects/<cwd>/*.jsonl` (+ subagent sidechains) | verified |
 | `codex` (`codex-acp`) | `~/.codex/sessions/**/rollout-*.jsonl` | verified |
 | `opencode` | `~/.local/share/opencode/storage/` | verified |
 | `gemini` (`gemini-cli`) | `~/.gemini/tmp/<hash>/chats/session-*.json` | verified |
@@ -31,97 +47,68 @@ Covers the coding-agent CLIs in the agent-dev-container nix profile. "Verified"
 | `qwen` (`qwen-code`) | `~/.qwen/projects/<cwd>/chats/*.jsonl` | fixture |
 | `amp` | `~/.local/share/amp/threads/T-*.json` | fixture |
 | `github-copilot` (`copilot`) | `~/.copilot/session-state/<id>/events.jsonl` | fixture |
-| `forge` (`forgecode`) | `/dump` JSON exports (live `~/.forge/.forge.db` SQLite is a follow-up) | fixture |
-
-Notes: Factory's token totals live in the `.settings.json` sidecar (no per-turn usage). Forge's primary store is SQLite; v1 reads its dependency-free `/dump` exports. ACP-only bridges (`claude-agent-acp`) may not persist a local transcript at all.
+| `forge` (`forgecode`) | `/dump` JSON exports | fixture |
 
-Adding a harness is one file implementing `HarnessTraceAdapter` (`locate` + `parse`) in `src/adapters/`.
+Factory stores token totals in `.settings.json`, not per turn. Forge reads `/dump` JSON exports (live SQLite is a follow-up). ACP-only bridges may not persist a local transcript.
 
 ## Commands
 
 ```bash
-traces list     --harness claude-code --last 20      # discover sessions
-traces analyze  --harness codex --last 1             # $0 deterministic report
+traces list     --harness claude-code --last 20    # discover sessions
+traces analyze  --harness codex --last 1           # $0 deterministic report
 traces analyze  --all --since 2026-06-18 --out report.md
-traces convert  --harness claude-code --last 1 --otlp spans.jsonl   # OTLP only → HALO
-traces analyze  --harness claude-code --last 1 --llm  # +agentic (needs OPENAI_API_KEY)
-traces watch    --all                                 # live observer: notify on stuck loops (read-only)
-traces upload   --since 1h --dry-run                  # redact + dedup + preview, no network
-traces upload   --since 24h                           # upload last day to the Intelligence Platform
+traces convert  --harness claude-code --last 1 --otlp spans.jsonl   # OTLP only
+traces watch    --all                              # live observer; notify on stuck loops
+traces upload   --since 1h --dry-run               # redact + dedup + preview, no network
+traces upload   --since 24h                        # upload last day to the Intelligence Platform
 ```
 
-### Options
-
 | Flag | Meaning |
 |---|---|
 | `--harness <id>` | Harness or alias (default: `claude-code`) |
-| `--all` | Sweep every known harness |
+| `--all` | Every known harness |
 | `--last <n>` | Most-recent N sessions |
-| `--session <path>` | Analyze one explicit session file |
-| `--cwd <dir>` | Filter sessions by working directory |
+| `--session <path>` | One explicit session file |
+| `--cwd <dir>` | Filter by working directory |
 | `--since <t>` | `upload`: window — `30m`/`2h`/`7d` or ISO (default 24h); `analyze`: ISO cutoff |
-| `--out <path>` | Write report to a file |
+| `--out <path>` | Write the report to a file |
 | `--otlp <path>` | OTLP artifact path (also the dry-run upload preview) |
-| `--llm` | Enable agentic RLM analysts (needs `OPENAI_API_KEY`) |
-| `--budget <usd>` | USD cap for agentic analysts |
-| `--dry-run` | `upload`: redact + dedup + preview, do not send |
-| `--yes`, `-y` | `upload`: skip the confirmation prompt |
-| `--interval <s>` / `--window <m>` | `watch`: poll interval / active-session window |
+| `--llm` / `--budget <usd>` | Enable agentic analysts (needs `OPENAI_API_KEY`) / cap their spend |
+| `--interval <s>` / `--window <m>` | `watch`: poll seconds (default 5) / active-session window minutes (default 30) |
 | `--min-loop <n>` | Identical repeated calls before flagging a loop (default 3) |
+| `--dry-run` / `--yes` | `upload`: preview without sending / skip the confirm prompt |
 
-**Upload** redacts PII/secrets *before anything leaves the machine*, dedups against already-uploaded sessions, and tags each session with metadata (harness, cwd, git branch, host). It needs the platform env: `TANGLE_INGEST_URL` (or `TANGLE_ORCHESTRATOR_URL`), `TANGLE_INGEST_API_KEY` (or `TANGLE_API_KEY`), `TANGLE_TENANT_ID`. Without them, `--dry-run` still works fully.
+`upload` redacts PII/secrets locally before anything leaves the machine, dedups against already-uploaded sessions, and tags each with metadata (harness, cwd, git branch, host). It needs `TANGLE_INGEST_URL` (or `TANGLE_ORCHESTRATOR_URL`), `TANGLE_INGEST_API_KEY` (or `TANGLE_API_KEY`), and `TANGLE_TENANT_ID`; without them, `--dry-run` still works.
 
 ## Use as a library
 
-The CLI is a thin layer over an exported SDK — build your own tooling on top:
+The CLI is a thin consumer of these exports. Full runnable examples in [`examples/`](./examples).
 
-```ts
-import {
-  watchSessions, collectSessions, analyzeSpans, executeUpload,
-  AnalystRegistry, makeFinding, listAdapters,
-} from '@tangle-network/traces'
-```
-
-**Observe live sessions** and feed findings into your own system (read-only, cancellable):
+| Export | Signature | Use |
+|---|---|---|
+| `analyzeSpans` | `(spans, { registry?, ai?, budgetUsd? }) → AnalyzeResult` | run analysts — built-in, or **your own** via `registry` |
+| `watchSessions` | `(ObserverOptions) → Promise<void>` | live observer; `onLoop` / `onReport` / `signal` / `adapters` |
+| `collectSessions` | `(CollectOptions) → SessionBatch[]` | redacted per-session batches for your own pipeline |
+| `redactSpans` | `(spans, rules?) → { spans, report }` | PII/secret redaction (`TRACES_REDACTION_RULES`) |
+| `planUpload` / `executeUpload` | `(…, { backend? }) → …` | redact + dedup + send to any sink |
+| `listAdapters` / `resolveAdapter` | `() → […]` / `(id) → adapter` | the harness registry |
+| `HarnessTraceAdapter` | interface (`locate` + `parse`) | implement to add a harness |
 
 ```ts
-const controller = new AbortController()
-await watchSessions({
-  all: true,
-  signal: controller.signal,
-  onLoop: (loop) => alertSlack(`stuck loop: ${loop.toolName} ×${loop.occurrences} in ${loop.sessionId}`),
-  onReport: (ref, report) => metrics.record(ref.harness, report.toolUse),
-})
-```
+import { watchSessions, analyzeSpans, AnalystRegistry, makeFinding } from '@tangle-network/traces'
 
-**Run your OWN analysts** (any agent/detector) instead of the built-ins — register against the
-[`@tangle-network/agent-eval`](https://www.npmjs.com/package/@tangle-network/agent-eval) `AnalystRegistry`:
+// 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) })
 
-```ts
+// Run your own analyst instead of the built-ins:
 const registry = new AnalystRegistry()
-registry.register({
-  id: 'my-detector', description: '…', inputKind: 'trace-store',
-  cost: { kind: 'deterministic' }, version: '1.0.0',
-  async analyze(store, ctx) { /* your logic */ return [makeFinding({ /* … */ })] },
-})
-const { result } = await analyzeSpans(spans, { registry })
-```
-
-**Collect redacted batches** to feed a vector store / fine-tune corpus / another pipeline:
-
-```ts
-const batches = await collectSessions({ all: true, sinceMs: Date.now() - 3_600_000 })
-//        → [{ ref, spans /* redacted */, redaction }]
-```
-
-**Upload to your own backend** (anything implementing `ingestTraces`), not just Tangle:
-
-```ts
-await executeUpload(plan, { backend: { async ingestTraces(spans, key) { /* POST anywhere */ return { accepted: spans.length } } } })
+registry.register({ id: 'mine', description: '…', inputKind: 'trace-store', cost: { kind: 'deterministic' }, version: '1.0.0',
+  async analyze() { return [makeFinding({ analyst_id: 'mine', area: 'custom', claim: '…', severity: 'info', evidence_refs: [], confidence: 0.9 })] } })
+await analyzeSpans(spans, { registry })
 ```
 
-**Register a new harness** — implement `HarnessTraceAdapter` (`locate` + `parse`) and pass it via
-`adapters: [...]` to `watchSessions`/`collectSessions`, or drop a file in `src/adapters/`.
+Add a new harness: implement `HarnessTraceAdapter` and pass it via `adapters: [...]` to `watchSessions`/`collectSessions`, or drop a file in `src/adapters/`. See [`examples/register-harness.ts`](./examples/register-harness.ts).
 
 ## Develop
 

package/dist/{chunk-HPBKRTTP.js → chunk-YYVPAOOD.js}

@@ -31,29 +31,21 @@ function serializeSpans(spans) {
 `;
 }
 async function writeOtlpFile(spans, outPath) {
-  const { mkdtemp: mkdtemp2, writeFile: writeFile3 } = await import("fs/promises");
-  const { tmpdir: tmpdir2 } = await import("os");
-  const { join: join14 } = await import("path");
-  const path = outPath ?? join14(await mkdtemp2(join14(tmpdir2(), "tangle-traces-")), "spans.otlp.jsonl");
-  await writeFile3(path, serializeSpans(spans), "utf8");
+  const { mkdtemp, writeFile: writeFile2 } = await import("fs/promises");
+  const { tmpdir } = await import("os");
+  const { join: join13 } = await import("path");
+  const path = outPath ?? join13(await mkdtemp(join13(tmpdir(), "traces-")), "spans.otlp.jsonl");
+  await writeFile2(path, serializeSpans(spans), "utf8");
   return path;
 }
 
 // src/analyze.ts
-import { mkdtemp, writeFile } from "fs/promises";
-import { tmpdir } from "os";
-import { join } from "path";
 import { buildDefaultAnalystRegistry } from "@tangle-network/agent-eval/analyst";
 import { OtlpFileTraceStore } from "@tangle-network/agent-eval/traces";
-async function writeOtlp(spans, outPath) {
-  const path = outPath ?? join(await mkdtemp(join(tmpdir(), "traces-")), "spans.otlp.jsonl");
-  await writeFile(path, serializeSpans(spans), "utf8");
-  return path;
-}
 var DETERMINISTIC_VIEW_CEILING = 256 * 1024 * 1024;
 async function analyzeSpans(spans, opts = {}) {
   if (spans.length === 0) throw new Error("analyzeSpans: no spans to analyze");
-  const otlpPath = await writeOtlp(spans, opts.otlpOutPath);
+  const otlpPath = await writeOtlpFile(spans, opts.otlpOutPath);
   const runId = opts.runId ?? `traces-${Date.now()}`;
   const detStore = new OtlpFileTraceStore({ path: otlpPath, perCallByteCeiling: DETERMINISTIC_VIEW_CEILING });
   await detStore.ensureIndexed();
@@ -135,13 +127,13 @@ async function runPipelines(spans, opts = {}) {
 // src/adapters/amp.ts
 import { readdir, readFile, stat } from "fs/promises";
 import { homedir } from "os";
-import { basename, join as join2 } from "path";
+import { basename, join } from "path";
 var SERVICE = "amp";
 var AmpAdapter = class {
   harness = "amp";
   threadsRoot() {
-    const base = process.env.XDG_DATA_HOME ?? join2(homedir(), ".local", "share");
-    return join2(base, "amp", "threads");
+    const base = process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+    return join(base, "amp", "threads");
   }
   async locate(opts = {}) {
     let files;
@@ -153,7 +145,7 @@ var AmpAdapter = class {
     const refs = [];
     for (const f of files) {
       if (!f.startsWith("T-") || !f.endsWith(".json")) continue;
-      const path = join2(this.threadsRoot(), f);
+      const path = join(this.threadsRoot(), f);
       let st;
       try {
         st = await stat(path);
@@ -235,7 +227,7 @@ var AmpAdapter = class {
 // src/adapters/claude.ts
 import { readdir as readdir2, readFile as readFile2, stat as stat2 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { basename as basename2, join as join3 } from "path";
+import { basename as basename2, join as join2 } from "path";
 var SERVICE2 = "claude-code";
 function parseLines(raw) {
   const out = [];
@@ -333,7 +325,7 @@ var ClaudeAdapter = class {
   harness = "claude-code";
   aliases = ["claude", "claudish", "openclaw", "nanoclaw"];
   root() {
-    return join3(homedir2(), ".claude", "projects");
+    return join2(homedir2(), ".claude", "projects");
   }
   async locate(opts = {}) {
     const root = this.root();
@@ -345,7 +337,7 @@ var ClaudeAdapter = class {
     }
     const refs = [];
     for (const dir of projectDirs) {
-      const dirPath = join3(root, dir);
+      const dirPath = join2(root, dir);
       let files;
       try {
         files = await readdir2(dirPath);
@@ -354,7 +346,7 @@ var ClaudeAdapter = class {
       }
       for (const f of files) {
         if (!f.endsWith(".jsonl")) continue;
-        const path = join3(dirPath, f);
+        const path = join2(dirPath, f);
         let st;
         try {
           st = await stat2(path);
@@ -401,7 +393,7 @@ var ClaudeAdapter = class {
   }
   /** Parse `<session>/subagents/agent-*.jsonl`, parenting each under its Agent call. */
   async foldSubagents(ref, traceId, main, out) {
-    const subDir = join3(ref.path.replace(/\.jsonl$/, ""), "subagents");
+    const subDir = join2(ref.path.replace(/\.jsonl$/, ""), "subagents");
     let files;
     try {
       files = await readdir2(subDir);
@@ -414,13 +406,13 @@ var ClaudeAdapter = class {
       const hash = basename2(f, ".jsonl");
       let meta = {};
       try {
-        meta = JSON.parse(await readFile2(join3(subDir, `${hash}.meta.json`), "utf8"));
+        meta = JSON.parse(await readFile2(join2(subDir, `${hash}.meta.json`), "utf8"));
       } catch {
       }
       const parent = meta.toolUseId && main.toolSpanByUseId.get(meta.toolUseId)?.span_id || `root:${traceId}`;
       let raw;
       try {
-        raw = await readFile2(join3(subDir, f), "utf8");
+        raw = await readFile2(join2(subDir, f), "utf8");
       } catch {
         continue;
       }
@@ -440,7 +432,7 @@ var ClaudeAdapter = class {
 // src/adapters/codex.ts
 import { readdir as readdir3, readFile as readFile3, stat as stat3 } from "fs/promises";
 import { homedir as homedir3 } from "os";
-import { basename as basename3, join as join4 } from "path";
+import { basename as basename3, join as join3 } from "path";
 var SERVICE3 = "codex";
 function parseLines2(raw) {
   const out = [];
@@ -473,7 +465,7 @@ async function* walkRollouts(root) {
     return;
   }
   for (const y of years) {
-    const yp = join4(root, y);
+    const yp = join3(root, y);
     let months;
     try {
       months = await readdir3(yp);
@@ -481,7 +473,7 @@ async function* walkRollouts(root) {
       continue;
     }
     for (const m of months) {
-      const mp = join4(yp, m);
+      const mp = join3(yp, m);
       let days;
       try {
         days = await readdir3(mp);
@@ -489,7 +481,7 @@ async function* walkRollouts(root) {
         continue;
       }
       for (const d of days) {
-        const dp = join4(mp, d);
+        const dp = join3(mp, d);
         let files;
         try {
           files = await readdir3(dp);
@@ -497,7 +489,7 @@ async function* walkRollouts(root) {
           continue;
         }
         for (const f of files) {
-          if (f.startsWith("rollout-") && f.endsWith(".jsonl")) yield join4(dp, f);
+          if (f.startsWith("rollout-") && f.endsWith(".jsonl")) yield join3(dp, f);
         }
       }
     }
@@ -507,7 +499,7 @@ var CodexAdapter = class {
   harness = "codex";
   aliases = ["codex-acp"];
   root() {
-    return process.env.CODEX_HOME ? join4(process.env.CODEX_HOME, "sessions") : join4(homedir3(), ".codex", "sessions");
+    return process.env.CODEX_HOME ? join3(process.env.CODEX_HOME, "sessions") : join3(homedir3(), ".codex", "sessions");
   }
   async locate(opts = {}) {
     const refs = [];
@@ -635,7 +627,7 @@ var CodexAdapter = class {
 // src/adapters/copilot.ts
 import { readdir as readdir4, readFile as readFile4, stat as stat4 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
+import { join as join4 } from "path";
 var SERVICE4 = "github-copilot";
 function parseLines3(raw) {
   const out = [];
@@ -652,7 +644,7 @@ var CopilotAdapter = class {
   harness = "github-copilot";
   aliases = ["copilot"];
   root() {
-    return join5(process.env.COPILOT_HOME ?? join5(homedir4(), ".copilot"), "session-state");
+    return join4(process.env.COPILOT_HOME ?? join4(homedir4(), ".copilot"), "session-state");
   }
   async locate(opts = {}) {
     let dirs;
@@ -663,7 +655,7 @@ var CopilotAdapter = class {
     }
     const refs = [];
     for (const id of dirs) {
-      const path = join5(this.root(), id, "events.jsonl");
+      const path = join4(this.root(), id, "events.jsonl");
       let st;
       try {
         st = await stat4(path);
@@ -761,7 +753,7 @@ var CopilotAdapter = class {
 // src/adapters/factory.ts
 import { readdir as readdir5, readFile as readFile5, stat as stat5 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { basename as basename4, join as join6 } from "path";
+import { basename as basename4, join as join5 } from "path";
 var SERVICE5 = "factory";
 function parseLines4(raw) {
   const out = [];
@@ -778,7 +770,7 @@ var FactoryAdapter = class {
   harness = "factory";
   aliases = ["factory-droids", "droid"];
   root() {
-    return join6(homedir5(), ".factory", "sessions");
+    return join5(homedir5(), ".factory", "sessions");
   }
   async locate(opts = {}) {
     const root = this.root();
@@ -790,7 +782,7 @@ var FactoryAdapter = class {
     }
     const refs = [];
     for (const dir of dirs) {
-      const dp = join6(root, dir);
+      const dp = join5(root, dir);
       let files;
       try {
         files = await readdir5(dp);
@@ -801,7 +793,7 @@ var FactoryAdapter = class {
       if (opts.cwd && !cwd.startsWith(opts.cwd)) continue;
       for (const f of files) {
         if (!f.endsWith(".jsonl")) continue;
-        const path = join6(dp, f);
+        const path = join5(dp, f);
         let st;
         try {
           st = await stat5(path);
@@ -899,7 +891,7 @@ var FactoryAdapter = class {
 // src/adapters/forge.ts
 import { readdir as readdir6, readFile as readFile6, stat as stat6 } from "fs/promises";
 import { homedir as homedir6 } from "os";
-import { basename as basename5, join as join7 } from "path";
+import { basename as basename5, join as join6 } from "path";
 var SERVICE6 = "forge";
 function tokens(t) {
   if (!t) return null;
@@ -910,7 +902,7 @@ var ForgeAdapter = class {
   aliases = ["forgecode"];
   /** Directories scanned for `*-dump.json` exports. */
   dumpDirs() {
-    return [process.cwd(), join7(homedir6(), ".forge")];
+    return [process.cwd(), join6(homedir6(), ".forge")];
   }
   async locate(opts = {}) {
     const refs = [];
@@ -924,7 +916,7 @@ var ForgeAdapter = class {
       }
       for (const f of files) {
         if (!f.endsWith("-dump.json")) continue;
-        const path = join7(dir, f);
+        const path = join6(dir, f);
         let st;
         try {
           st = await stat6(path);
@@ -1009,7 +1001,7 @@ var ForgeAdapter = class {
 // src/adapters/gemini.ts
 import { readdir as readdir7, readFile as readFile7, stat as stat7 } from "fs/promises";
 import { homedir as homedir7 } from "os";
-import { join as join8 } from "path";
+import { join as join7 } from "path";
 function iso(ts, fallback) {
   if (typeof ts === "number") return new Date(ts).toISOString();
   if (typeof ts === "string" && ts.length > 0) return ts;
@@ -1030,7 +1022,7 @@ var GeminiFamilyAdapter = class {
     this.homeDirName = cfg.homeDirName;
   }
   chatsRoot() {
-    return join8(homedir7(), this.homeDirName, "tmp");
+    return join7(homedir7(), this.homeDirName, "tmp");
   }
   async locate(opts = {}) {
     const root = this.chatsRoot();
@@ -1042,7 +1034,7 @@ var GeminiFamilyAdapter = class {
     }
     const refs = [];
     for (const pd of projectDirs) {
-      const chatsDir = join8(root, pd, "chats");
+      const chatsDir = join7(root, pd, "chats");
       let files;
       try {
         files = await readdir7(chatsDir);
@@ -1051,7 +1043,7 @@ var GeminiFamilyAdapter = class {
       }
       for (const f of files) {
         if (!f.startsWith("session-") || !f.endsWith(".json")) continue;
-        const path = join8(chatsDir, f);
+        const path = join7(chatsDir, f);
         let st;
         try {
           st = await stat7(path);
@@ -1147,7 +1139,7 @@ var GeminiAdapter = class extends GeminiFamilyAdapter {
 // src/adapters/opencode.ts
 import { readdir as readdir8, readFile as readFile8, stat as stat8 } from "fs/promises";
 import { homedir as homedir8 } from "os";
-import { join as join9 } from "path";
+import { join as join8 } from "path";
 var SERVICE7 = "opencode";
 function isoOf(ms2) {
   return new Date(ms2 ?? 0).toISOString();
@@ -1155,11 +1147,11 @@ function isoOf(ms2) {
 var OpencodeAdapter = class {
   harness = "opencode";
   storage() {
-    const base = process.env.XDG_DATA_HOME ?? join9(homedir8(), ".local", "share");
-    return join9(base, "opencode", "storage");
+    const base = process.env.XDG_DATA_HOME ?? join8(homedir8(), ".local", "share");
+    return join8(base, "opencode", "storage");
   }
   async locate(opts = {}) {
-    const msgRoot = join9(this.storage(), "message");
+    const msgRoot = join8(this.storage(), "message");
     let sessionDirs;
     try {
       sessionDirs = await readdir8(msgRoot);
@@ -1168,7 +1160,7 @@ var OpencodeAdapter = class {
     }
     const refs = [];
     for (const sid of sessionDirs) {
-      const dir = join9(msgRoot, sid);
+      const dir = join8(msgRoot, sid);
       let st;
       try {
         st = await stat8(dir);
@@ -1185,7 +1177,7 @@ var OpencodeAdapter = class {
   async parse(ref) {
     const traceId = ref.sessionId;
     const rootId = `root:${traceId}`;
-    const partRoot = join9(this.storage(), "part");
+    const partRoot = join8(this.storage(), "part");
     let msgFiles;
     try {
       msgFiles = (await readdir8(ref.path)).filter((f) => f.endsWith(".json"));
@@ -1195,7 +1187,7 @@ var OpencodeAdapter = class {
     const messages = [];
     for (const f of msgFiles) {
       try {
-        messages.push({ msg: JSON.parse(await readFile8(join9(ref.path, f), "utf8")), file: f });
+        messages.push({ msg: JSON.parse(await readFile8(join8(ref.path, f), "utf8")), file: f });
       } catch {
       }
     }
@@ -1235,7 +1227,7 @@ var OpencodeAdapter = class {
         })
       );
       step += 1;
-      const pdir = join9(partRoot, mid);
+      const pdir = join8(partRoot, mid);
       let partFiles;
       try {
         partFiles = (await readdir8(pdir)).filter((f) => f.endsWith(".json"));
@@ -1245,7 +1237,7 @@ var OpencodeAdapter = class {
       for (const pf of partFiles) {
         let part;
         try {
-          part = JSON.parse(await readFile8(join9(pdir, pf), "utf8"));
+          part = JSON.parse(await readFile8(join8(pdir, pf), "utf8"));
         } catch {
           continue;
         }
@@ -1279,7 +1271,7 @@ var OpencodeAdapter = class {
 // src/adapters/pi.ts
 import { readdir as readdir9, readFile as readFile9, stat as stat9 } from "fs/promises";
 import { homedir as homedir9 } from "os";
-import { basename as basename6, join as join10 } from "path";
+import { basename as basename6, join as join9 } from "path";
 var SERVICE8 = "pi";
 function parseLines5(raw) {
   const out = [];
@@ -1305,7 +1297,7 @@ function textOf(content) {
 var PiAdapter = class {
   harness = "pi";
   root() {
-    return join10(homedir9(), ".pi", "agent", "sessions");
+    return join9(homedir9(), ".pi", "agent", "sessions");
   }
   async locate(opts = {}) {
     const root = this.root();
@@ -1317,7 +1309,7 @@ var PiAdapter = class {
     }
     const refs = [];
     for (const dir of dirs) {
-      const dp = join10(root, dir);
+      const dp = join9(root, dir);
       let files;
       try {
         files = await readdir9(dp);
@@ -1328,7 +1320,7 @@ var PiAdapter = class {
       if (opts.cwd && !cwd.startsWith(opts.cwd)) continue;
       for (const f of files) {
         if (!f.endsWith(".jsonl")) continue;
-        const path = join10(dp, f);
+        const path = join9(dp, f);
         let st;
         try {
           st = await stat9(path);
@@ -1427,7 +1419,7 @@ var PiAdapter = class {
 // src/adapters/qwen.ts
 import { readdir as readdir10, readFile as readFile10, stat as stat10 } from "fs/promises";
 import { homedir as homedir10 } from "os";
-import { basename as basename7, join as join11 } from "path";
+import { basename as basename7, join as join10 } from "path";
 var SERVICE9 = "qwen";
 function parseLines6(raw) {
   const out = [];
@@ -1448,7 +1440,7 @@ var QwenAdapter = class {
   harness = "qwen";
   aliases = ["qwen-code"];
   root() {
-    return join11(homedir10(), ".qwen", "projects");
+    return join10(homedir10(), ".qwen", "projects");
   }
   async locate(opts = {}) {
     const root = this.root();
@@ -1460,7 +1452,7 @@ var QwenAdapter = class {
     }
     const refs = [];
     for (const pd of projectDirs) {
-      const chatsDir = join11(root, pd, "chats");
+      const chatsDir = join10(root, pd, "chats");
       let files;
       try {
         files = await readdir10(chatsDir);
@@ -1470,7 +1462,7 @@ var QwenAdapter = class {
       if (opts.cwd) continue;
       for (const f of files) {
         if (!f.endsWith(".jsonl")) continue;
-        const path = join11(chatsDir, f);
+        const path = join10(chatsDir, f);
         let st;
         try {
           st = await stat10(path);
@@ -1596,11 +1588,15 @@ function knownHarnesses() {
 
 // src/observer.ts
 var sleep = (ms2, signal) => new Promise((resolve) => {
-  const t = setTimeout(resolve, ms2);
-  signal?.addEventListener("abort", () => {
+  const onAbort = () => {
     clearTimeout(t);
     resolve();
-  }, { once: true });
+  };
+  const t = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms2);
+  signal?.addEventListener("abort", onAbort, { once: true });
 });
 function adaptersFor(opts) {
   if (opts.adapters && opts.adapters.length > 0) return opts.adapters;
@@ -1645,27 +1641,41 @@ async function watchSessions(opts) {
           continue;
         }
         sessionCount += 1;
-        if (opts.onReport) await opts.onReport(ref, report);
+        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) {
-              await opts.onLoop({
-                harness: adapter.harness,
-                sessionId: ref.sessionId,
-                cwd: ref.cwd,
-                toolName: f.toolName,
-                argHash: f.argHash,
-                occurrences: f.occurrences,
-                windowMs: f.windowMs
-              });
+              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);
+              }
             }
           }
         }
       }
     }
-    opts.onTick?.({ sessions: sessionCount });
+    try {
+      opts.onTick?.({ sessions: sessionCount });
+    } catch (err) {
+      opts.onError?.(err);
+    }
     if (opts.signal?.aborted) break;
     await sleep(intervalMs, opts.signal);
   }
@@ -1705,12 +1715,12 @@ function redactSpans(spans, rules = TRACES_REDACTION_RULES) {
 
 // src/upload-state.ts
 import { createHash } from "crypto";
-import { mkdir, readFile as readFile11, writeFile as writeFile2 } from "fs/promises";
+import { mkdir, readFile as readFile11, writeFile } from "fs/promises";
 import { homedir as homedir11 } from "os";
-import { dirname, join as join12 } from "path";
+import { dirname, join as join11 } from "path";
 function stateFile() {
-  const base = process.env.XDG_STATE_HOME ?? join12(homedir11(), ".local", "state");
-  return join12(base, "tangle-traces", "uploaded.json");
+  const base = process.env.XDG_STATE_HOME ?? join11(homedir11(), ".local", "state");
+  return join11(base, "tangle-traces", "uploaded.json");
 }
 function uploadKey(harness, sessionId) {
   return `${harness}:${sessionId}`;
@@ -1733,7 +1743,7 @@ async function loadState() {
 async function saveState(state) {
   const f = stateFile();
   await mkdir(dirname(f), { recursive: true });
-  await writeFile2(f, `${JSON.stringify(state, null, 2)}
+  await writeFile(f, `${JSON.stringify(state, null, 2)}
 `, "utf8");
 }
 function alreadyUploaded(state, harness, sessionId, hash) {
@@ -1744,7 +1754,7 @@ function alreadyUploaded(state, harness, sessionId, hash) {
 import { readFile as readFile12 } from "fs/promises";
 import { createRequire } from "module";
 import { hostname } from "os";
-import { basename as basename8, join as join13 } from "path";
+import { basename as basename8, join as join12 } 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);
@@ -1762,14 +1772,16 @@ async function planUpload(opts) {
     let refs;
     try {
       refs = await adapter.locate({ cwd: opts.cwd, sinceMs: opts.sinceMs });
-    } catch {
+    } catch (err) {
+      opts.onError?.(err);
       continue;
     }
     for (const ref of refs) {
       let raw;
       try {
         raw = await adapter.parse(ref);
-      } catch {
+      } catch (err) {
+        opts.onError?.(err, ref);
         continue;
       }
       if (raw.length === 0) continue;
@@ -1789,7 +1801,7 @@ async function planUpload(opts) {
 async function gitBranch(cwd) {
   if (!cwd) return void 0;
   try {
-    const head = await readFile12(join13(cwd, ".git", "HEAD"), "utf8");
+    const head = await readFile12(join12(cwd, ".git", "HEAD"), "utf8");
     const m = head.match(/^ref:\s*refs\/heads\/(.+)$/m);
     return m?.[1]?.trim();
   } catch {
@@ -1892,7 +1904,6 @@ export {
   span,
   serializeSpans,
   writeOtlpFile,
-  writeOtlp,
   analyzeSpans,
   toRuntimeStore,
   runPipelines,

package/dist/cli.js

@@ -8,8 +8,8 @@ import {
   resolveAdapter,
   runPipelines,
   watchSessions,
-  writeOtlp
-} from "./chunk-HPBKRTTP.js";
+  writeOtlpFile
+} from "./chunk-YYVPAOOD.js";
 
 // src/cli.ts
 import { stat, writeFile } from "fs/promises";
@@ -254,7 +254,7 @@ async function collectSpans(args) {
 async function cmdConvert(args) {
   const { spans } = await collectSpans(args);
   if (spans.length === 0) throw new Error("no spans found for the given selection");
-  const path = await writeOtlp(spans, args.otlp);
+  const path = await writeOtlpFile(spans, args.otlp);
   console.log(`wrote ${spans.length} spans \u2192 ${path}`);
 }
 async function cmdAnalyze(args) {

package/dist/index.d.ts

@@ -442,8 +442,6 @@ interface AnalyzeResult {
     otlpPath: string;
     result: Awaited<ReturnType<ReturnType<typeof buildDefaultAnalystRegistry>['run']>>;
 }
-/** Write spans to an OTLP-JSONL file and return its path. */
-declare function writeOtlp(spans: readonly OtlpSpan[], outPath?: string): Promise<string>;
 declare function analyzeSpans(spans: readonly OtlpSpan[], opts?: AnalyzeOptions): Promise<AnalyzeResult>;
 
 /**
@@ -553,6 +551,8 @@ interface CollectOptions {
     last?: number;
     /** Redact PII/secrets (default true). Set false to get raw spans. */
     redact?: boolean;
+    /** Called on a per-adapter locate/parse failure (collection continues). */
+    onError?: (error: unknown, ref?: SessionRef) => void;
 }
 interface SessionBatch {
     ref: SessionRef;
@@ -622,6 +622,8 @@ interface PlanOptions {
     all?: boolean;
     cwd?: string;
     sinceMs?: number;
+    /** Called on a per-adapter locate/parse failure (planning continues). */
+    onError?: (error: unknown, ref?: SessionRef) => void;
 }
 /** Read-only: select sessions in the window, redact, and mark which are new. */
 declare function planUpload(opts: PlanOptions): Promise<UploadPlan>;
@@ -654,4 +656,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 { AmpAdapter, type AnalyzeOptions, type AnalyzeResult, CODING_REDACTION_RULES, ClaudeAdapter, CodexAdapter, type CollectOptions, CopilotAdapter, type ExecuteOptions, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, QwenAdapter, type RuntimeTrace, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, alreadyUploaded, analyzeSpans, collectSessions, executeUpload, knownHarnesses, listAdapters, loadState, planUpload, redactSpans, resolveAdapter, runPipelines, saveState, serializeSpans, sessionHash, span, toRuntimeStore, toTraceSpanEvents, uploadKey, watchSessions, writeOtlp, writeOtlpFile };
+export { AmpAdapter, type AnalyzeOptions, type AnalyzeResult, CODING_REDACTION_RULES, ClaudeAdapter, CodexAdapter, type CollectOptions, CopilotAdapter, type ExecuteOptions, FactoryAdapter, ForgeAdapter, GeminiAdapter, type HarnessTraceAdapter, type LocateOptions, type ObservedLoop, type ObserverOptions, OpencodeAdapter, type OtlpSpan, type OtlpSpanKind, type OtlpStatusCode, PiAdapter, type PipelineOptions, type PipelineReport, type PlanOptions, QwenAdapter, type RuntimeTrace, type SessionBatch, type SessionRef, type SpanInput, type SpanRedaction, TRACES_REDACTION_RULES, type UploadBackend, type UploadItem, type UploadPlan, type UploadRecord, type UploadResult, type UploadState, alreadyUploaded, analyzeSpans, collectSessions, executeUpload, knownHarnesses, listAdapters, loadState, planUpload, redactSpans, resolveAdapter, runPipelines, saveState, serializeSpans, sessionHash, span, toRuntimeStore, toTraceSpanEvents, uploadKey, watchSessions, writeOtlpFile };

package/dist/index.js

@@ -29,9 +29,8 @@ import {
   toTraceSpanEvents,
   uploadKey,
   watchSessions,
-  writeOtlp,
   writeOtlpFile
-} from "./chunk-HPBKRTTP.js";
+} from "./chunk-YYVPAOOD.js";
 
 // src/collect.ts
 function adaptersFor(opts) {
@@ -50,7 +49,8 @@ async function collectSessions(opts = {}) {
     let refs;
     try {
       refs = await adapter.locate({ cwd: opts.cwd, sinceMs: opts.sinceMs });
-    } catch {
+    } catch (err) {
+      opts.onError?.(err);
       continue;
     }
     if (opts.last && opts.last > 0) refs = refs.slice(0, opts.last);
@@ -58,7 +58,8 @@ async function collectSessions(opts = {}) {
       let spans;
       try {
         spans = await adapter.parse(ref);
-      } catch {
+      } catch (err) {
+        opts.onError?.(err, ref);
         continue;
       }
       if (spans.length === 0) continue;
@@ -121,6 +122,5 @@ export {
   toTraceSpanEvents,
   uploadKey,
   watchSessions,
-  writeOtlp,
   writeOtlpFile
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",