testguard-cli 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-10-01
+
+Automated weekly release — everything merged since `v0.17.0`.
+
+### Changed
+
+- Merge branch 'main' into dependabot/github_actions/all-actions-d5b8684899
+- feat: native Node probes with measured startup savings (#192)
+- chore(homebrew): sha256 for v0.17.0 (#191)
+- chore(deps): bump actions/cache
+
+
+### Added
+
+- Explicit `--runner node-test` support for plain JavaScript projects using
+  Node's built-in test framework, with native entry-file discovery, fresh
+  process confirmations and bounded structured reports. No runner is installed
+  and existing automatic runner selection is unchanged.
+
 ## [0.17.0] - 2026-10-01
 
 Automated weekly release — everything merged since `v0.16.0`.

package/README.md

@@ -127,9 +127,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.17.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.18.0` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.17.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.18.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -302,7 +302,23 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    version, its own bin script — and only then from an executable on PATH,
    which the evidence records as `runner.source: "path"`; `npx` is never
    asked, because its cache answers for packages a project does not have.
-   Anything else goes through `--runner-cmd`. Each runner is proven against
+   **Node's built-in framework** uses explicit `--runner node-test` with plain
+   JavaScript test files and default Node collection. It uses the Node executable
+   running TestGuard, records `runner.source: "builtin"` and its actual version,
+   and installs nothing. Discovery loads test modules with test bodies filtered
+   out, so top-level code can run. Custom loaders, `NODE_OPTIONS`, `NODE_PATH`
+   and module-mocking configurations are outside this initial adapter's scope.
+   `auto` keeps its existing runner order. Each confirmation uses fresh isolated
+   processes and the same worker, timeout and confirmation rules.
+
+   To reproduce the narrow native-runner comparison, run
+   `node .github/scripts/benchmark-node-runner.mjs --out /absolute/receipt-dir`
+   from this repository after installing its pinned development dependencies.
+   It compares 17 identical classifier inputs and four existing faults through
+   complete probes, with three confirmations, fresh worker receipts and
+   reversed execution order. Results describe that workload and runtime only.
+
+   Other frameworks go through `--runner-cmd`. Each runner is proven against
    its own copy of the known-answer fixture.
 
    **Python** runs under `pytest` when the project's interpreter can import
@@ -769,12 +785,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.17.0
+- uses: raccioly/testguard@v0.18.0
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.17.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.18.0/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",

package/spec/GATE-SEMANTICS.md

@@ -311,6 +311,27 @@ Rules that follow from the table:
    competing owned runners or a declared defender absent from every manifest
    are precondition failures, never heuristic routing decisions.
 
+   The explicit `node-test` adapter uses Node's native collection with test
+   bodies excluded by a never-matching name pattern. Collection still loads
+   test modules and may run their top-level code; a load error, incomplete
+   collection or budget expiry refuses discovery. An injected child preload
+   records each actual entry file before project evaluation, so imported test
+   declarations cannot masquerade as additional entry files. No filename
+   fallback or inferred npm-script configuration is permitted. This adapter
+   supports plain JavaScript under Node's default collection, without custom
+   loaders, `NODE_OPTIONS` or `NODE_PATH`; it is never selected by `auto`.
+   Each confirmation uses fresh, isolated Node test processes under the
+   existing worker ceiling. Reports count executed test results, not individual
+   assertion calls: suite and file-container summaries are not extra tests,
+   and skipped/TODO results cannot establish a green defender by themselves.
+   A test-body failure counts as a rejection; a load error, hook failure,
+   cancellation or timeout never counts as an assertion kill. Malformed or
+   unfinished reports are load errors. Evidence names `node-test`, records
+   `source: builtin` and the actual Node version, and binds the executable and
+   reporter strategy to its discovery hash. Another framework's evidence
+   cannot supply its confirmations. Native module-mocking configurations are
+   outside this adapter's initial admission boundary.
+
    Static string literals are conservative dependency candidates, not proof
    of a filesystem dependency. Missing candidates and ordinary directories
    (including `/` in URL bases and string separators) are ignored. An existing

package/spec/lib/validate.mjs

@@ -183,6 +183,9 @@ const semantic = {
 
   evidence(doc) {
     const errors = [];
+    if (doc.run.runner?.source === 'builtin' && (doc.run.runner.name !== 'node-test' || !/^(?:[2-9]\d|[1-9]\d{2,})\.\d+\.\d+(?:[-+].+)?$/.test(doc.run.runner.version ?? ''))) {
+      errors.push({ path: '/run/runner', message: 'builtin source requires node-test and its actual Node version (20 or newer)' });
+    }
     if (doc.run.measurements) {
       const m = doc.run.measurements;
       if (Math.abs(m.elapsedMs - m.runnerMs - m.overheadMs) > 0.001) errors.push({ path: '/run/measurements', message: 'elapsedMs must equal runnerMs plus overheadMs' });

package/spec/schemas/evidence.schema.json

@@ -81,10 +81,11 @@
               "maxLength": 64
             },
             "source": {
-              "description": "`project`: the runner package resolved from the project and its own bin script ran. `path`: no such package in the project; an executable of that name on PATH ran instead (a legitimate monorepo setup, but not the project's pinned version).",
+              "description": "`project`: the runner package resolved from the project. `path`: an executable on PATH ran instead. `builtin`: the explicitly selected node-test engine uses the Node executable running TestGuard; its version is required.",
               "enum": [
                 "project",
-                "path"
+                "path",
+                "builtin"
               ]
             }
           },

package/src/cli.mjs

@@ -64,7 +64,7 @@ probe
                        append-only lines everywhere else, so a redirected log and CI see progress
                        instead of twenty silent minutes. Always on stderr; ndjson also streams verdicts
                        --confirm below 3 is PROVISIONAL: verdicts print with "?", evidence goes to .testguard/evidence-provisional.json
-  --runner <name>      vitest | jest | playwright | python | pytest | unittest | auto
+  --runner <name>      vitest | jest | playwright | python | pytest | unittest | node-test | auto
                        (default: auto — first of vitest, jest, python that resolves. A defender under playwright's testDir
                        always runs under playwright, and a .py defender always under python, whatever the project runner.
                        python picks pytest when the interpreter can import it and stdlib unittest otherwise; pytest and

package/src/probe/probe.mjs

@@ -403,7 +403,7 @@ export async function probe({
       startedAt,
       finishedAt: new Date().toISOString(),
       repo: { head, dirty, ...(snapshot ? { snapshot } : {}), ...(ignoredDirty.length ? { ignoredDirty } : {}) },
-      runner: { name: labelOf(runner), ...((runnerVersion ?? readRunnerVersion(projectDir, runner.name)) ? { version: runnerVersion ?? readRunnerVersion(projectDir, runner.name) } : {}) },
+      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,
       measurements,

package/src/probe/runners/discovery.mjs

@@ -156,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');
@@ -223,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/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;
+}

package/src/probe/runners/node-test.mjs

@@ -0,0 +1,130 @@
+import { closeSync, mkdtempSync, openSync, readFileSync, readSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { runProcess } from './shared.mjs';
+import { createDiscoveryManifest, DiscoveryError, hashDiscoveryConfigs, normalizeDiscoveredFiles, runDiscoveryProcess } from './discovery.mjs';
+
+export const name = 'node-test';
+export const testGlobs = []; // Native collection is authoritative; never guess from globs.
+const HERE = join(dirname(fileURLToPath(import.meta.url)), 'node');
+const RUNNER = join(HERE, 'runner.mjs');
+const ENTRY = join(HERE, 'entry.mjs');
+const VERSION = process.versions.node;
+const strategyHash = () => {
+  const digest = createHash('sha256');
+  const descriptor = openSync(process.execPath, 'r');
+  try {
+    const bytes = Buffer.alloc(256 * 1024);
+    let length;
+    while ((length = readSync(descriptor, bytes, 0, bytes.length, null)) > 0) digest.update(bytes.subarray(0, length));
+  } finally { closeSync(descriptor); }
+  for (const file of [fileURLToPath(import.meta.url), ...['runner.mjs', 'entry.mjs', 'report.mjs'].map((file) => join(HERE, file)), ...['shared.mjs', 'discovery.mjs', 'lifecycle.mjs'].map((file) => join(HERE, '..', file))]) digest.update(readFileSync(file));
+  return digest.digest('hex');
+};
+const admissionError = () => Number(VERSION.split('.')[0]) < 20 ? 'node-test requires Node20 or newer'
+  : process.env.NODE_OPTIONS || process.env.NODE_PATH ? 'node-test supports default JavaScript loading; NODE_OPTIONS and NODE_PATH must be unset'
+  : undefined;
+export const check = async () => admissionError()
+  ? { ok: false, message: admissionError() }
+  : { ok: true, version: VERSION, source: 'builtin' };
+export const fatalEdit = () => '/* testguard negative control: this file must not parse */\n(\n';
+
+const receipts = () => {
+  const dir = mkdtempSync(join(tmpdir(), 'testguard-node-'));
+  const file = join(dir, 'entries.json');
+  writeFileSync(file, '{"entries":[', { mode: 0o600 });
+  return { dir, file };
+};
+const environment = (file, collect, workers) => ({
+  TESTGUARD_NODE_ENTRIES: file,
+  TESTGUARD_NODE_COLLECT: collect ? '1' : '0',
+  TESTGUARD_NODE_WORKERS: String(workers),
+  TESTGUARD_NODE_REPORT: '{out}',
+  NODE_TEST_CONTEXT: '',
+  NODE_DISABLE_COMPILE_CACHE: '1',
+});
+export const argvFor = (projectDir, files) => [process.execPath, `--import=${ENTRY}`, RUNNER, ...files.map((file) => resolve(realpathSync(projectDir), file))];
+
+/** Reject unsupported/incomplete envelopes before deriving any verdict inputs. */
+export function validateReport(report) {
+  if (report?.schemaVersion !== 1 || report.engine !== name || report.complete !== true
+    || report.version !== VERSION || typeof report.collect !== 'boolean' || typeof report.failed !== 'boolean'
+    || !Array.isArray(report.entries) || report.entries.length > 100_000
+    || !Array.isArray(report.cases) || report.cases.length > 100_000
+    || report.diagnostic !== undefined && (typeof report.diagnostic !== 'string' || report.diagnostic.length > 65536)) throw new DiscoveryError('malformed or incomplete node-test report');
+  const pids = new Set();
+  for (const entry of report.entries) {
+    if (!entry || typeof entry.file !== 'string' || !entry.file || entry.file.includes('\0') || !Number.isSafeInteger(entry.pid) || entry.pid <= 0 || pids.has(entry.pid) || entry.version !== report.version) throw new DiscoveryError('malformed node-test worker receipt');
+    pids.add(entry.pid);
+  }
+  for (const t of report.cases) {
+    if (!t || typeof t.file !== 'string' || typeof t.name !== 'string'
+      || ['container', 'suite', 'skipped', 'passed'].some((k) => typeof t[k] !== 'boolean')
+      || t.error !== undefined && (typeof t.error !== 'object' || t.error === null || typeof t.error.failureType !== 'string' || typeof t.error.code !== 'string' || typeof t.error.message !== 'string' || typeof t.error.fileExit !== 'boolean')) throw new DiscoveryError('malformed node-test result');
+    if (t.passed && t.error || !t.container && (!t.file || t.file.split('/').some((part) => part === '..' || part === '') || t.file.includes('\\') || t.file.startsWith('/') || !t.name)) throw new DiscoveryError('inconsistent node-test result identity');
+  }
+  if (report.failed !== report.cases.some((t) => !t.passed && !t.skipped)) throw new DiscoveryError('inconsistent node-test failure summary');
+  return report;
+}
+
+export function parseReport(report, durationMs) {
+  validateReport(report);
+  if (report.collect) throw new DiscoveryError('collection is not a test run');
+  const tests = report.cases.filter((t) => !t.container && !t.suite && !t.skipped);
+  const failed = tests.filter((t) => !t.passed);
+  const timeout = report.cases.filter((t) => !t.skipped && t.error?.failureType === 'testTimeoutFailure');
+  const loadErrors = report.cases.filter((t) => !t.skipped && !t.passed
+    && (t.container || t.suite ? t.error?.failureType !== 'subtestsFailed' : !['testCodeFailure', 'testTimeoutFailure'].includes(t.error?.failureType) || t.error?.fileExit));
+  if (!tests.length || !report.entries.length) loadErrors.push({ error: { message: 'node-test executed no test bodies' } });
+  const assertionFailures = failed.filter((t) => t.error?.failureType === 'testCodeFailure' && !t.error.fileExit).length;
+  const names = new Map();
+  for (const t of tests) { const key = `${t.file}::${t.name}`; names.set(key, (names.get(key) ?? 0) + 1); }
+  const seen = new Map();
+  const failedTests = [];
+  for (const t of tests) {
+    const key = `${t.file}::${t.name}`;
+    const ordinal = (seen.get(key) ?? 0) + 1; seen.set(key, ordinal);
+    if (!t.passed) failedTests.push(names.get(key) > 1 ? `${key} [case ${ordinal}]` : key);
+  }
+  return {
+    run: { outcome: loadErrors.length ? 'error' : report.failed || failed.length ? 'fail' : 'pass', tests: { total: tests.length, passed: tests.length - failed.length, failed: failed.length }, assertionFailures: loadErrors.length ? 0 : assertionFailures, durationMs },
+    timeouts: timeout.length,
+    loadMessage: loadErrors.length ? report.diagnostic?.split(/\r?\n/).find((line) => /(?:\bError:|SyntaxError:|cannot find|unexpected token)/i.test(line))?.trim().slice(0, 1000) ?? loadErrors[0]?.error?.message : undefined,
+    failedTests,
+  };
+}
+
+export async function discoverTests({ projectDir, version, timeoutMs, maxOutputBytes } = {}) {
+  if (admissionError()) throw new DiscoveryError(admissionError());
+  const before = hashDiscoveryConfigs(projectDir);
+  const spool = receipts();
+  try {
+    const result = await runDiscoveryProcess({ projectDir, argv: argvFor(projectDir, []), timeoutMs, maxOutputBytes, cleanupOnClose: true, env: environment(spool.file, true, 1) });
+    let report;
+    try { report = validateReport(JSON.parse(result.stdout)); } catch (error) { throw new DiscoveryError(`node-test collection report: ${error.message}`); }
+    if (!report.collect || report.failed) throw new DiscoveryError('node-test collection did not complete successfully');
+    const files = normalizeDiscoveredFiles(projectDir, report.entries.map((entry) => entry.file));
+    if (files.length !== report.entries.length) throw new DiscoveryError('node-test collection executed a duplicate entry');
+    const configFiles = hashDiscoveryConfigs(projectDir);
+    if (JSON.stringify(configFiles) !== JSON.stringify(before)) throw new DiscoveryError('node-test discovery config changed while modules were being collected');
+    const strategy = strategyHash();
+    return createDiscoveryManifest({ runner: name, version, files, configFiles, source: `native-node-entry-v1:${strategy}` });
+  } finally { rmSync(spool.dir, { recursive: true, force: true }); }
+}
+
+export async function run(opts) {
+  if (admissionError()) throw new DiscoveryError(admissionError());
+  if (!opts.files?.length) throw new DiscoveryError('node-test requires explicit selected test files');
+  const files = normalizeDiscoveredFiles(opts.projectDir, opts.files);
+  const spool = receipts();
+  try {
+    return await runProcess({ ...opts, files, cleanupOnClose: true, env: environment(spool.file, false, opts.serial ? 1 : opts.workers ?? 1), argv: (selected) => argvFor(opts.projectDir, selected), parse: (report, durationMs) => {
+      validateReport(report);
+      const entries = normalizeDiscoveredFiles(opts.projectDir, report.entries.map((entry) => entry.file));
+      if (entries.length !== report.entries.length || JSON.stringify(entries) !== JSON.stringify(files)) throw new DiscoveryError('node-test did not execute every selected entry exactly');
+      return parseReport(report, durationMs);
+    } });
+  } finally { rmSync(spool.dir, { recursive: true, force: true }); }
+}

package/src/probe/runners/shared.mjs

@@ -241,7 +241,7 @@ export function parseReport(report, durationMs) {
  * runner's command line; `command` (tests) or `commandTemplate` (--runner-cmd)
  * override it.
  */
-export function runProcess({ projectDir, files, budgetMs = 120_000, command, commandTemplate, argv, env = {}, parse = parseReport }) {
+export function runProcess({ projectDir, files, budgetMs = 120_000, command, commandTemplate, argv, env = {}, parse = parseReport, cleanupOnClose = false }) {
   assertNotCancelled();
   const outFile = join(tmpdir(), `testguard-run-${randomBytes(6).toString('hex')}.json`);
   const [cmd, ...args] = command
@@ -268,6 +268,7 @@ export function runProcess({ projectDir, files, budgetMs = 120_000, command, com
 
     child.on('close', () => {
       clearTimeout(timer);
+      if (cleanupOnClose) terminateProcessTree(child);
       const durationMs = Date.now() - started;
       let result;
       if (killed) {