testguard-cli 0.16.0 → 0.18.0

package/src/probe/origin-policy.mjs

@@ -0,0 +1,69 @@
+import { isDeepStrictEqual } from 'node:util';
+import { validate, methodOf } from '../../spec/lib/validate.mjs';
+import { CLAIM_SOURCE_KINDS } from '../../spec/lib/origins.mjs';
+import { sameClaimMetadata, subjectOf } from './attribution.mjs';
+import { sha256 } from '../util/hash.mjs';
+
+/** Admit the planned probe option before loading claims or executing/writing. */
+export function originPolicyRequest(values, command = 'probe') {
+  const raw = values['require-origin'];
+  if (raw === undefined) return undefined;
+  if (command !== 'probe') throw new TypeError('--require-origin is only valid on probe');
+  if (!Array.isArray(raw) || !raw.length || raw.some((v) => typeof v !== 'string')) {
+    throw new TypeError('--require-origin must name declared source kinds');
+  }
+  const kinds = raw.flatMap((v) => v.split(',').map((k) => k.trim()));
+  if (kinds.some((k) => !CLAIM_SOURCE_KINDS.includes(k))) throw new TypeError('--require-origin contains an empty or unsupported kind');
+  if (values.claim !== undefined || values['allow-empty'] || values.ref !== undefined || values['ignore-dirty']) {
+    throw new TypeError('--require-origin needs a complete current-project run without --claim, --allow-empty, --ref or --ignore-dirty');
+  }
+  const n = Number(values.confirm ?? 3);
+  if (!Number.isInteger(n) || n < 3) throw new TypeError('--require-origin requires --confirm of at least 3');
+  return [...new Set(kinds)].sort();
+}
+
+/** Internal policy only: fresh must come from the existing input-binding checker. */
+export function evaluateOriginPolicy({ claims, evidence, eligibleKinds, fresh }) {
+  if (eligibleKinds === undefined) return undefined;
+  if (!Array.isArray(eligibleKinds) || !eligibleKinds.length || eligibleKinds.some((k) => !CLAIM_SOURCE_KINDS.includes(k))) {
+    throw new TypeError('origin policy needs a nonempty set of declared source kinds');
+  }
+  const eligible = [...new Set(eligibleKinds)].sort();
+  const reasons = new Set();
+  const claimsValid = validate('claims', claims).ok;
+  const evidenceValid = validate('evidence', evidence).ok;
+  if (!claimsValid) reasons.add('invalid-claims');
+  if (!evidenceValid) reasons.add('invalid-evidence');
+  if (fresh !== true) reasons.add('stale-inputs');
+  const current = claimsValid ? claims.claims : [];
+  const records = evidenceValid ? evidence.records : [];
+  const key = (claimId, faultId) => JSON.stringify([claimId, faultId]);
+  const expected = new Map(current.flatMap((claim) => claim.faults.map((fault) => [key(claim.id, fault.id), { claim, fault }])));
+  if (!current.length || !expected.size) reasons.add('empty-universe');
+  if (evidenceValid && (evidence.run.provisional === true || evidence.run.confirmRuns < 3)) reasons.add('provisional-evidence');
+  if (evidenceValid && methodOf(evidence.run) !== 'fault-injection') reasons.add('incompatible-method');
+  if (current.some((c) => c.faults.some((f) => methodOf(f) !== 'fault-injection'))) reasons.add('incompatible-method');
+  const seen = new Set();
+  for (const record of records) {
+    const identity = key(record.claim.id, record.subject.id);
+    if (seen.has(identity)) reasons.add('duplicate-record');
+    seen.add(identity);
+    const pair = expected.get(identity);
+    if (!pair) { reasons.add('extra-record'); continue; }
+    if (!sameClaimMetadata(record.claim, pair.claim)) reasons.add('claim-metadata-mismatch');
+    if (methodOf(pair.fault) !== 'fault-injection') continue;
+    const subject = subjectOf(pair.fault, sha256);
+    if (['kind', 'id', 'file', 'faultClass', 'contentHash'].some((field) => record.subject[field] !== subject[field])
+      || !isDeepStrictEqual(record.subject.producedBy, subject.producedBy)) reasons.add('fault-mismatch');
+  }
+  if ([...expected.keys()].some((identity) => !seen.has(identity))) reasons.add('missing-record');
+  const ineligibleClaims = current.filter((c) => !eligible.includes(c.source.kind)).map((c) => c.id).sort();
+  const nonKilledFaults = [...new Map(records.filter((r) => r.verdict !== 'killed').map((r) =>
+    [key(r.claim.id, r.subject.id), { claimId: r.claim.id, faultId: r.subject.id }])).values()]
+    .sort((a, b) => a.claimId.localeCompare(b.claimId) || a.faultId.localeCompare(b.faultId));
+  return {
+    state: reasons.size ? 'unavailable' : ineligibleClaims.length || nonKilledFaults.length ? 'failed' : 'passed',
+    eligibleKinds: eligible, claims: current.length, faults: expected.size,
+    ineligibleClaims, nonKilledFaults, unavailableReasons: [...reasons].sort(),
+  };
+}

