oh-my-opencode 5.0.0-beta.21 → 5.0.0-beta.23

package/packages/lsp-core/src/lsp/client-wrapper.ts

@@ -17,6 +17,7 @@ import {
 } from "./errors.js";
 import { getLspManager, type LspManager } from "./manager.js";
 import { findWorkspaceRootOutsideContext } from "./outside-context-workspace.js";
+import { LSP_LOCAL_INSTALL_HINTS } from "./server-definitions.js";
 import { loadInstallDecision } from "./server-install-state.js";
 import { findServerForExtension } from "./server-resolution.js";
 import type { ServerLookupResult } from "./types.js";
@@ -138,6 +139,26 @@ export function formatServerLookupError(result: Exclude<ServerLookupResult, { st
 	].join("\n");
 }
 
+/**
+ * Builds the install guidance, offering the repo-local install first.
+ *
+ * A repo-local install is resolvable without touching the global environment, so it is the
+ * recommended route whenever the server ships as a project dependency.
+ */
+function formatInstallOptions(serverId: string, installHint: string): string[] {
+	const localHint = LSP_LOCAL_INSTALL_HINTS[serverId];
+	if (localHint === undefined) {
+		return ["To install, run:", `  ${installHint}`];
+	}
+	return [
+		"To install in THIS repository (preferred — no global install needed):",
+		`  ${localHint}`,
+		"",
+		"Or install it globally:",
+		`  ${installHint}`,
+	];
+}
+
 function formatNotInstalled(result: Extract<ServerLookupResult, { status: "not_installed" }>): string {
 	const { server, installHint } = result;
 	const extensions = server.extensions.join(", ");
@@ -154,20 +175,20 @@ function formatNotInstalled(result: Extract<ServerLookupResult, { status: "not_i
 		`Command not found: ${server.command[0]}`,
 		"",
 	];
+	const installOptions = formatInstallOptions(server.id, installHint);
 
 	if (decision === "allowed") {
 		return [
 			...header,
 			"The user has pre-authorized LSP installation. Run the install command, then retry this tool:",
-			`  ${installHint}`,
+			...installOptions.slice(1),
 		].join("\n");
 	}
 
 	if (!context.capabilities.installDecisionTool) {
 		return [
 			...header,
-			"To install, run:",
-			`  ${installHint}`,
+			...installOptions,
 			"",
 			"ACTION REQUIRED — ASK THE USER whether to install this LSP server.",
 			"Install-decision recording is unavailable in this harness; proceed without LSP if the user declines.",
@@ -176,8 +197,7 @@ function formatNotInstalled(result: Extract<ServerLookupResult, { status: "not_i
 
 	return [
 		...header,
-		"To install, run:",
-		`  ${installHint}`,
+		...installOptions,
 		"",
 		"ACTION REQUIRED — ASK THE USER whether to install this LSP server.",
 		"- If the user agrees: run the install command above, then retry this tool.",

package/packages/lsp-core/src/lsp/client.ts

@@ -6,6 +6,7 @@ import type { LspClientTimeoutOptions } from "./transport.js";
 import type {
 	Diagnostic,
 	DocumentSymbol,
+	FormattingOptions,
 	Location,
 	LocationLink,
 	PrepareRenameDefaultBehavior,
@@ -13,6 +14,7 @@ import type {
 	Range,
 	ResolvedServer,
 	SymbolInfo,
+	TextEdit,
 	WorkspaceEdit,
 } from "./types.js";
 import { LspRequestTimeoutError } from "./errors.js";
@@ -133,6 +135,30 @@ export class LspClient extends LspClientConnection {
 		}, options);
 	}
 
+	/**
+	 * Requests whole-document formatting edits, returning null when the server never advertised the
+	 * capability so callers can report unavailability instead of surfacing a method-not-found error.
+	 */
+	async formatDocument(
+		filePath: string,
+		options: FormattingOptions,
+		signal?: AbortSignal,
+	): Promise<TextEdit[] | null> {
+		if (!this.isDocumentFormattingSupported()) return null;
+		const absPath = this.resolveWorkspacePath(filePath);
+		await this.openFile(absPath);
+		const requestOptions = signal === undefined ? {} : { signal };
+		const edits = await this.sendRequest<TextEdit[] | null>(
+			"textDocument/formatting",
+			{
+				textDocument: { uri: pathToFileURL(absPath).href },
+				options,
+			},
+			requestOptions,
+		);
+		return edits ?? [];
+	}
+
 	async workspaceSymbols(query: string, signal?: AbortSignal): Promise<SymbolInfo[]> {
 		const options = signal === undefined ? {} : { signal };
 		return this.sendRequest<SymbolInfo[]>("workspace/symbol", { query }, options);

package/packages/lsp-core/src/lsp/connection.ts

@@ -4,6 +4,7 @@ import { LspClientTransport } from "./transport.js";
 
 interface InitializeCapabilities {
 	readonly diagnosticProvider?: unknown;
+	readonly documentFormattingProvider?: unknown;
 }
 
 function supportsDiagnosticPull(capabilities: InitializeCapabilities | undefined): boolean {
@@ -11,6 +12,19 @@ function supportsDiagnosticPull(capabilities: InitializeCapabilities | undefined
 	return Object.hasOwn(capabilities, "diagnosticProvider");
 }
 
+/**
+ * Reads the whole-document formatting capability the server advertised at initialize time.
+ *
+ * The provider is either a boolean or an options object, and an explicit `false` means the
+ * server refuses the request, so both shapes are checked instead of mere key presence.
+ */
+function supportsDocumentFormatting(capabilities: InitializeCapabilities | undefined): boolean {
+	if (capabilities === undefined) return false;
+	const provider = capabilities.documentFormattingProvider;
+	if (provider === undefined || provider === null || provider === false) return false;
+	return provider === true || typeof provider === "object";
+}
+
 export class LspClientConnection extends LspClientTransport {
 	async initialize(): Promise<void> {
 		const rootUri = pathToFileURL(this.root).href;
@@ -28,6 +42,7 @@ export class LspClientConnection extends LspClientTransport {
 						references: {},
 						documentSymbol: { hierarchicalDocumentSymbolSupport: true },
 						publishDiagnostics: {},
+						formatting: { dynamicRegistration: false },
 						rename: {
 							prepareSupport: true,
 							prepareSupportDefaultBehavior: 1,
@@ -71,6 +86,7 @@ export class LspClientConnection extends LspClientTransport {
 			{ timeoutMs: this.initializeTimeoutMs },
 		);
 		this.setDiagnosticPullSupported(supportsDiagnosticPull(result?.capabilities));
+		this.setDocumentFormattingSupported(supportsDocumentFormatting(result?.capabilities));
 		await this.sendNotification("initialized", {});
 		await this.sendNotification("workspace/didChangeConfiguration", {
 			settings: { json: { validate: { enable: true } } },

package/packages/lsp-core/src/lsp/constants.ts

@@ -6,6 +6,7 @@ export const DEFAULT_MAX_DIRECTORY_FILES = 50;
 export const REQUEST_TIMEOUT_MS = 15_000;
 export const INIT_TIMEOUT_MS = 60_000;
 export const IDLE_TIMEOUT_MS = 5 * 60_000;
+export const MAX_RESIDENT_CLIENTS = 6;
 export const REAPER_INTERVAL_MS = 60_000;
 export const STOP_HARD_KILL_TIMEOUT_MS = 5_000;
 export const STOP_SIGKILL_GRACE_MS = 1_000;

package/packages/lsp-core/src/lsp/format-document.test.ts

@@ -0,0 +1,143 @@
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "bun:test";
+
+import type { LspClient } from "./client.js";
+import { formatDocumentWithClient } from "./format-document.js";
+import type { TextEdit } from "./types.js";
+
+const workspaces: string[] = [];
+
+afterEach(() => {
+	for (const workspace of workspaces.splice(0)) rmSync(workspace, { recursive: true, force: true });
+});
+
+function workspaceWith(fileName: string, content: string): { readonly root: string; readonly filePath: string } {
+	const root = mkdtempSync(join(tmpdir(), "lsp-format-"));
+	workspaces.push(root);
+	const filePath = join(root, fileName);
+	writeFileSync(filePath, content, "utf-8");
+	return { root, filePath };
+}
+
+function stubClient(edits: TextEdit[] | null): LspClient {
+	return {
+		async formatDocument() {
+			return edits;
+		},
+		async openFile() {},
+	} as Pick<LspClient, "formatDocument" | "openFile"> as LspClient;
+}
+
+describe("formatDocumentWithClient", () => {
+	it("#given a server returning text edits #when the document is formatted #then the file is rewritten and line deltas are reported", async () => {
+		// given
+		const { filePath } = workspaceWith("sample.ts", "const a=1\nconst b   =2\nconst c=3\n");
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 1, character: 12 } }, newText: "const a = 1;\nconst b = 2;" },
+		];
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(result.status).toBe("formatted");
+		expect(readFileSync(filePath, "utf-8")).toBe("const a = 1;\nconst b = 2;\nconst c=3\n");
+		expect(result).toMatchObject({ status: "formatted", linesAdded: 2, linesRemoved: 2 });
+	});
+
+	it("#given a server returning an edit that adds lines #when the document is formatted #then the added and removed line counts differ", async () => {
+		// given
+		const { filePath } = workspaceWith("sample.ts", "const a=1;const b=2\n");
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 19 } }, newText: "const a = 1;\nconst b = 2;" },
+		];
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(result).toMatchObject({ status: "formatted", linesAdded: 2, linesRemoved: 1 });
+		expect(readFileSync(filePath, "utf-8")).toBe("const a = 1;\nconst b = 2;\n");
+	});
+
+	it("#given a server that does not advertise document formatting #when the document is formatted #then the result is unavailable and the file bytes are untouched", async () => {
+		// given
+		const original = "const a=1\n";
+		const { filePath } = workspaceWith("sample.ts", original);
+		const before = statSync(filePath);
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(null), filePath);
+
+		// then
+		expect(result).toEqual({ status: "unavailable", reason: "capability_not_advertised" });
+		expect(readFileSync(filePath)).toEqual(Buffer.from(original));
+		expect(statSync(filePath).mtimeMs).toBe(before.mtimeMs);
+	});
+
+	it("#given a server returning no edits #when the document is formatted #then the result is unchanged and the file bytes are untouched", async () => {
+		// given
+		const original = "const a = 1;\n";
+		const { filePath } = workspaceWith("sample.ts", original);
+
+		// when
+		const result = await formatDocumentWithClient(stubClient([]), filePath);
+
+		// then
+		expect(result).toEqual({ status: "unchanged", linesAdded: 0, linesRemoved: 0 });
+		expect(readFileSync(filePath)).toEqual(Buffer.from(original));
+	});
+
+	it("#given edits that reproduce the current bytes #when the document is formatted #then the result is unchanged", async () => {
+		// given
+		const original = "const a = 1;\n";
+		const { filePath } = workspaceWith("sample.ts", original);
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 12 } }, newText: "const a = 1;" },
+		];
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(result.status).toBe("unchanged");
+		expect(readFileSync(filePath, "utf-8")).toBe(original);
+	});
+
+	it("#given the file shrinks after the server computed its edits #when the edits are applied #then the stale edit is rejected instead of corrupting the file", async () => {
+		// given
+		const { filePath } = workspaceWith("sample.ts", "const a=1\nconst b=2\n");
+		const staleEdits: TextEdit[] = [
+			{ range: { start: { line: 1, character: 0 }, end: { line: 1, character: 9 } }, newText: "const b = 2;" },
+		];
+		const racingClient = {
+			async formatDocument() {
+				writeFileSync(filePath, "short\n", "utf-8");
+				return staleEdits;
+			},
+			async openFile() {},
+		} as Pick<LspClient, "formatDocument" | "openFile"> as LspClient;
+
+		// when / then
+		await expect(formatDocumentWithClient(racingClient, filePath)).rejects.toThrow(/outside line/);
+		expect(readFileSync(filePath, "utf-8")).toBe("short\n");
+	});
+
+	it("#given a formatted document #when the write completes #then no temporary file is left behind", async () => {
+		// given
+		const { root, filePath } = workspaceWith("sample.ts", "const a=1\n");
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 9 } }, newText: "const a = 1;" },
+		];
+
+		// when
+		await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(readFileSync(filePath, "utf-8")).toBe("const a = 1;\n");
+		expect(() => statSync(join(root, "sample.ts.tmp"))).toThrow();
+	});
+});

