@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

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

@@ -1,11 +1,13 @@
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
-import { spawn } from "node:child_process";
+import { incrementDegradationCount } from "../../degradation-ledger.js";
+import { safeSpawnAsync } from "../../safe-spawn.js";
 import { PRIORITY } from "../priorities.js";
-// The PS script written to a temp file each run — avoids cmd.exe quoting issues
-// safeSpawnAsync uses shell:true on Windows, which mangles -Command strings.
-// Using -File with a temp script sidesteps all escaping problems.
+import { classifyProbeFailure, createAvailabilityLatch, isLatchingOutcome, logAvailabilityDecision, startHostStallSampler, } from "./utils/availability-policy.js";
+// The PS script written to a temp file each run. `-File` with a temp script
+// keeps the analysis argv free of embedded script text; safe-spawn itself never
+// uses a shell (#817), so nothing here is quoting-sensitive.
 const PS_SCRIPT = `
 param([string]$FilePath)
 Import-Module PSScriptAnalyzer -ErrorAction Stop
@@ -13,82 +15,229 @@ $results = @(Invoke-ScriptAnalyzer -Path $FilePath | Select-Object RuleName,@{N=
 if ($results.Count -eq 0) { Write-Output '[]'; exit 0 }
 $results | ConvertTo-Json -Depth 3 -Compress
 `.trim();
-// Cache resolved powershell binary and module availability per process
-let psCmd = undefined;
-let psAnalyzerAvailable = undefined;
 const PS_TIMEOUT_MS = 30000;
