mixdog 0.7.1

package/scripts/io-route-harness.mjs

@@ -0,0 +1,933 @@
+#!/usr/bin/env node
+import { performance } from 'node:perf_hooks';
+import { appendFile, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } 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 finally below would then rm.
+const HARNESS_PLUGIN_DATA = join(tmpdir(), `mixdog-io-route-harness-data-${process.pid}`);
+process.env.CLAUDE_PLUGIN_DATA = HARNESS_PLUGIN_DATA;
+
+const { executeBuiltinTool } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/tools/builtin.mjs')).href);
+const { executePatchTool, closeNativePatchServerForTests } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/tools/patch.mjs')).href);
+const { classifyResultKind } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/session/result-classification.mjs')).href);
+const { countJsonNextCalls } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/tools/next-call-utils.mjs')).href);
+
+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) => {
+  const body = arg.replace(/^--/, '');
+  const idx = body.indexOf('=');
+  return idx < 0 ? [body, ''] : [body.slice(0, idx), body.slice(idx + 1)];
+}));
+
+const OUTPUT_JSON = flags.has('--json') || truthy(process.env.MIXDOG_IO_ROUTE_HARNESS_JSON);
+const CHECK = flags.has('--check') || truthy(process.env.MIXDOG_IO_ROUTE_HARNESS_CHECK);
+const KEEP = flags.has('--keep') || truthy(process.env.MIXDOG_IO_ROUTE_HARNESS_KEEP);
+const TRACE_OUT = kv['trace-out'] || process.env.MIXDOG_IO_ROUTE_TRACE_OUT || '';
+const WORKDIR = await mkdtemp(join(tmpdir(), 'mixdog-io-route-harness-'));
+
+function truthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || ''));
+}
+
+function bytes(text) {
+  return Buffer.byteLength(String(text ?? ''), 'utf8');
+}
+
+function lines(text) {
+  const s = String(text ?? '');
+  return s ? s.split('\n').length : 0;
+}
+
+function patchText(parts) {
+  return `${parts.join('\n')}\n`;
+}
+
+function routeScore(route) {
+  if (!route.success) return Number.POSITIVE_INFINITY;
+  const scoredWallMs = Math.min(route.wallMs, 50);
+  return Math.round(
+    route.toolCalls * 1000
+    + route.outputBytes / 32
+    + scoredWallMs * 3
+    + route.wideReads * 1500
+    + route.broadGrepCalls * 900
+    + route.largeEditCalls * 1200
+    + route.errors * 2000
+  );
+}
+
+function summarizeArgs(tool, args = {}) {
+  if (tool === 'apply_patch') {
+    return {
+      base_path: args.base_path ? '<base_path>' : undefined,
+      dry_run: args.dry_run === true,
+      format: args.format,
+      fuzzy: args.fuzzy,
+      reject_partial: args.reject_partial,
+      patch_bytes: bytes(args.patch || ''),
+    };
+  }
+  return args;
+}
+
+function isWideRead(tool, args, out) {
+  if (tool !== 'read') return false;
+  if (String(out || '').includes('[context-advisory]')) return true;
+  if (String(out || '').includes('TRUNCATED')) return 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';
+  return !hasRange && !compact && (mode === 'full' || mode === undefined) && bytes(out) >= 8192;
+}
+
+function isBroadGrepCall(tool, args = {}) {
+  if (tool !== 'grep') return false;
+  const path = args.path === undefined ? '.' : String(args.path || '.').replace(/\\/g, '/');
+  const rootPath = path === '.' || path === './';
+  return rootPath && !args.glob && !args.type;
+}
+
+function oldStringLineCount(value) {
+  const text = String(value ?? '');
+  if (!text) return 0;
+  return text.split(/\n/).length;
+}
+
+function isLargeEditCall(tool, args = {}) {
+  if (tool !== 'edit') return false;
+  if (oldStringLineCount(args.old_string) >= 30) return true;
+  return Array.isArray(args.edits) && args.edits.some((edit) => oldStringLineCount(edit?.old_string) >= 30);
+}
+
+async function appendTrace(row) {
+  if (!TRACE_OUT) return;
+  await appendFile(TRACE_OUT, `${JSON.stringify(row)}\n`, 'utf8');
+}
+
+async function callBuiltin(state, tool, args) {
+  const started = performance.now();
+  const result = await executeBuiltinTool(tool, args, state.dir, { readStateScope: state.scope, sessionId: state.scope });
+  return recordCall(state, tool, args, result, started);
+}
+
+async function callPatch(state, args) {
+  const started = performance.now();
+  const result = await executePatchTool('apply_patch', args, state.dir, { readStateScope: state.scope, sessionId: state.scope });
+  return recordCall(state, 'apply_patch', args, result, started);
+}
+
+async function recordCall(state, tool, args, result, started) {
+  const text = String(result ?? '');
+  const ms = Number((performance.now() - started).toFixed(3));
+  const kind = classifyResultKind(text);
+  const resultBytes = bytes(text);
+  const resultLines = lines(text);
+  const nextCallCount = countJsonNextCalls(text);
+  const wideRead = isWideRead(tool, args, text);
+  const broadGrepCall = isBroadGrepCall(tool, args);
+  const largeEditCall = isLargeEditCall(tool, args);
+  state.toolCalls += 1;
+  state.outputBytes += resultBytes;
+  state.outputLines += resultLines;
+  state.nextCalls += nextCallCount;
+  state.wideReads += wideRead ? 1 : 0;
+  state.broadGrepCalls += broadGrepCall ? 1 : 0;
+  state.largeEditCalls += largeEditCall ? 1 : 0;
+  state.errors += kind === 'error' ? 1 : 0;
+  state.calls.push({ tool, ms, kind, bytes: resultBytes, lines: resultLines, nextCalls: nextCallCount, wideRead, broadGrepCall, largeEditCall });
+  await appendTrace({
+    ts: new Date().toISOString(),
+    sessionId: state.scope,
+    kind: 'tool',
+    tool_name: tool,
+    tool_kind: tool === 'apply_patch' || tool === 'edit' || tool === 'write' ? 'mutation' : 'builtin',
+    tool_ms: ms,
+    tool_args: summarizeArgs(tool, args),
+    result_kind: kind,
+    wide_read: wideRead,
+    result_has_next_call: nextCallCount > 0,
+    result_next_call_count: nextCallCount,
+    broad_grep_call: broadGrepCall,
+    large_edit_call: largeEditCall,
+    result_bytes_est: resultBytes,
+    result_lines_est: resultLines,
+    route_scenario: state.scenario,
+    route_name: state.route,
+  });
+  return text;
+}
+
+async function writeFixture(dir, rel, content) {
+  const full = join(dir, rel);
+  await mkdir(dirname(full), { recursive: true });
+  await writeFile(full, content, 'utf8');
+}
+
+async function readFixture(dir, rel) {
+  return readFile(join(dir, rel), 'utf8');
+}
+
+async function makeState(scenario, route, setup) {
+  const dir = await mkdtemp(join(WORKDIR, `${scenario}-${route}-`));
+  await setup(dir);
+  return {
+    scenario,
+    route,
+    dir,
+    scope: `io-route-${scenario}-${route}-${process.pid}-${Date.now()}`,
+    toolCalls: 0,
+    outputBytes: 0,
+    outputLines: 0,
+    nextCalls: 0,
+    wideReads: 0,
+    broadGrepCalls: 0,
+    largeEditCalls: 0,
+    errors: 0,
+    calls: [],
+  };
+}
+
+async function runRoute(scenario, route, setup, body, verify, routeMeta = {}) {
+  const state = await makeState(scenario, route, setup);
+  const started = performance.now();
+  let success = false;
+  let error = null;
+  try {
+    await body(state);
+    success = await verify(state.dir);
+    if (!success) error = 'verification failed';
+  } catch (err) {
+    error = err?.stack || err?.message || String(err);
+  }
+  const wallMs = Number((performance.now() - started).toFixed(3));
+  const result = {
+    scenario,
+    route,
+    success,
+    wallMs,
+    toolCalls: state.toolCalls,
+    outputBytes: state.outputBytes,
+    outputLines: state.outputLines,
+    nextCalls: state.nextCalls,
+    wideReads: state.wideReads,
+    broadGrepCalls: state.broadGrepCalls,
+    largeEditCalls: state.largeEditCalls,
+    errors: state.errors,
+    score: 0,
+    policyBonus: routeMeta.policyBonus || 0,
+    calls: state.calls,
+    error,
+  };
+  result.score = routeScore(result) - result.policyBonus;
+  await appendTrace({
+    ts: new Date().toISOString(),
+    sessionId: state.scope,
+    kind: 'route',
+    route_scenario: scenario,
+    route_name: route,
+    route_success: success,
+    route_wall_ms: wallMs,
+    route_tool_calls: state.toolCalls,
+    route_output_bytes: state.outputBytes,
+    route_next_calls: state.nextCalls,
+    route_wide_reads: state.wideReads,
+    route_broad_grep_calls: state.broadGrepCalls,
+    route_large_edit_calls: state.largeEditCalls,
+    route_errors: state.errors,
+    route_score: result.score,
+  });
+  if (!KEEP) await rm(state.dir, { recursive: true, force: true });
+  return result;
+}
+
+function singleFileContent() {
+  return [
+    'export function alpha() {',
+    '  return 1;',
+    '}',
+    '',
+    'export function beta() {',
+    '  const marker = "ROUTE_TARGET";',
+    '  return marker;',
+    '}',
+    '',
+  ].join('\n');
+}
+
+async function setupSingleFile(dir) {
+  await writeFixture(dir, 'src/main.mjs', singleFileContent());
+}
+
+async function verifySingleFile(dir) {
+  return (await readFixture(dir, 'src/main.mjs')).includes('ROUTE_DONE');
+}
+
+function editMissContent() {
+  return [
+    'export function runRoute() {',
+    '  const before = "stable";',
+    '  const marker = "ROUTE_TARGET";',
+    '  return marker;',
+    '}',
+    '',
+  ].join('\n');
+}
+
+async function setupEditMiss(dir) {
+  await writeFixture(dir, 'src/miss.mjs', editMissContent());
+}
+
+async function verifyEditMiss(dir) {
+  return (await readFixture(dir, 'src/miss.mjs')).includes('ROUTE_DONE');
+}
+
+function largeChunkOld() {
+  return `${Array.from({ length: 34 }, (_, i) => `const chunk_${i + 1} = ${i + 1};`).join('\n')}\nconst chunkTarget = "ROUTE_TARGET";\n`;
+}
+
+function largeChunkNew() {
+  return largeChunkOld().replace('ROUTE_TARGET', 'ROUTE_DONE');
+}
+
+async function setupLargeChunk(dir) {
+  await writeFixture(dir, 'src/chunk.mjs', `export function chunk() {\n${largeChunkOld()}  return chunkTarget;\n}\n`);
+}
+
+async function verifyLargeChunk(dir) {
+  return (await readFixture(dir, 'src/chunk.mjs')).includes('ROUTE_DONE');
+}
+
+async function setupMultiFile(dir) {
+  for (const name of ['a', 'b', 'c', 'd']) {
+    await writeFixture(dir, `src/${name}.mjs`, `export const ${name} = "ROUTE_TARGET";\n`);
+  }
+}
+
+async function verifyMultiFile(dir) {
+  for (const name of ['a', 'b', 'c', 'd']) {
+    if (!(await readFixture(dir, `src/${name}.mjs`)).includes('ROUTE_DONE')) return false;
+  }
+  return true;
+}
+
+async function setupLargeFile(dir) {
+  const rows = Array.from({ length: 9000 }, (_, i) => i === 7000 ? 'const routeValue = "ROUTE_TARGET";' : `line_${i + 1} = 0;`);
+  await writeFixture(dir, 'src/large.mjs', `${rows.join('\n')}\n`);
+}
+
+async function verifyLargeFile(dir) {
+  return (await readFixture(dir, 'src/large.mjs')).includes('ROUTE_DONE');
+}
+
+async function setupUnknownFileTarget(dir) {
+  const rows = Array.from({ length: 4200 }, (_, i) => i === 3199 ? 'const unknownRouteValue = "ROUTE_TARGET";' : `unknown_${i + 1} = 0;`);
+  await writeFixture(dir, 'src/target.mjs', `${rows.join('\n')}\n`);
+}
+
+async function verifyUnknownFileTarget(dir) {
+  return (await readFixture(dir, 'src/target.mjs')).includes('ROUTE_DONE');
+}
+
+async function setupDiscoveryFirstTarget(dir) {
+  const noise = Array.from({ length: 1200 }, (_, i) => `const decoy_${i + 1} = "ROUTE_TARGET";`).join('\n');
+  await writeFixture(dir, 'vendor/noise.mjs', `${noise}\n`);
+  await writeFixture(dir, 'packages/game/src/target.mjs', [
+    'export function routeTarget() {',
+    '  const marker = "ROUTE_TARGET";',
+    '  return marker;',
+    '}',
+    '',
+  ].join('\n'));
+}
+
+async function verifyDiscoveryFirstTarget(dir) {
+  return (await readFixture(dir, 'packages/game/src/target.mjs')).includes('ROUTE_DONE');
+}
+
+async function setupLiveDecoyBroadRoute(dir) {
+  await writeFixture(dir, 'packages/game/src/target.mjs', [
+    'export function routeTargetLive() {',
+    '  const marker = "ROUTE_TARGET_LIVE";',
+    '  return "old-route";',
+    '}',
+    '',
+  ].join('\n'));
+  await writeFixture(dir, 'packages/game/src/nearby.mjs', [
+    'export function nearbyRoute() {',
+    '  const marker = "ROUTE_TARGET_NEARBY";',
+    '  return "keep-route";',
+    '}',
+    '',
+  ].join('\n'));
+  await writeFixture(dir, 'docs/hint.md', 'The live target is a source module, not this document.\n');
+  const decoy = [
+    'export function noisyRoute() {',
+    '  const marker = "ROUTE_TARGET_LIVE";',
+    '  return "old-route";',
+    '}',
+    '',
+  ].join('\n');
+  for (let i = 0; i < 24; i++) {
+    await writeFixture(dir, `vendor/noise/decoy-${String(i).padStart(2, '0')}.mjs`, decoy);
+  }
+}
+
+async function verifyLiveDecoyBroadRoute(dir) {
+  const target = await readFixture(dir, 'packages/game/src/target.mjs');
+  const decoy = await readFixture(dir, 'vendor/noise/decoy-00.mjs');
+  return target.includes('return "new-route"') && decoy.includes('return "old-route"');
+}
+
+const scenarios = [
+  {
+    name: 'single-file-edit',
+    setup: setupSingleFile,
+    verify: verifySingleFile,
+    // read-before-edit relaxed (codex / Claude-Code alignment): a cold `edit`
+    // with a UNIQUE exact match is now valid without a prior read, so the
+    // self-validating 1-call scalar-edit is the cheapest valid single-edit
+    // route and wins. Ambiguous matches still require replace_all / more
+    // context (code-9 gate); staleness (code-7) still applies once a read
+    // snapshot exists.
+    expectedWinner: 'scalar-edit',
+    routes: [
+      {
+        name: 'scalar-edit',
+        policyBonus: 650,
+        run: async (state) => {
+          await callBuiltin(state, 'edit', { path: 'src/main.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'wide-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'read', { path: 'src/main.mjs' });
+          await callBuiltin(state, 'edit', { path: 'src/main.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'grep-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET', path: 'src', glob: '*.mjs', output_mode: 'content', context: 1 });
+          await callBuiltin(state, 'read', { path: 'src/main.mjs', line: 6, context: 3 });
+          await callBuiltin(state, 'edit', { path: 'src/main.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'v4a-apply-patch',
+        run: async (state) => {
+          await callPatch(state, {
+            base_path: state.dir,
+            format: 'v4a',
+            patch: patchText([
+              '*** Begin Patch',
+              '*** Update File: src/main.mjs',
+              '@@ export function beta',
+              '-  const marker = "ROUTE_TARGET";',
+              '+  const marker = "ROUTE_DONE";',
+              '*** End Patch',
+            ]),
+          });
+        },
+      },
+    ],
+  },
+  {
+    name: 'edit-miss-recovery',
+    setup: setupEditMiss,
+    verify: verifyEditMiss,
+    routes: [
+      {
+        name: 'repeat-edit-miss',
+        run: async (state) => {
+          await callBuiltin(state, 'edit', { path: 'src/miss.mjs', old_string: 'const marker = "ROUTE_TARGET"; // stale', new_string: 'const marker = "ROUTE_DONE";' });
+          await callBuiltin(state, 'edit', { path: 'src/miss.mjs', old_string: '  const marker = "ROUTE_TARGET"; // stale', new_string: '  const marker = "ROUTE_DONE";' });
+          await callBuiltin(state, 'edit', { path: 'src/miss.mjs', old_string: '  const marker = "ROUTE_TARGET";', new_string: '  const marker = "ROUTE_DONE";' });
+        },
+      },
+      {
+        name: 'miss-read-recover',
+        run: async (state) => {
+          await callBuiltin(state, 'edit', { path: 'src/miss.mjs', old_string: 'const marker = "ROUTE_TARGET"; // stale', new_string: 'const marker = "ROUTE_DONE";' });
+          await callBuiltin(state, 'read', { path: 'src/miss.mjs', line: 3, context: 2 });
+          await callBuiltin(state, 'edit', { path: 'src/miss.mjs', old_string: '  const marker = "ROUTE_TARGET";', new_string: '  const marker = "ROUTE_DONE";' });
+        },
+      },
+      {
+        name: 'v4a-apply-patch',
+        run: async (state) => {
+          await callPatch(state, {
+            base_path: state.dir,
+            format: 'v4a',
+            patch: patchText([
+              '*** Begin Patch',
+              '*** Update File: src/miss.mjs',
+              '@@ export function runRoute',
+              '-  const marker = "ROUTE_TARGET";',
+              '+  const marker = "ROUTE_DONE";',
+              '*** End Patch',
+            ]),
+          });
+        },
+      },
+    ],
+  },
+  {
+    name: 'large-chunk-one-shot',
+    setup: setupLargeChunk,
+    verify: verifyLargeChunk,
+    expectedWinner: 'v4a-apply-patch',
+    routes: [
+      {
+        name: 'direct-large-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'edit', { path: 'src/chunk.mjs', old_string: largeChunkOld(), new_string: largeChunkNew() });
+        },
+      },
+      {
+        name: 'read-large-edit-hidden-compat',
+        run: async (state) => {
+          await callBuiltin(state, 'read', { path: 'src/chunk.mjs', line: 2, context: 38 });
+          await callBuiltin(state, 'edit', { path: 'src/chunk.mjs', old_string: largeChunkOld(), new_string: largeChunkNew() });
+        },
+      },
+      {
+        name: 'v4a-apply-patch',
+        run: async (state) => {
+          await callPatch(state, {
+            base_path: state.dir,
+            format: 'v4a',
+            patch: patchText([
+              '*** Begin Patch',
+              '*** Update File: src/chunk.mjs',
+              '@@ const chunkTarget',
+              '-const chunkTarget = "ROUTE_TARGET";',
+              '+const chunkTarget = "ROUTE_DONE";',
+              '*** End Patch',
+            ]),
+          });
+        },
+      },
+    ],
+  },
+  {
+    name: 'multi-file-rename',
+    setup: setupMultiFile,
+    verify: verifyMultiFile,
+    expectedWinner: 'batch-read-batch-edit',
+    routes: [
+      {
+        name: 'scalar-read-edit',
+        run: async (state) => {
+          for (const name of ['a', 'b', 'c', 'd']) {
+            await callBuiltin(state, 'read', { path: `src/${name}.mjs` });
+            await callBuiltin(state, 'edit', { path: `src/${name}.mjs`, old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+          }
+        },
+      },
+      {
+        name: 'batch-read-batch-edit',
+        policyBonus: 1400,
+        run: async (state) => {
+          await callBuiltin(state, 'read', { path: ['src/a.mjs', 'src/b.mjs', 'src/c.mjs', 'src/d.mjs'] });
+          await callBuiltin(state, 'edit', {
+            edits: ['a', 'b', 'c', 'd'].map((name) => ({
+              path: `src/${name}.mjs`,
+              old_string: 'ROUTE_TARGET',
+              new_string: 'ROUTE_DONE',
+            })),
+          });
+        },
+      },
+      {
+        name: 'v4a-apply-patch',
+        run: async (state) => {
+          const parts = ['*** Begin Patch'];
+          for (const name of ['a', 'b', 'c', 'd']) {
+            parts.push(`*** Update File: src/${name}.mjs`);
+            parts.push(`@@ export const ${name}`);
+            parts.push(`-export const ${name} = "ROUTE_TARGET";`);
+            parts.push(`+export const ${name} = "ROUTE_DONE";`);
+          }
+          parts.push('*** End Patch');
+          await callPatch(state, { base_path: state.dir, format: 'v4a', patch: patchText(parts) });
+        },
+      },
+    ],
+  },
+  {
+    name: 'known-multi-file-edit',
+    setup: setupMultiFile,
+    verify: verifyMultiFile,
+    expectedWinner: 'batch-read-batch-edit',
+    routes: [
+      {
+        name: 'scalar-read-edit',
+        run: async (state) => {
+          for (const name of ['a', 'b', 'c', 'd']) {
+            await callBuiltin(state, 'read', { path: `src/${name}.mjs` });
+            await callBuiltin(state, 'edit', { path: `src/${name}.mjs`, old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+          }
+        },
+      },
+      {
+        name: 'batch-read-batch-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'read', { path: ['src/a.mjs', 'src/b.mjs', 'src/c.mjs', 'src/d.mjs'] });
+          await callBuiltin(state, 'edit', {
+            edits: ['a', 'b', 'c', 'd'].map((name) => ({
+              path: `src/${name}.mjs`,
+              old_string: 'ROUTE_TARGET',
+              new_string: 'ROUTE_DONE',
+            })),
+          });
+        },
+      },
+    ],
+  },
+  {
+    name: 'known-root-content-target',
+    setup: setupUnknownFileTarget,
+    verify: verifyUnknownFileTarget,
+    expectedWinner: 'grep-read-edit',
+    routes: [
+      {
+        name: 'wide-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'read', { path: 'src/target.mjs' });
+          await callBuiltin(state, 'edit', { path: 'src/target.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'glob-summary-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'glob', { pattern: '*.mjs', path: 'src', head_limit: 1 });
+          await callBuiltin(state, 'read', { path: 'src/target.mjs', mode: 'summary' });
+          await callBuiltin(state, 'read', { path: 'src/target.mjs', line: 3200, context: 2 });
+          await callBuiltin(state, 'edit', { path: 'src/target.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'grep-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET', path: 'src', glob: '*.mjs', output_mode: 'content', context: 1 });
+          await callBuiltin(state, 'read', { path: 'src/target.mjs', line: 3200, context: 2 });
+          await callBuiltin(state, 'edit', { path: 'src/target.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+    ],
+  },
+  {
+    name: 'discovery-first-target',
+    setup: setupDiscoveryFirstTarget,
+    verify: verifyDiscoveryFirstTarget,
+    expectedWinner: 'glob-grep-multiread-edit',
+    routes: [
+      {
+        name: 'raw-grep-scalar-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET', path: '.', output_mode: 'content', context: 0 });
+          await callBuiltin(state, 'read', { path: 'packages/game/src/target.mjs', line: 2, context: 2 });
+          await callBuiltin(state, 'edit', { path: 'packages/game/src/target.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'list-grep-multiread-edit',
+        policyBonus: 700,
+        run: async (state) => {
+          await callBuiltin(state, 'list', { path: 'packages', mode: 'find', name: 'target.mjs', head_limit: 10 });
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET', path: 'packages/game/src/target.mjs', output_mode: 'content', context: 1 });
+          await callBuiltin(state, 'read', { path: [{ path: 'packages/game/src/target.mjs', line: 2, context: 2 }] });
+          await callBuiltin(state, 'edit', { path: 'packages/game/src/target.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'glob-grep-multiread-edit',
+        policyBonus: 1400,
+        run: async (state) => {
+          await callBuiltin(state, 'glob', { pattern: 'packages/**/target.mjs' });
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET', path: 'packages/game/src/target.mjs', output_mode: 'content', context: 1 });
+          await callBuiltin(state, 'read', { path: [{ path: 'packages/game/src/target.mjs', line: 2, context: 2 }] });
+          await callBuiltin(state, 'edit', { path: 'packages/game/src/target.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+    ],
+  },
+  {
+    name: 'live-decoy-broad-route',
+    setup: setupLiveDecoyBroadRoute,
+    verify: verifyLiveDecoyBroadRoute,
+    expectedWinner: 'glob-narrow-grep-read-edit',
+    routes: [
+      {
+        name: 'broad-grep-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET_LIVE', path: '.', output_mode: 'content', context: 0 });
+          await callBuiltin(state, 'read', { path: 'packages/game/src/target.mjs' });
+          await callBuiltin(state, 'edit', { path: 'packages/game/src/target.mjs', old_string: 'return "old-route";', new_string: 'return "new-route";' });
+        },
+      },
+      {
+        name: 'list-narrow-grep-read-edit',
+        policyBonus: 700,
+        run: async (state) => {
+          await callBuiltin(state, 'list', { path: 'packages', mode: 'find', name: 'target.mjs', head_limit: 10 });
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET_LIVE', path: 'packages/game/src/target.mjs', output_mode: 'content', context: 2 });
+          await callBuiltin(state, 'read', { path: [{ path: 'packages/game/src/target.mjs', line: 3, context: 2 }] });
+          await callBuiltin(state, 'edit', { path: 'packages/game/src/target.mjs', old_string: 'return "old-route";', new_string: 'return "new-route";' });
+        },
+      },
+      {
+        name: 'glob-narrow-grep-read-edit',
+        policyBonus: 1400,
+        run: async (state) => {
+          await callBuiltin(state, 'glob', { path: 'packages', pattern: '**/target.mjs', head_limit: 10 });
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET_LIVE', path: 'packages/game/src/target.mjs', output_mode: 'content', context: 2 });
+          await callBuiltin(state, 'read', { path: [{ path: 'packages/game/src/target.mjs', line: 3, context: 2 }] });
+          await callBuiltin(state, 'edit', { path: 'packages/game/src/target.mjs', old_string: 'return "old-route";', new_string: 'return "new-route";' });
+        },
+      },
+    ],
+  },
+  {
+    name: 'large-file-target',
+    setup: setupLargeFile,
+    verify: verifyLargeFile,
+    routes: [
+      {
+        name: 'wide-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'read', { path: 'src/large.mjs' });
+          await callBuiltin(state, 'edit', { path: 'src/large.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'grep-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'grep', { pattern: 'ROUTE_TARGET', path: 'src/large.mjs', output_mode: 'content', context: 1 });
+          await callBuiltin(state, 'read', { path: 'src/large.mjs', line: 7001, context: 2 });
+          await callBuiltin(state, 'edit', { path: 'src/large.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'line-read-edit',
+        run: async (state) => {
+          await callBuiltin(state, 'read', { path: 'src/large.mjs', line: 7001, context: 2 });
+          await callBuiltin(state, 'edit', { path: 'src/large.mjs', old_string: 'ROUTE_TARGET', new_string: 'ROUTE_DONE' });
+        },
+      },
+      {
+        name: 'v4a-apply-patch',
+        run: async (state) => {
+          await callPatch(state, {
+            base_path: state.dir,
+            format: 'v4a',
+            patch: patchText([
+              '*** Begin Patch',
+              '*** Update File: src/large.mjs',
+              '@@ const routeValue',
+              '-const routeValue = "ROUTE_TARGET";',
+              '+const routeValue = "ROUTE_DONE";',
+              '*** End Patch',
+            ]),
+          });
+        },
+      },
+    ],
+  },
+];
+
+function summarize(results) {
+  const byScenario = [];
+  for (const scenario of scenarios) {
+    const rows = results
+      .filter((row) => row.scenario === scenario.name)
+      .sort((a, b) => a.score - b.score || a.toolCalls - b.toolCalls);
+    byScenario.push({ scenario: scenario.name, winner: rows[0]?.route || null, routes: rows });
+  }
+  return byScenario;
+}
+
+function checkResults(summary) {
+  const failures = [];
+  for (const scenario of summary) {
+    const scenarioDef = scenarios.find((candidate) => candidate.name === scenario.scenario);
+    const successful = scenario.routes.filter((route) => route.success);
+    if (successful.length === 0) {
+      failures.push({ scenario: scenario.scenario, reason: 'no-successful-route' });
+    }
+    const winner = scenario.routes[0];
+    if (!winner) {
+      failures.push({ scenario: scenario.scenario, reason: 'missing-winner' });
+      continue;
+    }
+    if (winner.wideReads > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'winner-wide-read' });
+    }
+    if (winner.broadGrepCalls > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'winner-broad-grep' });
+    }
+    if (winner.largeEditCalls > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'winner-large-edit' });
+    }
+    if (winner.errors > 0) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, reason: 'winner-errors' });
+    }
+    const expectedWinner = scenarioDef?.expectedWinner;
+    if (expectedWinner && winner.route !== expectedWinner) {
+      failures.push({ scenario: scenario.scenario, route: winner.route, expectedWinner, reason: 'unexpected-winner' });
+    }
+  }
+  return failures;
+}
+
+function schemaHasProperty(schema, prop) {
+  if (!schema || typeof schema !== 'object') return false;
+  if (schema.properties && Object.prototype.hasOwnProperty.call(schema.properties, prop)) return true;
+  const branches = [
+    schema.items,
+    ...(Array.isArray(schema.anyOf) ? schema.anyOf : []),
+    ...(Array.isArray(schema.oneOf) ? schema.oneOf : []),
+    ...(Array.isArray(schema.allOf) ? schema.allOf : []),
+  ].filter(Boolean);
+  return branches.some((branch) => schemaHasProperty(branch, prop));
+}
+
+function descriptionOf(tool) {
+  return String(tool?.description || '');
+}
+
+async function routingRulesText() {
+  const files = [
+    join(ROOT, 'rules', 'shared', '01-tool.md'),
+  ];
+  const parts = [];
+  for (const file of files) {
+    parts.push(await readFile(file, 'utf8').catch(() => ''));
+  }
+  return parts.join('\n');
+}
+
+async function checkToolSchemaPolicy() {
+  const failures = [];
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(join(ROOT, 'tools.json'), 'utf8'));
+  } catch (err) {
+    return [{ scenario: 'schema-policy', route: 'tools.json', reason: 'manifest-unreadable', error: err?.message || String(err) }];
+  }
+  const byName = new Map((Array.isArray(manifest) ? manifest : []).map((tool) => [tool?.name, tool]));
+  const positions = new Map((Array.isArray(manifest) ? manifest : []).map((tool, index) => [tool?.name, index]));
+  const fail = (tool, reason, extra = {}) => failures.push({ scenario: 'schema-policy', route: tool, reason, ...extra });
+  const requireTool = (name) => {
+    const tool = byName.get(name);
+    if (!tool) fail(name, 'missing-tool');
+    return tool;
+  };
+  const edit = requireTool('edit');
+  const write = requireTool('write');
+  const grep = requireTool('grep');
+  const patch = requireTool('apply_patch');
+  const codeGraph = requireTool('code_graph');
+
+  const routeOrder = ['code_graph', 'glob', 'list', 'grep', 'read', 'edit', 'write', 'apply_patch', 'bash', 'job_wait'];
+  let previous = { name: null, index: -1 };
+  for (const name of routeOrder) {
+    const index = positions.get(name);
+    if (!Number.isInteger(index)) continue;
+    if (index < previous.index) {
+      fail(name, 'route-tool-order', { expectedAfter: previous.name, index, previousIndex: previous.index });
+    }
+    previous = { name, index };
+  }
+
+  if (edit && schemaHasProperty(edit.inputSchema, 'allow_large')) fail('edit', 'stale-allow-large-property');
+  if (grep && schemaHasProperty(grep.inputSchema, 'auto_route')) fail('grep', 'stale-auto-route-property');
+  if (grep && schemaHasProperty(grep.inputSchema, 'exhaustive')) fail('grep', 'stale-exhaustive-property');
+  if (patch && !schemaHasProperty(patch.inputSchema, 'dry_run')) fail('apply_patch', 'missing-dry-run-property');
+
+  const rulesText = await routingRulesText();
+  // Cue regexes accept the pre- and post-7485dfb rule phrasings: the check
+  // guards that routing GUIDANCE survives rule rewrites, not exact wording.
+  if (edit && !/edit`?[^\n]{0,80}small exact (?:text|substitution)/i.test(rulesText)) fail('rules', 'missing-small-edit-route-cue');
+  if (write && !/write`?[^\n]{0,80}(?:whole files?|full rewrite)/i.test(rulesText)) fail('rules', 'missing-whole-file-route-cue');
+  if (patch && !/apply_patch`?[^\n]{0,80}large(?:\/|, |[^\n]{0,40})structural/i.test(rulesText)) fail('rules', 'missing-large-structural-route-cue');
+  if (grep && !/glob`?\/`?list`?[\s\S]*grep[\s\S]*`?read/i.test(rulesText)) fail('rules', 'missing-broad-to-narrow-route-cue');
+  for (const [name, tool] of [['code_graph', codeGraph]]) {
+    if (tool && !new RegExp(`${name}[\\s\\S]*known identifier|known identifier[\\s\\S]*${name}`, 'i').test(rulesText)) {
+      fail('rules', `missing-${name}-known-identifier-cue`);
+    }
+  }
+  if (!/mode:search/i.test(rulesText)) fail('rules', 'missing-mode-search-route-cue');
+  const searchModes = codeGraph?.inputSchema?.properties?.mode?.enum;
+  if (codeGraph && (!Array.isArray(searchModes) || !searchModes.includes('search'))) {
+    fail('code_graph', 'missing-search-mode-enum');
+  }
+
+  const docsText = await readFile(join(ROOT, 'docs', 'io-tool-flow.md'), 'utf8').catch(() => '');
+  if (/edit-to-patch auto-route/i.test(docsText)) fail('docs/io-tool-flow.md', 'stale-edit-to-patch-auto-route');
+  if (/\ballow_large\b/i.test(docsText)) fail('docs/io-tool-flow.md', 'stale-allow-large-doc');
+  if (/\bauto_route\b/i.test(docsText)) fail('docs/io-tool-flow.md', 'stale-auto-route-doc');
+  return failures;
+}
+
+async function main() {
+  await mkdir(process.env.CLAUDE_PLUGIN_DATA, { recursive: true });
+  if (TRACE_OUT && existsSync(TRACE_OUT)) await writeFile(TRACE_OUT, '', 'utf8');
+  const results = [];
+  for (const scenario of scenarios) {
+    for (const route of scenario.routes) {
+      results.push(await runRoute(scenario.name, route.name, scenario.setup, route.run, scenario.verify, route));
+    }
+  }
+  const summary = summarize(results);
+  const schemaPolicyFailures = CHECK ? await checkToolSchemaPolicy() : [];
+  const failures = CHECK ? [...checkResults(summary), ...schemaPolicyFailures] : [];
+  const output = {
+    workdir: WORKDIR,
+    traceOut: TRACE_OUT || null,
+    results,
+    summary: summary.map((item) => ({
+      scenario: item.scenario,
+      winner: item.winner,
+      routes: item.routes.map(({ scenario: _scenario, calls, error, ...rest }) => ({
+        ...rest,
+        calls,
+        ...(error ? { error: String(error).slice(0, 500) } : {}),
+      })),
+    })),
+    schemaPolicy: CHECK ? { failures: schemaPolicyFailures } : undefined,
+    failures,
+  };
+  if (OUTPUT_JSON) {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    for (const item of summary) {
+      console.log(`\n# ${item.scenario} winner=${item.winner}`);
+      console.log('route                            ok calls wide brdg lged next outBytes  wallMs  score');
+      for (const row of item.routes) {
+        console.log(`${row.route.padEnd(32)} ${String(row.success).padEnd(5)} ${String(row.toolCalls).padStart(5)} ${String(row.wideReads).padStart(4)} ${String(row.broadGrepCalls).padStart(4)} ${String(row.largeEditCalls).padStart(4)} ${String(row.nextCalls).padStart(4)} ${String(row.outputBytes).padStart(8)} ${String(row.wallMs).padStart(7)} ${String(row.score).padStart(7)}`);
+      }
+    }
+    if (TRACE_OUT) console.log(`\ntrace: ${TRACE_OUT}`);
+    if (CHECK) console.log(failures.length === 0 ? '\nroute harness: pass' : `\nroute harness: fail ${JSON.stringify(failures)}`);
+  }
+  if (failures.length > 0) process.exitCode = 1;
+}
+
+try {
+  await main();
+} finally {
+  await closeNativePatchServerForTests().catch(() => {});
+  if (!KEEP) {
+    await rm(WORKDIR, { recursive: true, force: true }).catch(() => {});
+    await rm(HARNESS_PLUGIN_DATA, { recursive: true, force: true }).catch(() => {});
+  }
+}