package/packages/lsp-core/src/lsp/format-document.ts

@@ -0,0 +1,90 @@
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+
+import type { LspClient } from "./client.js";
+import type { FormattingOptions, TextEdit } from "./types.js";
+import { normalizeTextEdits } from "./workspace-edit-text.js";
+
+export const DEFAULT_FORMATTING_OPTIONS: FormattingOptions = {
+	tabSize: 4,
+	insertSpaces: false,
+	trimTrailingWhitespace: true,
+	insertFinalNewline: true,
+	trimFinalNewlines: true,
+};
+
+export type FormatDocumentResult =
+	| { readonly status: "formatted"; readonly linesAdded: number; readonly linesRemoved: number }
+	| { readonly status: "unchanged"; readonly linesAdded: 0; readonly linesRemoved: 0 }
+	| { readonly status: "unavailable"; readonly reason: "capability_not_advertised" };
+
+export interface FormatDocumentOptions {
+	readonly formattingOptions?: FormattingOptions;
+	readonly signal?: AbortSignal;
+}
+
+const UNCHANGED: FormatDocumentResult = { status: "unchanged", linesAdded: 0, linesRemoved: 0 };
+
+/**
+ * Formats one document through the resident language server and commits the result to disk.
+ *
+ * The server is asked for whole-document edits rather than formatted text, so the edits are
+ * validated and applied with the same normalization the workspace-edit path uses. Nothing is
+ * written when the server declines the capability or when the edits reproduce the current bytes,
+ * which keeps a no-op format from touching file mtimes that downstream tooling watches.
+ */
+export async function formatDocumentWithClient(
+	client: LspClient,
+	filePath: string,
+	options: FormatDocumentOptions = {},
+): Promise<FormatDocumentResult> {
+	const edits = await client.formatDocument(
+		filePath,
+		options.formattingOptions ?? DEFAULT_FORMATTING_OPTIONS,
+		options.signal,
+	);
+	if (edits === null) return { status: "unavailable", reason: "capability_not_advertised" };
+	if (edits.length === 0) return UNCHANGED;
+
+	const before = readFileSync(filePath, "utf-8");
+	const normalized = normalizeTextEdits(before, edits, 0);
+	if (normalized.text === before) return UNCHANGED;
+
+	writeAtomically(filePath, normalized.text);
+	await client.openFile(filePath);
+
+	return {
+		status: "formatted",
+		...lineDelta(normalized.edits),
+	};
+}
+
+/**
+ * Counts the lines each edit removes from the document and adds back in its place.
+ *
+ * Counting from the edits instead of diffing the whole file keeps the report proportional to what
+ * the server actually rewrote, so an unrelated line never shows up as churn.
+ */
+function lineDelta(edits: readonly TextEdit[]): { readonly linesAdded: number; readonly linesRemoved: number } {
+	let linesAdded = 0;
+	let linesRemoved = 0;
+	for (const edit of edits) {
+		linesRemoved += edit.range.end.line - edit.range.start.line + 1;
+		linesAdded += edit.newText.split("\n").length;
+	}
+	return { linesAdded, linesRemoved };
+}
+
+function writeAtomically(filePath: string, content: string): void {
+	const tempPath = `${filePath}.omo-format.tmp`;
+	writeFileSync(tempPath, content, "utf-8");
+	try {
+		renameSync(tempPath, filePath);
+	} catch (error) {
+		try {
+			unlinkSync(tempPath);
+		} catch {
+			// The rename failure is the actionable error; a leftover temp file must not mask it.
+		}
+		throw error;
+	}
+}

