baldart 3.33.0 → 3.34.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.34.0] - 2026-05-30
+
+Adds an **assert-active git-hooks health check** to `baldart doctor` and the `worktree-manager` verify step. A consumer had `core.hooksPath` pointing at `.git/hooks` (empty) while the repo's versioned hooks lived in `scripts/git-hooks/` — the pre-commit schema guard and pre-push were **silently inactive for days**. The existing worktree-manager verify (`git config core.hooksPath || true`) only *read* the value without asserting anything, so it never caught the drift. Same class as the LSP bug: the framework "verifies" by reading a proxy instead of asserting the real state. This moves it from read-only to assert-active. **WARN-only** — the check never mutates `core.hooksPath` (a wrong heuristic + auto-fix would be worse than the original bug); it surfaces the exact remediation command and lets the user apply it. **No new `baldart.config.yml` keys** — it's a universal, always-on, filesystem-autodetected check, so the schema-propagation rule does not apply.
+
+### Added — git-hooks health check (assert-active)
+
+- **[src/utils/githooks.js](src/utils/githooks.js)**: new, self-contained, fail-safe utility (distinct from `src/utils/hooks.js`, which manages `.claude/settings.json` hooks). `getStatus(cwd)` detects the repo's versioned-hooks directory (`.husky`, `.githooks`, `scripts/git-hooks`, `githooks` — first that exists and contains a standard-named hook), resolves the **active** hooks dir explicitly (`core.hooksPath` → relative resolved against `git rev-parse --show-toplevel`, absolute verbatim; unset → `<git-dir>/hooks`, handling the worktree `.git`-is-a-file case), and asserts the active dir serves the versioned hooks. **`git rev-parse --git-path hooks` is deliberately NOT used** — empirically it returns the configured value relative/unresolved and historically some git versions ignored `core.hooksPath` for it. Returns `checked:false` (silent, `ok:true`) when no managed hooks exist or on any error, so the check never produces a false WARN.
+- **[src/utils/githooks.js](src/utils/githooks.js)**: pure exported `isActiveServing(activeAbs, expectedAbs)` — identical-or-nested decision (covers husky v9, which sets `core.hooksPath=.husky/_` with user hooks in `.husky/`). Paths are canonicalized (symlink-resolved, handling non-existent leaves) before comparison so a symlinked ancestor (macOS `/var`→`/private/var`, symlinked repo/home) never yields a false INACTIVE. Executability (`-x`) is asserted only for raw dirs git execs directly; husky user hooks (not required `+x` in v9) skip the assert.
+- **[src/commands/doctor.js](src/commands/doctor.js)**: probe wired into `detectState` (`state.gitHooks`), a `Git hooks` line in `renderDiagnostic` (silent when `checked:false`), and an **advisory print-only** action in `planActions` (`githooks-health`) whose `run()` prints the WARN + fix command and **never mutates** `core.hooksPath` (safe under `--auto`).
+- **[framework/.claude/skills/worktree-manager/SKILL.md](framework/.claude/skills/worktree-manager/SKILL.md)**: step 4 (isolation setup) replaces the silent `git config core.hooksPath || true` read with a lean **assert** — detects the versioned-hooks dir, resolves the active dir, and echoes a loud `⚠️ WARNING` + the `git config core.hooksPath <dir>` fix on mismatch (matches husky v9 `.husky/_` and `<dir>/*` as active). The worktree shares `core.hooksPath` via `.git/commondir`, so the same resolution applies.
+
+### Tests
+
+- **[src/utils/__tests__/githooks-active.test.js](src/utils/__tests__/githooks-active.test.js)**: new — 8 pure fixtures for `isActiveServing` (the mayo bug, husky v9 nesting, identical dirs, prefix-not-a-boundary, trailing-sep normalization).
+- **[scripts/test-githooks.sh](scripts/test-githooks.sh)**: new — drives **real** git repos: misconfig (`hooksPath=.git/hooks`, hooks in `scripts/git-hooks`) → inactive + fix; correctly wired → ok; non-executable raw hook → ok=false + chmod fix; husky v9 → active, `-x` assert skipped; no managed hooks → `checked:false` (silent).
+
+## [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/README.md

