pi-lens 3.8.72 → 3.8.74

package/dist/clients/installer/index.js

@@ -46,7 +46,7 @@
  * - GitHub releases (platform-specific binaries → ~/.pi-lens/bin/)
  */
 import { spawn } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, statSync, unlinkSync } from "node:fs";
 import fs from "node:fs/promises";
 import https from "node:https";
 import { createRequire } from "node:module";
@@ -54,17 +54,116 @@ import os from "node:os";
 import path from "node:path";
 const _installerRequire = createRequire(import.meta.url);
 import { createGunzip } from "node:zlib";
-import { isTestMode } from "../env-utils.js";
+import { logSessionStart } from "../sessionstart-logger.js";
 import { getGlobalPiLensDir } from "../file-utils.js";
 import { allAvailableGlobalBinDirs, installArgs, pmBinary, resolveNodePackageManager, } from "../package-manager.js";
+import { safeSpawnAsync } from "../safe-spawn.js";
 // Global installation directory for pi-lens tools
 const TOOLS_DIR = path.join(getGlobalPiLensDir(), "tools");
+const INSTALL_LOCK_PATH = path.join(TOOLS_DIR, ".install.lock");
+const activeInstallLocks = new Set();
+let installLockExitCleanupRegistered = false;
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function acquireInstallLock() {
+    await fs.mkdir(TOOLS_DIR, { recursive: true });
+    // #946 review F2: the waiter's bound must exceed the owner's install bound
+    // (PI_LENS_INSTALL_TIMEOUT_MS, default 120s) — a 30s waiter gave up on a
+    // legitimate slow install and reported the tool unavailable for the whole
+    // session even though it arrived seconds later.
+    const timeoutMs = Number(process.env.PI_LENS_INSTALL_LOCK_TIMEOUT_MS) || 150_000;
+    const deadline = Date.now() + timeoutMs;
+    let lastOwner = "unknown owner";
+    while (Date.now() < deadline) {
+        try {
+            const handle = await fs.open(INSTALL_LOCK_PATH, "wx");
+            await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: Date.now() }));
+            await handle.close();
+            activeInstallLocks.add(INSTALL_LOCK_PATH);
+            if (!installLockExitCleanupRegistered) {
+                installLockExitCleanupRegistered = true;
+                process.once("exit", () => {
+                    for (const lockPath of activeInstallLocks) {
+                        try {
+                            unlinkSync(lockPath);
+                        }
+                        catch {
+                            // Best effort; the next owner verifies this PID is dead.
+                        }
+                    }
+                });
+            }
+            let released = false;
+            return {
+                release: async () => {
+                    if (released)
+                        return;
+                    released = true;
+                    activeInstallLocks.delete(INSTALL_LOCK_PATH);
+                    await fs.rm(INSTALL_LOCK_PATH, { force: true });
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                const owner = JSON.parse(await fs.readFile(INSTALL_LOCK_PATH, "utf8"));
+                lastOwner = `pid=${owner.pid} createdAt=${owner.createdAt}`;
+                // #946 review F1: PID liveness alone cannot detect a hard-killed
+                // owner whose PID Windows has recycled — that lock would poison
+                // every future install with a full-timeout wait. A lock older
+                // than any legitimate install (owner install bound + slack) is
+                // stale regardless of what the PID now points at.
+                const maxAgeMs = (Number(process.env.PI_LENS_INSTALL_TIMEOUT_MS) || 120_000) +
+                    60_000;
+                const expired = Number.isFinite(owner.createdAt) &&
+                    Date.now() - owner.createdAt > maxAgeMs;
+                if (expired ||
+                    (Number.isInteger(owner.pid) &&
+                        owner.pid > 0 &&
+                        !isProcessAlive(owner.pid))) {
+                    await fs.rm(INSTALL_LOCK_PATH, { force: true });
+                    continue;
+                }
+            }
+            catch (readError) {
+                lastOwner = "unreadable owner";
+                // An unreadable/empty lock has no createdAt to age out — fall
+                // back to the file's own mtime for the max-age check so it is
+                // eventually recoverable (#946 review F1/F6).
+                try {
+                    const stat = await fs.stat(INSTALL_LOCK_PATH);
+                    const maxAgeMs = (Number(process.env.PI_LENS_INSTALL_TIMEOUT_MS) || 120_000) +
+                        60_000;
+                    if (Date.now() - stat.mtimeMs > maxAgeMs) {
+                        await fs.rm(INSTALL_LOCK_PATH, { force: true });
+                        continue;
+                    }
+                }
+                catch {
+                    // stat raced a release — loop and retry acquisition.
+                }
+                void readError;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    return {
+        reason: `timed out after ${timeoutMs}ms waiting for shared tools install lock (${lastOwner})`,
+    };
+}
 // Directory for GitHub-downloaded binaries
 const GITHUB_BIN_DIR = path.join(getGlobalPiLensDir(), "bin");
 // Debug flag - set via PI_LENS_DEBUG=1 or --debug
 const DEBUG = process.env.PI_LENS_DEBUG === "1" || process.argv.includes("--debug");
-const SESSIONSTART_LOG_DIR = getGlobalPiLensDir();
-const SESSIONSTART_LOG = path.join(SESSIONSTART_LOG_DIR, "sessionstart.log");
 /**
  * Log debug messages only when DEBUG is enabled
  */
@@ -73,18 +172,6 @@ function debugLog(...args) {
         console.error("[auto-install:debug]", ...args);
     }
 }