package/packages/lsp-core/src/lsp/manager-max-clients.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "bun:test";
+
+import type { LspClient } from "./client.js";
+import { LspManager } from "./manager.js";
+import type { ResolvedServer } from "./types.js";
+
+const SERVER: ResolvedServer = {
+	id: "typescript",
+	command: ["typescript-language-server", "--stdio"],
+	extensions: [".ts"],
+	priority: 1,
+};
+
+class FakeLspClient {
+	alive = true;
+	stopCallCount = 0;
+
+	constructor(readonly root: string) {}
+
+	async start(): Promise<void> {}
+
+	async initialize(): Promise<void> {}
+
+	isAlive(): boolean {
+		return this.alive;
+	}
+
+	command(): string[] {
+		return [...SERVER.command];
+	}
+
+	async stop(): Promise<void> {
+		this.stopCallCount += 1;
+		this.alive = false;
+	}
+}
+
+function managerWithFakes(maxResidentClients: number): {
+	readonly manager: LspManager;
+	readonly clients: Map<string, FakeLspClient>;
+	readonly clock: { value: number };
+} {
+	const clients = new Map<string, FakeLspClient>();
+	const clock = { value: 1_000 };
+	const manager = new LspManager({
+		maxResidentClients,
+		reaperIntervalMs: 60_000,
+		idleTimeoutMs: 60_000_000,
+		now: () => clock.value,
+		clientFactory: (root) => {
+			const client = new FakeLspClient(root);
+			clients.set(root, client);
+			return client as unknown as LspClient;
+		},
+	});
+	return { manager, clients, clock };
+}
+
+describe("LspManager resident client cap", () => {
+	it("#given a cap of two idle clients #when a third client is admitted #then the least recently used one is stopped and evicted", async () => {
+		// given
+		const { manager, clients, clock } = managerWithFakes(2);
+		try {
+			await manager.getClient("/root-a", SERVER);
+			manager.releaseClient("/root-a", SERVER.id);
+			clock.value += 10;
+			await manager.getClient("/root-b", SERVER);
+			manager.releaseClient("/root-b", SERVER.id);
+			clock.value += 10;
+
+			// when
+			await manager.getClient("/root-c", SERVER);
+			manager.releaseClient("/root-c", SERVER.id);
+
+			// then
+			expect(manager.clientCount()).toBe(2);
+			expect(manager.hasClient("/root-a", SERVER.id)).toBe(false);
+			expect(manager.hasClient("/root-b", SERVER.id)).toBe(true);
+			expect(manager.hasClient("/root-c", SERVER.id)).toBe(true);
+			expect(clients.get("/root-a")?.stopCallCount).toBe(1);
+		} finally {
+			await manager.stopAll();
+		}
+	});
+
+	it("#given the least recently used client is mid-request #when a new client is admitted #then the busy client survives and an idle one is evicted", async () => {
+		// given
+		const { manager, clients, clock } = managerWithFakes(2);
+		try {
+			await manager.getClient("/root-busy", SERVER);
+			clock.value += 10;
+			await manager.getClient("/root-idle", SERVER);
+			manager.releaseClient("/root-idle", SERVER.id);
+			clock.value += 10;
+
+			// when
+			await manager.getClient("/root-new", SERVER);
+			manager.releaseClient("/root-new", SERVER.id);
+
+			// then
+			expect(manager.hasClient("/root-busy", SERVER.id)).toBe(true);
+			expect(manager.hasClient("/root-idle", SERVER.id)).toBe(false);
+			expect(clients.get("/root-busy")?.stopCallCount).toBe(0);
+			expect(clients.get("/root-idle")?.stopCallCount).toBe(1);
+		} finally {
+			manager.releaseClient("/root-busy", SERVER.id);
+			await manager.stopAll();
+		}
+	});
+
+	it("#given every resident client is busy #when a new client is admitted #then nothing is evicted and the cap is exceeded rather than breaking a live request", async () => {
+		// given
+		const { manager, clients } = managerWithFakes(1);
+		try {
+			await manager.getClient("/root-busy", SERVER);
+
+			// when
+			await manager.getClient("/root-second", SERVER);
+
+			// then
+			expect(manager.clientCount()).toBe(2);
+			expect(clients.get("/root-busy")?.stopCallCount).toBe(0);
+		} finally {
+			manager.releaseClient("/root-busy", SERVER.id);
+			manager.releaseClient("/root-second", SERVER.id);
+			await manager.stopAll();
+		}
+	});
+
+	it("#given warmup requests beyond the cap #when a warm client is admitted #then the idle least recently used client is evicted too", async () => {
+		// given
+		const { manager, clients, clock } = managerWithFakes(1);
+		try {
+			await manager.getClient("/root-first", SERVER);
+			manager.releaseClient("/root-first", SERVER.id);
+			clock.value += 10;
+
+			// when
+			manager.warmupClient("/root-warm", SERVER);
+			await Promise.resolve();
+			await Promise.resolve();
+
+			// then
+			expect(manager.hasClient("/root-first", SERVER.id)).toBe(false);
+			expect(clients.get("/root-first")?.stopCallCount).toBe(1);
+			expect(manager.hasClient("/root-warm", SERVER.id)).toBe(true);
+		} finally {
+			await manager.stopAll();
+		}
+	});
+});

