baldart 3.32.0 → 3.33.1

package/CHANGELOG.md

@@ -5,6 +5,60 @@ 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.
+
+### Fixed — `add` is now atomic + never declares a half-install successful
+
+- **[src/commands/add.js](src/commands/add.js)**: `Hooks.registerAll` is **reordered ahead of** the optional git-aliases and configure prompts. Hook registration determines install correctness and must never sit behind a blocking prompt — if `add` is interrupted at an optional prompt, the hooks are already in place. The drift callback now passes `{ autoYes: nonInteractive }` (parity with `update.js`), so a drifted hook in non-TTY no longer throws.
+- **[src/utils/hooks.js](src/utils/hooks.js)**: new exported `verifyAll(cwd)` — a pure read over `getStatus` returning `{ ok, malformed, missing, path }`. It iterates only the **active** `HOOK_REGISTRY` (commented-out entries like `capture-detect` excluded for free). A malformed `settings.json` counts as a failure (registration was skipped).
+- **[src/commands/add.js](src/commands/add.js)**: **post-flight assert** before the success summary — re-reads `settings.json`, attempts a single best-effort re-registration if anything is missing, then exits non-zero ("Install is NOT complete") if a hook is still absent. Covers `update --reset` too, since that path delegates to `add(undefined, { yes: true })`.
+
+### Added — `add --yes` (non-interactive install for CI / agents)
+
+- **[bin/baldart.js](bin/baldart.js)**: registers `-y, --yes` on the `add` subcommand (the underlying `add(repo, options)` already honored `options.yes`, it was just unreachable from the CLI). With `--yes`, `add` auto-confirms optional prompts and passes `{ nonInteractive: true }` to `configure` so its wizard writes autodetected values without blocking.
+- **[src/commands/add.js](src/commands/add.js)**: `add --yes` on a repo that **already has** `.framework/` now fails fast with a clear pointer to `npx baldart update --reset --yes --i-know` instead of hitting the deliberately-interactive destructive "Remove and reinstall?" prompt (which would throw under non-TTY and surface as a generic failure). Clean installs only; reinstall goes through `--reset`.
+
+### Added — divergence classifier flags overlay-covered edits (`--reset` is safe)
+
+- **[src/utils/git.js](src/utils/git.js)**: `classifyDivergence` now tags each `custom-overlay-able` commit with `overlayCovered` — true when **every** framework file it touches already has a matching overlay in `.baldart/overlays/`. New pure static `overlayRelForFrameworkFile(path)` mirrors the `overlay.js` path conventions (unit-tested).
+- **[src/commands/update.js](src/commands/update.js)**: in the overlay-able divergence branch, when all commits are `overlayCovered` the UI/JSON now recommend `--reset --yes --i-know` as the **safe** resolution (intent already preserved in the overlays) and note that `scaffold-overlays` would create redundant skeletons. New `overlay_already_covered` field in the `--json` output.
+
+### Added — deterministic `overlay drift` via base-sha backfill
+
+- **[src/utils/overlay-merger.js](src/utils/overlay-merger.js)**: new `ensureBaseFileShaInOverlay(overlayPath, baseSha)` — **additive-only, idempotent, fail-safe**: stamps `base_file_sha` into an overlay's frontmatter when absent (never overwrites, never fabricates frontmatter). Called from the merger in **[src/utils/symlinks.js](src/utils/symlinks.js)** `_generateOverlayedFile` at `add`/`update` time, so `baldart overlay drift` becomes deterministic for **every** overlay — not just freshly-scaffolded ones (hand-written / pre-v3.19.0 overlays were "unknown" to drift).
+
+### Tests
+
+- **[scripts/test-add-postflight.sh](scripts/test-add-postflight.sh)**: new — encodes the post-flight **invariant** (a `settings.json` missing an active hook → `verifyAll().ok === false`; the dropped hook in the test is literally `baldart-overlay-telemetry`, the mayo failure). Fails on pre-v3.33.0 code (no `verifyAll`).
+- **[scripts/test-overlay-backfill.sh](scripts/test-overlay-backfill.sh)**: new — backfill is additive, idempotent, never overwrites an existing sha, never fabricates frontmatter, fail-safe.
+- **[src/utils/__tests__/classify-divergence.test.js](src/utils/__tests__/classify-divergence.test.js)**: extended with overlay-path-mapping fixtures (38 assertions, all green).
+
+### Changed — `/baldart-update` skill
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: post-flight report (step 4) documents the new CLI hook assert in `add`/`--reset`; `last_verified` v3.32.0 → v3.33.0 (`hook_registry_entries`/`update_js_prompts` unchanged).
+
 ## [3.32.0] - 2026-05-30
 
 Makes the CLI **agent-native at the output layer**: `npx baldart version --json` and `npx baldart update --json --yes` now emit a single **machine-readable JSON object** on stdout (schemas `baldart.version/1` / `baldart.update/1`), with every human line routed to stderr. This closes the last fragile seam in the autonomous-update path — the `/baldart-update` skill previously had to **regex-scrape human-readable prose** (the v3.26.0 wording change had already forced a dual-format tolerant parser in Step 0). An agent now reads a field instead of matching a sentence. Borrowed from the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) philosophy (`--json` on every command) — but BALDART is already a headless CLI, so this is a thin, hand-rolled output layer, not a generated wrapper. **No new `baldart.config.yml` keys** — `--json` is a CLI flag, not a config key, so the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.32.0
