mixdog 0.9.172 → 0.9.174

package/scripts/lib/cli-args.mjs

@@ -0,0 +1,43 @@
+// Argv reading shared by the scripts/ CLIs (bench, diag and smoke runners).
+// `--name value` and `--name=value` are equivalent; a missing option yields
+// the caller's fallback. `argv` is a seam for tests only — callers keep
+// reading the live process arguments.
+export function argValue(name, fallback = null, argv = process.argv) {
+  const index = argv.indexOf(name);
+  if (index >= 0 && index + 1 < argv.length) return argv[index + 1];
+  const prefix = `${name}=`;
+  const hit = argv.find((arg) => arg.startsWith(prefix));
+  return hit ? hit.slice(prefix.length) : fallback;
+}
+
+export function hasFlag(name, argv = process.argv) {
+  return argv.includes(name);
+}
+
+// The non-flag entries of `argv` (user arguments only, e.g.
+// process.argv.slice(2)). A bare `--name` consumes the next entry as its
+// value unless it is in `booleanFlags`; `--name=value` consumes nothing.
+export function positionalArgs(argv, booleanFlags) {
+  return argv.filter((arg, index) => {
+    if (arg.startsWith('--')) return false;
+    const prev = index > 0 ? argv[index - 1] : '';
+    return !(prev.startsWith('--') && !prev.includes('=') && !booleanFlags.has(prev));
+  });
+}
+
+// A numeric option that keeps a deliberate 0 (or negative): only a missing,
+// blank or non-numeric value takes the fallback.
+export function numArg(name, fallback, argv = process.argv) {
+  const raw = argValue(name, null, argv);
+  if (raw == null || raw.trim() === '') return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+// A positive-integer option: a missing, non-numeric or non-positive value
+// keeps the fallback, so a typo degrades to the documented default instead of
+// silently running with NaN.
+export function intArg(name, fallback, argv = process.argv) {
+  const parsed = Number.parseInt(argValue(name, String(fallback), argv), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}

package/scripts/lib/cli-args.test.mjs

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { argValue, hasFlag, intArg, numArg, positionalArgs } from './cli-args.mjs';
+
+test('argValue reads both the separated and the joined option form', () => {
+  const argv = ['node', 'bench.mjs', '--model', 'opus', '--round=3', '--trailing'];
+  assert.equal(argValue('--model', null, argv), 'opus');
+  assert.equal(argValue('--round', null, argv), '3');
+  assert.equal(argValue('--missing', null, argv), null);
+  assert.equal(argValue('--missing', 'fallback', argv), 'fallback');
+  // An explicit `undefined` fallback takes the parameter default, so a
+  // missing option always reads as null rather than undefined.
+  assert.equal(argValue('--missing', undefined, argv), null);
+});
+
+test('argValue falls back when the separated form has no value left', () => {
+  assert.equal(argValue('--save', 'default', ['node', 'bench.mjs', '--save']), 'default');
+  // An empty joined value is a value, not a missing option.
+  assert.equal(argValue('--save', 'default', ['node', 'bench.mjs', '--save=']), '');
+  // The next argument is taken verbatim, even when it looks like a flag.
+  assert.equal(argValue('--save', null, ['node', 'bench.mjs', '--save', '--json']), '--json');
+});
+
+test('hasFlag reports presence only', () => {
+  const argv = ['node', 'bench.mjs', '--json', '--limit=5'];
+  assert.equal(hasFlag('--json', argv), true);
+  assert.equal(hasFlag('--limit', argv), false);
+  assert.equal(hasFlag('--quiet', argv), false);
+});
+
+test('intArg accepts positive integers and keeps the fallback otherwise', () => {
+  assert.equal(intArg('--limit', 30, ['node', 'diag.mjs', '--limit', '5']), 5);
+  assert.equal(intArg('--limit', 30, ['node', 'diag.mjs', '--limit=12']), 12);
+  assert.equal(intArg('--limit', 30, ['node', 'diag.mjs']), 30);
+  assert.equal(intArg('--limit', 30, ['node', 'diag.mjs', '--limit', 'abc']), 30);
+  assert.equal(intArg('--limit', 30, ['node', 'diag.mjs', '--limit', '0']), 30);
+  assert.equal(intArg('--limit', 30, ['node', 'diag.mjs', '--limit', '-4']), 30);
+  // parseInt stops at the first non-digit, as the CLIs have always accepted.
+  assert.equal(intArg('--limit', 30, ['node', 'diag.mjs', '--limit', '7x']), 7);
+});
+
+test('numArg keeps a deliberate 0 and falls back only on missing or non-numeric values', () => {
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs', '--budget', '0']), 0);
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs', '--budget=0']), 0);
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs', '--budget', '2500']), 2500);
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs', '--budget', '0.5']), 0.5);
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs']), 16000);
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs', '--budget=']), 16000);
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs', '--budget', 'lots']), 16000);
+  assert.equal(numArg('--budget', 16000, ['node', 'bench.mjs', '--budget']), 16000);
+});
+
+test('positionalArgs never lets a boolean flag or a joined value swallow a positional', () => {
+  const booleans = new Set(['--render']);
+  assert.deepEqual(positionalArgs(['--render', 'deck.js', 'deck.pptx', '--mode', 'auto'], booleans), [
+    'deck.js',
+    'deck.pptx',
+  ]);
+  assert.deepEqual(positionalArgs(['--mode=auto', 'deck.js', 'deck.pptx'], booleans), ['deck.js', 'deck.pptx']);
+  assert.deepEqual(positionalArgs(['deck.js', '--out', 'result.json', 'deck.pptx', '--render'], booleans), [
+    'deck.js',
+    'deck.pptx',
+  ]);
+});

package/scripts/lib/coverage.mjs

@@ -0,0 +1,309 @@
+// V8 coverage, folded into the one artifact that answers a single question:
+// does the suite actually execute this function? Grepping test files for a
+// symbol answers it wrongly whenever a helper is reached only through a public
+// entry point, so the evidence comes from Node itself — NODE_V8_COVERAGE makes
+// every test process dump raw V8 coverage JSON at exit, and this module folds
+// those dumps (one per batch, one per test child) into per-function lines.
+//
+// No dependency is involved: V8 emits the raw data, `node:fs` reads it back.
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const ARTIFACT_PATH = '.runtime/coverage/coverage.json';
+
+// The runner's own lane patterns: *.test.mjs and *-test.mjs (plus the jsx/ts
+// spellings used by apps/desktop). A test executing itself proves nothing.
+const TEST_FILE = /[.-]test\.[cm]?[jt]sx?$/;
+// tsx transpiles TypeScript before V8 sees it, so the offsets V8 reports for a
+// .ts file describe the transpiled output instead of the file on disk.
+const TYPESCRIPT_FILE = /\.[cm]?tsx?$/;
+
+export const EXCLUSION_REASONS = {
+  'transpiled-by-tsx':
+    'TypeScript executed through tsx: V8 offsets describe the transpiled output, not this file, and this round does not translate them through source maps',
+  'offsets-beyond-source':
+    'recorded offsets run past the file on disk, so the executed source was generated or transformed rather than read from here',
+  'source-unreadable': 'the file could not be read back while folding coverage',
+};
+
+// The identity a later query uses to tell whether the file still is what was
+// measured. Content, not mtime or size: a checkout, a formatter rewriting a
+// file byte-identically or a restored backup all move mtime without changing a
+// single line, and an edit that swaps two lines keeps the size — either way the
+// recorded line ranges would be wrong or wrongly distrusted. Folding already
+// reads every source in full to translate offsets, so hashing it costs nothing
+// and answers exactly. (A file absent from the artifact has no recorded
+// content to compare, so its mtime against the collection time is the only
+// evidence there is; `queryCoverage` uses that for the unknown-file case.)
+export function sourceDigest(source) {
+  return createHash('sha256').update(source).digest('hex');
+}
+
+// Sources are normalized the same way at folding and at query time, so the
+// digest compares like with like.
+async function currentSource(rootPath, path) {
+  try {
+    return (await readFile(join(rootPath, path), 'utf8')).replace(/^\uFEFF/, '');
+  } catch {
+    return null;
+  }
+}
+
+async function modifiedAfter(rootPath, path, generatedAt) {
+  const collected = Date.parse(generatedAt ?? '');
+  if (Number.isNaN(collected)) return false;
+  try {
+    return (await stat(join(rootPath, path))).mtimeMs > collected;
+  } catch {
+    return false;
+  }
+}
+
+function lineStarts(source) {
+  const starts = [0];
+  for (let index = 0; index < source.length; index++) {
+    if (source.charCodeAt(index) === 10) starts.push(index + 1);
+  }
+  return starts;
+}
+
+// 1-based line holding a 0-based character offset.
+function lineOf(starts, offset) {
+  let low = 0;
+  let high = starts.length - 1;
+  while (low < high) {
+    const mid = (low + high + 1) >> 1;
+    if (starts[mid] <= offset) low = mid;
+    else high = mid - 1;
+  }
+  return low + 1;
+}
+
+// V8 keeps the script's own top-level range as a nameless function spanning the
+// whole source. It is the module body, not a function anyone can call, so it
+// becomes the file's `loaded` flag instead of an entry every line sits inside.
+const isModuleBody = (entry, length) => entry.name === '' && entry.startOffset === 0 && entry.endOffset >= length;
+
+function repoRelative(url, rootPath) {
+  if (!url.startsWith('file:')) return '';
+  const parsed = new URL(url);
+  parsed.search = '';
+  parsed.hash = '';
+  const absolute = fileURLToPath(parsed);
+  const path = relative(rootPath, absolute).replaceAll('\\', '/');
+  if (path === '' || path.startsWith('../') || isAbsolute(path)) return '';
+  return path;
+}
+
+// Raw V8 dumps -> { path -> [{ name, startOffset, endOffset, executed }] }.
+// Every dump contributes: a function executed in any batch is executed.
+function collectFunctions(reports, rootPath, excluded) {
+  const byFile = new Map();
+  for (const report of reports) {
+    for (const script of report?.result ?? []) {
+      const path = repoRelative(script.url ?? '', rootPath);
+      if (path === '' || path.split('/').includes('node_modules') || TEST_FILE.test(path)) continue;
+      if (TYPESCRIPT_FILE.test(path)) {
+        excluded.set(path, 'transpiled-by-tsx');
+        continue;
+      }
+      const functions = byFile.get(path) ?? new Map();
+      byFile.set(path, functions);
+      for (const entry of script.functions ?? []) {
+        const range = entry.ranges?.[0];
+        if (!range) continue;
+        const key = `${entry.functionName}\u0000${range.startOffset}\u0000${range.endOffset}`;
+        const merged = functions.get(key);
+        if (merged) merged.executed ||= range.count > 0;
+        else
+          functions.set(key, {
+            name: entry.functionName,
+            startOffset: range.startOffset,
+            endOffset: range.endOffset,
+            executed: range.count > 0,
+          });
+      }
+    }
+  }
+  return byFile;
+}
+
+// The artifact: per repository source file, every function V8 covered, with
+// offsets translated to 1-based lines and the single bit that matters.
+export async function foldCoverage(reports, { root = process.cwd() } = {}) {
+  const rootPath = resolve(root);
+  const excluded = new Map();
+  const collected = collectFunctions(reports, rootPath, excluded);
+  const files = {};
+  for (const path of [...collected.keys()].sort()) {
+    const entries = [...collected.get(path).values()].sort(
+      (left, right) => left.startOffset - right.startOffset || left.endOffset - right.endOffset
+    );
+    let source;
+    try {
+      source = (await readFile(join(rootPath, path), 'utf8')).replace(/^\uFEFF/, '');
+    } catch {
+      excluded.set(path, 'source-unreadable');
+      continue;
+    }
+    if (entries.some((entry) => entry.endOffset > source.length)) {
+      excluded.set(path, 'offsets-beyond-source');
+      continue;
+    }
+    const starts = lineStarts(source);
+    const body = entries.find((entry) => isModuleBody(entry, source.length));
+    files[path] = {
+      loaded: body ? body.executed : entries.some((entry) => entry.executed),
+      sha256: sourceDigest(source),
+      functions: entries
+        .filter((entry) => entry !== body)
+        .map((entry) => ({
+          name: entry.name || '(anonymous)',
+          startLine: lineOf(starts, entry.startOffset),
+          endLine: lineOf(starts, Math.max(entry.startOffset, entry.endOffset - 1)),
+          executed: entry.executed,
+        })),
+    };
+  }
+  const covered = Object.values(files);
+  return {
+    version: 2,
+    generatedAt: new Date().toISOString(),
+    root: rootPath.replaceAll('\\', '/'),
+    summary: {
+      filesWithExecutedFunctions: covered.filter((file) => file.functions.some((fn) => fn.executed)).length,
+      filesWithoutExecutedFunctions: covered.filter((file) => !file.functions.some((fn) => fn.executed)).length,
+      excludedFiles: excluded.size,
+    },
+    files,
+    exclusionReasons: EXCLUSION_REASONS,
+    excluded: [...excluded.keys()].sort().map((path) => ({ path, reason: excluded.get(path) })),
+  };
+}
+
+export async function readRawCoverage(directory) {
+  const names = (await readdir(directory)).filter((name) => name.endsWith('.json')).sort();
+  const reports = [];
+  for (const name of names) reports.push(JSON.parse(await readFile(join(directory, name), 'utf8')));
+  return reports;
+}
+
+export async function writeCoverageArtifact(artifact, { root = process.cwd(), artifactPath = ARTIFACT_PATH } = {}) {
+  const target = resolve(root, artifactPath);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, `${JSON.stringify(artifact, null, 2)}\n`);
+  return target;
+}
+
+export async function loadCoverageArtifact({ root = process.cwd(), artifactPath = ARTIFACT_PATH } = {}) {
+  return JSON.parse(await readFile(resolve(root, artifactPath), 'utf8'));
+}
+
+// Is this line inside a function the suite executed? The innermost enclosing
+// function answers; a line the file's functions do not cover is reported as
+// such rather than borrowed from the module body around it.
+//
+// A recorded answer is only worth giving while the file still is the file that
+// was measured, so every query re-reads the source and compares its digest
+// first: a changed file answers `stale`, never EXECUTED or NOT EXECUTED. An
+// artifact predating this check has no digest to match, which is itself a
+// mismatch, so it announces itself too.
+export async function queryCoverage(artifact, file, line, { root = process.cwd() } = {}) {
+  const rootPath = resolve(root);
+  const path = String(file).replaceAll('\\', '/').replace(/^\.\//, '');
+  const generatedAt = artifact.generatedAt;
+  const entry = artifact.files?.[path];
+  const excluded = artifact.excluded?.find((item) => item.path === path);
+  if (!entry) {
+    if (excluded) return { path, line, status: 'excluded', reason: excluded.reason, generatedAt };
+    // Nothing was recorded for this file, so there is no content to compare
+    // against; a file touched after the collection is the case where a test
+    // was added since, which is exactly how this answer misled a reader.
+    const changed = await modifiedAfter(rootPath, path, generatedAt);
+    return { path, line, status: 'unknown-file', generatedAt, changedSinceCollection: changed };
+  }
+  const source = await currentSource(rootPath, path);
+  if (source === null) return { path, line, status: 'stale', change: 'missing', generatedAt };
+  if (sourceDigest(source) !== entry.sha256) return { path, line, status: 'stale', change: 'modified', generatedAt };
+  const inside = entry.functions.filter((fn) => line >= fn.startLine && line <= fn.endLine);
+  const innermost = inside.reduce(
+    (best, fn) => (best === null || fn.endLine - fn.startLine <= best.endLine - best.startLine ? fn : best),
+    null
+  );
+  if (!innermost) return { path, line, status: 'outside-functions', loaded: entry.loaded, generatedAt };
+  return {
+    path,
+    line,
+    status: innermost.executed ? 'executed' : 'not-executed',
+    loaded: entry.loaded,
+    generatedAt,
+    function: innermost,
+  };
+}
+
+// Every answer a reader must not act on says what to do instead.
+const RECOLLECT = 're-run `node scripts/test.mjs --coverage`';
+
+export function formatCoverageAnswer(result) {
+  const at = `${result.path}:${result.line}`;
+  const collected = result.generatedAt ? `collected ${result.generatedAt}` : 'collected at an unrecorded time';
+  if (result.status === 'stale')
+    return result.change === 'missing'
+      ? `STALE ${at} — the file is gone since coverage was ${collected}, so nothing here can be answered: ${RECOLLECT}`
+      : `STALE ${at} — the file changed since coverage was ${collected}, so its recorded lines no longer describe it: ${RECOLLECT}`;
+  if (result.status === 'excluded')
+    return `EXCLUDED ${at} — not in the artifact: ${EXCLUSION_REASONS[result.reason] ?? result.reason}`;
+  if (result.status === 'unknown-file')
+    return result.changedSinceCollection
+      ? `STALE ${at} — no coverage was recorded for this file and it changed after coverage was ${collected}, so a test may cover it now: ${RECOLLECT}`
+      : `NO COVERAGE ${at} — the run ${collected} recorded no coverage for this file; if a test was added since, ${RECOLLECT}`;
+  if (result.status === 'outside-functions')
+    return `NO FUNCTION ${at} — outside every covered function (module body ${result.loaded ? 'ran' : 'never ran'})`;
+  const where = `${result.function.name} (lines ${result.function.startLine}-${result.function.endLine})`;
+  return result.status === 'executed'
+    ? `EXECUTED ${at} — inside ${where}, which the suite ran`
+    : `NOT EXECUTED ${at} — inside ${where}, which no test ran`;
+}
+
+// The whole-artifact signal: how much of what was measured no longer exists as
+// measured, and when it was measured, so a caller can decide to re-collect
+// before asking anything at all.
+export async function coverageStaleness(artifact, { root = process.cwd() } = {}) {
+  const rootPath = resolve(root);
+  const changed = [];
+  const missing = [];
+  for (const [path, entry] of Object.entries(artifact.files ?? {})) {
+    const source = await currentSource(rootPath, path);
+    if (source === null) missing.push(path);
+    else if (sourceDigest(source) !== entry.sha256) changed.push(path);
+  }
+  return {
+    generatedAt: artifact.generatedAt,
+    files: Object.keys(artifact.files ?? {}).length,
+    changed: changed.sort(),
+    missing: missing.sort(),
+    changedCount: changed.length + missing.length,
+    stale: changed.length + missing.length > 0,
+  };
+}
+
+export function formatStaleness(state) {
+  const collected = state.generatedAt ? `collected ${state.generatedAt}` : 'collected at an unrecorded time';
+  return state.stale
+    ? `STALE coverage ${collected}: ${state.changedCount} of ${state.files} files changed since (${state.missing.length} gone); ${RECOLLECT}`
+    : `FRESH coverage ${collected}: all ${state.files} files unchanged since`;
+}
+
+// Called once per `--coverage` run, after the last batch has exited.
+export async function reportCoverage(rawDirectory, { root = process.cwd(), log = console.error } = {}) {
+  const artifact = await foldCoverage(await readRawCoverage(rawDirectory), { root });
+  const target = await writeCoverageArtifact(artifact, { root });
+  const { filesWithExecutedFunctions, filesWithoutExecutedFunctions, excludedFiles } = artifact.summary;
+  log(
+    `Coverage: ${filesWithExecutedFunctions} files with executed functions, ${filesWithoutExecutedFunctions} without, ${excludedFiles} excluded`
+  );
+  log(`Coverage artifact: ${target}`);
+  return target;
+}

package/scripts/lib/embedding-model-bench-core.mjs

@@ -97,6 +97,8 @@ export function buildEvaluation(caseFile, kase) {
     : [];
   if (typeof query !== 'string' || !query.trim() || targets.length === 0) return null;
   const temporal = parsePeriod(String(kase?.args?.period || ''), true);
+  const startMs = Number(temporal?.startMs);
+  const endMs = Number(temporal?.endMs);
   return {
     id: String(kase.id),
     caseFile,
@@ -114,8 +116,8 @@ export function buildEvaluation(caseFile, kase) {
             .toLowerCase()
         )
         .filter(Boolean),
-      startMs: Number.isFinite(Number(temporal?.startMs)) ? Number(temporal.startMs) : null,
-      endMs: Number.isFinite(Number(temporal?.endMs)) ? Number(temporal.endMs) : null,
+      startMs: Number.isFinite(startMs) ? startMs : null,
+      endMs: Number.isFinite(endMs) ? endMs : null,
     },
   };
 }
@@ -342,10 +344,3 @@ export function aggregateScoredRows(rows) {
   }
   return { overall: aggregate(rows), byLanguage };
 }
