@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

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

@@ -9,8 +9,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { logSessionStart } from "../../../sessionstart-logger.js";
 import { getGlobalPiLensDir } from "../../../file-utils.js";
-import { ensureTool, isSpawnableCommand } from "../../../installer/index.js";
+import { PathKeyedMap } from "../../../path-keyed-map.js";
+import { normalizeEphemeralMapKey, normalizeMapKey, } from "../../../path-utils.js";
+import { ensureTool, 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";
@@ -83,6 +86,102 @@ export function createVenvFinder(command, windowsExt = "", quoteWindows = false)
         return command;
     };
 }
+/** Typed client-facing install seam for ordered/custom candidate probes. */
+export async function resolveManagedToolClient(options) {
+    const probed = await options.probe();
+    if (probed.outcome !== "missing")
+        return probed;
+    if (!shouldAutoInstallTool(options.toolId))
+        return probed;
+    const state = installStateFor(options.cwd, options.toolId);
+    if (state.suppressed)
+        return probed;
+    const installed = await ensureTool(options.toolId);
+    if (!installed) {
+        noteInstallFailure(options.toolId, options.cwd);
+        return probed;
+    }
+    const value = await options.acceptInstalled(installed);
+    if (value === null) {
+        noteInstallFailure(options.toolId, options.cwd);
+        return { outcome: "non-installable" };
+    }
+    noteInstallSuccess(options.toolId, options.cwd);
+    return { outcome: "success", value };
+}
+/**
+ * Child environment for managed-installable tools. Keeping this beside the
+ * probe/install seam makes managed npm shims visible to every standalone
+ * client, rather than only to Knip (#1289).
+ */
+export async function getManagedToolEnvironment(_toolId, cwd) {
+    let env;
+    try {
+        const { getToolEnvironment } = await import("../../../installer/index.js");
+        env = await getToolEnvironment();
+    }
+    catch {
+        // Installer-isolated unit tests historically mock only ensureTool. The
+        // ambient fallback preserves that isolation; production always exports it.
+        env = { ...process.env };
+    }
+    if (!cwd)
+        return env;
+    const separator = process.platform === "win32" ? ";" : ":";
+    const currentPath = env.PATH || env.Path || process.env.PATH || "";
+    const localBin = path.join(cwd, "node_modules", ".bin");
+    const augmentedPath = `${localBin}${separator}${currentPath}`;
+    return {
+        ...env,
+        PATH: augmentedPath,
+        ...(process.platform === "win32" ? { Path: augmentedPath } : {}),
+    };
+}
+/** Read-only managed/PATH discovery for spawn-time resolution memos. */
+export async function discoverManagedTool(toolId) {
+    return (await ensureTool(toolId, { allowInstall: false })) ?? null;
+}
+// This is session-scoped state, not a process-global tool/path cache. The cwd
+// key is normalized by PathKeyedMap and is cleared at session_start. A failed
+// install must not become an install attempt on every eligible file/turn.
+const installAttemptsByCwd = new PathKeyedMap(normalizeMapKey);
+const resolveInstallInFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+// 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;
+function installStateFor(cwd, toolId) {
+    let states = installAttemptsByCwd.get(cwd);
+    if (!states) {
+        states = new Map();
+        installAttemptsByCwd.set(cwd, states);
+    }
+    let state = states.get(toolId);
+    if (!state) {
+        state = { attempts: 0, suppressed: false };
+        states.set(toolId, state);
+    }
+    return state;
+}
+function noteInstallFailure(toolId, cwd) {
+    const state = installStateFor(cwd, toolId);
+    state.attempts += 1;
+    state.suppressed = true;
+    logSessionStart(`dispatch availability ${toolId}: install attempt ${state.attempts} failed; suppressing retries until the next session or a successful install`);
+}
+function noteInstallSuccess(toolId, cwd) {
+    const states = installAttemptsByCwd.get(cwd);
+    states?.delete(toolId);
+    if (states?.size === 0)
+        installAttemptsByCwd.delete(cwd);
+}
+/** Reset availability/install suppression at the session boundary. */
+export function resetDispatchAvailabilityState() {
+    installAttemptsByCwd.clear();
+    resolveInstallInFlightByCwd.clear();
+    resetPathWalkMemo();
+    availabilityStateGeneration += 1;
+}
 /**
  * Create a cached availability checker for a command.
  * The checker will look for the command in venv first, then global.
@@ -93,49 +192,138 @@ export function createVenvFinder(command, windowsExt = "", quoteWindows = false)
  * every machine, so toolchains with a non-standard version command must override
  * this.
  */
