@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

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

@@ -11,15 +11,16 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { logSessionStart } from "../../../sessionstart-logger.js";
 import { getGlobalPiLensDir } from "../../../file-utils.js";
+import { createGenerationSource, } from "../../../generation-guard.js";
 import { PathKeyedMap } from "../../../path-keyed-map.js";
 import { normalizeEphemeralMapKey, normalizeMapKey, } from "../../../path-utils.js";
-import { ensureTool, isSpawnableCommand, resetPathWalkMemo, } from "../../../installer/index.js";
+import { ensureTool, getInstallAttempt, getLastEnsureResolutionSource, getToolInstallStrategy, isSpawnableCommand, resetPathWalkMemo, } from "../../../installer/index.js";
 import { getServersForFileWithConfig, isServerDisabled, } from "../../../lsp/config.js";
 import { findGlobalBinary } from "../../../package-manager.js";
 import { safeSpawnAsync } from "../../../safe-spawn.js";
 import { getToolCommandSpec, shouldAutoInstallTool, } from "../../../tool-policy.js";
-import { classifyProbeFailure, createAvailabilityLatch, isLatchingOutcome, logAvailabilityDecision, startHostStallSampler, transientRetryDelayMs, } from "./availability-policy.js";
-export { createAvailabilityLatch, classifyProbeFailure, describeUnavailability, isTransientDecision, logAvailabilityDecision, startHostStallSampler, } from "./availability-policy.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";
 /**
  * True when the LSP runner will cover `ctx.filePath` via the given PRIMARY server
  * id. Used by CLI runners that duplicate a linter a warm LSP already wraps
@@ -67,34 +68,176 @@ if (typeof __dirname !== "undefined") {
 // Managed tools directory (~/.pi-lens/tools) — where ensureTool() installs binaries
 const _managedToolsDir = path.join(getGlobalPiLensDir(), "tools");
 /**
- * The managed shim for a Node CLI tool (`~/.pi-lens/tools/node_modules/.bin/<tool>`),
- * or null when it is not on disk.
- *
- * When the shim exists the tool IS installed, so availability needs no spawn at
- * all — and a spawn that cannot happen cannot time out (#1467). knip and jscpd
- * each carried a line-for-line copy of this resolver; #1476 folds them into one
- * definition so the next managed tool inherits the fast path instead of a
- * fourth copy.
+ * Managed-shim candidates for a Node CLI tool, in the installer's own
+ * preference order (`getToolPath`'s managed-first branch: `.cmd`, then `.exe`,
+ * then extensionless on Windows; extensionless elsewhere).
  *
  * The pi-lens dir is read per call, never memoized at module load, so tests that
  * point `getGlobalPiLensDir` at a temp home still see their own tree.
  */
-export function findManagedNodeToolBinary(tool) {
+function managedNodeToolCandidates(tool) {
     const base = path.join(getGlobalPiLensDir(), "tools", "node_modules", ".bin", tool);
-    const candidates = process.platform === "win32" ? [`${base}.cmd`, `${base}.exe`, base] : [base];
+    return process.platform === "win32"
+        ? [`${base}.cmd`, `${base}.exe`, base]
+        : [base];
+}
+/**
+ * Verification verdicts for managed shims, keyed by path + mtime + size, so a
+ * reinstall re-verifies and a session start re-arms.
+ *
+ * A plain `Map`, not a `PathKeyedMap`: `managedNodeToolCandidates` is the ONLY
+ * producer of these paths, so the write and read forms are the same string by
+ * construction and cannot diverge on case or separator.
+ */
+const managedBinaryVerdicts = new Map();
+/**
+ * Verifications in progress, keyed the same way. Concurrent first touches of
+ * one shim share the single probe instead of each spawning their own — the
+ * same in-flight-share shape `resolveInstallInFlightByCwd` uses for installs
+ * (#1674 review F2).
+ */
+const managedVerifyInFlight = new Map();
+/**
+ * Budget for the managed-shim verification spawn.
+ *
+ * 5s, not the checker's default probe budget: a cold npm shim on a cold file
+ * cache measured just over 2s in the #1674 review, so a tighter budget spends
+ * the whole wait and still learns nothing. This runs once per shim per session
+ * on the success path, and the installer's own verification keeps its more
+ * generous 10s.
+ */
+const MANAGED_VERIFY_TIMEOUT_MS = 5000;
+/** First cooldown after a verification that never got a fair run. */
+const MANAGED_VERIFY_COOLDOWN_MS = 60_000;
+/**
+ * Ceiling for the cooldown ladder — a shim that keeps stalling is still
+ * re-probed every 15 minutes.
+ */
+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) {
+    let transient = false;
+    let ok;
     try {
-        return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+        const { verifyToolBinary } = await import("../../../installer/index.js");
+        ok = await verifyToolBinary(candidate, undefined, () => {
+            transient = true;
+        }, MANAGED_VERIFY_TIMEOUT_MS);
     }
     catch {
-        return null;
+        // The verifier itself could not run — installer-isolated unit tests mock
+        // this module without it, and a throw here says nothing about the shim.
+        // "Cannot verify" is not "broken": keep the on-disk answer.
+        transient = true;
+        ok = false;
+    }
+    // An unspawnable prober is never a durable verdict (#1569): a timeout or a
+    // spawn-boundary failure says nothing about the shim, so it never demotes
+    // the candidate. It IS remembered, under a cooldown, so the wait is paid
+    // once per window rather than on every resolve (#1674 review F1).
+    // A verification that straddles a session boundary answers ITS caller, but
+    // its verdict belongs to the session that asked. Writing it into the fresh
+    // session would hand the new session the old one's cooldown — the exact
+    // re-arm this state clears at `session_start` (#1674 review F5). Same guard
+    // the install seam's in-flight share uses.
+    if (!ok && transient) {
+        const attempts = priorAttempts + 1;
+        generation.guardedWrite(stamp, () => {
+            managedBinaryVerdicts.set(stamp, {
+                verdict: "unverified",
+                attempts,
+                retryAtMs: Date.now() + managedVerifyCooldownMs(attempts),
+            });
+        });
+        return "unverified";
     }
+    generation.guardedWrite(stamp, () => {
+        managedBinaryVerdicts.set(stamp, { verdict: ok ? "ok" : "broken" });
+    });
+    if (!ok) {
+        // Once per shim per session, at the moment the verdict is reached — the
+        // memo answers every later call, so this cannot become per-dispatch spam.
+        logSessionStart(`dispatch availability: managed shim ${candidate} exists but does not run; falling through to PATH`);
+    }
+    return ok ? "ok" : "broken";
 }
+async function verifyManagedCandidate(candidate) {
+    let stamp;
+    try {
+        const stat = fs.statSync(candidate);
+        stamp = `${candidate}:${stat.mtimeMs}:${stat.size}`;
+    }
+    catch {
+        return "absent";
+    }
+    const memo = managedBinaryVerdicts.get(stamp);
+    let priorAttempts = 0;
+    if (memo) {
+        if (memo.verdict !== "unverified")
+            return memo.verdict;
+        if (Date.now() < memo.retryAtMs)
+            return "unverified";
+        priorAttempts = memo.attempts;
+    }
+    const existing = managedVerifyInFlight.get(stamp);
+    if (existing)
+        return existing;
+    const generation = availabilityGeneration.capture();
+    const probe = runManagedVerification(candidate, stamp, priorAttempts, generation).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, () => {
+            if (managedVerifyInFlight.get(stamp) === probe) {
+                managedVerifyInFlight.delete(stamp);
+            }
+        });
+    });
+    managedVerifyInFlight.set(stamp, probe);
+    return probe;
+}
+/**
+ * The managed shim for a Node CLI tool (`~/.pi-lens/tools/node_modules/.bin/<tool>`),
+ * or null when no candidate on disk actually runs.
+ *
+ * Verification uses the installer's own `verifyToolBinary`, the same check its
+ * managed-first branch runs before returning a managed path. A bare
+ * `existsSync` let a broken shim shadow a working PATH binary — the on-disk
+ * file wins the race and then fails every spawn behind it (#1657). knip and
+ * jscpd each carried a line-for-line copy of this resolver; #1476 folds them
+ * into one definition so the next managed tool inherits the fast path instead
+ * of a fourth copy.
+ *
+ * A settled verdict is memoized per file identity for the session, so the fast
+ * path answers without a spawn after the first call (#1467). A probe that
+ * cannot run keeps the optimistic answer rather than turning a stall into a
+ * "missing tool", and is memoized under a bounded cooldown ladder so the wait
+ * is paid once per window instead of on every resolve — while a shim that
+ * 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) {
+    for (const candidate of managedNodeToolCandidates(tool)) {
+        const verdict = await verifyManagedCandidate(candidate);
+        if (verdict === "ok" || verdict === "unverified")
+            return candidate;
+    }
+    return null;
+}
+// =============================================================================
+// VENV-AWARE COMMAND FINDER
+// =============================================================================
 /**
  * Find a command in venv first, then fall back to global.
  * Checks common venv locations (.venv, venv) before trying global.
+ *
+ * The resolved path is returned verbatim: every spawn consumer runs with
+ * `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 = "", quoteWindows = false) {
-    return (cwd) => {
+export function createVenvFinder(command, windowsExt = "") {
+    return async (cwd) => {
         const venvPaths = [
             `.venv/bin/${command}`,
             `venv/bin/${command}`,
@@ -104,9 +247,22 @@ export function createVenvFinder(command, windowsExt = "", quoteWindows = false)
         for (const venvPath of venvPaths) {
             const fullPath = path.join(cwd, venvPath);
             if (fs.existsSync(fullPath)) {
-                return quoteWindows && windowsExt ? `"${fullPath}"` : fullPath;
+                return fullPath;
             }
         }
+        // Managed-dir install (~/.pi-lens/tools/node_modules/.bin/<command>) — the
+        // same shim `ensureTool()` installs npm-strategy tools into. Checked BEFORE
+        // the bare-name PATH fallback (#1638): without this, a tool that only
+        // exists in the managed dir never resolves here, so `resolveAvailableOrInstall`
+        // clears the checker's cache on every install recovery for nothing — the
+        // very next probe misses PATH again, spawns a doomed `--version` process,
+        // and only THEN falls through to `ensureTool`'s own cache. One managed-dir
+        // 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);
+        if (managed)
+            return managed;
         // Fall back to global
         return command;
     };
@@ -171,10 +327,44 @@ export async function discoverManagedTool(toolId) {
 // install must not become an install attempt on every eligible file/turn.
 const installAttemptsByCwd = new PathKeyedMap(normalizeMapKey);
 const resolveInstallInFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+// Which (cwd, toolId) pairs already got their ONE compensating `available`
+// row this session for a GENUINE correction (#1612 review F2).
+// `checker.reset()` clears the checker's own cache on every install recovery,
+// so the NEXT call re-probes PATH from scratch — and that probe keeps missing
+// for a managed-dir-only install (createVenvFinder never searches the managed
+// tools dir; tracked separately as its own bug). Without this memo, every one
+// of those repeat probe failures looks like a fresh correction and re-logs
+// "available", even though only the first call actually ran an install.
+//
+// A correction is genuine only when a latched `unavailable` row for the same
+// pair stood before it. `verifyOrInstallCommand` also emits through this seam
+// with NO prior latch behind it (biome-check and oxlint reach it with no
+// checker probe at all), and burning this memo on such a row silences the
+// LATER genuine latch-then-recover for the same pair — the #1606 defect back
+// through the #1612 seam (#1657). Those rows dedupe against
+// `uncorrectedEmissionsByCwd` instead, so repeats stay suppressed without
+// pre-empting the real correction.
+const correctedAvailabilityByCwd = new PathKeyedMap(normalizeMapKey);
+// Which (cwd, toolId) pairs already emitted an `available` row that corrected
+// nothing (no latched `unavailable` stood before it). Same one-row-per-session
+// bound as the memo above, kept in a SEPARATE scope so it cannot answer for a
+// correction that has not happened yet (#1657).
+const uncorrectedEmissionsByCwd = new PathKeyedMap(normalizeMapKey);
+// Which (cwd, tool) pairs currently stand latched `unavailable` in the durable
+// log. Recorded where such a row is actually written, so "was there anything
+// to correct" is read from the log's own history rather than assumed by the
+// caller. Session-scoped: `resetDispatchAvailabilityState` clears it, so a new
+// session re-arms instead of inheriting the last one's latches (#1657).
+const latchedUnavailableByCwd = new PathKeyedMap(normalizeMapKey);
 // Checkers are created by runner modules and may also be created dynamically.
 // Keep the session reset as a generation rather than retaining every checker
 // reset closure forever.
-let availabilityStateGeneration = 0;
+//
+// #1754: the counter itself is now the shared `GenerationSource` primitive, so
+// the capture-before-await/check-after guards below are one implementation
+// 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");
 function installStateFor(cwd, toolId) {
     let states = installAttemptsByCwd.get(cwd);
     if (!states) {
@@ -200,12 +390,213 @@ function noteInstallSuccess(toolId, cwd) {
     if (states?.size === 0)
         installAttemptsByCwd.delete(cwd);
 }
+function hasId(map, cwd, id) {
+    return map.get(cwd)?.has(id) ?? false;
+}
+function addId(map, cwd, id) {
+    let ids = map.get(cwd);
+    if (!ids) {
+        ids = new Set();
+        map.set(cwd, ids);
+    }
+    ids.add(id);
+}
+function deleteIds(map, cwd, ids) {
+    const existing = map.get(cwd);
+    if (!existing)
+        return;
+    for (const id of ids)
+        existing.delete(id);
+    if (existing.size === 0)
+        map.delete(cwd);
+}
+/**
+ * True once a compensating `available` row has already fired for this
+ * (cwd, toolId) pair this session; `noteAvailabilityCorrected` records it the
+ * first time. #1612 review F2's "once per correction" — see
+ * `correctedAvailabilityByCwd`'s comment for why repeats need suppressing.
+ */
+function hasCorrectedAvailability(cwd, toolId) {
+    return hasId(correctedAvailabilityByCwd, cwd, toolId);
+}
+function noteAvailabilityCorrected(cwd, toolId) {
+    addId(correctedAvailabilityByCwd, cwd, toolId);
+}
+/**
+ * Record that a latched `unavailable` row now stands for this pair. Called
+ * from each seam that writes one (the availability checker and the shared
+ * probe latch), so a later compensating row can tell a genuine correction
+ * from a no-op emission (#1657).
+ */
+function noteLatchedUnavailable(cwd, tool) {
+    addId(latchedUnavailableByCwd, cwd, tool);
+}
+/**
+ * Drop the latch record for a pair, because the row it described no longer
+ * stands. Called on every `available` verdict as well as on the compensating
+ * row itself, so a latch cannot outlive the state it describes and later back
+ * a "correction" that corrects nothing (#1674 review F3).
+ */
+function clearLatchedUnavailable(cwd, ...tools) {
+    deleteIds(latchedUnavailableByCwd, cwd, tools);
+}
+/**
+ * Every name a latched row for this pair could have been written under. A
+ * checker logs its COMMAND (sometimes a resolved absolute path), the install
+ * seam knows a toolId, and the two are not always the same string. One
+ * derivation feeds BOTH the lookup and the clear, so the two can never
+ * disagree about which key the latch lives under (#1674 review F3).
+ */
+function latchKeysFor(toolId, command) {
+    const keys = [toolId];
+    if (command)
+        keys.push(command, path.basename(command));
+    return keys;
+}
+/**
+ * True when a latched `unavailable` row stands for any of these keys. A false
+ * positive only restores the pre-#1657 behavior (the row emits and burns the
+ * correction memo); a false negative still emits the row, under the
+ * uncorrected scope. Neither can swallow a genuine correction.
+ */
+function hasLatchedUnavailable(cwd, tools) {
+    return tools.some((tool) => hasId(latchedUnavailableByCwd, cwd, tool));
+}
+/**
+ * Which installer family resolved a tool, for the compensating row's
+ * `evidence.source` (#1612 review F1). Reads the registry's own
+ * `installStrategy` rather than hand-mapping per toolId — the two cannot
+ * drift apart because there is only one list.
+ */
+function sourceTagForToolId(toolId) {
+    switch (getToolInstallStrategy(toolId)) {
+        case "npm":
+            return "managed-dir";
+        case "pip":
+            return "pip-user";
+        case "github":
+            return "github-release";
+        case "archive":
+            return "archive-dist";
+        case "maven":
+            return "maven-jar";
+        default:
+            // "gem" has no CLI runner behind this seam yet, and an unknown toolId
+            // means the registry lookup itself missed — either way, no tag beats
+            // a guessed one.
+            return undefined;
+    }
+}
+/**
+ * How to tag a not-fresh install resolution in the compensating row's
+ * evidence (#1636 review, carried over from #1615's verify). `getInstallAttempt`
+ * answers `undefined` for BOTH a genuine cache hit and a plain PATH/managed-dir
+ * discovery, and answers `declined`/`skipped` for a policy refusal that still
+ * hands back whatever discovery found — three different facts a single
+ * `"cache"` tag used to flatten into one. `declined`/`skipped` take priority
+ * over the source map: a project-trust decline overwrites whatever the
+ * discovery pass underneath it found (see `ensureTool`'s trust-gate branch in
+ * installer/index.ts), so by the time this reads it, "declined" is the honest
+ * answer regardless of how the binary was actually found.
+ */
+function resolvedTagForAttempt(toolId, attempt) {
+    if (attempt?.outcome === "declined" || attempt?.outcome === "skipped") {
+        return "declined";
+    }
+    return getLastEnsureResolutionSource(toolId) === "path" ? "path" : "cache";
+}
+/**
+ * Emit the ONE compensating `available` row for a (cwd, toolId) correction,
+ * after a latched unavailable probe recovers via `ensureTool`. This is the
+ * SINGLE row constructor for every caller behind this seam —
+ * `resolveAvailableOrInstallUnshared` (#1612) and `verifyOrInstallCommand`
+ * (#1636) both call it rather than each hand-rolling their own, which is
+ * exactly the drift #1610's own review caught the first time this shape
+ * shipped twice.
+ *
+ * Gated on the once-per-correction memo (`correctedAvailabilityByCwd`,
+ * #1612 review F2): `checker.reset()` / a cleared probe cache means the NEXT
+ * call for the same (cwd, toolId) can resolve the same tool again with no
+ * fresh attempt behind it, and that must not re-log a "fresh correction"
+ * every time.
+ *
+ * `latchKeys` are every name a latched `unavailable` row for this pair could
+ * carry. A row that clears one of them is a genuine correction and burns the
+ * correction memo; a row with nothing to correct dedupes in its own scope, so
+ * it cannot silence the genuine latch-then-recover that follows it for the
+ * same pair (#1657).
+ */
+function emitCompensatingAvailableRow(cwd, toolId, installStartedAt, installedPath, latchKeys) {
+    if (hasCorrectedAvailability(cwd, toolId))
+        return;
+    const correctsLatchedRow = hasLatchedUnavailable(cwd, latchKeys);
+    if (correctsLatchedRow) {
+        noteAvailabilityCorrected(cwd, toolId);
+        // Clear every key the latch could live under, not just the toolId: the
+        // checker records the row under its COMMAND, and a leftover entry would
+        // later back a "correction" with nothing behind it (#1674 review F3).
+        clearLatchedUnavailable(cwd, ...latchKeys);
+    }
+    else {
+        if (hasId(uncorrectedEmissionsByCwd, cwd, toolId))
+            return;
+        addId(uncorrectedEmissionsByCwd, cwd, toolId);
+    }
+    // `installed`/`installedPath` can come back truthy WITHOUT ensureTool
+    // running an install this call — its in-memory cache, its on-disk probe
+    // cache, getToolPath finding it already present, or a concurrent peer's
+    // install all return a path with no fresh attempt recorded. Deriving from
+    // `getInstallAttempt` (rather than asserting "succeeded" because the path
+    // is truthy, or hand-rolling a second mapping) is what #1610's OWN
+    // failure-path mirror bug was caught on review; read the REAL outcome
+    // through the one function that already knows how, don't assume it. Hard
+    // import, no `typeof` guard (#1636 review): a genuinely removed export
+    // must throw here, not silently read as "not attempted".
+    const attempt = getInstallAttempt(toolId);
+    const installEvidence = describeInstallAttempt(attempt);
+    const evidence = {
+        ...installEvidence,
+        binary: path.basename(installedPath),
+        source: sourceTagForToolId(toolId),
+        // Set alongside any non-"succeeded" outcome: the path is truthy but
+        // nothing ran this call, so it came from an already-known-good answer
+        // rather than a fresh attempt (#1612 review F2).
+        ...(installEvidence.install !== "succeeded" && {
+            resolved: resolvedTagForAttempt(toolId, attempt),
+        }),
+        // The whole point of the memo split, on the record: a reader can tell a
+        // row that cleared a latched `unavailable` from one that corrected
+        // nothing, without re-deriving it from the surrounding rows (#1674
+        // review F4).
+        correctsLatchedRow,
+    };
+    logAvailabilityDecision({
+        tool: toolId,
+        verdict: "available",
+        outcome: "success",
+        cause: "ok",
+        elapsedMs: Date.now() - installStartedAt,
+        // `checker.reset()`/a fresh probe just cleared whatever cache stood
+        // behind this call, so nothing is actually held pinned the instant
+        // this row is written — the very next probe starts fresh
+        // (#1612 review F3). Writing `true` here would claim a durability
+        // this call doesn't have.
+        latched: false,
+        classifiedBy: "caller",
+        evidence,
+    }, cwd);
+}
 /** Reset availability/install suppression at the session boundary. */
 export function resetDispatchAvailabilityState() {
     installAttemptsByCwd.clear();
     resolveInstallInFlightByCwd.clear();
+    correctedAvailabilityByCwd.clear();
+    uncorrectedEmissionsByCwd.clear();
+    latchedUnavailableByCwd.clear();
+    managedBinaryVerdicts.clear();
+    managedVerifyInFlight.clear();
     resetPathWalkMemo();
-    availabilityStateGeneration += 1;
+    availabilityGeneration.bump();
 }
 /**
  * Create a cached availability checker for a command.
@@ -227,19 +618,19 @@ export function resetDispatchAvailabilityState() {
 export function createAvailabilityChecker(command, windowsExt = "", versionArgs = ["--version"], options = {}) {
     const cacheByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
     const inFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
-    let checkerGeneration = availabilityStateGeneration;
-    const findCommand = createVenvFinder(command, windowsExt, true);
+    let checkerGeneration = availabilityGeneration.current();
+    const findCommand = createVenvFinder(command, windowsExt);
     function ensureCurrentGeneration() {
-        if (checkerGeneration === availabilityStateGeneration)
+        if (checkerGeneration === availabilityGeneration.current())
             return;
         cacheByCwd.clear();
         inFlightByCwd.clear();
-        checkerGeneration = availabilityStateGeneration;
+        checkerGeneration = availabilityGeneration.current();
     }
     const reset = () => {
         cacheByCwd.clear();
         inFlightByCwd.clear();
-        checkerGeneration = availabilityStateGeneration;
+        checkerGeneration = availabilityGeneration.current();
     };
     function getCache(cwd) {
         ensureCurrentGeneration();
@@ -279,13 +670,31 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             retryAfterMs = transientRetryDelayMs(cache.transientAttempts, verdict.cause);
             cache.retryAtMs = Date.now() + retryAfterMs;
         }
+        const latched = verdict.available || isLatchingOutcome(verdict.outcome);
+        // Remember the pair whose durable row now says "unavailable and staying
+        // that way" — that is the row a later compensating `available` row
+        // corrects, and the only thing that makes such a row a correction
+        // (#1657).
+        if (!verdict.available && latched) {
+            noteLatchedUnavailable(resolvedCwd, command);
+        }
+        else if (verdict.available) {
+            // The latched row this pair carried no longer stands: THIS row says
+            // the tool is back. Dropping the record here keeps a stale latch from
+            // backing a later "correction" that corrects nothing (#1674 F3).
+            clearLatchedUnavailable(resolvedCwd, ...latchKeysFor(command));
+        }
         logAvailabilityDecision({
             tool: command,
             verdict: verdict.available ? "available" : "unavailable",
             outcome: verdict.outcome,
             cause: verdict.cause,
             elapsedMs: verdict.elapsedMs,
-            latched: verdict.available || isLatchingOutcome(verdict.outcome),
+            latched,
+            ...(verdict.classifiedBy !== undefined && {
+                classifiedBy: verdict.classifiedBy,
+            }),
+            ...(verdict.evidence !== undefined && { evidence: verdict.evidence }),
             ...(verdict.hostStallMs !== undefined && {
                 hostStallMs: verdict.hostStallMs,
             }),
@@ -325,7 +734,7 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
         const promiseGeneration = checkerGeneration;
         let promise;
         promise = (async () => {
-            const fastPath = options.fastPath?.();
+            const fastPath = await options.fastPath?.();
             if (fastPath) {
                 cache.command = fastPath;
                 noteDecision(cache, resolvedCwd, {
@@ -333,6 +742,9 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                     outcome: "success",
                     cause: "fast-path",
                     elapsedMs: 0,
+                    // Caller-asserted, and justifiably: an on-disk shim IS the tool, so
+                    // there is no spawn to derive anything from (#1500).
+                    classifiedBy: "caller",
                 });
                 return true;
             }
@@ -347,6 +759,9 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                         outcome: "non-installable",
                         cause: "bad-cwd",
                         elapsedMs: 0,
+                        // The workspace is gone. Asserted from a stat, not a probe, and it
+                        // must never read as "the tool is missing" (#1500).
+                        classifiedBy: "caller",
                     });
                     return false;
                 }
@@ -357,10 +772,11 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                     outcome: "non-installable",
                     cause: "bad-cwd",
                     elapsedMs: 0,
+                    classifiedBy: "caller",
                 });
                 return false;
             }
-            const cmd = findCommand(resolvedCwd);
+            const cmd = await findCommand(resolvedCwd);
             const env = await options.environment?.(resolvedCwd);
             // The probe budget is enforced by a HOST-side timer, so host event-loop
             // stalls are charged to the child. Measure the stall that overlapped the
@@ -388,10 +804,12 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                     cause: "ok",
                     elapsedMs,
                     hostStallMs,
+                    classifiedBy: "probe",
+                    evidence: describeProbeEvidence(result),
                 });
                 return true;
             }
-            const { outcome, cause } = classifyProbeFailure(result, {
+            const { outcome, cause, evidence } = classifyProbeFailure(result, {
                 hostStallMs,
                 unclassifiedFailureOutcome: options.unclassifiedFailureOutcome,
             });
@@ -406,6 +824,8 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                 cause,
                 elapsedMs,
                 hostStallMs,
+                classifiedBy: "probe",
+                evidence,
             });
             return false;
         })().finally(() => {
@@ -444,32 +864,173 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
 }
 /**
  * Per-cwd cached availability probe for spawn signatures that don't fit
- * `createAvailabilityChecker` — multi-arg subcommands like `npx biome
- * --version`, `cargo clippy --version`, `mix credo --version`, or a
- * dynamically-resolved `<cmd> --version`. Each cwd is probed at most once;
- * concurrent first-time callers share the in-flight promise.
+ * `createAvailabilityChecker` — multi-arg subcommands like `cargo clippy
+ * --version` and `mix credo --version`, or a dynamically-resolved
+ * `<cmd> --version` such as eslint's local-then-global binary. Each cwd is
+ * probed at most once per verdict; concurrent first-time callers share the
+ * in-flight promise.
+ *
+ * Those three ARE the consumers. `npx biome --version` used to be named here as
+ * one and never was: biome resolves through `resolveManagedToolClient` and its
+ * own latch in `biome-client.ts`.
  *
- * The cache stores the boolean outcome forever (same shape as
- * `createAvailabilityChecker`): once known unavailable for a cwd, the
- * runner stays skipped for that cwd until the process restarts. Pass a
- * fresh probe for retry-after-install flows.
+ * ## Latch policy (#1494)
+ *
+ * This used to cache the boolean forever, so one stalled `eslint --version`
+ * disabled eslint for that cwd until the process restarted. The verdict now
+ * goes through `availability-policy.ts`: the probe returns the SPAWN RESULT,
+ * the policy classifies it, and only a durable outcome (`missing` /
+ * `non-installable`) latches. A timeout, abort or host stall expires on a
+ * bounded cooldown and the next caller re-probes.
  */
-export function createCwdCachedProbe(probe) {
-    const cacheByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
-    let probeGeneration = availabilityStateGeneration;
-    return (cwd) => {
-        if (probeGeneration !== availabilityStateGeneration) {
-            cacheByCwd.clear();
-            probeGeneration = availabilityStateGeneration;
+export function createCwdCachedProbe(probe, options) {
+    const latchByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+    const inFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+    let probeGeneration = availabilityGeneration.current();
+    function clear() {
+        latchByCwd.clear();
+        inFlightByCwd.clear();
+    }
+    function ensureCurrentGeneration() {
+        if (probeGeneration === availabilityGeneration.current())
+            return;
+        clear();
+        probeGeneration = availabilityGeneration.current();
+    }
+    function latchFor(key) {
+        const existing = latchByCwd.get(key);
+        if (existing)
+            return existing;
+        const created = createAvailabilityLatch();
+        latchByCwd.set(key, created);
+        return created;
+    }
+    function note(latch, key, verdict) {
+        let retryAfterMs;
+        if (verdict.available) {
+            latch.noteAvailable(verdict.cause);
+        }
+        else {
+            const delay = latch.noteUnavailable(verdict.outcome, verdict.cause);
+            if (delay > 0)
+                retryAfterMs = delay;
+        }
+        const latched = verdict.available || isLatchingOutcome(verdict.outcome);
+        // Same correction bookkeeping as the checker seam above (#1657).
+        if (!verdict.available && latched) {
+            noteLatchedUnavailable(key, options.tool);
         }
+        else if (verdict.available) {
+            clearLatchedUnavailable(key, ...latchKeysFor(options.tool));
+        }
+        logAvailabilityDecision({
+            tool: options.tool,
+            verdict: verdict.available ? "available" : "unavailable",
+            outcome: verdict.outcome,
+            cause: verdict.cause,
+            elapsedMs: verdict.elapsedMs,
+            latched,
+            hostStallMs: verdict.hostStallMs,
+            ...(retryAfterMs !== undefined && { retryAfterMs }),
+            ...(options.budgetMs !== undefined && { budgetMs: options.budgetMs }),
+            // Every verdict here is derived from the probe this seam just ran.
+            classifiedBy: "probe",
+            ...(verdict.evidence !== undefined && { evidence: verdict.evidence }),
+        }, key);
+    }
+    const run = (cwd) => {
+        ensureCurrentGeneration();
         const key = path.resolve(cwd || process.cwd());
-        const existing = cacheByCwd.get(key);
+        const latch = latchFor(key);
+        const memo = latch.read();
+        if (memo !== null)
+            return Promise.resolve(memo);
+        const existing = inFlightByCwd.get(key);
         if (existing)
             return existing;
-        const promise = probe(key).catch(() => false);
-        cacheByCwd.set(key, promise);
+        const promiseGeneration = probeGeneration;
+        let promise;
+        promise = (async () => {
+            // The probe budget is enforced by a HOST-side timer, so a stalled event
+            // loop expires it while the child is still healthy. Measure the stall
+            // that overlapped the window and hand it to the classifier (#1467).
+            const stallSampler = startHostStallSampler();
+            const startedAt = Date.now();
+            let result;
+            let thrown;
+            try {
+                result = await probe(key);
+            }
+            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)),
+            };
+            if (result && !result.error && result.status === 0) {
+                note(latch, key, {
+                    available: true,
+                    outcome: "success",
+                    cause: "ok",
+                    elapsedMs,
+                    hostStallMs,
+                    evidence: describeProbeEvidence(result, options.tool),
+                });
+                return true;
+            }
+            const { outcome, cause, evidence } = classifyProbeFailure(shape, {
+                hostStallMs,
+                command: options.tool,
+                unclassifiedFailureOutcome: options.unclassifiedFailureOutcome,
+            });
+            note(latch, key, {
+                available: false,
+                outcome,
+                cause,
+                elapsedMs,
+                hostStallMs,
+                evidence,
+            });
+            return false;
+        })().finally(() => {
+            // A session reset clears the map and a caller may immediately start a
+            // replacement probe for the same cwd; the old promise must not delete
+            // that newer-generation entry when it settles.
+            if (probeGeneration === promiseGeneration &&
+                inFlightByCwd.get(key) === promise) {
+                inFlightByCwd.delete(key);
+            }
+        });
+        inFlightByCwd.set(key, promise);
         return promise;
     };
+    const cached = run;
+    cached.getVerdict = (cwd) => {
+        ensureCurrentGeneration();
+        const latch = latchFor(path.resolve(cwd || process.cwd()));
+        const outcome = latch.getOutcome();
+        return {
+            outcome,
+            cause: latch.getCause(),
+            elapsedMs: 0,
+            // Read the OUTCOME, never `read()`: `read()` answers `null` both for a
+            // cwd that was never probed and for a transient verdict whose cooldown
+            // expired, and `!== false` turned both of those into `latched: true` —
+            // the opposite of the truth in the expired case.
+            latched: outcome !== null && isLatchingOutcome(outcome),
+            retryAtMs: latch.getRetryAtMs(),
+        };
+    };
+    cached.reset = () => {
+        clear();
+        probeGeneration = availabilityGeneration.current();
+    };
+    return cached;
 }
 export function resolveNodeToolCommand(cwd, toolName, windowsExt = ".cmd") {
     const isWin = process.platform === "win32";
@@ -537,9 +1098,20 @@ async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--ve
     const state = installStateFor(cwd, toolId);
     if (state.suppressed)
         return null;
+    const installStartedAt = Date.now();
     const installed = await ensureTool(toolId);
     if (installed) {
         noteInstallSuccess(toolId, cwd);
+        // A latched `unavailable` row MAY stand here, written by whatever probe
+        // the caller ran first — but not always. The on-disk pre-check above
+        // logs nothing, and two runners reach this seam with no checker probe at
+        // all (biome-check and oxlint call
+        // `resolveToolCommandWithInstallFallback` directly, #1657). So the row is
+        // emitted either way, and only a call that really clears a latched row is
+        // recorded as a correction. Without the row, the durable log keeps saying
+        // the tool is off after the installer just brought it back — the third
+        // seam of #1606/#1610/#1612 (#1636).
+        emitCompensatingAvailableRow(cwd, toolId, installStartedAt, installed, latchKeysFor(toolId, command));
         return installed;
     }
     noteInstallFailure(toolId, cwd);
@@ -578,10 +1150,36 @@ async function resolveAvailableOrInstallUnshared(checker, toolId, cwd) {
     if (state.suppressed) {
         return null;
     }
+    const installStartedAt = Date.now();
     const installed = await ensureTool(toolId);
     if (installed) {
         noteInstallSuccess(toolId, cwd);
         checker.reset?.();
+        // The PATH probe above already wrote a latched `unavailable` row via
+        // `checker.isAvailableAsync`. Without a compensating row here, the durable
+        // log keeps saying the tool is off after the installer just brought it
+        // back — the shape #1606/PR #1610 fixed in `ensureViaInstaller`, shared
+        // here by ~16 runners behind this helper (#1612), and by
+        // `verifyOrInstallCommand` for the third seam (#1636).
+        //
+        // `checker.reset()` above clears the checker's cache, so the NEXT call
+        // re-probes PATH from scratch — and for a managed-dir-only install that
+        // probe misses again unless `createVenvFinder` finds it first (#1638).
+        // Left unguarded, every one of those repeat misses would re-fire this
+        // row, claiming a fresh install each time — `emitCompensatingAvailableRow`
+        // gates on the once-per-correction memo to prevent that.
+        //
+        // The probe above returned the latching `missing` outcome, so a latched
+        // `unavailable` row stands for this pair right now — recorded under the
+        // checker's own command name. Record it under the toolId too, so the
+        // emitter can READ that a correction is happening from the same ledger
+        // every other caller reads, instead of being told so by an argument
+        // (#1674 review F3).
+        noteLatchedUnavailable(cwd, toolId);
+        // This IS a genuine correction: the probe above returned the latching
+        // `missing` outcome, so a latched `unavailable` row stands for this pair
+        // right now (#1657).
+        emitCompensatingAvailableRow(cwd, toolId, installStartedAt, installed, latchKeysFor(toolId, checker.getCommand(cwd) ?? undefined));
         return installed;
     }
     noteInstallFailure(toolId, cwd);
@@ -598,16 +1196,19 @@ export function resolveAvailableOrInstall(checker, toolId, cwd) {
     const existing = byTool.get(toolId);
     if (existing)
         return existing;
-    const generation = availabilityStateGeneration;
+    // Same capture-before-await guard as the managed-verify seam, via the same
+    // primitive (#1754): a settling old-session transaction must not evict the
+    // entry a NEW session already installed for this (cwd, tool).
+    const generation = availabilityGeneration.capture();
     const promise = resolveAvailableOrInstallUnshared(checker, toolId, cwd).finally(() => {
-        if (generation !== availabilityStateGeneration)
-            return;
-        const current = resolveInstallInFlightByCwd.get(key);
-        if (current?.get(toolId) === promise) {
-            current.delete(toolId);
-            if (current.size === 0)
-                resolveInstallInFlightByCwd.delete(key);
-        }
+        generation.guardedWrite(`${toolId}@${key}`, () => {
+            const current = resolveInstallInFlightByCwd.get(key);
+            if (current?.get(toolId) === promise) {
+                current.delete(toolId);
+                if (current.size === 0)
+                    resolveInstallInFlightByCwd.delete(key);
+            }
+        });
     });
     byTool.set(toolId, promise);
     return promise;
@@ -628,6 +1229,26 @@ let sgCmdArgs = [];
 let sgSweepSawTransient = false;
 let sgSweepTransientCause = "probe-timeout";
 let sgSweepHostStallMs = 0;
+/**
+ * Candidates that were UNREACHABLE, in ask order (#1568).
+ *
+ * The sweep stops at the first candidate that answers, so at the moment of a
+ * win this list is exactly the set of candidates ahead of the winner that never
+ * got a fair hearing — i.e. the preferred tiers the winner did not really beat.
+ *
+ * Basenames, because tier 1 is an absolute `node_modules/.bin` path and this
+ * list is written to latency.log (#1568 review F3).
+ */
+let sgSweepUnreachable = [];
+/**
+ * Candidates that were probed and answered DURABLY missing this sweep — a
+ * real ENOENT/non-installable verdict, not a stall (#1593). The retained-arm
+ * fallback below only knows the sweep saw SOME transient candidate; without
+ * this list it cannot tell "the memoized winner itself just proved absent"
+ * from "an unrelated sibling merely stalled", and re-serves a command this
+ * very sweep disproved.
+ */
+let sgSweepDurablyMissing = [];
 function isAstGrepVersionOutput(output) {
     return /\bast[- ]grep\b/i.test(output);
 }
@@ -653,6 +1274,12 @@ async function probeAstGrepCommandAsync(cmd, argsPrefix = []) {
     if (outcome === "transient") {
         sgSweepSawTransient = true;
         sgSweepTransientCause = cause;
+        const name = path.basename(cmd);
+        if (!sgSweepUnreachable.includes(name))
+            sgSweepUnreachable.push(name);
+    }
+    else if (!sgSweepDurablyMissing.includes(cmd)) {
+        sgSweepDurablyMissing.push(cmd);
     }
     return false;
 }
@@ -684,15 +1311,15 @@ function buildSgLocalBins() {
     return bins;
 }
 let sgAvailableInFlight = null;
-let sgAvailabilityGeneration = availabilityStateGeneration;
+let sgAvailabilityGeneration = availabilityGeneration.current();
 function ensureCurrentSgGeneration() {
-    if (sgAvailabilityGeneration === availabilityStateGeneration)
+    if (sgAvailabilityGeneration === availabilityGeneration.current())
         return;
     sgLatch.reset();
     sgCmd = null;
     sgCmdArgs = [];
     sgAvailableInFlight = null;
-    sgAvailabilityGeneration = availabilityStateGeneration;
+    sgAvailabilityGeneration = availabilityGeneration.current();
 }
 export async function isSgAvailableAsync() {
     ensureCurrentSgGeneration();
@@ -708,6 +1335,8 @@ export async function isSgAvailableAsync() {
         sgSweepSawTransient = false;
         sgSweepTransientCause = "probe-timeout";
         sgSweepHostStallMs = 0;
+        sgSweepUnreachable = [];
+        sgSweepDurablyMissing = [];
         // 1. Local node_modules/.bin
         for (const localBin of buildSgLocalBins()) {
             if (await probeAstGrepCommandAsync(localBin)) {
@@ -744,6 +1373,21 @@ export async function isSgAvailableAsync() {
             noteSgAvailable(startedAt);
             return true;
         }
+        // Nothing answered, and nothing answered TRANSIENTLY, while the verdict we
+        // are about to overwrite is a provisional win whose command we still hold.
+        // #1476's principle applies to the result as much as to the probe: a
+        // timeout says nothing about the tool, so it cannot erase a command this
+        // process proved working one cooldown ago. Keep serving it and re-arm
+        // (#1568 review F1) — UNLESS this very sweep just proved the memoized
+        // command durably missing (#1593): a sibling tier stalling is not license
+        // to re-serve a winner that ENOENTed a moment ago in the same pass.
+        if (sgSweepSawTransient &&
+            sgLatch.isProvisional() &&
+            sgCmd !== null &&
+            !sgSweepDurablyMissing.includes(sgCmd)) {
+            noteSgAvailable(startedAt, { retained: true });
+            return true;
+        }
         // A timeout on ANY candidate is evidence about the host, not the tool.
         noteSgUnavailable(startedAt, sgSweepSawTransient ? "transient" : "missing", sgSweepSawTransient ? sgSweepTransientCause : "not-found");
         return false;
@@ -752,18 +1396,44 @@ export async function isSgAvailableAsync() {
     });
     return sgAvailableInFlight;
 }
-/** Record a successful shared-ast-grep sweep, with one decision record. */
-function noteSgAvailable(startedAt) {
-    sgLatch.noteAvailable();
+/**
+ * Record a successful shared-ast-grep sweep, with one decision record.
+ *
+ * A win reached while an EARLIER candidate was unreachable is provisional
+ * (#1568). The sweep stops at the first candidate that answers, so
+ * `sgSweepSawTransient` at this point means precisely "a tier this one is
+ * supposed to lose to never got a fair hearing" — the winner is used now, but
+ * caching it for the session would pin a healthy PATH ast-grep behind `npx`
+ * until the next restart.
+ *
+ * `retained` marks the other provisional case (#1568 review F1): no candidate
+ * answered at all, so the winner being reported is the one the previous sweep
+ * found, kept rather than discarded on a timeout.
+ */
+function noteSgAvailable(startedAt, opts = {}) {
+    const provisional = sgSweepSawTransient;
+    let retryAfterMs = 0;
+    if (provisional) {
+        retryAfterMs = sgLatch.noteProvisionallyAvailable(sgSweepTransientCause);
+    }
+    else {
+        sgLatch.noteAvailable();
+    }
     logAvailabilityDecision({
         tool: "ast-grep",
         verdict: "available",
         outcome: "success",
-        cause: "ok",
+        cause: provisional ? sgSweepTransientCause : "ok",
         elapsedMs: Date.now() - startedAt,
-        latched: true,
+        latched: !provisional,
         hostStallMs: sgSweepHostStallMs,
         budgetMs: 5000,
+        ...(provisional && {
+            provisional: true,
+            unreachablePreferred: [...sgSweepUnreachable],
+            ...(opts.retained === true && { retained: true }),
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+        }),
     });
 }
 /** Record a failed shared-ast-grep sweep; a transient verdict expires. */