@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

package/node_modules/pi-lens/dist/clients/formatters.js

@@ -9,6 +9,7 @@
  * Inspired by OpenCode's formatter.ts pattern
  */
 import { logExtension } from "./extension-log.js";
+import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { BoundedLruCache } from "./bounded-cache.js";
@@ -16,47 +17,26 @@ import { normalizeMapKey } from "./path-utils.js";
 import { TERRAGRUNT_FILENAMES } from "./file-kinds.js";
 import { detectIndentation, hasDetectableIndentation, } from "./dispatch/indent-detect.js";
 import { logLatency } from "./latency-logger.js";
-import { findGlobalBinary } from "./package-manager.js";
+import { classifyProbeFailure, createAvailabilityLatch, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
+import { findGlobalBinary, findLocalBinUpwards } from "./package-manager.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { assertInstallAllowed } from "./project-trust.js";
-import { getAutoInstallToolIdForFormatter, getFormatterPolicyForFile, getSmartDefaultFormatterName, hasBiomeConfig, hasBlackConfig, hasClangFormatConfig, hasCljfmtConfig, hasCmakeFormatConfig, hasGoogleJavaFormatConfig, hasKtfmtConfig, hasKtlintConfig, hasNearestPackageJsonDependency, hasNearestPackageJsonField, hasOcamlformatConfig, hasOxfmtConfig, hasOxfmtSvelteConfig, hasPhpCsFixerConfig, hasPrettierConfig, hasRubocopConfig, hasRuffConfig, hasSqlfluffConfig, hasStandardrbConfig, hasStyluaConfig, hasVitePlusConfig, OXFMT_SUPPORTED_EXTENSIONS, } from "./tool-policy.js";
-const _lazyInstallAttempts = new Set();
+import { tryLazyInstallForFormatter } from "./dispatch/runners/utils/lazy-installer.js";
+import { findPSScriptAnalyzerConfigPath, getAutoInstallToolIdForFormatter, getFormatterPolicyForFile, getSmartDefaultFormatterName, hasBiomeConfig, hasBlackConfig, hasClangFormatConfig, hasCljfmtConfig, hasCmakeFormatConfig, hasCsharpierConfig, hasFantomasConfig, hasGoogleJavaFormatConfig, hasKtfmtConfig, hasKtlintConfig, hasMixFormatConfig, hasNearestPackageJsonDependency, hasNearestPackageJsonField, hasOcamlformatConfig, hasOrmoluConfig, hasOxfmtConfig, hasOxfmtSvelteConfig, hasPhpCsFixerConfig, hasPrettierConfig, hasPSScriptAnalyzerConfig, hasRubocopConfig, hasRuffConfig, hasSqlfluffConfig, hasStandardrbConfig, hasStyluaConfig, hasSwiftformatConfig, hasTaploConfig, hasTerraformConfig, hasVitePlusConfig, OXFMT_SUPPORTED_EXTENSIONS, } from "./tool-policy.js";
+/**
+ * Lazy-install a formatter's tool, through the shared seam (#1537).
+ *
+ * This used to own a second copy of the attempt guard — `_lazyInstallAttempts`,
+ * a Set keyed before the install ran and never cleared — so a `gem install
+ * rubocop` that died on a network blip was never retried for the session. The
+ * state, the transient/durable classification and the retry ladder now live in
+ * `lazy-installer.ts`; what stays here is the one thing that is formatter
+ * business: a fresh binary on PATH invalidates every "not found" verdict (#1495).
+ */
 export async function tryLazyInstallFormatterTool(tool, cwd) {
-    if (!assertInstallAllowed(`formatter lazy install: ${tool}`))
-        return false;
-    const attemptKey = `${tool}:${cwd}`;
-    if (_lazyInstallAttempts.has(attemptKey))
-        return false;
-    _lazyInstallAttempts.add(attemptKey);
-    if (tool === "rubocop") {
-        const res = await safeSpawnAsync("gem", ["install", "rubocop", "--no-document"], {
-            timeout: 180000,
-            cwd,
-            ignoreAmbientSignal: true,
-        });
-        const ok = !res.error && res.status === 0;
-        if (!ok) {
-            logExtension({
-                subsystem: "format",
-                message: `lazy-install rubocop failed: ${res.error?.message ?? res.stderr ?? "exit " + res.status}`,
-                metadata: { tool: "rubocop", cwd },
-            });
-        }
-        return ok;
-    }
-    const res = await safeSpawnAsync("rustup", ["component", "add", "rustfmt"], {
-        timeout: 180000,
-        cwd,
-        ignoreAmbientSignal: true,
-    });
-    const ok = !res.error && res.status === 0;
-    if (!ok) {
-        logExtension({
-            subsystem: "format",
-            message: `lazy-install rustfmt failed: ${res.error?.message ?? res.stderr ?? "exit " + res.status}`,
-            metadata: { tool: "rustfmt", cwd },
-        });
-    }
+    const ok = await tryLazyInstallForFormatter(tool, cwd);
+    if (ok)
+        resetWhichLatches();
     return ok;
 }
 // --- Types ---
@@ -95,11 +75,236 @@ async function findUp(targets, startDir, stopDir = path.parse(startDir).root) {
     }
     return found;
 }
