@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/pi-lens/dist/clients/installer/index.js

@@ -45,6 +45,7 @@
  * - pip packages
  * - GitHub releases (platform-specific binaries → ~/.pi-lens/bin/)
  */
+import { logExtension } from "../extension-log.js";
 import { spawn } from "node:child_process";
 import { existsSync, statSync, unlinkSync } from "node:fs";
 import fs from "node:fs/promises";
@@ -52,17 +53,29 @@ import https from "node:https";
 import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
+import { BoundedLruCache } from "../bounded-cache.js";
+import { isFullyQualified } from "../path-utils.js";
+import { assertInstallAllowed, projectTrustDenialReason, } from "../project-trust.js";
 const _installerRequire = createRequire(import.meta.url);
 import { createGunzip } from "node:zlib";
 import { logSessionStart } from "../sessionstart-logger.js";
+import { commitDurableStoreAsync } from "../durable-store.js";
 import { getGlobalPiLensDir } from "../file-utils.js";
 import { allAvailableGlobalBinDirs, installArgs, pmBinary, resolveNodePackageManager, } from "../package-manager.js";
-import { safeSpawnAsync } from "../safe-spawn.js";
+import { resetSafeSpawnWindowsCommandCache, 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;
+/**
+ * The managed tools tree, for callers that need to tell a path `getToolPath()`
+ * returned from the managed install apart from a global/PATH hit (the tool
+ * registry is this module's business — don't re-derive `<pi-lens home>/tools`).
+ */
+export function getManagedToolsDir() {
+    return TOOLS_DIR;
+}
 function isProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -164,12 +177,27 @@ async function acquireInstallLock() {
 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");
+/** Test-only platform seam for Windows resource-layout coverage on Linux CI. */
+function installerPlatform() {
+    const override = process.env.PI_LENS_TEST_PLATFORM;
+    if (override === "win32" || override === "linux") {
+        return override;
+    }
+    return process.platform;
+}
 /**
  * Log debug messages only when DEBUG is enabled
  */
 function debugLog(...args) {
     if (DEBUG) {
-        console.error("[auto-install:debug]", ...args);
+        // #1333: DEBUG gate preserved; sink is extension.log, never the TUI.
+        logExtension({
+            subsystem: "auto-install",
+            level: "debug",
+            message: args
+                .map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg)))
+                .join(" "),
+        });
     }
 }
 /**
@@ -177,16 +205,25 @@ function debugLog(...args) {
  * the copy-pasted `if (platform === "linux") return arch === "arm64" ? … : …`
  * ladder that several release entries repeat verbatim. Each platform maps to its
  * `x64` (default) and optional `arm64` asset substring; a missing platform or
- * arch ⇒ unsupported (`undefined`), exactly as the hand-written ladders behaved.
+ * arch ⇒ unsupported (`undefined`). Arches outside x64/arm64 (ia32, ppc64, …)
+ * are unsupported too — no release entry ships a 32-bit or exotic asset, and
+ * handing back the x64 substring there would install an unrunnable binary.
  */
 function archAssetMatch(table) {
     return (platform, arch) => {
-        const entry = table[platform];
-        if (!entry)
+        if (arch !== "x64" && arch !== "arm64")
             return undefined;
-        return arch === "arm64" ? entry.arm64 : entry.x64;
+        return table[platform]?.[arch];
     };
 }
+// Go-style `<os>_<arch>.zip` release assets, shared verbatim by tflint and
+// terraform-ls — both entries carried byte-identical ladders, down to the asset
+// strings themselves.
+const OS_ARCH_ZIP_ASSETS = {
+    linux: { x64: "linux_amd64.zip", arm64: "linux_arm64.zip" },
+    darwin: { x64: "darwin_amd64.zip", arm64: "darwin_arm64.zip" },
+    win32: { x64: "windows_amd64.zip", arm64: "windows_arm64.zip" },
+};
 export const TOOLS = [
     // Core LSP servers
     {
@@ -418,6 +455,31 @@ export const TOOLS = [
             },
         },
     },
