testguard-cli 0.18.3 → 0.20.0

package/src/init/init.mjs

@@ -1,22 +1,36 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync, chmodSync } from 'node:fs';
 import { join, dirname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { PreconditionError } from '../probe/worktree.mjs';
 
 const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), 'templates');
 const AGENTS_BEGIN = '<!-- testguard:begin -->';
 const AGENTS_END = '<!-- testguard:end -->';
-export const GITIGNORE_LINES = ['.testguard/evidence.json', '.testguard/evidence-provisional.json', '.testguard/evidence-partial.json', '.testguard/brief.json', '.testguard/gate.json', '.testguard/scaffold-*.json', '.testguard/replay.json', '.testguard/calibration.json', '.testguard/ci-self-evidence.json', '.testguard/ci/'];
+/** Where fetch-ci-evidence.sh downloads CI's artifact, relative to the project. */
+export const CI_DOWNLOAD_DIR = '.testguard/ci';
+const GITIGNORE_HEADER = '# TestGuard: regenerated per run (baseline.json IS committed)';
+// Every regenerated file a command writes under .testguard/. test/init.test.mjs
+// derives that set from the code's own path joins and fails when one is missing
+// here, so a new artifact cannot ship without its ignore line.
+export const GITIGNORE_LINES = ['.testguard/evidence.json', '.testguard/evidence-provisional.json', '.testguard/evidence-partial.json', '.testguard/brief.json', '.testguard/gate.json', '.testguard/scaffold-*.json', '.testguard/replay.json', '.testguard/calibration.json', '.testguard/ci-self-evidence.json', '.testguard/ci/', '.testguard/sweep.json', '.testguard/sweep-evidence.json'];
 
 /**
- * The `.testguard/` files that ARE committed: the frozen contract, its
- * snapshot, and the CI-fetch helper the user runs by hand. Everything else in
- * the directory is regenerated. Named here so the two places that reason about
- * the directory — the lines init writes and the advice baseline prints — cannot
- * disagree about which of them is which.
+ * The `.testguard/` files that are NOT ignored: the frozen contract
+ * (baseline.json), the CI-fetch helper `init --ci-evidence` writes for the user
+ * to run by hand, and status.json — a name reserved for a status snapshot a
+ * project may choose to keep (`status --json > .testguard/status.json`). No
+ * command writes status.json; it is listed so that both ignore forms leave it
+ * trackable alike: init's per-file lines never name it, and the `.testguard/*`
+ * form baseline advises negates it. Everything else in the directory is
+ * regenerated. Named here so the two places that reason about the directory —
+ * the lines init writes and the advice baseline prints — cannot disagree.
  */
 export const COMMITTED_OUTPUTS = ['.testguard/baseline.json', '.testguard/status.json', '.testguard/fetch-ci-evidence.sh'];
 