-export function createAvailabilityChecker(command, windowsExt = "", versionArgs = ["--version"]) {
-    const cacheByCwd = new Map();
-    const inFlightByCwd = new Map();
+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);
+    function ensureCurrentGeneration() {
+        if (checkerGeneration === availabilityStateGeneration)
+            return;
+        cacheByCwd.clear();
+        inFlightByCwd.clear();
+        checkerGeneration = availabilityStateGeneration;
+    }
+    const reset = () => {
+        cacheByCwd.clear();
+        inFlightByCwd.clear();
+        checkerGeneration = availabilityStateGeneration;
+    };
     function getCache(cwd) {
+        ensureCurrentGeneration();
         const key = path.resolve(cwd || process.cwd());
         const existing = cacheByCwd.get(key);
         if (existing)
             return existing;
-        const created = { available: null, command: null };
+        const created = {
+            available: null,
+            command: null,
+            outcome: null,
+        };
         cacheByCwd.set(key, created);
         return created;
     }
     async function isAvailableAsync(cwd) {
+        ensureCurrentGeneration();
         const resolvedCwd = cwd || process.cwd();
         const cache = getCache(resolvedCwd);
-        if (cache.available !== null)
-            return cache.available;
+        if (cache.available === false)
+            return false;
+        if (cache.available === true && cache.command) {
+            if (await isSpawnableCommand(cache.command))
+                return true;
+            // Cached-positive spawn feedback: a removed absolute path or vanished
+            // PATH command must fall through to a fresh probe immediately.
+            cache.available = null;
+            cache.command = null;
+            cache.outcome = null;
+        }
         const key = path.resolve(resolvedCwd);
         const existing = inFlightByCwd.get(key);
         if (existing)
             return existing;
-        const promise = (async () => {
+        const promiseGeneration = checkerGeneration;
+        let promise;
+        promise = (async () => {
+            const fastPath = options.fastPath?.();
+            if (fastPath) {
+                cache.available = true;
+                cache.outcome = "success";
+                cache.command = fastPath;
+                return true;
+            }
+            // A bad/removed workspace must not be mistaken for a missing tool and
+            // trigger an install. This async probe stays off the synchronous dispatch
+            // burst and makes the failure taxonomy explicit at the seam.
+            try {
+                const cwdStat = await fs.promises.stat(resolvedCwd);
+                if (!cwdStat.isDirectory()) {
+                    cache.available = false;
+                    cache.outcome = "non-installable";
+                    return false;
+                }
+            }
+            catch {
+                cache.available = false;
+                cache.outcome = "non-installable";
+                return false;
+            }
             const cmd = findCommand(resolvedCwd);
+            const env = await options.environment?.(resolvedCwd);
             const result = await safeSpawnAsync(cmd, versionArgs, {
-                timeout: 5000,
+                timeout: options.probeTimeout ?? 5000,
+                cwd: resolvedCwd,
+                env,
             });
-            cache.available = !result.error && result.status === 0;
-            if (cache.available) {
+            if (!result.error && result.status === 0) {
+                cache.available = true;
+                cache.outcome = "success";
                 cache.command = cmd;
+                return true;
+            }
+            cache.available = false;
+            const errorCode = result.error?.code;
+            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";
             }
-            return cache.available;
+            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";
+            }
+            return false;
         })().finally(() => {
-            inFlightByCwd.delete(key);
+            // A session reset clears this 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 (checkerGeneration === promiseGeneration &&
+                inFlightByCwd.get(key) === promise) {
+                inFlightByCwd.delete(key);
+            }
         });
         inFlightByCwd.set(key, promise);
         return promise;
     }
     function getCommand(cwd) {
+        ensureCurrentGeneration();
         const cache = getCache(cwd || process.cwd());
         return cache.command;
     }
