testguard-cli 0.15.1 → 0.17.0

package/src/probe/probe.mjs

@@ -1,3 +1,6 @@
+import { resetInterpreterCache } from './runners/python.mjs';
+import { assertNotCancelled } from './runners/lifecycle.mjs';
+import { performance } from 'node:perf_hooks';
 import { existsSync, readFileSync, realpathSync as fsRealpathSync } from 'node:fs';
 import { gitRaw } from '../git.mjs';
 import { createRequire } from 'node:module';
@@ -13,10 +16,12 @@ import { selectRunner, discoverRunnerManifest, RUNNERS, OWNED_RUNNERS, partition
 import { classify, shouldStopEarly } from './classify.mjs';
 import { blastRadius, rank } from './rank.mjs';
 import { classifyIndependence } from './independence.mjs';
-import { escalationStart, foldEscalationRun, escalationResult, flakeRate, killersFromRuns, subjectOf, isReusable } from './attribution.mjs';
+import { escalationStart, foldEscalationRun, escalationResult, flakeRate, killersFromRuns, subjectOf, isReusable, defenderSelection } from './attribution.mjs';
 import { hashFile, sha256 } from '../util/hash.mjs';
 import { fingerprint } from '../../spec/lib/fingerprint.mjs';
+import { recordedOriginSummary } from '../../spec/lib/origins.mjs';
 import { persistenceSignalsFor } from '../supply/persistence.mjs';
+import { collectOwnedManifests, hashNativeTestUniverse } from './universe.mjs';
 
 
 /** Is `child` the same file as `root`, or under it? Both must already be real paths. */
@@ -51,6 +56,12 @@ export function selectClaims(claims, only) {
   return only.map((id) => byId.get(id));
 }
 
+/** Reuse cannot stand in for a measurement under a different worker policy. */
+export function sameWorkerPolicy(previousRun, { workers = 1, serial = workers === 1, runnerCommand } = {}) {
+  if (runnerCommand) return previousRun?.workers === undefined && !previousRun?.serial;
+  return previousRun?.workers === (serial ? 1 : workers) && Boolean(previousRun?.serial) === serial;
+}
+
 /**
  * Probe every fault of every claim. Returns a spec-conformant evidence
  * document; writing it is the caller's job.
@@ -63,7 +74,8 @@ export async function probe({
   ref = 'HEAD',
   refExplicit = false,
   ignoreDirty = false,
-  serial = false,
+  workers = 1,
+  serial = workers === 1,
   onWarn = () => {},
   budgetMs = 120_000,
   commandBudget,
@@ -80,6 +92,18 @@ export async function probe({
   previous,
   onProgress = () => {},
 }) {
+  if (!Number.isSafeInteger(workers) || workers < 1) throw new PreconditionError('workers must be a positive safe integer');
+  resetInterpreterCache(); // Cache only within this measurement, never across commands.
+  const measuredStart = performance.now();
+  const startedAt = new Date().toISOString();
+  const measurements = { elapsedMs: 0, runnerMs: 0, overheadMs: 0, runnerInvocations: 0 };
+  const timedRun = async (runner, opts) => {
+    assertNotCancelled();
+    const start = performance.now();
+    measurements.runnerInvocations++;
+    try { return await runner.run(opts); }
+    finally { measurements.runnerMs += performance.now() - start; }
+  };
   commandBudget?.assertOpen();
   // realpath: git reports the repository root by its real path (/private/var
   // on macOS, not /var); every relative() below must start from the same place.
@@ -154,11 +178,14 @@ export async function probe({
         }
       }
       for (const claim of scopedClaims) {
-        const discovered = claim.defendedBy?.length ? null : claim.faults.map((fault) => discoverDefendersDetailed(projectDir, fault.file, configuredFiles));
-        const declared = claim.defendedBy?.length ? resolveDefenders(projectDir, claim.defendedBy) : discovered.flatMap((detail) => detail.canDetect);
-        for (const d of declared) watched.add(relative(root, join(projectDir, d)));
-        for (const dependency of discovered?.flatMap((detail) => detail.dependencies) ?? []) watched.add(relative(root, join(projectDir, dependency)));
-        for (const g of claim.defendedBy ?? []) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
+        for (const fault of claim.faults) {
+          const { requested } = defenderSelection(claim, fault);
+          const discovered = requested.length ? null : discoverDefendersDetailed(projectDir, fault.file, configuredFiles);
+          const declared = requested.length ? resolveDefenders(projectDir, requested) : discovered.canDetect;
+          for (const d of declared) watched.add(relative(root, join(projectDir, d)));
+          for (const dependency of discovered?.dependencies ?? []) watched.add(relative(root, join(projectDir, dependency)));
+          for (const g of requested) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
+        }
       }
       for (const config of [
         'package.json', 'pnpm-workspace.yaml', 'pnpm-workspace.yml', 'lerna.json', 'nx.json', 'turbo.json', 'rush.json', 'workspace.json',
@@ -180,7 +207,6 @@ export async function probe({
   const contention = detectContention();
   if (contention.detected) onWarn(contentionWarning(contention));
 
-  const startedAt = new Date().toISOString();
   const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref: snapshot ?? ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
   const isoReal = realpathSync(iso.projectDir);
   const records = [];
@@ -215,20 +241,16 @@ export async function probe({
     // project runner is; it must resolve before the first such defender runs.
     const owned = OWNED_RUNNERS.filter((r) => r !== runner
       && !(r.name === 'python' && ['python', 'pytest', 'unittest'].includes(runner.name)));
-    const ownedChecked = new Map();
-    const manifests = new Map(primaryManifest ? [[runner, primaryManifest]] : []);
+    let ownedChecked = new Map();
+    let manifests = new Map(primaryManifest ? [[runner, primaryManifest]] : []);
     if (!commandTemplate) {
-      for (const r of owned) {
-        const check = await r.check({ projectDir: iso.projectDir, sourceDir: projectDir, python, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, budgetFor: () => commandBudget?.runBudget(budgetMs) ?? budgetMs });
-        commandBudget?.assertOpen();
-        ownedChecked.set(r, check);
-        if (!check.ok) continue;
-        try {
-          manifests.set(r, await discoverRunnerManifest(r, check, iso.projectDir, commandBudget?.runBudget(budgetMs) ?? budgetMs));
-        } catch (error) {
-          throw new PreconditionError(`${r.name}: test discovery failed: ${error.message}`);
-        }
-      }
+      try {
+        ({ ownedChecked, manifests } = await collectOwnedManifests(runner, primaryManifest, {
+          projectDir: iso.projectDir, sourceDir: projectDir, python, budgetMs,
+          budgetFor: () => commandBudget?.runBudget(budgetMs) ?? budgetMs,
+          assertOpen: () => commandBudget?.assertOpen(),
+        }));
+      } catch (error) { throw new PreconditionError(`test discovery failed: ${error.message}`); }
     }
     const ensureOwned = async (r, file) => {
       if (!ownedChecked.has(r)) {
@@ -262,9 +284,7 @@ export async function probe({
       : [...ownerByFile.keys()]).sort());
     const testUniverseHash = commandTemplate
       ? sha256(JSON.stringify({ schemaVersion: 1, source: 'custom-command-static', files: allTests }))
-      : sha256(JSON.stringify([...manifests]
-        .map(([r, manifest]) => ({ runner: r.name, hash: manifest.testUniverseHash }))
-        .sort((a, b) => a.runner.localeCompare(b.runner))));
+      : hashNativeTestUniverse(manifests);
     const baselineCache = new Map();
     const discoveryHashCache = new Map();
     // The negative control is charged per (target file, defender set): two
@@ -274,6 +294,7 @@ export async function probe({
     // runner — a `.py` source file is Python's whatever the project runs.
     const fatalEditFor = (file) => runnerFor(iso.projectDir, file, runner).fatalEdit?.();
     const prior = previous && previous.run.confirmRuns === confirmRuns
+      && sameWorkerPolicy(previous.run, { workers, serial, runnerCommand })
       ? new Map(previous.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]))
       : new Map();
     const partitionConfigured = (files) => {
@@ -292,7 +313,7 @@ export async function probe({
     // file the interpreter actually loaded (Python) reports it back.
     const runDefenders = async (files, targets = []) => {
       if (commandTemplate) {
-        const result = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, python, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate, serial, targets });
+        const result = await timedRun(runner, { projectDir: iso.projectDir, sourceDir: projectDir, python, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate, serial, workers, targets });
         commandBudget?.assertOpen();
         return result;
       }
@@ -301,7 +322,7 @@ export async function probe({
       for (const [r, group] of groups) {
         commandBudget?.assertOpen();
         if (r !== runner) await ensureOwned(r, group[0]);
-        parts.push(await r.run({ projectDir: iso.projectDir, sourceDir: projectDir, python, files: group, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, serial, targets }));
+        parts.push(await timedRun(r, { projectDir: iso.projectDir, sourceDir: projectDir, python, files: group, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, serial, workers, targets }));
         commandBudget?.assertOpen();
       }
       return mergeRuns(parts);
@@ -315,20 +336,21 @@ export async function probe({
 
     for (const claim of scopedClaims) {
       commandBudget?.assertOpen();
-      const declared = claim.defendedBy?.length ? resolveDefenders(iso.projectDir, claim.defendedBy) : null;
-      if (declared && !commandTemplate) {
-        const excluded = declared.filter((file) => !ownerByFile.has(file));
-        for (const file of excluded) {
-          const expectedOwner = owned.find((candidate) => candidate.owns?.(iso.projectDir, file));
-          const check = expectedOwner && ownedChecked.get(expectedOwner);
-          if (expectedOwner && check && !check.ok) {
-            throw new PreconditionError(`${file} is a ${expectedOwner.name} test (${expectedOwner.name === 'python' ? 'it is a .py file' : `it lives under ${expectedOwner.name}'s testDir`}) but ${expectedOwner.name} is not resolvable for the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${check.message}).`);
-          }
-        }
-        if (excluded.length) throw new PreconditionError(`${claim.id}: defendedBy resolves to ${excluded.join(', ')}, but the configured runners do not collect ${excluded.length === 1 ? 'that file' : 'those files'}`);
-      }
       for (const fault of claim.faults) {
         commandBudget?.assertOpen();
+        const { requested } = defenderSelection(claim, fault);
+        const declared = requested.length ? resolveDefenders(iso.projectDir, requested) : null;
+        if (declared && !commandTemplate) {
+          const excluded = declared.filter((file) => !ownerByFile.has(file));
+          for (const file of excluded) {
+            const expectedOwner = owned.find((candidate) => candidate.owns?.(iso.projectDir, file));
+            const check = expectedOwner && ownedChecked.get(expectedOwner);
+            if (expectedOwner && check && !check.ok) {
+              throw new PreconditionError(`${file} is a ${expectedOwner.name} test (${expectedOwner.name === 'python' ? 'it is a .py file' : `it lives under ${expectedOwner.name}'s testDir`}) but ${expectedOwner.name} is not resolvable for the ${mode === 'worktree' ? 'scratch worktree' : 'project'} (${check.message}).`);
+            }
+          }
+          if (excluded.length) throw new PreconditionError(`${claim.id}/${fault.id}: defendedBy resolves to ${excluded.join(', ')}, but the configured runners do not collect ${excluded.length === 1 ? 'that file' : 'those files'}`);
+        }
         // Mock-awareness: a discovered file that mocks the target is not a
         // defender; a declared one that mocks it stays (the author named it)
         // but is listed, because a declared defender that mocks the subject
@@ -369,6 +391,10 @@ export async function probe({
 
   commandBudget?.assertOpen();
 
+  assertNotCancelled();
+  const dirty = isDirty(root);
+  measurements.elapsedMs = performance.now() - measuredStart;
+  measurements.overheadMs = measurements.elapsedMs - measurements.runnerMs;
   return {
     schemaVersion: 1,
     tool: { name: 'testguard', version: toolVersion },
@@ -376,11 +402,13 @@ export async function probe({
       id: `run-${startedAt.replace(/[-:.]/g, '').slice(0, 15)}`,
       startedAt,
       finishedAt: new Date().toISOString(),
-      repo: { head, dirty: isDirty(root), ...(snapshot ? { snapshot } : {}), ...(ignoredDirty.length ? { ignoredDirty } : {}) },
+      repo: { head, dirty, ...(snapshot ? { snapshot } : {}), ...(ignoredDirty.length ? { ignoredDirty } : {}) },
       runner: { name: labelOf(runner), ...((runnerVersion ?? readRunnerVersion(projectDir, runner.name)) ? { version: runnerVersion ?? readRunnerVersion(projectDir, runner.name) } : {}) },
       ...(runnersUsed.size > 1 ? { runners: [...runnersUsed].map(([n, v]) => ({ name: n, ...(v ? { version: v } : {}) })) } : {}),
       confirmRuns,
-      ...(serial ? { serial: true } : {}),
+      measurements,
+      ...(!runnerCommand ? { workers: serial ? 1 : workers } : {}),
+      ...(serial && !runnerCommand ? { serial: true } : {}),
       ...(contention.detected ? { contention } : {}),
       ...(confirmRuns < 3 ? { provisional: true } : {}),
       // The isolation that was actually created, not the mode that was asked
@@ -390,6 +418,7 @@ export async function probe({
       mode: iso.mode,
     },
     records,
+    origins: recordedOriginSummary(records),
   };
 }
 
@@ -413,7 +442,7 @@ export function errorRecord({ claim, fault, defenders, discovered, byRunner, moc
     subject: subjectOf(fault, sha256),
     verdict: 'unverifiable',
     detail: { baselineRuns: [], probeRuns: [], reason: 'probe-error', message },
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
+    defenders: { ...defenderSelection(claim, fault), resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
     inputs,
   };
 }
@@ -428,7 +457,7 @@ export function discoveryIndeterminateRecord({ claim, fault, defenders, discover
     subject: subjectOf(fault, sha256),
     verdict: 'unverifiable',
     detail: { baselineRuns: [], probeRuns: [], reason: 'defender-discovery-indeterminate', message },
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: false, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
+    defenders: { ...defenderSelection(claim, fault), resolved: defenders, nocover: false, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(signals.length ? { signals } : {}) },
     inputs,
   };
 }
@@ -516,8 +545,8 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, is
   const subject = subjectOf(fault, sha256);
 
   // Same source, same defenders, same N, same fault: the verdict cannot have changed.
-  if (isReusable(prior, { inputs, requested: claim.defendedBy ?? [], resolved: defenders, contentHash: subject.contentHash })) {
-    return { ...prior, reusedFrom: prior.reusedFrom ?? priorRunId };
+  if (isReusable(prior, { claim, inputs, ...defenderSelection(claim, fault), resolved: defenders, contentHash: subject.contentHash })) {
+    return { ...prior, defenders: { ...prior.defenders, ...defenderSelection(claim, fault) }, reusedFrom: prior.reusedFrom ?? priorRunId };
   }
 
   const detail = { baselineRuns: [], probeRuns: [] };
@@ -655,7 +684,7 @@ async function probeOne({ claim, fault, defenders, discovered, allTests, iso, is
     subject,
     verdict,
     detail,
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(allSignals.length ? { signals: allSignals } : {}) },
+    defenders: { ...defenderSelection(claim, fault), resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}), ...(byRunner ? { byRunner } : {}), ...(mocking.length ? { mocking } : {}), ...(allSignals.length ? { signals: allSignals } : {}) },
     inputs,
     rank: rank({ severity: claim.severity, sourceKind: claim.source.kind, blast, independence: detail.independence?.class }),
   };

package/src/probe/runners/discovery.mjs

@@ -1,3 +1,4 @@
+import { registerChild } from './lifecycle.mjs';
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, rmSync, statSync } from 'node:fs';
@@ -177,6 +178,7 @@ export function runDiscoveryProcess({
       return;
     }
 
+    registerChild(child, () => terminateProcessTree(child));
     const started = Date.now();
     const stdout = [];
     const stderr = [];

package/src/probe/runners/jest.mjs

@@ -38,8 +38,8 @@ export async function discoverTests({ projectDir, version, timeoutMs, maxOutputB
 }
 // --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 } = {}) =>
-  [...runnerArgv(projectDir, 'jest', 'jest'), '--ci', '--json', `--outputFile=${outFile}`, ...(serial ? ['--runInBand'] : []), '--runTestsByPath', ...files];
+export const argvFor = (projectDir, files, outFile, { serial = false, workers = 1 } = {}) =>
+  [...runnerArgv(projectDir, 'jest', 'jest'), '--ci', '--json', `--outputFile=${outFile}`, ...(serial || workers === 1 ? ['--runInBand'] : [`--maxWorkers=${workers}`]), '--runTestsByPath', ...files];
 export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => argvFor(opts.projectDir, files, outFile, opts) });
 
 /**

package/src/probe/runners/lifecycle.mjs

@@ -0,0 +1,58 @@
+/** Own only children and cleanups registered by this TestGuard process. */
+const children = new Map();
+const cleanups = new Map();
+let installed = false;
+let cancelling = false;
+
+function cleanup() {
+  // Restore mutations before removing isolation, even across successive probes.
+  for (const [fn] of [...cleanups].reverse().sort((a, b) => b[1] - a[1])) {
+    try { fn(); } catch (error) { process.stderr.write(`cleanup failed: ${error.message}\n`); }
+  }
+  cleanups.clear();
+}
+
+function install() {
+  if (installed) return;
+  installed = true;
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, async () => {
+      if (cancelling) return;
+      cancelling = true;
+      const waits = [...children].map(([child, stop]) => {
+        const closed = new Promise((resolve) => child.once('close', resolve));
+        stop();
+        return closed;
+      });
+      let timer;
+      await Promise.race([
+        Promise.allSettled(waits),
+        new Promise((resolve) => { timer = setTimeout(resolve, 1000); }),
+      ]);
+      clearTimeout(timer);
+      cleanup();
+      process.exit(130);
+    });
+  }
+  process.on('exit', () => {
+    for (const stop of children.values()) stop();
+    cleanup();
+  });
+}
+
+export function registerChild(child, stop) {
+  install();
+  children.set(child, stop);
+  child.once('close', () => children.delete(child));
+  if (cancelling) stop();
+}
+
+export function registerCleanup(fn, { priority = 0 } = {}) {
+  install();
+  cleanups.set(fn, priority);
+  return () => cleanups.delete(fn);
+}
+
+export function assertNotCancelled() {
+  if (cancelling) throw new Error('TestGuard command cancelled; no partial result may be published');
+}