+    {
+        id: "helm",
+        name: "Helm",
+        checkCommand: "helm",
+        checkArgs: ["version", "--short"],
+        installStrategy: "github",
+        binaryName: "helm",
+        github: {
+            repo: "helm/helm",
+            assetMatch: (platform, arch) => {
+                // helm publishes per-OS archives: tar.gz for POSIX, zip for Windows.
+                const cpu = arch === "arm64" ? "arm64" : "amd64";
+                if (platform === "linux")
+                    return `linux-${cpu}.tar.gz`;
+                if (platform === "darwin")
+                    return `darwin-${cpu}.tar.gz`;
+                if (platform === "win32")
+                    return `windows-${cpu}.zip`;
+                return undefined;
+            },
+            // Release archives nest the executable under an OS/arch directory;
+            // the installer searches recursively and adds the Windows suffix.
+            binaryInArchive: "helm",
+        },
+    },
     {
         // Opengrep: a single standalone binary per platform on GitHub releases —
         // no login, no telemetry (the reason for switching off Semgrep, #111).
@@ -919,18 +981,39 @@ export const TOOLS = [
         binaryName: "tflint",
         github: {
             repo: "terraform-linters/tflint",
-            assetMatch: (platform, arch) => {
-                if (platform === "linux")
-                    return arch === "arm64" ? "linux_arm64.zip" : "linux_amd64.zip";
-                if (platform === "darwin")
-                    return arch === "arm64" ? "darwin_arm64.zip" : "darwin_amd64.zip";
-                if (platform === "win32")
-                    return arch === "arm64" ? "windows_arm64.zip" : "windows_amd64.zip";
-                return undefined;
-            },
+            assetMatch: archAssetMatch(OS_ARCH_ZIP_ASSETS),
             binaryInArchive: "tflint",
         },
     },
+    {
+        // Terragrunt ships a bare native binary per platform on GitHub releases.
+        // Windows arm64 uses the x64 binary through Windows' built-in emulation —
+        // there is no terragrunt_windows_arm64.exe upstream.
+        id: "terragrunt",
+        name: "terragrunt",
+        checkCommand: "terragrunt",
+        checkArgs: ["--version"],
+        installStrategy: "github",
+        binaryName: "terragrunt",
+        github: {
+            repo: "gruntwork-io/terragrunt",
+            assetMatch: archAssetMatch({
+                linux: {
+                    x64: "terragrunt_linux_amd64",
+                    arm64: "terragrunt_linux_arm64",
+                },
+                darwin: {
+                    x64: "terragrunt_darwin_amd64",
+                    arm64: "terragrunt_darwin_arm64",
+                },
+                win32: {
+                    x64: "terragrunt_windows_amd64.exe",
+                    arm64: "terragrunt_windows_amd64.exe",
+                },
+            }),
+            // bare binary — no binaryInArchive
+        },
+    },
     {
         id: "gitleaks",
         name: "gitleaks",
@@ -1055,15 +1138,7 @@ export const TOOLS = [
         github: {
             repo: "hashicorp/terraform-ls",
             hashiCorpReleaseProduct: "terraform-ls",
-            assetMatch: (platform, arch) => {
-                if (platform === "linux")
-                    return arch === "arm64" ? "linux_arm64.zip" : "linux_amd64.zip";
-                if (platform === "darwin")
-                    return arch === "arm64" ? "darwin_arm64.zip" : "darwin_amd64.zip";
-                if (platform === "win32")
-                    return arch === "arm64" ? "windows_arm64.zip" : "windows_amd64.zip";
-                return undefined;
-            },
+            assetMatch: archAssetMatch(OS_ARCH_ZIP_ASSETS),
             binaryInArchive: "terraform-ls",
         },
     },
@@ -1221,33 +1296,164 @@ 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 resolvedPathCache = new BoundedLruCache(256);
 const PROBE_CACHE_PATH = path.join(getGlobalPiLensDir(), "probe-cache.json");
+const PROBE_CACHE_LOCK_STALE_MS = 180_000;
 const PROBE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const PROBE_CACHE_FLUSH_LOCK_WAIT_MS = 250;
+const PROBE_CACHE_FLUSH_RETRY_DELAY_MS = 300;
+const PROBE_CACHE_FLUSH_RETRY_MAX_DELAY_MS = 30_000;
 let _probeCache = null;
 let _probeCacheDirty = false;
 let _probeCacheFlushTimer = null;
+let _probeCacheWriteInFlight = null;
+let _probeCacheRetryAttempt = 0;
+let _probeCacheChangeGeneration = 0;
+// Read-modify-write deltas let a long-lived process merge with entries another
+// process discovered after this process's initial read. `null` is a deliberate
+// deletion (TTL/stale-path eviction), not an absent map value.
+const _probeCacheChanges = new Map();
+const _probeCacheChangeVersions = new Map();
 async function readProbeCache() {
     if (_probeCache !== null)
         return _probeCache;
     try {
         const raw = await fs.readFile(PROBE_CACHE_PATH, "utf-8");
-        _probeCache = JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("probe-cache root is not an object");
+        }
+        _probeCache = parsed;
     }
-    catch {
+    catch (err) {
+        const code = err?.code;
+        if (code !== "ENOENT") {
+            logSessionStart(`auto-install probe-cache: read failed (${code ?? "invalid"}); treating cache as unavailable`);
+        }
         _probeCache = {};
     }
     return _probeCache;
 }
-function scheduleProbeFlush() {
+function markProbeCacheChange(toolId, entry) {
+    _probeCacheChanges.set(toolId, entry);
+    _probeCacheChangeVersions.set(toolId, ++_probeCacheChangeGeneration);
+    _probeCacheDirty = true;
+    scheduleProbeFlush();
+}
+function scheduleProbeFlush(delayMs = PROBE_CACHE_FLUSH_RETRY_DELAY_MS) {
     if (_probeCacheFlushTimer !== null)
         return;
     _probeCacheFlushTimer = setTimeout(() => {
         void flushProbeCache();
-    }, 300);
+    }, delayMs);
     _probeCacheFlushTimer.unref?.();
 }
-let _probeCacheWriteInFlight = null;
+function scheduleProbeFlushRetry() {
+    const delay = Math.min(PROBE_CACHE_FLUSH_RETRY_MAX_DELAY_MS, PROBE_CACHE_FLUSH_RETRY_DELAY_MS * 2 ** Math.min(_probeCacheRetryAttempt, 6));
+    _probeCacheRetryAttempt += 1;
+    scheduleProbeFlush(delay);
+}
+function snapshotProbeCacheChanges() {
+    return {
+        changes: new Map(_probeCacheChanges),
+        versions: new Map(_probeCacheChangeVersions),
+    };
+}
+function deserializeProbeCache(contents) {
+    if (contents === undefined)
+        return {};
+    const parsed = JSON.parse(contents);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("probe-cache root is not an object");
+    }
+    return parsed;
+}
+function applyProbeCacheChanges(disk, changes) {
+    for (const [toolId, entry] of changes) {
+        if (entry === null)
+            delete disk[toolId];
+        else
+            disk[toolId] = entry;
+    }
+}
+/**
+ * Install-lifetime ageing belongs to the authoritative merge, not only to the
+ * lookup path: a sibling process may have left expired entries on disk since
+ * this process loaded its in-memory snapshot. The async durable-store lock
+ * supplies the probe cache's former quarantine/stale-owner recovery.
+ */
+function ageProbeCache(disk) {
+    const cutoff = Date.now() - PROBE_CACHE_TTL_MS;
+    for (const [toolId, entry] of Object.entries(disk)) {
+        if (!Number.isFinite(entry.cachedAt) || entry.cachedAt < cutoff) {
+            delete disk[toolId];
+        }
+    }
+}
+function publishProbeCacheWrite(disk, snapshotVersions) {
+    // Publish the sibling-process merge plus any updates that arrived during
+    // the write. Only an unchanged snapshot entry is retired.
+    const pendingAfterWrite = new Map(_probeCacheChanges);
+    _probeCache = disk;
+    for (const [toolId, entry] of pendingAfterWrite) {
+        if (entry === null)
+            delete _probeCache[toolId];
+        else
+            _probeCache[toolId] = entry;
+    }
+    for (const [toolId, version] of snapshotVersions) {
+        if (_probeCacheChangeVersions.get(toolId) === version) {
+            _probeCacheChanges.delete(toolId);
+            _probeCacheChangeVersions.delete(toolId);
+        }
+    }
+    _probeCacheDirty = _probeCacheChanges.size > 0;
+    _probeCacheRetryAttempt = 0;
+    return _probeCacheDirty ? "written-with-pending" : "written";
+}
+async function writeProbeCache() {
+    try {
+        // Snapshot versions before the awaited disk read/write. A new update for
+        // the same tool may arrive while the atomic write is in flight; its newer
+        // version must remain pending for the next flush.
+        const { changes, versions } = snapshotProbeCacheChanges();
+        let result = "written";
+        const committed = await commitDurableStoreAsync({
+            path: PROBE_CACHE_PATH,
+            deserialize: deserializeProbeCache,
+            merge: (disk) => {
+                ageProbeCache(disk);
+                applyProbeCacheChanges(disk, changes);
+                return disk;
+            },
+            serialize: (disk) => JSON.stringify(disk, null, 2),
+            waitMs: PROBE_CACHE_FLUSH_LOCK_WAIT_MS,
+            retryMs: 25,
+            staleMs: PROBE_CACHE_LOCK_STALE_MS,
+            timeoutMessage: "Timed out waiting for probe-cache lock",
+            onContention: "skip-log",
+            logContention: () => {
+                logSessionStart("auto-install probe-cache: flush deferred because another process owns the lock");
+            },
+            afterWriteLocked: (disk) => {
+                result = publishProbeCacheWrite(disk, versions);
+            },
+        });
+        if (committed === undefined) {
+            scheduleProbeFlushRetry();
+            return "deferred";
+        }
+        return result;
+    }
+    catch (err) {
+        // Keep dirty state so a later timer/explicit flush can retry. The error
+        // is logged without paths, source, or command text; an unavailable cache
+        // must never look like a clean empty cache to operators.
+        logSessionStart(`auto-install probe-cache: flush failed (${err?.code ?? "write error"}); pending update retained`);
+        scheduleProbeFlushRetry();
+        return "failed";
+    }
+}
 /** Await pending probe-cache persistence before a one-shot process exits. */
 export async function flushProbeCache() {
     if (_probeCacheFlushTimer !== null) {
@@ -1257,22 +1463,17 @@ export async function flushProbeCache() {
     // #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) {
+    if (_probeCacheWriteInFlight) {
         await _probeCacheWriteInFlight;
-        return;
+        if (!_probeCacheDirty)
+            return "written";
     }
-    _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.
-        }
-    })();
+    if (!_probeCacheDirty || _probeCache === null)
+        return "idle";
+    const write = writeProbeCache();
     _probeCacheWriteInFlight = write;
     try {
-        await write;
+        return await write;
     }
     finally {
         if (_probeCacheWriteInFlight === write)
@@ -1316,8 +1517,7 @@ export async function checkProbeCache(toolId) {
     if (Date.now() - entry.cachedAt > PROBE_CACHE_TTL_MS) {
         logSessionStart(`auto-install probe-cache ${toolId}: miss (ttl expired)`);
         delete cache[toolId];
-        _probeCacheDirty = true;
-        scheduleProbeFlush();
+        markProbeCacheChange(toolId, null);
         return undefined;
     }
     try {
@@ -1326,15 +1526,13 @@ export async function checkProbeCache(toolId) {
         if (stat.mtimeMs !== entry.mtimeMs) {
             logSessionStart(`auto-install probe-cache ${toolId}: miss (mtime changed)`);
             delete cache[toolId];
-            _probeCacheDirty = true;
-            scheduleProbeFlush();
+            markProbeCacheChange(toolId, null);
             return undefined;
         }
         if (toolId === "ast-grep" && !(await verifyAstGrepProbePath(entry.path))) {
             logSessionStart(`auto-install probe-cache ${toolId}: miss (not ast-grep: ${entry.path})`);
             delete cache[toolId];
-            _probeCacheDirty = true;
-            scheduleProbeFlush();
+            markProbeCacheChange(toolId, null);
             return undefined;
         }
         return entry.path;
@@ -1342,8 +1540,7 @@ export async function checkProbeCache(toolId) {
     catch {
         logSessionStart(`auto-install probe-cache ${toolId}: miss (gone: ${entry.path})`);
         delete cache[toolId];
-        _probeCacheDirty = true;
-        scheduleProbeFlush();
+        markProbeCacheChange(toolId, null);
         return undefined;
     }
 }
@@ -1352,13 +1549,13 @@ export async function updateProbeCache(toolId, resolvedPath) {
     try {
         const stat = await fs.stat(resolvedPath);
         const cache = await readProbeCache();
-        cache[toolId] = {
+        const entry = {
             path: resolvedPath,
             mtimeMs: stat.mtimeMs,
             cachedAt: Date.now(),
         };
-        _probeCacheDirty = true;
-        scheduleProbeFlush();
+        cache[toolId] = entry;
+        markProbeCacheChange(toolId, entry);
     }
     catch {
         // best-effort
@@ -1368,16 +1565,33 @@ export async function updateProbeCache(toolId, resolvedPath) {
 export function resetProbeCacheStateForTesting() {
     _probeCache = null;
     _probeCacheDirty = false;
+    _probeCacheChanges.clear();
+    _probeCacheChangeVersions.clear();
+    _probeCacheChangeGeneration = 0;
+    _probeCacheRetryAttempt = 0;
     resolvedPathCache.clear();
     ensureInFlight.clear();
     installFailureReasons.clear();
     lastManagedInstallVersion.clear();
+    resetPathWalkMemo();
     if (_probeCacheFlushTimer !== null) {
         clearTimeout(_probeCacheFlushTimer);
         _probeCacheFlushTimer = null;
     }
 }
 // --- Check Functions ---
+const pathWalkMemo = new Map();
+function hashSync(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
+export function resetPathWalkMemo() {
+    pathWalkMemo.clear();
+}
 /**
  * Check if a command is available in PATH by walking PATH entries and
  * verifying each candidate is a real file with non-zero size.
@@ -1385,7 +1599,7 @@ export function resetProbeCacheStateForTesting() {
  * spawning a process — ~μs per candidate vs ~50ms for which/where.
  */
 export async function isCommandAvailable(command, _args) {
-    const isWindows = process.platform === "win32";
+    const isWindows = installerPlatform() === "win32";
     const pathEnv = process.env.PATH || process.env.Path || process.env.path || "";
     const dirs = pathEnv.split(path.delimiter);
     // On Windows, probe .exe, .cmd, and .bat extensions in addition to bare name.
@@ -1427,7 +1641,12 @@ export async function isSpawnableCommand(command) {
             return false;
         }
     }
-    return isCommandAvailable(command);
+    const memoKey = `${command}:${hashSync(process.env.PATH || "")}`;
+    if (pathWalkMemo.has(memoKey))
+        return pathWalkMemo.get(memoKey) ?? false;
+    const isSpawnable = await isCommandAvailable(command);
+    pathWalkMemo.set(memoKey, isSpawnable);
+    return isSpawnable;
 }
 // --- Verification Functions
 /**
@@ -1483,7 +1702,7 @@ const lastManagedInstallVersion = new Map();
  */
 async function verifyToolBinary(binPath, onVersionOutput) {
     return new Promise((resolve) => {
-        const isWindows = process.platform === "win32";
+        const isWindows = installerPlatform() === "win32";
         const hasKnownWindowsExt = /\.(cmd|exe|ps1)$/i.test(binPath);
         // On Windows, resolve the best executable path:
         // - extensionless → prefer .cmd (cmd.exe-safe)
@@ -1644,7 +1863,7 @@ export async function getAllToolStatuses() {
         }
         // 5. Check pi-lens auto-install (~/.pi-lens/tools/)
         const localBase = path.join(TOOLS_DIR, "node_modules", ".bin", tool.binaryName || tool.id);
-        const localPath = process.platform === "win32" ? `${localBase}.cmd` : localBase;
+        const localPath = installerPlatform() === "win32" ? `${localBase}.cmd` : localBase;
         try {
             await fs.access(localPath);
             if (await verifyToolBinary(localPath)) {
@@ -1709,7 +1928,7 @@ export function resolvePlatformPackageBinary(tool) {
     const spec = tool.platformPackage;
     if (!spec || !tool.packageName)
         return undefined;
-    const suffix = spec.suffixes[`${process.platform}-${process.arch}`];
+    const suffix = spec.suffixes[`${installerPlatform()}-${process.arch}`];
     if (!suffix)
         return undefined;
     const platformPkg = `${spec.base ?? tool.packageName}-${suffix}`;
@@ -1725,7 +1944,7 @@ export function resolvePlatformPackageBinary(tool) {
         catch {
             pkgDir = path.dirname(_installerRequire.resolve(`${platformPkg}/package.json`));
         }
-        const isWin = process.platform === "win32";
+        const isWin = installerPlatform() === "win32";
         for (const bin of spec.binaries) {
             for (const name of isWin ? [`${bin}.exe`, bin] : [bin]) {
                 const candidate = path.join(pkgDir, name);
@@ -1771,7 +1990,7 @@ export async function getToolPath(toolId) {
     // This avoids the ~2-5s overhead of spawning npm global probes and PATH
     // searches for tools we already manage locally.
     const localBase = path.join(TOOLS_DIR, "node_modules", ".bin", tool.binaryName || tool.id);
-    if (process.platform === "win32") {
+    if (installerPlatform() === "win32") {
         // Prefer .cmd over extensionless — Node.js can't execute POSIX shell scripts on Windows
         const cmdPath = `${localBase}.cmd`;
         try {
@@ -1798,15 +2017,17 @@ export async function getToolPath(toolId) {
             // fall through to extensionless
         }
     }
-    try {
-        await fs.access(localBase);
-        if (await verifyToolBinary(localBase, recordVersion)) {
-            return localBase;
+    if (installerPlatform() !== "win32") {
+        try {
+            await fs.access(localBase);
+            if (await verifyToolBinary(localBase, recordVersion)) {
+                return localBase;
+            }
+            logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
+        }
+        catch {
+            // fall through to global checks
         }
-        logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
-    }
-    catch {
-        // fall through to global checks
     }
     // npm/pnpm/bun: prefer the native per-platform binary directly. The main
     // package's launcher often can't find it under a symlink store / after a
@@ -1909,7 +2130,6 @@ async function findNpmGlobalToolPath(binaryName) {
             ? [
                 path.join(dir, `${binaryName}.cmd`),
                 path.join(dir, `${binaryName}.exe`),
-                path.join(dir, binaryName),
             ]
             : [path.join(dir, binaryName)];
         for (const candidate of candidates) {
@@ -2160,7 +2380,7 @@ async function installGitHubTool(tool) {
         logSessionStart(`github-install ${tool.id}: release fetch failed: ${err.message}`);
         return undefined;
     }
-    const asset = releaseJson.assets.find((a) => a.name.includes(assetSubstring)) ??
+    const asset = pickReleaseAsset(releaseJson.assets, assetSubstring) ??
         deriveHashiCorpReleaseAsset(tool, releaseJson.tag_name, assetSubstring);
     if (!asset) {
         logSessionStart(`github-install ${tool.id}: no asset matched "${assetSubstring}"`);
@@ -2537,7 +2757,7 @@ async function installNpmTool(packageName, binaryName) {
             await fs.writeFile(packageJsonPath, JSON.stringify({ name: "pi-lens-tools", version: "1.0.0" }, null, 2));
         }
         // Resolve the package manager for the tools dir and build install args.
-        const isWindows = process.platform === "win32";
+        const isWindows = installerPlatform() === "win32";
         const pm = await resolveNodePackageManager(TOOLS_DIR);
         const testNpmScript = process.env.PI_LENS_TEST_MODE === "1"
             ? process.env.PI_LENS_TEST_NPM_SCRIPT
@@ -2583,9 +2803,12 @@ async function installNpmTool(packageName, binaryName) {
         if (!outcome.ok) {
             throw new Error(`Failed to install ${packageName}: ${outcome.stderr}`);
         }
-        const binPath = path.join(TOOLS_DIR, "node_modules", ".bin", binaryName);
+        // npm creates a command shim on Windows; retain that actual executable path
+        // rather than probing/storing the extensionless POSIX sibling.
+        const binBase = path.join(TOOLS_DIR, "node_modules", ".bin", binaryName);
+        const binPath = installerPlatform() === "win32" ? `${binBase}.cmd` : binBase;
         // Make executable on Unix
-        if (process.platform !== "win32") {
+        if (installerPlatform() !== "win32") {
             try {
                 await fs.chmod(binPath, 0o750);
             }
@@ -2615,10 +2838,10 @@ async function installNpmTool(packageName, binaryName) {
             try {
                 const packagePath = path.join(TOOLS_DIR, "node_modules", packageName);
                 await fs.rm(packagePath, { recursive: true, force: true });
-                await fs.rm(binPath, { force: true });
+                await fs.rm(binBase, { force: true });
                 if (isWindows) {
-                    await fs.rm(`${binPath}.cmd`, { force: true });
-                    await fs.rm(`${binPath}.ps1`, { force: true });
+                    await fs.rm(`${binBase}.cmd`, { force: true });
+                    await fs.rm(`${binBase}.ps1`, { force: true });
                 }
             }
             catch {
@@ -2784,6 +3007,33 @@ async function installGemTool(packageName) {
         return undefined;
     }
 }
+async function finishInstallAttempt(toolId, ok, startedAt) {
+    logSessionStart(`auto-install ${toolId}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
+    if (ok) {
+        // A prior availability probe may have cached ENOENT for this exact child
+        // PATH. Make a successful mutation visible immediately rather than waiting
+        // for the bounded negative-cache TTL or the next session reset (#1199).
+        resetSafeSpawnWindowsCommandCache();
+        // #1276: the madge managed-path memo is keyed only by projectRoot, but
+        // reads PATH/discovery/install state that a completed install can just
+        // have changed — drop it here too, right alongside the safe-spawn reset.
+        // AWAITED (not fire-and-forget): a caller that starts the next madge
+        // resolution the instant `installTool`/`ensureTool` resolves must observe
+        // the reset memo, not a stale pre-install one, and a rejected dynamic
+        // import must not become a silent unhandled rejection. Dynamic import
+        // avoids a static dependency-checker.js <-> installer/index.js cycle
+        // (dependency-checker.js already imports this module dynamically for the
+        // same reason).
+        try {
+            const { resetMadgeManagedPathMemo } = await import("../dependency-checker.js");
+            resetMadgeManagedPathMemo();
+        }
+        catch (err) {
+            logSessionStart(`auto-install ${toolId}: madge memo reset failed: ${err.message}`);
+        }
+    }
+    return ok;
+}
 /**
  * Install a tool by ID
  */
@@ -2806,49 +3056,37 @@ export async function installTool(toolId) {
                 if (!tool.packageName || !tool.binaryName)
                     return false;
                 const npmPath = await installNpmTool(tool.packageName, tool.binaryName);
-                const ok = npmPath !== undefined;
-                logSessionStart(`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
-                return ok;
+                return finishInstallAttempt(tool.id, npmPath !== undefined, startedAt);
             }
             case "pip": {
                 if (!tool.packageName)
                     return false;
                 const pipPath = await installPipTool(tool.packageName);
-                const ok = pipPath !== undefined;
-                logSessionStart(`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
-                return ok;
+                return finishInstallAttempt(tool.id, pipPath !== undefined, startedAt);
             }
             case "gem": {
                 if (!tool.packageName)
                     return false;
                 const gemPath = await installGemTool(tool.packageName);
-                const ok = gemPath !== undefined;
-                logSessionStart(`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
-                return ok;
+                return finishInstallAttempt(tool.id, gemPath !== undefined, startedAt);
             }
             case "github": {
                 if (!tool.github)
                     return false;
                 const ghPath = await installGitHubTool(tool);
-                const ok = ghPath !== undefined;
-                logSessionStart(`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
-                return ok;
+                return finishInstallAttempt(tool.id, ghPath !== undefined, startedAt);
             }
             case "maven": {
                 if (!tool.maven)
                     return false;
                 const mavenPath = await installMavenTool(tool);
-                const ok = mavenPath !== undefined;
-                logSessionStart(`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
-                return ok;
+                return finishInstallAttempt(tool.id, mavenPath !== undefined, startedAt);
             }
             case "archive": {
                 if (!tool.archive)
                     return false;
                 const archivePath = await installArchiveTool(tool);
-                const ok = archivePath !== undefined;
-                logSessionStart(`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
-                return ok;
+                return finishInstallAttempt(tool.id, archivePath !== undefined, startedAt);
             }
             default:
                 logSessionStart(`auto-install ${tool.id}: unsupported strategy`);
@@ -2861,9 +3099,24 @@ export async function installTool(toolId) {
     }
 }
 /**
- * Ensure a tool is installed (check first, install if missing)
+ * Ensure a tool is installed (check first, install if missing).
+ *
+ * #1334 S5: when the pi host has actively denied project trust, the INSTALL
+ * half is switched off here — the request degrades to the existing
+ * `allowInstall:false` discovery-only path rather than failing outright, so an
+ * already-present binary keeps working while nothing is downloaded or executed
+ * on behalf of an untrusted project. A host with no trust surface at all
+ * (`"unknown"`) is unaffected.
  */
 export async function ensureTool(toolId, opts) {
+    if (opts?.allowInstall !== false &&
+        !assertInstallAllowed(`managed tool ensure: ${toolId}`)) {
+        logSessionStart(`auto-install ensure ${toolId}: install gated — ${projectTrustDenialReason()}; discovery only`);
+        return ensureToolResolved(toolId, { ...opts, allowInstall: false });
+    }
+    return ensureToolResolved(toolId, opts);
+}
+async function ensureToolResolved(toolId, opts) {
     installFailureReasons.delete(toolId);
     const cacheResolvedPath = (result) => {
         if (result) {
@@ -2885,8 +3138,7 @@ export async function ensureTool(toolId, opts) {
         try {
             const probeCache = await readProbeCache();
             delete probeCache[toolId];
-            _probeCacheDirty = true;
-            scheduleProbeFlush();
+            markProbeCacheChange(toolId, null);
         }
         catch {
             // best-effort
@@ -2925,8 +3177,23 @@ export async function ensureTool(toolId, opts) {
     }
     // Fast path 1: in-memory session cache — no I/O.
     const cached = resolvedPathCache.get(toolId);
-    if (cached)
-        return cached;
+    if (cached) {
+        if (!isFullyQualified(cached))
+            return cached;
+        try {
+            await fs.access(cached);
+            return cached;
+        }
+        catch {
+            // The executor would report ENOENT for this cached positive. Evict it
+            // before discovery so the failure heals on this call, not after restart.
+        }
+        resolvedPathCache.delete(toolId);
+        const probeCache = await readProbeCache();
+        delete probeCache[toolId];
+        markProbeCacheChange(toolId, null);
+        logSessionStart(`auto-install ensure ${toolId}: cached path disappeared; re-probing`);
+    }
     // Fast path 2: persistent probe cache — fs.access + stat, no process spawn.
     const diskCached = await checkProbeCache(toolId);
     if (diskCached) {
@@ -3100,9 +3367,11 @@ export const GITHUB_TOOLS = [
     "zizmor",
     "typos-lsp",
     "tflint",
+    "terragrunt",
     "terraform-ls",
     "zls",
     "hadolint",
+    "helm",
     "gitleaks",
     "taplo",
     "vale",
@@ -3135,6 +3404,28 @@ export function resolveGitHubArchiveBinaryCandidates(toolId, platform, assetName
     const binaryName = tool.github?.binaryInArchive ?? tool.binaryName ?? tool.id;
     return getArchiveBinaryCandidates(binaryName, platform, assetName);
 }
+// Signature/checksum siblings a release publishes next to the real asset. A
+// bare-binary tool's substring IS the whole asset name, so `includes` alone
+// matches `<asset>.asc` too and would install a signature file as the binary.
+const ASSET_SIDECAR_SUFFIXES = [
+    ".asc",
+    ".sig",
+    ".minisig",
+    ".pem",
+    ".cert",
+    ".sbom",
+    ".sha256",
+    ".sha256sum",
+    ".md5",
+];
+function isAssetSidecar(name) {
+    const lower = name.toLowerCase();
+    return ASSET_SIDECAR_SUFFIXES.some((suffix) => lower.endsWith(suffix));
+}
+export function pickReleaseAsset(assets, assetSubstring) {
+    return (assets.find((a) => a.name === assetSubstring) ??
+        assets.find((a) => a.name.includes(assetSubstring) && !isAssetSidecar(a.name)));
+}
 function deriveHashiCorpReleaseAsset(tool, tagName, assetSubstring) {
     const product = tool.github?.hashiCorpReleaseProduct;
     if (!product || !tagName)