@herbertgao/pi-extensions 2026.9.6 → 2026.9.8

package/node_modules/pi-lens/dist/tools/lsp-diagnostics.js

@@ -10,8 +10,13 @@ import { getProjectIgnoreMatcher, isExcludedDirName, } from "../clients/file-uti
 import { getLSPService, groupFilesByPrimaryServer, runPerServerGroups, } from "../clients/lsp/index.js";
 import { buildScopeKey, createWorkspaceDiagnosticsCacheContext, } from "../clients/lsp/workspace-diagnostics-cache.js";
 import { getServersForFileWithConfig, primaryServerId, } from "../clients/lsp/config.js";
+import { mapWithConcurrency } from "../clients/map-with-concurrency.js";
 import { combineAbortSignals, withDeadline, } from "../clients/deadline-utils.js";
 import { applyAuxiliarySuppressions, retagAuxiliaryDiagnostics, } from "../clients/dispatch/auxiliary-lsp.js";
+import { applyLspFindingPolicy, loadProjectRulePolicyMap, } from "../clients/dispatch/finding-policy.js";
+import { hasStrictDispositionMarks } from "../clients/diagnostic-dispositions.js";
+import { recordDegradationOnce } from "../clients/degradation-ledger.js";
+import { logLatency } from "../clients/latency-logger.js";
 import { detectFileRole } from "../clients/file-role.js";
 import { hashDiagnosticContent, touchCompletedConfirmationPolicy, touchCoverageGap, } from "../clients/lsp/diagnostic-binding.js";
 import { classifyCascadeWaitTier } from "../clients/lsp/wait-policy/index.js";
@@ -100,46 +105,6 @@ function boundedPositiveInt(value, fallback, min, max) {
  * for THIS tool's batch/directory sweep the same way #667 fixed it for the
  * workspace-diagnostics sweep.
  */
-async function mapWithConcurrency(items, concurrency, mapper, lspService, signal, onProgress) {
-    const results = [];
-    let completed = 0;
-    // Multiple original indices can map to the same file path (duplicate
-    // entries in an explicit `paths` batch) — track them as a per-file queue
-    // so each occurrence still lands in its own original slot.
-    const pendingIndices = new Map();
-    items.forEach((item, index) => {
-        const queue = pendingIndices.get(item);
-        if (queue)
-            queue.push(index);
-        else
-            pendingIndices.set(item, [index]);
-    });
-    const groups = groupFilesByPrimaryServer(items);
-    await runPerServerGroups(groups, concurrency, async (group) => {
-        if (signal?.aborted)
-            return;
-        const first = group.files[0];
-        if (first &&
-            lspService &&
-            !isWarmAttached() &&
-            typeof lspService.ensureWarmForSweep === "function") {
-            await lspService.ensureWarmForSweep(first, { signal });
-            if (signal?.aborted)
-                return;
-        }
-        for (const item of group.files) {
-            // Honor cancellation (Escape / turn abort): stop pulling new items
-            // rather than grind the whole batch. Completed entries are returned.
-            if (signal?.aborted)
-                return;
-            const index = pendingIndices.get(item).shift();
-            results[index] = await mapper(item, index);
-            completed += 1;
-            onProgress?.(completed, items.length);
-        }
-    }, signal);
-    return results;
-}
 /**
  * Project-ignore predicate rooted at `root`, fail-open. Lets a directory scan
  * honor the user's `.pi-lens.json` / `.gitignore` patterns — not just the
@@ -331,7 +296,17 @@ onConfirmedNoBlockers, getService = getLSPService) {
         },
     };
 }
-async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScope = "all") {
+async function collectDiagnosticsForFile(absPath, lspService, 
+/**
+ * #3041: project root the per-rule `ignores` globs (#965) are resolved
+ * against. ast-grep's LSP publishes per-document diagnostics without
+ * applying them, so this standalone `source=lsp` query has to — the same
+ * carve-out the NAPI runner applies on the same file. Positioned before the
+ * optional parameters so it is structurally REQUIRED: an optional
+ * `string | undefined` would silently disable the carve-out for whichever
+ * caller forgot to pass it.
+ */
+scanRoot, waitMs, serverScope = "all") {
     let timedOut = false;
     let content;
     // `touchFile` is the authoritative collection boundary for every scope: it
@@ -360,7 +335,11 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
                 const scopedDiagnostics = serverScope === "primary"
                     ? attached.response.diagnostics.filter((item) => item.serverId === primaryServerId(absPath))
                     : attached.response.diagnostics;
-                const filtered = applyAuxiliarySuppressions(scopedDiagnostics, content, { fileRole: detectFileRole(absPath, content) });
+                const filtered = applyAuxiliarySuppressions(scopedDiagnostics, content, {
+                    fileRole: detectFileRole(absPath, content),
+                    filePath: absPath,
+                    scanRoot,
+                });
                 return {
                     diagnostics: filtered,
                     timedOut: false,
@@ -420,6 +399,8 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
     const filtered = content !== undefined
         ? applyAuxiliarySuppressions(diagnostics, content, {
             fileRole: detectFileRole(absPath, content),
+            filePath: absPath,
+            scanRoot,
         })
         : diagnostics;
     // #1095: surface the touch's content binding (only a touch that resolved
@@ -588,6 +569,97 @@ function demoteInferredForFile(file, diagnostics, cwd, lspService) {
         service: lspService,
     });
 }
