pi-lens 4.2.0 → 4.3.0

package/dist/mcp/analyze-cli.js

@@ -165,6 +165,10 @@ function formatTurnEnd(response) {
  */
 const TURN_END_SKIP_REASONS = {
     "ipc-error": "no warm pi-lens MCP server answered for this workspace, or its build is stale — start the MCP server, or run `npm run build` if you have edited pi-lens sources",
+    // #3255: split out of `ipc-error` because its remedy is different and no
+    // rebuild reaches it. A server that was already running when pi-lens was
+    // upgraded still owns the endpoint name the previous build derived.
+    "no-listener": "nothing is listening on this workspace's warm endpoint — start the MCP server; if pi-lens was upgraded while a server was running, that server still owns the endpoint name of the previous build, so restart it",
     timeout: "the warm pi-lens MCP server did not finish the pass within the hook budget — the turn-end findings are kept and will be delivered on a later Stop",
     "schema-mismatch": "the warm pi-lens MCP server speaks a different turn-end schema than this hook binary — rebuild and restart the server so both halves match",
     "stale-answer": "the warm pi-lens MCP server replied about a superseded state — the findings are kept for a later Stop",

package/dist/mcp/server.js

@@ -321,8 +321,16 @@ function startIpcServer() {
                     socket.end(`${JSON.stringify({ error: String(err) })}\n`);
                 }
             });
+        }, {
+            label: "mcp-warm-server",
+            // #3383: a peer that never terminates its request line gets the same
+            // error reply every other unusable request gets, instead of this
+            // process holding its bytes until the client's timeout.
+            onOverflow: () => socket.end(`${JSON.stringify({ error: "warm request line exceeded the framing limit" })}\n`),
         }));
