oh-my-opencode 5.0.0-beta.8 → 5.0.0-beta.80

package/packages/lsp-core/src/lsp/client-diagnostics-pull-timeout.test.ts

@@ -0,0 +1,64 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { ControlledClock } from "./controlled-clock-test-support.js";
+import { LspClient } from "./client.js";
+import { LspRequestTimeoutError } from "./errors.js";
+import type { ResolvedServer } from "./types.js";
+
+const fakeServer: ResolvedServer = {
+	id: "pull-timeout-fake",
+	command: ["pull-timeout-fake"],
+	extensions: [".ts"],
+	priority: 0,
+};
+
+class HangingPullClient extends LspClient {
+	readonly grantedPullTimeouts: number[] = [];
+
+	constructor(root: string, private readonly clock: ControlledClock) {
+		super(root, fakeServer, { diagnosticsFreshnessTimeoutMs: 50, versionlessPublishQuiescenceMs: 5, timerProvider: clock });
+		this.setDiagnosticPullSupported(true);
+	}
+
+	protected override async sendNotification(): Promise<void> {}
+
+	protected override async sendRequest<T>(
+		method: string,
+		...args: [] | [unknown] | [unknown, { timeoutMs?: number; signal?: AbortSignal }]
+	): Promise<T> {
+		if (method !== "textDocument/diagnostic") {
+			throw new Error(`unexpected request in hanging-pull fixture: ${method}`);
+		}
+		const timeoutMs = args[1]?.timeoutMs ?? 0;
+		this.grantedPullTimeouts.push(timeoutMs);
+		this.clock.advanceBy(timeoutMs);
+		throw new LspRequestTimeoutError(method);
+	}
+}
+
+describe("LspClient diagnostics pull timeout conversion", () => {
+	let root: string | null = null;
+
+	afterEach(() => {
+		if (root !== null) rmSync(root, { recursive: true, force: true });
+		root = null;
+	});
+
+	it("#given a pull that exhausts the freshness window #when diagnostics settle #then the timeout converts to freshness_timeout instead of rejecting", async () => {
+		root = mkdtempSync(join(tmpdir(), "lsp-pull-timeout-"));
+		const source = join(root, "sample.ts");
+		writeFileSync(source, "const value = 1;\n", "utf-8");
+		const clock = new ControlledClock();
+		const client = new HangingPullClient(root, clock);
+
+		const result = await client.diagnostics(source);
+
+		expect(client.grantedPullTimeouts).toEqual([50]);
+		expect(result.items).toEqual([]);
+		expect(result.transientError?.kind).toBe("freshness_timeout");
+	});
+});

package/packages/lsp-core/src/lsp/client-wrapper-outside-cwd.test.ts

@@ -0,0 +1,78 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { createStandaloneMcpRequestContext, runWithRequestContext } from "../request-context.js";
+import { findWorkspaceRoot, resolveReadablePathInsideContext, resolvePathInsideContext } from "./client-wrapper.js";
+import { LspInvalidPathError } from "./errors.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+function tempRoot(prefix: string): string {
+	const root = mkdtempSync(join(tmpdir(), prefix));
+	tempDirectories.push(root);
+	return root;
+}
+
+describe("LSP read-only access outside request cwd", () => {
+	it("#given an absolute file outside cwd #when resolving a read path #then returns the canonical path", () => {
+		const root = tempRoot("lsp-outcwd-root-");
+		const outside = tempRoot("lsp-outcwd-outside-");
+		const outsideFile = join(outside, "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		const resolved = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			resolveReadablePathInsideContext(outsideFile),
+		);
+
+		expect(resolved).toBe(realpathSync(outsideFile));
+	});
+
+	it("#given an outside file inside its own marked project #when inferring workspace #then uses that project root", () => {
+		const root = tempRoot("lsp-outcwd-marker-root-");
+		const outside = tempRoot("lsp-outcwd-marker-outside-");
+		mkdirSync(join(outside, ".git"), { recursive: true });
+		mkdirSync(join(outside, "src"), { recursive: true });
+		const outsideFile = join(outside, "src", "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot(outsideFile),
+		);
+
+		expect(workspace).toBe(realpathSync(outside));
+	});
+
+	it("#given an outside file without any marker #when inferring workspace #then falls back to its own directory", () => {
+		const root = tempRoot("lsp-outcwd-nomarker-root-");
+		const outside = tempRoot("lsp-outcwd-nomarker-outside-");
+		const outsideFile = join(outside, "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot(outsideFile),
+		);
+
+		expect(workspace).toBe(realpathSync(outside));
+	});
+
+	it("#given an outside file #when resolving a mutating path #then still rejects to keep writes confined", () => {
+		const root = tempRoot("lsp-outcwd-write-root-");
+		const outside = tempRoot("lsp-outcwd-write-outside-");
+		const outsideFile = join(outside, "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		expect(() =>
+			runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+				resolvePathInsideContext(outsideFile),
+			),
+		).toThrow(LspInvalidPathError);
+	});
+});

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

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "bun:test";
 
 import { createStandaloneMcpRequestContext, runWithRequestContext } from "../request-context.js";