+/**
+ * #3088: the probe lane's stored-disposition / rule-policy / inline-suppression
+ * gate — the same `clients/dispatch/finding-policy.ts` stack `mode=full` and
+ * the per-edit dispatcher apply, called once per file at the position
+ * `demoteInferredForFile` already established: AFTER the confirmation verdict
+ * (which asks "did the server answer for this content" and must not be
+ * influenced by a policy drop) and BEFORE the rendered output, the severity
+ * filter and `reconcileWidgetFromLspResult`. One filtered set for all three, so
+ * the text, the counts and the widget footer cannot disagree — and so the
+ * footer reconcile can no longer re-arm a finding the mark-time
+ * `reconcileWidgetDisposition` demoted.
+ *
+ * Fails OPEN: a filter that throws returns the unfiltered set plus one bounded
+ * degradation record. A finding that stays visible is recoverable; one silently
+ * hidden by a broken filter is the harm this lane exists to prevent
+ * (AGENTS.md shape 48).
+ */
+function applyProbeFindingPolicy(file, diagnostics, cwd, content, 
+/**
+ * Round 2 F1: the caller's severity threshold. The count reported to the
+ * agent must be scoped to the SAME threshold the rendered result is, or a
+ * `severity: "error"` probe of a repo carrying warning-level marks prints
+ * "suppressed by disposition: N … Not a clean verdict" on a result that IS
+ * clean at that threshold — the skill's own folder-check recipe would emit
+ * the banner on every check. The threshold is applied HERE, in the tool that
+ * owns both the render and the record, rather than in the three call sites
+ * (three copies of one subtraction) or in
+ * `clients/dispatch/finding-policy.ts`, which must stay threshold-free: its
+ * other caller (`mode=full`) has no severity axis at all.
+ */
+severity) {
+    const started = Date.now();
+    try {
+        const result = applyLspFindingPolicy(diagnostics, {
+            cwd,
+            filePath: file,
+            content,
+            policyMap: loadProjectRulePolicyMap(cwd),
+            fileRole: detectFileRole(file, content),
+        });
+        const inScopeBefore = applySeverityFilter(diagnostics, severity).length;
+        const suppressed = inScopeBefore - applySeverityFilter(result.kept, severity).length;
+        if (suppressed > 0) {
+            // One record per FILE that actually dropped something the caller would
+            // otherwise have SEEN, never one per finding (AGENTS.md "bounded
+            // observability"). `total` is the in-scope population for the same
+            // reason the count is, so the record and the rendered line agree.
+            logLatency({
+                type: "phase",
+                toolName: "lsp_diagnostics",
+                filePath: file,
+                phase: "lsp_probe_disposition_filter",
+                durationMs: Date.now() - started,
+                metadata: {
+                    suppressed,
+                    total: inScopeBefore,
+                },
+            });
+        }
+        return { kept: result.kept, inlineKept: result.inlineKept, suppressed };
+    }
+    catch (err) {
+        recordDegradationOnce({
+            kind: "lsp-probe-finding-policy",
+            subject: cwd,
+            reason: err instanceof Error ? err.message : String(err),
+        });
+        return { kept: diagnostics, inlineKept: diagnostics, suppressed: 0 };
+    }
+}
+/**
+ * #3088 AC5/AC7: the content a cache REPLAY needs to evaluate STRICT
+ * (`false-positive`) disposition anchors, which hash the finding's own line.
+ * A cache hit means the file is unchanged since the entry was recorded, so this
+ * is the same content the recording touch read — but it is a disk read the
+ * replay path exists to avoid, so it is paid ONLY when the store actually holds
+ * a strict mark. With no marks (the overwhelmingly common case) the probe path
+ * adds zero I/O and the weak-anchored marks apply without content at all.
+ */
+function replayContentForStrictMarks(file, cwd) {
+    if (!hasStrictDispositionMarks(cwd))
+        return undefined;
+    try {
+        return fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        // Fail open — an unreadable file degrades to the weak-anchored filter
+        // rather than hiding or dropping anything.
+        return undefined;
+    }
+}
 function reconcileWidgetFromLspResult(file, rawDiags, confirmation, writeIndex, cwd, content, 
 // #1095: true when the result's content binding demonstrably mismatches disk
 // (boundToCurrentDisk === false). Such a result — even a NON-EMPTY one, which
@@ -670,7 +742,13 @@ onConfirmedNoBlockers) {
             // fresh touch does, so it gets the same demotion. Without this, replaying
             // yesterday's cached blocker would re-cement an orphan file as blocking
             // after mode=full had demoted it.
-            const cachedDiags = await demoteInferredForFile(file, cached.diagnostics, cwd, lspService);
+            const demotedCached = await demoteInferredForFile(file, cached.diagnostics, cwd, lspService);
+            // #3088 AC5: a replay is served to the agent exactly like a fresh
+            // observation, so it passes the same filter. The cached set is already
+            // inline-suppression-clean (the record below stores `inlineKept`), so
+            // only the revocable store/config filters run here.
+            const cachedPolicy = applyProbeFindingPolicy(file, demotedCached, cwd, replayContentForStrictMarks(file, cwd), severity);
+            const cachedDiags = cachedPolicy.kept;
             const filteredDiags = applySeverityFilter(cachedDiags, severity);
             // #692: cached.diagnostics were already suppression-/skipTestFiles-
             // filtered at write time (this same code path); no file content was
@@ -691,10 +769,13 @@ onConfirmedNoBlockers) {
                 diagnostics: diagnosticsToFileDiags(file, filteredDiags),
                 confirmation,
                 primaryServerId: primaryServerId(file),
+                ...(cachedPolicy.suppressed > 0 && {
+                    dispositionSuppressed: cachedPolicy.suppressed,
+                }),
             };
         }
     }
-    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(file, lspService, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(file, lspService, cwd, waitMs, serverScope);
     const health = lspService.getDiagnosticsHealth?.(file);
     // #570: a timed-out priming check is never a confirmed "clean" — treat it
     // as unconfirmed without consulting the (unrelated) silent-tier
@@ -753,6 +834,9 @@ onConfirmedNoBlockers) {
     }
     // #1645 review F3: one demotion rule for every writer of the widget store.
     effectiveRawDiags = await demoteInferredForFile(file, effectiveRawDiags, cwd, lspService);
+    // #3088: one filter for the output, the counts and the footer reconcile.
+    const policy = applyProbeFindingPolicy(file, effectiveRawDiags, cwd, collectedContent, severity);
+    effectiveRawDiags = policy.kept;
     const filteredDiags = applySeverityFilter(effectiveRawDiags, severity);
     const verdict = reconcileWidgetFromLspResult(file, effectiveRawDiags, confirmation, writeIndex, cwd, collectedContent, boundMismatch);
     if (verdict.confirmed && !verdict.blocking) {
@@ -775,7 +859,14 @@ onConfirmedNoBlockers) {
         confirmation !== "unconfirmed" &&
         diagnosticsUnsupportedServerIds.length === 0 &&
         unconfirmedServerIds.length === 0) {
-        cacheCtx.record(file, scopeKey, effectiveRawDiags, stat.mtimeMs, collectedContent !== undefined
+        // #3088: the entry records the INLINE-suppressed set, never the
+        // disposition/rule-policy-filtered one. An inline `pi-lens-ignore` comment
+        // cannot change without invalidating this content-keyed entry, so baking it
+        // in is safe and makes every later replay consistent with a fresh probe; a
+        // disposition mark or a `.pi-lens.json` rule can be revoked at any moment,
+        // so caching THEIR effect would keep a finding hidden after its mark was
+        // removed. The replay branch above re-applies those two on every serve.
+        cacheCtx.record(file, scopeKey, policy.inlineKept, stat.mtimeMs, collectedContent !== undefined
             ? hashDiagnosticContent(collectedContent)
             : undefined, stat.size);
     }
@@ -788,6 +879,9 @@ onConfirmedNoBlockers) {
         ...(skipReason !== undefined && { skipReason }),
         primaryServerId: primaryServerId(file),
         diagnosticsUnsupported: diagnosticsUnsupportedServerIds.length > 0,
+        ...(policy.suppressed > 0 && {
+            dispositionSuppressed: policy.suppressed,
+        }),
     };
 }
 async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWriteIndex, serverScope = "all", cwd = process.cwd(), 
