@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.0

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

@@ -0,0 +1,214 @@
+// Bounded push-publication telemetry for one client's diagnostic state.
+//
+// Push-only servers can publish an early result and a later semantic result
+// for one document synchronization (ADR 0021). This tracker records one
+// bounded per-synchronization publication summary per diagnostic operation
+// and one ambient event when a later publication promotes a synchronization
+// that an earlier operation already reported unconfirmed. Events carry only
+// bounded server, workspace, relative-file, synchronization identity, count,
+// and timing data. They never carry diagnostic payloads or source text.
+
+import * as path from "node:path";
+import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
+import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
+import { uriToFile } from "../utils.ts";
+
+/** Maximum tracked synchronizations before the oldest entry is evicted. */
+export const MAX_TRACKED_SYNCHRONIZATIONS = 64;
+
+/** Maximum synchronization entries in one bounded publication summary. */
+export const MAX_SUMMARY_SYNCHRONIZATIONS = 16;
+
+/** Maximum publication count retained for telemetry; 2 means two or more. */
+const MAX_PUBLICATIONS = 2;
+
+/** Bounded identity for one publication telemetry observation. */
+export interface DiagnosticPublicationIdentity {
+  /** Configured server name. */
+  readonly server?: string;
+  /** Absolute workspace root. */
+  readonly cwd?: string;
+  /** Workspace-relative file path; sync-file operations only. */
+  readonly file?: string;
+}
+
+/** One awaited synchronization of a completed diagnostic operation. */
+export interface DiagnosticPublicationSynchronization {
+  readonly uri: string;
+  readonly synchronizationId: number;
+  readonly evidenceRevision: number;
+  readonly confirmed: boolean;
+}
+
+/** One bounded per-synchronization publication summary entry. */
+export interface DiagnosticPublicationSummaryEntry {
+  readonly synchronizationId: number;
+  readonly publications: number;
+  readonly firstReceivedAt: number;
+  readonly lastReceivedAt: number;
+  readonly confirmed: boolean;
+}
+
+interface SynchronizationPublicationState {
+  readonly uri: string;
+  readonly synchronizationId: number;
+  readonly evidenceRevision: number;
+  publications: number;
+  firstReceivedAt: number;
+  lastReceivedAt: number;
+  /** When a finished operation first reported this synchronization unconfirmed. */
+  unconfirmedAt?: number;
+}
+
+function synchronizationKey(
+  uri: string,
+  synchronizationId: number,
+  evidenceRevision: number,
+): string {
+  return `${uri}|${synchronizationId}|${evidenceRevision}`;
+}
+
+/** Track bounded push-publication counts for one LSP client. */
+export class DiagnosticPublicationTracker {
+  readonly #states = new Map<string, SynchronizationPublicationState>();
+
+  constructor(
+    private readonly identity: { server?: string; cwd?: string },
+    private readonly fileFor: (uri: string) => string | undefined,
+  ) {}
+
+  /**
+   * Record one accepted push publication for a synchronization.
+   *
+   * The state map is bounded to {@link MAX_TRACKED_SYNCHRONIZATIONS}; the
+   * oldest tracked synchronization is evicted when the bound is exceeded.
+   */
+  record(
+    uri: string,
+    synchronizationId: number,
+    evidenceRevision: number,
+    receivedAt: number = Date.now(),
+  ): void {
+    const key = synchronizationKey(uri, synchronizationId, evidenceRevision);
+    const existing = this.#states.get(key);
+    if (existing) {
+      existing.publications = Math.min(existing.publications + 1, MAX_PUBLICATIONS);
+      existing.lastReceivedAt = receivedAt;
+      return;
+    }
+    this.#states.set(key, {
+      uri,
+      synchronizationId,
+      evidenceRevision,
+      publications: 1,
+      firstReceivedAt: receivedAt,
+      lastReceivedAt: receivedAt,
+    });
+    if (this.#states.size > MAX_TRACKED_SYNCHRONIZATIONS) {
+      const oldest = this.#states.keys().next().value;
+      if (oldest !== undefined) this.#states.delete(oldest);
+    }
+  }
+
+  /**
+   * Emit one bounded per-synchronization publication summary.
+   *
+   * Synchronizations with no observed push publication are omitted. A
+   * synchronization that ends unconfirmed is marked so a later promotion can
+   * emit the ambient late-republish event.
+   */
+  emitSummary(options: {
+    readonly operation: "refresh-open" | "sync-file";
+    readonly identity: DiagnosticPublicationIdentity;
+    readonly synchronizations: readonly DiagnosticPublicationSynchronization[];
+    readonly operationId?: string;
+  }): void {
+    const entries: DiagnosticPublicationSummaryEntry[] = [];
+    const now = Date.now();
+    for (const synchronization of options.synchronizations) {
+      const state = this.#states.get(
+        synchronizationKey(
+          synchronization.uri,
+          synchronization.synchronizationId,
+          synchronization.evidenceRevision,
+        ),
+      );
+      if (!state) continue;
+      entries.push({
+        synchronizationId: state.synchronizationId,
+        publications: state.publications,
+        firstReceivedAt: state.firstReceivedAt,
+        lastReceivedAt: state.lastReceivedAt,
+        confirmed: synchronization.confirmed,
+      });
+      if (!synchronization.confirmed) state.unconfirmedAt ??= now;
+      else state.unconfirmedAt = undefined;
+    }
+    if (entries.length === 0) return;
+    recordDebugEvent({
+      operationId: options.operationId,
+      source: "lsp",
+      level: "debug",
+      category: "diagnostics.publication",
+      message: "LSP diagnostic publication summary",
+      cwd: boundCwd(options.identity.cwd),
+      data: {
+        operation: options.operation,
+        synchronizations: entries.slice(0, MAX_SUMMARY_SYNCHRONIZATIONS),
+        ...(options.identity.server !== undefined
+          ? { server: truncateIdentity(options.identity.server) }
+          : {}),
+        ...(options.identity.file !== undefined
+          ? { file: truncateIdentity(options.identity.file) }
+          : {}),
+      },
+    });
+  }
+
+  /**
+   * Observe one promotion of a synchronization by a later publication.
+   *
+   * The ambient late-republish event fires only when a finished operation
+   * previously reported the synchronization unconfirmed. The mark is cleared
+   * so one promotion emits at most one event.
+   */
+  promoted(
+    uri: string,
+    synchronizationId: number,
+    evidenceRevision: number,
+    receivedAt: number = Date.now(),
+  ): void {
+    const state = this.#states.get(synchronizationKey(uri, synchronizationId, evidenceRevision));
+    const unconfirmedAt = state?.unconfirmedAt;
+    if (!state || state.publications < 2 || unconfirmedAt === undefined) return;
+    state.unconfirmedAt = undefined;
+    const file = this.fileFor(uri);
+    recordDebugEvent({
+      source: "lsp",
+      level: "debug",
+      category: "diagnostics.publication",
+      message: "LSP diagnostic late republish",
+      cwd: boundCwd(this.identity.cwd),
+      data: {
+        synchronizationId,
+        publications: state.publications,
+        receivedAt,
+        delayMs: Math.max(0, receivedAt - unconfirmedAt),
+        ...(this.identity.server !== undefined
+          ? { server: truncateIdentity(this.identity.server) }
+          : {}),
+        ...(file !== undefined ? { file: truncateIdentity(file) } : {}),
+      },
+    });
+  }
+}
+
+/** Return a workspace-relative diagnostic file path for telemetry identity. */
+export function trackerFileIdentityFor(
+  cwd: string | undefined,
+): (uri: string) => string | undefined {
+  return (uri) => {
+    if (cwd === undefined) return undefined;
+    return path.relative(cwd, path.resolve(cwd, uriToFile(uri)));
+  };
+}

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