+const WHICH_BUDGET_MS = 5000;
+/**
+ * PATH lookups, governed by the shared availability policy (#1495).
+ *
+ * `which()` is a spawn on a 5 s budget, not a filesystem check, and around a
+ * dozen `detect*` implementations gate on it. A transient timeout used to drop
+ * the formatter AND get written to `detectionCache` as an empty enabled-list —
+ * a cache invalidated only by a config file's mtime or size, never by time. One
+ * stalled `which rustfmt` therefore disabled Rust formatting for the session
+ * unless the user happened to edit a config file.
+ *
+ * Now: only a genuine absence latches, a stall expires on a cooldown, and the
+ * detection pass refuses to cache an empty result a stall caused.
+ */
+const whichLatchByCommand = new Map();
+/**
+ * Commands whose CURRENT `which` verdict is transient — a probe that never got a
+ * fair hearing, still inside its cooldown.
+ *
+ * Scoped per command on purpose (#1495 review). The first cut counted transient
+ * verdicts process-wide and compared the count across a detection pass, which
+ * over-suppressed: one stalled `which rustfmt` stopped an unrelated Python or
+ * shell detection from caching, and stamped `reason: "probe-timeout"` on
+ * selections where nothing had timed out. A command leaves the set as soon as
+ * its verdict becomes trustworthy — a resolved path or a genuine absence.
+ */
+const whichTransientCommands = new Set();
+/**
+ * The binaries `which()` was asked about inside the current `detect()` call
+ * (#1539).
+ *
+ * This replaces the `command[0]` approximation the poison guard used to run on.
+ * `command[0]` is the formatter's own binary, which is exact for most
+ * `detect()`s and wrong for the ones that consult a second binary — and the
+ * "extras are harmless" argument does not hold: `rustfmt` answering a GENUINE
+ * absence while `which rustup` stalls skips the lazy install and leaves nothing
+ * in the transient set for `command[0]` to match. Recording the actual probes
+ * makes the guard exact in both directions: it also stops a leftover transient
+ * verdict for some other pass's binary from being blamed on this decision.
+ *
+ * `AsyncLocalStorage` because `detect()` is async and two selection passes can
+ * be in flight at once (`tests/clients/formatters-which-latch.test.ts` runs
+ * exactly that); a module-level set would let one pass's probes leak into the
+ * other's verdict. Built eagerly — unlike `extension-log.ts`'s lazy console
+ * capture, this store is entered on every detection pass, so there is no window
+ * where paying for it is avoidable.
+ */
+const probedCommandsStorage = new AsyncLocalStorage();
+/**
+ * Run one candidate's `detect()` and read the per-candidate verdict back out of
+ * the PATH latch (#1539). `detected` is the plain boolean the caller still needs
+ * for selection; `verdict` is why.
+ */
+async function detectCandidate(formatter, cwd) {
+    const probed = new Set();
+    let detected = false;
+    let error;
+    try {
+        detected = await probedCommandsStorage.run(probed, () => formatter.detect(cwd));
+    }
+    catch (err) {
+        // A `detect()` that threw still probed whatever it probed first, and those
+        // probes are the fact the guard needs. Swallowing them here would let a
+        // stall inside a throwing detection cache as a clean "not this project".
+        error = err;
+    }
+    const stalledCommands = [...probed].filter((command) => whichTransientCommands.has(command));
+    return {
+        detected,
+        ...(error !== undefined && { error }),
+        outcome: {
+            name: formatter.name,
+            verdict: detected
+                ? "available"
+                : stalledCommands.length > 0
+                    ? "unreachable"
+                    : "missing",
+            stalledCommands,
+        },
+    };
+}
+/**
+ * Drop the PATH verdicts, so a newly installed binary is visible at once.
+ *
+ * Module-private on purpose. Clearing the latches alone does NOT re-arm
+ * formatter availability: `getFormattersForFile` answers from `detectionCache`
+ * before it ever probes PATH, so a caller that wants a genuine re-probe must
+ * drop both. `clearFormatterCache` is that pair, and it is the only reset a
+ * session boundary should call (#1895 review round).
+ */
+function resetWhichLatches() {
+    whichLatchByCommand.clear();
+    whichTransientCommands.clear();
+    cooldownRecordedForRetryAtMs.clear();
+}
+/**
+ * Last `retryAtMs` a cooldown-served record was emitted for, per command.
+ *
+ * The bound (#1539): the memo branch used to return before
+ * `logAvailabilityDecision`, so a formatter held off by a transient cooldown
+ * produced ONE record for arbitrarily many decisions — a reader counting
+ * `availability_decision` rows undercounted how long it had been off. Logging
+ * every cache hit is not an option either: this seam is consulted per save.
+ * One extra row per cooldown WINDOW is the compromise, and `retryAtMs` is the
+ * window's identity, so the ladder itself does the rate limiting.
+ */
+const cooldownRecordedForRetryAtMs = new Map();
+/**
+ * Record that a still-cooling verdict was served from the latch, at most once
+ * per cooldown window (#1539's second defect).
+ */
+function noteCooldownServedVerdict(command, latch) {
+    if (latch.getOutcome() !== "transient")
+        return;
+    const retryAtMs = latch.getRetryAtMs();
+    if (retryAtMs <= 0)
+        return;
+    if (cooldownRecordedForRetryAtMs.get(command) === retryAtMs)
+        return;
+    cooldownRecordedForRetryAtMs.set(command, retryAtMs);
+    const cause = latch.getCause();
+    if (cause === null) {
+        // `getOutcome() === "transient"` is only ever set by `noteUnavailable` in
+        // the same call that sets `cause`, so this is unreachable today. It is
+        // still not a throw (#1539 review F2): this runs inside `which()`, which
+        // runs inside `detect()`, and the smart-default branch of the selection
+        // pass rethrows a detection failure — so an invariant break in a LOGGING
+        // helper could take down formatting for the file. Nothing is fabricated
+        // either (#1535's rule: a made-up cause would mislabel WHY a formatter is
+        // off, in the record this fix exists to make honest). The row is dropped
+        // and the anomaly is reported, bounded by the same once-per-window gate
+        // this function already passed.
+        logExtension({
+            subsystem: "format",
+            message: `which latch: transient outcome with no cause for ${command}; cooldown-served record dropped`,
+            metadata: { tool: command, retryAtMs },
+        });
+        return;
+    }
+    logAvailabilityDecision({
+        tool: command,
+        verdict: "unavailable",
+        outcome: "transient",
+        cause,
+        elapsedMs: 0,
+        latched: false,
+        retryAfterMs: Math.max(1, retryAtMs - Date.now()),
+        budgetMs: WHICH_BUDGET_MS,
+        servedFromCooldown: true,
+    });
+}
 async function which(command) {
-    const result = await safeSpawnAsync(process.platform === "win32" ? "where" : "which", [command], { timeout: 5000 });
-    if (result.error || result.status !== 0)
-        return null;
-    return result.stdout?.trim().split(/\r?\n/)[0] ?? null;
+    probedCommandsStorage.getStore()?.add(command);
+    let entry = whichLatchByCommand.get(command);
+    if (!entry) {
+        entry = { latch: createAvailabilityLatch(), resolved: null };
+        whichLatchByCommand.set(command, entry);
+    }
+    const memo = entry.latch.read();
+    if (memo !== null) {
+        if (!memo)
+            noteCooldownServedVerdict(command, entry.latch);
+        return memo ? entry.resolved : null;
+    }
+    const stallSampler = startHostStallSampler();
+    const startedAt = Date.now();
+    const result = await safeSpawnAsync(process.platform === "win32" ? "where" : "which", [command], { timeout: WHICH_BUDGET_MS });
+    const hostStallMs = stallSampler.stop();
+    const elapsedMs = Date.now() - startedAt;
+    const resolved = !result.error && result.status === 0
+        ? (result.stdout?.trim().split(/\r?\n/)[0] ?? null)
+        : null;
+    if (resolved) {
+        entry.resolved = resolved;
+        entry.latch.noteAvailable();
+        whichTransientCommands.delete(command);
+        cooldownRecordedForRetryAtMs.delete(command);
+        logAvailabilityDecision({
+            tool: command,
+            verdict: "available",
+            outcome: "success",
+            cause: "ok",
+            elapsedMs,
+            latched: true,
+            hostStallMs,
+            budgetMs: WHICH_BUDGET_MS,
+        });
+        return resolved;
+    }
+    entry.resolved = null;
+    // A `which`/`where` that RAN and found nothing exits nonzero with NO spawn
+    // error, and only that is a genuine absence an install would fix.
+    //
+    // An UNSPAWNABLE prober is the opposite (#1495 review): EACCES, `spawn
+    // UNKNOWN`, EMFILE, an unresolvable cwd, or `where`/`which` itself missing
+    // says nothing about the tool that was asked for. Claiming `missing` there
+    // was the worst version of this bug, because the prober is shared by every
+    // which-gated formatter — one EACCES would have latched a dozen of them off
+    // for the session. So the `missing` override is granted only to a prober that
+    // ran, and anything that stopped it from running stays transient.
+    const proberRan = !result.error;
+    const classified = classifyProbeFailure(result, {
+        hostStallMs,
+        ...(proberRan && { unclassifiedFailureOutcome: "missing" }),
+    });
+    let { outcome, cause } = classified;
+    if (!proberRan && outcome !== "transient") {
+        outcome = "transient";
+        cause = "probe-rejected";
+    }
+    const retryAfterMs = entry.latch.noteUnavailable(outcome, cause);
+    if (outcome === "transient")
+        whichTransientCommands.add(command);
+    else
+        whichTransientCommands.delete(command);
+    // A fresh probe opens a new cooldown window (or ends the cooldown), so the
+    // next cache hit is entitled to its own record.
+    cooldownRecordedForRetryAtMs.delete(command);
+    logAvailabilityDecision({
+        tool: command,
+        verdict: "unavailable",
+        outcome,
+        cause,
+        elapsedMs,
+        latched: retryAfterMs === 0,
+        hostStallMs,
+        ...(retryAfterMs > 0 && { retryAfterMs }),
+        budgetMs: WHICH_BUDGET_MS,
+    });
+    return null;
 }
 async function resolveGoFmtBinary() {
     const inPath = await which("gofmt");
@@ -214,61 +419,85 @@ async function resolveManagedSmartDefaultCommand(formatterName, filePath, args)
         return null;
     return [installed, ...args, filePath];
 }
