testguard-cli 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-09-17
+
+From a second field report on a real codebase (456 tests, 27 claims, 35
+faults; 13 survived on the first run, two critical claims with zero coverage).
+
+### Fixed
+
+- **Worktree mode probed HEAD while reading the claims file from the working
+  tree**, so uncommitted defender changes were silently ignored — the same
+  survivors came back with no hint why. `probe` now refuses (exit 2) when any
+  resolved defender or fault target has uncommitted changes, naming the files
+  and the commit it would have probed. Every summary names the commit probed.
+- `killed-by-undeclared-tests` never said which tests killed the fault; the
+  author could not fix `defendedBy` without grepping the suite. Evidence now
+  carries `detail.undeclaredKillers` and the CLI names the files.
+- `anchor-ambiguous` did not say how many hits; `detail.anchor { hits,
+  expected }` is recorded and printed.
+- A replacement with an unbalanced paren was `suite-failed-to-load`, not
+  `replacement-does-not-compile`: esbuild/vitest wording is now matched.
+- The claims schema promised defender discovery for an absent `defendedBy`;
+  the tool answered `nocover`. Discovery is implemented: the test files that
+  import the fault's target (relative or alias), recorded as
+  `defenders.discovered`. `nocover` now means exactly "no test file imports
+  this source".
+- `baseline.json` records `dirty`, as evidence already did.
+
+### Added
+
+- `--include-dirty`: snapshot the working tree (tracked edits and untracked,
+  non-ignored files) into a throwaway commit and probe that. HEAD, index and
+  the user's tree are never touched; `run.repo.snapshot` records the commit.
+- A one-line progress indicator on stderr (TTY only) so a minute of silence
+  is not mistaken for a hang.
+- Fixture: a claim with no `defendedBy` whose defender is discovered.
+
+### Changed
+
+- **Default output shows only unproven faults plus a killed count.**
+  `--verbose` restores the full stream.
+- The `survived` hint reminds the author to check that the fault is
+  observable at all before writing a test for it.
+- README: `$schema` path for consumers, `min-release-age` note, the
+  worktree-vs-working-tree rule, `brief` writes `brief.json` by default.
+
 ## [0.1.2] - 2026-09-17
 
 From a field report on a real codebase (63 test files, 458 tests, 39 faults).

package/README.md

@@ -52,9 +52,13 @@ tests were written against the survivors, 39/39 were killed.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.1.2` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.1.3` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
 
+Projects that set `min-release-age` in `.npmrc` cannot see a version published
+less than that many days ago (`ENOVERSIONS`); install that one with
+`npm i -D testguard-cli --min-release-age=0`.
+
 ## How it works
 
 ```bash
@@ -64,9 +68,11 @@ npx testguard-cli baseline    # freeze today's unproven findings; from now on on
 npx testguard-cli brief       # tell the agent where the suite is blind, before it writes
 ```
 
-1. **Claims** live in `testguard.claims.json`: a statement, where it comes
-   from, which tests supposedly defend it, and one or more *faults* — each a
-   deterministic source change that would make the statement false. Every
+1. **Claims** live in `testguard.claims.json` (editors validate it against
+   `"$schema": "./node_modules/testguard-cli/spec/schemas/claims.schema.json"`):
+   a statement, where it comes from, which tests supposedly defend it, and
+   one or more *faults* — each a deterministic source change that would make
+   the statement false. Every
    claim and every fault records who produced it. `testguard claims`
    validates the file and reports drift against `@claim <ID>` annotations in
    source. Test files are deliberately not scanned — a claim asserted by a test is the authorship trap the tool exists for — and annotation ids must contain a hyphen so prose is never mistaken for one.
@@ -91,10 +97,23 @@ npx testguard-cli brief       # tell the agent where the suite is blind, before
    written to `.testguard/evidence.json` — validated against the spec before
    it is written.
 
