ultimate-pi 0.18.0 → 0.19.0

package/.pi/lib/harness-lens/clients/installer/index.ts

@@ -0,0 +1,2368 @@
+/**
+ * Auto-Installation System for pi-lens
+ *
+ * Minimal auto-install: Core tools that run frequently.
+ * Other tools require manual installation with clear instructions.
+ *
+ * Auto-install (22 tools):
+ * - typescript-language-server (TypeScript LSP)
+ * - pyright (Python LSP)
+ * - bash-language-server (Bash LSP)
+ * - yaml-language-server (YAML LSP)
+ * - vscode-langservers-extracted (JSON LSP)
+ * - ruff (Python linting)
+ * - @biomejs/biome (JS/TS/JSON linting/formatting)
+ * - oxlint (JS/TS linting)
+ * - madge (circular dependency detection)
+ * - jscpd (duplicate code detection)
+ * - @ast-grep/cli (structural code search)
+ * - knip (dead code detection)
+ * - yamllint (YAML linting)
+ * - actionlint (GitHub Actions workflow linting) [GitHub release]
+ * - sqlfluff (SQL linting/formatting)
+ * - markdownlint-cli2 (Markdown linting)
+ * - mypy (Python type checking)
+ * - rubocop (Ruby linting/autofix)
+ * - stylelint (CSS/SCSS/Less linting)
+ * - shellcheck (shell script linting) [GitHub release]
+ * - shfmt (shell script formatting) [GitHub release]
+ * - rust-analyzer (Rust LSP) [GitHub release]
+ * - golangci-lint (Go linting) [GitHub release]
+ *
+ * Manual install required (25+ tools):
+ * - yaml-language-server: npm install -g yaml-language-server
+ * - vscode-json-languageserver: npm install -g vscode-langservers-extracted
+ * - bash-language-server: npm install -g bash-language-server
+ * - svelte-language-server: npm install -g svelte-language-server
+ * - vscode-eslint-language-server: npm install -g vscode-langservers-extracted
+ * - vscode-css-languageserver: npm install -g vscode-langservers-extracted
+ * - @prisma/language-server: npm install -g @prisma/language-server
+ * - dockerfile-language-server: npm install -g dockerfile-language-server-nodejs
+ * - @vue/language-server: npm install -g @vue/language-server
+ * - And all language-specific servers (gopls, rust-analyzer, etc.)
+ *
+ * Strategies:
+ * - npm packages via npx/bun
+ * - pip packages
+ * - GitHub releases (platform-specific binaries → ~/.pi-lens/bin/)
+ */
+
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import fs from "node:fs/promises";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+import { createGunzip } from "node:zlib";
+
+// Global installation directory for pi-lens tools
+const TOOLS_DIR = path.join(os.homedir(), ".pi-lens", "tools");
+
+// Directory for GitHub-downloaded binaries
+const GITHUB_BIN_DIR = path.join(os.homedir(), ".pi-lens", "bin");
+
+// Debug flag - set via PI_LENS_DEBUG=1 or --debug
+const DEBUG =
+	process.env.PI_LENS_DEBUG === "1" || process.argv.includes("--debug");
+const SESSIONSTART_LOG_DIR = path.join(os.homedir(), ".pi-lens");
+const SESSIONSTART_LOG = path.join(SESSIONSTART_LOG_DIR, "sessionstart.log");
+
+/**
+ * Log debug messages only when DEBUG is enabled
+ */
+function debugLog(...args: unknown[]): void {
+	if (DEBUG) {
+		console.error("[auto-install:debug]", ...args);
+	}
+}
+
+function logSessionStart(msg: string): void {
+	if (
+		process.env.PI_LENS_TEST_MODE === "1" ||
+		(process.env.VITEST && process.env.PI_LENS_TEST_MODE !== "0")
+	) {
+		return;
+	}
+	const line = `[${new Date().toISOString()}] ${msg}\n`;
+	void fs
+		.mkdir(SESSIONSTART_LOG_DIR, { recursive: true })
+		.then(() => fs.appendFile(SESSIONSTART_LOG, line))
+		.catch(() => {
+			// best-effort logging
+		});
+}
+
+// --- Tool Definitions ---
+
+interface GitHubAssetSpec {
+	/** owner/repo on GitHub */
+	repo: string;
+	/**
+	 * Return the asset filename substring to match for this platform/arch,
+	 * or undefined if the platform is unsupported.
+	 * platform: "linux" | "darwin" | "win32"
+	 * arch:     "x64" | "arm64" | "ia32" | ...
+	 */
+	assetMatch: (platform: string, arch: string) => string | undefined;
+	/**
+	 * If the asset is an archive, the name of the binary inside it.
+	 * For bare .gz files (e.g. rust-analyzer) leave undefined — the asset IS the binary.
+	 */
+	binaryInArchive?: string;
+	hashiCorpReleaseProduct?: string;
+}
+
+interface ToolDefinition {
+	id: string;
+	name: string;
+	checkCommand: string;
+	checkArgs: string[];
+	installStrategy: "npm" | "pip" | "gem" | "github";
+	packageName?: string;
+	binaryName?: string;
+	github?: GitHubAssetSpec;
+}
+
+const ALL_TOOLS: ToolDefinition[] = [
+	// Core LSP servers
+	{
+		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",
+		binaryName: "tsc",
+	},
+	{
+		id: "pyright",
+		name: "Pyright",
+		checkCommand: "pyright",
+		checkArgs: ["--version"],
+		installStrategy: "npm",
+		packageName: "pyright",
+		binaryName: "pyright",
+	},
+	// Linting/formatting tools
+	{
+		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: "biome",
+		name: "Biome",
+		checkCommand: "biome",
+		checkArgs: ["--version"],
+		installStrategy: "npm",
+		packageName: "@biomejs/biome",
+		binaryName: "biome",
+	},
+	// Analysis tools (run at session start / turn end)
+	{
+		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@3.5.10", // jscpd v4 introduced reprism dep whose lib/languages/ dir is missing from the published package — v3.5.x is the last stable release
+		binaryName: "jscpd",
+	},
+	// Structural search and dead code detection
+	{
+		id: "ast-grep",
+		name: "ast-grep CLI",
+		checkCommand: "ast-grep",
+		checkArgs: ["--version"],
+		installStrategy: "npm",
+		packageName: "@ast-grep/cli",
+		binaryName: "ast-grep",
+	},
+	{
+		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"],
+		installStrategy: "npm",
+		packageName: "bash-language-server",
+		binaryName: "bash-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"],
+		installStrategy: "npm",
+		packageName: "vscode-langservers-extracted",
+		binaryName: "vscode-json-language-server",
+	},
+	{
+		id: "vscode-langservers-extracted",
+		name: "VSCode ESLint Language Server",
+		checkCommand: "vscode-eslint-language-server",
+		checkArgs: ["--version"],
+		installStrategy: "npm",
+		packageName: "vscode-langservers-extracted",
+		binaryName: "vscode-eslint-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 undefined;
+			},
+		},
+	},
+	{
+		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"],
+		installStrategy: "npm",
+		packageName: "@prisma/language-server",
+		binaryName: "prisma-language-server",
+	},
+	{
+		id: "@vue/language-server",
+		name: "Vue Language Server",
+		checkCommand: "vue-language-server",
+		checkArgs: ["--version"],
+		installStrategy: "npm",
+		packageName: "@vue/language-server",
+		binaryName: "vue-language-server",
+	},
+	{
+		id: "svelte-language-server",
+		name: "Svelte Language Server",
+		checkCommand: "svelteserver",
+		checkArgs: ["--version"],
+		installStrategy: "npm",
+		packageName: "svelte-language-server",
+		binaryName: "svelteserver",
+	},
+	{
+		id: "markdownlint",
+		name: "markdownlint-cli2",
+		checkCommand: "markdownlint-cli2",
+		checkArgs: ["--version"],
+		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",
+	},
+	// GitHub release binaries
+	{
+		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 undefined;
+			},
+			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 undefined;
+			},
+			// bare binary, no archive
+		},
+	},
+	{
+		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 undefined;
+			},
+			// Linux/macOS: bare .gz; Windows: .zip archive containing rust-analyzer.exe
+		},
+	},
+	{
+		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 undefined;
+			},
+			binaryInArchive: "golangci-lint",
+		},
+	},
+	{
+		id: "ktlint",
+		name: "ktlint",
+		checkCommand: "ktlint",
+		checkArgs: ["--version"],
+		installStrategy: "github",
+		binaryName: "ktlint",
+		github: {
+			// ktlint ships one universal binary "ktlint" for Linux/macOS (GraalVM native)
+			// and "ktlint.bat" for Windows (requires Java). No arm64-specific asset.
+			repo: "pinterest/ktlint",
+			assetMatch: (platform, _arch) => {
+				if (platform === "linux") return "ktlint";
+				if (platform === "darwin") return "ktlint";
+				if (platform === "win32") return "ktlint.bat";
+				return undefined;
+			},
+		},
+	},
+	{
+		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 undefined;
+			},
+			binaryInArchive: "actionlint",
+		},
+	},
+	{
+		id: "tflint",
+		name: "tflint",
+		checkCommand: "tflint",
+		checkArgs: ["--version"],
+		installStrategy: "github",
+		binaryName: "tflint",
+		github: {
+			repo: "terraform-linters/tflint",
+			assetMatch: (platform, arch) => {
+				if (platform === "linux")
+					return arch === "arm64" ? "linux_arm64.zip" : "linux_amd64.zip";
+				if (platform === "darwin")
+					return arch === "arm64" ? "darwin_arm64.zip" : "darwin_amd64.zip";
+				if (platform === "win32")
+					return arch === "arm64" ? "windows_arm64.zip" : "windows_amd64.zip";
+				return undefined;
+			},
+			binaryInArchive: "tflint",
+		},
+	},
+	{
+		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 undefined;
+			},
+			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 undefined;
+			},
+		},
+	},
+	{
+		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 undefined;
+			},
+			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: (platform, arch) => {
+				if (platform === "linux")
+					return arch === "arm64" ? "linux_arm64.zip" : "linux_amd64.zip";
+				if (platform === "darwin")
+					return arch === "arm64" ? "darwin_arm64.zip" : "darwin_amd64.zip";
+				if (platform === "win32")
+					return arch === "arm64" ? "windows_arm64.zip" : "windows_amd64.zip";
+				return undefined;
+			},
+			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 undefined;
+			},
+			binaryInArchive: "zls",
+		},
+	},
+];
+
+const NON_LSP_INSTALLER_TOOL_IDS = new Set([
+	"prettier",
+	"ruff",
+	"biome",
+	"ast-grep",
+	"madge",
+	"jscpd",
+	"knip",
+	"yamllint",
+	"sqlfluff",
+	"htmlhint",
+	"hadolint",
+	"oxlint",
+	"mypy",
+	"rubocop",
+	"stylelint",
+	"shellcheck",
+	"shfmt",
+	"golangci-lint",
+	"actionlint",
+	"ktlint",
+	"markdownlint-cli2",
+	"black",
+	"eslint",
+	"semgrep",
+]);
+
+function isHarnessLspInstallerTool(tool: ToolDefinition): boolean {
+	if (NON_LSP_INSTALLER_TOOL_IDS.has(tool.id)) return false;
+	if (tool.id === "typescript") return true;
+	if (
+		/language-server|languageserver|analyzer|intelephense|taplo|terraform-ls|pyright|rust-analyzer|zls/i.test(
+			tool.id,
+		)
+	) {
+		return true;
+	}
+	if (tool.checkCommand.includes("language-server")) return true;
+	return false;
+}
+
+const TOOLS = ALL_TOOLS.filter(isHarnessLspInstallerTool);
+
+const ensureInFlight = new Map<string, Promise<string | undefined>>();
+
+// Session-lifetime cache: once a tool path is resolved, skip the process-spawn check on subsequent calls.
+const resolvedPathCache = new Map<string, string>();
+
+// --- Persistent probe cache ---
+
+interface ProbeCacheEntry {
+	path: string;
+	mtimeMs: number;
+	cachedAt: number;
+}
+
+type ProbeCache = Record<string, ProbeCacheEntry>;
+
+const PROBE_CACHE_PATH = path.join(
+	os.homedir(),
+	".pi-lens",
+	"probe-cache.json",
+);
+const PROBE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+let _probeCache: ProbeCache | null = null;
+let _probeCacheDirty = false;
+let _probeCacheFlushTimer: ReturnType<typeof setTimeout> | null = null;
+
+async function readProbeCache(): Promise<ProbeCache> {
+	if (_probeCache !== null) return _probeCache;
+	try {
+		const raw = await fs.readFile(PROBE_CACHE_PATH, "utf-8");
+		_probeCache = JSON.parse(raw) as ProbeCache;
+	} catch {
+		_probeCache = {};
+	}
+	return _probeCache;
+}
+
+function scheduleProbeFlush(): void {
+	if (_probeCacheFlushTimer !== null) return;
+	_probeCacheFlushTimer = setTimeout(() => {
+		_probeCacheFlushTimer = null;
+		if (!_probeCacheDirty || _probeCache === null) return;
+		_probeCacheDirty = false;
+		void fs
+			.writeFile(PROBE_CACHE_PATH, JSON.stringify(_probeCache, null, 2))
+			.catch(() => {});
+	}, 300);
+}
+
+function isAstGrepVersionOutput(output: string): boolean {
+	return /\bast[- ]grep\b/i.test(output);
+}
+
+async function verifyAstGrepProbePath(binPath: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const proc = spawn(binPath, ["--version"], {
+			stdio: ["ignore", "pipe", "pipe"],
+			shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(binPath),
+			timeout: 5000,
+		});
+		let 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));
+	});
+}
+
+// Exported for testing only.
+export async function checkProbeCache(
+	toolId: string,
+): Promise<string | undefined> {
+	const cache = await readProbeCache();
+	const entry = cache[toolId];
+	if (!entry) return undefined;
+
+	if (Date.now() - entry.cachedAt > PROBE_CACHE_TTL_MS) {
+		logSessionStart(`auto-install probe-cache ${toolId}: miss (ttl expired)`);
+		delete cache[toolId];
+		_probeCacheDirty = true;
+		scheduleProbeFlush();
+		return undefined;
+	}
+
+	try {
+		await fs.access(entry.path);
+		const stat = await fs.stat(entry.path);
+		if (stat.mtimeMs !== entry.mtimeMs) {
+			logSessionStart(
+				`auto-install probe-cache ${toolId}: miss (mtime changed)`,
+			);
+			delete cache[toolId];
+			_probeCacheDirty = true;
+			scheduleProbeFlush();
+			return undefined;
+		}
+		if (toolId === "ast-grep" && !(await verifyAstGrepProbePath(entry.path))) {
+			logSessionStart(
+				`auto-install probe-cache ${toolId}: miss (not ast-grep: ${entry.path})`,
+			);
+			delete cache[toolId];
+			_probeCacheDirty = true;
+			scheduleProbeFlush();
+			return undefined;
+		}
+		return entry.path;
+	} catch {
+		logSessionStart(
+			`auto-install probe-cache ${toolId}: miss (gone: ${entry.path})`,
+		);
+		delete cache[toolId];
+		_probeCacheDirty = true;
+		scheduleProbeFlush();
+		return undefined;
+	}
+}
+
+// Exported for testing only.
+export async function updateProbeCache(
+	toolId: string,
+	resolvedPath: string,
+): Promise<void> {
+	try {
+		const stat = await fs.stat(resolvedPath);
+		const cache = await readProbeCache();
+		cache[toolId] = {
+			path: resolvedPath,
+			mtimeMs: stat.mtimeMs,
+			cachedAt: Date.now(),
+		};
+		_probeCacheDirty = true;
+		scheduleProbeFlush();
+	} catch {
+		// best-effort
+	}
+}
+
+// Exported for testing only.
+export function resetProbeCacheStateForTesting(): void {
+	_probeCache = null;
+	_probeCacheDirty = false;
+	if (_probeCacheFlushTimer !== null) {
+		clearTimeout(_probeCacheFlushTimer);
+		_probeCacheFlushTimer = null;
+	}
+}
+
+// --- Check Functions ---
+
+/**
+ * Check if a command is available in PATH by walking PATH entries and
+ * verifying each candidate is a real file with non-zero size.
+ * Catches broken symlinks (stat throws ENOENT or returns size 0) without
+ * spawning a process — ~μs per candidate vs ~50ms for which/where.
+ */
+async function isCommandAvailable(
+	command: string,
+	_args?: string[],
+): Promise<boolean> {
+	const isWindows = process.platform === "win32";
+	const pathEnv =
+		process.env.PATH || process.env.Path || process.env.path || "";
+	const dirs = pathEnv.split(path.delimiter);
+
+	// On Windows, probe .exe, .cmd, and .bat extensions in addition to bare name.
+	// On Unix, probe bare name and extensionless (scripts, symlinks).
+	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);
+				// isFile() returns false for broken symlinks (target missing)
+				if (stat.isFile() && stat.size > 0) {
+					return true;
+				}
+			} catch {
+				// ENOENT or permission denied — skip this candidate
+			}
+		}
+	}
+
+	return false;
+}
+
+// --- Verification Functions
+
+/**
+ * Verify a tool binary actually works by running --version
+ * This catches broken symlinks, partial installs, and corrupted binaries
+ */
+async function verifyToolBinary(binPath: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const isWindows = process.platform === "win32";
+		const hasKnownWindowsExt = /\.(cmd|exe|ps1)$/i.test(binPath);
+
+		// On Windows, resolve the best executable path:
+		// - extensionless → prefer .cmd (cmd.exe-safe)
+		// - .ps1 → prefer .cmd sibling to avoid PowerShell execution-policy hangs
+		// - .cmd / .exe → use as-is
+		let execPath =
+			isWindows && !hasKnownWindowsExt ? `${binPath}.cmd` : binPath;
+		let useShell = isWindows && /\.(cmd|bat)$/i.test(execPath);
+
+		if (isWindows && /\.ps1$/i.test(execPath)) {
+			const cmdSibling = `${execPath.slice(0, -4)}.cmd`;
+			if (require("node:fs").existsSync(cmdSibling)) {
+				execPath = cmdSibling;
+				useShell = true;
+			} else {
+				// Fall back to running without shell — cmd.exe can't run .ps1
+				useShell = false;
+			}
+		}
+
+		// When shell:true (Windows .cmd), bake args into the command string to avoid DEP0190.
+		const spawnCmd = useShell ? `"${execPath}" --version` : execPath;
+		const proc = spawn(spawnCmd, useShell ? [] : ["--version"], {
+			timeout: 10000,
+			stdio: ["ignore", "pipe", "pipe"],
+			shell: useShell,
+		});
+
+		let stdout = "";
+		let stderr = "";
+
+		proc.stdout?.on("data", (data) => (stdout += data));
+		proc.stderr?.on("data", (data) => (stderr += data));
+
+		proc.on("exit", (code) => {
+			if (code === 0) {
+				debugLog(`Verified: ${binPath} (version: ${stdout.trim()})`);
+				resolve(true);
+			} else {
+				logSessionStart(
+					`auto-install verify: failed for ${binPath} (exit=${code})`,
+				);
+				resolve(false);
+			}
+		});
+
+		proc.on("error", (err) => {
+			logSessionStart(
+				`auto-install verify: error for ${binPath}: ${err.message}`,
+			);
+			resolve(false);
+		});
+	});
+}
+
+export type ToolSource =
+	| "global-path"
+	| "npm-global"
+	| "pip-user"
+	| "pi-lens-auto"
+	| "github-release"
+	| "npx-fallback"
+	| "not-installed";
+
+export interface ToolStatus {
+	id: string;
+	name: string;
+	installed: boolean;
+	source: ToolSource;
+	path?: string;
+	version?: string;
+	strategy: "npm" | "pip" | "gem" | "github";
+}
+
+/**
+ * Get detailed status for all tools
+ */
+export async function getAllToolStatuses(): Promise<ToolStatus[]> {
+	const statuses: ToolStatus[] = [];
+
+	for (const tool of TOOLS) {
+		const status: ToolStatus = {
+			id: tool.id,
+			name: tool.name,
+			installed: false,
+			source: "not-installed",
+			strategy: tool.installStrategy,
+		};
+
+		// 1. Check if in PATH (global)
+		if (await isCommandAvailable(tool.checkCommand, tool.checkArgs)) {
+			status.installed = true;
+			status.source = "global-path";
+			status.path = tool.checkCommand;
+			// Try to get version
+			const versionResult = await new Promise<string>((resolve) => {
+				const proc = spawn(tool.checkCommand, ["--version"], {
+					stdio: ["ignore", "pipe", "pipe"],
+					shell: process.platform === "win32",
+					timeout: 5000,
+				});
+				let out = "";
+				proc.stdout?.on("data", (d) => (out += d));
+				proc.stderr?.on("data", (d) => (out += d));
+				proc.on("exit", () =>
+					resolve(out.trim().split("\n")[0]?.slice(0, 30) || ""),
+				);
+				proc.on("error", () => resolve(""));
+			});
+			status.version = versionResult || undefined;
+			statuses.push(status);
+			continue;
+		}
+
+		// 2. Check npm global
+		if (tool.installStrategy === "npm") {
+			const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id);
+			if (npmPath) {
+				status.installed = true;
+				status.source = "npm-global";
+				status.path = npmPath;
+				statuses.push(status);
+				continue;
+			}
+		}
+
+		// 3. Check pip user install
+		if (tool.installStrategy === "pip") {
+			const pipPath = await findPipUserToolPath(tool.binaryName || tool.id);
+			if (pipPath) {
+				status.installed = true;
+				status.source = "pip-user";
+				status.path = pipPath;
+				statuses.push(status);
+				continue;
+			}
+		}
+
+		// 4. Check GitHub releases (~/.pi-lens/bin/)
+		if (tool.installStrategy === "github") {
+			const githubPath = await findGitHubToolPath(tool.binaryName || tool.id);
+			if (githubPath) {
+				status.installed = true;
+				status.source = "github-release";
+				status.path = githubPath;
+				statuses.push(status);
+				continue;
+			}
+		}
+
+		// 5. Check pi-lens auto-install (~/.pi-lens/tools/)
+		const localBase = path.join(
+			TOOLS_DIR,
+			"node_modules",
+			".bin",
+			tool.binaryName || tool.id,
+		);
+		const localPath =
+			process.platform === "win32" ? `${localBase}.cmd` : localBase;
+		try {
+			await fs.access(localPath);
+			if (await verifyToolBinary(localPath)) {
+				status.installed = true;
+				status.source = "pi-lens-auto";
+				status.path = localPath;
+				statuses.push(status);
+				continue;
+			}
+		} catch {
+			// fall through to not-installed
+		}
+
+		// 6. Not installed - will use npx fallback if npm strategy
+		if (tool.installStrategy === "npm") {
+			status.source = "npx-fallback";
+		}
+
+		statuses.push(status);
+	}
+
+	return statuses;
+}
+
+/**
+ * Check if a tool is installed (globally or locally)
+ */
+export async function isToolInstalled(toolId: string): Promise<boolean> {
+	return (await getToolPath(toolId)) !== undefined;
+}
+
+/**
+ * Get the path to a tool (global or local)
+ */
+export async function getToolPath(toolId: string): Promise<string | undefined> {
+	const tool = TOOLS.find((t) => t.id === toolId);
+	if (!tool) return undefined;
+
+	// Fast path: check local npm install first (where auto-install places tools).
+	// This avoids the ~2-5s overhead of spawning npm global probes and PATH
+	// searches for tools we already manage locally.
+	const localBase = path.join(
+		TOOLS_DIR,
+		"node_modules",
+		".bin",
+		tool.binaryName || tool.id,
+	);
+	if (process.platform === "win32") {
+		// Prefer .cmd over extensionless — Node.js can't execute POSIX shell scripts on Windows
+		const cmdPath = `${localBase}.cmd`;
+		try {
+			await fs.access(cmdPath);
+			if (await verifyToolBinary(cmdPath)) {
+				return cmdPath;
+			}
+			logSessionStart(
+				`auto-install verify: ${cmdPath} exists but is broken, will reinstall`,
+			);
+		} catch {
+			// fall through to .exe
+		}
+		// Also check .exe — some postinstall scripts (e.g. @ast-grep/cli) place a
+		// .exe directly without a .cmd wrapper
+		const exePath = `${localBase}.exe`;
+		try {
+			await fs.access(exePath);
+			if (await verifyToolBinary(exePath)) {
+				return exePath;
+			}
+			logSessionStart(
+				`auto-install verify: ${exePath} exists but is broken, will reinstall`,
+			);
+		} catch {
+			// fall through to extensionless
+		}
+	}
+	try {
+		await fs.access(localBase);
+		if (await verifyToolBinary(localBase)) {
+			return localBase;
+		}
+		logSessionStart(
+			`auto-install verify: ${localBase} exists but is broken, will reinstall`,
+		);
+	} catch {
+		// fall through to global checks
+	}
+
+	// For github-strategy tools, prefer managed install (~/.pi-lens/bin/) over PATH.
+	// Managed installs are known-good binaries that pi-lens downloaded as a fallback
+	// when a PATH-resolved tool was broken or missing. Checking before PATH ensures
+	// force-reinstall flows find the newly downloaded binary.
+	if (tool.installStrategy === "github") {
+		const githubPath = await findGitHubToolPath(tool.binaryName || tool.id);
+		if (githubPath) return githubPath;
+	}
+
+	// Check if global
+	if (await isCommandAvailable(tool.checkCommand, tool.checkArgs)) {
+		return tool.checkCommand;
+	}
+
+	if (tool.installStrategy === "npm") {
+		const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id);
+		if (npmPath) {
+			return npmPath;
+		}
+	}
+
+	// For pip tools, also probe user-level script locations
+	if (tool.installStrategy === "pip") {
+		const pipPath = await findPipUserToolPath(tool.binaryName || tool.id);
+		if (pipPath) {
+			return pipPath;
+		}
+	}
+
+	return undefined;
+}
+
+async function findGitHubToolPath(
+	binaryName: string,
+): Promise<string | undefined> {
+	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 {
+			// continue
+		}
+	}
+	return undefined;
+}
+
+function hasExecutableExtension(name: string): boolean {
+	return /\.(exe|bat|cmd|ps1)$/i.test(name);
+}
+
+function getGitHubInstalledBinaryName(
+	binaryName: string,
+	platform: string,
+	assetName: string,
+): string {
+	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: string,
+	platform: string,
+	assetName: string,
+): string[] {
+	if (platform !== "win32") return [binaryName];
+	if (hasExecutableExtension(binaryName)) return [binaryName];
+	const candidates = new Set<string>();
+	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: string,
+): Promise<string | undefined> {
+	const isWindows = process.platform === "win32";
+	const binDirs = await getNpmGlobalBinCandidates();
+
+	for (const dir of binDirs) {
+		const candidates = isWindows
+			? [
+					path.join(dir, `${binaryName}.cmd`),
+					path.join(dir, `${binaryName}.exe`),
+					path.join(dir, binaryName),
+				]
+			: [path.join(dir, binaryName)];
+
+		for (const candidate of candidates) {
+			try {
+				await fs.access(candidate);
+				if (await verifyToolBinary(candidate)) {
+					return candidate;
+				}
+			} catch {
+				// continue
+			}
+		}
+	}
+
+	return undefined;
+}
+
+async function getNpmGlobalBinCandidates(): Promise<string[]> {
+	const dirs: string[] = [];
+	const seen = new Set<string>();
+
+	const add = (value: string | undefined): void => {
+		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"));
+	}
+
+	const pm = process.platform === "win32" ? "npm.cmd" : "npm";
+	const prefix = await new Promise<string>((resolve) => {
+		const proc = spawn(pm, ["config", "get", "prefix"], {
+			stdio: ["ignore", "pipe", "pipe"],
+			shell: process.platform === "win32",
+		});
+
+		let stdout = "";
+		proc.stdout?.on("data", (data: Buffer | string) => (stdout += data));
+		proc.on("exit", (code) => resolve(code === 0 ? stdout.trim() : ""));
+		proc.on("error", () => resolve(""));
+	});
+
+	if (prefix) {
+		add(process.platform === "win32" ? prefix : path.join(prefix, "bin"));
+	}
+
+	return dirs;
+}
+
+async function findPipUserToolPath(
+	binaryName: string,
+): Promise<string | undefined> {
+	const isWindows = process.platform === "win32";
+	const userBaseCandidates = await getPythonUserBaseCandidates();
+
+	for (const userBase of userBaseCandidates) {
+		const scriptDirs: string[] = [
+			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 {
+				// ignore
+			}
+		}
+
+		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)) {
+						return candidate;
+					}
+				} catch {
+					// continue
+				}
+			}
+		}
+	}
+
+	return undefined;
+}
+
+async function getPythonUserBaseCandidates(): Promise<string[]> {
+	const candidates: string[] = [];
+	const seen = new Set<string>();
+
+	const add = (value: string | undefined): void => {
+		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: Array<{ command: string; args: string[] }> =
+		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<string>((resolve) => {
+			const isWin = process.platform === "win32";
+			// Bake args into command string when shell:true on Windows to avoid DEP0190.
+			const spawnCmd = isWin
+				? [probe.command, ...probe.args].join(" ")
+				: probe.command;
+			const proc = spawn(spawnCmd, isWin ? [] : probe.args, {
+				stdio: ["ignore", "pipe", "pipe"],
+				shell: isWin,
+			});
+
+			let stdout = "";
+			proc.stdout?.on("data", (data: Buffer | string) => (stdout += data));
+			proc.on("exit", (code) => resolve(code === 0 ? stdout.trim() : ""));
+			proc.on("error", () => resolve(""));
+		});
+		add(userBase);
+	}
+
+	return candidates;
+}
+
+// --- Installation Functions
+
+/**
+ * Fetch a URL, following up to `maxRedirects` redirects.
+ * Returns the raw Buffer of the response body.
+ */
+function httpsGet(url: string, maxRedirects = 5): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		https
+			.get(url, { headers: { "User-Agent": "pi-lens/1.0" } }, (res) => {
+				if (
+					res.statusCode &&
+					res.statusCode >= 300 &&
+					res.statusCode < 400 &&
+					res.headers.location
+				) {
+					if (maxRedirects === 0)
+						return reject(new Error("Too many redirects"));
+					return resolve(httpsGet(res.headers.location, maxRedirects - 1));
+				}
+				if (res.statusCode !== 200) {
+					res.resume();
+					return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+				}
+				const chunks: Buffer[] = [];
+				res.on("data", (chunk: Buffer) => chunks.push(chunk));
+				res.on("end", () => resolve(Buffer.concat(chunks)));
+				res.on("error", reject);
+			})
+			.on("error", reject);
+	});
+}
+
+/**
+ * Run a shell command and return true on exit code 0.
+ */
+function runCommand(
+	command: string,
+	args: string[],
+	cwd: string,
+): Promise<boolean> {
+	return new Promise((resolve) => {
+		const proc = spawn(command, args, {
+			cwd,
+			stdio: "ignore",
+			shell: process.platform === "win32",
+		});
+		proc.on("exit", (code) => resolve(code === 0));
+		proc.on("error", () => resolve(false));
+	});
+}
+
+/**
+ * Download and install a tool from a GitHub release.
+ * Returns the path to the installed binary, or undefined on failure.
+ */
+async function installGitHubTool(
+	tool: ToolDefinition,
+): Promise<string | undefined> {
+	const spec = tool.github;
+	if (!spec) return undefined;
+
+	const platform = process.platform; // "linux" | "darwin" | "win32"
+	const arch = process.arch; // "x64" | "arm64" | ...
+	const assetSubstring = spec.assetMatch(platform, arch);
+	if (!assetSubstring) {
+		logSessionStart(
+			`github-install ${tool.id}: unsupported platform=${platform} arch=${arch}`,
+		);
+		return undefined;
+	}
+
+	// Fetch latest release metadata from GitHub API
+	logSessionStart(
+		`github-install ${tool.id}: fetching release metadata from ${spec.repo}`,
+	);
+	let releaseJson: {
+		tag_name?: string;
+		assets: Array<{ name: string; browser_download_url: string }>;
+	};
+	try {
+		const body = await httpsGet(
+			`https://api.github.com/repos/${spec.repo}/releases/latest`,
+		);
+		releaseJson = JSON.parse(body.toString("utf8"));
+	} catch (err) {
+		logSessionStart(
+			`github-install ${tool.id}: release fetch failed: ${(err as Error).message}`,
+		);
+		return undefined;
+	}
+
+	const asset =
+		releaseJson.assets.find((a) => a.name.includes(assetSubstring)) ??
+		deriveHashiCorpReleaseAsset(tool, releaseJson.tag_name, assetSubstring);
+	if (!asset) {
+		logSessionStart(
+			`github-install ${tool.id}: no asset matched "${assetSubstring}"`,
+		);
+		return undefined;
+	}
+
+	logSessionStart(`github-install ${tool.id}: downloading ${asset.name}`);
+	debugLog(
+		`[github] downloading ${asset.name} from ${asset.browser_download_url}`,
+	);
+
+	// Download the asset
+	const downloadStart = Date.now();
+	let assetBuffer: Buffer;
+	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 as Error).message}`,
+		);
+		return undefined;
+	}
+
+	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")) {
+			// Bare gzip (e.g. rust-analyzer-x86_64-unknown-linux-gnu.gz) — decompress directly
+			const decompressed = await new Promise<Buffer>((resolve, reject) => {
+				const gunzip = createGunzip();
+				const chunks: Buffer[] = [];
+				gunzip.on("data", (chunk: Buffer) => chunks.push(chunk));
+				gunzip.on("end", () => resolve(Buffer.concat(chunks)));
+				gunzip.on("error", reject);
+				gunzip.end(assetBuffer);
+			});
+			await fs.writeFile(destPath, decompressed, { mode: 0o755 });
+		} else if (assetName.endsWith(".tar.gz") || assetName.endsWith(".tar.xz")) {
+			// Write archive to temp file, extract with system tar
+			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, "--strip-components=1"],
+				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 undefined;
+			}
+
+			// Find the binary inside extracted dir
+			const srcBinary = path.join(tmpDir, spec.binaryInArchive ?? binaryName);
+			await fs.rename(srcBinary, destPath);
+			await fs.rm(tmpDir, { recursive: true, force: true });
+			if (!isWindows) await fs.chmod(destPath, 0o750);
+		} else if (assetName.endsWith(".zip")) {
+			// Write zip to temp, extract with unzip (Linux/macOS) or Expand-Archive (Windows)
+			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 undefined;
+			}
+
+			// Find binary — may be at root or inside a subdir
+			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 undefined;
+			}
+			await fs.rename(srcBinary, destPath);
+			await fs.rm(tmpDir, { recursive: true, force: true });
+			if (!isWindows) await fs.chmod(destPath, 0o750);
+		} else {
+			// Bare binary (e.g. shfmt_*_linux_amd64)
+			await fs.writeFile(destPath, assetBuffer, { mode: 0o755 });
+		}
+	} catch (err) {
+		logSessionStart(
+			`github-install ${tool.id}: install failed: ${(err as Error).message}`,
+		);
+		return undefined;
+	}
+
+	debugLog(`[github] installed ${tool.name} → ${destPath}`);
+	logSessionStart(`github-install ${tool.id}: installed → ${destPath}`);
+	return destPath;
+}
+
+/** Recursively find the first matching file under a directory. */
+async function findFirstFileRecursive(
+	dir: string,
+	names: string[],
+): Promise<string | undefined> {
+	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 undefined;
+}
+
+/**
+ * Install an npm package tool
+ */
+/**
+ * Packages that require postinstall scripts to download native binaries.
+ * All others get --ignore-scripts to prevent arbitrary code execution during install.
+ */
+const NEEDS_POSTINSTALL = new Set([
+	"@biomejs/biome",
+	"@ast-grep/cli", // postinstall copies platform binary (ast-grep.exe/sg.exe) into place
+	"@ast-grep/napi",
+	"esbuild",
+	"intelephense", // postinstall fetches platform binary; --ignore-scripts breaks install
+]);
+
+async function installNpmTool(
+	packageName: string,
+	binaryName: string,
+): Promise<string | undefined> {
+	try {
+		// Ensure tools directory exists
+		await fs.mkdir(TOOLS_DIR, { recursive: true });
+
+		// Create a minimal package.json if it doesn't exist
+		const packageJsonPath = path.join(TOOLS_DIR, "package.json");
+		try {
+			await fs.access(packageJsonPath);
+		} catch {
+			await fs.writeFile(
+				packageJsonPath,
+				JSON.stringify({ name: "pi-lens-tools", version: "1.0.0" }, null, 2),
+			);
+		}
+
+		// Install via npm or bun (use .cmd on Windows)
+		const isWindows = process.platform === "win32";
+		let pm = isWindows ? "npm.cmd" : "npm";
+		if (process.env.BUN_INSTALL) {
+			pm = isWindows ? "bun.exe" : "bun";
+		}
+		// Use --ignore-scripts unless the package explicitly needs postinstall
+		// (e.g. biome downloads a platform-specific native binary via postinstall).
+		const needsScripts = NEEDS_POSTINSTALL.has(packageName);
+		const baseInstallArgs = needsScripts
+			? ["install", packageName]
+			: ["install", "--ignore-scripts", packageName];
+
+		const INSTALL_TIMEOUT_MS = 120_000;
+		const runInstallAttempt = async (
+			args: string[],
+		): Promise<{ ok: boolean; stderr: string }> =>
+			new Promise((resolve) => {
+				const proc = spawn(pm, args, {
+					cwd: TOOLS_DIR,
+					stdio: ["ignore", "pipe", "pipe"],
+					shell: isWindows, // Required for .cmd files on Windows
+				});
+
+				let stderr = "";
+				proc.stderr?.on("data", (data) => (stderr += data));
+
+				const timer = setTimeout(() => {
+					proc.kill();
+					resolve({
+						ok: false,
+						stderr: `install timed out after ${INSTALL_TIMEOUT_MS / 1000}s`,
+					});
+				}, INSTALL_TIMEOUT_MS);
+
+				proc.on("exit", (code) => {
+					clearTimeout(timer);
+					resolve({ ok: code === 0, stderr });
+				});
+				proc.on("error", (err) => {
+					clearTimeout(timer);
+					resolve({ ok: false, stderr: err.message });
+				});
+			});
+
+		let outcome = await runInstallAttempt(baseInstallArgs);
+
+		const isNpm = pm === "npm" || pm === "npm.cmd";
+		const erResolve =
+			outcome.ok === false &&
+			/npm\s+error\s+ERESOLVE|\bERESOLVE\b|could not resolve/i.test(
+				outcome.stderr,
+			);
+
+		if (isNpm && erResolve) {
+			const retryArgs = needsScripts
+				? ["install", "--legacy-peer-deps", packageName]
+				: ["install", "--ignore-scripts", "--legacy-peer-deps", packageName];
+			logSessionStart(
+				`auto-install npm ${packageName}: retry with --legacy-peer-deps after ERESOLVE`,
+			);
+			outcome = await runInstallAttempt(retryArgs);
+		}
+
+		if (!outcome.ok) {
+			throw new Error(`Failed to install ${packageName}: ${outcome.stderr}`);
+		}
+
+		const binPath = path.join(TOOLS_DIR, "node_modules", ".bin", binaryName);
+
+		// Make executable on Unix
+		if (process.platform !== "win32") {
+			try {
+				await fs.chmod(binPath, 0o750);
+			} catch {
+				/* ignore */
+			}
+		}
+
+		// Brief delay — lets npm postinstall scripts finish writing bin wrappers
+		// before we stat/exec them (eliminates a race on slow Windows I/O).
+		await new Promise((r) => setTimeout(r, 500));
+
+		// Verify the binary actually works, retrying with backoff to handle
+		// postinstall scripts that complete asynchronously after npm exits 0.
+		debugLog(`Verifying ${binaryName}...`);
+		let isValid = false;
+		for (let attempt = 1; attempt <= 3; attempt++) {
+			isValid = await verifyToolBinary(binPath);
+			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) {
+			logSessionStart(
+				`auto-install ${packageName}: installed but verification failed, cleaning up`,
+			);
+			// Clean up the broken installation
+			try {
+				const packagePath = path.join(TOOLS_DIR, "node_modules", packageName);
+				await fs.rm(packagePath, { recursive: true, force: true });
+				await fs.rm(binPath, { force: true });
+				if (isWindows) {
+					await fs.rm(`${binPath}.cmd`, { force: true });
+					await fs.rm(`${binPath}.ps1`, { force: true });
+				}
+			} catch {
+				/* ignore cleanup errors */
+			}
+			return undefined;
+		}
+
+		return binPath;
+	} catch (err) {
+		logSessionStart(
+			`auto-install npm ${packageName}: exception: ${(err as Error).message}`,
+		);
+		return undefined;
+	}
+}
+/**
+ * Install a pip package tool
+ */
+async function installPipTool(
+	packageName: string,
+): Promise<string | undefined> {
+	try {
+		const isWindows = process.platform === "win32";
+		const pipCandidates = isWindows
+			? [
+					{ command: "pip", args: ["install", "--user", packageName] },
+					{
+						command: "py",
+						args: ["-m", "pip", "install", "--user", packageName],
+					},
+					{
+						command: "python",
+						args: ["-m", "pip", "install", "--user", packageName],
+					},
+				]
+			: [
+					{ command: "pip3", args: ["install", "--user", packageName] },
+					{ command: "pip", args: ["install", "--user", packageName] },
+					{
+						command: "python3",
+						args: ["-m", "pip", "install", "--user", packageName],
+					},
+					{
+						command: "python",
+						args: ["-m", "pip", "install", "--user", packageName],
+					},
+				];
+
+		let lastError = "";
+		for (const candidate of pipCandidates) {
+			const outcome = await new Promise<{ ok: boolean; error: string }>(
+				(resolve) => {
+					const proc = spawn(candidate.command, candidate.args, {
+						stdio: ["ignore", "pipe", "pipe"],
+						shell: isWindows, // Required for .cmd files on Windows
+					});
+
+					let stderr = "";
+					proc.stderr?.on("data", (data) => (stderr += data));
+
+					proc.on("exit", (code) => {
+						if (code === 0) {
+							resolve({ ok: true, error: "" });
+						} else {
+							resolve({ ok: false, error: stderr.trim() });
+						}
+					});
+
+					proc.on("error", (err) => {
+						resolve({ ok: false, error: err.message });
+					});
+				},
+			);
+
+			if (outcome.ok) {
+				// Ensure user-level scripts directory is available in current process PATH.
+				// This helps tools installed via `pip install --user` become immediately callable.
+				const userBaseResult = await new Promise<string>((resolve) => {
+					const probe = spawn(
+						candidate.command,
+						["-m", "site", "--user-base"],
+						{
+							stdio: ["ignore", "pipe", "pipe"],
+							shell: isWindows,
+						},
+					);
+					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: string[] = [
+						path.join(userBaseResult, isWindows ? "Scripts" : "bin"),
+					];
+
+					if (isWindows) {
+						// Some Python setups report USER_BASE as ...\Roaming\Python,
+						// while scripts live in ...\Roaming\Python\PythonXY\Scripts.
+						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 {
+							// ignore
+						}
+					}
+
+					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 as Error).message}`,
+		);
+		return undefined;
+	}
+}
+
+async function installGemTool(
+	packageName: string,
+): Promise<string | undefined> {
+	try {
+		const isWindows = process.platform === "win32";
+		const outcome = await new Promise<{ ok: boolean; error: string }>(
+			(resolve) => {
+				const proc = spawn("gem", ["install", packageName, "--no-document"], {
+					stdio: ["ignore", "pipe", "pipe"],
+					shell: isWindows,
+				});
+
+				let stderr = "";
+				proc.stderr?.on("data", (data) => (stderr += data));
+				proc.on("exit", (code) => {
+					resolve({ ok: code === 0, error: stderr.trim() });
+				});
+				proc.on("error", (err) => {
+					resolve({ ok: false, error: err.message });
+				});
+			},
+		);
+
+		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 as Error).message}`,
+		);
+		return undefined;
+	}
+}
+
+/**
+ * Install a tool by ID
+ */
+export async function installTool(toolId: string): Promise<boolean> {
+	const tool = TOOLS.find((t) => t.id === toolId);
+	if (!tool) {
+		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);
+				const ok = npmPath !== undefined;
+				logSessionStart(
+					`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`,
+				);
+				return ok;
+			}
+
+			case "pip": {
+				if (!tool.packageName) return false;
+				const pipPath = await installPipTool(tool.packageName);
+				const ok = pipPath !== undefined;
+				logSessionStart(
+					`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`,
+				);
+				return ok;
+			}
+
+			case "gem": {
+				if (!tool.packageName) return false;
+				const gemPath = await installGemTool(tool.packageName);
+				const ok = gemPath !== undefined;
+				logSessionStart(
+					`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`,
+				);
+				return ok;
+			}
+
+			case "github": {
+				if (!tool.github) return false;
+				const ghPath = await installGitHubTool(tool);
+				const ok = ghPath !== undefined;
+				logSessionStart(
+					`auto-install ${tool.id}: ${ok ? "success" : "failed"} (${Date.now() - startedAt}ms)`,
+				);
+				return ok;
+			}
+
+			default:
+				logSessionStart(`auto-install ${tool.id}: unsupported strategy`);
+				return false;
+		}
+	} catch (err) {
+		logSessionStart(
+			`auto-install ${tool.id}: exception ${(err as Error).message} (${Date.now() - startedAt}ms)`,
+		);
+		return false;
+	}
+}
+
+/**
+ * Ensure a tool is installed (check first, install if missing)
+ */
+export async function ensureTool(
+	toolId: string,
+	opts?: { forceReinstall?: boolean },
+): Promise<string | undefined> {
+	// forceReinstall: nuke caches, download from managed source, skip PATH entirely.
+	// Used when a PATH-resolved tool proves broken at launch (e.g. broken symlink).
+	if (opts?.forceReinstall) {
+		const ensureStartMs = Date.now();
+		logSessionStart(
+			`auto-install ensure ${toolId}: force reinstall — clearing caches`,
+		);
+
+		// Clear in-memory session cache
+		resolvedPathCache.delete(toolId);
+
+		// Clear persistent probe cache entry so getToolPath won't return stale PATH result
+		try {
+			const probeCache = await readProbeCache();
+			delete probeCache[toolId];
+			_probeCacheDirty = true;
+			scheduleProbeFlush();
+		} catch {
+			// best-effort
+		}
+
+		// Force download
+		const installed = await installTool(toolId);
+		if (!installed) {
+			logSessionStart(
+				`auto-install ensure ${toolId}: force reinstall failed (${Date.now() - ensureStartMs}ms)`,
+			);
+			return undefined;
+		}
+
+		// Find the newly installed binary (github-local check now comes before PATH)
+		const result = await getToolPath(toolId);
+		if (result) {
+			resolvedPathCache.set(toolId, result);
+			void updateProbeCache(toolId, result);
+			logSessionStart(
+				`auto-install ensure ${toolId}: force reinstall success at ${result} (${Date.now() - ensureStartMs}ms)`,
+			);
+		}
+		return result;
+	}
+
+	// Fast path 1: in-memory session cache — no I/O.
+	const cached = resolvedPathCache.get(toolId);
+	if (cached) return cached;
+
+	// Fast path 2: persistent probe cache — fs.access + stat, no process spawn.
+	const diskCached = await checkProbeCache(toolId);
+	if (diskCached) {
+		resolvedPathCache.set(toolId, diskCached);
+		logSessionStart(
+			`auto-install ensure ${toolId}: probe cache hit → ${diskCached}`,
+		);
+		return diskCached;
+	}
+
+	// Coalesce the whole ensure operation, not just installation. Most startup
+	// duplicates race while checking already-installed tools, before installTool()
+	// would ever run.
+	const inFlight = ensureInFlight.get(toolId);
+	if (inFlight) {
+		logSessionStart(
+			`auto-install ensure ${toolId}: waiting for in-flight ensure`,
+		);
+		return inFlight;
+	}
+
+	const ensureStartMs = Date.now();
+	const ensurePromise = (async () => {
+		logSessionStart(`auto-install ensure ${toolId}: start`);
+
+		// Check if already installed.
+		const existingPath = await getToolPath(toolId);
+		if (existingPath) {
+			resolvedPathCache.set(toolId, existingPath);
+			void updateProbeCache(toolId, existingPath);
+			logSessionStart(
+				`auto-install ensure ${toolId}: already available at ${existingPath} (${Date.now() - ensureStartMs}ms)`,
+			);
+			return existingPath;
+		}
+
+		const installed = await installTool(toolId);
+		if (!installed) {
+			logSessionStart(
+				`auto-install ensure ${toolId}: unavailable (${Date.now() - ensureStartMs}ms)`,
+			);
+			return undefined;
+		}
+
+		const result = await getToolPath(toolId);
+		if (result) {
+			resolvedPathCache.set(toolId, result);
+			void updateProbeCache(toolId, result);
+			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(toolId, ensurePromise);
+	try {
+		return await ensurePromise;
+	} finally {
+		ensureInFlight.delete(toolId);
+	}
+}
+
+// --- Integration Helpers ---
+
+/**
+ * Get environment with tool paths added
+ */
+export async function getToolEnvironment(): Promise<NodeJS.ProcessEnv> {
+	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: NodeJS.ProcessEnv = {
+		...process.env,
+		PATH: augmentedPath,
+	};
+
+	if (process.platform === "win32") {
+		env.Path = augmentedPath;
+	}
+
+	return env;
+}
+
+// --- Status Check ---
+
+/**
+ * Check status of all managed tools
+ */
+export async function checkAllTools(): Promise<
+	Array<{ id: string; name: string; installed: boolean; path?: string }>
+> {
+	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: string): boolean {
+	return TOOLS.some((tool) => tool.id === toolId);
+}
+
+export const GITHUB_TOOLS = [
+	"shellcheck",
+	"shfmt",
+	"rust-analyzer",
+	"golangci-lint",
+	"ktlint",
+	"actionlint",
+	"tflint",
+	"terraform-ls",
+	"zls",
+] as const;
+export type GitHubToolId = (typeof GITHUB_TOOLS)[number];
+
+/**
+ * Resolve the GitHub asset filename substring for a tool on a given platform/arch.
+ * Returns undefined if the tool has no GitHub spec or no asset for the platform.
+ * Exported for testing only.
+ */
+export function resolveGitHubAsset(
+	toolId: GitHubToolId,
+	platform: string,
+	arch: string,
+): string | undefined {
+	const tool = TOOLS.find((t) => t.id === toolId);
+	return tool?.github?.assetMatch(platform, arch);
+}
+
+export function resolveGitHubInstalledBinaryName(
+	toolId: GitHubToolId,
+	platform: string,
+	assetName: string,
+): string | undefined {
+	const tool = TOOLS.find((t) => t.id === toolId);
+	if (!tool) return undefined;
+	return getGitHubInstalledBinaryName(
+		tool.binaryName ?? tool.id,
+		platform,
+		assetName,
+	);
+}
+
+export function resolveGitHubArchiveBinaryCandidates(
+	toolId: GitHubToolId,
+	platform: string,
+	assetName: string,
+): string[] | undefined {
+	const tool = TOOLS.find((t) => t.id === toolId);
+	if (!tool) return undefined;
+	const binaryName = tool.github?.binaryInArchive ?? tool.binaryName ?? tool.id;
+	return getArchiveBinaryCandidates(binaryName, platform, assetName);
+}
+
+type DownloadAsset = { name: string; browser_download_url: string };
+
+function deriveHashiCorpReleaseAsset(
+	tool: ToolDefinition,
+	tagName: string | undefined,
+	assetSubstring: string,
+): DownloadAsset | undefined {
+	const product = tool.github?.hashiCorpReleaseProduct;
+	if (!product || !tagName) return undefined;
+
+	const version = tagName.replace(/^v/, "").trim();
+	if (!version) return undefined;
+
+	const assetName = `${product}_${version}_${assetSubstring}`;
+	return {
+		name: assetName,
+		browser_download_url: `https://releases.hashicorp.com/${product}/${version}/${assetName}`,
+	};
+}
+
+export function resolveDerivedHashiCorpReleaseAsset(
+	toolId: string,
+	tagName: string,
+	platform: string,
+	arch: string,
+): DownloadAsset | undefined {
+	const tool = TOOLS.find((t) => t.id === toolId);
+	if (!tool) return undefined;
+	const assetSubstring = tool.github?.assetMatch(platform, arch);
+	if (!assetSubstring) return undefined;
+	return deriveHashiCorpReleaseAsset(tool, tagName, assetSubstring);
+}