testguard-cli 0.14.1 → 0.15.0

package/src/probe/runners/index.mjs

@@ -2,6 +2,7 @@ import * as vitest from './vitest.mjs';
 import * as jest from './jest.mjs';
 import * as playwright from './playwright.mjs';
 import * as pythonRunner from './python.mjs';
+import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs } from './discovery.mjs';
 
 export const RUNNERS = {
   vitest,
@@ -27,15 +28,42 @@ export const RUNNER_NAMES = ['vitest', 'jest', 'playwright', 'python', 'pytest',
  */
 export const OWNED_RUNNERS = [playwright, pythonRunner];
 
+const PYTHON_DISCOVERY_CONFIG_FILES = ['pyproject.toml', 'pytest.ini', 'setup.cfg', 'tox.ini', 'conftest.py'];
+
+const immutableManifest = (manifest) => Object.freeze({
+  ...manifest,
+  runner: Object.freeze({ ...manifest.runner }),
+  files: Object.freeze([...manifest.files]),
+  configFiles: Object.freeze(manifest.configFiles.map((entry) => Object.freeze({ ...entry }))),
+});
+
+export async function discoverRunnerManifest(runner, check, projectDir, budgetMs) {
+  let manifest;
+  if (runner.discoverTests) {
+    manifest = await runner.discoverTests({ projectDir, version: check.version, ...(budgetMs === undefined ? {} : { timeoutMs: budgetMs }) });
+    return immutableManifest(manifest);
+  }
+  // Python's adapter discovery is already language-aware but is not a native
+  // subprocess listing yet. Bind its immutable universe to every conventional
+  // pytest configuration input so it cannot be reused across a config edit.
+  const before = hashDiscoveryConfigs(projectDir, PYTHON_DISCOVERY_CONFIG_FILES);
+  const files = runner.tests(projectDir);
+  const configFiles = hashDiscoveryConfigs(projectDir, PYTHON_DISCOVERY_CONFIG_FILES);
+  if (JSON.stringify(configFiles) !== JSON.stringify(before)) throw new DiscoveryError(`${runner.name} discovery config changed while tests were being listed`);
+  manifest = createDiscoveryManifest({ runner: runner.name, version: check.version, files, configFiles, source: 'adapter' });
+  return immutableManifest(manifest);
+}
+
 /**
  * Pick the project runner: an explicit name, or the first of vitest, jest,
  * python that is resolvable from the project. Returns
- * { runner, version, source, engine } or { error }. `engine` is set when the
- * runner has more than one (Python: pytest or unittest) and names the one
- * that will actually run — it, not the module name, is what the evidence
- * records.
+ * { runner, version, source, engine, manifest, testFiles } only after the
+ * runner's immutable non-empty test universe is known, or { error }. `engine`
+ * is set when the runner has more than one (Python: pytest or unittest) and
+ * names the one that will actually run — it, not the module name, is what the
+ * evidence records.
  */
-export async function selectRunner({ projectDir, sourceDir, python, name = 'auto' }) {
+export async function selectRunner({ projectDir, sourceDir, python, name = 'auto', budgetMs, budgetFor }) {
   const candidates = name === 'auto' ? [vitest, jest, pythonRunner] : [RUNNERS[name]];
   if (!candidates[0]) return { error: `unknown runner "${name}"; use ${RUNNER_NAMES.join(', ')} or auto` };
   const messages = [];
@@ -46,24 +74,28 @@ export async function selectRunner({ projectDir, sourceDir, python, name = 'auto
   // `nocover`: a damning statement about the project produced by a runner that
   // could not have seen its tests.
   //
-  // So `auto` prefers a candidate that can actually see tests. An explicitly
-  // named runner is still honoured, because the caller asked for it; it is
-  // reported with `testFiles` so a caller can say what it is working with.
-  let blind = null;
+  // So `auto` prefers a candidate that can actually see tests. An explicit
+  // runner with an empty universe is also refused: choosing it knowingly does
+  // not turn zero observations into evidence.
   for (const r of candidates) {
-    const c = await r.check({ projectDir, sourceDir, python });
+    const checkBudget = budgetFor ? budgetFor() : budgetMs;
+    const c = await r.check({ projectDir, sourceDir, python, budgetFor, ...(checkBudget === undefined ? {} : { budgetMs: checkBudget }) });
     if (!c.ok) { messages.push(`${r.name}: ${c.message}`); continue; }
-    const selected = { runner: r, version: c.version, source: c.source, engine: c.engine };
-    let testFiles = 0;
-    try { testFiles = r.tests(projectDir).length; } catch { testFiles = 0; }
+    let selected = { runner: r, version: c.version, source: c.source, engine: c.engine };
+    let manifest;
+    try {
+      manifest = await discoverRunnerManifest(r, c, projectDir, budgetFor ? budgetFor() : budgetMs);
+    } catch (error) {
+      return { error: `${r.name}: test discovery failed: ${error.message}` };
+    }
+    selected = { ...selected, manifest };
+    const testFiles = manifest.files.length;
+    const empty = `${r.name}: resolved but discovered no test files`;
+    if (name !== 'auto' && testFiles === 0) return { error: empty };
     if (testFiles > 0 || name !== 'auto') return { ...selected, testFiles };
-    blind ??= { ...selected, testFiles: 0 };
-    messages.push(`${r.name}: resolved but matched no test files`);
+    messages.push(empty);
   }
-  // Nothing saw a test file. Return the first that resolved, and say plainly
-  // what that means, rather than letting every verdict read as a finding.
-  if (blind) return { ...blind, warning: `no runner matched a test file in this project; using ${blind.runner.name}, which sees none — every verdict will be nocover` };
-  return { error: messages.join('; ') };
+  return { error: messages.length ? messages.join('; ') : 'no runner discovered test files' };
 }
 
 /** What the evidence calls a runner: the engine that actually ran, else the module's name. */

package/src/probe/runners/jest.mjs

@@ -1,10 +1,41 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { TEST_GLOBS, runProcess, checkRunner, runnerArgv, listTestFiles } from './shared.mjs';
+import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs, normalizeDiscoveredFiles, runDiscoveryProcess } from './discovery.mjs';
 
 export const name = 'jest';
 // jest's default testMatch also collects anything under __tests__/.
 export const testGlobs = [...TEST_GLOBS, '**/__tests__/**/*.js', '**/__tests__/**/*.mjs', '**/__tests__/**/*.cjs', '**/__tests__/**/*.ts', '**/__tests__/**/*.tsx', '**/__tests__/**/*.jsx'];
-export const check = (opts) => checkRunner({ ...opts, pkg: 'jest', bin: 'jest' });
+const DISCOVERY_CONFIG_FILES = ['js', 'mjs', 'cjs', 'ts', 'cts', 'json'].map((ext) => `jest.config.${ext}`);
+export async function check(opts) {
+  const result = await checkRunner({ ...opts, pkg: 'jest', bin: 'jest' });
+  if (!result.ok) return result;
+  const hasProjectConfig = ['package.json', ...DISCOVERY_CONFIG_FILES].some((file) => existsSync(join(opts.projectDir, file)));
+  return hasProjectConfig ? result : { ok: false, message: 'no package.json or jest.config.* in the project' };
+}
 export const tests = (projectDir) => listTestFiles(projectDir, testGlobs);
+/** Ask Jest itself to load config/projects and enumerate the files it would collect. */
+export const discoveryArgvFor = (projectDir) => [...runnerArgv(projectDir, 'jest', 'jest'), '--listTests', '--json', '--runInBand'];
+
+export function parseDiscoveryOutput(stdout) {
+  let files;
+  try {
+    files = JSON.parse(stdout);
+  } catch (error) {
+    throw new DiscoveryError(`Jest discovery output is not valid JSON: ${error.message}`, { cause: error });
+  }
+  if (!Array.isArray(files)) throw new DiscoveryError('Jest discovery output must be a JSON array');
+  return files;
+}
+
+export async function discoverTests({ projectDir, version, timeoutMs, maxOutputBytes } = {}) {
+  const before = hashDiscoveryConfigs(projectDir, DISCOVERY_CONFIG_FILES);
+  const result = await runDiscoveryProcess({ projectDir, argv: discoveryArgvFor(projectDir), timeoutMs, maxOutputBytes });
+  const configFiles = hashDiscoveryConfigs(projectDir, DISCOVERY_CONFIG_FILES);
+  if (JSON.stringify(configFiles) !== JSON.stringify(before)) throw new DiscoveryError('Jest discovery config changed while tests were being listed');
+  const files = normalizeDiscoveredFiles(projectDir, parseDiscoveryOutput(result.stdout));
+  return createDiscoveryManifest({ runner: name, version, files, configFiles });
+}
 // --runTestsByPath: positionals are exact paths, not regexes — a path with `+` or `(` would otherwise silently match nothing.
 /** The command line, as data. Exported so it is falsifiable without spawning anything. */
 export const argvFor = (projectDir, files, outFile, { serial = false } = {}) =>

package/src/probe/runners/playwright.mjs

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join, relative, resolve, sep } from 'node:path';
-import { npx, runProcess, listTestFiles, firstInformativeLine } from './shared.mjs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { npx, runProcess, listTestFiles, firstInformativeLine, runnerArgv } from './shared.mjs';
+import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs, normalizeDiscoveredFiles, runDiscoveryReportProcess } from './discovery.mjs';
 import { globToRegExp } from '../../util/glob.mjs';
 
 /**
@@ -88,6 +89,61 @@ export async function check({ projectDir }) {
 }
 
 export const tests = (projectDir) => listTestFiles(projectDir, SPEC_GLOBS).filter((f) => owns(projectDir, f));
+const DISCOVERY_CONFIG_FILES = ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'].map((ext) => `playwright.config.${ext}`);
+
+/** Ask Playwright itself to load config/projects and list without executing. */
+export const discoveryArgvFor = (projectDir) => [...runnerArgv(projectDir, '@playwright/test', 'playwright'), 'test', '--list', '--reporter=json'];
+
+export function parseDiscoveryReport(report) {
+  if (report == null || typeof report !== 'object' || Array.isArray(report) || !Array.isArray(report.suites)) {
+    throw new DiscoveryError('Playwright discovery report must contain a suites array');
+  }
+  if (report.errors !== undefined && !Array.isArray(report.errors)) {
+    throw new DiscoveryError('Playwright discovery report errors must be an array');
+  }
+  if (Array.isArray(report.errors) && report.errors.length > 0) {
+    const message = report.errors.map((error) => error?.message ?? String(error)).find(Boolean);
+    throw new DiscoveryError(`Playwright discovery failed${message ? `: ${firstInformativeLine(message)}` : ''}`);
+  }
+  const files = [];
+  const walk = (suite) => {
+    if (typeof suite?.file === 'string' && suite.file.length > 0) files.push(suite.file);
+    for (const spec of suite?.specs ?? []) {
+      if (typeof spec?.file === 'string' && spec.file.length > 0) files.push(spec.file);
+    }
+    for (const child of suite?.suites ?? []) walk(child);
+  };
+  for (const suite of report.suites) walk(suite);
+  return files;
+}
+
+export async function discoverTests({ projectDir, version, timeoutMs, maxOutputBytes } = {}) {
+  const before = hashDiscoveryConfigs(projectDir, DISCOVERY_CONFIG_FILES);
+  const { report } = await runDiscoveryReportProcess({
+    projectDir,
+    argv: discoveryArgvFor(projectDir),
+    timeoutMs,
+    maxOutputBytes,
+    env: { PLAYWRIGHT_JSON_OUTPUT_FILE: '{out}', PLAYWRIGHT_JSON_OUTPUT_NAME: '{out}' },
+  });
+  const configFiles = hashDiscoveryConfigs(projectDir, DISCOVERY_CONFIG_FILES);
+  if (JSON.stringify(configFiles) !== JSON.stringify(before)) throw new DiscoveryError('Playwright discovery config changed while tests were being listed');
+  const cfg = loadConfig(projectDir);
+  const reported = parseDiscoveryReport(report).map((file) => {
+    if (isAbsolute(file)) return file;
+    const fromRoot = resolve(projectDir, file);
+    const fromTestDir = resolve(projectDir, cfg?.testDir ?? '.', file);
+    const rootExists = existsSync(fromRoot);
+    const testDirExists = existsSync(fromTestDir);
+    if (rootExists && testDirExists && fromRoot !== fromTestDir) {
+      throw new DiscoveryError(`Playwright discovery path is ambiguous between the project and testDir: ${file}`);
+    }
+    if (testDirExists) return fromTestDir;
+    return file;
+  });
+  const files = normalizeDiscoveredFiles(projectDir, reported);
+  return createDiscoveryManifest({ runner: name, version, files, configFiles });
+}
 
 /**
  * Playwright's JSON report → the spec's testRun. Pure; exported for the

package/src/probe/runners/python.mjs

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { runProcess, listTestFiles, firstInformativeLine } from './shared.mjs';
+import { runProcess, listTestFiles, firstInformativeLine, terminateProcessTree } from './shared.mjs';
 
 /**
  * The Python runner. Selected **per file**: any `.py` defender runs here
@@ -116,7 +116,7 @@ function ask(path, budgetMs) {
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(path, ['-c', PROBE], { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, CI: '1' } });
+      child = spawn(path, ['-c', PROBE], { stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32', env: { ...process.env, CI: '1' } });
     } catch {
       return resolve(null);
     }
@@ -124,7 +124,7 @@ function ask(path, budgetMs) {
     child.on('error', () => resolve(null));
     child.stdout.on('data', (d) => (out += d));
     child.stderr.on('data', () => {});
-    const timer = setTimeout(() => child.kill('SIGKILL'), budgetMs);
+    const timer = setTimeout(() => terminateProcessTree(child), budgetMs);
     child.on('close', (code) => {
       clearTimeout(timer);
       if (code !== 0) return resolve(null);
@@ -145,14 +145,14 @@ function ask(path, budgetMs) {
  * meant to be — never copied and never symlinked, which would break the
  * `pyvenv.cfg` prefix detection that makes one work at all.
  */
-export function resolveInterpreter({ projectDir, python, budgetMs = 30_000 }) {
+export function resolveInterpreter({ projectDir, python, budgetMs = 30_000, budgetFor }) {
   const key = `${projectDir}\0${python ?? ''}`;
   if (interpreters.has(key)) return interpreters.get(key);
   const task = (async () => {
     const tried = [];
     for (const candidate of candidates(projectDir, python)) {
       if (!candidate.explicit && candidate.source === 'project' && !existsSync(candidate.path)) continue;
-      const answer = await ask(candidate.path, budgetMs);
+      const answer = await ask(candidate.path, budgetFor ? budgetFor() : budgetMs);
       if (answer) return { ...candidate, ...answer };
       tried.push(candidate.path);
     }
@@ -189,10 +189,10 @@ export function chooseEngine(pinned, found) {
 }
 
 export function makeCheck(pinned) {
-  return async ({ projectDir, sourceDir, python, budgetMs = 30_000 }) => {
+  return async ({ projectDir, sourceDir, python, budgetMs = 30_000, budgetFor }) => {
     // Always the ORIGINAL project directory when there is one: a virtualenv is
     // gitignored, so the scratch worktree does not contain it.
-    const found = await resolveInterpreter({ projectDir: sourceDir ?? projectDir, python, budgetMs });
+    const found = await resolveInterpreter({ projectDir: sourceDir ?? projectDir, python, budgetMs, budgetFor });
     if (found.error) return { ok: false, message: found.error };
     const chosen = chooseEngine(pinned, found);
     if (!chosen.ok) return chosen;

package/src/probe/runners/shared.mjs

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname } from 'node:path';
@@ -14,6 +14,50 @@ export const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
 /** Node's own advisory warnings about the probed project's configuration; never about the fault. */
 export const NODE_NOISE = /MODULE_TYPELESS_PACKAGE_JSON|ExperimentalWarning|--trace-warnings|Reparsing as ES module|To eliminate this warning/;
 
+function descendantPids(rootPid) {
+  if (process.platform === 'win32') return [];
+  const result = spawnSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8' });
+  if (result.status !== 0) return [];
+  const children = new Map();
+  for (const line of result.stdout.split('\n')) {
+    const [pid, ppid] = line.trim().split(/\s+/).map(Number);
+    if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
+    if (!children.has(ppid)) children.set(ppid, []);
+    children.get(ppid).push(pid);
+  }
+  const out = [];
+  const visit = (pid) => { for (const child of children.get(pid) ?? []) { visit(child); out.push(child); } };
+  visit(rootPid);
+  return out;
+}
+
+export const TIMEOUT_CLEANUP_WARNING = 'cleanup-unverified: TestGuard hard-killed the runner process group and descendants still attributable at timeout, but an already-reparented daemon may survive; use an OS or container containment boundary for daemonizing or untrusted commands';
+
+/**
+ * Best-effort runner cleanup. POSIX process groups plus a PPID snapshot cover
+ * ordinary descendants and a still-attributable detached child. Node exposes
+ * no portable cgroup/job-object/subreaper primitive, so a daemon that already
+ * reparented cannot be proven dead here. Callers must keep the result a
+ * timeout and surface TIMEOUT_CLEANUP_WARNING rather than claiming containment.
+ */
+export function terminateProcessTree(child) {
+  if (!child.pid) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    try { child.kill('SIGKILL'); } catch {}
+    return;
+  }
+  // Freeze the main group before enumerating so it cannot fork between the
+  // snapshot and the kill. A deliberately detached descendant is outside the
+  // group but remains visible through PPID and is killed explicitly.
+  try { process.kill(-child.pid, 'SIGSTOP'); } catch {}
+  for (const pid of descendantPids(child.pid)) {
+    try { process.kill(pid, 'SIGKILL'); } catch {}
+  }
+  try { process.kill(-child.pid, 'SIGKILL'); } catch {}
+  try { child.kill('SIGKILL'); } catch {}
+}
+
 /**
  * Split a runner command template into argv. Supports double and single
  * quotes; `{files}` expands to the test files (one argv entry each) and
@@ -94,7 +138,12 @@ export function checkRunner({ projectDir, pkg, bin, budgetMs = 60_000, env = pro
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn(process.platform === 'win32' ? `${bin}.cmd` : bin, ['--version'], { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], env: { ...env, CI: '1' } });
+      child = spawn(process.platform === 'win32' ? `${bin}.cmd` : bin, ['--version'], {
+        cwd: projectDir,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: process.platform !== 'win32',
+        env: { ...env, CI: '1' },
+      });
     } catch (e) {
       return resolve({ ok: false, message: e.message });
     }
@@ -103,7 +152,7 @@ export function checkRunner({ projectDir, pkg, bin, budgetMs = 60_000, env = pro
     child.on('error', () => resolve({ ok: false, message: `${pkg} is not installed in the project and \`${bin}\` is not on PATH (npm i -D ${pkg})` }));
     child.stdout.on('data', (d) => (out += d));
     child.stderr.on('data', (d) => (err += d));
-    const timer = setTimeout(() => child.kill('SIGKILL'), budgetMs);
+    const timer = setTimeout(() => terminateProcessTree(child), budgetMs);
     child.on('close', (code) => {
       clearTimeout(timer);
       const version = out.trim().replace(/^vitest\//, '').replace(/^Version\s+/i, '').split('\n').pop();
@@ -183,7 +232,7 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
   const started = Date.now();
 
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, CI: '1', FORCE_COLOR: '0', ...extraEnv } });
+    const child = spawn(cmd, args, { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32', env: { ...process.env, CI: '1', FORCE_COLOR: '0', ...extraEnv } });
     let stderr = '';
     // Node prints MODULE_TYPELESS_PACKAGE_JSON (and friends) for the PROBED
     // project's config, not for anything the fault did. Keep it out of the
@@ -193,7 +242,7 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
     let killed = false;
     const timer = setTimeout(() => {
       killed = true;
-      child.kill('SIGKILL');
+      terminateProcessTree(child);
     }, budgetMs);
 
     child.on('close', () => {
@@ -201,7 +250,7 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
       const durationMs = Date.now() - started;
       let result;
       if (killed) {
-        result = { run: { outcome: 'timeout', tests: { total: 0, passed: 0, failed: 0 }, assertionFailures: 0, durationMs }, timeouts: 1, loadMessage: `budget of ${budgetMs}ms exceeded`, failedTests: [] };
+        result = { run: { outcome: 'timeout', tests: { total: 0, passed: 0, failed: 0 }, assertionFailures: 0, durationMs }, timeouts: 1, loadMessage: `budget of ${budgetMs}ms exceeded; ${TIMEOUT_CLEANUP_WARNING}`, failedTests: [] };
       } else if (!existsSync(outFile)) {
         result = { run: { outcome: 'error', tests: { total: 0, passed: 0, failed: 0 }, assertionFailures: 0, durationMs }, timeouts: 0, loadMessage: stderr.trim().split('\n').filter(Boolean).slice(-1)[0] ?? 'runner produced no report', failedTests: [] };
       } else {

package/src/probe/runners/vitest.mjs

@@ -1,9 +1,30 @@
 import { TEST_GLOBS, runProcess, checkRunner, runnerArgv, listTestFiles } from './shared.mjs';
+import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs, normalizeDiscoveredFiles, runDiscoveryProcess } from './discovery.mjs';
 
 export const name = 'vitest';
 export const testGlobs = TEST_GLOBS;
 export const check = (opts) => checkRunner({ ...opts, pkg: 'vitest', bin: 'vitest' });
 export const tests = (projectDir) => listTestFiles(projectDir, testGlobs);
+const DISCOVERY_CONFIG_FILES = [
+  ...['js', 'mjs', 'cjs', 'ts', 'mts', 'cts'].flatMap((ext) => [`vitest.config.${ext}`, `vite.config.${ext}`, `vitest.workspace.${ext}`]),
+  'vitest.workspace.json',
+];
+/** Ask Vitest itself to load config and enumerate the files it would collect. */
+export const discoveryArgvFor = (projectDir) => [...runnerArgv(projectDir, 'vitest', 'vitest'), 'list', '--filesOnly', '--passWithNoTests'];
+
+export function parseDiscoveryOutput(stdout) {
+  if (typeof stdout !== 'string') throw new TypeError('Vitest discovery output must be text');
+  return stdout.split(/\r?\n/).filter((line) => line.length > 0);
+}
+
+export async function discoverTests({ projectDir, version, timeoutMs, maxOutputBytes } = {}) {
+  const before = hashDiscoveryConfigs(projectDir, DISCOVERY_CONFIG_FILES);
+  const result = await runDiscoveryProcess({ projectDir, argv: discoveryArgvFor(projectDir), timeoutMs, maxOutputBytes });
+  const configFiles = hashDiscoveryConfigs(projectDir, DISCOVERY_CONFIG_FILES);
+  if (JSON.stringify(configFiles) !== JSON.stringify(before)) throw new DiscoveryError('Vitest discovery config changed while tests were being listed');
+  const files = normalizeDiscoveredFiles(projectDir, parseDiscoveryOutput(result.stdout));
+  return createDiscoveryManifest({ runner: name, version, files, configFiles });
+}
 // --serial: one file at a time in one process, so a contended machine cannot turn a slow suite into a TIMEOUT verdict.
 /** The command line, as data. Exported so it is falsifiable without spawning anything. */
 export const argvFor = (projectDir, files, outFile, { serial = false } = {}) =>

package/src/replay/replay.mjs

@@ -3,9 +3,9 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { git, GitError, repoRoot, headSha } from '../git.mjs';
 import { createScratch, PreconditionError } from '../probe/worktree.mjs';
-import { selectRunner, RUNNERS } from '../probe/runners/index.mjs';
+import { selectRunner, discoverRunnerManifest, RUNNERS, OWNED_RUNNERS, mergeRuns } from '../probe/runners/index.mjs';
 import { parseCommandTemplate } from '../probe/runners/shared.mjs';
-import { fileImports } from '../probe/rank.mjs';
+import { fileImportRelation } from '../probe/rank.mjs';
 import { IS_PY_TEST, pyFileImports } from '../probe/pyimports.mjs';
 import { isPython } from '../probe/discover.mjs';
 import { labelDiff } from './label.mjs';
@@ -83,6 +83,7 @@ export async function replay({
   range,
   confirmRuns = 3,
   budgetMs = 120_000,
+  commandBudget,
   runnerCommand,
   runnerName = 'auto',
   nodeModules,
@@ -92,6 +93,7 @@ export async function replay({
   onProgress = () => {},
   onStage = () => {},
 }) {
+  commandBudget?.assertOpen();
   projectDir = realpathSync(resolve(projectDir));
   const root = repoRoot(projectDir);
   if (!headSha(root)) throw new PreconditionError('repository has no commits; there is nothing to replay');
@@ -109,17 +111,38 @@ export async function replay({
   let runnerVersion;
 
   for (const [i, fix] of selected.entries()) {
+    commandBudget?.assertOpen();
     onStage({ commit: fix.commit, i: i + 1, n: selected.length, stage: 'prepare' });
     const iso = createScratch({ repoRoot: root, projectDir, ref: fix.commit, scratchBase, nodeModules });
     try {
       const commandTemplate = runnerCommand ? parseCommandTemplate(runnerCommand) : undefined;
+      let universe;
       if (!commandTemplate) {
-        const sel = await selectRunner({ projectDir: iso.projectDir, name: runnerName });
+        const budgetFor = () => commandBudget?.runBudget(budgetMs) ?? budgetMs;
+        const sel = await selectRunner({ projectDir: iso.projectDir, sourceDir: projectDir, name: runnerName, budgetMs: budgetFor(), budgetFor });
+        commandBudget?.assertOpen();
         if (sel.error) throw new PreconditionError(`test runner is not resolvable in the scratch worktree (${sel.error}). Pass --node-modules <path>.`);
         runnerUsed = sel.runner;
         runnerVersion = sel.version;
+        const manifests = new Map([[runnerUsed, sel.manifest]]);
+        // A pinned Python engine is already the Python per-file adapter. Adding
+        // the unpinned adapter again would let manifest precedence silently
+        // replace `--runner unittest` with pytest (or vice versa).
+        const primaryIsPython = ['python', 'pytest', 'unittest'].includes(runnerUsed.name);
+        const owned = OWNED_RUNNERS.filter((candidate) => candidate !== runnerUsed && !(candidate.name === 'python' && primaryIsPython));
+        for (const candidate of owned) {
+          const check = await candidate.check({ projectDir: iso.projectDir, sourceDir: projectDir, budgetMs: budgetFor(), budgetFor });
+          commandBudget?.assertOpen();
+          if (!check.ok) continue;
+          try {
+            manifests.set(candidate, await discoverRunnerManifest(candidate, check, iso.projectDir, budgetFor()));
+          } catch (error) {
+            throw new PreconditionError(`${candidate.name}: test discovery failed: ${error.message}`);
+          }
+        }
+        universe = buildReplayRunnerUniverse(runnerUsed, manifests);
       }
-      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandTemplate, runner: runnerUsed, onStage, index: i + 1, total: selected.length });
+      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, commandTemplate, runner: runnerUsed, universe, onStage, index: i + 1, total: selected.length });
       records.push(record);
       onProgress(record);
     } finally {
@@ -127,6 +150,8 @@ export async function replay({
     }
   }
 
+  commandBudget?.assertOpen();
+
   return {
     schemaVersion: 1,
     tool: { name: 'testguard', version: toolVersion },
@@ -144,7 +169,47 @@ export async function replay({
   };
 }
 
-async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandTemplate, runner, onStage, index, total }) {
+/**
+ * Exact configured test universe for replay. The project runner may list a
+ * broad set that overlaps a per-file runner. A file listed by one owned
+ * runner belongs to it; primary+owned overlap therefore resolves to owned.
+ * Two owned runners listing the same file is ambiguous and fails closed.
+ * Filename heuristics are deliberately absent: native manifest membership is
+ * the evidence of which configured engine collects a file.
+ */
+export function buildReplayRunnerUniverse(primary, manifests) {
+  const ownerByFile = new Map();
+  for (const file of manifests.get(primary)?.files ?? []) ownerByFile.set(file, primary);
+  for (const [owner, manifest] of manifests) {
+    if (owner === primary) continue;
+    for (const file of manifest.files) {
+      const previous = ownerByFile.get(file);
+      if (previous && previous !== primary && previous !== owner) {
+        throw new PreconditionError(`${file} was listed by both ${previous.name} and ${owner.name}; TestGuard cannot choose which configured runner owns it.`);
+      }
+      ownerByFile.set(file, owner);
+    }
+  }
+  return Object.freeze({
+    files: Object.freeze([...ownerByFile.keys()].sort()),
+    ownerOf(file) { return ownerByFile.get(file); },
+  });
+}
+
+/** Partition only files proved to belong to the frozen configured universe. */
+export function partitionReplayDefenders(files, primary, universe) {
+  const groups = new Map([[primary, []]]);
+  for (const file of files) {
+    const owner = universe.ownerOf(file);
+    if (!owner) throw new PreconditionError(`${file} is not in any resolved runner's configured test universe`);
+    if (!groups.has(owner)) groups.set(owner, []);
+    groups.get(owner).push(file);
+  }
+  if (groups.get(primary).length === 0 && groups.size > 1) groups.delete(primary);
+  return groups;
+}
+
+async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, commandTemplate, runner, universe, onStage, index, total }) {
   // git reports paths from the REPOSITORY root; the runner and every file
   // operation here work inside the scratch worktree, relative to the PROJECT
   // directory. Map once, and refuse anything that would land outside the
@@ -211,7 +276,7 @@ async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, co
   // What remains that could possibly notice: the test files importing any
   // reverted source file. `nocover` means nothing does — worse than blind,
   // and a coverage report shows it as a red line you can ignore.
-  const all = runner.tests(iso.projectDir).filter((t) => !fix.tests.some((ft) => rel(ft) === t));
+  const all = (universe?.files ?? runner.tests(iso.projectDir)).filter((t) => !fix.tests.some((ft) => rel(ft) === t));
   // Removing the fix's test removes the whole FILE, which on a project with
   // few, large test files takes pre-existing tests with it — tests that did
   // exist before the fix and might have caught the bug. When nothing is left,
@@ -227,20 +292,50 @@ async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, co
   // JavaScript resolver matches nothing — `IMPORT_RE` wants a quoted
   // specifier and `from pkg.mod import x` has none — so `related` was always
   // empty for Python and EVERY verdict was `nocover`, however good the suite.
-  const related = all.filter((t) => fix.source.some((sf) => {
-    const target = rel(sf);
-    return isPython(target)
-      ? pyFileImports(iso.projectDir, join(iso.projectDir, t), target, t)
-      : fileImports(iso.projectDir, join(iso.projectDir, t), target);
-  }));
+  const related = [];
+  const indeterminate = [];
+  for (const test of all) {
+    let matched = false;
+    for (const sf of fix.source) {
+      const target = rel(sf);
+      if (isPython(target)) {
+        matched ||= test.endsWith('.py') && pyFileImports(iso.projectDir, join(iso.projectDir, test), target, test);
+        continue;
+      }
+      if (test.endsWith('.py')) continue;
+      const relation = fileImportRelation(iso.projectDir, join(iso.projectDir, test), target);
+      if (relation.status === 'matched') matched = true;
+      else if (relation.status === 'indeterminate') indeterminate.push({ test, target, reason: relation.reason });
+    }
+    if (matched) related.push(test);
+  }
+  if (indeterminate.length > 0) {
+    return { ...base, faultClass, verdict: 'unverifiable', reason: 'defender-discovery-indeterminate', ranTests: 0, runs: [{ outcome: 'error', durationMs: 0 }] };
+  }
   if (related.length === 0) {
     return { ...base, faultClass, verdict: 'nocover', reason: 'no-test-imports-the-reverted-source', ranTests: 0, runs: [{ outcome: 'error', durationMs: 0 }] };
   }
 
   const runs = [];
   for (let i = 0; i < confirmRuns; i++) {
+    commandBudget?.assertOpen();
     onStage({ commit: fix.commit, i: index, n: total, stage: `run ${i + 1}/${confirmRuns}` });
-    const res = await runner.run({ projectDir: iso.projectDir, files: related, budgetMs, commandTemplate });
+    let res;
+    if (commandTemplate) {
+      // A custom command is one explicit execution boundary. Preserve that
+      // contract exactly; TestGuard cannot infer several native engines from
+      // an opaque user command.
+      res = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files: related, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate });
+    } else {
+      const parts = [];
+      for (const [configuredRunner, files] of partitionReplayDefenders(related, runner, universe)) {
+        commandBudget?.assertOpen();
+        parts.push(await configuredRunner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs }));
+        commandBudget?.assertOpen();
+      }
+      res = mergeRuns(parts);
+    }
+    commandBudget?.assertOpen();
     runs.push(res.run);
     // A suite that cannot load says nothing about the bug.
     if (res.run.outcome === 'error') return { ...base, faultClass, verdict: 'unverifiable', reason: 'suite-failed-to-load', ranTests: related.length, runs };

package/src/sweep/sweep.mjs

@@ -162,6 +162,7 @@ export async function sweep({
   cap,
   confirmRuns = 3,
   budgetMs = 120_000,
+  commandBudget,
   runnerCommand,
   runnerName,
   nodeModules,
@@ -172,6 +173,7 @@ export async function sweep({
   onStage,
   onWarn = () => {},
 }) {
+  commandBudget?.assertOpen();
   const gate = computeChangedGate({ projectDir, ref, includeDirty, exclude, toolVersion, claimsPath, ignorePath });
 
   // ── What the sweep is pointed at. ──
@@ -208,6 +210,7 @@ export async function sweep({
   const skipped = [];
   const drafts = [];
   for (const file of targets) {
+    commandBudget?.assertOpen();
     let result;
     try {
       result = scaffoldFile({ projectDir, file, existingClaims, toolVersion });
@@ -256,6 +259,7 @@ export async function sweep({
       claims: { schemaVersion: 1, claims },
       confirmRuns,
       budgetMs,
+      commandBudget,
       mode: 'worktree',
       includeDirty,
       // A proposed fault has no declared defenders to be missing from, so the
@@ -288,6 +292,7 @@ export async function sweep({
   }
   const ordered = sortFindings(findings);
   const gating = gatingCount(ordered);
+  commandBudget?.assertOpen();
   return {
     schemaVersion: 1,
     tool: { name: 'testguard', version: toolVersion },