@cortexkit/aft-bridge 0.59.0 → 0.61.0

package/dist/lsp-github-install.js

@@ -0,0 +1,1455 @@
+/**
+ * GitHub-release auto-installer for LSP servers (Pattern C).
+ *
+ * Cache layout under `<aft-cache-root>/lsp-binaries/`:
+ *
+ *   <id>/
+ *     bin/<binary>                  ← standalone binary only
+ *     extracted/                    ← intact distribution and runtime resources
+ *     .aft-version-check            ← JSON: { last_checked, latest_eligible }
+ *     .aft-installing               ← lockfile while a download/extract runs
+ *
+ * `lsp_paths_extra` receives the executable's real directory: `bin/` for
+ * standalone servers, or the in-tree binary directory for distributions.
+ *
+ * Extraction containment:
+ *   1. Download to `<id>/<asset-name>` with a hard size cap.
+ *   2. Extract into a staging dir `<id>/extracted.staging-<rand>/`.
+ *   3. Walk the staging tree and reject any entry that is a symlink, hardlink,
+ *      or whose canonical path escapes the staging root.
+ *   4. Check the staged executable and runtime, then rename the old extraction
+ *      aside and swap the staged tree in, restoring the old tree if the swap fails.
+ *   5. Stage dir is always cleaned up — success or failure.
+ *
+ * GitHub pin resolution:
+ *   When `lsp.versions: { "owner/repo": "X" }` is set, we use GitHub's
+ *   `/releases/tags/<tag>` endpoint directly (with `v`-prefix tolerance)
+ *   instead of relying on the broader `/releases?per_page=30` probe. The
+ *   probe is for "what is the latest eligible version" — not "is this
+ *   specific pinned tag valid".
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, copyFileSync, createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { cachedFileSha256Sync, writeStampedFileDigest } from "./binary-identity.js";
+import { getAftLspBinariesDir } from "./cache-paths.js";
+import { execFile, spawn } from "./child-process.js";
+import { assertSafeVersion, isSafeVersion, probeGithubReleases, stripTagV, } from "./lsp-github-probe.js";
+import { detectHostPlatform, GITHUB_LSP_TABLE, } from "./lsp-github-table.js";
+import { relativePathEscapesRoot } from "./path-display.js";
+import { windowsTarExecutable } from "./tar-executable.js";
+/** Bind host logging, shared-cache leases and project scanning without forking installation policy. */
+export function createGithubInstaller(services) {
+    const { log, warn, error, readVersionCheck, writeVersionCheck, shouldRecheckVersion, withInstallLock, acquireInstallLock, hasRootMarker, relevantExtensionsInProject, } = services;
+    /* ─────────────────────────── cache layout ─────────────────────────── */
+    function ghCacheRoot() {
+        return getAftLspBinariesDir();
+    }
+    function ghPackageDir(spec) {
+        return join(ghCacheRoot(), spec.id);
+    }
+    function ghBinDir(spec) {
+        const platform = detectHostPlatform()?.platform ?? "linux";
+        return dirname(ghBinaryPath(spec, platform));
+    }
+    function ghExtractDir(spec) {
+        return join(ghPackageDir(spec), "extracted");
+    }
+    const INSTALLED_META_FILE = ".aft-installed";
+    const INSTALL_FAILED_FILE = ".aft-install-failed.json";
+    const INSTALL_FAILURE_BACKOFF_MS = 6 * 60 * 60 * 1000;
+    // Downloads and extraction can take several minutes, but a background refresh
+    // should not wait forever for a lock another process may have abandoned.
+    const INSTALL_LOCK_WAIT_MS = 10 * 60 * 1000;
+    const INSTALL_LOCK_POLL_INTERVAL_MS = 1_000;
+    const INSTALL_LOCK_WAIT_TIMEOUT_REASON = "install lock held by another process for 10 minutes";
+    function installFailureMarkerPath(spec) {
+        return join(ghPackageDir(spec), INSTALL_FAILED_FILE);
+    }
+    function readInstallFailureMarker(spec) {
+        try {
+            const marker = JSON.parse(readFileSync(installFailureMarkerPath(spec), "utf8"));
+            if (typeof marker.release !== "string" ||
+                typeof marker.sha256 !== "string" ||
+                typeof marker.error !== "string" ||
+                typeof marker.at !== "string" ||
+                !Number.isFinite(Date.parse(marker.at))) {
+                return null;
+            }
+            return marker;
+        }
+        catch {
+            return null;
+        }
+    }
+    function writeInstallFailureMarker(spec, release, sha256, installError) {
+        const path = installFailureMarkerPath(spec);
+        const markerError = installError.replace(/\s+/g, " ").trim();
+        const tempPath = `${path}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(tempPath, `${JSON.stringify({ release, sha256, error: markerError, at: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600 });
+            renameSync(tempPath, path);
+        }
+        catch (err) {
+            try {
+                rmSync(tempPath, { force: true });
+            }
+            catch { }
+            warn(`[lsp] could not write install failure marker ${path}: ${err}`);
+        }
+    }
+    function clearInstallFailureMarker(spec) {
+        try {
+            rmSync(installFailureMarkerPath(spec), { force: true });
+        }
+        catch { }
+    }
+    function sameRelease(left, right) {
+        return stripTagV(left) === stripTagV(right);
+    }
+    function isFreshInstallFailure(marker) {
+        return Math.abs(Date.now() - Date.parse(marker.at)) < INSTALL_FAILURE_BACKOFF_MS;
+    }
+    /** Final binary path under our cache. */
+    function ghBinaryPath(spec, platform) {
+        const meta = readGithubInstalledMetaIn(ghPackageDir(spec));
+        if (spec.layout === "distribution" &&
+            meta?.layout === "distribution" &&
+            isSafeVersion(meta.version)) {
+            const arch = detectHostPlatform()?.arch ?? "x64";
+            return join(ghExtractDir(spec), spec.binaryPathInArchive(platform, arch, stripTagV(meta.version)));
+        }
+        const ext = platform === "win32" ? ".exe" : "";
+        return join(ghPackageDir(spec), "bin", `${spec.binary}${ext}`);
+    }
+    function isGithubInstalled(spec, platform) {
+        for (const candidate of ghBinaryCandidates(spec, platform)) {
+            try {
+                if (statSync(join(ghBinDir(spec), candidate)).isFile())
+                    return true;
+            }
+            catch {
+                // Try the next Windows shim extension.
+            }
+        }
+        return false;
+    }
+    function ghBinaryCandidates(spec, platform) {
+        if (platform !== "win32")
+            return [spec.binary];
+        return [spec.binary, `${spec.binary}.cmd`, `${spec.binary}.exe`, `${spec.binary}.bat`];
+    }
+    function readGithubInstalledMetaIn(installDir) {
+        try {
+            const path = join(installDir, INSTALLED_META_FILE);
+            if (!statSync(path).isFile())
+                return null;
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (typeof parsed.version !== "string" || parsed.version.length === 0)
+                return null;
+            return {
+                version: parsed.version,
+                installedAt: typeof parsed.installedAt === "string" ? parsed.installedAt : "",
+                ...(typeof parsed.sha256 === "string" && parsed.sha256.length > 0
+                    ? { sha256: parsed.sha256 }
+                    : {}),
+                ...(typeof parsed.binarySha256 === "string" && parsed.binarySha256.length > 0
+                    ? { binarySha256: parsed.binarySha256 }
+                    : {}),
+                ...(typeof parsed.smoke?.binarySha256 === "string" &&
+                    (parsed.smoke.verdict === "passed" || parsed.smoke.verdict === "timeout")
+                    ? { smoke: parsed.smoke }
+                    : {}),
+                ...(parsed.layout === "distribution" || parsed.layout === "standalone"
+                    ? { layout: parsed.layout }
+                    : {}),
+                ...(typeof parsed.archiveSha256 === "string" && parsed.archiveSha256.length > 0
+                    ? { archiveSha256: parsed.archiveSha256 }
+                    : {}),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    function writeGithubInstalledMetaIn(installDir, version, binarySha256, archiveSha256, layout, smoke) {
+        try {
+            mkdirSync(installDir, { recursive: true });
+            const meta = {
+                version,
+                installedAt: new Date().toISOString(),
+                sha256: binarySha256,
+                binarySha256,
+                ...(archiveSha256 ? { archiveSha256 } : {}),
+                ...(layout ? { layout } : {}),
+                ...(smoke ? { smoke } : {}),
+            };
+            writeFileSync(join(installDir, INSTALLED_META_FILE), JSON.stringify(meta), "utf8");
+        }
+        catch (err) {
+            warn(`[lsp] failed to write github installed metadata in ${installDir}: ${err}`);
+        }
+    }
+    /* ─────────────────────────── per-call config ─────────────────────────── */
+    /* ─────────────────────────── safety constants ─────────────────────────── */
+    /**
+     * Hard cap on a single LSP-binary download (GitHub downloads are otherwise
+     * unbounded).
+     *
+     * 256 MB. The largest currently-shipped LSP we install is `clangd` at
+     * around 60 MB extracted (compressed less). The next-largest is
+     * `lua-language-server` at ~20 MB. Pinning at 256 MB leaves a 4× headroom
+     * for future-proofing while still aborting absurd payloads (TB-sized
+     * malicious responses, DoS via slow drip).
+     *
+     * If a legitimate release ever exceeds this, we'll bump it deliberately
+     * and the version-pin escape hatch lets users opt back in via `lsp.versions`.
+     */
+    const MAX_DOWNLOAD_BYTES = 256 * 1024 * 1024;
+    /**
+     * Maximum total uncompressed size for the extracted contents of one LSP
+     * archive (1 GiB, ~4× the download cap to allow for typical compression).
+     *
+     * Even with `MAX_DOWNLOAD_BYTES` capping the compressed
+     * payload, modern compressors can achieve very high ratios on uniform
+     * data — a 256 MB ZIP can decompress to dozens of GBs of zeros and fill
+     * the user's disk before any individual file looks suspicious. This cap
+     * forces us to fail closed if extracted bytes ever exceed a reasonable
+     * upper bound for an LSP server bundle.
+     *
+     * Real LSP archives extract to far less than 1 GB — clangd ~150 MB,
+     * lua-language-server ~80 MB, zls ~30 MB. 1 GB leaves headroom for
+     * future bundles while making decompression bombs detectable.
+     */
+    const MAX_EXTRACT_BYTES = 1024 * 1024 * 1024;
+    /**
+     * Compute the SHA-256 of `path` by streaming.
+     *
+     * Enables always-log of every downloaded archive's hash
+     * (forensics) plus TOFU verification when the same tag is reinstalled.
+     * Streaming avoids loading the (potentially 200 MB) archive into memory.
+     */
+    function sha256OfFile(path) {
+        return new Promise((resolve, reject) => {
+            const hash = createHash("sha256");
+            const stream = createReadStream(path);
+            stream.on("error", reject);
+            stream.on("data", (chunk) => hash.update(chunk));
+            stream.on("end", () => resolve(hash.digest("hex")));
+        });
+    }
+    /**
+     * Hash a file synchronously in 1 MiB slices. Cached LSP binaries are tens to
+     * hundreds of MB; reading one whole into a single buffer costs that much memory
+     * at once.
+     */
+    function sha256OfFileSync(path) {
+        const hash = createHash("sha256");
+        const fd = openSync(path, "r");
+        try {
+            const buffer = Buffer.allocUnsafe(1024 * 1024);
+            let read = readSync(fd, buffer, 0, buffer.length, null);
+            while (read > 0) {
+                hash.update(buffer.subarray(0, read));
+                read = readSync(fd, buffer, 0, buffer.length, null);
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+        return hash.digest("hex");
+    }
+    /**
+     * Digests of cached binaries this process already hashed, keyed by path and
+     * guarded by the file's identity (device, inode, size, mtime, ctime).
+     *
+     * Startup validates every cached binary, and the refresh after background
+     * installs settle validates them all again. Without this memo each check read
+     * and hashed the whole binary once more. Any write, replacement or chmod
+     * changes the identity (ctime moves on every one of them), so a binary that
+     * changed since it was hashed is always hashed again.
+     */
+    const binaryDigestMemo = new Map();
+    let binaryHashCount = 0;
+    function fileIdentity(path) {
+        const info = statSync(path, { bigint: true });
+        return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+    }
+    function cachedBinarySha256(path) {
+        // Take the identity before reading so a write during hashing leaves a stale
+        // identity behind, which forces the next check to hash again.
+        const identity = fileIdentity(path);
+        const known = binaryDigestMemo.get(path);
+        if (known && known.identity === identity)
+            return known.digest;
+        const digest = cachedFileSha256Sync(path, () => {
+            binaryHashCount += 1;
+            return sha256OfFileSync(path);
+        });
+        binaryDigestMemo.set(path, { identity, digest });
+        return digest;
+    }
+    /** Test hook: how many cached-binary hashes this process has computed. */
+    function __githubBinaryHashCountForTests() {
+        return binaryHashCount;
+    }
+    /* ─────────────────────────── pin resolution ─────────────────────────── */
+    /**
+     * Fetch a single release by tag from GitHub's `/releases/tags/<tag>` endpoint.
+     *
+     * Critical for `lsp.versions` pin support: the broader release-list probe
+     * only sees the most recent ~30 releases, so any older pin (clangd 18, an
+     * old terraform, etc.) returns no assets and the install path silently
+     * fails. The release-by-tag endpoint accepts arbitrary tag strings and
+     * returns full asset metadata.
+     *
+     * We try the user's pin verbatim first, then with a `v` prefix added if
+     * missing. GitHub release tags are inconsistent (clangd uses `21.1.0`,
+     * lua-language-server uses `3.15.0`, zls uses `0.16.0`, terraform-ls uses
+     * `v0.36.5`). User pins should not need to know each project's convention.
+     *
+     * Returns null on probe failure so the caller can fall back to keeping
+     * any existing install.
+     */
+    async function fetchReleaseByTag(githubRepo, tag, fetchImpl, signal) {
+        const candidates = [];
+        candidates.push(tag);
+        if (!tag.startsWith("v")) {
+            candidates.push(`v${tag}`);
+        }
+        else {
+            candidates.push(tag.slice(1));
+        }
+        const headers = {
+            accept: "application/vnd.github+json",
+            "user-agent": "aft-bridge",
+            "x-github-api-version": "2022-11-28",
+        };
+        if (process.env.GITHUB_TOKEN) {
+            headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+        }
+        for (const candidate of candidates) {
+            const url = `https://api.github.com/repos/${githubRepo}/releases/tags/${encodeURIComponent(candidate)}`;
+            const timeout = controlledTimeoutSignal(15_000, signal);
+            try {
+                const res = await fetchJsonFollowingRedirects(url, headers, fetchImpl, timeout.signal);
+                if (res.status === 404)
+                    continue; // try next candidate
+                if (!res.ok) {
+                    warn(`[lsp] github release-by-tag ${githubRepo}@${candidate}: HTTP ${res.status}`);
+                    return null;
+                }
+                const json = (await res.json());
+                if (!json.tag_name || !Array.isArray(json.assets)) {
+                    warn(`[lsp] github release-by-tag ${githubRepo}@${candidate}: malformed response`);
+                    return null;
+                }
+                const assets = json.assets
+                    .filter((a) => typeof a.name === "string" && typeof a.browser_download_url === "string")
+                    .map((a) => ({
+                    name: a.name,
+                    url: a.browser_download_url,
+                    size: typeof a.size === "number" ? a.size : undefined,
+                }));
+                return { tag: json.tag_name, assets };
+            }
+            catch (err) {
+                if (signal?.aborted) {
+                    warn(`[lsp] github release-by-tag ${githubRepo}@${candidate}: aborted`);
+                    return null;
+                }
+                warn(`[lsp] github release-by-tag ${githubRepo}@${candidate}: ${err}`);
+                // try next candidate
+            }
+            finally {
+                timeout.cleanup();
+            }
+        }
+        return null;
+    }
+    async function fetchJsonFollowingRedirects(url, headers, fetchImpl, signal) {
+        const maxRedirects = 5;
+        let currentUrl = url;
+        for (let i = 0; i <= maxRedirects; i += 1) {
+            assertAllowedDownloadUrl(currentUrl);
+            const res = await fetchImpl(currentUrl, { headers, redirect: "manual", signal });
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get("location");
+                if (!location)
+                    throw new Error(`redirect status ${res.status} without Location`);
+                currentUrl = new URL(location, currentUrl).toString();
+                continue;
+            }
+            return res;
+        }
+        throw new Error(`too many redirects (>${maxRedirects})`);
+    }
+    /* ─────────────────────────── orchestrator ─────────────────────────── */
+    /**
+     * Resolve which GitHub release tag to install, honoring user pins,
+     * cached version checks, and the 7-day grace window.
+     */
+    async function resolveTargetTag(spec, config, fetchImpl, signal) {
+        // 1. User pin via `lsp.versions: { "clangd/clangd": "21.1.0" }`.
+        //
+        // Use GitHub's release-by-tag endpoint directly. The
+        // previous code tried to find the pin in the latest-releases probe
+        // and returned `assets: []` if it wasn't there, silently breaking the
+        // documented escape hatch for any pin older than the latest 30 releases.
+        const pinned = config.versions[spec.githubRepo];
+        if (pinned) {
+            // Even though `lsp.versions` is user-only config,
+            // validate the pin defense-in-depth before it flows into URL paths and
+            // (eventually, via the probed tag) filesystem paths and `tar -xf`.
+            try {
+                assertSafeVersion(pinned);
+            }
+            catch (err) {
+                return {
+                    tag: null,
+                    assets: [],
+                    blockedByGrace: false,
+                    reason: `invalid pinned version ${JSON.stringify(pinned)}: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+            const release = await fetchReleaseByTag(spec.githubRepo, pinned, fetchImpl, signal);
+            if (release) {
+                return {
+                    tag: release.tag,
+                    assets: release.assets,
+                    blockedByGrace: false,
+                };
+            }
+            return {
+                tag: null,
+                assets: [],
+                blockedByGrace: false,
+                reason: `pinned tag ${pinned} not found on GitHub`,
+            };
+        }
+        // A fresh version check selects the cached tag without probing the release
+        // list again. Fetch that tag's assets directly; if unavailable, retry the
+        // live release list. Unsafe disk values are cache misses, never URL paths.
+        const cached = readVersionCheck(spec.githubRepo);
+        const weeklyMs = config.graceDays * 24 * 60 * 60 * 1000;
+        const cachedTag = cached?.latest_eligible ?? null;
+        const cachedSafe = isSafeVersion(cachedTag);
+        if (cached && !shouldRecheckVersion(cached, weeklyMs) && cachedSafe) {
+            // Installations still need the selected tag's asset URLs.
+            const release = await fetchReleaseByTag(spec.githubRepo, cachedTag, fetchImpl);
+            if (release) {
+                return {
+                    tag: release.tag,
+                    assets: release.assets,
+                    blockedByGrace: false,
+                };
+            }
+            // Cached tag now unreachable — fall through to live probe.
+        }
+        // 3. Live probe.
+        const probe = await probeGithubReleases(spec.githubRepo, config.graceDays, fetchImpl, warn);
+        if (!probe) {
+            // Probe failed. Return tag:null instead of
+            // `cached.latest_eligible` with empty assets. Returning a non-null
+            // tag with empty assets makes the caller try (and fail) to install,
+            // emitting misleading "asset not found" errors. Returning null lets
+            // the caller skip cleanly with a "github releases probe failed" reason.
+            return {
+                tag: null,
+                assets: [],
+                blockedByGrace: false,
+                reason: "github releases probe failed",
+            };
+        }
+        writeVersionCheck(spec.githubRepo, probe.tag);
+        return { tag: probe.tag, assets: probe.assets, blockedByGrace: probe.blockedByGrace };
+    }
+    /* ─────────────────────────── download ─────────────────────────── */
+    function controlledTimeoutSignal(timeoutMs, parent) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        timeout.unref?.();
+        const abort = () => controller.abort();
+        parent?.addEventListener("abort", abort, { once: true });
+        if (parent?.aborted)
+            abort();
+        return {
+            signal: controller.signal,
+            cleanup: () => {
+                clearTimeout(timeout);
+                parent?.removeEventListener("abort", abort);
+            },
+        };
+    }
+    /**
+     * Stream a remote URL to disk with a hard byte cap.
+     *
+     * Previously the download was unbounded, so a malicious or
+     * misconfigured release could fill the user's disk and stall plugin
+     * startup forever. We now:
+     *   - Reject if `Content-Length` (when present) exceeds the cap.
+     *   - Track streamed bytes during the pipeline and abort if the cap is
+     *     exceeded mid-download. This handles the case where the server lies
+     *     about Content-Length, omits it (chunked transfer), or sends more
+     *     bytes than advertised.
+     *
+     * `assetSize` is the size hint from GitHub's release JSON. When provided
+     * we sanity-check it against the cap before even starting the download.
+     */
+    /**
+     * Hosts we will download GitHub release artifacts from. The GitHub API
+     * returns `browser_download_url` values that almost always live on
+     * `github.com` (the canonical URL), but the actual blob is served from
+     * `objects.githubusercontent.com` after redirect. We allow both.
+     *
+     * Without this allowlist, a compromised or malicious
+     * GitHub API response could swap `browser_download_url` to an attacker-
+     * controlled host (e.g. `evil.example/payload.zip`) and we would happily
+     * follow the redirect chain. The download size cap and SHA-256 TOFU help
+     * but cannot stop the very first install on a tag we have never seen.
+     *
+     * We handle redirects manually so every hop is checked before any bytes are
+     * accepted. A compromised release URL may start on github.com and redirect to
+     * an attacker-controlled host; `redirect: "follow"` would hide that hop.
+     */
+    const ALLOWED_DOWNLOAD_HOSTS = new Set([
+        "github.com",
+        "api.github.com",
+        "objects.githubusercontent.com",
+        "release-assets.githubusercontent.com",
+        "raw.githubusercontent.com",
+        "codeload.github.com",
+    ]);
+    function assertAllowedDownloadUrl(rawUrl) {
+        let parsed;
+        try {
+            parsed = new URL(rawUrl);
+        }
+        catch {
+            throw new Error(`download url is not a valid URL: ${rawUrl}`);
+        }
+        if (parsed.protocol !== "https:") {
+            throw new Error(`download url must be https (got ${parsed.protocol}): ${rawUrl}`);
+        }
+        if (!ALLOWED_DOWNLOAD_HOSTS.has(parsed.hostname.toLowerCase())) {
+            throw new Error(`download url host ${parsed.hostname} is not in the GitHub allowlist: ${rawUrl}`);
+        }
+        return parsed;
+    }
+    async function downloadFile(url, destPath, fetchImpl, assetSize, signal) {
+        if (assetSize !== undefined && assetSize > MAX_DOWNLOAD_BYTES) {
+            throw new Error(`asset size ${assetSize} exceeds max ${MAX_DOWNLOAD_BYTES} (set lsp.versions to pin a smaller release if this is wrong)`);
+        }
+        const timeout = controlledTimeoutSignal(120_000, signal);
+        try {
+            const res = await fetchFollowingRedirects(url, fetchImpl, timeout.signal);
+            if (!res.ok || !res.body) {
+                throw new Error(`download failed (${res.status})`);
+            }
+            const advertised = Number.parseInt(res.headers.get("content-length") ?? "", 10);
+            if (Number.isFinite(advertised) && advertised > MAX_DOWNLOAD_BYTES) {
+                throw new Error(`Content-Length ${advertised} exceeds max ${MAX_DOWNLOAD_BYTES}`);
+            }
+            mkdirSync(dirname(destPath), { recursive: true });
+            // Streaming size guard. Wrap the response body in a transformer that
+            // counts bytes and aborts on overflow. If we don't do this we'll happily
+            // stream a 100 GB malicious response straight to disk.
+            let bytesWritten = 0;
+            const guard = new TransformStream({
+                transform(chunk, controller) {
+                    bytesWritten += chunk.byteLength;
+                    if (bytesWritten > MAX_DOWNLOAD_BYTES) {
+                        controller.error(new Error(`download exceeded ${MAX_DOWNLOAD_BYTES} bytes after streaming (server lied about size or sent unbounded body)`));
+                        return;
+                    }
+                    controller.enqueue(chunk);
+                },
+            });
+            const guarded = res.body.pipeThrough(guard);
+            // biome-ignore lint/suspicious/noExplicitAny: ReadableStream→Node stream conversion
+            const nodeStream = Readable.fromWeb(guarded);
+            await pipeline(nodeStream, createWriteStream(destPath), { signal: timeout.signal });
+        }
+        catch (err) {
+            // Always clean up the partial file on any download failure.
+            try {
+                unlinkSync(destPath);
+            }
+            catch {
+                // ignore
+            }
+            throw err;
+        }
+        finally {
+            timeout.cleanup();
+        }
+    }
+    async function fetchFollowingRedirects(url, fetchImpl, signal) {
+        const maxRedirects = 5;
+        let currentUrl = url;
+        for (let i = 0; i <= maxRedirects; i += 1) {
+            assertAllowedDownloadUrl(currentUrl);
+            const res = await fetchImpl(currentUrl, {
+                headers: { accept: "application/octet-stream" },
+                redirect: "manual",
+                signal,
+            });
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get("location");
+                if (!location)
+                    throw new Error(`redirect status ${res.status} without Location`);
+                currentUrl = new URL(location, currentUrl).toString();
+                continue;
+            }
+            return res;
+        }
+        throw new Error(`too many redirects (>${maxRedirects})`);
+    }
+    /* ─────────────────────────── extraction ─────────────────────────── */
+    /**
+     * Recursively validate that every entry under `stagingRoot` is contained
+     * within it (zip-slip + symlink containment).
+     *
+     * Rejects:
+     *   - Any symlink (regardless of where it points). Symlinks in LSP
+     *     installs are extremely rare and would be a red flag.
+     *   - Any hardlink that has multiple inodes pointing at the same file
+     *     OUTSIDE the staging root (we can't easily detect this for hardlinks
+     *     to other paths inside the same archive, but those aren't a containment
+     *     escape).
+     *   - Any entry whose `realpath()` resolves outside `stagingRoot`. This
+     *     catches what the platform extractor missed if it failed to defend
+     *     against `..` traversal.
+     *
+     * Throws on any violation. The caller cleans up the staging dir.
+     */
+    function validateExtraction(stagingRoot) {
+        const realStagingRoot = realpathSync(stagingRoot);
+        let totalBytes = 0;
+        const walk = (dir) => {
+            let entries;
+            try {
+                entries = readdirSync(dir);
+            }
+            catch (err) {
+                throw new Error(`failed to read staging dir ${dir}: ${err}`);
+            }
+            for (const entry of entries) {
+                const full = join(dir, entry);
+                // lstatSync does NOT follow symlinks, so we can detect them.
+                let lst;
+                try {
+                    lst = lstatSync(full);
+                }
+                catch (err) {
+                    throw new Error(`failed to lstat ${full}: ${err}`);
+                }
+                if (lst.isSymbolicLink()) {
+                    let target = "<unreadable>";
+                    try {
+                        target = readlinkSync(full);
+                    }
+                    catch {
+                        // ignore — we're rejecting either way
+                    }
+                    throw new Error(`archive contains symlink ${relative(realStagingRoot, full)} → ${target}; rejecting (zip-slip defense)`);
+                }
+                // Verify the entry's REAL path stays under the staging root. This
+                // is the canonical zip-slip check — if the platform extractor wrote
+                // a file with `..` components in its path, realpath will resolve it
+                // to wherever it actually landed.
+                let realFull;
+                try {
+                    realFull = realpathSync(full);
+                }
+                catch (err) {
+                    throw new Error(`failed to realpath ${full}: ${err}`);
+                }
+                const rel = relative(realStagingRoot, realFull);
+                if (relativePathEscapesRoot(rel) || resolve(realStagingRoot, rel) !== realFull) {
+                    throw new Error(`archive entry escapes staging root: ${full} → ${realFull} (zip-slip defense)`);
+                }
+                if (lst.isDirectory()) {
+                    walk(full);
+                }
+                else if (lst.isFile()) {
+                    // Accumulate uncompressed sizes and abort early if
+                    // we cross the cap. Walking the whole tree first would let a
+                    // decompression bomb fill the disk before we noticed.
+                    totalBytes += lst.size;
+                    if (totalBytes > MAX_EXTRACT_BYTES) {
+                        throw new Error(`extracted archive exceeds ${MAX_EXTRACT_BYTES} bytes (decompression bomb defense): saw ${totalBytes} bytes before hitting the cap`);
+                    }
+                }
+                else {
+                    // Sockets, FIFOs, character devices — none of these belong in an
+                    // LSP release. Reject defensively.
+                    throw new Error(`archive contains non-file/non-dir entry: ${full}`);
+                }
+            }
+        };
+        walk(realStagingRoot);
+    }
+    function assertArchiveEntryPath(entry) {
+        const normalized = entry.replaceAll("\\", "/");
+        if (normalized.startsWith("/") ||
+            /^[A-Za-z]:\//.test(normalized) ||
+            normalized.split("/").includes("..")) {
+            throw new Error(`archive entry escapes archive root: ${entry}`);
+        }
+    }
+    const ARCHIVE_LIST_TIMEOUT_MS = 30_000;
+    /**
+     * Run an archive tool without blocking the host's event loop. Listing and
+     * extracting a large LSP archive can take minutes (the extract timeout is
+     * 180 s); a synchronous call froze every other plugin hook for that long.
+     */
+    function runArchiveTool(command, args, timeout) {
+        return new Promise((resolvePromise, reject) => {
+            let child;
+            // execFile's callback waits for pipe EOF, even after the direct child exits.
+            // An inherited descriptor must not keep the install promise alive forever.
+            const deadline = setTimeout(() => {
+                reject(new Error(`${command} ${args[0]} timed out after ${timeout} ms`));
+                child?.kill("SIGKILL");
+                child?.stdin?.destroy();
+                child?.stdout?.destroy();
+                child?.stderr?.destroy();
+            }, timeout);
+            try {
+                child = execFile(command, args, { encoding: "utf8", timeout, killSignal: "SIGKILL" }, (err, stdout) => {
+                    clearTimeout(deadline);
+                    if (err)
+                        reject(err);
+                    else
+                        resolvePromise(stdout);
+                });
+                // Archive tools use explicit file arguments; none should wait for input.
+                child.stdin?.end();
+            }
+            catch (error) {
+                clearTimeout(deadline);
+                reject(error);
+            }
+        });
+    }
+    /** Run the platform tar extractor and name the resolved executable in failures. */
+    async function runTarExtraction(args, timeout) {
+        const executable = windowsTarExecutable();
+        try {
+            await runArchiveTool(executable, args, timeout);
+        }
+        catch (cause) {
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            throw new Error(`tar extraction failed using ${executable}: ${detail}`, { cause });
+        }
+    }
+    async function precheckWithTar(archivePath, command) {
+        let totalBytes = 0;
+        const verbose = await runArchiveTool(command, ["-tvf", archivePath], ARCHIVE_LIST_TIMEOUT_MS);
+        for (const line of verbose.split("\n")) {
+            // Both bsdtar and GNU tar render hardlinks with a leading `h` type marker.
+            // Reject them before extraction because the extracted inode cannot reveal
+            // the archive link target during the post-extraction containment walk.
+            if (line.startsWith("h")) {
+                throw new Error(`archive contains hardlink entry: ${line.trim()}`);
+            }
+            const parts = line.trim().split(/\s+/);
+            if (parts.length >= 6) {
+                const numeric = parts
+                    .map((part) => Number.parseInt(part, 10))
+                    .filter((value) => Number.isFinite(value) && value >= 0);
+                if (numeric.length > 0)
+                    totalBytes += Math.max(...numeric);
+            }
+        }
+        const names = await runArchiveTool(command, ["-tf", archivePath], ARCHIVE_LIST_TIMEOUT_MS);
+        for (const entry of names.split("\n")) {
+            if (entry.length > 0)
+                assertArchiveEntryPath(entry);
+        }
+        return totalBytes;
+    }
+    async function precheckArchiveContents(archivePath, archiveType, zipListingMode = "platform") {
+        let totalBytes = 0;
+        if (archiveType === "zip" && zipListingMode === "platform" && process.platform !== "win32") {
+            const out = await runArchiveTool("unzip", ["-l", archivePath], ARCHIVE_LIST_TIMEOUT_MS);
+            const match = out.match(/^\s*(\d+)\s+\d+\s+files?\s*$/m);
+            if (match)
+                totalBytes = Number.parseInt(match[1] ?? "0", 10);
+            const names = await runArchiveTool("unzip", ["-Z1", archivePath], ARCHIVE_LIST_TIMEOUT_MS);
+            for (const entry of names.split("\n")) {
+                if (entry.length > 0)
+                    assertArchiveEntryPath(entry);
+            }
+        }
+        else {
+            totalBytes = await precheckWithTar(archivePath, windowsTarExecutable());
+        }
+        if (totalBytes > MAX_EXTRACT_BYTES) {
+            throw new Error(`archive uncompressed size ${totalBytes} exceeds ${MAX_EXTRACT_BYTES}`);
+        }
+    }
+    async function extractArchiveSafely(archivePath, destDir, archiveType, validateStaged) {
+        // Per-process random suffix avoids collisions if two installs of the
+        // same package somehow race past the install lock (defense in depth).
+        const suffix = randomBytes(8).toString("hex");
+        const stagingDir = `${destDir}.staging-${suffix}`;
+        // Cleanup any stale staging dir from a prior crashed install.
+        try {
+            rmSync(stagingDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+        mkdirSync(stagingDir, { recursive: true });
+        try {
+            await precheckArchiveContents(archivePath, archiveType);
+            await runPlatformExtractor(archivePath, stagingDir, archiveType);
+            validateExtraction(stagingDir);
+            await validateStaged?.(stagingDir);
+            // Keep the previous distribution available for rollback until the swap succeeds.
+            // Renaming over a nonempty directory is not supported on Windows.
+            const previousDir = `${destDir}.previous-${suffix}`;
+            const hadPrevious = existsSync(destDir);
+            if (hadPrevious)
+                renameSync(destDir, previousDir);
+            try {
+                renameSync(stagingDir, destDir);
+            }
+            catch (err) {
+                if (hadPrevious)
+                    renameSync(previousDir, destDir);
+                throw err;
+            }
+            try {
+                rmSync(previousDir, { recursive: true, force: true });
+            }
+            catch (err) {
+                warn(`[lsp] could not remove previous extraction ${previousDir}: ${err}`);
+            }
+        }
+        catch (err) {
+            // Always clean up the staging dir on any failure path.
+            try {
+                rmSync(stagingDir, { recursive: true, force: true });
+            }
+            catch {
+                // ignore — cleanup failures are not as bad as the original error
+            }
+            throw err;
+        }
+    }
+    function quarantineCachedGithubInstall(spec, reason) {
+        const packageDir = ghPackageDir(spec);
+        const dest = join(ghCacheRoot(), ".quarantine", encodeURIComponent(spec.id), `${Date.now()}`);
+        warn(`[lsp] tofu_mismatch ${spec.id}: ${reason}; quarantining ${packageDir} -> ${dest}`);
+        try {
+            mkdirSync(dirname(dest), { recursive: true });
+            rmSync(dest, { recursive: true, force: true });
+            renameSync(packageDir, dest);
+        }
+        catch (err) {
+            warn(`[lsp] tofu_mismatch ${spec.id}: failed to quarantine cache entry: ${err}`);
+        }
+    }
+    /** A timeout is inconclusive: a cold or loaded server may simply need longer to start. */
+    async function smokeGithubBinary(spec, binaryPath) {
+        return new Promise((resolveSmoke) => {
+            let child;
+            let settled = false;
+            let output = Buffer.alloc(0);
+            const finish = (verdict, detail) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                child?.stdout?.destroy();
+                child?.stderr?.destroy();
+                if (verdict !== "passed") {
+                    warn(`[lsp] ${spec.id}: runtime smoke ${verdict} at ${binaryPath}: ${detail ?? output.toString("utf8").trim()}`);
+                }
+                resolveSmoke(verdict);
+            };
+            const timer = setTimeout(() => {
+                child?.kill("SIGKILL");
+                child?.unref();
+                finish("timeout", "exceeded 2000 ms; keeping install");
+            }, 2_000);
+            const capture = (chunk) => {
+                const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                const available = 64 * 1024 - output.length;
+                output = Buffer.concat([output, bytes.subarray(0, available)]);
+                if (bytes.length > available) {
+                    child?.kill("SIGKILL");
+                    finish("failed", "exceeded 64 KiB output limit");
+                }
+            };
+            try {
+                child = spawn(binaryPath, [...spec.smokeArgs], { stdio: ["ignore", "pipe", "pipe"] });
+                child.stdout?.on("data", capture);
+                child.stderr?.on("data", capture);
+                child.once("error", (error) => finish("failed", String(error)));
+                // Do not wait for pipe EOF: descendants may inherit handles after the server exits.
+                child.once("exit", (code, signal) => finish(code === 0 ? "passed" : "failed", `exit=${code}, signal=${signal}`));
+            }
+            catch (error) {
+                finish("failed", String(error));
+            }
+        });
+    }
+    function hasRequiredRuntime(spec, extractDir, version) {
+        return (spec.requiredRuntimePaths?.(stripTagV(version)) ?? []).every(({ path, kind }) => {
+            try {
+                const info = statSync(join(extractDir, path));
+                return kind === "file" ? info.isFile() : info.isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    /** Return known verdicts immediately without racing an install or waiting for its lock. */
+    function validateCachedGithubInstall(spec, platform) {
+        const lease = acquireInstallLock(spec.githubRepo);
+        if (!lease)
+            return null;
+        try {
+            const validation = validateCachedGithubInstallUnderLock(spec, platform);
+            if (typeof validation !== "boolean")
+                return validation.finally(() => lease.release());
+            lease.release();
+            return validation;
+        }
+        catch (err) {
+            lease.release();
+            throw err;
+        }
+    }
+    function validateCachedGithubInstallUnderLock(spec, platform) {
+        const packageDir = ghPackageDir(spec);
+        const meta = readGithubInstalledMetaIn(packageDir);
+        const binaryPath = ghBinaryCandidates(spec, platform)
+            .map((candidate) => join(ghBinDir(spec), candidate))
+            .find((candidate) => {
+            try {
+                return statSync(candidate).isFile();
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!meta?.version || !isSafeVersion(meta.version) || !binaryPath) {
+            quarantineCachedGithubInstall(spec, "missing/unsafe metadata or binary");
+            return false;
+        }
+        if (spec.layout === "distribution" && meta.layout !== "distribution") {
+            // Layout must be checked even if an older installer recorded a successful smoke.
+            quarantineCachedGithubInstall(spec, "distribution was installed without its runtime layout");
+            return false;
+        }
+        const currentHash = cachedBinarySha256(binaryPath);
+        const recordedBinaryHash = meta.binarySha256 ?? meta.sha256;
+        // Legacy metadata recorded the archive digest in sha256. Retain its audit
+        // value while migrating to the executable digest, but only after validation.
+        const legacyArchiveHash = meta.sha256 && !meta.binarySha256 && !meta.archiveSha256;
+        if (!recordedBinaryHash || (!legacyArchiveHash && currentHash !== recordedBinaryHash)) {
+            quarantineCachedGithubInstall(spec, `recorded ${recordedBinaryHash}, current ${currentHash}`);
+            return false;
+        }
+        if (meta.sha256 === currentHash &&
+            meta.binarySha256 === currentHash &&
+            meta.layout === spec.layout &&
+            meta.smoke?.binarySha256 === currentHash &&
+            hasRequiredRuntime(spec, ghExtractDir(spec), meta.version)) {
+            return true;
+        }
+        return (async () => {
+            if (!hasRequiredRuntime(spec, ghExtractDir(spec), meta.version)) {
+                quarantineCachedGithubInstall(spec, "missing required runtime files");
+                return false;
+            }
+            const verdict = await smokeGithubBinary(spec, binaryPath);
+            if (verdict === "failed") {
+                quarantineCachedGithubInstall(spec, "cached binary failed runtime smoke check");
+                return false;
+            }
+            // Do not certify a different executable if it changed while the subprocess ran.
+            if (!existsSync(binaryPath) || cachedBinarySha256(binaryPath) !== currentHash)
+                return false;
+            writeGithubInstalledMetaIn(packageDir, meta.version, currentHash, legacyArchiveHash ? meta.sha256 : meta.archiveSha256, spec.layout, { binarySha256: currentHash, verdict });
+            return true;
+        })();
+    }
+    /**
+     * Internal: run the platform extractor against a fresh empty target.
+     *
+     * The extractor's containment defenses are platform-dependent: modern
+     * `unzip` and `tar` reject absolute paths and `..` components, but we
+     * still validate post-extraction in case a defense slipped past.
+     */
+    async function runPlatformExtractor(archivePath, destDir, archiveType) {
+        if (archiveType === "zip") {
+            if (process.platform === "win32") {
+                // Avoid PowerShell and PATH-resolved GNU tar. System32 bsdtar accepts
+                // drive-letter paths and direct argv execution adds no shell parser.
+                await runTarExtraction(["-xf", archivePath, "-C", destDir], 180_000);
+                return;
+            }
+            await runArchiveTool("unzip", ["-q", "-o", archivePath, "-d", destDir], 180_000);
+            return;
+        }
+        if (archiveType === "tar.gz") {
+            await runTarExtraction(["-xzf", archivePath, "-C", destDir], 180_000);
+            return;
+        }
+        if (archiveType === "tar.xz") {
+            await runTarExtraction(["-xf", archivePath, "-C", destDir], 180_000);
+            return;
+        }
+        throw new Error(`unsupported archive type: ${archiveType}`);
+    }
+    /**
+     * Run the download + extract + binary-place flow for a single server.
+     * Returns hashes on success, or a hash and error for the caller to persist
+     * in `.aft-install-failed.json` so repeated failures back off.
+     */
+    async function downloadAndInstall(spec, tag, assets, platform, arch, fetchImpl, signal) {
+        const version = stripTagV(tag);
+        const expected = spec.resolveAsset(platform, arch, version);
+        if (!expected) {
+            const message = `unsupported platform/arch combo ${platform}/${arch}`;
+            warn(`[lsp] ${spec.id}: ${message}`);
+            return { ok: false, sha256: "", error: message };
+        }
+        const matchingAsset = assets.find((asset) => asset.name === expected.name);
+        if (!matchingAsset) {
+            const message = `asset ${expected.name} not found in release ${tag} (${assets.length} assets available)`;
+            warn(`[lsp] ${spec.id}: ${message}`);
+            return { ok: false, sha256: "", error: message };
+        }
+        const pkgDir = ghPackageDir(spec);
+        const extractDir = ghExtractDir(spec);
+        const archivePath = join(pkgDir, expected.name);
+        log(`[lsp] downloading ${spec.id} ${tag} → ${matchingAsset.url}`);
+        try {
+            await downloadFile(matchingAsset.url, archivePath, fetchImpl, matchingAsset.size, signal);
+        }
+        catch (err) {
+            const message = `download failed: ${err instanceof Error ? err.message : String(err)}`;
+            error(`[lsp] download ${spec.id} failed: ${err}`);
+            return { ok: false, sha256: "", error: message };
+        }
+        let archiveSha256;
+        try {
+            archiveSha256 = await sha256OfFile(archivePath);
+        }
+        catch (err) {
+            const message = `hash failed: ${err instanceof Error ? err.message : String(err)}`;
+            error(`[lsp] hash ${spec.id} failed: ${err}`);
+            try {
+                unlinkSync(archivePath);
+            }
+            catch { }
+            return { ok: false, sha256: "", error: message };
+        }
+        log(`[lsp] ${spec.id} ${tag} sha256=${archiveSha256}`);
+        const previousMeta = readGithubInstalledMetaIn(ghPackageDir(spec));
+        const previousArchiveSha256 = previousMeta?.archiveSha256 ??
+            (previousMeta?.binarySha256 ? undefined : previousMeta?.sha256);
+        if (previousMeta &&
+            previousMeta.version === tag &&
+            previousArchiveSha256 &&
+            previousArchiveSha256 !== archiveSha256) {
+            const message = `TOFU sha256 mismatch: previously installed archive sha256=${previousArchiveSha256}, ` +
+                `downloaded sha256=${archiveSha256}`;
+            error(`[lsp] ${spec.id} ${tag}: ${message}. ` +
+                `This means the published release for tag ${tag} changed. Investigate before proceeding. ` +
+                `Run \`npx @cortexkit/aft doctor --clear\` to wipe the cache and force a fresh install if you've verified the change.`);
+            try {
+                unlinkSync(archivePath);
+            }
+            catch { }
+            return { ok: false, sha256: archiveSha256, error: message };
+        }
+        let binarySha256 = "";
+        let smokeVerdict = "passed";
+        const binaryRelativePath = spec.binaryPathInArchive(platform, arch, version);
+        try {
+            await extractArchiveSafely(archivePath, extractDir, expected.archive, async (stagingDir) => {
+                const stagedBinary = join(stagingDir, binaryRelativePath);
+                if (!existsSync(stagedBinary) || !statSync(stagedBinary).isFile()) {
+                    throw new Error(`extracted binary not found at ${stagedBinary}`);
+                }
+                if (!hasRequiredRuntime(spec, stagingDir, version)) {
+                    throw new Error("missing required runtime files in staged distribution");
+                }
+                if (platform !== "win32") {
+                    const { chmodSync } = await import("node:fs");
+                    chmodSync(stagedBinary, 0o755);
+                }
+                const verdict = await smokeGithubBinary(spec, stagedBinary);
+                if (verdict === "failed")
+                    throw new Error("staged binary failed runtime smoke check");
+                smokeVerdict = verdict;
+                const identityBeforeHash = fileIdentity(stagedBinary);
+                binarySha256 = await sha256OfFile(stagedBinary);
+                if (fileIdentity(stagedBinary) !== identityBeforeHash) {
+                    throw new Error("staged executable changed while hashing");
+                }
+            });
+        }
+        catch (err) {
+            const message = `extract failed: ${err instanceof Error ? err.message : String(err)}`;
+            error(`[lsp] extract ${spec.id} failed: ${err}`);
+            return { ok: false, sha256: archiveSha256, error: message };
+        }
+        finally {
+            try {
+                unlinkSync(archivePath);
+            }
+            catch {
+                // A leftover archive does not make the validated extraction unsafe.
+            }
+        }
+        const innerBinaryPath = join(extractDir, binaryRelativePath);
+        const targetBinary = spec.layout === "distribution" ? innerBinaryPath : ghBinaryPath(spec, platform);
+        mkdirSync(dirname(targetBinary), { recursive: true });
+        try {
+            if (spec.layout === "standalone") {
+                const stagedBinary = `${targetBinary}.staging-${randomBytes(8).toString("hex")}`;
+                try {
+                    copyFileSync(innerBinaryPath, stagedBinary);
+                    if (platform !== "win32") {
+                        const { chmodSync } = await import("node:fs");
+                        chmodSync(stagedBinary, 0o755);
+                    }
+                    renameSync(stagedBinary, targetBinary);
+                }
+                finally {
+                    rmSync(stagedBinary, { force: true });
+                }
+            }
+        }
+        catch (err) {
+            const message = `failed to place binary at ${targetBinary}: ${err instanceof Error ? err.message : String(err)}`;
+            error(`[lsp] ${spec.id}: ${message}`);
+            return { ok: false, sha256: archiveSha256, error: message };
+        }
+        try {
+            const identity = fileIdentity(targetBinary);
+            // The staged executable was hashed before publication. Remember its new
+            // identity so the refresh does not hash the same bytes again.
+            binaryDigestMemo.set(targetBinary, { identity, digest: binarySha256 });
+            writeStampedFileDigest(targetBinary, binarySha256, identity);
+            log(`[lsp] installed ${spec.id} ${tag} at ${targetBinary}`);
+            log(`[lsp] ${spec.id} ${tag} binary_sha256=${binarySha256}`);
+            return {
+                ok: true,
+                archiveSha256,
+                binarySha256,
+                smoke: { binarySha256, verdict: smokeVerdict },
+            };
+        }
+        catch (err) {
+            const message = `failed to hash installed binary: ${err instanceof Error ? err.message : String(err)}`;
+            error(`[lsp] ${spec.id}: ${message}`);
+            return { ok: false, sha256: archiveSha256, error: message };
+        }
+    }
+    /* ─────────────────────────── per-server flow ─────────────────────────── */
+    async function ensureGithubInstalled(spec, config, fetchImpl, platform, arch, signal) {
+        const outcome = await withInstallLock(spec.githubRepo, async () => {
+            const failureMarker = readInstallFailureMarker(spec);
+            const pinnedRelease = config.versions[spec.githubRepo];
+            if (failureMarker) {
+                if (isFreshInstallFailure(failureMarker) &&
+                    (!pinnedRelease || sameRelease(failureMarker.release, pinnedRelease))) {
+                    warn(`[lsp] skipping ${spec.id}: recent install failure marker ${installFailureMarkerPath(spec)} ` +
+                        `for ${failureMarker.release}: ${failureMarker.error}`);
+                    return { started: false, reason: "recent install failure marker" };
+                }
+                clearInstallFailureMarker(spec);
+            }
+            const { tag, assets, blockedByGrace, reason } = await resolveTargetTag(spec, config, fetchImpl, signal);
+            if (!tag) {
+                const installed = isGithubInstalled(spec, platform);
+                if (installed) {
+                    warn(`[lsp] no eligible release of ${spec.githubRepo} (grace=${config.graceDays}d); keeping existing install`);
+                    return { started: false, reason: "kept existing install" };
+                }
+                const fallbackReason = reason ??
+                    (blockedByGrace
+                        ? `all releases are within ${config.graceDays}-day grace window`
+                        : "github releases probe failed");
+                warn(`[lsp] skipping ${spec.id}: ${fallbackReason}`);
+                return { started: false, reason: fallbackReason };
+            }
+            if (isGithubInstalled(spec, platform)) {
+                const installedMeta = readGithubInstalledMetaIn(ghPackageDir(spec));
+                if (installedMeta && installedMeta.version === tag) {
+                    clearInstallFailureMarker(spec);
+                    return { started: false, reason: "already installed" };
+                }
+                if (installedMeta) {
+                    log(`[lsp] reinstalling ${spec.id}: cached ${installedMeta.version} ≠ target ${tag}`);
+                }
+                else {
+                    log(`[lsp] reinstalling ${spec.id}@${tag}: no installed-version metadata recorded`);
+                }
+            }
+            const installResult = await downloadAndInstall(spec, tag, assets, platform, arch, fetchImpl, signal).catch((err) => {
+                const message = `install crashed: ${err instanceof Error ? err.message : String(err)}`;
+                error(`[lsp] github install ${spec.id} crashed: ${err}`);
+                return { ok: false, sha256: "", error: message };
+            });
+            if (!installResult.ok) {
+                writeInstallFailureMarker(spec, tag, installResult.sha256, installResult.error);
+                return { started: true, reason: "install failed (see plugin log)" };
+            }
+            clearInstallFailureMarker(spec);
+            writeGithubInstalledMetaIn(ghPackageDir(spec), tag, installResult.binarySha256, installResult.archiveSha256, spec.layout, installResult.smoke);
+            return { started: true };
+        });
+        if (outcome === null) {
+            return { started: false, reason: "another install in progress" };
+        }
+        return outcome;
+    }
+    /* ─────────────────────────── public entrypoint ─────────────────────────── */
+    /** Wait `ms` milliseconds, or less if `signal` aborts first. */
+    function sleepUntilAborted(ms, signal) {
+        if (signal.aborted)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", finish);
+                resolve();
+            };
+            const timer = setTimeout(finish, ms);
+            signal.addEventListener("abort", finish, { once: true });
+        });
+    }
+    const inFlightGithubInstalls = new Set();
+    function trackInFlightGithubInstall(controller, promise) {
+        const entry = { controller, promise };
+        inFlightGithubInstalls.add(entry);
+        promise.then(() => inFlightGithubInstalls.delete(entry), () => inFlightGithubInstalls.delete(entry));
+        return promise;
+    }
+    async function abortInFlightGithubInstalls() {
+        const installs = Array.from(inFlightGithubInstalls);
+        for (const install of installs) {
+            install.controller.abort();
+        }
+        await Promise.allSettled(installs.map((install) => install.promise));
+    }
+    /**
+     * Run the GitHub-release auto-install pass for every Pattern C server.
+     *
+     * Previously verified caches are returned synchronously for the first configure.
+     * Unverified caches and installs settle in the background; callers await
+     * installsComplete before refreshing paths without blocking unrelated startup.
+     */
+    function runGithubAutoInstall(relevantServers, config, fetchImpl = fetch, options = {}) {
+        const cachedBinDirs = [];
+        const skipped = [];
+        const installPromises = [];
+        const installingBinaries = [];
+        let installsStarted = 0;
+        const lockWaitTimeoutMs = Math.max(0, options.__lockWaitTimeoutMsForTests ?? INSTALL_LOCK_WAIT_MS);
+        const lockPollIntervalMs = Math.max(1, options.__lockPollIntervalMsForTests ?? INSTALL_LOCK_POLL_INTERVAL_MS);
+        function notifyCachedBinDirsChanged(directory) {
+            try {
+                options.onCachedBinDirsChanged?.(directory);
+            }
+            catch (err) {
+                warn(`[lsp] github cache path refresh callback failed: ${err}`);
+            }
+        }
+        /**
+         * Re-validate a cache whose install lock another process holds, polling
+         * until the lock frees or the wait deadline passes. Returns null when the
+         * cache could not be validated. An aborted signal (plugin shutdown) ends
+         * the wait at once and returns null without recording a lock-timeout skip,
+         * because the lock never timed out.
+         */
+        async function retryBusyCacheValidation(spec, platform, signal) {
+            const deadline = Date.now() + lockWaitTimeoutMs;
+            while (true) {
+                if (signal.aborted)
+                    return null;
+                const validation = await withInstallLock(spec.githubRepo, async () => validateCachedGithubInstallUnderLock(spec, platform));
+                if (validation !== null)
+                    return validation;
+                if (signal.aborted)
+                    return null;
+                const remainingMs = deadline - Date.now();
+                if (remainingMs <= 0) {
+                    skipped.push({
+                        id: spec.id,
+                        reason: INSTALL_LOCK_WAIT_TIMEOUT_REASON,
+                    });
+                    return null;
+                }
+                await sleepUntilAborted(Math.min(lockPollIntervalMs, remainingMs), signal);
+            }
+        }
+        const host = detectHostPlatform();
+        if (!host) {
+            // Without a supported platform/arch we cannot select or validate a cached executable.
+            return {
+                cachedBinDirs,
+                installsStarted: 0,
+                installingBinaries: [],
+                skipped,
+                installsComplete: Promise.resolve(),
+                getCachedBinDirs: async () => [...cachedBinDirs],
+            };
+        }
+        for (const spec of GITHUB_LSP_TABLE) {
+            // One controller per server covers both the busy-lock cache wait and
+            // the install that follows it, so shutdown can cancel either one.
+            const controller = new AbortController();
+            const validation = isGithubInstalled(spec, host.platform)
+                ? validateCachedGithubInstall(spec, host.platform)
+                : false;
+            if (validation === true)
+                cachedBinDirs.push(ghBinDir(spec));
+            const cacheReady = (validation === null
+                ? retryBusyCacheValidation(spec, host.platform, controller.signal)
+                : Promise.resolve(validation)).then((healthy) => {
+                if (healthy && validation !== true) {
+                    const directory = ghBinDir(spec);
+                    cachedBinDirs.push(directory);
+                    notifyCachedBinDirsChanged(directory);
+                }
+                return healthy;
+            });
+            // Track the cache wait on its own: servers skipped below (disabled,
+            // auto-install off, not relevant) still wait on a busy lock.
+            installPromises.push(trackInFlightGithubInstall(controller, cacheReady.then(() => { })));
+            if (config.disabled.has(spec.id)) {
+                skipped.push({ id: spec.id, reason: "disabled by config" });
+                continue;
+            }
+            if (!config.autoInstall) {
+                skipped.push({ id: spec.id, reason: "auto_install: false" });
+                continue;
+            }
+            if (!relevantServers.has(spec.id)) {
+                skipped.push({ id: spec.id, reason: "not relevant to project" });
+                continue;
+            }
+            installsStarted += 1;
+            if (services.reportInstallingBinaries)
+                installingBinaries.push(spec.binary);
+            const promise = cacheReady
+                .then((healthy) => validation === null && healthy === null
+                ? { started: false, reason: undefined }
+                : ensureGithubInstalled(spec, config, fetchImpl, host.platform, host.arch, controller.signal))
+                .then((outcome) => {
+                if (!outcome.started)
+                    installsStarted -= 1;
+                if (outcome.reason && outcome.reason !== "already installed") {
+                    skipped.push({ id: spec.id, reason: outcome.reason });
+                }
+                notifyCachedBinDirsChanged();
+            }, (err) => {
+                installsStarted -= 1;
+                const reason = err instanceof Error ? err.message : String(err);
+                skipped.push({ id: spec.id, reason: `install error: ${reason}` });
+                error(`[lsp] github install ${spec.id} promise rejected: ${reason}`);
+                notifyCachedBinDirsChanged();
+            });
+            installPromises.push(trackInFlightGithubInstall(controller, promise));
+        }
+        return {
+            cachedBinDirs,
+            installingBinaries,
+            get installsStarted() {
+                return installsStarted;
+            },
+            skipped,
+            installsComplete: Promise.all(installPromises).then(() => { }),
+            getCachedBinDirs: async () => {
+                const currentHost = detectHostPlatform();
+                if (!currentHost)
+                    return [];
+                const directories = await Promise.all(GITHUB_LSP_TABLE.map(async (spec) => isGithubInstalled(spec, currentHost.platform) &&
+                    (await validateCachedGithubInstall(spec, currentHost.platform))
+                    ? ghBinDir(spec)
+                    : null));
+                return directories.filter((directory) => directory !== null);
+            },
+        };
+    }
+    /* ─────────────────────────── discovery helper ─────────────────────────── */
+    /**
+     * Cheap project-relevance scan for GitHub-distributed servers. Root markers
+     * win immediately; otherwise use the bounded shared extension walk for
+     * monorepos with nested source files.
+     */
+    function discoverRelevantGithubServers(projectRoot) {
+        // Match crates/aft/src/lsp/registry.rs server extensions so discovery
+        // installs the same server kinds that Rust will select for these files.
+        const extToServerIds = {
+            c: ["clangd"],
+            "c++": ["clangd"],
+            cc: ["clangd"],
+            cpp: ["clangd"],
+            cxx: ["clangd"],
+            h: ["clangd"],
+            "h++": ["clangd"],
+            hpp: ["clangd"],
+            hh: ["clangd"],
+            hxx: ["clangd"],
+            lua: ["lua-ls"],
+            zig: ["zls"],
+            zon: ["zls"],
+            typ: ["tinymist"],
+            typc: ["tinymist"],
+            tex: ["texlab"],
+            bib: ["texlab"],
+        };
+        const rootMarkers = {
+            clangd: ["compile_commands.json", "compile_flags.txt", ".clangd"],
+            "lua-ls": [".luarc.json", ".luarc.jsonc", ".stylua.toml", "stylua.toml"],
+            zls: ["build.zig"],
+            tinymist: ["typst.toml"],
+            texlab: [".latexmkrc", "latexmkrc", ".texlabroot", "texlabroot"],
+        };
+        const relevant = new Set();
+        for (const spec of GITHUB_LSP_TABLE) {
+            if (hasRootMarker(projectRoot, rootMarkers[spec.id]))
+                relevant.add(spec.id);
+        }
+        const extensions = relevantExtensionsInProject(projectRoot, extToServerIds);
+        for (const ext of extensions) {
+            for (const id of extToServerIds[ext] ?? []) {
+                relevant.add(id);
+            }
+        }
+        return relevant;
+    }
+    return {
+        ghBinaryPath,
+        isGithubInstalled,
+        __githubBinaryHashCountForTests,
+        validateExtraction,
+        precheckArchiveContents,
+        abortInFlightGithubInstalls,
+        runGithubAutoInstall,
+        discoverRelevantGithubServers,
+        _assertAllowedDownloadUrlForTesting: assertAllowedDownloadUrl,
+        _downloadFileForTesting: downloadFile,
+        _extractArchiveSafelyForTesting: extractArchiveSafely,
+        _precheckArchiveSizeForTesting: precheckArchiveContents,
+        _runArchiveToolForTesting: runArchiveTool,
+    };
+}
+//# sourceMappingURL=lsp-github-install.js.map