pi-lens 4.1.2 → 4.1.4

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

@@ -10,16 +10,20 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { logSessionStart } from "../../../sessionstart-logger.js";
+import { incrementDegradationCount } from "../../../degradation-ledger.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, 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";
 import { isInSpawnTimeoutCooldown } from "../../../spawn-timeout-cooldown.js";
+import { createAvailabilityProbeFlight } from "../../../availability-probe-flight.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";
 /**
@@ -42,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");
@@ -86,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();
 /**
@@ -118,14 +115,14 @@ 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) {
+async function runManagedVerification(candidate, stamp, priorAttempts, generation, verificationArgs = ["--version"]) {
     let transient = false;
     let ok;
     try {
         const { verifyToolBinary } = await import("../../../installer/index.js");
         ok = await verifyToolBinary(candidate, undefined, () => {
             transient = true;
-        }, MANAGED_VERIFY_TIMEOUT_MS);
+        }, MANAGED_VERIFY_TIMEOUT_MS, verificationArgs);
     }
     catch {
         // The verifier itself could not run — installer-isolated unit tests mock
@@ -164,7 +161,7 @@ async function runManagedVerification(candidate, stamp, priorAttempts, generatio
     }
     return ok ? "ok" : "broken";
 }
-async function verifyManagedCandidate(candidate) {
+async function verifyManagedCandidate(candidate, verificationArgs = ["--version"]) {
     let stamp;
     try {
         const stat = fs.statSync(candidate);
@@ -186,7 +183,7 @@ async function verifyManagedCandidate(candidate) {
     if (existing)
         return existing;
     const generation = availabilityGeneration.capture();
-    const probe = runManagedVerification(candidate, stamp, priorAttempts, generation).finally(() => {
+    const probe = runManagedVerification(candidate, stamp, priorAttempts, generation, verificationArgs).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, () => {
@@ -218,14 +215,40 @@ async function verifyManagedCandidate(candidate) {
  * 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) {
+export async function findManagedNodeToolBinary(tool, verificationArgs = ["--version"]) {
     for (const candidate of managedNodeToolCandidates(tool)) {
-        const verdict = await verifyManagedCandidate(candidate);
+        const verdict = await verifyManagedCandidate(candidate, verificationArgs);
         if (verdict === "ok" || verdict === "unverified")
             return candidate;
     }
     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
 // =============================================================================
@@ -236,21 +259,30 @@ export async function findManagedNodeToolBinary(tool) {
  * 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 = "") {
+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
@@ -261,9 +293,15 @@ export function createVenvFinder(command, windowsExt = "") {
         // 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);
+        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;
     };
@@ -366,6 +404,19 @@ const latchedUnavailableByCwd = new PathKeyedMap(normalizeMapKey);
 // 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");
+export const getDispatchAvailabilityGeneration = () => availabilityGeneration.current();
+const checkerProbeFlights = createAvailabilityProbeFlight({ generation: getDispatchAvailabilityGeneration });
+export function recordAvailabilityProbeOverrun(tool, key, elapsedMs, budgetMs, failure) {
+    if (budgetMs === undefined || elapsedMs <= budgetMs)
+        return;
+    if (failure === "timeout" && elapsedMs <= budgetMs * 2)
+        return;
+    incrementDegradationCount({
+        kind: "availability-probe-overrun",
+        subject: `${tool}:${key}`,
+        reason: `probe took ${Math.round(elapsedMs)}ms; budget was ${Math.round(budgetMs)}ms`,
+    });
+}
 function installStateFor(cwd, toolId) {
     let states = installAttemptsByCwd.get(cwd);
     if (!states) {
@@ -488,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`
@@ -598,6 +684,9 @@ export function resetDispatchAvailabilityState() {
     managedVerifyInFlight.clear();
     resetPathWalkMemo();
     availabilityGeneration.bump();
+    checkerProbeFlights.clear();
+    cwdProbeFlights.clear();
+    // The generation bump invalidates dispatcherProbeFlights in its owner module.
 }
 /**
  * Create a cached availability checker for a command.
@@ -620,18 +709,21 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
     const cacheByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
     const inFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
     let checkerGeneration = availabilityGeneration.current();
-    const findCommand = createVenvFinder(command, windowsExt);
+    let checkerFlightGeneration = 0;
+    const findCommand = createVenvFinder(command, windowsExt, versionArgs);
     function ensureCurrentGeneration() {
         if (checkerGeneration === availabilityGeneration.current())
             return;
         cacheByCwd.clear();
         inFlightByCwd.clear();
         checkerGeneration = availabilityGeneration.current();
+        checkerFlightGeneration++;
     }
     const reset = () => {
         cacheByCwd.clear();
         inFlightByCwd.clear();
         checkerGeneration = availabilityGeneration.current();
+        checkerFlightGeneration++;
     };
     function getCache(cwd) {
         ensureCurrentGeneration();
@@ -692,9 +784,9 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             cause: verdict.cause,
             elapsedMs: verdict.elapsedMs,
             latched,
-            ...(verdict.classifiedBy !== undefined && {
-                classifiedBy: verdict.classifiedBy,
-            }),
+            // Every caller passes this (#2209); a direct key, not a conditional
+            // spread, keeps it visible to the call-shaped classifiedBy sweep.
+            classifiedBy: verdict.classifiedBy,
             ...(verdict.evidence !== undefined && { evidence: verdict.evidence }),
             ...(verdict.hostStallMs !== undefined && {
                 hostStallMs: verdict.hostStallMs,
@@ -777,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:
@@ -807,17 +908,22 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
             const startedAt = Date.now();
             let result;
             let hostStallMs;
+            let probeJoined = false;
             try {
-                result = await safeSpawnAsync(cmd, versionArgs, {
+                const shared = checkerProbeFlights.run(`checker:${command}|${versionArgs.join("|")}|${key}|${checkerFlightGeneration}|${windowsExt}|${cmd}|${JSON.stringify(Object.entries(env ?? {}).sort(([a], [b]) => compareOrdinal(a, b)))}`, () => safeSpawnAsync(cmd, versionArgs, {
                     timeout: options.probeTimeout ?? 5000,
                     cwd: resolvedCwd,
                     env,
-                });
+                    input: "",
+                }));
+                probeJoined = shared.joined;
+                result = await shared.promise;
             }
             finally {
                 hostStallMs = stallSampler.stop();
             }
             const elapsedMs = Date.now() - startedAt;
+            recordAvailabilityProbeOverrun(command, resolvedCwd, elapsedMs, options.probeTimeout ?? 5000, result.failure);
             if (!result.error && result.status === 0) {
                 cache.command = cmd;
                 noteDecision(cache, resolvedCwd, {
@@ -826,8 +932,12 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                     cause: "ok",
                     elapsedMs,
                     hostStallMs,
-                    classifiedBy: "probe",
-                    evidence: describeProbeEvidence(result),
+                    classifiedBy: probeJoined ? "joined" : "probe",
+                    evidence: {
+                        ...describeProbeEvidence(result),
+                        ...(await describeManagedResolution(command, cmd)),
+                        resolveMs,
+                    },
                 });
                 return true;
             }
@@ -846,7 +956,7 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
                 cause,
                 elapsedMs,
                 hostStallMs,
-                classifiedBy: "probe",
+                classifiedBy: probeJoined ? "joined" : "probe",
                 evidence,
             });
             return false;
@@ -885,6 +995,9 @@ export function createAvailabilityChecker(command, windowsExt = "", versionArgs
     }
     return { isAvailableAsync, getCommand, getOutcome, getVerdict, reset };
 }
+const cwdProbeFlights = createAvailabilityProbeFlight({
+    generation: getDispatchAvailabilityGeneration,
+});
 /**
  * Per-cwd cached availability probe for spawn signatures that don't fit
  * `createAvailabilityChecker` — multi-arg subcommands like `cargo clippy
@@ -957,7 +1070,7 @@ export function createCwdCachedProbe(probe, options) {
             ...(retryAfterMs !== undefined && { retryAfterMs }),
             ...(options.budgetMs !== undefined && { budgetMs: options.budgetMs }),
             // Every verdict here is derived from the probe this seam just ran.
-            classifiedBy: "probe",
+            classifiedBy: verdict.classifiedBy ?? "probe",
             ...(verdict.evidence !== undefined && { evidence: verdict.evidence }),
         }, key);
     }
@@ -981,20 +1094,24 @@ export function createCwdCachedProbe(probe, options) {
             const startedAt = Date.now();
             let result;
             let thrown;
+            let probeJoined = false;
             try {
-                result = await probe(key);
+                const shared = cwdProbeFlights.run(`cwd:${options.tool}|${options.flightKeyComponent ?? ""}|${key}`, () => probe(key));
+                probeJoined = shared.joined;
+                result = await shared.promise;
             }
             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)),
             };
+            recordAvailabilityProbeOverrun(options.tool, key, elapsedMs, options.budgetMs, shape.failure);
+            // 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`.
             if (result && !result.error && result.status === 0) {
                 note(latch, key, {
                     available: true,
@@ -1002,6 +1119,7 @@ export function createCwdCachedProbe(probe, options) {
                     cause: "ok",
                     elapsedMs,
                     hostStallMs,
+                    classifiedBy: probeJoined ? "joined" : "probe",
                     evidence: describeProbeEvidence(result, options.tool),
                 });
                 return true;
@@ -1017,6 +1135,7 @@ export function createCwdCachedProbe(probe, options) {
                 cause,
                 elapsedMs,
                 hostStallMs,
+                classifiedBy: probeJoined ? "joined" : "probe",
                 evidence,
             });
             return false;
@@ -1069,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);
@@ -1108,6 +1217,7 @@ async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--ve
         const versionCheck = await safeSpawnAsync(command, versionArgs, {
             timeout,
             cwd,
+            input: "",
         });
         if (!versionCheck.error && versionCheck.status === 0) {
             return command;
@@ -1141,7 +1251,7 @@ async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--ve
     return null;
 }
 export async function resolveCommandArgsWithInstallFallback(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
-    const versionCheck = await safeSpawnAsync(command.cmd, [...command.args, ...versionArgs], { timeout, cwd });
+    const versionCheck = await safeSpawnAsync(command.cmd, [...command.args, ...versionArgs], { timeout, cwd, input: "" });
     if (!versionCheck.error && versionCheck.status === 0) {
         return command;
     }
@@ -1318,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;
@@ -1353,19 +1486,19 @@ export async function isSgAvailableAsync() {
         return memo;
     if (sgAvailableInFlight)
         return sgAvailableInFlight;
-    sgAvailableInFlight = (async () => {
+    const flight = (async () => {
         const startedAt = Date.now();
         sgSweepSawTransient = false;
         sgSweepTransientCause = "probe-timeout";
         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;
             }
         }
@@ -1374,7 +1507,7 @@ export async function isSgAvailableAsync() {
             if (await probeAstGrepCommandAsync(cmd)) {
                 sgCmd = cmd;
                 sgCmdArgs = [];
-                noteSgAvailable(startedAt);
+                noteSgAvailable(startedAt, { source: "global" });
                 return true;
             }
         }
@@ -1385,7 +1518,7 @@ export async function isSgAvailableAsync() {
             if (globalBin && (await probeAstGrepCommandAsync(globalBin))) {
                 sgCmd = globalBin;
                 sgCmdArgs = [];
-                noteSgAvailable(startedAt);
+                noteSgAvailable(startedAt, { source: "global" });
                 return true;
             }
         }
@@ -1393,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
@@ -1415,9 +1548,19 @@ export async function isSgAvailableAsync() {
         noteSgUnavailable(startedAt, sgSweepSawTransient ? "transient" : "missing", sgSweepSawTransient ? sgSweepTransientCause : "not-found");
         return false;
     })().finally(() => {
-        sgAvailableInFlight = null;
+        // Identity-guarded release (#1968's pattern): clear the slot only if THIS
+        // flight still owns it. `ensureCurrentSgGeneration()` above nulls the slot
+        // on a generation bump (a session reset arriving mid-flight) so the NEXT
+        // caller starts a fresh flight rather than sharing this one's stale-generation
+        // answer — that fresh flight is a live successor. Without the guard, this
+        // flight's own late settlement would stomp the slot back to null out from
+        // under that successor, and the caller after it would start a redundant
+        // THIRD probe instead of sharing the still-running second one.
+        if (sgAvailableInFlight === flight)
+            sgAvailableInFlight = null;
     });
-    return sgAvailableInFlight;
+    sgAvailableInFlight = flight;
+    return flight;
 }
 /**
  * Record a successful shared-ast-grep sweep, with one decision record.
@@ -1432,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;
@@ -1442,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",
@@ -1449,6 +1610,7 @@ function noteSgAvailable(startedAt, opts = {}) {
         cause: provisional ? sgSweepTransientCause : "ok",
         elapsedMs: Date.now() - startedAt,
         latched: !provisional,
+        classifiedBy: "probe",
         hostStallMs: sgSweepHostStallMs,
         budgetMs: 5000,
         ...(provisional && {
@@ -1472,6 +1634,9 @@ function noteSgUnavailable(startedAt, outcome, cause) {
         hostStallMs: sgSweepHostStallMs,
         ...(retryAfterMs > 0 && { retryAfterMs }),
         budgetMs: 5000,
+        // Sibling of noteSgAvailable's "probe": both report the same
+        // candidate sweep this function ran (#2209).
+        classifiedBy: "probe",
     });
 }
 export function getSgCommand() {