pi-lens 3.8.66 → 3.8.67

package/CHANGELOG.md

@@ -10,6 +10,31 @@ All notable changes to pi-lens will be documented in this file.
 
 ### Fixed
 
+## [3.8.67] - 2026-07-09
+
+### Added
+
+- nightly clean-signal probe: probe-clean-signal.mjs generalized per-server (Tier 2 publishes-empty vs Tier 3 silent-on-clean among push LSPs) and wired into the tool-smoke nightly so the capability matrix's clean-behavior column self-populates (#460). The probe is phase-aware (dirty touch proves liveness; clean transitions are the discriminator) and classifies 4-way: `publishes-versioned` (tier 2 — affirmative + currency-proven, ast-grep), `publishes-unversioned` (tier 2\* — a version-less publish still early-returns the wait at runtime since the client accepts it as fresh, but currency is only temporally correlated: a staleness-risk note, not a latency cost — opengrep, yaml), `silent` (tier 3 — alive on dirty, silent on clean: the budget-wait case and #458's learned-deadline target set — typescript on a clean file), and `unknown` (no publish — conservatively unclassified). Clean fixtures (`typescript-clean`) are authoritative for a lang's row: typescript measurably re-publishes while dirty but goes silent once clean, so the dirty-fixture 2\* is overridden by the clean fixture's tier 3.
+- nightly LSP-docs commit-back (#390): the tool-smoke nightly now also runs `server-capabilities.mjs` (regenerating `docs/servercapabilities.md` incl. the ws-pull column) and opens/updates a single auto-PR (`bot/lsp-docs-refresh`) with the regenerated `lsp-capability-matrix.md` + `servercapabilities.md` — previously these were generated in CI then discarded. All three generators now **merge** into their docs (keyed by lang/server), so a server the ubuntu host can't spawn keeps its prior dev-box row and the nightly can never regress a richer run. The phase-aware probe refined opengrep's hand-noted Tier 2 to 2\* (re-publishes on clean scans, so the wait early-returns — but version-lessly, so currency is unproven).
+- **`serverOverrides` — per-server `initializationOptions` in project config** (#434) — `.pi-lens/lsp.json` (or `.pi-lens.json` / `pi-lsp.json`) accepts a `serverOverrides` key mapping a built-in server `id` (`"rust"`, `"nix"`, …) to an `initializationOptions` object that is deep-merged onto the server's built-in defaults at spawn time (user wins on conflicts; arrays replaced, not merged). Brings pi-lens diagnostics in line with a user's editor LSP setup (e.g. rust-analyzer `check.command: "clippy"`, nixd options expressions) without forking. Contributed by @vkarasen.
+- `lens_diagnostics` (and MCP `pilens_diagnostics`) accept `paths` to scope any mode to an explicit file/directory list — enables wrappers like "check exactly the git-staged files" (#461).
+
+### Changed
+
+- perf: cascade diagnostics now run concurrently after each edit instead of blocking the write pipeline (~26% median per-edit latency reduction); settled at turn_end with a bounded wait (#450)
+- perf: write-path micro batch — ESLint autofix runs a single `--fix` spawn (was dry-run + fix, double cold-start), LSP quick-fix lookups for blocking diagnostics run in parallel, and the lsp runner reuses its already-read file content for nosemgrep suppression (#453)
+- perf/refactor: the eight NDJSON debug loggers (latency, cascade, read-guard, tree-sitter, dead-code, actionable-warnings, ast-grep-tool, diagnostic) now share one buffered async writer (clients/ndjson-logger.ts) — no more synchronous appendFileSync on the per-edit hot path; best-effort sync flush at process exit (#454)
+- perf: the review-graph freshness check now uses RuntimeCoordinator sequence state to skip the per-build O(project) walk+stat sweep when only pi-observed edits occurred (seq fast path; periodic full re-verify every 20 builds/5 min catches external changes; PI_LENS_GRAPH_SEQ_FASTPATH=0 disables) (#451)
+- perf: skip the reverse-dependency index rebuild (O(graph edges)) and its project-snapshot disk write on cascade runs where the review graph didn't actually change — the index is a pure function of the graph, so a cache-hit graph build (or a seq-fastpath build that found nothing graph-relevant to re-parse) now reuses the last-built index instead of redoing both. Freshness keys on a new `ReviewGraph.buildGeneration` stamp that travels with the returned graph instance (`mode` alone can't distinguish a true seq-fastpath no-op from one that re-parsed files, and the global build-info slot can be clobbered by overlapping deferred cascades); per-workspace cache, `PI_LENS_REVERSE_DEPS_REUSE=0` disables (#459)
+
+### Fixed
+
+- **`no-init-return` no longer flags factory functions** (#439) — the ast-grep rule matched `return` inside any `function_definition` whose *body text* regex-contained `def __init__`, so a factory that returns a class with an `__init__` (and its sibling methods' returns) tripped it. It now matches a `function_definition` whose **name field** is `__init__` (`has: field: name`), so only real `__init__` returns are flagged. Regression fixtures added (factory + sibling-method cases).
+- **`python-assert-production` no longer fires in test files** (#440) — `assert` is the idiomatic test assertion, so flagging every `assert` in `tests/**` was pure noise that trained users to ignore the rule. Tree-sitter rules gain an opt-in `skip_test_files` field (the runner otherwise runs on test files, since structural issues matter there); `python-assert-production` sets it, so production `assert` (the `-O` strip risk) is still flagged while test asserts are skipped. Exercised through the real runner (prod fires, `tests/` skips).
+- **The opengrep/Semgrep runner now honors `# nosemgrep` suppression** (#441) — the canonical Semgrep inline suppression (`# nosemgrep` and `# nosemgrep: <rule-id>[,<rule-id>]`, also `//`) was ignored, leaving only `.pi-lens.json` path globs or code restructuring as escapes. The auxiliary-LSP runner now drops opengrep findings suppressed by a `nosemgrep` comment on the finding's own line (inline) or a standalone comment on the line above — matching Semgrep's placement semantics (an inline comment doesn't leak to the next line).
+- **`lens_diagnostics mode=full` now honors inline `# pi-lens-ignore` comments** (#442) — inline suppression (`// pi-lens-ignore: rule` / `# pi-lens-ignore: rule`) was applied only in the per-edit dispatch path (`mode=all`), so a site cleanly suppressed there reappeared as **blocking** in the project-wide `mode=full` sweep — making `mode=full` unusable as a "clean" gate for any project with a legitimate suppression. The suppression filter is now shared (`clients/dispatch/inline-suppressions.ts`) and applied to the merged `mode=full` summaries too: each flagged file is read and its inline ignores honored (fail-safe — a read error never hides a finding), and counts are re-summarized so a fully-suppressed file reports clean. Rule matching also normalizes `ast-grep:<id>` / `<id>-js` forms, so a bare `pi-lens-ignore: <id>` suppresses the finding in both modes. (The reporter's secondary ask — per-rule enable/disable in `.pi-lens.json` — is tracked separately as a follow-up.)
+- **The review-graph snapshot is now stamped with git HEAD + worktree root, and the read-substitute path drops it on mismatch** (#300) — `git worktree remove` followed by `add` at the same path for a different branch reuses the cwd-derived data-dir slug, so a `module_report`/blast-radius read fired before the first rebuild could return the previous branch's symbols/edges. The persisted snapshot now carries an optional git stamp (HEAD commit + worktree top-level path), resolved purely by reading `.git`/`HEAD`/`refs` files — no `git` subprocess, since the persist path includes the synchronous flush-on-exit handler and spawning at teardown crashes libuv on Windows (#234). The blind read path (`getCachedReviewGraph`, which trusts disk with no other verification) drops a stamped snapshot that mismatches the current repo; the build path deliberately keeps loading it unverified, because its signature/content-hash confirm (#202) already proves file-level freshness — so a plain `git commit` (HEAD moves, files unchanged) still cold-starts as a cheap "cached" reuse, never a full rebuild. An absent stamp (older snapshot, or a non-git cwd) behaves exactly as before. Separately, a cwd that isn't the git worktree top-level is now logged once per process (observability only, no hard-fail) — the review graph's cross-worktree isolation has always rested on that assumption, and it was previously invisible.
+
 ## [3.8.66] - 2026-07-07
 
 ### Added

package/README.md

@@ -57,7 +57,6 @@ pi-lens is released under the [MIT License](LICENSE).
 ## Contributors
 
 Thanks goes to these wonderful people:
-
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->

package/dist/clients/actionable-warnings-logger.js

@@ -1,51 +1,26 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
 const AW_LOG_DIR = getGlobalPiLensDir();
 const AW_LOG_FILE = path.join(AW_LOG_DIR, "actionable-warnings.log");
 const AW_LOG_BACKUP_FILE = path.join(AW_LOG_DIR, "actionable-warnings.log.1");
 const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_AW_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);
-try {
-    if (!fs.existsSync(AW_LOG_DIR)) {
-        fs.mkdirSync(AW_LOG_DIR, { recursive: true });
-    }
-}
-catch (err) {
-    void err;
-}
-function rotateIfNeeded() {
-    try {
-        if (!fs.existsSync(AW_LOG_FILE))
-            return;
-        const size = fs.statSync(AW_LOG_FILE).size;
-        if (size < MAX_LOG_BYTES)
-            return;
-        try {
-            fs.rmSync(AW_LOG_BACKUP_FILE, { force: true });
-        }
-        catch (err) {
-            void err;
-        }
-        fs.renameSync(AW_LOG_FILE, AW_LOG_BACKUP_FILE);
-    }
-    catch (err) {
-        void err;
-    }
-}
+const writer = createNdjsonLogger({
+    filePath: AW_LOG_FILE,
+    maxBytes: MAX_LOG_BYTES,
+    backupPath: AW_LOG_BACKUP_FILE,
+});
 export function logActionableWarningsEvent(entry) {
     if (isTestMode()) {
         return;
     }
-    const line = `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`;
-    try {
-        rotateIfNeeded();
-        fs.appendFileSync(AW_LOG_FILE, line);
-    }
-    catch (err) {
-        void err;
-    }
+    writer.log({ ts: new Date().toISOString(), ...entry });
 }
 export function getActionableWarningsLogPath() {
     return AW_LOG_FILE;
 }
+/** Resolve once all enqueued actionable-warnings writes are on disk. */
+export function flushActionableWarningsLog() {
+    return writer.flush();
+}

package/dist/clients/ast-grep-tool-logger.js

@@ -9,22 +9,19 @@
  *
  * Mirrors `actionable-warnings-logger.ts` for shape + rotation behaviour.
  */
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
 const AG_LOG_DIR = getGlobalPiLensDir();
 const AG_LOG_FILE = path.join(AG_LOG_DIR, "ast-grep-tools.log");
 const AG_LOG_BACKUP_FILE = path.join(AG_LOG_DIR, "ast-grep-tools.log.1");
 const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_AST_GREP_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);
-try {
-    if (!fs.existsSync(AG_LOG_DIR)) {
-        fs.mkdirSync(AG_LOG_DIR, { recursive: true });
-    }
-}
-catch (err) {
-    void err;
-}
+const writer = createNdjsonLogger({
+    filePath: AG_LOG_FILE,
+    maxBytes: MAX_LOG_BYTES,
+    backupPath: AG_LOG_BACKUP_FILE,
+});
 const PATTERN_TRUNCATE_AT = 500;
 const ERROR_TRUNCATE_AT = 300;
 function truncate(value, max) {
@@ -105,25 +102,6 @@ export function astGrepRemediationHint(kind) {
             return "Hint: verify the pattern is a single valid AST node for this `lang` (use ast_grep_dump to discover node kinds), or fall back to grep for plain-text search.";
     }
 }
-function rotateIfNeeded() {
-    try {
-        if (!fs.existsSync(AG_LOG_FILE))
-            return;
-        const size = fs.statSync(AG_LOG_FILE).size;
-        if (size < MAX_LOG_BYTES)
-            return;
-        try {
-            fs.rmSync(AG_LOG_BACKUP_FILE, { force: true });
-        }
-        catch (err) {
-            void err;
-        }
-        fs.renameSync(AG_LOG_FILE, AG_LOG_BACKUP_FILE);
-    }
-    catch (err) {
-        void err;
-    }
-}
 export function logAstGrepToolEvent(event) {
     if (isTestMode())
         return;
@@ -135,16 +113,13 @@ export function logAstGrepToolEvent(event) {
         rewriteLineCount: event.rewriteLineCount,
         errorRaw: truncate(event.errorRaw, ERROR_TRUNCATE_AT),
     };
-    const line = `${JSON.stringify({ ts: new Date().toISOString(), ...payload })}\n`;
-    try {
-        rotateIfNeeded();
-        fs.appendFileSync(AG_LOG_FILE, line);
-    }
-    catch (err) {
-        void err;
-    }
+    writer.log({ ts: new Date().toISOString(), ...payload });
 }
 export function getAstGrepToolLogPath() {
     return AG_LOG_FILE;
 }
+/** Resolve once all enqueued ast-grep-tool writes are on disk. */
+export function flushAstGrepToolLog() {
+    return writer.flush();
+}
 export { countLines as _countLinesForTest };

package/dist/clients/cascade-logger.js

@@ -1,25 +1,20 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
 const CASCADE_LOG_DIR = getGlobalPiLensDir();
 const CASCADE_LOG_FILE = path.join(CASCADE_LOG_DIR, "cascade.log");
-try {
-    if (!fs.existsSync(CASCADE_LOG_DIR)) {
-        fs.mkdirSync(CASCADE_LOG_DIR, { recursive: true });
-    }
-}
-catch { }
+const writer = createNdjsonLogger({ filePath: CASCADE_LOG_FILE });
 export function logCascade(entry) {
     if (isTestMode()) {
         return;
     }
-    const line = `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`;
-    try {
-        fs.appendFileSync(CASCADE_LOG_FILE, line);
-    }
-    catch { }
+    writer.log({ ts: new Date().toISOString(), ...entry });
 }
 export function getCascadeLogPath() {
     return CASCADE_LOG_FILE;
 }
+/** Resolve once all enqueued cascade writes are on disk (tests/shutdown). */
+export function flushCascadeLog() {
+    return writer.flush();
+}

package/dist/clients/dead-code-logger.js

@@ -5,26 +5,20 @@
  * input to phasing decisions in the issue). Mirrors `ast-grep-tool-logger.ts`
  * for shape + size-based rotation.
  */
-import * as fs from "node:fs";
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
 const LOG_DIR = getGlobalPiLensDir();
 const LOG_FILE = path.join(LOG_DIR, "dead-code.log");
 const LOG_BACKUP_FILE = path.join(LOG_DIR, "dead-code.log.1");
 const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_DEAD_CODE_LOG_MAX_BYTES ?? "1048576", 10) ||
     1048576);
-function rotateIfNeeded() {
-    try {
-        const stat = fs.statSync(LOG_FILE);
-        if (stat.size >= MAX_LOG_BYTES) {
-            fs.renameSync(LOG_FILE, LOG_BACKUP_FILE);
-        }
-    }
-    catch {
-        // no file yet, or rename raced — nothing to rotate
-    }
-}
+const writer = createNdjsonLogger({
+    filePath: LOG_FILE,
+    maxBytes: MAX_LOG_BYTES,
+    backupPath: LOG_BACKUP_FILE,
+});
 /**
  * Append one scan event. Fire-and-forget: telemetry must never break a scan, so
  * every fs error is swallowed. Skipped under test mode to keep the suite from
@@ -33,14 +27,9 @@ function rotateIfNeeded() {
 export function logDeadCodeScan(event) {
     if (isTestMode())
         return;
-    try {
-        if (!fs.existsSync(LOG_DIR))
-            fs.mkdirSync(LOG_DIR, { recursive: true });
-        rotateIfNeeded();
-        const row = JSON.stringify({ ts: new Date().toISOString(), ...event });
-        fs.appendFileSync(LOG_FILE, row + "\n");
-    }
-    catch {
-        // telemetry is best-effort
-    }
+    writer.log({ ts: new Date().toISOString(), ...event });
+}
+/** Resolve once all enqueued dead-code writes are on disk (tests/shutdown). */
+export function flushDeadCodeLog() {
+    return writer.flush();
 }

package/dist/clients/diagnostic-logger.js

@@ -3,17 +3,12 @@
  *
  * Log file: ~/.pi-lens/logs/{date}.jsonl
  */
-import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
+import { createNdjsonLogger } from "./ndjson-logger.js";
 function getLogDir() {
-    const home = os.homedir();
-    const logDir = path.join(home, ".pi-lens", "logs");
-    if (!fs.existsSync(logDir)) {
-        fs.mkdirSync(logDir, { recursive: true });
-    }
-    return logDir;
+    return path.join(os.homedir(), ".pi-lens", "logs");
 }
 function getLogFile() {
     const date = new Date().toISOString().split("T")[0];
@@ -28,30 +23,15 @@ export function getDiagnosticLogger() {
     return _logger;
 }
 export function createDiagnosticLogger() {
-    const pending = [];
-    let writing = false;
-    const writePending = async () => {
-        if (writing || pending.length === 0)
-            return;
-        writing = true;
-        const toWrite = pending.splice(0, pending.length);
-        const lines = toWrite.map((e) => JSON.stringify(e)).join("\n") + "\n";
-        try {
-            await fs.promises.appendFile(getLogFile(), lines);
-        }
-        catch (err) {
-            // pi-lens-ignore: missing-error-propagation — fire-and-forget log write, must not throw
-            console.error("Failed to write diagnostic log:", err);
-        }
-        writing = false;
-    };
+    // Lazy filePath: the log file is keyed on the current date, resolved per
+    // drain so a long-lived logger rolls over at midnight.
+    const writer = createNdjsonLogger({ filePath: () => getLogFile() });
     return {
         log(entry) {
             if (isTestMode()) {
                 return;
             }
-            pending.push(entry);
-            writePending(); // async, non-blocking
+            writer.log(entry); // async, non-blocking
         },
         logCaught(d, context, shownInline = false) {
             this.log({
@@ -77,11 +57,7 @@ export function createDiagnosticLogger() {
             });
         },
         async flush() {
-            // Drain any buffered entries, then wait for the write to finish.
-            await writePending();
-            while (writing) {
-                await new Promise((resolve) => setTimeout(resolve, 10));
-            }
+            await writer.flush();
         },
     };
 }

package/dist/clients/dispatch/auxiliary-lsp.js

@@ -20,6 +20,42 @@ import { findLocalOpengrepConfig } from "../opengrep-config.js";
 import { findLocalTyposConfig } from "../typos-config.js";
 import { findLocalZizmorConfig } from "../zizmor-config.js";
 import { classifyDefect } from "./diagnostic-taxonomy.js";
+/**
+ * Semgrep/opengrep `# nosemgrep` / `# nosemgrep: <rule-id>[,<rule-id>]` inline
+ * suppression (#441). A bare `# nosemgrep` drops every finding on its line; the
+ * `: <ids>` form drops only the listed rule ids. `d.code` is the semgrep rule id.
+ * Also accepts the `//` comment form.
+ *
+ * Matches Semgrep placement: honored on the finding's OWN line (inline or not),
+ * and on the line ABOVE only when that line is a STANDALONE comment (no code before
+ * it) — so `a()  # nosemgrep` suppresses a finding on `a()` but not the next line.
+ */
+const NOSEMGREP_RE = /(?:#|\/\/)\s*nosemgrep(?::\s*(.+))?/i;
+const NOSEMGREP_STANDALONE_RE = /^\s*(?:#|\/\/)\s*nosemgrep(?::\s*(.+))?\s*$/i;
+export function isNosemgrepSuppressed(d, content) {
+    const startLine = d.range?.start?.line; // 0-based
+    if (startLine == null)
+        return false;
+    const lines = content.split("\n");
+    const ruleId = String(d.code ?? "");
+    const checkLine = (text, standaloneOnly) => {
+        if (!text)
+            return false;
+        const m = (standaloneOnly ? NOSEMGREP_STANDALONE_RE : NOSEMGREP_RE).exec(text);
+        if (!m)
+            return false;
+        if (m[1] === undefined)
+            return true; // bare nosemgrep → suppress the line
+        return m[1]
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .includes(ruleId);
+    };
+    // The finding's own line (inline OK), then the line above (standalone comment only).
+    return (checkLine(lines[startLine], false) ||
+        checkLine(lines[startLine - 1], true));
+}
 export const AUXILIARY_LSP_PROFILES = [
     {
         serverId: "opengrep",
@@ -37,6 +73,8 @@ export const AUXILIARY_LSP_PROFILES = [
         allowBlocking: (cwd) => Boolean(findLocalOpengrepConfig(cwd)),
         semantic: (d, { blockingAllowed }) => blockingAllowed && d.severity === 1 ? "blocking" : "warning",
         defectClass: (d) => classifyDefect(String(d.code ?? ""), "opengrep", d.message ?? ""),
+        // Honor the canonical Semgrep suppression the user already knows (#441).
+        isSuppressed: isNosemgrepSuppressed,
     },
     {
         serverId: "ast-grep",

package/dist/clients/dispatch/dispatcher.js

@@ -27,6 +27,7 @@ import { loadPiLensProjectConfig } from "../project-lens-config.js";
 import { RUNTIME_CONFIG, getRunnerTimeoutFloorMs } from "../runtime-config.js";
 import { safeSpawnAsync } from "../safe-spawn.js";
 import { classifyDiagnostic } from "./diagnostic-taxonomy.js";
+import { applyInlineSuppressions } from "./inline-suppressions.js";
 import { getToolPlan } from "./plan.js";
 import { resolveRunnerPath } from "./runner-context.js";
 import { getToolProfile } from "./tool-profile.js";
@@ -187,42 +188,6 @@ function dedupeOverlappingDiagnostics(diagnostics) {
     }
     return [...byKey.values()];
 }
-/**
- * Apply inline suppression comments.
- * Syntax: `// pi-lens-ignore: rule-id` (JS/TS) or `# pi-lens-ignore: rule-id` (Python/Ruby/etc.)
- * Place on the same line as the diagnostic or the line immediately above it.
- */
-function applyInlineSuppressions(diagnostics, content) {
-    if (!content || !diagnostics.length)
-        return diagnostics;
-    // Build a set of (line, ruleId) pairs that are suppressed.
-    // Line numbers are 1-based to match diagnostic line numbers.
-    const suppressed = new Set();
-    const lines = content.split("\n");
-    const SUPPRESS_RE = /(?:\/\/|#)\s*pi-lens-ignore:\s*(.+)/;
-    for (let i = 0; i < lines.length; i++) {
-        const m = SUPPRESS_RE.exec(lines[i]);
-        if (!m)
-            continue;
-        const rules = m[1]
-            .split(",")
-            .map((r) => r.trim())
-            .filter(Boolean);
-        const suppressedLine = i + 1; // same line (1-based)
-        const nextLine = i + 2; // next line (1-based)
-        for (const ruleId of rules) {
-            suppressed.add(`${suppressedLine}:${ruleId}`);
-            suppressed.add(`${nextLine}:${ruleId}`);
-        }
-    }
-    if (suppressed.size === 0)
-        return diagnostics;
-    return diagnostics.filter((d) => {
-        const ruleId = d.rule ?? d.id ?? "";
-        const line = d.line ?? 1;
-        return !suppressed.has(`${line}:${ruleId}`);
-    });
-}
 function suppressLintOverlapsWithLsp(diagnostics) {
     const lspBySpanClass = new Set();
     const lspByLine = new Set();

package/dist/clients/dispatch/inline-suppressions.js

@@ -0,0 +1,61 @@
+/**
+ * Inline `pi-lens-ignore` suppression — shared between the per-edit dispatch
+ * pipeline (`lens_diagnostics mode=all`) and the project-wide `mode=full` sweep so
+ * BOTH honor the same comments (#442). Previously this lived privately in the
+ * dispatcher, so a site suppressed on the write path reappeared as blocking in the
+ * full scan, making `mode=full` unusable as a clean gate.
+ *
+ * Syntax: `// pi-lens-ignore: rule-id` (JS/TS) or `# pi-lens-ignore: rule-id`
+ * (Python/Ruby/…), comma-separated for multiple rules, on the same line as the
+ * diagnostic or the line immediately above it.
+ */
+const SUPPRESS_RE = /(?:\/\/|#)\s*pi-lens-ignore:\s*(.+)/;
+/**
+ * Normalize a rule id to the form a user writes in a `pi-lens-ignore` comment.
+ * The napi scan and the ast-grep LSP tag the same rule as `ast-grep:<id>` /
+ * `<id>-js` in some surfaces (see `normalizeRuleForDedup` in lens-diagnostics);
+ * a user's bare `<id>` must still suppress those, so we match the normalized form
+ * as well as the raw one.
+ */
+function normalizeSuppressRule(ruleId) {
+    return ruleId.replace(/^ast-grep:/, "").replace(/-js$/, "");
+}
+/**
+ * Drop diagnostics suppressed by an inline `pi-lens-ignore: <rule[,rule2]>`
+ * comment in `content` (the file the diagnostics belong to). A diagnostic is
+ * suppressed when its rule id — raw OR normalized — is listed on its own line or
+ * the line immediately above. Returns the surviving diagnostics (same array if
+ * nothing is suppressed).
+ */
+export function applyInlineSuppressions(diagnostics, content) {
+    if (!content || !diagnostics.length)
+        return diagnostics;
+    // Build the set of (1-based line, rule-id) pairs that are suppressed.
+    const suppressed = new Set();
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const m = SUPPRESS_RE.exec(lines[i]);
+        if (!m)
+            continue;
+        const rules = m[1]
+            .split(",")
+            .map((r) => r.trim())
+            .filter(Boolean);
+        const suppressedLine = i + 1; // same line (1-based)
+        const nextLine = i + 2; // next line (1-based)
+        for (const ruleId of rules) {
+            suppressed.add(`${suppressedLine}:${ruleId}`);
+            suppressed.add(`${nextLine}:${ruleId}`);
+        }
+    }
+    if (suppressed.size === 0)
+        return diagnostics;
+    return diagnostics.filter((d) => {
+        const rawId = d.rule ?? d.id ?? "";
+        const line = d.line ?? 1;
+        if (suppressed.has(`${line}:${rawId}`))
+            return false;
+        const normId = normalizeSuppressRule(rawId);
+        return normId === rawId || !suppressed.has(`${line}:${normId}`);
+    });
+}

package/dist/clients/dispatch/integration.js

@@ -292,6 +292,7 @@ export function resetDispatchBaselines(cwd) {
     resetSessionSlopScore();
     clearCoverageNoticeState();
     clearReviewGraphWorkspaceCache();
+    clearReverseDepsIndexCache();
     clearModuleGraphCache();
     neighborTouchCache.clear();
     recentlyCleanNeighborCache.clear();
@@ -337,6 +338,15 @@ function ensureCascadeTurnScope(turnSeq) {
 const CASCADE_TTL_MS = 240_000;
 const MAX_PER_FILE = RUNTIME_CONFIG.pipeline.cascadeMaxDiagnosticsPerFile;
 const MAX_FILES = RUNTIME_CONFIG.pipeline.cascadeMaxFiles;
+const reverseDepsIndexCache = new Map();
+function reverseDepsReuseEnabled() {
+    const raw = process.env.PI_LENS_REVERSE_DEPS_REUSE;
+    return raw !== "0" && raw !== "false";
+}
+/** Test-reset hook — mirrors clearReviewGraphWorkspaceCache's scope. */
+export function clearReverseDepsIndexCache() {
+    reverseDepsIndexCache.clear();
+}
 // Bounded transitive cascade (#162): expand neighbour derivation beyond the
 // one-hop importers/callers to depth-2 dependents, so an edit's blast radius
 // reaches indirect dependents — capped so the per-edit cost stays bounded. The
@@ -383,7 +393,7 @@ function isIgnoredCascadeNeighbor(filePath, cwd) {
     }
 }
 export async function computeCascadeForFile(filePath, cwd, options = {}) {
-    const { hasBlockers = false, dbg, turnSeq = 0, writeSeq } = options;
+    const { hasBlockers = false, dbg, turnSeq = 0, writeSeq, seqState } = options;
     ensureCascadeTurnScope(turnSeq);
     if (hasBlockers) {
         logCascade({
@@ -429,32 +439,71 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
     let referenceCount = 0;
     if (CASCADE_GRAPH_KINDS.has(fileKind)) {
         const graphStart = Date.now();
-        const graph = await buildOrUpdateGraph(cwd, [normalizedFile], sessionFacts);
+        const graph = await buildOrUpdateGraph(cwd, [normalizedFile], sessionFacts, seqState);
         const graphMs = Date.now() - graphStart;
-        const reverseDepsIndex = buildReverseDependencyIndexFromGraph({
-            cwd,
-            graph,
-        });
-        const reverseDepsSaved = writeReverseDependencyIndexToSnapshot({
-            cwd,
-            index: reverseDepsIndex,
-            dbg,
-        });
-        logCascade({
-            phase: "reverse_deps_cache",
-            filePath,
-            durationMs: Date.now() - graphStart,
-            metadata: {
-                action: "refresh_from_review_graph",
+        // #459: the reuse decision keys on graph.buildGeneration — a stamp that
+        // travels WITH the graph instance this cascade holds. Deliberately NOT the
+        // global last-build-info slot: post-#450 cascades overlap, and another
+        // cascade's cache-hit build can overwrite that slot (graphChanged:false)
+        // between this build mutating the graph and this read — which would turn a
+        // changed graph into a spurious reuse of a stale index that steady-state
+        // cache hits then never heal. Generation equality can't be clobbered into
+        // a false positive: a graph-mutating build always mints a new generation.
+        // An unstamped graph (mode "skipped") always rebuilds.
+        const graphBuildInfo = getLastGraphBuildInfo();
+        const workspaceKey = normalizeMapKey(cwd);
+        const cachedReverseDeps = reverseDepsIndexCache.get(workspaceKey);
+        const canReuse = reverseDepsReuseEnabled() &&
+            cachedReverseDeps !== undefined &&
+            graph.buildGeneration !== undefined &&
+            cachedReverseDeps.generation === graph.buildGeneration;
+        let reverseDepsIndex;
+        let reverseDepsSaved;
+        if (canReuse && cachedReverseDeps) {
+            reverseDepsIndex = cachedReverseDeps.index;
+            reverseDepsSaved = cachedReverseDeps.savedToSnapshot;
+            logCascade({
+                phase: "reverse_deps_cache",
+                filePath,
+                durationMs: Date.now() - graphStart,
+                metadata: {
+                    action: "reused_unchanged",
+                    savedToSnapshot: reverseDepsSaved,
+                    importsFileCount: Object.keys(reverseDepsIndex.imports).length,
+                    importedByFileCount: Object.keys(reverseDepsIndex.importedBy).length,
+                },
+            });
+        }
+        else {
+            reverseDepsIndex = buildReverseDependencyIndexFromGraph({
+                cwd,
+                graph,
+            });
+            reverseDepsSaved = writeReverseDependencyIndexToSnapshot({
+                cwd,
+                index: reverseDepsIndex,
+                dbg,
+            });
+            reverseDepsIndexCache.set(workspaceKey, {
+                index: reverseDepsIndex,
                 savedToSnapshot: reverseDepsSaved,
-                importsFileCount: Object.keys(reverseDepsIndex.imports).length,
-                importedByFileCount: Object.keys(reverseDepsIndex.importedBy).length,
-                importEdgeCount: Object.values(reverseDepsIndex.imports).reduce((total, imports) => total + imports.length, 0),
-            },
-        });
+                generation: graph.buildGeneration,
+            });
+            logCascade({
+                phase: "reverse_deps_cache",
+                filePath,
+                durationMs: Date.now() - graphStart,
+                metadata: {
+                    action: "refresh_from_review_graph",
+                    savedToSnapshot: reverseDepsSaved,
+                    importsFileCount: Object.keys(reverseDepsIndex.imports).length,
+                    importedByFileCount: Object.keys(reverseDepsIndex.importedBy).length,
+                    importEdgeCount: Object.values(reverseDepsIndex.imports).reduce((total, imports) => total + imports.length, 0),
+                },
+            });
+        }
         // Count files represented in the graph (nodes with a filePath).
         const graphFileCount = new Set([...graph.nodes.values()].flatMap((n) => n.filePath ? [n.filePath] : [])).size;
-        const graphBuildInfo = getLastGraphBuildInfo();
         logCascade({
             phase: "graph_build",
             filePath,
@@ -468,6 +517,9 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 skipReason: graphBuildInfo.skipReason,
                 sourceFileCount: graphBuildInfo.sourceFileCount,
                 maxFileCount: graphBuildInfo.maxFileCount,
+                // #451: when the seq fast path fell back (or was skipped), why — so
+                // cascade.log surfaces the fast-path hit/miss rate.
+                seqFastpathFallback: graphBuildInfo.seqFastpathFallback,
             },
         });
         impact = computeImpactCascade(graph, normalizedFile, cwd);