+/** A bad option to init: the CLI reports it as a usage error (exit 3). */
+export class InitUsageError extends Error {}
+
 /**
  * The session-start hook command. It runs from the git root (where the agent
  * session lives) and must never fetch from the network: a local install of
@@ -78,6 +92,63 @@ export function isGitIgnored(root, file) {
   return spawnSync('git', ['check-ignore', '-q', '--', file], { cwd: root }).status === 0;
 }
 
+/**
+ * The directory a TestGuard session-start hook briefs, or null when the
+ * command is not a TestGuard hook.
+ *
+ * Recognised by what every release's hook has run — `testguard brief --text`,
+ * through `npx -y testguard-cli`, `npx --no-install testguard`, a local
+ * `node_modules/.bin/testguard` or a `testguard` on PATH — not by the exact
+ * text of the current hookCommand(). Matching only the current text (and two
+ * named npx forms) meant any change to hookCommand() made the next `init`
+ * append a second hook beside the first, and every session briefed twice.
+ * The project is the token after `--text` when it is an argument rather than
+ * a redirect or a shell operator.
+ */
+export function briefHookDir(command) {
+  if (typeof command !== 'string') return null;
+  const m = /(?:^|[\s/])testguard(?:-cli)?(?:@[^\s"|;&]+)?\s+brief\s+--text\b(?:\s+([^\s"|;&]+))?/.exec(command);
+  if (!m) return null;
+  const token = m[1];
+  return !token || token.startsWith('2>') || token.startsWith('>') ? '.' : token;
+}
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * Read `.claude/settings.json` for the hook, or refuse. A file init cannot
+ * safely merge into is a precondition failure naming the file — never a crash,
+ * and never after another file has been written.
+ */
+function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return {};
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  } catch (e) {
+    throw new PreconditionError(`${settingsPath} is not valid JSON (${e.message}); fix it before init can add the hook. Nothing was written.`);
+  }
+  const refuse = (what) => { throw new PreconditionError(`${settingsPath}: ${what}; fix it before init can add the hook. Nothing was written.`); };
+  if (!isPlainObject(settings)) refuse('the settings must be a JSON object');
+  if (settings.hooks !== undefined && !isPlainObject(settings.hooks)) refuse('"hooks" must be an object');
+  if (settings.hooks?.SessionStart !== undefined && !Array.isArray(settings.hooks.SessionStart)) refuse('"hooks.SessionStart" must be an array');
+  return settings;
+}
+
+/**
+ * The `.gitignore` text with init's lines in it, or null when nothing is
+ * missing. Lines a previous init wrote stay where they are; lines a newer
+ * release added go directly after the last of them, so re-running init after
+ * an upgrade extends the one block instead of appending a second header.
+ */
+function gitignoreWithLines(gi, missing) {
+  const lines = gi.split('\n');
+  let last = -1;
+  lines.forEach((l, i) => { if (GITIGNORE_LINES.includes(l.trim())) last = i; });
+  if (last === -1) return (gi ? gi.replace(/\s*$/, '\n') : '') + GITIGNORE_HEADER + '\n' + missing.join('\n') + '\n';
+  return [...lines.slice(0, last + 1), ...missing, ...lines.slice(last + 1)].join('\n');
+}
+
 /**
  * Install the operating layer.
  *
@@ -93,35 +164,59 @@ export function isGitIgnored(root, file) {
  * hook line and an AGENTS.md bullet, never duplicates. Every written file is
  * checked against .gitignore; an ignored file is reported as ignored, never
  * as something to commit.
+ *
+ * All or nothing: every input is read and every refusal raised before the
+ * first write, so a bad option or an unmergeable settings.json leaves the
+ * project exactly as it was.
  */
