pi-lens 3.8.67 → 3.8.69

package/dist/clients/dispatch/dispatcher.js

@@ -116,6 +116,7 @@ function readFilePrefix(filePath, maxBytes = 4096) {
 }
 export function createDispatchContext(filePath, cwd, pi, facts, blockingOnly, modifiedRanges) {
     const absoluteFilePath = resolveRunnerPath(cwd, filePath);
+    const normalizedProjectRoot = normalizeMapKey(path.resolve(cwd));
     const normalizedCwd = normalizeMapKey(resolveLanguageRootForFile(absoluteFilePath, cwd));
     const normalizedFilePath = normalizeMapKey(absoluteFilePath);
     const kind = detectFileKind(normalizedFilePath);
@@ -123,6 +124,7 @@ export function createDispatchContext(filePath, cwd, pi, facts, blockingOnly, mo
     const projectConfig = loadPiLensProjectConfig(normalizedCwd);
     return {
         filePath: normalizedFilePath,
+        projectRoot: normalizedProjectRoot,
         cwd: normalizedCwd,
         kind,
         fileRole,

package/dist/clients/dispatch/integration.js

@@ -14,10 +14,12 @@ import { TOOL_PLANS } from "./plan.js";
 // Re-export latency tracking types and functions
 export { clearLatencyReports, formatLatencyReport, getLatencyReports };
 import * as nodeFs from "node:fs";
+import * as nodePath from "node:path";
 import { fileURLToPath } from "node:url";
 import { formatCascadeNeighborDiagnostics } from "../cascade-format.js";
 import { logCascade } from "../cascade-logger.js";
 import { getDiagnosticTracker } from "../diagnostic-tracker.js";
+import { classifyCascadeWaitTier, isTierAwareCascadeEnabled, recordOutstandingCascadeTouch, } from "../lsp/cascade-tier.js";
 import { getServersForFileWithConfig } from "../lsp/config.js";
 import { getLSPService } from "../lsp/index.js";
 import { isExternalOrVendorFile, normalizeMapKey } from "../path-utils.js";
@@ -28,6 +30,7 @@ import { buildOrUpdateGraph, computeImpactCascade, computeTransitiveImpact, form
 import { clearModuleGraphCache } from "../review-graph/workspace-modules.js";
 import { RUNTIME_CONFIG } from "../runtime-config.js";
 import { findCompiledClassesDir, hasJavaBuildDescriptor, } from "../tool-policy.js";
+import { removeWordIndexDocument, updateWordIndexDocument, WORD_INDEX_MAX_BYTES, } from "../word-index.js";
 // Register fact providers. All register eagerly here (the dispatch entry) — the
 // tree-sitter-backed providers included, since the parsing stack loads
 // `web-tree-sitter` lazily inside client.init(), not at module import, so it
@@ -355,7 +358,11 @@ export function clearReverseDepsIndexCache() {
 const CASCADE_TRANSITIVE_DEPTH = Math.max(1, Number.parseInt(process.env.PI_LENS_CASCADE_TRANSITIVE_DEPTH ?? "2", 10) || 2);
 const CASCADE_NEIGHBOUR_BUDGET = Math.max(MAX_FILES, Number.parseInt(process.env.PI_LENS_CASCADE_NEIGHBOUR_BUDGET ?? "40", 10) ||
     40);
-const CASCADE_GRAPH_KINDS = new Set([
+// Exported (not just module-local) so the MCP warm-analyze seam
+// (clients/mcp/analyze.ts, #536) can gate its own buildOrUpdateGraph call on
+// the SAME file-kind eligibility this cascade path uses — one source of truth
+// for "does this language get graph nodes at all", never a second hardcoded copy.
+export const CASCADE_GRAPH_KINDS = new Set([
     "jsts",
     "python",
     "go",
@@ -392,8 +399,67 @@ function isIgnoredCascadeNeighbor(filePath, cwd) {
         return false;
     }
 }
+/**
+ * #348 phase 2 per-edit seam: update the warm in-memory word index for one
+ * file, mirroring the review graph's per-edit rebuild at the same call site.
+ *
+ * Rules (each a documented, deliberate simplicity choice, not an oversight):
+ *  - `wordIndex` null (no index loaded yet) ⇒ no-op. Cold-session handoff is
+ *    OWNED by phase 1's lifecycle/background build, never invented here — an
+ *    edit arriving before that build finishes just doesn't update anything;
+ *    the eventual full build already reflects every file on disk, incl. this
+ *    edit, so nothing is lost, only delayed.
+ *  - `wordIndex.forward` undefined (pre-phase-2 index shape, e.g. a snapshot
+ *    persisted before this feature or one still using the old serialized
+ *    shape) ⇒ no-op. `updateWordIndexDocument` already refuses to mutate a
+ *    forward-index-less index (see its doc comment) — this is the same rule
+ *    surfaced one layer up so the caller isn't left guessing why nothing
+ *    happened. The NEXT full rebuild (session-start lifecycle) installs a
+ *    forward-index-bearing index that later edits CAN update incrementally.
+ *  - `content` undefined (pipeline couldn't read the file — deleted, or a
+ *    transient race) ⇒ no-op. Deletions aren't plumbed at this seam (this
+ *    call site only ever sees the edited file's post-write content, never a
+ *    delete event) — a removed file ages out at the next full rebuild, same
+ *    scope boundary the review graph accepts for deletes.
+ *  - File over the shared `WORD_INDEX_MAX_BYTES` cap ⇒ removed/absent from
+ *    the index (never partially indexed) — same cap phase 1's build path
+ *    enforces via `collectWordIndexDocs`.
+ *  - On a successful update, `onUpdated` fires so the caller can schedule a
+ *    debounced persist (never a synchronous write per edit — same #260
+ *    discipline as the graph).
+ *
+ * Race safety against a build-in-progress: this function body is entirely
+ * synchronous (no `await` anywhere in it) and is called synchronously at
+ * `computeCascadeForFile`'s entry, before its own `await buildOrUpdateGraph`.
+ * Node is single-threaded, so two overlapping cascades (#450's unawaited
+ * concurrency) can never interleave mid-mutation here — each call runs to
+ * completion in one turn. The only cross-build hazard is a full session-start
+ * rebuild REPLACING `runtime.wordIndex` with a new object between the caller
+ * reading `runtime.wordIndex` (in runtime-tool-result.ts, also synchronous)
+ * and this function receiving it — in that case this call simply mutates
+ * whichever index object it was handed (old or new), and the other one is
+ * abandoned/superseded, never corrupted. No queue, no lock: the simplest rule
+ * that is still provably correct.
+ */
+function updateWordIndexForCascade(args) {
+    const { wordIndex, filePath, content, onUpdated, dbg } = args;
+    if (!wordIndex || !wordIndex.forward)
+        return;
+    if (content === undefined)
+        return;
+    const byteLength = Buffer.byteLength(content, "utf-8");
+    if (byteLength > WORD_INDEX_MAX_BYTES) {
+        removeWordIndexDocument(wordIndex, filePath);
+        dbg?.(`word-index per-edit: dropped ${filePath} (over size cap)`);
+    }
+    else {
+        updateWordIndexDocument(wordIndex, { path: filePath, content });
+        dbg?.(`word-index per-edit: updated ${filePath}`);
+    }
+    onUpdated?.(wordIndex);
+}
 export async function computeCascadeForFile(filePath, cwd, options = {}) {
-    const { hasBlockers = false, dbg, turnSeq = 0, writeSeq, seqState } = options;
+    const { hasBlockers = false, dbg, turnSeq = 0, writeSeq, seqState, fileContent, wordIndex, onWordIndexUpdated, } = options;
     ensureCascadeTurnScope(turnSeq);
     if (hasBlockers) {
         logCascade({
@@ -425,6 +491,30 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
     // B10: record this file as a primary edit so later cascade calls in the same
     // turn won't show it as a neighbor.
     primaryFilesThisTurn.add(normalizedFileKey);
+    // #348 phase 2: warm per-edit word-index maintenance, review-graph style —
+    // update at the SAME seam as the graph rebuild below, using content the
+    // pipeline already read (no extra I/O). See computeCascadeForFile's
+    // `wordIndex`/`fileContent` doc comments for the cold/no-forward-index
+    // no-op rules.
+    //
+    // Deliberately keyed by `path.resolve(filePath)`, NOT `normalizedFile`
+    // (which is `normalizeMapKey`'d — realpath-canonicalized + lowercased on
+    // Windows). The word index's OWN keys come from `collectWordIndexDocs` →
+    // `collectSourceFilesAsync`'s file walk, which yields plain
+    // `path.resolve()`-joined paths (native separators, on-disk casing as
+    // reported by the walk, no realpath call). Keying this update with the
+    // cascade's normalized key would silently create a SECOND, orphaned entry
+    // next to the walker's original-cased entry instead of replacing it —
+    // exactly the kind of divergence the equivalence-property test is meant to
+    // catch, so the key shape here must match the build path's, not the
+    // cascade/graph's own (different) normalization scheme.
+    updateWordIndexForCascade({
+        wordIndex,
+        filePath: nodePath.resolve(filePath),
+        content: fileContent,
+        onUpdated: onWordIndexUpdated,
+        dbg,
+    });
     let impact = {
         filePath: normalizedFile,
         changedSymbols: [],
@@ -828,6 +918,67 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             }
             // A6: async read to avoid blocking event loop on network-mounted drives
             const content = await nodeFs.promises.readFile(neighborPath, "utf8");
+            // #458: tier-aware cascade-lane wait. A Tier-3 (push-only,
+            // silent-on-clean — typescript is the lone core-set instance today)
+            // primary can never give this in-lane wait an affirmative clean
+            // signal, so the budget is pure cost. Fire the touch (didOpen/
+            // didChange still happens — the server starts real work) and record
+            // it as outstanding for the agent_settled quiet window to reconcile
+            // instead of waiting here. Ambiguous/missing capability data always
+            // classifies as "waits" (today's behavior) — see cascade-tier.ts.
+            // The whole attempt is try/caught: any surprise (a service shape
+            // that doesn't expose getCapabilitySnapshots/getClientForFile, a
+            // thrown rejection) falls through to the existing full-wait path
+            // below rather than skip the wait on a failure.
+            if (isTierAwareCascadeEnabled()) {
+                try {
+                    const snapshots = (await lspService.getCapabilitySnapshots?.(neighborPath)) ?? [];
+                    const tier = classifyCascadeWaitTier(lspService, neighborPath, snapshots);
+                    if (tier === "tier3-silent") {
+                        const spawnedForTouch = await lspService.getClientForFile(neighborPath);
+                        if (spawnedForTouch) {
+                            // Sampled BEFORE the touchFile notify: a publish landing
+                            // in the notify→record gap must read as post-touch at
+                            // reconcile time, never be misclassified as pre-touch
+                            // (the reconcile compares this against the client's
+                            // PER-FILE publish timestamp — see cascade-tier.ts).
+                            const touchedAt = Date.now();
+                            await lspService.touchFile(neighborPath, content, {
+                                diagnostics: "none",
+                                collectDiagnostics: false,
+                                silent: true,
+                                source: "cascade",
+                                clientScope: "primary",
+                            });
+                            recordOutstandingCascadeTouch({
+                                filePath: neighborPath,
+                                serverId: spawnedForTouch.client.serverId,
+                                touchedAt,
+                            });
+                            const durationMs = Date.now() - neighborStart;
+                            logCascade({
+                                phase: "cascade_tier3_skip",
+                                filePath,
+                                neighborFile: neighborPath,
+                                durationMs,
+                                lspServerCount: configuredServerCount,
+                                coldSnapshot: isColdSnapshot,
+                                metadata: { serverId: spawnedForTouch.client.serverId },
+                            });
+                            // Deliberately NOT cached as clean/diagnosed — the wait was
+                            // skipped, not resolved, so neither neighborTouchCache nor
+                            // recentlyCleanNeighborCache may treat this as a real answer
+                            // (#240 doctrine). Return undefined: the degraded-fallback
+                            // path below still has a chance to surface a passive/stale
+                            // snapshot, same as any other "no fresh data this touch" case.
+                            return undefined;
+                        }
+                    }
+                }
+                catch (tierErr) {
+                    dbg?.(`cascade tier-aware skip attempt failed for ${neighborPath}, falling back to full wait: ${tierErr}`);
+                }
+            }
             // Open with silent=true (suppresses didChangeWatchedFiles rechecks, C2)
             // and collect diagnostics from the same touched clients.
             // Cold-snapshot neighbors (autoPropagate LSP, server warm) use a tighter

package/dist/clients/dispatch/runners/ast-grep-napi.js

@@ -9,12 +9,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadAstGrepNapi, } from "../../deps/ast-grep-napi.js";
-import { resolvePackagePath } from "../../package-root.js";
+import { getAstGrepRuleSources, } from "../../sgconfig.js";
 import { hasEslintConfig } from "../../tool-policy.js";
 import { enabledAuxiliaryLspServerIds } from "../auxiliary-lsp.js";
 import { classifyDefect } from "../diagnostic-taxonomy.js";
 import { PRIORITY } from "../priorities.js";
-import { calculateRuleComplexity, isOverlyBroadPattern, isStructuredRule, loadYamlRules, MAX_BLOCKING_RULE_COMPLEXITY, } from "./yaml-rule-parser.js";
+import { calculateRuleComplexity, isOverlyBroadPattern, isStructuredRule, loadYamlRules, loadYamlRulesFresh, MAX_BLOCKING_RULE_COMPLEXITY, } from "./yaml-rule-parser.js";
 // Lazy load the napi package
 let sg;
 let sgLoadAttempted = false;
@@ -122,6 +122,40 @@ export function getLang(filePath, sgModule) {
             return undefined;
     }
 }
+function duplicateRuleIds(rules) {
+    const counts = new Map();
+    for (const rule of rules) {
+        counts.set(rule.id, (counts.get(rule.id) ?? 0) + 1);
+    }
+    return Array.from(counts)
+        .filter(([, count]) => count > 1)
+        .map(([id]) => id)
+        .sort((a, b) => a.localeCompare(b));
+}
+function appendDuplicateRuleDiagnostics(diagnostics, seenRuleIds, duplicateIds, source, filePath, maxTotalDiagnostics) {
+    const sourceLabel = `${source.origin} ${source.tier} rules`;
+    for (const ruleId of duplicateIds) {
+        diagnostics.push({
+            id: `ast-grep-napi-config-duplicate-${source.origin}-${source.tier}-${ruleId}`,
+            message: `Duplicate ast-grep rule id "${ruleId}" in ${sourceLabel}`,
+            filePath,
+            line: 1,
+            column: 1,
+            severity: "error",
+            semantic: "blocking",
+            tool: "ast-grep-napi",
+            rule: ruleId,
+            defectClass: "correctness",
+            fixable: false,
+            autoFixAvailable: false,
+            fixSuggestion: `Give every rule in ${sourceLabel} a unique id`,
+        });
+        seenRuleIds.add(ruleId);
+        if (diagnostics.length >= maxTotalDiagnostics)
+            return true;
+    }
+    return false;
+}
 /**
  * Run the shipped ast-grep YAML ruleset against a parsed file via napi's native
  * engine, applying the same suppression policy (linter/tree-sitter overlap,
@@ -138,26 +172,34 @@ export function evaluateAstGrepRules(filePath, rootNode, cwd, kind, options = {}
     const diagnostics = [];
     const seenRuleIds = new Set();
     const suppressLinterOverlap = kind === "jsts" && hasEslintConfig(cwd);
-    const ruleDirs = [
-        path.join(process.cwd(), "rules", "ast-grep-rules", "rules"),
-        path.join(process.cwd(), "rules", "ast-grep-rules"),
-        resolvePackagePath(import.meta.url, "rules", "ast-grep-rules", "rules"),
-        resolvePackagePath(import.meta.url, "rules", "ast-grep-rules"),
-    ];
-    for (const ruleDir of ruleDirs) {
+    // Shared with the raw sgconfig materializer so both surfaces walk the same
+    // workspace-rooted sources in the same precedence order.
+    const ruleSources = getAstGrepRuleSources(options.projectRoot ?? cwd);
+    for (const source of ruleSources) {
         let rules;
         try {
-            rules = loadYamlRules(ruleDir, blockingOnly ? "error" : undefined);
+            // Project rules are mutable during a session, so their cache fingerprints
+            // relative paths and contents. Bundled catalogs are immutable per install.
+            const loader = source.origin === "project" ? loadYamlRulesFresh : loadYamlRules;
+            rules = loader(source.dir);
         }
         catch {
             continue;
         }
+        const duplicates = duplicateRuleIds(rules);
+        if (appendDuplicateRuleDiagnostics(diagnostics, seenRuleIds, duplicates, source, filePath, maxTotalDiagnostics)) {
+            return diagnostics;
+        }
+        const duplicateSet = new Set(duplicates);
         for (const rule of rules) {
-            // If the same rule id is loaded from multiple directories
-            // (workspace + bundled), prefer the first one to avoid duplicates.
+            if (duplicateSet.has(rule.id))
+                continue;
+            // Cross-layer collisions keep the first (higher-precedence) source.
             if (seenRuleIds.has(rule.id))
                 continue;
             seenRuleIds.add(rule.id);
+            if (blockingOnly && rule.severity !== "error")
+                continue;
             if (suppressLinterOverlap &&
                 LINTER_OVERLAP.has(normalizeRuleId(rule.id)) &&
                 !NON_SUPPRESSIBLE.has(normalizeRuleId(rule.id))) {
@@ -310,7 +352,10 @@ const astGrepNapiRunner = {
         catch {
             return { status: "skipped", diagnostics: [], semantic: "none" };
         }
-        const diagnostics = evaluateAstGrepRules(ctx.filePath, rootNode, ctx.cwd, ctx.kind, { blockingOnly: ctx.blockingOnly });
+        const diagnostics = evaluateAstGrepRules(ctx.filePath, rootNode, ctx.cwd, ctx.kind, {
+            blockingOnly: ctx.blockingOnly,
+            projectRoot: ctx.projectRoot,
+        });
         const hasBlocking = diagnostics.some((d) => d.semantic === "blocking");
         let semantic = "none";
         if (hasBlocking) {

package/dist/clients/dispatch/runners/yaml-rule-parser.js

@@ -6,11 +6,12 @@
  * (has/any/all/not/regex).
  *
  * Features:
- * - Caching with mtime-based invalidation
+ * - Mtime caching for bundled rules; content/path caching for project rules
  * - Severity filtering (error-only for blocking mode)
  * - Complexity scoring for performance optimization
  * - Overly broad pattern detection
  */
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import yaml from "../../deps/js-yaml.js";
@@ -29,41 +30,89 @@ export const MAX_BLOCKING_RULE_COMPLEXITY = 8;
 // --- Caches ---
 const rulesCache = new Map();
 const blockingRulesCache = new Map();
+const contentRulesCache = new Map();
+const contentBlockingRulesCache = new Map();
 // --- Public API ---
 export function clearRulesCache() {
     rulesCache.clear();
     blockingRulesCache.clear();
+    contentRulesCache.clear();
+    contentBlockingRulesCache.clear();
 }
 export function loadYamlRules(ruleDir, severityFilter) {
     return getCachedRules(ruleDir, severityFilter);
 }
-export function loadYamlRulesUncached(ruleDir, severityFilter) {
+function findYamlRuleFiles(ruleDir) {
+    let entries;
+    try {
+        entries = fs
+            .readdirSync(ruleDir, { withFileTypes: true })
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = path.join(ruleDir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...findYamlRuleFiles(full));
+        }
+        else if (entry.isFile() && /\.ya?ml$/i.test(entry.name)) {
+            files.push(full);
+        }
+    }
+    return files;
+}
+function loadYamlRuleFiles(files, severityFilter) {
     const rules = [];
-    if (!fs.existsSync(ruleDir))
-        return rules;
-    const files = fs.readdirSync(ruleDir).filter((f) => f.endsWith(".yml"));
     for (const file of files) {
         let content;
         try {
-            content = fs.readFileSync(path.join(ruleDir, file), "utf-8");
+            content = fs.readFileSync(file, "utf-8");
         }
         catch {
-            continue; // unreadable file
+            continue;
+        }
+        const documents = content.split(/^---\s*$/m).filter((doc) => doc.trim());
+        for (const document of documents) {
+            const rule = parseSimpleYaml(document.trim());
+            if (!rule?.id)
+                continue;
+            if (severityFilter && rule.severity !== severityFilter)
+                continue;
+            rules.push(rule);
         }
-        const documents = content.split(/^---$/m).filter((d) => d.trim());
-        // Parse each document independently so one malformed rule (e.g. an
-        // unquoted YAML-special scalar) skips only itself, not the whole file —
-        // slop-patterns.yml packs many rules into a single file.
-        for (const doc of documents) {
-            const rule = parseSimpleYaml(doc.trim());
-            if (rule?.id) {
-                if (severityFilter && rule.severity !== severityFilter) {
-                    continue;
-                }
-                rules.push(rule);
-            }
+    }
+    return rules;
+}
+export function loadYamlRulesUncached(ruleDir, severityFilter) {
+    return loadYamlRuleFiles(findYamlRuleFiles(ruleDir), severityFilter);
+}
+/** Content/path-aware cache used for mutable project-owned rule trees. */
+export function loadYamlRulesFresh(ruleDir, severityFilter) {
+    const files = findYamlRuleFiles(ruleDir);
+    const hash = createHash("sha256");
+    for (const file of files) {
+        hash.update(path.relative(ruleDir, file));
+        hash.update("\0");
+        try {
+            hash.update(fs.readFileSync(file));
+        }
+        catch {
+            hash.update("missing");
         }
+        hash.update("\0");
     }
+    const signature = hash.digest("hex");
+    const cache = severityFilter === "error"
+        ? contentBlockingRulesCache
+        : contentRulesCache;
+    const cached = cache.get(ruleDir);
+    if (cached?.signature === signature)
+        return cached.rules;
+    const rules = loadYamlRuleFiles(files, severityFilter);
+    cache.set(ruleDir, { rules, signature });
     return rules;
 }
 export function getCachedRules(ruleDir, severityFilter) {

package/dist/clients/file-utils.js

@@ -30,7 +30,7 @@ export function getProjectDataDir(cwd) {
     if (!configuredBase && fs.existsSync(legacyProjectDir)) {
         return legacyProjectDir;
     }
-    const base = configuredBase || path.join(os.homedir(), ".pi-lens", "projects");
+    const base = configuredBase || path.join(getGlobalPiLensDir(), "projects");
     const normalized = normalizeFilePath(path.resolve(cwd));
     const slug = normalized
         .replace(/^[a-z]:/i, "") // strip Windows drive letter
@@ -41,18 +41,31 @@ export function getProjectDataDir(cwd) {
     return path.join(base.trim(), slug || "default");
 }
 /**
- * Machine-global pi-lens directory: `~/.pi-lens/`.
+ * Machine-global pi-lens directory: `~/.pi-lens/` by default.
  *
  * Used for logs (latency, cascade, read-guard, tree-sitter, actionable-warnings,
- * sessionstart), tool binaries (`~/.pi-lens/tools/`, `~/.pi-lens/bin/`), LSP
- * server storage, and other state that is intentionally NOT project-scoped
- * — it spans every project pi-lens has touched.
+ * sessionstart), tool binaries (`~/.pi-lens/tools/`, `~/.pi-lens/bin/`), the
+ * cross-process instance registry (`instances.json`, #449/#525), the
+ * auto-install probe cache, and other state that is intentionally NOT
+ * project-scoped — it spans every project pi-lens has touched.
+ *
+ * Override: set `PI_LENS_HOME=/some/path` to relocate this ENTIRE root (every
+ * caller below routes through this one function, so one env var covers all of
+ * them — see #525). Tests MUST set this to a per-worker temp dir in
+ * `tests/support/vitest-setup.ts` rather than mocking each caller separately;
+ * otherwise a test that exercises `registerInstance`/`sweepOrphans` or any
+ * logger writes into the developer's REAL `~/.pi-lens` (dogfooded live: a
+ * test-fixture instance survived in the real `instances.json` for 17h).
  *
  * Distinct from `getProjectDataDir(cwd)`, which respects `PILENS_DATA_DIR`
- * and produces per-project subdirectories. Callers writing project caches,
- * snapshots, or worklogs should use `getProjectDataDir(cwd)` instead.
+ * (project-scoped) and produces per-project subdirectories. Callers writing
+ * project caches, snapshots, or worklogs should use `getProjectDataDir(cwd)`
+ * instead — `PI_LENS_HOME` is the MACHINE-scoped sibling of that override.
  */
 export function getGlobalPiLensDir() {
+    const override = process.env.PI_LENS_HOME?.trim();
+    if (override)
+        return path.resolve(override);
     return path.join(os.homedir(), ".pi-lens");
 }
 /**

package/dist/clients/installer/index.js

@@ -1036,11 +1036,41 @@ export const TOOLS = [
             // bare binary — no binaryInArchive
         },
     },
+    {
+        // Expert ships a bare native binary per platform on GitHub releases. Its
+        // `--stdio` flag is required to start the LSP transport. Windows arm64 uses
+        // the x64 binary through Windows' built-in x64 emulation.
+        id: "expert",
+        name: "Expert",
+        checkCommand: "expert",
+        checkArgs: ["--version"],
+        installStrategy: "github",
+        binaryName: "expert",
+        github: {
+            repo: "expert-lsp/expert",
+            assetMatch: (platform, arch) => {
+                if (arch !== "x64" && arch !== "arm64")
+                    return undefined;
+                if (platform === "linux")
+                    return arch === "arm64"
+                        ? "expert_linux_arm64"
+                        : "expert_linux_amd64";
+                if (platform === "darwin")
+                    return arch === "arm64"
+                        ? "expert_darwin_arm64"
+                        : "expert_darwin_amd64";
+                if (platform === "win32")
+                    return "expert_windows_amd64.exe";
+                return undefined;
+            },
+            // bare binary — no binaryInArchive
+        },
+    },
 ];
 const ensureInFlight = new Map();
 // Session-lifetime cache: once a tool path is resolved, skip the process-spawn check on subsequent calls.
 const resolvedPathCache = new Map();
-const PROBE_CACHE_PATH = path.join(os.homedir(), ".pi-lens", "probe-cache.json");
+const PROBE_CACHE_PATH = path.join(getGlobalPiLensDir(), "probe-cache.json");
 const PROBE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 let _probeCache = null;
 let _probeCacheDirty = false;
@@ -2735,6 +2765,7 @@ export const GITHUB_TOOLS = [
     "clojure-lsp",
     "gleam",
     "marksman",
+    "expert",
 ];
 /**
  * Resolve the GitHub asset filename substring for a tool on a given platform/arch.