package/packages/lsp-core/src/lsp/manager.ts

@@ -1,6 +1,6 @@
 import { reportBestEffortCleanupError } from "./cleanup-errors.js";
 import { LspClient } from "./client.js";
-import { IDLE_TIMEOUT_MS, INIT_TIMEOUT_MS, REAPER_INTERVAL_MS } from "./constants.js";
+import { IDLE_TIMEOUT_MS, INIT_TIMEOUT_MS, MAX_RESIDENT_CLIENTS, REAPER_INTERVAL_MS } from "./constants.js";
 import { installProcessSignalCleanup } from "./process-signal-cleanup.js";
 import type { ResolvedServer } from "./types.js";
 
@@ -28,6 +28,7 @@ export interface ClientSnapshot {
 export interface LspManagerOptions {
 	idleTimeoutMs?: number;
 	initTimeoutMs?: number;
+	maxResidentClients?: number;
 	reaperIntervalMs?: number;
 	clientFactory?: (root: string, server: ResolvedServer) => LspClient;
 	now?: () => number;
@@ -80,6 +81,7 @@ export class LspManager {
 
 	private readonly idleTimeoutMs: number;
 	private readonly initTimeoutMs: number;
+	private readonly maxResidentClients: number;
 	private readonly reaperIntervalMs: number;
 	private readonly clientFactory: (root: string, server: ResolvedServer) => LspClient;
 	private readonly now: () => number;
@@ -87,6 +89,7 @@ export class LspManager {
 	constructor(options: LspManagerOptions = {}) {
 		this.idleTimeoutMs = options.idleTimeoutMs ?? IDLE_TIMEOUT_MS;
 		this.initTimeoutMs = options.initTimeoutMs ?? INIT_TIMEOUT_MS;
+		this.maxResidentClients = options.maxResidentClients ?? MAX_RESIDENT_CLIENTS;
 		this.reaperIntervalMs = options.reaperIntervalMs ?? REAPER_INTERVAL_MS;
 		this.clientFactory = options.clientFactory ?? ((root, server) => new LspClient(root, server));
 		this.now = options.now ?? (() => Date.now());
@@ -134,6 +137,32 @@ export class LspManager {
 		}
 	}
 
+	/**
+	 * Frees capacity for one new client by stopping the least recently used idle client.
+	 *
+	 * Only clients with no in-flight work are eligible, so a resident server is never torn down
+	 * underneath a live request; when every resident client is busy the cap is exceeded instead.
+	 */
+	private evictForAdmission(): void {
+		while (this.clients.size >= this.maxResidentClients) {
+			const victim = this.leastRecentlyUsedIdleClient();
+			if (!victim) return;
+			this.clients.delete(victim.key);
+			void stopClientBestEffort(victim.managed.client);
+		}
+	}
+
+	private leastRecentlyUsedIdleClient(): { readonly key: string; readonly managed: ManagedClient } | null {
+		let candidate: { readonly key: string; readonly managed: ManagedClient } | null = null;
+		for (const [key, managed] of this.clients) {
+			if (managed.refCount > 0 || managed.pendingWaiters > 0 || managed.isInitializing) continue;
+			if (candidate === null || managed.lastUsedAt < candidate.managed.lastUsedAt) {
+				candidate = { key, managed };
+			}
+		}
+		return candidate;
+	}
+
 	private async tryDeleteIfOrphaned(key: string, managed: ManagedClient): Promise<void> {
 		if (
 			managed.refCount === 0 &&
@@ -197,6 +226,8 @@ export class LspManager {
 			return managed.client;
 		}
 
+		this.evictForAdmission();
+
 		const client = this.clientFactory(root, server);
 		const initStartedAt = this.now();
 		const initPromise = (async () => {
@@ -264,6 +295,8 @@ export class LspManager {
 		const key = this.getKey(root, server.id);
 		if (this.clients.has(key)) return;
 
+		this.evictForAdmission();
+
 		const client = this.clientFactory(root, server);
 		const initStartedAt = this.now();
 		const initPromise = (async () => {

package/packages/lsp-core/src/lsp/server-definitions.ts

@@ -49,6 +49,35 @@ export const LSP_INSTALL_HINTS: Record<string, string> = {
 		"Install: dotnet tool install -g roslyn-language-server --prerelease (requires v5.8.0+). See https://github.com/dotnet/razor",
 };
 
+/**
+ * Repo-local install commands, offered ahead of the global hints in `LSP_INSTALL_HINTS`.
+ *
+ * A devDependency (or project venv) is resolvable by `resolveServerBinary()` without any
+ * global install, and it pins the version the project actually expects. Only servers that
+ * are genuinely distributed per-project belong here; toolchain-wide servers (rust-analyzer,
+ * gopls, clangd, ...) keep their global hint alone.
+ */
+export const LSP_LOCAL_INSTALL_HINTS: Record<string, string> = {
+	typescript: "bun add -d typescript-language-server typescript",
+	vue: "bun add -d @vue/language-server",
+	eslint: "bun add -d vscode-langservers-extracted",
+	oxlint: "bun add -d oxlint",
+	biome: "bun add -d @biomejs/biome",
+	svelte: "bun add -d svelte-language-server",
+	astro: "bun add -d @astrojs/language-server",
+	bash: "bun add -d bash-language-server",
+	"bash-ls": "bun add -d bash-language-server",
+	"yaml-ls": "bun add -d yaml-language-server",
+	php: "bun add -d intelephense",
+	prisma: "bun add -d prisma",
+	dockerfile: "bun add -d dockerfile-language-server-nodejs",
+	pyright: "uv add --dev pyright",
+	basedpyright: "uv add --dev basedpyright",
+	ruff: "uv add --dev ruff",
+	ty: "uv add --dev ty",
+	"ruby-lsp": "bundle add ruby-lsp --group development",
+};
+
 export const BUILTIN_SERVERS: Record<string, Omit<LspServerConfig, "id">> = {
 	typescript: {
 		command: ["typescript-language-server", "--stdio"],