grix-connector 3.22.0 → 3.24.0

package/scripts/analyze-audit-replays.mjs

@@ -0,0 +1,1416 @@
+#!/usr/bin/env node
+
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_ROOT = join(homedir(), '.grix', 'data', 'audit-replay');
+const DEFAULT_TOP = 10;
+const OUTCOMES = ['completed', 'failed', 'cancelled'];
+const SPAN_STATUSES = ['completed', 'failed', 'cancelled', 'running'];
+
+function asNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+function parseTimestamp(value) {
+  if (typeof value !== 'string') return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+function countBy(items, keyOf) {
+  const counts = new Map();
+  for (const item of items) {
+    const key = keyOf(item);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function sortedCounts(counts) {
+  return [...counts.entries()]
+    .map(([name, count]) => ({ name, count }))
+    .sort((left, right) => right.count - left.count || left.name.localeCompare(right.name));
+}
+
+function sum(values) {
+  return values.reduce((total, value) => total + asNumber(value), 0);
+}
+
+function mean(values) {
+  return values.length === 0 ? null : sum(values) / values.length;
+}
+
+export function percentile(values, ratio) {
+  if (values.length === 0) return null;
+  const ordered = values
+    .filter((value) => typeof value === 'number' && Number.isFinite(value))
+    .sort((left, right) => left - right);
+  if (ordered.length === 0) return null;
+  const index = (ordered.length - 1) * ratio;
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return ordered[lower];
+  const weight = index - lower;
+  return ordered[lower] * (1 - weight) + ordered[upper] * weight;
+}
+
+function distribution(values) {
+  return {
+    mean: mean(values),
+    p50: percentile(values, 0.5),
+    p90: percentile(values, 0.9),
+    max: values.length === 0 ? null : Math.max(...values),
+  };
+}
+
+function safeRatio(numerator, denominator) {
+  return denominator > 0 ? numerator / denominator : null;
+}
+
+function pearson(left, right) {
+  if (left.length !== right.length || left.length < 2) return null;
+  const leftMean = mean(left);
+  const rightMean = mean(right);
+  if (leftMean === null || rightMean === null) return null;
+  let numerator = 0;
+  let leftVariance = 0;
+  let rightVariance = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    const leftDelta = left[index] - leftMean;
+    const rightDelta = right[index] - rightMean;
+    numerator += leftDelta * rightDelta;
+    leftVariance += leftDelta * leftDelta;
+    rightVariance += rightDelta * rightDelta;
+  }
+  const denominator = Math.sqrt(leftVariance * rightVariance);
+  return denominator > 0 ? numerator / denominator : null;
+}
+
+export function canonicalToolName(name) {
+  const normalized = String(name ?? 'unknown')
+    .trim()
+    .replace(/^mcp__/, '')
+    .replaceAll('__', '/')
+    .toLowerCase();
+  const aliases = new Map([
+    ['commandexecution', 'shell'],
+    ['shell', 'shell'],
+    ['bash', 'shell'],
+    ['functions/exec_command', 'shell'],
+    ['filechange', 'file_change'],
+    ['edit', 'file_change'],
+    ['write', 'file_change'],
+    ['functions/apply_patch', 'file_change'],
+    ['read', 'file_read'],
+    ['grep', 'file_search'],
+    ['glob', 'file_search'],
+    ['websearch', 'web_search'],
+    ['fetchurl', 'fetch_url'],
+    ['imageview', 'image_view'],
+    ['todolist', 'planning'],
+    ['updatetodos', 'planning'],
+  ]);
+  return aliases.get(normalized) ?? (normalized || 'unknown');
+}
+
+export function classifyTool(name) {
+  const tool = canonicalToolName(name);
+  if (
+    tool === 'agent'
+    || tool === 'await'
+    || tool === 'taskoutput'
+    || tool.includes('dispatch_agent')
+    || tool.includes('subagent')
+  ) {
+    return 'agent_orchestration';
+  }
+  if (
+    tool.includes('message_send')
+    || tool.includes('session_send')
+    || tool.includes('owner_relay')
+    || tool.includes('group')
+  ) {
+    return 'communication';
+  }
+  if (
+    tool.includes('grix_query')
+    || tool.includes('chat_state')
+    || tool.includes('audit_data')
+    || tool.includes('file_link')
+  ) {
+    return 'platform_query';
+  }
+  if (
+    tool === 'file_search'
+    || tool.includes('codebase-memory')
+    || tool.includes('search_graph')
+    || tool.includes('search_code')
+    || tool.includes('get_code_snippet')
+    || tool.includes('get_architecture')
+  ) {
+    return 'code_search';
+  }
+  if (tool === 'file_read' || tool.endsWith('/read_file')) return 'file_read';
+  if (tool === 'file_change' || tool.includes('apply_patch')) return 'file_change';
+  if (tool === 'shell' || tool.includes('exec_command')) return 'shell';
+  if (
+    tool === 'web_search'
+    || tool === 'fetch_url'
+    || tool.includes('browser')
+    || tool.includes('web_search')
+  ) {
+    return 'web';
+  }
+  if (tool === 'image_view' || tool.includes('imagegen') || tool.includes('image_gen')) {
+    return 'visual';
+  }
+  if (tool === 'planning' || tool.includes('update_plan')) return 'planning';
+  if (tool === 'skill' || tool.includes('skill')) return 'skill';
+  if (tool === 'mcp' || tool === 'getmcptools') return 'generic_mcp';
+  return 'other';
+}
+
+function dominantModel(replay) {
+  const counts = countBy(
+    (replay.spans ?? []).filter(
+      (span) => span?.kind === 'llm_request' && typeof span.modelId === 'string' && span.modelId.trim(),
+    ),
+    (span) => span.modelId.trim(),
+  );
+  const ordered = sortedCounts(counts);
+  return ordered[0]?.name ?? 'unknown';
+}
+
+function durationMs(replay) {
+  const startedAt = parseTimestamp(replay.startedAt);
+  const endedAt = parseTimestamp(replay.endedAt);
+  if (startedAt === null || endedAt === null || endedAt < startedAt) return null;
+  return endedAt - startedAt;
+}
+
+function replayMetrics(replay) {
+  const spans = Array.isArray(replay.spans) ? replay.spans : [];
+  const toolSpans = spans.filter((span) => span?.kind === 'tool_call');
+  const canonicalTools = toolSpans.map((span) => canonicalToolName(span.name));
+  const toolFamilies = toolSpans.map((span) => classifyTool(span.name));
+  const statusCounts = Object.fromEntries(SPAN_STATUSES.map((status) => [status, 0]));
+  for (const span of toolSpans) {
+    const status = SPAN_STATUSES.includes(span.status) ? span.status : 'running';
+    statusCounts[status] += 1;
+  }
+  const input = replay.usage?.input ?? {};
+  const output = replay.usage?.output ?? {};
+  const inputTokens = asNumber(input.total);
+  const outputTokens = asNumber(output.total);
+  const totalTokens = asNumber(replay.usage?.totalProcessed) || inputTokens + outputTokens;
+  const llmRequestCount = spans.filter((span) => span?.kind === 'llm_request').length;
+  const toolCallCount = toolSpans.length;
+
+  return {
+    replay,
+    auditId: String(replay.auditId ?? 'unknown'),
+    inputContentId: replay.input?.reference?.contentId ?? null,
+    provider: String(replay.provider ?? 'unknown'),
+    model: dominantModel(replay),
+    outcome: String(replay.outcome ?? 'unknown'),
+    qualityStatus: String(replay.quality?.status ?? 'unknown'),
+    rawRequestsStatus: replay.quality?.rawRequestsComplete === true
+      ? 'complete'
+      : (replay.quality?.rawRequestsComplete === false ? 'incomplete' : 'unknown'),
+    usageCompleteness: String(replay.usage?.completeness ?? 'unknown'),
+    durationMs: durationMs(replay),
+    spanCount: spans.length,
+    llmRequestCount,
+    toolCallCount,
+    toolStatusCounts: statusCounts,
+    uniqueTools: new Set(canonicalTools),
+    canonicalTools,
+    toolFamilies,
+    subagentCount: spans.filter((span) => span?.kind === 'subagent').length,
+    compactionCount: spans.filter((span) => span?.kind === 'compaction').length,
+    retryCount: spans.filter((span) => span?.kind === 'retry').length,
+    permissionCount: spans.filter((span) => span?.kind === 'permission').length,
+    inputTokens,
+    uncachedInputTokens: asNumber(input.uncached),
+    cacheReadTokens: asNumber(input.cacheRead),
+    cacheWriteTokens: asNumber(input.cacheWrite),
+    outputTokens,
+    reasoningTokens: asNumber(output.reasoning),
+    visibleOutputTokens: asNumber(output.visible),
+    totalTokens,
+    requestCount: asNumber(replay.usage?.requestCount),
+    startedAt: replay.startedAt,
+    finalizedAt: replay.finalizedAt,
+    toolsPerLlmRequest: safeRatio(toolCallCount, llmRequestCount),
+    tokensPerToolCall: safeRatio(totalTokens, toolCallCount),
+  };
+}
+
+function aggregateMetrics(metrics, label) {
+  const outcomes = Object.fromEntries(OUTCOMES.map((outcome) => [outcome, 0]));
+  const tools = [];
+  const toolFamilies = [];
+  const uniqueTools = new Set();
+  for (const item of metrics) {
+    outcomes[item.outcome] = (outcomes[item.outcome] ?? 0) + 1;
+    tools.push(...item.canonicalTools);
+    toolFamilies.push(...item.toolFamilies);
+    for (const tool of item.uniqueTools) uniqueTools.add(tool);
+  }
+  const inputTokens = sum(metrics.map((item) => item.inputTokens));
+  const outputTokens = sum(metrics.map((item) => item.outputTokens));
+  const totalTokens = sum(metrics.map((item) => item.totalTokens));
+  const cacheReadTokens = sum(metrics.map((item) => item.cacheReadTokens));
+  const reasoningTokens = sum(metrics.map((item) => item.reasoningTokens));
+  const toolCalls = sum(metrics.map((item) => item.toolCallCount));
+  const toolFailures = sum(metrics.map((item) => item.toolStatusCounts.failed));
+  const toolCancelled = sum(metrics.map((item) => item.toolStatusCounts.cancelled));
+  const completedTurns = outcomes.completed ?? 0;
+  const tokensByOutcome = Object.fromEntries(
+    [...new Set([...OUTCOMES, ...metrics.map((item) => item.outcome)])]
+      .map((outcome) => [
+        outcome,
+        sum(metrics.filter((item) => item.outcome === outcome).map((item) => item.totalTokens)),
+      ]),
+  );
+  const nonCompletedTokens = totalTokens - asNumber(tokensByOutcome.completed);
+  const durations = metrics
+    .map((item) => item.durationMs)
+    .filter((value) => value !== null);
+
+  return {
+    label,
+    turns: metrics.length,
+    outcomes,
+    successRate: safeRatio(completedTurns, metrics.length),
+    qualityCompleteTurns: metrics.filter((item) => item.qualityStatus === 'complete').length,
+    qualityCompleteRate: safeRatio(
+      metrics.filter((item) => item.qualityStatus === 'complete').length,
+      metrics.length,
+    ),
+    usageCompleteTurns: metrics.filter((item) => item.usageCompleteness === 'complete').length,
+    usageCompleteRate: safeRatio(
+      metrics.filter((item) => item.usageCompleteness === 'complete').length,
+      metrics.length,
+    ),
+    durationMs: distribution(durations),
+    llmRequests: {
+      total: sum(metrics.map((item) => item.llmRequestCount)),
+      ...distribution(metrics.map((item) => item.llmRequestCount)),
+    },
+    toolCalls: {
+      total: toolCalls,
+      ...distribution(metrics.map((item) => item.toolCallCount)),
+      zeroToolTurnRate: safeRatio(
+        metrics.filter((item) => item.toolCallCount === 0).length,
+        metrics.length,
+      ),
+      failed: toolFailures,
+      cancelled: toolCancelled,
+      failureRate: safeRatio(toolFailures, toolCalls),
+    },
+    uniqueToolCount: uniqueTools.size,
+    topTools: sortedCounts(countBy(tools, (tool) => tool)),
+    topToolFamilies: sortedCounts(countBy(toolFamilies, (family) => family)),
+    subagents: {
+      total: sum(metrics.map((item) => item.subagentCount)),
+      turns: metrics.filter((item) => item.subagentCount > 0).length,
+      turnRate: safeRatio(
+        metrics.filter((item) => item.subagentCount > 0).length,
+        metrics.length,
+      ),
+    },
+    compactions: {
+      total: sum(metrics.map((item) => item.compactionCount)),
+      turns: metrics.filter((item) => item.compactionCount > 0).length,
+      turnRate: safeRatio(
+        metrics.filter((item) => item.compactionCount > 0).length,
+        metrics.length,
+      ),
+    },
+    retries: sum(metrics.map((item) => item.retryCount)),
+    permissions: sum(metrics.map((item) => item.permissionCount)),
+    tokens: {
+      input: inputTokens,
+      output: outputTokens,
+      total: totalTokens,
+      reasoning: reasoningTokens,
+      cacheRead: cacheReadTokens,
+      perTurn: distribution(metrics.map((item) => item.totalTokens)),
+      inputPerTurn: distribution(metrics.map((item) => item.inputTokens)),
+      outputPerTurn: distribution(metrics.map((item) => item.outputTokens)),
+      perCompletedTurn: safeRatio(totalTokens, completedTurns),
+      perToolCall: safeRatio(totalTokens, toolCalls),
+      cacheReadRate: safeRatio(cacheReadTokens, inputTokens),
+      reasoningShare: safeRatio(reasoningTokens, outputTokens),
+      byOutcome: tokensByOutcome,
+      nonCompleted: nonCompletedTokens,
+      nonCompletedShare: safeRatio(nonCompletedTokens, totalTokens),
+    },
+    requests: {
+      total: sum(metrics.map((item) => item.requestCount)),
+      ...distribution(metrics.map((item) => item.requestCount)),
+    },
+  };
+}
+
+function groupMetrics(metrics, keyOf) {
+  const groups = new Map();
+  for (const item of metrics) {
+    const key = keyOf(item);
+    const group = groups.get(key) ?? [];
+    group.push(item);
+    groups.set(key, group);
+  }
+  return [...groups.entries()]
+    .map(([label, items]) => aggregateMetrics(items, label))
+    .sort((left, right) => right.turns - left.turns || left.label.localeCompare(right.label));
+}
+
+function rankOutliers(metrics, key, top) {
+  return metrics
+    .filter((item) => typeof item[key] === 'number' && Number.isFinite(item[key]))
+    .sort((left, right) => right[key] - left[key])
+    .slice(0, top)
+    .map((item) => ({
+      auditId: item.auditId,
+      provider: item.provider,
+      model: item.model,
+      outcome: item.outcome,
+      value: item[key],
+    }));
+}
+
+export function selectLatestRevisions(replays) {
+  const latest = new Map();
+  for (const replay of replays) {
+    const auditId = String(replay?.auditId ?? '').trim();
+    if (!auditId) continue;
+    // Session-scoped audits reuse one auditId across turns, so the dedupe key
+    // must include turnId or every turn but one would be collapsed away.
+    const key = `${auditId}/${String(replay.turnId ?? '').trim()}`;
+    const current = latest.get(key);
+    if (
+      !current
+      || asNumber(replay.revision) > asNumber(current.revision)
+      || (
+        asNumber(replay.revision) === asNumber(current.revision)
+        && (parseTimestamp(replay.finalizedAt) ?? 0) > (parseTimestamp(current.finalizedAt) ?? 0)
+      )
+    ) {
+      latest.set(key, replay);
+    }
+  }
+  return [...latest.values()];
+}
+
+export function analyzeReplays(replays, options = {}) {
+  const top = options.top ?? DEFAULT_TOP;
+  const latest = selectLatestRevisions(replays);
+  const metrics = latest.map(replayMetrics);
+  const overall = aggregateMetrics(metrics, 'all');
+  const totalTokens = metrics.map((item) => item.totalTokens);
+  const toolCalls = metrics.map((item) => item.toolCallCount);
+  const llmRequests = metrics.map((item) => item.llmRequestCount);
+  const pairedDurations = metrics.filter((item) => item.durationMs !== null);
+  const rawStatuses = sortedCounts(countBy(metrics, (item) => item.rawRequestsStatus));
+  const orderedTokenCosts = metrics
+    .map((item) => item.totalTokens)
+    .sort((left, right) => right - left);
+  const tokenCostTotal = sum(orderedTokenCosts);
+  const concentration = (count) => safeRatio(
+    sum(orderedTokenCosts.slice(0, count)),
+    tokenCostTotal,
+  );
+  const inputCohorts = new Map();
+  for (const item of metrics) {
+    if (!item.inputContentId) continue;
+    const cohort = inputCohorts.get(item.inputContentId) ?? [];
+    cohort.push(item);
+    inputCohorts.set(item.inputContentId, cohort);
+  }
+  const matchedCohorts = [...inputCohorts.values()].filter(
+    (items) => new Set(items.map((item) => item.provider)).size >= 2,
+  );
+  const matchedMetrics = matchedCohorts.flat();
+
+  return {
+    summary: {
+      sourceReplayCount: replays.length,
+      latestAuditCount: latest.length,
+      sessionCount: new Set(latest.map((replay) => replay.sessionId).filter(Boolean)).size,
+      startedAtMin: [...metrics.map((item) => item.startedAt).filter(Boolean)].sort()[0] ?? null,
+      finalizedAtMax: [...metrics.map((item) => item.finalizedAt).filter(Boolean)].sort().at(-1) ?? null,
+    },
+    dataQuality: {
+      parseErrors: options.parseErrors ?? [],
+      skippedWithoutAuditId: replays.filter(
+        (replay) => !String(replay?.auditId ?? '').trim(),
+      ).length,
+      rawRequestStatuses: rawStatuses,
+      qualityStatuses: sortedCounts(countBy(metrics, (item) => item.qualityStatus)),
+      usageCompleteness: sortedCounts(countBy(metrics, (item) => item.usageCompleteness)),
+    },
+    overall,
+    byProvider: groupMetrics(metrics, (item) => item.provider),
+    byProviderModel: groupMetrics(metrics, (item) => `${item.provider} / ${item.model}`),
+    matchedInputs: {
+      cohortCount: matchedCohorts.length,
+      turnCount: matchedMetrics.length,
+      providerSets: sortedCounts(countBy(
+        matchedCohorts,
+        (items) => [...new Set(items.map((item) => item.provider))].sort().join(' + '),
+      )),
+      byProvider: groupMetrics(matchedMetrics, (item) => item.provider),
+    },
+    correlations: {
+      toolCallsVsTotalTokens: pearson(toolCalls, totalTokens),
+      llmRequestsVsTotalTokens: pearson(llmRequests, totalTokens),
+      toolCallsVsDuration: pearson(
+        pairedDurations.map((item) => item.toolCallCount),
+        pairedDurations.map((item) => item.durationMs),
+      ),
+    },
+    costConcentration: {
+      top1TurnShare: concentration(1),
+      top5TurnsShare: concentration(5),
+      top10TurnsShare: concentration(10),
+    },
+    outliers: {
+      totalTokens: rankOutliers(metrics, 'totalTokens', top),
+      toolCalls: rankOutliers(metrics, 'toolCallCount', top),
+      durationMs: rankOutliers(metrics, 'durationMs', top),
+    },
+  };
+}
+
+async function collectJsonFiles(root) {
+  const files = [];
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) await visit(path);
+      else if (entry.isFile() && entry.name.endsWith('.json')) files.push(path);
+    }
+  }
+  await visit(root);
+  return files.sort();
+}
+
+async function loadReplays(root) {
+  const replayRoot = join(root, 'replays');
+  const files = await collectJsonFiles(replayRoot);
+  const replays = [];
+  const parseErrors = [];
+  for (const path of files) {
+    try {
+      const value = JSON.parse(await readFile(path, 'utf8'));
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        parseErrors.push({ path, error: 'root JSON value is not an object' });
+        continue;
+      }
+      replays.push(value);
+    } catch (error) {
+      parseErrors.push({
+        path,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return { replays, parseErrors, files };
+}
+
+function parseDateBound(value, endOfDay) {
+  if (!value) return null;
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(value);
+  const timestamp = Date.parse(dateOnly
+    ? `${value}T${endOfDay ? '23:59:59.999' : '00:00:00.000'}Z`
+    : value);
+  if (!Number.isFinite(timestamp)) throw new Error(`Invalid date: ${value}`);
+  return timestamp;
+}
+
+function filterReplays(replays, options) {
+  const since = parseDateBound(options.since, false);
+  const until = parseDateBound(options.until, true);
+  return replays.filter((replay) => {
+    if (options.provider && replay.provider !== options.provider) return false;
+    const startedAt = parseTimestamp(replay.startedAt);
+    if (since !== null && (startedAt === null || startedAt < since)) return false;
+    if (until !== null && (startedAt === null || startedAt > until)) return false;
+    return true;
+  });
+}
+
+function fmtInteger(value) {
+  return Math.round(asNumber(value)).toLocaleString('en-US');
+}
+
+function fmtDecimal(value, digits = 1) {
+  return value === null || value === undefined ? '-' : value.toFixed(digits);
+}
+
+function fmtPercent(value) {
+  return value === null || value === undefined ? '-' : `${(value * 100).toFixed(1)}%`;
+}
+
+function fmtDuration(value) {
+  if (value === null || value === undefined) return '-';
+  if (value < 1_000) return `${Math.round(value)}ms`;
+  if (value < 60_000) return `${(value / 1_000).toFixed(1)}s`;
+  return `${(value / 60_000).toFixed(1)}m`;
+}
+
+function escapeCell(value) {
+  return String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+}
+
+function table(headers, rows) {
+  return [
+    `| ${headers.map(escapeCell).join(' | ')} |`,
+    `| ${headers.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+  ].join('\n');
+}
+
+function groupTable(groups) {
+  return table(
+    [
+      'Group',
+      'Turns',
+      'Success',
+      'Quality',
+      'Tools avg/p50/p90',
+      'Tool fail',
+      'Tokens p50/p90',
+      'Cache read',
+      'Duration p50',
+      'Subagent turns',
+    ],
+    groups.map((group) => [
+      group.label,
+      fmtInteger(group.turns),
+      fmtPercent(group.successRate),
+      fmtPercent(group.qualityCompleteRate),
+      [
+        fmtDecimal(group.toolCalls.mean),
+        fmtDecimal(group.toolCalls.p50),
+        fmtDecimal(group.toolCalls.p90),
+      ].join('/'),
+      fmtPercent(group.toolCalls.failureRate),
+      `${fmtInteger(group.tokens.perTurn.p50)}/${fmtInteger(group.tokens.perTurn.p90)}`,
+      fmtPercent(group.tokens.cacheReadRate),
+      fmtDuration(group.durationMs.p50),
+      `${fmtInteger(group.subagents.turns)} (${fmtPercent(group.subagents.turnRate)})`,
+    ]),
+  );
+}
+
+function outlierTable(items, formatter) {
+  return table(
+    ['Audit ID', 'Provider / model', 'Outcome', 'Value'],
+    items.map((item) => [
+      item.auditId,
+      `${item.provider} / ${item.model}`,
+      item.outcome,
+      formatter(item.value),
+    ]),
+  );
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function htmlTable(headers, rows, className = '') {
+  return `<div class="table-wrap"><table class="${escapeHtml(className)}">
+    <thead><tr>${headers.map((header) => `<th>${escapeHtml(header)}</th>`).join('')}</tr></thead>
+    <tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join('')}</tr>`).join('')}</tbody>
+  </table></div>`;
+}
+
+function htmlGroupTable(groups) {
+  return htmlTable(
+    [
+      '分组',
+      '轮次',
+      '完成率',
+      '审计完整率',
+      '工具调用 平均/P50/P90',
+      '工具失败率',
+      'Token P50/P90',
+      '缓存读取率',
+      '耗时 P50',
+      '子 Agent 轮次',
+    ],
+    groups.map((group) => [
+      group.label,
+      fmtInteger(group.turns),
+      fmtPercent(group.successRate),
+      fmtPercent(group.qualityCompleteRate),
+      [
+        fmtDecimal(group.toolCalls.mean),
+        fmtDecimal(group.toolCalls.p50),
+        fmtDecimal(group.toolCalls.p90),
+      ].join(' / '),
+      fmtPercent(group.toolCalls.failureRate),
+      `${fmtInteger(group.tokens.perTurn.p50)} / ${fmtInteger(group.tokens.perTurn.p90)}`,
+      fmtPercent(group.tokens.cacheReadRate),
+      fmtDuration(group.durationMs.p50),
+      `${fmtInteger(group.subagents.turns)} (${fmtPercent(group.subagents.turnRate)})`,
+    ]),
+    'comparison-table',
+  );
+}
+
+function htmlOutlierTable(items, formatter) {
+  return htmlTable(
+    ['审计 ID', 'Provider / 模型', '结果', '数值'],
+    items.map((item) => [
+      item.auditId,
+      `${item.provider} / ${item.model}`,
+      item.outcome,
+      formatter(item.value),
+    ]),
+  );
+}
+
+function metricCard(label, value, note = '') {
+  return `<article class="metric-card">
+    <div class="metric-label">${escapeHtml(label)}</div>
+    <div class="metric-value">${escapeHtml(value)}</div>
+    ${note ? `<div class="metric-note">${escapeHtml(note)}</div>` : ''}
+  </article>`;
+}
+
+function barChart(groups, valueOf, formatter) {
+  const values = groups.map((group) => asNumber(valueOf(group)));
+  const max = Math.max(...values, 0);
+  return `<div class="bars">${groups.map((group, index) => {
+    const value = values[index];
+    const width = max > 0 ? Math.max((value / max) * 100, 1.5) : 0;
+    return `<div class="bar-row">
+      <div class="bar-label">${escapeHtml(group.label)}</div>
+      <div class="bar-track"><div class="bar-fill" style="width:${width.toFixed(2)}%"></div></div>
+      <div class="bar-value">${escapeHtml(formatter(value))}</div>
+    </div>`;
+  }).join('')}</div>`;
+}
+
+function capabilityCards(groups) {
+  return `<div class="capability-grid">${groups.map((group) => `
+    <article class="capability-card">
+      <div class="capability-head">
+        <h3>${escapeHtml(group.label)}</h3>
+        <span>${escapeHtml(fmtInteger(group.uniqueToolCount))} 种工具</span>
+      </div>
+      <p class="eyebrow">主要工具族</p>
+      <div class="tags">${group.topToolFamilies.slice(0, 6).map(
+        (item) => `<span>${escapeHtml(item.name)} <b>${escapeHtml(fmtInteger(item.count))}</b></span>`,
+      ).join('')}</div>
+      <p class="eyebrow">高频工具</p>
+      <ol class="tool-list">${group.topTools.slice(0, 8).map(
+        (item) => `<li><span>${escapeHtml(item.name)}</span><b>${escapeHtml(fmtInteger(item.count))}</b></li>`,
+      ).join('')}</ol>
+    </article>`).join('')}</div>`;
+}
+
+export function renderHtml(report, context) {
+  const overall = report.overall;
+  const filterSummary = Object.entries(context.filters ?? {})
+    .filter(([, value]) => value)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(', ') || '无';
+  const providerSets = report.matchedInputs.providerSets
+    .map((item) => `${item.name}:${item.count}`)
+    .join(', ') || '-';
+  const qualitySummary = report.dataQuality.qualityStatuses
+    .map((item) => `${item.name}:${item.count}`)
+    .join(', ') || '-';
+  const usageSummary = report.dataQuality.usageCompleteness
+    .map((item) => `${item.name}:${item.count}`)
+    .join(', ') || '-';
+  const rawCaptureSummary = report.dataQuality.rawRequestStatuses
+    .map((item) => `${item.name}:${item.count}`)
+    .join(', ') || '-';
+
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light">
+  <title>Grix Agent 审计分析报告</title>
+  <style>
+    :root {
+      --ink: #15263b;
+      --muted: #607086;
+      --line: #dbe4ee;
+      --paper: #ffffff;
+      --wash: #f3f7fb;
+      --navy: #153a5b;
+      --blue: #2176ae;
+      --teal: #1f9d8a;
+      --amber: #d98e04;
+      --red: #c94b50;
+      --shadow: 0 16px 45px rgba(21, 58, 91, .09);
+    }
+    * { box-sizing: border-box; }
+    html { scroll-behavior: smooth; }
+    body {
+      margin: 0;
+      color: var(--ink);
+      background:
+        radial-gradient(circle at 90% 0, rgba(33,118,174,.10), transparent 30rem),
+        var(--wash);
+      font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI",
+        "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;
+      line-height: 1.55;
+    }
+    a { color: inherit; }
+    .hero {
+      color: white;
+      background:
+        linear-gradient(120deg, rgba(21,58,91,.98), rgba(21,78,104,.96)),
+        var(--navy);
+      padding: 64px max(24px, calc((100vw - 1240px) / 2));
+      position: relative;
+      overflow: hidden;
+    }
+    .hero::after {
+      content: "";
+      position: absolute;
+      width: 440px;
+      height: 440px;
+      border: 1px solid rgba(255,255,255,.16);
+      border-radius: 50%;
+      right: -110px;
+      top: -250px;
+      box-shadow: 0 0 0 70px rgba(255,255,255,.035), 0 0 0 140px rgba(255,255,255,.02);
+    }
+    .kicker {
+      margin: 0 0 12px;
+      color: #8de3d2;
+      font-size: 13px;
+      font-weight: 800;
+      letter-spacing: .15em;
+      text-transform: uppercase;
+    }
+    h1 {
+      max-width: 780px;
+      margin: 0;
+      font-size: clamp(36px, 5vw, 66px);
+      line-height: 1.05;
+      letter-spacing: -.04em;
+    }
+    .hero-copy {
+      max-width: 760px;
+      margin: 22px 0 0;
+      color: rgba(255,255,255,.78);
+      font-size: 17px;
+    }
+    .hero-meta {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px 24px;
+      margin-top: 28px;
+      font-size: 13px;
+      color: rgba(255,255,255,.68);
+    }
+    .nav {
+      position: sticky;
+      top: 0;
+      z-index: 20;
+      display: flex;
+      gap: 8px;
+      overflow-x: auto;
+      padding: 12px max(20px, calc((100vw - 1240px) / 2));
+      background: rgba(255,255,255,.92);
+      border-bottom: 1px solid var(--line);
+      backdrop-filter: blur(16px);
+    }
+    .nav a {
+      flex: none;
+      padding: 7px 11px;
+      color: var(--muted);
+      font-size: 13px;
+      font-weight: 700;
+      text-decoration: none;
+      border-radius: 7px;
+    }
+    .nav a:hover { color: var(--navy); background: #e9f1f8; }
+    main {
+      width: min(1240px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 42px 0 72px;
+    }
+    section { margin-top: 52px; scroll-margin-top: 72px; }
+    .section-head {
+      display: flex;
+      align-items: end;
+      justify-content: space-between;
+      gap: 24px;
+      margin-bottom: 18px;
+    }
+    .section-head h2 {
+      margin: 0;
+      font-size: clamp(25px, 3vw, 36px);
+      line-height: 1.1;
+      letter-spacing: -.025em;
+    }
+    .section-head p { max-width: 620px; margin: 0; color: var(--muted); }
+    .metrics {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 14px;
+    }
+    .metric-card, .panel, .capability-card {
+      background: var(--paper);
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      box-shadow: var(--shadow);
+    }
+    .metric-card { padding: 22px; min-height: 142px; }
+    .metric-label {
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 800;
+      letter-spacing: .06em;
+      text-transform: uppercase;
+    }
+    .metric-value {
+      margin-top: 13px;
+      font-size: clamp(27px, 3vw, 39px);
+      font-weight: 850;
+      line-height: 1;
+      letter-spacing: -.035em;
+    }
+    .metric-note { margin-top: 12px; color: var(--muted); font-size: 12px; }
+    .insight {
+      display: grid;
+      grid-template-columns: 4px 1fr;
+      gap: 18px;
+      margin-top: 16px;
+      padding: 20px 22px;
+      background: #eaf5f2;
+      border: 1px solid #c9e8df;
+      border-radius: 12px;
+    }
+    .insight::before { content: ""; background: var(--teal); border-radius: 4px; }
+    .insight strong { display: block; margin-bottom: 4px; }
+    .insight p { margin: 0; color: #41655e; }
+    .split {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 16px;
+      margin-bottom: 16px;
+    }
+    .panel { padding: 22px; overflow: hidden; }
+    .panel h3 { margin: 0 0 18px; font-size: 17px; }
+    .bars { display: grid; gap: 14px; }
+    .bar-row {
+      display: grid;
+      grid-template-columns: minmax(80px, 130px) 1fr 72px;
+      align-items: center;
+      gap: 12px;
+      font-size: 13px;
+    }
+    .bar-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 700; }
+    .bar-track { height: 9px; overflow: hidden; background: #e6edf4; border-radius: 99px; }
+    .bar-fill {
+      height: 100%;
+      background: linear-gradient(90deg, var(--blue), var(--teal));
+      border-radius: inherit;
+    }
+    .bar-value { text-align: right; color: var(--muted); font-variant-numeric: tabular-nums; }
+    .table-wrap {
+      overflow-x: auto;
+      background: var(--paper);
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      box-shadow: var(--shadow);
+    }
+    table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    th, td {
+      padding: 12px 14px;
+      text-align: left;
+      white-space: nowrap;
+      border-bottom: 1px solid #e7edf3;
+      font-variant-numeric: tabular-nums;
+    }
+    th {
+      position: sticky;
+      top: 0;
+      color: #4f6075;
+      background: #f7fafc;
+      font-size: 11px;
+      letter-spacing: .035em;
+      text-transform: uppercase;
+    }
+    tbody tr:last-child td { border-bottom: 0; }
+    tbody tr:hover td { background: #f8fbfd; }
+    .capability-grid {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 16px;
+    }
+    .capability-card { padding: 22px; }
+    .capability-head {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      gap: 12px;
+    }
+    .capability-head h3 { margin: 0; font-size: 24px; text-transform: capitalize; }
+    .capability-head span { color: var(--muted); font-size: 12px; }
+    .eyebrow {
+      margin: 22px 0 8px;
+      color: var(--muted);
+      font-size: 11px;
+      font-weight: 800;
+      letter-spacing: .08em;
+      text-transform: uppercase;
+    }
+    .tags { display: flex; flex-wrap: wrap; gap: 7px; }
+    .tags span {
+      padding: 5px 9px;
+      color: #225f57;
+      background: #e8f6f3;
+      border-radius: 7px;
+      font-size: 12px;
+    }
+    .tags b { margin-left: 5px; }
+    .tool-list { margin: 0; padding-left: 24px; }
+    .tool-list li { padding: 5px 0; color: var(--muted); }
+    .tool-list li span { color: var(--ink); overflow-wrap: anywhere; }
+    .tool-list li b { float: right; color: var(--muted); }
+    .subsection { margin: 28px 0 12px; font-size: 19px; }
+    .quality-list {
+      display: grid;
+      grid-template-columns: repeat(2, 1fr);
+      gap: 10px 22px;
+      margin: 0;
+      padding: 0;
+      list-style: none;
+    }
+    .quality-list li { padding: 11px 0; border-bottom: 1px solid var(--line); }
+    .quality-list b { display: block; font-size: 12px; color: var(--muted); }
+    .guardrails {
+      margin: 0;
+      padding-left: 20px;
+      color: var(--muted);
+    }
+    .guardrails li { margin: 8px 0; }
+    footer {
+      padding: 28px;
+      color: var(--muted);
+      text-align: center;
+      font-size: 12px;
+      border-top: 1px solid var(--line);
+    }
+    @media (max-width: 900px) {
+      .metrics { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+      .split, .capability-grid { grid-template-columns: 1fr; }
+      .section-head { align-items: start; flex-direction: column; }
+    }
+    @media (max-width: 560px) {
+      .hero { padding-top: 48px; padding-bottom: 48px; }
+      .metrics { grid-template-columns: 1fr; }
+      .quality-list { grid-template-columns: 1fr; }
+      .bar-row { grid-template-columns: 86px 1fr 58px; }
+      main { width: min(100% - 20px, 1240px); }
+    }
+    @media print {
+      .nav { display: none; }
+      body { background: white; }
+      .hero { padding: 36px; print-color-adjust: exact; }
+      main { width: 100%; padding: 20px; }
+      section { break-inside: avoid; }
+      .metric-card, .panel, .capability-card, .table-wrap { box-shadow: none; }
+    }
+  </style>
+</head>
+<body>
+  <header class="hero">
+    <p class="kicker">Grix · Audit Intelligence</p>
+    <h1>Agent 审计分析报告</h1>
+    <p class="hero-copy">从能力覆盖、工具行为、成本效率、稳定性和相同输入对照五个视角，对本地审计回放进行元数据分析。</p>
+    <div class="hero-meta">
+      <span>生成时间 ${escapeHtml(context.generatedAt)}</span>
+      <span>数据范围 ${escapeHtml(report.summary.startedAtMin ?? '-')} → ${escapeHtml(report.summary.finalizedAtMax ?? '-')}</span>
+      <span>筛选条件 ${escapeHtml(filterSummary)}</span>
+    </div>
+  </header>
+  <nav class="nav" aria-label="报告导航">
+    <a href="#overview">概览</a>
+    <a href="#providers">Provider</a>
+    <a href="#matched">相同输入</a>
+    <a href="#capabilities">能力覆盖</a>
+    <a href="#cost">成本行为</a>
+    <a href="#outliers">异常轮次</a>
+    <a href="#quality">数据质量</a>
+  </nav>
+  <main>
+    <section id="overview">
+      <div class="section-head">
+        <h2>审计概览</h2>
+        <p>仅使用 replay JSON 元数据和 span 名称；不读取 prompt、response 或 Blob 正文。</p>
+      </div>
+      <div class="metrics">
+        ${metricCard('最新审计轮次', fmtInteger(report.summary.latestAuditCount), `${fmtInteger(report.summary.sessionCount)} 个会话`)}
+        ${metricCard('完成率', fmtPercent(overall.successRate), `${fmtInteger(overall.outcomes.completed)} 完成 · ${fmtInteger(overall.outcomes.failed)} 失败 · ${fmtInteger(overall.outcomes.cancelled)} 取消`)}
+        ${metricCard('工具调用', fmtInteger(overall.toolCalls.total), `P50 ${fmtDecimal(overall.toolCalls.p50)} · P90 ${fmtDecimal(overall.toolCalls.p90)}`)}
+        ${metricCard('总处理 Token', fmtInteger(overall.tokens.total), `缓存读取率 ${fmtPercent(overall.tokens.cacheReadRate)}`)}
+        ${metricCard('耗时 P50', fmtDuration(overall.durationMs.p50), `P90 ${fmtDuration(overall.durationMs.p90)}`)}
+        ${metricCard('完整审计', fmtPercent(overall.qualityCompleteRate), `${fmtInteger(overall.qualityCompleteTurns)} 条完整`)}
+        ${metricCard('子 Agent 调用', fmtInteger(overall.subagents.total), `分布在 ${fmtInteger(overall.subagents.turns)} 轮`)}
+        ${metricCard('失败/取消 Token', fmtPercent(overall.tokens.nonCompletedShare), `${fmtInteger(overall.tokens.nonCompleted)} tokens`)}
+      </div>
+      <div class="insight">
+        <div>
+          <strong>成本首先集中在少数长链路任务。</strong>
+          <p>Token 最高的前 5 轮占 ${escapeHtml(fmtPercent(report.costConcentration.top5TurnsShare))}，前 10 轮占 ${escapeHtml(fmtPercent(report.costConcentration.top10TurnsShare))}。工具调用与 Token 的相关系数为 ${escapeHtml(fmtDecimal(report.correlations.toolCallsVsTotalTokens, 3))}。</p>
+        </div>
+      </div>
+    </section>
+
+    <section id="providers">
+      <div class="section-head">
+        <h2>Provider 与模型对比</h2>
+        <p>展示观测样本，不把不同任务组合下的完成率直接解释为绝对能力排名。</p>
+      </div>
+      <div class="split">
+        <article class="panel">
+          <h3>完成率</h3>
+          ${barChart(report.byProvider, (group) => group.successRate, fmtPercent)}
+        </article>
+        <article class="panel">
+          <h3>单轮 Token P50</h3>
+          ${barChart(report.byProvider, (group) => group.tokens.perTurn.p50, fmtInteger)}
+        </article>
+      </div>
+      ${htmlGroupTable(report.byProvider)}
+      <h3 class="subsection">Provider / 主模型</h3>
+      ${htmlGroupTable(report.byProviderModel)}
+    </section>
+
+    <section id="matched">
+      <div class="section-head">
+        <h2>相同输入对照</h2>
+        <p>使用 input contentId 匹配完全相同的输入，不读取输入内容。它能减少任务组合偏差，但无法消除会话上下文和环境状态差异。</p>
+      </div>
+      <div class="metrics">
+        ${metricCard('跨 Provider 输入组', fmtInteger(report.matchedInputs.cohortCount), `${fmtInteger(report.matchedInputs.turnCount)} 个匹配轮次`)}
+        ${metricCard('Provider 组合', fmtInteger(report.matchedInputs.providerSets.length), providerSets)}
+      </div>
+      <div style="height:16px"></div>
+      ${report.matchedInputs.byProvider.length > 0
+        ? htmlGroupTable(report.matchedInputs.byProvider)
+        : '<div class="panel">没有发现跨 Provider 的相同输入组。</div>'}
+    </section>
+
+    <section id="capabilities">
+      <div class="section-head">
+        <h2>能力覆盖与工具画像</h2>
+        <p>工具别名经过跨 Provider 归一化；工具族是基于名称的保守分类，用于观察行为差异。</p>
+      </div>
+      ${capabilityCards(report.byProvider)}
+    </section>
+
+    <section id="cost">
+      <div class="section-head">
+        <h2>成本、行为与相关性</h2>
+        <p>高相关性不等于因果关系，但可以帮助定位最值得优化的长链路、重复调用和上下文膨胀。</p>
+      </div>
+      <div class="metrics">
+        ${metricCard('输入 Token', fmtInteger(overall.tokens.input))}
+        ${metricCard('输出 Token', fmtInteger(overall.tokens.output), `推理占输出 ${fmtPercent(overall.tokens.reasoningShare)}`)}
+        ${metricCard('每完成轮 Token', fmtInteger(overall.tokens.perCompletedTurn), '包含失败与取消产生的成本')}
+        ${metricCard('每工具调用 Token', fmtInteger(overall.tokens.perToolCall))}
+        ${metricCard('LLM 请求', fmtInteger(overall.llmRequests.total), `每轮平均 ${fmtDecimal(overall.llmRequests.mean)}`)}
+        ${metricCard('压缩次数', fmtInteger(overall.compactions.total), `分布在 ${fmtInteger(overall.compactions.turns)} 轮`)}
+        ${metricCard('Top 1 轮成本占比', fmtPercent(report.costConcentration.top1TurnShare))}
+        ${metricCard('Top 10 轮成本占比', fmtPercent(report.costConcentration.top10TurnsShare))}
+      </div>
+      <h3 class="subsection">变量相关性</h3>
+      ${htmlTable(
+        ['变量组合', 'Pearson r', '解读'],
+        [
+          ['工具调用 vs 总 Token', fmtDecimal(report.correlations.toolCallsVsTotalTokens, 3), '工具链越长，通常上下文与请求成本越高'],
+          ['LLM 请求 vs 总 Token', fmtDecimal(report.correlations.llmRequestsVsTotalTokens, 3), '多轮模型请求是 Token 成本的强信号'],
+          ['工具调用 vs 耗时', fmtDecimal(report.correlations.toolCallsVsDuration, 3), '工具密集型任务通常耗时更长'],
+        ],
+      )}
+    </section>
+
+    <section id="outliers">
+      <div class="section-head">
+        <h2>异常与高成本轮次</h2>
+        <p>用于进一步按 auditId 回放定位；报告不包含对话内容。</p>
+      </div>
+      <h3 class="subsection">Token 最高</h3>
+      ${htmlOutlierTable(report.outliers.totalTokens, fmtInteger)}
+      <h3 class="subsection">工具调用最多</h3>
+      ${htmlOutlierTable(report.outliers.toolCalls, fmtInteger)}
+      <h3 class="subsection">耗时最长</h3>
+      ${htmlOutlierTable(report.outliers.durationMs, fmtDuration)}
+    </section>
+
+    <section id="quality">
+      <div class="section-head">
+        <h2>数据质量与解释边界</h2>
+        <p>任何能力判断都应同时查看样本量、捕获完整性和任务构成。</p>
+      </div>
+      <div class="panel">
+        <ul class="quality-list">
+          <li><b>JSON 解析错误</b>${escapeHtml(fmtInteger(report.dataQuality.parseErrors.length))}</li>
+          <li><b>Usage 完整性</b>${escapeHtml(usageSummary)}</li>
+          <li><b>审计完整性</b>${escapeHtml(qualitySummary)}</li>
+          <li><b>原始请求捕获</b>${escapeHtml(rawCaptureSummary)}</li>
+        </ul>
+      </div>
+      <div class="panel" style="margin-top:16px">
+        <ul class="guardrails">
+          <li>Provider/模型分组是观测队列，任务难度差异可能主导结果。</li>
+          <li>相同输入组仍可能具有不同的会话上下文、代码状态和外部环境。</li>
+          <li>“完成”表示审计 outcome 为 completed，不代表独立验证了答案正确性。</li>
+          <li>工具别名经过归一化，工具族为启发式分类。</li>
+          <li>分析器只读取 replay JSON 元数据，不读取 Blob 内容。</li>
+        </ul>
+      </div>
+    </section>
+  </main>
+  <footer>Grix Agent Audit Analysis · ${escapeHtml(context.generatedAt)}</footer>
+</body>
+</html>
+`;
+}
+
+export function renderMarkdown(report, context) {
+  const overall = report.overall;
+  const top = context.top;
+  const lines = [
+    '# Audit replay analysis',
+    '',
+    `Generated: ${context.generatedAt}`,
+    '',
+    `Root: \`${context.root}\``,
+    '',
+    '## Scope',
+    '',
+    `- Latest audits: ${fmtInteger(report.summary.latestAuditCount)} from ${fmtInteger(report.summary.sessionCount)} sessions`,
+    `- Time range: ${report.summary.startedAtMin ?? '-'} → ${report.summary.finalizedAtMax ?? '-'}`,
+    `- Outcomes: ${fmtInteger(overall.outcomes.completed)} completed, ${fmtInteger(overall.outcomes.failed)} failed, ${fmtInteger(overall.outcomes.cancelled)} cancelled`,
+    `- Complete audit quality: ${fmtInteger(overall.qualityCompleteTurns)} (${fmtPercent(overall.qualityCompleteRate)})`,
+    '',
+    '## Provider comparison',
+    '',
+    groupTable(report.byProvider),
+    '',
+    '## Provider / primary model comparison',
+    '',
+    groupTable(report.byProviderModel),
+    '',
+    '## Matched exact-input cohorts',
+    '',
+    `Found ${fmtInteger(report.matchedInputs.cohortCount)} exact-input cohorts with ${fmtInteger(report.matchedInputs.turnCount)} turns spanning at least two providers.`,
+    '',
+    report.matchedInputs.byProvider.length > 0
+      ? groupTable(report.matchedInputs.byProvider)
+      : 'No cross-provider exact-input cohorts were found.',
+    '',
+    `Provider sets: ${report.matchedInputs.providerSets.map((item) => `${item.name}:${item.count}`).join(', ') || '-'}`,
+    '',
+    '## Capability footprint',
+    '',
+    table(
+      ['Provider', 'Unique tools', 'Top tool families', 'Top canonical tools'],
+      report.byProvider.map((group) => [
+        group.label,
+        fmtInteger(group.uniqueToolCount),
+        group.topToolFamilies.slice(0, 5).map((item) => `${item.name}:${item.count}`).join(', '),
+        group.topTools.slice(0, 8).map((item) => `${item.name}:${item.count}`).join(', '),
+      ]),
+    ),
+    '',
+    '## Overall cost and behavior',
+    '',
+    table(
+      ['Metric', 'Value'],
+      [
+        ['Tool calls', fmtInteger(overall.toolCalls.total)],
+        ['Tool calls per turn (avg / p50 / p90)', `${fmtDecimal(overall.toolCalls.mean)} / ${fmtDecimal(overall.toolCalls.p50)} / ${fmtDecimal(overall.toolCalls.p90)}`],
+        ['LLM requests', fmtInteger(overall.llmRequests.total)],
+        ['Subagent calls / turns', `${fmtInteger(overall.subagents.total)} / ${fmtInteger(overall.subagents.turns)}`],
+        ['Compactions / turns', `${fmtInteger(overall.compactions.total)} / ${fmtInteger(overall.compactions.turns)}`],
+        ['Input / output / total tokens', `${fmtInteger(overall.tokens.input)} / ${fmtInteger(overall.tokens.output)} / ${fmtInteger(overall.tokens.total)}`],
+        ['Tokens per completed turn', fmtInteger(overall.tokens.perCompletedTurn)],
+        ['Tokens per tool call', fmtInteger(overall.tokens.perToolCall)],
+        ['Tokens on failed/cancelled turns', `${fmtInteger(overall.tokens.nonCompleted)} (${fmtPercent(overall.tokens.nonCompletedShare)})`],
+        ['Top 1 / 5 / 10 turns share of tokens', `${fmtPercent(report.costConcentration.top1TurnShare)} / ${fmtPercent(report.costConcentration.top5TurnsShare)} / ${fmtPercent(report.costConcentration.top10TurnsShare)}`],
+        ['Cache read rate', fmtPercent(overall.tokens.cacheReadRate)],
+        ['Reasoning share of output', fmtPercent(overall.tokens.reasoningShare)],
+        ['Duration p50 / p90', `${fmtDuration(overall.durationMs.p50)} / ${fmtDuration(overall.durationMs.p90)}`],
+      ],
+    ),
+    '',
+    '## Relationships',
+    '',
+    table(
+      ['Pair', 'Pearson r'],
+      [
+        ['Tool calls vs total tokens', fmtDecimal(report.correlations.toolCallsVsTotalTokens, 3)],
+        ['LLM requests vs total tokens', fmtDecimal(report.correlations.llmRequestsVsTotalTokens, 3)],
+        ['Tool calls vs duration', fmtDecimal(report.correlations.toolCallsVsDuration, 3)],
+      ],
+    ),
+    '',
+    `## Top ${top} outliers`,
+    '',
+    '### Token usage',
+    '',
+    outlierTable(report.outliers.totalTokens, fmtInteger),
+    '',
+    '### Tool calls',
+    '',
+    outlierTable(report.outliers.toolCalls, fmtInteger),
+    '',
+    '### Duration',
+    '',
+    outlierTable(report.outliers.durationMs, fmtDuration),
+    '',
+    '## Data quality',
+    '',
+    `- Parse errors: ${fmtInteger(report.dataQuality.parseErrors.length)}`,
+    `- Usage completeness: ${report.dataQuality.usageCompleteness.map((item) => `${item.name}:${item.count}`).join(', ') || '-'}`,
+    `- Audit quality: ${report.dataQuality.qualityStatuses.map((item) => `${item.name}:${item.count}`).join(', ') || '-'}`,
+    `- Raw request capture: ${report.dataQuality.rawRequestStatuses.map((item) => `${item.name}:${item.count}`).join(', ') || '-'}`,
+    '',
+    '## Interpretation guardrails',
+    '',
+    '- Provider/model groups are observational cohorts. Different task mixes can dominate the comparison.',
+    '- Exact-input cohorts reduce prompt-mix bias, but session context and environment state can still differ.',
+    '- Success means the recorded turn outcome is `completed`; it does not independently judge answer correctness.',
+    '- Tool aliases are canonicalized for cross-provider comparison, while tool families are heuristic.',
+    '- The script reads replay JSON metadata only. It does not read blob content or include prompt/response text.',
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function help() {
+  return `Usage:
+  node scripts/analyze-audit-replays.mjs [options]
+
+Options:
+  --root <path>       Audit storage root (default: ~/.grix/data/audit-replay)
+  --format <value>    html, markdown, or json (default: markdown)
+  --output <path>     Write the report to a file instead of stdout
+  --provider <name>   Filter by provider
+  --since <date>      Include turns starting on/after an ISO date
+  --until <date>      Include turns starting on/before an ISO date
+  --top <number>      Number of outliers and top items (default: ${DEFAULT_TOP})
+  --help              Show this help
+
+The analyzer reads replay JSON metadata only and never reads audit blob content.
+`;
+}
+
+function parseArgs(argv) {
+  const options = {
+    root: process.env.GRIX_AUDIT_ROOT || DEFAULT_ROOT,
+    format: 'markdown',
+    output: null,
+    provider: null,
+    since: null,
+    until: null,
+    top: DEFAULT_TOP,
+    help: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--help' || argument === '-h') {
+      options.help = true;
+      continue;
+    }
+    if (!argument.startsWith('--')) throw new Error(`Unknown argument: ${argument}`);
+    const key = argument.slice(2);
+    if (!['root', 'format', 'output', 'provider', 'since', 'until', 'top'].includes(key)) {
+      throw new Error(`Unknown option: ${argument}`);
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`Missing value for ${argument}`);
+    index += 1;
+    if (key === 'top') {
+      const top = Number.parseInt(value, 10);
+      if (!Number.isInteger(top) || top < 1 || top > 100) {
+        throw new Error('--top must be an integer from 1 to 100');
+      }
+      options.top = top;
+    } else {
+      options[key] = value;
+    }
+  }
+  if (!['html', 'markdown', 'json'].includes(options.format)) {
+    throw new Error('--format must be html, markdown, or json');
+  }
+  options.root = resolve(options.root);
+  if (options.output) options.output = resolve(options.output);
+  return options;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    process.stdout.write(help());
+    return;
+  }
+  const { replays, parseErrors, files } = await loadReplays(options.root);
+  const filtered = filterReplays(replays, options);
+  const generatedAt = new Date().toISOString();
+  const report = analyzeReplays(filtered, {
+    top: options.top,
+    parseErrors,
+  });
+  const context = {
+    generatedAt,
+    root: options.root,
+    top: options.top,
+    sourceFiles: files.length,
+    filters: {
+      provider: options.provider,
+      since: options.since,
+      until: options.until,
+    },
+  };
+  const output = options.format === 'json'
+    ? `${JSON.stringify({ generatedAt, root: options.root, filters: context.filters, ...report }, null, 2)}\n`
+    : options.format === 'html'
+      ? renderHtml(report, context)
+      : renderMarkdown(report, context);
+  if (options.output) {
+    await writeFile(options.output, output, 'utf8');
+    process.stdout.write(`Wrote ${options.format} report to ${options.output}\n`);
+  } else {
+    process.stdout.write(output);
+  }
+}
+
+const isMain = process.argv[1]
+  && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+
+if (isMain) {
+  main().catch((error) => {
+    process.stderr.write(`audit analysis failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}