@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

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

@@ -15,9 +15,10 @@ 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, getInstallAttempt, getLastEnsureResolutionSource, getToolInstallStrategy, isSpawnableCommand, resetPathWalkMemo, } from "../../../installer/index.js";
+import { ensureTool, findManagedToolBinary, getInstallAttempt, getLastEnsureResolutionSource, getToolInstallStrategy, isSpawnableCommand, resetPathWalkMemo, } from "../../../installer/index.js";
 import { getServersForFileWithConfig, isServerDisabled, } from "../../../lsp/config.js";
-import { findGlobalBinary } from "../../../package-manager.js";
+import { findGlobalBinary, findLocalBinAt, findLocalBinsUpwards, findLocalBinUpwards, VENDOR_BIN_DIRS, VENV_BIN_DIRS, } from "../../../package-manager.js";
+import { logLatency } from "../../../latency-logger.js";
 import { safeSpawnAsync } from "../../../safe-spawn.js";
 import { compareOrdinal } from "../../../string-utils.js";
 import { getToolCommandSpec, shouldAutoInstallTool, } from "../../../tool-policy.js";
@@ -45,29 +46,21 @@ export function lspPrimaryCoversFile(ctx, serverId) {
     const primary = getServersForFileWithConfig(ctx.filePath).find((s) => s.role !== "auxiliary");
     return primary?.id === serverId;
 }
+const _realThisDir = (() => {
+    if (typeof __dirname !== "undefined")
+        return __dirname;
+    return path.dirname(fileURLToPath(import.meta.url));
+})();
+let _thisDir = _realThisDir;
 /**
- * Walk up from startDir until we find a directory containing node_modules/.bin.
- * Returns all such roots found up to the filesystem root — not just the nearest —
- * so callers can search them all for a specific binary.
+ * Test-only override for pi-lens's OWN install-tree root (#2544 round 4 F1).
+ * `_thisDir` is fixed at module load from the running file's own location, so
+ * a test cannot otherwise place it under a synthetic HOME to prove the
+ * own-install walk's `ceiling: false` exemption without writing into this
+ * process's REAL, shared `node_modules` tree.
  */
