oxmutate 1.1.0 → 1.2.1

package/dist/coordinator.js

@@ -1,14 +1,3 @@
-/**
- * One mutation run, end to end:
- *
- *   instrument (native, parallel) → dry run ×2 (coverage, timings, nondeterministic tests)
- *   → incremental reuse → plan → warm units on a work-stealing server pool, under a watchdog
- *   → isolated re-runs (static mutants, canary-flagged files, unfinished work, flaky verdicts)
- *   → verdicts
- *
- * Every decision that can make a verdict wrong is guarded and counted in `stats`, so a run says
- * what it had to correct, not just what it concluded.
- */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -17,6 +6,7 @@ import { ambientRuntime, run as spawn } from 'bellpull';
 import { checkSurvivors } from './checker.js';
 import { runCommandMutants } from './command-runner.js';
 import { disables } from './config.js';
+import { rangeDisables } from './directives.js';
 import { globToRegExp, matchFiles } from './files.js';
 import { changedLines, parseMutateSpec, shardOf, touches, withinRange } from './lanes.js';
 import { native } from './native.js';
@@ -36,20 +26,12 @@ function readRecords(file) {
         .map((l) => JSON.parse(l));
 }
 const sha = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
-/**
- * Work units of at most this many (mutant, test) executions: small enough to steal, large enough
- * that each unit's fresh worker, which imports the test file's whole graph, is paid for few units.
- * At 120, module loading was most of the CPU on burgee/controlroom (React/Ink in every worker); 400
- * cut units 172 -> 93 and wall 44 -> 39 s (paratext 39 -> 35 s), and 1000 gained nothing more
- * (2026-10-30). Smaller stays better for a pollution restart, which re-runs the rest of a unit.
- */
 const UNIT_PAIRS = 400;
+const RERUN_SLACK = 3;
 const MS_PER_MINUTE = 60_000;
 const PERCENT = 100;
-/** Every test that reaches a mutant: the score's, then a spec oracle's replay tests. */
 const allCovering = (m) => [...m.coveredBy, ...(m.specCoveredBy ?? [])];
 const percent = (n, of) => (of ? (PERCENT * n) / of : PERCENT);