+/**
+ * PowerShell spawns go through `safeSpawnAsync` (#1490).
+ *
+ * The hand-rolled version returned `status: null` for a timeout, a synchronous
+ * `spawn UNKNOWN` and a missing binary alike, so the call site had nothing to
+ * classify and remembered every one of them as "PowerShell analysis is not
+ * available". `safeSpawnAsync` carries the standard taxonomy — `failure`,
+ * `spawnFailure.kind` and the errno on `error` — which is what lets the
+ * availability policy tell a stall from an absence.
+ */
 function spawnPs(cmd, args, timeoutMs = PS_TIMEOUT_MS) {
-    return new Promise((resolve) => {
-        let child;
-        try {
-            child = spawn(cmd, args, { windowsHide: true, shell: false });
-        }
-        catch {
-            // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
-            // bug class, #533) — this best-effort runner must resolve, not reject.
-            resolve({ stdout: "", stderr: "", status: null });
-            return;
-        }
-        let stdout = "";
-        let stderr = "";
-        let settled = false;
-        const done = (status) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve({ stdout, stderr, status });
-        };
-        const timer = setTimeout(() => {
-            if (!settled) {
-                child.kill("SIGTERM");
-                setTimeout(() => { if (!settled)
-                    child.kill("SIGKILL"); }, 1000);
-                done(null);
-            }
-        }, timeoutMs);
-        child.stdout?.setEncoding("utf-8");
-        child.stderr?.setEncoding("utf-8");
-        child.stdout?.on("data", (d) => (stdout += d));
-        child.stderr?.on("data", (d) => (stderr += d));
-        child.on("close", (code) => done(code));
-        child.on("error", () => done(null));
+    return safeSpawnAsync(cmd, args, {
+        timeout: timeoutMs,
+        resourceLabel: "psscriptanalyzer",
     });
 }
+/**
+ * The two verdicts this runner memoizes, both owned by the shared policy.
+ *
+ * The availability-policy coverage gate never flagged either of them, and the
+ * reason is not a bug in the gate: it recognises a probe by a quoted VERSION
+ * FLAG, and neither probe below asks for a version. One runs `exit 0` to see if
+ * an interpreter answers; the other asks `Get-Module -ListAvailable`. A
+ * capability probe with no version flag is invisible to that pre-filter, so this
+ * file was skipped before any unit was analysed. The residual gate blindness is
+ * tracked with #1489's gate work; the migration here does not depend on it.
+ */
+const psCmdLatch = createAvailabilityLatch();
+const psAnalyzerLatchByCmd = new Map();
+/**
+ * Whether `-File` actually executes, keyed by interpreter (#1540).
+ *
+ * Neither probe above asks `-File` a question -- both use `-Command`, which
+ * PowerShell's execution policy does not gate. Under `Restricted`/`AllSigned`
+ * that lets both probes report "available" while the real analysis spawn
+ * (which DOES go through `-File`) gets a policy `SecurityError` on stderr and
+ * exits nonzero with empty stdout. This latch is deliberately populated by
+ * the real analysis run rather than a third `-Command`-shaped probe, so the
+ * verdict it records is direct evidence about `-File`, not an inference from
+ * a proxy that has already been shown to disagree with it.
+ */
+const psExecLatchByCmd = new Map();
+let psCmd = null;
+/** Record one decision, and report whether the caller may retry later. */
+function notePsDecision(latch, tool, verdict) {
+    let retryAfterMs;
+    if (verdict.available) {
+        latch.noteAvailable();
+    }
+    else {
+        const delay = latch.noteUnavailable(verdict.outcome, verdict.cause);
+        if (delay > 0)
+            retryAfterMs = delay;
+    }
+    logAvailabilityDecision({
+        tool,
+        verdict: verdict.available ? "available" : "unavailable",
+        outcome: verdict.available ? "success" : verdict.outcome,
+        cause: verdict.available ? "ok" : verdict.cause,
+        elapsedMs: verdict.elapsedMs,
+        latched: verdict.available || isLatchingOutcome(verdict.outcome),
+        hostStallMs: verdict.hostStallMs,
+        ...(retryAfterMs !== undefined && { retryAfterMs }),
+        budgetMs: PS_TIMEOUT_MS,
+    });
+}
+/**
+ * Drop both verdicts at the session boundary (#1490 review).
+ *
+ * Every other runner gets this for free through
+ * `resetDispatchAvailabilityState`'s generation counter; these latches are local
+ * to the module, so `session_start` clears them explicitly. Without it, a
+ * PowerShell or module install performed mid-process is invisible until the host
+ * restarts — the same "suppression outliving its session" defect #1222 fixed for
+ * install attempts.
+ */
+export function resetPsScriptAnalyzerAvailability() {
+    psCmdLatch.reset();
+    psAnalyzerLatchByCmd.clear();
+    psExecLatchByCmd.clear();
+    psCmd = null;
+}
+/**
+ * Resolve the PowerShell binary, once per session per verdict.
+ *
+ * A candidate that times out is NOT evidence that PowerShell is absent, so the
+ * loop only concludes "missing" when every candidate answered with a durable
+ * failure. One transient candidate makes the whole verdict transient, and the
+ * next turn after the cooldown probes again.
+ */
 async function resolvePowerShellCmd() {
-    if (psCmd !== undefined)
-        return psCmd;
+    const memo = psCmdLatch.read();
+    if (memo !== null)
+        return memo ? psCmd : null;
+    // Rank what the candidates said, rather than collapsing every failure to
+    // "not-found" (#1490 review). A stall outranks everything: it means we never
+    // got an answer. A present-but-rejecting interpreter (nonzero exit, EACCES)
+    // is durable but is NOT a missing install, and reporting it as one both sends
+    // the user to install PowerShell they already have and fabricates the cause in
+    // `availability_decision`. Only an all-candidates ENOENT sweep is `missing`.
+    let transient = null;
+    let rejected = null;
+    let elapsedTotalMs = 0;
+    let stallTotalMs = 0;
     for (const candidate of ["pwsh", "powershell"]) {
-        const r = await spawnPs(candidate, ["-NoProfile", "-NonInteractive", "-Command", "exit 0"]);
-        if (r.status === 0) {
+        const sampler = startHostStallSampler();
+        const startedAt = Date.now();
+        const result = await spawnPs(candidate, [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "exit 0",
+        ]);
+        const hostStallMs = sampler.stop();
+        const elapsedMs = Date.now() - startedAt;
+        elapsedTotalMs += elapsedMs;
+        stallTotalMs += hostStallMs;
+        if (!result.error && result.status === 0) {
             psCmd = candidate;
-            return psCmd;
+            notePsDecision(psCmdLatch, "powershell", {
+                available: true,
+                elapsedMs,
+                hostStallMs,
+            });
+            return candidate;
         }
+        const classified = classifyProbeFailure(result, { hostStallMs });
+        if (classified.outcome === "transient")
+            transient ??= classified;
+        else if (classified.outcome !== "missing")
+            rejected ??= classified;
     }
     psCmd = null;
+    const verdict = transient ??
+        rejected ?? {
+        outcome: "missing",
+        cause: "not-found",
+    };
+    notePsDecision(psCmdLatch, "powershell", {
+        available: false,
+        outcome: verdict.outcome,
+        cause: verdict.cause,
+        elapsedMs: elapsedTotalMs,
+        hostStallMs: stallTotalMs,
+    });
     return null;
 }
 async function checkModuleAvailable(cmd) {
-    if (psAnalyzerAvailable !== undefined)
-        return psAnalyzerAvailable;
-    const r = await spawnPs(cmd, [
+    let latch = psAnalyzerLatchByCmd.get(cmd);
+    if (!latch) {
+        latch = createAvailabilityLatch();
+        psAnalyzerLatchByCmd.set(cmd, latch);
+    }
+    const memo = latch.read();
+    if (memo !== null)
+        return memo;
+    const sampler = startHostStallSampler();
+    const startedAt = Date.now();
+    const result = await spawnPs(cmd, [
         "-NoProfile",
         "-NonInteractive",
         "-Command",
         "if (Get-Module -ListAvailable PSScriptAnalyzer) { exit 0 } else { exit 1 }",
     ]);
-    psAnalyzerAvailable = r.status === 0;
-    return psAnalyzerAvailable;
+    const hostStallMs = sampler.stop();
+    const elapsedMs = Date.now() - startedAt;
+    if (!result.error && result.status === 0) {
+        notePsDecision(latch, "psscriptanalyzer", {
+            available: true,
+            elapsedMs,
+            hostStallMs,
+        });
+        return true;
+    }
+    // A CLEAN `exit 1` is the module genuinely not being installed — the one
+    // outcome an install fixes, so that alone earns the `missing` override.
+    //
+    // Everything else did not answer the question (#1490 review). A `spawn
+    // UNKNOWN`, an EMFILE, an EACCES, or a PowerShell that vanished between the
+    // two probes all arrive with an error and no status, and calling those
+    // "PSScriptAnalyzer is not installed" latched PowerShell analysis off for the
+    // session on hosts where the module was present the whole time.
+    const moduleAbsent = result.status === 1 && !result.failure && !result.error;
+    const classified = classifyProbeFailure(result, {
+        hostStallMs,
+        ...(moduleAbsent && { unclassifiedFailureOutcome: "missing" }),
+    });
+    let { outcome, cause } = classified;
+    if (!moduleAbsent && outcome !== "transient") {
+        // Nothing here is evidence about the module, so the verdict must expire.
+        outcome = "transient";
+        cause = "probe-rejected";
+    }
+    notePsDecision(latch, "psscriptanalyzer", {
+        available: false,
+        outcome,
+        cause,
+        elapsedMs,
+        hostStallMs,
+    });
+    return false;
 }
+/**
+ * `null` means "unreadable" (#1598): empty stdout, or stdout that fails to
+ * parse as JSON. `PS_SCRIPT` always writes either the literal `[]` marker or
+ * a `ConvertTo-Json` array/object on a genuine run, so anything else on an
+ * exit-0 run is not a clean-file answer -- it is a lost or truncated write
+ * between the child and us. The caller must not read `null` the same way it
+ * reads a real `[]`.
+ */
 function parsePSAnalyzerOutput(raw, filePath) {
-    if (!raw.trim() || raw.trim() === "[]")
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed === "[]")
         return [];
     let parsed;
     try {
-        parsed = JSON.parse(raw);
+        parsed = JSON.parse(trimmed);
     }
     catch {
-        return [];
+        return null;
     }
     const items = Array.isArray(parsed) ? parsed : [parsed];
     return items
@@ -124,22 +273,149 @@ const psScriptAnalyzerRunner = {
         if (!(await checkModuleAvailable(cmd))) {
             return { status: "skipped", diagnostics: [], semantic: "none" };
         }
+        let execLatch = psExecLatchByCmd.get(cmd);
+        if (!execLatch) {
+            execLatch = createAvailabilityLatch();
+            psExecLatchByCmd.set(cmd, execLatch);
+        }
+        // A durably blocked `-File` execution (an execution policy, typically) is
+        // a fact about the interpreter, not about any one file -- re-spawning on
+        // every save would just re-confirm the same policy every time (#1540).
+        if (execLatch.read() === false) {
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
         const cwd = ctx.cwd || process.cwd();
         const absPath = path.resolve(cwd, ctx.filePath);
         // Write script to temp file so we avoid cmd.exe quoting entirely
         const tmpScript = path.join(os.tmpdir(), `pi-lens-psa-${process.pid}.ps1`);
         await fs.writeFile(tmpScript, PS_SCRIPT, "utf-8");
         try {
+            const sampler = startHostStallSampler();
+            const startedAt = Date.now();
             const result = await spawnPs(cmd, [
                 "-NoProfile",
                 "-NonInteractive",
                 "-File", tmpScript,
                 "-FilePath", absPath,
             ]);
+            const hostStallMs = sampler.stop();
+            const elapsedMs = Date.now() - startedAt;
+            // The two probes above use `-Command`, which PowerShell's execution
+            // policy does not gate; this run uses `-File`, which it does. A
+            // crashed/signal-killed process (#1540 second gap) or a blocked/
+            // erroring run (#1540 primary gap) must both produce a recorded,
+            // legible availability_decision -- never a silent "clean" read of
+            // empty stdout, and never a silent skip.
             if (result.status === null) {
+                const classified = classifyProbeFailure(result, { hostStallMs });
+                let { outcome, cause } = classified;
+                // A `spawn UNKNOWN`/EMFILE/crash never ran the script, so it is not
+                // evidence that `-File` is broken (mirrors the nonzero-exit guard
+                // below, and checkModuleAvailable's own guard against over-latching
+                // an unclassified failure). Latching an unspawnable prober's
+                // verdict would durably disable analysis for the whole session on
+                // a host where `-File` works fine.
+                if (outcome !== "transient") {
+                    outcome = "transient";
+                    cause = "probe-rejected";
+                }
+                notePsDecision(execLatch, "psscriptanalyzer-exec", {
+                    available: false,
+                    outcome,
+                    cause,
+                    elapsedMs,
+                    hostStallMs,
+                });
+                incrementDegradationCount({
+                    kind: "grammar-blocked",
+                    subject: "psscriptanalyzer",
+                    reason: `PowerShell (${cmd}) -File analysis exited with no status -- crash or signal-killed process`,
+                });
+                return { status: "skipped", diagnostics: [], semantic: "none" };
+            }
+            if (result.status !== 0) {
+                const stderrText = result.stderr ?? "";
+                // Require the SecurityError/UnauthorizedAccess pairing that a real
+                // script-load block produces, not a bare "unauthorizedaccess"
+                // match (#1556 review F4) -- that word alone also appears in
+                // unrelated file-permission and access-denied stderr that has
+                // nothing to do with the execution policy, and misclassifying it
+                // as `policy-denied` would latch analysis off durably for a
+                // transient, per-file permission error.
+                const policyDenied = /securityerror/i.test(stderrText) &&
+                    (/execution polic(y|ies)/i.test(stderrText) ||
+                        /running scripts is disabled/i.test(stderrText) ||
+                        /unauthorizedaccess/i.test(stderrText));
+                const classified = classifyProbeFailure(result, { hostStallMs });
+                let { outcome, cause } = classified;
+                if (policyDenied) {
+                    // Direct, unambiguous evidence: PowerShell's own execution
+                    // policy refused to load the script. Durable until the policy
+                    // changes, so this is the one case allowed to latch.
+                    outcome = "non-installable";
+                    cause = "policy-denied";
+                }
+                else if (outcome !== "transient") {
+                    // A single nonzero exit is not durable evidence that `-File`
+                    // is broken for every file (mirrors checkModuleAvailable's own
+                    // guard against over-latching an unclassified failure).
+                    outcome = "transient";
+                    cause = "probe-rejected";
+                }
+                notePsDecision(execLatch, "psscriptanalyzer-exec", {
+                    available: false,
+                    outcome,
+                    cause,
+                    elapsedMs,
+                    hostStallMs,
+                });
+                incrementDegradationCount({
+                    kind: "grammar-blocked",
+                    subject: "psscriptanalyzer",
+                    reason: policyDenied
+                        ? `PowerShell execution policy blocked -File analysis for ${cmd}: ${stderrText.trim().split("\n")[0] || "SecurityError"}`
+                        : `PowerShell -File analysis for ${cmd} exited ${result.status}: ${stderrText.trim().slice(0, 200) || "no stderr"}`,
+                });
                 return { status: "skipped", diagnostics: [], semantic: "none" };
             }
+            // `-File` ran and exited 0: direct proof it works. Log the decision
+            // once (memoized by the latch) rather than on every save.
+            if (execLatch.read() === null) {
+                notePsDecision(execLatch, "psscriptanalyzer-exec", {
+                    available: true,
+                    elapsedMs,
+                    hostStallMs,
+                });
+            }
             const diagnostics = parsePSAnalyzerOutput(result.stdout, ctx.filePath);
+            if (diagnostics === null) {
+                // Exit 0 proves `-File` itself ran, so this does NOT reuse the
+                // exec latch above -- one bad read says nothing durable about the
+                // interpreter (mirrors the nonzero-exit branch's own guard against
+                // over-latching an unclassified failure), and it is logged rather
+                // than latched. It must still never be read as a clean file
+                // (#1598): empty/malformed stdout on a successful exit is a lost
+                // or truncated write, not evidence of zero diagnostics.
+                const unreadableReason = result.stdout.trim()
+                    ? "unparseable"
+                    : "empty";
+                logAvailabilityDecision({
+                    tool: "psscriptanalyzer-stdout",
+                    verdict: "unavailable",
+                    outcome: "transient",
+                    cause: "empty-result",
+                    elapsedMs,
+                    latched: false,
+                    hostStallMs,
+                    budgetMs: PS_TIMEOUT_MS,
+                });
+                incrementDegradationCount({
+                    kind: "grammar-blocked",
+                    subject: "psscriptanalyzer",
+                    reason: `PowerShell -File analysis for ${cmd} exited 0 but stdout was ${unreadableReason}`,
+                });
+                return { status: "skipped", diagnostics: [], semantic: "none" };
+            }
             if (diagnostics.length === 0) {
                 return { status: "succeeded", diagnostics: [], semantic: "none" };
             }

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

@@ -99,20 +99,53 @@ const pyrightRunner = {
         }
     },
 };
-function parsePyrightOutput(data, _filePath) {
+/**
+ * Map pyright's own severity vocabulary onto the four-tier `Diagnostic.severity`
+ * (clients/dispatch/types.ts), the same way `normalizeBiomeSeverity` does for
+ * biome-check (#1791) and `normalizeRuleSeverity` does for ast-grep-napi
+ * (#1787). Pyright names its info tier `"information"`; `"error"`/`"warning"`
+ * pass through as-is. An unrecognized value falls back to `"warning"` — the
+ * tier every pyright diagnostic reported at before this fix, so reviving the
+ * info tier never silently demotes an existing finding. Pyright has no
+ * `"hint"` tier in its own vocabulary, so that tier is unreachable here.
+ */
+export function normalizePyrightSeverity(raw) {
+    switch (raw) {
+        case "error":
+            return "error";
+        case "information":
+            return "info";
+        // "warning" and any unrecognized value fall back below — the tier
+        // every pyright diagnostic reported at before this fix, so reviving
+        // the info tier never silently demotes an existing finding. There is
+        // no separate `case "warning"` branch: it would be redundant with
+        // this default and unprovable as its own branch.
+        default:
+            return "warning";
+    }
+}
+export function parsePyrightOutput(data, _filePath) {
     const diagnostics = [];
     // Pyright JSON output has generalDiagnostics array
     const generalDiags = data.generalDiagnostics || [];
     for (const diag of generalDiags) {
         // Skip if not for this file (pyright may output diagnostics for imports)
         // For now, include all - caller will filter if needed
+        // pyright's `range.start.line`/`character` are zero-based (see the
+        // `PyrightDiagnostic` note above); `Diagnostic.line`/`column` are
+        // one-based, the same convention ast-grep-napi and taplo already
+        // convert to (`range.start.line + 1`). `range` itself is omitted when
+        // pyright has nothing to point at, so both fall back to line 1.
+        const start = diag.range?.start;
         diagnostics.push({
-            id: `pyright-${diag.rule || diag.start?.line || "unknown"}`,
+            id: `pyright-${diag.rule || start?.line || "unknown"}`,
             message: diag.message || "Type error",
             filePath: diag.file || _filePath,
-            line: diag.start?.line || 0,
-            column: diag.start?.column || 0,
-            severity: diag.severity === "error" ? "error" : "warning",
+            line: (start?.line ?? 0) + 1,
+            column: (start?.character ?? 0) + 1,
+            severity: normalizePyrightSeverity(diag.severity),
+            // Blocking classification stays error-only — reviving the info tier
+            // must never widen what fails a turn.
             semantic: diag.severity === "error" ? "blocking" : "warning",
             tool: "pyright",
             rule: diag.rule,

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

@@ -8,7 +8,8 @@ import { findNearestContaining } from "../../path-utils.js";
 import { RustClient } from "../../rust-client.js";
 import { safeSpawnAsync } from "../../safe-spawn.js";
 import { stripAnsi } from "../../sanitize.js";
-import { tryLazyInstall } from "./utils/lazy-installer.js";
+import { getLazyInstallAttempt, tryLazyInstall, } from "./utils/lazy-installer.js";
+import { describeInstallAttempt, logAvailabilityDecision, } from "./utils/availability-policy.js";
 import { PRIORITY } from "../priorities.js";
 import { createCwdCachedProbe } from "./utils/runner-helpers.js";
 const rustClient = new RustClient();
@@ -21,20 +22,22 @@ const rustClient = new RustClient();
 // after install. We can't `delete` a Promise mid-flight, so the safe path
 // is: if the cached probe resolves false AND the install just succeeded,
 // fall back to a one-shot fresh probe rather than reusing the cached false.
-const probeClippy = (cargoExe) => createCwdCachedProbe(async (cwd) => {
-    const r = await safeSpawnAsync(cargoExe, ["clippy", "--version"], {
-        timeout: 8000,
-        cwd,
-    });
-    return !r.error && r.status === 0;
-});
-const clippyProbeByCargo = new Map();
+//
+// 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"], {
+    timeout: CLIPPY_PROBE_BUDGET_MS,
+    cwd,
+}), { tool: "clippy", budgetMs: CLIPPY_PROBE_BUDGET_MS });
+const clippyAvailabilityByCargo = new Map();
 function getClippyProbe(cargoExe) {
-    const existing = clippyProbeByCargo.get(cargoExe);
-    if (existing)
-        return existing;
-    const created = probeClippy(cargoExe);
-    clippyProbeByCargo.set(cargoExe, created);
+    return clippyAvailabilityByCargo.get(cargoExe) ?? refreshClippyProbe(cargoExe);
+}
+/** Replace the cached probe so a post-install state is observed. */
+function refreshClippyProbe(cargoExe) {
+    const created = makeClippyProbe(cargoExe);
+    clippyAvailabilityByCargo.set(cargoExe, created);
     return created;
 }
 const rustClippyRunner = {
@@ -51,10 +54,35 @@ const rustClippyRunner = {
         }
         const clippyProbe = getClippyProbe(cargoExe);
         if (!(await clippyProbe(ctx.cwd))) {
+            // A timed-out probe is not evidence that clippy is missing, so it must
+            // not drive an install. Skip this turn and let the policy re-probe once
+            // its cooldown expires (#1494).
+            if (clippyProbe.getVerdict(ctx.cwd).outcome === "transient") {
+                return { status: "skipped", diagnostics: [], semantic: "none" };
+            }
             await tryLazyInstall("rust-clippy", ctx.cwd);
-            // Bust the cwd-keyed cache so the post-install state is observed.
-            clippyProbeByCargo.set(cargoExe, probeClippy(cargoExe));
-            if (!(await getClippyProbe(cargoExe)(ctx.cwd))) {
+            // Bust the cwd-keyed cache so the post-install state is observed. Held in
+            // a local: `refreshClippyProbe` REPLACES the cached probe, so calling it
+            // again to read the verdict would spend a second probe.
+            const refreshedProbe = refreshClippyProbe(cargoExe);
+            if (!(await refreshedProbe(ctx.cwd))) {
+                // #1537: clippy is still absent, and the interesting question is WHY —
+                // "we tried `rustup component add` and the network failed" is a
+                // different fact from "this machine has no rustup", and until now the
+                // lazy installers recorded neither. Put the attempt beside the verdict
+                // it produced (#1500), so a reader does not have to infer the install
+                // from a runner that silently skipped.
+                const verdict = refreshedProbe.getVerdict(ctx.cwd);
+                logAvailabilityDecision({
+                    tool: "rust-clippy",
+                    verdict: "unavailable",
+                    outcome: verdict.outcome ?? "missing",
+                    cause: verdict.cause ?? "not-found",
+                    classifiedBy: "caller",
+                    evidence: describeInstallAttempt(getLazyInstallAttempt("rust-clippy", ctx.cwd)),
+                    elapsedMs: 0,
+                    latched: false,
+                });
                 return { status: "skipped", diagnostics: [], semantic: "none" };
             }
         }
@@ -107,6 +135,49 @@ function findCargoToml(filePath) {
     const dir = findNearestContaining(dirname(filePath), ["Cargo.toml"]);
     return dir ? join(dir, "Cargo.toml") : undefined;
 }
+/**
+ * #1802 fix round: the original review claimed rustc/clippy's top-level
+ * `compiler-message.level` is genuinely two-valued (error/warning). A live
+ * `cargo clippy --message-format=json` repro falsified that: rustc_errors's
+ * `Level` serializes SIX values, and top-level messages with a real primary
+ * span are NOT limited to error/warning —
+ *
+ *   - `"error"` — a hard compiler/lint error.
+ *   - `"warning"` — the common clippy-lint case.
+ *   - `"note"` — DOES appear as a top-level message with a non-empty primary
+ *     span (repro: an erroneous-constant note pointing at the offending
+ *     expression), not only as a `message.children[].level` annotation.
+ *   - `"help"` — a top-level suggestion-carrying message.
+ *   - `"failure-note"` — observed with an empty `spans` array, so it is
+ *     already filtered out by the `if (!span) continue` guard below; no
+ *     diagnostic is ever built from it. Verified, not assumed.
+ *   - `"error: internal compiler error"` — an ICE. The old `level === "error"`
+ *     exact-match ternary silently mapped this to `"warning"`, because the
+ *     string doesn't equal `"error"` — an ICE must never be under-reported,
+ *     so it is normalized to `"error"` here explicitly.
+ *
+ * `note`/`help` don't have a `"blocking"`-worthy tier of their own in the
+ * four-valued `Diagnostic.severity`, so they land on the two quiet tiers:
+ * `note` → `hint`, `help` → `info`. Blocking stays derived from the
+ * *normalized* severity (not the raw string), which is what makes the ICE
+ * case blocking too instead of silently passing.
+ */
+export function normalizeClippyLevel(raw) {
+    if (raw === "error")
+        return "error";
+    if (typeof raw === "string" &&
+        raw.startsWith("error: internal compiler error")) {
+        return "error";
+    }
+    if (raw === "note")
+        return "hint";
+    if (raw === "help")
+        return "info";
+    // "warning", "failure-note" (unreachable here, see above), and anything
+    // unrecognized fall back to "warning" — the tier every clippy diagnostic
+    // reported at before this fix.
+    return "warning";
+}
 /**
  * Find a machine-applicable suggested replacement across the message's spans.
  * Clippy emits one diagnostic per warning but can attach the auto-fix to a
@@ -145,14 +216,21 @@ export function parseClippyOutput(raw, fallbackPath, cargoDir) {
                     ? resolve(cargoDir, rawFile)
                     : rawFile
                 : fallbackPath;
+            // #1802: preserve clippy's real six-level vocabulary instead of
+            // collapsing it. See `normalizeClippyLevel` above for the verified
+            // mapping and the repro that falsified the original "two-valued"
+            // claim. Blocking is derived from the NORMALIZED severity so an ICE
+            // (`"error: internal compiler error"`) is blocking too, not just an
+            // exact-match `"error"` string.
+            const normalizedSeverity = normalizeClippyLevel(message.level);
             diagnostics.push({
                 id: `clippy-${message.code?.code || "unknown"}`,
                 message: message.message || "Clippy warning",
                 filePath,
                 line: span.line_start || 0,
                 column: span.column_start || 0,
-                severity: message.level === "error" ? "error" : "warning",
-                semantic: message.level === "error" ? "blocking" : "warning",
+                severity: normalizedSeverity,
+                semantic: normalizedSeverity === "error" ? "blocking" : "warning",
                 tool: "rust-clippy",
                 rule: message.code?.code,
                 defectClass: "correctness",