-const CI_EVIDENCE_HELPERS = {
-  github: `#!/bin/sh
-# Fetch the evidence CI wrote on a branch, then brief from it. Run it when you
-# want it: the session-start hook never touches the network, and this script
-# exits 0 with a message whenever anything is missing.
-BRANCH="\${1:-main}"
-OUT=.testguard/ci
-command -v gh >/dev/null 2>&1 || { echo "gh is not installed; see README > Read CI's evidence locally" >&2; exit 0; }
-command -v testguard >/dev/null 2>&1 || { echo "testguard is not on PATH; install it or run npx testguard-cli brief --evidence <file>" >&2; exit 0; }
-mkdir -p "$OUT" || exit 0
-gh run download --name "testguard-evidence-$BRANCH" --dir "$OUT" >/dev/null 2>&1 || { echo "no testguard-evidence-$BRANCH artifact to download" >&2; exit 0; }
-exec testguard brief . --text --evidence "$OUT/ci-self-evidence.json"
-`,
-  gitlab: `#!/bin/sh
+const CI_EVIDENCE_HELPER = (platform) => {
+  const github = platform === 'github';
+  const tool = github ? 'gh' : 'glab';
+  const download = github
+    ? 'gh run download --name "testguard-evidence-$BRANCH" --dir "$OUT"'
+    : 'glab ci artifact "$BRANCH" testguard:probe --path "$OUT/"';
+  const missing = github ? 'no testguard-evidence-$BRANCH artifact to download' : 'no testguard:probe artifact to download for $BRANCH';
+  // Where the evidence sits in the downloaded artifact. The action's
+  // `evidence` output names the one file its run wrote, uploaded at the
+  // artifact's root; ci-self-evidence.json is what an earlier workflow example
+  // uploaded. The GitLab template keeps the project's path from the repository
+  // root, so a project in a subdirectory finds its own evidence under that
+  // prefix — and never another project's from the same artifact.
+  const candidates = github
+    ? ['evidence.json', 'evidence-provisional.json', 'ci-self-evidence.json']
+    : ['${PREFIX}.testguard/evidence.json', '${PREFIX}.testguard/evidence-provisional.json'];
+  return `#!/bin/sh
 # Fetch the evidence CI wrote on a branch, then brief from it. Run it when you
 # want it: the session-start hook never touches the network, and this script
 # exits 0 with a message whenever anything is missing.
 BRANCH="\${1:-main}"
-OUT=.testguard/ci
-command -v glab >/dev/null 2>&1 || { echo "glab is not installed; see README > Read CI's evidence locally" >&2; exit 0; }
-command -v testguard >/dev/null 2>&1 || { echo "testguard is not on PATH; install it or run npx testguard-cli brief --evidence <file>" >&2; exit 0; }
-mkdir -p "$OUT" || exit 0
-glab ci artifact "$BRANCH" testguard:probe --path "$OUT/" >/dev/null 2>&1 || { echo "no testguard:probe artifact to download for $BRANCH" >&2; exit 0; }
-exec testguard brief . --text --evidence "$OUT/.testguard/evidence.json"
-`,
+# Run from the project this helper belongs to, whatever the caller's cwd.
+case "$0" in */*) cd "\${0%/*}/.." || exit 0 ;; *) cd .. || exit 0 ;; esac
+OUT=${CI_DOWNLOAD_DIR}
+command -v ${tool} >/dev/null 2>&1 || { echo "${tool} is not installed; see https://github.com/raccioly/testguard/blob/main/docs/guides/ci/${github ? 'github-actions' : 'gitlab'}.md#read-cis-evidence-locally" >&2; exit 0; }
+# The CLI the session-start hook would run: this project's install, then the
+# repository root's, then a testguard on PATH. Never a package-runner fetch.
+TG=
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+${github ? '' : '# This project\'s path from the repository root, with a trailing slash; empty at the root.\nPREFIX=$(git rev-parse --show-prefix 2>/dev/null)\n'}for c in ./node_modules/.bin/testguard "\${ROOT:+$ROOT/node_modules/.bin/testguard}"; do
+  if [ -n "$c" ] && [ -x "$c" ]; then TG=$c; break; fi
+done
+[ -n "$TG" ] || TG=$(command -v testguard 2>/dev/null)
+[ -n "$TG" ] || { echo "no testguard CLI found (./node_modules/.bin, the repository root's node_modules/.bin, or PATH); install it, or run npx testguard-cli brief . --text --evidence <file>" >&2; exit 0; }
+# A fresh download directory, so an earlier download is never briefed as this one.
+rm -rf "$OUT" && mkdir -p "$OUT" || exit 0
+${download} >/dev/null 2>&1 || { echo "${missing}" >&2; exit 0; }
+for f in ${candidates.map((c) => `"$OUT/${c}"`).join(' ')}; do
+  [ -f "$f" ] && exec "$TG" brief . --text --evidence "$f"
+done
+echo "the downloaded artifact holds no evidence for this project (looked for ${candidates.join(', ')})" >&2
+exit 0
+`;
 };