package/src/probe/policy-freshness.mjs

@@ -0,0 +1,74 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { validate, methodOf } from '../../spec/lib/validate.mjs';
+import { sha256 } from '../util/hash.mjs';
+import { defenderSelection, isReusable, subjectOf } from './attribution.mjs';
+import { discoverDefendersDetailed } from './discover.mjs';
+import { resolveDefenders } from './runners/shared.mjs';
+import { hashNativeTestUniverse } from './universe.mjs';
+
+// Point-in-time reads, not a transaction over the whole project. Never turn a
+// missing file into the empty-file hash that diagnostic probe records can use.
+function currentHash(projectDir, file) {
+  if (typeof file !== 'string' || isAbsolute(file) || file.split(/[\\/]/).includes('..')) throw new Error('unsafe input path');
+  const path = join(projectDir, file);
+  const resolved = realpathSync(path);
+  const inside = relative(realpathSync(projectDir), resolved);
+  if (isAbsolute(inside) || inside === '..' || inside.startsWith(`..${sep}`)) throw new Error('input escaped project');
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile()) throw new Error('input is not a regular file');
+    const hash = sha256(readFileSync(fd));
+    const after = fstatSync(fd);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || realpathSync(path) !== resolved) throw new Error('input changed during read');
+    return hash;
+  } finally { closeSync(fd); }
+}
+
+/** Internal policy boundary: native listing plus current per-fault bindings.
+ * Legacy/static universes and any uncertainty refuse; verdicts remain intact.
+ */
+export function originPolicyInputsFresh({ projectDir, claims, evidence, universe }) {
+  try {
+    if (!validate('claims', claims).ok || !validate('evidence', evidence).ok) return false;
+    if (methodOf(evidence.run) !== 'fault-injection' || evidence.run.provisional || evidence.run.confirmRuns < 3) return false;
+    const testUniverseHash = hashNativeTestUniverse(universe.manifests);
+    if (universe.testUniverseHash !== testUniverseHash) return false;
+    const matchesRunner = (recorded, current) => recorded?.name === current?.name && recorded?.version === current?.version;
+    if (!universe.primaryRunner || !matchesRunner(evidence.run.runner, universe.primaryRunner)) return false;
+    if ((evidence.run.runners ?? []).some((recorded) => !universe.runners?.some((current) => matchesRunner(recorded, current)))) return false;
+    const allTests = Object.freeze([...new Set([...universe.manifests.values()].flatMap((m) => m.files))].sort());
+    const expected = new Map();
+    for (const claim of claims.claims) for (const fault of claim.faults) {
+      if (methodOf(fault) !== 'fault-injection') return false;
+      expected.set(JSON.stringify([claim.id, fault.id]), { claim, fault });
+    }
+    if (!expected.size || evidence.records.length !== expected.size) return false;
+    const seen = new Set();
+    for (const record of evidence.records) {
+      const key = JSON.stringify([record.claim.id, record.subject.id]);
+      const current = expected.get(key);
+      if (!current || seen.has(key)) return false;
+      seen.add(key);
+      const { claim, fault } = current;
+      const subject = subjectOf(fault, sha256);
+      if (['kind', 'id', 'file', 'faultClass', 'contentHash', 'producedBy'].some((field) => !isDeepStrictEqual(record.subject[field], subject[field]))) return false;
+      const { requested, selectionSource } = defenderSelection(claim, fault);
+      const discovery = requested.length ? null : discoverDefendersDetailed(projectDir, fault.file, allTests);
+      if (discovery?.indeterminate.length) return false;
+      const resolved = requested.length ? resolveDefenders(projectDir, requested) : discovery.canDetect;
+      if (resolved.some((file) => !allTests.includes(file))) return false;
+      const hashes = (files) => Object.fromEntries(files.map((file) => [file, currentHash(projectDir, file)]));
+      const inputs = {
+        targetHash: currentHash(projectDir, fault.file),
+        defenderHashes: hashes(resolved),
+        testUniverseHash,
+        discoveryHashes: hashes(discovery?.dependencies ?? []),
+      };
+      if (!isReusable(record, { claim, requested, resolved, selectionSource, contentHash: subject.contentHash, inputs })) return false;
+    }
+    return true;
+  } catch { return false; }
+}

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';
@@ -16,7 +19,9 @@ import { classifyIndependence } from './independence.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.
@@ -183,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 = [];
@@ -218,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)) {
@@ -265,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
@@ -277,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) => {
@@ -295,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;
       }