@@ -797,7 +891,7 @@ onConfirmedNoBlockers) {
     // Reserve the token before awaiting this file's LSP result. The direct-file
     // path performs its own confirmation/reconciliation below (#1198).
     const writeIndex = nextWriteIndex?.();
-    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(absPath, lspService, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, diagnosticsUnsupportedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(absPath, lspService, cwd, waitMs, serverScope);
     const lspHealth = lspService.getDiagnosticsHealth?.(absPath);
     const unavailable = lspUnavailableMessage(absPath, lspHealth);
     // #533: an empty result needs a confirmed/unconfirmed verdict — a push-only,
@@ -857,6 +951,9 @@ onConfirmedNoBlockers) {
         confirmation = "unconfirmed";
     // #1645 review F3: one demotion rule for every writer of the widget store.
     effectiveRawDiags = await demoteInferredForFile(absPath, effectiveRawDiags, cwd, lspService);
+    // #3088: one filter for the output, the counts and the footer reconcile.
+    const policy = applyProbeFindingPolicy(absPath, effectiveRawDiags, cwd, collectedContent, severity);
+    effectiveRawDiags = policy.kept;
     const filtered = applySeverityFilter(effectiveRawDiags, severity);
     const total = filtered.length;
     const truncated = total > MAX_DIAGNOSTICS;
@@ -912,6 +1009,10 @@ onConfirmedNoBlockers) {
     const coverageLine = unconfirmedServerIds.length > 0
         ? `Auxiliary coverage INCOMPLETE — ${[...unconfirmedServerIds].join(", ")} did not answer within the wait budget, so ${unconfirmedServerIds.length === 1 ? "its findings are" : "their findings are"} NOT included here. This is not a clean bill of health for ${unconfirmedServerIds.length === 1 ? "that scanner" : "those scanners"}; re-check after the next edit. waitMs can extend an ordinary wait, but it cannot override a session-demoted scanner.`
         : undefined;
+    // #3088: the #1616 suppressed-bucket rule on this lane — a policy drop is
+    // stated as a count, never left to read as "nothing was wrong here"
+    // (AGENTS.md shape 10). Bounded: one line per call, whatever the count.
+    const suppressedLine = dispositionSuppressedLine(policy.suppressed);
     let text;
     if (total === 0) {
         text = [
@@ -919,6 +1020,7 @@ onConfirmedNoBlockers) {
             "",
             unavailable ?? "No auxiliary findings.",
             ...(coverageLine ? [coverageLine] : []),
+            ...(suppressedLine ? [suppressedLine] : []),
         ].join("\n");
     }
     else {
@@ -932,6 +1034,8 @@ onConfirmedNoBlockers) {
         }
         if (coverageLine)
             lines.push("", coverageLine);
+        if (suppressedLine)
+            lines.push("", suppressedLine);
         if (unavailable)
             lines.unshift(unavailable, "");
         if (truncated) {
@@ -958,6 +1062,9 @@ onConfirmedNoBlockers) {
                 code: d.code,
             })),
             totalDiagnostics: total,
+            ...(policy.suppressed > 0 && {
+                dispositionSuppressed: policy.suppressed,
+            }),
             truncated,
             unconfirmed,
             timedOut: unconfirmed ? timedOut : undefined,