-function logSessionStart(msg) {
-    if (isTestMode()) {
-        return;
-    }
-    const line = `[${new Date().toISOString()}] ${msg}\n`;
-    void fs
-        .mkdir(SESSIONSTART_LOG_DIR, { recursive: true })
-        .then(() => fs.appendFile(SESSIONSTART_LOG, line))
-        .catch(() => {
-        // best-effort logging
-    });
-}
 /**
  * Build a GitHub-release `assetMatch` from a small per-platform table, replacing
  * the copy-pasted `if (platform === "linux") return arch === "arm64" ? … : …`
@@ -257,6 +344,24 @@ export const TOOLS = [
         packageName: "bash-language-server",
         binaryName: "bash-language-server",
     },
+    {
+        id: "fish-lsp",
+        name: "Fish Language Server",
+        checkCommand: "fish-lsp",
+        checkArgs: ["--version"],
+        installStrategy: "npm",
+        packageName: "fish-lsp",
+        binaryName: "fish-lsp",
+    },
+    {
+        id: "cmake-language-server",
+        name: "CMake Language Server",
+        checkCommand: "cmake-language-server",
+        checkArgs: ["--version"],
+        installStrategy: "pip",
+        packageName: "cmake-language-server",
+        binaryName: "cmake-language-server",
+    },
     {
         id: "yaml-language-server",
         name: "YAML Language Server",
@@ -1110,6 +1215,11 @@ export const TOOLS = [
     },
 ];
 const ensureInFlight = new Map();
+const installFailureReasons = new Map();
+/** Last honest install refusal/failure reason for callers that need diagnostics. */
+export function getInstallFailureReason(toolId) {
+    return installFailureReasons.get(toolId);
+}
 // Session-lifetime cache: once a tool path is resolved, skip the process-spawn check on subsequent calls.
 const resolvedPathCache = new Map();
 const PROBE_CACHE_PATH = path.join(getGlobalPiLensDir(), "probe-cache.json");
@@ -1133,26 +1243,61 @@ function scheduleProbeFlush() {
     if (_probeCacheFlushTimer !== null)
         return;
     _probeCacheFlushTimer = setTimeout(() => {
-        _probeCacheFlushTimer = null;
-        if (!_probeCacheDirty || _probeCache === null)
-            return;
-        _probeCacheDirty = false;
-        void fs
-            .writeFile(PROBE_CACHE_PATH, JSON.stringify(_probeCache, null, 2))
-            .catch(() => { });
+        void flushProbeCache();
     }, 300);
     _probeCacheFlushTimer.unref?.();
 }
