canary-test-cli 7.1.0 → 8.0.0

package/dist/engine/guardian/pr-check.js

@@ -25,10 +25,9 @@
  *     to the later CLI wave. This module is the pure library logic.
  */
 import { readFileSync } from 'node:fs';
-import { extname, join } from 'node:path';
+import { join } from 'node:path';
 import { readJsonWithWarning } from '../core/config-validation.js';
-import { isAssertionFreeTest } from '../core/quality-scorer.js';
-import { Fidelity, coverageDegradedNotice, coverageStatus, isSourcePath, isTestPath, isTestSupportPath, isTypeOnlyModule, } from './coverage.js';
+import { Fidelity, coverageDegradedNotice, coverageDeltaNotice, coverageDeltaStatus, coverageCauses, coverageStatus, isSourcePath, isTestPath, isTestSupportPath, isTypeOnlyModule, } from './coverage.js';
 import { Severity, severitySortKey } from './impact-mapper.js';
 import { ensureAscii } from '../util/ensure-ascii.js';
 const HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
@@ -69,72 +68,143 @@ function mergeLines(lines) {
  */
 export function scopeDiff(diffText) {
     const addedByPath = new Map();
-    let currentPath = null;
-    let newLineno = 0;
-    let skipCurrent = false;
+    walkDiff(diffText, (line) => {
+        if (!line.added)
+            return;
+        const lines = addedByPath.get(line.path);
+        if (lines)
+            lines.push(line.lineno);
+        else
+            addedByPath.set(line.path, [line.lineno]);
+    });
+    const units = [];
+    for (const [path, lines] of addedByPath) {
+        units.push({ path, added_ranges: mergeLines(lines) });
+    }
+    return units;
+}
+// Single-character C escapes git's `quote_c_style` emits, per `sq_lookup`.
+const C_ESCAPES = {
+    a: 0x07,
+    b: 0x08,
+    f: 0x0c,
+    n: 0x0a,
+    r: 0x0d,
+    t: 0x09,
+    v: 0x0b,
+    '"': 0x22,
+    '\\': 0x5c,
+};
+const UTF8_DECODER = new TextDecoder('utf-8');
+/**
+ * Undo git's C-style path quoting (`core.quotePath`, on by default).
+ *
+ * A path with a non-ASCII (or control) byte is emitted by `git diff` wrapped in
+ * double quotes with its bytes octal-escaped:
+ * `+++ "b/caf\303\251.ts"`. Left as-is, the quotes ride along in the unit's
+ * path, so the file resolves to nothing: `extname` reads `.ts"`,
+ * {@link isSourcePath} says "not program source", and
+ * {@link filterHeuristicNoise} drops the finding — a silent false negative on
+ * every non-ASCII-named file. A value that is not quoted is returned verbatim.
+ */
+function unquoteCStyle(value) {
+    if (!isCQuoted(value))
+        return value;
+    const body = value.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch !== '\\') {
+            // Any non-escaped character is already a decoded code point; re-encode it
+            // so the whole path decodes as one UTF-8 byte stream.
+            for (const byte of new TextEncoder().encode(ch))
+                bytes.push(byte);
+            continue;
+        }
+        const next = body[i + 1];
+        if (next === undefined)
+            return value; // trailing backslash → not quoted
+        if (next >= '0' && next <= '7') {
+            const octal = /^[0-7]{1,3}/.exec(body.slice(i + 1))[0];
+            bytes.push(Number.parseInt(octal, 8) & 0xff);
+            i += octal.length;
+            continue;
+        }
+        const mapped = C_ESCAPES[next];
+        if (mapped === undefined)
+            return value; // unknown escape → leave alone
+        bytes.push(mapped);
+        i += 1;
+    }
+    return UTF8_DECODER.decode(new Uint8Array(bytes));
+}
+/**
+ * True when `value` is wrapped in the double quotes git uses for C-style path
+ * quoting. Split out of {@link unquoteCStyle} to keep its decode loop under
+ * the cyclomatic-complexity threshold.
+ */
+function isCQuoted(value) {
+    return value.length >= 2 && value.startsWith('"') && value.endsWith('"');
+}
+/** The new-side path a `+++ ` header names, or `null` for a deleted file. */
+function headerPath(line) {
+    // A quoted path is unquoted BEFORE the `b/` strip: the quotes wrap the
+    // prefix too (`"b/caf\303\251.ts"`), so stripping first would never match.
+    const target = unquoteCStyle(line.slice(4).trim());
+    if (target === '/dev/null')
+        return null;
+    // Strip the conventional "b/" prefix.
+    return target.startsWith('b/') ? target.slice(2) : target;
+}
+/**
+ * Walk a unified diff, calling `emit` once per NEW-SIDE line, in file order.
+ *
+ * The single parser behind {@link scopeDiff}, {@link addedContentByPath} and
+ * `visibleLinesByPath`. Those three read different things off the same walk —
+ * added line numbers, added text, and added-plus-context text — and each used
+ * to carry its own copy of the header/hunk bookkeeping, which is three places
+ * for a diff-format edge case to be fixed in two of.
+ *
+ * Removed (`-`) lines and the `` marker are not
+ * emitted and do not advance the new-side counter, since neither exists on that
+ * side. Deleted files (`+++ /dev/null`) emit nothing at all.
+ *
+ * FIX 7: `--- `/`+++ ` are file headers ONLY before the first hunk of a file.
+ * Inside a hunk body a `+++ ...` line is ADDED CONTENT whose real text is
+ * `++ ...`, and mistaking it for a header loses the rest of the file.
+ */
+export function walkDiff(diffText, emit) {
+    let path = null;
+    let lineno = 0;
     let inHunk = false;
     for (const line of splitLines(diffText)) {
         if (line.startsWith('diff --git')) {
-            // New file block begins → leave any prior hunk body; path is set by the
-            // upcoming `+++ ` header.
+            // A new file block begins → leave any prior hunk body; the path is set
+            // by the upcoming `+++ ` header.
             inHunk = false;
-            currentPath = null;
-            skipCurrent = false;
+            path = null;
             continue;
         }
-        // `--- `/`+++ ` are file headers ONLY before the first hunk of a file. Once
-        // inside a hunk body a `+++ ...` line is an ADDED content line whose real
-        // text is `++ ...` and must not be mistaken for a header (FIX 7).
         if (!inHunk && line.startsWith('+++ ')) {
-            const target = line.slice(4).trim();
-            if (target === '/dev/null') {
-                skipCurrent = true;
-                currentPath = null;
-                continue;
-            }
-            skipCurrent = false;
-            // Strip the conventional "b/" prefix.
-            currentPath = target.startsWith('b/') ? target.slice(2) : target;
-            if (!addedByPath.has(currentPath))
-                addedByPath.set(currentPath, []);
+            path = headerPath(line);
             continue;
         }
-        if (!inHunk && line.startsWith('--- ')) {
-            // Old-file header; ignored (path comes from +++).
+        // Old-file header; ignored (the path comes from `+++`).
+        if (!inHunk && line.startsWith('--- '))
             continue;
-        }
         const hunk = HUNK_RE.exec(line);
         if (hunk) {
-            newLineno = Number.parseInt(hunk[1], 10);
+            lineno = Number.parseInt(hunk[1], 10);
             inHunk = true;
             continue;
         }
-        if (skipCurrent || currentPath === null)
-            continue;
-        if (line.startsWith('+')) {
-            addedByPath.get(currentPath).push(newLineno);
-            newLineno += 1;
-        }
-        else if (line.startsWith('-')) {
-            // Removed line: does not advance the new-file counter.
+        if (path === null)
             continue;
-        }
-        else if (line.startsWith('\\')) {
-            // "" — metadata, ignore.
+        if (line.startsWith('-') || line.startsWith('\\'))
             continue;
-        }
-        else {
-            // Context line (leading space) or blank — advances new-file counter.
-            newLineno += 1;
-        }
+        emit({ path, lineno, text: line.slice(1), added: line.startsWith('+') });
+        lineno += 1;
     }
-    const units = [];
-    for (const [path, lines] of addedByPath) {
-        if (lines.length === 0)
-            continue;
-        units.push({ path, added_ranges: mergeLines(lines) });
-    }
-    return units;
 }
 // FIX 2 (signal-quality): a changed file whose ADDED lines are ONLY imports /
 // re-exports (no real declarations or logic) is a barrel/index file