@@ -1083,32 +1190,67 @@ async function collectBatchDiagnostics(files, severity, lspService, options) {
     const resolvedCwd = options.cwd ?? process.cwd();
     const cacheCtx = createWorkspaceDiagnosticsCacheContext(resolvedCwd);
     const scopeKey = buildScopeKey(options.serverScope ?? "all");
-    const results = await mapWithConcurrency(files, options.concurrency, async (file) => {
-        const work = collectFileDiagnosticResult(file, severity, lspService, options.waitMs, options.nextWriteIndex, options.serverScope, cacheCtx, scopeKey, resolvedCwd, options.onConfirmedNoBlockers);
-        const bounded = withDeadline(work, {
-            ms: batchFileDeadlineMs(),
-            onTimeout: "undefined",
-            onReject: "undefined",
-        });
-        const result = options.signal
-            ? await Promise.race([
-                bounded,
-                new Promise((resolve) => {
-                    if (options.signal?.aborted) {
-                        resolve(undefined);
-                        return;
-                    }
-                    options.signal?.addEventListener("abort", () => resolve(undefined), {
-                        once: true,
-                    });
-                }),
-            ])
-            : await bounded;
-        return (result ??
-            inconclusiveBatchResult(file, options.signal?.aborted
-                ? "Batch aborted before this file completed."
-                : `File check exceeded ${batchFileDeadlineMs()}ms.`));
-    }, lspService, options.signal, options.onProgress);
+    const resultsByIndex = new Map();
+    let completed = 0;
+    const pendingIndices = new Map();
+    files.forEach((file, index) => {
+        const queue = pendingIndices.get(file);
+        if (queue)
+            queue.push(index);
+        else
+            pendingIndices.set(file, [index]);
+    });
+    const groups = groupFilesByPrimaryServer(files);
+    await runPerServerGroups(groups, options.concurrency, async (group) => {
+        if (options.signal?.aborted)
+            return;
+        const first = group.files[0];
+        if (first &&
+            lspService &&
+            !isWarmAttached() &&
+            typeof lspService.ensureWarmForSweep === "function") {
+            await lspService.ensureWarmForSweep(first, {
+                signal: options.signal,
+            });
+            if (options.signal?.aborted)
+                return;
+        }
+        await mapWithConcurrency(group.files, 1, async (file) => {
+            // Keep duplicate explicit paths in their original result slots.
+            const index = pendingIndices.get(file).shift();
+            const work = collectFileDiagnosticResult(file, severity, lspService, options.waitMs, options.nextWriteIndex, options.serverScope, cacheCtx, scopeKey, resolvedCwd, options.onConfirmedNoBlockers);
+            const bounded = withDeadline(work, {
+                ms: batchFileDeadlineMs(),
+                onTimeout: "undefined",
+                onReject: "undefined",
+            });
+            const result = options.signal
+                ? await Promise.race([
+                    bounded,
+                    new Promise((resolve) => {
+                        if (options.signal?.aborted) {
+                            resolve(undefined);
+                            return;
+                        }
+                        options.signal?.addEventListener("abort", () => resolve(undefined), {
+                            once: true,
+                        });
+                    }),
+                ])
+                : await bounded;
+            resultsByIndex.set(index, result ??
+                inconclusiveBatchResult(file, options.signal?.aborted
+                    ? "Batch aborted before this file completed."
+                    : `File check exceeded ${batchFileDeadlineMs()}ms.`));
+            completed += 1;
+            options.onProgress?.(completed, files.length);
+        }, options.signal);
+    }, options.signal);
+    // The retired local pool returned only slots whose mapper had run. Keep that
+    // dense abort contract while restoring the original file order for callers.
+    const results = [...resultsByIndex.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([, result]) => result);
     // Persist whatever was recorded, including a partial/aborted sweep's
     // already-completed files — same "don't throw away confirmed work"
     // posture as `runWorkspaceDiagnostics`.
@@ -1167,6 +1309,9 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
     }
     const { results, fileErrors, lspHealthWarnings, total, truncated, display, primaryDisplay, auxiliaryDisplay, clean, unconfirmed, timedOut, outcomeCounts, incompleteFiles, } = await collectBatchDiagnostics(absPaths, severity, lspService, options);
     const navigationOnly = results.filter((result) => result.diagnosticsUnsupported).length;
+    // #3088: the batch's own suppressed bucket — one summed line, never one per
+    // file or per finding.
+    const dispositionSuppressed = results.reduce((sum, result) => sum + (result.dispositionSuppressed ?? 0), 0);
     const lines = [
         `Files checked: ${results.length}`,
         `Total diagnostics: ${total}`,
@@ -1221,6 +1366,9 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
             lines.push("", `... (${total - MAX_DIAGNOSTICS} more diagnostics not shown)`);
         }
     }
