@herbertgao/pi-extensions 2026.9.1 → 2026.9.3

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

@@ -66,6 +66,7 @@ import { commitDurableStoreAsync } from "../durable-store.js";
 import { getGlobalPiLensDir } from "../file-utils.js";
 import { allAvailableGlobalBinDirs, installArgs, pmBinary, resolveNodePackageManager, } from "../package-manager.js";
 import { resetSafeSpawnWindowsCommandCache, safeSpawnAsync, } from "../safe-spawn.js";
+import { probeToolAsync } from "../tool-probe.js";
 import { logSessionStart } from "../sessionstart-logger.js";
 // Global installation directory for pi-lens tools
 const TOOLS_DIR = path.join(getGlobalPiLensDir(), "tools");
@@ -227,6 +228,114 @@ const OS_ARCH_ZIP_ASSETS = {
     darwin: { x64: "darwin_amd64.zip", arm64: "darwin_arm64.zip" },
     win32: { x64: "windows_amd64.zip", arm64: "windows_arm64.zip" },
 };
+function managedPackageFormatterTool(spec) {
+    return {
+        id: spec.id,
+        name: spec.name,
+        checkCommand: spec.id,
+        checkArgs: ["--version"],
+        installStrategy: spec.installStrategy,
+        packageName: spec.packageName,
+        binaryName: spec.id,
+    };
+}
+const MANAGED_PACKAGE_FORMATTERS = [
+    { id: "black", name: "Black", installStrategy: "pip", packageName: "black" },
+    {
+        id: "cmake-format",
+        name: "cmake-format",
+        installStrategy: "pip",
+        packageName: "cmakelang",
+    },
+    { id: "oxfmt", name: "oxfmt", installStrategy: "npm", packageName: "oxfmt" },
+];
+function managedGitHubFormatterTool(spec) {
+    return {
+        id: spec.id,
+        name: spec.name,
+        checkCommand: spec.id,
+        checkArgs: ["--version"],
+        installStrategy: "github",
+        binaryName: spec.id,
+        github: {
+            repo: `${spec.owner}/${spec.repo}`,
+            assetMatch: spec.assetPattern,
+            ...(spec.binaryInArchive && { binaryInArchive: spec.binaryInArchive }),
+            ...(spec.kind === "phar" && { launcher: "php" }),
+            ...(spec.kind === "jar" && { launcher: "java" }),
+        },
+    };
+}
+const MANAGED_GITHUB_FORMATTERS = [
+    {
+        id: "stylua",
+        name: "StyLua",
+        owner: "JohnnyMorganz",
+        repo: "StyLua",
+        assetPattern: archAssetMatch({
+            linux: { x64: "linux-x86_64.zip", arm64: "linux-aarch64.zip" },
+            darwin: { x64: "macos-x86_64.zip", arm64: "macos-aarch64.zip" },
+            win32: { x64: "windows-x86_64.zip" },
+        }),
+        kind: "binary",
+        binaryInArchive: "stylua",
+    },
+    {
+        id: "php-cs-fixer",
+        name: "PHP CS Fixer",
+        owner: "PHP-CS-Fixer",
+        repo: "PHP-CS-Fixer",
+        assetPattern: (platform) => platform === "linux" || platform === "darwin" || platform === "win32"
+            ? "php-cs-fixer.phar"
+            : undefined,
+        kind: "phar",
+    },
+    {
+        id: "cljfmt",
+        name: "cljfmt",
+        owner: "weavejester",
+        repo: "cljfmt",
+        assetPattern: (platform, arch) => {
+            if (platform === "linux")
+                return arch === "arm64"
+                    ? "standalone.jar"
+                    : "linux-amd64-static.tar.gz";
+            if (platform === "darwin")
+                return "standalone.jar";
+            if (platform === "win32")
+                return "win-amd64.zip";
+            return undefined;
+        },
+        kind: "jar",
+        binaryInArchive: "cljfmt",
+    },
+];
+const MANAGED_MAVEN_FORMATTERS = [
+    {
+        id: "google-java-format",
+        name: "google-java-format",
+        groupId: "com.google.googlejavaformat",
+        artifactId: "google-java-format",
+        version: "1.27.0",
+        classifier: "all-deps",
+    },
+];
+function managedMavenFormatterTool(spec) {
+    return {
+        id: spec.id,
+        name: spec.name,
+        checkCommand: spec.id,
+        checkArgs: ["--version"],
+        installStrategy: "maven",
+        binaryName: spec.id,
+        maven: {
+            groupId: spec.groupId,
+            artifactId: spec.artifactId,
+            version: spec.version,
+            classifier: spec.classifier,
+        },
+    };
+}
 export const TOOLS = [
     // Core LSP servers
     {
@@ -275,6 +384,7 @@ export const TOOLS = [
         packageName: "prettier",
         binaryName: "prettier",
     },
+    ...MANAGED_PACKAGE_FORMATTERS.map(managedPackageFormatterTool),
     {
         id: "ruff",
         name: "Ruff",
@@ -548,10 +658,27 @@ export const TOOLS = [
         binaryName: "docker-langserver",
     },
     {
+        // #2722: intelephense has no CLI — its entry calls createConnection()
+        // unconditionally — and Node prints the offending source line before the
+        // error. The bundle is one ~4 MB minified line, so the transport-required
+        // marker #208 rescues on lands at byte 4,154,741 of a 4,423,356-byte
+        // stderr while Node truncates piped stderr at 1 MiB on exit. Measured on
+        // intelephense@1.18.5, linux, Node v22.22.1:
+        //   $ intelephense --version 2>&1 | wc -c              -> 1048576
+        //   $ intelephense --version 2>&1 | grep -c "Connection input stream is not set" -> 0
+        //   $ intelephense --version 2>err.txt; wc -c < err.txt -> 4423356
+        // Same run over the alternatives, each with stdin closed the way
+        // verifyToolBinary closes it (`input: ""`):
+        //   --help, -v, --socket=0 -> identical dump (exit 1, 4423356 bytes,
+        //     marker at 4154741, 1048576 through a pipe, marker absent)
+        //   --stdio                -> exit 1 with ZERO bytes on either stream,
+        //     so it carries no marker to rescue on either.
+        // No checkArgs value produces a verdict. Verified spawn-free instead.
         id: "intelephense",
         name: "Intelephense",
         checkCommand: "intelephense",
         checkArgs: ["--version"],
+        verification: "package-entry",
         installStrategy: "npm",
         packageName: "intelephense",
         binaryName: "intelephense",
@@ -690,6 +817,8 @@ export const TOOLS = [
             // bare binary, no archive
         },
     },
+    ...MANAGED_GITHUB_FORMATTERS.map(managedGitHubFormatterTool),
+    ...MANAGED_MAVEN_FORMATTERS.map(managedMavenFormatterTool),
     {
         id: "rust-analyzer",
         name: "rust-analyzer",
@@ -1616,29 +1745,16 @@ function isAstGrepVersionOutput(output) {
     return /\bast[- ]grep\b/i.test(output);
 }
 async function verifyAstGrepProbePath(binPath) {
-    return new Promise((resolve) => {
-        let proc;
-        try {
-            proc = spawn(binPath, ["--version"], {
-                stdio: ["ignore", "pipe", "pipe"],
-                shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(binPath),
-                timeout: 5000,
-            });
-        }
-        catch {
-            // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
-            // bug class, #533) — best-effort probe, resolve rather than reject.
-            resolve(false);
-            return;
-        }
-        let output = "";
-        proc.stdout?.on("data", (data) => (output += data));
-        proc.stderr?.on("data", (data) => (output += data));
-        proc.on("exit", (code) => {
-            resolve(code === 0 && isAstGrepVersionOutput(output));
-        });
-        proc.on("error", () => resolve(false));
+    // #2894: through the probe seam rather than a hand-rolled `spawn` promise.
+    // `probeToolAsync` already owns the synchronous-throw case (#533), the
+    // Windows `.cmd`/`.bat` resolution this used `shell: true` for, and the
+    // timeout tree-kill a bare `spawn({ timeout })` does not do.
+    const result = await probeToolAsync(binPath, ["--version"], {
+        timeout: 5000,
     });
+    return (!result.error &&
+        result.status === 0 &&
+        isAstGrepVersionOutput(`${result.stdout}${result.stderr}`));
 }
 // Exported for testing only.
 export async function checkProbeCache(toolId) {
@@ -1851,6 +1967,111 @@ function extractVersionToken(output) {
  * maven/archive) never populate or read this map.
  */
 const lastManagedInstallVersion = new Map();
+/**
+ * The package whose entry module verifies `tool`'s managed install spawn-free,
+ * or undefined when the tool is verified by spawning `checkArgs` (#2722).
+ * Registry-declared per tool — never inferred from the strategy: a spawn probe
+ * is the stronger check everywhere it can actually return a verdict.
+ */
+export function packageEntryVerification(tool) {
+    return tool.verification === "package-entry" ? tool.packageName : undefined;
+}
+/**
+ * Spawn-free verification of a managed npm install (#2722).
+ *
+ * For an stdio LSP server with no CLI surface, every `checkArgs` value is a
+ * throw, and #208's transport-required rescue is output-ORDER dependent: Node
+ * prints the offending source line ahead of the error, so a server whose bundle
+ * is megabytes of minified JS pushes the marker past both our retained window
+ * and Node's own 1 MiB pipe truncation. The bytes never leave the child, so no
+ * spawn can answer "is this install intact".
+ *
+ * The evidence used instead is the same class the `archive` strategy already
+ * accepts through `treeMarker`: the installed tree is inspected on disk. The
+ * install verifies when the package directory beside the `.bin` shim carries a
+ * readable `package.json` with a `version`, and the entry module that
+ * package.json itself names — `bin[<shim name>]` or a bare `bin` string —
+ * exists as a non-empty file. `main` is deliberately NOT a fallback: npm
+ * creates the `node_modules/.bin/<shim>` this function is given only from a
+ * `bin` field, so a manifest without one cannot be the manifest behind this
+ * shim. That is exactly what `verifyToolBinary` was documented to catch here —
+ * broken symlinks and partial installs — and it is strictly more than the
+ * `--version` spawn can report for this class.
+ */
+export async function verifyNpmPackageEntry(binPath, packageName) {
+    // `<...>/node_modules/.bin/<shim>` → `<...>/node_modules`.
+    const nodeModulesDir = path.dirname(path.dirname(binPath));
+    const pinned = parsePinnedVersion(packageName);
+    const bareName = pinned
+        ? packageName.slice(0, -(pinned.length + 1))
+        : packageName;
+    const packageDir = path.join(nodeModulesDir, ...bareName.split("/"));
+    const shimName = path
+        .basename(binPath)
+        .replace(/\.(cmd|exe|ps1|bat)$/i, "")
+        .toLowerCase();
+    const fail = (reason) => {
+        logSessionStart(`auto-install verify: failed for ${binPath} (check=package-entry, kind=${reason})`);
+        return false;
+    };
+    // R2-F1: the shim ITSELF, before anything else. Every path below is DERIVED
+    // from `binPath`, so without this a partial install — npm never wrote the
+    // `.bin` entry, or wrote one that is empty, a directory, or a symlink
+    // dangling at a deleted target — verified `true` on the strength of a
+    // package tree that nothing can execute, and `installNpmTool` then recorded
+    // the install as SUCCEEDED. `classifyInstallOutcome` grades any non-"failed"
+    // outcome as `⚠ unavailable (succeeded)`, so that answer re-hid exactly the
+    // nightly row #2722 exists to expose. `statSync` FOLLOWS the link, which is
+    // what makes missing and dangling one branch.
+    try {
+        const shim = statSync(binPath);
+        if (!shim.isFile() || shim.size === 0)
+            return fail("shim-not-a-file");
+    }
+    catch {
+        return fail("shim-missing");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(await fs.readFile(path.join(packageDir, "package.json"), "utf8"));
+    }
+    catch {
+        return fail("package-json-unreadable");
+    }
+    if (typeof manifest.version !== "string" || !manifest.version) {
+        return fail("package-json-no-version");
+    }
+    const bin = manifest.bin;
+    const entry = typeof bin === "string"
+        ? bin
+        : bin && typeof bin === "object"
+            ? Object.entries(bin).find(
+            // Case-folded on purpose: on a case-insensitive filesystem the
+            // shim on disk can differ in case from the manifest key npm
+            // wrote it from, and `path.basename` reads the disk name.
+            ([name]) => name.toLowerCase() === shimName)?.[1]
+            : undefined;
+    if (typeof entry !== "string" || !entry) {
+        return fail("package-json-no-entry");
+    }
+    try {
+        const stat = statSync(path.join(packageDir, entry));
+        if (!stat.isFile() || stat.size === 0)
+            return fail("entry-not-a-file");
+    }
+    catch {
+        return fail("entry-missing");
+    }
+    // R2-F3 (catalog shape 31): "did the new verifier run at all, and on what"
+    // has to be answerable from sessionstart.log, not only from a debug build —
+    // the failure branches above already log there. Measured volume on a real
+    // intelephense install, scratch PI_LENS_HOME: TWO rows on the session that
+    // installs (installNpmTool's verify, then the post-install resolution), and
+    // ZERO on every later session — the probe cache answers before any verify
+    // runs (`auto-install ensure intelephense: probe cache hit`).
+    logSessionStart(`auto-install verify: succeeded for ${binPath} (check=package-entry, version=${manifest.version}, entry=${entry})`);
+    return true;
+}
 /**
  * Verify a tool binary actually works by running its configured checkArgs.
  * This catches broken symlinks, partial installs, and corrupted binaries.
@@ -1878,7 +2099,26 @@ onTransient,
  * sensitive caller on the dispatch hot path passes a shorter one and treats
  * the expiry as transient rather than as a verdict (#1657).
  */
-timeoutMs = 10000, verificationArgs = ["--version"]) {
+timeoutMs = 10000, verificationArgs = ["--version"], 
+/**
+ * Package name from {@link packageEntryVerification} — present only for a
+ * registry entry declaring `verification: "package-entry"`. When present the
+ * spawn is skipped entirely and {@link verifyNpmPackageEntry} answers (#2722).
+ */
+packageEntryOf, 
+/**
+ * Called when a `false` verdict is INCONCLUSIVE rather than a verdict: the
+ * transport-required matcher was armed, never matched, and the child's
+ * output was cut off before the tail arrived, so the #208 rescue could not
+ * be evaluated at all (#2722). Distinct from `onTransient` on purpose — the
+ * prober DID run to completion and re-probing reproduces it exactly, so this
+ * is a durable "cannot be verified", not a stall (catalog shape 13). A
+ * caller must not treat it as "broken" and delete the installation.
+ */
+onInconclusive) {
+    if (packageEntryOf !== undefined) {
+        return verifyNpmPackageEntry(binPath, packageEntryOf);
+    }
     // #2015: safeSpawnAsync instead of raw spawn. Raw spawn's timeout
     // SIGTERMed only cmd.exe on Windows (.cmd shims run shell:true), orphaning
     // the grandchild node process - which kept scanning, held handles against
@@ -1937,6 +2177,31 @@ timeoutMs = 10000, verificationArgs = ["--version"]) {
         // verdict from the binary (#1569 transient semantics).
         if (result.signal !== undefined || result.spawnFailure)
             onTransient?.();
+        if (result.outputTruncated &&
+            result.signal === undefined &&
+            !result.spawnFailure) {
+            // #2722: the transport-required matcher above is armed on EVERY probe,
+            // and it never matched — but the output we kept is a prefix, so the
+            // marker may simply sit past it (intelephense emits ~4 MB of bundle
+            // ahead of its own diagnostic). "Unmatched within a truncated prefix"
+            // is not "this binary is broken"; callers must not delete the install
+            // on it. Recorded as its own kind so a monitor can tell an unreadable
+            // probe apart from a rejected binary.
+            //
+            // R2-F4: gated on the probe having actually FINISHED. A verbose child
+            // that is SIGTERMed at the timeout also arrives here truncated, and
+            // that is the #1569 transient class one line above, not this one —
+            // ungated, the two overlapped and `installNpmTool` (which tests
+            // inconclusive first) replaced the #2015 transient message with this
+            // one. The doc comment's "the prober DID run to completion" is now
+            // true rather than aspirational.
+            onInconclusive?.();
+            recordDegradationOnce({
+                kind: "installer-verification-inconclusive",
+                subject: binPath,
+                reason: `transport-required marker unresolved in truncated output (${verificationArgs.join(" ")})`,
+            });
+        }
         const kind = result.spawnFailure?.kind ??
             (result.signal
                 ? `killed-signal=${result.signal}`
@@ -1985,29 +2250,15 @@ export async function getAllToolStatuses() {
             status.installed = true;
             status.source = "global-path";
             status.path = tool.checkCommand;
-            // Try to get version
-            const versionResult = await new Promise((resolve) => {
-                let proc;
-                try {
-                    proc = spawn(tool.checkCommand, ["--version"], {
-                        stdio: ["ignore", "pipe", "pipe"],
-                        shell: process.platform === "win32",
-                        timeout: 5000,
-                    });
-                }
-                catch {
-                    // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the
-                    // pidusage bug class, #533) — best-effort, resolve empty version.
-                    resolve("");
-                    return;
-                }
-                let out = "";
-                proc.stdout?.on("data", (d) => (out += d));
-                proc.stderr?.on("data", (d) => (out += d));
-                proc.on("exit", () => resolve(out.trim().split("\n")[0]?.slice(0, 30) || ""));
-                proc.on("error", () => resolve(""));
+            // Try to get version — through the probe seam (#2894), which owns the
+            // synchronous-throw case (#533) and the timeout tree-kill that a bare
+            // `spawn({ timeout })` promise did not do.
+            const probe = await probeToolAsync(tool.checkCommand, ["--version"], {
+                timeout: 5000,
             });
-            status.version = versionResult || undefined;
+            status.version =
+                `${probe.stdout}${probe.stderr}`.trim().split("\n")[0]?.slice(0, 30) ||
+                    undefined;
             statuses.push(status);
             continue;
         }
@@ -2056,7 +2307,7 @@ export async function getAllToolStatuses() {
         const localPath = installerPlatform() === "win32" ? `${localBase}.cmd` : localBase;
         try {
             await fs.access(localPath);
-            if (await verifyToolBinary(localPath, undefined, undefined, getToolVerificationTimeout(tool), tool.checkArgs)) {
+            if (await verifyToolBinary(localPath, undefined, undefined, getToolVerificationTimeout(tool), tool.checkArgs, packageEntryVerification(tool))) {
                 status.installed = true;
                 status.source = "pi-lens-auto";
                 status.path = localPath;
@@ -2225,7 +2476,7 @@ async function getToolPathResolved(toolId, onTransient) {
         const cmdPath = `${localBase}.cmd`;
         try {
             await fs.access(cmdPath);
-            if (await verifyToolBinary(cmdPath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
+            if (await verifyToolBinary(cmdPath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs, packageEntryVerification(tool))) {
                 return cmdPath;
             }
             logSessionStart(`auto-install verify: ${cmdPath} exists but is broken, will reinstall`);
@@ -2238,7 +2489,7 @@ async function getToolPathResolved(toolId, onTransient) {
         const exePath = `${localBase}.exe`;
         try {
             await fs.access(exePath);
-            if (await verifyToolBinary(exePath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
+            if (await verifyToolBinary(exePath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs, packageEntryVerification(tool))) {
                 return exePath;
             }
             logSessionStart(`auto-install verify: ${exePath} exists but is broken, will reinstall`);
@@ -2250,7 +2501,7 @@ async function getToolPathResolved(toolId, onTransient) {
     if (installerPlatform() !== "win32") {
         try {
             await fs.access(localBase);
-            if (await verifyToolBinary(localBase, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
+            if (await verifyToolBinary(localBase, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs, packageEntryVerification(tool))) {
                 return localBase;
             }
             logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
@@ -2349,6 +2600,13 @@ function getGitHubInstalledBinaryName(binaryName, platform, assetName) {
         return `${binaryName}.cmd`;
     return `${binaryName}.exe`;
 }
+function launcherForGitHubAsset(spec, assetName) {
+    if (spec.launcher === "php" && assetName.endsWith(".phar"))
+        return "php";
+    if (spec.launcher === "java" && assetName.endsWith(".jar"))
+        return "java";
+    return undefined;
+}
 function getArchiveBinaryCandidates(binaryName, platform, assetName) {
     if (platform !== "win32")
         return [binaryName];
@@ -2701,10 +2959,35 @@ prefetchedRelease) {
     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);
+    let destPath = path.join(GITHUB_BIN_DIR, finalBinaryName);
     const assetName = asset.name;
+    const launcherRuntime = launcherForGitHubAsset(spec, assetName);
+    if (launcherRuntime &&
+        !(await isCommandAvailable(launcherRuntime, ["--version"]))) {
+        logSessionStart(`github-install ${tool.id}: ${launcherRuntime} not found — asset requires a runtime launcher`);
+        return undefined;
+    }
     try {
-        if (assetName.endsWith(".gz") && !assetName.endsWith(".tar.gz")) {
+        if (launcherRuntime) {
+            const assetPath = path.join(GITHUB_BIN_DIR, `${tool.id}${assetName.endsWith(".phar") ? ".phar" : ".jar"}`);
+            await writeFileAtomicAsync(assetPath, assetBuffer, {
+                bestEffort: false,
+                mode: 0o750,
+            });
+            const launcherName = isWindows ? `${binaryName}.bat` : binaryName;
+            destPath = path.join(GITHUB_BIN_DIR, launcherName);
+            const runtimeTarget = assetName.endsWith(".phar")
+                ? `${tool.id}.phar`
+                : `${tool.id}.jar`;
+            const command = isWindows
+                ? `@echo off\r\n${launcherRuntime} "%~dp0${runtimeTarget}" %*\r\n`
+                : `#!/bin/sh\nexec ${launcherRuntime} "$(dirname "$0")/${runtimeTarget}" "$@"\n`;
+            await writeFileAtomicAsync(destPath, command, {
+                bestEffort: false,
+                mode: isWindows ? undefined : 0o750,
+            });
+        }
+        else 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((resolve, reject) => {
                 const gunzip = createGunzip();
@@ -2873,6 +3156,7 @@ export function npmToolNeedsPostinstall(packageName) {
  * that wanders off it.
  */
 export function getRefreshableManagedNpmTools() {
+    const seenPackages = new Set();
     return getRefreshableManagedTools()
         .filter((candidate) => candidate.strategy === "npm")
         .map((candidate) => ({
@@ -2881,7 +3165,13 @@ export function getRefreshableManagedNpmTools() {
         // have both, so these are total.
         packageName: candidate.packageName,
         binaryName: candidate.binaryName,
-    }));
+    }))
+        .filter((candidate) => {
+        if (seenPackages.has(candidate.packageName))
+            return false;
+        seenPackages.add(candidate.packageName);
+        return true;
+    });
 }
 /** The Maven GAV a `maven` entry pins, as a stable identity string. */
 function mavenCoordinate(spec) {
@@ -2928,6 +3218,7 @@ export function getRefreshableManagedTools() {
                     packageName: tool.packageName,
                     binaryName: tool.binaryName,
                     verificationTimeoutMs: tool.verificationTimeoutMs,
+                    packageEntryOf: packageEntryVerification(tool),
                 });
                 break;
             }
@@ -3046,7 +3337,7 @@ async function probeManagedToolVersion(tool) {
     if (!cached?.path || !existsSync(cached.path))
         return undefined;
     try {
-        const result = await safeSpawnAsync(cached.path, tool.checkArgs, {
+        const result = await probeToolAsync(cached.path, tool.checkArgs, {
             timeout: getToolVerificationTimeout(tool),
             input: "",
             ignoreAmbientSignal: true,
@@ -3752,12 +4043,20 @@ async function installArchiveTool(tool) {
  * generic fallback `finishInstallAttempt` uses when nothing set it.
  */
 function recordPackageManagerInstallException(toolId, strategyLabel, packageName, err) {
-    const message = err.message;
+    const message = boundInstallError(err.message);
     logSessionStart(`auto-install ${strategyLabel} ${packageName}: exception: ${message}`);
     installFailureReasons.set(toolId, message);
     return undefined;
 }
-async function installNpmTool(toolId, packageName, binaryName, verificationArgs = ["--version"], verificationTimeoutMs = 10_000) {
+const INSTALL_ERROR_LINE_LIMIT = 1000;
+const INSTALL_CANDIDATE_ERROR_LIMIT = 200;
+function boundInstallError(value, limit = INSTALL_ERROR_LINE_LIMIT) {
+    const line = value.replace(/[\r\n]+/g, " ").trim();
+    return line.length > limit ? `${line.slice(0, limit - 3)}...` : line;
+}
+async function installNpmTool(toolId, packageName, binaryName, verificationArgs = ["--version"], verificationTimeoutMs = 10_000, 
+/** See {@link packageEntryVerification} — spawn-free verification (#2722). */
+packageEntryOf) {
     try {
         // Ensure tools directory exists
         await fs.mkdir(TOOLS_DIR, { recursive: true });
@@ -3837,11 +4136,15 @@ async function installNpmTool(toolId, packageName, binaryName, verificationArgs
         debugLog(`Verifying ${binaryName}...`);
         let isValid = false;
         let lastAttemptTransient = false;
+        let lastAttemptInconclusive = false;
         for (let attempt = 1; attempt <= 3; attempt++) {
             lastAttemptTransient = false;
+            lastAttemptInconclusive = false;
             isValid = await verifyToolBinary(binPath, undefined, () => {
                 lastAttemptTransient = true;
-            }, verificationTimeoutMs, verificationArgs);
+            }, verificationTimeoutMs, verificationArgs, packageEntryOf, () => {
+                lastAttemptInconclusive = true;
+            });
             if (isValid)
                 break;
             if (attempt < 3) {
@@ -3849,6 +4152,37 @@ async function installNpmTool(toolId, packageName, binaryName, verificationArgs
                 await new Promise((r) => setTimeout(r, 1000 * attempt));
             }
         }
+        if (!isValid && lastAttemptInconclusive) {
+            // #2722: the probe ran to completion but could not decide — the #208
+            // transport-required matcher was armed, never matched, and the kept
+            // output is a truncated prefix, so the marker may sit past it (the
+            // class intelephense fell into: ~4 MB of bundle ahead of the marker,
+            // unreachable through any pipe). Same rule as the transient branch
+            // below (#2015): a non-verdict must not delete a freshly installed
+            // package. Deliberately NOT folded into `lastAttemptTransient` —
+            // re-probing reproduces this exactly, so it is durable, and a
+            // transient verdict would keep re-arming the reinstall path
+            // (catalog shape 13).
+            // R2-F2: a non-verdict is a reason to keep ONLY while the tree on disk
+            // still looks like a complete install. With intelephense verified
+            // spawn-free, no registry entry reaches this branch healthy (measured:
+            // no other npm-strategy LSP server emits more than 1,527 bytes), so
+            // its live population is BROKEN servers that spew past the retained
+            // window and die — and for those the delete was the only repair that
+            // existed. Measured on npm 9.2.0 against a real managed prefix: a
+            // package file corrupted IN PLACE is not repaired by re-installing
+            // (`up to date`, the zeroed file stays zeroed), while a package
+            // directory, a `.bin` shim or a nested dependency that is GONE is
+            // reinstalled. So the same on-disk evidence `verification:
+            // "package-entry"` uses decides keep-vs-delete here — strictly as a
+            // gate, never as a verdict: the install is still recorded as failed,
+            // so the tool still reads `✗` and nothing is re-hidden.
+            if (await verifyNpmPackageEntry(binPath, packageName)) {
+                logSessionStart(`auto-install ${packageName}: verification inconclusive (output truncated before the transport-required marker) but the installed tree is intact; keeping installation for re-probe`);
+                return undefined;
+            }
+            logSessionStart(`auto-install ${packageName}: verification inconclusive AND the installed tree is incomplete; cleaning up so the next install can repair it`);
+        }
         if (!isValid && lastAttemptTransient) {
             // #2015: a killed/spawn-failed prober is NOT a verdict about the
             // binary (#1569 semantics). Cold-start verifies on fresh installs
@@ -3925,7 +4259,7 @@ options = {}) {
                 ? [...verb, packageName]
                 : ["-m", "pip", ...verb, packageName],
         }));
-        let lastError = "";
+        const errors = [];
         for (const candidate of pipCandidates) {
             const pipResult = await safeSpawnAsync(candidate.command, candidate.args, {
                 timeout: 120_000,
@@ -4015,10 +4349,11 @@ options = {}) {
                 }
                 return packageName;
             }
-            lastError = `${candidate.command} ${candidate.args.join(" ")}: ${outcome.error}`;
-            debugLog(`[pip-fallback] ${lastError}`);
+            const candidateError = `${candidate.command} ${candidate.args.join(" ")}: ${boundInstallError(outcome.error, INSTALL_CANDIDATE_ERROR_LIMIT)}`;
+            errors.push(candidateError);
+            debugLog(`[pip-fallback] ${candidateError}`);
         }
-        throw new Error(`Failed to install ${packageName}: no usable pip command found (${lastError || "unknown error"})`);
+        throw new Error(`Failed to install ${packageName}: no usable pip command found (${errors.join(" | ") || "unknown error"})`);
     }
     catch (err) {
         return recordPackageManagerInstallException(toolId, "pip", packageName, err);
@@ -4132,7 +4467,7 @@ export async function installTool(toolId) {
             case "npm": {
                 if (!tool.packageName || !tool.binaryName)
                     return false;
-                const npmPath = await installNpmTool(tool.id, tool.packageName, tool.binaryName, tool.checkArgs, getToolVerificationTimeout(tool));
+                const npmPath = await installNpmTool(tool.id, tool.packageName, tool.binaryName, tool.checkArgs, getToolVerificationTimeout(tool), packageEntryVerification(tool));
                 if (npmPath !== undefined) {
                     // #1746 review F4: an install just resolved this package's range
                     // against the registry, so record it as freshly checked. Otherwise a
@@ -4170,6 +4505,12 @@ export async function installTool(toolId) {
             case "github": {
                 if (!tool.github)
                     return false;
+                if (!tool.github.assetMatch(process.platform, process.arch)) {
+                    const reason = `unsupported platform=${process.platform} arch=${process.arch}`;
+                    noteInstallAttempt(tool.id, "unavailable", reason);
+                    logSessionStart(`auto-install ${tool.id}: ${reason}`);
+                    return false;
+                }
                 const ghPath = await installGitHubTool(tool);
                 return finishInstallAttempt(tool.id, ghPath !== undefined, startedAt);
             }
@@ -4182,6 +4523,12 @@ export async function installTool(toolId) {
             case "archive": {
                 if (!tool.archive)
                     return false;
+                if (!resolveArchiveUrl(tool.archive)) {
+                    const reason = `unsupported platform=${process.platform} arch=${process.arch}`;
+                    noteInstallAttempt(tool.id, "unavailable", reason);
+                    logSessionStart(`auto-install ${tool.id}: ${reason}`);
+                    return false;
+                }
                 const archivePath = await installArchiveTool(tool);
                 return finishInstallAttempt(tool.id, archivePath !== undefined, startedAt);
             }
@@ -4500,6 +4847,8 @@ export function getToolInstallStrategy(toolId) {
  * "at least one platform" guard instead.
  */
 export const GITHUB_TOOLS = [
+    "cljfmt",
+    "php-cs-fixer",
     "shellcheck",
     "shfmt",
     "rust-analyzer",
@@ -4534,6 +4883,12 @@ export function resolveGitHubAsset(toolId, platform, arch) {
     const tool = TOOLS.find((t) => t.id === toolId);
     return tool?.github?.assetMatch(platform, arch);
 }
+export function resolveGitHubAssetLauncher(toolId, _platform, assetName) {
+    const tool = TOOLS.find((t) => t.id === toolId);
+    return tool?.github
+        ? launcherForGitHubAsset(tool.github, assetName)
+        : undefined;
+}
 export function resolveGitHubInstalledBinaryName(toolId, platform, assetName) {
     const tool = TOOLS.find((t) => t.id === toolId);
     if (!tool)