baldart 3.33.0 → 3.33.1

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.33.1] - 2026-05-30
+
+Fixes a **false-positive in the LSP layer's verify step** that let `/lsp-bootstrap` (and `baldart configure` / `doctor`) report a language server as `verified` while every real LSP call failed with `Executable not found in $PATH` — a dead layer masked by `codebase-architect`'s silent Grep fallback. Root cause was a **resolution mismatch**: verify used `npx --no-install typescript-language-server --version` (resolves from `node_modules/.bin`), but the consumer — Claude Code's LSP tool — spawns the server **by name from `$PATH`**. The npm-dev install (`npm install --save-dev`) put the binary in `node_modules/.bin`, which is *not* on `$PATH`, so verify passed and spawn failed. The npm-managed adapters now install **globally** so the binary lands on `$PATH`, and verify checks `$PATH` reachability the *same way the consumer spawns it*. **No new `baldart.config.yml` keys** — reachability is computed, not configured, so the schema-propagation rule does not apply.
+
+### Fixed — LSP verify no longer reports unreachable servers as `verified`
+
+- **[src/utils/lsp-installer.js](src/utils/lsp-installer.js)**: `verifyServers()` rewritten around a 3-state taxonomy. It first probes `$PATH` reachability via `command -v <binary>` (new `_isOnPath` helper — mirrors the consumer's by-name spawn exactly), then runs the functional `verifyCommand()`. Results carry `status` ∈ `verified` (on `$PATH`, probe passed) / `installed-but-unreachable` (present in `node_modules` but not on `$PATH` — new `_isInstalledLocally` helper fingerprints the legacy devDep install; `fix` = global-install command) / `unreachable` / `not-installed` / `unknown-adapter`. Never throws.
+- **[src/utils/lsp-adapters/typescript.js](src/utils/lsp-adapters/typescript.js)** + **[src/utils/lsp-adapters/python.js](src/utils/lsp-adapters/python.js)**: `installMode` `npm-dev` → `npm-global`; `installCommand()` → `npm install -g …`; `verifyCommand()` → `<binary> --version` (resolved from `$PATH`, mirroring the consumer) instead of `npx --no-install …`. System adapters (go/rust/ruby) were already PATH-correct and are unchanged.
+
+### Changed — `configure` records unreachable servers; `doctor` fix is now real
+
+- **[src/commands/configure.js](src/commands/configure.js)**: **every** known-adapter result that isn't cleanly `verified` is now recorded in `lsp.installed_servers` (like system-mode pending installs) instead of being dropped by the old `filter(v => v.ok)` — otherwise re-runs reinstall blindly and `doctor` never sees the mismatch. This covers both `installed-but-unreachable` and the npm-global happy-path trap where `npm install -g` exits 0 but npm's global bin dir isn't on the current `$PATH` (→ status `not-installed`, since `npx` can't see the global prefix either) — without this, the primary configure path would have silently reintroduced the dead layer. The fix command (+ `npm prefix -g` PATH hint) is surfaced inline for each.
+- **[src/commands/doctor.js](src/commands/doctor.js)**: the `lsp-fix` remediation now reinstalls globally (a real fix that puts the binary on `$PATH`), where before it re-ran `npm install --save-dev` — a no-op for the reachability problem. The `why` text explains the `$PATH` contract, and a post-reinstall re-verify surfaces the `npm prefix -g` PATH escape when a server stays unreachable (so a misconfigured global bin dir doesn't trap the user in a reinstall loop).
+
+### Docs
+
+- **[framework/.claude/skills/lsp-bootstrap/SKILL.md](framework/.claude/skills/lsp-bootstrap/SKILL.md)**: Output Contract redefines `verified` as `$PATH`-reachable, adds the `installed-but-unreachable` status, and documents the **cold-start caveat** (first query may under-report references until indexing completes).
+- **[framework/agents/code-search-protocol.md](framework/agents/code-search-protocol.md)**: new fallback rule for cold-start under-reporting — re-issue the first query before trusting a suspiciously-low reference count; never declare a helper unused off one cold find-references.
+- **[framework/docs/LSP-LAYER.md](framework/docs/LSP-LAYER.md)** + **[framework/docs/PROJECT-CONFIGURATION.md](framework/docs/PROJECT-CONFIGURATION.md)**: adapter-contract table, install-mode descriptions, `verifyServers` contract, and troubleshooting §6.3/§6.4 updated for global install + `$PATH` reachability + the PATH-mismatch cause.
+
 ## [3.33.0] - 2026-05-30
 
 Closes a **structural silent-partial-install** failure mode (observed on the `mayo` consumer, 3.28→3.31, still live in 3.32.0; same class as the historic v3.27.1 bug): `add` was **non-atomic** — the hook registration ran *after* optional blocking prompts (git aliases, configure). In a non-TTY context (Claude's Bash tool never has a TTY on stdin) or on any interruption, those `inquirer` prompts throw/hang, so `.framework/` + `state.json` landed on the new version while `Hooks.registerAll` never ran — a half-install that `baldart status` still reported as "Valid". The fix makes install atomic (correctness-critical mutations run **before** every optional prompt), adds a **post-flight hook assert** that refuses to declare success with any active hook missing, and finally exposes `add --yes` so agents/CI can install unattended. Two additive, non-breaking follow-ups ship alongside. **No new `baldart.config.yml` keys** — `--yes` is a CLI flag, so the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.33.0
+3.33.1

package/framework/.claude/skills/lsp-bootstrap/SKILL.md

@@ -3,8 +3,8 @@ name: lsp-bootstrap
 description: >
   Install, verify, and document the LSP symbol-search layer for this project.
   Detects languages (TypeScript, Python, Go, Rust, Ruby), installs the matching
-  language servers (npm devDep where possible, system command otherwise),
-  verifies binaries are reachable, and writes lsp.installed_servers to
+  language servers (global npm install where possible, system command otherwise),
+  verifies binaries are reachable on $PATH, and writes lsp.installed_servers to
   baldart.config.yml. Use when the user says /lsp-bootstrap, "install LSP",
   "set up symbol search", or after enabling features.has_lsp_layer for the
   first time. Idempotent — re-running on an already-configured project
@@ -32,15 +32,22 @@ context on textual collisions; with it, references resolve to the same symbol
    present (markers: `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
    `Gemfile`, plus heuristic fallbacks).
 3. For each detected language:
-   - **npm-dev** adapters (TypeScript, Python via pyright): runs `npm install
-     --save-dev <pkg>` with user confirmation.
+   - **npm-global** adapters (TypeScript, Python via pyright): runs `npm install
+     -g <pkg>` with user confirmation. The install is **global** on purpose —
+     the consumer (Claude Code's LSP tool) spawns the server by name from
+     `$PATH`, and a project-local devDep under `node_modules/.bin/` is not on
+     `$PATH`, so it would never be reachable.
    - **system** adapters (Go gopls, Rust rust-analyzer, Ruby ruby-lsp): prints
      the install command for the user to run in a separate terminal. Does NOT
      execute system-level installs automatically.
-4. Verifies each binary is reachable (`<binary> --version`).
-5. Updates `lsp.installed_servers` in `baldart.config.yml` with the verified
-   set. System-mode servers are recorded even if not yet reachable (the user
-   may have a pending install) — `baldart doctor` will flag the mismatch.
+4. Verifies each binary is **reachable on `$PATH` the same way the consumer
+   spawns it** (`command -v <binary>`), then runs `<binary> --version` for the
+   functional check. A binary present only in `node_modules/.bin` (legacy
+   devDep) is reported as `installed-but-unreachable`, NOT `verified`.
+5. Updates `lsp.installed_servers` in `baldart.config.yml`. Both `verified` and
+   `installed-but-unreachable` servers are recorded (the latter so re-runs don't
+   reinstall blindly and `baldart doctor` keeps flagging the mismatch);
+   system-mode pending installs are recorded too.
 6. Prints a summary table and points the user to
    `framework/agents/code-search-protocol.md` for runtime behavior.
 
@@ -66,8 +73,11 @@ context on textual collisions; with it, references resolve to the same symbol
 4. **Install.** Run the appropriate `installCommand()`. Capture failures into a
    "Skipped" bucket — never abort the whole skill on one failure.
 
-5. **Verify.** For each installed server, call its `verifyCommand()`. Mark the
-   results.
+5. **Verify.** For each installed server, the installer first checks `$PATH`
+   reachability (`command -v <binary>` — exactly how the consumer spawns it),
+   then runs `verifyCommand()`. Mark each result `verified`,
+   `installed-but-unreachable` (present in node_modules but not on `$PATH` —
+   print the global-install fix), or `not-installed`.
 
 6. **Persist.** Update `baldart.config.yml`:
    ```yaml
@@ -86,19 +96,25 @@ A single short status block — never a multi-page report. Format:
 
 ```
 LSP bootstrap:
-  ✓ typescript-language-server (npm devDep, verified)
-  ✓ pyright (npm devDep, verified)
+  ✓ typescript-language-server (npm -g, on $PATH, verified)
+  ⚠ pyright — installed but not on $PATH; run `npm install -g pyright`, then `baldart doctor`
   ⚠ gopls — run `go install golang.org/x/tools/gopls@latest`, then `baldart doctor`
   · ruby — not detected (no Gemfile)
 Config updated: baldart.config.yml lsp.installed_servers = [typescript, python, go]
 Next: codebase-architect will now prefer LSP find-references over Grep for symbols.
+Note: the first LSP query after a cold start may under-report references until the
+workspace finishes indexing — re-run the query once warm if a count looks low.
 ```
 
+`verified` is reserved for binaries that resolve on `$PATH` (the consumer's
+spawn path). Never report `verified` for a binary that only `npx --no-install`
+can find — that is precisely the false positive this skill must not emit.
+
 ## Notes
 
 - This skill never edits source code or installs binaries that aren't language
-  servers — its only side effect is `npm install --save-dev <lsp-package>` and a
-  YAML write to `baldart.config.yml`.
+  servers — its only side effect is `npm install -g <lsp-package>` (global, so
+  the binary is reachable on `$PATH`) and a YAML write to `baldart.config.yml`.
 - For Claude Code users: in addition to the binaries, you may need to load a
   code-intelligence plugin (`/plugin` in Claude Code). That step is documented
   in the printed output when applicable, but the skill does NOT manage Claude

package/framework/agents/code-search-protocol.md

@@ -75,6 +75,14 @@ Before picking a tier, classify the query:
   a path excluded by `tsconfig.json`).
 - LSP times out (>8s) → fall back to Grep for this query, log the symptom in
   the agent's reasoning so the user can re-run doctor.
+- **Cold start under-reporting**: the first LSP query in a session can return
+  an incomplete set (e.g. find-references returning 1 hit where the symbol has
+  6) until the language server finishes indexing the workspace. If a reference
+  count looks suspiciously low for a symbol you expect to be widely used, treat
+  the first result as a warm-up: re-issue the same query once before trusting
+  it, or cross-check with a single Grep. Do not act on a cold-start count as if
+  it were exhaustive (e.g. don't declare a helper "unused / safe to delete"
+  off one cold find-references).
 
 ## Examples
 

package/framework/docs/LSP-LAYER.md

@@ -38,8 +38,9 @@ function named `handleSubmit` declared in `src/forms/Login.tsx` returns
 exactly the callsites that resolve to *that* declaration; the CLI utility's
 unrelated `handleSubmit` is filtered out before any file is read.
 
-The layer is **opt-in** (some consumers don't want devDep churn, some target
-languages we don't have an adapter for yet) and **degrades gracefully** (when
+The layer is **opt-in** (some consumers don't want a global npm install for a
+language server, some target languages we don't have an adapter for yet) and
+**degrades gracefully** (when
 LSP is unavailable, agents silently fall back to the legacy RAG → Grep flow,
 so existing behavior is preserved).
 
@@ -133,8 +134,13 @@ configure prompt (the user can still say no). The prompt copy is
 
 When the user confirms, for each detected language:
 
-- **npm-dev mode** (TS, Python via pyright): `npm install --save-dev <pkg>`
-  runs in-process. Success → added to `lsp.installed_servers`.
+- **npm-global mode** (TS, Python via pyright): `npm install -g <pkg>` runs
+  in-process. The install is **global** — the consumer (Claude Code's LSP
+  tool) spawns the server by name from `$PATH`, so a project-local devDep in
+  `node_modules/.bin/` would never be reachable (this was the pre-v3.33.1
+  dead-layer bug). Reachable on `$PATH` → recorded as `verified`; present but
+  not on `$PATH` → recorded as `installed-but-unreachable` (with the
+  global-install fix printed).
 - **system mode** (Go, Rust, Ruby): the install command is *printed*, never
   executed. The server name is recorded as pending in `installed_servers`;
   `baldart doctor` re-verifies on the next run and flags the mismatch if the
@@ -180,8 +186,10 @@ npx baldart                    # smart doctor (no-arg, default since v3.2.0)
 ```
 
 `doctor.js` reads `config.lsp.installed_servers`. When
-`lsp.auto_verify !== false`, it executes each adapter's `verifyCommand()`
-(e.g. `npx --no-install typescript-language-server --version`). Output:
+`lsp.auto_verify !== false`, the installer first checks `$PATH` reachability
+(`command -v <binary>` — exactly how the consumer spawns the server), then runs
+each adapter's `verifyCommand()` (e.g. `typescript-language-server --version`)
+for the functional check. Output:
 
 ```
 ·  LSP layer        2 server(s) verified (typescript, python)
@@ -268,10 +276,10 @@ Every adapter is a class exporting:
 | `name`               | string getter       | Stable id used in `installed_servers` (e.g. `"typescript"`)|
 | `label`              | string getter       | Human-readable for prompts/diagnostics                     |
 | `binary`             | string getter       | Executable name expected on PATH or in node_modules        |
-| `installMode`        | `"npm-dev"` / `"system"` | How the installer treats this language               |
-| `npmPackage`         | string (npm-dev only) | What goes after `npm install --save-dev`                 |
+| `installMode`        | `"npm-global"` / `"system"` | How the installer treats this language            |
+| `npmPackage`         | string (npm-global only) | What goes after `npm install -g`                      |
 | `installCommand()`   | string              | The exact shell command (printed or executed)              |
-| `verifyCommand()`    | string              | A no-side-effect probe (e.g. `--version`)                  |
+| `verifyCommand()`    | string              | Functional probe run by name from `$PATH` (e.g. `<binary> --version`); `$PATH` reachability is checked separately by the installer via `command -v <binary>` |
 | `claudePluginId()`   | string \| null      | Native Claude Code plugin id (e.g. `typescript-lsp@claude-plugins-official`) — installed by the configure flow alongside the language server (v3.14.0+). `null` = no companion plugin |
 | `static detect(cwd)` | boolean             | Pure: does the language live in this repo?                 |
 
@@ -289,7 +297,13 @@ to the REGISTRY in `lsp-adapters/index.js`.
 - `recommend(langs?)` → entries with install metadata for UI consumption
 - `installServers(names, { interactive=true, dryRun=false })` →
   `{ installed, skipped, manual }` — returns rather than throws
-- `verifyServers(names)` → `[{ name, ok, output|error }]` — never throws
+- `verifyServers(names)` → `[{ name, ok, status, output?, error?, fix? }]` —
+  never throws. `status` ∈ `verified` (on `$PATH`, probe passed) /
+  `installed-but-unreachable` (in node_modules but not on `$PATH`; `fix` =
+  global-install command) / `unreachable` (on `$PATH` but probe errored) /
+  `not-installed` / `unknown-adapter`. Reachability is `command -v <binary>`,
+  mirroring how the consumer spawns the server — never `npx --no-install`,
+  which resolves from node_modules and produces a false positive.
 
 **Native Claude Code plugin layer (since v3.14.0):**
 
@@ -396,20 +410,34 @@ The autodetector found no supported language markers. Either:
 
 ### 6.3 "doctor says my server is broken but it works in my editor"
 
-`verifyCommand()` executes from the consumer cwd with a hard 8s timeout. If
-the language server takes longer than that to print `--version` (rare, but
-seen on first-run cold caches), the verify fails. Re-run `baldart doctor`
-once warm. If still failing, run the exact `verifyCommand()` string in your
-shell — the actual error will surface.
-
-### 6.4 "I want to enable the layer but not have devDeps in package.json"
-
-For TypeScript / Python you can override the adapter's `installMode` by
-writing an overlay at `.baldart/overlays/agents/codebase-architect.md`
-documenting your alternative install path (e.g. system pyright via uv), and
-then manually setting `lsp.installed_servers: [python]` in the config. The
-runtime layer doesn't care *how* the binary got there, only that it's
-reachable. `baldart doctor` will continue to verify it.
+Two common causes:
+
+1. **PATH-resolution mismatch (the usual culprit).** Your editor resolves the
+   language server through `node_modules/.bin`, `npx`, or its own bundled copy;
+   the Claude Code LSP tool spawns it **by name from `$PATH`**. A binary
+   installed as a project-local devDep is visible to the editor but reports
+   `installed-but-unreachable` here, because it isn't on `$PATH`. Fix: install
+   it globally (`npm install -g <pkg>`) — or, if you installed globally and it's
+   still unreachable, confirm npm's global bin dir (`npm prefix -g`/`npm bin -g`)
+   is on your `$PATH`. This was the pre-v3.33.1 false-positive bug: verify used
+   `npx --no-install` (node_modules resolution) and passed while the consumer's
+   `$PATH` spawn failed.
+2. **Cold-start timeout.** `verifyCommand()` executes from the consumer cwd with
+   a hard 8s timeout. If the server takes longer than that to print `--version`
+   (rare, seen on first-run cold caches), verify fails. Re-run `baldart doctor`
+   once warm. If still failing, run the exact `command -v <binary>` and
+   `verifyCommand()` strings in your shell — the actual error will surface.
+
+### 6.4 "I don't want a global npm install for the language server"
+
+The npm-global default exists because the consumer spawns the server from
+`$PATH`. If you'd rather manage the binary yourself (system pyright via uv, a
+Volta/asdf shim, a Nix profile, whatever), do it your way — just make sure the
+binary ends up on `$PATH`. Then write an overlay at
+`.baldart/overlays/agents/codebase-architect.md` documenting your install path
+and manually set `lsp.installed_servers: [python]` in the config. The runtime
+layer doesn't care *how* the binary got onto `$PATH`, only that it's reachable
+there. `baldart doctor` will continue to verify it via `command -v`.
 
 ---
 

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -216,11 +216,11 @@ Populated by `baldart configure` and the `/lsp-bootstrap` skill when `features.h
 | Key | Meaning |
 |---|---|
 | `lsp.installed_servers` | List of language IDs (`typescript`, `python`, `go`, `rust`, `ruby`, …) whose server BALDART has recorded for this project. Identifiers map 1:1 to adapter files under `src/utils/lsp-adapters/`. |
-| `lsp.auto_verify` | When `true` (default), `baldart doctor` re-verifies the binaries are reachable on every run. Disable on CI if the verify step is too noisy. |
+| `lsp.auto_verify` | When `true` (default), `baldart doctor` re-verifies the binaries are reachable **on `$PATH`** (via `command -v`, mirroring how the Claude Code LSP tool spawns them) on every run. Disable on CI if the verify step is too noisy. |
 
 **Install modes per adapter:**
 
-- `typescript`, `python` — installed as npm devDeps (`npm install --save-dev typescript-language-server typescript` / `pyright`). Project-local, version-pinned.
+- `typescript`, `python` — installed globally via npm (`npm install -g typescript-language-server typescript` / `pyright`). Global on purpose: the consumer spawns the server by name from `$PATH`, so a project-local devDep under `node_modules/.bin/` would never be reachable. A binary present only in `node_modules` is reported `installed-but-unreachable`, not `verified`.
 - `go`, `rust`, `ruby` — installed via system tools (`go install …`, `rustup component add …`, `gem install …`). BALDART prints the command; the user runs it.
 
 **Fallback contract.** When the LSP layer is enabled but a server is missing or broken, agents silently fall back to Grep — code search never fails because of LSP issues. `baldart doctor` surfaces the mismatch and offers reinstall.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.33.0",
+  "version": "3.33.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -706,7 +706,26 @@ async function interactivePrompts(merged, detected) {
         }
         const verify = installer.verifyServers(installed.map(i => i.name));
         const verified = verify.filter(v => v.ok).map(v => v.name);
-        const newSet = new Set([...(merged.lsp.installed_servers || []), ...verified, ...manual.map(m => m.name)]);
+        // Every known-adapter result that isn't cleanly `verified` is STILL
+        // recorded (like system-mode pending installs): dropping it would make
+        // every re-run reinstall and `baldart doctor` would never see the
+        // mismatch. This covers `installed-but-unreachable` AND the npm-global
+        // happy-path trap where `npm install -g` exited 0 but npm's global bin
+        // dir isn't on the current `$PATH` (→ status `not-installed`, since npx
+        // can't see the global prefix either). Surface the fix in both cases.
+        const needsAttention = verify.filter(v => !v.ok && v.status !== 'unknown-adapter');
+        for (const u of needsAttention) {
+          UI.warning(`${u.name}: not reachable on $PATH (status: ${u.status}) — Claude Code's LSP tool can't spawn it.`);
+          if (u.fix) {
+            UI.code(u.fix, 'Run this, then ensure npm\'s global bin dir (`npm prefix -g` → /bin) is on $PATH; re-run `baldart doctor` to verify.');
+          }
+        }
+        const newSet = new Set([
+          ...(merged.lsp.installed_servers || []),
+          ...verified,
+          ...needsAttention.map(u => u.name),
+          ...manual.map(m => m.name)
+        ]);
         merged.lsp.installed_servers = Array.from(newSet);
         if (skipped.length) {
           UI.warning(`Skipped: ${skipped.map(s => `${s.name} (${s.reason})`).join(', ')}`);

package/src/commands/doctor.js

@@ -534,14 +534,23 @@ function planActions(state) {
     actions.push({
       key: 'lsp-fix',
       label: `Reinstall ${state.lspBroken.length} broken LSP server(s)`,
-      why: `LSP layer is enabled but these language servers are not reachable: ${state.lspBroken.join(', ')}. Symbol search will silently fall back to Grep until they are reinstalled.`,
-      autoOk: false, // touches dev-deps and is the kind of action a user may
-      // have made deliberate (switching from npm pyright to system pyright);
+      why: `LSP layer is enabled but these language servers are not reachable on $PATH: ${state.lspBroken.join(', ')}. The Claude Code LSP tool spawns each server by name from $PATH, so a binary that is missing OR only present in node_modules/.bin (a legacy devDep install) makes symbol search silently fall back to Grep. Reinstalling runs the global install so the binary lands on $PATH.`,
+      autoOk: false, // runs `npm install -g` and is the kind of action a user
+      // may have made deliberate (switching from npm pyright to system pyright);
       // keep the outer prompt + the per-server confirm both alive.
       run: async () => {
         const installer = new LspInstaller(state.cwd);
         const { installed, manual, skipped } = await installer.installServers(state.lspBroken);
-        if (installed.length) UI.success(`Reinstalled: ${installed.map(i => i.name).join(', ')}`);
+        if (installed.length) {
+          UI.success(`Reinstalled: ${installed.map(i => i.name).join(', ')}`);
+          // If a reinstall keeps coming back broken, npm's global bin dir is
+          // likely not on $PATH — surface the escape so the user doesn't loop.
+          const recheck = installer.verifyServers(installed.map(i => i.name));
+          if (recheck.some(r => !r.ok)) {
+            UI.warning('Some servers are still unreachable after reinstall.');
+            UI.info('Check that npm\'s global bin dir is on $PATH: `npm prefix -g` → add its `/bin` to PATH.');
+          }
+        }
         for (const m of manual) {
           UI.warning(`System-level reinstall required for ${m.label}:`);
           console.log(`    ${m.command}`);

package/src/utils/lsp-adapters/python.js

@@ -4,10 +4,12 @@ const path = require('path');
 /**
  * Python LSP adapter — Pyright.
  *
- * Pyright ships as both an npm package and a pip package. We default to the
- * npm devDep route so installs stay project-local and version-pinned without
- * touching the user's Python env. Users who already drive Python via pip/uv
- * can override by removing pyright from devDeps and installing system-wide.
+ * Pyright ships as both an npm package and a pip package. We default to a
+ * global npm install so the `pyright` binary lands on `$PATH` — the consumer
+ * (Claude Code's LSP tool) spawns it by name from `$PATH`, so a project-local
+ * devDep under `node_modules/.bin/` (the pre-v3.33.1 behaviour) was never
+ * reachable and the layer silently fell back to Grep. Users who already drive
+ * Python via pip/uv can override with an overlay and a system-managed pyright.
  *
  * Detection signal: pyproject.toml, setup.py, setup.cfg, requirements.txt,
  * Pipfile, or a top-level .py source tree.
@@ -18,11 +20,13 @@ class PythonAdapter {
   get name() { return 'python'; }
   get label() { return 'Python (Pyright)'; }
   get binary() { return 'pyright'; }
-  get installMode() { return 'npm-dev'; }
+  get installMode() { return 'npm-global'; }
   get npmPackage() { return 'pyright'; }
 
-  installCommand() { return 'npm install --save-dev pyright'; }
-  verifyCommand() { return 'npx --no-install pyright --version'; }
+  installCommand() { return 'npm install -g pyright'; }
+  // Functional probe; reachability on $PATH is checked by the installer via
+  // `command -v` (mirrors how the consumer spawns the binary).
+  verifyCommand() { return 'pyright --version'; }
   claudePluginId() { return 'pyright-lsp@claude-plugins-official'; }
 
   static detect(cwd = process.cwd()) {

package/src/utils/lsp-adapters/typescript.js

@@ -5,8 +5,13 @@ const path = require('path');
  * TypeScript / JavaScript LSP adapter.
  *
  * Language server: `typescript-language-server` (Node, npm).
- * Install mode: project-local devDep — keeps the binary inside the consumer
- * repo's node_modules and avoids polluting the user's global env.
+ * Install mode: global npm install — the binary MUST land on `$PATH` because
+ * the consumer (Claude Code's LSP tool) spawns it by name from `$PATH`, not
+ * via `npx`/node_modules resolution. A project-local devDep (the pre-v3.33.1
+ * behaviour) installed into `node_modules/.bin/` which is NOT on `$PATH`, so
+ * every LSP spawn failed with `Executable not found in $PATH` while the
+ * `npx --no-install` verify falsely reported success — a dead layer masked by
+ * the silent Grep fallback.
  *
  * Detection signal: presence of `tsconfig.json`, `jsconfig.json`, or a
  * `package.json` referencing typescript in deps/devDeps.
@@ -18,19 +23,29 @@ class TypeScriptAdapter {
   get label() { return 'TypeScript / JavaScript'; }
   get binary() { return 'typescript-language-server'; }
 
-  /** 'npm-dev' = npm devDependency, 'system' = printed install instructions. */
-  get installMode() { return 'npm-dev'; }
+  /**
+   * 'npm-global' = installed globally via npm so it lands on `$PATH`.
+   * 'system'     = printed install instructions (non-npm toolchains).
+   * Treated identically to system mode by the installer except that npm-global
+   * adapters are safe to auto-execute (no sudo, no toolchain assumptions).
+   */
+  get installMode() { return 'npm-global'; }
 
-  /** npm package to install when mode='npm-dev'. */
+  /** npm package(s) to install when mode='npm-global'. */
   get npmPackage() { return 'typescript-language-server typescript'; }
 
   /** Shell command the user (or installer) should run. */
   installCommand() {
-    return 'npm install --save-dev typescript-language-server typescript';
+    return 'npm install -g typescript-language-server typescript';
   }
 
-  /** Verify the binary is reachable (no execution side effects). */
-  verifyCommand() { return 'npx --no-install typescript-language-server --version'; }
+  /**
+   * Functional probe: invokes the binary the SAME way the consumer spawns it —
+   * by name from `$PATH`. Reachability on `$PATH` is the actual contract the
+   * consumer depends on; `LspInstaller.verifyServers()` checks it explicitly
+   * via `command -v` and only runs this probe once the binary resolves.
+   */
+  verifyCommand() { return 'typescript-language-server --version'; }
 
   /**
    * Claude Code code-intelligence plugin id, if any. Null = no companion plugin.

package/src/utils/lsp-installer.js

@@ -63,7 +63,7 @@ class LspInstaller {
   /**
    * Build a recommendation list from detected languages. Each entry carries
    * the install command and the install mode so the UI can decide whether
-   * to run it automatically (npm-dev) or just print it (system).
+   * to run it automatically (npm-global) or just print it (system).
    */
   recommend(langs = this.detectLanguages()) {
     return langs.map(name => {
@@ -82,7 +82,8 @@ class LspInstaller {
 
   /**
    * Install one or more language servers. Returns `{ installed, skipped, manual }`.
-   *  - npm-dev adapters: executed in-process (npm install --save-dev …).
+   *  - npm-global adapters: executed in-process (npm install -g …) so the
+   *    binary lands on `$PATH` where the consumer can spawn it.
    *  - system adapters: never executed automatically; surfaced under `manual`
    *    so the caller can print the command for the user to run.
    *
@@ -335,25 +336,96 @@ class LspInstaller {
   }
 
   /**
-   * Verify each named server's binary is reachable. Returns
-   * `[{ name, ok, output | error }]`. Never throws.
+   * Is `binary` resolvable on `$PATH`? This mirrors EXACTLY how the consumer
+   * (Claude Code's LSP tool) spawns the language server — by name, from
+   * `$PATH`. Using `npx --no-install` here instead would resolve from
+   * `node_modules/.bin/` and produce a false positive: the verify passes while
+   * every real LSP spawn fails with `Executable not found in $PATH`. That
+   * resolution mismatch was the root cause of the pre-v3.33.1 dead-layer bug.
+   */
+  _isOnPath(binary) {
+    try {
+      execSync(`command -v ${binary}`, {
+        cwd: this.cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 5000,
+        shell: '/bin/sh'
+      });
+      return true;
+    } catch { return false; }
+  }
+
+  /**
+   * For npm-managed adapters: is the binary installed project-locally (in
+   * `node_modules/.bin/`) even though it isn't on `$PATH`? This is the precise
+   * fingerprint of the legacy `npm install --save-dev` install — present, but
+   * unreachable by the consumer. System adapters have no local notion → false.
+   */
+  _isInstalledLocally(adapter) {
+    if (adapter.installMode === 'system') return false;
+    try {
+      execSync(`npx --no-install ${adapter.binary} --version`, {
+        cwd: this.cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 8000
+      });
+      return true;
+    } catch { return false; }
+  }
+
+  /**
+   * Verify each named server is reachable the way the consumer spawns it.
+   * Returns `[{ name, ok, status, output? , error?, fix? }]`. Never throws.
+   *
+   * `status` is one of:
+   *   - `verified`                — on `$PATH` AND the functional probe passed.
+   *   - `installed-but-unreachable` — installed locally (node_modules) but not
+   *     on `$PATH`; the consumer cannot spawn it. `fix` carries the command
+   *     that puts it on `$PATH`. Treated as broken (`ok:false`) — same honesty
+   *     bar already applied to system adapters whose binary isn't installed.
+   *   - `unreachable`             — on `$PATH` but the probe errored (corrupt
+   *     install / wrong flag). Rare.
+   *   - `not-installed`           — neither on `$PATH` nor locally installed.
+   *   - `unknown-adapter`         — name not in the registry.
    */
   verifyServers(serverNames) {
     return serverNames.map(name => {
       let a;
       try { a = getAdapter(name, this.cwd); }
-      catch (err) { return { name, ok: false, error: err.message }; }
+      catch (err) { return { name, ok: false, status: 'unknown-adapter', error: err.message }; }
 
-      try {
-        const out = execSync(a.verifyCommand(), {
-          cwd: this.cwd,
-          stdio: ['ignore', 'pipe', 'pipe'],
-          timeout: 8000
-        }).toString().trim();
-        return { name, ok: true, output: out };
-      } catch (err) {
-        return { name, ok: false, error: (err.message || '').split('\n')[0] };
+      if (this._isOnPath(a.binary)) {
+        try {
+          const out = execSync(a.verifyCommand(), {
+            cwd: this.cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 8000
+          }).toString().trim();
+          return { name, ok: true, status: 'verified', output: out };
+        } catch (err) {
+          return {
+            name, ok: false, status: 'unreachable',
+            error: (err.message || '').split('\n')[0],
+            fix: a.installCommand()
+          };
+        }
+      }
+
+      // Not on $PATH. Distinguish "installed locally but unreachable" (the
+      // documented false-positive scenario) from "not installed at all".
+      if (this._isInstalledLocally(a)) {
+        return {
+          name, ok: false, status: 'installed-but-unreachable',
+          error: `${a.binary} is installed locally but not on $PATH; the Claude Code LSP tool spawns it by name from $PATH`,
+          fix: a.installCommand()
+        };
       }
+
+      return {
+        name, ok: false, status: 'not-installed',
+        error: `${a.binary} not found on $PATH`,
+        fix: a.installCommand()
+      };
     });
   }
 }