+    const suppressedLine = dispositionSuppressedLine(dispositionSuppressed);
+    if (suppressedLine)
+        lines.push("", suppressedLine);
     return {
         content: [{ type: "text", text: lines.join("\n") }],
         details: {
@@ -1234,6 +1382,7 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
             primaryDiagnosticsCount: primaryDisplay.length,
             auxiliaryDiagnosticsCount: auxiliaryDisplay.length,
             totalDiagnostics: total,
+            ...(dispositionSuppressed > 0 && { dispositionSuppressed }),
             truncated,
             cleanFiles: clean,
             unconfirmedFiles: unconfirmed,
@@ -1308,6 +1457,9 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
     const filesToProcess = collectedFiles.slice(0, MAX_FILES);
     const { results, fileErrors, lspHealthWarnings, total, truncated, display, primaryDisplay, auxiliaryDisplay, clean, unconfirmed, timedOut, } = await collectBatchDiagnostics(filesToProcess, severity, lspService, options);
     const navigationOnly = results.filter((result) => result.diagnosticsUnsupported).length;
+    // #3088: the directory scan's own suppressed bucket — one summed line.
+    const dispositionSuppressed = results.reduce((sum, result) => sum + (result.dispositionSuppressed ?? 0), 0);
+    const suppressedLine = dispositionSuppressedLine(dispositionSuppressed);
     let text;
     if (total === 0) {
         // #533/#570: an unconfirmed-containing directory result must never
@@ -1326,6 +1478,7 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
                     ...lspHealthWarnings.slice(0, 10),
                 ]
                 : [cleanLine]),
+            ...(suppressedLine ? ["", suppressedLine] : []),
         ].join("\n");
     }
     else {
@@ -1365,6 +1518,8 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
         if (truncated) {
             lines.push("", `... (${total - MAX_DIAGNOSTICS} more diagnostics not shown)`);
         }
+        if (suppressedLine)
+            lines.push("", suppressedLine);
         text = lines.join("\n");
     }
     return {
@@ -1388,6 +1543,7 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
             primaryDiagnosticsCount: primaryDisplay.length,
             auxiliaryDiagnosticsCount: auxiliaryDisplay.length,
             totalDiagnostics: total,
+            ...(dispositionSuppressed > 0 && { dispositionSuppressed }),
             truncated,
             cleanFiles: clean,
             unconfirmedFiles: unconfirmed,
@@ -1401,6 +1557,22 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
     };
 }
 // ── helpers ─────────────────────────────────────────────────────────────