+   Worktree mode probes a **commit**. If a defender or target file has
+   uncommitted changes, `probe` refuses and says so — otherwise your new
+   tests would be silently absent and the same survivors would come back
+   with no hint why. `--include-dirty` snapshots the working tree (tracked
+   edits and new files) into a throwaway commit and probes that; your tree,
+   HEAD and index are never touched. Every summary names the commit probed.
+
+   A claim with no `defendedBy` has its defenders **discovered**: the test
+   files that import the fault's target, by relative path or resolved alias.
+   `NOCOVER` then means exactly "no test file imports this source".
+
    Practical loop: first pass `--no-escalate` (escalation re-runs the whole
-   suite N times per survivor); iterate on one claim with
-   `--claim <ID> --in-place` — only the files faults are applied to must be
-   committed, test files may be dirty; final pass with defaults. A custom
+   suite N times per survivor); iterate on one claim with `--claim <ID>` and
+   either `--include-dirty` or `--in-place` (only fault target files must be
+   clean there; test files may be dirty); final pass with defaults. By default
+   the stream shows only unproven faults plus a killed count — `--verbose`
+   shows every fault. A custom
    runner (`pnpm --filter`, a specific config) goes in
    `--runner-cmd "<cmd> {files} … {out}"`; if the scratch worktree cannot
    see your `node_modules`, pass `--node-modules <dir>`.
@@ -103,7 +122,8 @@ npx testguard-cli brief       # tell the agent where the suite is blind, before
    source and defenders are unchanged reuse their prior verdict, so a probe
    in CI costs only what changed.
 4. **Brief** turns evidence plus baseline into a ranked, capped
-   `## TEST BLINDSPOT CONTEXT` block. Wire it into an agent's session start
+   `## TEST BLINDSPOT CONTEXT` block, printed and also written to
+   `.testguard/brief.json` (`--text` prints only). Wire it into an agent's session start
    — for Claude Code, in `.claude/settings.json`:
 
    ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Proves a test suite defends the claims a project makes: injects the faults those claims forbid and reports every one the tests fail to detect.",
   "type": "module",
   "license": "MIT",

package/spec/GATE-SEMANTICS.md

@@ -35,10 +35,16 @@ Rules that follow from the table:
    reporting `survived` would be wrong the other way. It is `flaky-defender`.
 5. **Escalation never upgrades a verdict.** A fault that survives its declared
    defenders may be re-run against the whole suite. If the wider suite kills
-   it, the verdict stays `survived` with reason `killed-by-undeclared-tests`:
-   the claim's stated evidence chain is broken even though the suite is not
-   blind. It gates, and ranks below a true survivor.
-6. **Never a single global score.** Output is per claim, ranked. Blindness is
+   it, the verdict stays `survived` with reason `killed-by-undeclared-tests`
+   and `detail.undeclaredKillers` names the tests, so the author can fix
+   `defendedBy`. The claim's stated evidence chain is broken even though the
+   suite is not blind. It gates, and ranks below a true survivor.
+6. **A verdict names the commit it is about.** Evidence records `repo.head`;
+   when the working tree was probed instead, `repo.snapshot` holds the
+   throwaway commit that captured it. A tool must refuse to probe a commit
+   while defenders or targets have uncommitted changes, unless told to
+   snapshot the working tree — otherwise the answer looks right and is not.
+7. **Never a single global score.** Output is per claim, ranked. Blindness is
    concentrated, and one number hides where.
 
 ## Baseline and delta

package/spec/lib/validate.mjs