@@ -173,48 +243,20 @@ function isNeutralLine(stripped) {
 /**
  * Map each changed file to the CONTENT of its added (`+`) lines.
  *
- * Mirrors {@link scopeDiff}'s parser but captures the added-line *text* (the
- * `+` stripped) rather than line numbers. Deleted files (`+++ /dev/null`) are
- * excluded; a `+++ ` line inside a hunk body is added content, not a header
- * (same FIX 7 guard as `scopeDiff`).
+ * The same walk {@link scopeDiff} takes, reading the added-line *text* rather
+ * than its line number.
  */
-function addedContentByPath(diffText) {
+export function addedContentByPath(diffText) {
     const added = new Map();
-    let currentPath = null;
-    let skipCurrent = false;
-    let inHunk = false;
-    for (const line of splitLines(diffText)) {
-        if (line.startsWith('diff --git')) {
-            inHunk = false;
-            currentPath = null;
-            skipCurrent = false;
-            continue;
-        }
-        if (!inHunk && line.startsWith('+++ ')) {
-            const target = line.slice(4).trim();
-            if (target === '/dev/null') {
-                skipCurrent = true;
-                currentPath = null;
-                continue;
-            }
-            skipCurrent = false;
-            currentPath = target.startsWith('b/') ? target.slice(2) : target;
-            if (!added.has(currentPath))
-                added.set(currentPath, []);
-            continue;
-        }
-        if (!inHunk && line.startsWith('--- '))
-            continue;
-        if (HUNK_RE.test(line)) {
-            inHunk = true;
-            continue;
-        }
-        if (skipCurrent || currentPath === null)
-            continue;
-        if (line.startsWith('+')) {
-            added.get(currentPath).push(line.slice(1));
-        }
-    }
+    walkDiff(diffText, (line) => {
+        if (!line.added)
+            return;
+        const texts = added.get(line.path);
+        if (texts)
+            texts.push(line.text);
+        else
+            added.set(line.path, [line.text]);
+    });
     return added;
 }
 /**
@@ -656,91 +698,63 @@ export function buildFindings(results) {
     }
     return [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
 }
-// Map a test file's extension to the framework whose assertion/test patterns
-// the quality scorer should use. Unknown → pytest (the scorer's own fallback).
-const TEST_FRAMEWORK_BY_EXT = {
-    '.py': 'pytest',
-    '.ts': 'vitest',
-    '.tsx': 'vitest',
-    '.js': 'vitest',
-    '.jsx': 'vitest',
-    '.mjs': 'vitest',
-    '.cjs': 'vitest',
-};
-function frameworkForTestPath(path) {
-    return TEST_FRAMEWORK_BY_EXT[extname(path).toLowerCase()] ?? 'pytest';
-}
-// A test-function signature / decorator / block-close / comment — lines that
-// are not a test *body*. If a diff's added lines are ONLY these (e.g. a rename
-// that adds just `def test_new():` while the asserting body stays as context),
-// there is no added body to judge and we must not flag it.
-const TEST_SIGNATURE_RE = /^\s*(?:async\s+)?def\s+test\w*\s*\(|^\s*(?:it|test|describe)\s*\(/;
-const BLOCK_DELIMITERS = new Set(['})', '});', '}', ')', '{']);
 /**
- * True iff the added lines contain a real body line — not just a test
- * signature, decorator, comment, or a bare block delimiter.
+ * Percentage-point bands for a coverage **regression** (#606).
+ *
+ * A drop is graded by how far it fell and stops at `HIGH` — it never reaches
+ * `CRITICAL`. An uncovered new block is a fact about one artifact; a drop is a
+ * *relative* measurement across two, and guardian cannot verify that the base
+ * artifact it was handed is genuinely the base of this PR. The top of the scale
+ * is reserved for what guardian can prove on its own.
  */
-function hasAddedTestBody(added) {
-    for (const line of added) {
-        const stripped = line.trim();
-        if (!stripped)
-            continue;
-        if (stripped.startsWith('#') ||
-            stripped.startsWith('//') ||
-            stripped.startsWith('@') ||
-            stripped.startsWith('*') ||
-            stripped.startsWith('/*')) {
-            continue;
-        }
-        if (BLOCK_DELIMITERS.has(stripped))
-            continue;
-        if (TEST_SIGNATURE_RE.test(line))
-            continue;
-        return true;
-    }
-    return false;
+const REGRESSION_HIGH_POINTS = 20;
+const REGRESSION_MEDIUM_POINTS = 5;
+/** `92.0% (23/25)` — a ratio a reviewer can check without doing the division. */
+function ratioLabel(ratio) {
+    const pct = ((ratio.covered / ratio.coverable) * 100).toFixed(1);
+    return `${pct}% (${ratio.covered}/${ratio.coverable})`;
 }
 /**
- * Advisory `weak-test` findings for ADDED tests that assert nothing.
+ * Turn regressed base-vs-head deltas into `coverage-regression` findings (#606).
  *
- * Consumes the test-path units {@link filterTestUnits} sets aside (a test file
- * needs no test of its own, but an added test that asserts nothing is itself a
- * gap). Scores only the diff's *added* lines per test file via
- * {@link isAssertionFreeTest} — a high-precision signal (a real test function
- * with zero assertions), so snapshot/table-driven tests are not flagged. These
- * findings are `LOW`/`weak-test` and are **never** gated (see
- * {@link computeExitCode}): they surface, never block.
+ * Only `regressed` deltas become findings — an improvement and a flat result
+ * are not news. Fidelity is `COVERAGE_VERIFIED` because both sides of the
+ * comparison were measured by a real coverage run; there is no graph or
+ * heuristic path to a delta, and a tier that cannot measure must not guess one.
+ *
+ * The evidence carries both ratios AND both raw counts on purpose: base and
+ * head can disagree about how many lines are coverable at all (a diff adds
+ * lines; two producers may instrument differently), and a bare pair of
+ * percentages would hide that.
  */
-export function buildWeakTestFindings(testUnits, diffText) {
-    const addedByPath = addedContentByPath(diffText);
+export function buildRegressionFindings(deltas) {
     const findings = [];
-    for (const unit of testUnits) {
-        const added = addedByPath.get(unit.path);
-        if (!added || added.length === 0)
-            continue;
-        // A rename adds only the signature line (body is unchanged context) —
-        // nothing new to judge, so don't flag it (FP guard).
-        if (!hasAddedTestBody(added))
+    for (const delta of deltas) {
+        if (!delta.regressed)
             continue;
-        const code = added.join('\n');
-        const framework = frameworkForTestPath(unit.path);
-        if (isAssertionFreeTest(code, framework)) {
-            findings.push(new GuardianFinding({
-                path: unit.path,
-                unit: unit.path,
-                kind: 'weak-test',
-                fidelity: Fidelity.Heuristic,
-                severity: Severity.LOW,
-                evidence: 'added test asserts nothing (advisory — never blocks the gate)',
-                suggestion: 'add at least one assertion, or delete the test if it is a placeholder.',
-                added_ranges: [...unit.added_ranges],
-            }));
-        }
+        const points = delta.dropPoints;
+        const severity = points >= REGRESSION_HIGH_POINTS
+            ? Severity.HIGH
+            : points >= REGRESSION_MEDIUM_POINTS
+                ? Severity.MEDIUM
+                : Severity.LOW;
+        findings.push(new GuardianFinding({
+            path: delta.path,
+            unit: delta.path,
+            kind: 'coverage-regression',
+            fidelity: Fidelity.CoverageVerified,
+            severity,
+            evidence: `coverage fell ${points.toFixed(1)} points on a file this change ` +
+                `touches: base ${ratioLabel(delta.base)} ${ARROW} head ` +
+                `${ratioLabel(delta.head)}`,
+            suggestion: `Restore the lost coverage in \`${delta.path}\` — a test that ` +
+                'exercised this file on the base ref no longer reaches part of it.',
+        }));
     }
-    return findings;
+    return [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
 }
 /** Flatten inclusive `[start, end]` ranges into a sorted list of line numbers. */
-function linesInRanges(ranges) {
+export function linesInRanges(ranges) {
     const lines = new Set();
     for (const [start, end] of ranges) {
         for (let ln = start; ln <= end; ln++)
@@ -754,7 +768,7 @@ function linesInRanges(ranges) {
  * Requires a `//`/`#` comment leader (FIX 1), strips a trailing inline-comment
  * close (e.g. `*​/`), and trims surrounding whitespace.
  */
-function suppressionReason(line) {
+export function suppressionReason(line) {
     const match = SUPPRESS_RE.exec(line);
     if (match === null)
         return null;
@@ -846,26 +860,11 @@ export function computeExitCode(findings, gate) {
     return 0;
 }
 const STICKY_MARKER = '<!-- canary-pr-guardian -->';
-// Severity → status icon for the sticky comment (encodes severity in form, not
-// just text, so the most urgent findings read at a glance).
-//
-// Written as `\u{...}` escapes, not literal glyphs: this file is `.ts`, and the
-// house rule keeps emitted non-ASCII out of non-Markdown source (see the
-// "Output data glyphs" block in `cli.ts`). They are emitted verbatim.
 /**
- * Character budget for a rendered sticky comment (#457).
- *
- * GitHub rejects an issue/PR comment body over **65,536** characters. The post
- * path reports that as "could not post", so an over-long body means the gate
- * silently produces nothing on exactly the large PRs that need it most -- the
- * same silent-green failure #369 was filed for.
- *
- * 60,000 leaves ~5.5k of headroom for anything appended outside
- * `renderFindings` (degradation annotations, upsert wrappers) without inviting
- * a body that only *just* fits and then breaks when a filename grows.
- *
- * The cap applies ONLY to the comment. The `--emit-analysis` JSON record is the
- * authoritative complete set and is never truncated.
+ * Character budget for a rendered sticky comment (#457). GitHub rejects a body
+ * over 65,536 characters, which would silently post nothing on the largest PRs
+ * (#369); 60,000 leaves headroom for appended annotations. The comment only:
+ * the `--emit-analysis` record is complete and never truncated.
  */
 export const COMMENT_CHAR_BUDGET = 60_000;
 /** The line that accounts for findings the budget could not fit (#457). */
@@ -909,6 +908,26 @@ function findingDict(finding) {
         uncovered_lines: finding.uncovered_lines,
     };
 }
+/** Short display form for a rev: 10 chars of a sha, a ref name verbatim. */
+function shortRev(rev) {
+    if (!rev)
+        return '?';
+    return /^[0-9a-f]{40}$/i.test(rev) ? rev.slice(0, 10) : rev;
+}
+/**
+ * The one-line diff provenance shown on every surface (#761).
+ *
+ * Deliberately terse and always present — a line that appears only when
+ * something is wrong teaches readers to ignore it when it does appear.
+ */
+export const MERGE_REF_WARNING = 'HEAD is a pull_request MERGE REF, not the PR head, so this diff spans ' +
+    'commits merged into the base branch and is WIDER than the PR';
+export function provenanceLine(p) {
+    const noun = p.fileCount === 1 ? 'file' : 'files';
+    const range = `${shortRev(p.base)}...${shortRev(p.head)}`;
+    const warn = p.mergeRef ? ` ${EM_DASH} ${MERGE_REF_WARNING}` : '';
+    return `Diff: \`${range}\` (${p.fileCount} ${noun}, via ${p.origin})${warn}`;
+}
 /**
  * Join every degradation notice this run produced into one line, dropping the
  * empty ones. Notices are independent (the agent tier and the coverage input
@@ -923,19 +942,90 @@ function coverageBlock(state) {
     return { status: coverageStatus(state), ...state };
 }
 /**
- * The comment body for a run with zero active findings.
- *
- * #554: the ✅ all-clear headline is reserved for a run whose coverage report
- * spoke to every changed file. Anything less says so in the body — a `<sub>`
- * footer under a green headline is read as boilerplate, and this is the exact
- * shape that let 43 coverage-blind PRs read as covered.
+ * True when this run VERIFIED NO COVERAGE and every finding is a naming guess
+ * (#761): a confident count over a zero coverage denominator is an abstention.
+ * Not this case: `unitsTotal === 0` (no claim either way), any coverage- or
+ * graph-verified finding (real evidence), or no findings at all (the per-cause
+ * headline already says what was not verified, #928).
+ */
+export function isCoverageAbstention(coverage, findings) {
+    if (!coverage || coverage.unitsTotal === 0)
+        return false;
+    if (coverageStatus(coverage) !== 'unavailable')
+        return false;
+    if (findings.length === 0)
+        return false;
+    return findings.every((f) => f.fidelity === Fidelity.Heuristic);
+}
+/**
+ * The abstention headline (#761) — states what was NOT verified, and never a
+ * count of findings, which is what reads as a measured result.
+ */
+function abstentionHeadline(checked) {
+    const noun = checked === 1 ? 'file' : 'files';
+    return (`${WARNING} abstained: no coverage data ` +
+        `(${checked} ${noun} judged heuristically)`);
+}
+/** The body paragraph that stops the heuristic findings reading as a verdict. */
+const ABSTENTION_BODY = 'No coverage report reached this run, so nothing below is a coverage ' +
+    'verdict — every finding is a filename-level guess. A gate that verified ' +
+    'zero items has abstained; this is not a pass.';
+const files = (n) => `${n} file${n === 1 ? '' : 's'}`;
+/** The unverified-unit causes present on a run, worst first (#928). */
+function causeEntries(state) {
+    const { stale, scopeGap, nonCoverable } = coverageCauses(state);
+    const trees = (state.instrumentedTrees ?? []).map((t) => t || '.');
+    const entries = [
+        [
+            stale,
+            `${WARNING} coverage report stale: ${stale} changed ${files(stale).split(' ')[1]} missing from it`,
+            'coverage report stale (changed lines missing from it)',
+        ],
+        [
+            scopeGap,
+            `${WARNING} not coverage-checked: ${files(scopeGap)} outside instrumented trees (${trees.join(', ')})`,
+            'not coverage-checked (outside instrumented trees)',
+        ],
+        [
+            nonCoverable,
+            `${WHITE_CHECK} nothing to test: only non-executable lines changed (${files(nonCoverable)})`,
+            'nothing to test (only non-executable lines changed)',
+        ],
+    ];
+    return entries.filter(([n]) => n > 0);
+}
+/**
+ * One headline per cause (#928) plus the lesser causes as count lines. ✅ only
+ * when the report spoke to every changed unit (#554): any B or C unit is ⚠️.
+ */
+function coverageHeadline(state, notice) {
+    const clean = `${WHITE_CHECK} no test-coverage gaps`;
+    if (state?.unitsTotal === 0) {
+        return [`${WHITE_CHECK} nothing to test: no source files changed`, []];
+    }
+    if (!state?.parsed) {
+        const blind = `${WARNING} no gaps found, but coverage was ${state ? coverageStatus(state) : ''}`;
+        return [notice ? blind : clean, []];
+    }
+    const [worst, ...rest] = causeEntries(state);
+    // Matched units plus non-executable ones: nothing is missing, so plain ✅.
+    if (!worst || (worst[1].startsWith(WHITE_CHECK) && state.unitsMatched > 0)) {
+        return [clean, []];
+    }
+    return [worst[1], rest.map(([n, , label]) => `- ${files(n)}: ${label}`)];
+}
+/**
+ * The comment body for a run with zero active findings. The notice goes in the
+ * body, not only a `<sub>` footer, which is read as boilerplate (#554).
  */
-function noGapsLines(coverageState, suppressedCount) {
+function noGapsLines(coverageState, suppressedCount, abstained = false, checked = 0) {
     const notice = coverageState ? coverageDegradedNotice(coverageState) : null;
-    const headline = notice
-        ? `${WARNING} no gaps found, but coverage was ${coverageStatus(coverageState)}`
-        : `${WHITE_CHECK} no test-coverage gaps`;
-    const lines = [`## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ${headline}`];
+    const [cause, counts] = coverageHeadline(coverageState, notice);
+    const headline = abstained ? abstentionHeadline(checked) : cause;
+    const lines = [
+        `## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ${headline}`,
+        ...counts,
+    ];
     if (notice) {
         lines.push(`> **${notice}**`, '', 'Zero files matched is an abstention, not a pass — nothing here is ' +
             'evidence that the changed lines are covered.');
@@ -947,12 +1037,18 @@ function noGapsLines(coverageState, suppressedCount) {
 }
 export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, gateMeta = null, blobBase = null) {
     const ordered = [...findings].sort((a, b) => severitySortKey(a.severity) - severitySortKey(b.severity));
+    // #761: an abstained run never headlines a count, on any surface.
+    const abstained = gateMeta?.abstained === true;
     // #554: the coverage ladder's own degradation, stated alongside the tier's.
     const coverageState = gateMeta?.coverage ?? null;
     const coverageNotice = coverageState
         ? coverageDegradedNotice(coverageState)
         : null;
-    const notice = combineNotices(degradedNotice, coverageNotice);
+    // #606: the delta's own degradation is a THIRD independent reason a run can
+    // be blind, so it joins the same combined notice rather than replacing one.
+    const deltaState = gateMeta?.coverageDelta ?? null;
+    const deltaNotice = deltaState ? coverageDeltaNotice(deltaState) : null;
+    const notice = combineNotices(degradedNotice, coverageNotice, deltaNotice);
     if (fmt === 'json') {
         const payload = {
             findings: ordered.map(findingDict),
@@ -970,6 +1066,18 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
             payload['skipped'] = gateMeta.skipped ?? [];
             if (coverageState)
                 payload['coverage'] = coverageBlock(coverageState);
+            // #606: the delta's denominator, so a machine consumer can tell "no
+            // regressions" from "never compared" without re-deriving it.
+            if (deltaState) {
+                payload['coverage_delta'] = {
+                    status: coverageDeltaStatus(deltaState),
+                    ...deltaState,
+                };
+            }
+            // #761: machine consumers need the diff's endpoints for the same reason
+            // humans do — every count in this payload is scoped by them.
+            if (gateMeta.provenance)
+                payload['provenance'] = { ...gateMeta.provenance };
         }
         return ensureAscii(JSON.stringify(payload, null, 2));
     }
@@ -1018,24 +1126,38 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
     const CONFIDENCE_NOTE = 'Confidence — **coverage-verified**: measured from a real coverage run · ' +
         '**graph-verified**: inferred from the call graph · **heuristic**: filename ' +
         `guess (lowest). tier ${tier}: deterministic check, no LLM.`;
-    const footerLine = `<sub>${CONFIDENCE_NOTE}${notice ? ` ${EM_DASH} ${notice}` : ''}</sub>`;
-    // #554: a coverage-blind run must not present as a run that checked and found
-    // nothing. The notice goes in the BODY, not only the footer — a `<sub>` line
-    // under a green headline is read as boilerplate.
+    // #928: the coverage notice is rendered in the body, so the footer omits it.
+    const footerNotice = combineNotices(degradedNotice, deltaNotice);
+    const footerLine = `<sub>${CONFIDENCE_NOTE}${footerNotice ? ` ${EM_DASH} ${footerNotice}` : ''}</sub>`;
+    // #554: a coverage-blind run must not present as one that checked and passed.
     const coverageLine = coverageNotice ? `> **${coverageNotice}**` : null;
+    // #761: shown on EVERY comment, clean or not. The run that motivated this was
+    // a findings run whose findings were all phantom, so gating the line on a
+    // problem guardian had not detected would have hidden it exactly when needed.
+    const provLine = gateMeta?.provenance
+        ? `<sub>${provenanceLine(gateMeta.provenance)}</sub>`
+        : null;
     if (fmt === 'comment') {
         const fileCount = new Set(active.map((f) => f.path)).size;
         const lines = [STICKY_MARKER];
         if (active.length === 0) {
-            lines.push(...noGapsLines(coverageState, suppressed.length));
+            lines.push(...noGapsLines(coverageState, suppressed.length, abstained, gateMeta?.checked ?? 0));
         }
         else {
             const noun = fileCount === 1 ? 'file needs' : 'files need';
+            // #761: on an abstained run the headline states the abstention instead of
+            // a count. The findings stay in the table below — they are useful, they
+            // are just not a coverage verdict, and a count headline is exactly what
+            // makes a reader take them for one.
             lines.push(`## ${BABY_CHICK} Canary PR Guardian ${EM_DASH} ` +
-                `${fileCount} ${noun} test coverage`);
-            lines.push('These lines were changed by this PR but no test exercises them. Add or ' +
-                'extend a test that covers them, or mark the line ' +
-                '`// canary:allow-untested <reason>` if it is intentionally untested.');
+                (abstained
+                    ? abstentionHeadline(gateMeta?.checked ?? 0)
+                    : `${fileCount} ${noun} test coverage`));
+            lines.push(abstained
+                ? ABSTENTION_BODY
+                : 'These lines were changed by this PR but no test exercises them. Add or ' +
+                    'extend a test that covers them, or mark the line ' +
+                    '`// canary:allow-untested <reason>` if it is intentionally untested.');
             if (coverageLine)
                 lines.push('', coverageLine);
             lines.push('', '| Sev | File | What is uncovered, and what to do | Confidence |', '| --- | --- | --- | --- |');
@@ -1069,24 +1191,41 @@ export function renderFindings(findings, fmt, tier = 0, degradedNotice = null, g
                 lines.push('', `<sub>${suppressed.length} finding(s) suppressed as intentional and not counted above.</sub>`);
             }
         }
+        // Directly above the confidence footer: provenance and confidence are the
+        // two "how much should I trust this" facts, so they read as one block.
+        if (provLine)
+            lines.push('', provLine);
         lines.push('', footerLine);
         return lines.join('\n');
     }
     // fmt == "text" (default fallback): plain, no markdown/HTML.
-    const cleanHeadline = coverageNotice
-        ? // #554: same rule as the comment surface — a blind run never claims clean.
-            `Canary PR Guardian — no gaps found, but coverage was ${coverageStatus(coverageState)}`
-        : 'Canary PR Guardian — no test-coverage gaps';
+    // #554/#928: the comment surface's per-cause headline, without its glyph.
+    const [cause, causeCounts] = coverageHeadline(coverageState, coverageNotice);
+    const cleanHeadline = `Canary PR Guardian — ${cause.replace(/^\S+ /, '')}`;
+    // #761: the same rule on the surface an engineer reads at their desk. The
+    // headline is stripped of the comment surface's markdown-era glyph so the
+    // terminal line stays plain text.
+    const textAbstention = `Canary PR Guardian — ` +
+        abstentionHeadline(gateMeta?.checked ?? 0).replace(`${WARNING} `, '');
     const lines = [
-        active.length === 0
-            ? cleanHeadline
-            : `Canary PR Guardian — ${new Set(active.map((f) => f.path)).size} file(s) need test coverage`,
+        abstained
+            ? textAbstention
+            : active.length === 0
+                ? cleanHeadline
+                : `Canary PR Guardian — ${new Set(active.map((f) => f.path)).size} file(s) need test coverage`,
+        ...(abstained || active.length > 0 ? [] : causeCounts),
     ];
     for (const finding of ordered) {
         const unit = finding.unit && finding.unit !== finding.path ? ` → ${finding.unit}` : '';
         const mark = finding.suppressed ? ' (suppressed)' : '';
         lines.push(`[${finding.severity}] ${finding.path}${unit} — ${finding.evidence} (${finding.fidelity})${mark}`);
     }
+    // #761: the terminal surface gets the same provenance the comment does —
+    // this is the one an engineer reads at their desk, where a wrong `--diff` is
+    // likeliest.
+    if (gateMeta?.provenance) {
+        lines.push(provenanceLine(gateMeta.provenance).replace(/`/g, ''));
+    }
     let footer = `tier ${tier}: deterministic check, no LLM`;
     if (notice)
         footer += ` - ${notice}`;
@@ -1142,16 +1281,8 @@ export const DEFAULT_SKIP_GLOBS = [
     '**/__generated__/**',
 ];
 /**
- * Parsed `canary.guardian` config block.
- *
- * Phase 1 stores every field but only `pr_*` gate/tier drive behavior.
- * `skip_globs` and the `precommit_*`/`coverage_paths` fields are read into the
- * object (scaffold) for later phases (SC-2 skip, SC-5 tier).
- *
- * `skip_globs` defaults to docs/markdown PLUS generated/dependency artifacts
- * (lockfiles, `dist`/`build` outputs, minified JS, snapshots — see
- * {@link DEFAULT_SKIP_GLOBS}) so noise-only paths skip out of the box; an
- * explicit `skipGlobs` in config (even `[]`) overrides it.
+ * Parsed `canary.guardian` config block. `skip_globs` defaults to
+ * {@link DEFAULT_SKIP_GLOBS}; an explicit `skipGlobs` (even `[]`) overrides it.
  */
 export class GuardianConfig {
     pr_enabled;