-function hasExplicitFormatterConfig(formatterName, cwd, ext) {
-    switch (formatterName) {
-        case "biome":
-            return hasBiomeConfig(cwd);
-        case "prettier":
-            return (hasPrettierConfig(cwd) || hasNearestPackageJsonField(cwd, "prettier"));
-        case "oxfmt":
-            // .svelte is conditional beyond "an oxfmt config exists": oxfmt
-            // requires the `svelte` package installed AND the config's `svelte`
-            // flag enabled (verified empirically — see hasOxfmtSvelteConfig).
-            // The generic checks below are NOT sufficient for .svelte — an
-            // oxfmt.toml with no svelte flag, or an oxfmt dependency alone,
-            // both fail at runtime for .svelte specifically (other extensions
-            // are unaffected by this stricter gate).
-            if (ext === ".svelte") {
-                return hasOxfmtSvelteConfig(cwd);
-            }
-            return (hasOxfmtConfig(cwd) ||
+/**
+ * One entry per formatter that can be selected via explicit project config
+ * (the `formatterPolicy` "explicit-config" branch of `getFormattersForFile`).
+ * A formatter with NO entry here can never win that branch — the switch this
+ * table replaced had exactly that failure mode for `psscriptanalyzer-format`
+ * (#1572: `.ps1`'s policy sets `defaultWhenUnconfigured: false` AND the
+ * formatter had no config check, so neither selection branch could ever pick
+ * it).
+ *
+ * This table IS the source of truth for "which formatters have an explicit-
+ * config check" — `FORMATTERS_WITH_EXPLICIT_CONFIG_CHECK` below derives its
+ * membership from these keys rather than hand-listing them a second time, so
+ * the coverage guard in formatter-policy-consistency.test.ts (#1572) can never
+ * drift from what this function actually does.
+ */
+// A `Map`, not an object literal: an object literal's lookup inherits
+// `Object.prototype`, so `checks["toString"]` or `checks["constructor"]`
+// resolves to a real (non-formatter) function instead of `undefined` —
+// a formatter genuinely NAMED one of those prototype properties would read
+// as "has an explicit-config check" when it has none (review finding, #1572).
+// `Map.prototype.get` has no such inherited-key hazard.
+const EXPLICIT_FORMATTER_CONFIG_CHECKS = new Map([
+    ["biome", (cwd) => hasBiomeConfig(cwd)],
+    [
+        "prettier",
+        (cwd) => hasPrettierConfig(cwd) || hasNearestPackageJsonField(cwd, "prettier"),
+    ],
+    // .svelte is conditional beyond "an oxfmt config exists": oxfmt requires the
+    // `svelte` package installed AND the config's `svelte` flag enabled
+    // (verified empirically — see hasOxfmtSvelteConfig). The generic checks
+    // below are NOT sufficient for .svelte — an oxfmt.toml with no svelte flag,
+    // or an oxfmt dependency alone, both fail at runtime for .svelte
+    // specifically (other extensions are unaffected by this stricter gate).
+    [
+        "oxfmt",
+        (cwd, ext) => ext === ".svelte"
+            ? hasOxfmtSvelteConfig(cwd)
+            : hasOxfmtConfig(cwd) ||
                 hasVitePlusConfig(cwd) ||
                 // The published package is `oxfmt`; `@oxc-project/oxfmt` does not
                 // exist on npm. Accept both (scoped kept for forward-compat).
                 hasNearestPackageJsonDependency(cwd, "oxfmt") ||
-                hasNearestPackageJsonDependency(cwd, "@oxc-project/oxfmt"));
-        case "ruff":
-            return hasRuffConfig(cwd);
-        case "black":
-            return hasBlackConfig(cwd);
-        case "sqlfluff":
-            return hasSqlfluffConfig(cwd);
-        case "rubocop":
-            return hasRubocopConfig(cwd);
-        case "standardrb":
-            return hasStandardrbConfig(cwd);
-        case "clang-format":
-            return hasClangFormatConfig(cwd);
-        case "php-cs-fixer":
-            return hasPhpCsFixerConfig(cwd);
-        case "stylua":
-            return hasStyluaConfig(cwd);
-        case "ocamlformat":
-            return hasOcamlformatConfig(cwd);
-        case "google-java-format":
-            return hasGoogleJavaFormatConfig(cwd);
-        case "ktfmt":
-            return hasKtfmtConfig(cwd);
-        case "ktlint":
-            return hasKtlintConfig(cwd);
-        case "cljfmt":
-            return hasCljfmtConfig(cwd);
-        case "cmake-format":
-            return hasCmakeFormatConfig(cwd);
-        default:
-            return false;
-    }
+                hasNearestPackageJsonDependency(cwd, "@oxc-project/oxfmt"),
+    ],
+    ["ruff", (cwd) => hasRuffConfig(cwd)],
+    ["black", (cwd) => hasBlackConfig(cwd)],
+    ["sqlfluff", (cwd) => hasSqlfluffConfig(cwd)],
+    ["rubocop", (cwd) => hasRubocopConfig(cwd)],
+    ["standardrb", (cwd) => hasStandardrbConfig(cwd)],
+    ["clang-format", (cwd) => hasClangFormatConfig(cwd)],
+    ["php-cs-fixer", (cwd) => hasPhpCsFixerConfig(cwd)],
+    ["stylua", (cwd) => hasStyluaConfig(cwd)],
+    ["ocamlformat", (cwd) => hasOcamlformatConfig(cwd)],
+    ["google-java-format", (cwd) => hasGoogleJavaFormatConfig(cwd)],
+    ["ktfmt", (cwd) => hasKtfmtConfig(cwd)],
+    ["ktlint", (cwd) => hasKtlintConfig(cwd)],
+    ["cljfmt", (cwd) => hasCljfmtConfig(cwd)],
+    ["cmake-format", (cwd) => hasCmakeFormatConfig(cwd)],
+    ["psscriptanalyzer-format", (cwd) => hasPSScriptAnalyzerConfig(cwd)],
+    // #1595 sweep — see the comment above hasCsharpierConfig et al. in
+    // tool-policy.ts for why nixfmt (the 8th formatter #1572 flagged) is NOT
+    // wired here: it has no config-file convention and no manifest-marker
+    // equivalent to `.terraform.lock.hcl`, so there is no honest opt-in signal.
+    ["csharpier", (cwd) => hasCsharpierConfig(cwd)],
+    ["ormolu", (cwd) => hasOrmoluConfig(cwd)],
+    ["taplo", (cwd) => hasTaploConfig(cwd)],
+    ["terraform", (cwd) => hasTerraformConfig(cwd)],
+    ["swiftformat", (cwd) => hasSwiftformatConfig(cwd)],
+    ["fantomas", (cwd) => hasFantomasConfig(cwd)],
+    ["mix", (cwd) => hasMixFormatConfig(cwd)],
+]);
+function hasExplicitFormatterConfig(formatterName, cwd, ext) {
+    return EXPLICIT_FORMATTER_CONFIG_CHECKS.get(formatterName)?.(cwd, ext) ?? false;
 }
+// Exported for the "every registered formatter is selectable" coverage guard
+// (formatter-policy-consistency.test.ts, #1572): derived from the table above,
+// not hand-listed, so it cannot drift from what `hasExplicitFormatterConfig`
+// actually checks.
+export const FORMATTERS_WITH_EXPLICIT_CONFIG_CHECK = new Set(EXPLICIT_FORMATTER_CONFIG_CHECKS.keys());
 // --- Formatter Definitions ---
 async function hasEditorConfig(cwd) {
     try {
@@ -851,8 +1080,17 @@ export const styluaFormatter = {
     name: "stylua",
     command: ["stylua", "$FILE"],
     extensions: [".lua"],
+    async resolveCommand(filePath, cwd) {
+        // Project binary first (#1731, discipline B): stylua has no pi-lens
+        // managed install, so before this the ONLY resolution was a bare
+        // `stylua` PATH lookup — a project-local install via npm
+        // `@johnnymorganz/stylua` (`node_modules/.bin/stylua`) was invisible.
+        const local = findLocalBinUpwards("stylua", cwd);
+        return local ? [local, filePath] : null;
+    },
     async detect(cwd) {
-        if ((await which("stylua")) === null)
+        const local = findLocalBinUpwards("stylua", cwd);
+        if (!local && (await which("stylua")) === null)
             return false;
         // Prefer explicit config but also run if binary is present in a Lua project
         const configs = ["stylua.toml", ".stylua.toml"];
@@ -915,6 +1153,18 @@ export const cmakeFormatFormatter = {
         return hasCmakeFormatConfig(cwd);
     },
 };
+export const cueFormatter = {
+    name: "cue",
+    // `cue fmt <file>` rewrites in place already. There is no `-w`: the only
+    // flags are --check, -d/--diff and --files, so `cue fmt -w` aborts with
+    // "unknown shorthand flag: 'w'" on every .cue write (verified on cue
+    // v0.17.1).
+    command: ["cue", "fmt", "$FILE"],
+    extensions: [".cue"],
+    async detect(_cwd) {
+        return (await which("cue")) !== null;
+    },
+};
 /**
  * The PowerShell one-liner behind `psscriptanalyzer-format`.
  *
@@ -930,16 +1180,25 @@ export const cmakeFormatFormatter = {
  *  - single-quoted interpolation broke on any path containing an apostrophe.
  * An empty/whitespace-only file exits 0 without touching anything, so "nothing
  * to format" stays a clean no-op rather than a reported failure.
+ *
+ * `settingsPath`, when the project has one (#1572 review F2), is passed
+ * straight to `Invoke-Formatter -Settings`. Gating selection on the file's
+ * presence without ever reading its rules would run the project through the
+ * stock `CodeFormatting` ruleset regardless of what it declared — the same
+ * stock-style imposition #1144 banned for the other config-first formatters.
  */
-function psScriptAnalyzerCommand(filePath) {
+function psScriptAnalyzerCommand(filePath, settingsPath) {
     // PowerShell single-quoted strings escape an apostrophe by doubling it.
     const quoted = filePath.replace(/'/g, "''");
+    const settingsArg = settingsPath
+        ? ` -Settings '${settingsPath.replace(/'/g, "''")}'`
+        : "";
     return [
         "$ErrorActionPreference = 'Stop'",
         `$p = '${quoted}'`,
         "$content = Get-Content -Raw -LiteralPath $p",
         "if ([string]::IsNullOrWhiteSpace($content)) { exit 0 }",
-        "$formatted = Invoke-Formatter -ScriptDefinition $content",
+        `$formatted = Invoke-Formatter -ScriptDefinition $content${settingsArg}`,
         "if ($null -eq $formatted) { throw 'Invoke-Formatter returned no output' }",
         "Set-Content -LiteralPath $p -Value $formatted",
     ].join("; ");
@@ -948,11 +1207,17 @@ export const psscriptanalyzerFormatFormatter = {
     name: "psscriptanalyzer-format",
     command: ["pwsh", "-NoProfile", "-Command", psScriptAnalyzerCommand("$FILE")],
     extensions: [".ps1", ".psm1", ".psd1"],
-    async resolveCommand(filePath, _cwd) {
+    async resolveCommand(filePath, cwd) {
         const pwsh = (await which("pwsh")) ?? (await which("powershell"));
         if (!pwsh)
             return null;
-        return [pwsh, "-NoProfile", "-Command", psScriptAnalyzerCommand(filePath)];
+        const settingsPath = findPSScriptAnalyzerConfigPath(cwd);
+        return [
+            pwsh,
+            "-NoProfile",
+            "-Command",
+            psScriptAnalyzerCommand(filePath, settingsPath),
+        ];
     },
     async detect(_cwd) {
         const pwsh = (await which("pwsh")) ?? (await which("powershell"));
@@ -1005,6 +1270,7 @@ export const ALL_FORMATTERS = [
     googleJavaFormatFormatter,
     cljfmtFormatter,
     cmakeFormatFormatter,
+    cueFormatter,
     psscriptanalyzerFormatFormatter,
 ];
 // Basenames claimed by a filename-keyed formatter, e.g. terragrunt.hcl.
@@ -1013,17 +1279,35 @@ const FILENAME_FORMATTER_BASENAMES = new Set(ALL_FORMATTERS.flatMap((f) => f.fil
 const detectionCache = new BoundedLruCache(32);
 // These are the formatter configuration files consulted by the policy helpers
 // above. Their metadata is part of detection cache identity: changing a file
-// must re-run detection even when PATH and installed tools are unchanged.
+// must re-run detection even when PATH and installed tools are unchanged. A
+// filename a `has*Config` check reads but this list omits is invisible to the
+// cache: the signature never moves when that file is added, so a project that
+// opts in AFTER the first `getFormattersForFile` call for its cwd keeps
+// getting the stale (pre-opt-in) cached answer for the rest of the session
+// (#1572 review F1 — proved for psscriptanalyzer-format's settings file;
+// swept against every `EXPLICIT_FORMATTER_CONFIG_CHECKS` entry below, which
+// turned up the same gap for google-java-format, cljfmt, cmake-format, the
+// Kotlin/Spotless gradle files, sqlfluff's setup.cfg, and oxfmt's
+// vite-plus.json / additional vite.config extensions).
 const FORMATTER_CONFIG_FILES = [
     "package.json", "biome.json", "biome.jsonc", ".prettierrc", ".prettierrc.json",
     ".prettierrc.yml", ".prettierrc.yaml", ".prettierrc.js", ".prettierrc.cjs",
     ".prettierrc.mjs", "prettier.config.js", "prettier.config.cjs", "prettier.config.mjs",
     "prettier.config.ts", "pyproject.toml", "ruff.toml", ".ruff.toml", "black.toml",
-    ".black", "tox.ini", "requirements.txt", "Pipfile", ".sqlfluff", ".rubocop.yml", ".rubocop.yaml", "Gemfile", ".clang-format",
+    ".black", "tox.ini", "setup.cfg", "requirements.txt", "Pipfile", ".sqlfluff", ".rubocop.yml", ".rubocop.yaml", "Gemfile", ".clang-format",
     "_clang-format", ".php-cs-fixer.php", ".php-cs-fixer.dist.php", "stylua.toml",
-    ".stylua.toml", ".ocamlformat", ".editorconfig", ".ktfmt", ".ktfmt.kts",
-    ".cljfmt.edn", "cmake-format.py", ".cmake-format.yaml", ".cmake-format.json",
-    "oxfmt.toml", ".oxfmtrc.json", "vite.config.ts", "vite.config.js", "vite.config.mjs",
+    ".stylua.toml", ".ocamlformat", ".editorconfig", ".google-java-format",
+    ".ktfmt", ".ktfmt.kts", "build.gradle.kts", "build.gradle", "settings.gradle.kts", "settings.gradle",
+    ".cljfmt.edn", "cljfmt.edn", ".cljfmt",
+    ".cmake-format", ".cmake-format.yaml", ".cmake-format.yml", ".cmake-format.json", ".cmake-format.py",
+    "cmake-format.py", "cmake-format.yaml", "cmake-format.yml",
+    "oxfmt.toml", ".oxfmtrc.json", "vite-plus.json",
+    "vite.config.ts", "vite.config.mts", "vite.config.cts", "vite.config.js", "vite.config.mjs", "vite.config.cjs",
+    "PSScriptAnalyzerSettings.psd1", "ScriptAnalyzerSettings.psd1",
+    // #1595 sweep additions.
+    ".csharpierrc", ".csharpierrc.json", ".csharpierrc.yaml", ".csharpierrc.yml",
+    ".ormolu", "taplo.toml", ".taplo.toml", ".terraform.lock.hcl", ".swiftformat",
+    ".fantomasignore", ".formatter.exs",
 ];
 async function formatterConfigSignature(cwd) {
     const paths = await findUp(FORMATTER_CONFIG_FILES, cwd);
@@ -1054,9 +1338,16 @@ export async function getFormattersForFile(filePath, cwd) {
     const configSignature = await formatterConfigSignature(cwd);
     // Check cache
     let cached = detectionCache.get(normalizedCwd);
-    if (cached?.signature !== configSignature) {
-        cached = undefined;
+    if (cached && cached.signature !== configSignature) {
+        // An EXISTING entry whose signature moved is the user telling us the world
+        // changed. Re-probe PATH too, so "install the tool, touch the config" still
+        // works within one session now that a durable absence latches (#1495).
+        // Scoped to a real change on purpose: keying this off "no entry yet" would
+        // drop every PATH verdict on the first save in each new directory, which in
+        // a monorepo means re-probing forever.
         detectionCache.delete(normalizedCwd);
+        cached = undefined;
+        resetWhichLatches();
     }
     if (!cached) {
         cached = { signature: configSignature, entries: new Map() };
@@ -1077,6 +1368,13 @@ export async function getFormattersForFile(filePath, cwd) {
         ? matching.filter((f) => formatterPolicy.formatterNames.includes(f.name))
         : matching;
     let selected;
+    /**
+     * One entry per candidate this pass actually ASKED, in the order it asked
+     * them (#1539). Candidates eliminated without a probe — an explicit-config
+     * decision is pure filesystem — contribute nothing, which is the point: a
+     * decision that never probed cannot have been degraded by a probe.
+     */
+    const candidateOutcomes = [];
     if (formatterPolicy) {
         const explicitlyConfigured = candidateFormatters.filter((formatter) => hasExplicitFormatterConfig(formatter.name, cwd, ext));
         if (explicitlyConfigured.length > 0) {
@@ -1093,33 +1391,93 @@ export async function getFormattersForFile(filePath, cwd) {
             const smartDefaultFormatter = candidateFormatters.find((f) => f.name === smartDefaultFormatterName);
             if (smartDefaultFormatter) {
                 const autoInstallToolId = getAutoInstallToolIdForFormatter(smartDefaultFormatter.name);
-                if (autoInstallToolId || (await smartDefaultFormatter.detect(cwd))) {
+                if (autoInstallToolId) {
                     selected = smartDefaultFormatter;
                 }
+                else {
+                    const { detected, error, outcome } = await detectCandidate(smartDefaultFormatter, cwd);
+                    candidateOutcomes.push(outcome);
+                    // This branch never caught a throwing detection, and still
+                    // does not: `detectCandidate` catches only so the probes survive.
+                    if (error !== undefined)
+                        throw error;
+                    if (detected)
+                        selected = smartDefaultFormatter;
+                }
             }
         }
     }
     else {
         for (const formatter of candidateFormatters) {
-            try {
-                if (await formatter.detect(cwd)) {
-                    selected = formatter;
-                    break;
-                }
-            }
-            catch (err) {
+            const { detected, error, outcome } = await detectCandidate(formatter, cwd);
+            candidateOutcomes.push(outcome);
+            if (error !== undefined) {
                 // pi-lens-ignore: missing-error-propagation — optional formatter detection, skip on failure
                 logExtension({
                     subsystem: "format",
-                    message: `Detection failed for ${formatter.name}: ${err instanceof Error ? err.message : String(err)}`,
+                    message: `Detection failed for ${formatter.name}: ${error instanceof Error ? error.message : String(error)}`,
                     metadata: { formatter: formatter.name, cwd },
                 });
+                continue;
+            }
+            if (detected) {
+                selected = formatter;
+                break;
             }
         }
     }
     const enabled = selected ? [selected] : [];
+    // The #925/#1467 `wouldPoisonCache` shape: an empty result produced while a
+    // PATH probe was timing out is not a finding about this project. Caching it
+    // would survive until a config file's mtime or size changed, so leave the
+    // cache untouched and let the next turn re-detect.
+    // Which of THIS file's candidates are currently un-answered? Read off the
+    // binaries the candidates' own `detect()`s actually probed (#1539), so a
+    // stalled `which rustfmt` cannot stop a shell or Python detection from
+    // caching (#1495 review) AND a leftover transient verdict for a binary this
+    // pass never consulted cannot be blamed on this decision.
+    //
+    // This replaces the `command[0]` approximation, which missed both shapes of
+    // extra probe: a co-equal ALTERNATIVE (`pwsh` ?? `powershell`) and — the
+    // case the old comment wrongly called harmless — an install FALLBACK reached
+    // after the primary answered a GENUINE absence. `rustfmt` missing plus a
+    // stalled `which rustup` skips the lazy install, and nothing named `rustfmt`
+    // is transient, so the empty result used to cache for the session.
+    //
+    // Residual: the record covers this module's own `which()` only. A detection
+    // that reaches PATH some other way is invisible to it — ktlint's `detect()`
+    // falls back to the installer's `getToolPath("ktlint")`, which has its own
+    // probe and its own 24-hour cache. Widening the record to those is deferred to
+    // the installer-side follow-up rather than bolted on here.
+    const stalledCandidateCommands = [
+        ...new Set(candidateOutcomes.flatMap((outcome) => outcome.stalledCommands)),
+    ];
+    const poisonedByTransientProbe = enabled.length === 0 && stalledCandidateCommands.length > 0;
+    // A NON-empty result the poison guard cannot see (#1539): the winner won only
+    // because a candidate ahead of it was never asked. `candidateOutcomes` is in
+    // ask order and the loop stops at the winner, so every entry before the
+    // winner's is a candidate that lost — and an `unreachable` one did not lose
+    // on the merits. Caching this would hand the session to the runner-up until
+    // a config file's mtime or size changed.
+    const winnerIndex = selected
+        ? candidateOutcomes.findIndex((outcome) => outcome.name === selected.name)
+        : -1;
+    const unreachablePreferred = candidateOutcomes
+        .slice(0, winnerIndex === -1 ? 0 : winnerIndex)
+        .filter((outcome) => outcome.verdict === "unreachable")
+        .map((outcome) => outcome.name);
+    const degradedSelection = unreachablePreferred.length > 0;
     let selectionReason;
-    if (!selected) {
+    if (poisonedByTransientProbe) {
+        selectionReason = "probe-timeout";
+    }
+    else if (degradedSelection) {
+        // The reason now describes how the winner WON, not just what the config
+        // looks like. "explicit-config" on a selection whose preferred candidate
+        // was never reachable was the most misleading record in this seam.
+        selectionReason = "preferred-unreachable";
+    }
+    else if (!selected) {
         selectionReason = "none";
     }
     else if (!formatterPolicy) {
@@ -1130,6 +1488,7 @@ export async function getFormattersForFile(filePath, cwd) {
             ? "explicit-config"
             : "smart-default";
     }
+    const provisional = poisonedByTransientProbe || degradedSelection;
     logLatency({
         type: "phase",
         phase: "formatter_selected",
@@ -1139,19 +1498,45 @@ export async function getFormattersForFile(filePath, cwd) {
             formatter: selected?.name ?? null,
             reason: selectionReason,
             cwd,
+            ...(provisional && {
+                cached: false,
+                stalledProbes: stalledCandidateCommands,
+            }),
+            ...(degradedSelection && { unreachablePreferred }),
         },
     });
+    // Provisional either way: not cached, so the next pass re-detects once the
+    // cooldown expires and the preferred formatter's recovery takes effect
+    // without waiting on a config-file edit.
+    if (provisional)
+        return enabled;
     // Store the list of enabled formatter names in cache
     const enabledNames = enabled.map((f) => f.name);
     cached.entries.set(cacheKey, enabledNames);
     return enabled;
 }
+/**
+ * Re-arm formatter availability: drop both the per-cwd selection cache and the
+ * PATH latches.
+ *
+ * #1895: this is the session-boundary reset. Both halves are required. The
+ * latches decide whether `which` runs at all, but `detectionCache` short-
+ * circuits ahead of them — a same-cwd lookup returns the previous verdict's
+ * formatter names without reaching a probe. Clearing only the latches
+ * therefore re-arms every directory EXCEPT the one the user is working in.
+ */
 export function clearFormatterCache() {
     detectionCache.clear();
+    resetWhichLatches();
 }
 export function clearFormatterRuntimeState() {
     detectionCache.clear();
-    _lazyInstallAttempts.clear();
+    resetWhichLatches();
+    // NO `resetLazyInstallAttempts()` here (#1537 review F1). This function runs
+    // from `resetFormatService()`, which `handleTurnEnd` calls every turn — so
+    // clearing the lazy-install hold here made "held for the session" mean "held
+    // for a turn", and a failing install re-ran every turn. The hold's only reset
+    // is `session_start`'s block in runtime-session.ts.
 }
 // ESC is built via fromCharCode so no raw control byte sits in the source.
 const ANSI_ESCAPE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*[A-Za-z]`, "g");