oxmutate 1.1.0 → 1.2.0

package/README.md

@@ -189,7 +189,7 @@ setting a value inside the worker that already has the tests loaded.
 | Re-parse | Every instrumented file is parsed again before it runs; one that does not parse stops the run (exit 3) instead of scoring a broken file |
 | Canary | The unmutated test must still pass after mutants run in a context, with its `beforeEach`/`afterEach` hooks re-run around every run, file-level ones included; if a mutant left a cache, a registry or a fixture behind, the context restarts and the suspect verdicts run again. A kill that follows unchecked runs is checked at once and decided again from clean state, so no kill rests on another mutant's leftovers |
 | Survivor confirmation | A survivor is re-run with the mutant armed across its covering tests in one file, as Stryker arms it, so a mutant that only fails across tests is killed |
-| Watchdog | A synchronous runaway is stopped and its server replaced; the stop is re-run at 3x the budget before it is reported as a timeout |
+| Watchdog | A synchronous runaway is stopped and its server replaced; the stop is re-run at 3x the budget before it is reported as a timeout. A stop whose worker was idle inside a test body (its event loop still turning, by a heartbeat, and its server under 25% of a core) is a hang, not a slow test: it is a Timeout as it stands, the way Stryker scores it, with no 3x re-run |
 | Static mutants | Code that runs at import is decided in a live worker: the mutant is armed, the module registry reset and the test file collected again, against the files that load it. A file whose collection changes globals, `process.env` or a built-in prototype, or a mutant that leaves a trace, goes back to a fresh worker per mutant (`OXMUTATE_ISOLATE_STATIC=1` sends all of them there) |
 | Flaky tests | Tests that behave differently across two dry runs have their mutants re-run; a verdict that changes is reported `flaky` |
 | No orphans | Every Vitest server exits when its run does, killed or not |
@@ -261,7 +261,8 @@ head-to-head runs (`bench/burgee-pair.mts`, concurrency 4, one tool after the ot
 
 The ceiling depends on the suite as much as the tool: controlroom's own `vitest run` takes ~8 s and
 every fresh worker imports React and Ink, so even zero overhead would make it ~6x. The figures to
-publish will come from the `oxmutate-bench.yml` lane on a runner nothing else shares.
+publish come from `bench/burgee-pair.mts`, run locally on a quiet machine: no mutation run happens
+in GitHub Actions (`D-20261101-no-mutation-in-gha`).
 
 ## Benchmarks
 

package/dist/child.js

@@ -14,11 +14,14 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ExitCode } from 'burgee';
+import { BEAT_ENV, beatFile, CPU_SAMPLE_MS } from './heartbeat.js';
 import { resolveEsm } from './resolve.js';
-import { ACTIVE_MUTANT_ENV, argv, env, exit } from './runtime.js';
+import { ACTIVE_MUTANT_ENV, argv, env, exit, pid } from './runtime.js';
 import { instrumentedSources } from './vite-plugin.js';
 const config = JSON.parse(readFileSync(argv[2] ?? '', 'utf8'));
 env['NODE_ENV'] ??= 'test';
+// Before Vitest starts any worker, so each one inherits it (heartbeat.ts).
+env[BEAT_ENV] = beatFile(path.dirname(config.instrumentedMap), pid);
 const vitestNode = (await import(resolveEsm('vitest/node', config.root)));
 const runner = fileURLToPath(new URL('./runner.js', import.meta.url));
 const silent = { onInit() { }, onFinished() { } };
