mixdog 0.7.1

package/scripts/io-explore-bench.mjs

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+// I/O EXPLORATION bench — multi-turn cost of LOOKUP routes.
+//
+// Why this exists: io-route-harness scores edit ROUTES; io-mini-bench scores
+// per-call LATENCY. Neither measures the cost that dominates real exploration
+// work: round-trips (turns) and the CONTEXT INTEGRAL — every tool result stays
+// in context and is re-processed as prompt on every later turn, so early/large
+// outputs cost ~ (output x remaining turns). This bench runs the REAL lookup
+// tools (code_graph / grep / glob / list / read) on a hermetic fixture, then
+// scores each competing route with that multi-turn model. `explore` (an LLM
+// sub-agent) is MODELED, not executed, and labelled [modeled].
+//
+// Usage:
+//   node scripts/io-explore-bench.mjs            # table
+//   node scripts/io-explore-bench.mjs --json     # machine-readable
+//   node scripts/io-explore-bench.mjs --check    # assert per-task expected winner (exit 1 on regression)
+
+import { performance } from 'node:perf_hooks';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+process.env.CLAUDE_PLUGIN_ROOT ||= ROOT;
+// SAFETY: own an isolated temp data dir; never `||=` the LIVE CLAUDE_PLUGIN_DATA,
+// which the cleanup below would then rm.
+const BENCH_PLUGIN_DATA = join(tmpdir(), `mixdog-io-explore-bench-data-${process.pid}`);
+process.env.CLAUDE_PLUGIN_DATA = BENCH_PLUGIN_DATA;
+
+const { executeBuiltinTool } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/tools/builtin.mjs')).href);
+const { executeCodeGraphTool } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/tools/code-graph.mjs')).href);
+
+const ARGV = process.argv.slice(2);
+const JSON_OUT = ARGV.includes('--json');
+const CHECK = ARGV.includes('--check');
+const WORKDIR = await mkdtemp(join(tmpdir(), 'mixdog-io-explore-bench-'));
+
+// ---- multi-turn cost model (bytes/4 ~= tokens) -----------------------------
+const B2T = (b) => b / 4;
+const P0 = 6000;                    // fixed prefix tokens (system+rules+convo)
+const REASON_PER_TURN = 180;        // model thinking tokens per turn
+const RT_SECONDS = 1.4;             // round-trip per turn (network+exec+TTFT)
+const PROMPT_TOK_PER_S = 9000;
+const GEN_TOK_PER_S = 90;
+const CACHE_PREFIX_DISCOUNT = 0.1;  // cached prefix billed at 0.1x
+// A lookup is never the last thing you do: its OUTPUT lingers in context and is
+// re-billed on the remaining task turns (the edit, the verify, the next probe).
+// Without this, single-turn routes look cost-tied and tighter output (the real
+// differentiator) is invisible. ~4 follow-on turns is a conservative tail.
+const TAIL_TURNS = 4;
+// gen bytes = what the model writes to invoke each tool (call args), by tool.
+const GEN_BYTES = { code_graph: 40, grep: 55, glob: 40, list: 50, read: 45, explore: 120 };
+
+// ---- hermetic fixture ------------------------------------------------------
+// A small but realistic project: one hot symbol with several callers, a module
+// with multiple exports, a config literal, nested dirs, and decoy files.
+async function buildFixture(dir) {
+  const f = async (rel, body) => {
+    const full = join(dir, rel);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, body, 'utf8');
+  };
+  await f('package.json', JSON.stringify({ name: 'fx', version: '1.0.0', type: 'module' }, null, 2) + '\n');
+  await f('src/core/engine.mjs', [
+    'import { validate } from "./validate.mjs";',
+    'import { CONFIG } from "../config.mjs";',
+    'export function runEngine(input) {',
+    '  const v = validate(input);',
+    '  return v ? input * CONFIG.MAX_RETRIES : 0;',
+    '}',
+    'export function bootEngine() {',
+    '  return runEngine(1) + runEngine(2);',
+    '}',
+    '',
+  ].join('\n'));
+  await f('src/core/validate.mjs', [
+    'export function validate(x) {',
+    '  return typeof x === "number" && x >= 0;',
+    '}',
+    '',
+  ].join('\n'));
+  await f('src/config.mjs', [
+    'export const CONFIG = {',
+    '  MAX_RETRIES: 5,',
+    '  TIMEOUT_MS: 3000,',
+    '};',
+    '',
+  ].join('\n'));
+  await f('src/api/handler.mjs', [
+    'import { runEngine } from "../core/engine.mjs";',
+    'export function handle(req) {',
+    '  return runEngine(req.value);',
+    '}',
+    'export function batchHandle(reqs) {',
+    '  return reqs.map((r) => runEngine(r.value));',
+    '}',
+    '',
+  ].join('\n'));
+  await f('src/api/routes.mjs', [
+    'import { handle } from "./handler.mjs";',
+    'export const routes = { post: handle };',
+    '',
+  ].join('\n'));
+  // decoys so glob/list/grep have noise to wade through
+  for (let i = 0; i < 6; i++) {
+    await f(`src/util/util-${i}.mjs`, `export const util${i} = () => ${i};\n`);
+  }
+  // a large module to exercise read context-budget modes (full vs max_lines vs
+  // summary vs count) — small files would all fit under budget and show nothing.
+  await f('src/big-module.mjs', Array.from({ length: 320 }, (_, i) => `export const item${i} = { id: ${i}, name: "item-${i}", weight: ${i * 3} };`).join('\n') + '\n');
+}
+
+// ---- real tool execution wrappers ------------------------------------------
+async function call(state, kind, run) {
+  const started = performance.now();
+  let out = '';
+  let ok = true;
+  try {
+    out = String((await run()) ?? '');
+    if (/^Error(\s|\[|:)/.test(out)) ok = false;
+  } catch (e) {
+    out = `Error: ${e?.message || String(e)}`;
+    ok = false;
+  }
+  const ms = Number((performance.now() - started).toFixed(3));
+  state.calls.push({ kind, outBytes: Buffer.byteLength(out, 'utf8'), ms, ok });
+  return out;
+}
+
+const TOOL = {
+  code_graph: (dir, args) => (s) => call(s, 'code_graph', () => executeCodeGraphTool('code_graph', { ...args, cwd: dir }, dir)),
+  grep: (dir, args) => (s) => call(s, 'grep', () => executeBuiltinTool('grep', args, dir, { readStateScope: s.scope, sessionId: s.scope })),
+  glob: (dir, args) => (s) => call(s, 'glob', () => executeBuiltinTool('glob', args, dir, { readStateScope: s.scope, sessionId: s.scope })),
+  list: (dir, args) => (s) => call(s, 'list', () => executeBuiltinTool('list', args, dir, { readStateScope: s.scope, sessionId: s.scope })),
+  read: (dir, args) => (s) => call(s, 'read', () => executeBuiltinTool('read', args, dir, { readStateScope: s.scope, sessionId: s.scope })),
+  // explore is an LLM sub-agent — MODELED, not executed. Background explore costs
+  // the LEAD exactly 2 turns regardless of N: (1) dispatch (lead writes the
+  // N-query array, gets a handle) and (2) integrate the dispatch_result brief.
+  // The N explorers run in parallel on a cheap model in throwaway contexts, so
+  // their inference is hiddenTok (NOT lead context); the merged brief is capped.
+  explore: (n = 1) => (s) => {
+    const BRIEF_CAP = 30000;                          // merged brief smart-truncate cap
+    const briefBytes = Math.min(BRIEF_CAP, 8000 * n); // grows with N, then capped
+    s.calls.push({ kind: 'explore', outBytes: 80, gen: 120 * n, ms: 0, modeled: true, ok: true });          // turn 1: dispatch
+    s.calls.push({ kind: 'explore', outBytes: briefBytes, gen: 20, ms: 0, modeled: true, hiddenTok: 14000 * n, ok: true }); // turn 2: notify
+    return Promise.resolve('[modeled explore]');
+  },
+};
+
+// ---- score a completed route (sequence of recorded calls) ------------------
+// scoreTurns: a route is a list of TURNS; each turn is a list of calls executed
+// in ONE assistant message (parallel tool use = one round-trip, outputs land
+// together). Round-trip + prompt pass are billed PER TURN, not per call — so
+// batching independent calls into one turn cuts both turns (time) and the
+// intermediate context re-processing.
+function scoreTurns(turns) {
+  let ctxTok = P0, genTok = 0, promptIntegral = 0, hiddenTok = 0, seconds = 0;
+  let turnCount = 0;
+  for (const turn of turns) {
+    turnCount += 1;
+    const genThisTurn = turn.reduce((a, c) => a + B2T(c.gen ?? GEN_BYTES[c.kind] ?? 40), 0) + REASON_PER_TURN;
+    const cached = P0 * CACHE_PREFIX_DISCOUNT;
+    const fresh = (ctxTok - P0) + genThisTurn;
+    promptIntegral += cached + fresh;
+    genTok += genThisTurn;
+    for (const c of turn) hiddenTok += c.hiddenTok || 0;
+    seconds += RT_SECONDS + (cached + fresh) / PROMPT_TOK_PER_S + genThisTurn / GEN_TOK_PER_S;
+    ctxTok += turn.reduce((a, c) => a + B2T(c.outBytes), 0) + genThisTurn;
+  }
+  const calls = turns.flat();
+  // Tail: this route's accumulated OUTPUT persists through ~TAIL_TURNS follow-on
+  // task turns, re-billed each time. Tighter lookup output wins here.
+  const outTok = calls.reduce((a, c) => a + B2T(c.outBytes), 0);
+  promptIntegral += outTok * TAIL_TURNS;
+  // leadTok = what the LEAD context actually pays (turns + briefs + tail).
+  // totalTok = leadTok + hidden sub-agent inference (offloaded, NOT in lead ctx).
+  // For direct tools hidden=0, so leadTok === totalTok. For explore they diverge:
+  // the heavy explorer loop is billed to a throwaway sub-agent context (and a
+  // cheaper model), so the lead only eats the brief.
+  const leadTok = Math.round(promptIntegral + genTok);
+  const totalTok = leadTok + Math.round(hiddenTok);
+  return {
+    turns: turnCount,
+    outBytes: calls.reduce((a, c) => a + c.outBytes, 0),
+    genTok: Math.round(genTok),
+    ctxIntegral: Math.round(promptIntegral),
+    hiddenTok: Math.round(hiddenTok),
+    leadTok,
+    totalTok,
+    seconds: +seconds.toFixed(1),
+    anyError: calls.some((c) => c.ok === false),
+  };
+}
+
+// Serial route: each call is its own turn (one round-trip per call).
+const score = (calls) => scoreTurns(calls.map((c) => [c]));
+
+// ---- tasks: each = realistic exploration goal + competing routes -----------
+// expectedWinner names the tool/route that SHOULD be cheapest for that niche;
+// --check fails if a different route wins (route regression / mis-routing).
+function tasks(dir) {
+  return [
+    {
+      // Lesson the bench taught: for JUST a definition location, grep's one tight
+      // line beats code_graph, which over-delivers callees you didn't ask for.
+      name: 'locate-symbol-def (where is runEngine defined?)',
+      expectedWinner: 'grep',
+      routes: {
+        code_graph: [TOOL.code_graph(dir, { mode: 'find_symbol', symbol: 'runEngine' })],
+        grep: [TOOL.grep(dir, { pattern: 'function runEngine', path: 'src', glob: '*.mjs', output_mode: 'content', '-n': true })],
+        'glob+grep': [
+          TOOL.glob(dir, { pattern: 'src/**/*.mjs' }),
+          TOOL.grep(dir, { pattern: 'function runEngine', path: 'src', output_mode: 'content', '-n': true }),
+        ],
+      },
+    },
+    {
+      name: 'find-callers (who calls runEngine?)',
+      expectedWinner: 'code_graph',
+      routes: {
+        code_graph: [TOOL.code_graph(dir, { mode: 'callers', symbol: 'runEngine' })],
+        'grep+reads': [
+          TOOL.grep(dir, { pattern: 'runEngine', path: 'src', glob: '*.mjs', output_mode: 'content', '-n': true }),
+          TOOL.read(dir, { path: 'src/api/handler.mjs', line: 3, context: 2 }),
+          TOOL.read(dir, { path: 'src/core/engine.mjs', line: 8, context: 2 }),
+        ],
+      },
+    },
+    {
+      name: 'find-config-literal (where is MAX_RETRIES set?)',
+      expectedWinner: 'grep',
+      routes: {
+        grep: [TOOL.grep(dir, { pattern: 'MAX_RETRIES', path: 'src', glob: '*.mjs', output_mode: 'content', '-n': true })],
+        code_graph: [TOOL.code_graph(dir, { mode: 'find_symbol', symbol: 'MAX_RETRIES' })],
+        explore: [TOOL.explore()],
+      },
+    },
+    {
+      name: 'keyword-to-symbols (partial name Engine — which symbols?)',
+      expectedWinner: 'code_graph',
+      routes: {
+        code_graph: [TOOL.code_graph(dir, { mode: 'search', symbol: 'Engine' })],
+        grep: [TOOL.grep(dir, { pattern: 'Engine', path: 'src', glob: '*.mjs', output_mode: 'content', '-n': true })],
+        explore: [TOOL.explore()],
+      },
+    },
+
+    {
+      name: 'locate-file-by-name (find the config module)',
+      expectedWinner: 'glob',
+      routes: {
+        glob: [TOOL.glob(dir, { pattern: 'src/**/config.mjs' })],
+        list: [TOOL.list(dir, { mode: 'find', path: 'src', name: 'config', type: 'file' })],
+        grep: [TOOL.grep(dir, { pattern: 'CONFIG', path: 'src', glob: '*.mjs', output_mode: 'files_with_matches' })],
+      },
+    },
+    {
+      // read context-budget ladder on a 320-line module: count < summary <
+      // max_lines < full. Shows the new max_lines / mode knobs cut lead cost.
+      name: 'glance-large-file (320-line module)',
+      expectedWinner: 'count',
+      routes: {
+        count: [TOOL.read(dir, { path: 'src/big-module.mjs', mode: 'count' })],
+        summary: [TOOL.read(dir, { path: 'src/big-module.mjs', mode: 'summary', n: 30 })],
+        max_lines: [TOOL.read(dir, { path: 'src/big-module.mjs', max_lines: 40 })],
+        full: [TOOL.read(dir, { path: 'src/big-module.mjs' })],
+      },
+    },
+    {
+      name: 'understand-subsystem (entry points of src/core)',
+      expectedWinner: 'code_graph',
+      routes: {
+        code_graph: [TOOL.code_graph(dir, { mode: 'overview', file: 'src/core/engine.mjs' })],
+        'list+read': [
+          TOOL.list(dir, { path: 'src/core' }),
+          TOOL.read(dir, { path: 'src/core/engine.mjs' }),
+          TOOL.read(dir, { path: 'src/core/validate.mjs' }),
+        ],
+        explore: [TOOL.explore()],
+      },
+    },
+  ];
+}
+
+async function main() {
+  await mkdir(BENCH_PLUGIN_DATA, { recursive: true });
+  const dir = await mkdtemp(join(WORKDIR, 'fx-'));
+  await buildFixture(dir);
+
+  const results = [];
+  for (const task of tasks(dir)) {
+    const rows = [];
+    for (const [routeName, steps] of Object.entries(task.routes)) {
+      const state = { scope: `explore-bench-${routeName}-${process.pid}`, calls: [] };
+      for (const step of steps) await step(state);
+      rows.push({ route: routeName, ...score(state.calls) });
+    }
+    rows.sort((a, b) => a.totalTok - b.totalTok);
+    results.push({ task: task.name, expectedWinner: task.expectedWinner, winner: rows[0].route, rows });
+  }
+
+  // ---- fan-out economics: explore's 2-turn LEAD overhead amortized across N
+  // parallel sub-queries. Modeled (explore can't be executed). Shows leadTok
+  // (lead context cost) diverging from totalTok (incl. hidden sub-agent loop).
+  const perAreaDirect = () => [
+    { kind: 'list', outBytes: 120, ok: true },
+    { kind: 'read', outBytes: 250, ok: true },
+    { kind: 'read', outBytes: 260, ok: true },
+  ];
+  const fanout = [1, 3, 6, 12].map((N) => {
+    // direct serial: per area list+read+read, each call its own turn.
+    const directSerial = []; for (let i = 0; i < N; i++) directSerial.push(...perAreaDirect());
+    // direct PARALLEL: turn 1 = N discovery calls batched, turn 2 = N reads batched
+    // (2 turns flat like explore) — but ALL raw output lands in LEAD context, no cap.
+    const directParallelTurns = [
+      Array.from({ length: N }, () => ({ kind: 'list', outBytes: 120, ok: true })),
+      Array.from({ length: N }, () => ({ kind: 'read', outBytes: 510, ok: true })),
+    ];
+    const sepExplore = []; for (let i = 0; i < N; i++) { const s = { calls: [] }; TOOL.explore(1)(s); sepExplore.push(...s.calls); }
+    const batchState = { calls: [] }; TOOL.explore(N)(batchState);
+    return {
+      N,
+      directSerial: score(directSerial),
+      directParallel: scoreTurns(directParallelTurns),
+      separateExplore: score(sepExplore),
+      batchedExplore: score(batchState.calls),
+    };
+  });
+
+  // ---- parallel-in-1-turn demo: independent calls batched into ONE turn vs
+  // serial (one round-trip each). Dependent chains (grep->read) cannot collapse.
+  const R = (b) => ({ kind: 'read', outBytes: b, ok: true });
+  const G = (b) => ({ kind: 'grep', outBytes: b, ok: true });
+  const parallelDemo = [
+    {
+      name: '3 independent file reads',
+      serial: score([R(260), R(260), R(260)]),
+      parallel: scoreTurns([[R(260), R(260), R(260)]]),
+    },
+    {
+      name: 'grep then 2 callsite reads (grep is dependency)',
+      serial: score([G(350), R(260), R(260)]),
+      parallel: scoreTurns([[G(350)], [R(260), R(260)]]),
+    },
+  ];
+
+  // ---- uniform output-cap effect: REAL full read of the 320-line module
+  // (~23KB) with options.toolOutputMaxBytes swept. Shows the single knob's
+  // actual leadTok reduction on a real runaway output.
+  // Distinct file per cap so the process-global read cache (keyed without scope
+  // or the cap) can't dedup later reads to a "[file unchanged]" stub.
+  const capSweep = [];
+  for (const cap of [0, 8000, 4000, 2000]) {
+    const rel = `src/cap-target-${cap}.mjs`;
+    await writeFile(join(dir, rel), Array.from({ length: 320 }, (_, i) => `export const c${cap}_item${i} = { id: ${i}, pad: "xxxxxxxxxxxxxxxxxxxx" };`).join('\n') + '\n', 'utf8');
+    const opts = { readStateScope: `cap-${cap}`, sessionId: `cap-${cap}` };
+    if (cap > 0) opts.toolOutputMaxBytes = cap;
+    const out = String(await executeBuiltinTool('read', { path: rel, full: true }, dir, opts));
+    const ob = Buffer.byteLength(out, 'utf8');
+    capSweep.push({ cap, outBytes: ob, capped: out.includes('tool_output_token_limit'), leadTok: scoreTurns([[{ kind: 'read', outBytes: ob, ok: true }]]).leadTok });
+  }
+
+  const failures = [];
+  if (CHECK) {
+    for (const r of results) {
+      if (r.expectedWinner && r.winner !== r.expectedWinner) {
+        failures.push({ task: r.task, winner: r.winner, expectedWinner: r.expectedWinner });
+      }
+      const w = r.rows[0];
+      if (w.anyError) failures.push({ task: r.task, winner: r.winner, reason: 'winner-errored' });
+    }
+  }
+
+  const pad = (s, n) => String(s).padEnd(n);
+  const padL = (s, n) => String(s).padStart(n);
+  if (JSON_OUT) {
+    console.log(JSON.stringify({ results, fanout, parallelDemo, capSweep, ...(CHECK ? { failures } : {}) }, null, 2));
+  } else {
+    console.log('## Niche map (ranked by totalTok; leadTok = lead-context cost only)');
+    for (const r of results) {
+      console.log(`\n### ${r.task}   winner=${r.winner}${r.expectedWinner && r.winner !== r.expectedWinner ? ` (EXPECTED ${r.expectedWinner})` : ''}`);
+      console.log(pad('route', 14) + padL('turns', 6) + padL('outB', 8) + padL('leadTok', 9) + padL('hidden', 8) + padL('totalTok', 10) + padL('sec', 7));
+      const best = r.rows[0].totalTok;
+      for (const row of r.rows) {
+        const mark = row.totalTok === best ? '  <=' : ` ${(row.totalTok / best).toFixed(2)}x`;
+        console.log(pad(row.route, 14) + padL(row.turns, 6) + padL(row.outBytes, 8) + padL(row.leadTok, 9) + padL(row.hiddenTok, 8) + padL(row.totalTok, 10) + padL(row.seconds, 7) + mark + (row.anyError ? ' ERR' : ''));
+      }
+    }
+    console.log('\n## Parallel-in-1-turn (independent calls share ONE round-trip) — modeled');
+    console.log(pad('task', 46) + pad('mode', 10) + padL('turns', 6) + padL('leadTok', 9) + padL('sec', 7));
+    for (const d of parallelDemo) {
+      for (const [m, c] of [['serial', d.serial], ['parallel', d.parallel]]) {
+        const mark = m === 'parallel' ? ` ${(c.leadTok / d.serial.leadTok).toFixed(2)}x` : '';
+        console.log(pad(d.name, 46) + pad(m, 10) + padL(c.turns, 6) + padL(c.leadTok, 9) + padL(c.seconds, 7) + mark);
+      }
+    }
+    console.log('\n## Fan-out economics (N exploration areas) — modeled');
+    console.log('Both directParallel and batchedExplore are ~2 turns; only explore CAPS lead context.');
+    console.log(pad('N', 4) + pad('strategy', 20) + padL('turns', 6) + padL('leadTok', 9) + padL('total', 9) + padL('lead/area', 11));
+    for (const fo of fanout) {
+      for (const [label, c] of [['direct serial', fo.directSerial], ['direct parallel', fo.directParallel], ['N separate explore', fo.separateExplore], ['1 batched explore', fo.batchedExplore]]) {
+        console.log(pad(String(fo.N), 4) + pad(label, 20) + padL(c.turns, 6) + padL(c.leadTok, 9) + padL(c.totalTok, 9) + padL(Math.round(c.leadTok / fo.N), 11));
+      }
+      console.log('');
+    }
+    console.log('\n## Uniform output-cap effect (REAL full read of 320-line module, sweep toolOutputMaxBytes)');
+    console.log(pad('cap', 10) + padL('outBytes', 9) + padL('leadTok', 9) + padL('vs off', 8) + '  capped');
+    const offLead = capSweep[0]?.leadTok || 1;
+    for (const c of capSweep) {
+      console.log(pad(c.cap === 0 ? 'off' : String(c.cap), 10) + padL(c.outBytes, 9) + padL(c.leadTok, 9) + padL((c.leadTok / offLead).toFixed(2) + 'x', 8) + '  ' + (c.capped ? 'yes' : 'no'));
+    }
+    if (CHECK) console.log(`\nexplore-bench: ${failures.length === 0 ? 'pass' : 'fail ' + JSON.stringify(failures)}`);
+    console.log('note: tokens=bytes/4 proxy. leadTok=lead context (turns+briefs+tail). totalTok=leadTok+hidden sub-agent (offloaded, cheap model). explore [modeled], 2 lead turns.');
+  }
+  if (CHECK && failures.length > 0) process.exitCode = 1;
+}
+
+try {
+  await main();
+} finally {
+  await rm(WORKDIR, { recursive: true, force: true }).catch(() => {});
+  await rm(BENCH_PLUGIN_DATA, { recursive: true, force: true }).catch(() => {});
+}

package/scripts/io-guardrails-smoke.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const DATA_DIR = await mkdtemp(join(tmpdir(), 'mixdog-io-guardrails-data-'));
+const WORKDIR = await mkdtemp(join(tmpdir(), 'mixdog-io-guardrails-'));
+process.env.CLAUDE_PLUGIN_ROOT ||= ROOT;
+process.env.CLAUDE_PLUGIN_DATA ||= DATA_DIR;
+const { countJsonNextCalls } = await import('../src/agent/orchestrator/tools/next-call-utils.mjs');
+
+function assert(cond, message) {
+  if (!cond) throw new Error(message);
+}
+
+function runScript(script, args = [], env = {}) {
+  return spawnSync(process.execPath, [join(ROOT, script), ...args], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      CLAUDE_PLUGIN_ROOT: ROOT,
+      CLAUDE_PLUGIN_DATA: DATA_DIR,
+      ...env,
+    },
+  });
+}
+
+function parseJson(label, text) {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${label}: failed to parse JSON: ${err?.message || String(err)}\n${text}`);
+  }
+}
+
+function traceLine(row) {
+  return `${JSON.stringify({ ts: Date.now(), ...row })}\n`;
+}
+
+try {
+  assert(countJsonNextCalls('next_call: read({"path":"a.txt","line":1})') === 1, 'valid next_call should count');
+  assert(countJsonNextCalls('next_call: read({path,line})') === 0, 'non-JSON next_call should not count');
+  assert(countJsonNextCalls('next_call: read({"path":"a.txt"})\nnext_call: grep({"pattern":"x","path":"."})') === 2, 'multiple next_calls should count');
+
+  const passTrace = join(WORKDIR, 'telemetry-pass.jsonl');
+  await writeFile(passTrace, [
+    traceLine({ kind: 'tool', tool_name: 'read', tool_ms: 5, result_kind: 'normal', result_bytes_est: 120, result_lines_est: 5, tool_args: { path: 'a.txt', offset: 1, limit: 5 } }),
+    traceLine({ kind: 'tool', tool_name: 'grep', tool_ms: 8, result_kind: 'normal', result_has_next_call: true, result_next_call_count: 1, result_bytes_est: 80, result_lines_est: 2, tool_args: { pattern: 'needle', path: '.', output_mode: 'content' } }),
+  ].join(''), 'utf8');
+  const pass = runScript('scripts/io-telemetry-report.mjs', ['--json', '--check', `--trace=${passTrace}`], {
+    MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON: JSON.stringify({
+      read: { p90: 100, errorRate: 0.5, wideReadRate: 0.5 },
+      grep: { p90: 100, errorRate: 0.5, nextCallRateMin: 0.5 },
+    }),
+  });
+  assert(pass.status === 0, `telemetry pass should exit 0\nstdout=${pass.stdout}\nstderr=${pass.stderr}`);
+  const passJson = parseJson('telemetry pass', pass.stdout);
+  assert(Array.isArray(passJson.failures) && passJson.failures.length === 0, `telemetry pass failures not empty: ${pass.stdout}`);
+  const grepRow = (passJson.tools || []).find((row) => row.tool === 'grep');
+  assert(grepRow && grepRow.nextCalls === 1 && grepRow.nextCallRate === 1 && grepRow.nextCallTotal === 1, `telemetry next_call coverage missing: ${pass.stdout}`);
+  const readRow = (passJson.tools || []).find((row) => row.tool === 'read');
+  assert(readRow?.outputBytes?.p90 === 120 && readRow?.outputLines?.p90 === 5, `telemetry output cost missing: ${pass.stdout}`);
+
+  const routeTrace = join(WORKDIR, 'telemetry-route.jsonl');
+  await writeFile(routeTrace, [
+    traceLine({ kind: 'tool', tool_name: 'read', tool_ms: 3, result_kind: 'normal', wide_read: true, result_bytes_est: 6000, tool_args: { path: 'big.txt' } }),
+    traceLine({ kind: 'route', route_scenario: 'large-file-target', route_name: 'wide-read-edit', route_success: false, route_tool_calls: 2, route_output_bytes: 6000, route_wide_reads: 1, route_errors: 0, route_score: null }),
+    traceLine({ kind: 'route', route_scenario: 'large-file-target', route_name: 'line-read-edit', route_success: true, route_tool_calls: 2, route_output_bytes: 260, route_wide_reads: 0, route_errors: 0, route_score: 2020 }),
+  ].join(''), 'utf8');
+  const routePass = runScript('scripts/io-telemetry-report.mjs', ['--json', '--check', '--require-rows', `--trace=${routeTrace}`], {
+    MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON: JSON.stringify({
+      read: { p90: 100, errorRate: 0.5, wideReadRate: 1 },
+    }),
+  });
+  assert(routePass.status === 0, `telemetry route pass should exit 0\nstdout=${routePass.stdout}\nstderr=${routePass.stderr}`);
+  const routeJson = parseJson('telemetry route pass', routePass.stdout);
+  assert(routeJson.tools?.find((row) => row.tool === 'read')?.wideReads === 1, `telemetry explicit wide_read missing: ${routePass.stdout}`);
+  const routeRow = routeJson.routes?.find((row) => row.scenario === 'large-file-target');
+  assert(routeRow?.winner === 'line-read-edit' && routeRow.failures === 1, `telemetry route summary missing: ${routePass.stdout}`);
+
+  const emptyTrace = join(WORKDIR, 'telemetry-empty.jsonl');
+  await writeFile(emptyTrace, '', 'utf8');
+  const emptyFail = runScript('scripts/io-telemetry-report.mjs', ['--json', '--check', '--require-rows', `--trace=${emptyTrace}`]);
+  assert(emptyFail.status === 1, `telemetry require rows should fail on empty trace\nstdout=${emptyFail.stdout}\nstderr=${emptyFail.stderr}`);
+  const emptyJson = parseJson('telemetry empty fail', emptyFail.stdout);
+  assert((emptyJson.failures || []).some((f) => f.reason === 'no-trace-rows'), `telemetry empty failure reason missing: ${emptyFail.stdout}`);
+
+  const routeOnlyTrace = join(WORKDIR, 'telemetry-route-only.jsonl');
+  await writeFile(routeOnlyTrace, traceLine({ kind: 'route', route_scenario: 'route-only', route_name: 'winner', route_success: true, route_score: 1 }), 'utf8');
+  const routeOnlyFail = runScript('scripts/io-telemetry-report.mjs', ['--json', '--check', '--require-rows', `--trace=${routeOnlyTrace}`]);
+  assert(routeOnlyFail.status === 1, `telemetry require rows should fail without tool rows\nstdout=${routeOnlyFail.stdout}\nstderr=${routeOnlyFail.stderr}`);
+  const routeOnlyJson = parseJson('telemetry route-only fail', routeOnlyFail.stdout);
+  assert((routeOnlyJson.failures || []).some((f) => f.reason === 'no-io-tool-rows'), `telemetry route-only failure reason missing: ${routeOnlyFail.stdout}`);
+
+  mkdirSync(DATA_DIR, { recursive: true });
+  await writeFile(join(DATA_DIR, 'tool-events.log'), [
+    `[${new Date().toISOString()}] [tool=edit] [code=8] old_string not found in C:\\Project\\App\\src\\Loop.cs (no exact/fold/nfc-fold/crlf-fold match). Nearest match at line 40: "        void Run()".`,
+    `[${new Date().toISOString()}] [tool=edit] [code=8] old_string not found in C:\\Project\\App\\src\\Loop.cs (no exact/fold/nfc-fold/crlf-fold match). Nearest match at line 41: "        var x = 1;".`,
+    `[${new Date().toISOString()}] [tool=write] [code=10] partial-read snapshot — read full file before overwriting: C:\\Project\\App\\src\\Other.cs`,
+  ].join('\n') + '\n', 'utf8');
+  const eventsFail = runScript('scripts/io-telemetry-report.mjs', ['--json', '--check', '--require-rows', '--hours=1'], {
+    MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON: JSON.stringify({
+      edit: { p90: 100, errorRate: 1 },
+      write: { p90: 100, errorRate: 1 },
+    }),
+  });
+  assert(eventsFail.status === 1, `telemetry tool-events fallback should flag edit miss loop\nstdout=${eventsFail.stdout}\nstderr=${eventsFail.stderr}`);
+  const eventsJson = parseJson('telemetry tool-events fail', eventsFail.stdout);
+  assert(eventsJson.source === 'tool-events' && eventsJson.toolEventRows === 3, `telemetry did not use tool-events fallback: ${eventsFail.stdout}`);
+  assert((eventsJson.failures || []).some((f) => f.reason === 'same-file-edit-miss-loop'), `telemetry event loop failure missing: ${eventsFail.stdout}`);
+  assert((eventsJson.eventClusters || []).some((c) => c.tool === 'edit' && c.code === '8' && c.count === 2), `telemetry event clusters missing edit loop: ${eventsFail.stdout}`);
+
+  const mcpDebugLog = join(WORKDIR, 'mcp-debug.log');
+  const emptyEventsLog = join(WORKDIR, 'empty-tool-events.log');
+  const nowIso = new Date().toISOString();
+  await writeFile(emptyEventsLog, '', 'utf8');
+  await writeFile(mcpDebugLog, [
+    `[${nowIso}] [lead=1 server=10 session=s] [dispatch] start id=10-1 tool=read`,
+    `[${nowIso}] [lead=1 server=10 session=s] [dispatch] ok id=10-1 tool=read elapsed=2ms`,
+    `[${nowIso}] [lead=1 server=10 session=s] [dispatch] start id=10-2 tool=read`,
+    `[${nowIso}] [lead=1 server=10 session=s] [dispatch] ok id=10-2 tool=read elapsed=3ms`,
+    `[${nowIso}] [lead=1 server=10 session=s] [dispatch] start id=10-3 tool=read`,
+    `[${nowIso}] [lead=1 server=10 session=s] [dispatch] ok id=10-3 tool=read elapsed=4ms`,
+  ].join('\n') + '\n', 'utf8');
+  const mcpDebugPass = runScript('scripts/io-telemetry-report.mjs', ['--json', '--hours=1', `--mcp-debug=${mcpDebugLog}`, `--events=${emptyEventsLog}`], {
+    MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON: JSON.stringify({
+      read: { p90: 100, errorRate: 0.5, wideReadRate: 1 },
+    }),
+  });
+  assert(mcpDebugPass.status === 0, `telemetry mcp-debug fallback should pass\nstdout=${mcpDebugPass.stdout}\nstderr=${mcpDebugPass.stderr}`);
+  const mcpDebugJson = parseJson('telemetry mcp-debug pass', mcpDebugPass.stdout);
+  assert(mcpDebugJson.source === 'mcp-debug' && mcpDebugJson.mcpDebugRows === 3, `telemetry did not use mcp-debug fallback: ${mcpDebugPass.stdout}`);
+  assert(mcpDebugJson.tools?.find((row) => row.tool === 'read')?.count === 3, `telemetry mcp-debug read count missing: ${mcpDebugPass.stdout}`);
+  assert((mcpDebugJson.repeatClusters || []).some((c) => c.tool === 'read' && c.count === 3), `telemetry repeat cluster missing: ${mcpDebugPass.stdout}`);
+
+  const failTrace = join(WORKDIR, 'telemetry-fail.jsonl');
+  await writeFile(failTrace, traceLine({
+    kind: 'tool',
+    tool_name: 'read',
+    tool_ms: 300,
+    result_kind: 'error',
+    result_bytes_est: 20000,
+    result_lines_est: 800,
+    tool_args: { path: 'big.txt', mode: 'full' },
+  }), 'utf8');
+  const fail = runScript('scripts/io-telemetry-report.mjs', ['--json', '--check', `--trace=${failTrace}`], {
+    MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON: JSON.stringify({
+      read: { p90: 10, errorRate: 0.01, wideReadRate: 0.01, outputBytesP90: 1000 },
+    }),
+  });
+  assert(fail.status === 1, `telemetry fail should exit 1\nstdout=${fail.stdout}\nstderr=${fail.stderr}`);
+  const failJson = parseJson('telemetry fail', fail.stdout);
+  const reasons = new Set((failJson.failures || []).map((f) => f.reason));
+  for (const reason of ['slow-p90', 'error-rate', 'wide-read-rate', 'output-bytes-p90']) {
+    assert(reasons.has(reason), `telemetry fail missing ${reason}: ${fail.stdout}`);
+  }
+
+  const nextCallFailTrace = join(WORKDIR, 'telemetry-next-call-fail.jsonl');
+  await writeFile(nextCallFailTrace, traceLine({
+    kind: 'tool',
+    tool_name: 'grep',
+    tool_ms: 5,
+    result_kind: 'normal',
+    result_has_next_call: false,
+    tool_args: { pattern: 'needle', path: '.', output_mode: 'content' },
+  }), 'utf8');
+  const nextCallFail = runScript('scripts/io-telemetry-report.mjs', ['--json', '--check', `--trace=${nextCallFailTrace}`], {
+    MIXDOG_IO_TELEMETRY_THRESHOLDS_JSON: JSON.stringify({
+      grep: { p90: 100, errorRate: 0.5, nextCallRateMin: 1 },
+    }),
+  });
+  assert(nextCallFail.status === 1, `telemetry next_call fail should exit 1\nstdout=${nextCallFail.stdout}\nstderr=${nextCallFail.stderr}`);
+  const nextCallFailJson = parseJson('telemetry next_call fail', nextCallFail.stdout);
+  assert((nextCallFailJson.failures || []).some((f) => f.reason === 'next-call-rate'), `telemetry fail missing next-call-rate: ${nextCallFail.stdout}`);
+  const nextCallFailGrep = (nextCallFailJson.tools || []).find((row) => row.tool === 'grep');
+  assert(nextCallFailGrep?.nextCallMisses?.['grep:content'] === 1, `telemetry fail missing nextCallMisses shape: ${nextCallFail.stdout}`);
+  assert((nextCallFailJson.recommendations || []).some((line) => line.includes('top missing: grep:content:1')), `telemetry recommendation missing shape detail: ${nextCallFail.stdout}`);
+
+  const tightBaseline = join(WORKDIR, 'bench-tight-baseline.json');
+  await writeFile(tightBaseline, JSON.stringify({
+    thresholds_ms: {
+      'small-edit': 0.001,
+      'multi-edit': 0.001,
+      'large-dry-run-patch': 0.001,
+      'range-read-cache-hit': 0.001,
+      'grep-cache-hit': 0.001,
+    },
+  }), 'utf8');
+  const benchFail = runScript('scripts/io-mini-bench.mjs', ['--json', '--check-thresholds', `--baseline=${tightBaseline}`], {
+    MIXDOG_IO_MINI_BENCH_ITERS: '1',
+  });
+  assert(benchFail.status !== 0, `bench with tight baseline should fail\nstdout=${benchFail.stdout}\nstderr=${benchFail.stderr}`);
+  const benchJson = parseJson('bench fail', benchFail.stdout);
+  assert(Array.isArray(benchJson.failures) && benchJson.failures.length > 0, `bench failures missing: ${benchFail.stdout}`);
+
+  console.log('io-guardrails smoke passed');
+} finally {
+  await rm(WORKDIR, { recursive: true, force: true });
+  await rm(DATA_DIR, { recursive: true, force: true });
+}

package/scripts/io-mini-bench-baseline.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "note": "Conservative local I/O regression guard. Thresholds are intentionally loose enough for noisy desktop runs; tighten only after collecting stable trace/bench history.",
+  "thresholds_ms": {
+    "small-edit": 250,
+    "multi-edit": 300,
+    "large-dry-run-patch": 1500,
+    "range-read-cache-hit": 80,
+    "grep-cache-hit": 80
+  }
+}