-/** Stryker's score: detected over everything valid and not ignored; `covered` leaves out no-coverage. */
 function scoreOf(mutants) {
     const scored = mutants.filter((m) => !['Ignored', 'CompileError', 'RuntimeError'].includes(m.status));
     const detected = scored.filter((m) => m.status === 'Killed' || m.status === 'Timeout').length;
@@ -61,8 +43,8 @@ export async function run(options) {
     const { root } = options;
     const work = mkdtempSync(path.join(tmpdir(), 'oxmutate-'));
     const stats = {
-        files: 0, mutants: 0, instrumentMs: 0, dryRunMs: 0, mutationMs: 0, isolatedMs: 0, wallMs: 0, testExecutions: 0,
-        watchdogKills: 0, crashes: 0, canaryFiles: 0, pollutionRestarts: 0, survivorsOverturned: 0, timeoutsOverturned: 0, compileErrors: 0, isolatedRuns: 0, reused: 0, flakyTests: 0, flakyMutants: 0, units: 0, serversSpawned: 0,
+        files: 0, mutants: 0, instrumentMs: 0, dryRunMs: 0, mutationMs: 0, staticMs: 0, staticRecollections: 0, isolatedMs: 0, wallMs: 0, testExecutions: 0,
+        watchdogKills: 0, idleStalls: 0, crashes: 0, canaryFiles: 0, pollutionRestarts: 0, survivorsOverturned: 0, timeoutsOverturned: 0, compileErrors: 0, isolatedRuns: 0, reused: 0, flakyTests: 0, flakyMutants: 0, units: 0, serversSpawned: 0,
     };
     let unitSeq = 0;
     const fileFor = (kind, ext) => path.join(work, `${kind}-${String(unitSeq++)}.${ext}`);
@@ -70,8 +52,6 @@ export async function run(options) {
     const progress = startProgress(options.reporters, stderr);
     try {
         progress.phase('instrumenting');
-        // ── 1. Instrument ─────────────────────────────────────────────────────────────────────────
-        // Stryker's `file:line-line` entries select files by their glob and mutants by their range.
         const specs = options.mutate.map(parseMutateSpec);
         const files = matchFiles(root, specs.map((x) => x.glob));
         const rangesFor = (file) => {
@@ -93,8 +73,9 @@ export async function run(options) {
         const directiveErrors = [];
         for (const f of instrumented) {
             const { disables: offs, errors } = disables(sources[f.path] ?? '', f.path);
+            const ranged = rangeDisables(sources[f.path] ?? '', f.path);
             const ranges = rangesFor(f.path);
-            directiveErrors.push(...errors);
+            directiveErrors.push(...errors, ...ranged.errors);
             let any = false;
             for (const m of f.mutants) {
                 if (changed && !touches(changed, f.path, m.start.line, m.end.line))
@@ -104,13 +85,14 @@ export async function run(options) {
                 if (options.shard && shardOf(m.id, options.shard.count) !== options.shard.index)
                     continue;
                 const off = offs.find((d) => d.line === m.start.line && (d.mutators === 'all' || d.mutators.includes(m.mutatorName)));
+                const inRange = ranged.reasonFor(m.start.line, m.mutatorName);
                 const excluded = options.excludedMutations.includes(m.mutatorName);
                 mutants.push({
                     ...m,
                     file: f.path,
                     coveredBy: [],
-                    status: off || excluded || m.ignoredReason ? 'Ignored' : 'NoCoverage',
-                    statusReason: off?.reason ?? m.ignoredReason ?? (excluded ? `excluded mutator ${m.mutatorName}` : undefined),
+                    status: off || inRange !== undefined || excluded || m.ignoredReason ? 'Ignored' : 'NoCoverage',
+                    statusReason: off?.reason ?? inRange ?? m.ignoredReason ?? (excluded ? `excluded mutator ${m.mutatorName}` : undefined),
                 });
                 any = true;
             }
@@ -122,16 +104,13 @@ export async function run(options) {
         stats.files = files.length;
         stats.mutants = mutants.length;
         const mapFile = path.join(work, 'instrumented.json');
-        // The frozen oracle's base-ref test files ride along in the same map (frozen.ts).
         writeFileSync(mapFile, JSON.stringify({ ...codeMap, ...options.testOverrides }));
-        // ── 1b. The build, once, before anything runs (Stryker's `buildCommand`) ─────────────────
         if (options.buildCommand) {
             const [command = '', ...args] = options.buildCommand.trim().split(/\s+/);
             const built = await spawn(command, args, { cwd: root, runtime: ambientRuntime() });
             if (!built.ok)
                 throw new InstrumentFault(`buildCommand \`${options.buildCommand}\` exited ${String(built.code)}: ${(built.stderr || built.stdout).trim().slice(-1500)}. fix: make the build pass on its own first`);
         }
-        // ── 1c. The command runner: any test command, one process per mutant (command-runner.ts) ──
         if (options.commandRunner) {
             const m0 = performance.now();
             try {
@@ -146,8 +125,6 @@ export async function run(options) {
             stats.wallMs = performance.now() - wall0;
             return { root, options, sources, mutants, tests: [], stats, score: scoreOf(mutants) };
         }
-        // ── 2. Dry run, twice (the second only to find nondeterministic tests) ────────────────────
-        // Spec oracles' traces, generated once; servers inherit where they are (spec.ts reads it).
         const traceDirs = {};
         for (const oracle of options.specOracles)
             traceDirs[oracle.name] = await tracesFor(oracle, root, work);
@@ -193,8 +170,6 @@ export async function run(options) {
             throw new InstrumentFault(`${String(failing.length)} test(s) fail with no mutant active, so no verdict can be trusted: ${failing.slice(0, 5).map((t) => t.name).join('; ')}. fix: make the suite pass first`);
         if (dry.tests.length === 0 && !options.allowEmpty)
             throw new InstrumentFault('the dry run ran no tests. fix: check the Vitest config the run used, or set allowEmpty');
-        // The second dry run only finds nondeterministic tests, which matter at step 7: it runs beside
-        // the warm phase instead of before it (6 s of a 107 s burgee/controlroom run, 2026-10-27).
         const findFlakyTests = async () => {
             const flaky = new Set();
             if (options.flakyReruns > 0) {
@@ -211,11 +186,10 @@ export async function run(options) {
             return flaky;
         };
         const flakyCheck = findFlakyTests();
-        flakyCheck.catch(() => undefined); // awaited at step 7; a run that fails first must not also reject unhandled
+        flakyCheck.catch(() => undefined);
         const testInfo = new Map(dry.tests.map((t) => [t.id, t]));
         const coveringTests = new Map();
         const hits = new Map();
-        /** Static mutant → the test files whose collection (imports, beforeAll) reached it. */
         const staticFiles = new Map();
         for (const [testId, perMutant] of Object.entries(dry.perTest)) {
             if (testId.startsWith(FILE_KEY)) {
@@ -234,8 +208,6 @@ export async function run(options) {
             }
         }
         const staticIds = new Set([...Object.keys(dry.static), ...staticFiles.keys()]);
-        // A spec oracle's replay tests, by test id → oracle name. They are not tests of the score:
-        // their kills are reported as the spec's, on a track of their own.
         const specOf = new Map();
         for (const oracle of options.specOracles) {
             const replay = new Set(matchFiles(root, oracle.replay).map((f) => path.join(root, f)));
@@ -272,7 +244,6 @@ export async function run(options) {
             const tests = dry.tests.map(({ id, file, name, ms }) => ({ id, file, name, ms }));
             return { root, options, sources, mutants, tests, stats, score: { detected: 0, undetected: 0, total: 0, mutationScore: 0, covered: 0 }, dryRunOnly: true };
         }
-        // ── 3. Incremental reuse ──────────────────────────────────────────────────────────────────
         const fileHashes = new Map();
         const fileHash = (abs) => {
             let h = fileHashes.get(abs);
@@ -296,21 +267,12 @@ export async function run(options) {
                 stats.reused++;
             }
         }
-        // ── 4. Warm units on the server pool ──────────────────────────────────────────────────────
-        // Static mutants, hybrids included, never run warm: a module evaluated without the mutant
-        // cannot stand in for one evaluated with it. Tried 2026-10-27: warm kills of hybrids gave 3
-        // false kills on burgee/paratext (an import-time registration the tests then read).
         const toRun = mutants.filter((m) => !m.reused && m.status !== 'Ignored' && !m.static && allCovering(m).length > 0);
         const byId = new Map(mutants.map((m) => [m.id, m]));
-        /** The switch-taken count past which a run is a runaway: 100x what the dry run saw, at least 1000. */
         const hitLimitOf = (id) => Math.max(1000, (hits.get(id) ?? 1) * 100);
         const hitLimits = Object.fromEntries(toRun.map((m) => [m.id, hitLimitOf(m.id)]));
         const maxTestMs = (id) => { const m = byId.get(id); return Math.max(0, ...(m ? allCovering(m) : []).map((t) => testInfo.get(t)?.ms ?? 0)); };
-        // The watchdog is for runaways, which loop in fast code; a slow test under a loaded machine is
-        // not one. 3x the covering test's dry-run time, not Stryker's 1.5x: at 1.5x, subprocess-heavy
-        // burgee/paratext tests were stopped as false timeouts (2026-10-27).
         const warmBudget = (id) => options.timeoutMS + Math.max(options.timeoutFactor, 3) * maxTestMs(id) + 250;
-        // Files a mutant's covering tests live in, cheapest first (by the covering tests' time there).
         const fileOrder = new Map();
         for (const m of toRun) {
             const cost = new Map();
@@ -330,7 +292,6 @@ export async function run(options) {
             stats.units++;
             return unit;
         };
-        /** Split a file's plan into units of about UNIT_PAIRS executions, by mutant. */
         const unitsFor = (file, plan) => {
             const ids = [...new Set(Object.values(plan).flat())];
             const pairs = Object.values(plan).reduce((sum, l) => sum + l.length, 0);
@@ -340,7 +301,6 @@ export async function run(options) {
                 return makeUnit(file, Object.fromEntries(Object.entries(plan).map(([t, l]) => [t, l.filter((id) => mine.has(id))]).filter(([, l]) => l.length > 0)));
             });
         };
-        /** Units for these mutants, each planned only in the files `pick` selects for it. */
         const unitsForRound = (mutantsHere, pick) => {
             const perFile = new Map();
             for (const m of mutantsHere) {
@@ -358,22 +318,16 @@ export async function run(options) {
                 }
             }
             const units = [...perFile].flatMap(([file, tests]) => unitsFor(file, Object.fromEntries(tests)));
-            // Sizing and ordering units by dry-run time instead of pair count (longest first) was tried:
-            // 30% more units and ~10% more CPU on burgee/controlroom, and no wall-clock gain that this
-            // machine's load (average 21 to 76 across the A/B) could show (2026-10-27).
             const weight = (u) => Object.values(planUnits.get(u.results)?.plan ?? {}).reduce((sum, l) => sum + l.length, 0);
             return units.sort((a, b) => weight(b) - weight(a));
         };
         const records = [];
         const runaways = new Set();
         const crashedIds = new Set();
-        // Dependencies inlined here too, so the static phase (5b) reuses these servers instead of starting its own.
         const pool = createPool({ root, vitestConfig: options.vitestConfig, workers: 1, instrumentedMap: mapFile, nodeArgs: options.testRunnerNodeArgs, inlineDeps: true }, options.concurrency, work, 'mutant');
         pools.push(pool);
-        /** Mutants decided on one verdict track: the tests', or a spec oracle's replay tests'. */
         const killedSoFar = (spec) => new Set([...runaways, ...crashedIds, ...records.filter((r) => r.type === 'mutant' && r.status !== 'Survived' && Boolean(r.spec) === spec).map((r) => r.id ?? '')]);
         const afterUnit = (unit, outcome) => {
-            // Verdicts a failed canary cannot vouch for are dropped; their pairs are re-queued below.
             const raw = readRecords(unit.results);
             const suspect = new Set(raw.filter((r) => r.type === 'polluted').flatMap((r) => (r.suspects ?? []).map((id) => `${id}|${r.test ?? ''}`)));
             const recs = raw.filter((r) => !(r.type === 'mutant' && suspect.has(`${r.id ?? ''}|${r.test ?? ''}`)));
@@ -388,7 +342,6 @@ export async function run(options) {
                 runaways.add(outcome.killedFor);
             else if (bad)
                 crashedIds.add(bad);
-            // The rest of the unit: pairs not yet run, mutants not yet decided, into a fresh context.
             const ran = new Set(recs.filter((r) => r.type === 'mutant').map((r) => `${r.id ?? ''}|${r.test ?? ''}`));
             const decided = { tests: killedSoFar(false), spec: killedSoFar(true) };
             const { file, plan, depth } = planUnits.get(unit.results);
@@ -401,8 +354,6 @@ export async function run(options) {
             }
             if (Object.keys(rest).length === 0)
                 return [];
-            // A unit that made no progress, or that keeps being polluted, is left to the isolated
-            // re-run rather than retried for ever.
             if (ran.size === 0 || depth >= 40) {
                 for (const id of new Set(Object.values(rest).flat()))
                     unfinished.add(id);
@@ -418,13 +369,6 @@ export async function run(options) {
         const killedCount = () => `${String(killedSoFar(false).size)} of ${String(toRun.length)} mutants killed so far`;
         progress.phase('warm runs', killedCount);
         const m0 = performance.now();
-        // One round, every covering file at once. A two-round plan (cheapest file first, survivors
-        // to the rest) cut executions 23% on burgee/paratext but took 2.9x longer: the second round
-        // waits for the first to drain, and the expensive files then run as a tail (2026-10-27).
-        // Kills are filtered out at dispatch, not when a unit is built: most units wait in the queue while
-        // others run, and a mutant another unit has killed (vouched for by its canary) needs no more of its
-        // covering tests. 1,022 of 6,550 warm executions on burgee/paratext ran after the mutant's kill
-        // (2026-10-30). Verdicts are unchanged: a Killed mutant needs no other pair (dispatch.qnt).
         const beforeUnit = (unit) => {
             const entry = planUnits.get(unit.results);
             if (!entry)
@@ -445,7 +389,6 @@ export async function run(options) {
         };
         await pool.drain(unitsForRound(toRun, (m) => fileOrder.get(m.id) ?? []), (_, id) => warmBudget(id), afterUnit, beforeUnit);
         stats.mutationMs = performance.now() - m0;
-        // ── 5. Verdicts from the warm run ─────────────────────────────────────────────────────────
         const byMutant = new Map();
         for (const r of records)
             if (r.type === 'mutant' && r.id)
@@ -460,10 +403,10 @@ export async function run(options) {
             if (m.specCoveredBy)
                 m.spec = specVerdict(m, all.filter((r) => r.spec));
             if (m.coveredBy.length === 0 && !runaways.has(m.id) && !crashedIds.has(m.id)) {
-                continue; // reached only by a spec oracle: no test covers it, and its status says so
+                continue;
             }
             else if (runaways.has(m.id)) {
-                isolatedQueue.push(m); // a watchdog stop is confirmed before it is reported (6, below)
+                isolatedQueue.push(m);
             }
             else if (crashedIds.has(m.id)) {
                 m.status = 'RuntimeError';
@@ -479,22 +422,15 @@ export async function run(options) {
                 m.testsCompleted = recs.length;
             }
             else {
-                isolatedQueue.push(m); // unfinished: a crash left work undone
+                isolatedQueue.push(m);
             }
         }
         const staticMutants = mutants.filter((m) => m.static && m.status !== 'Ignored' && !m.reused);
-        // ── 6. Isolated re-runs: the switch armed before import, Vitest run normally ──────────────
         const allTestFiles = [...new Set(dry.tests.map((t) => t.file))];
-        // A static mutant needs the files that load it (plus any whose tests reach it); only a hit
-        // with no file to attribute it to (a setup file outside collection) falls back to all files.
         const fileCost = new Map();
         for (const t of dry.tests)
             fileCost.set(t.file, (fileCost.get(t.file) ?? 0) + t.ms);
         const byCost = (files) => [...files].sort((a, b) => (fileCost.get(a) ?? 0) - (fileCost.get(b) ?? 0));
-        // Test file -> source file -> how many of that source's mutants its tests reach. A static mutant
-        // rarely has covering tests of its own, so its loaders were tried cheapest first, and the cheapest
-        // seldom tests the module: on burgee/controlroom each tabs.ts static mutant ran 75 tests in two
-        // files where Stryker needed 37 (2026-10-30). The file that exercises the module goes first.
         const affinity = new Map();
         for (const mm of mutants) {
             for (const t of mm.coveredBy) {
@@ -513,35 +449,20 @@ export async function run(options) {
             const loaders = staticFiles.get(m.id);
             if (!loaders || m.id in dry.static)
                 return byCost(allTestFiles);
-            // Files whose tests reach the mutant first: they kill it. Ordering all loaders by cost alone
-            // ran a file that only imports it first, and 288 of 349 isolated kills on burgee/paratext
-            // came from a later file (2026-10-27).
             const covering = byCost([...new Set(tests)]);
             return [...covering, ...byAffinity(m.file, [...loaders].filter((f) => !covering.includes(f)))];
         };
         const isolatedBudget = (id) => {
             const m = byId.get(id);
             const fs = m ? filesFor(m) : allTestFiles;
-            // A non-static mutant's isolated run executes only its covering tests (`tests` below), so they
-            // are its budget; every test of its files made a hang wait 30-40 s on oxmutate's own suite,
-            // where its covering tests take a fraction of that (2026-10-30). A static mutant runs them all.
             const covering = new Set(m && !m.static ? m.coveredBy : []);
             const ms = dry.tests.filter((t) => fs.includes(t.file) && (covering.size === 0 || covering.has(t.id))).reduce((sum, t) => sum + t.ms, 0);
             return 1500 + options.timeoutMS + options.timeoutFactor * ms * 2;
         };
-        // A non-static mutant runs only its covering tests, armed across all of them in file order:
-        // Stryker's semantics, so cross-test effects still show (a no-op reset() lets state pile up
-        // for the next covering test). A static mutant runs every test of its files, because an
-        // import-time change reaches tests that never execute the mutated line.
-        /**
-         * Static mutants decided in live workers, one unit per (test file, batch of its static mutants),
-         * on a pool that inlines dependencies. Returns the mutants this path could not decide.
-         */
         const decideStaticLive = async (items) => {
             if (items.length === 0)
                 return [];
             const STATIC_BATCH = 25;
-            /** Units of up to STATIC_BATCH mutants per test file, for the files each mutant gets this round. */
             const unitsFor = (filesOf) => {
                 const byFile = new Map();
                 for (const m of items)
@@ -553,9 +474,8 @@ export async function run(options) {
                 })));
             };
             const killed = new Map();
-            /** Decided by the hit-count limit: a runaway, Timeout like a warm one. */
             const timedOut = new Set();
-            const passed = new Map(); // mutant -> files that ran it clean
+            const passed = new Map();
             const back = new Set();
             const ran = new Map();
             const staticPool = pool;
@@ -563,6 +483,8 @@ export async function run(options) {
                 const file = unit.files[0] ?? '';
                 const decided = new Set();
                 for (const r of readRecords(unit.results)) {
+                    if (r.type === 'recollection')
+                        stats.staticRecollections++;
                     if (r.type === 'static-fallback')
                         for (const id of r.ids ?? [])
                             back.add(id);
@@ -577,7 +499,6 @@ export async function run(options) {
                     else
                         (passed.get(r.id) ?? passed.set(r.id, new Set()).get(r.id))?.add(file);
                 }
-                // A stop or a crash leaves the rest of the batch undecided: the fresh-worker path decides it.
                 if (outcome.killedFor || outcome.crashed)
                     for (const id of unit.staticIds ?? [])
                         if (!decided.has(id))
@@ -588,13 +509,8 @@ export async function run(options) {
                 unit.staticIds = (unit.staticIds ?? []).filter((id) => !killed.has(id) && !back.has(id));
                 return unit.staticIds.length > 0;
             };
-            // Two rounds: each mutant first in the file most likely to kill it (filesFor puts the files whose
-            // tests reach it first, cheapest first), then its other files only if it survived. In one round
-            // every loading file ran a mutant at once, and a kill in one did not spare the others: 41 tests a
-            // static kill on burgee/controlroom against Stryker's 33.6 (2026-10-30).
             const open = (m) => !killed.has(m.id) && !back.has(m.id);
             const rounds = [(m) => filesFor(m).slice(0, 1), (m) => (open(m) ? filesFor(m).slice(1) : [])];
-            // the mutant's run and the unarmed canary after it
             for (const round of rounds)
                 await staticPool.drain(unitsFor(round), (_, id) => 2 * isolatedBudget(id), afterStatic, keepUndecided);
             const undecided = [];
@@ -619,9 +535,6 @@ export async function run(options) {
             if (items.length === 0)
                 return verdicts;
             const mk = (batch) => ({ mode: 'isolated', files: [], results: fileFor('iso', 'jsonl'), progress: fileFor('iso', 'progress'), batch: batch.map((m) => ({ id: m.id, files: filesFor(m), tests: m.static ? undefined : m.coveredBy, hitLimit: hitLimitOf(m.id) })) });
-            // Packed by estimated cost, heaviest first into the lightest bin, and the heaviest bins run
-            // first. Equal mutant counts left one unit at 8.4 s while the others finished in under 3 s on
-            // burgee/controlroom (2026-10-30): a mutant's cost is its files' dry-run time, not one.
             const cost = (m) => isolatedBudget(m.id);
             const bins = Array.from({ length: Math.min(items.length, options.concurrency * 2) }, () => ({ load: 0, batch: [] }));
             for (const m of [...items].sort((x, y) => cost(y) - cost(x))) {
@@ -632,7 +545,6 @@ export async function run(options) {
             const units = bins.sort((x, y) => y.load - x.load).map((b) => mk(b.batch));
             stats.isolatedRuns += items.length;
             await pool.drain(units, (_, id) => slack * isolatedBudget(id), (unit, outcome) => {
-                // Vitest reports per test file: a mutant is killed if any of its files failed.
                 for (const rec of readRecords(unit.results)) {
                     if (rec.type !== 'isolated' || !rec.id)
                         continue;
@@ -646,7 +558,7 @@ export async function run(options) {
                         verdicts.set(rec.id, { status: prev?.status ?? 'Survived', killedBy: prev?.killedBy, testsCompleted });
                 }
                 if (outcome.killedFor)
-                    verdicts.set(outcome.killedFor, { status: 'Timeout' });
+                    verdicts.set(outcome.killedFor, { status: 'Timeout', idle: outcome.stall === 'idle' });
                 if (outcome.crashed && outcome.crashedFor)
                     verdicts.set(outcome.crashedFor, { status: 'RuntimeError' });
                 if (!outcome.killedFor && !outcome.crashed)
@@ -660,21 +572,15 @@ export async function run(options) {
                     verdicts.set(m.id, { status: 'RuntimeError' });
             return verdicts;
         };
-        // ── 5b. Static mutants in live workers (.sdlc/intents/oxmutate/staticwarm.qnt) ─────────────
-        // A fresh worker per (static mutant, file) cost ~80 ms of start-up around tests that take a few
-        // ms: 29 of 35 s on burgee/paratext (2026-10-30). A live worker re-evaluates the project's modules
-        // per mutant instead; whatever it cannot vouch for comes back here for the fresh-worker path.
-        // OXMUTATE_ISOLATE_STATIC=1 sends every static mutant down the fresh-worker path, as before.
+        const s0 = performance.now();
         const staticBack = env['OXMUTATE_ISOLATE_STATIC'] ? staticMutants : await decideStaticLive(staticMutants);
+        stats.staticMs = performance.now() - s0;
         isolatedQueue.push(...staticBack);
         progress.phase(`isolated runs (static mutants and stragglers: ${String(isolatedQueue.length)})`);
         const i0 = performance.now();
         const first = await runIsolated(isolatedQueue);
-        // A watchdog stop on a loaded machine is a slow test, not a runaway: 31 of them on one
-        // burgee/paratext run while the load average sat at 40, all Survived for Stryker (2026-10-27).
-        // Each stop gets one more run with 3x the budget; only one that is stopped again is a Timeout.
-        const stopped = isolatedQueue.filter((m) => first.get(m.id)?.status === 'Timeout');
-        const again = await runIsolated(stopped, 3);
+        const stopped = isolatedQueue.filter((m) => first.get(m.id)?.status === 'Timeout' && !first.get(m.id)?.idle);
+        const again = await runIsolated(stopped, RERUN_SLACK);
         for (const m of stopped) {
             const v = again.get(m.id);
             if (v && v.status !== 'Timeout' && v.status !== 'RuntimeError') {
@@ -689,25 +595,13 @@ export async function run(options) {
                 m.killedBy = v.killedBy;
                 m.testsCompleted = v.testsCompleted;
                 if (v.status === 'Timeout')
-                    m.statusReason = 'stopped by the watchdog twice, the second time with 3x the budget';
+                    m.statusReason = v.idle ? 'its test waited past the budget with the worker idle: a hang, not a slow test' : 'stopped by the watchdog twice, the second time with 3x the budget';
             }
         }
-        // ── 6b. Confirm survivors under whole-file semantics ──────────────────────────────────────
-        // The warm runner arms a mutant for one test at a time, so a mutant whose effect only shows
-        // across tests (a `reset()` in beforeEach made a no-op, so state piles up for the next test)
-        // survives warm and is killed when armed for the whole file, the way Stryker runs it (burgee/
-        // paratext plugin.ts, 2026-10-27). Survivors are what a person acts on, so each one is
-        // re-run once with the mutant armed across its covering files before it is reported.
-        // A survivor with one covering test is not re-run: confirmation runs only covering tests, so there
-        // is no later test for its leftover state to reach, and the warm run already armed that test
-        // through its hooks from clean state (.sdlc/intents/oxmutate/confirm.qnt).
         const survivors = toRun.filter((m) => m.status === 'Survived' && new Set(m.coveredBy).size > 1);
         const confirmed = await runIsolated(survivors);
-        // A timeout here is a watchdog stop like any other, and a loaded machine makes them: two
-        // closeout survivors were reported killed this way while a docs build shared the machine
-        // (2026-10-27). The same rule as section 6: one more run at 3x the budget before believing it.
-        const stoppedHere = survivors.filter((m) => confirmed.get(m.id)?.status === 'Timeout');
-        const recheck = await runIsolated(stoppedHere, 3);
+        const stoppedHere = survivors.filter((m) => confirmed.get(m.id)?.status === 'Timeout' && !confirmed.get(m.id)?.idle);
+        const recheck = await runIsolated(stoppedHere, RERUN_SLACK);
         for (const m of stoppedHere) {
             const v = recheck.get(m.id);
             if (v)
@@ -722,10 +616,8 @@ export async function run(options) {
                 stats.survivorsOverturned++;
             }
         }
-        // ── 6c. Survivors that do not type-check are CompileErrors (checker.ts) ────────────────────
         if (options.typeCheck) {
             progress.phase('type-checking survivors');
-            // Every undetected mutant is one somebody would act on: survivors and the uncovered.
             const survived = mutants.filter((m) => m.status === 'Survived' || m.status === 'NoCoverage');
             const refused = await checkSurvivors({ root, tsconfig: options.tsconfigFile, command: options.typeChecker, concurrency: options.concurrency }, survived).catch((error) => {
                 throw new InstrumentFault(error instanceof Error ? error.message : String(error));
@@ -736,7 +628,6 @@ export async function run(options) {
                 stats.compileErrors++;
             }
         }
-        // ── 7. Flaky verdicts: re-run mutants whose covering tests are nondeterministic ───────────
         const flakyTests = await flakyCheck;
         stats.flakyTests = flakyTests.size;
         const flakyCandidates = toRun.filter((m) => m.coveredBy.some((t) => flakyTests.has(t)));
@@ -759,8 +650,8 @@ export async function run(options) {
         }
         stats.isolatedMs = performance.now() - i0;
         stats.watchdogKills = pool.stats.killed;
+        stats.idleStalls = pool.stats.idle;
         stats.crashes = pool.stats.crashed;
-        // ── 8. Score, cache, result ───────────────────────────────────────────────────────────────
         if (options.incremental) {
             mkdirSync(path.dirname(options.incrementalFile), { recursive: true });
             const next = { ...cache };
@@ -800,4 +691,3 @@ export async function run(options) {
             rmSync(work, { recursive: true, force: true });
     }
 }
-//# sourceMappingURL=coordinator.js.map

package/dist/directives.js

@@ -0,0 +1,38 @@
+const HEAD = /\/\/\s*(?:Stryker|oxmutate)\s+(disable|restore)\s+(\S.*)/i;
+const LIST = /^(?:all|\w+(?:\s*,\s*\w+)*)$/i;
+const covers = (r, mutator) => r.mutators === 'all' || r.mutators.includes(mutator);
+export function rangeDisables(source, file) {
+    const rules = [];
+    const errors = [];
+    source.split('\n').forEach((text, i) => {
+        const m = HEAD.exec(text);
+        if (!m)
+            return;
+        const body = m[2];
+        const colon = body.indexOf(':');
+        const list = (colon === -1 ? body : body.slice(0, colon)).trim();
+        if (!LIST.test(list))
+            return;
+        const kind = m[1].toLowerCase();
+        const reason = colon === -1 ? '' : body.slice(colon + 1).trim();
+        if (kind === 'disable' && !reason) {
+            errors.push(`${file}:${String(i + 1)}: disable comment without a reason. fix: add ": <why these mutants cannot be killed>"`);
+            return;
+        }
+        const mutators = list.toLowerCase() === 'all' ? 'all' : list.split(',').map((s) => s.trim().toLowerCase());
+        rules.push({ line: i + 1, kind, mutators, reason });
+    });
+    return {
+        errors,
+        reasonFor(line, mutator) {
+            const name = mutator.toLowerCase();
+            for (let k = rules.length - 1; k >= 0; k--) {
+                const r = rules[k];
+                if (r.line >= line || !covers(r, name))
+                    continue;
+                return r.kind === 'disable' ? r.reason : undefined;
+            }
+            return undefined;
+        },
+    };
+}

package/dist/files.js

@@ -1,21 +1,13 @@
-/**
- * The files to mutate, from Stryker-style globs (`src/**\/*.ts`, `!src/**\/*.test.ts`, `{a,b}`).
- * No dependency: a glob is translated to one regular expression, and the walk skips the
- * directories a project never mutates.
- */
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.turbo', '.oxmutate', '.stryker-tmp', 'reports']);
 const escapeRegExp = (s) => s.replace(/[.+^$()|[\]\\]/g, '\\$&');
-/** Translate one glob (without a leading `!`) into an anchored regular expression. */
 export function globToRegExp(glob) {
     let re = '';
-    // Stryker disable next-line EqualityOperator: one step past the end reads charAt(length), an empty string, which appends nothing
     for (let i = 0; i < glob.length; i++) {
         const c = glob.charAt(i);
         if (c === '*') {
             if (glob[i + 1] === '*') {
-                // `**/` matches zero or more directories; a bare `**` matches anything.
                 if (glob[i + 2] === '/') {
                     re += '(?:.*/)?';
                     i += 2;
@@ -40,7 +32,6 @@ export function globToRegExp(glob) {
     }
     return new RegExp(`^${re}$`);
 }
-/** Repository-relative paths (forward slashes) of files matching the include and exclude globs. */
 export function matchFiles(root, patterns) {
     const include = patterns.filter((p) => !p.startsWith('!')).map(globToRegExp);
     const exclude = patterns.filter((p) => p.startsWith('!')).map((p) => globToRegExp(p.slice(1)));
@@ -59,4 +50,3 @@ export function matchFiles(root, patterns) {
     walk('');
     return out.sort();
 }
-//# sourceMappingURL=files.js.map

package/dist/frozen.js

@@ -1,22 +1,8 @@
-/**
- * The frozen oracle (spec R14): a change that edits tests is also scored against the base ref's
- * tests. The code under test is the same in both runs, so the mutants and their ids are the same;
- * only the test files differ. A mutant the base tests detect and the changed tests do not is a test
- * the change weakened, which is how a patch that "makes the check pass" by editing the check shows
- * up (the reward-hacking concern in the intent, written as a CI result).
- *
- * The base tests are served to Vitest from memory, the way instrumented sources are: nothing in
- * the working tree is touched.
- */
 import path from 'node:path';
 import { ambientRuntime, run as spawn } from 'bellpull';
 import { run } from './coordinator.js';
 const detected = (m) => m?.status === 'Killed' || m?.status === 'Timeout';
 const undetected = (m) => m?.status === 'Survived' || m?.status === 'NoCoverage';
-/**
- * A test file the change added has no base version. It is served as one skipped test, so the base
- * run has the file (Vitest finds it on disk) and none of its tests.
- */
 const ABSENT_AT_BASE = "import { it } from 'vitest';\nit.skip('absent at the base ref (oxmutate frozen oracle)', () => {});\n";
 async function git(root, args) {
     const r = await spawn('git', args, { cwd: root, runtime: ambientRuntime() });
@@ -44,4 +30,3 @@ export async function frozenOracle(head, base) {
         .map((m) => ({ id: m.id, file: m.file, line: m.start.line, mutatorName: m.mutatorName, replacement: m.replacement }));
     return result;
 }
-//# sourceMappingURL=frozen.js.map

package/dist/heartbeat.js

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export const HEARTBEAT_MS = 250;
+export const STALE_MS = 1000;
+export const CPU_SAMPLE_MS = 250;
+export const CPU_WINDOW_MS = 1000;
+export const MIN_CPU_SPAN_MS = 500;
+export const IDLE_CPU = 0.25;
+export const BEAT_ENV = 'OXMUTATE_BEAT';
+export const beatFile = (workDir, pid) => path.join(workDir, `beat-${String(pid)}`);
+const { setInterval: realSetInterval, clearInterval: realClearInterval } = globalThis;
+export const realNow = Date.now.bind(Date);
+const BEAT_KEY = Symbol.for('oxmutate.heartbeat');
+let inTest = false;
+export function markTest(running) {
+    inTest = running;
+}
+export function startHeartbeat(file) {
+    if (!file)
+        return;
+    const holder = globalThis;
+    realClearInterval(holder[BEAT_KEY]);
+    const beat = () => {
+        try {
+            writeFileSync(file, inTest ? `${String(realNow())} test` : String(realNow()));
+        }
+        catch {
+            return false;
+        }
+        return true;
+    };
+    beat();
+    holder[BEAT_KEY] = realSetInterval(() => {
+        if (!beat())
+            realClearInterval(holder[BEAT_KEY]);
+    }, HEARTBEAT_MS);
+    holder[BEAT_KEY].unref();
+}
+export function readBeat(file, now = Date.now()) {
+    let text;
+    try {
+        text = String(readFileSync(file));
+    }
+    catch {
+        return { age: Number.POSITIVE_INFINITY, inTest: false };
+    }
+    const [stamp, where] = text.split(' ');
+    const at = Number(stamp);
+    return { age: Number.isFinite(at) && at > 0 ? now - at : Number.POSITIVE_INFINITY, inTest: where === 'test' };
+}
+const US_PER_MS = 1000;
+export function cpuShare(samples, now) {
+    const recent = samples.filter((s) => s.at >= now - CPU_WINDOW_MS && s.at <= now);
+    const first = recent[0];
+    const last = recent.at(-1);
+    if (!first || !last || last.at - first.at < MIN_CPU_SPAN_MS)
+        return undefined;
+    return (last.us - first.us) / US_PER_MS / (last.at - first.at);
+}
+export function classifyStall(o) {
+    return o.beat.inTest && o.beat.age < STALE_MS && (o.cpuShare ?? IDLE_CPU) < IDLE_CPU ? 'idle' : 'busy';
+}