@octocodeai/octocode-engine 16.5.1 → 16.6.2

package/dist/lsp/client.d.ts

@@ -1,6 +1,7 @@
 import type { CallHierarchyItem, CodeSnippet, ExactPosition, IncomingCall, LanguageServerConfig, OutgoingCall } from './types.js';
 export declare class LSPClient {
     private readonly nativeClient;
+    private readonly command;
     private initialized;
     constructor(config: LanguageServerConfig);
     start(): Promise<void>;
@@ -20,6 +21,11 @@ export declare class LSPClient {
     prepareCallHierarchy(filePath: string, position: ExactPosition, content?: string): Promise<CallHierarchyItem[]>;
     getIncomingCalls(item: CallHierarchyItem): Promise<IncomingCall[]>;
     getOutgoingCalls(item: CallHierarchyItem): Promise<OutgoingCall[]>;
+    workspaceSymbol(query: string): Promise<unknown[]>;
+    prepareTypeHierarchy(filePath: string, position: ExactPosition, content?: string): Promise<unknown[]>;
+    typeHierarchySupertypes(item: unknown): Promise<unknown[]>;
+    typeHierarchySubtypes(item: unknown): Promise<unknown[]>;
+    getDiagnostics(filePath: string, content?: string): Promise<unknown>;
     hasCapability(_capability: string): boolean;
     getRecentStderr(): string[];
     openDocument(filePath: string, content?: string): Promise<void>;

package/dist/lsp/client.js

@@ -1,9 +1,12 @@
 import { promises as fs } from 'node:fs';
 import { nativeBinding } from './native.js';
+import { validateLSPServerPath } from './validation.js';
 export class LSPClient {
     nativeClient;
+    command;
     initialized = false;
     constructor(config) {
+        this.command = config.command;
         this.nativeClient = new nativeBinding.NativeLspClient({
             command: config.command,
             args: config.args,
@@ -14,6 +17,13 @@ export class LSPClient {
         });
     }
     async start() {
+        // Security gate: never spawn a command that isn't a real, executable,
+        // non-shell server binary — even one resolved from the managed download
+        // cache. This is the single chokepoint before the native process spawn.
+        const validation = validateLSPServerPath(this.command);
+        if (!validation.isValid) {
+            throw new Error(`Refusing to start language server: ${validation.error ?? `invalid server path '${this.command}'`}`);
+        }
         await this.nativeClient.start();
         this.initialized = true;
     }
@@ -76,6 +86,27 @@ export class LSPClient {
         const result = await this.nativeClient.outgoingCalls(item);
         return Array.isArray(result) ? result : [];
     }
+    async workspaceSymbol(query) {
+        const result = await this.nativeClient.workspaceSymbol(query);
+        return Array.isArray(result) ? result : [];
+    }
+    async prepareTypeHierarchy(filePath, position, content) {
+        await this.openDocument(filePath, content);
+        const result = await this.nativeClient.prepareTypeHierarchy(filePath, position.line, position.character);
+        return Array.isArray(result) ? result : [];
+    }
+    async typeHierarchySupertypes(item) {
+        const result = await this.nativeClient.typeHierarchySupertypes(item);
+        return Array.isArray(result) ? result : [];
+    }
+    async typeHierarchySubtypes(item) {
+        const result = await this.nativeClient.typeHierarchySubtypes(item);
+        return Array.isArray(result) ? result : [];
+    }
+    async getDiagnostics(filePath, content) {
+        await this.openDocument(filePath, content);
+        return this.nativeClient.getDiagnostics(filePath);
+    }
     hasCapability(_capability) {
         return (this.initialized &&
             (this.nativeClient.hasCapability?.(_capability) ?? true));

package/dist/lsp/config.d.ts

@@ -1,3 +1,31 @@
-import type { LanguageServerConfig } from './types.js';
+import type { LanguageServerConfig, LspServerSource } from './types.js';
+/**
+ * Names of the servers octocode bundles (offline-ready, zero install). Single
+ * source for any "what's bundled" listing (e.g. the `lsp-server` CLI), derived
+ * from the maps above so it never drifts. pyright is the bundled Python server
+ * even though the native default command is `pylsp`.
+ */
+export declare const BUNDLED_SERVER_NAMES: readonly string[];
 export declare function detectLanguageId(filePath: string): string;
+/**
+ * Resolve the language-server config for a file, walking the resolution ladder
+ * behind a stable signature. The public contract is unchanged — callers still
+ * get a `LanguageServerConfig | null`; only the resolution behind it is richer.
+ */
 export declare function getLanguageServerForFile(filePath: string, workspaceRoot?: string): Promise<LanguageServerConfig | null>;
+export interface ServerResolution {
+    config: LanguageServerConfig;
+    source: LspServerSource;
+}
+/**
+ * Full resolution including provenance, for status reporting. Order:
+ *   L0/L1 explicit override + PATH  (already applied natively in config.rs)
+ *   L2    bundled JS server         (npm dep, launched via current Node)
+ *   L3    project-local / ecosystem (cargo/go/python/npm-global/mason/brew…)
+ *   L4    managed download cache    (~/.octocode/lsp, if pre-provisioned)
+ * Returns `source: 'unavailable'` (config still populated) when nothing on the
+ * machine provides the server, so the caller can report honest guidance.
+ */
+/** Check whether a bare command name is available on the current process PATH. */
+export declare function isCommandOnPath(command: string): boolean;
+export declare function resolveServerForFile(filePath: string, workspaceRoot?: string): Promise<ServerResolution | null>;

package/dist/lsp/config.js

@@ -1,7 +1,162 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
 import { nativeBinding } from './native.js';
+import { discoverServer } from './serverDiscovery.js';
+import { manifestServer, resolveCachedServer } from './serverManifest.js';
+const requireFromPackage = createRequire(import.meta.url);
+/**
+ * Pure-JS language servers shipped as npm dependencies of this package. When
+ * the named command is not otherwise available we launch the bundled CLI with
+ * the current Node runtime — so TS/JS, YAML, and the JSON/HTML/CSS data-format
+ * servers work in production with zero user install. Keyed by the bare command
+ * name the native spec table (`config.rs`) emits, so the native `args` carry
+ * over unchanged.
+ */
+const BUNDLED_JS_SERVERS = {
+    'typescript-language-server': 'typescript-language-server/lib/cli.mjs',
+    'yaml-language-server': 'yaml-language-server/bin/yaml-language-server',
+    'vscode-json-language-server': 'vscode-langservers-extracted/bin/vscode-json-language-server',
+    'vscode-html-language-server': 'vscode-langservers-extracted/bin/vscode-html-language-server',
+    'vscode-css-language-server': 'vscode-langservers-extracted/bin/vscode-css-language-server',
+    // PHP: native spec defaults to `intelephense` — command-keyed so native args carry over.
+    'intelephense': 'intelephense/lib/intelephense.js',
+};
+/**
+ * Bundled servers selected by languageId when the native default command
+ * differs from the bundled one. Python's spec defaults to `pylsp`, but we ship
+ * `pyright` — a different launch contract (`pyright-langserver --stdio`) — so
+ * it is matched by language, not command name, and supplies its own args.
+ */
+const BUNDLED_BY_LANGUAGE = {
+    python: { cli: 'pyright/langserver.index.js', args: ['--stdio'] },
+    // Shell scripts: native spec table has no shellscript server spec, so this
+    // is the pre-native fallback path (detectLanguageId → 'shellscript' → here).
+    shellscript: { cli: 'bash-language-server/out/cli.js', args: ['start'] },
+};
+/**
+ * Names of the servers octocode bundles (offline-ready, zero install). Single
+ * source for any "what's bundled" listing (e.g. the `lsp-server` CLI), derived
+ * from the maps above so it never drifts. pyright is the bundled Python server
+ * even though the native default command is `pylsp`.
+ */
+export const BUNDLED_SERVER_NAMES = [
+    ...Object.keys(BUNDLED_JS_SERVERS),
+    'pyright',
+    'bash-language-server',
+];
 export function detectLanguageId(filePath) {
     return nativeBinding.detectLanguageId(filePath) ?? 'plaintext';
 }
+/**
+ * Resolve the language-server config for a file, walking the resolution ladder
+ * behind a stable signature. The public contract is unchanged — callers still
+ * get a `LanguageServerConfig | null`; only the resolution behind it is richer.
+ */
 export async function getLanguageServerForFile(filePath, workspaceRoot = process.cwd()) {
-    return (nativeBinding.getLanguageServerForFile(filePath, workspaceRoot) ?? null);
+    return (await resolveServerForFile(filePath, workspaceRoot))?.config ?? null;
+}
+/**
+ * Full resolution including provenance, for status reporting. Order:
+ *   L0/L1 explicit override + PATH  (already applied natively in config.rs)
+ *   L2    bundled JS server         (npm dep, launched via current Node)
+ *   L3    project-local / ecosystem (cargo/go/python/npm-global/mason/brew…)
+ *   L4    managed download cache    (~/.octocode/lsp, if pre-provisioned)
+ * Returns `source: 'unavailable'` (config still populated) when nothing on the
+ * machine provides the server, so the caller can report honest guidance.
+ */
+/** Check whether a bare command name is available on the current process PATH. */
+export function isCommandOnPath(command) {
+    return nativeBinding.isCommandAvailable(command);
+}
+export async function resolveServerForFile(filePath, workspaceRoot = process.cwd()) {
+    const base = nativeBinding.getLanguageServerForFile(filePath, workspaceRoot) ?? null;
+    // Pre-native: languages absent from the native spec table (e.g. shellscript)
+    // can still get a bundled server via BUNDLED_BY_LANGUAGE.
+    if (!base) {
+        const langId = nativeBinding.detectLanguageId(filePath) ?? '';
+        const preNative = langId ? BUNDLED_BY_LANGUAGE[langId] : undefined;
+        if (preNative) {
+            const cliPath = resolveBundledCli(preNative.cli);
+            if (cliPath) {
+                return {
+                    config: {
+                        command: process.execPath,
+                        args: [cliPath, ...preNative.args],
+                        languageId: langId,
+                    },
+                    source: 'bundled',
+                };
+            }
+        }
+        return null;
+    }
+    // L0/L1: the native command already resolved (explicit override or on PATH).
+    if (nativeBinding.isCommandAvailable(base.command)) {
+        return { config: base, source: 'path' };
+    }
+    // L2: bundled JS server launched with the current Node runtime.
+    const bundled = withBundledJsServer(base);
+    if (bundled)
+        return { config: bundled, source: 'bundled' };
+    // L3: discover a server installed outside PATH (ecosystem/project-local dirs).
+    const discovered = discoverServer(base.command, workspaceRoot);
+    if (discovered) {
+        return {
+            config: { ...base, command: discovered.command },
+            source: discovered.source === 'project-local' ? 'project-local' : 'ecosystem',
+        };
+    }
+    // L4: a binary already sitting in the managed download cache.
+    const cached = resolveCachedServer(base.command);
+    if (cached) {
+        const manifest = manifestServer(base.command);
+        return {
+            config: {
+                ...base,
+                command: cached,
+                args: manifest?.launchArgs ?? base.args,
+            },
+            source: 'managed-cache',
+        };
+    }
+    return { config: base, source: 'unavailable' };
+}
+function withBundledJsServer(config) {
+    // 1) Command-keyed: native command name matches the bundled package; keep
+    //    the native args.
+    const byCommand = BUNDLED_JS_SERVERS[path.basename(config.command)];
+    if (byCommand) {
+        const cliPath = resolveBundledCli(byCommand);
+        if (cliPath) {
+            return {
+                ...config,
+                command: process.execPath,
+                args: [cliPath, ...(config.args ?? [])],
+            };
+        }
+    }
+    // 2) Language-keyed: a different bundled server than the native default
+    //    (e.g. pyright for Python); use the bundled server's own launch args.
+    const byLanguage = config.languageId
+        ? BUNDLED_BY_LANGUAGE[config.languageId]
+        : undefined;
+    if (byLanguage) {
+        const cliPath = resolveBundledCli(byLanguage.cli);
+        if (cliPath) {
+            return {
+                ...config,
+                command: process.execPath,
+                args: [cliPath, ...byLanguage.args],
+            };
+        }
+    }
+    return null;
+}
+function resolveBundledCli(modulePath) {
+    try {
+        return requireFromPackage.resolve(modulePath);
+    }
+    catch {
+        return null;
+    }
 }

package/dist/lsp/ideContext.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Detects which host the octocode engine is running under, so LSP server
+ * resolution can prefer the editor's own servers when hosted in an IDE and
+ * fall back to standalone discovery in a plain terminal.
+ *
+ * Signals are environment variables the editor sets deliberately (see
+ * jonschlinkert/detect-terminal and VS Code's `terminalEnvironment.ts`).
+ * `TERM_PROGRAM` is the primary signal; the vendor `*_PID` / IPC-handle vars
+ * corroborate it. `TERM` is intentionally ignored — it is terminfo, not an
+ * editor identity.
+ */
+export type IdeHost = 'vscode' | 'cursor' | 'windsurf' | 'zed' | 'jetbrains' | 'terminal' | 'unknown';
+export interface IdeContext {
+    host: IdeHost;
+    /** True when running inside an editor that ships language servers we could reuse. */
+    isIde: boolean;
+}
+export declare function detectIdeContext(env?: NodeJS.ProcessEnv): IdeContext;

package/dist/lsp/ideContext.js

@@ -0,0 +1,29 @@
+function vscodeFork(env) {
+    // Cursor / Windsurf are VS Code forks and also report TERM_PROGRAM=vscode;
+    // disambiguate on their vendor markers before defaulting to upstream VS Code.
+    if (Object.keys(env).some(key => key.startsWith('CURSOR')))
+        return 'cursor';
+    if ('WINDSURF_PID' in env ||
+        Object.keys(env).some(key => key.startsWith('WINDSURF') || key.startsWith('CODEIUM'))) {
+        return 'windsurf';
+    }
+    return 'vscode';
+}
+export function detectIdeContext(env = process.env) {
+    const termProgram = (env.TERM_PROGRAM ?? '').toLowerCase();
+    if (termProgram === 'vscode' || 'VSCODE_PID' in env || 'VSCODE_GIT_IPC_HANDLE' in env) {
+        const host = vscodeFork(env);
+        return { host, isIde: true };
+    }
+    if (termProgram === 'zed' || 'ZED_TERM' in env) {
+        return { host: 'zed', isIde: true };
+    }
+    // JetBrains does not set TERM_PROGRAM; its tell is the JediTerm emulator.
+    if (env.TERMINAL_EMULATOR === 'JetBrains-JediTerm' || 'IDEA_INITIAL_DIRECTORY' in env) {
+        return { host: 'jetbrains', isIde: true };
+    }
+    if (termProgram === 'apple_terminal' || termProgram === 'iterm.app' || 'WT_SESSION' in env) {
+        return { host: 'terminal', isIde: false };
+    }
+    return { host: 'unknown', isIde: false };
+}

package/dist/lsp/index.d.ts

@@ -1,7 +1,12 @@
 export { LSPClient } from './client.js';
-export { detectLanguageId, getLanguageServerForFile } from './config.js';
-export { acquirePooledClient, getLspStatus, isLanguageServerAvailable, LSP_UNAVAILABLE_HINT, pooledClientCount, releaseAllPooledClients, releasePooledClientForFile, type LspStatusInput, type LspStatusResult, } from './manager.js';
+export { detectLanguageId, getLanguageServerForFile, isCommandOnPath, resolveServerForFile, BUNDLED_SERVER_NAMES, type ServerResolution, } from './config.js';
+export { detectPlatformId, isMuslLinux, type PlatformId } from './platform.js';
+export { detectIdeContext, type IdeContext, type IdeHost, } from './ideContext.js';
+export { clearDiscoveryCache, discoverServer, discoverServerBatch, type DiscoveredServer, type DiscoverySource, } from './serverDiscovery.js';
+export { cachedServerBinPath, isAutoDownloadable, listManifestServers, managedCacheRoot, manifestInstallHint, manifestServer, provisionMode, resolveCachedServer, type ArchiveKind, type ManifestAsset, type ManifestServer, type ProvisionMode, } from './serverManifest.js';
+export { provisionServer, uninstallServer, type ProvisionResult, } from './serverProvisioner.js';
+export { acquirePooledClient, getLspStatus, isLanguageServerAvailable, LSP_UNAVAILABLE_HINT, pooledClientCount, releaseAllPooledClients, releasePooledClientForFile, unavailableHintFor, TOOLCHAIN_SERVERS, type ToolchainServer, type LspStatusInput, type LspStatusResult, } from './manager.js';
 export { resolveImportAliasDefinitions, SymbolResolver, type ImportAliasDefinitionInput, } from './resolver.js';
 export { safeReadFile, validateLSPServerPath } from './validation.js';
 export { resolveWorkspaceRootForFile } from './workspaceRoot.js';
-export type { CallHierarchyItem, CodeSnippet, ExactPosition, FuzzyPosition, IncomingCall, InitializationOptions, LanguageServerCommand, LanguageServerConfig, LSPPaginationInfo, LSPRange, OutgoingCall, ReferenceLocation, ReferencesByFile, SymbolKind, UserLanguageServerConfig, } from './types.js';
+export type { CallHierarchyItem, CodeSnippet, ExactPosition, FuzzyPosition, IncomingCall, InitializationOptions, LanguageServerCommand, LanguageServerConfig, LSPPaginationInfo, LSPRange, LspServerSource, OutgoingCall, ReferenceLocation, ReferencesByFile, SymbolKind, UserLanguageServerConfig, } from './types.js';

package/dist/lsp/index.js

@@ -1,6 +1,11 @@
 export { LSPClient } from './client.js';
-export { detectLanguageId, getLanguageServerForFile } from './config.js';
-export { acquirePooledClient, getLspStatus, isLanguageServerAvailable, LSP_UNAVAILABLE_HINT, pooledClientCount, releaseAllPooledClients, releasePooledClientForFile, } from './manager.js';
+export { detectLanguageId, getLanguageServerForFile, isCommandOnPath, resolveServerForFile, BUNDLED_SERVER_NAMES, } from './config.js';
+export { detectPlatformId, isMuslLinux } from './platform.js';
+export { detectIdeContext, } from './ideContext.js';
+export { clearDiscoveryCache, discoverServer, discoverServerBatch, } from './serverDiscovery.js';
+export { cachedServerBinPath, isAutoDownloadable, listManifestServers, managedCacheRoot, manifestInstallHint, manifestServer, provisionMode, resolveCachedServer, } from './serverManifest.js';
+export { provisionServer, uninstallServer, } from './serverProvisioner.js';
+export { acquirePooledClient, getLspStatus, isLanguageServerAvailable, LSP_UNAVAILABLE_HINT, pooledClientCount, releaseAllPooledClients, releasePooledClientForFile, unavailableHintFor, TOOLCHAIN_SERVERS, } from './manager.js';
 export { resolveImportAliasDefinitions, SymbolResolver, } from './resolver.js';
 export { safeReadFile, validateLSPServerPath } from './validation.js';
 export { resolveWorkspaceRootForFile } from './workspaceRoot.js';

package/dist/lsp/manager.d.ts

@@ -1,7 +1,16 @@
 import { LSPClient } from './client.js';
 import { type PoolKey } from './lspClientPool.js';
+import type { LspServerSource } from './types.js';
 export declare function isLanguageServerAvailable(filePath: string, workspaceRoot?: string): Promise<boolean>;
 export declare const LSP_UNAVAILABLE_HINT = "No language server is available for this file, so no semantic results were returned. Install a matching language server or set the relevant OCTOCODE_*_SERVER_PATH environment variable. For a text-based search meanwhile, use localSearchCode.";
+export interface ToolchainServer {
+    server: string;
+    languageId: string;
+    hint: string;
+}
+export declare const TOOLCHAIN_SERVERS: readonly ToolchainServer[];
+/** Honest, actionable guidance for a file whose server did not resolve. */
+export declare function unavailableHintFor(languageId?: string, command?: string): string;
 export declare function acquirePooledClient(workspaceRoot: string, filePath: string): Promise<LSPClient | null>;
 export declare function releaseAllPooledClients(): Promise<void>;
 export declare function releasePooledClientForFile(workspaceRoot: string, filePath: string): Promise<boolean>;
@@ -17,6 +26,8 @@ export type LspStatusResult = {
     workspaceRoot?: string;
     languageId?: string;
     serverAvailable?: boolean;
+    /** Which layer of the resolution ladder provided the server (or `unavailable`). */
+    serverSource?: LspServerSource;
     hints: string[];
 };
 export declare function getLspStatus(input?: LspStatusInput): Promise<LspStatusResult>;

package/dist/lsp/manager.js

@@ -1,16 +1,71 @@
 import { LSPClient } from './client.js';
-import { getLanguageServerForFile } from './config.js';
+import { getLanguageServerForFile, resolveServerForFile, } from './config.js';
 import { LspClientPool } from './lspClientPool.js';
-import { nativeBinding } from './native.js';
+import { manifestInstallHint } from './serverManifest.js';
 import { resolveWorkspaceRootForFile } from './workspaceRoot.js';
 export async function isLanguageServerAvailable(filePath, workspaceRoot) {
-    const serverConfig = await getLanguageServerForFile(filePath, workspaceRoot ?? process.cwd());
-    if (!serverConfig)
-        return false;
-    return nativeBinding.isCommandAvailable(serverConfig.command);
+    const resolution = await resolveServerForFile(filePath, workspaceRoot ?? process.cwd());
+    return resolution != null && resolution.source !== 'unavailable';
 }
 export const LSP_UNAVAILABLE_HINT = 'No language server is available for this file, so no semantic results were returned. Install a matching language server or set the relevant OCTOCODE_*_SERVER_PATH environment variable. For a text-based search meanwhile, use localSearchCode.';
+export const TOOLCHAIN_SERVERS = [
+    {
+        server: 'gopls',
+        languageId: 'go',
+        hint: 'Install Go, then `go install golang.org/x/tools/gopls@latest` (gopls needs the Go toolchain at runtime).',
+    },
+    {
+        server: 'jdtls',
+        languageId: 'java',
+        hint: 'Install a JDK/JRE 21+ and Eclipse JDT LS (https://download.eclipse.org/jdtls/).',
+    },
+    {
+        server: 'sourcekit-lsp',
+        languageId: 'swift',
+        hint: 'Install Xcode or Xcode Command Line Tools (`xcode-select --install`); sourcekit-lsp ships at /usr/bin/sourcekit-lsp on macOS.',
+    },
+    {
+        server: 'csharp-ls',
+        languageId: 'csharp',
+        hint: 'Install .NET SDK, then `dotnet tool install -g csharp-ls` (adds csharp-ls to ~/.dotnet/tools).',
+    },
+];
+const TOOLCHAIN_INSTALL_HINTS = Object.fromEntries(TOOLCHAIN_SERVERS.map(t => [t.languageId, t.hint]));
+/** Honest, actionable guidance for a file whose server did not resolve. */
+export function unavailableHintFor(languageId, command) {
+    const toolchain = languageId ? TOOLCHAIN_INSTALL_HINTS[languageId] : undefined;
+    if (toolchain)
+        return toolchain;
+    const manifest = command ? manifestInstallHint(command) : null;
+    if (manifest)
+        return manifest;
+    return LSP_UNAVAILABLE_HINT;
+}
 const POOL_IDLE_TIMEOUT_MS = parseInt(process.env.OCTOCODE_LSP_POOL_IDLE_MS || '60000', 10);
+// Languages whose servers emit $/progress notifications and need waitForReady.
+// TypeScript, Python, C/C++, and data-format servers (JSON/YAML/HTML/CSS)
+// answer queries immediately after the LSP handshake — skipping waitForReady
+// avoids burning the 2-second SETTLE_MS window for them.
+const PROGRESS_LANGUAGES = new Set([
+    'go',
+    'rust',
+    'java',
+    'csharp',
+    'swift',
+]);
+// Per-language upper bound for $/progress drain (ms).
+// These are ceilings — waitForReady returns as soon as the server goes idle.
+const SERVER_READY_TIMEOUT_MS = {
+    go: 15_000,
+    rust: 60_000,
+    java: 120_000,
+    csharp: 30_000,
+    swift: 30_000,
+};
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+function readyTimeoutForLanguage(languageId) {
+    return SERVER_READY_TIMEOUT_MS[languageId] ?? DEFAULT_READY_TIMEOUT_MS;
+}
 const sharedPool = new LspClientPool({
     idleTimeoutMs: POOL_IDLE_TIMEOUT_MS,
     factory: async (key) => {
@@ -20,6 +75,13 @@ const sharedPool = new LspClientPool({
         const client = new LSPClient(serverConfig);
         try {
             await client.start();
+            // Wait for servers that do workspace-wide indexing before answering
+            // semantic queries. Servers that don't emit $/progress (TypeScript,
+            // Python, clangd) answer immediately after the handshake — we skip
+            // waitForReady for them to avoid the 2-second SETTLE_MS penalty.
+            if (PROGRESS_LANGUAGES.has(key.languageId)) {
+                await client.waitForReady(readyTimeoutForLanguage(key.languageId));
+            }
             return client;
         }
         catch {
@@ -59,20 +121,20 @@ export async function getLspStatus(input = {}) {
         };
     }
     const workspaceRoot = input.workspaceRoot ?? (await resolveWorkspaceRootForFile(input.filePath));
-    const serverConfig = await getLanguageServerForFile(input.filePath, workspaceRoot);
-    const languageId = serverConfig?.languageId;
-    const serverAvailable = serverConfig
-        ? nativeBinding.isCommandAvailable(serverConfig.command)
-        : false;
+    const resolution = await resolveServerForFile(input.filePath, workspaceRoot);
+    const languageId = resolution?.config.languageId;
+    const serverSource = resolution?.source ?? 'unavailable';
+    const serverAvailable = serverSource !== 'unavailable';
     return {
         ...base,
         filePath: input.filePath,
         workspaceRoot,
         languageId,
         serverAvailable,
+        serverSource,
         hints: serverAvailable
-            ? ['Language server appears available for this file.']
-            : [LSP_UNAVAILABLE_HINT],
+            ? [`Language server resolved for this file (source: ${serverSource}).`]
+            : [unavailableHintFor(languageId, resolution?.config.command)],
     };
 }
 export function pooledClientCount() {

package/dist/lsp/native.d.ts

@@ -15,6 +15,11 @@ export type NativeLspClientBinding = {
     prepareCallHierarchy(filePath: string, line: number, character: number): Promise<unknown>;
     incomingCalls(item: unknown): Promise<unknown>;
     outgoingCalls(item: unknown): Promise<unknown>;
+    workspaceSymbol(query: string): Promise<unknown>;
+    prepareTypeHierarchy(filePath: string, line: number, character: number): Promise<unknown>;
+    typeHierarchySupertypes(item: unknown): Promise<unknown>;
+    typeHierarchySubtypes(item: unknown): Promise<unknown>;
+    getDiagnostics(filePath: string): Promise<unknown>;
 };
 type NativeBinding = {
     NativeLspClient: new (config: unknown) => NativeLspClientBinding;

package/dist/lsp/platform.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical `{os}-{arch}[-musl]` platform identifier, matching the npm
+ * native-addon convention (the same keys esbuild / swc / the engine's own
+ * optionalDependencies use): `darwin-arm64`, `darwin-x64`, `linux-x64`,
+ * `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`,
+ * `win32-arm64`. This is the key the server download manifest is keyed on.
+ */
+export type PlatformId = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'linux-arm64' | 'linux-x64-musl' | 'linux-arm64-musl' | 'win32-x64' | 'win32-arm64';
+/** True when the current Linux runtime links musl libc (Alpine etc.). */
+export declare function isMuslLinux(): boolean;
+/** Resolve (and cache) the canonical platform id for this machine. */
+export declare function detectPlatformId(): PlatformId;
+/**
+ * Executable file-name candidates for a bare command on this OS. On Windows a
+ * server may exist only as `gopls.exe` / `pyright.cmd`, so we expand against
+ * `PATHEXT`; on POSIX the bare name is the only candidate.
+ */
+export declare function executableNames(command: string): string[];
+/** First existing path among `dir/<name>` for every executable-name candidate. */
+export declare function firstExecutableIn(dir: string, command: string, join: (dir: string, name: string) => string): string | null;

package/dist/lsp/platform.js

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync } from 'node:fs';
+let cachedPlatformId;
+/** True when the current Linux runtime links musl libc (Alpine etc.). */
+export function isMuslLinux() {
+    if (process.platform !== 'linux')
+        return false;
+    // 1) Fastest, in-process: glibc runtime version is absent on musl.
+    try {
+        const report = process.report?.getReport();
+        if (report?.header) {
+            return report.header.glibcVersionRuntime == null;
+        }
+    }
+    catch {
+        // process.report unavailable — fall through to the loader probe.
+    }
+    // 2) Dynamic-loader probe: musl ships `/lib/ld-musl-*.so.1`.
+    try {
+        return readdirSync('/lib').some(name => name.startsWith('ld-musl-'));
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve (and cache) the canonical platform id for this machine. */
+export function detectPlatformId() {
+    if (cachedPlatformId)
+        return cachedPlatformId;
+    const arch = process.arch === 'x64' ? 'x64' : 'arm64';
+    if (process.platform === 'darwin') {
+        cachedPlatformId = `darwin-${arch}`;
+    }
+    else if (process.platform === 'win32') {
+        cachedPlatformId = `win32-${arch}`;
+    }
+    else {
+        const suffix = isMuslLinux() ? '-musl' : '';
+        cachedPlatformId = `linux-${arch}${suffix}`;
+    }
+    return cachedPlatformId;
+}
+/**
+ * Executable file-name candidates for a bare command on this OS. On Windows a
+ * server may exist only as `gopls.exe` / `pyright.cmd`, so we expand against
+ * `PATHEXT`; on POSIX the bare name is the only candidate.
+ */
+export function executableNames(command) {
+    if (process.platform !== 'win32')
+        return [command];
+    const pathext = (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM')
+        .split(';')
+        .map(ext => ext.trim().toLowerCase())
+        .filter(Boolean);
+    return [command, ...pathext.map(ext => `${command}${ext}`)];
+}
+/** First existing path among `dir/<name>` for every executable-name candidate. */
+export function firstExecutableIn(dir, command, join) {
+    for (const name of executableNames(command)) {
+        const candidate = join(dir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}