testguard-cli 0.16.0 → 0.18.0

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/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);
@@ -238,7 +241,8 @@ 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
     ?? (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(() => {
@@ -262,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) {
@@ -270,7 +277,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. */

package/src/replay/replay.mjs

@@ -1,3 +1,4 @@
+import { resetInterpreterCache } from '../probe/runners/python.mjs';
 import { existsSync, rmSync, realpathSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -84,6 +85,8 @@ export async function replay({
   confirmRuns = 3,
   budgetMs = 120_000,
   commandBudget,
+  workers = 1,
+  serial = workers === 1,
   runnerCommand,
   runnerName = 'auto',
   nodeModules,
@@ -93,6 +96,7 @@ export async function replay({
   onProgress = () => {},
   onStage = () => {},
 }) {
+  resetInterpreterCache();
   commandBudget?.assertOpen();
   projectDir = realpathSync(resolve(projectDir));
   const root = repoRoot(projectDir);
@@ -142,7 +146,7 @@ export async function replay({
         }
         universe = buildReplayRunnerUniverse(runnerUsed, manifests);
       }
-      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, commandTemplate, runner: runnerUsed, universe, onStage, index: i + 1, total: selected.length });
+      const record = await replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner: runnerUsed, universe, onStage, index: i + 1, total: selected.length });
       records.push(record);
       onProgress(record);
     } finally {
@@ -209,7 +213,7 @@ export function partitionReplayDefenders(files, primary, universe) {
   return groups;
 }
 
-async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, commandTemplate, runner, universe, onStage, index, total }) {
+async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, commandBudget, workers, serial, commandTemplate, runner, universe, onStage, index, total }) {
   // git reports paths from the REPOSITORY root; the runner and every file
   // operation here work inside the scratch worktree, relative to the PROJECT
   // directory. Map once, and refuse anything that would land outside the
@@ -325,12 +329,12 @@ async function replayOne({ fix, iso, root, projectDir, confirmRuns, budgetMs, co
       // A custom command is one explicit execution boundary. Preserve that
       // contract exactly; TestGuard cannot infer several native engines from
       // an opaque user command.
-      res = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files: related, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate });
+      res = await runner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files: related, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, commandTemplate, workers, serial });
     } else {
       const parts = [];
       for (const [configuredRunner, files] of partitionReplayDefenders(related, runner, universe)) {
         commandBudget?.assertOpen();
-        parts.push(await configuredRunner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs }));
+        parts.push(await configuredRunner.run({ projectDir: iso.projectDir, sourceDir: projectDir, files, budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs, workers, serial }));
         commandBudget?.assertOpen();
       }
       res = mergeRuns(parts);

package/src/scaffold/admission.mjs