-    return { isAvailableAsync, getCommand };
+    function getOutcome(cwd) {
+        ensureCurrentGeneration();
+        return getCache(cwd || process.cwd()).outcome;
+    }
+    return { isAvailableAsync, getCommand, getOutcome, reset };
 }
 /**
  * Per-cwd cached availability probe for spawn signatures that don't fit
@@ -150,8 +338,13 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
  * fresh probe for retry-after-install flows.
  */
 export function createCwdCachedProbe(probe) {
-    const cacheByCwd = new Map();
+    const cacheByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+    let probeGeneration = availabilityStateGeneration;
     return (cwd) => {
+        if (probeGeneration !== availabilityStateGeneration) {
+            cacheByCwd.clear();
+            probeGeneration = availabilityStateGeneration;
+        }
         const key = path.resolve(cwd || process.cwd());
         const existing = cacheByCwd.get(key);
         if (existing)
@@ -209,7 +402,8 @@ export async function resolveToolCommandWithInstallFallback(cwd, toolId, timeout
 async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
     // Skip the --version spawn when the command isn't even on disk — the ~μs
     // stat/PATH walk beats a guaranteed-to-fail spawn round-trip.
-    if (await isSpawnableCommand(command)) {
+    const spawnable = await isSpawnableCommand(command);
+    if (spawnable) {
         const versionCheck = await safeSpawnAsync(command, versionArgs, {
             timeout,
             cwd,
@@ -217,16 +411,22 @@ async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--ve
         if (!versionCheck.error && versionCheck.status === 0) {
             return command;
         }
+        // A command that was found but rejected its probe is not fixed by a
+        // reinstall. This also covers permissions and malformed shims.
+        return null;
     }
-    if (!shouldAutoInstallTool(toolId)) {
+    if (!shouldAutoInstallTool(toolId))
+        return null;
+    const state = installStateFor(cwd, toolId);
+    if (state.suppressed)
         return null;
+    const installed = await ensureTool(toolId);
+    if (installed) {
+        noteInstallSuccess(toolId, cwd);
+        return installed;
     }
-    // ensureTool's result is already trusted: a probe-cache hit validated
-    // path+mtime, and a fresh install verified the binary. Re-probing
-    // --version here booted the tool's node shim once per invocation for
-    // zero new information; a broken install now surfaces as the runner's
-    // own spawn error instead of a silent null.
-    return (await ensureTool(toolId)) ?? null;
+    noteInstallFailure(toolId, cwd);
+    return null;
 }
 export async function resolveCommandArgsWithInstallFallback(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
     const versionCheck = await safeSpawnAsync(command.cmd, [...command.args, ...versionArgs], { timeout, cwd });
@@ -245,16 +445,55 @@ export async function resolveCommandArgsWithInstallFallback(command, toolId, cwd
 export async function resolveCommandWithInstallFallback(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
     return verifyOrInstallCommand(command, toolId, cwd, versionArgs, timeout);
 }
-export async function resolveAvailableOrInstall(checker, toolId, cwd) {
+async function resolveAvailableOrInstallUnshared(checker, toolId, cwd) {
     const available = await checker.isAvailableAsync(cwd);
     if (available) {
         return checker.getCommand(cwd);
     }
-    if (!shouldAutoInstallTool(toolId)) {
+    // Only a typed ENOENT/missing-command result is repairable by installing.
+    // Probe failures caused by bad cwd, permissions, rejected flags, aborts, and
+    // timeouts are unavailable/non-installable and must not enter an install loop.
+    if (checker.getOutcome?.(cwd) !== "missing")
+        return null;
+    if (!shouldAutoInstallTool(toolId))
+        return null;
+    const state = installStateFor(cwd, toolId);
+    if (state.suppressed) {
         return null;
     }
     const installed = await ensureTool(toolId);
-    return installed ?? null;
+    if (installed) {
+        noteInstallSuccess(toolId, cwd);
+        checker.reset?.();
+        return installed;
+    }
+    noteInstallFailure(toolId, cwd);
+    return null;
+}
+/** Share the complete probe/install transaction for each cwd/tool pair. */
+export function resolveAvailableOrInstall(checker, toolId, cwd) {
+    const key = normalizeEphemeralMapKey(cwd);
+    let byTool = resolveInstallInFlightByCwd.get(key);
+    if (!byTool) {
+        byTool = new Map();
+        resolveInstallInFlightByCwd.set(key, byTool);
+    }
+    const existing = byTool.get(toolId);
+    if (existing)
+        return existing;
+    const generation = availabilityStateGeneration;
+    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);
+        }
+    });
+    byTool.set(toolId, promise);
+    return promise;
 }
 // =============================================================================
 // SHARED AST-GREP AVAILABILITY
@@ -302,7 +541,18 @@ function buildSgLocalBins() {
     return bins;
 }
 let sgAvailableInFlight = null;
+let sgAvailabilityGeneration = availabilityStateGeneration;
+function ensureCurrentSgGeneration() {
+    if (sgAvailabilityGeneration === availabilityStateGeneration)
+        return;
+    sgAvailable = null;
+    sgCmd = null;
+    sgCmdArgs = [];
+    sgAvailableInFlight = null;
+    sgAvailabilityGeneration = availabilityStateGeneration;
+}
 export async function isSgAvailableAsync() {
+    ensureCurrentSgGeneration();
     if (sgAvailable !== null)
         return sgAvailable;
     if (sgAvailableInFlight)
@@ -352,6 +602,7 @@ export async function isSgAvailableAsync() {
     return sgAvailableInFlight;
 }
 export function getSgCommand() {
+    ensureCurrentSgGeneration();
     return {
         cmd: sgCmd ?? "npx",
         args: sgCmdArgs.length ? sgCmdArgs : ["--no", "--", "ast-grep"],

package/node_modules/pi-lens/dist/clients/dispatch/runners/utils/spawn-outcome.js

@@ -0,0 +1,22 @@
+/**
+ * True when a tool both failed and produced nothing to parse — it never got as
+ * far as linting the file. Callers map this to `skipped`, never `succeeded`.
+ *
+ * Guarding on `result.error` alone covers only half of it: safe-spawn sets
+ * `error` for spawn/timeout/signal failures and resolves a NORMAL exit with no
+ * `error` at any status (see `SpawnResult.failure` — "nonzero exit statuses are
+ * not spawn failures"). An unknown subcommand, a rejected flag, or a config
+ * that fails to load exits non-zero with the message on stderr and an empty
+ * stdout, so an `error`-only guard falls through, parses "" into zero
+ * diagnostics, and reports a clean file that nothing ever checked.
+ *
+ * Tools that exit non-zero *because* they found something are unaffected: their
+ * findings are on stdout, so the output half of the test is false.
+ *
+ * `output` defaults to stdout. Runners that parse stderr too pass the exact
+ * string they are about to hand the parser, so "nothing to parse" means both
+ * streams rather than just one.
+ */
+export function spawnFailedWithNoOutput(result, output = result.stdout) {
+    return (Boolean(result.error) || result.status !== 0) && !output?.trim();
+}

package/node_modules/pi-lens/dist/clients/dispatch/runners/yaml-rule-parser.js

@@ -15,6 +15,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import yaml from "../../deps/js-yaml.js";
+import { BoundedLruCache } from "../../bounded-cache.js";
 // --- Constants ---
 /** Overly broad patterns that match everything (cause false positive explosions) */
 export const OVERLY_BROAD_PATTERNS = [
@@ -28,10 +29,10 @@ export const OVERLY_BROAD_PATTERNS = [
 /** Maximum complexity score for rules in blockingOnly mode */
 export const MAX_BLOCKING_RULE_COMPLEXITY = 8;
 // --- Caches ---
-const rulesCache = new Map();
-const blockingRulesCache = new Map();
-const contentRulesCache = new Map();
-const contentBlockingRulesCache = new Map();
+const rulesCache = new BoundedLruCache(64);
+const blockingRulesCache = new BoundedLruCache(64);
+const contentRulesCache = new BoundedLruCache(64);
+const contentBlockingRulesCache = new BoundedLruCache(64);
 // --- Public API ---
 export function clearRulesCache() {
     rulesCache.clear();

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

@@ -24,9 +24,10 @@
 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";
 export const BUS_DISPOSITION_EVENT = "pilens:diagnostic:disposition";
 export const BUS_DISPOSITION_VERSION = 1;
-let busEmit;
+const liveEmitter = createLiveBusEmitter();
 let hasLoggedFailure = false;
 let hasLoggedUnwired = false;
 let hasLoggedDisabled = false;
@@ -38,11 +39,14 @@ let hasLoggedDisabled = false;
  * the MCP server path run in (no pi host, no `pi.events`).
  */
 export function wireDispositionBusEmitter(emitFn) {
-    busEmit = emitFn;
+    liveEmitter.wire(emitFn);
+}
+export function wireDispositionBusEmitterGetter(getter) {
+    liveEmitter.wireGetter(getter);
 }
 /** Test-only: reset module state between test files. */
 export function _resetDispositionPublishForTests() {
-    busEmit = undefined;
+    liveEmitter.reset();
     hasLoggedFailure = false;
     hasLoggedUnwired = false;
     hasLoggedDisabled = false;
@@ -63,6 +67,7 @@ export function publishDisposition(args) {
         }
         return;
     }
+    const busEmit = liveEmitter.get();
     if (!busEmit) {
         if (!hasLoggedUnwired) {
             hasLoggedUnwired = true;
@@ -88,6 +93,7 @@ export function publishDisposition(args) {
             reason: args.reason,
         };
         busEmit(BUS_DISPOSITION_EVENT, payload);
+        hasLoggedFailure = false;
         logBusEvent({
             event: BUS_DISPOSITION_EVENT,
             outcome: "emitted",
@@ -103,6 +109,7 @@ export function publishDisposition(args) {
         });
         if (!hasLoggedFailure) {
             hasLoggedFailure = true;
+            recordStaleBusFailure(BUS_DISPOSITION_EVENT, err);
             args.dbg?.(`disposition-publish: pilens:diagnostic:disposition emit failed (further failures suppressed): ${err}`);
         }
     }

package/node_modules/pi-lens/dist/clients/durable-store.js

@@ -0,0 +1,97 @@
+/**
+ * Synchronous locked read-modify-write commit seam for behavior-gating JSON
+ * stores shared by multiple pi-lens processes.
+ *
+ * The authoritative read happens only after the bounded PID lock is held; the
+ * caller merges only its delta, publication is a throwing atomic replacement,
+ * and success telemetry runs only after publication succeeds.
+ *
+ * Short synchronous commits use a file lock. Awaited commits use the shared
+ * quarantine directory lock, preserving bounded contention and stale-owner
+ * recovery without allowing a late release to delete a replacement owner.
+ */
+import * as fs from "node:fs";
+import fsp from "node:fs/promises";
+import { writeFileAtomic, writeFileAtomicAsync } from "./atomic-write.js";
+import { acquireBoundedPidFileLock, acquireQuarantinePidFileLock, } from "./bounded-pid-file-lock.js";
+function readLocked(path) {
+    try {
+        return fs.readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function commitDurableStore(options) {
+    const release = options.onContention === "skip-log"
+        ? acquireBoundedPidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "skip-log",
+            logContention: options.logContention,
+        })
+        : acquireBoundedPidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "throw",
+        });
+    if (!release)
+        return undefined;
+    let committed;
+    try {
+        const current = options.deserialize(readLocked(options.path));
+        committed = options.merge(current);
+        writeFileAtomic(options.path, options.serialize(committed), {
+            bestEffort: false,
+        });
+        options.afterWriteLocked?.(committed);
+    }
+    finally {
+        release();
+    }
+    return committed;
+}
+async function readLockedAsync(path) {
+    try {
+        return await fsp.readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function commitDurableStoreAsync(options) {
+    const release = options.onContention === "skip-log"
+        ? await acquireQuarantinePidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            staleMs: options.staleMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "skip-log",
+            logContention: options.logContention,
+        })
+        : await acquireQuarantinePidFileLock(`${options.path}.lock`, {
+            waitMs: options.waitMs,
+            retryMs: options.retryMs,
+            staleMs: options.staleMs,
+            timeoutMessage: options.timeoutMessage,
+            onContention: "throw",
+        });
+    if (!release)
+        return undefined;
+    try {
+        const current = options.deserialize(await readLockedAsync(options.path));
+        const committed = options.merge(current);
+        await writeFileAtomicAsync(options.path, options.serialize(committed), {
+            bestEffort: false,
+        });
+        await options.afterWriteLocked?.(committed);
+        return committed;
+    }
+    finally {
+        await release();
+    }
+}