@@ -239,7 +239,7 @@ The `ui-expert` agent is upgraded from a generic baseline to a world-class UI/UX
 
 ### LSP Symbol Search Layer (new in v3.10.0)
 
-When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (npm devDeps for TypeScript/Python, system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).
+When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (global npm install for TypeScript/Python — the binary must be on `$PATH` because Claude Code's LSP tool spawns it by name; system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).
 
 ### Commands
 

package/VERSION

@@ -1 +1 @@
-3.33.0
+3.34.0

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/.claude/skills/worktree-manager/SKILL.md

@@ -411,8 +411,32 @@ else
   echo "PORT=$PORT" >> .env.local
 fi
 
-# 5. Verify husky hooks work (they share via .git/commondir)
-git config core.hooksPath || true
+# 5. ASSERT git hooks are ACTIVE — not just readable.
+#    The worktree shares core.hooksPath via .git/commondir, so the same
+#    resolution applies here as in the main checkout. Reading the value
+#    (the old `git config core.hooksPath || true`) is NOT enough: it never
+#    catches the failure mode where core.hooksPath points at an empty dir
+#    while the repo's versioned hooks live elsewhere (pre-commit / pre-push
+#    silently inactive). Detect the versioned-hooks dir and assert it is served.
+HOOK_SRC=""
+for d in .husky .githooks scripts/git-hooks githooks; do
+  if [ -d "$d" ] && ls "$d" 2>/dev/null | grep -qE '^(pre-commit|pre-push|commit-msg)$'; then
+    HOOK_SRC="$d"; break
+  fi
+done
+if [ -n "$HOOK_SRC" ]; then
+  ACTIVE="$(git config --get core.hooksPath || echo .git/hooks)"
+  # Lean literal-string match (HOOK_SRC is relative). Full path resolution +
+  # canonicalization lives in `baldart doctor` (src/utils/githooks.js); an
+  # absolute core.hooksPath here would warn spuriously — rare, run doctor to confirm.
+  case "$ACTIVE" in
+    "$HOOK_SRC"|"$HOOK_SRC"/*|.husky/_) : ;;  # active dir serves the versioned hooks (incl. husky v9 .husky/_)
+    *)
+      echo "⚠️  WARNING: git hooks INATTIVI — gli hook versionati sono in '$HOOK_SRC' ma core.hooksPath = '$ACTIVE'." >&2
+      echo "    Esegui per riattivarli:  git config core.hooksPath $HOOK_SRC" >&2
+      ;;
+  esac
+fi
 ```
 
 ### 5. Verify baseline

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.34.0",
   "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

@@ -30,6 +30,7 @@ const GitUtils = require('../utils/git');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
+const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
@@ -234,6 +235,16 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) {}
 
+    // ---- Git-hooks health (since v3.34.0) ------------------------------
+    // Assert that the repo's versioned git hooks (pre-commit/pre-push/…) are
+    // actually being run — i.e. `core.hooksPath` resolves to the directory
+    // that holds them. A drift here (e.g. core.hooksPath=.git/hooks while the
+    // hooks live in scripts/git-hooks/) silently disables every hook. Distinct
+    // from the BALDART `.claude/settings.json` hooks probed above. Fully
+    // fail-safe: `checked:false` when no managed hooks exist or on any error.
+    state.gitHooks = { checked: false, ok: true };
+    try { state.gitHooks = GitHooks.getStatus(cwd); } catch (_) {}
+
     // ---- Agent symlink integrity (since v3.20.0) -----------------------
     // Source of truth for the BALDART agent list is the framework filesystem
     // directory itself (`.framework/framework/.claude/agents/*.md`). For each
@@ -503,6 +514,28 @@ function planActions(state) {
     });
   }
 
+  // Git-hooks health (since v3.34.0). ADVISORY ONLY — the action's run() never
+  // mutates `core.hooksPath` (a wrong heuristic + auto-fix is worse than the
+  // original silent-inactive bug). It surfaces the WARN + the exact remediation
+  // command so the user applies it deliberately. Present as an action (rather
+  // than a bare table WARN) so `doctor` doesn't contradict it with "Nothing to
+  // do". Safe to run in --auto since it only prints.
+  if (state.gitHooks && state.gitHooks.checked && !state.gitHooks.ok) {
+    actions.push({
+      key: 'githooks-health',
+      label: state.gitHooks.inactive
+        ? `Git hooks INACTIVE — ${state.gitHooks.source} hooks in ${state.gitHooks.expectedDir} are not being run`
+        : `Git hooks not executable — ${state.gitHooks.nonExecutable.join(', ')}`,
+      why: `${state.gitHooks.detail}. Fix: ${state.gitHooks.fixCommand}`,
+      autoOk: true, // advisory print-only; run() does NOT mutate config
+      run: () => {
+        UI.warning(state.gitHooks.detail);
+        UI.info('Run to re-activate the repo\'s versioned git hooks:');
+        console.log(`    ${state.gitHooks.fixCommand}`);
+      },
+    });
+  }
+
   // Agent symlink integrity (since v3.20.0). Re-runs the agent merge loop to
   // recreate any missing per-agent symlink. Calls `SymlinkUtils.mergeAgents`
   // directly rather than dispatching to `update` — we want only the symlink
@@ -534,14 +567,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}`);
@@ -778,6 +820,29 @@ function renderDiagnostic(state) {
       console.log(`   • pre-v3.18: ${state.hooksLegacy.join(', ')}`);
   }
 
+  // Git-hooks health (v3.34.0+). Silent when no versioned-hooks dir exists
+  // (`checked:false`) — most consumers have no managed git hooks and must see
+  // zero noise here.
+  if (state.gitHooks && state.gitHooks.checked) {
+    if (state.gitHooks.ok) {
+      console.log(statusLine(
+        'Git hooks',
+        `${state.gitHooks.source} active (${state.gitHooks.expectedHooks.join(', ')})`,
+        'ok'
+      ));
+    } else if (state.gitHooks.inactive) {
+      console.log(statusLine(
+        'Git hooks',
+        `INACTIVE — ${state.gitHooks.source} hooks in ${state.gitHooks.expectedDir} not run by core.hooksPath`,
+        'warn'
+      ));
+      console.log(`   • fix: ${state.gitHooks.fixCommand}`);
+    } else {
+      console.log(statusLine('Git hooks', state.gitHooks.detail, 'warn'));
+      console.log(`   • fix: ${state.gitHooks.fixCommand}`);
+    }
+  }
+
   if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
     console.log(statusLine(
       '.gitignore',

package/src/utils/__tests__/githooks-active.test.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Fixture-driven test for the git-hooks active-vs-expected decision.
+ *
+ * Run: node src/utils/__tests__/githooks-active.test.js
+ * Exits 0 on success, 1 on any mismatch (CI-friendly).
+ *
+ * `isActiveServing` is the one decision that, if wrong, silently invalidates
+ * the entire git-hooks health check (src/utils/githooks.js). It is pure (path
+ * logic only) so it is fully unit-testable without a live repo — covering the
+ * husky-version branches that fs/git probing can't easily exercise.
+ */
+const path = require('path');
+const { isActiveServing } = require('../githooks');
+
+// Absolute roots so the fixtures don't depend on cwd. Normalize through
+// path.resolve the same way the implementation does.
+const ROOT = path.resolve('/repo');
+const j = (...p) => path.join(ROOT, ...p);
+
+const FIXTURES = [
+  // ─── the mayo bug: core.hooksPath=.git/hooks, hooks in scripts/git-hooks ──
+  { active: j('.git', 'hooks'), expected: j('scripts', 'git-hooks'), want: false, note: 'mayo: inactive' },
+
+  // ─── husky v9: active=.husky/_ wrappers, user hooks in .husky ─────────────
+  { active: j('.husky', '_'),   expected: j('.husky'),               want: true,  note: 'husky v9 nested' },
+  // ─── husky v5-v8: core.hooksPath=.husky, hooks in .husky ──────────────────
+  { active: j('.husky'),        expected: j('.husky'),               want: true,  note: 'husky v8 identical' },
+
+  // ─── scripts convention, correctly wired ─────────────────────────────────
+  { active: j('scripts', 'git-hooks'), expected: j('scripts', 'git-hooks'), want: true, note: 'scripts identical' },
+
+  // ─── .githooks convention, wired to default .git/hooks (inactive) ─────────
+  { active: j('.git', 'hooks'), expected: j('.githooks'),            want: false, note: '.githooks inactive' },
+
+  // ─── reverse nesting (expected within active) also counts as serving ──────
+  { active: j('.husky'),        expected: j('.husky', '_'),          want: true,  note: 'reverse nesting' },
+
+  // ─── sibling dirs sharing a prefix must NOT match (prefix-not-boundary) ───
+  { active: j('hooks'),         expected: j('hooks-extra'),          want: false, note: 'prefix not a path boundary' },
+
+  // ─── trailing-slash / non-normalized inputs normalize equal ──────────────
+  { active: j('.husky') + path.sep, expected: j('.husky'),           want: true,  note: 'trailing sep normalized' },
+];
+
+let failures = 0;
+for (const f of FIXTURES) {
+  const got = isActiveServing(f.active, f.expected);
+  const ok = got === f.want;
+  if (!ok) {
+    failures++;
+    console.error(`✗ ${f.note}: isActiveServing(${f.active}, ${f.expected}) = ${got}, expected ${f.want}`);
+  } else {
+    console.log(`✓ ${f.note}`);
+  }
+}
+
+if (failures) {
+  console.error(`\n${failures} failure(s).`);
+  process.exit(1);
+}
+console.log(`\nAll ${FIXTURES.length} fixtures passed.`);
+process.exit(0);

package/src/utils/githooks.js

@@ -0,0 +1,233 @@
+/**
+ * Git-hooks health check — **assert-active**, not read-only.
+ *
+ * NOT to be confused with `src/utils/hooks.js`: that module manages the Claude
+ * Code hooks registered in `.claude/settings.json`. THIS module inspects the
+ * repo's own *git* hooks (pre-commit, pre-push, …) and asserts they are
+ * actually being executed by git — i.e. that `core.hooksPath` resolves to the
+ * directory where the repo's versioned hooks live.
+ *
+ * **Why it exists** (since v3.34.0)
+ *
+ * A consumer had `core.hooksPath` pointing at `.git/hooks` (empty) while the
+ * repo's real, versioned hooks lived in `scripts/git-hooks/`. Result: the
+ * pre-commit schema guard and pre-push were silently inactive for days, and
+ * the worktree-manager verify step (`git config core.hooksPath || true`) only
+ * *read* the value without asserting anything — so it never caught the drift.
+ * Same class as the LSP bug: the framework "verifies" by reading a proxy
+ * instead of asserting the real state. This moves it from read-only to
+ * assert-active.
+ *
+ * **Resolution of the active hooks dir** (the crux)
+ *
+ * `git rev-parse --git-path hooks` is NOT used: empirically it returns the
+ * configured value *relative and unresolved*, and historically some git
+ * versions ignored `core.hooksPath` for `--git-path` entirely. Instead we
+ * resolve explicitly:
+ *   - `core.hooksPath` set      → relative resolves against the working-tree
+ *                                 top (`git rev-parse --show-toplevel`),
+ *                                 absolute is used verbatim.
+ *   - `core.hooksPath` unset    → `<git rev-parse --git-dir>/hooks` (handles
+ *                                 the worktree case where `.git` is a file).
+ *
+ * **Design invariants**
+ *
+ *   - Fail-safe: every probe is wrapped; any internal error yields
+ *     `{ checked: false, ok: true }` so the check NEVER blocks legitimate work
+ *     and never produces a false WARN.
+ *   - Silent when nothing to assert: a repo with no versioned-hooks directory
+ *     returns `checked: false` (most consumers have no managed hooks).
+ *   - No config flag: this is a universal, always-on health check auto-detected
+ *     from the filesystem, so the schema-change-propagation rule does not apply.
+ *   - WARN only: this module never mutates `core.hooksPath`. It reports a
+ *     `fixCommand` string; applying it is the caller's (user's) decision.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Standard git hook filenames. A managed-hooks directory is recognized by
+// containing at least one of these (husky places them at `.husky/<name>`,
+// raw dirs at `<dir>/<name>`).
+const STANDARD_HOOKS = [
+  'pre-commit', 'pre-push', 'commit-msg', 'prepare-commit-msg',
+  'pre-rebase', 'pre-merge-commit', 'post-checkout', 'post-commit',
+  'post-merge', 'post-rewrite', 'pre-applypatch', 'applypatch-msg',
+];
+
+// Candidate versioned-hooks directories, in priority order. The first that
+// exists AND contains a standard-named hook wins. `scripts/git-hooks` and
+// `githooks` are conventions (not universal) — we enumerate a small known set
+// rather than guess.
+const MANAGED_DIRS = [
+  { dir: '.husky',            source: 'husky' },
+  { dir: '.githooks',         source: 'githooks' },
+  { dir: 'scripts/git-hooks', source: 'scripts' },
+  { dir: 'githooks',          source: 'githooks' },
+];
+
+function git(cwd, args) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+/**
+ * Find the repo's versioned-hooks directory, or null when none is managed.
+ * @returns {{ dir: string, abs: string, source: string, hooks: string[] } | null}
+ */
+function detectExpected(cwd) {
+  for (const cand of MANAGED_DIRS) {
+    const abs = path.join(cwd, cand.dir);
+    let names = [];
+    try {
+      if (!fs.statSync(abs).isDirectory()) continue;
+      names = fs.readdirSync(abs).filter((f) => STANDARD_HOOKS.includes(f));
+    } catch (_) { continue; }
+    if (names.length) return { dir: cand.dir, abs, source: cand.source, hooks: names };
+  }
+  return null;
+}
+
+/**
+ * Resolve the directory git will actually look in for hooks.
+ * @returns {{ configured: string | null, abs: string }}
+ */
+function resolveActiveDir(cwd) {
+  let configured = null;
+  try { configured = git(cwd, ['config', '--get', 'core.hooksPath']) || null; } catch (_) {}
+
+  if (configured) {
+    if (path.isAbsolute(configured)) return { configured, abs: configured };
+    // Relative core.hooksPath resolves against the working-tree top, not cwd.
+    let top = cwd;
+    try { top = git(cwd, ['rev-parse', '--show-toplevel']); } catch (_) {}
+    return { configured, abs: path.resolve(top, configured) };
+  }
+
+  // Unset → <git-dir>/hooks. git-dir may be relative or a worktree gitdir.
+  let gitDir;
+  try { gitDir = git(cwd, ['rev-parse', '--git-dir']); } catch (_) { gitDir = path.join(cwd, '.git'); }
+  if (!path.isAbsolute(gitDir)) gitDir = path.resolve(cwd, gitDir);
+  return { configured: null, abs: path.join(gitDir, 'hooks') };
+}
+
+/**
+ * Resolve a path to its canonical (symlink-free) form so two paths computed
+ * from different bases compare correctly. The active dir (from git's
+ * realpath-resolved toplevel/git-dir) and the expected dir (from cwd) can
+ * otherwise differ purely by a symlinked ancestor — e.g. macOS `/var` →
+ * `/private/var`, or a symlinked repo/home path — yielding a false INACTIVE.
+ *
+ * Handles non-existent leaves (the active `.git/hooks` may not exist on a
+ * misconfigured repo): realpath the deepest existing ancestor, re-append the
+ * rest. Falls back to a plain resolve if nothing along the path is realpath-able.
+ */
+function canonicalize(p) {
+  let dir = path.resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync(dir);
+      return tail.length ? path.join(real, ...tail) : real;
+    } catch (_) {
+      const parent = path.dirname(dir);
+      if (parent === dir) return path.resolve(p); // reached fs root
+      tail.unshift(path.basename(dir));
+      dir = parent;
+    }
+  }
+}
+
+/**
+ * PURE decision: is the active hooks dir serving the versioned hooks?
+ *
+ * True when the two dirs are identical OR one is nested within the other.
+ * The nesting case covers husky v9, which sets `core.hooksPath=.husky/_`
+ * (wrappers) while the user hooks live in `.husky/`. Exported for unit tests —
+ * this is the one decision that, if wrong, silently invalidates the whole check.
+ */
+function isActiveServing(activeAbs, expectedAbs) {
+  const a = path.resolve(activeAbs);
+  const e = path.resolve(expectedAbs);
+  if (a === e) return true;
+  return a.startsWith(e + path.sep) || e.startsWith(a + path.sep);
+}
+
+/**
+ * Inspect the repo's git-hooks health. Fail-safe.
+ * @returns {{
+ *   checked: boolean, ok: boolean, source: string|null, configured: string|null,
+ *   activeDir: string|null, expectedDir: string|null, expectedHooks: string[],
+ *   inactive: boolean, nonExecutable: string[], detail: string, fixCommand: string|null
+ * }}
+ */
+function getStatus(cwd = process.cwd()) {
+  const result = {
+    checked: false,
+    ok: true,
+    source: null,
+    configured: null,
+    activeDir: null,
+    expectedDir: null,
+    expectedHooks: [],
+    inactive: false,
+    nonExecutable: [],
+    detail: '',
+    fixCommand: null,
+  };
+
+  try {
+    const expected = detectExpected(cwd);
+    if (!expected) return result; // no managed hooks → silent, ok
+
+    const active = resolveActiveDir(cwd);
+    result.checked = true;
+    result.source = expected.source;
+    result.configured = active.configured;
+    result.activeDir = active.abs;
+    result.expectedDir = expected.dir;
+    result.expectedHooks = expected.hooks;
+
+    // Canonicalize both ends before comparing — they're computed from different
+    // bases (git realpath vs cwd) and a symlinked ancestor would otherwise
+    // produce a false INACTIVE.
+    if (!isActiveServing(canonicalize(active.abs), canonicalize(expected.abs))) {
+      result.inactive = true;
+      result.ok = false;
+      result.fixCommand = `git config core.hooksPath ${expected.dir}`;
+      result.detail = `core.hooksPath risolve a ${active.abs} ma gli hook versionati sono in ${expected.dir}`;
+      return result;
+    }
+
+    // Executability assert — only for raw dirs git execs directly. Husky sources
+    // user hooks via its `_` wrappers and v9 does NOT require them to be +x, so
+    // asserting -x there would manufacture false positives.
+    if (expected.source !== 'husky') {
+      for (const h of expected.hooks) {
+        try { fs.accessSync(path.join(expected.abs, h), fs.constants.X_OK); }
+        catch (_) { result.nonExecutable.push(h); }
+      }
+      if (result.nonExecutable.length) {
+        result.ok = false;
+        result.detail = `hook non eseguibili (manca il bit -x): ${result.nonExecutable.join(', ')}`;
+        result.fixCommand = `chmod +x ${result.nonExecutable.map((h) => path.join(expected.dir, h)).join(' ')}`;
+      }
+    }
+
+    return result;
+  } catch (_) {
+    // Never block doctor / worktree verify on a probe failure.
+    return { ...result, checked: false, ok: true };
+  }
+}
+
+module.exports = { getStatus, isActiveServing };
+// Exposed for completeness / advanced callers and unit tests.
+module.exports.detectExpected = detectExpected;
+module.exports.resolveActiveDir = resolveActiveDir;
+module.exports.STANDARD_HOOKS = STANDARD_HOOKS;
+module.exports.MANAGED_DIRS = MANAGED_DIRS;

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()
+      };
     });
   }
 }