+3.33.1

package/bin/baldart.js

@@ -65,6 +65,7 @@ program
   .command('add [repo]')
   .description('Install the framework in your project')
   .option('-b, --branch <branch>', 'Branch to use', 'main')
+  .option('-y, --yes', 'Non-interactive install (CI / agents): auto-confirm all optional prompts and skip the interactive configure wizard. Refuses to reinstall over an existing .framework/ — use `update --reset` for that.')
   .action(async (repo, options) => {
     const addCommand = require('../src/commands/add');
     await addCommand(repo || 'antbald/BALDART', options);

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -15,7 +15,7 @@ this skill needs an update is left to a human reviewer.
 update_js_prompts: 6
 hook_registry_entries: 4
 config_template_top_level_keys: features,git,identity,lsp,paths,stack,tools,version
-last_verified: v3.32.0
+last_verified: v3.33.0
 -->
 
 <!--
@@ -498,7 +498,15 @@ Report to the user, in order:
 3. **CLI self-upgrade**: if stdout mentions "Auto-relaunching via npx
    baldart@…", surface it once so the user knows the CLI bumped too.
 4. **Hooks reconciled**: any hook backfilled (parse "Auto-registered N
-   missing hook(s)" or per-line "Registered hook" from stdout).
+   missing hook(s)" or per-line "Registered hook" from stdout). Since v3.33.0
+   the CLI also runs a **post-flight hook assert** at the end of `add` (and
+   therefore of `update --reset`, which delegates to `add`): it re-reads
+   `.claude/settings.json` and refuses to declare success — exiting non-zero
+   with "Install is NOT complete" — if any active `HOOK_REGISTRY` entry is
+   missing. So a clean `--reset` can no longer leave a half-install that
+   reports "Valid" (the mayo 3.28→3.31 / v3.27.1 failure class). If you see
+   that error, the repo is in an inconsistent state: run `npx baldart doctor`
+   to repair, do NOT report success.
 5. **Agent layout migration (v3.27.0+)**: parse stdout for lines matching
    `agent generated (overlay applied): .claude/agents/<name>.md → ../../.baldart/generated/agents/<name>.md`.
    Pre-v3.27.0 overlay-merged agents (`coder`, `ui-expert`, `code-reviewer`,

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.32.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/add.js

@@ -44,6 +44,15 @@ async function add(repo, options) {
     const exists = await git.frameworkExists();
     if (exists) {
       UI.warning('Framework already installed!');
+      // A non-interactive `add --yes` must never block on (or auto-confirm) the
+      // destructive "Remove and reinstall?" prompt. Reinstalling is an explicit
+      // user decision routed through `update --reset` (which rm -rf's
+      // `.framework/` itself, so this branch is never reached on that path).
+      // Fail fast with a clear pointer instead of a generic catch below.
+      if (nonInteractive) {
+        UI.error('.framework/ already present — a non-interactive reinstall must go through `npx baldart update --reset --yes --i-know`.');
+        process.exit(1);
+      }
       const shouldReinstall = await UI.confirm(
         'Remove and reinstall? (You will lose customizations)',
         false
@@ -163,6 +172,35 @@ async function add(repo, options) {
     UI.newline();
     symlinks.copyCustomizableFiles();
 
+    // BALDART hooks (multi-hook registry since v3.18.0)
+    // Auto-register every hook in src/utils/hooks.js HOOK_REGISTRY into
+    // .claude/settings.json. Drift on an existing entry triggers an
+    // interactive prompt (Keep / Replace / Show diff), or 'keep' in --yes mode.
+    //
+    // This runs BEFORE the optional prompts below (git aliases, configure) —
+    // hook registration determines the correctness of the install and must
+    // never sit behind a blocking prompt. If `add` is interrupted at an
+    // optional prompt (non-TTY, Ctrl-C), the hooks are already in place.
+    // (Reordered in v3.33.0 to close the silent partial-install gap.)
+    try {
+      const res = await Hooks.registerAll(process.cwd(), {
+        onDrift: Hooks.createDriftPrompt(UI, { autoYes: nonInteractive }),
+      });
+      if (res.malformed) {
+        UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
+      } else {
+        for (const r of res.results) {
+          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\` in .claude/settings.json`);
+          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
+          else if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
+          else if (r.status === 'drift-kept') UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
+          else if (r.status === 'already') UI.info(`Hook \`${r.id}\` already registered.`);
+        }
+      }
+    } catch (err) {
+      UI.warning(`Hook registration skipped: ${err.message}`);
+    }
+
     // Configure Git aliases
     UI.section('Configuring Git Aliases');
 
@@ -201,29 +239,6 @@ async function add(repo, options) {
       }
     }
 
-    // BALDART hooks (multi-hook registry since v3.18.0)
-    // Auto-register every hook in src/utils/hooks.js HOOK_REGISTRY into
-    // .claude/settings.json. Drift on an existing entry triggers an
-    // interactive prompt (Keep / Replace / Show diff).
-    try {
-      const res = await Hooks.registerAll(process.cwd(), {
-        onDrift: Hooks.createDriftPrompt(UI),
-      });
-      if (res.malformed) {
-        UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
-      } else {
-        for (const r of res.results) {
-          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\` in .claude/settings.json`);
-          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
-          else if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
-          else if (r.status === 'drift-kept') UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
-          else if (r.status === 'already') UI.info(`Hook \`${r.id}\` already registered.`);
-        }
-      }
-    } catch (err) {
-      UI.warning(`Hook registration skipped: ${err.message}`);
-    }
-
     // Routines wizard (since v2.1.0)
     try {
       const routinesCmd = require('./routines');
@@ -245,7 +260,9 @@ async function add(repo, options) {
     if (runConfigure) {
       try {
         const configureCmd = require('./configure');
-        await configureCmd();
+        // In --yes mode, configure must write autodetected values without
+        // prompting — otherwise its inquirer prompts block in non-TTY.
+        await configureCmd(nonInteractive ? { nonInteractive: true } : undefined);
       } catch (err) {
         UI.warning(`Configure step failed: ${err.message}`);
         UI.info('Run `npx baldart configure` later to complete setup.');
@@ -254,6 +271,31 @@ async function add(repo, options) {
       UI.info('Skipped. Run `npx baldart configure` before invoking skills.');
     }
 
+    // Post-flight assert — never declare success with missing hooks.
+    // Re-reads .claude/settings.json and confirms every active hook in
+    // HOOK_REGISTRY is present. Guards against the silent partial-install
+    // class (v3.27.1 / mayo 3.28→3.31). Covers `update --reset` too, since
+    // that path delegates to add(undefined, { yes: true }).
+    let verify = Hooks.verifyAll(process.cwd());
+    if (!verify.ok && !verify.malformed) {
+      // A single best-effort re-registration before failing hard.
+      try {
+        await Hooks.registerAll(process.cwd(), {
+          onDrift: Hooks.createDriftPrompt(UI, { autoYes: nonInteractive }),
+        });
+      } catch (_) { /* fall through to the assert below */ }
+      verify = Hooks.verifyAll(process.cwd());
+    }
+    if (!verify.ok) {
+      UI.error(
+        verify.malformed
+          ? '.claude/settings.json is malformed — cannot verify hooks. Install is NOT complete.'
+          : `Hooks missing after install: ${verify.missing.join(', ')}. Install is NOT complete.`
+      );
+      UI.info('Run `npx baldart doctor` to repair, then re-check `npx baldart status`.');
+      process.exit(1);
+    }
+
     // Success summary
     UI.header('✓ INSTALLATION COMPLETE');
 

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/commands/update.js

@@ -592,6 +592,19 @@ async function update(options = {}) {
           UI.info(`  • ${c.sha.slice(0, 7)} — ${c.subject}`);
         }
 
+        // If every overlay-able commit only touches files that ALREADY have a
+        // matching overlay in `.baldart/overlays/`, the divergent edit's intent
+        // is already preserved — `--reset` is safe and `scaffold-overlays`
+        // would only create redundant skeletons. Surface that so the user/agent
+        // picks the cheap, correct resolution. (v3.33.0)
+        const allCovered = overlayCommits.length > 0
+          && overlayCommits.every((c) => c.overlayCovered === true);
+        if (allCovered) {
+          UI.newline();
+          UI.success('These edits are already preserved in `.baldart/overlays/` — `--reset` is safe (your overlays are re-applied); scaffolding new overlays would be redundant.');
+          UI.info('Fast path: `npx baldart update --reset --yes --i-know`.');
+        }
+
         // Non-interactive resolution (agents / CI) via --on-divergence.
         if (divStrategy === 'scaffold-overlays') {
           UI.newline();
@@ -604,7 +617,7 @@ async function update(options = {}) {
             'Alternatively, push the edits upstream with `/baldart-push` if they are generic improvements.',
           ], 'cyan');
           emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
-            divergence_class: status.divergenceClass,
+            divergence_class: status.divergenceClass, overlay_already_covered: allCovered,
             installed_before: status.installedVersion, remote_version: status.remoteVersion,
             reason: 'Scaffolded overlay skeleton(s); fill them in, then re-run.',
             next_command: 'npx baldart update --reset --yes --i-know' }, 0);
@@ -624,15 +637,23 @@ async function update(options = {}) {
           UI.error('Custom edits present — refusing to resolve them unattended under --yes.');
           UI.info('Re-run with one of:');
           UI.list([
-            '--on-divergence scaffold-overlays  → auto-create overlay skeleton(s), then stop so you can fill them',
+            allCovered
+              ? '--reset --yes --i-know             → SAFE here: these edits are already in `.baldart/overlays/` (recommended)'
+              : '--on-divergence scaffold-overlays  → auto-create overlay skeleton(s), then stop so you can fill them',
             '--on-divergence pull               → keep the commits and merge the update (non-destructive)',
-            '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
+            allCovered
+              ? '--on-divergence scaffold-overlays  → would create redundant skeletons (edits already covered)'
+              : '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
           ], 'cyan');
           emitUpdateJson({ ok: false, action: 'divergence-refused',
-            divergence_class: status.divergenceClass,
+            divergence_class: status.divergenceClass, overlay_already_covered: allCovered,
             installed_before: status.installedVersion, remote_version: status.remoteVersion,
-            reason: 'Custom edits present — refusing to resolve them unattended under --yes.',
-            next_command: 'npx baldart update --json --yes --on-divergence scaffold-overlays' }, 1);
+            reason: allCovered
+              ? 'Custom edits present but already preserved in .baldart/overlays/ — `--reset --yes --i-know` is the safe resolution.'
+              : 'Custom edits present — refusing to resolve them unattended under --yes.',
+            next_command: allCovered
+              ? 'npx baldart update --reset --yes --i-know'
+              : 'npx baldart update --json --yes --on-divergence scaffold-overlays' }, 1);
         } else {
           const choice = await UI.select('How would you like to proceed?', [
             { name: 'Scaffold overlay skeleton(s) now (recommended — then fill them in & re-run)', value: 'overlay' },

package/src/utils/__tests__/classify-divergence.test.js

@@ -149,6 +149,45 @@ const PATH_FIXTURES = [
   },
 ];
 
+// overlayRelForFrameworkFile(p) — pure mapping of a touched .framework/ payload
+// file to the consumer overlay path that would preserve a customization of it.
+// Mirrors src/commands/overlay.js conventions (overlayPath). null when no
+// overlay maps to the file. Used by overlayCoversTouched() to flag commits
+// whose intent is already preserved (→ `--reset` safe, scaffold redundant).
+const path = require('path');
+const OVERLAY_REL_FIXTURES = [
+  {
+    name: 'skill SKILL.md → flat overlay',
+    file: '.framework/framework/.claude/skills/ui-design/SKILL.md',
+    expected: path.join('.baldart', 'overlays', 'ui-design.md'),
+  },
+  {
+    name: 'skill nested script → same flat overlay',
+    file: '.framework/framework/.claude/skills/ui-design/scripts/foo.sh',
+    expected: path.join('.baldart', 'overlays', 'ui-design.md'),
+  },
+  {
+    name: 'agent .md → agents/ overlay',
+    file: '.framework/framework/.claude/agents/ui-expert.md',
+    expected: path.join('.baldart', 'overlays', 'agents', 'ui-expert.md'),
+  },
+  {
+    name: 'command .md → commands/ overlay',
+    file: '.framework/framework/.claude/commands/check.md',
+    expected: path.join('.baldart', 'overlays', 'commands', 'check.md'),
+  },
+  {
+    name: 'src file → null (no overlay maps)',
+    file: '.framework/src/utils/git.js',
+    expected: null,
+  },
+  {
+    name: 'nested agent path → null (agents are flat .md)',
+    file: '.framework/framework/.claude/agents/sub/x.md',
+    expected: null,
+  },
+];
+
 let pass = 0, fail = 0;
 
 console.log('─── Subject classifier ───');
@@ -187,5 +226,48 @@ for (const f of AGGREGATE_FIXTURES) {
   }
 }
 
+console.log('\n─── Overlay path mapping ───');
+for (const f of OVERLAY_REL_FIXTURES) {
+  const actual = GitUtils.overlayRelForFrameworkFile(f.file);
+  if (actual === f.expected) {
+    pass++;
+    console.log(`  ✓ ${f.name} → ${actual}`);
+  } else {
+    fail++;
+    console.log(`  ✗ ${f.name} → ${actual} (expected ${f.expected})`);
+  }
+}
+
+// overlayCoversTouched(touched) — fs-backed: true only when EVERY touched file
+// maps to an EXISTING overlay. This is the `overlayCovered` field that flows
+// (via classifyDivergence → getUpdateStatus.divergenceCommits, a direct
+// pass-through) into update.js's "reset is safe" branch. Lock the fs semantics.
+console.log('\n─── overlayCoversTouched (fs-backed) ───');
+{
+  const fsMod = require('fs');
+  const os = require('os');
+  const tmp = fsMod.mkdtempSync(path.join(os.tmpdir(), 'baldart-ovl-'));
+  fsMod.mkdirSync(path.join(tmp, '.baldart', 'overlays', 'agents'), { recursive: true });
+  fsMod.writeFileSync(path.join(tmp, '.baldart', 'overlays', 'agents', 'coder.md'), '---\n---\n');
+  const g2 = new GitUtils(tmp);
+  const cases = [
+    { name: 'touched file has an existing overlay → covered',
+      touched: ['.framework/framework/.claude/agents/coder.md'], expected: true },
+    { name: 'touched file has NO overlay → not covered',
+      touched: ['.framework/framework/.claude/agents/ui-expert.md'], expected: false },
+    { name: 'one covered + one uncovered → not covered (every)',
+      touched: ['.framework/framework/.claude/agents/coder.md',
+                '.framework/framework/.claude/agents/ui-expert.md'], expected: false },
+    { name: 'empty touched → not covered',
+      touched: [], expected: false },
+  ];
+  for (const c of cases) {
+    const actual = g2.overlayCoversTouched(c.touched);
+    if (actual === c.expected) { pass++; console.log(`  ✓ ${c.name} → ${actual}`); }
+    else { fail++; console.log(`  ✗ ${c.name} → ${actual} (expected ${c.expected})`); }
+  }
+  fsMod.rmSync(tmp, { recursive: true, force: true });
+}
+
 console.log(`\nResult: ${pass} pass, ${fail} fail`);
 process.exit(fail > 0 ? 1 : 0);

package/src/utils/git.js

@@ -256,6 +256,47 @@ class GitUtils {
     return allOverlayable ? 'custom-overlay-able' : 'custom-other';
   }
 
+  // Maps a touched `.framework/` payload file to the consumer overlay path that
+  // would preserve a customization of it, or null when no overlay maps to it.
+  // Mirrors the conventions in src/commands/overlay.js (overlayPath):
+  //   .framework/framework/.claude/skills/<name>/...   → .baldart/overlays/<name>.md
+  //   .framework/framework/.claude/agents/<name>.md    → .baldart/overlays/agents/<name>.md
+  //   .framework/framework/.claude/commands/<name>.md  → .baldart/overlays/commands/<name>.md
+  // Pure (no fs) so it stays unit-testable.
+  static overlayRelForFrameworkFile(p) {
+    const prefix = '.framework/framework/.claude/';
+    if (!p.startsWith(prefix)) return null;
+    const rest = p.slice(prefix.length);
+    const slash = rest.indexOf('/');
+    if (slash < 0) return null;
+    const dir = rest.slice(0, slash);
+    if (dir === 'skills') {
+      const name = rest.slice(slash + 1).split('/')[0];
+      if (!name) return null;
+      return path.join('.baldart', 'overlays', `${name}.md`);
+    }
+    if (dir === 'agents' || dir === 'commands') {
+      const file = rest.slice(slash + 1);
+      if (!file || file.includes('/')) return null; // flat <name>.md files only
+      const name = file.replace(/\.md$/, '');
+      if (!name) return null;
+      return path.join('.baldart', 'overlays', dir, `${name}.md`);
+    }
+    return null;
+  }
+
+  // True when EVERY overlay-able file touched by the commit already has an
+  // existing overlay in `.baldart/overlays/` — i.e. the divergent edit's intent
+  // is already preserved, so `--reset` is safe and `scaffold-overlays` would
+  // only create redundant skeletons.
+  overlayCoversTouched(touched) {
+    if (!touched || !touched.length) return false;
+    return touched.every((p) => {
+      const rel = GitUtils.overlayRelForFrameworkFile(p);
+      return rel ? fs.existsSync(path.join(this.cwd, rel)) : false;
+    });
+  }
+
   async classifyDivergence() {
     // Inspect aheadScoped commits — those not on FETCH_HEAD that touch .framework/.
     const commits = [];
@@ -297,7 +338,10 @@ class GitUtils {
           } catch (_) { /* leave empty → custom-other */ }
           category = this.classifyCommitByPaths(touched);
         }
-        commits.push({ sha, subject, category, parents, touched: touched || [] });
+        const overlayCovered = category === 'custom-overlay-able'
+          ? this.overlayCoversTouched(touched)
+          : false;
+        commits.push({ sha, subject, category, parents, touched: touched || [], overlayCovered });
       }
     } catch (_) {
       return { class: 'unknown', commits: [] };

package/src/utils/hooks.js

@@ -384,6 +384,38 @@ function unregisterAll(cwd = process.cwd()) {
   return { malformed: false, path: settingsPath, results };
 }
 
+// ---------------------------------------------------------------------------
+// Verify — post-flight assertion that every active hook is registered
+// ---------------------------------------------------------------------------
+
+/**
+ * Confirms that every active hook in HOOK_REGISTRY is present in
+ * `.claude/settings.json`. Pure read (delegates to `getStatus`). Designed as
+ * the post-flight gate for `add` / `update --reset`: the install must never
+ * declare success while a hook is missing (the silent partial-install class,
+ * v3.27.1 / mayo 3.28→3.31). Commented-out registry entries (e.g.
+ * capture-detect) are excluded for free — `getStatus` only iterates the array.
+ *
+ * A malformed settings.json counts as a failure: registration was skipped, so
+ * the hooks are not verifiably present.
+ *
+ * @param {string} [cwd]
+ * @returns {{ ok: boolean, malformed: boolean, missing: string[], path: string }}
+ */
+function verifyAll(cwd = process.cwd()) {
+  const status = getStatus(cwd);
+  if (status.malformed) {
+    return {
+      ok: false,
+      malformed: true,
+      missing: HOOK_REGISTRY.map((d) => d.id),
+      path: status.path,
+    };
+  }
+  const missing = status.hooks.filter((h) => !h.registered).map((h) => h.id);
+  return { ok: missing.length === 0, malformed: false, missing, path: status.path };
+}
+
 // ---------------------------------------------------------------------------
 // Drift prompt helper (interactive Keep / Replace / Show diff)
 // ---------------------------------------------------------------------------
@@ -434,6 +466,7 @@ module.exports = {
   HOOK_REGISTRY,
   SETTINGS_FILE,
   getStatus,
+  verifyAll,
   registerAll,
   unregisterAll,
   createDriftPrompt,

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

package/src/utils/overlay-merger.js

@@ -1,4 +1,5 @@
 const crypto = require('crypto');
+const fs = require('fs');
 const yaml = require('js-yaml');
 
 /**
@@ -41,6 +42,45 @@ function computeBaseFileSha(content) {
   return shortSha(content);
 }
 
+/**
+ * Idempotently backfill `base_file_sha` into an overlay file's frontmatter so
+ * `baldart overlay drift` is deterministic for EVERY overlay — not only those
+ * freshly scaffolded by `overlay scaffold` (which already writes it). Overlays
+ * authored by hand or by pre-v3.19.0 versions are otherwise "unknown" to drift
+ * (overlay.js drift § no base_file_sha). The merger knows the base file, so it
+ * stamps the sha here at `add`/`update` time.
+ *
+ * Contract: ADDITIVE-ONLY. Never overwrites an existing `base_file_sha`. Only
+ * touches a file that already has a leading YAML frontmatter block — never
+ * fabricates frontmatter on a file that lacks it. Fail-safe: any I/O error is
+ * swallowed (returns `changed:false`) so a backfill can never block a merge.
+ *
+ * @param {string} overlayPath absolute path to `.baldart/overlays/<…>.md`
+ * @param {string} baseSha     12-char hex from computeBaseFileSha(baseContent)
+ * @returns {{ changed: boolean, reason: string }}
+ */
+function ensureBaseFileShaInOverlay(overlayPath, baseSha) {
+  if (!baseSha) return { changed: false, reason: 'no-base-sha' };
+  let content;
+  try { content = fs.readFileSync(overlayPath, 'utf8'); }
+  catch (_) { return { changed: false, reason: 'unreadable' }; }
+  // Leading frontmatter block only (optionally after a BOM / blank lines).
+  const m = content.match(/^(\uFEFF?\s*)---\n([\s\S]*?)\n---(\r?\n|$)/);
+  if (!m) return { changed: false, reason: 'no-frontmatter' };
+  const fmBody = m[2];
+  if (/^\s*base_file_sha\s*:/m.test(fmBody)) {
+    return { changed: false, reason: 'already-present' };
+  }
+  // Quote the value — a 12-char hex can be all digits, which YAML would
+  // otherwise parse as a number (matches overlay.js buildFrontmatter).
+  const newFmBody = `${fmBody.replace(/\n+$/, '')}\nbase_file_sha: "${baseSha}"`;
+  const replaced = `${m[1]}---\n${newFmBody}\n---${m[3]}`;
+  const updated = content.slice(0, m.index) + replaced + content.slice(m.index + m[0].length);
+  try { fs.writeFileSync(overlayPath, updated, 'utf8'); }
+  catch (_) { return { changed: false, reason: 'unwritable' }; }
+  return { changed: true, reason: 'backfilled' };
+}
+
 function buildMarker({ kind, name, baseVersion, baseSha, overlaySha }) {
   const baseShaField = baseSha ? ` base_sha=${baseSha}` : '';
   return `${MARKER_PREFIX} kind=${kind} name=${name} base_version=${baseVersion}${baseShaField} overlay_sha=${overlaySha}
@@ -239,5 +279,6 @@ module.exports = {
   parseMarkdown,
   shortSha,
   computeBaseFileSha,
+  ensureBaseFileShaInOverlay,
   MARKER_PREFIX
 };

package/src/utils/symlinks.js

@@ -484,8 +484,17 @@ class SymlinkUtils {
   }
 
   _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
-    const { mergeOverlay, readMarker, isGeneratedFile } = require('./overlay-merger');
+    const { mergeOverlay, isGeneratedFile, computeBaseFileSha, ensureBaseFileShaInOverlay } = require('./overlay-merger');
     const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    // Backfill base_file_sha into the overlay frontmatter so `overlay drift` is
+    // deterministic for EVERY overlay, not just freshly-scaffolded ones
+    // (additive-only, never overwrites). Done BEFORE reading overlayContent so
+    // the marker's overlay_sha already reflects it — no one-time regen churn.
+    // (v3.33.0)
+    try {
+      const bf = ensureBaseFileShaInOverlay(overlayAbs, computeBaseFileSha(baseContent));
+      if (bf.changed) UI.info(`[${adapter.label}] ${kind} ${name}: backfilled base_file_sha into overlay frontmatter.`);
+    } catch (_) { /* non-fatal — never block a merge on backfill */ }
     const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
     const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion });