pi-lens 4.1.2 → 4.1.4

package/dist/clients/installer/index.js

@@ -29,16 +29,17 @@
  * - rust-analyzer (Rust LSP) [GitHub release]
  * - golangci-lint (Go linting) [GitHub release]
  *
- * Manual install required (25+ tools):
- * - yaml-language-server: npm install -g yaml-language-server
- * - vscode-json-languageserver: npm install -g vscode-langservers-extracted
- * - bash-language-server: npm install -g bash-language-server
- * - svelte-language-server: npm install -g svelte-language-server
- * - vscode-css-languageserver: npm install -g vscode-langservers-extracted
- * - @prisma/language-server: npm install -g @prisma/language-server
- * - dockerfile-language-server: npm install -g dockerfile-language-server-nodejs
- * - @vue/language-server: npm install -g @vue/language-server
- * - And all language-specific servers (gopls, rust-analyzer, etc.)
+ * Every other managed tool (including several the list above omits, e.g.
+ * bash-language-server, yaml-language-server, svelte-language-server,
+ * @prisma/language-server, @vue/language-server, dockerfile-language-server-nodejs,
+ * and vscode-css-languageserver — all of which ARE auto-installed) is
+ * documented by the `TOOLS` array below, not restated here. #2638: a
+ * hand-kept "manual install" list naming specific package specs used to live
+ * in this comment, drifted from `TOOLS` (it named a since-unpublished npm
+ * package for the CSS entry, and several tools it called "manual" were
+ * already auto-install above) and nothing caught it. `TOOLS` is the single
+ * source of truth for every id, package, and strategy; deleted rather than
+ * re-derived, since a comment cannot be generated from code at write time.
  *
  * Strategies:
  * - npm packages via npx/bun
