@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/dispatch/runners/rust-clippy.js

@@ -26,17 +26,22 @@ const rustClient = new RustClient();
 // The verdict is governed by the shared availability policy (#1494): a probe
 // timeout expires on a cooldown, so only a genuinely absent clippy latches.
 const CLIPPY_PROBE_BUDGET_MS = 8000;
-const makeClippyProbe = (cargoExe) => createCwdCachedProbe((cwd) => safeSpawnAsync(cargoExe, ["clippy", "--version"], {
+let clippyProbeRevision = 0;
+const makeClippyProbe = (cargoExe, flightKeyComponent = cargoExe) => createCwdCachedProbe((cwd) => safeSpawnAsync(cargoExe, ["clippy", "--version"], {
     timeout: CLIPPY_PROBE_BUDGET_MS,
     cwd,
-}), { tool: "clippy", budgetMs: CLIPPY_PROBE_BUDGET_MS });
+}), {
+    tool: "clippy",
+    budgetMs: CLIPPY_PROBE_BUDGET_MS,
+    flightKeyComponent,
+});
 const clippyAvailabilityByCargo = new Map();
 function getClippyProbe(cargoExe) {
     return (clippyAvailabilityByCargo.get(cargoExe) ?? refreshClippyProbe(cargoExe));
 }
 /** Replace the cached probe so a post-install state is observed. */
 function refreshClippyProbe(cargoExe) {
-    const created = makeClippyProbe(cargoExe);
+    const created = makeClippyProbe(cargoExe, `${cargoExe}#refresh-${++clippyProbeRevision}`);
     clippyAvailabilityByCargo.set(cargoExe, created);
     return created;
 }

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/runner-helpers.js

@@ -10,6 +10,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { logSessionStart } from "../../../sessionstart-logger.js";
+import { incrementDegradationCount } from "../../../degradation-ledger.js";
 import { getGlobalPiLensDir } from "../../../file-utils.js";
 import { createGenerationSource, } from "../../../generation-guard.js";
 import { PathKeyedMap } from "../../../path-keyed-map.js";
