testguard-cli 0.18.2 → 0.19.0

package/src/commands/probe.mjs

@@ -14,6 +14,7 @@ import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
 import { originPolicyRequest, evaluateOriginPolicy } from '../probe/origin-policy.mjs';
 import { readNativeTestUniverse } from '../probe/universe.mjs';
 import { originPolicyInputsFresh } from '../probe/policy-freshness.mjs';
+import { runnerOptions } from './runner-options.mjs';
 export const provisionalEvidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence-provisional.json');
 
 export const evidencePath = (projectDir) => join(projectDir, '.testguard', 'evidence.json');
@@ -57,6 +58,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     io.err('--command-budget must be at least 1000 milliseconds');
     return 3;
   }
+  const runner = runnerOptions(values);
+  if (runner.error) {
+    io.err(runner.error);
+    return 3;
+  }
   const commandBudget = createCommandBudget(commandBudgetMs);
   if (values.progress && !isProgressMode(values.progress)) {
     io.err(`--progress must be one of auto, tty, plain, ndjson, none (got ${values.progress})`);
@@ -113,10 +119,10 @@ export async function probeCommand({ projectDir, values, version }, io) {
     refExplicit: values.ref !== undefined,
     ignoreDirty: values['ignore-dirty'],
     onWarn: (m) => io.err(`warning: ${m}`),
-    runnerCommand: values['runner-cmd'],
+    runnerCommand: runner.runnerCommand,
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
-    python: values.python ? resolve(values.python) : undefined,
+    python: runner.python,
     only,
     escalate: !values['no-escalate'],
     toolVersion: version,
@@ -139,11 +145,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     let universe;
     // Custom commands carry a static universe, which cannot establish this
     // native policy boundary. Discovery failures are unavailability, not kills.
-    if (!values['runner-cmd']) {
+    if (!runner.runnerCommand) {
       try {
         universe = await readNativeTestUniverse({
           projectDir, sourceDir: projectDir, runnerName: values.runner,
-          python: values.python ? resolve(values.python) : undefined,
+          python: runner.python,
           budgetMs: commandBudget?.runBudget(budgetMs) ?? budgetMs,
           budgetFor: () => commandBudget?.runBudget(budgetMs) ?? budgetMs,
           assertOpen: () => commandBudget?.assertOpen(),
@@ -187,7 +193,9 @@ export async function probeCommand({ projectDir, values, version }, io) {
     const killed = evidence.records.filter((r) => r.verdict === 'killed').length;
     if (killed) io.out(`  ${killed} killed (not listed; --verbose to see them)`);
   }
-  io.out(renderSummary(evidence.records, evidence.run) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
+  io.out(renderSummary(evidence.records, evidence.run));
+  // Its own line: the summary ends with the origins line, which is not a sentence to append to.
+  io.out(baseline ? `${g.new.length} new since baseline, ${g.baselined.length} baselined.` : 'No baseline.');
   if (policy) io.out(renderOriginPolicy(policy, { basis: 'current' }));
   if (values.cost) {
     io.out('');

package/src/commands/replay.mjs

@@ -2,6 +2,7 @@ import { dirname, join, resolve } from 'node:path';
 import { replay, calibrationFrom, renderReplay } from '../replay/replay.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
+import { runnerOptions } from './runner-options.mjs';
 
 export const replayPath = (projectDir) => join(projectDir, '.testguard', 'replay.json');
 export const calibrationPath = (projectDir) => join(projectDir, '.testguard', 'calibration.json');
@@ -29,6 +30,11 @@ export async function replayCommand({ projectDir, values, version }, io) {
     io.err('--command-budget must be at least 1000 milliseconds');
     return 3;
   }
+  const runner = runnerOptions(values);
+  if (runner.error) {
+    io.err(runner.error);
+    return 3;
+  }
   const commandBudget = createCommandBudget(commandBudgetMs);
 
   const doc = await replay({
@@ -39,9 +45,10 @@ export async function replayCommand({ projectDir, values, version }, io) {
     workers,
     serial: values.serial || workers === 1,
     commandBudget,
-    runnerCommand: values['runner-cmd'],
+    runnerCommand: runner.runnerCommand,
     runnerName: values.runner,
     nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+    python: runner.python,
     limit,
     toolVersion: version,
     onStage: !values.quiet && !values.json && process.stderr.isTTY ? ({ commit, i, n, stage }) => process.stderr.write(`\r\x1b[K  … ${commit.slice(0, 9)} (${i}/${n}) ${stage}`) : undefined,
@@ -55,7 +62,7 @@ export async function replayCommand({ projectDir, values, version }, io) {
   // Beside the replay document, whatever --out says: the two are one result,
   // and splitting them across directories loses the pairing — and leaves a
   // file behind in a repository the run is only meant to read.
-  const calPath = values.baseline ? resolve(values.baseline) : values.out ? join(dirname(outPath), 'calibration.json') : calibrationPath(projectDir);
+  const calPath = values['calibration-out'] ? resolve(values['calibration-out']) : values.out ? join(dirname(outPath), 'calibration.json') : calibrationPath(projectDir);
   // Replay and calibration are one result. Cross the deadline boundary only
   // after both complete documents exist in memory; serialization is then the
   // documented non-interruptible final step, so expiry can never leave half

package/src/commands/runner-options.mjs

@@ -0,0 +1,28 @@
+import { parseCommandTemplate } from '../probe/runners/shared.mjs';
+
+/**
+ * The runner options every command that runs tests shares — probe, admit,
+ * sweep, replay — checked once, before any work. A malformed `--runner-cmd` is
+ * a usage error (exit 3) with the reason, never a RangeError surfacing as
+ * "this is a bug in testguard"; and an empty value was asked for, so it is
+ * refused rather than read as "no command".
+ *
+ * `python` is passed through as typed. Whether it is a command on PATH or a
+ * path is decided in one place (`explicitInterpreter`), the same way for
+ * `--python` and `TESTGUARD_PYTHON`.
+ */
+export function runnerOptions(values) {
+  const runnerCommand = values['runner-cmd'];
+  if (runnerCommand !== undefined) {
+    try {
+      parseCommandTemplate(runnerCommand);
+    } catch (error) {
+      return { error: error.message };
+    }
+  }
+  const python = values.python;
+  if (python !== undefined && python.trim() === '') {
+    return { error: '--python must name an interpreter: a path such as .venv/bin/python, or a command on PATH such as python3' };
+  }
+  return { runnerCommand, python };
+}

package/src/commands/sweep.mjs

@@ -3,6 +3,7 @@ import { sweep, renderSweep, ConcernError } from '../sweep/sweep.mjs';
 import { resolveChangedRef } from '../gate/changed.mjs';
 import { writeSpecDoc } from '../evidence/writer.mjs';
 import { createCommandBudget, parseCommandBudget } from '../command-budget.mjs';
+import { runnerOptions } from './runner-options.mjs';
 
 export const sweepPath = (projectDir) => join(projectDir, '.testguard', 'sweep.json');
 /**
@@ -46,6 +47,11 @@ export async function sweepCommand({ projectDir, values, version }, io) {
     io.err('--command-budget must be at least 1000 milliseconds');
     return 3;
   }
+  const runner = runnerOptions(values);
+  if (runner.error) {
+    io.err(runner.error);
+    return 3;
+  }
   const commandBudget = createCommandBudget(commandBudgetMs);
   // A concern that aims at the write surface or at a glob needs no diff, the
   // same as --save-paths. Only a concern that defers to the gate does.
@@ -85,9 +91,10 @@ export async function sweepCommand({ projectDir, values, version }, io) {
       workers,
       serial: values.serial || workers === 1,
       commandBudget,
-      runnerCommand: values['runner-cmd'],
+      runnerCommand: runner.runnerCommand,
       runnerName: values.runner,
       nodeModules: values['node-modules'] ? resolve(values['node-modules']) : process.env.TESTGUARD_NODE_MODULES,
+      python: runner.python,
       toolVersion: version,
       claimsPath: values.claims ? resolve(values.claims) : undefined,
       ignorePath: values.ignore ? resolve(values.ignore) : undefined,

package/src/gate/changed.mjs

@@ -45,6 +45,17 @@ export const DEFAULT_EXCLUDES = Object.freeze([
 ]);
 const DEFAULT_EXCLUDE_RES = DEFAULT_EXCLUDES.map(globToRegExp);
 
+/**
+ * What `gate --explain` prints, built from the two lists the gate itself
+ * applies. A hand-written copy of the extension list omitted `.py` for as long
+ * as the gate had treated Python as source.
+ */
+export const explainExclusions = () => [
+  'Files that are source by extension but never carry claims (excluded by default; add more with --exclude <glob>):',
+  ...DEFAULT_EXCLUDES.map((g) => `  ${g}`),
+  `Non-source files (anything but ${[...SOURCE_EXT].join(' ')}) are excluded before these patterns apply.`,
+];
+
 /** Whether a source-shaped path is outside TestGuard's claimable module surface. */
 export const isDefaultExcluded = (file) => DEFAULT_EXCLUDE_RES.some((re) => re.test(file));
 

package/src/git.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { devNull, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
@@ -33,7 +33,17 @@ export function isAncestor(dir, ancestor, ref = 'HEAD') {
 /** True when any of `paths` (repo-relative; empty = whole tree) has uncommitted changes. */
 export const isDirty = (dir, paths = []) => git(['status', '--porcelain', '--', ...paths], dir).length > 0;
 
-export const addWorktree = (repo, dest, ref = 'HEAD') => git(['worktree', 'add', '--detach', dest, ref], repo);
+/**
+ * Leading options for a git command that checks files out into TestGuard's own
+ * scratch tree. That tree is the instrument, not a checkout the user made, so
+ * their post-checkout hook (husky, lefthook, Git LFS) must not run on it: a
+ * failing one fails the whole command after the files are already written, and
+ * Git LFS's fails whenever git-lfs is not on PATH. Filters, LFS smudge
+ * included, are config, not hooks, and still apply.
+ */
+export const NO_HOOKS = Object.freeze(['-c', `core.hooksPath=${devNull}`]);
+
+export const addWorktree = (repo, dest, ref = 'HEAD') => git([...NO_HOOKS, 'worktree', 'add', '--detach', dest, ref], repo);
 
 /**
  * A dangling commit holding the working tree exactly as it is — tracked

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());