@@ -142,5 +145,13 @@ process.on('message', (msg) => {
 // and a worker thread may still be looping in a mutant. Two such servers were found spinning at
 // 100% CPU 11 hours after their run ended, and slowed the next run 50x (2026-10-27).
 process.on('disconnect', () => exit(ExitCode.OK));
+// The server's CPU time, every thread (the test worker included), for the watchdog to tell an idle
+// stall from a loop (heartbeat.ts). This thread stays free while a worker loops, so the samples come.
+const sendCpu = () => {
+    const { user, system } = process.cpuUsage();
+    process.send?.({ type: 'cpu', at: Date.now(), us: user + system });
+};
+sendCpu();
+setInterval(sendCpu, CPU_SAMPLE_MS).unref();
 process.send?.({ type: 'ready' });
 //# sourceMappingURL=child.js.map

package/dist/coordinator.d.ts

@@ -36,10 +36,16 @@ export interface RunStats {
     instrumentMs: number;
     dryRunMs: number;
     mutationMs: number;
+    /** Static mutants decided in live workers (section 5b), between the warm and the isolated phases. */
+    staticMs: number;
+    /** Unarmed re-collections in that phase, the guard each live static verdict waits on (runner.ts). */
+    staticRecollections: number;
     isolatedMs: number;
     wallMs: number;
     testExecutions: number;
     watchdogKills: number;
+    /** Of `watchdogKills`, the stops whose worker was idle, waiting (heartbeat.ts). In an isolated run each is a Timeout as it stands. */
+    idleStalls: number;
     crashes: number;
     canaryFiles: number;
     /** Contexts restarted because a mutant left state behind (the per-execution canary fired). */

package/dist/coordinator.js

@@ -17,6 +17,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';
@@ -44,6 +45,8 @@ const sha = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
  * (2026-10-30). Smaller stays better for a pollution restart, which re-runs the rest of a unit.
  */
 const UNIT_PAIRS = 400;
+/** How many times its isolated budget a busy stop gets on its re-run. */
+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. */
@@ -61,8 +64,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}`);
@@ -93,8 +96,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 +108,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;
             }
@@ -563,6 +568,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);
@@ -646,7 +653,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)
@@ -665,7 +672,9 @@ export async function run(options) {
         // 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();
@@ -673,8 +682,12 @@ export async function run(options) {
         // 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);
+        // An idle stop is not re-run: its worker was waiting with its event loop turning and no CPU spent,
+        // on something the mutant never lets happen, which no budget cures; it is a Timeout as Stryker
+        // scores it. Re-run at 3x, 375 of them on caique's 10-31 run "finished" only because Vitest's 30 s
+        // test timeout failed the test (D-20261101-idle-stall-is-timeout, stall.qnt).
+        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,7 +702,7 @@ 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 ──────────────────────────────────────
@@ -706,8 +719,8 @@ export async function run(options) {
         // 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)
@@ -759,6 +772,7 @@ 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) {

package/dist/directives.js

@@ -0,0 +1,55 @@
+/**
+ * Stryker's range directives: a `disable` comment naming mutators (or `all`) and a reason turns them
+ * off from the next line on, until a `restore` comment naming them (either spelled with `Stryker` or
+ * `oxmutate`). The `next-line` form is config.ts's `disables`. Before this, oxmutate read only the
+ * `next-line` form and graded every mutant inside a range as if no directive were there: 116 such
+ * mutants in compat-oracle's `hosts.ts` alone (.sdlc/intents/oxmutate/sc8-profile.md).
+ *
+ * Read by line, as written. Stryker reads a directive only as the leading comment of the next AST
+ * node, so a `restore` that closes an object (`// Stryker restore all` above its `}`) is invisible to
+ * it, and its `disable` then runs to the end of the file. oxmutate does not reproduce that: the
+ * directive means what it says.
+ */
+const HEAD = /\/\/\s*(?:Stryker|oxmutate)\s+(disable|restore)\s+(\S.*)/i;
+/** `all`, or a comma list of mutator names. */
+const LIST = /^(?:all|\w+(?:\s*,\s*\w+)*)$/i;
+const covers = (r, mutator) => r.mutators === 'all' || r.mutators.includes(mutator);
+/** The range directives of a file. A `disable` without a reason is an error, as `next-line`'s is. */
+export function rangeDisables(source, file) {
+    const rules = [];
+    const errors = [];
+    source.split('\n').forEach((text, i) => {
+        const m = HEAD.exec(text);
+        if (!m)
+            return;
+        // `next-line` is not a list (the hyphen), so that form is left to config.ts here too.
+        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();
+            // The latest directive before the line that names this mutator decides it.
+            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;
+        },
+    };
+}
+//# sourceMappingURL=directives.js.map

package/dist/heartbeat.js

@@ -0,0 +1,111 @@
+/**
+ * The watchdog's evidence for the difference between a mutant that loops and one that hangs
+ * (.sdlc/intents/oxmutate/stall.qnt, D-20261101-idle-stall-is-timeout).
+ *
+ * Two readings, both taken when a run passes its budget:
+ *
+ * - **The beat.** The test worker writes the time to its server's beat file every HEARTBEAT_MS
+ *   from a real interval timer. The beat keeps coming only while the worker's event loop turns. A
+ *   synchronous loop stops it, and so does a microtask loop.
+ * - **The CPU.** The server reports its process's CPU time (every thread, the worker included)
+ *   every CPU_SAMPLE_MS. Over the last CPU_WINDOW_MS, a loop burns about a core.
+ *
+ * A run whose worker is inside a test body, with a fresh beat and under IDLE_CPU of a core, is
+ * **idle**: the test waits on something the mutant never lets happen (a prompt awaiting a
+ * keypress). Anything else is **busy**, including a worker still collecting its file: on a loaded
+ * machine a short budget can run out while modules load, at low CPU, and that is a slow machine. On a caique
+ * subset 18 of 19 stops read 0–2% CPU with a live beat, and the one loop read 72%
+ * (sc8-profile.md). An idle stop is a Timeout as it stands, the way Stryker scores it. A busy stop
+ * may be a slow test on a loaded machine, so it keeps its re-run at 3x.
+ *
+ * The beat file is the server's, named by its pid and set in its environment when it starts, so
+ * every worker it ever runs inherits it: a path set per unit could reach a worker that started
+ * under an earlier unit, and on caique two stops read a beat that never came.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/** How often the worker writes its beat. */
+export const HEARTBEAT_MS = 250;
+/** A beat older than this means the worker's event loop is not turning: a loop, not a wait. */
+export const STALE_MS = 1000;
+/** How often a server reports its CPU time. */
+export const CPU_SAMPLE_MS = 250;
+/** The window a stop's CPU share is measured over. */
+export const CPU_WINDOW_MS = 1000;
+/** The shortest span of samples a CPU share is read from; less, and the stop counts as busy. */
+export const MIN_CPU_SPAN_MS = 500;
+/** Under this share of one core, with a fresh beat, a stopped run is idle. Measured: idle 0–2%, a loop 72–108%. */
+export const IDLE_CPU = 0.25;
+/** The environment variable that hands a server's beat file to its test workers. */
+export const BEAT_ENV = 'OXMUTATE_BEAT';
+/** A server's beat file, in the run's work directory. */
+export const beatFile = (workDir, pid) => path.join(workDir, `beat-${String(pid)}`);
+// Captured when this module is evaluated, before any test file can install fake timers: a faked
+// clock would write a frozen time, and the watchdog would read a live worker as a stale one.
+const { setInterval: realSetInterval, clearInterval: realClearInterval } = globalThis;
+const realNow = Date.now.bind(Date);
+/** The beat this thread runs: one at a time, whatever re-evaluates this module. */
+// Stryker disable next-line StringLiteral: any key names one registry symbol on every evaluation of this module, which is all the key is for
+const BEAT_KEY = Symbol.for('oxmutate.heartbeat');
+/** Whether a test body is running in this worker (the runner marks it); the beat carries it. */
+let inTest = false;
+/** Mark a test body as running, or done. Only a wait inside a test body can be an idle stall. */
+export function markTest(running) {
+    inTest = running;
+}
+/** Start this worker's beat into `file`. Does nothing when no beat file is set. */
+export function startHeartbeat(file) {
+    if (!file)
+        return;
+    const holder = globalThis;
+    realClearInterval(holder[BEAT_KEY]);
+    /** One beat; false once the run's directory is gone: the run is over, and nothing reads the beat. */
+    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);
+    // Stryker disable next-line CallExpression: unref only lets a process exit while its beat runs; Vitest ends its workers regardless, so no verdict depends on it
+    holder[BEAT_KEY].unref();
+}
+/** The last beat of this server's workers. */
+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;
+/**
+ * The share of one core a server used over the last CPU_WINDOW_MS before `now`, from its samples
+ * (oldest first). Undefined when the samples span less than MIN_CPU_SPAN_MS of that window.
+ */
+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);
+    // Stryker disable next-line LogicalOperator: the first and the last sample are both there or both missing, so `&&` reads the same
+    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);
+}
+/** A stopped run is idle when its worker waits inside a test body, its event loop turning, and its server burns almost no CPU. */
+export function classifyStall(o) {
+    return o.beat.inTest && o.beat.age < STALE_MS && (o.cpuShare ?? IDLE_CPU) < IDLE_CPU ? 'idle' : 'busy';
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/reports.js

@@ -142,7 +142,7 @@ export function textSummary(r, opts = {}) {
         `oxmutate ${VERSION}: ${String(r.mutants.length)} mutants in ${String(s.files)} files, ${(s.wallMs / MS_PER_S).toFixed(1)} s`,
         `  mutation score ${r.score.mutationScore.toFixed(2)}% (covered ${r.score.covered.toFixed(2)}%)`,
         `  killed ${String(count('Killed'))} · timeout ${String(count('Timeout'))} · survived ${String(count('Survived'))} · no coverage ${String(count('NoCoverage'))} · ignored ${String(count('Ignored'))} · errors ${String(count('RuntimeError') + count('CompileError'))}`,
-        `  instrument ${s.instrumentMs.toFixed(0)} ms · dry run ${(s.dryRunMs / MS_PER_S).toFixed(1)} s · mutants ${(s.mutationMs / MS_PER_S).toFixed(1)} s · isolated ${(s.isolatedMs / MS_PER_S).toFixed(1)} s`,
+        `  instrument ${s.instrumentMs.toFixed(0)} ms · dry run ${(s.dryRunMs / MS_PER_S).toFixed(1)} s · mutants ${(s.mutationMs / MS_PER_S).toFixed(1)} s · static ${(s.staticMs / MS_PER_S).toFixed(1)} s · isolated ${(s.isolatedMs / MS_PER_S).toFixed(1)} s`,
     ];
     const corrected = corrections(s);
     if (corrected.length)

package/dist/runner.js

@@ -25,6 +25,7 @@
 import { appendFileSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { BEAT_ENV, markTest, startHeartbeat } from './heartbeat.js';
 import { resolveEsm } from './resolve.js';
 import { ACTIVE_MUTANT_ENV, FILE_KEY, NAMESPACE, cwd, env } from './runtime.js';
 /**
@@ -65,6 +66,7 @@ const { Base, statics } = await loadBase();
 const mode = env['OXMUTATE_MODE'] ?? 'dry';
 const resultsPath = env['OXMUTATE_RESULTS'];
 const progressPath = env['OXMUTATE_PROGRESS'];
+startHeartbeat(env[BEAT_ENV]); // the watchdog tells a wait from a loop by it (heartbeat.ts)
 const ns = (globalThis[NAMESPACE] ??= {});
 ns.mutantCoverage ??= { static: {}, perTest: {} };
 const plan = mode === 'mutant' && env['OXMUTATE_PLAN'] ? JSON.parse(readFileSync(env['OXMUTATE_PLAN'], 'utf8')) : { tests: {}, hitLimits: {}, skip: [] };
@@ -123,6 +125,8 @@ const sameSnapshot = (a, b) => snapshotDiff(a, b).length === 0;
 let pristine;
 /** Set when a mutant left state behind; the rest of this context runs no mutants. */
 let polluted = false;
+/** `static` mode: the most mutants decided between two unarmed re-collections (staticwarm.qnt `grouped`). */
+const STATIC_CANARY_MAX = 4;
 /** Mutants between canaries; doubles while the canary stays clean, back to 1 when it fails. */
 let canaryEvery = 1;
 const MAX_CANARY_EVERY = 8;
@@ -249,7 +253,14 @@ export default class OxmutateRunner extends Base {
         if (mode !== 'mutant') {
             if (only && !only.has(test.id))
                 return;
-            await fn();
+            // Only a wait inside a test body can be an idle stall; collection at low CPU is a slow machine.
+            markTest(true);
+            try {
+                await fn();
+            }
+            finally {
+                markTest(false);
+            }
             return;
         }
         const context = test.context;
@@ -428,22 +439,40 @@ export default class OxmutateRunner extends Base {
                 ns.hitLimit = undefined;
             }
         };
+        // Verdicts since the last clean unarmed re-collection are held, not emitted: the re-collection runs
+        // after the first mutant, then after every 2, then every STATIC_CANARY_MAX while it stays clean, and
+        // one that fails sends every held mutant back with the rest. Each mutant's own snapshot diff still
+        // runs at once. The re-collection runs the file's tests unarmed, and after every mutant it was half
+        // of the live static phase, 6,713 s of compat-oracle's 11,193 s weekly run (sc8-profile.md,
+        // staticwarm.qnt `grouped`).
+        let held = [];
+        let every = 1;
+        const back = (reason, keys = []) => {
+            rest.unshift(...held.map((h) => h.id));
+            held = [];
+            fallback(reason, keys);
+        };
         while (rest.length) {
-            const id = rest[0];
+            const id = rest.shift();
             if (progressPath)
                 writeFileSync(progressPath, `${id} ${String(Date.now())}\n`);
-            const verdict = await evaluate(id);
+            held.push({ id, verdict: await evaluate(id) });
             const left = snapshotDiff(before, snapshot());
             if (left.length)
-                return fallback('the mutant left a trace', left);
+                return back('the mutant left a trace', left);
+            if (held.length < every && rest.length)
+                continue;
             const unarmed = await evaluate(undefined);
+            emit({ type: 'recollection' });
             if (unarmed.failed.length > 0)
-                return fallback('the unarmed re-collection failed', unarmed.error ? [unarmed.error] : []);
+                return back('the unarmed re-collection failed', unarmed.error ? [unarmed.error] : []);
             const after = snapshotDiff(before, snapshot());
             if (after.length)
-                return fallback('the unarmed re-collection left a trace', after);
-            rest.shift();
-            emit({ type: 'isolated', id, killed: verdict.failed.length > 0 && !verdict.timeout, failed: verdict.failed, ran: verdict.ran, ...(verdict.timeout && { timeout: true }) });
+                return back('the unarmed re-collection left a trace', after);
+            for (const { id: done, verdict } of held)
+                emit({ type: 'isolated', id: done, killed: verdict.failed.length > 0 && !verdict.timeout, failed: verdict.failed, ran: verdict.ran, ...(verdict.timeout && { timeout: true }) });
+            held = [];
+            every = Math.min(STATIC_CANARY_MAX, every * 2);
         }
         if (progressPath)
             writeFileSync(progressPath, '');

package/dist/runtime.js

@@ -18,6 +18,7 @@ export const ACTIVE_MUTANT_ENV = '__OXMUTATE_ACTIVE_MUTANT__';
 // place the package touches it. `env` is the live object: a write here is a write to the process.
 export const env = process.env;
 export const argv = process.argv;
+export const pid = process.pid;
 export const cwd = () => process.cwd();
 export const stderr = process.stderr;
 export const exit = (code) => process.exit(code);

package/dist/scheduler.js

@@ -12,6 +12,8 @@ import { fork } from 'node:child_process';
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { beatFile, classifyStall, CPU_WINDOW_MS, cpuShare, readBeat } from './heartbeat.js';
+import { env, stderr } from './runtime.js';
 const childJs = fileURLToPath(new URL('./child.js', import.meta.url));
 /** The tail of a server's stderr kept for an error message. */
 const STDERR_TAIL = 4000;
@@ -28,15 +30,23 @@ function inFlight(progress) {
         return undefined;
     }
 }
+const PERCENT = 100;
+/** How many CPU samples a server keeps: a little over the window. */
+const CPU_SAMPLES_KEPT = 8;
 class Server {
     child;
     ready;
     stderr = '';
+    /** Where this server's test workers beat (heartbeat.ts). */
+    beat;
+    /** The server's latest CPU readings, oldest first (child.ts sends them). */
+    cpu = [];
     onMessage;
     onExit;
     exited = false;
-    constructor(configFile, cwd, execArgv) {
+    constructor(configFile, cwd, execArgv, workDir) {
         this.child = fork(childJs, [configFile], { cwd, stdio: ['ignore', 'ignore', 'pipe', 'ipc'], execArgv });
+        this.beat = beatFile(workDir, this.child.pid);
         this.child.stderr?.on('data', (d) => (this.stderr = (this.stderr + d.toString()).slice(-STDERR_TAIL)));
         this.ready = new Promise((resolve) => {
             const first = (m) => {
@@ -48,7 +58,15 @@ class Server {
             this.child.on('message', first);
             this.child.once('exit', () => resolve(false));
         });
-        this.child.on('message', (m) => this.onMessage?.(m));
+        this.child.on('message', (m) => {
+            if (m.type === 'cpu') {
+                this.cpu.push({ at: m.at ?? 0, us: m.us ?? 0 });
+                if (this.cpu.length > CPU_SAMPLES_KEPT)
+                    this.cpu.shift();
+                return;
+            }
+            this.onMessage?.(m);
+        });
         this.child.once('exit', (code) => {
             this.exited = true;
             this.onExit?.(code);
@@ -78,9 +96,18 @@ class Server {
                 if (!line)
                     return;
                 const [id = '', since = '0'] = line.split(' ');
-                if (Date.now() - Number(since) > budget(id)) {
+                const now = Date.now();
+                if (now - Number(since) > budget(id)) {
+                    // Read before the kill: an idle stop is a Timeout as it stands, a busy one is re-run (heartbeat.ts).
+                    const beat = readBeat(this.beat, now);
+                    const share = cpuShare(this.cpu, now);
+                    const stall = classifyStall({ beat, cpuShare: share });
+                    if (env['OXMUTATE_DEBUG_WATCHDOG']) {
+                        const cpu = share === undefined ? '?' : `${String(Math.round(share * PERCENT))}%`;
+                        stderr.write(`oxmutate watchdog: stop ${id} after ${String(now - Number(since))} ms; ${stall}; beat ${Number.isFinite(beat.age) ? `${String(beat.age)} ms ago` : 'never'}${beat.inTest ? ' in a test' : ''}; cpu ${cpu} over ${String(CPU_WINDOW_MS)} ms\n`);
+                    }
                     this.child.kill('SIGKILL');
-                    finish({ killedFor: id, stderr: this.stderr });
+                    finish({ killedFor: id, stall, stderr: this.stderr });
                 }
             }, WATCHDOG_POLL_MS);
             this.onMessage = (m) => {
@@ -104,13 +131,21 @@ class Server {
 export function createPool(config, size, workDir, tag) {
     const configFile = path.join(workDir, `server-${tag}.json`);
     writeFileSync(configFile, JSON.stringify(config));
-    const stats = { spawned: 0, killed: 0, crashed: 0 };
+    const stats = { spawned: 0, killed: 0, idle: 0, crashed: 0 };
     const spawn = () => {
         stats.spawned++;
-        return new Server(configFile, config.root, config.nodeArgs ?? []);
+        return new Server(configFile, config.root, config.nodeArgs ?? [], workDir);
     };
     const servers = Array.from({ length: size }, spawn);
     let spare = spawn();
+    const tally = (outcome) => {
+        if (outcome.killedFor)
+            stats.killed++;
+        if (outcome.stall === 'idle')
+            stats.idle++;
+        if (outcome.crashed)
+            stats.crashed++;
+    };
     const replacement = () => {
         const next = spare ?? spawn();
         spare = spawn();
@@ -152,10 +187,7 @@ export function createPool(config, size, workDir, tag) {
                         await server.ready;
                     }
                     const outcome = await server.run(unit, (id) => budget(unit, id));
-                    if (outcome.killedFor)
-                        stats.killed++;
-                    if (outcome.crashed)
-                        stats.crashed++;
+                    tally(outcome);
                     if (outcome.killedFor || outcome.crashed) {
                         servers[slot] = replacement();
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxmutate",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Mutation testing for JavaScript and TypeScript on the oxc engine, run warm inside the project's own Vitest, with CI lanes, SARIF and an agent surface. No dependency outside the burgee family. A Stryker migration path.",
   "license": "MIT",
   "repository": {