-        socket.on("error", () => socket.destroy());
+        // The stream is already destroyed when this handler runs; the listener
+        // remains the surviving teardown witness, while destroy() was a no-op.
+        socket.on("error", () => { });
     });
     ipc.on("error", (err) => {
         // Listener failure must not take down the MCP server — warm channel is an
@@ -1623,28 +1631,32 @@ async function handleRequest(request) {
     }
 }
 // --- stdio read loop (newline-delimited JSON) --------------------------------
-let buffer = "";
 process.stdin.setEncoding("utf8");
-process.stdin.on("data", (chunk) => {
-    buffer += chunk;
-    let newlineIndex = buffer.indexOf("\n");
-    while (newlineIndex !== -1) {
-        const line = buffer.slice(0, newlineIndex).trim();
-        buffer = buffer.slice(newlineIndex + 1);
-        if (line.length > 0) {
-            let request;
-            try {
-                request = JSON.parse(line);
-            }
-            catch {
-                sendError(null, -32700, "Parse error");
-            }
-            if (request)
-                void handleRequest(request);
-        }
-        newlineIndex = buffer.indexOf("\n");
+// #3383: framed by the shared reader, so the partial line this loop holds
+// between chunks has a ceiling. It used to be `buffer += chunk` with none: a
+// host that never sent a newline grew one JS string until V8 refused the next
+// concatenation with `RangeError: Invalid string length` — raised inside this
+// `data` handler, where nothing can catch it, which is the ending #3375 fixed
+// for child output. `continuous` because this is a stream of requests, not one
+// request per connection like every socket reader.
+process.stdin.on("data", createWarmIpcLineReader((raw) => {
+    const line = raw.trim();
+    if (line.length === 0)
+        return;
+    let request;
+    try {
+        request = JSON.parse(line);
     }
-});
+    catch {
+        sendError(null, -32700, "Parse error");
+    }
+    if (request)
+        void handleRequest(request);
+}, {
+    label: "mcp-stdio",
+    continuous: true,
+    onOverflow: () => sendError(null, -32700, "Parse error: request line exceeded the framing limit"),
+}));
 process.stdin.on("end", () => {
     endSituationalToolTelemetry();
     void flushExtensionLog().finally(() => process.exit(0));

package/dist/scripts/lib/web-tree-sitter-dir.mjs

@@ -0,0 +1,123 @@
+/**
+ * Where web-tree-sitter is installed — ONE ladder, for every caller that needs
+ * the answer (#3409).
+ *
+ * Callers: `clients/tree-sitter-client.ts` (the grammar read path and the
+ * lazy-fetch write target), `clients/install-diagnostics.ts` (the pasted
+ * environment fingerprint) and `scripts/install-selftest.mjs` (the installed
+ * host's own diagnostic). Each used to spell its own rungs, and the two that led
+ * with a BARE specifier were unconditionally broken on the host pi ships: inside
+ * a `bun build --compile` binary `require.resolve("web-tree-sitter")` throws
+ * MODULE_NOT_FOUND while `require.resolve("web-tree-sitter/tree-sitter.wasm")` —
+ * an explicit file subpath — still resolves.
+ *
+ * It lives in `scripts/lib/` rather than `clients/` because the installed
+ * selftest is packaged (`files[]`) without `clients/`, and this is the house
+ * pattern for logic a packaged .mjs script and the TypeScript runtime share
+ * (`scripts/lib/skills-predicate.mjs`, `scripts/lib/process-scan.mjs`). It
+ * imports nothing but `node:fs` and `node:path`, so it loads even on the hosts
+ * whose broken dependency graph the selftest exists to report.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** The package this module is about. Also the name its manifest must carry. */
+const WEB_TREE_SITTER = "web-tree-sitter";
+/**
+ * The wasm the runtime loads, at the package root — where 0.25.10's `exports`
+ * map puts it (`"./tree-sitter.wasm": "./tree-sitter.wasm"`). If a later release
+ * moves it (#381's 0.26 migration), the two FALLBACK rungs below stop matching
+ * and the resolver rungs, which ask Node for that same subpath, keep working;
+ * this constant is then the one line to update.
+ */
+const RUNTIME_WASM = "tree-sitter.wasm";
+/**
+ * True when `dir` IS an installed web-tree-sitter package: its own manifest
+ * names it, and the wasm the runtime loads is in it.
+ *
+ * Round 1 review of #3409 (R3418-1): the constructed rungs used to accept any
+ * directory that merely EXISTED at `<base>/node_modules/web-tree-sitter`, so an
+ * empty or foreign directory of that name became the runtime fetch's write
+ * target and a downloaded grammar would land in an unrelated tree. Existence is
+ * not identity. The manifest name is the identity; the wasm is what makes the
+ * directory the right place to put grammars, since a grammar is only loadable by
+ * the web-tree-sitter runtime sitting next to it (the ABI drift #1564 is about).
+ */
+export function isWebTreeSitterPackageDir(dir) {
+    try {
+        if (!fs.existsSync(path.join(dir, RUNTIME_WASM)))
+            return false;
+        const manifest = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+        return manifest?.name === WEB_TREE_SITTER;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The package directory owning `resolvedFile`: walk up until a directory passes
+ * the identity check, or the filesystem root is reached. The walk exists because
+ * an `exports` map may point into a subdirectory, so the file's own parent is
+ * not necessarily the package; the identity check is what stops the walk, so a
+ * resolver that answers outside any web-tree-sitter package yields nothing
+ * rather than an unrelated ancestor.
+ */
+function packageDirOf(resolvedFile) {
+    let dir = path.dirname(resolvedFile);
+    for (;;) {
+        if (isWebTreeSitterPackageDir(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * web-tree-sitter's installed package directory, or undefined.
+ *
+ * Rung order, most authoritative first:
+ *  1. the `tree-sitter.wasm` SUBPATH, which resolves on a compiled host as well
+ *     as a plain one. This is the rung that makes the non-core grammars
+ *     fetchable there at all.
+ *  2. the BARE specifier, for a future web-tree-sitter whose exports map no
+ *     longer carries `./tree-sitter.wasm`.
+ *  3. pi-lens's own package root, for the temp-dir compile layout (#20) where
+ *     the resolver's context is a temp directory but the package root still has
+ *     the right `node_modules`.
+ *  4. the working directory, the pre-#3409 last resort.
+ *
+ * Rungs 1-2 are the resolver's answer and outrank the constructed guesses: the
+ * grammars must come from the SAME package whose wasm the runtime loaded. Every
+ * rung's candidate passes `isWebTreeSitterPackageDir` before it is returned.
+ *
+ * `resolve`, `packageRoot` and `cwd` are injected, never defaulted: the caller's
+ * resolver context and package root are what differ on a compiled host, so they
+ * must not be silently replaced by this module's — and a rung nothing can vary
+ * is a rung no test can drive.
+ */
+export function resolveWebTreeSitterPackageDir(deps) {
+    for (const specifier of [
+        `${WEB_TREE_SITTER}/${RUNTIME_WASM}`,
+        WEB_TREE_SITTER,
+    ]) {
+        try {
+            const dir = packageDirOf(deps.resolve(specifier));
+            if (dir)
+                return dir;
+        }
+        catch {
+            /* next rung */
+        }
+    }
+    for (const base of [deps.packageRoot, deps.cwd]) {
+        try {
+            const candidate = path.join(base(), "node_modules", WEB_TREE_SITTER);
+            if (isWebTreeSitterPackageDir(candidate))
+                return candidate;
+        }
+        catch {
+            /* next rung */
+        }
+    }
+    return undefined;
+}

package/dist/tools/lens-diagnostic-mark.js

@@ -45,8 +45,9 @@ import * as path from "node:path";
 import { Type } from "../clients/deps/typebox.js";
 import { markDisposition, normalizeMessage, } from "../clients/diagnostic-dispositions.js";
 import { insertSuppressComment } from "../clients/dispatch/suppress-writer.js";
-import { getFileDiagnostics, } from "../clients/widget-state.js";
+import { normalizeMapKey } from "../clients/path-utils.js";
 import { resolveLensToolName } from "../clients/tool-config.js";
+import { getFileDiagnostics, } from "../clients/widget-state.js";
 const DISPOSITIONS = [
     "false-positive",
     "suppress",
@@ -70,11 +71,22 @@ function isBlank(text) {
  * violation) are ambiguous; per #802 this picks the match CLOSEST to the
  * caller's line rather than guessing — the conservative choice for suppress,
  * which must never place a comment above the wrong site.
+ *
+ * #3160: `getFileDiagnostics` keys with `normalizeEphemeralMapKey` — case-
+ * preserving on POSIX by design (no filesystem I/O on that hot path) — but
+ * the widget's own writers key from `ctx.filePath`, which
+ * `createDispatchContext` already canonicalizes to the on-disk casing
+ * (#2016/#3098). `absPath` here is the caller's RAW spelling, so on a
+ * case-insensitive filesystem a mis-cased mark call must derive the same
+ * canonical key the writers used or it silently misses the live diagnostic
+ * and falls through to the fuzzy fallback below — do NOT case-fold
+ * `normalizeEphemeralMapKey` itself for this: on a case-sensitive filesystem
+ * that would merge two genuinely different files.
  */
 function widgetCrossCheck(absPath, tool, rule, message, callerLine) {
     let diagnostics;
     try {
-        diagnostics = getFileDiagnostics(absPath);
+        diagnostics = getFileDiagnostics(normalizeMapKey(absPath));
     }
     catch {
         return undefined;

package/dist/tools/lens-diagnostics.js

@@ -18,13 +18,13 @@ import { DEPENDENCY_DRIFT_MAX_DELIVERIES } from "../clients/blocker-freshness.js
 import { freshnessFromMtime } from "../clients/freshness.js";
 import { applyFindingPolicy, loadProjectRulePolicyMap, } from "../clients/dispatch/finding-policy.js";
 import { gateFindingsByPathFreshness } from "../clients/advisory-provenance.js";
-import { markUnreconciledFindings } from "../clients/finding-delivery-gate.js";
+import { formatCacheAgeLabel, markUnreconciledFindings, } from "../clients/finding-delivery-gate.js";
 import { normalizeRuleId } from "../clients/dispatch/rule-id-normalize.js";
 import { applyRulePolicy, } from "../clients/dispatch/rule-policy.js";
 import { compactRenderResult } from "./render-compact.js";
 import { combineAbortSignals } from "../clients/deadline-utils.js";
 import { getProjectIgnoreMatcher } from "../clients/file-utils.js";
-import { isAtOrAboveHomeDir, normalizeEphemeralMapKey, normalizeFilePath, realpathOrResolve, } from "../clients/path-utils.js";
+import { isAtOrAboveHomeDir, normalizeEphemeralMapKey, normalizeFilePath, normalizeMapKey, realpathOrResolve, } from "../clients/path-utils.js";
 import { getLSPService } from "../clients/lsp/index.js";
 import { retireInlineBlockerAndResyncGuard } from "../clients/git-guard.js";
 import { primaryServerId, resolveLspCwdForFile, } from "../clients/lsp/config.js";
@@ -47,7 +47,7 @@ import { findAuxiliaryProfileForSource, retagAuxiliaryDiagnostics, } from "../cl
 import { detectFileRole } from "../clients/file-role.js";
 import { STALE_LINE_MARKER } from "../clients/stale-marker.js";
 import { makeProgressReporter, scanningSummaryLine } from "./scan-progress.js";
-import { createLspDiagnosticsTool, LSP_SEVERITY_FILTERS, MAX_BATCH_FILES, } from "./lsp-diagnostics.js";
+import { createLspDiagnosticsTool, LSP_SEVERITY_FILTERS, MAX_BATCH_FILES, renderBatchOutcomeLines, } from "./lsp-diagnostics.js";
 import { demotePastEofDiagnostics, PAST_EOF_STALE_MARKER, resyncDocumentOnPastEof, } from "../clients/diagnostic-line-freshness.js";
 // The widget state exposes the full per-file diagnostic set; this is the tool's
 // own generous display budget per file (independent of the TUI's 12 cap), to
@@ -197,11 +197,15 @@ captureLspStatusRepaint, getRuntime, isLensGuardEnabled = () => true) {
                 if ((details.unconfirmedFiles ?? 0) > 0)
                     return `lens_diagnostics${scope} — ${count} ${noun} · ${details.cleanFiles ?? 0} clean · ${details.unconfirmedFiles} unconfirmed${details.timedOutFiles ? ` (${details.timedOutFiles} timed out)` : ""}`;
                 const outcomeCounts = details.outcomeCounts;
+                const tooLargeLines = renderBatchOutcomeLines(details.outcomes ?? []);
+                if (tooLargeLines.length > 0)
+                    return `lens_diagnostics${scope} — too large: ${tooLargeLines.join("; ")}`;
                 const notConfirmed = outcomeCounts
                     ? (outcomeCounts.inconclusive ?? 0) +
                         (outcomeCounts.unavailable ?? 0) +
                         (outcomeCounts.unsupported ?? 0) +
-                        (outcomeCounts.failed ?? 0)
+                        (outcomeCounts.failed ?? 0) +
+                        (outcomeCounts.too_large ?? 0)
                     : 0;
                 if (notConfirmed > 0)
                     return `lens_diagnostics${scope} — ${count} ${noun} · ${notConfirmed} checks not confirmed`;
@@ -508,16 +512,19 @@ function formatProjectDeltaDiagnostic(diagnostic, stale) {
  * rule/message), live -> unchanged. See `clients/finding-delivery-gate.ts`
  * surface `lens-diagnostics:mode-delta`.
  */
-function appendProjectDiagnosticsDeltaLines(lines, cwd, report, severity, includeFile) {
+function appendProjectDiagnosticsDeltaLines(groups, cwd, report, severity, includeFile) {
     const scoped = (report?.diagnostics ?? []).filter((diagnostic) => includeFile(diagnostic.filePath) &&
         matchesSeverity(projectDiagnosticToWidget(diagnostic, diagnostic.filePath), severity));
-    const gated = gateFindingsByPathFreshness({
-        store: "lens-diagnostics-delta-project",
-        findings: scoped,
+    const { "lens-diagnostics-delta-project": gated } = gateFindingsByPathFreshness({
         cwd,
-        scannedAt: report?.generatedAt,
-        citedPath: (d) => d.filePath,
-        onMissing: "drop",
+        sources: {
+            "lens-diagnostics-delta-project": {
+                findings: scoped,
+                scannedAt: report?.generatedAt,
+                citedPath: (d) => d.filePath,
+                onMissing: "drop",
+            },
+        },
     });
     const staleSet = new Set(gated.stale);
     // Concatenating live-then-stale reorders a file's demoted rows to the end
@@ -532,11 +539,9 @@ function appendProjectDiagnosticsDeltaLines(lines, cwd, report, severity, includ
         byFile.set(filePath, bucket);
     }
     for (const [filePath, fileDiagnostics] of byFile) {
-        const rel = path.relative(cwd, filePath);
-        if (!lines.includes(rel))
-            lines.push(rel);
+        const group = getDeltaFileGroup(groups, cwd, filePath);
         for (const diagnostic of fileDiagnostics) {
-            lines.push(formatProjectDeltaDiagnostic(diagnostic, staleSet.has(diagnostic)));
+            group.projectLines.push(formatProjectDeltaDiagnostic(diagnostic, staleSet.has(diagnostic)));
         }
     }
     return diagnostics.length;
@@ -704,13 +709,16 @@ function applyDeltaFreshnessGate(files, cwd, generatedAt) {
     }
     if (flat.length === 0)
         return files;
-    const gated = gateFindingsByPathFreshness({
-        store: "lens-diagnostics-delta",
-        findings: flat,
+    const { "lens-diagnostics-delta": gated } = gateFindingsByPathFreshness({
         cwd,
-        scannedAt: effectiveAt,
-        citedPath: (f) => f.filePath,
-        onMissing: "drop",
+        sources: {
+            "lens-diagnostics-delta": {
+                findings: flat,
+                scannedAt: effectiveAt,
+                citedPath: (f) => f.filePath,
+                onMissing: "drop",
+            },
+        },
     });
     // Two passes (live, then stale) reorder a file's demoted rows to the end
     // of its warnings array rather than the original report order — cosmetic
@@ -723,7 +731,15 @@ function applyDeltaFreshnessGate(files, cwd, generatedAt) {
     }
     for (const f of gated.stale) {
         const arr = byFile.get(f.filePath) ?? [];
-        arr.push({ ...f.warning, stale: true, line: undefined });
+        // Fix B (#3167): carry the stamp the row was judged against so the render
+        // can emit one age label per file group — the row's own observation stamp,
+        // not the report-level one (the #2504 r4 multi-stamp case).
+        arr.push({
+            ...f.warning,
+            stale: true,
+            line: undefined,
+            staleAsOf: effectiveAt,
+        });
         byFile.set(f.filePath, arr);
     }
     return files
@@ -733,10 +749,34 @@ function applyDeltaFreshnessGate(files, cwd, generatedAt) {
     }))
         .filter((file) => file.warnings.length > 0);
 }
+function getDeltaFileGroup(groups, cwd, filePath) {
+    const rel = path.relative(cwd, filePath);
+    let group = groups.get(rel);
+    if (!group) {
+        group = {
+            rel,
+            actionableLines: [],
+            qualityLines: [],
+            projectLines: [],
+            incomplete: false,
+        };
+        groups.set(rel, group);
+    }
+    return group;
+}
 // @delivery-surface: lens-diagnostics:mode-delta
 function formatDeltaMode(cacheManager, cwd, severity, pathsScope) {
     const actionableEntry = cacheManager.readCache("actionable-warnings", cwd);
     const qualityEntry = cacheManager.readCache("code-quality-warnings", cwd);
+    // #3170: files whose re-verify pass could not complete inside its budget —
+    // their rows render as carried, plus this explicit gap label (never a
+    // false clean). Computed from the RAW actionable-warnings cache entries
+    // because the freshness pipeline below rebuilds the file shape. The
+    // re-verify only ever writes the actionable-warnings cache — the quality
+    // report's file shape carries no such marker.
+    const reverifyIncompletePaths = new Set((actionableEntry?.data?.files ?? [])
+        .filter((file) => file.reVerifyIncomplete)
+        .map((file) => normalizeMapKey(file.filePath)));
     const actionable = actionableEntry?.data;
     const quality = qualityEntry?.data;
     // Project rule policy (`.pi-lens.json` `rules.<id>.disable` /
@@ -778,32 +818,69 @@ function formatDeltaMode(cacheManager, cwd, severity, pathsScope) {
         warnings: matchingWarnings(file.warnings),
     }))
         .filter((file) => file.warnings.length > 0);
-    const lines = [];
+    // #3196: one grouping pass keyed by file — every tier below appends into
+    // the SAME per-file group (see `DeltaFileGroup`/`getDeltaFileGroup`), so a
+    // file present in more than one report always renders its rows under its
+    // own header, wherever that header ends up in the final buffer.
+    const groups = new Map();
     // Fixable warnings from actionable-warnings and quality cache entries retain
     // their own severity tier. Apply the same threshold semantics as the LSP path.
+    // F5/F10 (#3168): at most ONE label group (age and/or #3170's re-verify
+    // gap) per file. The actionable tier is folded first, so its stale row (if
+    // any) wins the group's age label; the quality tier only supplies one when
+    // the actionable tier had none for that file (#3168 F10(c)'s quality-only
+    // shape). The `(re-verify incomplete)` flag is a fact about the file (from
+    // the raw actionable cache, independent of which tier's rows happen to
+    // render it), so it is recorded on the group the first time either tier
+    // touches that file and never predicted.
     if (filteredActionableFiles.length > 0) {
         for (const file of filteredActionableFiles) {
-            const rel = path.relative(cwd, file.filePath);
-            lines.push(`${rel}`);
+            const group = getDeltaFileGroup(groups, cwd, file.filePath);
             for (const w of file.warnings) {
                 const where = w.stale ? STALE_LINE_MARKER : `L${w.line ?? "?"}`;
-                lines.push(`  ⚠ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
+                group.actionableLines.push(`  ⚠ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
+            }
+            const key = normalizeMapKey(file.filePath);
+            if (reverifyIncompletePaths.has(key))
+                group.incomplete = true;
+            if (!group.staleRow) {
+                const staleWarning = file.warnings.find((w) => w.stale);
+                if (staleWarning)
+                    group.staleRow = { staleAsOf: staleWarning.staleAsOf };
             }
         }
     }
     // Quality issues
     if (filteredQualityFiles.length > 0) {
         for (const file of filteredQualityFiles) {
-            const rel = path.relative(cwd, file.filePath);
-            if (!lines.includes(rel))
-                lines.push(rel);
+            const group = getDeltaFileGroup(groups, cwd, file.filePath);
             for (const w of file.warnings) {
                 const where = w.stale ? STALE_LINE_MARKER : `L${w.line ?? "?"}`;
-                lines.push(`  ℹ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
+                group.qualityLines.push(`  ℹ ${where}  ${w.rule ?? w.code ?? w.tool}  ${w.message}`);
             }
+            const key = normalizeMapKey(file.filePath);
+            if (reverifyIncompletePaths.has(key))
+                group.incomplete = true;
+            if (!group.staleRow) {
+                const staleWarning = file.warnings.find((w) => w.stale);
+                if (staleWarning)
+                    group.staleRow = { staleAsOf: staleWarning.staleAsOf };
+            }
+        }
+    }
+    const projectDeltaCount = appendProjectDiagnosticsDeltaLines(groups, cwd, projectDelta, severity, includeFile);
+    const lines = [];
+    for (const group of groups.values()) {
+        lines.push(group.rel);
+        lines.push(...group.actionableLines);
+        lines.push(...group.qualityLines);
+        lines.push(...group.projectLines);
+        if (group.staleRow) {
+            lines.push(`  (${formatCacheAgeLabel(group.staleRow.staleAsOf)})`);
         }
+        if (group.incomplete)
+            lines.push("  (re-verify incomplete)");
     }
-    const projectDeltaCount = appendProjectDiagnosticsDeltaLines(lines, cwd, projectDelta, severity, includeFile);
     const selectedActionableFiles = filteredActionableFiles;
     const selectedQualityFiles = filteredQualityFiles;
     const aw = selectedActionableFiles.reduce((count, file) => count + file.warnings.length, 0);
@@ -1093,11 +1170,20 @@ function runnerIdOf(diagnostic) {
 }
 /**
  * The one project-runner retirement decision. Coverage is authoritative when
- * present for the runner; the older id-only arm is used only when absent.
+ * present for the runner; the older id-only arm is used only when the runner
+ * declared no coverage at all.
+ *
+ * #2962: an entry with an EMPTY file set is a declaration, not a missing one —
+ * "this producer analysed the root and proved zero files". Selecting it out by
+ * its own size (the pre-#2962 `entry.files.size > 0` filter) dropped it into the
+ * whole-root id-only arm, so one complete opengrep report with
+ * `paths.scanned: []` retired every retained opengrep finding in the tree even
+ * though no file had been scanned. The id-only arm is unchanged for the eight
+ * runners that declare no coverage.
  */
 export function runnerRetirementDecision(diagnostic, filePath, authoritativeRunnerIds, authoritativeCoverage) {
     const runnerId = runnerIdOf(diagnostic);
-    const coverage = (authoritativeCoverage ?? []).filter((entry) => entry.runnerId === runnerId && entry.files.size > 0);
+    const coverage = (authoritativeCoverage ?? []).filter((entry) => entry.runnerId === runnerId);
     if (coverage.length === 0) {
         return authoritativeRunnerIds?.has(runnerId) ? "retire" : "keep";
     }
@@ -1792,6 +1878,14 @@ async function formatFullMode(cwd, severity, lspService, cacheManager, options =
         });
     }
     for (const entry of authoritativeRunnerCoverage) {
+        // #2962: a zero-file declaration retires nothing, so it must neither
+        // write this row (a `runner_coverage_retired` row with count 0 would
+        // report the opposite of what happened) nor BURN the once-per-session
+        // claim — the session's first real coverage row would then be suppressed
+        // by the call that proved no coverage. Its own observation is the
+        // `runner-coverage-empty` ledger row raised at the fresh-fetch seam.
+        if (entry.files.size === 0)
+            continue;
         if (!claimPhaseOncePerSession("runner_coverage_retired", entry.runnerId)) {
             continue;
         }