+const CI_PLATFORMS = ['github', 'gitlab'];
 
 export function initProject({ projectDir, force = false, here = false, ciEvidence, mcp = false }) {
+  if (ciEvidence !== undefined && !CI_PLATFORMS.includes(ciEvidence)) throw new InitUsageError(`--ci-evidence must be github or gitlab, not ${JSON.stringify(ciEvidence)}`);
   projectDir = realpathSync(resolve(projectDir));
   const root = here ? null : gitRoot(projectDir);
   const agentRoot = root ?? projectDir;
@@ -132,65 +227,56 @@ export function initProject({ projectDir, force = false, here = false, ciEvidenc
   let mcpConfig;
   const skipped = [];
   const warnings = [];
+  const writes = [];
   const rel = (p) => relative(agentRoot, p).split(sep).join('/');
   const note = (p) => { if (isGitIgnored(ignoreRoot, p)) warnings.push(`${rel(p)} is ignored by .gitignore — it was written, but git will not track it and agents in a fresh clone will never see it; unignore it or move it`); };
+  const write = (path, content, { mode, checkIgnored = true } = {}) => writes.push({ path, content, mode, checkIgnored });
+
+  // ---- preflight: read everything, refuse here, write nothing yet ----
+  const settingsPath = join(agentRoot, '.claude', 'settings.json');
+  const settings = readSettings(settingsPath);
 
   const skillDir = join(agentRoot, '.claude', 'skills', 'testguard');
   const skillPath = join(skillDir, 'SKILL.md');
   if (!existsSync(skillPath) || force) {
     const replaced = force && existsSync(skillPath);
-    mkdirSync(skillDir, { recursive: true });
-    writeFileSync(skillPath, readFileSync(join(TEMPLATES, 'SKILL.md'), 'utf8'));
+    write(skillPath, readFileSync(join(TEMPLATES, 'SKILL.md'), 'utf8'));
     done.push(`${rel(skillPath)}${replaced ? ' (replaced)' : ''}`);
-    note(skillPath);
   } else {
     skipped.push(`${rel(skillPath)} exists (use --force to replace)`);
   }
 
-  const settingsPath = join(agentRoot, '.claude', 'settings.json');
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-    } catch (e) {
-      throw new Error(`${rel(settingsPath)} is not valid JSON (${e.message}); fix it before init can add the hook`);
-    }
-  }
   settings.hooks ??= {};
   settings.hooks.SessionStart ??= [];
+  const groups = settings.hooks.SessionStart;
   const cmd = hookCommand(dir);
-  const hasCmd = settings.hooks.SessionStart.some((e) => JSON.stringify(e).includes(cmd));
-  // Any earlier hook that reached for npx — `-y` fetched outright, and
-  // `--no-install` still resolves the packument from the registry — is replaced.
-  // Which project a hook is for is the token right after `brief --text`, if
-  // that token is an argument rather than a redirect or a shell operator.
-  // Testing for any non-space there mistook `brief --text 2>/dev/null` for a
-  // hook belonging to a directory, so a legacy root hook was never replaced.
-  const hookDir = (text) => {
-    const m = /brief --text(?:\s+([^\s"|;&]+))?/.exec(text);
-    const token = m?.[1];
-    return !token || token.startsWith('2>') || token.startsWith('>') ? '.' : token;
-  };
-  const legacy = settings.hooks.SessionStart.findIndex((e) => {
-    const text = JSON.stringify(e);
-    return /npx\s+(-y|--no-install)[^"]*brief --text/.test(text) && hookDir(text) === dir;
-  });
+  // Every TestGuard hook already briefing this project, whichever release wrote it.
+  const ours = [];
+  groups.forEach((g, gi) => { if (Array.isArray(g?.hooks)) g.hooks.forEach((h, hi) => { if (briefHookDir(h?.command) === dir) ours.push({ gi, hi, command: h.command }); }); });
+  const hasCmd = ours.length === 1 && ours[0].command === cmd;
   if (hasCmd) {
     skipped.push(`SessionStart hook for ${dir === '.' ? 'this project' : dir} already present in ${rel(settingsPath)}`);
   } else {
-    if (legacy !== -1) {
-      settings.hooks.SessionStart.splice(legacy, 1);
-      done.push(`${rel(settingsPath)}: replaced the network-reaching npx hook with a local-then-PATH one`);
+    if (ours.length) {
+      // Replace the first in place, keeping its position and any other keys
+      // (a timeout, say); drop the rest, which are duplicates an older init left.
+      const [first, ...extra] = ours;
+      groups[first.gi].hooks[first.hi] = { ...groups[first.gi].hooks[first.hi], command: cmd };
+      for (const { gi, hi } of extra.reverse()) groups[gi].hooks.splice(hi, 1);
+      settings.hooks.SessionStart = groups.filter((g, gi) => !extra.some((x) => x.gi === gi) || g.hooks.length > 0);
+      const npx = ours.some((o) => /\bnpx\b/.test(o.command));
+      done.push(npx
+        ? `${rel(settingsPath)}: replaced the network-reaching npx hook with a local-then-PATH one`
+        : `${rel(settingsPath)}: replaced an earlier TestGuard hook for ${dir === '.' ? 'this project' : dir} in place`);
+    } else {
+      groups.push({ hooks: [{ type: 'command', command: cmd }] });
     }
-    settings.hooks.SessionStart.push({ hooks: [{ type: 'command', command: cmd }] });
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    write(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     // Describes hookCommand() above, which emits no npx of any kind: a local
     // install, then a testguard on PATH, then nothing. The claim
     // TG-README-HOOK-MATCHES-THE-CODE holds this sentence to that, here and in
     // every other surface that describes the hook.
     done.push(`${rel(settingsPath)}: SessionStart hook → brief --text${dir === '.' ? '' : ` ${dir}`} (local install first, then a testguard on PATH, never a fetch)`);
-    note(settingsPath);
   }
 
   const agentsPath = join(agentRoot, 'AGENTS.md');
@@ -204,41 +290,50 @@ export function initProject({ projectDir, force = false, here = false, ciEvidenc
     if (entries.includes(dir)) {
       skipped.push(`AGENTS.md already has the TestGuard section for ${dir === '.' ? 'this project' : dir}`);
     } else {
-      writeFileSync(agentsPath, agents.slice(0, begin) + agentsBlock([...entries, dir]) + agents.slice(end + AGENTS_END.length));
+      write(agentsPath, agents.slice(0, begin) + agentsBlock([...entries, dir]) + agents.slice(end + AGENTS_END.length));
       done.push(legacyBlock ? `AGENTS.md: TestGuard section rewritten to list ${dir}` : `AGENTS.md: TestGuard section now lists ${dir}`);
-      note(agentsPath);
     }
   } else {
-    writeFileSync(agentsPath, (agents ? agents.replace(/\s*$/, '\n\n') : '# Agent instructions\n\n') + agentsBlock([dir]) + '\n');
+    write(agentsPath, (agents ? agents.replace(/\s*$/, '\n\n') : '# Agent instructions\n\n') + agentsBlock([dir]) + '\n');
     done.push(agents ? 'AGENTS.md: TestGuard section appended' : 'AGENTS.md created with the TestGuard section');
-    note(agentsPath);
   }
 
   const giPath = join(projectDir, '.gitignore');
   const gi = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
   const entries = gi.split('\n').map((x) => x.trim());
   const dirIgnored = entries.some((x) => /^\/?\.testguard\/?$/.test(x));
-  const missing = dirIgnored ? [] : GITIGNORE_LINES.filter((l) => !entries.includes(l));
+  // `.testguard/*` with negations is the form `baseline` advises: it already
+  // covers every output, present and future, so per-file lines would be noise.
+  const starForm = entries.some((x) => /^\/?\.testguard\/\*$/.test(x));
+  const missing = dirIgnored || starForm ? [] : GITIGNORE_LINES.filter((l) => !entries.includes(l));
   if (dirIgnored) {
     skipped.push(`${rel(giPath)} ignores .testguard/ entirely — note that baseline.json should be committed; ignore only the regenerated files if you adopt a baseline`);
+  } else if (starForm) {
+    skipped.push(`${rel(giPath)} ignores .testguard/* — every regenerated output is covered; keep ${COMMITTED_OUTPUTS.map((p) => `!${p}`).join(', ')} beside it`);
   } else if (missing.length) {
-    writeFileSync(giPath, (gi ? gi.replace(/\s*$/, '\n') : '') + '# TestGuard: regenerated per run (baseline.json IS committed)\n' + missing.join('\n') + '\n');
+    write(giPath, gitignoreWithLines(gi, missing), { checkIgnored: false });
     done.push(`${rel(giPath)}: ${missing.length} line${missing.length === 1 ? '' : 's'} added`);
   } else {
     skipped.push(`${rel(giPath)} already ignores the regenerated files`);
   }
-  if (ciEvidence) {
+  if (ciEvidence !== undefined) {
     const helperPath = join(projectDir, '.testguard', 'fetch-ci-evidence.sh');
-    const body = CI_EVIDENCE_HELPERS[ciEvidence];
-    if (!body) throw new Error(`--ci-evidence must be github or gitlab, not ${ciEvidence}`);
     if (!existsSync(helperPath) || force) {
-      mkdirSync(dirname(helperPath), { recursive: true });
-      writeFileSync(helperPath, body, { mode: 0o755 });
+      write(helperPath, CI_EVIDENCE_HELPER(ciEvidence), { mode: 0o755, checkIgnored: false });
       done.push(`.testguard/fetch-ci-evidence.sh (${ciEvidence}) — run it on demand; the session-start hook stays offline`);
     } else {
       skipped.push('.testguard/fetch-ci-evidence.sh exists (use --force to replace)');
     }
   }
+
+  // ---- every check passed: write ----
+  for (const w of writes) {
+    mkdirSync(dirname(w.path), { recursive: true });
+    writeFileSync(w.path, w.content, w.mode === undefined ? undefined : { mode: w.mode });
+    if (w.mode !== undefined) chmodSync(w.path, w.mode); // an existing file keeps its old mode otherwise
+    if (w.checkIgnored) note(w.path);
+  }
+
   if (mcp) {
     // Printed, never written: a harness's own config is the person's file
     // (and often global), so init shows the snippet and lets them place it.

package/src/probe/attribution.mjs

@@ -131,6 +131,11 @@ export function isReusable(prior, current) {
   // A record that exists because the probe threw is a statement about the run,
   // not about the code. Reusing it would make one disturbed run permanent.
   if (prior.detail?.reason === 'probe-error') return false;
+  // Defenders that never loaded say something about the environment — a
+  // broken --runner-cmd, a missing dependency, an interpreter without the test
+  // requirements — and none of that is hashed below. Fixing it changes no
+  // input, so the failure would keep being reported as the current answer.
+  if (prior.detail?.reason === 'defenders-failed-to-load') return false;
   const origin = prior.defenders.selectionSource ?? (prior.defenders.requested.length ? 'claim' : 'discovery');
   if (current.selectionSource && origin !== current.selectionSource) return false;
   const same = (x, y) => JSON.stringify(x) === JSON.stringify(y);

package/src/probe/contention.mjs

@@ -90,8 +90,19 @@ export function detectContention({ self = process.pid, alive = defaultAlive, ...
   return { detected: runners.length > 0, runners };
 }
 
-/** One line for the operator: what is running, and what it costs. */
-export const contentionWarning = (c) =>
+/**
+ * What would actually change this run. `--serial` is the same as `--workers 1`,
+ * which is the default, so advising it to a run that is already serial offers
+ * a flag that changes nothing; a custom command's concurrency is its own.
+ */
+function contentionAdvice({ serial = true, workers = 1, custom = false }) {
+  if (custom) return 'Wait for it to finish; a --runner-cmd manages its own concurrency, so make that command run one test file at a time if it does not already.';
+  if (serial || workers <= 1) return 'Wait for it to finish: this probe already runs one test file at a time (--workers 1), so --serial would change nothing.';
+  return `Wait for it to finish, or lower --workers ${workers} (or pass --serial) to run one test file at a time.`;
+}
+
+/** One line for the operator: what is running, what it costs, and what would help. */
+export const contentionWarning = (c, policy = {}) =>
   `${c.runners.length} test runner${c.runners.length === 1 ? ' is' : 's are'} already running (${c.runners.map((r) => `pid ${r.pid}`).join(', ')}); ` +
   'defenders run N times each here, and a suite that times out under parallel load yields TIMEOUT or FLAKY-DEFENDER — verdicts about the load, not the claim. ' +
-  'Wait for it to finish, or pass --serial to run one test file at a time.';
+  contentionAdvice(policy);

package/src/probe/cost.mjs

@@ -109,7 +109,13 @@ export function costReport(records, { run } = {}) {
   };
 }
 
-const secs = (ms) => (ms >= 10_000 ? `${Math.round(ms / 1000)}s` : ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`);
+// Measured durations are performance.now() differences, so they are fractional:
+// round before choosing the unit, or 659.1493330000001ms prints verbatim and
+// 999.6 prints as "1000ms".
+const secs = (ms) => {
+  const whole = Math.round(ms);
+  return whole >= 10_000 ? `${Math.round(ms / 1000)}s` : whole >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${whole}ms`;
+};
 /** Exported so a caller can format a duration the same way the report does. */
 export const formatMs = secs;
 

package/src/probe/policy-freshness.mjs

@@ -36,7 +36,11 @@ export function originPolicyInputsFresh({ projectDir, claims, evidence, universe
     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;
+    // Where the runner came from is part of its identity: a global vitest of
+    // the same version is a different binary from the project's, the same
+    // rule verdict reuse applies (sameRunner in probe.mjs).
+    const matchesRunner = (recorded, current) => recorded?.name === current?.name && recorded?.version === current?.version
+      && (recorded?.source ?? null) === (current?.source ?? null);
     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());

package/src/probe/probe.mjs

@@ -21,7 +21,7 @@ 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';
+import { collectOwnedManifests, hashNativeTestUniverse, hashCustomCommandUniverse } from './universe.mjs';
 
 
 /** Is `child` the same file as `root`, or under it? Both must already be real paths. */
@@ -62,6 +62,27 @@ export function sameWorkerPolicy(previousRun, { workers = 1, serial = workers ==
   return previousRun?.workers === (serial ? 1 : workers) && Boolean(previousRun?.serial) === serial;
 }
 
+/**
+ * What the evidence says ran: the engine's name, the version it reported, and
+ * where it was resolved from (`project`, `path`, `builtin`). A custom command
+ * resolves nothing, so it claims no source.
+ */
+export function runnerRecord(name, version, source) {
+  return { name, ...(version ? { version } : {}), ...(source ? { source } : {}) };
+}
+
+/**
+ * Reuse cannot stand in for a measurement by a different runner. pytest and
+ * unittest are one adapter and two engines; a global vitest of the same
+ * version is a different binary from the project's. Evidence that recorded no
+ * runner cannot vouch for this one.
+ */
+export function sameRunner(previousRun, current) {
+  const recorded = previousRun?.runner;
+  if (!recorded) return false;
+  return recorded.name === current.name && recorded.version === current.version && recorded.source === current.source;
+}
+
 /**
  * Probe every fault of every claim. Returns a spec-conformant evidence
  * document; writing it is the caller's job.
@@ -205,13 +226,14 @@ export async function probe({
   // Contention: name it before the first run, and record it, so a later
   // reader of a TIMEOUT or FLAKY-DEFENDER knows the machine was loaded.
   const contention = detectContention();
-  if (contention.detected) onWarn(contentionWarning(contention));
+  if (contention.detected) onWarn(contentionWarning(contention, { serial, workers, custom: Boolean(runnerCommand) }));
 
   const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref: snapshot ?? ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
   const isoReal = realpathSync(iso.projectDir);
   const records = [];
   let runnerVersion;
   let runnerSource;
+  let recordedRunner;
   let primaryManifest;
   let runner = RUNNERS[runnerName === 'auto' ? 'vitest' : runnerName];
   // A runner with more than one engine (Python: pytest or unittest) is recorded
@@ -236,7 +258,8 @@ export async function probe({
       primaryManifest = sel.manifest;
       if (sel.engine) engines.set(sel.runner, sel.engine);
     }
-    runnersUsed.set(labelOf(runner), runnerVersion ?? readRunnerVersion(projectDir, runner.name));
+    recordedRunner = runnerRecord(labelOf(runner), runnerVersion ?? readRunnerVersion(projectDir, runner.name), runnerSource);
+    runnersUsed.set(recordedRunner.name, recordedRunner.version);
     // Files an owning runner (Playwright) claims run under it, whatever the
     // project runner is; it must resolve before the first such defender runs.
     const owned = OWNED_RUNNERS.filter((r) => r !== runner
@@ -283,7 +306,7 @@ export async function probe({
       ? [...new Set([...runner.tests(iso.projectDir).filter((t) => !owned.some((r) => r.owns(iso.projectDir, t))), ...owned.flatMap((r) => r.tests(iso.projectDir))])]
       : [...ownerByFile.keys()]).sort());
     const testUniverseHash = commandTemplate
-      ? sha256(JSON.stringify({ schemaVersion: 1, source: 'custom-command-static', files: allTests }))
+      ? hashCustomCommandUniverse(allTests, commandTemplate)
       : hashNativeTestUniverse(manifests);
     const baselineCache = new Map();
     const discoveryHashCache = new Map();
@@ -295,6 +318,7 @@ export async function probe({
     const fatalEditFor = (file) => runnerFor(iso.projectDir, file, runner).fatalEdit?.();
     const prior = previous && previous.run.confirmRuns === confirmRuns
       && sameWorkerPolicy(previous.run, { workers, serial, runnerCommand })
+      && sameRunner(previous.run, recordedRunner)
       ? new Map(previous.records.map((r) => [`${r.claim.id}/${r.subject.id}`, r]))
       : new Map();
     const partitionConfigured = (files) => {
@@ -403,7 +427,9 @@ 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) } : {}), ...(runnerSource === 'builtin' ? { source: runnerSource } : {}) },
+      // Where the runner came from is part of what was measured: recorded for
+      // every resolved runner, as the schema documents, not only the builtin.
+      runner: recordedRunner,
       ...(runnersUsed.size > 1 ? { runners: [...runnersUsed].map(([n, v]) => ({ name: n, ...(v ? { version: v } : {}) })) } : {}),
       confirmRuns,
       measurements,

package/src/probe/runners/python.mjs

@@ -2,7 +2,7 @@ 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 { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runProcess, listTestFiles, firstInformativeLine, terminateProcessTree } from './shared.mjs';
 
@@ -69,6 +69,20 @@ export const testGlobs = ['**/test_*.py', '**/test*.py', '**/*_test.py'];
 const PY_FILE = /\.py$/;
 const TIMEOUT = /\bTimeout >|\btimed out\b|\bTimeoutError\b/i;
 
+/**
+ * The interpreter the operator named, with `--python` or `TESTGUARD_PYTHON` —
+ * both the same way, as a shell would. A bare command name (`python3`, no path
+ * separator) is looked up on PATH: resolving it against the working directory
+ * produced `<cwd>/python3`, which is never an interpreter. Anything with a
+ * separator is a path, resolved once against the working directory. An empty
+ * value names nothing.
+ */
+export function explicitInterpreter(value) {
+  if (typeof value !== 'string' || value === '') return undefined;
+  const bare = !value.includes('/') && !(process.platform === 'win32' && value.includes('\\'));
+  return bare ? { path: value, source: 'path' } : { path: resolve(value), source: 'project' };
+}
+
 /**
  * Interpreters to try, best first: the active virtualenv, the project's own,
  * then PATH.
@@ -82,8 +96,8 @@ function candidates(projectDir, python) {
   const out = [];
   const win = process.platform === 'win32';
   const binOf = (root) => (win ? join(root, 'Scripts', 'python.exe') : join(root, 'bin', 'python'));
-  const explicit = python ?? process.env.TESTGUARD_PYTHON;
-  if (explicit) return [{ path: explicit, source: 'project', explicit: true }];
+  const explicit = explicitInterpreter(python ?? process.env.TESTGUARD_PYTHON);
+  if (explicit) return [{ ...explicit, explicit: true }];
   if (process.env.VIRTUAL_ENV) out.push({ path: binOf(process.env.VIRTUAL_ENV), source: 'project' });
   for (const dir of ['.venv', 'venv', '.env']) out.push({ path: binOf(join(projectDir, dir)), source: 'project' });
   out.push({ path: win ? 'python.exe' : 'python3', source: 'path' });
@@ -159,9 +173,9 @@ export function resolveInterpreter({ projectDir, python, budgetMs = 30_000, budg
       if (answer) return { ...candidate, ...answer };
       tried.push(candidate.path);
     }
-    const explicit = python ?? process.env.TESTGUARD_PYTHON;
+    const explicit = explicitInterpreter(python ?? process.env.TESTGUARD_PYTHON);
     return { error: explicit
-      ? `${explicit} is not a usable Python interpreter`
+      ? `${explicit.path} is not a usable Python interpreter${explicit.source === 'path' ? ' (looked up on PATH)' : ''}`
       : `no usable Python interpreter (tried ${tried.join(', ') || 'nothing'}); install Python 3.8+, or point --python / TESTGUARD_PYTHON at one` };
   })();
   interpreters.set(key, task);

package/src/probe/universe.mjs

@@ -18,6 +18,17 @@ export function hashNativeTestUniverse(manifests) {
   return sha256(JSON.stringify(bound));
 }
 
+/**
+ * A custom `--runner-cmd` has no native listing, so its universe is the static
+ * file set — and the command itself. The files alone cannot tell a broken
+ * command from the fixed one, and a verdict measured by one is not an answer
+ * from the other. The parsed argv is hashed, so reformatting whitespace is not
+ * a change and the command text never appears in the evidence.
+ */
+export function hashCustomCommandUniverse(files, commandTemplate) {
+  return sha256(JSON.stringify({ schemaVersion: 2, source: 'custom-command-static', command: commandTemplate, files }));
+}
+
 /** 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
@@ -41,7 +52,8 @@ export async function readNativeTestUniverse(options) {
   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 }))];
+  const identity = (name, version, source) => ({ name, version, ...(source ? { source } : {}) });
+  const primaryRunner = identity(selected.engine ?? selected.runner.name, selected.version, selected.source);
+  const runners = [primaryRunner, ...[...collection.ownedChecked].filter(([, check]) => check.ok).map(([runner, check]) => identity(check.engine ?? runner.name, check.version, check.source))];
   return { ...collection, primary: selected.runner, primaryRunner, runners, testUniverseHash: hashNativeTestUniverse(collection.manifests) };
 }