@@ -72,6 +72,9 @@ const semantic = {
       if (r.verdict === 'nocover' && !r.defenders.nocover) {
         errors.push({ path: `${p}/defenders/nocover`, message: 'nocover verdict requires defenders.nocover = true' });
       }
+      if (r.detail.undeclaredKillers && r.detail.reason !== 'killed-by-undeclared-tests') {
+        errors.push({ path: `${p}/detail/undeclaredKillers`, message: 'undeclaredKillers is only meaningful with reason killed-by-undeclared-tests' });
+      }
       if (r.verdict === 'unverifiable' && !r.detail.reason) {
         errors.push({ path: `${p}/detail/reason`, message: 'unverifiable requires a reason (e.g. anchor-missing, anchor-ambiguous)' });
       }

package/spec/schemas/baseline.schema.json

@@ -11,6 +11,10 @@
     "tool": { "$ref": "urn:guard-spec:v1:common#/$defs/tool" },
     "createdAt": { "$ref": "urn:guard-spec:v1:common#/$defs/isoDateTime" },
     "head": { "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
+    "dirty": {
+      "description": "Whether the working tree had uncommitted changes when the evidence behind this baseline was taken.",
+      "type": "boolean"
+    },
     "fingerprints": {
       "type": "object",
       "propertyNames": { "pattern": "^[a-f0-9]{64}$" },

package/spec/schemas/claims.schema.json

@@ -42,7 +42,7 @@
         "severity": { "$ref": "urn:guard-spec:v1:common#/$defs/severity" },
         "producedBy": { "$ref": "urn:guard-spec:v1:common#/$defs/provenance" },
         "defendedBy": {
-          "description": "Globs (repo-relative) for the test files that supposedly defend this claim. Empty or absent means: let the runner discover related tests. If the globs resolve to zero files the verdict is `nocover`.",
+          "description": "Globs (project-relative) for the test files that supposedly defend this claim. Empty or absent means: discover defenders as the test files that import each fault's target file (relative paths and resolved aliases). If nothing resolves, the verdict is `nocover`.",
           "type": "array",
           "items": { "type": "string", "minLength": 1 },
           "uniqueItems": true

package/spec/schemas/evidence.schema.json

@@ -21,7 +21,11 @@
           "required": ["head", "dirty"],
           "properties": {
             "head": { "$ref": "urn:guard-spec:v1:common#/$defs/gitSha" },
-            "dirty": { "type": "boolean" }
+            "dirty": { "type": "boolean" },
+            "snapshot": {
+              "description": "When the working tree was probed instead of `head`: the dangling commit that captured it. Not a ref; may be garbage-collected.",
+              "$ref": "urn:guard-spec:v1:common#/$defs/gitSha"
+            }
           },
           "additionalProperties": false
         },
@@ -149,6 +153,22 @@
             "escalationRuns": {
               "type": "array",
               "items": { "$ref": "#/$defs/testRun" }
+            },
+            "undeclaredKillers": {
+              "description": "With reason `killed-by-undeclared-tests`: the tests (as `file::name`) that failed in every escalation run. Names what to add to `defendedBy`.",
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            },
+            "anchor": {
+              "description": "With an anchor-related reason: how many times `find` occurred versus how many were expected.",
+              "type": "object",
+              "required": ["hits", "expected"],
+              "properties": {
+                "hits": { "type": "integer", "minimum": 0 },
+                "expected": { "type": "integer", "minimum": 1 }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
@@ -159,7 +179,11 @@
           "properties": {
             "requested": { "type": "array", "items": { "type": "string" } },
             "resolved": { "type": "array", "items": { "$ref": "urn:guard-spec:v1:common#/$defs/repoPath" } },
-            "nocover": { "type": "boolean" }
+            "nocover": { "type": "boolean" },
+            "discovered": {
+              "description": "True when no defenders were declared and `resolved` was found by static import of the subject's file.",
+              "type": "boolean"
+            }
           },
           "additionalProperties": false
         },

package/src/baseline/baseline.mjs

@@ -7,7 +7,7 @@ export function buildBaseline(evidence, { createdAt = new Date().toISOString() }
     if (r.verdict === 'killed') continue;
     fingerprints[r.fingerprint] = (fingerprints[r.fingerprint] ?? 0) + 1;
   }
-  return { schemaVersion: 1, tool: evidence.tool, createdAt, head: evidence.run.repo.head, fingerprints };
+  return { schemaVersion: 1, tool: evidence.tool, createdAt, head: evidence.run.repo.head, dirty: evidence.run.repo.dirty, fingerprints };
 }
 
 /**

package/src/brief/brief.mjs

@@ -11,7 +11,7 @@ export function hintFor(r) {
     case 'survived':
       return r.detail.reason === 'killed-by-undeclared-tests'
         ? `Only tests outside its declared defenders (${defenders}) catch this; fix the claim's defendedBy or move the assertion.`
-        : `${defenders} stayed green with this fault applied; add an assertion that fails on it and passes on HEAD.`;
+        : `${defenders} stayed green with this fault applied; add an assertion that fails on it and passes on HEAD. If no test's outcome can change, first check the fault is observable at all.`;
     case 'nocover':
       return `No test file matches ${r.defenders.requested.join(', ') || '(no defenders declared)'}; nothing defends this claim.`;
     case 'unverifiable':

package/src/cli.mjs

@@ -29,6 +29,8 @@ probe
   --severity <level>   gate only at or above   (default: low)
   --ref <commit>       probe this commit in the scratch worktree (default: HEAD)
   --claim <ID,ID>      probe only these claims; writes .testguard/evidence-partial.json
+  --include-dirty      probe the working tree (a snapshot commit) instead of HEAD; uncommitted tests count
+  --verbose            also print each killed fault (default: only unproven ones, plus a count)
   --runner-cmd "<cmd>" custom runner; must contain {files} and {out}, e.g. "pnpm vitest run {files} --reporter=json --outputFile={out}"
   --node-modules <dir> node_modules to link into the scratch worktree (or TESTGUARD_NODE_MODULES)
   --in-place           mutate the working tree instead of a scratch worktree
@@ -62,6 +64,8 @@ export async function main(argv, io = { out: (s) => process.stdout.write(s + '\n
         max: { type: 'string', default: '20' },
         ref: { type: 'string', default: 'HEAD' },
         claim: { type: 'string' },
+        'include-dirty': { type: 'boolean', default: false },
+        verbose: { type: 'boolean', default: false },
         'runner-cmd': { type: 'string' },
         'node-modules': { type: 'string' },
         'in-place': { type: 'boolean', default: false },

package/src/commands/baseline.mjs

@@ -15,7 +15,7 @@ export async function baselineCommand({ projectDir, values }, io) {
   const outPath = values.out ? resolve(values.out) : baselinePath(projectDir);
   writeSpecDoc('baseline', outPath, baseline);
   const n = Object.values(baseline.fingerprints).reduce((a, b) => a + b, 0);
-  io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)} → ${outPath}`);
+  io.out(`baseline: ${n} unproven finding${n === 1 ? '' : 's'} frozen at ${baseline.head.slice(0, 12)}${baseline.dirty ? ' (working tree was dirty)' : ''} → ${outPath}`);
   io.out('Commit this file; from now on only new findings gate. Ignore the regenerated ones — add to .gitignore:');
   io.out('  .testguard/evidence.json');
   io.out('  .testguard/brief.json');

package/src/commands/claims.mjs

@@ -2,6 +2,7 @@ import { resolve } from 'node:path';
 import { loadClaims, defaultClaimsPath } from '../claims/load.mjs';
 import { scanAnnotations, reconcile } from '../claims/annotations.mjs';
 import { resolveDefenders } from '../probe/runner-vitest.mjs';
+import { discoverDefenders } from '../probe/discover.mjs';
 
 export async function claimsCommand({ projectDir, values }, io) {
   const path = values.claims ? resolve(values.claims) : defaultClaimsPath(projectDir);
@@ -16,8 +17,9 @@ export async function claimsCommand({ projectDir, values }, io) {
     io.out(`${claims.claims.length} claims in ${path} — ${annotated.size} carry a @claim annotation in source (test files are not scanned)`);
     io.out('');
     for (const c of claims.claims) {
-      const defenders = resolveDefenders(projectDir, c.defendedBy);
-      const cover = defenders.length ? `${defenders.length} defender${defenders.length === 1 ? '' : 's'}` : 'NO DEFENDER';
+      const declared = c.defendedBy?.length > 0;
+      const defenders = declared ? resolveDefenders(projectDir, c.defendedBy) : [...new Set(c.faults.flatMap((f) => discoverDefenders(projectDir, f.file)))];
+      const cover = defenders.length ? `${defenders.length} ${declared ? 'defender' : 'discovered'}${defenders.length === 1 ? '' : 's'}` : 'NO DEFENDER';
       io.out(`${annotated.has(c.id) ? '@ ' : '  '}${c.id.padEnd(14)} ${c.severity.padEnd(8)} ${c.source.kind.padEnd(10)} ${String(c.faults.length).padStart(2)} fault${c.faults.length === 1 ? ' ' : 's'}  ${cover.padEnd(12)}  ${c.statement}`);
     }
     if (drift.undeclared.length || drift.stale.length) io.out('');

package/src/commands/probe.mjs

@@ -41,7 +41,12 @@ export async function probeCommand({ projectDir, values, version }, io) {
     only,
     escalate: !values['no-escalate'],
     toolVersion: version,
-    onProgress: values.quiet ? undefined : (r) => io.out(renderRecord(r) + (r.reusedFrom ? '  (reused)' : '')),
+    includeDirty: values['include-dirty'],
+    onStage: !values.quiet && process.stderr.isTTY ? ({ claimId, faultId, stage, i, n }) => process.stderr.write(`\r\x1b[K  … ${claimId}/${faultId} ${stage} ${i}/${n}`) : undefined,
+    onProgress: values.quiet ? undefined : (r) => {
+      if (process.stderr.isTTY) process.stderr.write('\r\x1b[K');
+      if (values.verbose || r.verdict !== 'killed') io.out(renderRecord(r) + (r.reusedFrom ? '  (reused)' : ''));
+    },
   });
   writeSpecDoc('evidence', outPath, evidence);
 
@@ -52,7 +57,11 @@ export async function probeCommand({ projectDir, values, version }, io) {
     for (const r of sortForReport(evidence.records).filter((x) => x.verdict !== 'killed')) io.out('  ' + tag(r) + renderRecord(r));
   }
   io.out('');
-  io.out(renderSummary(evidence.records) + (baseline ? ` ${g.new.length} new since baseline, ${g.baselined.length} baselined.` : ' No baseline.'));
+  if (!values.quiet && !values.verbose) {
+    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(`evidence: ${outPath}${only ? ` (partial: --claim ${only.join(',')}; not the canonical evidence file)` : ''}`);
   return g.new.length > 0 ? 1 : 0;
 }

package/src/git.mjs

@@ -1,10 +1,13 @@
 import { spawnSync } from 'node:child_process';
 import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
 
 export class GitError extends Error {}
 
-export function git(args, cwd) {
-  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+export function git(args, cwd, env) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', env: env ? { ...process.env, ...env } : process.env });
   if (r.status !== 0) throw new GitError(`git ${args.join(' ')}: ${(r.stderr || r.stdout).trim()}`);
   return r.stdout.trim();
 }
@@ -25,6 +28,29 @@ export const isDirty = (dir, paths = []) => git(['status', '--porcelain', '--',
 
 export const addWorktree = (repo, dest, ref = 'HEAD') => git(['worktree', 'add', '--detach', dest, ref], repo);
 
+/**
+ * A dangling commit holding the working tree exactly as it is — tracked
+ * changes AND untracked (non-ignored) files — without touching HEAD, the
+ * index, or any ref. Built through a temporary index so the user's staging
+ * area is never read or written.
+ */
+export function snapshotWorkingTree(repo) {
+  const index = join(tmpdir(), `testguard-index-${randomBytes(6).toString('hex')}`);
+  const env = {
+    GIT_INDEX_FILE: index,
+    GIT_AUTHOR_NAME: 'testguard', GIT_AUTHOR_EMAIL: 'testguard@localhost',
+    GIT_COMMITTER_NAME: 'testguard', GIT_COMMITTER_EMAIL: 'testguard@localhost',
+  };
+  try {
+    git(['read-tree', 'HEAD'], repo, env);
+    git(['add', '-A', '--', '.'], repo, env);
+    const tree = git(['write-tree'], repo, env);
+    return git(['commit-tree', tree, '-p', 'HEAD', '-m', 'testguard: working-tree snapshot (not a ref)'], repo, env);
+  } finally {
+    rmSync(index, { force: true });
+  }
+}
+
 export function removeWorktree(repo, dest) {
   spawnSync('git', ['worktree', 'remove', '--force', dest], { cwd: repo });
   rmSync(dest, { recursive: true, force: true });

package/src/probe/classify.mjs

@@ -15,7 +15,8 @@ export function classify({ defenders, anchor, baselineRuns, probeRuns, confirmRu
   }
   const loadError = probeRuns.find((r) => r.outcome === 'error');
   if (loadError) {
-    const parseError = /syntax|parse/i.test(loadError.loadMessage ?? '');
+    // esbuild/vitest wording: "Transform failed with 1 error", `Expected ")" but found ";"`, "Unexpected token"
+    const parseError = /syntax|parse|transform failed|expected .+ but found|unexpected token/i.test(loadError.loadMessage ?? '');
     return { verdict: 'fault-invalid', reason: parseError ? 'replacement-does-not-compile' : 'suite-failed-to-load' };
   }
   if (probeRuns.some((r) => r.outcome === 'timeout' || r.timeouts > 0)) return { verdict: 'timeout', reason: 'test-timed-out' };

package/src/probe/discover.mjs

@@ -0,0 +1,12 @@
+import { join } from 'node:path';
+import { listTestFiles } from './runner-vitest.mjs';
+import { fileImports } from './rank.mjs';
+
+/**
+ * When a claim declares no defenders: the test files that import the fault's
+ * target file, directly, by relative path or through a resolved alias. This
+ * is what `nocover` measures against — no test file even imports the source.
+ */
+export function discoverDefenders(projectDir, targetRel) {
+  return listTestFiles(projectDir).filter((t) => fileImports(projectDir, join(projectDir, t), targetRel));
+}

package/src/probe/probe.mjs

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { git } from '../git.mjs';
 import { createRequire } from 'node:module';
 import { join, relative, resolve } from 'node:path';
-import { repoRoot as gitRoot, headSha, isDirty } from '../git.mjs';
+import { repoRoot as gitRoot, headSha, isDirty, snapshotWorkingTree } from '../git.mjs';
+import { discoverDefenders } from './discover.mjs';
 import { createScratch, inPlace, PreconditionError } from './worktree.mjs';
 import { applyFault, locate } from './inject.mjs';
 import * as vitest from './runner-vitest.mjs';
@@ -34,13 +36,17 @@ export async function probe({
   runnerCommand,
   nodeModules,
   only,
+  includeDirty = false,
+  onStage = () => {},
   escalate = true,
   scratchBase,
   toolVersion = '0.0.0',
   previous,
   onProgress = () => {},
 }) {
-  projectDir = resolve(projectDir);
+  // realpath: git reports the repository root by its real path (/private/var
+  // on macOS, not /var); every relative() below must start from the same place.
+  projectDir = realpathSync(resolve(projectDir));
   const root = gitRoot(projectDir);
   if (mode === 'in-place' && ref !== 'HEAD') throw new PreconditionError('--ref needs a scratch worktree; drop --in-place');
   const head = headSha(root, ref);
@@ -50,6 +56,8 @@ export async function probe({
   if (mode === 'in-place' && isDirty(root, targets)) {
     throw new PreconditionError(`uncommitted changes in fault target files (${targets.join(', ')}); commit or stash them, or drop --in-place. Only the files faults are applied to must be clean — test files may be dirty, which is what makes --in-place usable while writing tests.`);
   }
+  if (includeDirty && mode !== 'worktree') throw new PreconditionError('--include-dirty applies to worktree mode; drop --in-place');
+  if (includeDirty && ref !== 'HEAD') throw new PreconditionError('--include-dirty snapshots the working tree; it cannot be combined with --ref');
   const selected = only ? new Set(only) : null;
   if (selected) {
     const known = new Set(claims.claims.map((c) => c.id));
@@ -57,8 +65,28 @@ export async function probe({
     if (unknown.length) throw new PreconditionError(`--claim: unknown claim id(s) ${unknown.join(', ')}`);
   }
 
+  // Worktree mode probes a commit, not the working tree. Uncommitted defender
+  // or target edits would be silently absent — the same survivors, no hint why.
+  let snapshot;
+  if (mode === 'worktree') {
+    if (includeDirty) {
+      if (isDirty(root)) snapshot = snapshotWorkingTree(root);
+    } else if (ref === 'HEAD') {
+      const watched = new Set(targets);
+      for (const claim of claims.claims) {
+        if (selected && !selected.has(claim.id)) continue;
+        const declared = claim.defendedBy?.length ? vitest.resolveDefenders(projectDir, claim.defendedBy) : claim.faults.flatMap((f) => discoverDefenders(projectDir, f.file));
+        for (const d of declared) watched.add(relative(root, join(projectDir, d)));
+        for (const g of claim.defendedBy ?? []) if (!g.includes('*')) watched.add(relative(root, join(projectDir, g)));
+      }
+      const dirty = git(['status', '--porcelain', '--', ...watched], root).split('\n').filter(Boolean).map((l) => l.replace(/^[ MADRCU?!]{1,2}\s+/, '').replace(/^.* -> /, ''));
+      if (dirty.length) {
+        throw new PreconditionError(`${dirty.length} defender/target file${dirty.length === 1 ? ' has' : 's have'} uncommitted changes (${dirty.join(', ')}); worktree mode probes HEAD (${head.slice(0, 7)}), so those changes would be silently ignored. Commit them, run with --include-dirty to probe the working tree, or use --in-place.`);
+      }
+    }
+  }
   const startedAt = new Date().toISOString();
-  const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
+  const iso = mode === 'worktree' ? createScratch({ repoRoot: root, projectDir, ref: snapshot ?? ref, scratchBase, nodeModules }) : inPlace({ repoRoot: root, projectDir });
   const records = [];
   let runnerVersion;
   try {
@@ -81,9 +109,11 @@ export async function probe({
 
     for (const claim of claims.claims) {
       if (selected && !selected.has(claim.id)) continue;
-      const defenders = vitest.resolveDefenders(iso.projectDir, claim.defendedBy);
+      const declared = claim.defendedBy?.length ? vitest.resolveDefenders(iso.projectDir, claim.defendedBy) : null;
       for (const fault of claim.faults) {
-        const record = await probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, prior: prior.get(`${claim.id}/${fault.id}`), priorRunId: previous?.run.id });
+        const defenders = declared ?? discoverDefenders(iso.projectDir, fault.file);
+        const stage = (name, i, n) => onStage({ claimId: claim.id, faultId: fault.id, stage: name, i, n });
+        const record = await probeOne({ claim, fault, defenders, discovered: declared === null, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, stage, prior: prior.get(`${claim.id}/${fault.id}`), priorRunId: previous?.run.id });
         records.push(record);
         onProgress(record);
       }
@@ -99,7 +129,7 @@ export async function probe({
       id: `run-${startedAt.replace(/[-:.]/g, '').slice(0, 15)}`,
       startedAt,
       finishedAt: new Date().toISOString(),
-      repo: { head, dirty: isDirty(root) },
+      repo: { head, dirty: isDirty(root), ...(snapshot ? { snapshot } : {}) },
       runner: { name: vitest.name, ...((runnerVersion ?? readRunnerVersion(projectDir)) ? { version: runnerVersion ?? readRunnerVersion(projectDir) } : {}) },
       confirmRuns,
       mode,
@@ -108,7 +138,7 @@ export async function probe({
   };
 }
 
-async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, prior, priorRunId }) {
+async function probeOne({ claim, fault, defenders, discovered, allTests, iso, confirmRuns, escalate, baselineCache, runDefenders, stage, prior, priorRunId }) {
   const targetPath = join(iso.projectDir, fault.file);
   const targetExists = existsSync(targetPath);
   const inputs = {
@@ -134,6 +164,7 @@ async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, e
         const runs = [];
         let loadMessage;
         for (let i = 0; i < confirmRuns; i++) {
+          stage('baseline', i + 1, confirmRuns);
           const res = await runDefenders(defenders);
           runs.push(res.run);
           if (res.run.outcome !== 'pass') {
@@ -156,6 +187,7 @@ async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, e
         try {
           const probeRuns = rawProbeRuns;
           for (let i = 0; i < confirmRuns; i++) {
+            stage('probe', i + 1, confirmRuns);
             const { run, timeouts, loadMessage } = await runDefenders(defenders);
             probeRuns.push({ ...run, timeouts, loadMessage });
             if (shouldStopEarly(probeRuns)) break;
@@ -171,6 +203,7 @@ async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, e
             const runs = [];
             let killers = null;
             for (let i = 0; i < confirmRuns; i++) {
+              stage('escalation', i + 1, confirmRuns);
               const { run, failedTests } = await runDefenders(allTests);
               runs.push(run);
               killers = killers === null ? new Set(failedTests) : new Set(failedTests.filter((t) => killers.has(t)));
@@ -178,7 +211,10 @@ async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, e
             }
             detail.escalated = true;
             detail.escalationRuns = runs;
-            if (killers.size > 0 && runs.length === confirmRuns && runs.every(isKill)) detail.reason = 'killed-by-undeclared-tests';
+            if (killers.size > 0 && runs.length === confirmRuns && runs.every(isKill)) {
+              detail.reason = 'killed-by-undeclared-tests';
+              detail.undeclaredKillers = [...killers].sort();
+            }
           }
         } finally {
           mutation.restore();
@@ -189,6 +225,7 @@ async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, e
 
   const { verdict, reason } = classify({ defenders, anchor, baselineRuns: detail.baselineRuns, probeRuns: rawProbeRuns, confirmRuns });
   if (reason && !detail.reason) detail.reason = reason;
+  if (anchor && anchor.status !== 'ok' && anchor.status !== 'file-missing' && anchor.status !== 'defenders-failed-to-load') detail.anchor = { hits: anchor.hits, expected: anchor.expected };
 
   const blast = targetExists ? blastRadius(iso.projectDir, fault.file) : 0;
 
@@ -198,7 +235,7 @@ async function probeOne({ claim, fault, defenders, allTests, iso, confirmRuns, e
     subject: { kind: 'fault', id: fault.id, description: fault.description, file: fault.file, faultClass: fault.faultClass, producedBy: fault.producedBy },
     verdict,
     detail,
-    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0 },
+    defenders: { requested: claim.defendedBy ?? [], resolved: defenders, nocover: defenders.length === 0, ...(discovered ? { discovered: true } : {}) },
     inputs,
     rank: rank({ severity: claim.severity, sourceKind: claim.source.kind, blast }),
   };

package/src/probe/rank.mjs

@@ -94,6 +94,20 @@ function resolvesTo(fromFile, specifier, targetAbs, aliases) {
   return bases.some((b) => expandBase(b).includes(targetAbs));
 }
 
+/** Does the file at `absFile` import `targetRel` (relative or alias-resolved)? */
+export function fileImports(projectDir, absFile, targetRel) {
+  const targetAbs = resolve(projectDir, targetRel);
+  const aliases = loadAliases(projectDir);
+  let src;
+  try {
+    src = readFileSync(absFile, 'utf8');
+  } catch {
+    return false;
+  }
+  for (const m of src.matchAll(IMPORT_RE)) if (resolvesTo(absFile, m[1], targetAbs, aliases)) return true;
+  return false;
+}
+
 /**
  * Number of non-test source files that import `targetRel`: relative specifiers,
  * tsconfig/jsconfig `paths` aliases and package.json `imports` are resolved;

package/src/render.mjs

@@ -5,7 +5,16 @@ export const formatVerdict = (v) => (v === 'killed' ? 'killed' : v.toUpperCase()
 
 export function renderRecord(r) {
   const head = `${formatVerdict(r.verdict).padEnd(15)} ${r.claim.id}/${r.subject.id}`.padEnd(38);
-  const why = r.detail.reason ? `  [${r.detail.reason}]` : '';
+  let why = '';
+  if (r.detail.reason === 'killed-by-undeclared-tests' && r.detail.undeclaredKillers?.length) {
+    const files = [...new Set(r.detail.undeclaredKillers.map((k) => k.split('::')[0]))];
+    why = `  [killed-by-undeclared-tests: ${files.join(', ')}]`;
+  } else if (r.detail.reason === 'anchor-ambiguous' && r.detail.anchor) {
+    why = `  [anchor-ambiguous: ${r.detail.anchor.hits} hits, expected ${r.detail.anchor.expected}]`;
+  } else if (r.detail.reason) {
+    why = `  [${r.detail.reason}]`;
+  }
+  if (r.defenders.discovered) why += '  (defenders discovered by import)';
   return `${head} ${r.claim.severity.padEnd(8)} ${r.subject.file}  ${r.subject.description}${why}`;
 }
 
@@ -15,12 +24,13 @@ export function summarize(records) {
   return byVerdict;
 }
 
-export function renderSummary(records) {
+export function renderSummary(records, run) {
   const byVerdict = summarize(records);
   const parts = ORDER.filter((v) => byVerdict[v]).map((v) => `${byVerdict[v]} ${formatVerdict(v)}`);
   const unproven = records.filter((r) => r.verdict !== 'killed');
   const claims = new Set(unproven.map((r) => r.claim.id)).size;
-  return `${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.`;
+  const where = run ? ` Probed ${run.repo.snapshot ? `working tree (snapshot ${run.repo.snapshot.slice(0, 7)} of ${run.repo.head.slice(0, 7)})` : run.mode === 'in-place' ? `in place at ${run.repo.head.slice(0, 7)}${run.repo.dirty ? ' (dirty)' : ''}` : run.repo.head.slice(0, 7)}.` : '';
+  return `${records.length} faults probed: ${parts.join(', ')}. ${unproven.length} unproven fault${unproven.length === 1 ? '' : 's'} across ${claims} claim${claims === 1 ? '' : 's'}.${where}`;
 }
 
 /** Survivors first, then by rank score; killed last. */