@duckmind/dm-linux-x64 0.63.9 → 0.64.2

package/extensions/dm-lens/clients/installer/index.js

@@ -0,0 +1,3275 @@
+import { spawn } from "node:child_process";
+import { existsSync, statSync, unlinkSync } from "node:fs";
+import fs from "node:fs/promises";
+import https from "node:https";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { writeFileAtomicAsync } from "../atomic-write.js";
+import { BoundedLruCache } from "../bounded-cache.js";
+import { logExtension } from "../extension-log.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 { TRANSIENT_MAX_COOLDOWN_MS } from "../dispatch/runners/utils/availability-policy.js";
+import { recordDegradationOnce } from "../degradation-ledger.js";
+import { commitDurableStoreAsync } from "../durable-store.js";
+import { getGlobalDmLensDir } from "../file-utils.js";
+import {
+  allAvailableGlobalBinDirs,
+  installArgs,
+  pmBinary,
+  resolveNodePackageManager
+} from "../package-manager.js";
+import {
+  resetSafeSpawnWindowsCommandCache,
+  safeSpawnAsync
+} from "../safe-spawn.js";
+import { logSessionStart } from "../sessionstart-logger.js";
+const TOOLS_DIR = path.join(getGlobalDmLensDir(), "tools");
+const INSTALL_LOCK_PATH = path.join(TOOLS_DIR, ".install.lock");
+const activeInstallLocks = new Set;
+let installLockExitCleanupRegistered = false;
+export function getManagedToolsDir() {
+  return TOOLS_DIR;
+}
+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 });
+  const timeoutMs = Number(process.env.DM_LENS_INSTALL_LOCK_TIMEOUT_MS) || 150000;
+  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 {}
+          }
+        });
+      }
+      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}`;
+        const maxAgeMs = (Number(process.env.DM_LENS_INSTALL_TIMEOUT_MS) || 120000) + 60000;
+        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";
+        try {
+          const stat = await fs.stat(INSTALL_LOCK_PATH);
+          const maxAgeMs = (Number(process.env.DM_LENS_INSTALL_TIMEOUT_MS) || 120000) + 60000;
+          if (Date.now() - stat.mtimeMs > maxAgeMs) {
+            await fs.rm(INSTALL_LOCK_PATH, { force: true });
+            continue;
+          }
+        } catch {}
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+  return {
+    reason: `timed out after ${timeoutMs}ms waiting for shared tools install lock (${lastOwner})`
+  };
+}
+const GITHUB_BIN_DIR = path.join(getGlobalDmLensDir(), "bin");
+const DEBUG = process.env.DM_LENS_DEBUG === "1" || process.argv.includes("--debug");
+function installerPlatform() {
+  const override = process.env.DM_LENS_TEST_PLATFORM;
+  if (override === "win32" || override === "linux") {
+    return override;
+  }
+  return process.platform;
+}
+function debugLog(...args) {
+  if (DEBUG) {
+    logExtension({
+      subsystem: "auto-install",
+      level: "debug",
+      message: args.map((arg) => typeof arg === "string" ? arg : JSON.stringify(arg)).join(" ")
+    });
+  }
+}
+function archAssetMatch(table) {
+  return (platform, arch) => {
+    if (arch !== "x64" && arch !== "arm64")
+      return;
+    return table[platform]?.[arch];
+  };
+}
+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 = [
+  {
+    id: "typescript-language-server",
+    name: "TypeScript Language Server",
+    checkCommand: "typescript-language-server",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "typescript-language-server",
+    binaryName: "typescript-language-server"
+  },
+  {
+    id: "typescript",
+    name: "TypeScript",
+    checkCommand: "tsc",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "typescript@5.9.3",
+    binaryName: "tsc"
+  },
+  {
+    id: "pyright",
+    name: "Pyright",
+    checkCommand: "pyright",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "pyright",
+    binaryName: "pyright"
+  },
+  {
+    id: "prettier",
+    name: "Prettier",
+    checkCommand: "prettier",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "prettier",
+    binaryName: "prettier"
+  },
+  {
+    id: "ruff",
+    name: "Ruff",
+    checkCommand: "ruff",
+    checkArgs: ["--version"],
+    installStrategy: "pip",
+    packageName: "ruff",
+    binaryName: "ruff"
+  },
+  {
+    id: "jedi-language-server",
+    name: "Jedi Language Server",
+    checkCommand: "jedi-language-server",
+    checkArgs: ["--version"],
+    installStrategy: "pip",
+    packageName: "jedi-language-server",
+    binaryName: "jedi-language-server"
+  },
+  {
+    id: "biome",
+    name: "Biome",
+    checkCommand: "biome",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "@biomejs/biome",
+    binaryName: "biome",
+    platformPackage: {
+      base: "@biomejs/cli",
+      suffixes: {
+        "linux-x64": "linux-x64",
+        "linux-arm64": "linux-arm64",
+        "darwin-x64": "darwin-x64",
+        "darwin-arm64": "darwin-arm64",
+        "win32-x64": "win32-x64",
+        "win32-arm64": "win32-arm64"
+      },
+      binaries: ["biome"]
+    }
+  },
+  {
+    id: "madge",
+    name: "Madge",
+    checkCommand: "madge",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "madge",
+    binaryName: "madge"
+  },
+  {
+    id: "jscpd",
+    name: "jscpd",
+    checkCommand: "jscpd",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "jscpd@5.0.12",
+    binaryName: "jscpd"
+  },
+  {
+    id: "ast-grep",
+    name: "ast-grep CLI",
+    checkCommand: "ast-grep",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "@ast-grep/cli",
+    binaryName: "ast-grep",
+    platformPackage: {
+      suffixes: {
+        "linux-x64": "linux-x64-gnu",
+        "linux-arm64": "linux-arm64-gnu",
+        "darwin-x64": "darwin-x64",
+        "darwin-arm64": "darwin-arm64",
+        "win32-x64": "win32-x64-msvc",
+        "win32-arm64": "win32-arm64-msvc",
+        "win32-ia32": "win32-ia32-msvc"
+      },
+      binaries: ["ast-grep", "sg"]
+    }
+  },
+  {
+    id: "knip",
+    name: "Knip",
+    checkCommand: "knip",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "knip",
+    binaryName: "knip"
+  },
+  {
+    id: "yamllint",
+    name: "yamllint",
+    checkCommand: "yamllint",
+    checkArgs: ["--version"],
+    installStrategy: "pip",
+    packageName: "yamllint",
+    binaryName: "yamllint"
+  },
+  {
+    id: "sqlfluff",
+    name: "sqlfluff",
+    checkCommand: "sqlfluff",
+    checkArgs: ["--version"],
+    installStrategy: "pip",
+    packageName: "sqlfluff",
+    binaryName: "sqlfluff"
+  },
+  {
+    id: "bash-language-server",
+    name: "Bash Language Server",
+    checkCommand: "bash-language-server",
+    checkArgs: ["--version"],
+    verificationTimeoutMs: 20000,
+    installStrategy: "npm",
+    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",
+    checkCommand: "yaml-language-server",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "yaml-language-server",
+    binaryName: "yaml-language-server"
+  },
+  {
+    id: "vscode-json-language-server",
+    name: "VSCode JSON Language Server",
+    checkCommand: "vscode-json-language-server",
+    checkArgs: ["--version"],
+    verificationTimeoutMs: 20000,
+    installStrategy: "npm",
+    packageName: "vscode-langservers-extracted",
+    binaryName: "vscode-json-language-server"
+  },
+  {
+    id: "vscode-html-languageserver-bin",
+    name: "VSCode HTML Language Server",
+    checkCommand: "vscode-html-language-server",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "vscode-html-languageserver-bin",
+    binaryName: "vscode-html-language-server"
+  },
+  {
+    id: "htmlhint",
+    name: "HTMLHint",
+    checkCommand: "htmlhint",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "htmlhint",
+    binaryName: "htmlhint"
+  },
+  {
+    id: "hadolint",
+    name: "Hadolint",
+    checkCommand: "hadolint",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "hadolint",
+    github: {
+      repo: "hadolint/hadolint",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "linux.aarch64" : "linux.x86_64";
+        if (platform === "darwin")
+          return arch === "arm64" ? "macos-arm64" : "macos-x86_64";
+        if (platform === "win32")
+          return "windows-x86_64.exe";
+        return;
+      }
+    }
+  },
+  {
+    id: "helm",
+    name: "Helm",
+    checkCommand: "helm",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "helm",
+    github: {
+      repo: "helm/helm",
+      assetMatch: (platform, arch) => {
+        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;
+      },
+      binaryInArchive: "helm"
+    }
+  },
+  {
+    id: "opengrep",
+    name: "Opengrep",
+    checkCommand: "opengrep",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "opengrep",
+    github: {
+      repo: "opengrep/opengrep",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "opengrep_manylinux_aarch64" : "opengrep_manylinux_x86";
+        if (platform === "darwin")
+          return arch === "arm64" ? "opengrep_osx_arm64" : "opengrep_osx_x86";
+        if (platform === "win32")
+          return "opengrep_windows_x86.exe";
+        return;
+      }
+    }
+  },
+  {
+    id: "vscode-css-languageserver",
+    name: "VSCode CSS Language Server",
+    checkCommand: "vscode-css-language-server",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "vscode-css-languageserver",
+    binaryName: "vscode-css-language-server"
+  },
+  {
+    id: "dockerfile-language-server-nodejs",
+    name: "Dockerfile Language Server",
+    checkCommand: "docker-langserver",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "dockerfile-language-server-nodejs",
+    binaryName: "docker-langserver"
+  },
+  {
+    id: "intelephense",
+    name: "Intelephense",
+    checkCommand: "intelephense",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "intelephense",
+    binaryName: "intelephense"
+  },
+  {
+    id: "@prisma/language-server",
+    name: "Prisma Language Server",
+    checkCommand: "prisma-language-server",
+    checkArgs: ["--version"],
+    verificationTimeoutMs: 40000,
+    installStrategy: "npm",
+    packageName: "@prisma/language-server",
+    binaryName: "prisma-language-server"
+  },
+  {
+    id: "@vue/language-server",
+    name: "Vue Language Server",
+    checkCommand: "vue-language-server",
+    checkArgs: ["--version"],
+    verificationTimeoutMs: 30000,
+    installStrategy: "npm",
+    packageName: "@vue/language-server",
+    binaryName: "vue-language-server"
+  },
+  {
+    id: "svelte-language-server",
+    name: "Svelte Language Server",
+    checkCommand: "svelteserver",
+    checkArgs: ["--version"],
+    verificationTimeoutMs: 20000,
+    installStrategy: "npm",
+    packageName: "svelte-language-server",
+    binaryName: "svelteserver"
+  },
+  {
+    id: "markdownlint",
+    name: "markdownlint-cli2",
+    checkCommand: "markdownlint-cli2",
+    checkArgs: ["--no-globs", "-"],
+    installStrategy: "npm",
+    packageName: "markdownlint-cli2",
+    binaryName: "markdownlint-cli2"
+  },
+  {
+    id: "mypy",
+    name: "mypy",
+    checkCommand: "mypy",
+    checkArgs: ["--version"],
+    installStrategy: "pip",
+    packageName: "mypy",
+    binaryName: "mypy"
+  },
+  {
+    id: "rubocop",
+    name: "RuboCop",
+    checkCommand: "rubocop",
+    checkArgs: ["--version"],
+    installStrategy: "gem",
+    packageName: "rubocop",
+    binaryName: "rubocop"
+  },
+  {
+    id: "stylelint",
+    name: "Stylelint",
+    checkCommand: "stylelint",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "stylelint",
+    binaryName: "stylelint"
+  },
+  {
+    id: "oxlint",
+    name: "Oxlint",
+    checkCommand: "oxlint",
+    checkArgs: ["--version"],
+    installStrategy: "npm",
+    packageName: "oxlint",
+    binaryName: "oxlint"
+  },
+  {
+    id: "shellcheck",
+    name: "ShellCheck",
+    checkCommand: "shellcheck",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "shellcheck",
+    github: {
+      repo: "koalaman/shellcheck",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "linux.aarch64.tar.xz" : "linux.x86_64.tar.xz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "darwin.aarch64.tar.xz" : "darwin.x86_64.tar.xz";
+        if (platform === "win32")
+          return "zip";
+        return;
+      },
+      binaryInArchive: "shellcheck"
+    }
+  },
+  {
+    id: "shfmt",
+    name: "shfmt",
+    checkCommand: "shfmt",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "shfmt",
+    github: {
+      repo: "mvdan/sh",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "linux_arm64" : "linux_amd64";
+        if (platform === "darwin")
+          return arch === "arm64" ? "darwin_arm64" : "darwin_amd64";
+        if (platform === "win32")
+          return arch === "arm64" ? "windows_arm64.exe" : "windows_amd64.exe";
+        return;
+      }
+    }
+  },
+  {
+    id: "rust-analyzer",
+    name: "rust-analyzer",
+    checkCommand: "rust-analyzer",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "rust-analyzer",
+    github: {
+      repo: "rust-lang/rust-analyzer",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "aarch64-unknown-linux-gnu.gz" : "x86_64-unknown-linux-gnu.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "aarch64-apple-darwin.gz" : "x86_64-apple-darwin.gz";
+        if (platform === "win32")
+          return "x86_64-pc-windows-msvc.zip";
+        return;
+      }
+    }
+  },
+  {
+    id: "deno",
+    name: "Deno",
+    checkCommand: "deno",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "deno",
+    github: {
+      repo: "denoland/deno",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "deno-aarch64-unknown-linux-gnu.zip" : "deno-x86_64-unknown-linux-gnu.zip";
+        if (platform === "darwin")
+          return arch === "arm64" ? "deno-aarch64-apple-darwin.zip" : "deno-x86_64-apple-darwin.zip";
+        if (platform === "win32")
+          return "deno-x86_64-pc-windows-msvc.zip";
+        return;
+      }
+    }
+  },
+  {
+    id: "golangci-lint",
+    name: "golangci-lint",
+    checkCommand: "golangci-lint",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "golangci-lint",
+    github: {
+      repo: "golangci/golangci-lint",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "linux-arm64.tar.gz" : "linux-amd64.tar.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "darwin-arm64.tar.gz" : "darwin-amd64.tar.gz";
+        if (platform === "win32")
+          return arch === "arm64" ? "windows-arm64.zip" : "windows-amd64.zip";
+        return;
+      },
+      binaryInArchive: "golangci-lint"
+    }
+  },
+  {
+    id: "ktlint",
+    name: "ktlint",
+    checkCommand: "ktlint",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "ktlint",
+    github: {
+      repo: "pinterest/ktlint",
+      assetMatch: (platform, _arch) => {
+        if (platform === "linux")
+          return "ktlint";
+        if (platform === "darwin")
+          return "ktlint";
+        if (platform === "win32")
+          return "ktlint.bat";
+        return;
+      },
+      extraAssets: (platform) => platform === "win32" ? ["ktlint"] : []
+    }
+  },
+  {
+    id: "ktfmt",
+    name: "ktfmt",
+    checkCommand: "ktfmt",
+    checkArgs: ["--version"],
+    installStrategy: "maven",
+    binaryName: "ktfmt",
+    maven: {
+      groupId: "com.facebook",
+      artifactId: "ktfmt",
+      version: "0.63",
+      classifier: "with-dependencies"
+    }
+  },
+  {
+    id: "spotbugs",
+    name: "SpotBugs",
+    checkCommand: "spotbugs",
+    checkArgs: ["--version"],
+    installStrategy: "archive",
+    binaryName: "spotbugs",
+    archive: {
+      url: "https://github.com/spotbugs/spotbugs/releases/download/4.10.2/spotbugs-4.10.2.tgz",
+      kind: "tgz",
+      launcher: "bin/spotbugs"
+    }
+  },
+  {
+    id: "powershell-editor-services",
+    name: "PowerShell Editor Services",
+    checkCommand: "pwsh",
+    checkArgs: [
+      "-NoProfile",
+      "-Command",
+      "$PSVersionTable.PSVersion.ToString()"
+    ],
+    installStrategy: "archive",
+    binaryName: "powershell-editor-services",
+    archive: {
+      url: "https://github.com/PowerShell/PowerShellEditorServices/releases/download/v4.6.0/PowerShellEditorServices.zip",
+      kind: "zip",
+      stripComponents: 0,
+      treeMarker: "PowerShellEditorServices/Start-EditorServices.ps1"
+    }
+  },
+  {
+    id: "clangd",
+    name: "clangd",
+    checkCommand: "clangd",
+    checkArgs: ["--version"],
+    installStrategy: "archive",
+    binaryName: "clangd",
+    archive: {
+      url: (platform, arch) => {
+        const version = "22.1.0";
+        const base = `https://github.com/clangd/clangd/releases/download/${version}`;
+        if (platform === "linux")
+          return arch === "x64" ? `${base}/clangd-linux-${version}.zip` : undefined;
+        if (platform === "darwin")
+          return `${base}/clangd-mac-${version}.zip`;
+        if (platform === "win32")
+          return `${base}/clangd-windows-${version}.zip`;
+        return;
+      },
+      kind: "zip",
+      stripComponents: 1,
+      treeMarker: "bin"
+    }
+  },
+  {
+    id: "lua-language-server",
+    name: "lua-language-server",
+    checkCommand: "lua-language-server",
+    checkArgs: ["--version"],
+    installStrategy: "archive",
+    binaryName: "lua-language-server",
+    archive: {
+      url: (platform, arch) => {
+        const version = "3.18.2";
+        const base = `https://github.com/LuaLS/lua-language-server/releases/download/${version}`;
+        if (platform === "linux")
+          return arch === "arm64" ? `${base}/lua-language-server-${version}-linux-arm64.tar.gz` : `${base}/lua-language-server-${version}-linux-x64.tar.gz`;
+        if (platform === "darwin")
+          return arch === "arm64" ? `${base}/lua-language-server-${version}-darwin-arm64.tar.gz` : `${base}/lua-language-server-${version}-darwin-x64.tar.gz`;
+        if (platform === "win32")
+          return arch === "arm64" ? undefined : `${base}/lua-language-server-${version}-win32-x64.zip`;
+        return;
+      },
+      kind: "zip",
+      stripComponents: 0,
+      treeMarker: "bin"
+    }
+  },
+  {
+    id: "actionlint",
+    name: "actionlint",
+    checkCommand: "actionlint",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "actionlint",
+    github: {
+      repo: "rhysd/actionlint",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "linux_arm64.tar.gz" : "linux_amd64.tar.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "darwin_arm64.tar.gz" : "darwin_amd64.tar.gz";
+        if (platform === "win32")
+          return arch === "arm64" ? "windows_arm64.zip" : "windows_amd64.zip";
+        return;
+      },
+      binaryInArchive: "actionlint"
+    }
+  },
+  {
+    id: "zizmor",
+    name: "zizmor",
+    checkCommand: "zizmor",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "zizmor",
+    github: {
+      repo: "zizmorcore/zizmor",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "aarch64-unknown-linux-gnu.tar.gz" : "x86_64-unknown-linux-gnu.tar.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "aarch64-apple-darwin.tar.gz" : "x86_64-apple-darwin.tar.gz";
+        if (platform === "win32")
+          return "x86_64-pc-windows-msvc.zip";
+        return;
+      },
+      binaryInArchive: "zizmor"
+    }
+  },
+  {
+    id: "typos-lsp",
+    name: "typos-lsp",
+    checkCommand: "typos-lsp",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "typos-lsp",
+    github: {
+      repo: "tekumara/typos-lsp",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "aarch64-unknown-linux-gnu.tar.gz" : "x86_64-unknown-linux-gnu.tar.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "aarch64-apple-darwin.tar.gz" : "x86_64-apple-darwin.tar.gz";
+        if (platform === "win32")
+          return arch === "arm64" ? "aarch64-pc-windows-msvc.zip" : "x86_64-pc-windows-msvc.zip";
+        return;
+      },
+      binaryInArchive: "typos-lsp"
+    }
+  },
+  {
+    id: "tflint",
+    name: "tflint",
+    checkCommand: "tflint",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "tflint",
+    github: {
+      repo: "terraform-linters/tflint",
+      assetMatch: archAssetMatch(OS_ARCH_ZIP_ASSETS),
+      binaryInArchive: "tflint"
+    }
+  },
+  {
+    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"
+        }
+      })
+    }
+  },
+  {
+    id: "gitleaks",
+    name: "gitleaks",
+    checkCommand: "gitleaks",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "gitleaks",
+    github: {
+      repo: "gitleaks/gitleaks",
+      assetMatch: archAssetMatch({
+        linux: { x64: "linux_x64.tar.gz", arm64: "linux_arm64.tar.gz" },
+        darwin: { x64: "darwin_x64.tar.gz", arm64: "darwin_arm64.tar.gz" },
+        win32: { x64: "windows_x64.zip", arm64: "windows_arm64.zip" }
+      }),
+      binaryInArchive: "gitleaks"
+    }
+  },
+  {
+    id: "trivy",
+    name: "Trivy",
+    checkCommand: "trivy",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "trivy",
+    github: {
+      repo: "aquasecurity/trivy",
+      assetMatch: archAssetMatch({
+        linux: { x64: "Linux-64bit.tar.gz", arm64: "Linux-ARM64.tar.gz" },
+        darwin: { x64: "macOS-64bit.tar.gz", arm64: "macOS-ARM64.tar.gz" },
+        win32: { x64: "windows-64bit.zip" }
+      }),
+      binaryInArchive: "trivy"
+    }
+  },
+  {
+    id: "swiftlint",
+    name: "SwiftLint",
+    checkCommand: "swiftlint",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "swiftlint",
+    github: {
+      repo: "realm/SwiftLint",
+      assetMatch: (platform, arch) => {
+        if (platform === "darwin")
+          return "portable_swiftlint.zip";
+        if (platform === "linux")
+          return arch === "arm64" ? "swiftlint_linux_arm64.zip" : "swiftlint_linux_amd64.zip";
+        return;
+      },
+      binaryInArchive: "swiftlint"
+    }
+  },
+  {
+    id: "taplo",
+    name: "taplo",
+    checkCommand: "taplo",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "taplo",
+    github: {
+      repo: "tamasfe/taplo",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "taplo-linux-aarch64.gz" : "taplo-linux-x86_64.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "taplo-darwin-aarch64.gz" : "taplo-darwin-x86_64.gz";
+        if (platform === "win32")
+          return "taplo-windows-x86_64.gz";
+        return;
+      }
+    }
+  },
+  {
+    id: "vale",
+    name: "Vale",
+    checkCommand: "vale",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "vale",
+    github: {
+      repo: "vale-cli/vale",
+      assetMatch: (platform, arch) => {
+        const version = "3.14.2";
+        if (platform === "linux")
+          return arch === "arm64" ? `vale_${version}_Linux_arm64.tar.gz` : `vale_${version}_Linux_64-bit.tar.gz`;
+        if (platform === "darwin")
+          return arch === "arm64" ? `vale_${version}_macOS_arm64.tar.gz` : `vale_${version}_macOS_64-bit.tar.gz`;
+        if (platform === "win32")
+          return `vale_${version}_Windows_64-bit.zip`;
+        return;
+      },
+      binaryInArchive: "vale"
+    }
+  },
+  {
+    id: "terraform-ls",
+    name: "terraform-ls",
+    checkCommand: "terraform-ls",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "terraform-ls",
+    github: {
+      repo: "hashicorp/terraform-ls",
+      hashiCorpReleaseProduct: "terraform-ls",
+      assetMatch: archAssetMatch(OS_ARCH_ZIP_ASSETS),
+      binaryInArchive: "terraform-ls"
+    }
+  },
+  {
+    id: "zls",
+    name: "zls",
+    checkCommand: "zls",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "zls",
+    github: {
+      repo: "zigtools/zls",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "aarch64-linux.tar.xz" : "x86_64-linux.tar.xz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "aarch64-macos.tar.xz" : "x86_64-macos.tar.xz";
+        if (platform === "win32")
+          return arch === "arm64" ? "aarch64-windows.zip" : "x86_64-windows.zip";
+        return;
+      },
+      binaryInArchive: "zls"
+    }
+  },
+  {
+    id: "clojure-lsp",
+    name: "clojure-lsp",
+    checkCommand: "clojure-lsp",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "clojure-lsp",
+    github: {
+      repo: "clojure-lsp/clojure-lsp",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "native-linux-aarch64.zip" : "native-linux-amd64.zip";
+        if (platform === "darwin")
+          return arch === "arm64" ? "native-macos-aarch64.zip" : "native-macos-amd64.zip";
+        if (platform === "win32")
+          return "native-windows-amd64.zip";
+        return;
+      },
+      binaryInArchive: "clojure-lsp"
+    }
+  },
+  {
+    id: "cue",
+    name: "CUE",
+    checkCommand: "cue",
+    checkArgs: ["version"],
+    installStrategy: "github",
+    binaryName: "cue",
+    github: {
+      repo: "cue-lang/cue",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "linux_arm64.tar.gz" : "linux_amd64.tar.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "darwin_arm64.tar.gz" : "darwin_amd64.tar.gz";
+        if (platform === "win32")
+          return arch === "arm64" ? "windows_arm64.zip" : "windows_amd64.zip";
+        return;
+      },
+      binaryInArchive: "cue"
+    }
+  },
+  {
+    id: "gleam",
+    name: "Gleam",
+    checkCommand: "gleam",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "gleam",
+    github: {
+      repo: "gleam-lang/gleam",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "aarch64-unknown-linux-musl.tar.gz" : "x86_64-unknown-linux-musl.tar.gz";
+        if (platform === "darwin")
+          return arch === "arm64" ? "aarch64-apple-darwin.tar.gz" : "x86_64-apple-darwin.tar.gz";
+        if (platform === "win32")
+          return arch === "arm64" ? "aarch64-pc-windows-msvc.zip" : "x86_64-pc-windows-msvc.zip";
+        return;
+      },
+      binaryInArchive: "gleam"
+    }
+  },
+  {
+    id: "marksman",
+    name: "Marksman",
+    checkCommand: "marksman",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "marksman",
+    github: {
+      repo: "artempyanykh/marksman",
+      assetMatch: (platform, arch) => {
+        if (platform === "linux")
+          return arch === "arm64" ? "marksman-linux-arm64" : "marksman-linux-x64";
+        if (platform === "darwin")
+          return "marksman-macos";
+        if (platform === "win32")
+          return "marksman.exe";
+        return;
+      }
+    }
+  },
+  {
+    id: "expert",
+    name: "Expert",
+    checkCommand: "expert",
+    checkArgs: ["--version"],
+    installStrategy: "github",
+    binaryName: "expert",
+    github: {
+      repo: "expert-lsp/expert",
+      assetMatch: (platform, arch) => {
+        if (arch !== "x64" && arch !== "arm64")
+          return;
+        if (platform === "linux")
+          return arch === "arm64" ? "expert_linux_arm64" : "expert_linux_amd64";
+        if (platform === "darwin")
+          return arch === "arm64" ? "expert_darwin_arm64" : "expert_darwin_amd64";
+        if (platform === "win32")
+          return "expert_windows_amd64.exe";
+        return;
+      }
+    }
+  }
+];
+export function getToolVerificationTimeout(tool) {
+  return tool.verificationTimeoutMs ?? 1e4;
+}
+const ensureInFlight = new Map;
+const installFailureReasons = new Map;
+export function getInstallFailureReason(toolId) {
+  return installFailureReasons.get(toolId);
+}
+const installAttempts = new Map;
+function noteInstallAttempt(toolId, outcome, reason) {
+  installAttempts.set(toolId, { outcome, reason, at: Date.now() });
+}
+function noteInstallAttemptIfUnrecorded(toolId, outcome, reason) {
+  if (installAttempts.has(toolId))
+    return;
+  noteInstallAttempt(toolId, outcome, reason);
+}
+export function getInstallAttempt(toolId) {
+  return installAttempts.get(toolId);
+}
+const lastEnsureResolutionSource = new Map;
+export function getLastEnsureResolutionSource(toolId) {
+  return lastEnsureResolutionSource.get(toolId);
+}
+const resolvedPathCache = new BoundedLruCache(256);
+export function resetResolvedPathCache() {
+  resolvedPathCache.clear();
+}
+const PROBE_CACHE_PATH = path.join(getGlobalDmLensDir(), "probe-cache.json");
+const PROBE_CACHE_LOCK_STALE_MS = 180000;
+const PROBE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const PROBE_CACHE_TRANSIENT_COOLDOWN_MS = TRANSIENT_MAX_COOLDOWN_MS;
+const PROBE_CACHE_FLUSH_LOCK_WAIT_MS = 250;
+const PROBE_CACHE_FLUSH_RETRY_DELAY_MS = 300;
+const PROBE_CACHE_FLUSH_RETRY_MAX_DELAY_MS = 30000;
+let _probeCache = null;
+let _probeCacheDirty = false;
+let _probeCacheFlushTimer = null;
+let _probeCacheWriteInFlight = null;
+let _probeCacheRetryAttempt = 0;
+let _probeCacheChangeGeneration = 0;
+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");
+    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 (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 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(() => {
+    flushProbeCache();
+  }, delayMs);
+  _probeCacheFlushTimer.unref?.();
+}
+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 {};
+  try {
+    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;
+  } catch (err) {
+    logSessionStart(`auto-install probe-cache: write-side read was corrupt (${err.message}); recovering as empty`);
+    return {};
+  }
+}
+function applyProbeCacheChanges(disk, changes) {
+  for (const [toolId, entry] of changes) {
+    if (entry === null)
+      delete disk[toolId];
+    else
+      disk[toolId] = entry;
+  }
+}
+function ageProbeCache(disk) {
+  const now = Date.now();
+  for (const [toolId, entry] of Object.entries(disk)) {
+    const ttl = entry.transient ? PROBE_CACHE_TRANSIENT_COOLDOWN_MS : PROBE_CACHE_TTL_MS;
+    if (!Number.isFinite(entry.cachedAt) || entry.cachedAt < now - ttl) {
+      delete disk[toolId];
+    }
+  }
+}
+function publishProbeCacheWrite(disk, snapshotVersions) {
+  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 {
+    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) {
+    logSessionStart(`auto-install probe-cache: flush failed (${err?.code ?? "write error"}); pending update retained`);
+    scheduleProbeFlushRetry();
+    return "failed";
+  }
+}
+export async function flushProbeCache() {
+  if (_probeCacheFlushTimer !== null) {
+    clearTimeout(_probeCacheFlushTimer);
+    _probeCacheFlushTimer = null;
+  }
+  if (_probeCacheWriteInFlight) {
+    await _probeCacheWriteInFlight;
+    if (!_probeCacheDirty)
+      return "written";
+  }
+  if (!_probeCacheDirty || _probeCache === null)
+    return "idle";
+  const write = writeProbeCache();
+  _probeCacheWriteInFlight = write;
+  try {
+    return 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) => {
+    let proc;
+    try {
+      proc = spawn(binPath, ["--version"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(binPath),
+        timeout: 5000
+      });
+    } catch {
+      resolve(false);
+      return;
+    }
+    let output = "";
+    proc.stdout?.on("data", (data) => output += data);
+    proc.stderr?.on("data", (data) => output += data);
+    proc.on("exit", (code) => {
+      resolve(code === 0 && isAstGrepVersionOutput(output));
+    });
+    proc.on("error", () => resolve(false));
+  });
+}
+export async function checkProbeCache(toolId) {
+  const cache = await readProbeCache();
+  const entry = cache[toolId];
+  if (!entry)
+    return;
+  const ttl = entry.transient ? PROBE_CACHE_TRANSIENT_COOLDOWN_MS : PROBE_CACHE_TTL_MS;
+  if (Date.now() - entry.cachedAt > ttl) {
+    logSessionStart(`auto-install probe-cache ${toolId}: miss (${entry.transient ? "transient cooldown" : "ttl"} expired)`);
+    delete cache[toolId];
+    markProbeCacheChange(toolId, null);
+    return;
+  }
+  try {
+    await fs.access(entry.path);
+    const stat = await fs.stat(entry.path);
+    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;
+    }
+    if (toolId === "ast-grep" && !await verifyAstGrepProbePath(entry.path)) {
+      logSessionStart(`auto-install probe-cache ${toolId}: miss (not ast-grep: ${entry.path})`);
+      delete cache[toolId];
+      markProbeCacheChange(toolId, null);
+      return;
+    }
+    return entry.path;
+  } catch {
+    logSessionStart(`auto-install probe-cache ${toolId}: miss (gone: ${entry.path})`);
+    delete cache[toolId];
+    markProbeCacheChange(toolId, null);
+    return;
+  }
+}
+export async function updateProbeCache(toolId, resolvedPath, transient = false) {
+  try {
+    const stat = await fs.stat(resolvedPath);
+    const cache = await readProbeCache();
+    const entry = {
+      path: resolvedPath,
+      mtimeMs: stat.mtimeMs,
+      sizeBytes: stat.size,
+      cachedAt: Date.now(),
+      ...transient && { transient: true }
+    };
+    cache[toolId] = entry;
+    markProbeCacheChange(toolId, entry);
+  } catch {}
+}
+export function resetProbeCacheStateForTesting() {
+  _probeCache = null;
+  _probeCacheDirty = false;
+  _probeCacheChanges.clear();
+  _probeCacheChangeVersions.clear();
+  _probeCacheChangeGeneration = 0;
+  _probeCacheRetryAttempt = 0;
+  resetResolvedPathCache();
+  ensureInFlight.clear();
+  installFailureReasons.clear();
+  installAttempts.clear();
+  lastEnsureResolutionSource.clear();
+  lastManagedInstallVersion.clear();
+  lastResolveTransient.clear();
+  resetPathWalkMemo();
+  if (_probeCacheFlushTimer !== null) {
+    clearTimeout(_probeCacheFlushTimer);
+    _probeCacheFlushTimer = null;
+  }
+}
+export function _peekEnsureInFlightForTesting() {
+  return ensureInFlight;
+}
+const pathWalkMemo = new Map;
+function hashSync(value) {
+  let hash = 2166136261;
+  for (let i = 0;i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16);
+}
+export function resetPathWalkMemo() {
+  pathWalkMemo.clear();
+}
+export async function isCommandAvailable(command, _args) {
+  const isWindows = installerPlatform() === "win32";
+  const pathEnv = process.env.PATH || process.env.Path || process.env.path || "";
+  const dirs = pathEnv.split(path.delimiter);
+  const names = isWindows ? [command, `${command}.exe`, `${command}.cmd`, `${command}.bat`] : [command];
+  for (const dir of dirs) {
+    if (!dir)
+      continue;
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      try {
+        const stat = statSync(candidate);
+        if (stat.isFile() && stat.size > 0) {
+          return true;
+        }
+      } catch {}
+    }
+  }
+  return false;
+}
+export async function isSpawnableCommand(command) {
+  if (/[\\/]/.test(command)) {
+    try {
+      const stat = statSync(command);
+      return stat.isFile() && stat.size > 0;
+    } catch {
+      return false;
+    }
+  }
+  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;
+}
+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;
+function parsePinnedVersion(packageName) {
+  const at = packageName.lastIndexOf("@");
+  if (at <= 0)
+    return;
+  return packageName.slice(at + 1) || undefined;
+}
+function extractVersionToken(output) {
+  return output.match(/\d+\.\d+\.\d+(?:[-+][\w.]+)?/)?.[0];
+}
+const lastManagedInstallVersion = new Map;
+export async function verifyToolBinary(binPath, onVersionOutput, onTransient, timeoutMs = 1e4, verificationArgs = ["--version"]) {
+  const isWindows = installerPlatform() === "win32";
+  const hasKnownWindowsExt = /\.(cmd|exe|ps1)$/i.test(binPath);
+  let execPath = isWindows && !hasKnownWindowsExt ? `${binPath}.cmd` : binPath;
+  if (isWindows && /\.ps1$/i.test(execPath)) {
+    const cmdSibling = `${execPath.slice(0, -4)}.cmd`;
+    if (require("node:fs").existsSync(cmdSibling)) {
+      execPath = cmdSibling;
+    }
+  }
+  const useShell = isWindows && /\.(cmd|bat)$/i.test(execPath);
+  try {
+    const result = await safeSpawnAsync(execPath, verificationArgs, {
+      timeout: timeoutMs,
+      input: "",
+      maxOutputBytes: 64 * 1024,
+      matchWhileStreaming: lspTransportRequiredMatcher
+    });
+    const output = `${result.stdout}
+${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} (${verificationArgs.join(" ")}: ${result.stdout.trim()})`);
+      onVersionOutput?.(result.stdout);
+      return true;
+    }
+    if (result.streamingMatch || isLspTransportRequiredError(output)) {
+      debugLog(`Verified (stdio LSP, transport-required): ${binPath}`);
+      return true;
+    }
+    if (result.signal !== undefined || result.spawnFailure)
+      onTransient?.();
+    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) {
+    logSessionStart(`auto-install verify: spawn threw for ${binPath} (${err instanceof Error ? err.message : String(err)})`);
+    onTransient?.();
+    return false;
+  }
+}
+export async function getAllToolStatuses() {
+  const statuses = [];
+  for (const tool of TOOLS) {
+    const status = {
+      id: tool.id,
+      name: tool.name,
+      installed: false,
+      source: "not-installed",
+      strategy: tool.installStrategy
+    };
+    if (tool.installStrategy === "archive" && !tool.archive?.launcher) {
+      const bundleDir = await getArchiveTreeBundlePath(tool);
+      if (bundleDir) {
+        status.installed = true;
+        status.source = "archive-dist";
+        status.path = bundleDir;
+      }
+      statuses.push(status);
+      continue;
+    }
+    if (await isCommandAvailable(tool.checkCommand, tool.checkArgs)) {
+      status.installed = true;
+      status.source = "global-path";
+      status.path = tool.checkCommand;
+      const versionResult = await new Promise((resolve) => {
+        let proc;
+        try {
+          proc = spawn(tool.checkCommand, ["--version"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: process.platform === "win32",
+            timeout: 5000
+          });
+        } catch {
+          resolve("");
+          return;
+        }
+        let out = "";
+        proc.stdout?.on("data", (d) => out += d);
+        proc.stderr?.on("data", (d) => out += d);
+        proc.on("exit", () => resolve(out.trim().split(`
+`)[0]?.slice(0, 30) || ""));
+        proc.on("error", () => resolve(""));
+      });
+      status.version = versionResult || undefined;
+      statuses.push(status);
+      continue;
+    }
+    if (tool.installStrategy === "npm") {
+      const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, undefined, tool.checkArgs, getToolVerificationTimeout(tool));
+      if (npmPath) {
+        status.installed = true;
+        status.source = "npm-global";
+        status.path = npmPath;
+        statuses.push(status);
+        continue;
+      }
+    }
+    if (tool.installStrategy === "pip") {
+      const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, undefined, tool.checkArgs, getToolVerificationTimeout(tool));
+      if (pipPath) {
+        status.installed = true;
+        status.source = "pip-user";
+        status.path = pipPath;
+        statuses.push(status);
+        continue;
+      }
+    }
+    if (tool.installStrategy === "github" || tool.installStrategy === "maven" || tool.installStrategy === "archive") {
+      const githubPath = await findGitHubToolPath(tool.binaryName || tool.id);
+      if (githubPath) {
+        status.installed = true;
+        status.source = tool.installStrategy === "maven" ? "maven-jar" : tool.installStrategy === "archive" ? "archive-dist" : "github-release";
+        status.path = githubPath;
+        statuses.push(status);
+        continue;
+      }
+    }
+    const localBase = path.join(TOOLS_DIR, "node_modules", ".bin", tool.binaryName || tool.id);
+    const localPath = installerPlatform() === "win32" ? `${localBase}.cmd` : localBase;
+    try {
+      await fs.access(localPath);
+      if (await verifyToolBinary(localPath, undefined, undefined, getToolVerificationTimeout(tool), tool.checkArgs)) {
+        status.installed = true;
+        status.source = "dm-lens-auto";
+        status.path = localPath;
+        statuses.push(status);
+        continue;
+      }
+    } catch {}
+    if (tool.installStrategy === "npm") {
+      status.source = "npx-fallback";
+    }
+    statuses.push(status);
+  }
+  return statuses;
+}
+export async function isToolInstalled(toolId) {
+  return await getToolPath(toolId) !== undefined;
+}
+async function getArchiveTreeBundlePath(tool) {
+  if (tool.installStrategy !== "archive" || tool.archive?.launcher) {
+    return;
+  }
+  const extractDir = path.join(TOOLS_DIR, tool.id);
+  const marker = tool.archive?.treeMarker ? path.join(extractDir, ...tool.archive.treeMarker.split("/")) : extractDir;
+  try {
+    await fs.access(marker);
+    return extractDir;
+  } catch {
+    return;
+  }
+}
+export function resolvePlatformPackageBinary(tool) {
+  const spec = tool.platformPackage;
+  if (!spec || !tool.packageName)
+    return;
+  const suffix = spec.suffixes[`${installerPlatform()}-${process.arch}`];
+  if (!suffix)
+    return;
+  const platformPkg = `${spec.base ?? tool.packageName}-${suffix}`;
+  try {
+    const mainPkgJson = _installerRequire.resolve(`${tool.packageName}/package.json`);
+    const fromMain = createRequire(mainPkgJson);
+    let pkgDir;
+    try {
+      pkgDir = path.dirname(fromMain.resolve(`${platformPkg}/package.json`));
+    } catch {
+      pkgDir = path.dirname(_installerRequire.resolve(`${platformPkg}/package.json`));
+    }
+    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);
+        if (existsSync(candidate))
+          return candidate;
+      }
+    }
+  } catch {}
+  return;
+}
+const lastResolveTransient = new Map;
+const lastInstallResolutionId = new Map;
+export function wasLastResolveTransient(toolId) {
+  return lastResolveTransient.get(toolId) ?? false;
+}
+export async function getToolPath(toolId) {
+  let sawTransient = false;
+  const markTransient = () => {
+    sawTransient = true;
+  };
+  const result = await getToolPathResolved(toolId, markTransient);
+  lastResolveTransient.set(toolId, sawTransient);
+  return result;
+}
+async function getToolPathResolved(toolId, onTransient) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (!tool)
+    return;
+  if (tool.installStrategy === "archive" && !tool.archive?.launcher) {
+    return getArchiveTreeBundlePath(tool);
+  }
+  const pinnedVersion = tool.installStrategy === "npm" && tool.packageName ? parsePinnedVersion(tool.packageName) : undefined;
+  if (pinnedVersion)
+    lastManagedInstallVersion.delete(toolId);
+  const recordVersion = pinnedVersion ? (output) => {
+    const seen = extractVersionToken(output);
+    if (seen)
+      lastManagedInstallVersion.set(toolId, seen);
+  } : undefined;
+  const localBase = path.join(TOOLS_DIR, "node_modules", ".bin", tool.binaryName || tool.id);
+  if (installerPlatform() === "win32") {
+    const cmdPath = `${localBase}.cmd`;
+    try {
+      await fs.access(cmdPath);
+      if (await verifyToolBinary(cmdPath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
+        return cmdPath;
+      }
+      logSessionStart(`auto-install verify: ${cmdPath} exists but is broken, will reinstall`);
+    } catch {}
+    const exePath = `${localBase}.exe`;
+    try {
+      await fs.access(exePath);
+      if (await verifyToolBinary(exePath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
+        return exePath;
+      }
+      logSessionStart(`auto-install verify: ${exePath} exists but is broken, will reinstall`);
+    } catch {}
+  }
+  if (installerPlatform() !== "win32") {
+    try {
+      await fs.access(localBase);
+      if (await verifyToolBinary(localBase, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
+        return localBase;
+      }
+      logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
+    } catch {}
+  }
+  if (tool.platformPackage) {
+    const platformBin = resolvePlatformPackageBinary(tool);
+    if (platformBin && await verifyToolBinary(platformBin, undefined, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
+      logSessionStart(`auto-install ${toolId}: resolved platform-package binary at ${platformBin}`);
+      return platformBin;
+    }
+    logSessionStart(`auto-install ${toolId}: platform-package binary not resolved (${process.platform}-${process.arch}, base=${tool.platformPackage.base ?? tool.packageName}) — falling back to PATH/managed install`);
+  }
+  if (tool.installStrategy === "github" || tool.installStrategy === "maven" || tool.installStrategy === "archive") {
+    const githubPath = await findGitHubToolPath(tool.binaryName || tool.id);
+    if (githubPath)
+      return githubPath;
+  }
+  if (await isCommandAvailable(tool.checkCommand, tool.checkArgs)) {
+    return tool.checkCommand;
+  }
+  if (tool.installStrategy === "npm") {
+    const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, onTransient, tool.checkArgs, getToolVerificationTimeout(tool));
+    if (npmPath) {
+      return npmPath;
+    }
+  }
+  if (tool.installStrategy === "pip") {
+    const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, onTransient, tool.checkArgs, getToolVerificationTimeout(tool));
+    if (pipPath) {
+      return pipPath;
+    }
+  }
+  return;
+}
+async function findGitHubToolPath(binaryName) {
+  const isWindows = process.platform === "win32";
+  const candidates = isWindows ? [
+    path.join(GITHUB_BIN_DIR, `${binaryName}.exe`),
+    path.join(GITHUB_BIN_DIR, `${binaryName}.bat`),
+    path.join(GITHUB_BIN_DIR, `${binaryName}.cmd`),
+    path.join(GITHUB_BIN_DIR, binaryName)
+  ] : [path.join(GITHUB_BIN_DIR, binaryName)];
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {}
+  }
+  return;
+}
+export async function findManagedToolBinary(toolId) {
+  const tool = TOOLS.find((candidate) => candidate.id === toolId);
+  if (!tool)
+    return;
+  if (tool.installStrategy !== "github" && tool.installStrategy !== "maven" && tool.installStrategy !== "archive") {
+    return;
+  }
+  return findGitHubToolPath(tool.binaryName || tool.id);
+}
+function hasExecutableExtension(name) {
+  return /\.(exe|bat|cmd|ps1)$/i.test(name);
+}
+function getGitHubInstalledBinaryName(binaryName, platform, assetName) {
+  if (platform !== "win32")
+    return binaryName;
+  if (hasExecutableExtension(binaryName))
+    return binaryName;
+  if (assetName.endsWith(".bat"))
+    return `${binaryName}.bat`;
+  if (assetName.endsWith(".cmd"))
+    return `${binaryName}.cmd`;
+  return `${binaryName}.exe`;
+}
+function getArchiveBinaryCandidates(binaryName, platform, assetName) {
+  if (platform !== "win32")
+    return [binaryName];
+  if (hasExecutableExtension(binaryName))
+    return [binaryName];
+  const candidates = new Set;
+  if (assetName.endsWith(".bat"))
+    candidates.add(`${binaryName}.bat`);
+  if (assetName.endsWith(".cmd"))
+    candidates.add(`${binaryName}.cmd`);
+  candidates.add(`${binaryName}.exe`);
+  candidates.add(binaryName);
+  candidates.add(`${binaryName}.bat`);
+  candidates.add(`${binaryName}.cmd`);
+  return [...candidates];
+}
+async function findNpmGlobalToolPath(binaryName, onTransient, verificationArgs = ["--version"], verificationTimeoutMs = 1e4) {
+  const isWindows = process.platform === "win32";
+  const binDirs = await getNpmGlobalBinCandidates(onTransient);
+  for (const dir of binDirs) {
+    const candidates = isWindows ? [
+      path.join(dir, `${binaryName}.cmd`),
+      path.join(dir, `${binaryName}.exe`)
+    ] : [path.join(dir, binaryName)];
+    for (const candidate of candidates) {
+      try {
+        await fs.access(candidate);
+        if (await verifyToolBinary(candidate, undefined, onTransient, verificationTimeoutMs, verificationArgs)) {
+          return candidate;
+        }
+      } catch {}
+    }
+  }
+  return;
+}
+async function getNpmGlobalBinCandidates(onTransient) {
+  const dirs = [];
+  const seen = new Set;
+  const add = (value) => {
+    if (!value)
+      return;
+    const normalized = path.resolve(value.trim());
+    if (!normalized)
+      return;
+    if (seen.has(normalized))
+      return;
+    seen.add(normalized);
+    dirs.push(normalized);
+  };
+  if (process.platform === "win32") {
+    add(path.join(process.env.APPDATA || "", "npm"));
+  } else {
+    add(path.join(os.homedir(), ".npm-global", "bin"));
+  }
+  for (const dir of await allAvailableGlobalBinDirs(onTransient)) {
+    add(dir);
+  }
+  return dirs;
+}
+async function findPipUserToolPath(binaryName, onTransient, verificationArgs = ["--version"], verificationTimeoutMs = 1e4) {
+  const isWindows = process.platform === "win32";
+  const userBaseCandidates = await getPythonUserBaseCandidates();
+  for (const userBase of userBaseCandidates) {
+    const scriptDirs = [
+      path.join(userBase, isWindows ? "Scripts" : "bin")
+    ];
+    if (isWindows) {
+      try {
+        const children = await fs.readdir(userBase, { withFileTypes: true });
+        for (const entry of children) {
+          if (!entry.isDirectory())
+            continue;
+          if (!/^python\d+$/i.test(entry.name))
+            continue;
+          scriptDirs.push(path.join(userBase, entry.name, "Scripts"));
+        }
+      } catch {}
+    }
+    for (const dir of scriptDirs) {
+      const candidates = isWindows ? [
+        path.join(dir, `${binaryName}.exe`),
+        path.join(dir, `${binaryName}.cmd`),
+        path.join(dir, binaryName)
+      ] : [path.join(dir, binaryName)];
+      for (const candidate of candidates) {
+        try {
+          await fs.access(candidate);
+          if (await verifyToolBinary(candidate, undefined, onTransient, verificationTimeoutMs, verificationArgs)) {
+            return candidate;
+          }
+        } catch {}
+      }
+    }
+  }
+  return;
+}
+async function getPythonUserBaseCandidates() {
+  const candidates = [];
+  const seen = new Set;
+  const add = (value) => {
+    if (!value)
+      return;
+    const normalized = value.trim();
+    if (!normalized)
+      return;
+    if (seen.has(normalized))
+      return;
+    seen.add(normalized);
+    candidates.push(normalized);
+  };
+  if (process.platform === "win32") {
+    add(path.join(process.env.APPDATA || "", "Python"));
+  }
+  const probes = process.platform === "win32" ? [
+    { command: "py", args: ["-m", "site", "--user-base"] },
+    { command: "python", args: ["-m", "site", "--user-base"] }
+  ] : [
+    { command: "python3", args: ["-m", "site", "--user-base"] },
+    { command: "python", args: ["-m", "site", "--user-base"] }
+  ];
+  for (const probe of probes) {
+    const userBase = await new Promise((resolve) => {
+      const isWin = process.platform === "win32";
+      const spawnCmd = isWin ? [probe.command, ...probe.args].join(" ") : probe.command;
+      let proc;
+      try {
+        proc = spawn(spawnCmd, isWin ? [] : probe.args, {
+          stdio: ["ignore", "pipe", "pipe"],
+          shell: isWin
+        });
+      } catch {
+        resolve("");
+        return;
+      }
+      let stdout = "";
+      proc.stdout?.on("data", (data) => stdout += data);
+      proc.on("exit", (code) => resolve(code === 0 ? stdout.trim() : ""));
+      proc.on("error", () => resolve(""));
+    });
+    add(userBase);
+  }
+  return candidates;
+}
+function githubApiAuthHeaders() {
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+function sameHost(a, b) {
+  try {
+    return new URL(a).host === new URL(b).host;
+  } catch {
+    return false;
+  }
+}
+function httpsGetWithMeta(url, maxRedirects = 5, headers = {}) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { "User-Agent": "dm-lens/1.0", ...headers } }, (res) => {
+      if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        if (maxRedirects === 0)
+          return reject(new Error("Too many redirects"));
+        const location = res.headers.location;
+        const nextHeaders = sameHost(url, location) ? headers : (() => {
+          const { Authorization: _drop, ...rest } = headers;
+          return rest;
+        })();
+        return resolve(httpsGetWithMeta(location, maxRedirects - 1, nextHeaders));
+      }
+      const etag = typeof res.headers.etag === "string" ? res.headers.etag : undefined;
+      if (res.statusCode === 304) {
+        res.resume();
+        return resolve({ statusCode: 304, body: Buffer.alloc(0), etag });
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve({ statusCode: 200, body: Buffer.concat(chunks), etag }));
+      res.on("error", reject);
+    }).on("error", reject);
+  });
+}
+async function httpsGet(url, maxRedirects = 5, headers = {}) {
+  const response = await httpsGetWithMeta(url, maxRedirects, headers);
+  if (response.statusCode !== 200) {
+    throw new Error(`HTTP ${response.statusCode} for ${url}`);
+  }
+  return response.body;
+}
+function runCommand(command, args, cwd) {
+  return new Promise((resolve) => {
+    let proc;
+    try {
+      proc = spawn(command, args, {
+        cwd,
+        stdio: "ignore",
+        shell: process.platform === "win32"
+      });
+    } catch {
+      resolve(false);
+      return;
+    }
+    proc.on("exit", (code) => resolve(code === 0));
+    proc.on("error", () => resolve(false));
+  });
+}
+async function installGitHubTool(tool, prefetchedRelease) {
+  const spec = tool.github;
+  if (!spec)
+    return;
+  const platform = process.platform;
+  const arch = process.arch;
+  const assetSubstring = spec.assetMatch(platform, arch);
+  if (!assetSubstring) {
+    logSessionStart(`github-install ${tool.id}: unsupported platform=${platform} arch=${arch}`);
+    return;
+  }
+  let releaseJson;
+  if (prefetchedRelease) {
+    releaseJson = prefetchedRelease;
+    logSessionStart(`github-install ${tool.id}: using caller-supplied release metadata for ${spec.repo} (${prefetchedRelease.tag_name ?? "untagged"})`);
+  } else {
+    logSessionStart(`github-install ${tool.id}: fetching release metadata from ${spec.repo}`);
+    try {
+      const body = await httpsGet(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, githubApiAuthHeaders());
+      releaseJson = JSON.parse(body.toString("utf8"));
+    } catch (err) {
+      logSessionStart(`github-install ${tool.id}: release fetch failed: ${err.message}`);
+      return;
+    }
+  }
+  if (releaseJson.tag_name) {
+    lastInstallResolutionId.set(tool.id, releaseJson.tag_name);
+  }
+  if (!Array.isArray(releaseJson.assets)) {
+    logSessionStart(`github-install ${tool.id}: release metadata has no assets array`);
+    return;
+  }
+  const asset = pickReleaseAsset(releaseJson.assets, assetSubstring) ?? deriveHashiCorpReleaseAsset(tool, releaseJson.tag_name, assetSubstring);
+  if (!asset) {
+    logSessionStart(`github-install ${tool.id}: no asset matched "${assetSubstring}"`);
+    return;
+  }
+  logSessionStart(`github-install ${tool.id}: downloading ${asset.name}`);
+  debugLog(`[github] downloading ${asset.name} from ${asset.browser_download_url}`);
+  const downloadStart = Date.now();
+  let assetBuffer;
+  try {
+    assetBuffer = await httpsGet(asset.browser_download_url);
+    logSessionStart(`github-install ${tool.id}: downloaded ${asset.name} (${assetBuffer.length} bytes, ${Date.now() - downloadStart}ms)`);
+  } catch (err) {
+    logSessionStart(`github-install ${tool.id}: download failed: ${err.message}`);
+    return;
+  }
+  await fs.mkdir(GITHUB_BIN_DIR, { recursive: true });
+  const binaryName = tool.binaryName ?? tool.id;
+  const isWindows = platform === "win32";
+  const finalBinaryName = getGitHubInstalledBinaryName(binaryName, platform, asset.name);
+  const destPath = path.join(GITHUB_BIN_DIR, finalBinaryName);
+  const assetName = asset.name;
+  try {
+    if (assetName.endsWith(".gz") && !assetName.endsWith(".tar.gz")) {
+      const decompressed = await new Promise((resolve, reject) => {
+        const gunzip = createGunzip();
+        const chunks = [];
+        gunzip.on("data", (chunk) => chunks.push(chunk));
+        gunzip.on("end", () => resolve(Buffer.concat(chunks)));
+        gunzip.on("error", reject);
+        gunzip.end(assetBuffer);
+      });
+      await writeFileAtomicAsync(destPath, decompressed, {
+        bestEffort: false,
+        mode: 488
+      });
+    } else if (assetName.endsWith(".tar.gz") || assetName.endsWith(".tar.xz")) {
+      const tmpArchive = path.join(GITHUB_BIN_DIR, `_tmp_${assetName}`);
+      await fs.writeFile(tmpArchive, assetBuffer);
+      const tmpDir = path.join(GITHUB_BIN_DIR, `_tmp_extract_${tool.id}`);
+      await fs.mkdir(tmpDir, { recursive: true });
+      const extracted = await runCommand("tar", ["xf", tmpArchive, "-C", tmpDir], GITHUB_BIN_DIR);
+      await fs.rm(tmpArchive, { force: true });
+      if (!extracted) {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+        logSessionStart(`github-install ${tool.id}: tar extraction failed for ${assetName}`);
+        return;
+      }
+      const tarBinaryName = spec.binaryInArchive ?? binaryName;
+      const tarSrcBinary = await findFirstFileRecursive(tmpDir, getArchiveBinaryCandidates(tarBinaryName, platform, assetName));
+      if (!tarSrcBinary) {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+        logSessionStart(`github-install ${tool.id}: binary candidates ${JSON.stringify(getArchiveBinaryCandidates(tarBinaryName, platform, assetName))} not found in tar ${assetName}`);
+        return;
+      }
+      await fs.rename(tarSrcBinary, destPath);
+      await fs.rm(tmpDir, { recursive: true, force: true });
+      if (!isWindows)
+        await fs.chmod(destPath, 488);
+    } else if (assetName.endsWith(".zip")) {
+      const tmpArchive = path.join(GITHUB_BIN_DIR, `_tmp_${assetName}`);
+      await fs.writeFile(tmpArchive, assetBuffer);
+      const tmpDir = path.join(GITHUB_BIN_DIR, `_tmp_extract_${tool.id}`);
+      await fs.mkdir(tmpDir, { recursive: true });
+      const extracted = isWindows ? await runCommand("powershell", [
+        "-NoProfile",
+        "-Command",
+        `Expand-Archive -LiteralPath '${tmpArchive}' -DestinationPath '${tmpDir}' -Force`
+      ], GITHUB_BIN_DIR) : await runCommand("unzip", ["-q", "-o", tmpArchive, "-d", tmpDir], GITHUB_BIN_DIR);
+      await fs.rm(tmpArchive, { force: true });
+      if (!extracted) {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+        logSessionStart(`github-install ${tool.id}: zip extraction failed for ${assetName}`);
+        return;
+      }
+      const archiveBinaryName = spec.binaryInArchive ?? binaryName;
+      const srcBinary = await findFirstFileRecursive(tmpDir, getArchiveBinaryCandidates(archiveBinaryName, platform, assetName));
+      if (!srcBinary) {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+        logSessionStart(`github-install ${tool.id}: binary candidates ${JSON.stringify(getArchiveBinaryCandidates(archiveBinaryName, platform, assetName))} not found in zip ${assetName}`);
+        return;
+      }
+      await fs.rename(srcBinary, destPath);
+      await fs.rm(tmpDir, { recursive: true, force: true });
+      if (!isWindows)
+        await fs.chmod(destPath, 488);
+    } else {
+      await writeFileAtomicAsync(destPath, assetBuffer, {
+        bestEffort: false,
+        mode: 488
+      });
+    }
+  } catch (err) {
+    logSessionStart(`github-install ${tool.id}: install failed: ${err.message}`);
+    return;
+  }
+  for (const extraName of spec.extraAssets?.(platform, arch) ?? []) {
+    const extraAsset = releaseJson.assets.find((a) => a.name === extraName);
+    if (!extraAsset) {
+      logSessionStart(`github-install ${tool.id}: required extra asset "${extraName}" not found`);
+      return;
+    }
+    try {
+      const extraBuffer = await httpsGet(extraAsset.browser_download_url);
+      await writeFileAtomicAsync(path.join(GITHUB_BIN_DIR, extraName), extraBuffer, { bestEffort: false, mode: 488 });
+      logSessionStart(`github-install ${tool.id}: installed extra asset ${extraName} (${extraBuffer.length} bytes)`);
+    } catch (err) {
+      logSessionStart(`github-install ${tool.id}: extra asset ${extraName} download failed: ${err.message}`);
+      return;
+    }
+  }
+  debugLog(`[github] installed ${tool.name} → ${destPath}`);
+  logSessionStart(`github-install ${tool.id}: installed → ${destPath}`);
+  return destPath;
+}
+async function findFirstFileRecursive(dir, names) {
+  const wanted = new Set(names.map((name) => name.toLowerCase()));
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const found = await findFirstFileRecursive(full, names);
+      if (found)
+        return found;
+    } else if (wanted.has(entry.name.toLowerCase())) {
+      return full;
+    }
+  }
+  return;
+}
+const NEEDS_POSTINSTALL = new Set([
+  "@biomejs/biome",
+  "@ast-grep/cli",
+  "@ast-grep/napi",
+  "esbuild",
+  "intelephense"
+]);
+export function npmToolNeedsPostinstall(packageName) {
+  return NEEDS_POSTINSTALL.has(packageName);
+}
+export function getRefreshableManagedNpmTools() {
+  return getRefreshableManagedTools().filter((candidate) => candidate.strategy === "npm").map((candidate) => ({
+    toolId: candidate.toolId,
+    packageName: candidate.packageName,
+    binaryName: candidate.binaryName
+  }));
+}
+function mavenCoordinate(spec) {
+  return [
+    spec.repoBaseUrl ?? MAVEN_CENTRAL_BASE,
+    spec.groupId,
+    spec.artifactId,
+    spec.version,
+    spec.classifier ?? ""
+  ].join(":");
+}
+export function getRefreshableManagedTools() {
+  const refreshable = [];
+  for (const tool of TOOLS) {
+    switch (tool.installStrategy) {
+      case "npm": {
+        if (!tool.packageName)
+          continue;
+        if (parsePinnedVersion(tool.packageName) !== undefined)
+          continue;
+        if (!tool.binaryName)
+          continue;
+        refreshable.push({
+          toolId: tool.id,
+          strategy: "npm",
+          checkArgs: tool.checkArgs,
+          packageName: tool.packageName,
+          binaryName: tool.binaryName,
+          verificationTimeoutMs: tool.verificationTimeoutMs
+        });
+        break;
+      }
+      case "pip":
+      case "gem": {
+        if (!tool.packageName)
+          continue;
+        refreshable.push({
+          toolId: tool.id,
+          strategy: tool.installStrategy,
+          checkArgs: tool.checkArgs,
+          packageName: tool.packageName
+        });
+        break;
+      }
+      case "github": {
+        if (!tool.github)
+          continue;
+        refreshable.push({
+          toolId: tool.id,
+          strategy: "github",
+          checkArgs: tool.checkArgs
+        });
+        break;
+      }
+      case "maven": {
+        if (!tool.maven)
+          continue;
+        refreshable.push({
+          toolId: tool.id,
+          strategy: "maven",
+          checkArgs: tool.checkArgs,
+          pinnedCoordinate: mavenCoordinate(tool.maven)
+        });
+        break;
+      }
+      case "archive": {
+        if (!tool.archive)
+          continue;
+        const url = resolveArchiveUrl(tool.archive);
+        if (!url)
+          continue;
+        refreshable.push({
+          toolId: tool.id,
+          strategy: "archive",
+          checkArgs: tool.checkArgs,
+          pinnedCoordinate: url
+        });
+        break;
+      }
+    }
+  }
+  return refreshable;
+}
+export async function isManagedToolPresent(toolId) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (!tool)
+    return false;
+  switch (tool.installStrategy) {
+    case "npm": {
+      if (!tool.packageName)
+        return false;
+      try {
+        await fs.access(path.join(TOOLS_DIR, "node_modules", tool.packageName, "package.json"));
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    case "github":
+    case "maven":
+      return await findGitHubToolPath(tool.binaryName ?? tool.id) !== undefined;
+    case "archive":
+      return await findGitHubToolPath(tool.binaryName ?? tool.id) !== undefined || await getArchiveTreeBundlePath(tool) !== undefined;
+    case "pip":
+    case "gem": {
+      const cached = (await readProbeCache())[toolId];
+      return cached?.path !== undefined && existsSync(cached.path);
+    }
+    default:
+      return false;
+  }
+}
+async function probeManagedToolVersion(tool) {
+  const cached = (await readProbeCache())[tool.id];
+  if (!cached?.path || !existsSync(cached.path))
+    return;
+  try {
+    const result = await safeSpawnAsync(cached.path, tool.checkArgs, {
+      timeout: getToolVerificationTimeout(tool),
+      input: "",
+      ignoreAmbientSignal: true,
+      resourceLabel: `tool-refresh-version:${tool.id}`
+    });
+    if (result.status !== 0)
+      return;
+    return extractVersionToken(`${result.stdout}
+${result.stderr}`);
+  } catch {
+    return;
+  }
+}
+export async function acquireManagedInstallGate(context) {
+  if (process.env.DM_LENS_DISABLE_TOOL_INSTALL === "1") {
+    return {
+      ok: false,
+      reason: "installation disabled by DM_LENS_DISABLE_TOOL_INSTALL=1"
+    };
+  }
+  if (!assertInstallAllowed(context)) {
+    return {
+      ok: false,
+      reason: `project trust: ${projectTrustDenialReason()}`
+    };
+  }
+  const lock = await acquireInstallLock();
+  if (!lock.release) {
+    return { ok: false, reason: lock.reason ?? "install lock held" };
+  }
+  return { ok: true, release: lock.release };
+}
+export async function refreshManagedTool(toolId, known = {}) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (!tool) {
+    return { ok: false, unchanged: true, reason: "unknown tool id" };
+  }
+  if (tool.installStrategy !== "github" && tool.installStrategy !== "pip" && tool.installStrategy !== "gem" && tool.installStrategy !== "maven" && tool.installStrategy !== "archive") {
+    return {
+      ok: false,
+      unchanged: true,
+      reason: `strategy ${tool.installStrategy} is not refreshable here`
+    };
+  }
+  const strategy = tool.installStrategy;
+  const gate = await acquireManagedInstallGate(`managed tool refresh: ${toolId}`);
+  if (!gate.ok) {
+    return { ok: false, unchanged: true, declined: true, reason: gate.reason };
+  }
+  try {
+    switch (strategy) {
+      case "github":
+        return await refreshGitHubManagedTool(tool, known);
+      case "pip":
+      case "gem":
+        return await refreshPackageManagerManagedTool(tool);
+      case "maven":
+      case "archive":
+        return await refreshPinnedManagedTool(tool, known);
+      default:
+        return {
+          ok: false,
+          unchanged: true,
+          reason: `strategy ${strategy} is not refreshable here`
+        };
+    }
+  } finally {
+    await gate.release?.();
+  }
+}
+async function refreshGitHubManagedTool(tool, known) {
+  const spec = tool.github;
+  if (!spec)
+    return { ok: false, unchanged: true, reason: "no github spec" };
+  let response;
+  try {
+    response = await httpsGetWithMeta(`https://api.github.com/repos/${spec.repo}/releases/latest`, 5, {
+      ...githubApiAuthHeaders(),
+      ...known.etag ? { "If-None-Match": known.etag } : {}
+    });
+  } catch (err) {
+    return {
+      ok: false,
+      unchanged: true,
+      reason: `release query failed: ${err.message}`
+    };
+  }
+  if (response.statusCode === 304) {
+    return {
+      ok: true,
+      unchanged: true,
+      resolutionId: known.resolutionId,
+      etag: known.etag,
+      version: known.version
+    };
+  }
+  let release;
+  try {
+    const parsed = JSON.parse(response.body.toString("utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("release metadata is not an object");
+    }
+    release = parsed;
+  } catch (err) {
+    return {
+      ok: false,
+      unchanged: true,
+      reason: `release metadata unparseable: ${err.message}`
+    };
+  }
+  const tag = release.tag_name;
+  if (!tag) {
+    return { ok: false, unchanged: true, reason: "release has no tag_name" };
+  }
+  if (known.resolutionId === tag) {
+    return {
+      ok: true,
+      unchanged: true,
+      resolutionId: tag,
+      etag: response.etag ?? known.etag,
+      version: known.version ?? tag
+    };
+  }
+  const installed = await installGitHubTool(tool, release);
+  if (!installed) {
+    return {
+      ok: false,
+      unchanged: true,
+      resolutionId: known.resolutionId,
+      version: known.version,
+      reason: `install from release ${tag} failed`
+    };
+  }
+  const verified = await verifyRefreshedArtifact(tool, installed);
+  if (!verified) {
+    return {
+      ok: false,
+      unchanged: false,
+      resolutionId: known.resolutionId,
+      version: known.version,
+      reason: `release ${tag} installed but its binary does not run`
+    };
+  }
+  return {
+    ok: true,
+    unchanged: false,
+    resolutionId: tag,
+    etag: response.etag,
+    version: tag
+  };
+}
+async function verifyRefreshedArtifact(tool, installedPath) {
+  if (tool.installStrategy === "archive" && !tool.archive?.launcher) {
+    await updateProbeCache(tool.id, installedPath);
+    return true;
+  }
+  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;
+  }
+  await updateProbeCache(tool.id, installedPath);
+  return true;
+}
+async function refreshPackageManagerManagedTool(tool) {
+  if (!tool.packageName) {
+    return { ok: false, unchanged: true, reason: "no package name" };
+  }
+  const previous = await probeManagedToolVersion(tool);
+  const installed = tool.installStrategy === "pip" ? await installPipTool(tool.packageName, { upgrade: true }) : await installGemTool(tool.packageName);
+  if (!installed) {
+    return {
+      ok: false,
+      unchanged: true,
+      version: previous,
+      reason: `${tool.installStrategy} upgrade failed`
+    };
+  }
+  const current = await probeManagedToolVersion(tool);
+  if (previous !== undefined && current === undefined) {
+    return {
+      ok: false,
+      unchanged: false,
+      version: previous,
+      reason: `${tool.installStrategy} upgrade left the binary unable to report a version`
+    };
+  }
+  return {
+    ok: true,
+    unchanged: previous === undefined || current === undefined || previous === current,
+    version: current ?? previous
+  };
+}
+async function refreshPinnedManagedTool(tool, known) {
+  const coordinate = tool.installStrategy === "maven" ? tool.maven && mavenCoordinate(tool.maven) : tool.archive && resolveArchiveUrl(tool.archive);
+  if (!coordinate) {
+    return {
+      ok: false,
+      unchanged: true,
+      reason: "no coordinate for this platform"
+    };
+  }
+  if (known.resolutionId === coordinate) {
+    return {
+      ok: true,
+      unchanged: true,
+      resolutionId: coordinate,
+      version: known.version
+    };
+  }
+  const installed = tool.installStrategy === "maven" ? await installMavenTool(tool) : await installArchiveTool(tool);
+  if (!installed) {
+    return {
+      ok: false,
+      unchanged: true,
+      resolutionId: known.resolutionId,
+      version: known.version,
+      reason: `reinstall from ${coordinate} failed`
+    };
+  }
+  if (!await verifyRefreshedArtifact(tool, installed)) {
+    return {
+      ok: false,
+      unchanged: false,
+      resolutionId: known.resolutionId,
+      version: known.version,
+      reason: `reinstall from ${coordinate} produced an artifact that does not run`
+    };
+  }
+  return {
+    ok: true,
+    unchanged: known.resolutionId === undefined,
+    resolutionId: coordinate,
+    version: coordinate
+  };
+}
+export function resolveManagedNpmBinPath(binaryName) {
+  const binBase = path.join(TOOLS_DIR, "node_modules", ".bin", binaryName);
+  return installerPlatform() === "win32" ? `${binBase}.cmd` : binBase;
+}
+export function invalidateManagedToolResolution(toolId) {
+  resolvedPathCache.delete(toolId);
+  if (_probeCache !== null)
+    delete _probeCache[toolId];
+  markProbeCacheChange(toolId, null);
+}
+const MAVEN_CENTRAL_BASE = "https://repo1.maven.org/maven2";
+async function installMavenTool(tool) {
+  const spec = tool.maven;
+  if (!spec)
+    return;
+  const binaryName = tool.binaryName ?? tool.id;
+  const isWindows = process.platform === "win32";
+  if (!await isCommandAvailable("java", ["-version"])) {
+    logSessionStart(`maven-install ${tool.id}: java not found — a JAR tool can't run without a JRE`);
+    return;
+  }
+  let base = spec.repoBaseUrl ?? MAVEN_CENTRAL_BASE;
+  while (base.endsWith("/"))
+    base = base.slice(0, -1);
+  const groupPath = spec.groupId.replace(/\./g, "/");
+  const jarFile = `${spec.artifactId}-${spec.version}${spec.classifier ? `-${spec.classifier}` : ""}.jar`;
+  const url = `${base}/${groupPath}/${spec.artifactId}/${spec.version}/${jarFile}`;
+  lastInstallResolutionId.set(tool.id, mavenCoordinate(spec));
+  logSessionStart(`maven-install ${tool.id}: downloading ${url}`);
+  let jarBuffer;
+  try {
+    jarBuffer = await httpsGet(url);
+  } catch (err) {
+    logSessionStart(`maven-install ${tool.id}: download failed: ${err.message}`);
+    return;
+  }
+  try {
+    await fs.mkdir(GITHUB_BIN_DIR, { recursive: true });
+    const jarPath = path.join(GITHUB_BIN_DIR, `${tool.id}.jar`);
+    await writeFileAtomicAsync(jarPath, jarBuffer, { bestEffort: false });
+    const launcherName = isWindows ? `${binaryName}.bat` : binaryName;
+    const launcherPath = path.join(GITHUB_BIN_DIR, launcherName);
+    if (isWindows) {
+      await writeFileAtomicAsync(launcherPath, `@echo off\r
+java -jar "%~dp0${tool.id}.jar" %*\r
+`, { bestEffort: false });
+    } else {
+      await writeFileAtomicAsync(launcherPath, `#!/bin/sh
+exec java -jar "$(dirname "$0")/${tool.id}.jar" "$@"
+`, { bestEffort: false, mode: 488 });
+    }
+    logSessionStart(`maven-install ${tool.id}: installed → ${launcherPath} (${jarBuffer.length} bytes)`);
+    debugLog(`[maven] installed ${tool.name} → ${launcherPath}`);
+    return launcherPath;
+  } catch (err) {
+    logSessionStart(`maven-install ${tool.id}: install failed: ${err.message}`);
+    return;
+  }
+}
+export function resolveArchiveUrl(spec, platform = process.platform, arch = process.arch) {
+  return typeof spec.url === "function" ? spec.url(platform, arch) : spec.url;
+}
+export async function swapExtractedDir(toolId, tmpDir, finalDir) {
+  const backupDir = `${finalDir}.rollback`;
+  await fs.rm(backupDir, { recursive: true, force: true });
+  let hadPrevious = false;
+  try {
+    await fs.rename(finalDir, backupDir);
+    hadPrevious = true;
+  } catch (err) {
+    if (err.code !== "ENOENT")
+      throw err;
+  }
+  try {
+    await fs.rename(tmpDir, finalDir);
+  } catch (err) {
+    if (hadPrevious) {
+      try {
+        await fs.rename(backupDir, finalDir);
+      } catch (rollbackErr) {
+        recordDegradationOnce({
+          kind: "managed-tool-refresh",
+          subject: toolId,
+          reason: `swap rollback failed after a failed install: working copy orphaned at ${backupDir} (${rollbackErr.message})`
+        });
+        logSessionStart(`archive-install ${toolId}: swap rollback failed — working copy orphaned at ${backupDir} (${rollbackErr.message})`);
+      }
+    }
+    throw err;
+  }
+  if (hadPrevious) {
+    await fs.rm(backupDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+async function installArchiveTool(tool) {
+  const spec = tool.archive;
+  if (!spec)
+    return;
+  const binaryName = tool.binaryName ?? tool.id;
+  const isWindows = process.platform === "win32";
+  const url = resolveArchiveUrl(spec);
+  if (!url) {
+    logSessionStart(`archive-install ${tool.id}: no archive for ${process.platform}/${process.arch} — unsupported, skipping`);
+    return;
+  }
+  lastInstallResolutionId.set(tool.id, url);
+  logSessionStart(`archive-install ${tool.id}: downloading ${url}`);
+  let archiveBuffer;
+  try {
+    archiveBuffer = await httpsGet(url);
+  } catch (err) {
+    logSessionStart(`archive-install ${tool.id}: download failed: ${err.message}`);
+    return;
+  }
+  const extractName = tool.id;
+  const tmpExtractName = `${extractName}.refresh-tmp`;
+  const archiveName = `${tool.id}.download.${spec.kind === "zip" ? "zip" : "tgz"}`;
+  const extractDir = path.join(TOOLS_DIR, extractName);
+  const tmpExtractDir = path.join(TOOLS_DIR, tmpExtractName);
+  const tmpArchive = path.join(TOOLS_DIR, archiveName);
+  try {
+    await fs.mkdir(TOOLS_DIR, { recursive: true });
+    await fs.rm(tmpExtractDir, { recursive: true, force: true });
+    await fs.mkdir(tmpExtractDir, { recursive: true });
+    await fs.writeFile(tmpArchive, archiveBuffer);
+    const stripComponents = spec.stripComponents ?? 1;
+    const tarArgs = [
+      spec.kind === "tgz" ? "-xzf" : "-xf",
+      archiveName,
+      "-C",
+      tmpExtractName,
+      ...stripComponents > 0 ? [`--strip-components=${stripComponents}`] : []
+    ];
+    const tarBin = isWindows ? `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\tar.exe` : "tar";
+    const extractResult = await safeSpawnAsync(tarBin, tarArgs, {
+      cwd: TOOLS_DIR,
+      timeout: 120000,
+      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} — keeping installed version`);
+      await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => {});
+      return;
+    }
+    if (!spec.launcher) {
+      const tmpMarker = spec.treeMarker ? path.join(tmpExtractDir, ...spec.treeMarker.split("/")) : tmpExtractDir;
+      try {
+        await fs.access(tmpMarker);
+      } catch {
+        logSessionStart(`archive-install ${tool.id}: tree marker not found at ${tmpMarker} after extraction — keeping installed version`);
+        await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => {});
+        return;
+      }
+      await swapExtractedDir(tool.id, tmpExtractDir, extractDir);
+      logSessionStart(`archive-install ${tool.id}: installed tree bundle → ${extractDir} (extracted ${archiveBuffer.length} bytes)`);
+      debugLog(`[archive] installed ${tool.name} bundle → ${extractDir}`);
+      return extractDir;
+    }
+    const launcherParts = spec.launcher.split("/").map((p) => p);
+    const tmpInnerLauncher = path.join(tmpExtractDir, ...launcherParts);
+    const tmpResolvedInner = isWindows ? `${tmpInnerLauncher}.bat` : tmpInnerLauncher;
+    try {
+      await fs.access(tmpResolvedInner);
+    } catch {
+      logSessionStart(`archive-install ${tool.id}: launcher not found at ${tmpResolvedInner} after extraction — keeping installed version`);
+      await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => {});
+      return;
+    }
+    if (!isWindows)
+      await fs.chmod(tmpResolvedInner, 488).catch(() => {});
+    await swapExtractedDir(tool.id, tmpExtractDir, extractDir);
+    const innerLauncher = path.join(extractDir, ...launcherParts);
+    const resolvedInner = isWindows ? `${innerLauncher}.bat` : innerLauncher;
+    await fs.mkdir(GITHUB_BIN_DIR, { recursive: true });
+    const launcherName = isWindows ? `${binaryName}.bat` : binaryName;
+    const shimPath = path.join(GITHUB_BIN_DIR, launcherName);
+    if (isWindows) {
+      await writeFileAtomicAsync(shimPath, `@echo off\r
+call "${resolvedInner}" %*\r
+`, { bestEffort: false });
+    } else {
+      await writeFileAtomicAsync(shimPath, `#!/bin/sh
+exec "${resolvedInner}" "$@"
+`, { bestEffort: false, mode: 488 });
+    }
+    logSessionStart(`archive-install ${tool.id}: installed → ${shimPath} (extracted ${archiveBuffer.length} bytes)`);
+    debugLog(`[archive] installed ${tool.name} → ${shimPath}`);
+    return shimPath;
+  } catch (err) {
+    await fs.rm(tmpArchive, { force: true }).catch(() => {});
+    await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => {});
+    logSessionStart(`archive-install ${tool.id}: install failed: ${err.message} — keeping installed version`);
+    return;
+  }
+}
+async function installNpmTool(packageName, binaryName, verificationArgs = ["--version"], verificationTimeoutMs = 1e4) {
+  try {
+    await fs.mkdir(TOOLS_DIR, { recursive: true });
+    const packageJsonPath = path.join(TOOLS_DIR, "package.json");
+    try {
+      await fs.access(packageJsonPath);
+    } catch {
+      await writeFileAtomicAsync(packageJsonPath, JSON.stringify({ name: "dm-lens-tools", version: "1.0.0" }, null, 2), { bestEffort: false });
+    }
+    const isWindows = installerPlatform() === "win32";
+    const pm = await resolveNodePackageManager(TOOLS_DIR);
+    const testNpmScript = process.env.DM_LENS_TEST_MODE === "1" ? process.env.DM_LENS_TEST_NPM_SCRIPT : undefined;
+    const pmCommand = testNpmScript ? process.execPath : pmBinary(pm);
+    const needsScripts = NEEDS_POSTINSTALL.has(packageName);
+    const baseInstallArgs = installArgs(pm, packageName, {
+      ignoreScripts: !needsScripts
+    });
+    const INSTALL_TIMEOUT_MS = Number(process.env.DM_LENS_INSTALL_TIMEOUT_MS) || 120000;
+    const runInstallAttempt = async (args) => {
+      const result = await safeSpawnAsync(pmCommand, args, {
+        cwd: TOOLS_DIR,
+        timeout: INSTALL_TIMEOUT_MS,
+        ignoreAmbientSignal: true,
+        lifetimeCoupled: true
+      });
+      return {
+        ok: result.status === 0,
+        stderr: result.error?.message ?? result.stderr
+      };
+    };
+    let outcome = await runInstallAttempt([
+      ...testNpmScript ? [testNpmScript] : [],
+      ...baseInstallArgs
+    ]);
+    const erResolve = outcome.ok === false && /npm\s+error\s+ERESOLVE|\bERESOLVE\b|could not resolve/i.test(outcome.stderr);
+    if (pm === "npm" && erResolve) {
+      const retryArgs = installArgs(pm, packageName, {
+        ignoreScripts: !needsScripts,
+        legacyPeerDeps: true
+      });
+      logSessionStart(`auto-install npm ${packageName}: retry with --legacy-peer-deps after ERESOLVE`);
+      outcome = await runInstallAttempt([
+        ...testNpmScript ? [testNpmScript] : [],
+        ...retryArgs
+      ]);
+    }
+    if (!outcome.ok) {
+      throw new Error(`Failed to install ${packageName}: ${outcome.stderr}`);
+    }
+    const binBase = path.join(TOOLS_DIR, "node_modules", ".bin", binaryName);
+    const binPath = installerPlatform() === "win32" ? `${binBase}.cmd` : binBase;
+    if (installerPlatform() !== "win32") {
+      try {
+        await fs.chmod(binPath, 488);
+      } catch {}
+    }
+    await new Promise((r) => setTimeout(r, 500));
+    debugLog(`Verifying ${binaryName}...`);
+    let isValid = false;
+    let lastAttemptTransient = false;
+    for (let attempt = 1;attempt <= 3; attempt++) {
+      lastAttemptTransient = false;
+      isValid = await verifyToolBinary(binPath, undefined, () => {
+        lastAttemptTransient = true;
+      }, verificationTimeoutMs, verificationArgs);
+      if (isValid)
+        break;
+      if (attempt < 3) {
+        logSessionStart(`auto-install verify ${binaryName}: attempt ${attempt} failed, retrying in ${attempt}s`);
+        await new Promise((r) => setTimeout(r, 1000 * attempt));
+      }
+    }
+    if (!isValid && lastAttemptTransient) {
+      logSessionStart(`auto-install ${packageName}: verification inconclusive (transient); keeping installation for re-probe`);
+      return;
+    }
+    if (!isValid) {
+      logSessionStart(`auto-install ${packageName}: installed but verification failed, cleaning up`);
+      try {
+        const packagePath = path.join(TOOLS_DIR, "node_modules", packageName);
+        await fs.rm(packagePath, { recursive: true, force: true });
+        await fs.rm(binBase, { force: true });
+        if (isWindows) {
+          await fs.rm(`${binBase}.cmd`, { force: true });
+          await fs.rm(`${binBase}.ps1`, { force: true });
+        }
+      } catch {}
+      return;
+    }
+    return binPath;
+  } catch (err) {
+    logSessionStart(`auto-install npm ${packageName}: exception: ${err.message}`);
+    return;
+  }
+}
+async function installPipTool(packageName, options = {}) {
+  try {
+    const isWindows = process.platform === "win32";
+    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]
+      }
+    ];
+    let lastError = "";
+    for (const candidate of pipCandidates) {
+      const pipResult = await safeSpawnAsync(candidate.command, candidate.args, {
+        timeout: 120000,
+        ignoreAmbientSignal: true,
+        lifetimeCoupled: true
+      });
+      const outcome = {
+        ok: pipResult.status === 0,
+        error: (pipResult.error?.message ?? pipResult.stderr).trim()
+      };
+      if (outcome.ok) {
+        const userBaseResult = await new Promise((resolve) => {
+          let probe;
+          try {
+            probe = spawn(candidate.command, ["-m", "site", "--user-base"], {
+              stdio: ["ignore", "pipe", "pipe"],
+              shell: isWindows
+            });
+          } catch {
+            resolve("");
+            return;
+          }
+          let stdout = "";
+          probe.stdout?.on("data", (data) => stdout += data);
+          probe.on("exit", (code) => {
+            if (code === 0)
+              resolve(stdout.trim());
+            else
+              resolve("");
+          });
+          probe.on("error", () => resolve(""));
+        });
+        if (userBaseResult) {
+          const candidateScriptDirs = [
+            path.join(userBaseResult, isWindows ? "Scripts" : "bin")
+          ];
+          if (isWindows) {
+            try {
+              const children = await fs.readdir(userBaseResult, {
+                withFileTypes: true
+              });
+              for (const entry of children) {
+                if (!entry.isDirectory())
+                  continue;
+                if (!/^python\d+$/i.test(entry.name))
+                  continue;
+                candidateScriptDirs.push(path.join(userBaseResult, entry.name, "Scripts"));
+              }
+            } catch {}
+          }
+          const currentPath = process.env.PATH || process.env.Path || process.env.path || "";
+          const separator = isWindows ? ";" : ":";
+          const normalizedPath = currentPath.toLowerCase().split(separator).map((p) => p.trim());
+          for (const scriptsDir of candidateScriptDirs) {
+            try {
+              await fs.access(scriptsDir);
+              if (!normalizedPath.includes(scriptsDir.toLowerCase())) {
+                const existingPath = process.env.PATH || process.env.Path || process.env.path || "";
+                const updatedPath = `${scriptsDir}${separator}${existingPath}`;
+                process.env.PATH = updatedPath;
+                if (isWindows) {
+                  process.env.Path = updatedPath;
+                }
+                debugLog(`Added pip user scripts dir to PATH: ${scriptsDir}`);
+              }
+            } catch {
+              debugLog(`pip user scripts dir not accessible: ${scriptsDir}`);
+            }
+          }
+        }
+        return packageName;
+      }
+      lastError = `${candidate.command} ${candidate.args.join(" ")}: ${outcome.error}`;
+      debugLog(`[pip-fallback] ${lastError}`);
+    }
+    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;
+  }
+}
+async function installGemTool(packageName) {
+  try {
+    const gemResult = await safeSpawnAsync("gem", ["install", packageName, "--no-document"], {
+      timeout: 120000,
+      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}`);
+    }
+    return packageName;
+  } catch (err) {
+    logSessionStart(`auto-install gem ${packageName}: exception: ${err.message}`);
+    return;
+  }
+}
+async function stampInstallResolution(toolId) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (tool?.installStrategy === "npm")
+    return;
+  try {
+    const resolutionId = lastInstallResolutionId.get(toolId);
+    const refresh = await import("./managed-tool-refresh.js");
+    await refresh.stampManagedToolInstall(toolId, resolutionId);
+  } catch {}
+}
+async function finishInstallAttempt(toolId, ok, startedAt) {
+  logSessionStart(`auto-install ${toolId}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`);
+  if (ok)
+    await stampInstallResolution(toolId);
+  noteInstallAttempt(toolId, ok ? "succeeded" : "failed", ok ? undefined : installFailureReasons.get(toolId) ?? "install failed");
+  if (ok) {
+    resetSafeSpawnWindowsCommandCache();
+    try {
+      const { resetMadgeManagedPathMemo } = await import("../dependency-checker.js");
+      resetMadgeManagedPathMemo();
+    } catch (err) {
+      logSessionStart(`auto-install ${toolId}: madge memo reset failed: ${err.message}`);
+    }
+  }
+  return ok;
+}
+export async function installTool(toolId) {
+  if (process.env.DM_LENS_DISABLE_TOOL_INSTALL === "1") {
+    installFailureReasons.set(toolId, "installation disabled by DM_LENS_DISABLE_TOOL_INSTALL=1");
+    noteInstallAttempt(toolId, "declined", "installation disabled by DM_LENS_DISABLE_TOOL_INSTALL=1");
+    logSessionStart(`auto-install ${toolId}: refused — DM_LENS_DISABLE_TOOL_INSTALL=1`);
+    return false;
+  }
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (!tool) {
+    noteInstallAttempt(toolId, "declined", "unknown tool id");
+    logSessionStart(`auto-install ${toolId}: unknown tool id`);
+    return false;
+  }
+  const startedAt = Date.now();
+  logSessionStart(`auto-install ${tool.id}: start strategy=${tool.installStrategy} package=${tool.packageName ?? "n/a"}`);
+  try {
+    switch (tool.installStrategy) {
+      case "npm": {
+        if (!tool.packageName || !tool.binaryName)
+          return false;
+        const npmPath = await installNpmTool(tool.packageName, tool.binaryName, tool.checkArgs, getToolVerificationTimeout(tool));
+        if (npmPath !== undefined) {
+          await import("./managed-tool-refresh.js").then((m) => m.stampManagedToolInstalled(tool.id, tool.packageName)).catch(() => {});
+        }
+        return finishInstallAttempt(tool.id, npmPath !== undefined, startedAt);
+      }
+      case "pip": {
+        if (!tool.packageName)
+          return false;
+        const pipPath = await installPipTool(tool.packageName);
+        return finishInstallAttempt(tool.id, pipPath !== undefined, startedAt);
+      }
+      case "gem": {
+        if (!tool.packageName)
+          return false;
+        const gemPath = await installGemTool(tool.packageName);
+        return finishInstallAttempt(tool.id, gemPath !== undefined, startedAt);
+      }
+      case "github": {
+        if (!tool.github)
+          return false;
+        const ghPath = await installGitHubTool(tool);
+        return finishInstallAttempt(tool.id, ghPath !== undefined, startedAt);
+      }
+      case "maven": {
+        if (!tool.maven)
+          return false;
+        const mavenPath = await installMavenTool(tool);
+        return finishInstallAttempt(tool.id, mavenPath !== undefined, startedAt);
+      }
+      case "archive": {
+        if (!tool.archive)
+          return false;
+        const archivePath = await installArchiveTool(tool);
+        return finishInstallAttempt(tool.id, archivePath !== undefined, startedAt);
+      }
+      default:
+        logSessionStart(`auto-install ${tool.id}: unsupported strategy`);
+        return false;
+    }
+  } catch (err) {
+    logSessionStart(`auto-install ${tool.id}: exception ${err.message} (${Date.now() - startedAt}ms)`);
+    return false;
+  }
+}
+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`);
+    const denialReason = projectTrustDenialReason();
+    const discovered = await ensureToolResolved(toolId, {
+      ...opts,
+      allowInstall: false
+    });
+    noteInstallAttempt(toolId, "declined", `project trust: ${denialReason}`);
+    return discovered;
+  }
+  return ensureToolResolved(toolId, opts);
+}
+async function ensureToolResolved(toolId, opts) {
+  installFailureReasons.delete(toolId);
+  installAttempts.delete(toolId);
+  lastEnsureResolutionSource.delete(toolId);
+  const cacheResolvedPath = (result) => {
+    if (result) {
+      resolvedPathCache.set(toolId, result);
+      updateProbeCache(toolId, result, wasLastResolveTransient(toolId));
+    }
+    return result;
+  };
+  if (opts?.forceReinstall) {
+    const ensureStartMs = Date.now();
+    logSessionStart(`auto-install ensure ${toolId}: force reinstall — clearing caches`);
+    resolvedPathCache.delete(toolId);
+    try {
+      const probeCache = await readProbeCache();
+      delete probeCache[toolId];
+      markProbeCacheChange(toolId, null);
+    } catch {}
+    if (opts.allowInstall === false) {
+      noteInstallAttempt(toolId, "declined", "install disabled by caller");
+      logSessionStart(`auto-install ensure ${toolId}: force reinstall blocked — install disabled, discovery only (${Date.now() - ensureStartMs}ms)`);
+      return cacheResolvedPath(await getToolPath(toolId));
+    }
+    if (process.env.DM_LENS_DISABLE_TOOL_INSTALL === "1") {
+      installFailureReasons.set(toolId, "installation disabled by DM_LENS_DISABLE_TOOL_INSTALL=1");
+      noteInstallAttempt(toolId, "declined", "installation disabled by DM_LENS_DISABLE_TOOL_INSTALL=1");
+      logSessionStart(`auto-install ensure ${toolId}: refused — DM_LENS_DISABLE_TOOL_INSTALL=1`);
+      return;
+    }
+    const lock = await acquireInstallLock();
+    if (!lock.release) {
+      noteInstallAttempt(toolId, "skipped", lock.reason ?? "install lock held");
+      logSessionStart(`auto-install ensure ${toolId}: ${lock.reason}`);
+      return;
+    }
+    let installed;
+    try {
+      installed = await installTool(toolId);
+    } finally {
+      await lock.release();
+    }
+    if (!installed) {
+      noteInstallAttemptIfUnrecorded(toolId, "failed", "install failed");
+      logSessionStart(`auto-install ensure ${toolId}: force reinstall failed (${Date.now() - ensureStartMs}ms)`);
+      return;
+    }
+    const result = cacheResolvedPath(await getToolPath(toolId));
+    if (result) {
+      logSessionStart(`auto-install ensure ${toolId}: force reinstall success at ${result} (${Date.now() - ensureStartMs}ms)`);
+    }
+    return result;
+  }
+  const cached = resolvedPathCache.get(toolId);
+  if (cached) {
+    if (!isFullyQualified(cached)) {
+      lastEnsureResolutionSource.set(toolId, "session-cache");
+      return cached;
+    }
+    try {
+      await fs.access(cached);
+      lastEnsureResolutionSource.set(toolId, "session-cache");
+      return cached;
+    } catch {}
+    resolvedPathCache.delete(toolId);
+    const probeCache = await readProbeCache();
+    delete probeCache[toolId];
+    markProbeCacheChange(toolId, null);
+    logSessionStart(`auto-install ensure ${toolId}: cached path disappeared; re-probing`);
+  }
+  const diskCached = await checkProbeCache(toolId);
+  if (diskCached) {
+    resolvedPathCache.set(toolId, diskCached);
+    lastEnsureResolutionSource.set(toolId, "probe-cache");
+    logSessionStart(`auto-install ensure ${toolId}: probe cache hit → ${diskCached}`);
+    return diskCached;
+  }
+  const inFlightKey = opts?.allowInstall === false ? `${toolId}:discovery-only` : toolId;
+  const inFlight = ensureInFlight.get(inFlightKey);
+  if (inFlight) {
+    logSessionStart(`auto-install ensure ${toolId}: waiting for in-flight ensure (${inFlightKey})`);
+    return inFlight;
+  }
+  const ensureStartMs = Date.now();
+  const ensurePromise = (async () => {
+    logSessionStart(`auto-install ensure ${toolId}: start`);
+    const existingPath = await getToolPath(toolId);
+    if (existingPath) {
+      const tool = TOOLS.find((t) => t.id === toolId);
+      const pinnedVersion = tool?.installStrategy === "npm" && tool.packageName ? parsePinnedVersion(tool.packageName) : undefined;
+      if (pinnedVersion) {
+        const seenVersion = lastManagedInstallVersion.get(toolId);
+        if (seenVersion && seenVersion !== pinnedVersion) {
+          lastManagedInstallVersion.delete(toolId);
+          logSessionStart(`auto-install ensure ${toolId}: version drift (installed ${seenVersion} != pinned ${pinnedVersion}) — forcing reinstall (${Date.now() - ensureStartMs}ms)`);
+          return ensureTool(toolId, {
+            forceReinstall: true,
+            allowInstall: opts?.allowInstall
+          });
+        }
+      }
+      resolvedPathCache.set(toolId, existingPath);
+      updateProbeCache(toolId, existingPath, wasLastResolveTransient(toolId));
+      lastEnsureResolutionSource.set(toolId, "path");
+      logSessionStart(`auto-install ensure ${toolId}: already available at ${existingPath} (${Date.now() - ensureStartMs}ms)`);
+      return existingPath;
+    }
+    if (opts?.allowInstall === false) {
+      noteInstallAttempt(toolId, "declined", "install disabled by caller");
+      logSessionStart(`auto-install ensure ${toolId}: install disabled — discovery only, not found (${Date.now() - ensureStartMs}ms)`);
+      return;
+    }
+    if (process.env.DM_LENS_DISABLE_TOOL_INSTALL === "1") {
+      installFailureReasons.set(toolId, "installation disabled by DM_LENS_DISABLE_TOOL_INSTALL=1");
+      noteInstallAttempt(toolId, "declined", "installation disabled by DM_LENS_DISABLE_TOOL_INSTALL=1");
+      logSessionStart(`auto-install ensure ${toolId}: refused — DM_LENS_DISABLE_TOOL_INSTALL=1 (${Date.now() - ensureStartMs}ms)`);
+      return;
+    }
+    const lock = await acquireInstallLock();
+    if (!lock.release) {
+      installFailureReasons.set(toolId, lock.reason ?? "install lock failed");
+      noteInstallAttempt(toolId, "skipped", lock.reason ?? "install lock held");
+      logSessionStart(`auto-install ensure ${toolId}: ${lock.reason}`);
+      return;
+    }
+    let installed;
+    try {
+      const installedByPeer = await getToolPath(toolId);
+      if (installedByPeer) {
+        noteInstallAttempt(toolId, "succeeded", "installed by a concurrent process");
+        resolvedPathCache.set(toolId, installedByPeer);
+        updateProbeCache(toolId, installedByPeer, wasLastResolveTransient(toolId));
+        return installedByPeer;
+      }
+      installed = await installTool(toolId);
+    } finally {
+      await lock.release();
+    }
+    if (!installed) {
+      noteInstallAttemptIfUnrecorded(toolId, "failed", "install failed");
+      logSessionStart(`auto-install ensure ${toolId}: unavailable (${Date.now() - ensureStartMs}ms)`);
+      return;
+    }
+    const result = await getToolPath(toolId);
+    if (result) {
+      resolvedPathCache.set(toolId, result);
+      updateProbeCache(toolId, result, wasLastResolveTransient(toolId));
+      logSessionStart(`auto-install ensure ${toolId}: success at ${result} (${Date.now() - ensureStartMs}ms)`);
+    } else {
+      logSessionStart(`auto-install ensure ${toolId}: unavailable (${Date.now() - ensureStartMs}ms)`);
+    }
+    return result;
+  })();
+  ensureInFlight.set(inFlightKey, ensurePromise);
+  try {
+    return await ensurePromise;
+  } finally {
+    if (ensureInFlight.get(inFlightKey) === ensurePromise) {
+      ensureInFlight.delete(inFlightKey);
+    }
+  }
+}
+export async function getToolEnvironment() {
+  const localBin = path.join(TOOLS_DIR, "node_modules", ".bin");
+  const currentPath = process.env.PATH || process.env.Path || process.env.path || "";
+  const separator = process.platform === "win32" ? ";" : ":";
+  const nodeDir = path.dirname(process.execPath);
+  const withNode = nodeDir ? `${nodeDir}${separator}${currentPath}` : currentPath;
+  const augmentedPath = `${GITHUB_BIN_DIR}${separator}${localBin}${separator}${withNode}`;
+  const env = {
+    ...process.env,
+    PATH: augmentedPath
+  };
+  if (process.platform === "win32") {
+    env.Path = augmentedPath;
+  }
+  return env;
+}
+export async function checkAllTools() {
+  const results = [];
+  for (const tool of TOOLS) {
+    const path = await getToolPath(tool.id);
+    results.push({
+      id: tool.id,
+      name: tool.name,
+      installed: path !== undefined,
+      path
+    });
+  }
+  return results;
+}
+export function isKnownToolId(toolId) {
+  return TOOLS.some((tool) => tool.id === toolId);
+}
+export function getToolInstallStrategy(toolId) {
+  return TOOLS.find((tool) => tool.id === toolId)?.installStrategy;
+}
+export const GITHUB_TOOLS = [
+  "shellcheck",
+  "shfmt",
+  "rust-analyzer",
+  "golangci-lint",
+  "ktlint",
+  "actionlint",
+  "zizmor",
+  "typos-lsp",
+  "tflint",
+  "terragrunt",
+  "terraform-ls",
+  "zls",
+  "hadolint",
+  "helm",
+  "gitleaks",
+  "taplo",
+  "vale",
+  "opengrep",
+  "deno",
+  "clojure-lsp",
+  "cue",
+  "gleam",
+  "marksman",
+  "expert"
+];
+export function resolveGitHubAsset(toolId, platform, arch) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  return tool?.github?.assetMatch(platform, arch);
+}
+export function resolveGitHubInstalledBinaryName(toolId, platform, assetName) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (!tool)
+    return;
+  return getGitHubInstalledBinaryName(tool.binaryName ?? tool.id, platform, assetName);
+}
+export function resolveGitHubArchiveBinaryCandidates(toolId, platform, assetName) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (!tool)
+    return;
+  const binaryName = tool.github?.binaryInArchive ?? tool.binaryName ?? tool.id;
+  return getArchiveBinaryCandidates(binaryName, platform, assetName);
+}
+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)
+    return;
+  const version = tagName.replace(/^v/, "").trim();
+  if (!version)
+    return;
+  const assetName = `${product}_${version}_${assetSubstring}`;
+  return {
+    name: assetName,
+    browser_download_url: `https://releases.hashicorp.com/${product}/${version}/${assetName}`
+  };
+}
+export function resolveDerivedHashiCorpReleaseAsset(toolId, tagName, platform, arch) {
+  const tool = TOOLS.find((t) => t.id === toolId);
+  if (!tool)
+    return;
+  const assetSubstring = tool.github?.assetMatch(platform, arch);
+  if (!assetSubstring)
+    return;
+  return deriveHashiCorpReleaseAsset(tool, tagName, assetSubstring);
+}