@@ -304,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);
@@ -373,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 },
@@ -380,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 } : {}) },
-      runner: { name: labelOf(runner), ...((runnerVersion ?? readRunnerVersion(projectDir, runner.name)) ? { version: runnerVersion ?? readRunnerVersion(projectDir, runner.name) } : {}) },
+      repo: { head, dirty, ...(snapshot ? { snapshot } : {}), ...(ignoredDirty.length ? { ignoredDirty } : {}) },
+      runner: { name: labelOf(runner), ...((runnerVersion ?? readRunnerVersion(projectDir, runner.name)) ? { version: runnerVersion ?? readRunnerVersion(projectDir, runner.name) } : {}), ...(runnerSource === 'builtin' ? { source: runnerSource } : {}) },
       ...(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
@@ -394,6 +418,7 @@ export async function probe({
       mode: iso.mode,
     },
     records,
+    origins: recordedOriginSummary(records),
   };
 }
 
@@ -520,7 +545,7 @@ 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, ...defenderSelection(claim, fault), resolved: defenders, contentHash: subject.contentHash })) {
+  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 };
   }
 

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';
@@ -155,6 +156,7 @@ export function runDiscoveryProcess({
   timeoutMs = DISCOVERY_TIMEOUT_MS,
   maxOutputBytes = MAX_DISCOVERY_OUTPUT_BYTES,
   env = {},
+  cleanupOnClose = false,
 }) {
   validateArgv(argv);
   if (typeof projectDir !== 'string' || projectDir.length === 0 || projectDir.includes('\0')) throw new DiscoveryError('projectDir must be a non-empty path');
@@ -177,6 +179,7 @@ export function runDiscoveryProcess({
       return;
     }
 
+    registerChild(child, () => terminateProcessTree(child));
     const started = Date.now();
     const stdout = [];
     const stderr = [];
@@ -221,6 +224,7 @@ export function runDiscoveryProcess({
 
     child.on('close', (code, signal) => {
       clearTimeout(timer);
+      if (cleanupOnClose) terminateProcessTree(child);
       if (settled) return;
       if (terminalError) {
         reject(terminalError);

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 * as nodeTest from './node-test.mjs';
 import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs } from './discovery.mjs';
 
 export const RUNNERS = {
@@ -14,9 +15,10 @@ export const RUNNERS = {
   // evidence means.
   pytest: pythonRunner.pinned('pytest'),
   unittest: pythonRunner.pinned('unittest'),
+  'node-test': nodeTest,
 };
 
-export const RUNNER_NAMES = ['vitest', 'jest', 'playwright', 'python', 'pytest', 'unittest'];
+export const RUNNER_NAMES = ['vitest', 'jest', 'playwright', 'python', 'pytest', 'unittest', 'node-test'];
 
 /**
  * Runners that own files rather than projects: a defender under Playwright's

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/node/entry.mjs

@@ -0,0 +1,11 @@
+import { appendFileSync, statSync } from 'node:fs';
+
+// Node sets this only in its isolated test workers. Record the entry before
+// evaluating project code; a declaration imported from a helper is not an entry.
+if (process.env.NODE_TEST_CONTEXT?.startsWith('child')) {
+  const receipt = JSON.stringify({ file: process.argv[1], pid: process.pid, version: process.versions.node });
+  if (Buffer.byteLength(receipt) > 8192 || statSync(process.env.TESTGUARD_NODE_ENTRIES).size + Buffer.byteLength(receipt) > 16 * 1024 * 1024) {
+    throw new Error('node-test entry receipts exceeded their byte bound');
+  }
+  appendFileSync(process.env.TESTGUARD_NODE_ENTRIES, `${receipt},`);
+}

package/src/probe/runners/node/report.mjs

@@ -0,0 +1,66 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+const MAX_RESULTS = 100_000;
+const MAX_REPORT_BYTES = 16 * 1024 * 1024;
+const boundedText = (value) => String(value ?? '').slice(0, 1000);
+
+/** Keep only structured identity, never arbitrary error objects or assertion values. */
+const errorIdentity = (error) => error == null ? undefined : {
+  failureType: boundedText(error.failureType),
+  code: boundedText(error.code),
+  message: boundedText(error.message ?? error),
+  fileExit: Object.hasOwn(error, 'exitCode') || Object.hasOwn(error, 'signal'),
+};
+
+/** Pure report accumulator. File/suite summaries never count as assertion kills. */
+export function createReport({ projectDir, version, collect = false }) {
+  const cases = [];
+  const parents = [];
+  const pending = new Map();
+  let bytes = 0;
+  let failed = false;
+  let diagnostic = '';
+  const add = (item) => {
+    bytes += Buffer.byteLength(JSON.stringify(item));
+    if (cases.length >= MAX_RESULTS || bytes > MAX_REPORT_BYTES) throw new Error('node-test results exceeded their report bound');
+    cases.push(item);
+  };
+  const accept = ({ type, data }) => {
+    if (['test:stderr', 'test:diagnostic'].includes(type)) {
+      diagnostic = `${diagnostic}\n${String(data?.message ?? '')}`.slice(-65536);
+      return;
+    }
+    if (!['test:start', 'test:pass', 'test:fail'].includes(type)) return;
+    if (!data || typeof data.name !== 'string' || !Number.isSafeInteger(data.nesting) || data.nesting < 0) throw new Error('malformed node-test event identity');
+    const file = typeof data.file === 'string' ? resolve(projectDir, data.file) : undefined;
+    const names = parents;
+    const key = JSON.stringify([file, data.nesting, data.name]);
+    if (type === 'test:start') {
+      if (pending.size >= MAX_RESULTS || data.nesting > 1000) throw new Error('node-test pending results exceeded their bound');
+      pending.set(key, (pending.get(key) ?? 0) + 1);
+      names.length = data.nesting;
+      names[data.nesting] = data.name;
+      return;
+    }
+    if (!pending.has(key)) throw new Error('node-test finished a result without its start');
+    if (pending.get(key) === 1) pending.delete(key);
+    else pending.set(key, pending.get(key) - 1);
+    const error = errorIdentity(data.details?.error);
+    const skipped = ['skip', 'todo', 'expectFailure'].some((key) => Object.hasOwn(data, key) && data[key] !== false);
+    if (type === 'test:fail' && !skipped) failed = true;
+    const container = data.nesting === 0 && (isAbsolute(data.name) || file && resolve(projectDir, data.name) === file)
+      && (data.line === undefined || data.line === 1) && (data.column === undefined || data.column === 1);
+    const suite = data.details?.type === 'suite' || error?.failureType === 'subtestsFailed';
+    const name = [...names.slice(0, data.nesting), data.name].join(' > ');
+    const rel = file ? relative(projectDir, file).split(sep).join('/') : '';
+    // Refuse ambiguous/escaped attribution rather than invent a killer id.
+    const outside = rel === '..' || rel.startsWith('../') || isAbsolute(rel);
+    if (!container && (!rel || outside || !name || name.length > 1000)) throw new Error(outside ? 'node-test result attribution is outside the selected project' : 'node-test result has unavailable or unsupported attribution');
+    add({ file: rel, name, container, suite, skipped, passed: type === 'test:pass', ...(error ? { error } : {}) });
+  };
+  const finish = (entries) => {
+    if (pending.size) throw new Error('node-test stopped before every started result finished');
+    return { schemaVersion: 1, engine: 'node-test', version, collect, complete: true, failed, entries, cases, diagnostic };
+  };
+  return { accept, finish };
+}

package/src/probe/runners/node/runner.mjs

@@ -0,0 +1,42 @@
+import { appendFileSync, writeFileSync } from 'node:fs';
+import { readBoundedJsonFile } from '../discovery.mjs';
+import { createReport } from './report.mjs';
+
+// The tool may itself be called from a Node test worker. This new controller
+// must initialize as a parent, rather than Node's nested-run no-op mode.
+delete process.env.NODE_TEST_CONTEXT;
+const { run } = await import('node:test');
+
+const collect = process.env.TESTGUARD_NODE_COLLECT === '1';
+const workers = Number(process.env.TESTGUARD_NODE_WORKERS);
+const files = process.argv.slice(2);
+if (!Number.isSafeInteger(workers) || workers < 1) throw new Error('invalid node-test worker ceiling');
+const report = createReport({ projectDir: process.cwd(), version: process.versions.node, collect });
+// run() on the Node20 floor uses argv for default native collection. The
+// launcher is not a project test entry. Explicit file runs keep their paths.
+process.argv = [process.execPath];
+// The floor predates run({testNamePatterns}) and --test-concurrency. Put the
+// name filter only in CHILD argv, keeping native file containers collectible.
+if (collect) process.execArgv.push('--test-name-pattern=(?!)');
+const cancellation = new AbortController();
+const stream = run({ signal: cancellation.signal, concurrency: workers, ...(files.length ? { files } : {}), ...(collect ? { testNamePatterns: ['(?!)'] } : {}) });
+try {
+  for await (const event of stream) report.accept(event);
+  appendFileSync(process.env.TESTGUARD_NODE_ENTRIES, 'null]}');
+  const entries = readBoundedJsonFile(process.env.TESTGUARD_NODE_ENTRIES).entries;
+  if (!Array.isArray(entries) || entries.at(-1) !== null) throw new Error('incomplete node-test entry receipts');
+  entries.pop();
+  const doc = report.finish(entries);
+  const text = JSON.stringify(doc);
+  if (Buffer.byteLength(text) > 16 * 1024 * 1024) throw new Error('node-test report exceeded its byte bound');
+  if (collect) process.stdout.write(text);
+  else writeFileSync(process.env.TESTGUARD_NODE_REPORT, text, { mode: 0o600 });
+  if (doc.failed) process.exitCode = 1;
+} catch (error) {
+  cancellation.abort();
+  stream.destroy();
+  // The Node20 floor's test harness can swallow an uncaught controller error.
+  // Retain bounded diagnostics while leaving the incomplete report unwritten.
+  process.stderr.write(`node-test reporter failed: ${String(error.message ?? error).slice(0, 1000)}\n`);
+  process.exitCode = 1;
+}