@@ -14,14 +14,19 @@ import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
 import {
   type DiagnosticCacheEntry,
   type DiagnosticSynchronization,
+  hasCurrentEvidence,
   hasFreshEvidence,
   hasFreshPush,
   isCurrentSynchronization,
-  latestFreshEvidenceReceivedAt,
+  latestCurrentEvidenceReceivedAt,
   nextDocumentVersion,
   raceDiagnosticPull,
 } from "./client-diagnostic-evidence.ts";
 import type { ClientDiagnosticsHost } from "./client-diagnostic-host.ts";
+import type {
+  DiagnosticPublicationIdentity,
+  DiagnosticPublicationSynchronization,
+} from "./client-diagnostic-publication.ts";
 import { pullDiagnosticEvidence } from "./client-diagnostic-pull.ts";
 import type { DiagnosticPullRequest } from "./client-diagnostic-request.ts";
 import {
@@ -30,7 +35,11 @@ import {
   isDiagnosticTimeout,
 } from "./client-diagnostic-timing.ts";
 import type { DiagnosticStateWait, DiagnosticWaitRegistry } from "./client-diagnostic-waiters.ts";
-import type { OpenDocumentState } from "./client-document-state.ts";
+import {
+  fingerprintDocumentContent,
+  hasConfirmedDiagnosticEvidence,
+  type OpenDocumentState,
+} from "./client-document-state.ts";
 import {
   type ResynchronizeDocumentsResult,
   reopenDocument,
@@ -60,12 +69,15 @@ export function buildDiagnosticRefreshEvidence(options: {
   currentEvidenceRevision: number;
   openDocuments: ReadonlyMap<string, unknown>;
   diagnosticStore: ReadonlyMap<string, DiagnosticCacheEntry>;
+  /** Required quiet time after the latest push for this refresh result. */
+  pushQuietMs?: number;
 }): DiagnosticEvidenceSummary {
   const synchronizationByFile = new Map(
     options.synchronizations.map((item) => [uriToFile(item.uri), item]),
   );
   const removedFiles = new Set(options.resynchronization.removedFiles);
   const failedFiles = new Set(options.resynchronization.failedFiles);
+  const observedAt = Date.now();
   const documents = options.requestedFiles.map((file) => {
     const uri = fileToUri(file);
     const synchronization = synchronizationByFile.get(file);
@@ -84,7 +96,13 @@ export function buildDiagnosticRefreshEvidence(options: {
     }
     if (
       synchronization &&
-      hasFreshEvidence(options.diagnosticStore, synchronization, options.currentEvidenceRevision)
+      hasSettledRefreshEvidence({
+        store: options.diagnosticStore,
+        synchronization,
+        currentEvidenceRevision: options.currentEvidenceRevision,
+        pushQuietMs: options.pushQuietMs,
+        observedAt,
+      })
     ) {
       return { file, status: "confirmed" as const };
     }
@@ -96,6 +114,25 @@ export function buildDiagnosticRefreshEvidence(options: {
   return summarizeDiagnosticEvidence(documents);
 }
 
+/** Test whether fresh evidence can confirm this refresh result. */
+function hasSettledRefreshEvidence(options: {
+  store: ReadonlyMap<string, DiagnosticCacheEntry>;
+  synchronization: DiagnosticSynchronization;
+  currentEvidenceRevision: number;
+  pushQuietMs: number | undefined;
+  observedAt: number;
+}): boolean {
+  if (!hasFreshEvidence(options.store, options.synchronization, options.currentEvidenceRevision)) {
+    return false;
+  }
+  const entry = options.store.get(options.synchronization.uri);
+  return (
+    options.pushQuietMs === undefined ||
+    entry?.source !== "push" ||
+    options.observedAt - entry.receivedAt >= options.pushQuietMs
+  );
+}
+
 /** Pull one document and reject evidence from a stale client generation. */
 export function pullClientDiagnosticEvidence(
   options: Omit<DiagnosticPullRequest, "previousResultId"> & {
@@ -214,6 +251,70 @@ export async function pullDiagnosticsForOpenDocuments(options: {
   }
 }
 
+/**
+ * Classify open documents for a refresh by disk content.
+ *
+ * A document whose disk content still matches its open fingerprint stays in
+ * the server's current state:
+ * - with current evidence it is reusable without document synchronization;
+ * - without current evidence it is retained: it keeps its synchronization and
+ *   collection waits for the server's existing pipeline instead of forcing a
+ *   no-op didChange. Large push-only servers (typescript-language-server)
+ *   skip empty-to-empty publishes, so a no-op didChange of a clean file can
+ *   never confirm — it only invalidates in-progress evidence and restarts
+ *   full-program checks (#344).
+ *
+ * Documents outside the current evidence revision were invalidated by a
+ * workspace change and must resynchronize: their stale revision cannot
+ * produce fresh evidence without an explicit sync (ADR 0020).
+ */
+function classifyReusableDocuments(options: {
+  openDocuments: ReadonlyMap<string, OpenDocumentState>;
+  diagnosticStore: ReadonlyMap<string, DiagnosticCacheEntry>;
+  evidenceRevision: number;
+  failedFiles: ReadonlySet<string>;
+}): {
+  reusableUris: Set<string>;
+  retainedUris: Set<string>;
+  preloadedContent: Map<string, string>;
+} {
+  const reusableUris = new Set<string>();
+  const retainedUris = new Set<string>();
+  const preloadedContent = new Map<string, string>();
+  for (const [uri, document] of options.openDocuments) {
+    const filePath = uriToFile(uri);
+    if (options.failedFiles.has(filePath)) continue;
+    let content: string;
+    try {
+      content = readFileSync(filePath, "utf-8");
+    } catch {
+      // The resynchronization path classifies removed and unreadable files.
+      continue;
+    }
+    if (document.evidenceRevision !== options.evidenceRevision) {
+      // Invalidated generation: the resync didChange re-establishes proof.
+      preloadedContent.set(uri, content);
+      continue;
+    }
+    if (fingerprintDocumentContent(content) !== document.contentFingerprint) {
+      preloadedContent.set(uri, content);
+      continue;
+    }
+    if (
+      hasConfirmedDiagnosticEvidence(
+        document,
+        options.diagnosticStore.get(uri),
+        options.evidenceRevision,
+      )
+    ) {
+      reusableUris.add(uri);
+    } else {
+      retainedUris.add(uri);
+    }
+  }
+  return { reusableUris, retainedUris, preloadedContent };
+}
+
 interface ClientDiagnosticRefreshOptions {
   readonly host: ClientDiagnosticsHost;
   readonly openDocuments: Map<string, OpenDocumentState>;
@@ -229,7 +330,98 @@ interface ClientDiagnosticRefreshOptions {
   readonly invalidateEvidence: (uri: string) => void;
   readonly markUnversionedSyncMoment: (uri: string) => void;
   readonly clearFailedFile: (uri: string) => void;
+  /** Server-requested refreshes bypass normal push-only evidence reuse. */
+  readonly forceResynchronize?: boolean;
   readonly options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl;
+  /** Push-publication telemetry surface for this client. */
+  readonly publications: {
+    emitSummary(options: {
+      readonly operation: "refresh-open";
+      readonly identity: DiagnosticPublicationIdentity;
+      readonly synchronizations: readonly DiagnosticPublicationSynchronization[];
+      readonly operationId?: string;
+    }): void;
+  };
+}
+
+interface PreparedRefreshDocuments {
+  readonly resynchronization: ResynchronizeDocumentsResult;
+  readonly synchronizations: DiagnosticSynchronization[];
+  readonly fullyReusable: boolean;
+}
+
+/** Classify reusable documents, then resynchronize only the remaining set. */
+function prepareRefreshDocuments(
+  options: ClientDiagnosticRefreshOptions,
+  supportsPull: boolean,
+  evidenceRevision: number,
+): PreparedRefreshDocuments {
+  const reuseEnabled = !options.forceResynchronize;
+  const classification = reuseEnabled
+    ? classifyReusableDocuments({
+        openDocuments: options.openDocuments,
+        diagnosticStore: options.diagnosticStore,
+        evidenceRevision,
+        failedFiles: options.failedFiles(),
+      })
+    : undefined;
+  const reusableUris = classification?.reusableUris ?? new Set<string>();
+  const retainedUris = classification?.retainedUris ?? new Set<string>();
+  const documentsToResynchronize = new Map(
+    Array.from(options.openDocuments).filter(
+      ([uri]) => !reusableUris.has(uri) && !retainedUris.has(uri),
+    ),
+  );
+  const resynchronization = resynchronizeOpenDocuments({
+    openDocuments: documentsToResynchronize,
+    waiters: options.waiters,
+    nextVersion: (uri) => nextDocumentVersion(options.versionHistory, uri),
+    nextSynchronizationId: options.nextSynchronizationId,
+    evidenceRevision,
+    incrementalSync: options.host.usesIncrementalDocumentSync(),
+    sendNotification: (method, params) => options.host.sendNotification(method, params),
+    uriToFile,
+    preloadedContent: classification?.preloadedContent,
+    clearFile: options.clearFile,
+    invalidateEvidence: options.invalidateEvidence,
+    markUnversionedSyncMoment: options.markUnversionedSyncMoment,
+    clearFailedFile: options.clearFailedFile,
+  });
+  const reusableSynchronizations: DiagnosticSynchronization[] = [];
+  for (const uri of reusableUris) {
+    const document = options.openDocuments.get(uri);
+    if (!document) continue;
+    reusableSynchronizations.push({
+      uri,
+      synchronizationId: document.synchronizationId,
+      evidenceRevision: document.evidenceRevision,
+    });
+  }
+  // Retained documents keep their current synchronization: settle waits for
+  // the server's existing pipeline without any protocol work.
+  const retainedSynchronizations: DiagnosticSynchronization[] = [];
+  for (const uri of retainedUris) {
+    const document = options.openDocuments.get(uri);
+    if (!document) continue;
+    retainedSynchronizations.push({
+      uri,
+      synchronizationId: document.synchronizationId,
+      evidenceRevision: document.evidenceRevision,
+    });
+  }
+  const synchronizations = [
+    ...reusableSynchronizations,
+    ...retainedSynchronizations,
+    ...resynchronization.synchronizations,
+  ];
+  // Pull-capable routes still request current diagnostics even when every
+  // document synchronization is reusable.
+  const fullyReusable =
+    reuseEnabled &&
+    !supportsPull &&
+    options.openDocuments.size > 0 &&
+    reusableUris.size === options.openDocuments.size;
+  return { resynchronization, synchronizations, fullyReusable };
 }
 
 /** Refresh one client and return exact document evidence for that attempt. */
@@ -259,25 +451,11 @@ export async function refreshClientOpenDiagnostics(
   const maxWaitMs = options.options.maxWaitMs ?? 3_000;
   const quietMs = options.options.quietMs ?? 200;
   const syncStart = Date.now();
-  const resynchronization = resynchronizeOpenDocuments({
-    openDocuments: options.openDocuments,
-    waiters: options.waiters,
-    nextVersion: (uri) => nextDocumentVersion(options.versionHistory, uri),
-    nextSynchronizationId: options.nextSynchronizationId,
-    evidenceRevision: options.evidenceRevision(),
-    sendNotification: (method, params) => options.host.sendNotification(method, params),
-    uriToFile,
-    clearFile: options.clearFile,
-    invalidateEvidence: options.invalidateEvidence,
-    markUnversionedSyncMoment: options.markUnversionedSyncMoment,
-    clearFailedFile: options.clearFailedFile,
-  });
-  let synchronizations = resynchronization.synchronizations;
-  const settleEpoch = options.waiters.settleEpoch;
-  observer.synchronized();
-  const documentCount = synchronizations.length;
+  const prepared = prepareRefreshDocuments(options, supportsPull, options.evidenceRevision());
+  const resynchronization = prepared.resynchronization;
+  let synchronizations = prepared.synchronizations;
   let failedPullUris: ReadonlySet<string> = new Set();
-  const buildEvidence = () =>
+  const buildEvidence = (pushQuietMs?: number) =>
     buildDiagnosticRefreshEvidence({
       requestedFiles: options.requestedFiles,
       resynchronization,
@@ -288,8 +466,19 @@ export async function refreshClientOpenDiagnostics(
       currentEvidenceRevision: options.evidenceRevision(),
       openDocuments: options.openDocuments,
       diagnosticStore: options.diagnosticStore,
+      pushQuietMs,
     });
-  if (documentCount === 0) {
+
+  // A fully reusable push-only refresh has no protocol work to collect.
+  // Preserve the existing cache timing event format and return current evidence.
+  if (prepared.fullyReusable) {
+    observer.cacheReused(synchronizations.length);
+    return buildEvidence();
+  }
+
+  const settleEpoch = options.waiters.settleEpoch;
+  observer.synchronized();
+  if (synchronizations.length === 0) {
     observer.skipped(0);
     return buildEvidence();
   }
@@ -306,60 +495,64 @@ export async function refreshClientOpenDiagnostics(
     if (pull.completed) return buildEvidence();
   }
 
-  let finalSettle = await options.waiters.waitForSettle(
-    {
-      syncStart,
-      maxWaitMs,
-      quietMs,
-      settleEpoch,
-      isComplete: () =>
-        synchronizations.every((item) =>
-          hasFreshEvidence(options.diagnosticStore, item, options.evidenceRevision()),
-        ),
-      latestReceived: () =>
-        latestFreshEvidenceReceivedAt(
-          options.diagnosticStore,
-          synchronizations,
-          options.evidenceRevision(),
-        ),
-    },
-    options.options,
-  );
+  const waitForDiagnosticSettle = (settleStart: number, settleGeneration: number) =>
+    options.waiters.waitForSettle(
+      {
+        syncStart: settleStart,
+        maxWaitMs,
+        quietMs,
+        settleEpoch: settleGeneration,
+        isComplete: () =>
+          synchronizations.every((item) =>
+            hasFreshEvidence(options.diagnosticStore, item, options.evidenceRevision()),
+          ),
+        latestReceived: () =>
+          latestCurrentEvidenceReceivedAt(
+            options.diagnosticStore,
+            synchronizations,
+            options.evidenceRevision(),
+          ),
+      },
+      options.options,
+    );
+
+  let finalSettle = await waitForDiagnosticSettle(syncStart, settleEpoch);
   if (!supportsPull && finalSettle.outcome === "timed-out") {
     const reopen = await reopenUnconfirmedDocuments({
       options,
       synchronizations,
-      maxWaitMs,
-      quietMs,
+      reopenCandidates: resynchronization.resynchronizedUris,
       observer,
     });
     if (reopen.performed) {
       synchronizations = reopen.synchronizations;
-      finalSettle = await options.waiters.waitForSettle(
-        {
-          syncStart: reopen.startedAt,
-          maxWaitMs: reopen.budgetMs,
-          quietMs,
-          settleEpoch: options.waiters.settleEpoch,
-          isComplete: () =>
-            synchronizations.every((item) =>
-              hasFreshEvidence(options.diagnosticStore, item, options.evidenceRevision()),
-            ),
-          latestReceived: () =>
-            latestFreshEvidenceReceivedAt(
-              options.diagnosticStore,
-              synchronizations,
-              options.evidenceRevision(),
-            ),
-        },
-        options.options,
-      );
+      // A large push-only project may still be processing the reopen batch.
+      // The replacement pass uses the same collection budget as the initial pass.
+      finalSettle = await waitForDiagnosticSettle(reopen.startedAt, options.waiters.settleEpoch);
     }
   }
-  observer.pushSettled(documentCount, finalSettle);
+  observer.pushSettled(synchronizations.length, finalSettle);
   // A cancelled settle must not publish evidence the caller no longer awaits.
   throwIfCodeRequestInterrupted(options.options);
-  return buildEvidence();
+  options.publications.emitSummary({
+    operation: "refresh-open",
+    identity: {
+      server: options.host.server,
+      cwd: options.host.cwd,
+    },
+    synchronizations: synchronizations.map((synchronization) => ({
+      uri: synchronization.uri,
+      synchronizationId: synchronization.synchronizationId,
+      evidenceRevision: synchronization.evidenceRevision ?? options.evidenceRevision(),
+      confirmed: hasFreshEvidence(
+        options.diagnosticStore,
+        synchronization,
+        options.evidenceRevision(),
+      ),
+    })),
+    operationId: options.options.operationId,
+  });
+  return buildEvidence(quietMs);
 }
 
 /**
@@ -420,31 +613,38 @@ async function collectPullEvidenceForRefresh(options: {
 }
 
 /**
- * Reopen-resync fallback (R2): on push-only routes an open document that
-
- * stays unconfirmed after the settle window receives no further push — a
- * clean file gets no push on didChange at all. Close and reopen each
- * unconfirmed document so the server publishes on didOpen, then settle
- * again within a bounded second window. The cache entry and version
- * history survive the reopen; other documents keep their server state.
+ * Reopen-resync fallback (R2): on push-only routes a document that was
+ * didChange-synchronized and stays unconfirmed after the settle window may
+ * have been skipped by the server — a clean file gets no push on didChange
+ * at all, but the server publishes on didOpen. Close and reopen each such
+ * document so the server publishes, then settle again within a bounded
+ * second window. The cache entry and version history survive the reopen;
+ * other documents keep their server state.
+ *
+ * Only documents this pass resynchronized are candidates: retained documents
+ * wait for the server's existing pipeline, and reopening them would cancel
+ * in-progress server work without fixing any publish gap (#344).
  */
 async function reopenUnconfirmedDocuments(options: {
   options: ClientDiagnosticRefreshOptions;
   synchronizations: readonly DiagnosticSynchronization[];
-  maxWaitMs: number;
-  quietMs: number;
+  /** URIs that received a didChange in this pass and may need a reopen push. */
+  reopenCandidates: ReadonlySet<string>;
   observer: DiagnosticObserver;
 }): Promise<{
   performed: boolean;
   startedAt: number;
-  budgetMs: number;
   synchronizations: DiagnosticSynchronization[];
 }> {
-  const { options: refresh, synchronizations, maxWaitMs, quietMs, observer } = options;
+  const { options: refresh, synchronizations, reopenCandidates, observer } = options;
   const startedAt = Date.now();
-  const budgetMs = Math.min(maxWaitMs, quietMs * 4);
   const unconfirmed = synchronizations.filter(
-    (item) => !hasFreshEvidence(refresh.diagnosticStore, item, refresh.evidenceRevision()),
+    (item) =>
+      reopenCandidates.has(item.uri) &&
+      // A document with any current publication — tentative included — is
+      // not a reopen candidate: its server pipeline is alive and a republish
+      // can still promote the retained cache (ADR 0021).
+      !hasCurrentEvidence(refresh.diagnosticStore, item, refresh.evidenceRevision()),
   );
   const reopenedSynchronizations: DiagnosticSynchronization[] = [];
   for (const item of unconfirmed) {
@@ -478,14 +678,13 @@ async function reopenUnconfirmedDocuments(options: {
     });
   }
   if (reopenedSynchronizations.length === 0) {
-    return { performed: false, startedAt, budgetMs, synchronizations: [...synchronizations] };
+    return { performed: false, startedAt, synchronizations: [...synchronizations] };
   }
   observer.reopened(reopenedSynchronizations.length);
   const reopenedByUri = new Map(reopenedSynchronizations.map((item) => [item.uri, item]));
   return {
     performed: true,
     startedAt,
-    budgetMs,
     synchronizations: synchronizations.map((item) => reopenedByUri.get(item.uri) ?? item),
   };
 }