@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.0

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

@@ -6,8 +6,20 @@ type DiagnosticCollection = "cache" | "fallback" | "none" | "pull" | "push";
 type DiagnosticFreshness = "not-observed" | "observed";
 type DiagnosticOutcome = "completed" | "incomplete" | "skipped" | "timed-out";
 type DiagnosticPullOutcome = "completed" | "failed" | "not-supported" | "not-used" | "timed-out";
-type DiagnosticPushOutcome = "not-used" | "published" | "released" | "settled" | "timed-out";
-type DiagnosticSettleOutcome = "not-used" | "published" | "quiet" | "released" | "timed-out";
+type DiagnosticPushOutcome =
+  | "not-used"
+  | "published"
+  | "tentative"
+  | "released"
+  | "settled"
+  | "timed-out";
+type DiagnosticSettleOutcome =
+  | "not-used"
+  | "published"
+  | "tentative"
+  | "quiet"
+  | "released"
+  | "timed-out";
 type DiagnosticTimingOperation = "refresh-open" | "sync-file";
 
 /** Result of waiting for a quiet push-diagnostic window. */
@@ -17,7 +29,7 @@ export interface DiagnosticSettleResult {
 }
 
 /** Result of waiting for one file's push diagnostics. */
-export type DiagnosticPushWaitOutcome = "published" | "released" | "timed-out";
+export type DiagnosticPushWaitOutcome = "published" | "tentative" | "released" | "timed-out";
 
 interface DiagnosticTimingData {
   readonly collection: DiagnosticCollection;
@@ -134,10 +146,15 @@ export class DiagnosticObserver {
     this.#timer.mark("pull");
   }
 
-  /** Record that the reopen-resync fallback re-opened unconfirmed documents. */
+  /**
+   * Record that the reopen-resync fallback re-opened unconfirmed documents.
+   *
+   * The mark fires when the second settle window starts, so the measured
+   * phase is the preceding first settle window, not the reopen work.
+   */
   reopened(count: number): void {
     this.#reopened += count;
-    this.#timer.mark("reopen");
+    this.#timer.mark("first-settle");
   }
 
   pushSettled(documentCount: number, settle: DiagnosticSettleResult): void {
@@ -161,14 +178,18 @@ export class DiagnosticObserver {
   }
 
   pushWaitCompleted(documentCount: number, push: DiagnosticPushWaitOutcome): void {
-    const timedOut = push === "timed-out";
+    const confirmed = push === "published";
+    // A tentative result used the full wait budget without a confirming
+    // republish. Keep its distinct push value and report the budget expiry.
+    const timedOut = push === "tentative" || push === "timed-out";
+    const observed = push === "published" || push === "tentative";
     this.#finish(
       {
         collection: this.supportsPull ? "fallback" : "push",
         documentCount,
         fallback: this.supportsPull,
-        freshness: push === "published" ? "observed" : "not-observed",
-        outcome: push === "published" ? "completed" : timedOut ? "timed-out" : "incomplete",
+        freshness: observed ? "observed" : "not-observed",
+        outcome: confirmed ? "completed" : timedOut ? "timed-out" : "incomplete",
         pull: this.#pull,
         push,
         reopen: this.#reopened,

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

@@ -15,12 +15,17 @@ import { collectSynchronizedFileDiagnostics } from "./client-diagnostic-collecti
 import {
   type DiagnosticCacheEntry,
   type DiagnosticSynchronization,
+  hasCurrentEvidence,
   hasFreshPush,
   isCurrentSynchronization,
   isValidPublishDiagnosticsParams,
   nextDocumentVersion,
 } from "./client-diagnostic-evidence.ts";
 import type { ClientDiagnosticsHost } from "./client-diagnostic-host.ts";
+import {
+  DiagnosticPublicationTracker,
+  trackerFileIdentityFor,
+} from "./client-diagnostic-publication.ts";
 import {
   pullClientDiagnosticEvidenceFromHost,
   refreshClientOpenDiagnostics,
@@ -32,7 +37,7 @@ import {
   type ClientDiagnosticSnapshot,
   type DiagnosticEntry,
   fingerprintDocumentContent,
-  hasCurrentDiagnosticEvidence,
+  hasConfirmedDiagnosticEvidence,
   type OpenDocumentState,
 } from "./client-document-state.ts";
 import {
@@ -52,6 +57,8 @@ export class ClientDiagnostics {
   readonly #waiters = new DiagnosticWaitRegistry();
   readonly #versionHistory = new Map<string, number>();
   readonly #failedUris = new Set<string>();
+  /** Bounded push-publication telemetry for one client's diagnostic state. */
+  readonly #publications: DiagnosticPublicationTracker;
   /** Client-side sync moment per URI: unversioned pushes before it stay rejected. */
   readonly #unversionedPushSyncMoments = new Map<string, number>();
   /** URIs closed by a lifecycle operation: versioned pushes stay fail-closed. */
@@ -59,7 +66,12 @@ export class ClientDiagnostics {
   #evidenceRevision = 0;
   #nextSynchronizationId = 0;
 
-  constructor(private readonly host: ClientDiagnosticsHost) {}
+  constructor(private readonly host: ClientDiagnosticsHost) {
+    this.#publications = new DiagnosticPublicationTracker(
+      { server: host.server, cwd: host.cwd },
+      trackerFileIdentityFor(host.cwd),
+    );
+  }
 
   get openFiles(): string[] {
     return Array.from(this.#openDocs.keys()).map(uriToFile);
@@ -105,6 +117,7 @@ export class ClientDiagnostics {
       version,
       synchronizationId: ++this.#nextSynchronizationId,
       evidenceRevision: this.#evidenceRevision,
+      content,
       contentFingerprint: fingerprintDocumentContent(content),
     });
     this.host.sendNotification("textDocument/didOpen", {
@@ -135,6 +148,7 @@ export class ClientDiagnostics {
       nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
       nextSynchronizationId: () => ++this.#nextSynchronizationId,
       evidenceRevision: this.#evidenceRevision,
+      incrementalSync: this.host.usesIncrementalDocumentSync(),
       waiters: this.#waiters,
       sendNotification: (method, params) => this.host.sendNotification(method, params),
       markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
@@ -157,7 +171,11 @@ export class ClientDiagnostics {
   }
 
   pruneMissingFiles(): string[] {
-    const uris = new Set([...this.#openDocs.keys(), ...this.#diagnosticStore.keys()]);
+    const uris = new Set([
+      ...this.#openDocs.keys(),
+      ...this.#diagnosticStore.keys(),
+      ...this.#failedUris,
+    ]);
     const removedFiles: string[] = [];
 
     for (const uri of uris) {
@@ -165,7 +183,7 @@ export class ClientDiagnostics {
       if (getDiagnosticFileState(filePath) !== "removed") continue;
 
       const wasOpen = this.#openDocs.has(uri);
-      this.#failedUris.add(uri);
+      this.#failedUris.delete(uri);
       this.#unversionedPushSyncMoments.delete(uri);
       this.#closedVersionedBarrier.add(uri);
       clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
@@ -224,23 +242,49 @@ export class ClientDiagnostics {
 
   handlePublishDiagnostics(params: unknown): void {
     if (!isValidPublishDiagnosticsParams(params)) return;
-    if (
-      !applyPushDiagnostics({
-        store: this.#diagnosticStore,
-        openDocuments: this.#openDocs,
-        params,
-        evidenceRevision: this.#evidenceRevision,
-        unversionedSyncMoment: this.#unversionedPushSyncMoments.get(params.uri),
-        closedVersionedBarrier: this.#closedVersionedBarrier.has(params.uri),
-      })
-    ) {
-      return;
+    const result = applyPushDiagnostics({
+      store: this.#diagnosticStore,
+      openDocuments: this.#openDocs,
+      params,
+      evidenceRevision: this.#evidenceRevision,
+      unversionedSyncMoment: this.#unversionedPushSyncMoments.get(params.uri),
+      closedVersionedBarrier: this.#closedVersionedBarrier.has(params.uri),
+    });
+    if (!result.accepted) return;
+    const entry = this.#diagnosticStore.get(params.uri);
+    if (entry?.synchronizationId !== undefined && entry.evidenceRevision !== undefined) {
+      this.#publications.record(
+        params.uri,
+        entry.synchronizationId,
+        entry.evidenceRevision,
+        entry.receivedAt,
+      );
+      if (result.promoted) {
+        this.#publications.promoted(
+          params.uri,
+          entry.synchronizationId,
+          entry.evidenceRevision,
+          entry.receivedAt,
+        );
+      }
     }
     this.#waiters.releaseFile(params.uri, "published");
     this.#waiters.notifySettle();
   }
   async refreshOpenDiagnostics(
     options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl = {},
+  ): Promise<DiagnosticEvidenceSummary> {
+    return this.#refreshOpenDiagnostics(options, false);
+  }
+
+  /** Force a full document resynchronization for a server refresh request. */
+  async refreshForServerRequest(): Promise<DiagnosticEvidenceSummary> {
+    return this.#refreshOpenDiagnostics({}, true);
+  }
+
+  async #refreshOpenDiagnostics(
+    options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl,
+    forceResynchronize: boolean,
   ): Promise<DiagnosticEvidenceSummary> {
     const requestedFiles = Array.from(
       new Set([...this.#openDocs.keys(), ...this.#diagnosticStore.keys(), ...this.#failedUris]),
@@ -262,14 +306,26 @@ export class ClientDiagnostics {
         if (document) document.evidenceRevision = -1;
       },
       clearFile: (uri) => {
-        this.#failedUris.add(uri);
+        this.#failedUris.delete(uri);
         this.#unversionedPushSyncMoments.delete(uri);
         this.#closedVersionedBarrier.add(uri);
         clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
       },
       markUnversionedSyncMoment: (uri) => this.#unversionedPushSyncMoments.set(uri, Date.now()),
       clearFailedFile: (uri) => this.#failedUris.delete(uri),
+      forceResynchronize,
       options,
+      publications: {
+        emitSummary: (summaryOptions) =>
+          this.#publications.emitSummary({
+            ...summaryOptions,
+            identity: {
+              server: this.host.server,
+              cwd: this.host.cwd,
+              ...summaryOptions.identity,
+            },
+          }),
+      },
     });
   }
 
@@ -296,8 +352,9 @@ export class ClientDiagnostics {
     const contentUnchanged =
       openDocument?.contentFingerprint === fingerprintDocumentContent(content);
     const synchronizationCurrent = openDocument?.evidenceRevision === this.#evidenceRevision;
-    const cacheCurrent = hasCurrentDiagnosticEvidence(openDocument, cached, this.#evidenceRevision);
-    if (!contentUnchanged || !synchronizationCurrent || (cached !== undefined && !cacheCurrent)) {
+    // Equivalent content joins the current synchronization. Cached evidence
+    // cannot force a no-op didChange that cancels an in-flight push or pull.
+    if (!contentUnchanged || !synchronizationCurrent) {
       synchronizeTrackedDocument({
         uri,
         content,
@@ -305,6 +362,7 @@ export class ClientDiagnostics {
         nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
         nextSynchronizationId: () => ++this.#nextSynchronizationId,
         evidenceRevision: this.#evidenceRevision,
+        incrementalSync: this.host.usesIncrementalDocumentSync(),
         waiters: this.#waiters,
         sendNotification: (method, params) => this.host.sendNotification(method, params),
         markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
@@ -319,7 +377,7 @@ export class ClientDiagnostics {
     }
     if (
       contentUnchanged &&
-      hasCurrentDiagnosticEvidence(synchronization, cached, this.#evidenceRevision)
+      hasConfirmedDiagnosticEvidence(synchronization, cached, this.#evidenceRevision)
     ) {
       observer.cacheReused(1);
       return completedCodeQuery(cachedDiagnostics ?? []);
@@ -390,6 +448,13 @@ export class ClientDiagnostics {
           current: () => isCurrentSynchronization(this.#openDocs, attemptRequest),
           freshPush: () =>
             hasFreshPush(this.#diagnosticStore, attemptRequest, this.#evidenceRevision),
+          currentPushReceivedAt: () => {
+            const entry = this.#diagnosticStore.get(attemptRequest.uri);
+            return entry?.source === "push" &&
+              hasCurrentEvidence(this.#diagnosticStore, attemptRequest, this.#evidenceRevision)
+              ? entry.receivedAt
+              : undefined;
+          },
           diagnostics: () => this.getDiagnostics(filePath),
           pullDiagnostics: (timeoutMs, signal) =>
             pullClientDiagnosticEvidenceFromHost({
@@ -454,6 +519,23 @@ export class ClientDiagnostics {
       attemptMaxWaitMs = REOPEN_EVIDENCE_WAIT_MS;
     }
     observer.pushWaitCompleted(1, pushOutcome ?? "timed-out");
+    this.#publications.emitSummary({
+      operation: "sync-file",
+      identity: {
+        server: this.host.server,
+        cwd: this.host.cwd,
+        file: relativeDiagnosticFile(this.host.cwd, filePath),
+      },
+      synchronizations: [
+        {
+          uri,
+          synchronizationId: attemptRequest.synchronizationId,
+          evidenceRevision: attemptRequest.evidenceRevision ?? this.#evidenceRevision,
+          confirmed: result.kind === "completed",
+        },
+      ],
+      operationId: control?.operationId,
+    });
     return result;
   }
 }

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

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { Diagnostic } from "../config/types.ts";
-import type { DiagnosticCacheEntry } from "./client-diagnostic-evidence.ts";
+import { type DiagnosticCacheEntry, isTentativePushEntry } from "./client-diagnostic-evidence.ts";
 
 /** One file's stored diagnostics as consumed by manager-level collection. */
 export interface DiagnosticEntry {
@@ -28,6 +28,8 @@ export interface OpenDocumentState {
   version: number;
   synchronizationId: number;
   evidenceRevision: number;
+  /** Last text sent to the server. Used to form incremental changes. */
+  content: string;
   contentFingerprint: string;
 }
 
@@ -50,3 +52,19 @@ export function hasCurrentDiagnosticEvidence(
       entry.evidenceRevision === evidenceRevision,
   );
 }
+
+/**
+ * Test whether cached diagnostics confirm the current document state.
+ *
+ * A current tentative push matches the document state but cannot support a
+ * clean-result or cache-reuse claim until a republish confirms it (ADR 0021).
+ */
+export function hasConfirmedDiagnosticEvidence(
+  document: OpenDocumentState | undefined,
+  entry: DiagnosticCacheEntry | undefined,
+  evidenceRevision: number,
+): boolean {
+  return (
+    hasCurrentDiagnosticEvidence(document, entry, evidenceRevision) && !isTentativePushEntry(entry)
+  );
+}

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

@@ -14,10 +14,39 @@ interface SynchronizeDocumentOptions {
   version: number;
   synchronizationId: number;
   evidenceRevision: number;
+  incrementalSync: boolean;
   waiters: DiagnosticWaitRegistry;
   sendNotification: NotificationSender;
 }
 
+function endPosition(content: string): { line: number; character: number } {
+  const lines = content.split(/\r\n|\r|\n/);
+  return { line: lines.length - 1, character: lines.at(-1)?.length ?? 0 };
+}
+
+/**
+ * For incremental sync, replace the old full range with the new text.
+ * This is a valid incremental edit and avoids a second text-diff engine.
+ */
+function contentChanges(
+  previousContent: string,
+  content: string,
+  incrementalSync: boolean,
+): unknown[] {
+  if (incrementalSync) {
+    return [
+      {
+        range: {
+          start: { line: 0, character: 0 },
+          end: endPosition(previousContent),
+        },
+        text: content,
+      },
+    ];
+  }
+  return [{ text: content }];
+}
+
 /** Advance and publish one explicit document synchronization. */
 export function synchronizeDocument(options: SynchronizeDocumentOptions): void {
   options.waiters.releaseFile(options.uri);
@@ -25,13 +54,19 @@ export function synchronizeDocument(options: SynchronizeDocumentOptions): void {
   options.document.version = options.version;
   options.document.synchronizationId = options.synchronizationId;
   options.document.evidenceRevision = options.evidenceRevision;
+  const changes = contentChanges(
+    options.document.content,
+    options.content,
+    options.incrementalSync,
+  );
+  options.document.content = options.content;
   options.document.contentFingerprint = fingerprintDocumentContent(options.content);
   options.sendNotification("textDocument/didChange", {
     textDocument: {
       uri: options.uri,
       version: options.version,
     } satisfies VersionedTextDocumentIdentifier,
-    contentChanges: [{ text: options.content }],
+    contentChanges: changes,
   });
 }
 
@@ -74,6 +109,7 @@ export function reopenDocument(options: {
   options.document.version = version;
   options.document.synchronizationId = options.nextSynchronizationId();
   options.document.evidenceRevision = options.evidenceRevision;
+  options.document.content = options.content;
   options.document.contentFingerprint = fingerprintDocumentContent(options.content);
   options.sendNotification("textDocument/didOpen", {
     textDocument: {
@@ -93,6 +129,7 @@ export function synchronizeTrackedDocument(options: {
   nextVersion(): number;
   nextSynchronizationId(): number;
   evidenceRevision: number;
+  incrementalSync: boolean;
   waiters: DiagnosticWaitRegistry;
   sendNotification: NotificationSender;
   markUnversionedSyncMoment?(): void;
@@ -111,6 +148,7 @@ export function synchronizeTrackedDocument(options: {
     version: options.nextVersion(),
     synchronizationId: options.nextSynchronizationId(),
     evidenceRevision: options.evidenceRevision,
+    incrementalSync: options.incrementalSync,
     waiters: options.waiters,
     sendNotification: options.sendNotification,
   });
@@ -123,8 +161,11 @@ interface ResynchronizeDocumentsOptions {
   nextVersion(uri: string): number;
   nextSynchronizationId(): number;
   evidenceRevision: number;
+  incrementalSync: boolean;
   sendNotification: NotificationSender;
   uriToFile(uri: string): string;
+  /** Disk content already read by classification; avoids a second read. */
+  preloadedContent?: ReadonlyMap<string, string>;
   clearFile(uri: string): void;
   invalidateEvidence(uri: string): void;
   markUnversionedSyncMoment(uri: string): void;
@@ -135,6 +176,8 @@ interface ResynchronizeDocumentsOptions {
 export interface ResynchronizeDocumentsResult {
   /** Documents that were synchronized and can receive fresh evidence. */
   synchronizations: DiagnosticSynchronization[];
+  /** URIs that received a new didChange synchronization in this pass. */
+  resynchronizedUris: ReadonlySet<string>;
   /** Existing tracked documents removed because their files no longer exist. */
   removedFiles: string[];
   /** Existing tracked documents that could not be read or synchronized. */
@@ -146,6 +189,7 @@ export function resynchronizeOpenDocuments(
   options: ResynchronizeDocumentsOptions,
 ): ResynchronizeDocumentsResult {
   const synchronizations: DiagnosticSynchronization[] = [];
+  const resynchronizedUris = new Set<string>();
   const removedFiles: string[] = [];
   const failedFiles: string[] = [];
   for (const [uri, document] of options.openDocuments) {
@@ -154,15 +198,17 @@ export function resynchronizeOpenDocuments(
       options.markUnversionedSyncMoment(uri);
       synchronizeDocument({
         uri,
-        content: readFileSync(filePath, "utf-8"),
+        content: options.preloadedContent?.get(uri) ?? readFileSync(filePath, "utf-8"),
         document,
         version: options.nextVersion(uri),
         synchronizationId: options.nextSynchronizationId(),
         evidenceRevision: options.evidenceRevision,
+        incrementalSync: options.incrementalSync,
         waiters: options.waiters,
         sendNotification: options.sendNotification,
       });
       options.clearFailedFile(uri);
+      resynchronizedUris.add(uri);
       synchronizations.push({
         uri,
         synchronizationId: document.synchronizationId,
@@ -181,5 +227,5 @@ export function resynchronizeOpenDocuments(
       // Keep the document open when a transient read fails.
     }
   }
-  return { synchronizations, removedFiles, failedFiles };
+  return { synchronizations, resynchronizedUris, removedFiles, failedFiles };
 }

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

@@ -13,7 +13,7 @@ import {
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
-import type { ProgressToken } from "vscode-languageserver-protocol";
+import { type ProgressToken, TextDocumentSyncKind } from "vscode-languageserver-protocol";
 import { CLIENT_CAPABILITIES } from "../config/capabilities.ts";
 import type {
   CodeAction,
@@ -198,6 +198,7 @@ export class LspClient {
       cwd: cwd,
       isOperational: () => this.rpc !== null && this._status === "running",
       supportsPullDiagnostics: () => this.hasDiagnosticProvider,
+      usesIncrementalDocumentSync: () => this.usesIncrementalDocumentSync,
       sendNotification: (method, params) => {
         if (this.rpc) void this.rpc.sendNotification(method, params);
       },
@@ -237,6 +238,13 @@ export class LspClient {
     return this.capabilities;
   }
 
+  /** Whether the server requires range-based document changes. */
+  get usesIncrementalDocumentSync(): boolean {
+    const sync = this.capabilities?.textDocumentSync;
+    const change = typeof sync === "number" ? sync : sync?.change;
+    return change === TextDocumentSyncKind.Incremental;
+  }
+
   /** Whether the server is currently not indexing and ready to serve queries. */
   get ready(): boolean {
     return this._isReady;
@@ -262,7 +270,7 @@ export class LspClient {
       this.process = spawn(cmd, args, {
         cwd: this.root,
         stdio: ["pipe", "pipe", "pipe"],
-        env: { ...process.env },
+        env: { ...process.env, ...this.config.env },
         // Run the server in its own process group so we can atomically
         // kill the entire tree (server + subprocesses like tsserver)
         // with `process.kill(-pid, signal)` on Unix or `taskkill /T` on Windows.
@@ -313,6 +321,12 @@ export class LspClient {
       const result = (await this.rpc.sendRequest("initialize", {
         processId: process.pid,
         rootUri: fileToUri(this.root),
+        workspaceFolders: [
+          {
+            uri: fileToUri(this.root),
+            name: path.basename(this.root) || this.root,
+          },
+        ],
         capabilities: CLIENT_CAPABILITIES,
         initializationOptions: this.config.initializationOptions,
       })) as InitializeResult;
@@ -322,7 +336,7 @@ export class LspClient {
         throw new Error(`Server selected unsupported position encoding "${positionEncoding}".`);
       }
       this.capabilities = result.capabilities;
-      void this.rpc.sendNotification("initialized", {});
+      await this.rpc.sendNotification("initialized", {});
       this._status = "running";
       this.publishLifecycle("startup");
 
@@ -708,11 +722,10 @@ export class LspClient {
       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;
+        // Refresh the tracked diagnostic set without blocking the server's
+        // request. The LSP response is always null; the pass records its
+        // terminal result asynchronously for local protocol diagnosis.
+        return this.handleServerDiagnosticRefreshRequest();
       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
@@ -727,6 +740,51 @@ export class LspClient {
     }
   }
 
+  /** Run a server-requested refresh through the forced diagnostic path. */
+  private refreshForServerRequest(): Promise<DiagnosticEvidenceSummary> {
+    return this.diagnostics.refreshForServerRequest();
+  }
+
+  private handleServerDiagnosticRefreshRequest(): null {
+    // Defer the pass before invoking it. Its setup rereads and resynchronizes
+    // tracked documents, so even an async method can otherwise delay the null
+    // response on the JSON-RPC request stack.
+    void Promise.resolve()
+      .then(() => this.refreshForServerRequest())
+      .then(
+        (evidence) => this.recordDiagnosticRefreshRequest("completed", evidence),
+        () => this.recordDiagnosticRefreshRequest("failed"),
+      )
+      // Consume failures from the telemetry callback as well as the pass.
+      .catch(() => {});
+    return null;
+  }
+
+  private recordDiagnosticRefreshRequest(
+    outcome: "completed" | "failed",
+    evidence?: DiagnosticEvidenceSummary,
+  ): void {
+    recordDebugEvent({
+      source: "lsp",
+      level: "debug",
+      category: "diagnostics.refresh-request",
+      message: `LSP diagnostic refresh request ${outcome}`,
+      cwd: boundCwd(this.cwd),
+      data:
+        outcome === "completed" && evidence
+          ? {
+              outcome,
+              server: truncateIdentity(this.name),
+              requested: evidence.requested,
+              confirmed: evidence.confirmed,
+              unconfirmed: evidence.unconfirmed,
+              failed: evidence.failed,
+              removed: evidence.removed,
+            }
+          : { outcome, server: truncateIdentity(this.name) },
+    });
+  }
+
   private buildWorkspaceConfigurationResult(params: unknown): unknown[] {
     if (!params || typeof params !== "object") return [];
     const items = (params as { items?: unknown }).items;
@@ -836,7 +894,7 @@ export class LspClient {
         category: "readiness.progress-begin",
         message: `Readiness progress begin for ${this.name}`,
         cwd: boundCwd(this.cwd),
-        data: { server: this.name, root: truncateIdentity(this.root) },
+        data: { server: truncateIdentity(this.name), root: truncateIdentity(this.root) },
       });
       // begin is the only transition that proves active work: it cancels
       // the no-progress grace timer, blocks readiness, and arms the
@@ -866,7 +924,7 @@ export class LspClient {
         category: "readiness.progress-end",
         message: `Readiness progress end for ${this.name}`,
         cwd: boundCwd(this.cwd),
-        data: { server: this.name, root: truncateIdentity(this.root) },
+        data: { server: truncateIdentity(this.name), root: truncateIdentity(this.root) },
       });
       const state = this.trackedTokens.get(token);
       if (state === undefined) return; // Unknown token: ignore fail-closed.
@@ -919,7 +977,7 @@ export class LspClient {
       category: "readiness.resolved",
       message: `LSP client ${this.name} is ready`,
       cwd: boundCwd(this.cwd),
-      data: { server: this.name, root: truncateIdentity(this.root) },
+      data: { server: truncateIdentity(this.name), root: truncateIdentity(this.root) },
     });
   }
 
@@ -958,7 +1016,7 @@ export class LspClient {
       message: `LSP client ${this.name} readiness rejected: ${reason.message}`,
       cwd: boundCwd(this.cwd),
       data: {
-        server: this.name,
+        server: truncateIdentity(this.name),
         root: truncateIdentity(this.root),
         status: this._status,
       },
@@ -983,7 +1041,7 @@ export class LspClient {
         category: "readiness.token-timeout",
         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 },
+        data: { server: truncateIdentity(this.name), root: truncateIdentity(this.root), timeoutMs },
       });
       this.checkAllTokensEnded();
     }, timeoutMs);
@@ -1010,7 +1068,7 @@ export class LspClient {
         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) },
+        data: { server: truncateIdentity(this.name), root: truncateIdentity(this.root) },
       });
     }
   }
@@ -1033,7 +1091,7 @@ export class LspClient {
           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) },
+          data: { server: truncateIdentity(this.name), root: truncateIdentity(this.root) },
         });
         this.resolveReady();
       }