@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/lsp/client.js

@@ -7,27 +7,32 @@
  * - Diagnostics with debouncing
  * - Request/response handling
  */
-import { logExtension } from "../extension-log.js";
 import { spawn as nodeSpawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { access, readFile } from "node:fs/promises";
 import * as os from "node:os";
 import { pathToFileURL } from "node:url";
+import { emitBounded } from "../bounded-telemetry.js";
 import { withTimeout } from "../deadline-utils.js";
-import { logLatency } from "../latency-logger.js";
+import { incrementDegradationCount } from "../degradation-ledger.js";
 // vscode-jsonrpc v9 ships an `exports` map exposing the Node entry as the
 // `./node` subpath (no `.js`); the old `/node.js` file path no longer resolves.
 import { CancellationTokenSource, createMessageConnection, StreamMessageReader, StreamMessageWriter, } from "../deps/vscode-jsonrpc.js";
+import { logExtension } from "../extension-log.js";
+import { recordLspChild, removeLspChild } from "../instance-registry.js";
+import { logLatency } from "../latency-logger.js";
+import { newLspMutationCorrelationId, } from "../lsp-mutation.js";
 import { getAmbientAbortSignal } from "../safe-spawn.js";
+import { raceToCompletion } from "./aggregation.js";
 import { hashDiagnosticContent, } from "./diagnostic-binding.js";
-import { newLspMutationCorrelationId, } from "../lsp-mutation.js";
-import { applyWorkspaceEdit, normalizeWorkspaceEditToUtf16, } from "./edits.js";
-import { recordLspChild, removeLspChild } from "../instance-registry.js";
+import { applyWorkspaceEdit, normalizeWorkspaceEditToUtf16 } from "./edits.js";
 import { normalizeMapKey, uriToPath } from "./path-utils.js";
-import { probeTsserverProjectIdentity } from "./tsserver-sync.js";
 import { ADVERTISED_POSITION_ENCODINGS, convertCharacterOffset, lineTextAt, negotiatePositionEncoding, } from "./position-encoding.js";
+import { negotiateSyncKind, TEXT_DOCUMENT_SYNC_KIND_FULL, TEXT_DOCUMENT_SYNC_KIND_INCREMENTAL, } from "./sync-kind.js";
+import { probeTsserverProjectIdentity } from "./tsserver-sync.js";
 import { getStrategy } from "./wait-policy/index.js";
 import { WatchedFilesQueue } from "./watch-queue.js";
+import { clearAllWorkspaceDiagnosticsCaches, clearWorkspaceDiagnosticsCacheAtAndAbove, } from "./workspace-diagnostics-cache.js";
 // Opt-in publishDiagnostics trace (PILENS_PUB_DEBUG=1) — read once, negligible
 // hot-path cost. Surfaces each server's publish behavior (version + count) to
 // diagnose the clean-file affirmative-signal question (#240): which servers
@@ -48,6 +53,8 @@ const PUB_DEBUG = Boolean(process.env.PILENS_PUB_DEBUG);
  * argument, without new server-specific code.
  */
 function extractSpawnMarker(args) {
+    if (!args)
+        return undefined;
     const tmpDir = os.tmpdir();
     for (let i = 0; i < args.length - 1; i++) {
         const flag = args[i];
@@ -126,7 +133,31 @@ const PULL_DIAGNOSTICS_RETRY_INTERVAL_MS = positiveIntFromEnv("PI_LENS_LSP_PULL_
 // the diagnostics flush. On timeout the request is treated as `unavailable`, which
 // (per #240) is NOT read as clean and falls through to the bounded push backstop.
 const PULL_REQUEST_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_PULL_REQUEST_TIMEOUT_MS", 10_000);
+// #1773: the smallest budget this codebase treats as usable — dispatching
+// BELOW it is not a real attempt. The old clamp (`Math.max(1, ...)`) let an
+// exhausted `budgetMs` (0 or negative) through as a 1ms pull — sent, timed
+// out by construction, and recorded as a genuine `lsp_pull_diagnostic_timeout`
+// with a fabricated `effectiveBudgetMs: 1` (observed live: both pull-timeout
+// records in the 2026-08-20 plegma dogfood session carried exactly that).
+// 5ms sits below the smallest budget this codebase's own regression fixtures
+// already treat as a real dispatch (`tests/clients/lsp/pull-diagnostic-
+// timeout-telemetry.test.ts` exercises 20ms and 30ms as genuinely-attempted-
+// then-timed-out) and above the 1-4ms band that is indistinguishable from
+// "already exhausted" — a local stdio server round trip (write + compute +
+// parse) needs more than a handful of milliseconds even on the fast path.
+// `budgetMs === PULL_MIN_USABLE_BUDGET_MS` dispatches (the comparison below
+// is strict `<`), so the name reads literally: this is the floor value that
+// still gets a real attempt.
+const PULL_MIN_USABLE_BUDGET_MS = 5;
 const SHUTDOWN_REQUEST_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_SHUTDOWN_TIMEOUT_MS", 1000);
+// #1620: the `exit` NOTIFICATION needs its own ceiling, for the same reason the
+// `shutdown` REQUEST has one. A notification write on a pipe that is not
+// draining neither resolves nor rejects, so `safeSendNotification`'s catch never
+// runs and the await is unbounded. The #1459 wedged-write breaker calls this
+// teardown precisely when that stdin has already been PROVEN wedged, so the
+// unbounded await was the whole mechanism of the leak. Kept equal to the request
+// budget: a healthy server still gets a brief graceful window before the kill.
+const EXIT_NOTIFY_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_EXIT_NOTIFY_TIMEOUT_MS", 1000);
 // #1277: cheap liveness round-trip for the silent-clean gates (`index.ts`).
 // Those gates convert a diagnostics-wait timeout into a confirmed-clean
 // result from a STATIC capability classification (`silentOnClean`) alone —
@@ -146,6 +177,36 @@ const LIVENESS_PING_QUERY = "__pi_lens_liveness_ping__";
 // cheaply rebuilt by the next full pull, the worst case is just one extra full
 // (non-`unchanged`) report per affected file.
 const WORKSPACE_PULL_RESULT_CACHE_MAX = 4096;
+// #1713: `workspace/diagnostic` has no per-file/per-identifier request to key
+// telemetry identity on — it is one project-wide pull — so timeout/late-answer
+// records use this fixed subject/scope instead of a real path.
+const WORKSPACE_PULL_SCOPE = "*workspace*";
+// #1669 review N2: cap on simultaneous re-pulls the `workspace/diagnostic/
+// refresh` handler fires for open documents. A workspace with hundreds of
+// open documents fanning out one `textDocument/diagnostic` request each,
+// with no cap, floods the server the refresh itself just told us is under
+// load. Small and fixed — this is a background improvement after the
+// protocol reply, never something worth tuning per project.
+const REFRESH_REPULL_CONCURRENCY = 4;
+/** Run `mapper` over `items` with at most `concurrency` in flight at once.
+ *  Same shape as `dependency-checker.ts`'s helper of the same name — a
+ *  worker-pool pattern repeated per-file by design in this codebase rather
+ *  than shared, so each caller can keep it un-exported and file-local. */
+async function mapWithConcurrency(items, concurrency, mapper) {
+    if (items.length === 0)
+        return;
+    let nextIndex = 0;
+    const workerCount = Math.max(1, Math.min(concurrency, items.length));
+    const worker = async () => {
+        while (true) {
+            const index = nextIndex++;
+            if (index >= items.length)
+                return;
+            await mapper(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+}
 // Anti-deadlock backstop for workspace/executeCommand. Deliberately generous
 // (30s): the command is mutating and legitimately long-running (a real server
 // refactor / organize-imports), so this must not truncate valid work — it only
@@ -414,10 +475,15 @@ function normalizeLspDiagnostic(diagnostic) {
 function normalizeLspDiagnostics(diagnostics) {
     return diagnostics.map(normalizeLspDiagnostic);
 }
-function mergeDiagnosticLists(push, pull) {
+/**
+ * Union of diagnostic lists, first occurrence wins, exact duplicates dropped.
+ * Variadic since #1667 so the per-identifier pull sources merge through the
+ * SAME key as the push/pull merge rather than growing a second dedupe rule.
+ */
+function mergeDiagnosticLists(...lists) {
     const merged = [];
     const seen = new Set();
-    for (const diagnostic of [...(push ?? []), ...(pull ?? [])]) {
+    for (const diagnostic of lists.flatMap((list) => list ?? [])) {
         const key = [
             diagnostic.range.start.line,
             diagnostic.range.start.character,
@@ -435,14 +501,185 @@ function mergeDiagnosticLists(push, pull) {
     return merged;
 }
 function getMergedDiagnosticsForPath(state, normalizedPath) {
+    // SAFETY: `diagnostics` is the pre-split field name that older states (and
+    // older embedders holding a state built before `pushDiagnostics` existed)
+    // still carry. It is absent from `LSPClientState` on purpose — new code
+    // must not write it. The cast declares it OPTIONAL, so the read below is
+    // still `undefined`-guarded and a state without it falls through to the
+    // current field.
     const legacy = state;
     return mergeDiagnosticLists(state.pushDiagnostics?.get(normalizedPath) ??
         legacy.diagnostics?.get(normalizedPath), state.documentPullDiagnostics?.get(normalizedPath));
 }
+/**
+ * #1667: per-source pull-diagnostic bookkeeping.
+ *
+ * A pull-mode server can expose several diagnostic SOURCES, each named by its
+ * registration's `registerOptions.identifier` (Roslyn: syntax, semantic,
+ * analyzers). Each source answers independently, with its own `resultId` and
+ * its own findings, so per-path state that used to be a single slot has to
+ * become one slot per (path, source):
+ *
+ *  - `pullResultIds` keys on `pullSourceKey(path, identifier)`, so an
+ *    `unchanged` report is only ever answered against the id THAT source
+ *    issued (#240/#1104 machinery, now per source).
+ *  - `documentPullDiagnosticsBySource` holds each source's findings, and
+ *    `documentPullDiagnostics` is their deduped union - recomputed whenever a
+ *    source reports, so a fresh answer from one source never wipes another's.
+ *
+ * The bare (identifier-less) source keys on the plain path, so a single-source
+ * server stores exactly what it stored before this change.
+ */
+// NUL is the one byte a filesystem path can never contain, so
+// `path + SEP + identifier` is unambiguous: no path/identifier pair can
+// produce the same key as a different pair, and the bare source's key (the
+// plain path) can never collide with a named source's.
+const PULL_SOURCE_KEY_SEPARATOR = "\u0000";
+const BARE_PULL_SOURCE = "";
+function pullSourceKey(normalizedPath, identifier) {
+    return identifier === undefined
+        ? normalizedPath
+        : `${normalizedPath}${PULL_SOURCE_KEY_SEPARATOR}${identifier}`;
+}
+/** Every `pullResultIds` key belonging to a path - the bare key plus one per
+ *  identifier. Used by the clear path so a resync drops EVERY source's basis. */
+function pullSourceKeysForPath(state, normalizedPath) {
+    const prefix = `${normalizedPath}${PULL_SOURCE_KEY_SEPARATOR}`;
+    return [
+        normalizedPath,
+        ...[...(state.pullResultIds?.keys() ?? [])].filter((key) => key.startsWith(prefix)),
+    ];
+}
+function pullSourcesFor(state, normalizedPath) {
+    if (!state.documentPullDiagnosticsBySource) {
+        state.documentPullDiagnosticsBySource = new Map();
+    }
+    let sources = state.documentPullDiagnosticsBySource.get(normalizedPath);
+    if (!sources) {
+        sources = new Map();
+        state.documentPullDiagnosticsBySource.set(normalizedPath, sources);
+    }
+    return sources;
+}
+/** This source's currently stored findings for a path - what an `unchanged`
+ *  report inherits. Falls back to the whole per-path list when the source map
+ *  has no entry yet, so a state that pulled before this change (or a caller
+ *  that seeded `documentPullDiagnostics` directly) still inherits correctly. */
+function pullSourceDiagnostics(state, normalizedPath, identifier) {
+    const sources = state.documentPullDiagnosticsBySource?.get(normalizedPath);
+    const stored = sources?.get(identifier ?? BARE_PULL_SOURCE);
+    if (stored)
+        return stored;
+    return sources && sources.size > 0
+        ? []
+        : (state.documentPullDiagnostics.get(normalizedPath) ?? []);
+}
+/** Store one source's findings and republish the union to
+ *  `documentPullDiagnostics`, which every reader outside this file uses. */
+function storePullSourceDiagnostics(state, normalizedPath, identifier, diagnostics) {
+    const sources = pullSourcesFor(state, normalizedPath);
+    sources.set(identifier ?? BARE_PULL_SOURCE, diagnostics);
+    state.documentPullDiagnostics.set(normalizedPath, mergeDiagnosticLists(...sources.values()));
+}
+/** #1667: the pull generation for a path. The fan-out deliberately lets losing
+ *  pulls run to completion so their findings still reach the cache; a resync
+ *  that lands first must win, so every late write re-checks this. */
+function pullGenerationFor(state, normalizedPath) {
+    return state.pullGenerations?.get(normalizedPath) ?? 0;
+}
+function bumpPullGeneration(state, normalizedPath) {
+    if (!state.pullGenerations)
+        state.pullGenerations = new Map();
+    state.pullGenerations.set(normalizedPath, (state.pullGenerations.get(normalizedPath) ?? 0) + 1);
+}
+/** #1667: claim the newest-request slot for a source and return the claim.
+ *  Called at REQUEST time; `isNewestPullRequest` re-checks it at WRITE time so
+ *  a slow answer from an earlier fan-out cannot overwrite a newer one's. */
+function claimPullRequestSequence(state, sourceKey) {
+    if (!state.pullRequestSequences)
+        state.pullRequestSequences = new Map();
+    const next = (state.pullRequestSequences.get(sourceKey) ?? 0) + 1;
+    state.pullRequestSequences.set(sourceKey, next);
+    return next;
+}
+function isNewestPullRequest(state, sourceKey, sequence) {
+    return (state.pullRequestSequences?.get(sourceKey) ?? 0) === sequence;
+}
+/**
+ * #1667: drop every trace of a diagnostic source the server just unregistered.
+ *
+ * `client/unregisterCapability` retires a source, but its findings sit in
+ * `documentPullDiagnosticsBySource` and its resultId in `pullResultIds`, so
+ * without this the union keeps serving a retired source's diagnostics until
+ * something resyncs the file. Roslyn and vtsls re-register their sources on
+ * solution reload, which is exactly when the old source's findings are stale.
+ *
+ * Purges the source's slice from every path and republishes each affected
+ * path's union, so the removal is visible on the next read rather than only
+ * after the next pull.
+ */
+function retirePullSource(state, identifier) {
+    const suffix = `${PULL_SOURCE_KEY_SEPARATOR}${identifier}`;
+    for (const source of [state.pullResultIds, state.pullRequestSequences]) {
+        if (!source)
+            continue;
+        for (const key of [...source.keys()]) {
+            if (key.endsWith(suffix))
+                source.delete(key);
+        }
+    }
+    for (const [normalizedPath, sources,] of state.documentPullDiagnosticsBySource ?? []) {
+        if (!sources.delete(identifier))
+            continue;
+        state.documentPullDiagnostics.set(normalizedPath, mergeDiagnosticLists(...sources.values()));
+        bumpDiagnosticsVersion(state, normalizedPath);
+        state.diagnosticEmitter.emit("diagnostics", normalizedPath);
+    }
+}
+/**
+ * #1667: the diagnostic sources to pull for a document - always the bare
+ * request (a server may answer it even while registering named sources, and it
+ * is the ONLY request a single-source server understands), plus one per
+ * distinct `identifier` on a live `textDocument/diagnostic` registration.
+ *
+ * Derived from `dynamicRegistrations` on every call rather than cached in a
+ * parallel list: the registration map is the single source of truth, and
+ * `client/unregisterCapability` must be able to retire a source immediately.
+ */
+export function pullDiagnosticSources(state) {
+    const identifiers = new Set();
+    for (const registration of state.dynamicRegistrations?.values() ?? []) {
+        if (registration.method !== "textDocument/diagnostic")
+            continue;
+        if (registration.identifier)
+            identifiers.add(registration.identifier);
+    }
+    // Sorted for a stable, reproducible request order in logs and tests; the
+    // fan-out is parallel, so order carries no priority.
+    return [undefined, ...[...identifiers].sort((a, b) => a.localeCompare(b))];
+}
+/** #1531: bump the client-global diagnostics counter and stamp the path it was
+ * bumped FOR. The single seam every "fresh diagnostics stored" site goes
+ * through, so the per-path stamp can never drift from the global counter. */
+export function bumpDiagnosticsVersion(state, normalizedPath) {
+    state.diagnosticsVersion += 1;
+    state.diagnosticsVersionsByPath?.set(normalizedPath, state.diagnosticsVersion);
+}
+/** #1531: the global counter's value when diagnostics were last stored for
+ * `normalizedPath`, or 0 when nothing is stored. 0 is a safe floor because the
+ * counter starts at 0 and only ever increases, so any later publication for the
+ * path compares greater than a baseline read while it was absent. */
+export function diagnosticsVersionForPath(state, normalizedPath) {
+    return state.diagnosticsVersionsByPath?.get(normalizedPath) ?? 0;
+}
 /** Exported for tests: the quiet-window timer cancel on clear/resync is the
  * headline #1412 safety property (a stale versionless publication must never
  * land after the document content changed). */
 export function clearDiagnosticsForPath(state, normalizedPath) {
+    // SAFETY: same pre-split field names as `getMergedDiagnosticsForPath`.
+    // Clearing must cover the legacy maps too, or a state that still carries
+    // them replays a stale diagnostic after the clear. Both are declared
+    // OPTIONAL, so every use below is `?.`-guarded on a state that lacks them.
     const legacy = state;
     state.pushDiagnostics?.delete(normalizedPath);
     const pending = state.pendingDiagnostics?.get(normalizedPath);
@@ -458,37 +695,96 @@ export function clearDiagnosticsForPath(state, normalizedPath) {
     // `documentContentHashes` record is intentionally retained: it describes what
     // we sent, which the NEXT publish for that version still needs to bind to.)
     state.diagnosticBindings?.delete(normalizedPath);
+    // #1531: the per-path publication stamp describes diagnostics that no longer
+    // exist — drop it with them. Safe because the stamps hold the GLOBAL counter's
+    // value: a baseline captured before this clear still compares less than any
+    // later publication for the path, so dropping the entry cannot manufacture a
+    // missed answer.
+    state.diagnosticsVersionsByPath?.delete(normalizedPath);
     // #1104: a resync invalidates any `unchanged`-report basis too — the next
     // pull must not inherit a resultId/contentHash computed against the
     // content this resync just replaced.
-    state.pullResultIds?.delete(normalizedPath);
+    // #1667: every SOURCE's basis, not just the bare one - a multi-source server
+    // holds one resultId per identifier, and leaving even one behind lets the
+    // next pull inherit against content this resync replaced.
+    for (const key of pullSourceKeysForPath(state, normalizedPath)) {
+        state.pullResultIds?.delete(key);
+    }
+    // `pullRequestSequences` is deliberately NOT cleared here. It is a
+    // monotonic per-source counter, and resetting it would let a request issued
+    // BEFORE this resync claim the same number as one issued after, so the stale
+    // answer would pass the newest-request check. The two guards cover different
+    // cases and neither subsumes the other: the generation bump below invalidates
+    // in-flight work when nothing newer was requested, and the sequence stamp
+    // invalidates it when something newer was.
+    state.documentPullDiagnosticsBySource?.delete(normalizedPath);
+    // #1667: invalidate any pull still in flight for this path. The fan-out lets
+    // losing pulls run to completion so their findings still reach the cache;
+    // without this bump one of them could resurrect what this resync cleared.
+    bumpPullGeneration(state, normalizedPath);
     state.workspacePullResultCache?.delete(normalizedPath);
     legacy.diagnostics?.delete(normalizedPath);
     legacy.diagnosticTimestamps?.delete(normalizedPath);
 }
-function logTypeScriptPullSettle(state, normalizedPath) {
+/**
+ * #1639: `durationMs` measures the PULL SETTLE ITSELF — the caller passes how
+ * long `clientRequestPullDiagnostics` (plus any retries) took to resolve
+ * `found`/`clean` — never time-since-didOpen. Document age is a genuinely
+ * useful signal but a DIFFERENT one; it stays under its own honest name in
+ * `metadata.elapsedSinceDidOpenMs`, exactly like the push-path `logSequence`
+ * above already does. Before this fix the top-level field carried the same
+ * age value pull requests use for retry-budget bookkeeping, so a session's
+ * latency percentiles for this phase read multi-second document lifetimes as
+ * millisecond operation costs (147/239 records read >60s "durations" for
+ * settles that took milliseconds).
+ *
+ * `version` reads the real tracked version from `diagnosticsVersionsByPath`
+ * (bumped by `bumpDiagnosticsVersion` right after this pull's diagnostics
+ * were stored — see the `documentPullDiagnostics.set` call above it) instead
+ * of a hardcoded `null`, which made every pull settle look "unbound" to
+ * staleness forensics even though this codebase already tracks a real
+ * version for the path. Falls back to the explicit `"pull-unversioned"`
+ * marker only when nothing has been stored yet, so "no data" is never
+ * confused with "confirmed no version" (`null`).
+ *
+ * `pullSettleSource` distinguishes the two legitimate call paths that can
+ * both settle a pull for the same file close together: a real
+ * content-collecting touch ("pull") and `ensureWarmForSweep`'s warm-up-only
+ * touch ("pull-warmup"), which runs a real round trip purely to prove the
+ * server answers before the sweep's real touch immediately follows it.
+ * Before this fix both logged identically as settleSource "pull", so a
+ * session with warm-up sweeps double-counted: 239 records against 145
+ * touches, with same-file pairs ~60ms apart and near-identical document
+ * ages — the warm-up settle and the real touch's settle for the same file.
+ */
+function logTypeScriptPullSettle(state, normalizedPath, durationMs, pullSettleSource) {
     if (state.serverId !== "typescript")
         return;
     const diagnostics = state.documentPullDiagnostics.get(normalizedPath) ?? [];
     const elapsedSinceDidOpenMs = Math.max(0, Date.now() - (state.documentOpenedAt.get(normalizedPath) ?? Date.now()));
-    const diagnosticCodes = [...new Set(diagnostics
+    const diagnosticCodes = [
+        ...new Set(diagnostics
             .map((diagnostic) => diagnostic.code)
             .filter((code) => code !== undefined)
-            .map(String))].slice(0, 8);
+            .map(String)),
+    ].slice(0, 8);
+    const trackedVersion = state.diagnosticsVersionsByPath?.get(normalizedPath);
     logLatency({
         type: "phase",
         phase: "lsp_typescript_diagnostic_sequence",
         filePath: normalizedPath,
-        durationMs: elapsedSinceDidOpenMs,
+        durationMs,
         metadata: {
+            serverId: state.serverId,
+            outcome: "settled",
             launchVariant: state.launchVariant ?? "unknown",
             publicationIndex: state.diagnosticPublicationCounts.get(normalizedPath) ?? 0,
-            version: null,
+            version: trackedVersion ?? "pull-unversioned",
             diagnosticCount: diagnostics.length,
             diagnosticCodes,
             elapsedSinceDidOpenMs,
             settledReturn: true,
-            settleSource: "pull",
+            settleSource: pullSettleSource,
         },
     });
 }
@@ -504,7 +800,93 @@ function recordSentContent(state, normalizedPath, version, content) {
     state.documentContentHashes.set(normalizedPath, {
         version,
         hash: hashDiagnosticContent(content),
+        // #1669: retain the full text only for Incremental — the sole reader
+        // (`buildContentChanges`) needs it to compute the NEXT change against
+        // what the server last saw; Full/None never read this field.
+        ...(state.syncKind === TEXT_DOCUMENT_SYNC_KIND_INCREMENTAL && {
+            text: content,
+        }),
     });
+    // #1641 criterion 3: the in-memory document's version + content length AT
+    // SEND TIME, so a later "diagnostic cited a line past current disk EOF"
+    // record (`diagnostic_past_eof`, clients/diagnostic-line-freshness.ts) can be
+    // paired with the send that produced the divergent in-memory document —
+    // today only the symptom (the stale citation) is observable; this is the
+    // cause side of the same timeline.
+    //
+    // Review round F4/F1: `contentLineCount` MUST use the same LSP-addressable
+    // convention as the gate itself (newline count + 1 — a trailing `\n` adds
+    // one more, empty, addressable line; an empty document is still 1 line),
+    // or the two records disagree by one at exactly the boundary this counter
+    // exists to help debug. Counted directly (no `.split("\n")`, which
+    // allocates one substring per line — measured at 13.3ms/200k allocations
+    // on a 7MB send) since only the COUNT is needed here, not the lines.
+    let newlineCount = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content.charCodeAt(i) === 10)
+            newlineCount++;
+    }
+    logLatency({
+        type: "phase",
+        phase: "lsp_document_send",
+        filePath: normalizedPath,
+        durationMs: 0,
+        metadata: {
+            version,
+            contentLength: content.length,
+            contentLineCount: newlineCount + 1,
+        },
+    });
+}
+/**
+ * #1669: the `contentChanges` array for a `textDocument/didChange` notification.
+ *
+ * Full/None (or unrecognized/absent) sync kind: unchanged — a single
+ * whole-document `{ text }` event, the shape pi-lens has always sent.
+ *
+ * Incremental: a server registering Incremental-only expects every change
+ * event to carry a `range`; a shapeless whole-document event is out of spec
+ * for it. Rather than hand-roll a real diff, send the SAFEST incremental
+ * representation of a full update — one ranged edit spanning the entire
+ * PREVIOUS document (start of file to its last character), replacing it with
+ * the entire new content. That is spec-valid for any Incremental server and
+ * semantically identical to the Full-sync event it replaces.
+ *
+ * The previous document's end position is computed from the text
+ * `recordSentContent` retained for THIS path the last time content was sent
+ * (reusing that seam rather than a second parallel content store — see its
+ * doc comment). No prior text on record (first change since Incremental was
+ * negotiated, or the path was never sent before) falls back to the
+ * whole-document shape — still spec-valid, and self-heals once the next
+ * change has a retained previous text to diff against.
+ */
+function buildContentChanges(state, normalizedPath, content) {
+    if (state.syncKind !== TEXT_DOCUMENT_SYNC_KIND_INCREMENTAL) {
+        return [{ text: content }];
+    }
+    const previousText = state.documentContentHashes.get(normalizedPath)?.text;
+    if (previousText === undefined) {
+        return [{ text: content }];
+    }
+    // #1669 review F6: split on every LSP line terminator (\r\n, lone \r, or
+    // \n), not just \n — a document using CRLF or lone-CR line endings would
+    // otherwise be undercounted, computing a range that ends mid-document
+    // instead of at the real last line.
+    const previousLines = previousText.split(/\r\n|\r|\n/);
+    const lastLine = previousLines.length - 1;
+    const lastLineText = previousLines[lastLine] ?? "";
+    return [
+        {
+            range: {
+                start: { line: 0, character: 0 },
+                end: {
+                    line: lastLine,
+                    character: convertCharacterOffset(state.positionEncoding, lastLineText, lastLineText.length),
+                },
+            },
+            text: content,
+        },
+    ];
 }
 // Methods that can be registered dynamically and map to operationSupport keys
 const DYNAMIC_OPERATION_METHOD_MAP = {
@@ -522,14 +904,23 @@ const DYNAMIC_OPERATION_METHOD_MAP = {
     "textDocument/prepareCallHierarchy": "callHierarchy",
 };
 export function applyDynamicCapabilities(state) {
-    const registeredMethods = new Set(state.dynamicRegistrations.values());
+    const registrations = [...state.dynamicRegistrations.values()];
+    const registeredMethods = new Set(registrations.map((r) => r.method));
     const hasDynamicPull = registeredMethods.has("textDocument/diagnostic") ||
         registeredMethods.has("workspace/diagnostic");
     if (hasDynamicPull) {
         state.workspaceDiagnosticsSupport = {
             advertised: true,
             mode: "pull",
-            workspaceDiagnostics: registeredMethods.has("workspace/diagnostic"),
+            // #1667: workspace-pull support is what the REGISTRATION declares. The
+            // spec registers workspace pull as `registerOptions.workspaceDiagnostics`
+            // on a `textDocument/diagnostic` registration - `workspace/diagnostic` is
+            // not itself a registrable method - so reading the method name alone
+            // missed every conforming server and this client never issued a
+            // workspace pull for one. The method-name check stays as a fallback for
+            // servers that register it as a method anyway.
+            workspaceDiagnostics: registrations.some((r) => r.workspaceDiagnostics === true) ||
+                registeredMethods.has("workspace/diagnostic"),
             diagnosticProviderKind: "dynamic",
         };
     }
@@ -549,15 +940,6 @@ export function applyDynamicCapabilities(state) {
         }
     }
 }
-/**
- * Resolve a `workspace/configuration` request item's `section` (a dot-path,
- * e.g. "scan.jobs") against the server's `initializationOptions` blob.
- * - No section (undefined/empty) → the whole blob, per spec ("if a scope
- *   isn't asked for" the client returns the full settings for that scope).
- * - An unresolvable path → `null`, never the whole blob — a server asking
- *   for a section it doesn't get must not silently receive unrelated config.
- * Exported for the #983 regression test.
- */
 export function resolveConfigurationSection(initialization, section) {
     if (!initialization)
         return section ? null : {};
@@ -565,9 +947,7 @@ export function resolveConfigurationSection(initialization, section) {
         return initialization;
     let cur = initialization;
     for (const part of section.split(".")) {
-        if (typeof cur !== "object" ||
-            cur === null ||
-            !Object.prototype.hasOwnProperty.call(cur, part)) {
+        if (typeof cur !== "object" || cur === null || !Object.hasOwn(cur, part)) {
             return null;
         }
         cur = cur[part];
@@ -579,6 +959,12 @@ export function resolveConfigurationSection(initialization, section) {
 // a real language server. Not part of the public client API surface.
 export function setupIncomingHandlers(state, initialization) {
     state.connection.onNotification("textDocument/publishDiagnostics", (params) => {
+        // #1639: the settle operation's own clock for THIS publish. A
+        // "quiet-window" settle's durationMs below measures from here (when
+        // this publish arrived and — armed or re-armed — the debounce timer)
+        // to when that timer actually fires, i.e. the real debounce wait, not
+        // time-since-didOpen.
+        const publishReceivedAt = Date.now();
         const filePath = uriToPath(params.uri);
         const normalizedPath = normalizeMapKey(filePath);
         // A server can flush a queued publish after didClose during teardown.
@@ -608,12 +994,38 @@ export function setupIncomingHandlers(state, initialization) {
             state.diagnosticPublicationCounts.set(normalizedPath, publicationIndex);
         }
         const diagnosticCodes = isTypeScriptTelemetry
-            ? [...new Set(newDiags
+            ? [
+                ...new Set(newDiags
                     .map((diagnostic) => diagnostic.code)
                     .filter((code) => code !== undefined)
-                    .map(String))].slice(0, 8)
+                    .map(String)),
+            ].slice(0, 8)
             : [];
-        const logSequence = (settledReturn, settleSource) => {
+        // #1639: `durationMs` measures the settle operation, never
+        // time-since-didOpen — document age keeps its own honest name in
+        // `metadata.elapsedSinceDidOpenMs`, exactly like the pull-path
+        // producer above. Before this fix EVERY call (settled or not) logged
+        // the doc-age value as durationMs, which is what actually produced
+        // the issue's cited evidence: this push-path producer, not the pull
+        // path, emitted all 239 records (147 of them >60s "durations" for
+        // settles that took milliseconds; a 61ms same-file pair is this
+        // function's OWN unsettled-then-settled shape — the
+        // `logSequence(false)` raw-receipt record immediately followed by
+        // the `logSequence(true, ...)` settle record for the same publish).
+        // - "first-push": settles immediately — the seed-first-push strategy
+        //   bypasses the debounce timer entirely, so there is no wait to
+        //   measure; durationMs is 0.
+        // - "quiet-window": the real debounce wait, timed from THIS publish's
+        //   own receipt (a later publish that re-arms the timer captures its
+        //   OWN `publishReceivedAt`, so a re-armed wait is timed from the
+        //   push that actually won the debounce, not the first one that lost
+        //   it).
+        // - "publication": a raw per-publication receipt, never itself a
+        //   settle — durationMs is 0 and `settledReturn` stays false. This
+        //   is the record that used to log with NO settleSource at all;
+        //   giving it one closes AC3 (distinguish, don't silently overload,
+        //   the phase's two shapes) for the pairs that actually occur.
+        const logSequence = (settledReturn, settleSource, durationMs) => {
             if (state.serverId !== "typescript")
                 return;
             const elapsedSinceDidOpenMs = Math.max(0, Date.now() -
@@ -622,16 +1034,18 @@ export function setupIncomingHandlers(state, initialization) {
                 type: "phase",
                 phase: "lsp_typescript_diagnostic_sequence",
                 filePath: normalizedPath,
-                durationMs: elapsedSinceDidOpenMs,
+                durationMs,
                 metadata: {
+                    serverId: state.serverId,
+                    outcome: settledReturn ? "settled" : "published",
                     launchVariant: state.launchVariant ?? "unknown",
                     publicationIndex,
-                    version: docVersion ?? null,
+                    version: docVersion ?? "push-unversioned",
                     diagnosticCount: newDiags.length,
                     diagnosticCodes,
                     elapsedSinceDidOpenMs,
                     settledReturn,
-                    ...(settleSource && { settleSource }),
+                    settleSource,
                 },
             });
         };
@@ -679,10 +1093,12 @@ export function setupIncomingHandlers(state, initialization) {
         // Known, deliberately out-of-scope gaps: the pull-diagnostics path
         // (clientRequestPullDiagnostics/clientRequestWorkspaceDiagnostics) has no
         // version stamp to compare against in this codebase's current handling,
-        // so nothing analogous is applied there. And diagnosticsVersion is a
-        // single global counter rather than per-path, so an unrelated path's
-        // fresh push can still satisfy a wait for this path's version bump —
-        // both are separate, larger changes.
+        // so nothing analogous is applied there. The other gap this note used to
+        // record — `diagnosticsVersion` being a single global counter, so an
+        // unrelated path's fresh push satisfied a wait for THIS path — is closed by
+        // #1531: every bump also stamps `diagnosticsVersionsByPath`, and both the
+        // `minVersion` freshness gate and the auxiliary answered/silent evidence
+        // check read that per-path stamp.
         const isSupersededPush = () => {
             if (docVersion === undefined)
                 return false;
@@ -698,12 +1114,14 @@ export function setupIncomingHandlers(state, initialization) {
             state.pushDiagnostics.set(normalizedPath, newDiags);
             state.pushDiagnosticTimestamps.set(normalizedPath, Date.now());
             recordDocVersion();
-            state.diagnosticsVersion += 1;
+            bumpDiagnosticsVersion(state, normalizedPath);
             state.diagnosticEmitter.emit("diagnostics", normalizedPath);
-            logSequence(true, "first-push");
+            // Immediate settle — no debounce wait to measure.
+            logSequence(true, "first-push", 0);
             return;
         }
-        logSequence(false);
+        // A raw per-publication receipt, not itself a settle.
+        logSequence(false, "publication", 0);
         const existingTimer = state.pendingDiagnostics.get(normalizedPath);
         if (existingTimer)
             clearTimeout(existingTimer);
@@ -714,9 +1132,10 @@ export function setupIncomingHandlers(state, initialization) {
             state.pushDiagnostics.set(normalizedPath, newDiags);
             state.pushDiagnosticTimestamps.set(normalizedPath, Date.now());
             recordDocVersion();
-            state.diagnosticsVersion += 1;
+            bumpDiagnosticsVersion(state, normalizedPath);
             state.diagnosticEmitter.emit("diagnostics", normalizedPath);
-            logSequence(true, "quiet-window");
+            // The real debounce wait, timed from THIS publish's own receipt.
+            logSequence(true, "quiet-window", Date.now() - publishReceivedAt);
         }, strategy.debounceMs);
         state.pendingDiagnostics.set(normalizedPath, timer);
     });
@@ -725,25 +1144,57 @@ export function setupIncomingHandlers(state, initialization) {
     ]);
     state.connection.onRequest("client/registerCapability", async (params) => {
         for (const reg of params?.registrations ?? []) {
+            const options = reg.registerOptions;
+            const commands = Array.isArray(options?.commands)
+                ? options.commands.filter((cmd) => typeof cmd === "string")
+                : undefined;
             if (reg.id && reg.method) {
-                state.dynamicRegistrations.set(reg.id, reg.method);
+                // #1667: keep the whole registration, not just its method. An empty
+                // `identifier` is treated as absent - it names no source, and
+                // sending `identifier: ""` would be a second, indistinguishable
+                // bare pull.
+                state.dynamicRegistrations.set(reg.id, {
+                    method: reg.method,
+                    ...(typeof options?.identifier === "string" && options.identifier
+                        ? { identifier: options.identifier }
+                        : {}),
+                    ...(typeof options?.workspaceDiagnostics === "boolean"
+                        ? { workspaceDiagnostics: options.workspaceDiagnostics }
+                        : {}),
+                    ...(commands ? { commands } : {}),
+                });
             }
             // executeCommand commands can arrive dynamically too — merge them
             // into the allowlist so dynamically-registered commands are runnable.
-            if (reg.method === "workspace/executeCommand" &&
-                Array.isArray(reg.registerOptions?.commands)) {
-                for (const cmd of reg.registerOptions.commands) {
-                    if (typeof cmd === "string")
-                        state.advertisedCommands.add(cmd);
-                }
+            if (reg.method === "workspace/executeCommand" && commands) {
+                for (const cmd of commands)
+                    state.advertisedCommands.add(cmd);
             }
         }
         applyDynamicCapabilities(state);
     });
     state.connection.onRequest("client/unregisterCapability", async (params) => {
+        const retiredIdentifiers = new Set();
         for (const unreg of params?.unregisterations ?? []) {
-            if (unreg.id) {
-                state.dynamicRegistrations.delete(unreg.id);
+            if (!unreg.id)
+                continue;
+            const registration = state.dynamicRegistrations.get(unreg.id);
+            state.dynamicRegistrations.delete(unreg.id);
+            if (registration?.method === "textDocument/diagnostic" &&
+                registration.identifier) {
+                retiredIdentifiers.add(registration.identifier);
+            }
+        }
+        // #1667: a retired source's cached findings and resultId must go with
+        // it, or the union keeps serving them. Checked after the deletes above,
+        // and only when NO surviving registration still speaks for that
+        // identifier.
+        const stillRegistered = new Set([...state.dynamicRegistrations.values()]
+            .filter((r) => r.method === "textDocument/diagnostic")
+            .map((r) => r.identifier));
+        for (const identifier of retiredIdentifiers) {
+            if (!stillRegistered.has(identifier)) {
+                retirePullSource(state, identifier);
             }
         }
         applyDynamicCapabilities(state);
@@ -792,6 +1243,128 @@ export function setupIncomingHandlers(state, initialization) {
         return items.map((item) => resolveConfigurationSection(initialization, item?.section));
     });
     state.connection.onRequest("window/workDoneProgress/create", async () => { });
+    // #1669: a server can send `workspace/diagnostic/refresh` (typically after a
+    // project-wide config change) to say every pull result it has already
+    // reported may be stale. Left unhandled, vscode-jsonrpc replies
+    // MethodNotFound to a server explicitly telling us its results are stale —
+    // this is exactly the signal `workspacePullResultCache` and the persisted
+    // workspace-diagnostics cache want (the #1461 family, server-initiated for
+    // once). Reply null per spec and drop both so the NEXT pull recomputes
+    // instead of replaying — or inheriting an `unchanged` basis from — results
+    // the server just told us to distrust.
+    // #1669 review R1: single-flight coalescing latch for the re-pull pool
+    // below, scoped to THIS client (one `setupIncomingHandlers` call per
+    // connection). A refresh FLOOD — a watch-mode rebuild or a `git checkout`
+    // can legitimately fire many `workspace/diagnostic/refresh` requests in a
+    // tight burst — used to queue one independent capped pool PER refresh:
+    // N refreshes meant N pools running concurrently (peak concurrency N x
+    // the per-pool cap) and N full passes over every open document (N x
+    // redundant pulls for the SAME documents). `refreshRepullRunning` gates a
+    // SECOND pool from ever starting while one is already in flight;
+    // `refreshRepullRerunRequested` remembers that at least one more refresh
+    // arrived meanwhile and coalesces it into exactly ONE trailing rerun
+    // after the current pool finishes, using a FRESH snapshot of open
+    // documents at rerun time (not the stale list from whenever the burst
+    // started) — so an arbitrarily large burst still costs at most 2 passes
+    // and never more than `REFRESH_REPULL_CONCURRENCY` pulls at once.
+    let refreshRepullRunning = false;
+    let refreshRepullRerunRequested = false;
+    const runRefreshRepullPool = async () => {
+        do {
+            refreshRepullRerunRequested = false;
+            const toRepull = state.workspaceDiagnosticsSupport.mode === "pull"
+                ? [...state.openDocuments]
+                : [];
+            if (toRepull.length > 0) {
+                try {
+                    await mapWithConcurrency(toRepull, REFRESH_REPULL_CONCURRENCY, async (normalizedPath) => {
+                        const uri = state.openDocumentUris?.get(normalizedPath);
+                        const filePath = uri ? uriToPath(uri) : normalizedPath;
+                        await clientRequestPullDiagnostics(state, filePath);
+                    });
+                }
+                catch (err) {
+                    // #1669 review N2: rejections are observed, never
+                    // `void`-swallowed — `clientRequestPullDiagnostics` itself never
+                    // throws (it returns an `unavailable` outcome), so this only
+                    // fires on a genuine programming error, but a silent throw
+                    // inside `mapWithConcurrency`'s `Promise.all` must not vanish.
+                    incrementDegradationCount({
+                        kind: "lsp-pull-unconfirmed",
+                        subject: state.serverId,
+                        reason: `refresh re-pull threw: ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                }
+            }
+            // A refresh that arrived WHILE this pool was running gets exactly
+            // one more pass, never a pass per refresh.
+        } while (refreshRepullRerunRequested);
+        refreshRepullRunning = false;
+    };
+    state.connection.onRequest("workspace/diagnostic/refresh", async () => {
+        state.workspacePullResultCache.clear();
+        // #1669 review F1: clear every on-disk sweep cache this process has
+        // recorded a cwd for — `state.root` alone is a per-SERVER identity
+        // marker that a monorepo/multi-root project routinely nests BELOW the
+        // real sweep cwd, so clearing ONLY there would miss the cache file the
+        // sweep actually reads/writes. See the doc comment on
+        // `clearAllWorkspaceDiagnosticsCaches`.
+        clearAllWorkspaceDiagnosticsCaches();
+        // #1669 review N3: ALSO clear at `state.root` directly. The registry
+        // above only knows cwds a sweep has already run under IN THIS PROCESS —
+        // a refresh arriving before this project's first sweep this process
+        // (e.g. right after a respawn) would otherwise clear nothing at all,
+        // and a later sweep would load the untouched, now-genuinely-stale
+        // on-disk cache a PRIOR process/session left behind. `state.root` is
+        // the one cwd this handler can always reach regardless of registry
+        // state — a cheap, durable backstop for the common single-root case
+        // where root and sweep cwd coincide. It does NOT cover a monorepo
+        // subproject a sweep hasn't reached yet under a DIFFERENT cwd than
+        // `state.root` — that residual gap is tracked in #1707, not silently
+        // claimed as solved (see `clearAllWorkspaceDiagnosticsCaches`'s doc
+        // comment for the full shape).
+        clearWorkspaceDiagnosticsCacheAtAndAbove(state.root);
+        // #1669 review F3: a server-initiated "everything may be stale" signal
+        // must drop the SAME per-document state a normal resync already drops
+        // via `clearDiagnosticsForPath` (pullResultIds, pushDiagnostics,
+        // documentPullDiagnostics, diagnosticBindings,
+        // diagnosticsVersionsByPath, ...) — dropping only
+        // `workspacePullResultCache` above left every open document's OTHER
+        // pull state intact, so the next pull would echo a disowned
+        // `previousResultId`, get back `kind: "unchanged"`, and re-confirm
+        // stale diagnostics under a fresh timestamp; nothing would ever
+        // re-pull on its own. This clear is cheap and always runs — every
+        // refresh in a burst gets its own, unlike the re-pull pool below.
+        for (const normalizedPath of state.openDocuments) {
+            clearDiagnosticsForPath(state, normalizedPath);
+        }
+        // #1669 review N2: reply to the PROTOCOL request now — every clear
+        // above is synchronous and already complete, so there is nothing left
+        // this reply should wait on. The re-pull below is a background
+        // improvement (so an open document reflects the refresh without
+        // waiting on its next edit), never something worth delaying — or
+        // risking — the required `null` reply over.
+        if (state.workspaceDiagnosticsSupport.mode === "pull" &&
+            state.openDocuments.size > 0) {
+            if (refreshRepullRunning) {
+                // #1669 review R1: a pool is already in flight from an earlier
+                // refresh in this burst — coalesce instead of starting a second
+                // one.
+                refreshRepullRerunRequested = true;
+            }
+            else {
+                refreshRepullRunning = true;
+                // `setImmediate` defers even the SYNCHRONOUS prefix of the pool
+                // (URI lookups, map bookkeeping) to the next tick, so it can
+                // never compete with this reply for the current one regardless
+                // of how many documents are open.
+                setImmediate(() => {
+                    void runRefreshRepullPool();
+                });
+            }
+        }
+        return null;
+    });
 }
 /**
  * #1127: record the FIRST moment this client observed its own death. Detection
@@ -849,27 +1422,196 @@ function setupConnectionLifecycle(state, recentStderr) {
             });
         }
     });
+    // #1969: the exit CAUSE, in the degradation ledger.
+    //
+    // The `exit` log above is one latency.log line per death. That line is
+    // necessary but not sufficient: an ast-grep child died 14 times in one day
+    // with `code=1` and empty stderr, and the only thing visible downstream was
+    // 19 `lsp_client_skipped_broken` cooldowns and 32 coverage gaps — fallout
+    // with no cause attached. The ledger is what a session-end health read
+    // looks at, so the cause belongs there too, counted per server.
+    //
+    // `close` rather than `exit`: `close` fires only after the child's stdio
+    // streams have drained, so "stderr was empty" is a statement about the
+    // server rather than a race against the pipe. `exit` can arrive first with
+    // stderr still buffered.
+    //
+    // Gated on `shutdownRequested` exactly as the exit log is — an eviction or
+    // an ordinary teardown is not a degradation and must not be recorded.
+    // `incrementDegradationCount` counts every occurrence and retains the
+    // latest reason per server, so a server dying in a loop shows as one entry
+    // with an honest count rather than N entries.
+    state.lspProcess.process.on("close", (code, signal) => {
+        if (state.shutdownRequested)
+            return;
+        try {
+            const stderrTail = recentStderr(20);
+            incrementDegradationCount({
+                kind: "lsp-server-unexpected-close",
+                subject: state.serverId,
+                reason: `closed unprompted: code=${code ?? "none"} signal=${signal ?? "none"} ` +
+                    `stderr=${stderrTail.length > 0 ? `present(${stderrTail.length}b)` : "empty"} root=${state.root}`,
+            });
+        }
+        catch {
+            // Telemetry must never break the observed path.
+        }
+    });
 }
+/** Margin between each source's own request timeout and the race's backstop
+ *  deadline, so the natural "all sources settled" path wins over the backstop
+ *  and the race never reports `unavailable` for sources that did answer. */
+const PULL_RACE_BACKSTOP_MARGIN_MS = 25;
+/**
+ * #1667: pull EVERY registered diagnostic source for a file, in parallel, and
+ * answer as soon as the first source returns findings for that file.
+ *
+ * Roslyn, vtsls and some Java setups register `textDocument/diagnostic` once
+ * per source (syntax, semantic, analyzers), each named by
+ * `registerOptions.identifier`. One bare request asks only the server's default
+ * source, so whole categories of findings were never requested. The fan-out
+ * asks all of them plus the bare request.
+ *
+ * Timing is deliberate and load-bearing:
+ *  - PARALLEL, never one source after another. Sequencing would add every
+ *    slow source's latency to every touch.
+ *  - The race resolves on the FIRST source with findings for the file, with no
+ *    settle or debounce window after the match. A post-match wait is the exact
+ *    latency shape #1112/#1407 already cost this codebase once.
+ *  - Losing sources are NOT cancelled. Each source writes its own findings into
+ *    the pull cache before it resolves, so a late answer merges in the
+ *    background and the NEXT read of the file sees it. Late answers are not
+ *    dropped, they are just not waited for.
+ *
+ * The race runs inside the existing `raceToCompletion` primitive rather than a
+ * second first-wins helper.
+ */
 async function clientRequestPullDiagnostics(state, filePath, budgetMs = PULL_REQUEST_TIMEOUT_MS) {
     if (!isClientAlive(state))
         return { status: "unavailable" };
-    const uri = pathToFileURL(filePath).href;
+    const sources = pullDiagnosticSources(state);
+    if (sources.length === 1) {
+        // The overwhelmingly common case: no named sources registered. Skip the
+        // race entirely so a single-source server pays nothing for this feature.
+        return aggregatePullOutcomes(state, filePath, [
+            await pullDiagnosticSource(state, filePath, budgetMs, undefined),
+        ]);
+    }
+    const attempts = sources.map((identifier) => pullDiagnosticSource(state, filePath, budgetMs, identifier));
+    const settled = await raceToCompletion(attempts, (results) => results.some((r) => r.status === "found" && r.primaryCount > 0), {
+        // No graceMs: finalize the instant a source answers for this file.
+        // The per-request `withTimeout` inside each attempt is the real bound;
+        // this deadline is only a backstop, so it sits just past it.
+        timeoutMs: Math.max(1, Math.min(PULL_REQUEST_TIMEOUT_MS, budgetMs)) +
+            PULL_RACE_BACKSTOP_MARGIN_MS,
+    });
+    return aggregatePullOutcomes(state, filePath, settled);
+}
+/**
+ * Collapse the sources that answered into one outcome for the caller.
+ * `found` beats `clean` beats `unavailable`: a source with findings is an
+ * answer, an authoritative empty report is an answer, and only "nobody
+ * answered" is unavailable (#240 — an empty result must distinguish clean
+ * from errored).
+ */
+function aggregatePullOutcomes(state, filePath, outcomes) {
+    const found = outcomes.filter((o) => o.status === "found");
+    if (found.length > 0) {
+        const normalizedPath = normalizeMapKey(filePath);
+        // The union for the requested file, which is what a caller reading the
+        // cache will see. A source that only reported `relatedDocuments` findings
+        // contributes nothing there, so fall back to its own count.
+        const unionCount = state.documentPullDiagnostics.get(normalizedPath)?.length ?? 0;
+        return {
+            status: "found",
+            count: Math.max(unionCount, ...found.map((o) => o.count)),
+        };
+    }
+    // #240, applied across sources: `clean` is an authoritative "this file has no
+    // findings", and one source saying so proves nothing about a source that
+    // FAILED to answer. A fan-out where any source errored is therefore
+    // unavailable, not clean - the caller falls through to the push-wait/timeout
+    // backstop instead of recording a confirmed-clean touch it cannot support.
+    // (`raceToCompletion` drops still-pending promises from its result array, so
+    // "every source settled, none errored" is the only shape that reads clean.)
+    if (outcomes.some((o) => o.status === "unavailable")) {
+        return { status: "unavailable" };
+    }
+    return outcomes.some((o) => o.status === "clean")
+        ? { status: "clean" }
+        : { status: "unavailable" };
+}
+async function pullDiagnosticSource(state, filePath, budgetMs, identifier) {
+    if (!isClientAlive(state))
+        return { status: "unavailable" };
     const normalizedPath = normalizeMapKey(filePath);
+    // #1773: a budget at or below the usable floor cannot complete a real
+    // round trip. Skip the dispatch entirely — no `safeSendRequest` call, no
+    // generation/sequence claim — and say so with a distinct record, so
+    // `lsp_pull_diagnostic_timeout` only ever means a pull was genuinely
+    // attempted. The caller sees the same `unavailable` outcome a timeout
+    // would have produced (#240: unavailable, never a false clean), so
+    // nothing downstream of this call changes shape.
+    if (budgetMs < PULL_MIN_USABLE_BUDGET_MS) {
+        emitBounded("lsp_pull_skipped_budget_exhausted", `${state.serverId}::${pullSourceKey(normalizedPath, identifier)}`, {
+            type: "phase",
+            filePath: normalizedPath,
+            durationMs: 0,
+            metadata: {
+                identifier: identifier ?? "bare",
+                remainingBudgetMs: budgetMs,
+                server: state.serverId,
+            },
+        }, {
+            ledgerKind: "lsp-pull-skipped-budget-exhausted",
+            reason: `pull skipped on ${state.serverId}: budget already exhausted (${budgetMs}ms remaining)`,
+        });
+        return { status: "unavailable" };
+    }
+    const uri = pathToFileURL(filePath).href;
     // #1104: echo the last resultId we hold for this document so a server that
     // hasn't changed its view can answer `kind: "unchanged"` instead of
     // recomputing — see the `kind === "unchanged"` branch below for how that's
     // honored (inherit, never treat an omitted `items` as clean).
-    const previousResultId = state.pullResultIds.get(normalizedPath);
+    // #1667: read THIS source's id, never another source's. Result ids are
+    // issued per source, so echoing a syntax id on a semantic request asks the
+    // server to compare against a basis it never handed out.
+    const sourceKey = pullSourceKey(normalizedPath, identifier);
+    if (state.abandonedPullRequests?.has(sourceKey)) {
+        return { status: "unavailable" };
+    }
+    const previousResultId = state.pullResultIds.get(sourceKey);
+    // #1667: the generation this pull was computed against. A resync landing
+    // while the request is in flight bumps it, and every write below is dropped
+    // rather than resurrecting state the resync cleared.
+    const generation = pullGenerationFor(state, normalizedPath);
+    // #1667: claim the newest-request slot for THIS source. Two fan-outs can
+    // overlap for the same file with no resync between them (`ensureWarmForSweep`
+    // touches, then the real touch follows ~60ms later), so the generation check
+    // alone would let a slow answer from the earlier round land on top of a newer
+    // one. Re-checked at write time below.
+    const requestSequence = claimPullRequestSequence(state, sourceKey);
+    // #1889: give the request a cancellation token. `withTimeout` only abandons
+    // its await; aborting in the timeout branch below also sends `$/cancelRequest`
+    // so repeated touches cannot leave an aging backlog inside the server.
+    const requestStartedAt = Date.now();
+    const effectiveTimeoutMs = Math.max(1, Math.min(PULL_REQUEST_TIMEOUT_MS, budgetMs));
+    const pullAbort = new AbortController();
+    const pullSettlement = { cancelled: false };
+    const requestPromise = safeSendRequest(state.connection, "textDocument/diagnostic", {
+        textDocument: { uri },
+        // #1667: name the source this request is for, so the server answers
+        // from that source instead of its default one.
+        ...(identifier !== undefined && { identifier }),
+        ...(previousResultId !== undefined && { previousResultId }),
+    }, pullAbort.signal, pullSettlement);
     try {
         // withTimeout is the backstop against a hung pull-mode server: without it
         // this await never settles unless the stream is destroyed. Bounded by the
         // smaller of the absolute ceiling and the caller's remaining wait budget.
         // On timeout the caught error yields `unavailable` below (never a false
         // `clean`), so it falls through to the push-wait/timeout backstop.
-        const report = await withTimeout(safeSendRequest(state.connection, "textDocument/diagnostic", {
-            textDocument: { uri },
-            ...(previousResultId !== undefined && { previousResultId }),
-        }), Math.max(1, Math.min(PULL_REQUEST_TIMEOUT_MS, budgetMs)));
+        const report = await withTimeout(requestPromise, effectiveTimeoutMs);
         if (!report) {
             recordPullFailure(state, "textDocument/diagnostic", new Error("empty response"));
             return { status: "unavailable" };
@@ -882,13 +1624,28 @@ async function clientRequestPullDiagnostics(state, filePath, budgetMs = PULL_REQ
         // response describes whatever the server had when it answered, which for
         // a pi-lens-opened document is exactly that last-sent payload.
         const sentHash = state.documentContentHashes.get(normalizedPath)?.hash;
-        let totalCount;
+        // #1667: two ways this answer can already be obsolete, and neither may
+        // write. Report the round trip as unavailable - a superseded answer is not
+        // evidence the file is clean (#240).
+        //  - A resync landed while the request was in flight, so these findings
+        //    describe content that no longer exists.
+        //  - A LATER request for this same source has already been issued (an
+        //    overlapping fan-out), so this answer is the stale loser and would
+        //    clobber the newer result.
+        if (pullGenerationFor(state, normalizedPath) !== generation ||
+            !isNewestPullRequest(state, sourceKey, requestSequence)) {
+            return { status: "unavailable" };
+        }
+        let primaryCount;
         if (report.kind === "unchanged") {
             // #1104: same resultId basis as last time — an omitted `items` here
             // means "no change", NOT "clean". Overwriting with `[]` would be the
             // exact false-clean shape #570/#571 already fixed for the touch path;
             // keep the previously stored diagnostics and binding as-is.
-            totalCount = state.documentPullDiagnostics.get(normalizedPath)?.length ?? 0;
+            // #1667: "the previously stored diagnostics" means THIS SOURCE's, so
+            // one source reporting unchanged neither inherits nor disturbs another
+            // source's findings for the same file.
+            primaryCount = pullSourceDiagnostics(state, normalizedPath, identifier).length;
             // Still a fresh confirmation as of `now` even though the content is
             // unchanged — bump the timestamp so `getAllDiagnostics()` doesn't read
             // this entry as aging purely because the server had nothing new to say.
@@ -896,30 +1653,43 @@ async function clientRequestPullDiagnostics(state, filePath, budgetMs = PULL_REQ
         }
         else {
             const primaryItems = normalizeLspDiagnostics(report.items ?? []);
-            state.documentPullDiagnostics.set(normalizedPath, primaryItems);
+            // #1667: replace only this source's slice; `documentPullDiagnostics`
+            // becomes the deduped union of every source that has reported.
+            storePullSourceDiagnostics(state, normalizedPath, identifier, primaryItems);
             state.documentPullDiagnosticTimestamps.set(normalizedPath, now);
-            state.diagnosticsVersion += 1;
+            bumpDiagnosticsVersion(state, normalizedPath);
             state.diagnosticBindings.set(normalizedPath, { contentHash: sentHash });
-            totalCount = primaryItems.length;
+            primaryCount = primaryItems.length;
         }
+        let totalCount = primaryCount;
         if (report.resultId !== undefined) {
-            state.pullResultIds.set(normalizedPath, report.resultId);
+            state.pullResultIds.set(sourceKey, report.resultId);
         }
         else {
-            state.pullResultIds.delete(normalizedPath);
+            state.pullResultIds.delete(sourceKey);
         }
+        // #1531 note (pre-existing, unchanged): a related document's diagnostics are
+        // STORED below but earn no version bump and therefore no per-path stamp —
+        // exactly as before, since this loop never bumped the global counter either.
+        // A wait on a path that only ever hears about itself through some other
+        // document's `relatedDocuments` sees no freshness evidence and rides its
+        // timeout. Direction is under-detection, and correcting it means deciding
+        // what a related-document publication is evidence OF (its binding is
+        // honestly "unknown" per #1104), so it stays out of scope here.
         if (report.relatedDocuments) {
             for (const [relatedUri, related] of Object.entries(report.relatedDocuments)) {
                 const relatedPath = uriToPath(relatedUri);
                 const relatedNormalized = normalizeMapKey(relatedPath);
+                // #1667: a related document's report belongs to the SAME source as
+                // the request that carried it, so it stores and inherits under that
+                // source's key too.
                 if (related?.kind === "unchanged") {
-                    totalCount +=
-                        state.documentPullDiagnostics.get(relatedNormalized)?.length ?? 0;
+                    totalCount += pullSourceDiagnostics(state, relatedNormalized, identifier).length;
                     state.documentPullDiagnosticTimestamps.set(relatedNormalized, now);
                 }
                 else {
                     const relatedItems = normalizeLspDiagnostics(related?.items ?? []);
-                    state.documentPullDiagnostics.set(relatedNormalized, relatedItems);
+                    storePullSourceDiagnostics(state, relatedNormalized, identifier, relatedItems);
                     state.documentPullDiagnosticTimestamps.set(relatedNormalized, now);
                     // #1104: a related document's diagnostics were NOT computed against
                     // content we independently sent/fingerprinted (we never requested
@@ -929,20 +1699,186 @@ async function clientRequestPullDiagnostics(state, filePath, budgetMs = PULL_REQ
                     totalCount += relatedItems.length;
                 }
                 if (related?.resultId !== undefined) {
-                    state.pullResultIds.set(relatedNormalized, related.resultId);
+                    state.pullResultIds.set(pullSourceKey(relatedNormalized, identifier), related.resultId);
                 }
             }
         }
         state.diagnosticEmitter.emit("diagnostics", normalizedPath);
         return totalCount > 0
-            ? { status: "found", count: totalCount }
+            ? { status: "found", count: totalCount, primaryCount }
             : { status: "clean" };
     }
     catch (err) {
+        if (isPullTimeoutError(err, effectiveTimeoutMs)) {
+            trackAbandonedPullRequest(state, sourceKey, requestPromise);
+            pullAbort.abort();
+            recordPullTimeoutTelemetry({
+                scope: normalizedPath,
+                identifier,
+                effectiveBudgetMs: effectiveTimeoutMs,
+                hadPreviousResultId: previousResultId !== undefined,
+                elapsedMs: Date.now() - requestStartedAt,
+                server: state.serverId,
+            });
+            armLateAnswerTelemetry({
+                requestPromise,
+                scope: normalizedPath,
+                identifier,
+                subject: sourceKey,
+                requestStartedAt,
+                server: state.serverId,
+                settlement: pullSettlement,
+            });
+        }
         recordPullFailure(state, "textDocument/diagnostic", err);
         return { status: "unavailable" };
     }
 }
+function trackAbandonedPullRequest(state, sourceKey, requestPromise) {
+    if (!state.abandonedPullRequests)
+        state.abandonedPullRequests = new Map();
+    state.abandonedPullRequests.set(sourceKey, requestPromise);
+    const release = () => {
+        if (state.abandonedPullRequests?.get(sourceKey) === requestPromise) {
+            state.abandonedPullRequests.delete(sourceKey);
+        }
+    };
+    requestPromise.then(release, release);
+}
+/**
+ * #1713: `withTimeout` rejects with this EXACT message (`clients/deadline-utils.ts`)
+ * only when its own timer wins the race — every other rejection is the request
+ * itself failing (bad params, dead connection, thrown by the server). Only the
+ * timer-won case is a "the answer might still be coming" situation worth a
+ * late-answer watch; a request that already failed fast has nothing further to
+ * observe.
+ */
+function isPullTimeoutError(err, timeoutMs) {
+    return err instanceof Error && err.message === `Timeout after ${timeoutMs}ms`;
+}
+/**
+ * #1713: every pull timeout emits exactly one bounded latency.log record — the
+ * observability gap the issue names (`withTimeout`'s throw previously skipped
+ * ALL telemetry for this site). Never throws: telemetry must not perturb the
+ * timeout path, which has already decided to return `unavailable` regardless.
+ *
+ * #1743: routed through `emitBounded`. This phase takes NO rising-edge gate
+ * and NO per-turn cap, which is the pre-existing behavior kept exactly: a
+ * pull timeout costs at least the full budget (seconds), so the call cadence
+ * already bounds the volume, unlike `navRequest` below. The helper still
+ * supplies the identity discipline and the registry membership the sweep
+ * checks.
+ */
+function recordPullTimeoutTelemetry(args) {
+    // #1771: this record is written on a genuine failure path (a dispatched
+    // pull that never answered), so per the bounded-telemetry rule
+    // (`clients/bounded-telemetry.ts`) it needs a `ledgerKind`, not just the
+    // detailed latency.log record. Before this it counted nothing in the
+    // degradation ledger — every occurrence wrote a detail line, but nothing
+    // tallied. No `risingEdgePer`: timeouts repeat and every one should count,
+    // matching the pre-existing "no rising-edge gate" behavior for the
+    // detailed record itself.
+    emitBounded("lsp_pull_diagnostic_timeout", `${args.server}::${args.scope}::${args.identifier ?? "bare"}`, {
+        type: "phase",
+        filePath: args.scope,
+        durationMs: args.elapsedMs,
+        metadata: {
+            identifier: args.identifier ?? "bare",
+            effectiveBudgetMs: args.effectiveBudgetMs,
+            hadPreviousResultId: args.hadPreviousResultId,
+            server: args.server,
+        },
+    }, {
+        ledgerKind: "lsp-pull-diagnostic-timeout",
+        reason: `pull timeout on ${args.server} after ${args.elapsedMs}ms (budget ${args.effectiveBudgetMs}ms)`,
+    });
+}
+/**
+ * #1713: a telemetry-only continuation on the ALREADY-abandoned request
+ * promise. `withTimeout` only raced it against a timer — the request is still
+ * live server-side — so if it eventually resolves, this is the only place that
+ * ever finds out. Purely observational: it runs after the caller has already
+ * moved on with `unavailable`, and it never writes into `state`.
+ *
+ * Bounded via the degradation-ledger convention (`incrementDegradationCount`,
+ * chosen over a hand-rolled per-identity rising-edge Set): the ledger already
+ * caps entries per kind and re-arms at `session_start`
+ * (`resetDegradationLedger`, wired into `handleSessionStart`), so reusing it
+ * avoids a second latch this fix would otherwise have to register and reset
+ * itself. `subject` is the same `pullSourceKey` (path + identifier) the pull
+ * path already uses, so the discriminating identity survives aggregation.
+ *
+ * Attaching `.then` here creates no timer, socket, or other handle — it only
+ * observes a promise the request already created — so it cannot keep the
+ * process alive a moment longer than that pending request already does.
+ */
+function armLateAnswerTelemetry(args) {
+    args.requestPromise.then(() => {
+        if (args.settlement.cancelled)
+            return;
+        try {
+            const elapsedMs = Date.now() - args.requestStartedAt;
+            // #1743: `emitBounded` counts every late answer in the ledger
+            // under the same `pullSourceKey` subject as before, then writes
+            // the record. No rising-edge gate, matching #1713's original
+            // behavior: a late answer arrives at most once per abandoned
+            // request, so the record count cannot exceed the timeout count.
+            emitBounded("lsp_pull_late_answer_discarded", args.subject, {
+                type: "phase",
+                filePath: args.scope,
+                durationMs: elapsedMs,
+                metadata: { identifier: args.identifier ?? "bare" },
+            }, {
+                ledgerKind: "lsp-pull-late-answer",
+                reason: `late pull answer discarded after ${elapsedMs}ms`,
+            });
+        }
+        catch {
+            // Telemetry must never break the observed path.
+        }
+    }, (err) => {
+        // #1774: the abandoned request eventually REJECTED rather than
+        // answering. Behavior is unchanged — the rejection is still
+        // swallowed here, exactly as before — but "timeout then silence"
+        // and "timeout then server rejection (e.g. ContentModified)" were
+        // previously indistinguishable: `recordPullFailure` at request
+        // time reports the FIRST failure only, and this rejection happens
+        // strictly after that request already timed out, so it needs its
+        // own record. Bounded via the degradation ledger, same shape as
+        // the late-answer branch above, so this rejection cannot outpace
+        // the timeout count that gates it.
+        try {
+            const elapsedMs = Date.now() - args.requestStartedAt;
+            const candidate = err;
+            const code = typeof candidate?.code === "number" ||
+                typeof candidate?.code === "string"
+                ? candidate.code
+                : undefined;
+            emitBounded("lsp_pull_late_rejection", 
+            // #1774 review: prefix the server, same reason the timeout kind
+            // does (#1771). The workspace call site's `subject` is the bare
+            // `WORKSPACE_PULL_SCOPE` constant — without the server prefix,
+            // two servers' abandoned-workspace-pull rejections would collapse
+            // into one ledger subject and hide which server is storming.
+            `${args.server}::${args.subject}`, {
+                type: "phase",
+                filePath: args.scope,
+                durationMs: elapsedMs,
+                metadata: {
+                    identifier: args.identifier ?? "bare",
+                    server: args.server,
+                    ...(code !== undefined && { code }),
+                },
+            }, {
+                ledgerKind: "lsp-pull-late-rejection",
+                reason: `late pull rejection ${elapsedMs}ms after timeout${code !== undefined ? ` (code ${code})` : ""}`,
+            });
+        }
+        catch {
+            // Telemetry must never break the observed path.
+        }
+    });
+}
 const PULL_FAILURE_HISTORY_LIMIT = 10;
 function recordPullFailure(state, method, error) {
     const candidate = error;
@@ -958,9 +1894,7 @@ function recordPullFailure(state, method, error) {
         ...(typeof candidate.code === "number" || typeof candidate.code === "string"
             ? { code: candidate.code }
             : {}),
-        message: typeof candidate.message === "string"
-            ? candidate.message
-            : String(error),
+        message: typeof candidate.message === "string" ? candidate.message : String(error),
     });
     if (state.pullFailureHistory.length > PULL_FAILURE_HISTORY_LIMIT) {
         state.pullFailureHistory.splice(0, state.pullFailureHistory.length - PULL_FAILURE_HISTORY_LIMIT);
@@ -978,15 +1912,58 @@ export async function clientRequestWorkspaceDiagnostics(state, budgetMs) {
         return undefined;
     if (!state.workspaceDiagnosticsSupport.workspaceDiagnostics)
         return undefined;
+    if (state.abandonedPullRequests?.has(WORKSPACE_PULL_SCOPE))
+        return undefined;
+    // #1104: echo every resultId we hold from a PRIOR pull so the server can
+    // answer `kind: "unchanged"` for files it hasn't recomputed, instead of
+    // resending (and us re-hashing) every file on every sweep.
+    const previousResultIds = Array.from(state.workspacePullResultCache.values()).map((entry) => ({ uri: entry.uri, value: entry.resultId }));
+    // #1773: same floor as `pullDiagnosticSource` — an exhausted budget here is
+    // the SAME clamp-then-dispatch defect via a second entry point. Observed
+    // live in the 2026-08-20 plegma dogfood session via
+    // `lsp_workspace_diagnostics_start` (not just the `lens_diagnostics_full`
+    // fan-out `pullDiagnosticSource` covers), so this call site needs its own
+    // skip, not just a shared helper the caller happens to hit.
+    if (budgetMs < PULL_MIN_USABLE_BUDGET_MS) {
+        emitBounded("lsp_pull_skipped_budget_exhausted", `${state.serverId}::${WORKSPACE_PULL_SCOPE}`, {
+            type: "phase",
+            filePath: WORKSPACE_PULL_SCOPE,
+            durationMs: 0,
+            metadata: {
+                identifier: "bare",
+                remainingBudgetMs: budgetMs,
+                server: state.serverId,
+            },
+        }, {
+            ledgerKind: "lsp-pull-skipped-budget-exhausted",
+            reason: `workspace pull skipped on ${state.serverId}: budget already exhausted (${budgetMs}ms remaining)`,
+        });
+        return undefined;
+    }
+    // #1713: declared OUTSIDE the try so the catch below can still reach them —
+    // same shape as `pullDiagnosticSource` above. Captured outside `withTimeout`
+    // so a timeout still holds a live handle on the request for the late-answer
+    // watch.
+    const workspacePullStartedAt = Date.now();
+    const workspacePullTimeoutMs = Math.max(1, budgetMs);
+    const workspacePullAbort = new AbortController();
+    const workspacePullSettlement = { cancelled: false };
+    const workspaceRequestPromise = safeSendRequest(state.connection, "workspace/diagnostic", { previousResultIds }, workspacePullAbort.signal, workspacePullSettlement);
     try {
-        // #1104: echo every resultId we hold from a PRIOR pull so the server can
-        // answer `kind: "unchanged"` for files it hasn't recomputed, instead of
-        // resending (and us re-hashing) every file on every sweep.
-        const previousResultIds = Array.from(state.workspacePullResultCache.values()).map((entry) => ({ uri: entry.uri, value: entry.resultId }));
-        const report = await withTimeout(safeSendRequest(state.connection, "workspace/diagnostic", { previousResultIds }), Math.max(1, budgetMs));
+        const report = await withTimeout(workspaceRequestPromise, workspacePullTimeoutMs);
         if (!report || !Array.isArray(report.items))
             return undefined;
         const out = [];
+        // #1669 review N1: ONE deadline, shared across every "unchanged, no
+        // cached basis" fallback pull this call makes — not a fresh `budgetMs`
+        // grant handed to EACH one. A refresh clears `workspacePullResultCache`,
+        // so the very next sweep after a refresh can route every item down this
+        // path; granting each one the full budget serially turned a bounded call
+        // unbounded (measured: 6 files x 300ms budget = 1844ms; worst case is
+        // the normal case — 2000 files x 30s). Mirrors the shared-budget shape
+        // `runWorkspaceDiagnosticsSwept`'s `perFileMs` bounds each file to,
+        // scoped to fallback pulls made from within THIS one call.
+        const fallbackPullDeadline = Date.now() + Math.max(1, budgetMs);
         for (const item of report.items) {
             if (!item?.uri)
                 continue;
@@ -998,8 +1975,53 @@ export async function clientRequestWorkspaceDiagnostics(state, budgetMs) {
                 // `items`, so without this a file the server confirmed unchanged
                 // would silently drop out of the sweep result entirely.
                 const prior = state.workspacePullResultCache.get(normalizedPath);
-                if (!prior)
-                    continue; // no earlier basis to inherit — nothing to report
+                if (!prior) {
+                    // #1669 review F4: no earlier basis to inherit (e.g. right after a
+                    // `workspace/diagnostic/refresh` cleared `workspacePullResultCache`)
+                    // — the server is answering "unchanged" against a resultId basis we
+                    // no longer hold, so there is nothing honest to report for this
+                    // file from THIS response. `continue`-ing here would make the file
+                    // silently absent from `out`, which the caller reads as "clean" —
+                    // a false clean for a file the server just told us it hasn't even
+                    // looked at freshly. Treat it as needs-full-pull: request the
+                    // per-file diagnostic directly instead.
+                    const remainingMs = fallbackPullDeadline - Date.now();
+                    if (remainingMs <= 0) {
+                        // #1669 review N1: the shared fallback-pull deadline is already
+                        // exhausted by earlier files in this same loop — bail WITHOUT
+                        // attempting a request (never fabricate clean; this file was
+                        // never actually asked about) and surface it as unavailable via
+                        // the same degradation ledger path as a real unavailable pull.
+                        incrementDegradationCount({
+                            kind: "lsp-pull-unconfirmed",
+                            subject: state.serverId,
+                            reason: "unchanged report with no workspacePullResultCache basis; the shared fallback-pull deadline was already exhausted by earlier files this sweep",
+                        });
+                        continue;
+                    }
+                    const outcome = await clientRequestPullDiagnostics(state, filePath, remainingMs);
+                    if (outcome.status === "found") {
+                        out.push({
+                            filePath,
+                            diagnostics: state.documentPullDiagnostics.get(normalizedPath) ?? [],
+                            contentHash: state.diagnosticBindings.get(normalizedPath)?.contentHash,
+                        });
+                    }
+                    else if (outcome.status === "unavailable") {
+                        // Genuinely unconfirmed — never fabricate a clean result. Recorded
+                        // via the shared degradation ledger (AGENTS.md: repeated
+                        // degradations use incrementDegradationCount, not a hand-rolled
+                        // counter) so a server that keeps racing refresh against sweeps
+                        // is visible in aggregate instead of silently absorbed per-file.
+                        incrementDegradationCount({
+                            kind: "lsp-pull-unconfirmed",
+                            subject: state.serverId,
+                            reason: "unchanged report with no workspacePullResultCache basis, and the per-file fallback pull was unavailable",
+                        });
+                    }
+                    // "clean": genuinely clean, correctly absent from `out`.
+                    continue;
+                }
                 if (item.resultId !== undefined) {
                     state.workspacePullResultCache.set(normalizedPath, {
                         ...prior,
@@ -1045,6 +2067,27 @@ export async function clientRequestWorkspaceDiagnostics(state, budgetMs) {
         return out;
     }
     catch (err) {
+        if (isPullTimeoutError(err, workspacePullTimeoutMs)) {
+            trackAbandonedPullRequest(state, WORKSPACE_PULL_SCOPE, workspaceRequestPromise);
+            workspacePullAbort.abort();
+            recordPullTimeoutTelemetry({
+                scope: WORKSPACE_PULL_SCOPE,
+                identifier: undefined,
+                effectiveBudgetMs: workspacePullTimeoutMs,
+                hadPreviousResultId: previousResultIds.length > 0,
+                elapsedMs: Date.now() - workspacePullStartedAt,
+                server: state.serverId,
+            });
+            armLateAnswerTelemetry({
+                requestPromise: workspaceRequestPromise,
+                scope: WORKSPACE_PULL_SCOPE,
+                identifier: undefined,
+                subject: WORKSPACE_PULL_SCOPE,
+                requestStartedAt: workspacePullStartedAt,
+                server: state.serverId,
+                settlement: workspacePullSettlement,
+            });
+        }
         recordPullFailure(state, "workspace/diagnostic", err);
         return undefined;
     }
@@ -1052,7 +2095,17 @@ export async function clientRequestWorkspaceDiagnostics(state, budgetMs) {
 export async function clientWaitForDiagnostics(state, filePath, timeoutMs, options = {}) {
     const normalizedPath = normalizeMapKey(filePath);
     const minVersion = options.minVersion;
-    const hasFreshDiagnostics = () => minVersion === undefined || state.diagnosticsVersion > minVersion;
+    const pullSettleSource = options.pullSettleSource ?? "pull";
+    // #1531: the freshness gate is PER PATH. `minVersion` is a reading of the
+    // client-global counter, and `diagnosticsVersionsByPath` stores that same
+    // counter's value at each store — the two are on one axis, so comparing them
+    // asks "has a publication landed for THIS file since the baseline?" instead of
+    // "has anything at all landed on this client?". Reading the global counter here
+    // let a sibling file's publication end this file's wait before its own budget
+    // lapsed, which then labelled the outcome row `silent` (reserved for "own
+    // budget lapsed with nothing published") instead of `cut_off`.
+    const hasFreshDiagnostics = () => minVersion === undefined ||
+        diagnosticsVersionForPath(state, normalizedPath) > minVersion;
     // Version coherence: a cached push is "stale" only when the server reported
     // the document version it computed against AND that version lags the latest
     // didChange we sent. This prevents serving diagnostics from a superseded
@@ -1076,9 +2129,13 @@ export async function clientWaitForDiagnostics(state, filePath, timeoutMs, optio
         // `hasFreshDiagnostics()`, which is unconditionally true when there is no
         // version baseline (`minVersion === undefined`), so a failed pull returned
         // 0 and was read as a fresh clean.
+        // #1639: the settle operation's OWN clock — durationMs on the eventual
+        // log record measures from here, never from didOpen (that stays in
+        // metadata.elapsedSinceDidOpenMs, computed separately below).
+        const pullSettleStartedAt = Date.now();
         let outcome = await clientRequestPullDiagnostics(state, filePath, timeoutMs);
         if (outcome.status === "found") {
-            logTypeScriptPullSettle(state, normalizedPath);
+            logTypeScriptPullSettle(state, normalizedPath, Date.now() - pullSettleStartedAt, pullSettleSource);
             return;
         }
         let sawClean = outcome.status === "clean";
@@ -1099,12 +2156,12 @@ export async function clientWaitForDiagnostics(state, filePath, timeoutMs, optio
         }
         if (options.pullOnly) {
             if (outcome.status === "found" || sawClean) {
-                logTypeScriptPullSettle(state, normalizedPath);
+                logTypeScriptPullSettle(state, normalizedPath, Date.now() - pullSettleStartedAt, pullSettleSource);
             }
             return;
         }
         if (outcome.status === "found" || sawClean) {
-            logTypeScriptPullSettle(state, normalizedPath);
+            logTypeScriptPullSettle(state, normalizedPath, Date.now() - pullSettleStartedAt, pullSettleSource);
             return;
         }
     }
@@ -1143,6 +2200,21 @@ export async function clientWaitForDiagnostics(state, filePath, timeoutMs, optio
         }, timeoutMs);
     });
 }
+/**
+ * Queue a watched-files change for a file this client did not learn about
+ * through textDocument/didOpen or didChange — an external bash write/delete,
+ * or any other disk change outside the open-document sync path (#1668).
+ * Shares `handleNotifyOpen`'s per-client debounced queue (#271), so a burst
+ * of external changes coalesces into one notification per debounce window
+ * instead of flooding the server with one per file.
+ */
+export function handleNotifyExternalChange(state, filePath, type) {
+    if (!isClientAlive(state))
+        return;
+    const normalizedPath = normalizeMapKey(filePath);
+    const uri = state.openDocumentUris?.get(normalizedPath) ?? pathToFileURL(filePath).href;
+    state.watchQueue.enqueue(uri, type);
+}
 export async function handleNotifyOpen(state, filePath, content, languageId, preserveDiagnostics = false, silent = false) {
     if (!isClientAlive(state))
         return;
@@ -1187,19 +2259,21 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
             state.diagnosticPublicationCounts.set(normalizedPath, 0);
             if (!isClientAlive(state))
                 return;
-            await safeSendNotification(state.connection, "textDocument/didOpen", {
-                textDocument: { uri, languageId, version, text: content },
-            });
-            recordSentContent(state, normalizedPath, version, content);
+            const reopenSent = await safeSendNotification(state.connection, "textDocument/didOpen", { textDocument: { uri, languageId, version, text: content } });
+            // #1669 review F7: only mirror the send locally once it actually left
+            // the process — see safeSendNotification's doc comment.
+            if (reopenSent)
+                recordSentContent(state, normalizedPath, version, content);
             state.openDocuments.add(normalizedPath);
             state.openDocumentUris?.set(normalizedPath, uri);
             return;
         }
-        await safeSendNotification(state.connection, "textDocument/didChange", {
+        const changeSent = await safeSendNotification(state.connection, "textDocument/didChange", {
             textDocument: { uri, version },
-            contentChanges: [{ text: content }],
+            contentChanges: buildContentChanges(state, normalizedPath, content),
         });
-        recordSentContent(state, normalizedPath, version, content);
+        if (changeSent)
+            recordSentContent(state, normalizedPath, version, content);
         return;
     }
     state.pendingOpens.add(normalizedPath);
@@ -1232,10 +2306,9 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
     }
     if (!isClientAlive(state))
         return;
-    await safeSendNotification(state.connection, "textDocument/didOpen", {
-        textDocument: { uri, languageId, version: 0, text: content },
-    });
-    recordSentContent(state, normalizedPath, 0, content);
+    const openSent = await safeSendNotification(state.connection, "textDocument/didOpen", { textDocument: { uri, languageId, version: 0, text: content } });
+    if (openSent)
+        recordSentContent(state, normalizedPath, 0, content);
     state.pendingOpens.delete(normalizedPath);
     state.openDocuments.add(normalizedPath);
     state.closedDocuments?.delete(normalizedPath);
@@ -1267,13 +2340,19 @@ export async function handleNotifyChange(state, filePath, content) {
     if (!state.openDocuments.has(normalizedPath)) {
         // Safety fallback: keep protocol ordering valid even if caller sends
         // didChange before first didOpen for this document.
-        await safeSendNotification(state.connection, "textDocument/didOpen", {
-            textDocument: { uri, languageId: "plaintext", version: 0, text: content },
+        const fallbackOpenSent = await safeSendNotification(state.connection, "textDocument/didOpen", {
+            textDocument: {
+                uri,
+                languageId: "plaintext",
+                version: 0,
+                text: content,
+            },
         });
         state.documentVersions.set(normalizedPath, 0);
         state.documentOpenedAt.set(normalizedPath, Date.now());
         state.diagnosticPublicationCounts.set(normalizedPath, 0);
-        recordSentContent(state, normalizedPath, 0, content);
+        if (fallbackOpenSent)
+            recordSentContent(state, normalizedPath, 0, content);
         state.openDocuments.add(normalizedPath);
         state.openDocumentUris?.set(normalizedPath, uri);
         return;
@@ -1283,11 +2362,12 @@ export async function handleNotifyChange(state, filePath, content) {
     // Clear stale diagnostics before sending new content so waitForDiagnostics
     // doesn't return immediately with the previous edit's results.
     clearDiagnosticsForPath(state, normalizedPath);
-    await safeSendNotification(state.connection, "textDocument/didChange", {
+    const changeSent = await safeSendNotification(state.connection, "textDocument/didChange", {
         textDocument: { uri, version },
-        contentChanges: [{ text: content }],
+        contentChanges: buildContentChanges(state, normalizedPath, content),
     });
-    recordSentContent(state, normalizedPath, version, content);
+    if (changeSent)
+        recordSentContent(state, normalizedPath, version, content);
 }
 /** Close a document through the same lifecycle path exposed by the client. */
 export async function closeDocument(state, filePath) {
@@ -1298,7 +2378,8 @@ export async function closeDocument(state, filePath) {
         return;
     await safeSendNotification(state.connection, "textDocument/didClose", {
         textDocument: {
-            uri: state.openDocumentUris?.get(normalizedPath) ?? pathToFileURL(filePath).href,
+            uri: state.openDocumentUris?.get(normalizedPath) ??
+                pathToFileURL(filePath).href,
         },
     });
     state.openDocuments.delete(normalizedPath);
@@ -1314,7 +2395,67 @@ export async function closeDocument(state, filePath) {
     state.projectIdentityProbedFiles?.delete(normalizedPath);
     clearDiagnosticsForPath(state, normalizedPath);
 }
-export async function clientShutdown(state, options = {}) {
+/**
+ * #1620 residual review F1: `fast` and `processExiting` only ever escalate —
+ * a `true` demands strictly less work (or none) than a `false`, never more.
+ * `existing` covers `requested` when it is at least as demanding on BOTH
+ * axes, so deduping onto it can't silently downgrade what the new caller
+ * needs (e.g. a `processExiting` caller must never inherit a teardown that
+ * might still spawn `taskkill`).
+ */
+function isAtLeastAsAggressiveShutdown(existing, requested) {
+    return (!!existing.fast >= !!requested.fast &&
+        !!existing.processExiting >= !!requested.processExiting);
+}
+export function clientShutdown(state, options = {}) {
+    // #1620 residual 3: idempotent across racing callers — see the doc comment
+    // on `LSPClientState.shutdownPromise`. The FIRST call starts the real
+    // teardown and stores its promise; every subsequent call (any of the 8
+    // call sites, on the same state) whose options are no MORE aggressive
+    // awaits that same promise instead of running the RPC handshake and
+    // emitting `lsp_client_shutdown` again.
+    //
+    // #1620 residual review F1: a call whose options ARE more aggressive does
+    // NOT dedupe — it starts (and takes over as) its own teardown instead.
+    // The concrete failure this closes: `resetLSPService`'s session-exit path
+    // (`index.ts`) calls `shutdown({fast:true, processExiting:true})` — the
+    // event loop is already closing, and `processExiting` exists precisely so
+    // this teardown never spawns `taskkill` (a closing-loop `uv_async_send`
+    // hard-aborts, `src\win\async.c`). If a GRACEFUL teardown (default
+    // options — e.g. `client_ceiling_lru` eviction) is already in flight on
+    // this same client when the exit path arrives, blindly deduping would
+    // make the exit path inherit that graceful run's own `taskkill` spawn and
+    // its close-event wait — the exact hazard `processExiting` forbids, on
+    // top of blocking the closing loop for however long that takes. The
+    // weaker in-flight teardown is left to finish on its own (every step
+    // downstream — dispose, kill, deregister — is already idempotent).
+    if (state.shutdownPromise &&
+        state.shutdownOptions &&
+        isAtLeastAsAggressiveShutdown(state.shutdownOptions, options)) {
+        return state.shutdownPromise;
+    }
+    state.shutdownOptions = options;
+    const attempt = clientShutdownOnce(state, options);
+    state.shutdownPromise = attempt;
+    // #1620 residual review F3: a REJECTED teardown (e.g. `killProcessTree`
+    // throwing something its own internal catches don't cover) must not
+    // latch a permanently-rejected promise here — every later call, even one
+    // with equal or weaker options, would dedupe onto it forever and never
+    // retry, so the child leaks silently with no further kill/dispose/
+    // deregister attempt. Clear the latch on rejection (only if nothing more
+    // aggressive has already superseded it) so the NEXT call starts a fresh
+    // attempt instead of re-handing back the same dead promise. The rejection
+    // itself still propagates to whoever is awaiting `attempt` right now —
+    // this only affects callers that haven't asked yet.
+    attempt.catch(() => {
+        if (state.shutdownPromise === attempt) {
+            state.shutdownPromise = undefined;
+            state.shutdownOptions = undefined;
+        }
+    });
+    return attempt;
+}
+async function clientShutdownOnce(state, options) {
     const shutdownStart = Date.now();
     state.shutdownRequested = true;
     state.isConnected = false;
@@ -1334,53 +2475,124 @@ export async function clientShutdown(state, options = {}) {
     state.watchQueue?.cancel();
     state.diagnosticEmitter.removeAllListeners();
     let shutdownRequestTimedOut = false;
-    if (!options.fast) {
-        try {
-            await withTimeout(safeSendRequest(state.connection, "shutdown", {}), SHUTDOWN_REQUEST_TIMEOUT_MS);
-        }
-        catch {
-            /* ignore — proceed to exit/kill so shutdown cannot hang the session */
-            shutdownRequestTimedOut = true;
-        }
-        try {
-            await safeSendNotification(state.connection, "exit", {});
-        }
-        catch {
-            /* ignore */
+    let exitNotifyTimedOut = false;
+    // #1620 residual 1 / residual-review F2: a failure that ISN'T the timer
+    // winning was previously folded into the same "*TimedOut" flag as a real
+    // timeout — honest for the rolled-up `shutdownOutcome` (still "forced"
+    // either way), imprecise about WHICH failure happened. Two shapes land
+    // here, both meaning "no confirmation this reached the server":
+    //   (a) a genuine promise rejection that isn't the timer (an immediate
+    //       protocol error) — reaches the `catch` below.
+    //   (b) `safeSendRequest`/`safeSendNotification` SWALLOW a stream error
+    //       (EPIPE, disposed connection — `isStreamError`) and RESOLVE
+    //       instead of rejecting, so the `catch` never runs at all. A real
+    //       `shutdown` reply is `null`, never `undefined`, and a real `exit`
+    //       notify send returns `true`; `undefined`/`false` is the swallow
+    //       case. Without this, a coded EPIPE reported `shutdownOutcome:
+    //       "graceful"` — nothing was delivered, but the log called it clean.
+    let shutdownRequestUndelivered = false;
+    let exitNotifyUndelivered = false;
+    // #1620: the graceful handshake is BEST-EFFORT and the teardown is not. A
+    // teardown path must not depend on the health of the thing it is tearing
+    // down — the breaker fires exactly when the server is unresponsive. Keep the
+    // handshake inside the `try` and every irreversible teardown step in the
+    // `finally`, so disposal, the record, the deregistration, and the kill run no
+    // matter how the two writes behave, and so a future added await here cannot
+    // reintroduce the class.
+    try {
+        if (!options.fast) {
+            try {
+                const shutdownAck = await withTimeout(safeSendRequest(state.connection, "shutdown", {}), SHUTDOWN_REQUEST_TIMEOUT_MS);
+                if (shutdownAck === undefined)
+                    shutdownRequestUndelivered = true;
+            }
+            catch (err) {
+                /* ignore — proceed to exit/kill so shutdown cannot hang the session */
+                if (isShutdownTimeoutError(err, SHUTDOWN_REQUEST_TIMEOUT_MS)) {
+                    shutdownRequestTimedOut = true;
+                }
+                else {
+                    shutdownRequestUndelivered = true;
+                }
+            }
+            try {
+                const exitSent = await withTimeout(safeSendNotification(state.connection, "exit", {}), EXIT_NOTIFY_TIMEOUT_MS);
+                if (exitSent === false)
+                    exitNotifyUndelivered = true;
+            }
+            catch (err) {
+                /* ignore — same reason as the request above */
+                if (isShutdownTimeoutError(err, EXIT_NOTIFY_TIMEOUT_MS)) {
+                    exitNotifyTimedOut = true;
+                }
+                else {
+                    exitNotifyUndelivered = true;
+                }
+            }
         }
     }
-    disposeClientConnection(state);
-    const pid = state.lspProcess.pid;
-    logLatency({
-        type: "phase",
-        phase: "lsp_client_shutdown",
-        filePath: state.root,
-        durationMs: Date.now() - shutdownStart,
-        metadata: {
-            serverId: state.serverId,
-            pid,
-            fast: !!options.fast,
-            processExiting: !!options.processExiting,
-            shutdownRequestTimedOut,
-        },
-    });
-    // #449/#472: deregister this LSP child from the instance registry. Fire-
-    // and-forget (async fs, no spawn) — must not add latency/risk to shutdown,
-    // including the `processExiting` path where the event loop is closing
-    // (#234 forbids spawning here, but a plain fs write/rename is fine; even
-    // so, we don't await it to keep this teardown path as fast as before).
-    void removeLspChild(pid).catch((err) => {
+    finally {
+        disposeClientConnection(state);
+        const pid = state.lspProcess.pid;
         logLatency({
             type: "phase",
-            phase: "lsp_registry_write_failed",
-            filePath: "",
-            durationMs: 0,
-            metadata: { op: "remove", pid, error: String(err) },
+            phase: "lsp_client_shutdown",
+            filePath: state.root,
+            durationMs: Date.now() - shutdownStart,
+            metadata: {
+                serverId: state.serverId,
+                pid,
+                fast: !!options.fast,
+                processExiting: !!options.processExiting,
+                shutdownRequestTimedOut,
+                // #1620: `shutdownRequestTimedOut` covered only the request half, so
+                // a hung exit notify was indistinguishable from a clean exit — and
+                // pre-fix no record was emitted at all. Report both halves plus one
+                // rolled-up verdict, so a forced teardown is countable from the log.
+                exitNotifyTimedOut,
+                // #1620 residual 1 / residual-review F2: the *Undelivered pair covers
+                // the failure the *TimedOut pair used to also claim — a rejection
+                // that is NOT the timer winning, OR (the F2 gap) a swallowed stream
+                // error that `safeSendRequest`/`safeSendNotification` resolved
+                // instead of rejecting, so no exception ever reached the catches
+                // above. Both still roll into shutdownOutcome "forced" below — an
+                // undelivered write is never reported as "graceful".
+                shutdownRequestUndelivered,
+                exitNotifyUndelivered,
+                shutdownOutcome: options.fast
+                    ? "fast"
+                    : shutdownRequestTimedOut ||
+                        exitNotifyTimedOut ||
+                        shutdownRequestUndelivered ||
+                        exitNotifyUndelivered
+                        ? "forced"
+                        : "graceful",
+            },
         });
-    });
-    // On Windows, killing the direct child first can orphan grandchildren before
-    // taskkill can traverse the tree. Kill the full tree first and wait briefly.
-    await killProcessTree(state.lspProcess.process, pid, options);
+        // #449/#472: deregister this LSP child from the instance registry. Fire-
+        // and-forget (async fs, no spawn) — must not add latency/risk to shutdown,
+        // including the `processExiting` path where the event loop is closing
+        // (#234 forbids spawning here, but a plain fs write/rename is fine; even
+        // so, we don't await it to keep this teardown path as fast as before).
+        // #1724: pass this spawn's marker so removeLspChild can guard against a
+        // pid-recycling window (a NEW child claiming this exact pid before this
+        // fire-and-forget write lands) rather than removing whichever child
+        // currently sits at this pid.
+        void removeLspChild(pid, extractSpawnMarker(state.lspProcess.args)).catch((err) => {
+            logLatency({
+                type: "phase",
+                phase: "lsp_registry_write_failed",
+                filePath: "",
+                durationMs: 0,
+                metadata: { op: "remove", pid, error: String(err) },
+            });
+        });
+        // On Windows, killing the direct child first can orphan grandchildren before
+        // taskkill can traverse the tree. Kill the full tree first and wait briefly.
+        // Safe and idempotent on an already-exited child: killProcessTree returns
+        // early on an observed exit rather than signalling a possibly-recycled pid.
+        await killProcessTree(state.lspProcess.process, pid, options);
+    }
 }
 /**
  * Translate a caller-supplied (UTF-16) `(line, character)` into the position the
@@ -1429,7 +2641,30 @@ signal = getAmbientAbortSignal()) {
     const requestVersion = normalizedPath !== undefined
         ? state.documentVersions.get(normalizedPath)
         : undefined;
-    const result = (await withTimeout(safeSendRequest(state.connection, method, params, signal), timeoutMs).catch((err) => {
+    // #1716: captured OUTSIDE withTimeout, mirroring #1713's pull-diagnostic
+    // fix (`pullDiagnosticSource`), so a timeout's catch below still holds a
+    // live handle on the request for the late-answer watch. `withTimeout`
+    // only races it against a timer — the request keeps running server-side
+    // either way, and without this handle an abandoned answer would settle
+    // into the void with no way to observe it.
+    const requestStartedAt = Date.now();
+    const requestPromise = safeSendRequest(state.connection, method, params, signal);
+    const result = (await withTimeout(requestPromise, timeoutMs).catch((err) => {
+        if (isNavTimeoutError(err, timeoutMs)) {
+            recordNavTimeoutTelemetry({
+                method,
+                scope: normalizedPath,
+                budgetMs: timeoutMs,
+                elapsedMs: Date.now() - requestStartedAt,
+            });
+            armNavLateAnswerTelemetry({
+                requestPromise,
+                method,
+                scope: normalizedPath,
+                requestStartedAt,
+            });
+            return undefined;
+        }
         if (err instanceof Error && err.message.startsWith("Timeout after")) {
             return undefined;
         }
@@ -1447,13 +2682,188 @@ signal = getAmbientAbortSignal()) {
     }
     return result;
 }
+/**
+ * #1716: `withTimeout` rejects with this EXACT message (`clients/deadline-
+ * utils.ts`) only when its own timer wins the race — mirrors #1713's
+ * `isPullTimeoutError`. Only the timer-won case is a "the answer might still
+ * be coming" situation worth a late-answer watch; a request that already
+ * failed fast (or a stale-message coincidence) has nothing further to
+ * observe. `navRequest`'s own behavior still falls back to the looser
+ * `startsWith` check afterward, unchanged, so this stricter check only gates
+ * telemetry — never the existing timeout-handling behavior.
+ */
+function isNavTimeoutError(err, timeoutMs) {
+    return err instanceof Error && err.message === `Timeout after ${timeoutMs}ms`;
+}
+/**
+ * #1620 residual 1: `withTimeout` rejects with this EXACT message only when
+ * its own timer wins the race — mirrors #1713's `isPullTimeoutError` and
+ * #1716's `isNavTimeoutError`. `clientShutdown`'s two catches previously
+ * treated ANY rejection (a real timeout OR an immediate protocol error) as
+ * "timed out"; honest for the rolled-up `shutdownOutcome` (both are
+ * "forced"), imprecise for the per-field flag a log reader keys on.
+ */
+function isShutdownTimeoutError(err, timeoutMs) {
+    return err instanceof Error && err.message === `Timeout after ${timeoutMs}ms`;
+}
+// #1716: subject/scope used when a nav request has no `staleCheckPath` (e.g.
+// workspaceSymbol, call-hierarchy follow-ups) — mirrors WORKSPACE_PULL_SCOPE
+// above for the same reason: telemetry identity needs a stable placeholder
+// where there is no real path.
+const NAV_REQUEST_NO_PATH_SCOPE = "*no-path*";
+/**
+ * #1716: `navRequest` is the highest-volume LSP call site — hover,
+ * definition, references, signatureHelp, documentSymbol, workspace/symbol,
+ * call hierarchy all route through it, often several times per turn. A stuck
+ * server can storm timeouts across many methods and files far faster than
+ * the pull-diagnostic path #1713 fixed, so a per-event latency.log write
+ * (that fix's shape) would itself become the flood. Every timeout is still
+ * counted exactly, via the degradation ledger (bounded, in-memory, no I/O),
+ * but only the RISING EDGE — the first occurrence per (method, file) this
+ * session — also pays for a detailed log write. `incrementDegradationCount`'s
+ * return value (`true` on the first occurrence for a kind/subject pair) is
+ * reused as that rising-edge gate instead of a second hand-rolled latch: it
+ * already re-arms at session_start via `resetDegradationLedger`, so this
+ * adds zero new module state. Never throws: telemetry must not perturb a
+ * path that has already decided to return `undefined` regardless.
+ */
+function recordNavTimeoutTelemetry(args) {
+    // #1743: `risingEdgePer: "identity"` is the same gate this site hand-rolled
+    // off `incrementDegradationCount`'s return value, now expressed as an
+    // option. The ledger still counts every timeout exactly, per (method, file).
+    emitBounded("lsp_nav_request_timeout", `${args.method}:${args.scope ?? NAV_REQUEST_NO_PATH_SCOPE}`, {
+        type: "phase",
+        filePath: args.scope ?? NAV_REQUEST_NO_PATH_SCOPE,
+        durationMs: args.elapsedMs,
+        metadata: { method: args.method, effectiveBudgetMs: args.budgetMs },
+    }, {
+        ledgerKind: "lsp-nav-request-timeout",
+        risingEdgePer: "identity",
+        reason: `timeout budget=${args.budgetMs}ms elapsed=${args.elapsedMs}ms`,
+    });
+}
+/**
+ * #1716: nav-request sibling of #1713's `armLateAnswerTelemetry`. A
+ * telemetry-only continuation on the ALREADY-abandoned request promise —
+ * purely observational, never touches `state`, and attaching `.then` here
+ * creates no new timer, socket, or other handle, so it cannot keep the
+ * process alive a moment longer than the pending request already does.
+ *
+ * Bounded the same way as the timeout record above: every late answer is
+ * counted exactly via the ledger, but only the rising edge per (method,
+ * file) also writes an `lsp_nav_late_answer_discarded` record.
+ *
+ * Nav answers are read-once — unlike diagnostics' persistent pull cache,
+ * there is no stale value this could poison — so this exists purely for
+ * observability: telling a dogfood session "truly hung" apart from
+ * "answered late", the same distinction #1713 made possible for pulls.
+ */
+function armNavLateAnswerTelemetry(args) {
+    args.requestPromise.then(() => {
+        try {
+            const elapsedMs = Date.now() - args.requestStartedAt;
+            // #1743: same rising-edge gate as the timeout record above, now
+            // carried by the helper instead of hand-rolled here.
+            emitBounded("lsp_nav_late_answer_discarded", `${args.method}:${args.scope ?? NAV_REQUEST_NO_PATH_SCOPE}`, {
+                type: "phase",
+                filePath: args.scope ?? NAV_REQUEST_NO_PATH_SCOPE,
+                durationMs: elapsedMs,
+                metadata: { method: args.method },
+            }, {
+                ledgerKind: "lsp-nav-late-answer",
+                risingEdgePer: "identity",
+                reason: `late nav answer discarded after ${elapsedMs}ms`,
+            });
+        }
+        catch {
+            // Telemetry must never break the observed path.
+        }
+    }, () => {
+        // The abandoned request eventually failed rather than answering —
+        // not an "answer discarded" event. Nothing more to record here; this
+        // handler exists so the request's eventual rejection never surfaces
+        // as an unhandled rejection.
+    });
+}
+/**
+ * #1969: pick the request the liveness probe may send to THIS server.
+ *
+ * The probe only needs a round-trip, so any request works — but it must be one
+ * the server advertised. #1277 originally hardcoded `workspace/symbol` because
+ * it needs no open document, and treated `MethodNotFound` as proof of life.
+ * That rationale is sound for the round-trip, and wrong as a default: a server
+ * that does not implement the method logs an error for every probe. ast-grep's
+ * tower_lsp backend wrote "got a 'workspace/symbol' request, but it is not
+ * implemented" on each one, and its `code=1` deaths clustered after them
+ * (#1969). pi-lens must not keep pushing an unimplemented method at a server
+ * just to learn it is awake.
+ *
+ * The ladder, best first:
+ *  1. `workspace/symbol` when `workspaceSymbolProvider` is advertised — the
+ *     #1277 probe, unchanged, and still needs no open document.
+ *  2. `textDocument/documentSymbol` on an already-open document when
+ *     `documentSymbolProvider` is advertised. Read-only, scoped to a document
+ *     the server already has, and cheap.
+ *  3. `textDocument/hover` at the start of an already-open document when
+ *     `hoverProvider` is advertised. This step is what keeps ast-grep covered:
+ *     `docs/servercapabilities.md:53` records its advertised set as
+ *     codeActionProvider, executeCommandProvider, hoverProvider and
+ *     textDocumentSync — no symbol provider of either kind. #1714's own
+ *     measurement (clients/lsp/index.ts, `paceAuxNotify`) timed hover against
+ *     the real ast-grep binary at 1 ms idle and 2086 ms behind 30 `didOpen`s,
+ *     the same ordering proof it recorded for `workspace/symbol`. So the
+ *     notify throttle keeps a real barrier here, not a hollow one.
+ *  4. Nothing. The caller then reports liveness from process and connection
+ *     state alone, and records that it did.
+ *
+ * `MethodNotFound`-counts-as-alive still holds for every probe: dynamic
+ * registration can retract a capability after `initialize`, and an error reply
+ * is still a reply. What changes is that pi-lens no longer PROVOKES that error
+ * on every probe.
+ */
+function chooseLivenessProbe(state) {
+    if (state.operationSupport?.workspaceSymbol === true) {
+        return {
+            method: "workspace/symbol",
+            params: { query: LIVENESS_PING_QUERY },
+        };
+    }
+    const openUri = firstOpenDocumentUri(state);
+    if (openUri === undefined)
+        return undefined;
+    if (state.operationSupport?.documentSymbol === true) {
+        return {
+            method: "textDocument/documentSymbol",
+            params: { textDocument: { uri: openUri } },
+        };
+    }
+    if (state.operationSupport?.hover === true) {
+        return {
+            method: "textDocument/hover",
+            params: {
+                textDocument: { uri: openUri },
+                position: { line: 0, character: 0 },
+            },
+        };
+    }
+    return undefined;
+}
+/** URI of any document this client currently holds open, if it holds one. */
+function firstOpenDocumentUri(state) {
+    for (const normalizedPath of state.openDocuments) {
+        const uri = state.openDocumentUris?.get(normalizedPath);
+        if (uri !== undefined)
+            return uri;
+    }
+    return undefined;
+}
 // #1277: cheap liveness round-trip used by the silent-clean gates in
 // `index.ts`. `isAlive()`/`checkAlive()` only look at process/connection
 // state — a server that accepted the notify write and then wedged (still
 // running, connection still open, just never replying) reads as "alive" by
 // those checks even though it will never answer anything again. This sends a
-// real request (`workspace/symbol`, chosen because it needs no open document)
-// and reports whether the connection round-tripped it — success, a genuine
+// real request (see `chooseLivenessProbe` for which, #1969) and reports
+// whether the connection round-tripped it — success, a genuine
 // protocol-level error (e.g. MethodNotFound), and a stream-destroyed/
 // cancelled response (safeSendRequest swallows those to `undefined`, so the
 // final `isClientAlive` re-check is what catches "died mid-flight") ALL count
@@ -1463,10 +2873,30 @@ signal = getAmbientAbortSignal()) {
 async function clientPingLiveness(state, timeoutMs = LIVENESS_PING_TIMEOUT_MS) {
     if (!isClientAlive(state))
         return false;
+    const probe = chooseLivenessProbe(state);
+    if (probe === undefined) {
+        // #1969: no advertised method to probe with, so this answer comes from
+        // process and connection state alone — exactly the checks the probe
+        // exists to strengthen. Say so in the ledger rather than let a weaker
+        // verdict pass as the strong one. Rising edge per server, via the
+        // ledger's own tally; the count carries the repeats.
+        try {
+            incrementDegradationCount({
+                kind: "lsp-liveness-probe-unsupported",
+                subject: state.serverId,
+                reason: "no advertised request method to probe with (no " +
+                    "workspaceSymbolProvider, and no open document with " +
+                    "documentSymbolProvider or hoverProvider); liveness from " +
+                    "process and connection state only",
+            });
+        }
+        catch {
+            // Telemetry must never break the observed path.
+        }
+        return isClientAlive(state);
+    }
     try {
-        await withTimeout(safeSendRequest(state.connection, "workspace/symbol", {
-            query: LIVENESS_PING_QUERY,
-        }), timeoutMs);
+        await withTimeout(safeSendRequest(state.connection, probe.method, probe.params), timeoutMs);
     }
     catch (err) {
         if (err instanceof Error && err.message.startsWith("Timeout after")) {
@@ -1569,10 +2999,14 @@ export async function runReadOnlyServerCommand(state, command, args, timeoutMs =
 }
 function validateWorkspaceEditVersions(state, edit) {
     for (const change of edit.documentChanges ?? []) {
-        if (typeof change !== "object" || change === null || !("textDocument" in change))
+        if (typeof change !== "object" ||
+            change === null ||
+            !("textDocument" in change))
             continue;
         const textDocument = change.textDocument;
-        if (!textDocument || typeof textDocument.uri !== "string" || textDocument.version == null)
+        if (!textDocument ||
+            typeof textDocument.uri !== "string" ||
+            textDocument.version == null)
             continue;
         const current = state.documentVersions.get(normalizeMapKey(uriToPath(textDocument.uri)));
         if (current === undefined || current !== textDocument.version) {
@@ -1639,7 +3073,10 @@ async function resolveCodeActionBestEffort(state, action) {
         return action;
     const merged = { ...action, ...resolved };
     return merged.edit
-        ? { ...merged, edit: await normalizeClientWorkspaceEdit(state, merged.edit) }
+        ? {
+            ...merged,
+            edit: await normalizeClientWorkspaceEdit(state, merged.edit),
+        }
         : merged;
 }
 // --- Client Factory ---
@@ -1736,10 +3173,21 @@ export async function createLSPClient(options) {
     // for concurrent waitForDiagnostics calls.
     const diagnosticEmitter = new EventEmitter();
     diagnosticEmitter.setMaxListeners(50);
+    // SAFETY: three fields below are seeded `undefined as unknown as T` because
+    // they cannot be built here. `workspaceDiagnosticsSupport` and
+    // `operationSupport` are derived from the server's `initialize` result, and
+    // `watchQueue`'s flush closure needs `state` itself. Each is assigned
+    // in this same function before `state` reaches any caller:
+    // `state.watchQueue` on the statement immediately after this literal, and
+    // the two capability fields right after the `initialize` handshake
+    // returns. Reorder that and the fields are genuinely `undefined` at their
+    // declared non-optional types.
     const state = {
         isConnected: true,
         isDestroyed: false,
         shutdownRequested: false,
+        shutdownPromise: undefined,
+        shutdownOptions: undefined,
         exitedAt: undefined,
         connectionDisposed: false,
         lastError: undefined,
@@ -1754,11 +3202,15 @@ export async function createLSPClient(options) {
         documentOpenedAt: new Map(),
         diagnosticEmitter,
         diagnosticsVersion: 0,
+        diagnosticsVersionsByPath: new Map(),
         documentVersions: new Map(),
         diagnosticDocVersions: new Map(),
         documentContentHashes: new Map(),
         diagnosticBindings: new Map(),
         pullResultIds: new Map(),
+        documentPullDiagnosticsBySource: new Map(),
+        pullGenerations: new Map(),
+        pullRequestSequences: new Map(),
         workspacePullResultCache: new Map(),
         openDocuments: new Set(),
         closedDocuments: new Set(),
@@ -1766,10 +3218,14 @@ export async function createLSPClient(options) {
         pendingOpens: new Set(),
         projectIdentityProbedFiles: new Set(),
         // these are filled in after initialize — cast to avoid two-phase init
-        workspaceDiagnosticsSupport: undefined,
+        workspaceDiagnosticsSupport: 
+        // SAFETY: initialize fills this capability before any workspace diagnostic request.
+        undefined,
+        // SAFETY: initialize fills this capability before operation dispatch.
         operationSupport: undefined,
         staticDiagnosticsMode: "push-only",
         positionEncoding: "utf-16",
+        syncKind: TEXT_DOCUMENT_SYNC_KIND_FULL,
         dynamicRegistrations: new Map(),
         advertisedCommands: new Set(),
         serverEditsAllowed: 0,
@@ -1779,6 +3235,7 @@ export async function createLSPClient(options) {
         root,
         lspProcess,
         // two-phase: the flush closure needs `state` (below)
+        // SAFETY: state construction completes before the flush closure can run.
         watchQueue: undefined,
     };
     // #271: batch per-file workspace/didChangeWatchedFiles into one notification
@@ -1804,6 +3261,18 @@ export async function createLSPClient(options) {
         }), initializeTimeoutMs);
     }
     catch (err) {
+        // #1969: claim this kill BEFORE issuing it. `setupConnectionLifecycle`
+        // ran above, so its `exit` and `close` handlers are already armed on
+        // this child, and both read `state.shutdownRequested` to tell a crash
+        // from a teardown we asked for. The kill below is one we asked for.
+        // Without this line it reported as an unprompted death, fabricating a
+        // `lsp-server-unexpected-close` entry reading
+        // "code=1 signal=none stderr=empty" — character for character the
+        // ast-grep signature this issue exists to make trustworthy — every time
+        // a server merely failed to complete its handshake. It also silenced a
+        // false `lsp_server_unexpected_exit` latency line that this path has
+        // been writing since the #615 follow-up.
+        state.shutdownRequested = true;
         // Hard-kill the hung process so it doesn't become a zombie.
         // SIGTERM alone is unreliable on Windows for cmd.exe/PowerShell trees.
         const pid = lspProcess.pid;
@@ -1811,7 +3280,7 @@ export async function createLSPClient(options) {
         // A child registered above (recordLspChild) but never reaching a healthy
         // createLSPClient return must still be deregistered here — otherwise the
         // registry keeps a stale entry for a process we just killed.
-        void removeLspChild(pid).catch((err) => {
+        void removeLspChild(pid, extractSpawnMarker(lspProcess.args)).catch((err) => {
             // best-effort — a stale registry entry is harmless (the reaper's
             // liveness check will find it dead on the next sweep regardless)
             logLatency({
@@ -1872,6 +3341,7 @@ export async function createLSPClient(options) {
         detectWorkspaceDiagnosticsSupport(initResult);
     state.operationSupport = detectOperationSupport(initResult);
     state.positionEncoding = negotiatePositionEncoding(initResult?.capabilities);
+    state.syncKind = negotiateSyncKind(initResult?.capabilities);
     state.rawCapabilityKeys = Object.keys(initResult?.capabilities ??
         {}).sort((a, b) => a.localeCompare(b));
     for (const cmd of detectExecuteCommands(initResult)) {
@@ -1913,6 +3383,9 @@ export async function createLSPClient(options) {
             async change(filePath, content) {
                 return handleNotifyChange(state, filePath, content);
             },
+            watchedFileChange(filePath, type) {
+                handleNotifyExternalChange(state, filePath, type);
+            },
         },
         getDiagnostics(filePath) {
             return getMergedDiagnosticsForPath(state, normalizeMapKey(filePath));
@@ -1920,6 +3393,9 @@ export async function createLSPClient(options) {
         getDiagnosticBinding(filePath) {
             return state.diagnosticBindings.get(normalizeMapKey(filePath));
         },
+        getDiagnosticsVersionForPath(filePath) {
+            return diagnosticsVersionForPath(state, normalizeMapKey(filePath));
+        },
         getAllDiagnostics() {
             const result = new Map();
             const keys = new Set([
@@ -1936,10 +3412,12 @@ export async function createLSPClient(options) {
             return result;
         },
         getTrackedDiagnosticPaths() {
-            return [...new Set([
+            return [
+                ...new Set([
                     ...state.pushDiagnostics.keys(),
                     ...state.documentPullDiagnostics.keys(),
-                ])].map((filePath) => process.platform === "win32" ? filePath.replace(/\//g, "\\") : filePath);
+                ]),
+            ].map((filePath) => process.platform === "win32" ? filePath.replace(/\//g, "\\") : filePath);
         },
         pruneDiagnostics(predicate) {
             let removed = 0;
@@ -1978,6 +3456,9 @@ export async function createLSPClient(options) {
         async executeCommand(command, args, mutationContext) {
             return runServerCommand(state, command, args, EXECUTE_COMMAND_TIMEOUT_MS, mutationContext);
         },
+        async executeReadOnlyCommand(command, args) {
+            return runReadOnlyServerCommand(state, command, args);
+        },
         get diagnosticsVersion() {
             return state.diagnosticsVersion;
         },
@@ -2143,14 +3624,25 @@ export async function createLSPClient(options) {
     };
 }
 // Helper to safely send notifications - catches stream destruction
+/**
+ * Returns `true` once the notification was actually handed to the transport,
+ * `false` when a stream error was swallowed (connection error handlers will
+ * update state separately). #1669 review F7: callers that mirror what they
+ * just told the server locally (`recordSentContent`) MUST gate on this
+ * return value — recording a send that never left the process would desync
+ * the mirror from what the server actually has, with nothing to self-heal
+ * it (the next Incremental range would be computed against content the
+ * server never saw).
+ */
 async function safeSendNotification(connection, method, params) {
     try {
         await connection.sendNotification(method, params);
+        return true;
     }
     catch (err) {
         if (isStreamError(err)) {
             // Silently ignore - stream was destroyed, connection error handlers will update state
-            return;
+            return false;
         }
         throw err;
     }
@@ -2162,7 +3654,7 @@ async function safeSendRequest(connection, method, params,
 // vscode-jsonrpc's CancellationToken → an LSP `$/cancelRequest` notification,
 // so a server stops computing a result the agent has already abandoned (#238
 // Item 1). The rejection that follows is swallowed (treated as `undefined`).
-signal) {
+signal, settlement) {
     // Already abandoned before we even sent — don't bother the server.
     if (signal?.aborted)
         return undefined;
@@ -2189,9 +3681,13 @@ signal) {
                 return (await send());
             }
             catch (err) {
-                if (isStreamError(err) || isCancellationError(err)) {
-                    // Stream destroyed, or we cancelled the request on abort — either
-                    // way there is no result to return.
+                if (isCancellationError(err)) {
+                    if (settlement)
+                        settlement.cancelled = true;
+                    return undefined;
+                }
+                if (isStreamError(err)) {
+                    // Stream destroyed; connection handlers update client state separately.
                     return undefined;
                 }
                 if (isContentModifiedError(err)) {