-
-export function percentile(values, ratio) {
-  if (!Array.isArray(values) || values.length === 0) return 0;
-  const sorted = [...values].sort((left, right) => left - right);
-  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * ratio) - 1));
-  return sorted[index];
-}

package/scripts/lib/recall-bench-eval.mjs

@@ -184,12 +184,12 @@ export function scoreWithinPeriod(items, temporal, toleranceMs = 60_000) {
   const endMs = Number(temporal?.endMs);
   const hasStart = Number.isFinite(startMs);
   const hasEnd = Number.isFinite(endMs);
-  const offenders = items.filter(
+  const timestamped = items.filter((item) => item.timestampMs !== null);
+  const offenders = timestamped.filter(
     (item) =>
-      item.timestampMs !== null &&
-      ((hasStart && item.timestampMs < startMs - toleranceMs) || (hasEnd && item.timestampMs > endMs + toleranceMs))
+      (hasStart && item.timestampMs < startMs - toleranceMs) || (hasEnd && item.timestampMs > endMs + toleranceMs)
   );
-  return { checked: items.filter((item) => item.timestampMs !== null).length, offenders, ok: offenders.length === 0 };
+  return { checked: timestamped.length, offenders, ok: offenders.length === 0 };
 }
 
 export function evaluateCase(kase, outcome, quality, recency, allContain, withinPeriod, pageOrder) {

package/scripts/lib/run-node-tests.mjs

@@ -1,28 +1,185 @@
 import { spawn } from 'node:child_process';
-import { mkdtemp } from 'node:fs/promises';
+import { appendFile, mkdtemp, readdir, readFile, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { FAILURE_RECORDS_ENV } from './test-failure-records.mjs';
+import { classifyRerunOutcomes, formatFailureSummary } from './test-failure-summary.mjs';
 
 const SUMMARY_REPORTER = new URL('./test-summary-reporter.mjs', import.meta.url).href;
 
+// A whole-suite run passes ~700 paths to one node process. Windows caps a
+// command line at 32767 characters (CreateProcess) and POSIX caps argv+env at
+// ARG_MAX, so the file list is spawned in batches that stay under the cap
+// instead of dying with spawn ENAMETOOLONG before any test runs.
+export const ARG_BUDGET = process.platform === 'win32' ? 30_000 : 1_000_000;
+
+// An argument costs its own characters plus the separator and its quotes.
+const argCost = (arg) => arg.length + 3;
+
+// Full logs are kept for reading after the run; older ones are stale.
+const TEST_LOG_PREFIX = 'mixdog-test-output-';
+const TEST_LOG_RETENTION_MS = 3 * 24 * 60 * 60 * 1000;
+
+async function pruneStaleTestLogs(root) {
+  let names = [];
+  try {
+    names = await readdir(root);
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - TEST_LOG_RETENTION_MS;
+  for (const name of names) {
+    if (!name.startsWith(TEST_LOG_PREFIX)) continue;
+    const path = join(root, name);
+    try {
+      if ((await stat(path)).mtimeMs < cutoff) await rm(path, { recursive: true, force: true });
+    } catch {
+      /* another run may own or be removing it */
+    }
+  }
+}
+
+// Batches keep the file order Node was given; a single path larger than the
+// budget still gets its own batch rather than being dropped. An empty list
+// stays one batch: Node's own discovery is what an argument-less run means.
+export function chunkFileArgs(fileArgs, budget) {
+  const chunks = [[]];
+  let cost = 0;
+  for (const file of fileArgs) {
+    const current = chunks.at(-1);
+    if (current.length > 0 && cost + argCost(file) > budget) {
+      chunks.push([file]);
+      cost = argCost(file);
+      continue;
+    }
+    current.push(file);
+    cost += argCost(file);
+  }
+  return chunks;
+}
+
+function spawnBatch(args, env) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { stdio: 'inherit', env });
+    child.on('error', (error) => {
+      console.error(error);
+      resolve(1);
+    });
+    child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+  });
+}
+
+// The failure reporter writes one JSON line per failed test; a spawn that
+// died before Node opened its destination leaves no file at all.
+async function readFailureRecords(path) {
+  const text = await readFile(path, 'utf8').catch(() => '');
+  return text
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
 // Both discovery and explicit-file runs use the same output contract. Node
-// still owns test selection, diagnostics, skip/todo counts and exit status.
-export async function runNodeTests(nodeArgs, fileArgs) {
-  const logPath = join(await mkdtemp(join(tmpdir(), 'mixdog-test-output-')), 'full.log');
+// still owns test selection, diagnostics, skip/todo counts and exit status;
+// a batched run keeps one full log and fails on the first failing batch.
+//
+// With `coverage`, every batch inherits one fresh NODE_V8_COVERAGE directory,
+// so V8 writes a dump per test process into it and the batches fold into a
+// single artifact. Without it nothing here changes — not the spawn options,
+// not the environment, not the output.
+//
+// `rerunFailed` (default 0 = off) re-runs the files that failed, up to n
+// times. A test that passes on a re-run is reported as flaky and, because the
+// flag was passed, does not fail the run; a test that fails every re-run
+// still exits 1. Every run ends with the failure summary block, so a filtered
+// log can still name what failed.
+export async function runNodeTests(
+  nodeArgs,
+  fileArgs,
+  { argBudget = ARG_BUDGET, coverage = false, rerunFailed = 0 } = {}
+) {
+  await pruneStaleTestLogs(tmpdir());
+  const logPath = join(await mkdtemp(join(tmpdir(), TEST_LOG_PREFIX)), 'full.log');
   console.error(`Full test log: ${logPath}`);
-  const child = spawn(process.execPath, [
+  // Failure records live outside the log directory: the log directory holds
+  // exactly one merged log, and these records are an internal artifact.
+  const failureDir = await mkdtemp(join(tmpdir(), 'mixdog-test-failures-'));
+  // Test processes get a private temp root that is removed after the run, so
+  // every fixture directory a test forgets to delete goes with it instead of
+  // piling up in the system temp directory.
+  const scratchDir = await mkdtemp(join(tmpdir(), 'mixdog-test-scratch-'));
+  const runArgs = [
     ...nodeArgs,
     `--test-reporter=${SUMMARY_REPORTER}`,
     '--test-reporter-destination=stdout',
     '--test-reporter=spec',
-    `--test-reporter-destination=${logPath}`,
-    ...fileArgs,
-  ], { stdio: 'inherit' });
-  child.on('error', (error) => {
-    console.error(error);
-    process.exitCode = 1;
-  });
-  child.on('exit', (code, signal) => {
-    process.exitCode = code ?? (signal ? 1 : 0);
+  ];
+  const fixedCost =
+    argCost(process.execPath) +
+    runArgs.reduce((total, arg) => total + argCost(arg), 0) +
+    argCost(`--test-reporter-destination=${logPath}`) +
+    argCost('.999'); // the per-batch log suffix
+  const batches = chunkFileArgs(fileArgs, Math.max(argBudget - fixedCost, 1));
+  const coverageDir = coverage ? await mkdtemp(join(tmpdir(), 'mixdog-v8-coverage-')) : '';
+  // Failure records travel by environment, not argv: the command line is
+  // already budgeted, and a third reporter would warn about listeners.
+  const childEnv = (recordsPath) => ({
+    ...process.env,
+    TEMP: scratchDir,
+    TMP: scratchDir,
+    TMPDIR: scratchDir,
+    [FAILURE_RECORDS_ENV]: recordsPath,
+    ...(coverageDir ? { NODE_V8_COVERAGE: coverageDir } : {}),
   });
+  let status = 0;
+  const failures = [];
+  for (const [index, batch] of batches.entries()) {
+    const batchLog = batches.length === 1 ? logPath : `${logPath}.${index + 1}`;
+    const batchFailures = join(failureDir, `batch-${index + 1}.jsonl`);
+    const code = await spawnBatch(
+      [...runArgs, `--test-reporter-destination=${batchLog}`, ...batch],
+      childEnv(batchFailures)
+    );
+    if (batchLog !== logPath) {
+      await appendFile(logPath, await readFile(batchLog));
+      await rm(batchLog, { force: true });
+    }
+    failures.push(...(await readFailureRecords(batchFailures)));
+    if (status === 0) status = code;
+  }
+
+  const attempts = [];
+  let lastAttemptStatus = 0;
+  let pending = failures;
+  for (let attempt = 1; attempt <= rerunFailed && pending.length > 0; attempt += 1) {
+    const files = [...new Set(pending.map((record) => record.file))];
+    console.error(`Re-running ${files.length} failed file(s): attempt ${attempt}/${rerunFailed}`);
+    const attemptLog = `${logPath}.rerun-${attempt}`;
+    const attemptFailures = join(failureDir, `rerun-${attempt}.jsonl`);
+    lastAttemptStatus = await spawnBatch(
+      [...runArgs, `--test-reporter-destination=${attemptLog}`, ...files],
+      childEnv(attemptFailures)
+    );
+    await appendFile(logPath, await readFile(attemptLog));
+    await rm(attemptLog, { force: true });
+    attempts.push({ files, failures: await readFailureRecords(attemptFailures) });
+    pending = classifyRerunOutcomes(failures, attempts).failed;
+  }
+  const { failed, flaky } = classifyRerunOutcomes(failures, attempts);
+  // Flaky tolerance applies only to an ordinary test-failure exit that the
+  // re-runs fully explained: nothing failed twice and the last re-run itself
+  // came back clean.
+  if (rerunFailed > 0 && status === 1 && failed.length === 0 && flaky.length > 0 && lastAttemptStatus === 0) status = 0;
+  process.exitCode = status;
+
+  await rm(failureDir, { recursive: true, force: true });
+  // A process a test left running may still hold a file; what it holds stays.
+  await rm(scratchDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }).catch(() => {});
+  if (coverageDir) {
+    const { reportCoverage } = await import('./coverage.mjs');
+    await reportCoverage(coverageDir);
+    await rm(coverageDir, { recursive: true, force: true });
+  }
+  // Last line of the run, after every reporter and the coverage report.
+  process.stdout.write(`\n${formatFailureSummary({ failed, flaky, rerunFailed })}`);
 }