@octocodeai/octocode-engine 16.6.0 → 16.7.0

package/dist/lsp/client.d.ts

@@ -1,21 +1,31 @@
-import type { CallHierarchyItem, CodeSnippet, ExactPosition, IncomingCall, LanguageServerConfig, OutgoingCall } from './types.js';
+import type { CallHierarchyItem, CodeSnippet, ExactPosition, IncomingCall, LanguageServerConfig, LspReadiness, OutgoingCall } from './types.js';
 export declare class LSPClient {
     private readonly nativeClient;
+    private readonly command;
     private initialized;
+    private lastReadiness;
     constructor(config: LanguageServerConfig);
     start(): Promise<void>;
     stop(): Promise<void>;
-    waitForReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Wait for the server to finish post-`initialized` indexing and record the
+     * readiness signal. Runtime tolerance: until the native addon is rebuilt with
+     * the readiness return, the old binding resolves to `undefined` — treat that
+     * as the conservative `settledFallback` (we cannot confirm indexing finished).
+     */
+    waitForReady(timeoutMs?: number): Promise<LspReadiness>;
+    /**
+     * The readiness recorded by the most recent `waitForReady`, or `undefined`
+     * if it was never called (e.g. servers that answer immediately and skip the
+     * readiness wait). A zero-results semantic query on a client whose readiness
+     * is not `progressIdle` may be "not indexed yet" rather than a true absence.
+     */
+    getReadiness(): LspReadiness | undefined;
     gotoDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
-    getDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
     findReferences(filePath: string, position: ExactPosition, includeDeclaration?: boolean, content?: string): Promise<CodeSnippet[]>;
-    getHover(filePath: string, position: ExactPosition, content?: string): Promise<unknown>;
     hover(filePath: string, position: ExactPosition, content?: string): Promise<unknown>;
-    getTypeDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
     typeDefinition(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
-    getImplementation(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
     implementation(filePath: string, position: ExactPosition, content?: string): Promise<CodeSnippet[]>;
-    getDocumentSymbols(filePath: string, content?: string): Promise<unknown>;
     documentSymbols(filePath: string, content?: string): Promise<unknown>;
     prepareCallHierarchy(filePath: string, position: ExactPosition, content?: string): Promise<CallHierarchyItem[]>;
     getIncomingCalls(item: CallHierarchyItem): Promise<IncomingCall[]>;
@@ -25,9 +35,8 @@ export declare class LSPClient {
     typeHierarchySupertypes(item: unknown): Promise<unknown[]>;
     typeHierarchySubtypes(item: unknown): Promise<unknown[]>;
     getDiagnostics(filePath: string, content?: string): Promise<unknown>;
-    hasCapability(_capability: string): boolean;
+    hasCapability(capability: string): boolean;
     getRecentStderr(): string[];
     openDocument(filePath: string, content?: string): Promise<void>;
-    ensureDocumentSynced(filePath: string, content?: string): Promise<void>;
     closeDocument(filePath: string): Promise<void>;
 }

package/dist/lsp/client.js

@@ -1,9 +1,13 @@
 import { promises as fs } from 'node:fs';
 import { nativeBinding } from './native.js';
+import { validateLSPServerPath } from './validation.js';
 export class LSPClient {
     nativeClient;
+    command;
     initialized = false;
+    lastReadiness;
     constructor(config) {
+        this.command = config.command;
         this.nativeClient = new nativeBinding.NativeLspClient({
             command: config.command,
             args: config.args,
@@ -14,6 +18,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;
     }
@@ -21,13 +32,27 @@ export class LSPClient {
         await this.nativeClient.stop();
         this.initialized = false;
     }
+    /**
+     * Wait for the server to finish post-`initialized` indexing and record the
+     * readiness signal. Runtime tolerance: until the native addon is rebuilt with
+     * the readiness return, the old binding resolves to `undefined` — treat that
+     * as the conservative `settledFallback` (we cannot confirm indexing finished).
+     */
     async waitForReady(timeoutMs = 45_000) {
-        await this.nativeClient.waitForReady(timeoutMs);
+        const readiness = await this.nativeClient.waitForReady(timeoutMs);
+        this.lastReadiness = readiness ?? 'settledFallback';
+        return this.lastReadiness;
+    }
+    /**
+     * The readiness recorded by the most recent `waitForReady`, or `undefined`
+     * if it was never called (e.g. servers that answer immediately and skip the
+     * readiness wait). A zero-results semantic query on a client whose readiness
+     * is not `progressIdle` may be "not indexed yet" rather than a true absence.
+     */
+    getReadiness() {
+        return this.lastReadiness;
     }
     async gotoDefinition(filePath, position, content) {
-        return this.getDefinition(filePath, position, content);
-    }
-    async getDefinition(filePath, position, content) {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getDefinition(filePath, position.line, position.character));
     }
@@ -35,34 +60,22 @@ export class LSPClient {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getReferences(filePath, position.line, position.character, includeDeclaration));
     }
-    async getHover(filePath, position, content) {
+    async hover(filePath, position, content) {
         await this.openDocument(filePath, content);
         return this.nativeClient.getHover(filePath, position.line, position.character);
     }
-    async hover(filePath, position, content) {
-        return this.getHover(filePath, position, content);
-    }
-    async getTypeDefinition(filePath, position, content) {
+    async typeDefinition(filePath, position, content) {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getTypeDefinition(filePath, position.line, position.character));
     }
-    async typeDefinition(filePath, position, content) {
-        return this.getTypeDefinition(filePath, position, content);
-    }
-    async getImplementation(filePath, position, content) {
+    async implementation(filePath, position, content) {
         await this.openDocument(filePath, content);
         return (await this.nativeClient.getImplementation(filePath, position.line, position.character));
     }
-    async implementation(filePath, position, content) {
-        return this.getImplementation(filePath, position, content);
-    }
-    async getDocumentSymbols(filePath, content) {
+    async documentSymbols(filePath, content) {
         await this.openDocument(filePath, content);
         return this.nativeClient.getDocumentSymbols(filePath);
     }
-    async documentSymbols(filePath, content) {
-        return this.getDocumentSymbols(filePath, content);
-    }
     async prepareCallHierarchy(filePath, position, content) {
         await this.openDocument(filePath, content);
         const result = await this.nativeClient.prepareCallHierarchy(filePath, position.line, position.character);
@@ -97,17 +110,14 @@ export class LSPClient {
         await this.openDocument(filePath, content);
         return this.nativeClient.getDiagnostics(filePath);
     }
-    hasCapability(_capability) {
+    hasCapability(capability) {
         return (this.initialized &&
-            (this.nativeClient.hasCapability?.(_capability) ?? true));
+            (this.nativeClient.hasCapability?.(capability) ?? true));
     }
     getRecentStderr() {
         return this.nativeClient.getRecentStderr?.() ?? [];
     }
     async openDocument(filePath, content) {
-        await this.ensureDocumentSynced(filePath, content ?? (await fs.readFile(filePath, 'utf8')));
-    }
-    async ensureDocumentSynced(filePath, content) {
         await this.nativeClient.openDocument(filePath, content ?? (await fs.readFile(filePath, 'utf8')));
     }
     async closeDocument(filePath) {

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 = path.basename(config.command) === config.command && 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/lspClientPool.d.ts

@@ -21,7 +21,9 @@ export declare class LspClientPool<T extends PooledClient> {
     clearAll(): Promise<void>;
     size(): number;
     keys(): PoolKey[];
+    has(key: PoolKey): boolean;
     private resetIdleTimer;
     private startIdleTimer;
 }
+export declare function serializeKey(key: PoolKey): string;
 export {};

package/dist/lsp/lspClientPool.js

@@ -53,6 +53,10 @@ export class LspClientPool {
     keys() {
         return [...this.entries.values()].map(entry => entry.key);
     }
+    has(key) {
+        const k = serializeKey(key);
+        return this.entries.has(k) || this.inflight.has(k);
+    }
     resetIdleTimer(k) {
         const entry = this.entries.get(k);
         if (!entry)
@@ -68,13 +72,14 @@ export class LspClientPool {
             this.entries.delete(k);
             void safeStop(entry.client);
         }, this.options.idleTimeoutMs);
-        if (typeof timer === 'object' && 'unref' in timer) {
-            timer.unref();
-        }
+        // This package is Node-only (napi-rs). The timer is always a NodeJS.Timeout
+        // with an unref() method; calling it keeps the idle timer from preventing
+        // a clean process exit when no real work is in flight.
+        timer.unref?.();
         return timer;
     }
 }
-function serializeKey(key) {
+export function serializeKey(key) {
     return `${key.serverId ?? key.languageId}\u0000${key.workspaceRoot}`;
 }
 async function safeStop(client) {

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>;