@@ -0,0 +1,117 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { readSpecDoc } from '../evidence/writer.mjs';
+import { sha256 } from '../util/hash.mjs';
+
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_SOURCE_BYTES = 16 * 1024 * 1024;
+const MAX_FILES = 32;
+const SUPPORTED = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx', '.py']);
+const PROTECTED = new Set(['evidence.json', 'evidence-partial.json', 'evidence-provisional.json', 'baseline.json', 'sweep-evidence.json']);
+
+function refuse(reason) { throw new Error(`draft append admission refused: ${reason}`); }
+function identity(stat) { return { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, mode: stat.mode }; }
+function same(stat, expected) { return Object.entries(expected).every(([key, value]) => stat[key] === value); }
+
+function selectedPath(requestedRoot, file) {
+  if (typeof file !== 'string' || !file || file.includes('\0') || file.includes('\\') || file.split('/').some((part) => part === '.' || part === '..')) refuse('unsafe-path');
+  const rel = relative(requestedRoot, resolve(requestedRoot, file));
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) refuse('outside-project');
+  return rel.split(sep).join('/');
+}
+
+/** Repeat the complete in-checkout path walk; never authorize by existence. */
+function inspect(root, file) {
+  const base = lstatSync(root);
+  if (base.isSymbolicLink() || !base.isDirectory()) refuse('unsafe-root');
+  const parts = file.split('/');
+  let path = root;
+  for (let i = 0; i < parts.length; i++) {
+    path = join(path, parts[i]);
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) refuse('symlink');
+    if (i < parts.length - 1) {
+      if (!stat.isDirectory()) refuse('not-directory');
+      try { lstatSync(join(path, 'testguard.claims.json')); refuse('nested-project'); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    } else {
+      if (!stat.isFile() || stat.nlink !== 1) refuse('not-single-regular-file');
+      if (stat.size > MAX_FILE_BYTES) refuse('file-byte-limit');
+      return { path, stat };
+    }
+  }
+}
+
+function readInput(root, file, admitted) {
+  if (constants.O_NOFOLLOW === undefined) refuse('nofollow-unavailable');
+  const fd = openSync(admitted.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const expected = identity(admitted.stat);
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1 || !same(before, expected)) refuse('input-changed');
+    const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = readSync(fd, buffer, length, buffer.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    if (length > MAX_FILE_BYTES) refuse('file-byte-limit');
+    if (length !== expected.size || !same(fstatSync(fd), expected)) refuse('input-changed');
+    const current = inspect(root, file);
+    if (!same(current.stat, expected)) refuse('input-changed');
+    const bytes = buffer.subarray(0, length);
+    let source;
+    try { source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); }
+    catch { refuse('invalid-utf8'); }
+    if (source.includes('\0')) refuse('invalid-encoding');
+    return { file, path: admitted.path, source, hash: sha256(bytes), identity: expected };
+  } finally { closeSync(fd); }
+}
+
+/** Explicit text input only: no statements, claims, provenance promotion or writes. */
+export function admitIntentDocument({ projectDir, file }) {
+  const requestedRoot = resolve(projectDir);
+  if (lstatSync(requestedRoot).isSymbolicLink()) refuse('unsafe-root');
+  const root = realpathSync(requestedRoot);
+  const name = selectedPath(requestedRoot, file);
+  if (name.split('/').some(part => ['.local', '.wolf', '.git', '.testguard', 'graphify-out'].includes(part))) refuse('excluded-document');
+  if (!['.md', '.txt', '.rst', '.adoc'].includes(extname(name))) refuse('unsupported-document');
+  const input = readInput(root, name, inspect(root, name));
+  Object.freeze(input.identity);
+  return Object.freeze(input);
+}
+
+/** Selected conforming marker only; neither claim contents nor scope authority are returned. */
+export function admitIntentProject({ projectDir }) {
+  const requestedRoot = resolve(projectDir);
+  if (lstatSync(requestedRoot).isSymbolicLink()) refuse('unsafe-root');
+  const root = realpathSync(requestedRoot);
+  if (root.split(sep).some(part => ['.local', '.wolf', '.git', '.testguard', 'graphify-out'].includes(part))) refuse('excluded-project');
+  const file = 'testguard.claims.json';
+  const input = readInput(root, file, inspect(root, file));
+  readSpecDoc('claims', input.path, { source: input.source });
+  const marker = Object.freeze({ file, hash: input.hash, identity: Object.freeze(input.identity) });
+  return Object.freeze({ projectDir: root, marker });
+}
+
+/** Internal read-only input snapshot. This is not publication authority. */
+export function admitDraftAppend({ projectDir, draftPath, files, claimId }) {
+  if (!Array.isArray(files) || !files.length || files.length > MAX_FILES) refuse('source-count-limit');
+  if (typeof claimId !== 'string' || !claimId.trim() || claimId !== claimId.trim() || claimId.includes(',')) refuse('claim-selection');
+  const requestedRoot = resolve(projectDir);
+  if (lstatSync(requestedRoot).isSymbolicLink()) refuse('unsafe-root');
+  const root = realpathSync(requestedRoot);
+  const draftFile = selectedPath(requestedRoot, draftPath);
+  if (basename(draftFile) === 'testguard.claims.json' || (draftFile.startsWith('.testguard/') && PROTECTED.has(basename(draftFile)))) refuse('protected-destination');
+  const names = files.map((file) => selectedPath(requestedRoot, file));
+  if (new Set(names).size !== names.length || names.includes(draftFile)) refuse('input-alias');
+  if (names.some((file) => !SUPPORTED.has(extname(file)))) refuse('unsupported-source');
+  const draftInput = readInput(root, draftFile, inspect(root, draftFile));
+  const doc = readSpecDoc('claims', draftInput.path, { source: draftInput.source });
+  if (doc.claims.filter((claim) => claim.id === claimId).length !== 1) refuse('unknown-claim');
+  const admitted = names.sort().map((file) => ({ file, ...inspect(root, file) }));
+  if (admitted.reduce((total, input) => total + input.stat.size, 0) > MAX_SOURCE_BYTES) refuse('source-byte-limit');
+  const sources = admitted.map((input) => readInput(root, input.file, input));
+  return { projectDir: root, claimId, draft: { ...draftInput, doc }, sources };
+}

package/src/scaffold/append.mjs

@@ -0,0 +1,41 @@
+import { validate } from '../../spec/lib/validate.mjs';
+
+const injection = (fault) => (fault.method ?? 'fault-injection') === 'fault-injection';
+// A different explicit defender selection is a different measurement, even
+// when the injected bytes match. Absence and explicit [] must stay distinct.
+const anchorKey = (fault) => JSON.stringify([
+  fault.file, fault.faultClass, fault.find, fault.replace,
+  fault.expectHits ?? 1, fault.occurrence ?? 1,
+  Object.hasOwn(fault, 'defendedBy') ? [...fault.defendedBy].sort() : null,
+]);
+
+function conforming(label, doc) {
+  const result = validate('claims', doc);
+  if (!result.ok) throw new Error(`non-conforming ${label}: ${result.errors.map((e) => `${e.path}: ${e.message}`).join('; ')}`);
+}
+
+/** Pure draft merge only. The future CLI owns all file admission/publication. */
+export function appendDraft({ draft, proposals, claimId }) {
+  conforming('draft', draft);
+  conforming('proposals', proposals);
+  if (typeof claimId !== 'string' || !claimId) throw new Error('append requires one existing claim ID');
+  const doc = structuredClone(draft);
+  const target = doc.claims.find((claim) => claim.id === claimId);
+  if (!target) throw new Error('append selection does not name an existing draft claim');
+  const candidates = proposals.claims.flatMap((claim) => claim.faults);
+  if (candidates.some((fault) => !injection(fault))) throw new Error('append proposals require fault-injection methods');
+  const seen = new Set(target.faults.filter(injection).map(anchorKey));
+  const used = new Set(target.faults.map((fault) => fault.id));
+  let next = 1;
+  for (const candidate of candidates) {
+    const key = anchorKey(candidate);
+    if (seen.has(key)) continue;
+    while (used.has(`S${next}`)) next++;
+    const id = `S${next++}`;
+    used.add(id);
+    target.faults.push({ ...structuredClone(candidate), id });
+    seen.add(key);
+  }
+  conforming('appended draft', doc);
+  return doc;
+}