@@ -18,8 +19,10 @@ import { ensureTool, getInstallAttempt, getLastEnsureResolutionSource, getToolIn
 import { getServersForFileWithConfig, isServerDisabled, } from "../../../lsp/config.js";
 import { findGlobalBinary } from "../../../package-manager.js";
 import { safeSpawnAsync } from "../../../safe-spawn.js";
+import { compareOrdinal } from "../../../string-utils.js";
 import { getToolCommandSpec, shouldAutoInstallTool, } from "../../../tool-policy.js";
 import { isInSpawnTimeoutCooldown } from "../../../spawn-timeout-cooldown.js";
+import { createAvailabilityProbeFlight } from "../../../availability-probe-flight.js";
 import { classifyProbeFailure, createAvailabilityLatch, describeInstallAttempt, describeProbeEvidence, isLatchingOutcome, logAvailabilityDecision, startHostStallSampler, transientRetryDelayMs, } from "./availability-policy.js";
 export { createAvailabilityLatch, classifyProbeFailure, describeProbeEvidence, describeUnavailability, isTransientDecision, logAvailabilityDecision, startHostStallSampler, } from "./availability-policy.js";
 /**
@@ -118,14 +121,14 @@ const MANAGED_VERIFY_COOLDOWN_MAX_MS = 15 * 60_000;
 function managedVerifyCooldownMs(attempts) {
     return Math.min(MANAGED_VERIFY_COOLDOWN_MAX_MS, MANAGED_VERIFY_COOLDOWN_MS * 2 ** (attempts - 1));
 }
-async function runManagedVerification(candidate, stamp, priorAttempts, generation) {
+async function runManagedVerification(candidate, stamp, priorAttempts, generation, verificationArgs = ["--version"]) {
     let transient = false;
     let ok;
     try {
         const { verifyToolBinary } = await import("../../../installer/index.js");
         ok = await verifyToolBinary(candidate, undefined, () => {
             transient = true;
-        }, MANAGED_VERIFY_TIMEOUT_MS);
+        }, MANAGED_VERIFY_TIMEOUT_MS, verificationArgs);
     }
     catch {
         // The verifier itself could not run — installer-isolated unit tests mock
@@ -164,7 +167,7 @@ async function runManagedVerification(candidate, stamp, priorAttempts, generatio
     }
     return ok ? "ok" : "broken";
 }
-async function verifyManagedCandidate(candidate) {
+async function verifyManagedCandidate(candidate, verificationArgs = ["--version"]) {
     let stamp;
     try {
         const stat = fs.statSync(candidate);
@@ -186,7 +189,7 @@ async function verifyManagedCandidate(candidate) {
     if (existing)
         return existing;
     const generation = availabilityGeneration.capture();
-    const probe = runManagedVerification(candidate, stamp, priorAttempts, generation).finally(() => {
+    const probe = runManagedVerification(candidate, stamp, priorAttempts, generation, verificationArgs).finally(() => {
         // A settling old-session probe must not evict the live entry a new
         // session already started for the same shim (#1674 review F5).
         generation.guardedWrite(stamp, () => {
@@ -218,9 +221,9 @@ async function verifyManagedCandidate(candidate) {
  * stalls on a cold cache still gets re-probed later (#1674 review F1).
  * Concurrent first touches share one probe (#1674 review F2).
  */
-export async function findManagedNodeToolBinary(tool) {
+export async function findManagedNodeToolBinary(tool, verificationArgs = ["--version"]) {
     for (const candidate of managedNodeToolCandidates(tool)) {
-        const verdict = await verifyManagedCandidate(candidate);
+        const verdict = await verifyManagedCandidate(candidate, verificationArgs);
         if (verdict === "ok" || verdict === "unverified")
             return candidate;
     }
@@ -237,7 +240,7 @@ export async function findManagedNodeToolBinary(tool) {
  * `shell: false` (safe-spawn, #817), so wrapping it in quotes would make it
  * a literal filename that ENOENTs on every platform (#1508).
  */
-export function createVenvFinder(command, windowsExt = "") {
+export function createVenvFinder(command, windowsExt = "", verificationArgs = ["--version"]) {
     return async (cwd) => {
         const venvPaths = [
             `.venv/bin/${command}`,
@@ -261,7 +264,7 @@ export function createVenvFinder(command, windowsExt = "") {
         // check settles it without a spawn — after one verification per shim per
         // session, so a shim that cannot run falls through to PATH instead of
         // shadowing a working binary (#1657).
-        const managed = await findManagedNodeToolBinary(command);
+        const managed = await findManagedNodeToolBinary(command, verificationArgs);
         if (managed)
             return managed;
         // Fall back to global
@@ -366,6 +369,19 @@ const latchedUnavailableByCwd = new PathKeyedMap(normalizeMapKey);
 // instead of five hand-rolled ones, and a dropped straddling write is visible
 // in the degradation ledger instead of silent.
 const availabilityGeneration = createGenerationSource("dispatch-availability");
+export const getDispatchAvailabilityGeneration = () => availabilityGeneration.current();
+const checkerProbeFlights = createAvailabilityProbeFlight({ generation: getDispatchAvailabilityGeneration });
+export function recordAvailabilityProbeOverrun(tool, key, elapsedMs, budgetMs, failure) {
+    if (budgetMs === undefined || elapsedMs <= budgetMs)
+        return;
+    if (failure === "timeout" && elapsedMs <= budgetMs * 2)
+        return;
+    incrementDegradationCount({
+        kind: "availability-probe-overrun",
+        subject: `${tool}:${key}`,
+        reason: `probe took ${Math.round(elapsedMs)}ms; budget was ${Math.round(budgetMs)}ms`,
+    });
+}
 function installStateFor(cwd, toolId) {
     let states = installAttemptsByCwd.get(cwd);
     if (!states) {
@@ -598,6 +614,9 @@ export function resetDispatchAvailabilityState() {
     managedVerifyInFlight.clear();
     resetPathWalkMemo();
     availabilityGeneration.bump();
+    checkerProbeFlights.clear();
+    cwdProbeFlights.clear();
+    // The generation bump invalidates dispatcherProbeFlights in its owner module.
 }
 /**
  * Create a cached availability checker for a command.
@@ -620,18 +639,21 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
     const cacheByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
     const inFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
     let checkerGeneration = availabilityGeneration.current();
-    const findCommand = createVenvFinder(command, windowsExt);
+    let checkerFlightGeneration = 0;
+    const findCommand = createVenvFinder(command, windowsExt, versionArgs);
     function ensureCurrentGeneration() {
         if (checkerGeneration === availabilityGeneration.current())
             return;
         cacheByCwd.clear();
         inFlightByCwd.clear();
         checkerGeneration = availabilityGeneration.current();
+        checkerFlightGeneration++;
     }
     const reset = () => {
         cacheByCwd.clear();
         inFlightByCwd.clear();
         checkerGeneration = availabilityGeneration.current();
+        checkerFlightGeneration++;
     };
     function getCache(cwd) {
         ensureCurrentGeneration();
@@ -692,9 +714,9 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             cause: verdict.cause,
             elapsedMs: verdict.elapsedMs,
             latched,
-            ...(verdict.classifiedBy !== undefined && {
-                classifiedBy: verdict.classifiedBy,
-            }),
+            // Every caller passes this (#2209); a direct key, not a conditional
+            // spread, keeps it visible to the call-shaped classifiedBy sweep.
+            classifiedBy: verdict.classifiedBy,
             ...(verdict.evidence !== undefined && { evidence: verdict.evidence }),
             ...(verdict.hostStallMs !== undefined && {
                 hostStallMs: verdict.hostStallMs,
@@ -807,17 +829,22 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             const startedAt = Date.now();
             let result;
             let hostStallMs;
+            let probeJoined = false;
             try {
-                result = await safeSpawnAsync(cmd, versionArgs, {
+                const shared = checkerProbeFlights.run(`checker:${command}|${versionArgs.join("|")}|${key}|${checkerFlightGeneration}|${windowsExt}|${cmd}|${JSON.stringify(Object.entries(env ?? {}).sort(([a], [b]) => compareOrdinal(a, b)))}`, () => safeSpawnAsync(cmd, versionArgs, {
                     timeout: options.probeTimeout ?? 5000,
                     cwd: resolvedCwd,
                     env,
-                });
+                    input: "",
+                }));
+                probeJoined = shared.joined;
+                result = await shared.promise;
             }
             finally {
                 hostStallMs = stallSampler.stop();
             }
             const elapsedMs = Date.now() - startedAt;
+            recordAvailabilityProbeOverrun(command, resolvedCwd, elapsedMs, options.probeTimeout ?? 5000, result.failure);
             if (!result.error && result.status === 0) {
                 cache.command = cmd;
                 noteDecision(cache, resolvedCwd, {
@@ -826,7 +853,7 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                     cause: "ok",
                     elapsedMs,
                     hostStallMs,
-                    classifiedBy: "probe",
+                    classifiedBy: probeJoined ? "joined" : "probe",
                     evidence: describeProbeEvidence(result),
                 });
                 return true;
@@ -846,7 +873,7 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                 cause,
                 elapsedMs,
                 hostStallMs,
-                classifiedBy: "probe",
+                classifiedBy: probeJoined ? "joined" : "probe",
                 evidence,
             });
             return false;
@@ -885,6 +912,9 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
     }
     return { isAvailableAsync, getCommand, getOutcome, getVerdict, reset };
 }
+const cwdProbeFlights = createAvailabilityProbeFlight({
+    generation: getDispatchAvailabilityGeneration,
+});
 /**
  * Per-cwd cached availability probe for spawn signatures that don't fit
  * `createAvailabilityChecker` — multi-arg subcommands like `cargo clippy
@@ -957,7 +987,7 @@ export function createCwdCachedProbe(probe, options) {
             ...(retryAfterMs !== undefined && { retryAfterMs }),
             ...(options.budgetMs !== undefined && { budgetMs: options.budgetMs }),
             // Every verdict here is derived from the probe this seam just ran.
-            classifiedBy: "probe",
+            classifiedBy: verdict.classifiedBy ?? "probe",
             ...(verdict.evidence !== undefined && { evidence: verdict.evidence }),
         }, key);
     }
@@ -981,20 +1011,24 @@ export function createCwdCachedProbe(probe, options) {
             const startedAt = Date.now();
             let result;
             let thrown;
+            let probeJoined = false;
             try {
-                result = await probe(key);
+                const shared = cwdProbeFlights.run(`cwd:${options.tool}|${options.flightKeyComponent ?? ""}|${key}`, () => probe(key));
+                probeJoined = shared.joined;
+                result = await shared.promise;
             }
             catch (error) {
                 thrown = error;
             }
             const hostStallMs = stallSampler.stop();
             const elapsedMs = Date.now() - startedAt;
-            // A probe that threw carries its errno in the Error, which is exactly
-            // what the taxonomy reads — so a thrown EAGAIN stays transient instead
-            // of collapsing into an untyped `false`.
             const shape = result ?? {
                 error: thrown instanceof Error ? thrown : new Error(String(thrown)),
             };
+            recordAvailabilityProbeOverrun(options.tool, key, elapsedMs, options.budgetMs, shape.failure);
+            // A probe that threw carries its errno in the Error, which is exactly
+            // what the taxonomy reads — so a thrown EAGAIN stays transient instead
+            // of collapsing into an untyped `false`.
             if (result && !result.error && result.status === 0) {
                 note(latch, key, {
                     available: true,
@@ -1002,6 +1036,7 @@ export function createCwdCachedProbe(probe, options) {
                     cause: "ok",
                     elapsedMs,
                     hostStallMs,
+                    classifiedBy: probeJoined ? "joined" : "probe",
                     evidence: describeProbeEvidence(result, options.tool),
                 });
                 return true;
@@ -1017,6 +1052,7 @@ export function createCwdCachedProbe(probe, options) {
                 cause,
                 elapsedMs,
                 hostStallMs,
+                classifiedBy: probeJoined ? "joined" : "probe",
                 evidence,
             });
             return false;
@@ -1108,6 +1144,7 @@ async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--ve
         const versionCheck = await safeSpawnAsync(command, versionArgs, {
             timeout,
             cwd,
+            input: "",
         });
         if (!versionCheck.error && versionCheck.status === 0) {
             return command;
@@ -1141,7 +1178,7 @@ async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--ve
     return null;
 }
 export async function resolveCommandArgsWithInstallFallback(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
-    const versionCheck = await safeSpawnAsync(command.cmd, [...command.args, ...versionArgs], { timeout, cwd });
+    const versionCheck = await safeSpawnAsync(command.cmd, [...command.args, ...versionArgs], { timeout, cwd, input: "" });
     if (!versionCheck.error && versionCheck.status === 0) {
         return command;
     }
@@ -1353,7 +1390,7 @@ export async function isSgAvailableAsync() {
         return memo;
     if (sgAvailableInFlight)
         return sgAvailableInFlight;
-    sgAvailableInFlight = (async () => {
+    const flight = (async () => {
         const startedAt = Date.now();
         sgSweepSawTransient = false;
         sgSweepTransientCause = "probe-timeout";
@@ -1415,9 +1452,19 @@ export async function isSgAvailableAsync() {
         noteSgUnavailable(startedAt, sgSweepSawTransient ? "transient" : "missing", sgSweepSawTransient ? sgSweepTransientCause : "not-found");
         return false;
     })().finally(() => {
-        sgAvailableInFlight = null;
+        // Identity-guarded release (#1968's pattern): clear the slot only if THIS
+        // flight still owns it. `ensureCurrentSgGeneration()` above nulls the slot
+        // on a generation bump (a session reset arriving mid-flight) so the NEXT
+        // caller starts a fresh flight rather than sharing this one's stale-generation
+        // answer — that fresh flight is a live successor. Without the guard, this
+        // flight's own late settlement would stomp the slot back to null out from
+        // under that successor, and the caller after it would start a redundant
+        // THIRD probe instead of sharing the still-running second one.
+        if (sgAvailableInFlight === flight)
+            sgAvailableInFlight = null;
     });
-    return sgAvailableInFlight;
+    sgAvailableInFlight = flight;
+    return flight;
 }
 /**
  * Record a successful shared-ast-grep sweep, with one decision record.
@@ -1449,6 +1496,7 @@ function noteSgAvailable(startedAt, opts = {}) {
         cause: provisional ? sgSweepTransientCause : "ok",
         elapsedMs: Date.now() - startedAt,
         latched: !provisional,
+        classifiedBy: "probe",
         hostStallMs: sgSweepHostStallMs,
         budgetMs: 5000,
         ...(provisional && {
@@ -1472,6 +1520,9 @@ function noteSgUnavailable(startedAt, outcome, cause) {
         hostStallMs: sgSweepHostStallMs,
         ...(retryAfterMs > 0 && { retryAfterMs }),
         budgetMs: 5000,
+        // Sibling of noteSgAvailable's "probe": both report the same
+        // candidate sweep this function ran (#2209).
+        classifiedBy: "probe",
     });
 }
 export function getSgCommand() {

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/spawn-outcome.js

@@ -1,4 +1,5 @@
 import { LEDGER_FIELD_MAX } from "../../../ledger-bounds.js";
+import { truncatedByOutputCap } from "../../../spawn-output-cap.js";
 /**
  * The first non-empty line of a tool's output, bounded.
  *
@@ -58,6 +59,9 @@ export function classifyRunOutcome(input) {
         firstOutputLine: firstOutputLine(result.stderr) ||
             firstOutputLine(result.stdout) ||
             firstOutputLine(result.error?.message),
+        // Evidence carried alongside the verdict, never part of deciding it — the
+        // branches below are byte-for-byte the pre-#2100 rules.
+        outputCapped: truncatedByOutputCap(result),
     };
     if (result.error || signal)
         return { kind: "did-not-run", ...base };

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/tool-failure.js

@@ -5,6 +5,23 @@
 import { incrementDegradationCount } from "../../../degradation-ledger.js";
 import { truncateForLedger } from "../../../ledger-bounds.js";
 import { classifyRunOutcome, firstOutputLine, } from "./spawn-outcome.js";
+/**
+ * What ended this run, as one clause, most specific cause first.
+ *
+ * A signal is a stronger explanation than the exit status, so it displaces a
+ * `null` one rather than sitting beside it. Our own output cap is stronger
+ * still: the signal it killed with is a detail of OUR decision, and naming that
+ * signal alone reads as the tool misbehaving (#2100).
+ */
+function describeEnding(input) {
+    if (input.outputCapped)
+        return "was stopped at its output cap";
+    if (input.signal)
+        return `was killed by ${input.signal}`;
+    if (input.status === null)
+        return "did not run (spawn failure)";
+    return `exited ${input.status}`;
+}
 /**
  * One wording for "this tool did not produce a usable result" (#1816).
  *
@@ -21,13 +38,7 @@ export function formatToolFailure(input) {
     const identity = entries.length
         ? `${input.tool} (${entries.map(([key, value]) => `${key}=${value}`).join(", ")})`
         : input.tool;
-    // A signal is the strongest available explanation, so it displaces the exit
-    // status rather than sitting beside a `null` one.
-    const what = input.signal
-        ? `was killed by ${input.signal}`
-        : input.status === null
-            ? "did not run (spawn failure)"
-            : `exited ${input.status}`;
+    const what = describeEnding(input);
     const missing = input.reportMissing ? "no report file" : "no output";
     const detail = firstOutputLine(input.stderr) ||
         firstOutputLine(input.stdout) ||
@@ -44,6 +55,7 @@ export function formatRunOutcomeFailure(tool, outcome, fields) {
         tool,
         status: outcome.status,
         signal: outcome.signal,
+        outputCapped: outcome.outputCapped,
         stderr: outcome.firstOutputLine,
         reportMissing: outcome.kind === "report-missing",
         fields: { outcome: outcome.kind, ...fields },

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/toolchain-availability.js

@@ -13,6 +13,9 @@
  */
 import { createAvailabilityLatch, logAvailabilityDecision, } from "./availability-policy.js";
 import { probeAvailabilityCandidates } from "./candidate-probe.js";
+import { createAvailabilityProbeFlight } from "../../../availability-probe-flight.js";
+import { createSingleFlight } from "../../../single-flight.js";
+const toolchainProbeFlights = createAvailabilityProbeFlight();
 /**
  * Own one toolchain's availability: sweep the platform candidate list, memoize
  * the path that answered, and park the verdict behind the shared latch so a
@@ -28,12 +31,13 @@ export function createToolchainAvailability(config) {
     let sweepHostStallMs = 0;
     /** What the last classified candidate returned, for the decision record. */
     let sweepEvidence;
-    let ensureInFlight = null;
+    const ensureFlight = createSingleFlight();
     async function findPath() {
         if (toolPath)
             return toolPath;
         const paths = process.platform === "win32" ? config.windowsPaths : config.unixPaths;
-        const sweep = await probeAvailabilityCandidates(paths, config.probeArgs, config.budgetMs);
+        const shared = toolchainProbeFlights.run(`toolchain:${config.tool}|${config.probeArgs.join("|")}|${config.windowsPaths.join("|")}|${config.unixPaths.join("|")}`, () => probeAvailabilityCandidates(paths, config.probeArgs, config.budgetMs));
+        const sweep = await shared.promise;
         sweepSawTransient = sweep.sawTransient;
         sweepTransientCause = sweep.transientCause;
         sweepHostStallMs = sweep.hostStallMs;
@@ -90,17 +94,7 @@ export function createToolchainAvailability(config) {
         const memo = availabilityLatch.read();
         if (memo !== null)
             return memo;
-        // Now that a verdict can expire, concurrent callers arriving just after a
-        // cooldown must share ONE sweep rather than each spawning their own.
-        if (ensureInFlight)
-            return ensureInFlight;
-        ensureInFlight = resolveAvailability();
-        try {
-            return await ensureInFlight;
-        }
-        finally {
-            ensureInFlight = null;
-        }
+        return ensureFlight.run("availability", resolveAvailability);
     }
     return { findPath, isAvailable };
 }

package/node_modules/pi-lens/dist/clients/dispatch/runners/yaml-rule-parser.js

@@ -16,6 +16,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import yaml from "../../deps/js-yaml.js";
 import { BoundedLruCache } from "../../bounded-cache.js";
+import { compareOrdinal } from "../../string-utils.js";
 // --- Constants ---
 /** Overly broad patterns that match everything (cause false positive explosions) */
 export const OVERLY_BROAD_PATTERNS = [
@@ -28,18 +29,22 @@ export const OVERLY_BROAD_PATTERNS = [
 ];
 /** Maximum complexity score for rules in blockingOnly mode */
 export const MAX_BLOCKING_RULE_COMPLEXITY = 8;
+/**
+ * `getCachedRules` re-stats a rule directory's files at most once per this
+ * window (#2262 round 2). `scanner.ts:235` calls `loadYamlRules` per file
+ * scanned; a full metadata sweep (readdir + stat every rule file) on every
+ * warmed call measured 250x master's per-call cost on a mid-size catalog.
+ * Same value and same shape as `file-utils.ts`'s
+ * `PROJECT_IGNORE_FRESHNESS_CADENCE_MS` (#2159/#2071): 2s is the accepted
+ * staleness bound for a rule tree pi-lens itself did not just write.
+ */
+export const RULES_CACHE_FRESHNESS_CADENCE_MS = 2_000;
 // --- Caches ---
 const rulesCache = new BoundedLruCache(64);
 const blockingRulesCache = new BoundedLruCache(64);
 const contentRulesCache = new BoundedLruCache(64);
 const contentBlockingRulesCache = new BoundedLruCache(64);
 // --- Public API ---
-export function clearRulesCache() {
-    rulesCache.clear();
-    blockingRulesCache.clear();
-    contentRulesCache.clear();
-    contentBlockingRulesCache.clear();
-}
 export function loadYamlRules(ruleDir, severityFilter) {
     return getCachedRules(ruleDir, severityFilter);
 }
@@ -48,7 +53,14 @@ function findYamlRuleFiles(ruleDir) {
     try {
         entries = fs
             .readdirSync(ruleDir, { withFileTypes: true })
-            .sort((a, b) => a.name.localeCompare(b.name));
+            // Ordinal (code-unit), not locale, comparison: this order feeds the
+            // index-aligned file-stamp identity compared in `getCachedRules` and
+            // the hash input order in `loadYamlRulesFresh`. `localeCompare` can
+            // order the same file set differently across locales/processes,
+            // which would desync the two and mint spurious cache misses or
+            // (worse) content-hash collisions across differently-ordered runs.
+            // Same reasoning as `rule-cache.ts`'s `computeRuleHash` (#2155/#2165).
+            .sort((a, b) => compareOrdinal(a.name, b.name));
     }
     catch {
         return [];
@@ -118,20 +130,42 @@ export function getCachedRules(ruleDir, severityFilter) {
     if (!fs.existsSync(ruleDir)) {
         return [];
     }
-    let currentMtime = 0;
-    try {
-        currentMtime = fs.statSync(ruleDir).mtimeMs;
-    }
-    catch {
-        return [];
-    }
     const cache = severityFilter === "error" ? blockingRulesCache : rulesCache;
     const cached = cache.get(ruleDir);
-    if (cached && cached.mtime === currentMtime) {
+    const now = Date.now();
+    if (cached && now - cached.checkedAtMs < RULES_CACHE_FRESHNESS_CADENCE_MS) {
+        // Inside the cadence window: no stat sweep at all. `getCachedRules` is
+        // the bundled-catalog path only (project rules route through
+        // `loadYamlRulesFresh` — see `ast-grep-napi.ts`'s route split), and
+        // `scanner.ts:235` calls it once per scanned file, so a per-call
+        // `readdirSync`+`statSync*N` sweep is the hot-path cost this window
+        // exists to remove.
         return cached.rules;
     }
-    const rules = loadYamlRulesUncached(ruleDir, severityFilter);
-    cache.set(ruleDir, { rules, mtime: currentMtime });
+    const files = findYamlRuleFiles(ruleDir);
+    const fileStamps = files.flatMap((file) => {
+        try {
+            const stat = fs.statSync(file);
+            return [{ path: file, mtimeMs: stat.mtimeMs, size: stat.size }];
+        }
+        catch {
+            return [];
+        }
+    });
+    const metadataMatches = cached?.files.length === fileStamps.length &&
+        cached.files.every((file, index) => file.path === fileStamps[index].path &&
+            file.mtimeMs === fileStamps[index].mtimeMs &&
+            file.size === fileStamps[index].size);
+    if (cached && metadataMatches) {
+        // Nothing drifted. Re-arm the window from *now* regardless — otherwise
+        // the next call re-stats immediately instead of waiting a full cadence
+        // (the #2260/#2071 "checkedAtMs must re-arm on every check, not only on
+        // a miss" lesson).
+        cached.checkedAtMs = now;
+        return cached.rules;
+    }
+    const rules = loadYamlRuleFiles(files, severityFilter);
+    cache.set(ruleDir, { rules, files: fileStamps, checkedAtMs: now });
     return rules;
 }
 export function isOverlyBroadPattern(pattern) {

package/node_modules/pi-lens/dist/clients/event-loop-monitor.js

@@ -82,6 +82,66 @@ export function startEventLoopMonitor(resolutionMs = 20) {
         });
     }
 }
+/**
+ * Below this, a block is not classified at all (`below-floor`). #1980 mined
+ * the 5 s+ tier; 1 s is a deliberately conservative floor that still covers
+ * every block that tier cares about while keeping sub-second jitter — where
+ * measurement slop rivals the signal — out of the verdict.
+ */
+export const STALL_CLASSIFY_FLOOR_MS = 1000;
+/**
+ * Slack allowed to the CPU budget before a block counts as unaccounted.
+ * `process.cpuUsage()` and the histogram are sampled at slightly different
+ * instants and the histogram quantizes, so a block whose CPU coverage is
+ * within this much of exact is called `cpu-accounted`, not a stall.
+ */
+export const STALL_CLASSIFY_SLOP_MS = 250;
+/**
+ * Split a block into compute-vs-stall from the CPU it could possibly have
+ * burned (#1980). Pure, so the discrimination is testable without the native
+ * histogram or a real machine stall — the same reason
+ * {@link isSuspendSuspectedBlock} is pure.
+ *
+ * ## Why this is sound in exactly one direction
+ *
+ * `windowCpuMs` is the CPU the WHOLE process consumed across the WHOLE window
+ * — every thread, every phase, not just this block. So it is an UPPER BOUND on
+ * the CPU this one block could have burned. A synchronous compute block of D ms
+ * needs ≈ D ms of main-thread CPU. Therefore:
+ *
+ * - `windowCpuMs + slop < maxMs` PROVES the block was not compute. Even if the
+ *   block had been the only thing running, there was not enough CPU in the
+ *   whole window to cover it. This is the `non-cpu-stall` verdict and it is a
+ *   real inference, not a heuristic.
+ * - The converse proves nothing. A window can burn 30 s of CPU in other phases
+ *   and still contain a 5 s I/O park. That is why the label is
+ *   `cpu-accounted` ("the budget covers it") rather than "compute": it reports
+ *   the absence of proof, not the presence of compute.
+ *
+ * The existing 20 s suspend verdict is not re-derived here; this delegates to
+ * {@link isSuspendSuspectedBlock} so there is one definition of a suspend, and
+ * `system-stall` is checked BEFORE `non-cpu-stall` because a suspend is the
+ * strictly more specific case of the same evidence.
+ *
+ * ## Known ambiguity, carried forward not silenced
+ *
+ * `isSuspendSuspectedBlock`'s own doc records that a >20 s synchronous syscall
+ * stall is CPU-indistinguishable from a suspend. Nothing here fixes that. What
+ * this adds is the tier BELOW that floor: a 5-20 s non-CPU block, which used
+ * to read as ordinary compute and now reads as `non-cpu-stall` with the
+ * `inFlightPhase` attribution beside it.
+ */
+export function classifyLoopBlock(maxMs, windowCpuMs, options = {}) {
+    const { floorMs = STALL_CLASSIFY_FLOOR_MS, slopMs = STALL_CLASSIFY_SLOP_MS, suspendFloorMs, suspendSlopMs, } = options;
+    const cpuCoverageRatio = maxMs > 0 ? Math.round((windowCpuMs / maxMs) * 100) / 100 : undefined;
+    if (maxMs < floorMs)
+        return { stallClass: "below-floor", cpuCoverageRatio };
+    if (isSuspendSuspectedBlock(maxMs, windowCpuMs, suspendFloorMs, suspendSlopMs))
+        return { stallClass: "system-stall", cpuCoverageRatio };
+    if (windowCpuMs + slopMs < maxMs)
+        return { stallClass: "non-cpu-stall", cpuCoverageRatio };
+    return { stallClass: "cpu-accounted", cpuCoverageRatio };
+}
 const safeMs = (ns) => Number.isFinite(ns) ? Math.round((ns / NS_PER_MS) * 10) / 10 : 0;
 /**
  * Classify a worst-block sample as genuine CPU work or a suspend/freeze
@@ -123,13 +183,18 @@ export function getEventLoopStats() {
     const maxMs = safeMs(histogram.max);
     const windowWallMs = Math.max(0, Date.now() - windowStartWallMs);
     const windowCpuMs = Math.max(0, cpuTotalMs() - windowStartCpuMs);
+    // One classification pass feeds both fields, so `suspectSystemStall` and
+    // `stallClass` can never disagree about the same sample (#1980).
+    const classification = classifyLoopBlock(maxMs, windowCpuMs);
     return {
         maxMs,
         p99Ms: safeMs(histogram.percentile(99)),
         meanMs: safeMs(histogram.mean),
         windowWallMs: Math.round(windowWallMs),
         windowCpuMs: Math.round(windowCpuMs),
-        suspectSystemStall: isSuspendSuspectedBlock(maxMs, windowCpuMs),
+        suspectSystemStall: classification.stallClass === "system-stall",
+        stallClass: classification.stallClass,
+        cpuCoverageRatio: classification.cpuCoverageRatio,
     };
 }
 /**