-function findNodeBinRoots(startDir) {
-    const roots = [];
-    let current = startDir;
-    const fsRoot = path.parse(current).root;
-    while (current !== fsRoot) {
-        if (fs.existsSync(path.join(current, "node_modules", ".bin"))) {
-            roots.push(current);
-        }
-        const parent = path.dirname(current);
-        if (parent === current)
-            break;
-        current = parent;
-    }
-    return roots;
-}
-let _thisDir = path.dirname(fileURLToPath(import.meta.url));
-if (typeof __dirname !== "undefined") {
-    _thisDir = __dirname;
+export function _setThisDirForTests(dir) {
+    _thisDir = dir ?? _realThisDir;
 }
 // Managed tools directory (~/.pi-lens/tools) — where ensureTool() installs binaries
 const _managedToolsDir = path.join(getGlobalPiLensDir(), "tools");
@@ -89,9 +82,10 @@ function managedNodeToolCandidates(tool) {
  * 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.
+ * A plain `Map`, not a `PathKeyedMap`: every path keyed here is produced by
+ * `path.join` from one of two producers — `managedNodeToolCandidates` and the
+ * installer's `findManagedToolBinary` (#2140) — so the write and read forms are
+ * the same string by construction and cannot diverge on case or separator.
  */
 const managedBinaryVerdicts = new Map();
 /**
@@ -229,6 +223,32 @@ export async function findManagedNodeToolBinary(tool, verificationArgs = ["--ver
     }
     return null;
 }
+/**
+ * The release-managed binary for a tool (`~/.pi-lens/bin/<tool>`), or null when
+ * the registry does not put this tool there / nothing on disk actually runs.
+ *
+ * `findManagedToolBinary` is the INSTALLER's own lookup — the one `getToolPath`
+ * runs before PATH for every github/maven/archive-strategy tool, and the one
+ * `getToolEnvironment` puts at the front of a spawn's PATH. Calling it here is
+ * what makes probe and spawn resolve through a single definition instead of two
+ * (#2140): before this, the probe fell straight to the bare command name, missed
+ * PATH, and latched `missing` — while the install fallback a few hundred ms
+ * later handed the caller the very binary sitting in that directory. Every
+ * session, for every tool the user already had (7 unavailable/available pairs in
+ * one 3h dogfood window).
+ *
+ * Verification is the same `verifyManagedCandidate` the npm-shim rung above
+ * uses, for the same reason (#1657): `findManagedToolBinary` answers from a bare
+ * `fs.access`, and an on-disk binary that cannot run must not shadow a working
+ * PATH binary — it falls through instead.
+ */
+async function findManagedReleaseBinary(tool, verificationArgs = ["--version"]) {
+    const candidate = await findManagedToolBinary(tool);
+    if (!candidate)
+        return null;
+    const verdict = await verifyManagedCandidate(candidate, verificationArgs);
+    return verdict === "ok" || verdict === "unverified" ? candidate : null;
+}
 // =============================================================================
 // VENV-AWARE COMMAND FINDER
 // =============================================================================
@@ -239,21 +259,30 @@ export async function findManagedNodeToolBinary(tool, verificationArgs = ["--ver
  * 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).
+ *
+ * The venv directory list is `VENV_BIN_DIRS` (`package-manager.ts`), shared
+ * with `formatters.ts`'s `findInVenv` and `dead-code-client.ts`'s vulture
+ * candidates — three independent spellings of the same four directories before
+ * #2544 review F1.
+ *
+ * Resolution is a fixed lookup at `cwd` ONLY (`findLocalBinAt`, no ancestor
+ * walk). #2544 review round 3 folded this onto the shared ANCESTOR walker,
+ * on the reasoning that a monorepo package should find its repo-root venv —
+ * but that was an unrequested behaviour change with no #2514 defect behind
+ * it (#2514 is about the HOME ceiling, not about climbing at all), and the
+ * inversion is real: `~/code/app` with no venv of its own would resolve
+ * `~/code/.venv/bin/ruff` — an unrelated SIBLING project's interpreter —
+ * ahead of PATH. Reverted in round 4 F2. The HOME ceiling is moot here: a
+ * lookup at exactly `cwd` can never climb past it.
  */
 export function createVenvFinder(command, windowsExt = "", verificationArgs = ["--version"]) {
     return async (cwd) => {
-        const venvPaths = [
-            `.venv/bin/${command}`,
-            `venv/bin/${command}`,
-            `.venv/Scripts/${command}${windowsExt}`,
-            `venv/Scripts/${command}${windowsExt}`,
-        ];
-        for (const venvPath of venvPaths) {
-            const fullPath = path.join(cwd, venvPath);
-            if (fs.existsSync(fullPath)) {
-                return fullPath;
-            }
-        }
+        const venvBin = findLocalBinAt(command, cwd, {
+            windowsExt,
+            binDirs: VENV_BIN_DIRS,
+        });
+        if (venvBin)
+            return venvBin;
         // 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
@@ -267,6 +296,12 @@ export function createVenvFinder(command, windowsExt = "", verificationArgs = ["
         const managed = await findManagedNodeToolBinary(command, verificationArgs);
         if (managed)
             return managed;
+        // Release-managed install (`~/.pi-lens/bin/<command>`) — where `ensureTool`
+        // puts every github/maven/archive-strategy tool. Same rung, same reason as
+        // the npm shim above, for the other half of the managed families (#2140).
+        const release = await findManagedReleaseBinary(command, verificationArgs);
+        if (release)
+            return release;
         // Fall back to global
         return command;
     };
@@ -504,6 +539,41 @@ function sourceTagForToolId(toolId) {
             return undefined;
     }
 }
+/**
+ * `binary`/`source` for a probe that resolved through one of pi-lens's OWN
+ * managed installs rather than through PATH or a project venv (#2140). A reader
+ * of latency.log could otherwise not tell the two apart, and the whole point of
+ * the fix is that the managed directories now answer where PATH used to miss.
+ *
+ * BOTH managed rungs are asked, in the order `createVenvFinder` walks them
+ * (#2140 review F1). The first version asked only about the release directory,
+ * so every npm-shim hit — knip, jscpd, madge, pyright, biome, htmlhint,
+ * stylelint — logged an evidence-free row indistinguishable from a PATH hit,
+ * while the doc claimed the opposite. Each rung is asked of THE function that
+ * produced its own paths (`managedNodeToolCandidates`, `findManagedToolBinary`)
+ * and settled by string identity, never by a path-prefix predicate over a
+ * directory: a second opinion about which paths are managed is exactly the
+ * parallel-list drift `sourceTagForToolId` exists to avoid, and it would answer
+ * differently for case or separator variants.
+ *
+ * `binary` present IS the managed hit; `source` names the family whenever the
+ * command is a registry id (`sourceTagForToolId` reads the registry's own
+ * `installStrategy`). A managed shim whose COMMAND is not itself a registry id
+ * — `markdownlint-cli2`, installed under registry id `markdownlint` — carries
+ * `binary` alone rather than a guessed family. `binary` is a BASENAME, never
+ * the absolute path — same rule as every other evidence field (#1568 review).
+ */
+async function describeManagedResolution(tool, resolved) {
+    const managed = managedNodeToolCandidates(tool).includes(resolved) ||
+        (await findManagedToolBinary(tool)) === resolved;
+    if (!managed)
+        return {};
+    const source = sourceTagForToolId(tool);
+    return {
+        binary: path.basename(resolved),
+        ...(source !== undefined && { source }),
+    };
+}
 /**
  * How to tag a not-fresh install resolution in the compensating row's
  * evidence (#1636 review, carried over from #1615's verify). `getInstallAttempt`
@@ -799,7 +869,16 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                 });
                 return false;
             }
+            // Resolution is measured separately from the spawn (#2140 review F2).
+            // It is no longer free — the managed rungs stat two directories and,
+            // on a first touch, pay their own verification spawn — and it runs
+            // BEFORE `startedAt`, so neither `durationMs` nor
+            // `recordAvailabilityProbeOverrun` can see it. Folding it into
+            // `durationMs` would instead charge the probe budget for work that
+            // budget does not govern, so the two spans are reported side by side.
+            const resolveStartedAt = Date.now();
             const cmd = await findCommand(resolvedCwd);
+            const resolveMs = Date.now() - resolveStartedAt;
             // #1995: a command cooling down after a RUNTIME timeout (lint or
             // autofix lane blew its real budget) must not re-probe on every
             // edit - the positive verdict is effectively cooled. Consult-only:
@@ -854,7 +933,11 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                     elapsedMs,
                     hostStallMs,
                     classifiedBy: probeJoined ? "joined" : "probe",
-                    evidence: describeProbeEvidence(result),
+                    evidence: {
+                        ...describeProbeEvidence(result),
+                        ...(await describeManagedResolution(command, cmd)),
+                        resolveMs,
+                    },
                 });
                 return true;
             }
@@ -1105,30 +1188,20 @@ export function resolveToolCommand(cwd, toolId) {
         return null;
     return resolveNodeToolCommand(cwd, spec.command, spec.windowsExt ?? ".cmd");
 }
+/**
+ * Composer's `vendor/bin/<tool>` from the nearest ancestor that has one.
+ *
+ * Delegates to THE shared bin walker (#2544 review F1): this was a fifth
+ * private copy of that climb, unceilinged, so a `vendor/bin` at or above
+ * `$HOME` — which can never be this project's own Composer install — was
+ * resolved as the project's tool (#2514, same class as `findInVendorBin`,
+ * which had already been folded).
+ */
 export function resolveVendorToolCommand(cwd, toolName, windowsExt = ".bat") {
-    const isWin = process.platform === "win32";
-    const candidates = isWin
-        ? [
-            path.join("vendor", "bin", `${toolName}${windowsExt}`),
-            path.join("vendor", "bin", toolName),
-        ]
-        : [path.join("vendor", "bin", toolName)];
-    let dir = cwd;
-    const root = path.parse(dir).root;
-    while (true) {
-        for (const candidate of candidates) {
-            const full = path.join(dir, candidate);
-            if (fs.existsSync(full))
-                return full;
-        }
-        if (dir === root)
-            break;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return null;
+    return (findLocalBinUpwards(toolName, cwd, {
+        windowsExt,
+        binDirs: VENDOR_BIN_DIRS,
+    }) ?? null);
 }
 export async function resolveToolCommandWithInstallFallback(cwd, toolId, timeout = 5000) {
     const spec = getToolCommandSpec(toolId);
@@ -1355,17 +1428,40 @@ function buildSgLocalBins() {
             : [".cmd", ".exe", ""]
         : [""];
     const binaryCandidates = ["ast-grep", "sg"].flatMap((base) => extensions.map((ext) => `${base}${ext}`));
-    const binRoots = [
-        ...findNodeBinRoots(_thisDir),
-        ...findNodeBinRoots(process.cwd()),
-        _managedToolsDir,
+    // THE shared bin walk (#2544 review F1). This used to be a private
+    // `findNodeBinRoots` climb with no HOME ceiling, so on a box with a
+    // home-level `node_modules` (the pi-extensions manifest installs its own
+    // bins, #2514) `$HOME` itself came back as a bin root and an unrelated
+    // ast-grep was probed as if it were this project's. `windowsExt: ""`
+    // because the candidate names already carry their extensions — in a
+    // shell-dependent ORDER (`hasBash` above) that a single `windowsExt`
+    // cannot express.
+    //
+    // The PROJECT walk (from `process.cwd()`) keeps the default HOME ceiling —
+    // a `node_modules/.bin/ast-grep` at or above `$HOME` can never be THIS
+    // project's own dependency. pi-lens's OWN install-tree walk (from
+    // `_thisDir`) is exempt (`ceiling: false`, #2544 round 4 F1): `pi install
+    // npm:pi-lens` installs into the HOME-level manifest
+    // (`~/package.json` → `~/node_modules/pi-lens`), so pi-lens's bundled
+    // `@ast-grep/cli` shim can sit AT `~/node_modules/.bin/ast-grep` — exactly
+    // the directory the PROJECT ceiling exists to stop at. A previous version
+    // of this comment claimed the own install always lives "under"
+    // `~/.pi/extensions/…`, below the ceiling; that is false for the
+    // HOME-level manifest layout, and the round-2 ceiling silently made this
+    // walk return nothing for it (PATH, `findGlobalBinary` and npx do not
+    // cover this location either). `_managedToolsDir` (`~/.pi-lens/tools`) is
+    // a fixed location, not a walk, so it is checked directly as before —
+    // also own-install, since `ensureTool()` puts npm-strategy installs there.
+    const projectWalkOptions = { windowsExt: "" };
+    const ownInstallWalkOptions = { windowsExt: "", ceiling: false };
+    const bins = [
+        ...findLocalBinsUpwards(binaryCandidates, _thisDir, ownInstallWalkOptions).map((binPath) => ({ path: binPath, source: "own-install" })),
+        ...findLocalBinsUpwards(binaryCandidates, process.cwd(), projectWalkOptions).map((binPath) => ({ path: binPath, source: "project" })),
     ];
-    const bins = [];
-    for (const root of binRoots) {
-        for (const candidate of binaryCandidates) {
-            const localBin = path.join(root, "node_modules", ".bin", candidate);
-            if (fs.existsSync(localBin))
-                bins.push(localBin);
+    for (const candidate of binaryCandidates) {
+        const managedBin = path.join(_managedToolsDir, "node_modules", ".bin", candidate);
+        if (fs.existsSync(managedBin)) {
+            bins.push({ path: managedBin, source: "own-install" });
         }
     }
     return bins;
@@ -1397,12 +1493,12 @@ export async function isSgAvailableAsync() {
         sgSweepHostStallMs = 0;
         sgSweepUnreachable = [];
         sgSweepDurablyMissing = [];
-        // 1. Local node_modules/.bin
-        for (const localBin of buildSgLocalBins()) {
-            if (await probeAstGrepCommandAsync(localBin)) {
-                sgCmd = localBin;
+        // 1. Local node_modules/.bin (own-install tree, then project tree)
+        for (const candidate of buildSgLocalBins()) {
+            if (await probeAstGrepCommandAsync(candidate.path)) {
+                sgCmd = candidate.path;
                 sgCmdArgs = [];
-                noteSgAvailable(startedAt);
+                noteSgAvailable(startedAt, { source: candidate.source });
                 return true;
             }
         }
@@ -1411,7 +1507,7 @@ export async function isSgAvailableAsync() {
             if (await probeAstGrepCommandAsync(cmd)) {
                 sgCmd = cmd;
                 sgCmdArgs = [];
-                noteSgAvailable(startedAt);
+                noteSgAvailable(startedAt, { source: "global" });
                 return true;
             }
         }
@@ -1422,7 +1518,7 @@ export async function isSgAvailableAsync() {
             if (globalBin && (await probeAstGrepCommandAsync(globalBin))) {
                 sgCmd = globalBin;
                 sgCmdArgs = [];
-                noteSgAvailable(startedAt);
+                noteSgAvailable(startedAt, { source: "global" });
                 return true;
             }
         }
@@ -1430,7 +1526,7 @@ export async function isSgAvailableAsync() {
         if (await probeAstGrepCommandAsync("npx", ["--no", "--", "ast-grep"])) {
             sgCmd = "npx";
             sgCmdArgs = ["--no", "--", "ast-grep"];
-            noteSgAvailable(startedAt);
+            noteSgAvailable(startedAt, { source: "npx" });
             return true;
         }
         // Nothing answered, and nothing answered TRANSIENTLY, while the verdict we
@@ -1479,6 +1575,11 @@ export async function isSgAvailableAsync() {
  * `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.
+ *
+ * `source` (omitted for a `retained` win, which resolved nothing new this
+ * sweep) logs one `tool_bin_resolved` phase so F1's own-install-vs-project
+ * ceiling distinction is visible in `latency.log` instead of only inferable
+ * from a bin's absence (#2544 round 4 F4).
  */
 function noteSgAvailable(startedAt, opts = {}) {
     const provisional = sgSweepSawTransient;
@@ -1489,6 +1590,19 @@ function noteSgAvailable(startedAt, opts = {}) {
     else {
         sgLatch.noteAvailable();
     }
+    if (opts.source) {
+        logLatency({
+            type: "phase",
+            phase: "tool_bin_resolved",
+            filePath: "<pi-lens>",
+            durationMs: Math.round(Date.now() - startedAt),
+            metadata: {
+                tool: "ast-grep",
+                source: opts.source,
+                ceilingApplied: opts.source === "project",
+            },
+        });
+    }
     logAvailabilityDecision({
         tool: "ast-grep",
         verdict: "available",

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

@@ -14,8 +14,39 @@
 import { createAvailabilityLatch, logAvailabilityDecision, } from "./availability-policy.js";
 import { probeAvailabilityCandidates } from "./candidate-probe.js";
 import { createAvailabilityProbeFlight } from "../../../availability-probe-flight.js";
+import { createGenerationSource } from "../../../generation-guard.js";
 import { createSingleFlight } from "../../../single-flight.js";
-const toolchainProbeFlights = createAvailabilityProbeFlight();
+/**
+ * Session generation for toolchain-availability resets (#2455 fix round 3, F2).
+ *
+ * `reset()` clears the memo and the latch, but a probe that was ALREADY in
+ * flight when it ran knows nothing about that. Without a generation, a
+ * post-reset caller joins the pre-reset flight and, worse, that flight's own
+ * settlement writes its stale verdict back into the freshly cleared latch — so
+ * a tool installed between sessions still read "missing" for the whole new
+ * session. That is #1674's defect read from both the sharing side and the
+ * settle side, and the reason `SingleFlightOptions.generation` exists.
+ *
+ * This is the repo's extracted primitive (`clients/generation-guard.ts`, #1754)
+ * rather than a hand-rolled counter (#2455 fix round 4, F1). Two things come
+ * with it that the hand-rolled form did not have: the source is declared by
+ * construction, so the #1754 ratchet can see it; and `guardedWrite` puts every
+ * superseded write in the degradation ledger as a bounded
+ * `generation-guard-stale-write` record per (source, subject), so a dogfood
+ * session can tell "the guard is working" from "the guard never fires" instead
+ * of watching superseded writes vanish silently (F4).
+ *
+ * A module-level source rather than a per-instance one, deliberately. It is a
+ * counter, so nothing has to be hand-maintained and no flight is retained for
+ * the sake of superseding it. And `toolchainProbeFlights` is itself shared
+ * ACROSS instances (#2131: two clients probing the same candidate list run one
+ * sweep), so its supersede signal cannot live on any one instance. The cost is
+ * that resetting one toolchain also supersedes another's in-flight sweep; that
+ * is at worst one extra probe, never a wrong verdict, and every registered
+ * reset fires in the same `session_start` block anyway.
+ */
+const toolchainGenerations = createGenerationSource("toolchain-availability");
+const toolchainProbeFlights = createAvailabilityProbeFlight({ generation: toolchainGenerations.current });
 /**
  * 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
@@ -31,34 +62,61 @@ export function createToolchainAvailability(config) {
     let sweepHostStallMs = 0;
     /** What the last classified candidate returned, for the decision record. */
     let sweepEvidence;
-    const ensureFlight = createSingleFlight();
+    const ensureFlight = createSingleFlight({
+        generation: toolchainGenerations.current,
+    });
     async function findPath() {
         if (toolPath)
             return toolPath;
         const paths = process.platform === "win32" ? config.windowsPaths : config.unixPaths;
+        const handle = toolchainGenerations.capture();
         const shared = toolchainProbeFlights.run(`toolchain:${config.tool}|${config.probeArgs.join("|")}|${config.windowsPaths.join("|")}|${config.unixPaths.join("|")}`, () => probeAvailabilityCandidates(paths, config.probeArgs, config.budgetMs));
         const sweep = await shared.promise;
-        sweepSawTransient = sweep.sawTransient;
-        sweepTransientCause = sweep.transientCause;
-        sweepHostStallMs = sweep.hostStallMs;
-        sweepEvidence = sweep.evidence;
-        if (sweep.foundPath)
-            toolPath = sweep.foundPath;
+        // A reset may have landed while this sweep was running. Its answer then
+        // describes the session that just ended, so it must not write itself back
+        // into the memo `reset()` just cleared, nor into the classification fields
+        // the replacement flight reads to build ITS verdict. The memo is the
+        // sharper half: a superseded sweep that writes `foundPath` latches a path
+        // the reset may have been called BECAUSE it went away, so the seam that
+        // exists to un-latch a false "missing" would instead latch a false
+        // "found". Callers already holding this promise still get what the sweep
+        // actually found.
+        handle.guardedWrite(`findPath:${config.tool}`, () => {
+            sweepSawTransient = sweep.sawTransient;
+            sweepTransientCause = sweep.transientCause;
+            sweepHostStallMs = sweep.hostStallMs;
+            sweepEvidence = sweep.evidence;
+            if (sweep.foundPath)
+                toolPath = sweep.foundPath;
+        });
         return sweep.foundPath;
     }
     async function resolveAvailability() {
         const startedAt = Date.now();
-        const found = (await findPath()) !== null;
+        const handle = toolchainGenerations.capture();
+        const resolvedPath = await findPath();
+        const found = resolvedPath !== null;
+        // #2455 fix round 3, F2: a reset during the probe opened a NEW session.
+        // This flight answers the OLD one, so writing its verdict into the
+        // freshly cleared latch would re-latch a stale "missing" for the whole
+        // new session — the bug the reset exists to prevent, reintroduced by the
+        // reset's own timing. Report the verdict to this flight's own callers;
+        // do not latch it, and say so in the decision record's `latched`.
+        const superseded = !handle.isCurrent();
         if (found) {
-            availabilityLatch.noteAvailable();
-            config.log(`${config.label} found: ${toolPath}`);
+            handle.guardedWrite(`latch:${config.tool}`, () => availabilityLatch.noteAvailable());
+            // The RESOLVED path, not the memo (#2455 fix round 4, F6). A superseded
+            // sweep is forbidden from writing `toolPath`, so reading the memo here
+            // logged `Go found: null` on exactly the branch this line exists to
+            // explain.
+            config.log(`${config.label} found: ${resolvedPath}`);
             logAvailabilityDecision({
                 tool: config.tool,
                 verdict: "available",
                 outcome: "success",
                 cause: "ok",
                 elapsedMs: Date.now() - startedAt,
-                latched: true,
+                latched: !superseded,
                 hostStallMs: sweepHostStallMs,
                 budgetMs: config.budgetMs,
                 classifiedBy: "probe",
@@ -70,14 +128,14 @@ export function createToolchainAvailability(config) {
         // 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);
+        const retryAfterMs = handle.guardedWrite(`latch:${config.tool}`, () => availabilityLatch.noteUnavailable(outcome, cause)) ?? 0;
         logAvailabilityDecision({
             tool: config.tool,
             verdict: "unavailable",
             outcome,
             cause,
             elapsedMs: Date.now() - startedAt,
-            latched: outcome !== "transient",
+            latched: !superseded && outcome !== "transient",
             hostStallMs: sweepHostStallMs,
             ...(retryAfterMs > 0 && { retryAfterMs }),
             budgetMs: config.budgetMs,
@@ -96,5 +154,16 @@ export function createToolchainAvailability(config) {
             return memo;
         return ensureFlight.run("availability", resolveAvailability);
     }
-    return { findPath, isAvailable };
+    function reset() {
+        toolPath = null;
+        availabilityLatch.reset();
+        // Supersede every sweep and availability flight already running, in this
+        // instance and in the shared registry. No `clear()`: the generation bump
+        // is what makes a stale flight unjoinable and unable to re-latch, and
+        // `SingleFlight.release`'s identity check already stops it from evicting
+        // its successor. Clearing the SHARED registry here would additionally
+        // drop another toolchain's live claim and cost it a duplicate sweep.
+        toolchainGenerations.bump();
+    }
+    return { findPath, isAvailable, reset };
 }

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

@@ -13,24 +13,3 @@ export function readFileContent(filePath) {
         return undefined;
     }
 }
-/**
- * Parse common tool output line into a diagnostic
- * Format: file:line:col message (category)
- */
-export function parseToolLine(line, toolName, filePath) {
-    const match = line.match(/^(.+?):(\d+):(\d+)\s+(.+?)\s*\((.+?)\)/);
-    if (!match)
-        return null;
-    return {
-        id: `${toolName}-${match[2]}-${match[5]}`,
-        message: `${match[5]}: ${match[4]}`,
-        filePath,
-        line: parseInt(match[2], 10),
-        column: parseInt(match[3], 10),
-        severity: line.includes("error") ? "error" : "warning",
-        semantic: "warning",
-        tool: toolName,
-        rule: match[5],
-        fixable: false,
-    };
-}

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

@@ -70,7 +70,6 @@ const valeRunner = {
     id: "vale",
     appliesTo: ["markdown"],
     priority: PRIORITY.DOC_QUALITY,
-    enabledByDefault: true,
     skipTestFiles: false,
     async run(ctx) {
         const cwd = ctx.cwd || process.cwd();

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

@@ -19,14 +19,7 @@ import { BoundedLruCache } from "../../bounded-cache.js";
 import { compareOrdinal } from "../../string-utils.js";
 // --- Constants ---
 /** Overly broad patterns that match everything (cause false positive explosions) */
-export const OVERLY_BROAD_PATTERNS = [
-    "$NAME",
-    "$FIELD",
-    "$_",
-    "$X",
-    "$VAR",
-    "$EXPR",
-];
+const OVERLY_BROAD_PATTERNS = ["$NAME", "$FIELD", "$_", "$X", "$VAR", "$EXPR"];
 /** Maximum complexity score for rules in blockingOnly mode */
 export const MAX_BLOCKING_RULE_COMPLEXITY = 8;
 /**
@@ -126,7 +119,7 @@ export function loadYamlRulesFresh(ruleDir, severityFilter) {
     cache.set(ruleDir, { rules, signature });
     return rules;
 }
-export function getCachedRules(ruleDir, severityFilter) {
+function getCachedRules(ruleDir, severityFilter) {
     if (!fs.existsSync(ruleDir)) {
         return [];
     }
@@ -179,17 +172,6 @@ export function isOverlyBroadPattern(pattern) {
         return true;
     return /^\$[A-Z_]+$/i.test(pattern.trim());
 }
-export function isValidCondition(condition) {
-    if (!condition)
-        return false;
-    if (condition.all !== undefined && condition.all.length === 0)
-        return false;
-    if (condition.any !== undefined && condition.any.length === 0)
-        return false;
-    if (isOverlyBroadPattern(condition.pattern))
-        return false;
-    return true;
-}
 export function isStructuredRule(rule) {
     if (!rule.rule)
         return false;

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

@@ -33,7 +33,6 @@ const yamllintRunner = {
     id: "yamllint",
     appliesTo: ["yaml"],
     priority: PRIORITY.YAML_LINT,
-    enabledByDefault: true,
     skipTestFiles: false,
     async run(ctx) {
         const cwd = ctx.cwd || process.cwd();
@@ -55,6 +54,7 @@ const yamllintRunner = {
         if (!cmd)
             return { status: "skipped", diagnostics: [], semantic: "none" };
         const result = await safeSpawnAsync(cmd, ["-f", "parsable", ctx.filePath], {
+            cwd,
             timeout: 15000,
         });
         // #1816: this runner read `result.status` zero times, so a yamllint

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

@@ -44,7 +44,6 @@ const zigCheckRunner = {
     id: "zig-check",
     appliesTo: ["zig"],
     priority: PRIORITY.GENERAL_ANALYSIS,
-    enabledByDefault: true,
     skipTestFiles: false,
     async run(ctx) {
         const cwd = ctx.cwd || process.cwd();