@@ -234,7 +235,12 @@ export const TOOLS = [
         checkCommand: "typescript-language-server",
         checkArgs: ["--version"],
         installStrategy: "npm",
-        packageName: "typescript-language-server",
+        // Pinned below the package's own floor: 6.0.0 declares
+        // engines.node >=22.22.2, above the pi host's own floor (pi-lens
+        // must never require more than pi does — #2633) — an unpinned
+        // install here resolves latest and prints EBADENGINE on any pi
+        // host's supported Node. 5.3.0's own floor is engines.node >=20.
+        packageName: "typescript-language-server@5.3.0",
         binaryName: "typescript-language-server",
     },
     {
@@ -383,6 +389,12 @@ export const TOOLS = [
         name: "Bash Language Server",
         checkCommand: "bash-language-server",
         checkArgs: ["--version"],
+        // The #2188 sweep measured a 9,667ms cold `--version` start with closed
+        // stdin — close enough to the 10s installer default that modest host
+        // contention pushes it over and emits a false verification degradation.
+        // 20s gives the same kind of headroom Vue's 30s bound gives its own
+        // slower cold start (#2176), without inventing a shared literal (#2194).
+        verificationTimeoutMs: 20_000,
         installStrategy: "npm",
         packageName: "bash-language-server",
         binaryName: "bash-language-server",
@@ -419,6 +431,11 @@ export const TOOLS = [
         name: "VSCode JSON Language Server",
         checkCommand: "vscode-json-language-server",
         checkArgs: ["--version"],
+        // The #2188 sweep measured an 11,047ms cold `--version` start with closed
+        // stdin — over the 10s installer default, so a cold or contended host can
+        // see a false verification degradation before the binary ever answers.
+        // 20s mirrors the bash-language-server bound above (#2194).
+        verificationTimeoutMs: 20_000,
         installStrategy: "npm",
         packageName: "vscode-langservers-extracted",
         binaryName: "vscode-json-language-server",
@@ -429,7 +446,7 @@ export const TOOLS = [
         checkCommand: "vscode-html-language-server",
         checkArgs: ["--version"],
         installStrategy: "npm",
-        packageName: "vscode-html-languageserver-bin",
+        packageName: "vscode-langservers-extracted",
         binaryName: "vscode-html-language-server",
     },
     {
@@ -465,7 +482,8 @@ export const TOOLS = [
         id: "helm",
         name: "Helm",
         checkCommand: "helm",
-        checkArgs: ["version", "--short"],
+        // intended: version --short — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "github",
         binaryName: "helm",
         github: {
@@ -517,7 +535,7 @@ export const TOOLS = [
         checkCommand: "vscode-css-language-server",
         checkArgs: ["--version"],
         installStrategy: "npm",
-        packageName: "vscode-css-languageserver",
+        packageName: "vscode-langservers-extracted",
         binaryName: "vscode-css-language-server",
     },
     {
@@ -543,6 +561,11 @@ export const TOOLS = [
         name: "Prisma Language Server",
         checkCommand: "prisma-language-server",
         checkArgs: ["--version"],
+        // #2169: a real closed-stdin cold run measured 27,265ms, and a warm-cache
+        // rerun still took 9,860ms — well past the 10s installer default. 40s
+        // keeps the same margin-over-worst-observed ratio Vue's 30s bound uses
+        // (#2176) rather than trimming it for a slower binary.
+        verificationTimeoutMs: 40_000,
         installStrategy: "npm",
         packageName: "@prisma/language-server",
         binaryName: "prisma-language-server",
@@ -552,6 +575,10 @@ export const TOOLS = [
         name: "Vue Language Server",
         checkCommand: "vue-language-server",
         checkArgs: ["--version"],
+        // Vue's launcher loads the full language-service bundle before answering
+        // --version. Its cold start exceeds the dispatch probe budget on some hosts
+        // even though warm starts complete quickly (#2176).
+        verificationTimeoutMs: 30_000,
         installStrategy: "npm",
         packageName: "@vue/language-server",
         binaryName: "vue-language-server",
@@ -561,6 +588,10 @@ export const TOOLS = [
         name: "Svelte Language Server",
         checkCommand: "svelteserver",
         checkArgs: ["--version"],
+        // #2169: a real closed-stdin cold run measured 12,410ms — over the 10s
+        // installer default, matching the bash/JSON class of false verification
+        // degradation from a cold-cache host (#2194). 20s mirrors that bound.
+        verificationTimeoutMs: 20_000,
         installStrategy: "npm",
         packageName: "svelte-language-server",
         binaryName: "svelteserver",
@@ -569,7 +600,9 @@ export const TOOLS = [
         id: "markdownlint",
         name: "markdownlint-cli2",
         checkCommand: "markdownlint-cli2",
-        checkArgs: ["--version"],
+        // `--version` is interpreted as a file glob by markdownlint-cli2. Use
+        // stdin with globs disabled so verification cannot scan the workspace.
+        checkArgs: ["--no-globs", "-"],
         installStrategy: "npm",
         packageName: "markdownlint-cli2",
         binaryName: "markdownlint-cli2",
@@ -784,7 +817,8 @@ export const TOOLS = [
         id: "spotbugs",
         name: "SpotBugs",
         checkCommand: "spotbugs",
-        checkArgs: ["-version"],
+        // intended: -version — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "archive",
         binaryName: "spotbugs",
         archive: {
@@ -1030,7 +1064,8 @@ export const TOOLS = [
         id: "gitleaks",
         name: "gitleaks",
         checkCommand: "gitleaks",
-        checkArgs: ["version"],
+        // intended: version — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "github",
         binaryName: "gitleaks",
         github: {
@@ -1144,7 +1179,8 @@ export const TOOLS = [
         id: "terraform-ls",
         name: "terraform-ls",
         checkCommand: "terraform-ls",
-        checkArgs: ["version"],
+        // intended: version — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "github",
         binaryName: "terraform-ls",
         github: {
@@ -1216,6 +1252,7 @@ export const TOOLS = [
         id: "cue",
         name: "CUE",
         checkCommand: "cue",
+        // Probed locally with CUE v0.17.1: `cue version` exits 0.
         checkArgs: ["version"],
         installStrategy: "github",
         binaryName: "cue",
@@ -1324,6 +1361,10 @@ export const TOOLS = [
         },
     },
 ];
+/** Return the bounded managed-binary verification budget for a registered tool. */
+export function getToolVerificationTimeout(tool) {
+    return tool.verificationTimeoutMs ?? 10_000;
+}
 const ensureInFlight = new Map();
 const installFailureReasons = new Map();
 /** Last honest install refusal/failure reason for callers that need diagnostics. */
@@ -1621,8 +1662,13 @@ export async function checkProbeCache(toolId) {
     try {
         await fs.access(entry.path);
         const stat = await fs.stat(entry.path);
-        if (stat.mtimeMs !== entry.mtimeMs) {
-            logSessionStart(`auto-install probe-cache ${toolId}: miss (mtime changed)`);
+        // #2300: size alongside mtime, from the same stat — a binary replaced
+        // in-place within the same coarse-granularity mtime tick would otherwise
+        // pass this check unnoticed. `entry.sizeBytes` absent (pre-#2300 entry)
+        // fails open to the mtime-only check (see the field's doc comment).
+        if (stat.mtimeMs !== entry.mtimeMs ||
+            (entry.sizeBytes !== undefined && stat.size !== entry.sizeBytes)) {
+            logSessionStart(`auto-install probe-cache ${toolId}: miss (mtime/size changed)`);
             delete cache[toolId];
             markProbeCacheChange(toolId, null);
             return undefined;
@@ -1650,6 +1696,7 @@ export async function updateProbeCache(toolId, resolvedPath, transient = false)
         const entry = {
             path: resolvedPath,
             mtimeMs: stat.mtimeMs,
+            sizeBytes: stat.size,
             cachedAt: Date.now(),
             ...(transient && { transient: true }),
         };
@@ -1681,6 +1728,14 @@ export function resetProbeCacheStateForTesting() {
         _probeCacheFlushTimer = null;
     }
 }
+/**
+ * Exported for testing only. Read the `ensureTool` in-flight map directly
+ * (#1968's ABA regression: a second writer replacing an entry mid-flight,
+ * then a late-settling first run evicting it with a bare delete-by-key).
+ */
+export function _peekEnsureInFlightForTesting() {
+    return ensureInFlight;
+}
 // --- Check Functions ---
 const pathWalkMemo = new Map();
 function hashSync(value) {
@@ -1765,6 +1820,7 @@ export async function isSpawnableCommand(command) {
 export function isLspTransportRequiredError(output) {
     return /Connection (?:input|output) stream is not set|Use arguments of createConnection/i.test(output);
 }
+const lspTransportRequiredMatcher = /Connection (?:input|output) stream is not set|Use arguments of createConnection/i;
 /**
  * Parse the exact version pinned in a TOOLS `packageName` spec, e.g.
  * `"jscpd@3.5.10"` -> `"3.5.10"`. Scoped packages (`"@ast-grep/cli"`) have no
@@ -1773,7 +1829,7 @@ export function isLspTransportRequiredError(output) {
  * correctly reports "no pin" rather than mistaking the scope for a version.
  * Returns undefined when packageName has no explicit `@version` suffix.
  */
-function parsePinnedVersion(packageName) {
+export function parsePinnedVersion(packageName) {
     const at = packageName.lastIndexOf("@");
     if (at <= 0)
         return undefined;
@@ -1796,7 +1852,7 @@ function extractVersionToken(output) {
  */
 const lastManagedInstallVersion = new Map();
 /**
- * Verify a tool binary actually works by running --version
+ * Verify a tool binary actually works by running its configured checkArgs.
  * This catches broken symlinks, partial installs, and corrupted binaries.
  * `onVersionOutput`, when provided, receives the raw stdout on a successful
  * (exit 0) probe — used to piggyback version-pin drift detection onto this
@@ -1822,7 +1878,7 @@ onTransient,
  * sensitive caller on the dispatch hot path passes a shorter one and treats
  * the expiry as transient rather than as a verdict (#1657).
  */
-timeoutMs = 10000) {
+timeoutMs = 10000, verificationArgs = ["--version"]) {
     // #2015: safeSpawnAsync instead of raw spawn. Raw spawn's timeout
     // SIGTERMed only cmd.exe on Windows (.cmd shims run shell:true), orphaning
     // the grandchild node process - which kept scanning, held handles against
@@ -1849,16 +1905,29 @@ timeoutMs = 10000) {
     // there), so no shell option exists or is needed here.
     void useShell;
     try {
-        const result = await safeSpawnAsync(execPath, ["--version"], {
+        const result = await safeSpawnAsync(execPath, verificationArgs, {
             timeout: timeoutMs,
+            input: "",
+            // A broken or version-blind language server can emit a bundled
+            // megabytes-long diagnostic on stderr. Keep verification bounded even
+            // when the child reaches its normal timeout first.
+            maxOutputBytes: 64 * 1024,
+            matchWhileStreaming: lspTransportRequiredMatcher,
         });
         const output = `${result.stdout}\n${result.stderr}`;
+        if (result.outputTruncated) {
+            recordDegradationOnce({
+                kind: "installer-verification-output-truncated",
+                subject: binPath,
+                reason: `verification output exceeded 65536 bytes (${verificationArgs.join(" ")})`,
+            });
+        }
         if (result.status === 0 && !result.error) {
-            debugLog(`Verified: ${binPath} (version: ${result.stdout.trim()})`);
+            debugLog(`Verified: ${binPath} (${verificationArgs.join(" ")}: ${result.stdout.trim()})`);
             onVersionOutput?.(result.stdout);
             return true;
         }
-        if (isLspTransportRequiredError(output)) {
+        if (result.streamingMatch || isLspTransportRequiredError(output)) {
             // Valid stdio LSP server that rejects `--version` (#208) — the
             // transport-required error proves the binary works.
             debugLog(`Verified (stdio LSP, transport-required): ${binPath}`);
@@ -1868,7 +1937,13 @@ timeoutMs = 10000) {
         // verdict from the binary (#1569 transient semantics).
         if (result.signal !== undefined || result.spawnFailure)
             onTransient?.();
-        logSessionStart(`auto-install verify: failed for ${binPath} (kind=${result.signal ? `killed-signal=${result.signal}` : result.error ? "spawn-error" : "exit-nonzero"}${result.status !== null ? `, exit=${result.status}` : ""})`);
+        const kind = result.spawnFailure?.kind ??
+            (result.signal
+                ? `killed-signal=${result.signal}`
+                : result.error
+                    ? "spawn-error"
+                    : "exit-nonzero");
+        logSessionStart(`auto-install verify: failed for ${binPath} (check=${verificationArgs.join(" ")}, kind=${kind}${result.status !== null ? `, exit=${result.status}` : ""})`);
         return false;
     }
     catch (err) {
@@ -1938,7 +2013,7 @@ export async function getAllToolStatuses() {
         }
         // 2. Check npm global
         if (tool.installStrategy === "npm") {
-            const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id);
+            const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, undefined, tool.checkArgs, getToolVerificationTimeout(tool));
             if (npmPath) {
                 status.installed = true;
                 status.source = "npm-global";
@@ -1949,7 +2024,7 @@ export async function getAllToolStatuses() {
         }
         // 3. Check pip user install
         if (tool.installStrategy === "pip") {
-            const pipPath = await findPipUserToolPath(tool.binaryName || tool.id);
+            const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, undefined, tool.checkArgs, getToolVerificationTimeout(tool));
             if (pipPath) {
                 status.installed = true;
                 status.source = "pip-user";
@@ -1981,7 +2056,7 @@ export async function getAllToolStatuses() {
         const localPath = installerPlatform() === "win32" ? `${localBase}.cmd` : localBase;
         try {
             await fs.access(localPath);
-            if (await verifyToolBinary(localPath)) {
+            if (await verifyToolBinary(localPath, undefined, undefined, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 status.installed = true;
                 status.source = "pi-lens-auto";
                 status.path = localPath;
@@ -2150,7 +2225,7 @@ async function getToolPathResolved(toolId, onTransient) {
         const cmdPath = `${localBase}.cmd`;
         try {
             await fs.access(cmdPath);
-            if (await verifyToolBinary(cmdPath, recordVersion, onTransient)) {
+            if (await verifyToolBinary(cmdPath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 return cmdPath;
             }
             logSessionStart(`auto-install verify: ${cmdPath} exists but is broken, will reinstall`);
@@ -2163,7 +2238,7 @@ async function getToolPathResolved(toolId, onTransient) {
         const exePath = `${localBase}.exe`;
         try {
             await fs.access(exePath);
-            if (await verifyToolBinary(exePath, recordVersion, onTransient)) {
+            if (await verifyToolBinary(exePath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 return exePath;
             }
             logSessionStart(`auto-install verify: ${exePath} exists but is broken, will reinstall`);
@@ -2175,7 +2250,7 @@ async function getToolPathResolved(toolId, onTransient) {
     if (installerPlatform() !== "win32") {
         try {
             await fs.access(localBase);
-            if (await verifyToolBinary(localBase, recordVersion, onTransient)) {
+            if (await verifyToolBinary(localBase, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 return localBase;
             }
             logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
@@ -2191,7 +2266,7 @@ async function getToolPathResolved(toolId, onTransient) {
     if (tool.platformPackage) {
         const platformBin = resolvePlatformPackageBinary(tool);
         if (platformBin &&
-            (await verifyToolBinary(platformBin, undefined, onTransient))) {
+            (await verifyToolBinary(platformBin, undefined, onTransient, getToolVerificationTimeout(tool), tool.checkArgs))) {
             logSessionStart(`auto-install ${toolId}: resolved platform-package binary at ${platformBin}`);
             return platformBin;
         }
@@ -2213,14 +2288,14 @@ async function getToolPathResolved(toolId, onTransient) {
         return tool.checkCommand;
     }
     if (tool.installStrategy === "npm") {
-        const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, onTransient);
+        const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, onTransient, tool.checkArgs, getToolVerificationTimeout(tool));
         if (npmPath) {
             return npmPath;
         }
     }
     // For pip tools, also probe user-level script locations
     if (tool.installStrategy === "pip") {
-        const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, onTransient);
+        const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, onTransient, tool.checkArgs, getToolVerificationTimeout(tool));
         if (pipPath) {
             return pipPath;
         }
@@ -2248,6 +2323,18 @@ async function findGitHubToolPath(binaryName) {
     }
     return undefined;
 }
+/** Resolve a release-managed binary without probing PATH first. */
+export async function findManagedToolBinary(toolId) {
+    const tool = TOOLS.find((candidate) => candidate.id === toolId);
+    if (!tool)
+        return undefined;
+    if (tool.installStrategy !== "github" &&
+        tool.installStrategy !== "maven" &&
+        tool.installStrategy !== "archive") {
+        return undefined;
+    }
+    return findGitHubToolPath(tool.binaryName || tool.id);
+}
 function hasExecutableExtension(name) {
     return /\.(exe|bat|cmd|ps1)$/i.test(name);
 }
@@ -2278,7 +2365,7 @@ function getArchiveBinaryCandidates(binaryName, platform, assetName) {
     candidates.add(`${binaryName}.cmd`);
     return [...candidates];
 }
-async function findNpmGlobalToolPath(binaryName, onTransient) {
+async function findNpmGlobalToolPath(binaryName, onTransient, verificationArgs = ["--version"], verificationTimeoutMs = 10_000) {
     const isWindows = process.platform === "win32";
     const binDirs = await getNpmGlobalBinCandidates(onTransient);
     for (const dir of binDirs) {
@@ -2291,7 +2378,7 @@ async function findNpmGlobalToolPath(binaryName, onTransient) {
         for (const candidate of candidates) {
             try {
                 await fs.access(candidate);
-                if (await verifyToolBinary(candidate, undefined, onTransient)) {
+                if (await verifyToolBinary(candidate, undefined, onTransient, verificationTimeoutMs, verificationArgs)) {
                     return candidate;
                 }
             }
@@ -2332,7 +2419,7 @@ async function getNpmGlobalBinCandidates(onTransient) {
     }
     return dirs;
 }
-async function findPipUserToolPath(binaryName, onTransient) {
+async function findPipUserToolPath(binaryName, onTransient, verificationArgs = ["--version"], verificationTimeoutMs = 10_000) {
     const isWindows = process.platform === "win32";
     const userBaseCandidates = await getPythonUserBaseCandidates();
     for (const userBase of userBaseCandidates) {
@@ -2365,7 +2452,7 @@ async function findPipUserToolPath(binaryName, onTransient) {
             for (const candidate of candidates) {
                 try {
                     await fs.access(candidate);
-                    if (await verifyToolBinary(candidate, undefined, onTransient)) {
+                    if (await verifyToolBinary(candidate, undefined, onTransient, verificationTimeoutMs, verificationArgs)) {
                         return candidate;
                     }
                 }
@@ -2837,8 +2924,10 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: "npm",
+                    checkArgs: tool.checkArgs,
                     packageName: tool.packageName,
                     binaryName: tool.binaryName,
+                    verificationTimeoutMs: tool.verificationTimeoutMs,
                 });
                 break;
             }
@@ -2849,6 +2938,7 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: tool.installStrategy,
+                    checkArgs: tool.checkArgs,
                     packageName: tool.packageName,
                 });
                 break;
@@ -2856,7 +2946,11 @@ export function getRefreshableManagedTools() {
             case "github": {
                 if (!tool.github)
                     continue;
-                refreshable.push({ toolId: tool.id, strategy: "github" });
+                refreshable.push({
+                    toolId: tool.id,
+                    strategy: "github",
+                    checkArgs: tool.checkArgs,
+                });
                 break;
             }
             case "maven": {
@@ -2865,6 +2959,7 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: "maven",
+                    checkArgs: tool.checkArgs,
                     pinnedCoordinate: mavenCoordinate(tool.maven),
                 });
                 break;
@@ -2880,6 +2975,7 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: "archive",
+                    checkArgs: tool.checkArgs,
                     pinnedCoordinate: url,
                 });
                 break;
@@ -2951,7 +3047,8 @@ async function probeManagedToolVersion(tool) {
         return undefined;
     try {
         const result = await safeSpawnAsync(cached.path, tool.checkArgs, {
-            timeout: 10_000,
+            timeout: getToolVerificationTimeout(tool),
+            input: "",
             ignoreAmbientSignal: true,
             resourceLabel: `tool-refresh-version:${tool.id}`,
         });
@@ -3187,8 +3284,8 @@ async function verifyRefreshedArtifact(tool, installedPath) {
         await updateProbeCache(tool.id, installedPath);
         return true;
     }
-    if (!(await verifyToolBinary(installedPath))) {
-        logSessionStart(`managed-tool-refresh ${tool.id}: refreshed artifact at ${installedPath} failed its --version check`);
+    if (!(await verifyToolBinary(installedPath, undefined, undefined, getToolVerificationTimeout(tool), tool.checkArgs))) {
+        logSessionStart(`managed-tool-refresh ${tool.id}: refreshed artifact at ${installedPath} failed its verification check`);
         return false;
     }
     // Record the NEW mtime rather than leaving the persisted entry to miss its
@@ -3212,10 +3309,10 @@ async function refreshPackageManagerManagedTool(tool) {
     const installed = tool.installStrategy === "pip"
         ? // `-U` is the whole fix: without it pip treats the installed copy as
             // satisfying the requirement and the day-one version never moves.
-            await installPipTool(tool.packageName, { upgrade: true })
+            await installPipTool(tool.id, tool.packageName, { upgrade: true })
         : // `gem install` always fetches the newest version that satisfies the
             // requirement, so the install command IS the upgrade command.
-            await installGemTool(tool.packageName);
+            await installGemTool(tool.id, tool.packageName);
     if (!installed) {
         return {
             ok: false,
@@ -3643,7 +3740,24 @@ async function installArchiveTool(tool) {
         return undefined;
     }
 }
-async function installNpmTool(packageName, binaryName) {
+/**
+ * Record a genuine package-manager install exception against `toolId` and
+ * log it — the one place `installNpmTool`/`installPipTool`/`installGemTool`'s
+ * catch blocks funnel through (#2661 review F3/Sonar: the three catches were
+ * byte-identical but for the strategy label, a duplication SonarCloud's new-
+ * code gate correctly flagged). The real error (registry E404, EBADENGINE, a
+ * network failure, "no version satisfies…") lands in `installFailureReasons`
+ * so a caller that distinguishes a genuine installer defect from a policy
+ * decline (the tool-smoke lane, #2638) sees the actual message, never the
+ * generic fallback `finishInstallAttempt` uses when nothing set it.
+ */
+function recordPackageManagerInstallException(toolId, strategyLabel, packageName, err) {
+    const message = err.message;
+    logSessionStart(`auto-install ${strategyLabel} ${packageName}: exception: ${message}`);
+    installFailureReasons.set(toolId, message);
+    return undefined;
+}
+async function installNpmTool(toolId, packageName, binaryName, verificationArgs = ["--version"], verificationTimeoutMs = 10_000) {
     try {
         // Ensure tools directory exists
         await fs.mkdir(TOOLS_DIR, { recursive: true });
@@ -3727,7 +3841,7 @@ async function installNpmTool(packageName, binaryName) {
             lastAttemptTransient = false;
             isValid = await verifyToolBinary(binPath, undefined, () => {
                 lastAttemptTransient = true;
-            });
+            }, verificationTimeoutMs, verificationArgs);
             if (isValid)
                 break;
             if (attempt < 3) {
@@ -3767,14 +3881,26 @@ async function installNpmTool(packageName, binaryName) {
         return binPath;
     }
     catch (err) {
-        logSessionStart(`auto-install npm ${packageName}: exception: ${err.message}`);
-        return undefined;
+        return recordPackageManagerInstallException(toolId, "npm", packageName, err);
     }
 }
+/**
+ * The pip command ladder `installPipTool` tries, per platform, in priority
+ * order — exported so a caller that needs to know "is ANY pip toolchain
+ * reachable on this runner" (without running an install) probes the SAME
+ * candidates rather than a second, narrower guess (#2661 review F4/S5: the
+ * tool-smoke lane's own presence check tried bare `pip` only and missed a
+ * `pip3`-only or python-module-only runner).
+ */
+export function pipCommandCandidates() {
+    return process.platform === "win32"
+        ? ["pip", "py", "python"]
+        : ["pip3", "pip", "python3", "python"];
+}
 /**
  * Install a pip package tool
  */
-async function installPipTool(packageName, 
+async function installPipTool(toolId, packageName, 
 /**
  * Add `-U`, turning the install into an upgrade. Without it `pip install`
  * treats an already-present package as satisfied and leaves the day-one
@@ -3789,30 +3915,16 @@ options = {}) {
         const verb = options.upgrade
             ? ["install", "-U", "--user"]
             : ["install", "--user"];
-        const pipCandidates = isWindows
-            ? [
-                { command: "pip", args: [...verb, packageName] },
-                {
-                    command: "py",
-                    args: ["-m", "pip", ...verb, packageName],
-                },
-                {
-                    command: "python",
-                    args: ["-m", "pip", ...verb, packageName],
-                },
-            ]
-            : [
-                { command: "pip3", args: [...verb, packageName] },
-                { command: "pip", args: [...verb, packageName] },
-                {
-                    command: "python3",
-                    args: ["-m", "pip", ...verb, packageName],
-                },
-                {
-                    command: "python",
-                    args: ["-m", "pip", ...verb, packageName],
-                },
-            ];
+        // Built from `pipCommandCandidates()` — the single source of truth this
+        // module and any other caller (the tool-smoke lane's toolchain-presence
+        // probe, #2661 review) share, rather than a second, independently
+        // maintained ladder that can drift.
+        const pipCandidates = pipCommandCandidates().map((command) => ({
+            command,
+            args: command === "pip" || command === "pip3"
+                ? [...verb, packageName]
+                : ["-m", "pip", ...verb, packageName],
+        }));
         let lastError = "";
         for (const candidate of pipCandidates) {
             const pipResult = await safeSpawnAsync(candidate.command, candidate.args, {
@@ -3909,11 +4021,10 @@ options = {}) {
         throw new Error(`Failed to install ${packageName}: no usable pip command found (${lastError || "unknown error"})`);
     }
     catch (err) {
-        logSessionStart(`auto-install pip ${packageName}: exception: ${err.message}`);
-        return undefined;
+        return recordPackageManagerInstallException(toolId, "pip", packageName, err);
     }
 }
-async function installGemTool(packageName) {
+async function installGemTool(toolId, packageName) {
     try {
         const gemResult = await safeSpawnAsync("gem", ["install", packageName, "--no-document"], {
             timeout: 120_000,
@@ -3930,8 +4041,7 @@ async function installGemTool(packageName) {
         return packageName;
     }
     catch (err) {
-        logSessionStart(`auto-install gem ${packageName}: exception: ${err.message}`);
-        return undefined;
+        return recordPackageManagerInstallException(toolId, "gem", packageName, err);
     }
 }
 /**
@@ -4022,7 +4132,7 @@ export async function installTool(toolId) {
             case "npm": {
                 if (!tool.packageName || !tool.binaryName)
                     return false;
-                const npmPath = await installNpmTool(tool.packageName, tool.binaryName);
+                const npmPath = await installNpmTool(tool.id, tool.packageName, tool.binaryName, tool.checkArgs, getToolVerificationTimeout(tool));
                 if (npmPath !== undefined) {
                     // #1746 review F4: an install just resolved this package's range
                     // against the registry, so record it as freshly checked. Otherwise a
@@ -4048,13 +4158,13 @@ export async function installTool(toolId) {
             case "pip": {
                 if (!tool.packageName)
                     return false;
-                const pipPath = await installPipTool(tool.packageName);
+                const pipPath = await installPipTool(tool.id, tool.packageName);
                 return finishInstallAttempt(tool.id, pipPath !== undefined, startedAt);
             }
             case "gem": {
                 if (!tool.packageName)
                     return false;
-                const gemPath = await installGemTool(tool.packageName);
+                const gemPath = await installGemTool(tool.id, tool.packageName);
                 return finishInstallAttempt(tool.id, gemPath !== undefined, startedAt);
             }
             case "github": {
@@ -4316,7 +4426,13 @@ async function ensureToolResolved(toolId, opts) {
         return await ensurePromise;
     }
     finally {
-        ensureInFlight.delete(inFlightKey);
+        // Identity-guarded release (#1968's pattern): delete only if THIS run is
+        // still the registered one. A bare delete-by-key lets a late-settling run
+        // evict a live successor a second writer registered under the same key
+        // mid-flight, after which the next caller starts a duplicate ensure/install.
+        if (ensureInFlight.get(inFlightKey) === ensurePromise) {
+            ensureInFlight.delete(inFlightKey);
+        }
     }
 }
 // --- Integration Helpers ---