@tangle-network/traces 0.15.4 → 0.16.0

package/dist/cli.js

@@ -8,6 +8,7 @@ import {
   appendAll,
   assembleSessionBundle,
   assertOutsideSourceBundle,
+  assessSpans,
   buildPolicyEvidenceRecord,
   buildSessionFactsReport,
   buildSessionIndexFromRows,
@@ -17,11 +18,13 @@ import {
   collectSessionSelection,
   commandAnalyzer,
   commandRedactor,
+  diffRuns,
   executeUpload,
   exportTraceEvidenceFile,
   externalFailureMessage,
   fileRunContextSupervisorRunReader,
   findingRejectionDetail,
+  formatVerdict,
   haloAnalyzer,
   hodoscopeAnalyzer,
   importCodeTraceBench,
@@ -34,14 +37,19 @@ import {
   locateSessions,
   mergeTracesConfig,
   normalizeTraceQuestions,
+  openAgenticTraceStore,
+  parseIsoToEpochMs,
   parseSession,
   parseSince,
   planUpload,
   primeAnalyzer,
   projectSessionBundle,
+  readJsonl,
   readOtlpInput,
   readSessionIndexFile,
+  redactSpans,
   renderInspectionReport,
+  renderRunDiff,
   renderSessionFacts,
   renderValidation,
   resolveAdapter,
@@ -57,26 +65,31 @@ import {
   serializeTraceStreamEvent,
   sessionReportSource,
   streamSessions,
+  toolArgumentsFromAttributes,
   totalAgenticFailureMessage,
   traceStreamEventsFromSpans,
+  tracesVersion,
   validationExitCode,
+  verdictExitCode,
   verifyFindingsInSandbox,
+  verifySafe,
   verifySessionBundle,
   watchRunTarget,
   watchSessions,
+  writeAnalysisTraceFile,
   writeInspectionReportFile,
   writeOtlpFile,
   writePolicyEvidenceFile,
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceQuestionsArtifacts
-} from "./chunk-SKOW5V5U.js";
+} from "./chunk-G5KKIQZ6.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
-import { mkdir, mkdtemp, readFile, stat, writeFile } from "fs/promises";
+import { mkdir as mkdir2, mkdtemp, readFile as readFile2, stat, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir } from "os";
-import { basename, join, resolve } from "path";
+import { basename, join as join2, resolve } from "path";
 import {
   parseCorpusFlag,
   renderVerifiedFindingsSection
@@ -89,11 +102,306 @@ import {
   renderSupervisorRunMarkdown,
   rollupSupervisorRuns
 } from "@tangle-network/agent-eval/supervisor-run";
-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");
-  return pkg.version;
+
+// src/mcp.ts
+import { rm } from "fs/promises";
+import { dirname } from "path";
+import { buildTraceAnalysisToolDescriptors, redact, shareAllowed, UNTRUSTED_TRACE_TEXT } from "@tangle-network/agent-eval/traces";
+import { createStdioToolServer } from "@tangle-network/agent-runtime/mcp";
+var MCP_RESULT_BYTE_CAP = 512 * 1024;
+async function traceMcpTools(options) {
+  const { spans } = redactSpans(options.spans);
+  const verdict = assessSpans(spans);
+  if (!shareAllowed(verdict)) {
+    const findings = verdict.findings.map((f) => `${f.category}/${f.detector} (${f.count})`).join(", ");
+    throw new Error(
+      `mcp: refusing to serve \u2014 redacted spans are still ${verdict.status}` + (findings ? `: ${findings}` : "") + (verdict.unreadable.length > 0 ? `; unreadable: ${verdict.unreadable.join("; ")}` : "")
+    );
+  }
+  const file = await writeAnalysisTraceFile(spans);
+  const store = await openAgenticTraceStore(file);
+  const descriptors = buildTraceAnalysisToolDescriptors({ store }).filter((d) => d.name !== "readSpanSource");
+  const tools = descriptors.map((descriptor) => ({
+    name: descriptor.name,
+    description: descriptor.description,
+    inputSchema: descriptor.parameters,
+    annotations: {
+      readOnlyHint: descriptor.readOnly,
+      idempotentHint: descriptor.idempotent,
+      destructiveHint: false,
+      openWorldHint: false
+    },
+    handler: async (args) => {
+      const { value } = redact(await descriptor.handler(args));
+      const result = { untrusted: UNTRUSTED_TRACE_TEXT, result: value };
+      const bytes = Buffer.byteLength(JSON.stringify(result));
+      if (bytes > MCP_RESULT_BYTE_CAP) {
+        throw new RangeError(
+          `${descriptor.name}: result is ${bytes} bytes, above the ${MCP_RESULT_BYTE_CAP}-byte cap; narrow the request`
+        );
+      }
+      return result;
+    }
+  }));
+  return { tools, otlpPath: file.otlpPath };
+}
+async function serveTraceMcp(options) {
+  const { tools, otlpPath } = await traceMcpTools(options);
+  const server = createStdioToolServer({ serverName: "traces", serverVersion: tracesVersion(), tools });
+  try {
+    await server.serve();
+  } finally {
+    await rm(dirname(otlpPath), { recursive: true, force: true });
+  }
+}
+
+// src/cli.ts
+import { explainTraceContract as explainTraceContract2 } from "@tangle-network/agent-eval";
+
+// src/check.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import {
+  compileTraceContractSpec,
+  evaluateTraceContract,
+  explainTraceContract,
+  lintTraceContractSpec
+} from "@tangle-network/agent-eval";
+var CHECK_EXIT = Object.freeze({
+  pass: 0,
+  fail: 1,
+  /** The contract is malformed or contradicts itself, or a rule could not run. */
+  badContract: 2,
+  unreadable: 3,
+  ambiguous: 4
+});
+var AmbiguousTraceInputError = class extends Error {
+  name = "AmbiguousTraceInputError";
+};
+var ContractFileError = class extends Error {
+  name = "ContractFileError";
+};
+async function loadContract(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    throw new ContractFileError(`cannot read contract ${path}: ${errorText(error)}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    throw new ContractFileError(`contract ${path} is not JSON: ${errorText(error)}`);
+  }
+  try {
+    const findings = lintTraceContractSpec(json);
+    const errors = findings.filter((f) => f.level === "error");
+    if (errors.length > 0) {
+      throw new ContractFileError(
+        `contract ${path} contradicts itself:
+${errors.map((f) => `  ${f.path}: ${f.message} [${f.code}]`).join("\n")}`
+      );
+    }
+    return {
+      contract: compileTraceContractSpec(json),
+      warnings: findings.map((f) => `${f.path}: ${f.message} [${f.code}]`)
+    };
+  } catch (error) {
+    if (error instanceof ContractFileError) throw error;
+    throw new ContractFileError(`contract ${path}: ${errorText(error)}`);
+  }
+}
+var SNIFF_ROWS = 20;
+async function sniffCheckInput(path) {
+  const rows = [];
+  for await (const row of readJsonl(path)) {
+    rows.push(row);
+    if (rows.length >= SNIFF_ROWS) break;
+  }
+  const objects = rows.filter(isObject);
+  if (objects.length === 0) throw new Error(`${path} holds no JSON rows`);
+  const kinds = [];
+  if (objects.every((r) => typeof r.trace_id === "string" && typeof r.span_id === "string")) kinds.push("otlp");
+  if (objects.some((r) => (typeof r.sessionId === "string" || typeof r.session_id === "string") && typeof r.type === "string") && !objects.some(hasSpanId)) {
+    kinds.push("claude-code");
+  }
+  if (objects.some((r) => CODEX_LINE_TYPES.has(String(r.type)) && isObject(r.payload))) kinds.push("codex");
+  if (objects.every(isEvidenceRow)) kinds.push("evidence");
+  if (kinds.length === 1) return kinds[0];
+  if (kinds.length === 0) {
+    throw new Error(`${path} is not a trace this command reads (OTLP spans, a Claude Code or Codex session, or trace evidence)`);
+  }
+  throw new AmbiguousTraceInputError(
+    `${path} reads as ${kinds.join(" and ")}; pass --format ${kinds.join(" or --format ")}`
+  );
+}
+var CODEX_LINE_TYPES = /* @__PURE__ */ new Set(["session_meta", "response_item", "event_msg", "turn_context"]);
+function hasSpanId(row) {
+  return typeof row.span_id === "string";
+}
+function isEvidenceRow(row) {
+  if (hasSpanId(row)) return false;
+  if (row.kind === "traces.policy_evidence.session") return true;
+  if (Array.isArray(row.messages) || typeof row.role === "string" && "content" in row) return true;
+  return typeof row.trace_id === "string" && typeof row.name === "string" && isObject(row.attributes);
+}
+function contractSpansFromOtlp(spans) {
+  return spans.map((span) => {
+    const startedAt = epochMs(span.start_time);
+    const endedAt = epochMs(span.end_time);
+    const args = toolArgumentsFromAttributes(span.attributes);
+    const truncated = span.attributes["traces.input.truncated"] === true;
+    return {
+      spanId: span.span_id,
+      parentSpanId: span.parent_span_id,
+      name: span.name,
+      ...startedAt === void 0 ? {} : { startedAt },
+      ...endedAt === void 0 ? {} : { endedAt },
+      ...span.status.code === "ERROR" ? { status: "error" } : span.status.code === "OK" ? { status: "ok" } : {},
+      // A truncated argument capture is not the call's arguments.
+      ...args.argsCaptured && !truncated ? { args: args.args } : { argsCaptured: false },
+      attributes: span.attributes
+    };
+  });
 }
+function epochMs(value) {
+  try {
+    return parseIsoToEpochMs(value);
+  } catch {
+    return void 0;
+  }
+}
+function groupByTrace(spans) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    const list = groups.get(span.trace_id) ?? [];
+    list.push(span);
+    groups.set(span.trace_id, list);
+  }
+  return [...groups].map(([traceId, list]) => ({ traceId, spans: list }));
+}
+async function runCheck(contract, spans, opts) {
+  const traces = [];
+  for (const group of groupByTrace(spans)) {
+    const verdict = evaluateTraceContract(contract, contractSpansFromOtlp(group.spans));
+    const check = { traceId: group.traceId, spanCount: group.spans.length, verdict };
+    if (verdict.status !== "pass") {
+      check.evidenceDir = await writeEvidence(opts.evidenceRoot, contract, group.traceId, group.spans, verdict);
+    }
+    traces.push(check);
+  }
+  const status = traces.some((t) => t.verdict.status === "error") ? "error" : traces.every((t) => t.verdict.status === "pass") ? "pass" : "fail";
+  const exitCode = status === "pass" ? CHECK_EXIT.pass : status === "fail" ? CHECK_EXIT.fail : CHECK_EXIT.badContract;
+  return { contract: contract.name, status, exitCode, traces };
+}
+async function writeEvidence(root, contract, traceId, spans, verdict) {
+  const dir = join(root, `${safeName(contract.name)}-${safeName(traceId).slice(0, 40)}`);
+  await mkdir(dir, { recursive: true });
+  const cited = new Set(verdict.violations.map((v) => v.spanId).filter((id) => id !== void 0));
+  const redacted = redactSpans(spans.filter((s) => cited.has(s.span_id)));
+  await writeFile(join(dir, "verdict.json"), `${JSON.stringify({ traceId, verdict }, null, 2)}
+`);
+  await writeFile(join(dir, "contract.json"), `${JSON.stringify(contract, null, 2)}
+`);
+  await writeFile(join(dir, "explain.txt"), `${explainTraceContract(contract)}
+`);
+  await writeFile(join(dir, "cited-spans.jsonl"), redacted.spans.map((s) => JSON.stringify(s)).join("\n") + (redacted.spans.length ? "\n" : ""));
+  return dir;
+}
+function safeName(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+function ruleLines(verdict) {
+  const branchPassed = /* @__PURE__ */ new Map();
+  for (const e of verdict.ruleExecutions) {
+    if (e.alternative === void 0) continue;
+    branchPassed.set(e.alternative, (branchPassed.get(e.alternative) ?? true) && e.status === "pass");
+  }
+  const anyBranchPassed = [...branchPassed.values()].some(Boolean);
+  return verdict.ruleExecutions.map((e) => {
+    const rule = e.alternative ? `${e.alternative}/${e.rule}` : e.rule;
+    const status = e.alternative && anyBranchPassed && !branchPassed.get(e.alternative) ? "skipped" : e.status;
+    return {
+      rule,
+      status,
+      ...e.error === void 0 ? {} : { error: e.error },
+      details: verdict.violations.filter((x) => x.rule === rule).map((x) => x.detail)
+    };
+  });
+}
+function renderCheckText(report) {
+  const lines = [];
+  for (const t of report.traces) {
+    const v = t.verdict;
+    lines.push(`${v.status.toUpperCase()}  contract ${report.contract}  trace ${t.traceId}  (${t.spanCount} spans, ${v.notes})`);
+    for (const r of ruleLines(v)) {
+      lines.push(`  ${r.status.padEnd(7)} ${r.rule}${r.error ? `  ${r.error}` : ""}`);
+      if (r.status === "fail") for (const detail of r.details.slice(0, 5)) lines.push(`          ${detail}`);
+    }
+    if (t.evidenceDir) lines.push(`  evidence \u2192 ${t.evidenceDir}`);
+  }
+  return lines.join("\n");
+}
+function renderJUnit(report) {
+  const suites = report.traces.map((t) => {
+    const rules = ruleLines(t.verdict);
+    const count = (status) => rules.filter((r) => r.status === status).length;
+    const cases = rules.map((r) => {
+      const open = `    <testcase classname="${xml(report.contract)}" name="${xml(r.rule)}">`;
+      if (r.status === "pass") return `${open}</testcase>`;
+      if (r.status === "skipped") return `${open}
+      <skipped message="another alternative passed"/>
+    </testcase>`;
+      if (r.status === "error") {
+        return `${open}
+      <error message="${xml(r.error ?? "rule could not be evaluated")}"/>
+    </testcase>`;
+      }
+      return `${open}
+      <failure message="${xml(r.details[0] ?? "rule failed")}">${xml(r.details.join("\n"))}</failure>
+    </testcase>`;
+    });
+    return [
+      `  <testsuite name="${xml(`${report.contract} @ ${t.traceId}`)}" tests="${rules.length}" failures="${count("fail")}" errors="${count("error")}" skipped="${count("skipped")}">`,
+      ...cases,
+      "  </testsuite>"
+    ].join("\n");
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="traces check">
+${suites.join("\n")}
+</testsuites>
+`;
+}
+function renderGithubAnnotations(report) {
+  const lines = [];
+  for (const t of report.traces) {
+    for (const r of ruleLines(t.verdict)) {
+      if (r.status === "pass" || r.status === "skipped") continue;
+      const detail = r.status === "error" ? `could not be evaluated: ${r.error ?? "unknown"}` : r.details.join("\n");
+      lines.push(`::error title=${ghProperty(`${report.contract}: ${r.rule}`)}::${ghData(`trace ${t.traceId}: ${detail}`)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function xml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, "");
+}
+function ghData(value) {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function ghProperty(value) {
+  return ghData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/cli.ts
 function parseArgs(argv) {
   const a = {
     command: argv[0] === "--help" || argv[0] === "-h" ? "help" : argv[0] ?? "help",
@@ -123,7 +431,9 @@ function parseArgs(argv) {
     concurrency: 4,
     verifyFindings: false,
     replayCorpora: [],
-    questions: []
+    questions: [],
+    annotations: false,
+    explain: false
   };
   for (let i = 1; i < argv.length; i++) {
     const arg = argv[i];
@@ -280,6 +590,21 @@ function parseArgs(argv) {
       case "--format":
         a.format = next();
         break;
+      case "--contract":
+        a.contract = next();
+        break;
+      case "--junit":
+        a.junit = next();
+        break;
+      case "--evidence":
+        a.evidence = next();
+        break;
+      case "--annotations":
+        a.annotations = true;
+        break;
+      case "--explain":
+        a.explain = true;
+        break;
       case "--help":
       case "-h":
         a.help = true;
@@ -296,22 +621,24 @@ function parseArgs(argv) {
   }
   return a;
 }
-var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set(["analyze", "facts", "investigate", "improve", "ask", "stream", "validate"]);
-function migrateWritingOtlpFlag(args) {
-  if (args.otlp === void 0 || OTLP_INPUT_COMMANDS.has(args.command)) return args;
-  if (args.otlpOut !== void 0) {
+var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set([
+  "analyze",
+  "check",
+  "facts",
+  "investigate",
+  "improve",
+  "ask",
+  "stream",
+  "validate",
+  "mcp"
+]);
+function validateOtlpSelection(args) {
+  if (args.otlp === void 0) return args;
+  if (!OTLP_INPUT_COMMANDS.has(args.command)) {
     throw new Error(
-      `${args.command} was given both --otlp and --otlp-out. --otlp is the deprecated spelling of --otlp-out on writing commands; pass only --otlp-out.`
+      `${args.command} does not read --otlp. --otlp reads OTLP-JSONL on ${[...OTLP_INPUT_COMMANDS].join(", ")}; use --otlp-out <path> to write the artifact.`
     );
   }
-  console.error(
-    `warning: --otlp is deprecated on \`${args.command}\` and will be removed in 0.12. --otlp now READS OTLP-JSONL; use --otlp-out <path> to write the artifact. Treating it as --otlp-out for this run.`
-  );
-  return { ...args, otlpOut: args.otlp, otlp: void 0 };
-}
-function validateOtlpSelection(raw) {
-  const args = migrateWritingOtlpFlag(raw);
-  if (args.otlp === void 0) return args;
   if (args.input) throw new Error("--otlp cannot be combined with an input file");
   if (args.session) throw new Error("--otlp reads a file and cannot be combined with --session");
   if (args.supervisorRunDir) throw new Error("--otlp cannot be combined with --supervisor-run-dir");
@@ -448,7 +775,7 @@ async function resolveSelectedSession(args) {
       `no ${args.all ? "selected" : adapter.harness} session with ID "${args.session}"; run \`traces list\` to select an ID, or pass an explicit session path`
     );
   }
-  throw new Error(
+  throw new AmbiguousTraceInputError(
     `session ID "${args.session}" is ambiguous across ${matches.length} files; select one harness or pass its explicit session path`
   );
 }
@@ -531,7 +858,7 @@ async function collectSpans(args) {
     for (const output of [args.out, args.dir, args.otlpOut]) {
       if (output) await assertOutsideSourceBundle(args.sourceBundle, output);
     }
-    return collectOtlpSpans(join(args.sourceBundle, "derived", "trace.otlp.jsonl"));
+    return collectOtlpSpans(join2(args.sourceBundle, "derived", "trace.otlp.jsonl"));
   }
   if (args.otlp) return collectOtlpSpans(args.otlp);
   if (args.input) {
@@ -583,6 +910,62 @@ async function cmdValidate(args) {
   }
   process.exitCode = validationExitCode(validation);
 }
+var EVIDENCE_FORMATS = /* @__PURE__ */ new Set(["policy-evidence", "sandbox-events", "openinference", "intelligence-spans", "chat-trajectory"]);
+async function checkInputArgs(args) {
+  if (!args.input) return args;
+  if (args.otlp || args.session) throw new Error("name the trace once: a positional path, --otlp, or --session");
+  const info = await stat(args.input);
+  let kind;
+  if (args.format && EVIDENCE_FORMATS.has(args.format)) kind = "evidence";
+  else if (args.format === "otlp" || args.format === "claude-code" || args.format === "codex") kind = args.format;
+  else if (args.format) throw new Error(`unknown --format "${args.format}" (otlp, claude-code, codex, or an evidence format)`);
+  else kind = info.isDirectory() ? "otlp" : await sniffCheckInput(args.input);
+  if (kind === "otlp") return { ...args, otlp: args.input, input: void 0 };
+  if (kind === "evidence") return args;
+  return { ...args, harness: kind, harnessExplicit: true, session: args.input, input: void 0 };
+}
+async function cmdCheck(args) {
+  if (!args.contract) {
+    process.stderr.write("error: check needs --contract <contract.json>\n");
+    process.exitCode = CHECK_EXIT.badContract;
+    return;
+  }
+  let loaded;
+  try {
+    loaded = await loadContract(args.contract);
+  } catch (error) {
+    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = CHECK_EXIT.badContract;
+    return;
+  }
+  for (const warning of loaded.warnings) process.stderr.write(`warning: ${warning}
+`);
+  if (args.explain) {
+    console.log(explainTraceContract2(loaded.contract));
+    return;
+  }
+  let spans;
+  try {
+    spans = (await collectSpans(await checkInputArgs(args))).spans;
+    if (spans.length === 0) throw new Error("the trace holds no spans");
+  } catch (error) {
+    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = error instanceof AmbiguousTraceInputError ? CHECK_EXIT.ambiguous : CHECK_EXIT.unreadable;
+    return;
+  }
+  const report = await runCheck(loaded.contract, spans, { evidenceRoot: args.evidence ?? join2(".traces", "check") });
+  console.log(renderCheckText(report));
+  if (args.junit) await writeFile2(args.junit, renderJUnit(report), "utf8");
+  if (args.out) await writeFile2(args.out, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+  if (args.annotations || process.env.GITHUB_ACTIONS === "true") {
+    const annotations = renderGithubAnnotations(report);
+    if (annotations) console.log(annotations);
+  }
+  process.exitCode = report.exitCode;
+}
 async function cmdConvert(args) {
   const { spans, workflow } = await collectSpans(args);
   if (spans.length === 0) throw new Error("no spans found for the given selection");
@@ -686,6 +1069,73 @@ async function cmdBundle(args) {
     `session bundle (${manifest.view} view) \u2192 ${result.directory}  (${manifest.files.length} file(s), ${manifest.ledgerSlices.length} ledger slice(s), ${manifest.absent.length} recorded absent)`
   );
 }
+async function cmdMcp(args) {
+  if (args.help) {
+    process.stdout.write(`traces mcp \u2014 read-only MCP server over stdio for the selected traces
+
+Usage:
+  traces mcp --otlp <file|dir>                  any OTLP-JSONL
+  traces mcp --harness claude-code --last 5     recent harness sessions (any selection flag)
+
+Register with a client, for example:
+  claude mcp add traces -- traces mcp --otlp ./spans.otlp.jsonl
+
+Every tool is read-only and idempotent and says so in its MCP annotations.
+Spans (including causal links) and results are redacted, the server refuses
+to start if the redacted spans are still UNSAFE or UNKNOWN, each result
+carries an untrusted-text notice, and a result above 512 KiB is refused
+rather than truncated. readSpanSource is not served: windowed reads of
+original source bytes cannot be redacted.
+`);
+    return;
+  }
+  const selected = validateOtlpSelection(validateWorkflowSelection(applyCurrentSessionSelection(args)));
+  const collected = await collectSpans(selected);
+  if (collected.spans.length === 0) throw new Error("mcp: no spans found for the given selection");
+  warnIncompleteWorkflow(collected.workflow);
+  process.stderr.write(`traces mcp: serving ${collected.spans.length} span(s) over stdio
+`);
+  await serveTraceMcp({ spans: collected.spans });
+}
+async function cmdDiff(argv) {
+  const inputs = [];
+  const kinds = [];
+  let format = "text";
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      process.stdout.write(`traces diff \u2014 where two runs of one task first diverge
+
+Usage:
+  traces diff <a> <b> [--kind TOOL]... [--format text|json]
+
+Each side is an OTLP file or directory, any file convert reads, file#<trace id>,
+or file#branch=<id> for one arm (agent.branch.id or agent.branch.arm, and every
+span below it \u2014 refused if the label names more than one subtree). Steps pair
+by span id, then position with the same name and kind, then name and kind
+anywhere. Exit 0 when the runs agree on outcome, 1 when they diverge, 2 when a
+side cannot be read, 3 when the steps line up with no divergence but neither
+side carries a definitive OK/ERROR status or a TOOL step \u2014 there is no
+recorded outcome to call agreement on.
+`);
+      return;
+    }
+    if (arg === "--format") format = argv[++i] ?? "";
+    else if (arg === "--kind") kinds.push(argv[++i] ?? "");
+    else if (arg.startsWith("--")) throw new Error(`diff: unknown flag ${arg}`);
+    else inputs.push(arg);
+  }
+  if (inputs.length !== 2) {
+    throw new Error("diff needs two runs: traces diff <a> <b> (a file, a directory, file#<trace id> or file#branch=<id>)");
+  }
+  if (format !== "json" && format !== "text") throw new Error(`diff: --format must be json or text, got "${format}"`);
+  if (kinds.some((kind) => !kind)) throw new Error("diff: --kind needs a span kind, e.g. --kind TOOL");
+  const report = await diffRuns(inputs[0], inputs[1], { kinds });
+  process.stdout.write(format === "json" ? `${JSON.stringify(report, null, 2)}
+` : renderRunDiff(report));
+  if (report.diff.firstDivergence) process.exitCode = 1;
+  else if (report.caveat) process.exitCode = 3;
+}
 async function cmdBundleVerify(argv) {
   let dir;
   let format = "text";
@@ -754,7 +1204,7 @@ async function cmdFacts(args) {
   const rendered = format === "json" ? `${JSON.stringify(report, null, 2)}
 ` : renderSessionFacts(report);
   if (args.out) {
-    await writeFile(args.out, rendered, "utf8");
+    await writeFile2(args.out, rendered, "utf8");
     console.log(`session facts \u2192 ${args.out}  (${report.sessions.length} session(s), $0, no model call)`);
     return;
   }
@@ -850,7 +1300,7 @@ function parseAttributeValue(raw) {
 async function loadExportAttributes(args) {
   const attributes = {};
   if (args.metadata) {
-    const parsed = JSON.parse(await readFile(args.metadata, "utf8"));
+    const parsed = JSON.parse(await readFile2(args.metadata, "utf8"));
     if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error("--metadata must point to a JSON object");
     }
@@ -1075,8 +1525,8 @@ async function cmdAsk(args) {
   const collected = await collectSpans(args);
   if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
   warnIncompleteWorkflow(collected.workflow);
-  const directory = resolve(args.dir ?? await mkdtemp(join(tmpdir(), "traces-ask-")));
-  await mkdir(directory, { recursive: true });
+  const directory = resolve(args.dir ?? await mkdtemp(join2(tmpdir(), "traces-ask-")));
+  await mkdir2(directory, { recursive: true });
   const controller = new AbortController();
   const interrupt = () => controller.abort(new Error("ask interrupted"));
   process.once("SIGINT", interrupt);
@@ -1090,7 +1540,7 @@ async function cmdAsk(args) {
       concurrency: args.concurrency,
       ...args.budget !== void 0 ? { budgetUsd: args.budget } : {},
       ...args.sourceBundle ? { sourceBundle: { path: args.sourceBundle } } : {},
-      otlpOutPath: args.otlpOut ?? join(directory, "traces.otlp.jsonl"),
+      otlpOutPath: args.otlpOut ?? join2(directory, "traces.otlp.jsonl"),
       signal: controller.signal,
       log: analystLog
     });
@@ -1296,11 +1746,11 @@ async function cmdUpload(args) {
   const redactorParts = args.redactorCmd?.split(/\s+/).filter(Boolean) ?? [];
   const redactor = redactorParts[0] ? commandRedactor({ command: redactorParts[0], args: redactorParts.slice(1) }) : void 0;
   const candidates = plan.items;
-  const byRule = {};
+  const byDetector = {};
   let totalRedactions = 0;
   for (const i of candidates) {
     totalRedactions += i.redaction.redactionCount;
-    for (const [r, n] of Object.entries(i.redaction.byRule)) byRule[r] = (byRule[r] ?? 0) + n;
+    for (const [r, n] of Object.entries(i.redaction.byDetector)) byDetector[r] = (byDetector[r] ?? 0) + n;
   }
   const w = (s) => process.stderr.write(s);
   w(`
@@ -1308,7 +1758,7 @@ Window: since ${new Date(sinceMs).toISOString()}
 `);
   w(`Sessions found: ${plan.items.length}  \xB7  final privacy-mode dedup runs before upload
 `);
-  w(`PII/secrets redacted: ${totalRedactions}${Object.keys(byRule).length ? ` (${Object.entries(byRule).map(([r, n]) => `${r}:${n}`).join(", ")})` : ""}
+  w(`PII/secrets redacted: ${totalRedactions}${Object.keys(byDetector).length ? ` (${Object.entries(byDetector).map(([r, n]) => `${r}:${n}`).join(", ")})` : ""}
 `);
   for (const i of candidates.slice(0, 25)) {
     w(`  + [${i.ref.harness}] ${i.ref.sessionId.slice(0, 8)}  ${i.spans.length} spans  ${i.redaction.redactionCount} redacted  ${i.ref.cwd ?? ""}
@@ -1322,7 +1772,8 @@ Window: since ${new Date(sinceMs).toISOString()}
   }
   if (args.dryRun) {
     const res2 = await executeUpload(plan, { dryRun: true, otlpOut: args.otlpOut, stripContent: args.noContent, redactor });
-    console.log(`dry run: ${candidates.length - res2.skippedSessions} session(s), ${totalRedactions} redaction(s). Redacted OTLP -> ${res2.otlpPath}`);
+    reportRefused(res2.refused);
+    console.log(`dry run: ${candidates.length - res2.skippedSessions - res2.refused.length} session(s), ${totalRedactions} redaction(s). Redacted OTLP -> ${res2.otlpPath}`);
     console.log("No upload performed. Set TANGLE_INGEST_URL / TANGLE_INGEST_API_KEY / TANGLE_TENANT_ID and drop --dry-run to send.");
     return;
   }
@@ -1335,10 +1786,79 @@ Window: since ${new Date(sinceMs).toISOString()}
   }
   const res = await executeUpload(plan, { log: (m) => w(`${m}
 `), stripContent: args.noContent, redactor });
+  reportRefused(res.refused);
   console.log(
-    `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped.`
+    `Uploaded ${res.uploadedSessions} session(s), ${res.acceptedSpans} spans accepted, ${res.redactionCount} redaction(s); ${res.skippedSessions} already-uploaded skipped; ${res.refused.length} refused.`
   );
 }
+function reportRefused(refused) {
+  for (const { harness, sessionId, verdict } of refused) {
+    process.stderr.write(`  REFUSED [${harness}] ${sessionId.slice(0, 8)}: ${verdict.status}
+`);
+    for (const finding of verdict.findings.filter((f) => f.severity === "error")) {
+      process.stderr.write(`    ${finding.category}/${finding.detector} x${finding.count} at ${finding.paths.join(", ")}
+`);
+    }
+    for (const entry of verdict.unreadable) process.stderr.write(`    unread ${entry}
+`);
+  }
+  if (refused.length > 0) {
+    process.stderr.write(`${refused.length} session(s) refused by the share-safety check and kept on this machine.
+`);
+    process.exitCode = 1;
+  }
+}
+async function cmdVerifySafe(argv) {
+  let target;
+  let format = "text";
+  let profile = "share";
+  const knownSecrets = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--format") format = argv[++i] ?? "";
+    else if (arg === "--profile") profile = argv[++i] ?? "";
+    else if (arg === "--known-secret-env") {
+      const name = argv[++i] ?? "";
+      const value = process.env[name];
+      if (!value) throw new Error(`verify-safe: environment variable ${name || "(missing name)"} is not set`);
+      knownSecrets.push(value);
+    } else if (arg === "--help" || arg === "-h") {
+      usageVerifySafe();
+      return;
+    } else if (arg.startsWith("--")) throw new Error(`verify-safe: unknown flag ${arg}`);
+    else if (target === void 0) target = arg;
+    else throw new Error(`verify-safe: unexpected argument ${arg}`);
+  }
+  if (!target) throw new Error("verify-safe needs a file or directory: traces verify-safe <file|dir>");
+  if (format !== "json" && format !== "text") throw new Error(`verify-safe: --format must be json or text, got "${format}"`);
+  if (profile !== "default" && profile !== "share" && profile !== "strict") {
+    throw new Error(`verify-safe: --profile must be default, share or strict, got "${profile}"`);
+  }
+  const result = await verifySafe(target, { profile, knownSecrets });
+  process.stdout.write(format === "json" ? `${JSON.stringify(result, null, 2)}
+` : `${formatVerdict(result)}
+`);
+  process.exitCode = verdictExitCode(result);
+}
+function usageVerifySafe() {
+  console.log(`traces verify-safe <file|dir> [--profile default|share|strict] [--known-secret-env NAME]... [--format text|json]
+
+Check whether files are safe to share, without changing them. A directory is read
+recursively. .json files are parsed whole, .jsonl and .ndjson line by line, and
+any other file is scanned as text.
+
+  SAFE                 nothing found                                   exit 0
+  SAFE_WITH_WARNINGS   only warnings (raw content, identifiers, media) exit 0
+  UNSAFE               a credential, or personal data under share/strict exit 1
+  UNKNOWN              a file, line or byte range could not be read      exit 2
+
+--profile           default | share (default) | strict; see agent-eval docs/redaction.md
+--known-secret-env  name of an environment variable holding a secret to look for in
+                    any encoding (repeatable); the value is never printed
+--format            text (default) | json
+
+Findings name the file, line and JSON Pointer, never the matched value.`);
+}
 function usageExport() {
   console.log(`traces export: convert trace evidence files to OpenInference JSONL
 
@@ -1365,7 +1885,7 @@ Examples:
   halo spans.openinference.jsonl --prompt "Analyze this trace slice" --max-turns 1
 
 Safety:
-  export runs the same local regex redaction used by upload before writing spans.
+  export runs the same local redaction (agent-eval's redaction core) used by upload before writing spans.
   --metadata must be a JSON object; --attr key=value is repeatable and overrides matching metadata keys.`);
 }
 function usageImportCodeTraceBench() {
@@ -1434,6 +1954,14 @@ Two ways in:
 
 Commands:
   validate  Report what a trace can and cannot answer (exit 1 on error findings)
+  check     Gate a run on a trace contract: check <trace> --contract <file.json>
+            [--junit out.xml] [--out report.json] [--evidence dir] [--annotations].
+            check --contract <file.json> --explain prints what the contract checks.
+            <trace> is claude -p stream-json output, OTLP spans (file or dir),
+            a Claude Code or Codex session file, or trace evidence; --format
+            names it when the sniff cannot.
+            Exit 0 pass, 1 fail, 2 bad contract or a rule could not run,
+            3 unreadable trace, 4 ambiguous trace reference
   list      List discovered sessions
   analyze   Run analyst suite + loop/waste pipelines over OTLP (--otlp), sessions,
             or an input file; names every analysis the spans could not support
@@ -1447,7 +1975,8 @@ Commands:
   facts     Print the deterministic session-facts sheet for the selected
             sessions: tool calls excluding synthesized spans, subagent spawns
             with task names, human turns in order, the final message per task,
-            changed paths, first/last record times, and the harness token total.
+            changed paths, first/last record times, the harness token total, and
+            the first failure by agent-eval's fixed precedence (or none).
             No model call, no budget, $0. Every fact names the span ids it came
             from; a fact the spans cannot support is null with its reason.
             --format json (default) or text (exit 1 when a session cannot be read)
@@ -1458,6 +1987,17 @@ Commands:
             ledger sliced to the session window, git log, and a sha256 manifest
             (needs --session <id|path> and --out <new-dir>). This is the FULL
             view: it holds the session's own words, for a reader who cites them
+  mcp       Serve the selected traces to an MCP client over stdio: 7 read-only,
+            idempotent trace tools; spans and results redacted, results capped
+            and marked untrusted (traces mcp --help)
+  diff <a> <b>
+            Pair two runs' steps (by span id, then position with the same name
+            and kind, then name and kind anywhere) and mark the first divergence:
+            changed, replaced, only-in-a, only-in-b or reordered. Each side is an
+            OTLP file or directory, any file convert reads, file#<trace id>, or
+            file#branch=<id> for one arm (agent.branch.id or agent.branch.arm).
+            --kind TOOL (repeatable) keeps only steps of that span kind.
+            Exit 0 agree, 1 diverge, 2 unreadable (--format text|json)
   bundle verify <bundle-dir>
             Check a bundle against its manifest: every listed file present with
             its recorded size and SHA-256, no unlisted or non-regular file beside
@@ -1487,7 +2027,11 @@ Commands:
   stream    Emit JSONL trace stream events for live visualizers or replay
   watch     Online observer: tail active sessions, notify on loops + semantic findings
             (watch <target> tails ONE run tree instead: a run directory or a span file)
-  upload    Redact + upload sessions in a time window to the Tangle Intelligence Platform
+  upload    Redact + upload sessions in a time window to the Tangle Intelligence Platform;
+            a session whose final events are UNSAFE or UNKNOWN is refused (exit 1)
+  verify-safe <file|dir>
+            Say whether files are safe to share: SAFE, SAFE_WITH_WARNINGS, UNSAFE
+            (exit 1) or UNKNOWN (exit 2). Read-only (--help for flags)
 
 Options:
   --harness <id>   Harness or alias (default: claude-code). Known: ${knownHarnesses().join(", ")}
@@ -1513,9 +2057,8 @@ Options:
                    A directory reads the OTLP files under it \u2014 only the otlp/
                    subdirectory when the producer made one \u2014 and names the JSONL
                    that is not OTLP instead of reading it as broken spans.
-                   Supported by: validate, analyze, investigate, improve, ask, stream.
-                   On a WRITING command it is the deprecated spelling of
-                   --otlp-out; it still works, with a warning, until 0.12.
+                   Supported by: validate, analyze, facts, investigate, improve, ask,
+                   stream, mcp. Writing commands take --otlp-out.
   --source-bundle <dir>  Analyze a retained full bundle; explicitly grant source-field reads.
                    Available for analyze, investigate, improve, and ask.
   --otlp-out <path>  WRITE the OTLP-JSONL artifact here (also evidence
@@ -1567,7 +2110,7 @@ Options:
   --min-loop <n>   Min identical repeated calls to flag a loop (default 3)
   --dry-run        upload: redact + dedup + preview, write OTLP, but do NOT send
   --no-content     upload: strip prompt/response text; send metadata only
-  --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the regex pass
+  --redactor <cmd> upload: external PII scrubber (JSON array stdin\u2192stdout) after the redaction core
   --yes, -y        upload: skip the confirmation prompt
   --version, -v    Print the installed traces version
   --help, -h       Show help (use \`traces validate --help\`, \`traces export --help\`,
@@ -1585,7 +2128,7 @@ Upload env: TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KE
 async function main() {
   const rawArgs = process.argv.slice(2);
   if (rawArgs[0] === "--version" || rawArgs[0] === "-v" || rawArgs[0] === "version") {
-    console.log(`traces ${packageVersion()}`);
+    console.log(`traces ${tracesVersion()}`);
     return;
   }
   if (rawArgs[0] === "replay-verify") {
@@ -1600,10 +2143,28 @@ async function main() {
     await cmdVerifyFindings(rawArgs.slice(1));
     return;
   }
+  if (rawArgs[0] === "mcp") {
+    await cmdMcp(parseArgs(rawArgs));
+    return;
+  }
+  if (rawArgs[0] === "diff") {
+    try {
+      await cmdDiff(rawArgs.slice(1));
+    } catch (err) {
+      process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exitCode = 2;
+    }
+    return;
+  }
   if (rawArgs[0] === "bundle" && rawArgs[1] === "verify") {
     await cmdBundleVerify(rawArgs.slice(2));
     return;
   }
+  if (rawArgs[0] === "verify-safe") {
+    await cmdVerifySafe(rawArgs.slice(1));
+    return;
+  }
   const parsedArgs = parseArgs(rawArgs);
   if (parsedArgs.help) {
     if (parsedArgs.command === "import-codetracebench" || parsedArgs.command === "help" && parsedArgs.input === "import-codetracebench") usageImportCodeTraceBench();
@@ -1631,6 +2192,9 @@ async function main() {
     case "validate":
       await cmdValidate(args);
       break;
+    case "check":
+      await cmdCheck(args);
+      break;
     case "investigate":
       await cmdInvestigate(args);
       break;
@@ -1683,5 +2247,5 @@ async function main() {
 main().catch((err) => {
   process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
 `);
-  process.exitCode = 1;
+  process.exitCode = process.argv[2] === "check" ? CHECK_EXIT.badContract : 1;
 });