package/src/probe/runners/playwright.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { npx, runProcess, listTestFiles, firstInformativeLine, runnerArgv } from './shared.mjs';
+import { runProcess, listTestFiles, firstInformativeLine, runnerArgv } from './shared.mjs';
 import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs, normalizeDiscoveredFiles, runDiscoveryReportProcess } from './discovery.mjs';
 import { globToRegExp } from '../../util/glob.mjs';
 
@@ -185,7 +185,7 @@ export function parseReport(report, durationMs) {
 
 export const run = (opts) => {
   const env = { PLAYWRIGHT_JSON_OUTPUT_FILE: '{out}', PLAYWRIGHT_JSON_OUTPUT_NAME: '{out}' };
-  return runProcess({ ...opts, env, parse: parseReport, argv: (files) => [npx, 'playwright', 'test', '--reporter=json', ...(opts.serial ? ['--workers=1'] : []), ...files] });
+  return runProcess({ ...opts, env, parse: parseReport, argv: (files) => argvFor(opts.projectDir, files, opts) });
 };
 
 /**
@@ -196,3 +196,7 @@ export const run = (opts) => {
  * contained before.
  */
 export const fatalEdit = () => '/* testguard negative control: this file must not parse */\n(\n';
+
+/** Run the project-pinned CLI directly, avoiding an npm subprocess per confirmation. */
+export const argvFor = (projectDir, files, { serial = false, workers = 1 } = {}) =>
+  [...runnerArgv(projectDir, '@playwright/test', 'playwright'), 'test', '--reporter=json', `--workers=${serial ? 1 : workers}`, ...files];

package/src/probe/runners/python.mjs

@@ -1,4 +1,6 @@
+import { performance } from 'node:perf_hooks';
 import { existsSync, readFileSync } from 'node:fs';
+import { registerChild } from './lifecycle.mjs';
 import { spawn } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -120,9 +122,10 @@ function ask(path, budgetMs) {
     } catch {
       return resolve(null);
     }
+    registerChild(child, () => terminateProcessTree(child));
     let out = '';
     child.on('error', () => resolve(null));
-    child.stdout.on('data', (d) => (out += d));
+    child.stdout.on('data', (d) => (out = (out + d).slice(-65536)));
     child.stderr.on('data', () => {});
     const timer = setTimeout(() => terminateProcessTree(child), budgetMs);
     child.on('close', (code) => {
@@ -276,10 +279,10 @@ export function environment(targets) {
  * the configured value; the rest of the project's `addopts` is left alone,
  * because TestGuard runs a project's tests the way the project runs them.
  */
-export function argvFor({ engine, interpreter, files, serial }) {
+export function argvFor({ engine, interpreter, files, serial = true }) {
   if (engine === 'pytest') {
     return [interpreter, '-m', 'pytest', '-p', '_testguard_pytest_plugin', '-p', 'no:cacheprovider',
-      '--maxfail=0', '-q', ...(serial ? ['-p', 'no:xdist'] : []), ...files];
+      '--maxfail=0', '-q', '-p', 'no:xdist', ...files];
   }
   return [interpreter, '-m', '_testguard_unittest_main', ...files];
 }
@@ -287,12 +290,15 @@ export function argvFor({ engine, interpreter, files, serial }) {
 export function makeRun(pinned) {
   const check = makeCheck(pinned);
   return async (opts) => {
-    const resolved = await check({ projectDir: opts.sourceDir ?? opts.projectDir, python: opts.python });
+    const deadline = performance.now() + (opts.budgetMs ?? 120_000);
+    const remaining = () => Math.max(1, Math.floor(deadline - performance.now()));
+    const resolved = await check({ projectDir: opts.sourceDir ?? opts.projectDir, python: opts.python, budgetMs: remaining(), budgetFor: remaining });
     if (!resolved.ok) {
       return { run: { outcome: 'error', tests: { total: 0, passed: 0, failed: 0 }, assertionFailures: 0, durationMs: 0 }, timeouts: 0, loadMessage: resolved.message, failedTests: [], provenance: {} };
     }
     return runProcess({
       ...opts,
+      budgetMs: remaining(),
       env: environment(opts.targets),
       parse: parseReport,
       argv: (files) => argvFor({ engine: resolved.engine, interpreter: resolved.interpreter, files, serial: opts.serial }),

package/src/probe/runners/shared.mjs

@@ -1,4 +1,6 @@
 import { spawn, spawnSync } from 'node:child_process';
+import { registerChild, assertNotCancelled } from './lifecycle.mjs';
+import { readBoundedJsonFile } from './discovery.mjs';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname } from 'node:path';
@@ -16,7 +18,7 @@ export const NODE_NOISE = /MODULE_TYPELESS_PACKAGE_JSON|ExperimentalWarning|--tr
 
 function descendantPids(rootPid) {
   if (process.platform === 'win32') return [];
-  const result = spawnSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8' });
+  const result = spawnSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8', timeout: 1000, maxBuffer: 4 * 1024 * 1024 });
   if (result.status !== 0) return [];
   const children = new Map();
   for (const line of result.stdout.split('\n')) {
@@ -43,7 +45,7 @@ export const TIMEOUT_CLEANUP_WARNING = 'cleanup-unverified: TestGuard hard-kille
 export function terminateProcessTree(child) {
   if (!child.pid) return;
   if (process.platform === 'win32') {
-    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', timeout: 1000 });
     try { child.kill('SIGKILL'); } catch {}
     return;
   }
@@ -147,11 +149,12 @@ export function checkRunner({ projectDir, pkg, bin, budgetMs = 60_000, env = pro
     } catch (e) {
       return resolve({ ok: false, message: e.message });
     }
+    registerChild(child, () => terminateProcessTree(child));
     let out = '';
     let err = '';
     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));
+    child.stdout.on('data', (d) => (out = (out + d).slice(-65536)));
+    child.stderr.on('data', (d) => (err = (err + d).slice(-65536)));
     const timer = setTimeout(() => terminateProcessTree(child), budgetMs);
     child.on('close', (code) => {
       clearTimeout(timer);
@@ -239,6 +242,7 @@ export function parseReport(report, durationMs) {
  * override it.
  */
 export function runProcess({ projectDir, files, budgetMs = 120_000, command, commandTemplate, argv, env = {}, parse = parseReport }) {
+  assertNotCancelled();
   const outFile = join(tmpdir(), `testguard-run-${randomBytes(6).toString('hex')}.json`);
   const [cmd, ...args] = command
     ?? (commandTemplate ? expandCommand(commandTemplate, files, outFile) : argv(files, outFile));
@@ -248,11 +252,13 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
 
   return new Promise((resolve) => {
     const child = spawn(cmd, args, { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32', env: { ...process.env, CI: '1', FORCE_COLOR: '0', ...extraEnv } });
+    registerChild(child, () => terminateProcessTree(child));
+    child.stdout.resume(); // Reports are read from the file; drain logs to prevent pipe backpressure.
     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
     // stream and out of `loadMessage`, which names the cause of a load error.
-    child.stderr.on('data', (d) => (stderr += String(d).split('\n').filter((l) => !NODE_NOISE.test(l)).join('\n')));
+    child.stderr.on('data', (d) => (stderr = (stderr + String(d).split('\n').filter((l) => !NODE_NOISE.test(l)).join('\n')).slice(-65536)));
     child.on('error', (e) => (stderr += e.message));
     let killed = false;
     const timer = setTimeout(() => {
@@ -270,7 +276,7 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
         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 {
         try {
-          result = parse(JSON.parse(readFileSync(outFile, 'utf8')), durationMs);
+          result = parse(readBoundedJsonFile(outFile), durationMs);
         } catch (e) {
           result = { run: { outcome: 'error', tests: { total: 0, passed: 0, failed: 0 }, assertionFailures: 0, durationMs }, timeouts: 0, loadMessage: `unreadable report: ${e.message}`, failedTests: [] };
         }

package/src/probe/runners/vitest.mjs

@@ -10,7 +10,7 @@ const DISCOVERY_CONFIG_FILES = [
   '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 const discoveryArgvFor = (projectDir) => [...runnerArgv(projectDir, 'vitest', 'vitest'), 'list', '--filesOnly', '--passWithNoTests', '--maxWorkers=1'];
 
 export function parseDiscoveryOutput(stdout) {
   if (typeof stdout !== 'string') throw new TypeError('Vitest discovery output must be text');
@@ -27,8 +27,8 @@ export async function discoverTests({ projectDir, version, timeoutMs, maxOutputB
 }
 // --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 } = {}) =>
-  [...runnerArgv(projectDir, 'vitest', 'vitest'), 'run', ...files, '--reporter=json', `--outputFile=${outFile}`, ...(serial ? ['--no-file-parallelism'] : [])];
+export const argvFor = (projectDir, files, outFile, { serial = false, workers = 1 } = {}) =>
+  [...runnerArgv(projectDir, 'vitest', 'vitest'), 'run', ...files, '--reporter=json', `--outputFile=${outFile}`, `--maxWorkers=${serial ? 1 : workers}`, ...(serial || workers === 1 ? ['--no-file-parallelism'] : [])];
 export const run = (opts) => runProcess({ ...opts, argv: (files, outFile) => argvFor(opts.projectDir, files, outFile, opts) });
 
 /**

package/src/probe/universe.mjs

@@ -0,0 +1,47 @@
+import { sha256 } from '../util/hash.mjs';
+import { selectRunner, discoverRunnerManifest, OWNED_RUNNERS } from './runners/index.mjs';
+import { createDiscoveryManifest, DiscoveryError } from './runners/discovery.mjs';
+
+/** The same adapter/configuration universe used by probing, never a file-glob guess. */
+export function hashNativeTestUniverse(manifests) {
+  const entries = [...manifests];
+  if (!entries.length) throw new DiscoveryError('a native test universe requires runner manifests');
+  if (!entries.some(([, manifest]) => manifest?.files?.length)) throw new DiscoveryError('a native test universe must contain test files');
+  const names = new Set();
+  const bound = entries.map(([runner, manifest]) => {
+    if (!runner?.name || names.has(runner.name) || !manifest?.runner) throw new DiscoveryError('native universe runner identities must be unique');
+    names.add(runner.name);
+    const canonical = createDiscoveryManifest({ runner: manifest.runner.name, version: manifest.runner.version, files: manifest.files, configFiles: manifest.configFiles, source: manifest.source });
+    if (canonical.testUniverseHash !== manifest.testUniverseHash || runner.name !== manifest.runner.name) throw new DiscoveryError('native universe manifest binding is inconsistent');
+    return { runner: runner.name, hash: manifest.testUniverseHash };
+  }).sort((a, b) => a.runner.localeCompare(b.runner));
+  return sha256(JSON.stringify(bound));
+}
+
+/** Shared owning-adapter collection; check failures retain existing probe semantics. */
+export async function collectOwnedManifests(runner, primaryManifest, { projectDir, sourceDir, python, budgetMs, budgetFor, assertOpen = () => {} }) {
+  const owned = OWNED_RUNNERS.filter((r) => r !== runner
+    && !(r.name === 'python' && ['python', 'pytest', 'unittest'].includes(runner.name)));
+  const ownedChecked = new Map();
+  const manifests = new Map(primaryManifest ? [[runner, primaryManifest]] : []);
+  for (const r of owned) {
+    const check = await r.check({ projectDir, sourceDir, python, budgetMs: budgetFor ? budgetFor() : budgetMs, budgetFor });
+    assertOpen();
+    ownedChecked.set(r, check);
+    if (!check.ok) continue;
+    manifests.set(r, await discoverRunnerManifest(r, check, projectDir, budgetFor ? budgetFor() : budgetMs));
+    assertOpen();
+  }
+  return { owned, ownedChecked, manifests };
+}
+
+/** Fresh current-project collection for an explicitly requested policy boundary. */
+export async function readNativeTestUniverse(options) {
+  const selected = await selectRunner({ ...options, name: options.runnerName ?? 'auto' });
+  options.assertOpen?.();
+  if (selected.error) throw new DiscoveryError(selected.error);
+  const collection = await collectOwnedManifests(selected.runner, selected.manifest, options);
+  const primaryRunner = { name: selected.engine ?? selected.runner.name, version: selected.version };
+  const runners = [primaryRunner, ...[...collection.ownedChecked].filter(([, check]) => check.ok).map(([runner, check]) => ({ name: check.engine ?? runner.name, version: check.version }))];
+  return { ...collection, primary: selected.runner, primaryRunner, runners, testUniverseHash: hashNativeTestUniverse(collection.manifests) };
+}

package/src/probe/worktree.mjs

@@ -1,3 +1,4 @@
+import { registerCleanup } from './runners/lifecycle.mjs';
 import { existsSync, mkdtempSync, readdirSync, symlinkSync, mkdirSync, statSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative, dirname } from 'node:path';
@@ -53,6 +54,7 @@ export function createScratch({ repoRoot, projectDir, ref = 'HEAD', scratchBase
     throw new PreconditionError(ref === 'HEAD' ? 'repository has no commits; commit first, or run with --in-place' : `ref ${ref} does not resolve to a commit`);
   }
   const dest = mkdtempSync(join(scratchBase, 'testguard-'));
+  const unregister = registerCleanup(() => removeWorktree(repoRoot, dest));
   addWorktree(repoRoot, dest, sha);
   const links = findNodeModules(repoRoot);
   if (nodeModules) {
@@ -71,7 +73,7 @@ export function createScratch({ repoRoot, projectDir, ref = 'HEAD', scratchBase
     sha,
     root: dest,
     projectDir: join(dest, relative(repoRoot, projectDir)),
-    cleanup: () => removeWorktree(repoRoot, dest),
+    cleanup: () => { removeWorktree(repoRoot, dest); unregister(); },
   };
 }
 

package/src/render.mjs

@@ -1,5 +1,15 @@
+import { recordedOriginSummary } from '../spec/lib/origins.mjs';
+
 const ORDER = ['survived', 'nocover', 'unverifiable', 'fault-invalid', 'timeout', 'flaky-defender', 'killed'];
 
+/** Informational declarations only; never a verdict or an eligibility gate. */
+export function renderOrigins(origins) {
+  const split = (counts) => Object.entries(counts).filter(([, n]) => n > 0).map(([kind, n]) => `${kind}: ${n}`).join(', ') || 'none';
+  return `origins (${origins.basis}): ${origins.claims.total} distinct claims (${split(origins.claims.byKind)}; mixed: ${origins.claims.mixed})` +
+    (origins.records ? `; ${origins.records.total} records (${split(origins.records.byKind)})` : '') +
+    ' — declared origins, not authenticated independence';
+}
+
 /** Non-passing verdicts shout; the one pass does not. */
 export const formatVerdict = (v, provisional = false) => (v === 'killed' ? 'killed' : v.toUpperCase()) + (provisional ? '?' : '');
 
@@ -37,7 +47,13 @@ export function renderSummary(records, run) {
   const kills = records.filter((r) => r.verdict === 'killed');
   const coAuthored = kills.filter((r) => r.detail.independence?.class === 'co-authored').length;
   const quality = coAuthored ? `\n${coAuthorshipWarning(coAuthored, kills.length)}` : '';
-  return `${run?.provisional ? 'PROVISIONAL: ' : ''}${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}${quality}`;
+  return `${run?.provisional ? 'PROVISIONAL: ' : ''}${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}${quality}\n${renderOrigins(recordedOriginSummary(records))}`;
+}
+
+/** Distinguish current admission, offline audit and recorded-run policy. */
+export function renderOriginPolicy(policy, { basis = 'recorded' } = {}) {
+  const label = basis === 'offline' ? 'current declarations; offline freshness unavailable' : basis === 'current' ? 'current inputs' : 'recorded run';
+  return `origin policy (${label}): ${policy.state}; eligible declarations: ${policy.eligibleKinds.join(', ')}; ${policy.claims} claims / ${policy.faults} faults; ${policy.ineligibleClaims.length} ineligible claims; ${policy.nonKilledFaults.length} non-killed faults${policy.unavailableReasons.length ? `; unavailable: ${policy.unavailableReasons.join(', ')}` : ''} — declared origins, not authenticated independence${basis === 'recorded' ? '; not current freshness' : ''}`;
 }
 
 /** Survivors first, then by rank score; killed last. */