+/**
+ * #3088: the one rendering of the probe lane's policy drop, shared by the
+ * single-file, batch and directory renders so the three cannot word the same
+ * fact differently. Returns `undefined` when nothing was dropped — the #1616
+ * rule asks for a count when there IS one, not a "0 suppressed" line on every
+ * clean probe.
+ */
+function dispositionSuppressedLine(suppressed) {
+    if (suppressed <= 0)
+        return undefined;
+    return (`suppressed by disposition: ${suppressed} finding(s) dropped from this ` +
+        "result because they're marked false-positive/won't-fix, disabled by " +
+        "`.pi-lens.json` rule policy, or suppressed by an inline `pi-lens-ignore` " +
+        "comment. Not a clean verdict for those locations — they were found, " +
+        "then intentionally hidden.");
+}
 function applySeverityFilter(diags, severity) {
     if (severity === "all")
         return diags;

package/node_modules/pi-lens/docs/audit1.md

@@ -38,16 +38,16 @@ This document records structural inconsistencies and centralization gaps found w
 
 ---
 
-### 3. Tree-sitter query loader uses a hand-rolled YAML parser
+### 3. Tree-sitter query loader uses a hand-rolled YAML parser (partially resolved)
 
 **Files:**
-- `clients/tree-sitter-query-loader.ts` — `parseYaml()` and `extractMultilineValue()` are custom
+- `clients/tree-sitter-query-loader.ts` — `parseYaml()` now calls `yaml.load` directly (refs #3054); the hand-rolled scanner and `extractMultilineValue()` are deleted.
 - `clients/dispatch/runners/yaml-rule-parser.ts` — uses `js-yaml` for ast-grep rules
-- `scripts/validate-rule-catalog.mjs` — uses regex to scrape YAML scalars
+- `scripts/validate-rule-catalog.mjs` — still uses regex to scrape YAML scalars (unchanged by #3054; out of that PR's scope)
 
-**Impact:** The tree-sitter loader does not support multiple YAML documents per file, complex nested objects, or arrays the way `js-yaml` does. A contributor writing a tree-sitter rule with richer metadata may hit silent parse failures. The three rule loaders do not share code, so fixes and behavior diverge.
+**Impact:** `scripts/validate-rule-catalog.mjs` remains its own regex-based reader, so the tree-sitter and ast-grep rule catalogs now share one parser (`js-yaml`) while the validation script is a third, still-divergent implementation.
 
-**Recommended fix:** Replace the hand-rolled parser in `tree-sitter-query-loader.ts` with `js-yaml` (already a runtime dependency), or reuse `parseSimpleYaml` from `yaml-rule-parser.ts`.
+**Recommended fix:** Fold `scripts/validate-rule-catalog.mjs`'s scraping onto `js-yaml` too, the same shape #3054 applied to the query loader.
 
 ---
 

package/node_modules/pi-lens/docs/dependencies.md

@@ -52,3 +52,14 @@ Auto-install behavior depends on gate type:
 | `psscriptanalyzer`                  | PowerShell linting               | Manual         | —                                  |
 
 Additional language servers (gopls, ruby-lsp, solargraph, etc.) are auto-detected from PATH or installed via native package managers (`go install`, `gem install`) when their language is detected.
+
+## Pip tool installation order
+
+For pip-backed tools, pi-lens uses this order:
+
+1. Use `pipx install` when `pipx` is available.
+2. Create or reuse `<PI_LENS_HOME>/pip-tools` with `python3 -m venv`, then use that venv's `pip`.
+3. Use `pip install --user` when the interpreter accepts a normal user install.
+4. If PEP 668 refuses the user install, use `--user --break-system-packages` only with `PYTHONUSERBASE` set to the pi-lens-private `<PI_LENS_HOME>/pip-user` prefix.
+
+Pi-lens never passes `--break-system-packages` to a system prefix. It adds the selected pipx, venv, or private-prefix `bin`/`Scripts` directory to the current process path so the availability probe resolves the installed tool.

package/node_modules/pi-lens/docs/dispositions.md

@@ -52,6 +52,58 @@ per-disposition binding strength:
   edits to the line and drift elsewhere in the file. (`suppress` is enforced
   by the inline comment anyway; the store entry is an audit mirror.)
 
+Both anchors also hash the producing `tool`, so a finding that changes hands
+between tools gets a fresh anchor. One such change shipped in #3041: `mode:
+"full"` used to render auxiliary-scanner findings (ast-grep, opengrep, zizmor,
+typos) under the generic `tool: "lsp"` while every other surface already showed
+them under their real tool id. It now shows the real id everywhere, so a mark
+recorded against the old `lsp`-labelled copy no longer matches and the finding
+gets one fresh chance to be re-marked — under the same `tool` the per-edit path
+has always used.
+
+## Which surfaces honor a mark
+
+Every model-facing surface that renders a diagnostic applies the same filter
+stack, in the same order: inline `pi-lens-ignore` comments, then the stored
+dispositions, then the project's `.pi-lens.json` `rules.<id>.disable`/`select`
+policy (`clients/dispatch/finding-policy.ts`). That covers the per-edit
+feedback, `lens_diagnostics` `mode=delta`/`mode=all`/`mode=full`, and — since
+#3088 — the `lens_diagnostics` `source=lsp` probe lane together with the legacy
+`lsp_diagnostics` tool and the MCP `pilens_lsp_diagnostics` shim that share it.
+Since #3102 it also covers the two PUSH surfaces that were still unfiltered:
+the turn-end **late-auxiliary advisory** (findings an auxiliary LSP published
+after its grace window, drained at the next `turn_end`) and the **cold-neighbour
+cascade run** (`buildResolvedFoundCascadeRun`, built in the quiet-window
+reconcile). Both are pushed rather than asked for, so when a mark suppresses
+everything they had to say they say nothing at all — silence on a push surface
+is not a claim that the file is clean, and the drop count is recorded in the
+lane's own `late_auxiliary_findings` / `cascade_finding_policy` latency row. A
+delivery that still has something to say states what it dropped inline.
+
+Before #3088 the probe lane was the one exception: it returned the raw LSP
+result, so a finding marked `false-positive` stayed hidden in `delta`/`full`
+and re-appeared on every probe — the lane
+`skills/pi-lens-lsp-navigation` steers agents to as PRIMARY. It now filters
+like every other surface, its footer reconcile writes the FILTERED set (so a
+probe can no longer re-arm a finding the mark demoted), and a drop is always
+stated as a count:
+
+```text
+suppressed by disposition: 1 finding(s) dropped from this result …
+```
+
+Two properties of the probe lane are worth knowing:
+
+- **A mark converges whichever surface you made it from.** The probe renders a
+  finding as `[<source>] (<code>)` while the widget footer and `mode=full`
+  render the canonical `tool: "lsp"` / `rule: "<source>:<code>"`, and `tool` is
+  optional on the mark tool. The probe filter matches every one of those
+  spellings, so a mark made from the probe's own output works, and so does one
+  made from any other surface.
+- **A blocking finding still needs a strict mark.** `semantic: "blocking"`
+  findings are dropped only by a content-bound `false-positive` match, never by
+  a weak `suppress`/`defer` — on this lane too (#1625 F1).
+
 ## Suppression comments
 
 `suppress` writes a pi-lens-owned ignore comment on the line immediately

package/node_modules/pi-lens/docs/environment-variables.md

@@ -47,9 +47,9 @@ review-graph, install-choices, etc.).
 
 **Default resolution order:**
 
-1. `$PILENS_DATA_DIR/<sanitized-cwd-slug>/` (if `PILENS_DATA_DIR` is set)
+1. `$PILENS_DATA_DIR/<sanitized-cwd-slug>-<8-hex-hash>/` (if `PILENS_DATA_DIR` is set)
 2. `<cwd>/.pi-lens/` (legacy — only if it already exists in the project)
-3. `~/.pi-lens/projects/<sanitized-cwd-slug>/` (current default)
+3. `~/.pi-lens/projects/<sanitized-cwd-slug>-<8-hex-hash>/` (current default)
 
 **When to set it:** running pi with a local model server (llama.cpp,
 Ollama, etc.) that monitors the project directory — cache-file churn

package/node_modules/pi-lens/docs/features.md

@@ -2,7 +2,7 @@
 
 ### LSP Support
 
-pi-lens includes **45 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server is not installed, pi-lens offers an interactive install prompt.
+pi-lens includes **46 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server is not installed, pi-lens offers an interactive install prompt.
 
 **LSP Idle Management:** LSP servers shut down after 240 seconds of inactivity (no files modified) to free resources. The timer resets when you resume editing, preventing cold-start penalties during active development.
 
@@ -19,13 +19,13 @@ pi-lens includes **45 language server definitions** (including four cross-cuttin
 - **`capabilities`** — shows which operations are supported by the active LSP server(s) for a file, read directly from the cached `initialize` response (no round-trip).
 - **Symbol column resolution** — passing `symbol: "myFunc"` instead of an exact `character` position resolves the correct column automatically. Use `symbol: "foo#2"` for the second occurrence of `foo` on the line.
 
-LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
+LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Typst (tinymist), Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
 
 ### Formatters
 
-pi-lens auto-detects and runs **34 formatters** based on project config:
+pi-lens auto-detects and runs **35 formatters** based on project config:
 
-biome, prettier, oxfmt, ruff, black, sqlfluff, gofmt, rustfmt, zig fmt, dart format, shfmt, nixfmt, mix format, ocamlformat, clang-format, ktlint, ktfmt, rubocop, standardrb, gleam format, terraform fmt, terragrunt-hcl, php-cs-fixer, csharpier, fantomas, swiftformat, stylua, ormolu, taplo, google-java-format, cljfmt, cmake-format, cue fmt, psscriptanalyzer-format
+biome, prettier, oxfmt, ruff, black, sqlfluff, gofmt, rustfmt, zig fmt, dart format, shfmt, nixfmt, mix format, ocamlformat, clang-format, ktlint, ktfmt, rubocop, standardrb, gleam format, typstyle, terraform fmt, terragrunt-hcl, php-cs-fixer, csharpier, fantomas, swiftformat, stylua, ormolu, taplo, google-java-format, cljfmt, cmake-format, cue fmt, psscriptanalyzer-format
 
 Detection rules: