@herbertgao/pi-extensions 2026.8.5 → 2026.8.6

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

@@ -18,6 +18,8 @@ import { getServersForFileWithConfig, isServerDisabled, } from "../../../lsp/con
 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";
 /**
  * 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
@@ -64,6 +66,29 @@ 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.
+ *
+ * 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) {
+    const base = path.join(getGlobalPiLensDir(), "tools", "node_modules", ".bin", tool);
+    const candidates = process.platform === "win32" ? [`${base}.cmd`, `${base}.exe`, base] : [base];
+    try {
+        return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Find a command in venv first, then fall back to global.
  * Checks common venv locations (.venv, venv) before trying global.
@@ -191,6 +216,13 @@ export function resetDispatchAvailabilityState() {
  * `zig --version`). Passing the wrong probe makes the runner silently skip on
  * every machine, so toolchains with a non-standard version command must override
  * this.
+ *
+ * ## Latch policy (#1467)
+ *
+ * A `missing` / `non-installable` verdict is durable and is cached for the
+ * session. A `transient` verdict — timeout, abort, EAGAIN — is NOT: it is
+ * cached only for a bounded cooldown, after which the next caller re-probes.
+ * An installed tool therefore recovers on its own, without a host restart.
  */
 export function createAvailabilityChecker(command, windowsExt = "", versionArgs = ["--version"], options = {}) {
     const cacheByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
@@ -219,16 +251,63 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             available: null,
             command: null,
             outcome: null,
+            cause: null,
+            elapsedMs: 0,
+            retryAtMs: 0,
+            transientAttempts: 0,
         };
         cacheByCwd.set(key, created);
         return created;
     }
+    /** Record a verdict on the cache and emit exactly one decision record. */
+    function noteDecision(cache, resolvedCwd, verdict) {
+        cache.available = verdict.available;
+        cache.outcome = verdict.outcome;
+        cache.cause = verdict.cause;
+        cache.elapsedMs = verdict.elapsedMs;
+        let retryAfterMs;
+        if (verdict.available) {
+            cache.retryAtMs = 0;
+            cache.transientAttempts = 0;
+        }
+        else if (isLatchingOutcome(verdict.outcome)) {
+            cache.retryAtMs = 0;
+            cache.transientAttempts = 0;
+        }
+        else {
+            cache.transientAttempts += 1;
+            retryAfterMs = transientRetryDelayMs(cache.transientAttempts, verdict.cause);
+            cache.retryAtMs = Date.now() + retryAfterMs;
+        }
+        logAvailabilityDecision({
+            tool: command,
+            verdict: verdict.available ? "available" : "unavailable",
+            outcome: verdict.outcome,
+            cause: verdict.cause,
+            elapsedMs: verdict.elapsedMs,
+            latched: verdict.available || isLatchingOutcome(verdict.outcome),
+            ...(verdict.hostStallMs !== undefined && {
+                hostStallMs: verdict.hostStallMs,
+            }),
+            ...(retryAfterMs !== undefined && { retryAfterMs }),
+            budgetMs: options.probeTimeout ?? 5000,
+        }, resolvedCwd);
+    }
     async function isAvailableAsync(cwd) {
         ensureCurrentGeneration();
         const resolvedCwd = cwd || process.cwd();
         const cache = getCache(resolvedCwd);
-        if (cache.available === false)
-            return false;
+        if (cache.available === false) {
+            // A durable "this machine does not have the tool" stays cached; a
+            // transient probe failure only holds until its cooldown expires, so an
+            // installed tool cannot be disabled for the life of the process by one
+            // slow second at warm-up (#1467).
+            if (cache.outcome !== "transient")
+                return false;
+            if (Date.now() < cache.retryAtMs)
+                return false;
+            cache.available = null;
+        }
         if (cache.available === true && cache.command) {
             if (await isSpawnableCommand(cache.command))
                 return true;
@@ -237,6 +316,7 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             cache.available = null;
             cache.command = null;
             cache.outcome = null;
+            cache.cause = null;
         }
         const key = path.resolve(resolvedCwd);
         const existing = inFlightByCwd.get(key);
@@ -247,9 +327,13 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
         promise = (async () => {
             const fastPath = options.fastPath?.();
             if (fastPath) {
-                cache.available = true;
-                cache.outcome = "success";
                 cache.command = fastPath;
+                noteDecision(cache, resolvedCwd, {
+                    available: true,
+                    outcome: "success",
+                    cause: "fast-path",
+                    elapsedMs: 0,
+                });
                 return true;
             }
             // A bad/removed workspace must not be mistaken for a missing tool and
@@ -258,49 +342,71 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             try {
                 const cwdStat = await fs.promises.stat(resolvedCwd);
                 if (!cwdStat.isDirectory()) {
-                    cache.available = false;
-                    cache.outcome = "non-installable";
+                    noteDecision(cache, resolvedCwd, {
+                        available: false,
+                        outcome: "non-installable",
+                        cause: "bad-cwd",
+                        elapsedMs: 0,
+                    });
                     return false;
                 }
             }
             catch {
-                cache.available = false;
-                cache.outcome = "non-installable";
+                noteDecision(cache, resolvedCwd, {
+                    available: false,
+                    outcome: "non-installable",
+                    cause: "bad-cwd",
+                    elapsedMs: 0,
+                });
                 return false;
             }
             const cmd = findCommand(resolvedCwd);
             const env = await options.environment?.(resolvedCwd);
-            const result = await safeSpawnAsync(cmd, versionArgs, {
-                timeout: options.probeTimeout ?? 5000,
-                cwd: resolvedCwd,
-                env,
-            });
+            // 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
+            // window and hand it to the classifier (#1467).
+            const stallSampler = startHostStallSampler();
+            const startedAt = Date.now();
+            let result;
+            let hostStallMs;
+            try {
+                result = await safeSpawnAsync(cmd, versionArgs, {
+                    timeout: options.probeTimeout ?? 5000,
+                    cwd: resolvedCwd,
+                    env,
+                });
+            }
+            finally {
+                hostStallMs = stallSampler.stop();
+            }
+            const elapsedMs = Date.now() - startedAt;
             if (!result.error && result.status === 0) {
-                cache.available = true;
-                cache.outcome = "success";
                 cache.command = cmd;
+                noteDecision(cache, resolvedCwd, {
+                    available: true,
+                    outcome: "success",
+                    cause: "ok",
+                    elapsedMs,
+                    hostStallMs,
+                });
                 return true;
             }
-            cache.available = false;
-            const errorCode = result.error?.code;
-            if (result.spawnFailure?.kind === "tool-not-found") {
+            const { outcome, cause } = classifyProbeFailure(result, {
+                hostStallMs,
+                unclassifiedFailureOutcome: options.unclassifiedFailureOutcome,
+            });
+            // Only a TYPED tool-not-found invalidates the PATH walk memo; an
+            // `unclassifiedFailureOutcome: "missing"` compatibility verdict is a
+            // guess, not evidence that PATH changed.
+            if (result.spawnFailure?.kind === "tool-not-found")
                 resetPathWalkMemo();
-                cache.outcome = "missing";
-            }
-            else if (result.failure === "timeout" ||
-                result.failure === "aborted" ||
-                result.failure === "signal" ||
-                result.spawnFailure?.kind === "killed" ||
-                errorCode === "EAGAIN" ||
-                errorCode === "EBUSY") {
-                cache.outcome = "transient";
-            }
-            else {
-                // A present command that rejects its version probe (or an EACCES/
-                // EINVAL/UNKNOWN failure) is not repaired by reinstalling it.
-                cache.outcome =
-                    options.unclassifiedFailureOutcome ?? "non-installable";
-            }
+            noteDecision(cache, resolvedCwd, {
+                available: false,
+                outcome,
+                cause,
+                elapsedMs,
+                hostStallMs,
+            });
             return false;
         })().finally(() => {
             // A session reset clears this map and a caller may immediately start a
@@ -323,7 +429,18 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
         ensureCurrentGeneration();
         return getCache(cwd || process.cwd()).outcome;
     }
-    return { isAvailableAsync, getCommand, getOutcome, reset };
+    function getVerdict(cwd) {
+        ensureCurrentGeneration();
+        const cache = getCache(cwd || process.cwd());
+        return {
+            outcome: cache.outcome,
+            cause: cache.cause,
+            elapsedMs: cache.elapsedMs,
+            latched: cache.available !== false || isLatchingOutcome(cache.outcome ?? "missing"),
+            retryAtMs: cache.retryAtMs,
+        };
+    }
+    return { isAvailableAsync, getCommand, getOutcome, getVerdict, reset };
 }
 /**
  * Per-cwd cached availability probe for spawn signatures that don't fit
@@ -498,20 +615,46 @@ export function resolveAvailableOrInstall(checker, toolId, cwd) {
 // =============================================================================
 // SHARED AST-GREP AVAILABILITY
 // =============================================================================
-// Shared ast-grep availability cache across all slop runners
-let sgAvailable = null;
+/**
+ * Shared ast-grep availability across all slop runners, behind the transient-
+ * aware latch (#1476). This module-level memo carried the same shape `SgRunner`
+ * did — one failed sweep, including a timeout, disabled ast-grep for every slop
+ * runner for the life of the process.
+ */
+const sgLatch = createAvailabilityLatch();
 let sgCmd = null;
 let sgCmdArgs = [];
+/** Classification of the current sweep, accumulated across candidates. */
+let sgSweepSawTransient = false;
+let sgSweepTransientCause = "probe-timeout";
+let sgSweepHostStallMs = 0;
 function isAstGrepVersionOutput(output) {
     return /\bast[- ]grep\b/i.test(output);
 }
 async function probeAstGrepCommandAsync(cmd, argsPrefix = []) {
-    const check = await safeSpawnAsync(cmd, [...argsPrefix, "--version"], {
-        timeout: 5000,
-    });
-    return (!check.error &&
+    const sampler = startHostStallSampler();
+    let check;
+    let hostStallMs;
+    try {
+        check = await safeSpawnAsync(cmd, [...argsPrefix, "--version"], {
+            timeout: 5000,
+        });
+    }
+    finally {
+        hostStallMs = sampler.stop();
+        sgSweepHostStallMs += hostStallMs;
+    }
+    if (!check.error &&
         check.status === 0 &&
-        isAstGrepVersionOutput(`${check.stdout}\n${check.stderr}`));
+        isAstGrepVersionOutput(`${check.stdout}\n${check.stderr}`)) {
+        return true;
+    }
+    const { outcome, cause } = classifyProbeFailure(check, { hostStallMs });
+    if (outcome === "transient") {
+        sgSweepSawTransient = true;
+        sgSweepTransientCause = cause;
+    }
+    return false;
 }
 /** Pre-filter local node_modules/.bin candidates that actually exist on disk. */
 function buildSgLocalBins() {
@@ -545,7 +688,7 @@ let sgAvailabilityGeneration = availabilityStateGeneration;
 function ensureCurrentSgGeneration() {
     if (sgAvailabilityGeneration === availabilityStateGeneration)
         return;
-    sgAvailable = null;
+    sgLatch.reset();
     sgCmd = null;
     sgCmdArgs = [];
     sgAvailableInFlight = null;
@@ -553,17 +696,24 @@ function ensureCurrentSgGeneration() {
 }
 export async function isSgAvailableAsync() {
     ensureCurrentSgGeneration();
-    if (sgAvailable !== null)
-        return sgAvailable;
+    // `read()` returns null when the last verdict was transient and its cooldown
+    // expired: re-probe rather than stay dead for the session (#1476).
+    const memo = sgLatch.read();
+    if (memo !== null)
+        return memo;
     if (sgAvailableInFlight)
         return sgAvailableInFlight;
     sgAvailableInFlight = (async () => {
+        const startedAt = Date.now();
+        sgSweepSawTransient = false;
+        sgSweepTransientCause = "probe-timeout";
+        sgSweepHostStallMs = 0;
         // 1. Local node_modules/.bin
         for (const localBin of buildSgLocalBins()) {
             if (await probeAstGrepCommandAsync(localBin)) {
                 sgCmd = localBin;
                 sgCmdArgs = [];
-                sgAvailable = true;
+                noteSgAvailable(startedAt);
                 return true;
             }
         }
@@ -572,7 +722,7 @@ export async function isSgAvailableAsync() {
             if (await probeAstGrepCommandAsync(cmd)) {
                 sgCmd = cmd;
                 sgCmdArgs = [];
-                sgAvailable = true;
+                noteSgAvailable(startedAt);
                 return true;
             }
         }
@@ -583,7 +733,7 @@ export async function isSgAvailableAsync() {
             if (globalBin && (await probeAstGrepCommandAsync(globalBin))) {
                 sgCmd = globalBin;
                 sgCmdArgs = [];
-                sgAvailable = true;
+                noteSgAvailable(startedAt);
                 return true;
             }
         }
@@ -591,16 +741,46 @@ export async function isSgAvailableAsync() {
         if (await probeAstGrepCommandAsync("npx", ["--no", "--", "ast-grep"])) {
             sgCmd = "npx";
             sgCmdArgs = ["--no", "--", "ast-grep"];
-            sgAvailable = true;
+            noteSgAvailable(startedAt);
             return true;
         }
-        sgAvailable = false;
+        // A timeout on ANY candidate is evidence about the host, not the tool.
+        noteSgUnavailable(startedAt, sgSweepSawTransient ? "transient" : "missing", sgSweepSawTransient ? sgSweepTransientCause : "not-found");
         return false;
     })().finally(() => {
         sgAvailableInFlight = null;
     });
     return sgAvailableInFlight;
 }
+/** Record a successful shared-ast-grep sweep, with one decision record. */
+function noteSgAvailable(startedAt) {
+    sgLatch.noteAvailable();
+    logAvailabilityDecision({
+        tool: "ast-grep",
+        verdict: "available",
+        outcome: "success",
+        cause: "ok",
+        elapsedMs: Date.now() - startedAt,
+        latched: true,
+        hostStallMs: sgSweepHostStallMs,
+        budgetMs: 5000,
+    });
+}
+/** Record a failed shared-ast-grep sweep; a transient verdict expires. */
+function noteSgUnavailable(startedAt, outcome, cause) {
+    const retryAfterMs = sgLatch.noteUnavailable(outcome, cause);
+    logAvailabilityDecision({
+        tool: "ast-grep",
+        verdict: "unavailable",
+        outcome,
+        cause,
+        elapsedMs: Date.now() - startedAt,
+        latched: outcome !== "transient",
+        hostStallMs: sgSweepHostStallMs,
+        ...(retryAfterMs > 0 && { retryAfterMs }),
+        budgetMs: 5000,
+    });
+}
 export function getSgCommand() {
     ensureCurrentSgGeneration();
     return {

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

@@ -0,0 +1,97 @@
+/**
+ * Shared toolchain-availability lifecycle (#1476 Sonar follow-up).
+ *
+ * `candidate-probe.ts` factored out the PATH sweep the Go and Rust clients ran,
+ * but the LIFECYCLE around it stayed written twice: the transient-aware latch,
+ * the in-flight dedupe that keeps concurrent first-time callers to one sweep,
+ * the path memo, and the two `availability_decision` records. Two copies of one
+ * rule is how #1467's fix missed seven sites, so the rule lives here once and
+ * each client contributes only its configuration.
+ *
+ * Callers keep their own public method names — `isGoAvailableAsync`,
+ * `findCargoPathAsync` — because other modules call them; only the body moves.
+ */
+import { createAvailabilityLatch, logAvailabilityDecision, } from "./availability-policy.js";
+import { probeAvailabilityCandidates } from "./candidate-probe.js";
+/**
+ * Own one toolchain's availability: sweep the platform candidate list, memoize
+ * the path that answered, and park the verdict behind the shared latch so a
+ * timed-out probe expires instead of latching "the toolchain is not installed"
+ * for the life of the process.
+ */
+export function createToolchainAvailability(config) {
+    const availabilityLatch = createAvailabilityLatch();
+    let toolPath = null;
+    /** Classification of the candidate sweep, for the retry decision. */
+    let sweepSawTransient = false;
+    let sweepTransientCause = "probe-timeout";
+    let sweepHostStallMs = 0;
+    let ensureInFlight = null;
+    async function findPath() {
+        if (toolPath)
+            return toolPath;
+        const paths = process.platform === "win32" ? config.windowsPaths : config.unixPaths;
+        const sweep = await probeAvailabilityCandidates(paths, config.probeArgs, config.budgetMs);
+        sweepSawTransient = sweep.sawTransient;
+        sweepTransientCause = sweep.transientCause;
+        sweepHostStallMs = sweep.hostStallMs;
+        if (sweep.foundPath)
+            toolPath = sweep.foundPath;
+        return sweep.foundPath;
+    }
+    async function resolveAvailability() {
+        const startedAt = Date.now();
+        const found = (await findPath()) !== null;
+        if (found) {
+            availabilityLatch.noteAvailable();
+            config.log(`${config.label} found: ${toolPath}`);
+            logAvailabilityDecision({
+                tool: config.tool,
+                verdict: "available",
+                outcome: "success",
+                cause: "ok",
+                elapsedMs: Date.now() - startedAt,
+                latched: true,
+                hostStallMs: sweepHostStallMs,
+                budgetMs: config.budgetMs,
+            });
+            return true;
+        }
+        // A timed-out version probe is evidence about this moment, not about
+        // whether the toolchain is installed; it expires instead of latching.
+        const outcome = sweepSawTransient ? "transient" : "missing";
+        const cause = sweepSawTransient ? sweepTransientCause : "not-found";
+        const retryAfterMs = availabilityLatch.noteUnavailable(outcome, cause);
+        logAvailabilityDecision({
+            tool: config.tool,
+            verdict: "unavailable",
+            outcome,
+            cause,
+            elapsedMs: Date.now() - startedAt,
+            latched: outcome !== "transient",
+            hostStallMs: sweepHostStallMs,
+            ...(retryAfterMs > 0 && { retryAfterMs }),
+            budgetMs: config.budgetMs,
+        });
+        return false;
+    }
+    async function isAvailable() {
+        // `read()` returns null when the last verdict was transient and its
+        // cooldown expired, which re-enters the candidate sweep (#1476).
+        const memo = availabilityLatch.read();
+        if (memo !== null)
+            return memo;
+        // Now that a verdict can expire, concurrent callers arriving just after a
+        // cooldown must share ONE sweep rather than each spawning their own.
+        if (ensureInFlight)
+            return ensureInFlight;
+        ensureInFlight = resolveAvailability();
+        try {
+            return await ensureInFlight;
+        }
+        finally {
+            ensureInFlight = null;
+        }
+    }
+    return { findPath, isAvailable };
+}

package/node_modules/pi-lens/dist/clients/disposition-publish.js

@@ -24,7 +24,7 @@
 import { logBusEvent } from "./bus-events-logger.js";
 import { isBusPublishEnabled } from "./bus-publish.js";
 import { normalizeFilePath } from "./path-utils.js";
-import { createLiveBusEmitter, recordStaleBusFailure, } from "./live-bus-emitter.js";
+import { createLiveBusEmitter, recordStaleBusFailure, resolveLiveBusEmitter, } from "./live-bus-emitter.js";
 export const BUS_DISPOSITION_EVENT = "pilens:diagnostic:disposition";
 export const BUS_DISPOSITION_VERSION = 1;
 const liveEmitter = createLiveBusEmitter();
@@ -67,8 +67,13 @@ export function publishDisposition(args) {
         }
         return;
     }
-    const busEmit = liveEmitter.get();
-    if (!busEmit) {
+    const resolution = resolveLiveBusEmitter(liveEmitter, () => ({
+        event: BUS_DISPOSITION_EVENT,
+        cwd: normalizeFilePath(args.cwd),
+    }));
+    if (resolution.outcome === "stale-session")
+        return;
+    if (resolution.outcome === "unwired") {
         if (!hasLoggedUnwired) {
             hasLoggedUnwired = true;
             logBusEvent({
@@ -79,6 +84,7 @@ export function publishDisposition(args) {
         }
         return;
     }
+    const busEmit = resolution.emit;
     try {
         const payload = {
             v: BUS_DISPOSITION_VERSION,
@@ -106,6 +112,7 @@ export function publishDisposition(args) {
             outcome: "emit_failed",
             cwd: normalizeFilePath(args.cwd),
             error: String(err),
+            ctxSource: resolution.ctxSource,
         });
         if (!hasLoggedFailure) {
             hasLoggedFailure = true;

package/node_modules/pi-lens/dist/clients/eval-timestamp.js

@@ -0,0 +1,17 @@
+import { performance } from "node:perf_hooks";
+/**
+ * The moment pi-lens's module graph started evaluating, captured as this
+ * module's first statement (#1374 host-boot vs extension-eval split).
+ *
+ * This module is otherwise side-effect-free by design (#1434 S3d review): it
+ * does nothing but capture a timestamp. `clients/console-guard-install.ts`
+ * imports it as its FIRST import so the capture happens before the guard's
+ * own install work, and `clients/startup-timing.ts` imports it too, for the
+ * constant alone. Before this split, `startup-timing.ts` imported the
+ * constant FROM `console-guard-install.ts` — which meant importing
+ * startup-timing anywhere (e.g. a test measuring load time) silently
+ * installed the console guard as a side effect. Splitting the constant out
+ * means importing this module, or `startup-timing.ts`, never installs
+ * anything.
+ */
+export const PI_LENS_EVAL_STARTED_MS = performance.now();