+import type { LspClient } from "./client.js";
 import { findWorkspaceRoot, resolveReadablePathInsideContext, withLspClient } from "./client-wrapper.js";
 import { LspInvalidPathError } from "./errors.js";
 import { LspManager } from "./manager.js";
@@ -22,6 +23,102 @@ function tempRoot(prefix: string): string {
 	return root;
 }
 
+describe("LSP workspace root collapse in monorepos", () => {
+	it("#given a git repository containing four package.json packages #when resolving workspace roots for files in each package #then all collapse to the repository root", () => {
+		const root = tempRoot("lsp-client-wrapper-monorepo-");
+		mkdirSync(join(root, ".git"), { recursive: true });
+		const packageDirs = ["alpha", "beta", "gamma", "delta"].map((name) => join(root, "packages", name));
+		for (const packageDir of packageDirs) {
+			mkdirSync(join(packageDir, "src"), { recursive: true });
+			writeFileSync(join(packageDir, "package.json"), "{}\n");
+			writeFileSync(join(packageDir, "src", "file.ts"), "export const value = 1;\n");
+		}
+		const context = createStandaloneMcpRequestContext({ cwd: root });
+
+		const roots = packageDirs.map((packageDir) =>
+			runWithRequestContext(context, () => findWorkspaceRoot(join(packageDir, "src", "file.ts"))),
+		);
+
+		expect(new Set(roots).size).toBe(1);
+		expect(roots[0]).toBe(realpathSync(root));
+	});
+
+	it("#given nested package.json markers without any .git #when resolving workspace #then keeps the nearest package root", () => {
+		const root = tempRoot("lsp-client-wrapper-nested-");
+		const nested = join(root, "parent", "nested");
+		mkdirSync(join(nested, "src"), { recursive: true });
+		writeFileSync(join(root, "parent", "package.json"), "{}\n");
+		writeFileSync(join(nested, "package.json"), "{}\n");
+		writeFileSync(join(nested, "src", "file.ts"), "export const value = 1;\n");
+
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot(join(nested, "src", "file.ts")),
+		);
+
+		expect(workspace).toBe(realpathSync(nested));
+	});
+
+	it("#given four monorepo package files under one .git root #when acquiring clients #then one client serves the whole repository", async () => {
+		const root = tempRoot("lsp-client-wrapper-oneclient-");
+		mkdirSync(join(root, ".git"), { recursive: true });
+		const userConfig = join(root, "user-lsp.json");
+		writeFileSync(
+			userConfig,
+			JSON.stringify({ lsp: { monorepoProbe: { command: [process.execPath], extensions: [".monoroot"] } } }),
+		);
+		const filePaths = ["alpha", "beta", "gamma", "delta"].map((name) => {
+			const packageDir = join(root, "packages", name);
+			mkdirSync(join(packageDir, "src"), { recursive: true });
+			writeFileSync(join(packageDir, "package.json"), "{}\n");
+			const filePath = join(packageDir, "src", "probe.monoroot");
+			writeFileSync(filePath, "const value = 1;\n");
+			return filePath;
+		});
+		const factoryRoots: string[] = [];
+		const manager = new LspManager({
+			clientFactory: (workspaceRoot) => {
+				factoryRoots.push(workspaceRoot);
+				return new StubLspClient() as unknown as LspClient;
+			},
+		});
+
+		try {
+			const context = createStandaloneMcpRequestContext({
+			cwd: root,
+			env: { LSP_TOOLS_MCP_USER_CONFIG: userConfig },
+		});
+			await Promise.all(
+				filePaths.map((filePath) =>
+					runWithRequestContext(context, () =>
+						withLspClient(filePath, async () => undefined, "diagnostics", { manager }),
+				),
+			),
+			);
+
+			expect(factoryRoots).toEqual([realpathSync(root)]);
+			expect(manager.clientCount()).toBe(1);
+		} finally {
+			await manager.stopAll();
+		}
+	});
+});
+
+class StubLspClient {
+	async start(): Promise<void> {}
+
+	async initialize(): Promise<void> {}
+
+	isAlive(): boolean {
+		return true;
+	}
+
+	command(): string[] {
+		return [process.execPath];
+	}
+
+	async stop(): Promise<void> {}
+}
+
 describe("LSP client path confinement", () => {
 	it("#given a relative file inside context cwd #when resolving workspace #then marker search stays inside cwd", () => {
 		const root = tempRoot("lsp-client-wrapper-root-");
@@ -36,17 +133,17 @@ describe("LSP client path confinement", () => {
 		expect(workspace).toBe(realpathSync(root));
 	});
 
-	it("#given an absolute file outside context cwd #when resolving #then rejects before workspace inference", () => {
+	it("#given an absolute file outside context cwd #when resolving #then infers the file's own project root", () => {
 		const root = tempRoot("lsp-client-wrapper-cwd-");
 		const outside = tempRoot("lsp-client-wrapper-outside-");
 		mkdirSync(join(outside, ".git"), { recursive: true });
 		writeFileSync(join(outside, "file.ts"), "export const outside = true;\n");
 
-		expect(() =>
-			runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
-				findWorkspaceRoot(join(outside, "file.ts")),
-			),
-		).toThrow(LspInvalidPathError);
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot(join(outside, "file.ts")),
+		);
+
+		expect(workspace).toBe(realpathSync(outside));
 	});
 
 	it("#given a symlink inside cwd that points outside #when resolving read path #then keeps lexical path and cwd root", () => {

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

@@ -16,11 +16,12 @@ import {
 	LspServerLookupError,
 } 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";
-
-const WORKSPACE_MARKERS = [".git", "package.json", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml", "build.gradle"];
+import { GIT_WORKSPACE_MARKER, PROJECT_WORKSPACE_MARKERS } from "./workspace-markers.js";
 
 export function isDirectoryPath(filePath: string): boolean {
 	try {
@@ -30,6 +31,15 @@ export function isDirectoryPath(filePath: string): boolean {
 	}
 }
 
+/**
+ * Resolves the workspace root for a file inside the request cwd.
+ *
+ * A `.git`-containing ancestor always wins over nearer package markers, so all packages of a
+ * monorepo share one workspace root (one resident client per repository instead of one per
+ * package, which multiplies language-server processes by the package count). The nearest
+ * package-marked directory is remembered while walking and used only when no `.git` ancestor
+ * exists within the request cwd.
+ */
 export function findWorkspaceRoot(filePath: string): string {
 	const cwd = contextCwd();
 	const abs = resolveReadablePathInsideContext(filePath);
@@ -39,21 +49,29 @@ export function findWorkspaceRoot(filePath: string): string {
 		dir = dirname(dir);
 	}
 
+	if (!isPathInside(cwd, abs)) return findWorkspaceRootOutsideContext(dir);
+
 	const fallbackRoot = nearestExistingDirectoryInsideContext(dir, cwd) ?? cwd;
+	let nearestPackageRoot: string | undefined;
 	while (isPathInside(cwd, dir)) {
 		const canonicalDir = existingDirectoryInsideContext(dir, cwd);
 		if (canonicalDir !== undefined) {
-			for (const marker of WORKSPACE_MARKERS) {
-				if (existsSync(join(dir, marker))) {
-					return canonicalDir;
-				}
+			if (existsSync(join(dir, GIT_WORKSPACE_MARKER))) {
+				return canonicalDir;
+			}
+			if (nearestPackageRoot === undefined && hasProjectWorkspaceMarker(dir)) {
+				nearestPackageRoot = canonicalDir;
 			}
 		}
 		if (dir === cwd) break;
 		dir = dirname(dir);
 	}
 
-	return fallbackRoot;
+	return nearestPackageRoot ?? fallbackRoot;
+}
+
+function hasProjectWorkspaceMarker(directory: string): boolean {
+	return PROJECT_WORKSPACE_MARKERS.some((marker) => existsSync(join(directory, marker)));
 }
 
 export function resolveReadablePathInsideContext(filePath: string): string {
@@ -64,10 +82,7 @@ export function resolveReadablePathInsideContext(filePath: string): string {
 	const rebased = rebaseThroughCanonicalAncestor(abs, cwd);
 	if (rebased !== undefined) return rebased;
 
-	const canonical = canonicalizeExistingOrNearestAncestor(abs);
-	if (isPathInside(cwd, canonical)) return canonical;
-
-	throw new LspInvalidPathError(`LSP file path must be inside request cwd: ${filePath}`);
+	return canonicalizeExistingOrNearestAncestor(abs);
 }
 
 export function resolvePathInsideContext(filePath: string): string {
@@ -139,6 +154,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(", ");
@@ -155,20 +190,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.",
@@ -177,8 +212,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,10 +14,12 @@ import type {
 	Range,
 	ResolvedServer,
 	SymbolInfo,
+	TextEdit,
 	WorkspaceEdit,
 } from "./types.js";
 import { LspRequestTimeoutError } from "./errors.js";
 import { WorkspaceDocumentState } from "./workspace-document-state.js";
+import type { TimerProvider } from "./timer-provider.js";
 import type { LspRenameResult, WorkspaceEditCommitIo } from "./workspace-edit-types.js";
 import { WorkspaceMutationController } from "./workspace-mutation-controller.js";
 
@@ -34,6 +37,7 @@ export interface LspDiagnosticsResult {
 export interface LspClientOptions extends LspClientTimeoutOptions {
 	readonly diagnosticsFreshnessTimeoutMs?: number;
 	readonly versionlessPublishQuiescenceMs?: number;
+	readonly timerProvider?: TimerProvider;
 }
 
 export class LspClient extends LspClientConnection {
@@ -50,6 +54,7 @@ export class LspClient extends LspClientConnection {
 			(method, params) => this.sendNotification(method, params),
 			(uri) => this.diagnosticsStore.delete(uri),
 			{
+				timerProvider: this.timerProvider,
 				versionlessPublishQuiescenceMs:
 					options.versionlessPublishQuiescenceMs ?? VERSIONLESS_PUBLISH_QUIESCENCE_MS,
 			},
@@ -133,6 +138,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);
@@ -181,7 +210,7 @@ export class LspClient extends LspClientConnection {
 		const absPath = this.resolveWorkspacePath(filePath);
 		const uri = pathToFileURL(absPath).href;
 		await this.openFile(absPath);
-		const deadlineAt = Date.now() + this.diagnosticsFreshnessTimeoutMs;
+		const deadlineAt = this.timerProvider.now() + this.diagnosticsFreshnessTimeoutMs;
 
 		for (;;) {
 			signal?.throwIfAborted();
@@ -194,7 +223,7 @@ export class LspClient extends LspClientConnection {
 			if (!pushFallbackOnly) {
 				const cached = this.documents.getPullCache(snapshot);
 				try {
-					const remainingMs = deadlineAt - Date.now();
+					const remainingMs = deadlineAt - this.timerProvider.now();
 					if (remainingMs <= 0) return this.freshnessTimeout(absPath);
 					const result = await this.sendRequest<{ items?: Diagnostic[]; kind?: string; resultId?: string }>(
 						"textDocument/diagnostic",
@@ -236,7 +265,7 @@ export class LspClient extends LspClientConnection {
 
 			if (!pushFallbackOnly) continue;
 
-			const remainingMs = deadlineAt - Date.now();
+			const remainingMs = deadlineAt - this.timerProvider.now();
 			if (remainingMs <= 0) {
 				// A server that never advertised pull diagnostics (or rejected the pull
 				// method) and has never published for this document stays silent for a

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,12 @@ 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;
+
+/** Max consecutive dead client generations respawned for one key before admission is blocked. */
+export const CLIENT_RESPAWN_RETRY_LIMIT = 2;
+/** How long a spent respawn budget blocks admission before a fresh attempt window opens. */
+export const CLIENT_RESPAWN_COOLDOWN_MS = 60_000;

package/packages/lsp-core/src/lsp/controlled-clock-test-support.ts

@@ -0,0 +1,90 @@
+import type { TimerProvider } from "./timer-provider.js";
+
+interface ControlledTimer {
+	readonly at: number;
+	readonly callback: () => void;
+	cancelled: boolean;
+}
+
+interface TimerWaiter {
+	readonly delayMs: number | undefined;
+	readonly resolve: () => void;
+}
+
+interface ScheduleWaiter {
+	readonly count: number;
+	readonly resolve: () => void;
+}
+
+/**
+ * Deterministic TimerProvider for tests: timers fire only through advanceBy(),
+ * and waitForTimer(delayMs) resolves once a timer with exactly that delay is
+ * scheduled, so tests order themselves behind the timer they intend to fire.
+ */
+export class ControlledClock implements TimerProvider {
+	private readonly timers: ControlledTimer[] = [];
+	private currentTime = 0;
+	private readonly timerWaiters = new Set<TimerWaiter>();
+	private readonly scheduleWaiters = new Set<ScheduleWaiter>();
+	readonly scheduledDelays: number[] = [];
+
+	readonly now = (): number => this.currentTime;
+	readonly setTimeout = (callback: () => void, delayMs: number): ReturnType<typeof setTimeout> => {
+		const timer: ControlledTimer = { at: this.currentTime + delayMs, callback, cancelled: false };
+		this.scheduledDelays.push(delayMs);
+		this.timers.push(timer);
+		for (const waiter of this.timerWaiters) {
+			if (waiter.delayMs === undefined || waiter.delayMs === delayMs) {
+				this.timerWaiters.delete(waiter);
+				waiter.resolve();
+			}
+		}
+		for (const waiter of this.scheduleWaiters) {
+			if (this.scheduledDelays.length >= waiter.count) {
+				this.scheduleWaiters.delete(waiter);
+				waiter.resolve();
+			}
+		}
+		return timer as unknown as ReturnType<typeof setTimeout>;
+	};
+	readonly clearTimeout = (handle: ReturnType<typeof setTimeout>): void => {
+		(handle as unknown as { cancelled: boolean }).cancelled = true;
+	};
+
+	waitForTimer(delayMs?: number): Promise<void> {
+		const hasTimer = this.timers.some(
+			(timer) => !timer.cancelled && (delayMs === undefined || timer.at === this.currentTime + delayMs),
+		);
+		if (hasTimer) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.timerWaiters.add({ delayMs, resolve });
+		});
+	}
+
+	/**
+	 * Resolves once this clock has been asked to schedule `count` timers in total.
+	 *
+	 * Timer DELAYS are ambiguous whenever the code under test derives several budgets from the same
+	 * remaining window (an LSP request timeout and the push-fallback wait are both "whatever is left
+	 * of the freshness window"). The schedule ORDER is not ambiguous: a step that only runs after an
+	 * earlier request settled can only arm its timer once that request's own timer was cleared. So a
+	 * test that must fire the LATER timer waits for the later schedule instead of a delay value, and
+	 * never races the earlier one.
+	 */
+	waitForScheduled(count: number): Promise<void> {
+		if (this.scheduledDelays.length >= count) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.scheduleWaiters.add({ count, resolve });
+		});
+	}
+
+	advanceBy(delayMs: number): void {
+		this.currentTime += delayMs;
+		for (;;) {
+			const index = this.timers.findIndex((timer) => timer.at <= this.currentTime);
+			if (index < 0) return;
+			const timer = this.timers.splice(index, 1)[0];
+			if (timer && !timer.cancelled) timer.callback();
+		}
+	}
+}

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

@@ -69,6 +69,21 @@ export class LspProcessSpawnError extends Error {
 	override readonly name = "LspProcessSpawnError";
 }
 
+export class LspClientRespawnBudgetExceededError extends Error {
+	override readonly name = "LspClientRespawnBudgetExceededError";
+
+	constructor(
+		readonly serverId: string,
+		readonly root: string,
+		readonly retryLimit: number,
+	) {
+		super(
+			`LSP server ${serverId} at ${root} failed to stay alive; respawn budget exhausted ` +
+				`(${retryLimit} consecutive dead generations). Retrying after the cooldown may succeed.`,
+		);
+	}
+}
+
 export function isLspDeadConnectionError(err: unknown): err is LspConnectionClosedError | LspProcessExitedError {
 	return err instanceof LspConnectionClosedError || err instanceof LspProcessExitedError;
 }