mixdog 0.7.1

package/scripts/io-telemetry-report.mjs

@@ -0,0 +1,691 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+process.env.CLAUDE_PLUGIN_ROOT ||= ROOT;
+const { getPluginData } = await import('../src/agent/orchestrator/config.mjs');
+const { countJsonNextCalls } = await import('../src/agent/orchestrator/tools/next-call-utils.mjs');
+
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((arg) => !arg.includes('=')));
+const kv = Object.fromEntries(argv.filter((arg) => arg.includes('=')).map((arg) => arg.replace(/^--/, '').split('=')));
+
+const JSON_OUT = flags.has('--json');
+const CHECK = flags.has('--check');
+const REQUIRE_ROWS = flags.has('--require-rows') || /^(1|true|yes|on)$/i.test(String(process.env.MIXDOG_IO_TELEMETRY_REQUIRE_ROWS || ''));
+const HOURS = Math.max(1, Number.parseInt(kv.hours || '24', 10) || 24);
+const LIMIT = Math.max(1, Number.parseInt(kv.limit || '10', 10) || 10);
+const SINCE_MS = Date.now() - HOURS * 3600_000;
+const TRACE_PATH = kv.trace || join(getPluginData(), 'history', 'bridge-trace.jsonl');
+const TRACE_EXPLICIT = Object.prototype.hasOwnProperty.call(kv, 'trace');
+const TOOL_EVENTS_PATH = kv.events || join(getPluginData(), 'tool-events.log');
+const MCP_DEBUG_PATH = kv.mcpDebug || kv['mcp-debug'] || join(getPluginData(), 'mcp-debug.log');
+
+const IO_TOOLS = new Set(['read', 'grep', 'glob', 'list', 'tree', 'find_files', 'apply_patch', 'edit', 'write', 'bash', 'job_wait']);
+const DEFAULT_THRESHOLDS = {
+  read: { p90: 250, errorRate: 0.10, wideReadRate: 0.30 },
+  grep: { p90: 500, errorRate: 0.10 },
+  glob: { p90: 500, errorRate: 0.10 },
+  edit: { p90: 500, errorRate: 0.15 },
+  apply_patch: { p90: 2000, errorRate: 0.15 },
+  write: { p90: 400, errorRate: 0.10 },
+};
+
+function loadThresholds() {
+  const raw = process.env.MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON;
+  if (!raw) return DEFAULT_THRESHOLDS;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return DEFAULT_THRESHOLDS;
+    return { ...DEFAULT_THRESHOLDS, ...parsed };
+  } catch (err) {
+    throw new Error(`invalid MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON: ${err?.message || String(err)}`);
+  }
+}
+
+function rowTime(row) {
+  const raw = row?.ts ?? row?.timestamp;
+  if (typeof raw === 'number') return raw;
+  const parsed = Date.parse(raw || 0);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function loadTraceRows(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    })
+    .filter((row) => row && rowTime(row) >= SINCE_MS);
+}
+
+function parseToolEventPath(message) {
+  const text = String(message || '');
+  const inMatch = text.match(/\bin ([A-Za-z]:\\.*?)(?: \(|$)/);
+  if (inMatch?.[1]) return inMatch[1].trim();
+  const colonMatch = text.match(/: ([A-Za-z]:\\.*)$/);
+  if (colonMatch?.[1]) return colonMatch[1].trim();
+  return '';
+}
+
+function parseNearestLine(message) {
+  const match = String(message || '').match(/Nearest match at line (\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function loadToolEventRows(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      const match = line.match(/^\[(?<ts>[^\]]+)\] \[tool=(?<tool>[^\]]+)\] \[code=(?<code>[^\]]+)\] (?<message>.*)$/);
+      if (!match?.groups) return null;
+      const ts = match.groups.ts;
+      if (rowTime({ ts }) < SINCE_MS) return null;
+      const message = match.groups.message || '';
+      const eventPath = parseToolEventPath(message);
+      const nearestLine = parseNearestLine(message);
+      const nextCallCount = countJsonNextCalls(message);
+      return {
+        ts,
+        kind: 'tool',
+        event_source: 'tool-events',
+        tool_name: match.groups.tool,
+        tool_kind: ['edit', 'write', 'apply_patch'].includes(match.groups.tool) ? 'mutation' : 'builtin',
+        tool_ms: 0,
+        tool_args: eventPath ? { path: eventPath } : {},
+        result_kind: 'error',
+        result_has_next_call: nextCallCount > 0,
+        result_next_call_count: nextCallCount,
+        result_bytes_est: Buffer.byteLength(message, 'utf8'),
+        result_lines_est: message ? message.split('\n').length : 0,
+        event_code: match.groups.code,
+        event_path: eventPath || null,
+        event_nearest_line: nearestLine,
+        event_message: message,
+      };
+    })
+    .filter(Boolean);
+}
+
+function parseMcpDebugStartRest(rest) {
+  const text = String(rest || '');
+  const out = {};
+  const mode = text.match(/\bmode=([^\s]+)/);
+  if (mode?.[1]) out.mode = mode[1];
+  const itemCount = text.match(/\bitemCount=(\d+)/);
+  if (itemCount?.[1]) out.itemCount = Number(itemCount[1]);
+  const inputHash = text.match(/\binputHash=([a-f0-9]+)/i);
+  if (inputHash?.[1]) out.inputHash = inputHash[1];
+  const cmdPreview = text.match(/\bcmdPreview="([^"]*)"/);
+  if (cmdPreview?.[1]) out.command_preview = cmdPreview[1];
+  return out;
+}
+
+function loadMcpDebugRows(path) {
+  if (!existsSync(path)) return [];
+  const starts = new Map();
+  const rows = [];
+  for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
+    if (!line) continue;
+    let match = line.match(/^\[(?<ts>[^\]]+)\].*?\[dispatch\] start id=(?<id>\S+) tool=(?<tool>\S+)(?<rest>.*)$/);
+    if (match?.groups) {
+      const ts = match.groups.ts;
+      if (rowTime({ ts }) >= SINCE_MS) {
+        starts.set(match.groups.id, {
+          ts,
+          id: match.groups.id,
+          tool: match.groups.tool,
+          rest: match.groups.rest || '',
+        });
+      }
+      continue;
+    }
+    match = line.match(/^\[(?<ts>[^\]]+)\].*?\[dispatch\] ok id=(?<id>\S+) tool=(?<tool>\S+) elapsed=(?<elapsed>\d+)ms/);
+    if (!match?.groups) continue;
+    const ts = match.groups.ts;
+    if (rowTime({ ts }) < SINCE_MS) continue;
+    const start = starts.get(match.groups.id);
+    const tool = match.groups.tool || start?.tool || 'unknown';
+    rows.push({
+      ts,
+      kind: 'tool',
+      event_source: 'mcp-debug',
+      tool_name: tool,
+      tool_kind: ['edit', 'write', 'apply_patch'].includes(tool) ? 'mutation' : 'builtin',
+      tool_ms: Number(match.groups.elapsed) || 0,
+      tool_args: start ? parseMcpDebugStartRest(start.rest) : {},
+      result_kind: 'normal',
+      result_has_next_call: false,
+      result_next_call_count: 0,
+      dispatch_id: match.groups.id,
+      dispatch_session_id: String(match.groups.id).split('-')[0] || null,
+      dispatch_started_at: start?.ts || null,
+    });
+  }
+  return rows;
+}
+
+function percentile(values, p) {
+  if (!values.length) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * p));
+  return sorted[idx];
+}
+
+function round(value) {
+  return Number((Number(value) || 0).toFixed(2));
+}
+
+function summarizeSamples(samples) {
+  return {
+    count: samples.length,
+    p50: round(percentile(samples, 0.50)),
+    p90: round(percentile(samples, 0.90)),
+    max: round(samples.length ? Math.max(...samples) : 0),
+    total: round(samples.reduce((sum, value) => sum + value, 0)),
+  };
+}
+
+function groupToolRows(rows) {
+  const byTool = new Map();
+  for (const row of rows) {
+    if (row.kind !== 'tool') continue;
+    const tool = row.tool_name || row.toolName || 'unknown';
+    if (!IO_TOOLS.has(tool)) continue;
+    const ms = Number(row.tool_ms ?? row.toolMs);
+    if (!Number.isFinite(ms)) continue;
+    if (!byTool.has(tool)) byTool.set(tool, { samples: [], resultKinds: new Map(), wideReads: 0, broadGrepCalls: 0, largeEditCalls: 0, nextCalls: 0, nextCallTotal: 0, nextCallMisses: new Map(), outputBytes: [], outputLines: [] });
+    const bucket = byTool.get(tool);
+    bucket.samples.push(ms);
+    const kind = row.result_kind || 'normal';
+    bucket.resultKinds.set(kind, (bucket.resultKinds.get(kind) || 0) + 1);
+    const hasNextCall = row.result_has_next_call === true || row.resultHasNextCall === true;
+    const args = row.tool_args || row.toolArgs || {};
+    const resultBytes = Number(row.result_bytes_est ?? row.resultBytesEst ?? row.result_bytes ?? row.resultBytes);
+    const resultLines = Number(row.result_lines_est ?? row.resultLinesEst ?? row.result_lines ?? row.resultLines);
+    if (Number.isFinite(resultBytes)) bucket.outputBytes.push(resultBytes);
+    if (Number.isFinite(resultLines)) bucket.outputLines.push(resultLines);
+    if (hasNextCall) {
+      bucket.nextCalls += 1;
+      bucket.nextCallTotal += Math.max(1, Number(row.result_next_call_count ?? row.resultNextCallCount) || 1);
+    } else {
+      const shape = nextCallShape(tool, args);
+      bucket.nextCallMisses.set(shape, (bucket.nextCallMisses.get(shape) || 0) + 1);
+    }
+    if (tool === 'read') {
+      const explicitWide = row.wide_read === true || row.wideRead === true;
+      const hasRange = args.offset !== undefined || args.limit !== undefined || args.line !== undefined || args.context !== undefined;
+      const mode = args.mode === undefined ? undefined : String(args.mode).toLowerCase();
+      const compact = args.budget === 'compact';
+      const explicitFull = args.full === true || mode === 'full';
+      const defaultFull = mode === undefined && args.full !== false;
+      const likelyWide = !hasRange && !compact && (explicitFull || (defaultFull && Number.isFinite(resultBytes) && resultBytes >= 8192));
+      if (explicitWide || likelyWide) bucket.wideReads += 1;
+    }
+    if (tool === 'grep') {
+      if (row.broad_grep_call === true || row.broadGrepCall === true) bucket.broadGrepCalls += 1;
+    }
+    if (tool === 'edit' && (row.large_edit_call === true || row.largeEditCall === true)) {
+      bucket.largeEditCalls += 1;
+    }
+  }
+  return [...byTool.entries()]
+    .map(([tool, value]) => ({
+      tool,
+      ...summarizeSamples(value.samples),
+      resultKinds: Object.fromEntries(value.resultKinds),
+      errors: value.resultKinds.get('error') || 0,
+      wideReads: value.wideReads || 0,
+      broadGrepCalls: value.broadGrepCalls || 0,
+      largeEditCalls: value.largeEditCalls || 0,
+      nextCalls: value.nextCalls || 0,
+      nextCallTotal: value.nextCallTotal || 0,
+      nextCallRate: value.samples.length > 0 ? round((value.nextCalls || 0) / value.samples.length) : 0,
+      nextCallMisses: Object.fromEntries([...value.nextCallMisses.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 5)),
+      outputBytes: summarizeSamples(value.outputBytes),
+      outputLines: summarizeSamples(value.outputLines),
+    }))
+    .sort((a, b) => b.p90 - a.p90 || b.count - a.count);
+}
+
+function nextCallShape(tool, args = {}) {
+  if (tool === 'grep') return `grep:${args.output_mode || args.mode || 'files_with_matches'}`;
+  if (tool === 'glob') return `glob:${args.pattern || args.glob || args.file_pattern ? 'pattern' : 'missing-pattern'}`;
+  if (tool === 'read') {
+    if (args.mode) return `read:${args.mode}`;
+    if (args.line !== undefined) return 'read:line';
+    if (args.offset !== undefined || args.limit !== undefined) return 'read:range';
+    return 'read:full';
+  }
+  if (tool === 'apply_patch') return args.dry_run === true ? 'apply_patch:dry_run' : 'apply_patch:apply';
+  if (tool === 'edit') return Array.isArray(args.edits) ? 'edit:batch' : 'edit:single';
+  return `${tool}:default`;
+}
+
+function evaluateTools(tools, thresholds, options = {}) {
+  const failures = [];
+  const recommendations = [];
+  const skipGenericErrorRate = options.skipGenericErrorRate === true;
+  for (const item of tools) {
+    const threshold = thresholds[item.tool] || {};
+    const errorRate = item.count > 0 ? item.errors / item.count : 0;
+    const wideReadRate = item.count > 0 ? item.wideReads / item.count : 0;
+    if (Number.isFinite(Number(threshold.p90)) && item.p90 > Number(threshold.p90)) {
+      failures.push({ tool: item.tool, reason: 'slow-p90', p90: item.p90, threshold: Number(threshold.p90) });
+      recommendations.push(`${item.tool}: p90 ${item.p90}ms exceeds ${threshold.p90}ms; inspect cache hit rate and prefer batched/ranged calls.`);
+    }
+    if (!skipGenericErrorRate && Number.isFinite(Number(threshold.errorRate)) && errorRate > Number(threshold.errorRate)) {
+      failures.push({ tool: item.tool, reason: 'error-rate', errorRate: round(errorRate), threshold: Number(threshold.errorRate) });
+      recommendations.push(`${item.tool}: error rate ${round(errorRate * 100)}%; improve call-shape hints or add a focused smoke for the dominant error.`);
+    }
+    if (item.tool === 'read' && Number.isFinite(Number(threshold.wideReadRate)) && wideReadRate > Number(threshold.wideReadRate)) {
+      failures.push({ tool: item.tool, reason: 'wide-read-rate', wideReadRate: round(wideReadRate), threshold: Number(threshold.wideReadRate) });
+      recommendations.push(`read: wide-read rate ${round(wideReadRate * 100)}%; prefer grep/find_symbol or read({file_path, offset, limit}).`);
+    }
+    if (item.tool === 'grep' && item.broadGrepCalls > 0) {
+      recommendations.push(`grep: ${item.broadGrepCalls} broad root search call(s); prefer glob/list -> narrowed grep -> batched read when the target root is not pinned.`);
+    }
+    if (item.tool === 'edit' && item.largeEditCalls > 0) {
+      recommendations.push(`edit: ${item.largeEditCalls} large old_string call(s); use direct apply_patch for chunks >=30 lines or structural edits.`);
+    }
+    if (Number.isFinite(Number(threshold.nextCallRateMin)) && item.nextCallRate < Number(threshold.nextCallRateMin)) {
+      failures.push({ tool: item.tool, reason: 'next-call-rate', nextCallRate: item.nextCallRate, threshold: Number(threshold.nextCallRateMin) });
+      const missing = Object.entries(item.nextCallMisses || {})
+        .slice(0, 3)
+        .map(([shape, count]) => `${shape}:${count}`)
+        .join(', ');
+      recommendations.push(`${item.tool}: next_call coverage ${round(item.nextCallRate * 100)}%; add or preserve direct retry/follow-up guidance for result-bearing paths${missing ? ` (top missing: ${missing})` : ''}.`);
+    }
+    if (Number.isFinite(Number(threshold.outputBytesP90)) && item.outputBytes?.p90 > Number(threshold.outputBytesP90)) {
+      failures.push({ tool: item.tool, reason: 'output-bytes-p90', outputBytesP90: item.outputBytes.p90, threshold: Number(threshold.outputBytesP90) });
+      recommendations.push(`${item.tool}: output p90 ${item.outputBytes.p90} bytes exceeds ${threshold.outputBytesP90}; prefer bounded read ranges or tighter result limits.`);
+    }
+  }
+  return { failures, recommendations: Array.from(new Set(recommendations)) };
+}
+
+function summarizeLoop(rows) {
+  const send = [];
+  const bodyBytes = [];
+  for (const row of rows) {
+    if (row.kind !== 'loop') continue;
+    const ms = Number(row.send_ms ?? row.sendMs);
+    const bytes = Number(row.body_bytes_est ?? row.bodyBytesEst);
+    if (Number.isFinite(ms)) send.push(ms);
+    if (Number.isFinite(bytes)) bodyBytes.push(bytes);
+  }
+  return {
+    sends: summarizeSamples(send),
+    bodyBytes: summarizeSamples(bodyBytes),
+  };
+}
+
+function summarizeTrim(rows) {
+  let count = 0;
+  let bytesBefore = 0;
+  let bytesAfter = 0;
+  let changed = 0;
+  for (const row of rows) {
+    if (row.kind !== 'trim_meta') continue;
+    count += 1;
+    if (row.trim_changed) changed += 1;
+    const before = Number(row.before_bytes);
+    const after = Number(row.after_bytes);
+    if (Number.isFinite(before)) bytesBefore += before;
+    if (Number.isFinite(after)) bytesAfter += after;
+  }
+  return { count, changed, bytesBefore, bytesAfter, bytesSaved: Math.max(0, bytesBefore - bytesAfter) };
+}
+
+function summarizeCompression(rows) {
+  let count = 0;
+  let before = 0;
+  let after = 0;
+  for (const row of rows) {
+    if (row.kind !== 'compress') continue;
+    const payload = row.payload || {};
+    const b = Number(payload.bytes_before);
+    const a = Number(payload.bytes_after);
+    if (!Number.isFinite(b) || !Number.isFinite(a)) continue;
+    count += 1;
+    before += b;
+    after += a;
+  }
+  return { count, bytesBefore: before, bytesAfter: after, bytesSaved: Math.max(0, before - after) };
+}
+
+function summarizeRoutes(rows) {
+  const byScenario = new Map();
+  for (const row of rows) {
+    if (row.kind !== 'route') continue;
+    const scenario = row.route_scenario || row.routeScenario || 'unknown';
+    const route = row.route_name || row.routeName || 'unknown';
+    const score = Number(row.route_score ?? row.routeScore);
+    const item = {
+      route,
+      success: row.route_success === true || row.routeSuccess === true,
+      wallMs: round(Number(row.route_wall_ms ?? row.routeWallMs)),
+      toolCalls: Number(row.route_tool_calls ?? row.routeToolCalls) || 0,
+      outputBytes: Number(row.route_output_bytes ?? row.routeOutputBytes) || 0,
+      nextCalls: Number(row.route_next_calls ?? row.routeNextCalls) || 0,
+      wideReads: Number(row.route_wide_reads ?? row.routeWideReads) || 0,
+      broadGrepCalls: Number(row.route_broad_grep_calls ?? row.routeBroadGrepCalls) || 0,
+      largeEditCalls: Number(row.route_large_edit_calls ?? row.routeLargeEditCalls) || 0,
+      errors: Number(row.route_errors ?? row.routeErrors) || 0,
+      score: Number.isFinite(score) ? score : null,
+    };
+    if (!byScenario.has(scenario)) byScenario.set(scenario, []);
+    byScenario.get(scenario).push(item);
+  }
+  return [...byScenario.entries()]
+    .map(([scenario, routes]) => {
+      const ranked = [...routes].sort((a, b) => {
+        if (a.success !== b.success) return a.success ? -1 : 1;
+        const aScore = Number.isFinite(a.score) ? a.score : Number.POSITIVE_INFINITY;
+        const bScore = Number.isFinite(b.score) ? b.score : Number.POSITIVE_INFINITY;
+        return aScore - bScore || a.toolCalls - b.toolCalls || a.outputBytes - b.outputBytes;
+      });
+      const winner = ranked.find((route) => route.success) || null;
+      return {
+        scenario,
+        winner: winner?.route || null,
+        count: routes.length,
+        failures: routes.filter((route) => !route.success).length,
+        routes: ranked,
+      };
+    })
+    .sort((a, b) => a.scenario.localeCompare(b.scenario));
+}
+
+function evaluateRoutes(routes) {
+  const failures = [];
+  const recommendations = [];
+  for (const scenario of routes) {
+    const winner = scenario.routes.find((route) => route.route === scenario.winner) || null;
+    if (!winner) {
+      failures.push({ scenario: scenario.scenario, reason: 'no-successful-route' });
+      recommendations.push(`${scenario.scenario}: no successful route; inspect fixture, route policy, or tool failure output.`);
+      continue;
+    }
+    if (winner.wideReads > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'route-winner-wide-read' });
+      recommendations.push(`${scenario.scenario}: winning route ${winner.route} used a wide read; prefer grep, read({file_path, offset, limit}), or apply_patch.`);
+    }
+    if (winner.broadGrepCalls > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'route-winner-broad-grep' });
+      recommendations.push(`${scenario.scenario}: winning route ${winner.route} used broad grep; prefer glob/list before repo-root grep.`);
+    }
+    if (winner.largeEditCalls > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'route-winner-large-edit' });
+      recommendations.push(`${scenario.scenario}: winning route ${winner.route} used large edit; prefer direct apply_patch for large chunks.`);
+    }
+    if (winner.errors > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'route-winner-errors' });
+      recommendations.push(`${scenario.scenario}: winning route ${winner.route} had tool errors; route scoring or fallback handling needs attention.`);
+    }
+  }
+  return { failures, recommendations };
+}
+
+function summarizeEventClusters(rows) {
+  const eventRows = rows.filter((row) => row.event_source === 'tool-events' && row.kind === 'tool');
+  const byKey = new Map();
+  for (const row of eventRows) {
+    const key = `${row.tool_name || 'unknown'}|${row.event_code || ''}|${row.event_path || '(none)'}`;
+    let bucket = byKey.get(key);
+    if (!bucket) {
+      bucket = {
+        tool: row.tool_name || 'unknown',
+        code: row.event_code || '',
+        path: row.event_path || null,
+        count: 0,
+        firstAt: row.ts,
+        lastAt: row.ts,
+        nearestLines: new Map(),
+        sample: row.event_message || '',
+      };
+      byKey.set(key, bucket);
+    }
+    bucket.count += 1;
+    bucket.lastAt = row.ts;
+    if (row.event_nearest_line) {
+      const line = String(row.event_nearest_line);
+      bucket.nearestLines.set(line, (bucket.nearestLines.get(line) || 0) + 1);
+    }
+  }
+  return [...byKey.values()]
+    .map((bucket) => ({
+      ...bucket,
+      nearestLines: Object.fromEntries([...bucket.nearestLines.entries()].sort((a, b) => b[1] - a[1] || Number(a[0]) - Number(b[0]))),
+      sample: String(bucket.sample || '').slice(0, 220),
+    }))
+    .sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool))
+    .slice(0, LIMIT);
+}
+
+function summarizeRepeatClusters(rows) {
+  const debugRows = rows
+    .filter((row) => row.event_source === 'mcp-debug' && row.kind === 'tool' && row.dispatch_session_id)
+    .sort((a, b) => rowTime(a) - rowTime(b));
+  const bySession = new Map();
+  for (const row of debugRows) {
+    const sid = row.dispatch_session_id;
+    if (!bySession.has(sid)) bySession.set(sid, []);
+    bySession.get(sid).push(row);
+  }
+  const clusters = [];
+  const maxGapMs = 15_000;
+  for (const [session, sessionRows] of bySession.entries()) {
+    for (let i = 0; i < sessionRows.length;) {
+      let j = i + 1;
+      const tool = sessionRows[i].tool_name || 'unknown';
+      while (
+        j < sessionRows.length
+        && (sessionRows[j].tool_name || 'unknown') === tool
+        && rowTime(sessionRows[j]) - rowTime(sessionRows[j - 1]) <= maxGapMs
+      ) {
+        j += 1;
+      }
+      const count = j - i;
+      if (count >= 3) {
+        clusters.push({
+          session,
+          tool,
+          count,
+          firstAt: sessionRows[i].ts,
+          lastAt: sessionRows[j - 1].ts,
+          spanMs: rowTime(sessionRows[j - 1]) - rowTime(sessionRows[i]),
+        });
+      }
+      i = j;
+    }
+  }
+  return clusters
+    .sort((a, b) => b.count - a.count || b.spanMs - a.spanMs || a.tool.localeCompare(b.tool))
+    .slice(0, LIMIT);
+}
+
+function evaluateRepeatClusters(clusters) {
+  const recommendations = [];
+  for (const cluster of clusters) {
+    if (cluster.tool === 'read') {
+      recommendations.push(`read: ${cluster.count} consecutive reads in session ${cluster.session}; use one wider read({file_path, offset, limit}) window when the ranges are adjacent.`);
+    } else if (cluster.tool === 'grep') {
+      recommendations.push(`grep: ${cluster.count} consecutive searches in session ${cluster.session}; combine patterns/globs or switch to read/find_symbol after the first useful hit.`);
+    } else if (cluster.tool === 'bash') {
+      recommendations.push(`bash: ${cluster.count} consecutive shell calls in session ${cluster.session}; use persistent:true/session_id for setup-heavy commands or dedicated read/grep/list tools for file I/O.`);
+    } else if (cluster.tool === 'edit') {
+      recommendations.push(`edit: ${cluster.count} consecutive edits in session ${cluster.session}; batch independent replacements in edit({edits:[...]}) or route multi-hunk changes through apply_patch.`);
+    } else if (cluster.tool === 'apply_patch') {
+      recommendations.push(`apply_patch: ${cluster.count} consecutive patches in session ${cluster.session}; merge adjacent hunks into one patch when they touch the same file.`);
+    }
+  }
+  return { recommendations: Array.from(new Set(recommendations)) };
+}
+
+function evaluateEventClusters(clusters) {
+  const failures = [];
+  const recommendations = [];
+  for (const cluster of clusters) {
+    if (cluster.tool === 'edit' && cluster.code === '8' && cluster.path && cluster.count >= 2) {
+      failures.push({ tool: 'edit', code: '8', path: cluster.path, count: cluster.count, reason: 'same-file-edit-miss-loop' });
+      const lines = Object.keys(cluster.nearestLines || {}).slice(0, 3).join(', ');
+      recommendations.push(`edit: ${cluster.count} old_string misses on ${cluster.path}${lines ? ` near lines ${lines}` : ''}; re-read a narrow Mixdog window and switch to exact visible bytes or apply_patch.`);
+    }
+    if (cluster.tool === 'edit' && cluster.code === '10' && cluster.count >= 1) {
+      recommendations.push(`edit: ${cluster.count} large old_string warning(s); route chunks >=30 lines through apply_patch instead of edit.`);
+    }
+    if (cluster.tool === 'write' && cluster.code === '10' && cluster.count >= 1) {
+      recommendations.push(`write: ${cluster.count} partial-read overwrite block(s); use apply_patch for partial changes or full read before whole-file write.`);
+    }
+  }
+  return { failures, recommendations: Array.from(new Set(recommendations)) };
+}
+
+const traceRows = loadTraceRows(TRACE_PATH);
+const toolEventRows = !TRACE_EXPLICIT ? loadToolEventRows(TOOL_EVENTS_PATH) : [];
+const mcpDebugRows = !TRACE_EXPLICIT ? loadMcpDebugRows(MCP_DEBUG_PATH) : [];
+const fallbackRows = [...mcpDebugRows, ...toolEventRows].sort((a, b) => rowTime(a) - rowTime(b));
+const rows = traceRows.length > 0 ? traceRows : fallbackRows;
+const source = traceRows.length > 0
+  ? 'bridge-trace'
+  : (mcpDebugRows.length > 0 && toolEventRows.length > 0
+    ? 'mcp-debug+tool-events'
+    : (mcpDebugRows.length > 0 ? 'mcp-debug' : (toolEventRows.length > 0 ? 'tool-events' : 'none')));
+const thresholds = loadThresholds();
+const routeTraceMode = TRACE_EXPLICIT && rows.some((row) => row.kind === 'route' || row.route_scenario || row.routeScenario);
+const tools = groupToolRows(rows).slice(0, LIMIT);
+const evaluation = evaluateTools(tools, thresholds, { skipGenericErrorRate: routeTraceMode });
+const routes = summarizeRoutes(rows);
+const routeEvaluation = evaluateRoutes(routes);
+const eventRows = traceRows.length > 0 ? [...rows, ...toolEventRows] : rows;
+const eventClusters = summarizeEventClusters(eventRows);
+const eventEvaluation = evaluateEventClusters(eventClusters);
+const repeatRows = traceRows.length > 0 ? [...rows, ...mcpDebugRows] : rows;
+const repeatClusters = summarizeRepeatClusters(repeatRows);
+const repeatEvaluation = evaluateRepeatClusters(repeatClusters);
+const toolSampleCount = tools.reduce((sum, row) => sum + row.count, 0);
+const warnings = [];
+if (traceRows.length === 0 && toolEventRows.length > 0) {
+  warnings.push(`no bridge trace rows found at ${TRACE_PATH}; using tool-events fallback at ${TOOL_EVENTS_PATH}`);
+}
+if (traceRows.length === 0 && mcpDebugRows.length > 0) {
+  warnings.push(`no bridge trace rows found at ${TRACE_PATH}; using mcp-debug fallback at ${MCP_DEBUG_PATH}`);
+}
+if (rows.length === 0) {
+  warnings.push(`no trace rows found at ${TRACE_PATH}; run a live session with MIXDOG_BRIDGE_TRACE_VERBOSE=1, pass --trace=<bridge-trace.jsonl>, feed scripts/io-route-harness.mjs --trace-out=<file>, or inspect tool-events at ${TOOL_EVENTS_PATH}`);
+}
+if (rows.length > 0 && toolSampleCount === 0) {
+  warnings.push(`trace rows found at ${TRACE_PATH}, but no I/O tool rows matched; check bridge trace verbosity or feed a route harness trace`);
+}
+const rowFailures = rows.length === 0 && REQUIRE_ROWS
+  ? [{ reason: 'no-trace-rows', tracePath: TRACE_PATH, windowHours: HOURS }]
+  : (toolSampleCount === 0 && REQUIRE_ROWS
+    ? [{ reason: 'no-io-tool-rows', tracePath: TRACE_PATH, windowHours: HOURS }]
+    : []);
+const output = {
+  windowHours: HOURS,
+  tracePath: TRACE_PATH,
+  toolEventsPath: TOOL_EVENTS_PATH,
+  mcpDebugPath: MCP_DEBUG_PATH,
+  source,
+  traceRows: traceRows.length,
+  toolEventRows: toolEventRows.length,
+  mcpDebugRows: mcpDebugRows.length,
+  rows: rows.length,
+  tools,
+  routes,
+  eventClusters,
+  repeatClusters,
+  loop: summarizeLoop(rows),
+  trim: summarizeTrim(rows),
+  compression: summarizeCompression(rows),
+  thresholds: CHECK ? thresholds : undefined,
+  failures: CHECK ? [...rowFailures, ...evaluation.failures, ...routeEvaluation.failures, ...eventEvaluation.failures] : undefined,
+  warnings,
+  recommendations: Array.from(new Set([...warnings, ...evaluation.recommendations, ...routeEvaluation.recommendations, ...eventEvaluation.recommendations, ...repeatEvaluation.recommendations])),
+};
+
+if (JSON_OUT) {
+  console.log(JSON.stringify(output, null, 2));
+} else {
+  console.log(`# I/O Telemetry (${HOURS}h)`);
+  console.log(`trace: ${TRACE_PATH}`);
+  console.log(`events: ${TOOL_EVENTS_PATH}`);
+  console.log(`mcp-debug: ${MCP_DEBUG_PATH}`);
+  console.log(`source: ${source}`);
+  console.log(`rows: ${rows.length}`);
+  if (!rows.length) {
+    for (const warning of warnings) console.log(`warning: ${warning}`);
+    if (CHECK && REQUIRE_ROWS) {
+      console.log('');
+      console.log('thresholds: fail no-trace-rows');
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+  console.log('');
+  console.log('tool                 count    p50ms    p90ms     maxms    totalms  notes');
+  for (const item of output.tools) {
+    const notes = [];
+    if (item.wideReads) notes.push(`wide-read:${item.wideReads}`);
+    if (item.broadGrepCalls) notes.push(`broad-call:${item.broadGrepCalls}`);
+    if (item.largeEditCalls) notes.push(`large-edit:${item.largeEditCalls}`);
+    if (item.nextCalls) notes.push(`next_call:${item.nextCalls}/${item.count}`);
+    if (item.nextCallTotal && item.nextCallTotal !== item.nextCalls) notes.push(`next_call_total:${item.nextCallTotal}`);
+    if (item.nextCallMisses && Object.keys(item.nextCallMisses).length > 0) notes.push(`missing_next_call:${Object.entries(item.nextCallMisses).map(([k, v]) => `${k}=${v}`).join(',')}`);
+    if (item.outputBytes?.p90) notes.push(`out-p90:${item.outputBytes.p90}B`);
+    if (item.outputLines?.p90) notes.push(`lines-p90:${item.outputLines.p90}`);
+    const errors = item.resultKinds.error || 0;
+    if (errors) notes.push(`errors:${errors}`);
+    console.log(`${item.tool.padEnd(18)} ${String(item.count).padStart(5)} ${String(item.p50).padStart(8)} ${String(item.p90).padStart(8)} ${String(item.max).padStart(9)} ${String(item.total).padStart(10)}  ${notes.join(' ')}`);
+  }
+  if (eventClusters.length > 0) {
+    console.log('');
+    console.log('event clusters');
+    for (const cluster of eventClusters) {
+      const lines = Object.keys(cluster.nearestLines || {}).slice(0, 4).join(',');
+      console.log(`${cluster.tool} code=${cluster.code || '-'} count=${cluster.count} path=${cluster.path || '(none)'}${lines ? ` nearest=${lines}` : ''}`);
+    }
+  }
+  if (repeatClusters.length > 0) {
+    console.log('');
+    console.log('repeat clusters');
+    for (const cluster of repeatClusters) {
+      console.log(`${cluster.tool} count=${cluster.count} session=${cluster.session} span=${cluster.spanMs}ms`);
+    }
+  }
+  if (output.routes.length > 0) {
+    console.log('');
+    console.log('route scenario                  winner                 routes  failed  notes');
+    for (const item of output.routes) {
+      const winner = item.routes.find((route) => route.route === item.winner);
+      const notes = winner ? `score:${winner.score} calls:${winner.toolCalls} broad:${winner.broadGrepCalls || 0} largeEdit:${winner.largeEditCalls || 0} out:${winner.outputBytes}B` : '';
+      console.log(`${item.scenario.padEnd(31)} ${(item.winner || '(none)').padEnd(22)} ${String(item.count).padStart(6)} ${String(item.failures).padStart(7)}  ${notes}`);
+    }
+  }
+  console.log('');
+  console.log(`provider send p50/p90/max ms: ${output.loop.sends.p50}/${output.loop.sends.p90}/${output.loop.sends.max}`);
+  console.log(`provider body p50/p90/max bytes: ${output.loop.bodyBytes.p50}/${output.loop.bodyBytes.p90}/${output.loop.bodyBytes.max}`);
+  console.log(`trim changed: ${output.trim.changed}/${output.trim.count}, bytes saved: ${output.trim.bytesSaved}`);
+  console.log(`compression rows: ${output.compression.count}, bytes saved: ${output.compression.bytesSaved}`);
+  if (output.recommendations.length > 0) {
+    console.log('');
+    console.log('recommendations:');
+    for (const line of output.recommendations) console.log(`- ${line}`);
+  }
+  if (CHECK) {
+    console.log('');
+    console.log(output.failures.length === 0 ? 'thresholds: pass' : `thresholds: fail ${output.failures.length}`);
+  }
+}
+
+if (CHECK && output.failures?.length > 0) {
+  process.exit(1);
+}