@mrclrchtr/supi-code-intelligence 4.10.0 → 5.0.0

package/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts

@@ -6,7 +6,10 @@ import { type ChildProcess, execSync, spawn } from "node:child_process";
 import * as path from "node:path";
 import {
   type CodeQueryResult,
+  type CodeRequestControl,
   completedCodeQuery,
+  isCodeRequestInterruption,
+  throwIfCodeRequestInterrupted,
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
@@ -25,7 +28,6 @@ import type {
   Location,
   LocationLink,
   Position,
-  PublishDiagnosticsParams,
   Range,
   ServerCapabilities,
   ServerConfig,
@@ -33,14 +35,35 @@ import type {
   WorkspaceEdit,
   WorkspaceSymbol,
 } from "../config/types.ts";
+import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
+import type { DiagnosticEvidenceSummary } from "../diagnostics/evidence.ts";
+import { raceRequestControl } from "../session/readiness.ts";
 import { fileToUri } from "../utils.ts";
-import { ClientDiagnostics, type DiagnosticEntry } from "./client-diagnostics.ts";
+import {
+  ClientDynamicRegistrations,
+  DOCUMENT_DIAGNOSTIC_METHOD,
+  isValidDiagnosticOptions,
+} from "./client-diagnostic-capabilities.ts";
+import { ClientDiagnostics } from "./client-diagnostics.ts";
+import type { ClientDiagnosticSnapshot, DiagnosticEntry } from "./client-document-state.ts";
 import { JsonRpcClient, JsonRpcRequestError } from "./transport.ts";
 
 const SHUTDOWN_TIMEOUT_MS = 5_000;
 
+/**
+ * Fixed bound after which a running client that never became ready is
+ * considered readiness-stalled and eligible for a recovery restart.
+ */
+export const RECOVERY_CLIENT_STARTUP_BOUND_MS = 5_000;
+
+/** Repeated protocol-stall failures that justify a recovery restart. */
+export const RECOVERY_PROTOCOL_FAILURE_THRESHOLD = 3;
+
+/** Stall signals that justify replacing a client's server process. */
+export type RecoveryRestartReason = "readiness-stall" | "protocol-errors";
+
 /** Race an operation against a timeout without retaining the timer after settlement. */
-async function withTimeout<T>(
+export async function withTimeout<T>(
   operation: Promise<T>,
   timeoutMs: number,
   message: string,
@@ -58,6 +81,41 @@ async function withTimeout<T>(
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read and validate the `registrations` array of a `client/registerCapability`
+ * request. Each entry must be a record with string `id` and `method`; the
+ * optional `registerOptions` stay unvalidated here (method-specific checks
+ * happen in the handler). Malformed values reject the request.
+ */
+function readRegistrations(
+  params: unknown,
+  requestName: string,
+): Array<{ id: string; method: string; registerOptions?: unknown }> {
+  if (!isRecord(params) || !Array.isArray(params.registrations)) {
+    throw new JsonRpcRequestError(-32602, `Malformed ${requestName} params.`);
+  }
+  const registrations: Array<{ id: string; method: string; registerOptions?: unknown }> = [];
+  for (const registration of params.registrations) {
+    if (
+      !isRecord(registration) ||
+      typeof registration.id !== "string" ||
+      typeof registration.method !== "string"
+    ) {
+      throw new JsonRpcRequestError(-32602, `Malformed ${requestName} registration.`);
+    }
+    registrations.push({
+      id: registration.id,
+      method: registration.method,
+      registerOptions: registration.registerOptions,
+    });
+  }
+  return registrations;
+}
+
 // ── Process-tree cleanup ──────────────────────────────────────────────
 
 /**
@@ -86,6 +144,17 @@ function killProcessTree(pid: number): void {
 // ── Types ─────────────────────────────────────────────────────────────
 export type ClientStatus = "initializing" | "running" | "error" | "shutdown";
 
+/** Package-internal facts that the manager projects into workspace lifecycle transitions. */
+export type LspClientLifecycleTransitionKind =
+  | "startup"
+  | "readiness"
+  | "crash"
+  | "shutdown"
+  | "tracked-files";
+
+/** Observer for one concrete client's lifecycle facts. */
+export type LspClientLifecycleListener = (kind: LspClientLifecycleTransitionKind) => void;
+
 // ── LspClient ─────────────────────────────────────────────────────────
 export class LspClient {
   readonly name: string;
@@ -96,37 +165,61 @@ export class LspClient {
   private _status: ClientStatus = "initializing";
   private capabilities: ServerCapabilities | null = null;
   private readonly diagnostics: ClientDiagnostics;
+  /** Dynamic capability registrations for this client instance only. */
+  private readonly dynamicRegistrations = new ClientDynamicRegistrations();
 
   // ── Readiness (work-done-progress) ──────────────────────────────────
-  private trackedTokens = new Map<ProgressToken, "begin-seen" | "ended">();
+  private trackedTokens = new Map<ProgressToken, "created" | "active" | "ended">();
+  private tokenCreatedAt = new Map<ProgressToken, number>();
   private _readyPromise: Promise<void> | null = null;
   private _readyResolve: (() => void) | undefined;
   private _readyReject: ((err: Error) => void) | undefined;
   private _isReady = false;
+  /** Whether this client generation ever reached concrete readiness. */
+  private everReady = false;
   private noProgressTimer: ReturnType<typeof setTimeout> | null = null;
   private tokenTimeouts = new Map<ProgressToken, ReturnType<typeof setTimeout>>();
+  /** Wall-clock start of the current client generation, for stall detection. */
+  private startedAt = 0;
 
+  // biome-ignore lint/complexity/useMaxParams: internal constructor keeps positional identity for test call sites
   constructor(
     name: string,
     private readonly config: ServerConfig,
     root: string,
+    private readonly onLifecycleTransition?: LspClientLifecycleListener,
+    /** Absolute workspace root for debug-telemetry identity. */
+    readonly cwd?: string,
   ) {
     this.name = name;
     this.root = root;
     this.diagnostics = new ClientDiagnostics({
+      server: name,
+      cwd: cwd,
       isOperational: () => this.rpc !== null && this._status === "running",
       supportsPullDiagnostics: () => this.hasDiagnosticProvider,
       sendNotification: (method, params) => {
         if (this.rpc) void this.rpc.sendNotification(method, params);
       },
-      pullDocumentDiagnostics: async (uri, previousResultId, timeoutMs) => {
+      pullDocumentDiagnostics: async (request) => {
         const rpc = this.rpc;
         if (!rpc || this._status !== "running") throw new Error("client not running");
-        await this.getReady();
+        await this.getReady({
+          signal: request.signal,
+          deadline: request.deadline,
+        });
         return rpc.sendRequest(
-          "textDocument/diagnostic",
-          { textDocument: { uri }, previousResultId },
-          { timeoutMs },
+          DOCUMENT_DIAGNOSTIC_METHOD,
+          {
+            textDocument: { uri: request.uri },
+            previousResultId: request.previousResultId,
+          },
+          {
+            timeoutMs: request.timeoutMs,
+            signal: request.signal,
+            deadline: request.deadline,
+            operationId: request.operationId,
+          },
         ) as Promise<DocumentDiagnosticReport>;
       },
     });
@@ -149,11 +242,21 @@ export class LspClient {
     return this._isReady;
   }
 
+  /** Publish one client fact without letting an observer disrupt the client. */
+  private publishLifecycle(kind: LspClientLifecycleTransitionKind): void {
+    try {
+      this.onLifecycleTransition?.(kind);
+    } catch {
+      // Lifecycle observers must not alter protocol behavior.
+    }
+  }
+
   // ── Lifecycle ───────────────────────────────────────────────────────
   /** Spawn the server process and perform the initialize handshake. */
   async start(): Promise<void> {
     const cmd = this.config.command;
     const args = this.config.args ?? [];
+    this.startedAt = Date.now();
 
     try {
       this.process = spawn(cmd, args, {
@@ -166,22 +269,27 @@ export class LspClient {
         detached: true,
       });
     } catch (err) {
-      this._status = "error";
-      throw new Error(`Failed to spawn ${cmd}: ${err}`, { cause: err });
+      const failure = new Error(`Failed to spawn ${cmd}: ${err}`, { cause: err });
+      this.handleProcessFailure(failure);
+      throw failure;
     }
 
     if (!this.process.stdin || !this.process.stdout) {
-      this._status = "error";
+      const failure = new Error(`${cmd}: missing stdin/stdout`);
+      this.handleProcessFailure(failure);
       this.process.kill();
-      throw new Error(`${cmd}: missing stdin/stdout`);
+      throw failure;
     }
 
-    this.rpc = new JsonRpcClient(this.process.stdout, this.process.stdin);
+    this.rpc = new JsonRpcClient(this.process.stdout, this.process.stdin, {
+      server: this.name,
+      cwd: this.cwd,
+    });
 
     // Handle notifications
     this.rpc.onNotification((method, params) => {
       if (method === "textDocument/publishDiagnostics") {
-        this.handlePublishDiagnostics(params as PublishDiagnosticsParams);
+        this.handlePublishDiagnostics(params);
       } else if (method === "$/progress") {
         this.handleProgress(params as { token: ProgressToken; value: { kind: string } });
       }
@@ -190,19 +298,11 @@ export class LspClient {
 
     // Handle crashes
     this.process.on("exit", (_code) => {
-      if (this._status !== "shutdown") {
-        this._status = "error";
-        this.cancelNoProgressTimer();
-        this.rejectReady(new Error("Client crashed"));
-      }
-      this.rpc?.dispose();
+      this.handleProcessFailure(new Error("Client crashed"));
     });
 
     this.process.on("error", (_err) => {
-      if (this._status !== "shutdown") {
-        this._status = "error";
-        this.rejectReady(new Error("Client process error"));
-      }
+      this.handleProcessFailure(new Error("Client process error"));
     });
 
     // Suppress stderr to avoid noise in the agent
@@ -217,15 +317,21 @@ export class LspClient {
         initializationOptions: this.config.initializationOptions,
       })) as InitializeResult;
 
+      const positionEncoding = result.capabilities.positionEncoding ?? "utf-16";
+      if (positionEncoding !== "utf-16") {
+        throw new Error(`Server selected unsupported position encoding "${positionEncoding}".`);
+      }
       this.capabilities = result.capabilities;
       void this.rpc.sendNotification("initialized", {});
       this._status = "running";
+      this.publishLifecycle("startup");
 
       this.armNoProgressTimer();
     } catch (err) {
-      this._status = "error";
+      const failure = new Error(`${this.name}: initialize failed: ${err}`, { cause: err });
+      this.handleProcessFailure(failure);
       this.process.kill();
-      throw new Error(`${this.name}: initialize failed: ${err}`, { cause: err });
+      throw failure;
     }
   }
 
@@ -233,6 +339,11 @@ export class LspClient {
   async shutdown(): Promise<void> {
     if (this._status === "shutdown") return;
     this._status = "shutdown";
+    this.diagnostics.clear();
+    this.dynamicRegistrations.clear();
+    this.cancelNoProgressTimer();
+    this.rejectReady(new Error("Client shutdown"));
+    this.publishLifecycle("shutdown");
 
     if (!this.rpc || !this.process) return;
 
@@ -271,38 +382,123 @@ export class LspClient {
         });
       }
     }
+  }
 
-    this.diagnostics.clear();
+  /**
+   * Terminate the process tree without a protocol handshake.
+   *
+   * Used when a replacement startup exceeds its recovery bound, so the
+   * orphaned server process cannot outlive the failed restart.
+   */
+  async forceKill(): Promise<void> {
+    const pid = this.process?.pid;
+    this.rpc?.dispose();
+    if (pid && this.process?.exitCode === null) {
+      killProcessTree(pid);
+      if (process.platform !== "win32") {
+        // Escalate to SIGKILL after a brief grace period on Unix, mirroring
+        // the graceful shutdown path for servers that ignore SIGTERM.
+        await new Promise<void>((resolve) => {
+          setTimeout(() => {
+            try {
+              process.kill(-pid, "SIGKILL");
+            } catch {
+              // Already dead — ignore.
+            }
+            resolve();
+          }, 500);
+        });
+      }
+    }
+    this.handleProcessFailure(new Error("Client start bound exceeded"));
+  }
 
-    // Clear readiness state
-    if (this.noProgressTimer) {
-      clearTimeout(this.noProgressTimer);
-      this.noProgressTimer = null;
+  private handleProcessFailure(reason: Error): void {
+    const didCrash = this._status !== "shutdown" && this._status !== "error";
+    if (didCrash) {
+      this._status = "error";
+      this.cancelNoProgressTimer();
+      this.rejectReady(reason);
     }
-    for (const timer of this.tokenTimeouts.values()) clearTimeout(timer);
-    this.tokenTimeouts.clear();
-    this.rejectReady(new Error("Client shutdown"));
+    this.diagnostics.clear({ preserveFailedDocuments: didCrash || this._status === "error" });
+    this.dynamicRegistrations.clear();
+    this.rpc?.dispose();
+    if (didCrash) this.publishLifecycle("crash");
   }
 
   // ── Document Synchronization and Diagnostics ────────────────────────
   /** Open a document, or update it when it is already open. */
   didOpen(filePath: string, content: string): void {
+    const trackedCount = this.openFiles.length;
     this.diagnostics.didOpen(filePath, content);
+    this.publishTrackedFileChange(trackedCount);
   }
 
   /** Update a document, or open it when it is not tracked yet. */
   didChange(filePath: string, content: string): void {
+    const trackedCount = this.openFiles.length;
     this.diagnostics.didChange(filePath, content);
+    this.publishTrackedFileChange(trackedCount);
   }
 
   /** Close a document and remove its cached diagnostic state. */
   didClose(filePath: string): void {
+    const trackedCount = this.openFiles.length;
     this.diagnostics.didClose(filePath);
+    this.publishTrackedFileChange(trackedCount);
   }
 
   /** Remove missing document and diagnostic state, and return the removed paths. */
   pruneMissingFiles(): string[] {
-    return this.diagnostics.pruneMissingFiles();
+    const trackedCount = this.openFiles.length;
+    const removed = this.diagnostics.pruneMissingFiles();
+    this.publishTrackedFileChange(trackedCount);
+    return removed;
+  }
+
+  private publishTrackedFileChange(previousCount: number): void {
+    if (this.openFiles.length !== previousCount) this.publishLifecycle("tracked-files");
+  }
+
+  /** Retain a failed document outcome when a replacement cannot reopen it. */
+  markFailedFile(filePath: string): void {
+    this.diagnostics.markFailedFile(filePath);
+  }
+
+  /**
+   * Return the stall signal that justifies replacing this client's process,
+   * or null when the client is healthy. Recovery restarts clients only on
+   * these signals, never on unconfirmed evidence alone (ADR 0020).
+   */
+  getRecoveryStallSignal(): RecoveryRestartReason | null {
+    if (this._status !== "running") return null;
+    // The startup bound applies only before the client ever became ready: a
+    // later readiness loss (a normal progress begin during indexing) is not
+    // a startup stall.
+    const pastStartupBound =
+      this.startedAt > 0 && Date.now() - this.startedAt >= RECOVERY_CLIENT_STARTUP_BOUND_MS;
+    if (!this.everReady && pastStartupBound) return "readiness-stall";
+    if (this.hasUnbegunCreatedToken()) return "readiness-stall";
+    if ((this.rpc?.getProtocolFailureCount() ?? 0) >= RECOVERY_PROTOCOL_FAILURE_THRESHOLD) {
+      return "protocol-errors";
+    }
+    return null;
+  }
+
+  /** Test whether a created progress token never began within its per-token bound. */
+  private hasUnbegunCreatedToken(): boolean {
+    const boundMs = this.config.readinessTimeoutMs ?? 10_000;
+    for (const [token, createdAt] of this.tokenCreatedAt) {
+      if (this.trackedTokens.get(token) === "created" && Date.now() - createdAt >= boundMs) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Return the current client version, or null when the document is not open. */
+  getOpenDocumentVersion(filePath: string): number | null {
+    return this.diagnostics.getOpenDocumentVersion(filePath);
   }
 
   /** Return stored diagnostics for one file. */
@@ -311,8 +507,12 @@ export class LspClient {
   }
 
   /** Return non-empty diagnostics for files that still exist. */
+  getDiagnosticSnapshot(): ClientDiagnosticSnapshot {
+    return this.diagnostics.getDiagnosticSnapshot();
+  }
+
   getAllDiagnostics(): DiagnosticEntry[] {
-    return this.diagnostics.getAllDiagnostics();
+    return this.getDiagnosticSnapshot().entries;
   }
 
   /** Force the next pull refresh to request complete diagnostic reports. */
@@ -322,12 +522,20 @@ export class LspClient {
 
   /** Check if server supports pull diagnostics. */
   get hasDiagnosticProvider(): boolean {
-    return this.capabilities?.diagnosticProvider !== undefined;
+    // Static state: a valid `diagnosticProvider` in the initialize result.
+    // Dynamic state: an active registration for the diagnostic method. A
+    // malformed static shape or an empty dynamic set fails closed, so an
+    // unsupported server never gets pull requests.
+    return (
+      isValidDiagnosticOptions(this.capabilities?.diagnosticProvider) ||
+      this.dynamicRegistrations.has(DOCUMENT_DIAGNOSTIC_METHOD)
+    );
   }
 
   /** Notify the server that watched workspace files changed. */
   notifyWorkspaceFileChanges(changes: FileEvent[]): void {
     if (!this.rpc || this._status !== "running" || changes.length === 0) return;
+    this.diagnostics.invalidateCachedEvidence();
     void this.rpc.sendNotification("workspace/didChangeWatchedFiles", {
       changes,
     } satisfies DidChangeWatchedFilesParams);
@@ -335,118 +543,157 @@ export class LspClient {
 
   /** Re-read open documents, then collect pull diagnostics or wait for push diagnostics. */
   async refreshOpenDiagnostics(
-    options: { maxWaitMs?: number; quietMs?: number } = {},
-  ): Promise<void> {
+    options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl = {},
+  ): Promise<DiagnosticEvidenceSummary> {
     return this.diagnostics.refreshOpenDiagnostics(options);
   }
 
-  /** Sync one file and return its diagnostics after pull or push collection. */
-  async syncAndWaitForDiagnostics(filePath: string, content: string): Promise<Diagnostic[]> {
-    return this.diagnostics.syncAndWaitForDiagnostics(filePath, content);
+  /** Sync one file and return diagnostics with explicit evidence availability. */
+  async syncAndWaitForDiagnostics(
+    filePath: string,
+    content: string,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Diagnostic[]>> {
+    return this.diagnostics.syncAndWaitForDiagnostics(filePath, content, control);
   }
 
   // ── LSP Requests ───────────────────────────────────────────────────
-  async hover(filePath: string, position: Position): Promise<CodeQueryResult<Hover | null>> {
-    return this.query("textDocument/hover", {
-      textDocument: { uri: fileToUri(filePath) },
-      position,
-    });
+  async hover(
+    filePath: string,
+    position: Position,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Hover | null>> {
+    return this.query(
+      "textDocument/hover",
+      { textDocument: { uri: fileToUri(filePath) }, position },
+      control,
+    );
   }
 
   async definition(
     filePath: string,
     position: Position,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>> {
-    return this.query("textDocument/definition", {
-      textDocument: { uri: fileToUri(filePath) },
-      position,
-    });
+    return this.query(
+      "textDocument/definition",
+      { textDocument: { uri: fileToUri(filePath) }, position },
+      control,
+    );
   }
 
   async references(
     filePath: string,
     position: Position,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Location[] | null>> {
-    return this.query("textDocument/references", {
-      textDocument: { uri: fileToUri(filePath) },
-      position,
-      context: { includeDeclaration: true },
-    });
+    return this.query(
+      "textDocument/references",
+      {
+        textDocument: { uri: fileToUri(filePath) },
+        position,
+        context: { includeDeclaration: true },
+      },
+      control,
+    );
   }
 
   async documentSymbols(
     filePath: string,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[] | null>> {
-    return this.query("textDocument/documentSymbol", {
-      textDocument: { uri: fileToUri(filePath) },
-    });
+    return this.query(
+      "textDocument/documentSymbol",
+      { textDocument: { uri: fileToUri(filePath) } },
+      control,
+    );
   }
 
   async workspaceSymbol(
     query: string,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<SymbolInformation[] | WorkspaceSymbol[] | null>> {
     if (!this.capabilities?.workspaceSymbolProvider) {
       return unavailableCodeQuery("Workspace-symbol requests are not supported by this server.");
     }
-    return this.query("workspace/symbol", { query });
+    return this.query("workspace/symbol", { query }, control);
   }
 
   async rename(
     filePath: string,
     position: Position,
     newName: string,
+    control?: CodeRequestControl,
   ): Promise<WorkspaceEdit | null> {
-    return this.request("textDocument/rename", {
-      textDocument: { uri: fileToUri(filePath) },
-      position,
-      newName,
-    });
+    return this.request(
+      "textDocument/rename",
+      { textDocument: { uri: fileToUri(filePath) }, position, newName },
+      control,
+    );
   }
 
   async codeActions(
     filePath: string,
     range: Range,
     context: CodeActionContext,
+    control?: CodeRequestControl,
   ): Promise<CodeAction[] | null> {
-    return this.request("textDocument/codeAction", {
-      textDocument: { uri: fileToUri(filePath) },
-      range,
-      context,
-    });
+    return this.request(
+      "textDocument/codeAction",
+      { textDocument: { uri: fileToUri(filePath) }, range, context },
+      control,
+    );
   }
 
   async implementation(
     filePath: string,
     position: Position,
+    control?: CodeRequestControl,
   ): Promise<CodeQueryResult<Location | Location[] | LocationLink[] | null>> {
     if (!this.capabilities?.implementationProvider) {
       return unavailableCodeQuery("Implementation requests are not supported by this server.");
     }
-    return this.query("textDocument/implementation", {
-      textDocument: { uri: fileToUri(filePath) },
-      position,
-    });
+    return this.query(
+      "textDocument/implementation",
+      { textDocument: { uri: fileToUri(filePath) }, position },
+      control,
+    );
   }
 
   // ── Private ─────────────────────────────────────────────────────────
-  private async query<T>(method: string, params: unknown): Promise<CodeQueryResult<T | null>> {
+  private async query<T>(
+    method: string,
+    params: unknown,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<T | null>> {
+    // An already-cancelled caller gets the interruption, not an unavailable
+    // outcome that could mask the cancellation.
+    throwIfCodeRequestInterrupted(control);
     if (!this.rpc || this._status !== "running") {
       return unavailableCodeQuery(
         `LSP request ${method} is unavailable because the client is not running.`,
       );
     }
     try {
-      await this.getReady();
-      const data = (await this.rpc.sendRequest(method, params)) as T | null | undefined;
+      await this.getReady(control);
+      const data = (await this.rpc.sendRequest(method, params, control)) as T | null | undefined;
       return completedCodeQuery(data ?? null);
     } catch (error) {
+      // Cancellation and absolute-deadline expiry propagate as interruptions:
+      // the caller no longer awaits a result, so no unavailable outcome may
+      // mask the cancellation.
+      if (isCodeRequestInterruption(error, control)) throw error;
       const detail = error instanceof Error ? error.message : String(error);
       return unavailableCodeQuery(`LSP request ${method} failed: ${detail}`);
     }
   }
 
-  private async request<T>(method: string, params: unknown): Promise<T | null> {
-    const result = await this.query<T>(method, params);
+  private async request<T>(
+    method: string,
+    params: unknown,
+    control?: CodeRequestControl,
+  ): Promise<T | null> {
+    const result = await this.query<T>(method, params, control);
     return result.kind === "unavailable" ? null : result.data;
   }
 
@@ -457,23 +704,22 @@ export class LspClient {
       case "workspace/workspaceFolders":
         return [{ uri: fileToUri(this.root), name: path.basename(this.root) || this.root }];
       case "client/registerCapability":
+        return this.handleRegisterCapability(params);
       case "client/unregisterCapability":
+        return this.handleUnregisterCapability(params);
+      case "workspace/diagnostic/refresh":
+        // The client does not advertise refresh support, but pyright sends
+        // this request anyway when a document opens in pull mode. Answering
+        // with an error crashes pyright (exit 1); answering null keeps the
+        // server alive and pull-on-demand still serves fresh diagnostics.
         return null;
       case "window/workDoneProgress/create": {
+        // A create reserves a token; it does not prove active work. The
+        // token stays pending and readiness is untouched until a begin
+        // arrives, so an unused token never causes false readiness loss.
         const token = (params as { token: ProgressToken }).token;
-        this.trackedTokens.set(token, "begin-seen");
-        this.cancelNoProgressTimer();
-        this._isReady = false;
-        if (!this._readyPromise) {
-          this._readyPromise = new Promise<void>((resolve, reject) => {
-            this._readyResolve = resolve;
-            this._readyReject = reject;
-          });
-          // Prevent unhandled rejection when rejectReady fires before any
-          // consumer is actively awaiting this promise (e.g. during shutdown).
-          this._readyPromise.catch(() => {});
-        }
-        this.startTokenTimeout(token);
+        this.trackedTokens.set(token, "created");
+        this.tokenCreatedAt.set(token, Date.now());
         return null;
       }
       default:
@@ -488,8 +734,52 @@ export class LspClient {
     return items.map(() => null);
   }
 
+  /**
+   * Apply a dynamic registration for `textDocument/diagnostic`.
+   *
+   * Registrations for other methods are ignored (status quo). Malformed
+   * params or malformed diagnostic registration options reject the request
+   * without enabling pull, so a server never gets pull requests it did not
+   * validly register for.
+   */
+  private handleRegisterCapability(params: unknown): null {
+    const registrations = readRegistrations(params, "client/registerCapability");
+    for (const registration of registrations) {
+      if (registration.method !== DOCUMENT_DIAGNOSTIC_METHOD) continue;
+      if (!isValidDiagnosticOptions(registration.registerOptions)) {
+        throw new JsonRpcRequestError(
+          -32602,
+          "Malformed textDocument/diagnostic registration options.",
+        );
+      }
+      this.dynamicRegistrations.register(registration.method, registration.id);
+    }
+    return null;
+  }
+
+  /**
+   * Remove dynamic registrations for `textDocument/diagnostic`.
+   *
+   * The params key is the LSP specification's documented compatibility typo
+   * `unregisterations` (renamed to `unregistrations` only in a future 4.x).
+   * Capability loss disables pull as soon as the last id is removed.
+   */
+  private handleUnregisterCapability(params: unknown): null {
+    if (!isRecord(params) || !Array.isArray(params.unregisterations)) {
+      throw new JsonRpcRequestError(-32602, "Malformed client/unregisterCapability params.");
+    }
+    for (const entry of params.unregisterations) {
+      if (!isRecord(entry) || typeof entry.id !== "string" || typeof entry.method !== "string") {
+        throw new JsonRpcRequestError(-32602, "Malformed client/unregisterCapability entry.");
+      }
+      if (entry.method !== DOCUMENT_DIAGNOSTIC_METHOD) continue;
+      this.dynamicRegistrations.unregister(entry.method, entry.id);
+    }
+    return null;
+  }
+
   /** Apply a diagnostic publication received from the LSP transport. */
-  handlePublishDiagnostics(params: PublishDiagnosticsParams): void {
+  handlePublishDiagnostics(params: unknown): void {
     this.diagnostics.handlePublishDiagnostics(params);
   }
 
@@ -499,9 +789,17 @@ export class LspClient {
    * Wait for the server to be ready to serve queries.
    * Returns immediately if already ready; returns the ongoing promise
    * if one is pending; creates and returns a new one otherwise.
+   * With request control, the caller's wait stops promptly on abort or
+   * deadline while the shared readiness state keeps its own lifecycle.
    */
-  async getReady(): Promise<void> {
-    if (this._isReady) return;
+  async getReady(control?: CodeRequestControl): Promise<void> {
+    const pending = this.pendingReady();
+    if (!control) return pending;
+    return raceRequestControl(pending, control);
+  }
+
+  private pendingReady(): Promise<void> {
+    if (this._isReady) return Promise.resolve();
     if (this._readyPromise !== null) return this._readyPromise;
     // If no progress timer was ever armed and no tokens are tracked,
     // the server was either never started with a real process (test scenario)
@@ -509,8 +807,11 @@ export class LspClient {
     // only when the client is still running — a crash or shutdown clears
     // both fields but must not report the client as ready.
     if (this.noProgressTimer === null && this.trackedTokens.size === 0) {
-      if (this._status === "running") this._isReady = true;
-      return;
+      if (this._status === "running") {
+        this._isReady = true;
+        this.everReady = true;
+      }
+      return Promise.resolve();
     }
     this._readyPromise = new Promise<void>((resolve, reject) => {
       this._readyResolve = resolve;
@@ -533,14 +834,20 @@ export class LspClient {
         source: "lsp",
         level: "debug",
         category: "readiness.progress-begin",
-        message: `Readiness progress begin for token ${token}`,
-        data: { token },
+        message: `Readiness progress begin for ${this.name}`,
+        cwd: boundCwd(this.cwd),
+        data: { server: this.name, root: truncateIdentity(this.root) },
       });
-      // Cancel the 2s no-progress grace timer — a server that sends
-      // begin without a prior create is spec-deviant but valid.
+      // begin is the only transition that proves active work: it cancels
+      // the no-progress grace timer, blocks readiness, and arms the
+      // bounded per-token timeout. A server that sends begin without a
+      // prior create is spec-deviant but valid.
       this.cancelNoProgressTimer();
-      this.trackedTokens.set(token, "begin-seen");
+      this.trackedTokens.set(token, "active");
+      this.tokenCreatedAt.delete(token);
+      const wasReady = this._isReady;
       this._isReady = false;
+      if (wasReady) this.publishLifecycle("readiness");
       // Re-arm readiness promise if not already pending
       if (!this._readyPromise) {
         this._readyPromise = new Promise<void>((resolve, reject) => {
@@ -557,22 +864,36 @@ export class LspClient {
         source: "lsp",
         level: "debug",
         category: "readiness.progress-end",
-        message: `Readiness progress end for token ${token}`,
-        data: { token },
+        message: `Readiness progress end for ${this.name}`,
+        cwd: boundCwd(this.cwd),
+        data: { server: this.name, root: truncateIdentity(this.root) },
       });
+      const state = this.trackedTokens.get(token);
+      if (state === undefined) return; // Unknown token: ignore fail-closed.
+      this.tokenCreatedAt.delete(token);
+      if (state === "created") {
+        // A pending token never blocked readiness; its end removes it.
+        this.trackedTokens.delete(token);
+        return;
+      }
       this.trackedTokens.set(token, "ended");
       this.clearTokenTimeout(token);
       this.checkAllTokensEnded();
     }
-    // kind: "report" — intentionally no-op
+    // kind: "report" — intentionally no-op; active state is retained.
   }
 
-  /** Check whether all tracked tokens have ended and resolve readiness. */
-  private checkAllTokensEnded(): void {
-    if (this.trackedTokens.size === 0) return;
+  /** Test whether any token has active (begun) work. */
+  private hasActiveTokens(): boolean {
     for (const state of this.trackedTokens.values()) {
-      if (state !== "ended") return;
+      if (state === "active") return true;
     }
+    return false;
+  }
+
+  /** Resolve readiness when no token is active; pending tokens do not block. */
+  private checkAllTokensEnded(): void {
+    if (this.hasActiveTokens()) return;
     this.trackedTokens.clear();
     this.resolveReady();
   }
@@ -585,15 +906,35 @@ export class LspClient {
       this._readyResolve = undefined;
       this._readyReject = undefined;
     }
+    // A rejected or disposed client must never be marked ready again,
+    // even if a stray progress end arrives after the rejection.
+    if (this._status !== "running") return;
+    const becameReady = !this._isReady;
     this._isReady = true;
+    if (becameReady) this.everReady = true;
+    if (becameReady) this.publishLifecycle("readiness");
     recordDebugEvent({
       source: "lsp",
       level: "info",
       category: "readiness.resolved",
-      message: `LSP client ${this.name} is ready (cwd: ${this.root})`,
+      message: `LSP client ${this.name} is ready`,
+      cwd: boundCwd(this.cwd),
+      data: { server: this.name, root: truncateIdentity(this.root) },
     });
   }
 
+  /**
+   * Tear down readiness state without a protocol shutdown.
+   *
+   * Clears pending and active progress tokens and rejects any pending
+   * readiness. Called when a client is discarded or its observer is
+   * disposed so token state cannot outlive the client.
+   */
+  dispose(): void {
+    this.cancelNoProgressTimer();
+    this.dynamicRegistrations.clear();
+    this.rejectReady(new Error("Client disposed"));
+  }
   /**
    * Reject the current readiness promise (if any) and mark the client
    * not ready. Called on shutdown, crash, or restart.
@@ -607,6 +948,7 @@ export class LspClient {
     }
     this._isReady = false;
     this.trackedTokens.clear();
+    this.tokenCreatedAt.clear();
     for (const timer of this.tokenTimeouts.values()) clearTimeout(timer);
     this.tokenTimeouts.clear();
     recordDebugEvent({
@@ -614,7 +956,12 @@ export class LspClient {
       level: this._status === "shutdown" ? "debug" : "warning",
       category: "readiness.rejected",
       message: `LSP client ${this.name} readiness rejected: ${reason.message}`,
-      data: { status: this._status },
+      cwd: boundCwd(this.cwd),
+      data: {
+        server: this.name,
+        root: truncateIdentity(this.root),
+        status: this._status,
+      },
     });
   }
 
@@ -634,8 +981,9 @@ export class LspClient {
         source: "lsp",
         level: "debug",
         category: "readiness.token-timeout",
-        message: `Readiness per-token timeout fired for token ${token} after ${timeoutMs}ms`,
-        data: { token, timeoutMs },
+        message: `Readiness per-token timeout fired for ${this.name} after ${timeoutMs}ms`,
+        cwd: boundCwd(this.cwd),
+        data: { server: this.name, root: truncateIdentity(this.root), timeoutMs },
       });
       this.checkAllTokensEnded();
     }, timeoutMs);
@@ -661,6 +1009,8 @@ export class LspClient {
         level: "debug",
         category: "readiness.no-progress-cancelled",
         message: `No-progress grace timer cancelled for ${this.name}`,
+        cwd: boundCwd(this.cwd),
+        data: { server: this.name, root: truncateIdentity(this.root) },
       });
     }
   }
@@ -676,12 +1026,14 @@ export class LspClient {
    */
   private armNoProgressTimer(): void {
     this.noProgressTimer = setTimeout(() => {
-      if (this.trackedTokens.size === 0 && this._status === "running") {
+      if (!this.hasActiveTokens() && this._status === "running") {
         recordDebugEvent({
           source: "lsp",
           level: "debug",
           category: "readiness.no-progress-resolved",
           message: `No-progress grace timer resolved for ${this.name}`,
+          cwd: boundCwd(this.cwd),
+          data: { server: this.name, root: truncateIdentity(this.root) },
         });
         this.resolveReady();
       }