pi-lens 4.1.2 → 4.1.4

package/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/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/dist/clients/dispatch/runners/utils/toolchain-availability.js

@@ -13,6 +13,40 @@
  */
 import { createAvailabilityLatch, logAvailabilityDecision, } from "./availability-policy.js";
 import { probeAvailabilityCandidates } from "./candidate-probe.js";
+import { createAvailabilityProbeFlight } from "../../../availability-probe-flight.js";
+import { createGenerationSource } from "../../../generation-guard.js";
+import { createSingleFlight } from "../../../single-flight.js";
+/**
+ * Session generation for toolchain-availability resets (#2455 fix round 3, F2).
+ *
+ * `reset()` clears the memo and the latch, but a probe that was ALREADY in
+ * flight when it ran knows nothing about that. Without a generation, a
+ * post-reset caller joins the pre-reset flight and, worse, that flight's own
+ * settlement writes its stale verdict back into the freshly cleared latch — so
+ * a tool installed between sessions still read "missing" for the whole new
+ * session. That is #1674's defect read from both the sharing side and the
+ * settle side, and the reason `SingleFlightOptions.generation` exists.
+ *
+ * This is the repo's extracted primitive (`clients/generation-guard.ts`, #1754)
+ * rather than a hand-rolled counter (#2455 fix round 4, F1). Two things come
+ * with it that the hand-rolled form did not have: the source is declared by
+ * construction, so the #1754 ratchet can see it; and `guardedWrite` puts every
+ * superseded write in the degradation ledger as a bounded
+ * `generation-guard-stale-write` record per (source, subject), so a dogfood
+ * session can tell "the guard is working" from "the guard never fires" instead
+ * of watching superseded writes vanish silently (F4).
+ *
+ * A module-level source rather than a per-instance one, deliberately. It is a
+ * counter, so nothing has to be hand-maintained and no flight is retained for
+ * the sake of superseding it. And `toolchainProbeFlights` is itself shared
+ * ACROSS instances (#2131: two clients probing the same candidate list run one
+ * sweep), so its supersede signal cannot live on any one instance. The cost is
+ * that resetting one toolchain also supersedes another's in-flight sweep; that
+ * is at worst one extra probe, never a wrong verdict, and every registered
+ * reset fires in the same `session_start` block anyway.
+ */
+const toolchainGenerations = createGenerationSource("toolchain-availability");
+const toolchainProbeFlights = createAvailabilityProbeFlight({ generation: toolchainGenerations.current });
 /**
  * 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,33 +62,61 @@ 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({
+        generation: toolchainGenerations.current,
+    });
     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);
-        sweepSawTransient = sweep.sawTransient;
-        sweepTransientCause = sweep.transientCause;
-        sweepHostStallMs = sweep.hostStallMs;
-        sweepEvidence = sweep.evidence;
-        if (sweep.foundPath)
-            toolPath = sweep.foundPath;
+        const handle = toolchainGenerations.capture();
+        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;
+        // A reset may have landed while this sweep was running. Its answer then
+        // describes the session that just ended, so it must not write itself back
+        // into the memo `reset()` just cleared, nor into the classification fields
+        // the replacement flight reads to build ITS verdict. The memo is the
+        // sharper half: a superseded sweep that writes `foundPath` latches a path
+        // the reset may have been called BECAUSE it went away, so the seam that
+        // exists to un-latch a false "missing" would instead latch a false
+        // "found". Callers already holding this promise still get what the sweep
+        // actually found.
+        handle.guardedWrite(`findPath:${config.tool}`, () => {
+            sweepSawTransient = sweep.sawTransient;
+            sweepTransientCause = sweep.transientCause;
+            sweepHostStallMs = sweep.hostStallMs;
+            sweepEvidence = sweep.evidence;
+            if (sweep.foundPath)
+                toolPath = sweep.foundPath;
+        });
         return sweep.foundPath;
     }
     async function resolveAvailability() {
         const startedAt = Date.now();
-        const found = (await findPath()) !== null;
+        const handle = toolchainGenerations.capture();
+        const resolvedPath = await findPath();
+        const found = resolvedPath !== null;
+        // #2455 fix round 3, F2: a reset during the probe opened a NEW session.
+        // This flight answers the OLD one, so writing its verdict into the
+        // freshly cleared latch would re-latch a stale "missing" for the whole
+        // new session — the bug the reset exists to prevent, reintroduced by the
+        // reset's own timing. Report the verdict to this flight's own callers;
+        // do not latch it, and say so in the decision record's `latched`.
+        const superseded = !handle.isCurrent();
         if (found) {
-            availabilityLatch.noteAvailable();
-            config.log(`${config.label} found: ${toolPath}`);
+            handle.guardedWrite(`latch:${config.tool}`, () => availabilityLatch.noteAvailable());
+            // The RESOLVED path, not the memo (#2455 fix round 4, F6). A superseded
+            // sweep is forbidden from writing `toolPath`, so reading the memo here
+            // logged `Go found: null` on exactly the branch this line exists to
+            // explain.
+            config.log(`${config.label} found: ${resolvedPath}`);
             logAvailabilityDecision({
                 tool: config.tool,
                 verdict: "available",
                 outcome: "success",
                 cause: "ok",
                 elapsedMs: Date.now() - startedAt,
-                latched: true,
+                latched: !superseded,
                 hostStallMs: sweepHostStallMs,
                 budgetMs: config.budgetMs,
                 classifiedBy: "probe",
@@ -66,14 +128,14 @@ export function createToolchainAvailability(config) {
         // whether the toolchain is installed; it expires instead of latching.
         const outcome = sweepSawTransient ? "transient" : "missing";
         const cause = sweepSawTransient ? sweepTransientCause : "not-found";
-        const retryAfterMs = availabilityLatch.noteUnavailable(outcome, cause);
+        const retryAfterMs = handle.guardedWrite(`latch:${config.tool}`, () => availabilityLatch.noteUnavailable(outcome, cause)) ?? 0;
         logAvailabilityDecision({
             tool: config.tool,
             verdict: "unavailable",
             outcome,
             cause,
             elapsedMs: Date.now() - startedAt,
-            latched: outcome !== "transient",
+            latched: !superseded && outcome !== "transient",
             hostStallMs: sweepHostStallMs,
             ...(retryAfterMs > 0 && { retryAfterMs }),
             budgetMs: config.budgetMs,
@@ -90,17 +152,18 @@ 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);
+    }
+    function reset() {
+        toolPath = null;
+        availabilityLatch.reset();
+        // Supersede every sweep and availability flight already running, in this
+        // instance and in the shared registry. No `clear()`: the generation bump
+        // is what makes a stale flight unjoinable and unable to re-latch, and
+        // `SingleFlight.release`'s identity check already stops it from evicting
+        // its successor. Clearing the SHARED registry here would additionally
+        // drop another toolchain's live claim and cost it a duplicate sweep.
+        toolchainGenerations.bump();
     }
-    return { findPath, isAvailable };
+    return { findPath, isAvailable, reset };
 }

package/dist/clients/dispatch/runners/vale.js

@@ -70,7 +70,6 @@ const valeRunner = {
     id: "vale",
     appliesTo: ["markdown"],
     priority: PRIORITY.DOC_QUALITY,
-    enabledByDefault: true,
     skipTestFiles: false,
     async run(ctx) {
         const cwd = ctx.cwd || process.cwd();

package/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/dist/clients/dispatch/runners/yamllint.js

@@ -33,7 +33,6 @@ const yamllintRunner = {
     id: "yamllint",
     appliesTo: ["yaml"],
     priority: PRIORITY.YAML_LINT,
-    enabledByDefault: true,
     skipTestFiles: false,
     async run(ctx) {
         const cwd = ctx.cwd || process.cwd();

package/dist/clients/dispatch/runners/zig-check.js

@@ -44,7 +44,6 @@ const zigCheckRunner = {
     id: "zig-check",
     appliesTo: ["zig"],
     priority: PRIORITY.GENERAL_ANALYSIS,
-    enabledByDefault: true,
     skipTestFiles: false,
     async run(ctx) {
         const cwd = ctx.cwd || process.cwd();

package/dist/clients/disposition-logger.js

@@ -1,6 +1,6 @@
 /**
  * NDJSON telemetry log for diagnostic disposition marks (#690). Same shape as
- * clients/actionable-warnings-logger.ts: machine-global (getGlobalPiLensDir),
+ * clients/actionable-warnings-logger.ts: machine-global (getGlobalPiLensLogDir),
  * size-capped with a single `.log.1` backup, isTestMode no-op.
  *
  * Why a log at all: #181 identified false-positive marks flowing to telemetry
@@ -13,9 +13,9 @@
  */
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
-const DISPOSITION_LOG_DIR = getGlobalPiLensDir();
+const DISPOSITION_LOG_DIR = getGlobalPiLensLogDir();
 const DISPOSITION_LOG_FILE = path.join(DISPOSITION_LOG_DIR, "dispositions.log");
 const DISPOSITION_LOG_BACKUP_FILE = path.join(DISPOSITION_LOG_DIR, "dispositions.log.1");
 const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_DISPOSITION_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);