+let _probeCacheWriteInFlight = null;
+/** Await pending probe-cache persistence before a one-shot process exits. */
+export async function flushProbeCache() {
+    if (_probeCacheFlushTimer !== null) {
+        clearTimeout(_probeCacheFlushTimer);
+        _probeCacheFlushTimer = null;
+    }
+    // #946 review F4: if the 300ms timer's write already started, the dirty
+    // flag is false but the write may still be in flight — an immediate
+    // process.exit would truncate it. Always await the in-flight write.
+    if (!_probeCacheDirty || _probeCache === null) {
+        await _probeCacheWriteInFlight;
+        return;
+    }
+    _probeCacheDirty = false;
+    const write = (async () => {
+        try {
+            await fs.writeFile(PROBE_CACHE_PATH, JSON.stringify(_probeCache, null, 2));
+        }
+        catch {
+            // Cache persistence is best effort; discovery remains authoritative.
+        }
+    })();
+    _probeCacheWriteInFlight = write;
+    try {
+        await write;
+    }
+    finally {
+        if (_probeCacheWriteInFlight === write)
+            _probeCacheWriteInFlight = null;
+    }
+}
 function isAstGrepVersionOutput(output) {
     return /\bast[- ]grep\b/i.test(output);
 }
 async function verifyAstGrepProbePath(binPath) {
     return new Promise((resolve) => {
-        const proc = spawn(binPath, ["--version"], {
-            stdio: ["ignore", "pipe", "pipe"],
-            shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(binPath),
-            timeout: 5000,
-        });
+        let proc;
+        try {
+            proc = spawn(binPath, ["--version"], {
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(binPath),
+                timeout: 5000,
+            });
+        }
+        catch {
+            // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
+            // bug class, #533) — best-effort probe, resolve rather than reject.
+            resolve(false);
+            return;
+        }
         let output = "";
         proc.stdout?.on("data", (data) => (output += data));
         proc.stderr?.on("data", (data) => (output += data));
@@ -1225,6 +1370,7 @@ export function resetProbeCacheStateForTesting() {
     _probeCacheDirty = false;
     resolvedPathCache.clear();
     ensureInFlight.clear();
+    installFailureReasons.clear();
     lastManagedInstallVersion.clear();
     if (_probeCacheFlushTimer !== null) {
         clearTimeout(_probeCacheFlushTimer);
@@ -1238,7 +1384,7 @@ export function resetProbeCacheStateForTesting() {
  * Catches broken symlinks (stat throws ENOENT or returns size 0) without
  * spawning a process — ~μs per candidate vs ~50ms for which/where.
  */
-async function isCommandAvailable(command, _args) {
+export async function isCommandAvailable(command, _args) {
     const isWindows = process.platform === "win32";
     const pathEnv = process.env.PATH || process.env.Path || process.env.path || "";
     const dirs = pathEnv.split(path.delimiter);
@@ -1266,6 +1412,23 @@ async function isCommandAvailable(command, _args) {
     }
     return false;
 }
+/**
+ * Can `command` even be spawned? Path-bearing commands stat the file directly;
+ * bare names walk PATH. ~μs either way — callers use this to skip a `--version`
+ * probe that is guaranteed to fail with a full spawn round-trip.
+ */
+export async function isSpawnableCommand(command) {
+    if (/[\\/]/.test(command)) {
+        try {
+            const stat = statSync(command);
+            return stat.isFile() && stat.size > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    return isCommandAvailable(command);
+}
 // --- Verification Functions
 /**
  * Stdio LSP servers built on `vscode-languageserver-node` (the entire
@@ -1341,11 +1504,21 @@ async function verifyToolBinary(binPath, onVersionOutput) {
         }
         // When shell:true (Windows .cmd), bake args into the command string to avoid DEP0190.
         const spawnCmd = useShell ? `"${execPath}" --version` : execPath;
-        const proc = spawn(spawnCmd, useShell ? [] : ["--version"], {
-            timeout: 10000,
-            stdio: ["ignore", "pipe", "pipe"],
-            shell: useShell,
-        });
+        let proc;
+        try {
+            proc = spawn(spawnCmd, useShell ? [] : ["--version"], {
+                timeout: 10000,
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: useShell,
+            });
+        }
+        catch (err) {
+            // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
+            // bug class, #533) — best-effort verify, resolve rather than reject.
+            logSessionStart(`auto-install verify: spawn threw for ${binPath} (${err instanceof Error ? err.message : String(err)})`);
+            resolve(false);
+            return;
+        }
         let stdout = "";
         let stderr = "";
         proc.stdout?.on("data", (data) => (stdout += data));
@@ -1405,11 +1578,20 @@ export async function getAllToolStatuses() {
             status.path = tool.checkCommand;
             // Try to get version
             const versionResult = await new Promise((resolve) => {
-                const proc = spawn(tool.checkCommand, ["--version"], {
-                    stdio: ["ignore", "pipe", "pipe"],
-                    shell: process.platform === "win32",
-                    timeout: 5000,
-                });
+                let proc;
+                try {
+                    proc = spawn(tool.checkCommand, ["--version"], {
+                        stdio: ["ignore", "pipe", "pipe"],
+                        shell: process.platform === "win32",
+                        timeout: 5000,
+                    });
+                }
+                catch {
+                    // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the
+                    // pidusage bug class, #533) — best-effort, resolve empty version.
+                    resolve("");
+                    return;
+                }
                 let out = "";
                 proc.stdout?.on("data", (d) => (out += d));
                 proc.stderr?.on("data", (d) => (out += d));
@@ -1849,10 +2031,19 @@ async function getPythonUserBaseCandidates() {
             const spawnCmd = isWin
                 ? [probe.command, ...probe.args].join(" ")
                 : probe.command;
-            const proc = spawn(spawnCmd, isWin ? [] : probe.args, {
-                stdio: ["ignore", "pipe", "pipe"],
-                shell: isWin,
-            });
+            let proc;
+            try {
+                proc = spawn(spawnCmd, isWin ? [] : probe.args, {
+                    stdio: ["ignore", "pipe", "pipe"],
+                    shell: isWin,
+                });
+            }
+            catch {
+                // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the
+                // pidusage bug class, #533) — best-effort probe, resolve empty.
+                resolve("");
+                return;
+            }
             let stdout = "";
             proc.stdout?.on("data", (data) => (stdout += data));
             proc.on("exit", (code) => resolve(code === 0 ? stdout.trim() : ""));
@@ -1925,11 +2116,20 @@ function httpsGet(url, maxRedirects = 5, headers = {}) {
  */
 function runCommand(command, args, cwd) {
     return new Promise((resolve) => {
-        const proc = spawn(command, args, {
-            cwd,
-            stdio: "ignore",
-            shell: process.platform === "win32",
-        });
+        let proc;
+        try {
+            proc = spawn(command, args, {
+                cwd,
+                stdio: "ignore",
+                shell: process.platform === "win32",
+            });
+        }
+        catch {
+            // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
+            // bug class, #533) — resolve false rather than reject/crash.
+            resolve(false);
+            return;
+        }
         proc.on("exit", (code) => resolve(code === 0));
         proc.on("error", () => resolve(false));
     });
@@ -2257,23 +2457,16 @@ async function installArchiveTool(tool) {
         const tarBin = isWindows
             ? `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\tar.exe`
             : "tar";
-        const extracted = await new Promise((resolve) => {
-            const proc = spawn(tarBin, tarArgs, {
-                cwd: TOOLS_DIR,
-                stdio: ["ignore", "ignore", "pipe"],
-            });
-            let stderr = "";
-            proc.stderr?.on("data", (d) => (stderr += d));
-            const timer = setTimeout(() => {
-                proc.kill();
-                resolve({ ok: false, stderr: "extraction timed out" });
-            }, 120_000);
-            proc.on("exit", (code) => {
-                clearTimeout(timer);
-                resolve({ ok: code === 0, stderr });
-            });
-            proc.on("error", (err) => resolve({ ok: false, stderr: err.message }));
+        const extractResult = await safeSpawnAsync(tarBin, tarArgs, {
+            cwd: TOOLS_DIR,
+            timeout: 120_000,
+            ignoreAmbientSignal: true,
+            lifetimeCoupled: true,
         });
+        const extracted = {
+            ok: extractResult.status === 0,
+            stderr: extractResult.error?.message ?? extractResult.stderr,
+        };
         await fs.rm(tmpArchive, { force: true });
         if (!extracted.ok) {
             logSessionStart(`archive-install ${tool.id}: extraction failed: ${extracted.stderr}`);
@@ -2346,39 +2539,33 @@ async function installNpmTool(packageName, binaryName) {
         // Resolve the package manager for the tools dir and build install args.
         const isWindows = process.platform === "win32";
         const pm = await resolveNodePackageManager(TOOLS_DIR);
-        const pmCommand = pmBinary(pm);
+        const testNpmScript = process.env.PI_LENS_TEST_MODE === "1"
+            ? process.env.PI_LENS_TEST_NPM_SCRIPT
+            : undefined;
+        const pmCommand = testNpmScript ? process.execPath : pmBinary(pm);
         // Use --ignore-scripts unless the package explicitly needs postinstall
         // (e.g. biome downloads a platform-specific native binary via postinstall).
         const needsScripts = NEEDS_POSTINSTALL.has(packageName);
         const baseInstallArgs = installArgs(pm, packageName, {
             ignoreScripts: !needsScripts,
         });
-        const INSTALL_TIMEOUT_MS = 120_000;
-        const runInstallAttempt = async (args) => new Promise((resolve) => {
-            const proc = spawn(pmCommand, args, {
+        const INSTALL_TIMEOUT_MS = Number(process.env.PI_LENS_INSTALL_TIMEOUT_MS) || 120_000;
+        const runInstallAttempt = async (args) => {
+            const result = await safeSpawnAsync(pmCommand, args, {
                 cwd: TOOLS_DIR,
-                stdio: ["ignore", "pipe", "pipe"],
-                shell: isWindows, // Required for .cmd files on Windows
+                timeout: INSTALL_TIMEOUT_MS,
+                ignoreAmbientSignal: true,
+                lifetimeCoupled: true,
             });
-            let stderr = "";
-            proc.stderr?.on("data", (data) => (stderr += data));
-            const timer = setTimeout(() => {
-                proc.kill();
-                resolve({
-                    ok: false,
-                    stderr: `install timed out after ${INSTALL_TIMEOUT_MS / 1000}s`,
-                });
-            }, INSTALL_TIMEOUT_MS);
-            proc.on("exit", (code) => {
-                clearTimeout(timer);
-                resolve({ ok: code === 0, stderr });
-            });
-            proc.on("error", (err) => {
-                clearTimeout(timer);
-                resolve({ ok: false, stderr: err.message });
-            });
-        });
-        let outcome = await runInstallAttempt(baseInstallArgs);
+            return {
+                ok: result.status === 0,
+                stderr: result.error?.message ?? result.stderr,
+            };
+        };
+        let outcome = await runInstallAttempt([
+            ...(testNpmScript ? [testNpmScript] : []),
+            ...baseInstallArgs,
+        ]);
         // --legacy-peer-deps is npm-only; retry just npm's ERESOLVE failures.
         const erResolve = outcome.ok === false &&
             /npm\s+error\s+ERESOLVE|\bERESOLVE\b|could not resolve/i.test(outcome.stderr);
@@ -2388,7 +2575,10 @@ async function installNpmTool(packageName, binaryName) {
                 legacyPeerDeps: true,
             });
             logSessionStart(`auto-install npm ${packageName}: retry with --legacy-peer-deps after ERESOLVE`);
-            outcome = await runInstallAttempt(retryArgs);
+            outcome = await runInstallAttempt([
+                ...(testNpmScript ? [testNpmScript] : []),
+                ...retryArgs,
+            ]);
         }
         if (!outcome.ok) {
             throw new Error(`Failed to install ${packageName}: ${outcome.stderr}`);
@@ -2475,33 +2665,32 @@ async function installPipTool(packageName) {
             ];
         let lastError = "";
         for (const candidate of pipCandidates) {
-            const outcome = await new Promise((resolve) => {
-                const proc = spawn(candidate.command, candidate.args, {
-                    stdio: ["ignore", "pipe", "pipe"],
-                    shell: isWindows, // Required for .cmd files on Windows
-                });
-                let stderr = "";
-                proc.stderr?.on("data", (data) => (stderr += data));
-                proc.on("exit", (code) => {
-                    if (code === 0) {
-                        resolve({ ok: true, error: "" });
-                    }
-                    else {
-                        resolve({ ok: false, error: stderr.trim() });
-                    }
-                });
-                proc.on("error", (err) => {
-                    resolve({ ok: false, error: err.message });
-                });
+            const pipResult = await safeSpawnAsync(candidate.command, candidate.args, {
+                timeout: 120_000,
+                ignoreAmbientSignal: true,
+                lifetimeCoupled: true,
             });
+            const outcome = {
+                ok: pipResult.status === 0,
+                error: (pipResult.error?.message ?? pipResult.stderr).trim(),
+            };
             if (outcome.ok) {
                 // Ensure user-level scripts directory is available in current process PATH.
                 // This helps tools installed via `pip install --user` become immediately callable.
                 const userBaseResult = await new Promise((resolve) => {
-                    const probe = spawn(candidate.command, ["-m", "site", "--user-base"], {
-                        stdio: ["ignore", "pipe", "pipe"],
-                        shell: isWindows,
-                    });
+                    let probe;
+                    try {
+                        probe = spawn(candidate.command, ["-m", "site", "--user-base"], {
+                            stdio: ["ignore", "pipe", "pipe"],
+                            shell: isWindows,
+                        });
+                    }
+                    catch {
+                        // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the
+                        // pidusage bug class, #533) — best-effort probe, resolve empty.
+                        resolve("");
+                        return;
+                    }
                     let stdout = "";
                     probe.stdout?.on("data", (data) => (stdout += data));
                     probe.on("exit", (code) => {
@@ -2576,21 +2765,15 @@ async function installPipTool(packageName) {
 }
 async function installGemTool(packageName) {
     try {
-        const isWindows = process.platform === "win32";
-        const outcome = await new Promise((resolve) => {
-            const proc = spawn("gem", ["install", packageName, "--no-document"], {
-                stdio: ["ignore", "pipe", "pipe"],
-                shell: isWindows,
-            });
-            let stderr = "";
-            proc.stderr?.on("data", (data) => (stderr += data));
-            proc.on("exit", (code) => {
-                resolve({ ok: code === 0, error: stderr.trim() });
-            });
-            proc.on("error", (err) => {
-                resolve({ ok: false, error: err.message });
-            });
+        const gemResult = await safeSpawnAsync("gem", ["install", packageName, "--no-document"], {
+            timeout: 120_000,
+            ignoreAmbientSignal: true,
+            lifetimeCoupled: true,
         });
+        const outcome = {
+            ok: gemResult.status === 0,
+            error: (gemResult.error?.message ?? gemResult.stderr).trim(),
+        };
         if (!outcome.ok) {
             throw new Error(`Failed to install ${packageName} via gem: ${outcome.error}`);
         }
@@ -2605,6 +2788,11 @@ async function installGemTool(packageName) {
  * Install a tool by ID
  */
 export async function installTool(toolId) {
+    if (process.env.PI_LENS_DISABLE_TOOL_INSTALL === "1") {
+        installFailureReasons.set(toolId, "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
+        logSessionStart(`auto-install ${toolId}: refused — PI_LENS_DISABLE_TOOL_INSTALL=1`);
+        return false;
+    }
     const tool = TOOLS.find((t) => t.id === toolId);
     if (!tool) {
         logSessionStart(`auto-install ${toolId}: unknown tool id`);
@@ -2676,6 +2864,7 @@ export async function installTool(toolId) {
  * Ensure a tool is installed (check first, install if missing)
  */
 export async function ensureTool(toolId, opts) {
+    installFailureReasons.delete(toolId);
     const cacheResolvedPath = (result) => {
         if (result) {
             resolvedPathCache.set(toolId, result);
@@ -2706,8 +2895,23 @@ export async function ensureTool(toolId, opts) {
             logSessionStart(`auto-install ensure ${toolId}: force reinstall blocked — install disabled, discovery only (${Date.now() - ensureStartMs}ms)`);
             return cacheResolvedPath(await getToolPath(toolId));
         }
-        // Force download
-        const installed = await installTool(toolId);
+        if (process.env.PI_LENS_DISABLE_TOOL_INSTALL === "1") {
+            installFailureReasons.set(toolId, "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
+            logSessionStart(`auto-install ensure ${toolId}: refused — PI_LENS_DISABLE_TOOL_INSTALL=1`);
+            return undefined;
+        }
+        const lock = await acquireInstallLock();
+        if (!lock.release) {
+            logSessionStart(`auto-install ensure ${toolId}: ${lock.reason}`);
+            return undefined;
+        }
+        let installed;
+        try {
+            installed = await installTool(toolId);
+        }
+        finally {
+            await lock.release();
+        }
         if (!installed) {
             logSessionStart(`auto-install ensure ${toolId}: force reinstall failed (${Date.now() - ensureStartMs}ms)`);
             return undefined;
@@ -2783,7 +2987,32 @@ export async function ensureTool(toolId, opts) {
             logSessionStart(`auto-install ensure ${toolId}: install disabled — discovery only, not found (${Date.now() - ensureStartMs}ms)`);
             return undefined;
         }
-        const installed = await installTool(toolId);
+        if (process.env.PI_LENS_DISABLE_TOOL_INSTALL === "1") {
+            installFailureReasons.set(toolId, "installation disabled by PI_LENS_DISABLE_TOOL_INSTALL=1");
+            logSessionStart(`auto-install ensure ${toolId}: refused — PI_LENS_DISABLE_TOOL_INSTALL=1 (${Date.now() - ensureStartMs}ms)`);
+            return undefined;
+        }
+        const lock = await acquireInstallLock();
+        if (!lock.release) {
+            installFailureReasons.set(toolId, lock.reason ?? "install lock failed");
+            logSessionStart(`auto-install ensure ${toolId}: ${lock.reason}`);
+            return undefined;
+        }
+        let installed;
+        try {
+            // Cross-process double-check: the lock waiter may now observe the tool
+            // installed by its predecessor and must not run a second package manager.
+            const installedByPeer = await getToolPath(toolId);
+            if (installedByPeer) {
+                resolvedPathCache.set(toolId, installedByPeer);
+                void updateProbeCache(toolId, installedByPeer);
+                return installedByPeer;
+            }
+            installed = await installTool(toolId);
+        }
+        finally {
+            await lock.release();
+        }
         if (!installed) {
             logSessionStart(`auto-install ensure ${toolId}: unavailable (${Date.now() - ensureStartMs}ms)`);
             return undefined;