From 06e76129cd6b4e0cf383a39f89194a2e72019600 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Sat, 19 Sep 2026 00:31:14 -0700
Subject: [PATCH] fix(lsp): surface the pnpm failure reason and document the
 exotic-subdep block

pnpm prints ERR_PNPM_* to stdout, so the install warning showed an empty
reason. The composite live pass hit ERR_PNPM_EXOTIC_SUBDEP installing
@vue/language-server@2 (git-hosted transitive dep) with lsp.package_manager: pnpm;
the policy stays fail-closed, the docs now say why and how to opt out.
---
 agent/lsp/install.py                    | 4 +++-
 website/docs/user-guide/features/lsp.md | 6 +++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/agent/lsp/install.py b/agent/lsp/install.py
index 06341963ff..fcf7f5d908 100644
--- a/agent/lsp/install.py
+++ b/agent/lsp/install.py
@@ -175,7 +175,9 @@ def _run_installer(tool: str, pkg: str, cmd: list, *, timeout: int, env: Optiona
             timeout=timeout, env=env, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags(),
         )
         if proc.returncode != 0:
-            logger.warning("[install] %s install failed for %s: %s", tool, pkg, proc.stderr.strip()[:500])
+            # pnpm reports ERR_PNPM_* on stdout with an empty stderr; log whichever stream carries the reason.
+            detail = (proc.stderr.strip() or proc.stdout.strip())[:500]
+            logger.warning("[install] %s install failed for %s: %s", tool, pkg, detail)
             return False
     except (subprocess.TimeoutExpired, OSError) as e:
         logger.warning("[install] %s install errored for %s: %s", tool, pkg, e)
diff --git a/website/docs/user-guide/features/lsp.md b/website/docs/user-guide/features/lsp.md
index f079bbda4c..0a77a35e77 100644
--- a/website/docs/user-guide/features/lsp.md
+++ b/website/docs/user-guide/features/lsp.md
@@ -200,7 +200,11 @@ lsp:
   # using npm, so a pnpm/yarn supply-chain policy (minimumReleaseAge,
   # allowBuilds, …) is never bypassed. Yarn Berry (2+): its default PnP
   # linker writes no node_modules/.bin, so set `nodeLinker: node-modules`
-  # in <HERMES_HOME>/lsp/.yarnrc.yml.
+  # in <HERMES_HOME>/lsp/.yarnrc.yml. pnpm 11 blocks git-hosted transitive
+  # deps by default (ERR_PNPM_EXOTIC_SUBDEP); @vue/language-server 2.x pulls
+  # one in, so under pnpm that server is skipped with the pnpm error in the
+  # log — install it once with npm, or relax block-exotic-subdeps in
+  # <HERMES_HOME>/lsp/.npmrc if your policy allows it.
   package_manager: npm
 
   # How long an unused language-server client stays alive (seconds).