@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

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

@@ -7,26 +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 { 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
@@ -47,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];
@@ -125,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 —
@@ -145,12 +177,46 @@ 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
 // stops a hung server from blocking the caller forever. On timeout the command
 // may still be applying server-side; we surface that rather than pretend it ran.
 const EXECUTE_COMMAND_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_EXECUTE_COMMAND_TIMEOUT_MS", 30_000);
+// #1412 H1: short ceiling for the read-only tsserver project-identity probe.
+// This is a telemetry sample, not a mutation — it must never hold the door
+// open for anything close to EXECUTE_COMMAND_TIMEOUT_MS.
+const PROBE_COMMAND_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_PROJECT_IDENTITY_PROBE_TIMEOUT_MS", 2_500);
 const LSP_CRASH_CODES = new Set([
     "ERR_STREAM_DESTROYED",
     "ERR_STREAM_WRITE_AFTER_END",
@@ -409,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,
@@ -430,13 +501,191 @@ 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));
 }
-function clearDiagnosticsForPath(state, 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);
+    if (pending)
+        clearTimeout(pending);
+    state.pendingDiagnostics?.delete(normalizedPath);
     state.pushDiagnosticTimestamps?.delete(normalizedPath);
     state.documentPullDiagnostics?.delete(normalizedPath);
     state.documentPullDiagnosticTimestamps?.delete(normalizedPath);
@@ -446,14 +695,99 @@ 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);
 }
+/**
+ * #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
+            .map((diagnostic) => diagnostic.code)
+            .filter((code) => code !== undefined)
+            .map(String)),
+    ].slice(0, 8);
+    const trackedVersion = state.diagnosticsVersionsByPath?.get(normalizedPath);
+    logLatency({
+        type: "phase",
+        phase: "lsp_typescript_diagnostic_sequence",
+        filePath: normalizedPath,
+        durationMs,
+        metadata: {
+            serverId: state.serverId,
+            outcome: "settled",
+            launchVariant: state.launchVariant ?? "unknown",
+            publicationIndex: state.diagnosticPublicationCounts.get(normalizedPath) ?? 0,
+            version: trackedVersion ?? "pull-unversioned",
+            diagnosticCount: diagnostics.length,
+            diagnosticCodes,
+            elapsedSinceDidOpenMs,
+            settledReturn: true,
+            settleSource: pullSettleSource,
+        },
+    });
+}
 /**
  * #1095: fingerprint the EXACT didOpen/didChange payload text at SEND time and
  * tag it with the document version it was sent as, so a later
@@ -466,8 +800,94 @@ 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 = {
     "textDocument/definition": "definition",
@@ -484,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",
         };
     }
@@ -511,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 : {};
@@ -527,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];
@@ -541,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.
@@ -558,7 +982,73 @@ export function setupIncomingHandlers(state, initialization) {
                 message: `server=${state.serverId} pubVersion=${docVersion} docVersion=${state.documentVersions?.get(normalizedPath)} diags=${newDiags.length}`,
             });
         }
-        const strategy = getStrategy(state.serverId);
+        const strategy = getStrategy(state.serverId, state.launchVariant);
+        // Publication counting and code extraction exist only for the
+        // TypeScript diagnostic-sequence telemetry; skip the bookkeeping for
+        // every other push server on this hot receive path.
+        const isTypeScriptTelemetry = state.serverId === "typescript";
+        const publicationIndex = isTypeScriptTelemetry
+            ? (state.diagnosticPublicationCounts.get(normalizedPath) ?? 0) + 1
+            : 0;
+        if (isTypeScriptTelemetry) {
+            state.diagnosticPublicationCounts.set(normalizedPath, publicationIndex);
+        }
+        const diagnosticCodes = isTypeScriptTelemetry
+            ? [
+                ...new Set(newDiags
+                    .map((diagnostic) => diagnostic.code)
+                    .filter((code) => code !== undefined)
+                    .map(String)),
+            ].slice(0, 8)
+            : [];
+        // #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() -
+                (state.documentOpenedAt.get(normalizedPath) ?? Date.now()));
+            logLatency({
+                type: "phase",
+                phase: "lsp_typescript_diagnostic_sequence",
+                filePath: normalizedPath,
+                durationMs,
+                metadata: {
+                    serverId: state.serverId,
+                    outcome: settledReturn ? "settled" : "published",
+                    launchVariant: state.launchVariant ?? "unknown",
+                    publicationIndex,
+                    version: docVersion ?? "push-unversioned",
+                    diagnosticCount: newDiags.length,
+                    diagnosticCodes,
+                    elapsedSinceDidOpenMs,
+                    settledReturn,
+                    settleSource,
+                },
+            });
+        };
         // Record the document version these diagnostics were computed against
         // (when the server reports it) so waitForDiagnostics can reject results
         // that lag behind the latest didChange instead of serving them as fresh.
@@ -603,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;
@@ -622,10 +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);
+            // Immediate settle — no debounce wait to measure.
+            logSequence(true, "first-push", 0);
             return;
         }
+        // A raw per-publication receipt, not itself a settle.
+        logSequence(false, "publication", 0);
         const existingTimer = state.pendingDiagnostics.get(normalizedPath);
         if (existingTimer)
             clearTimeout(existingTimer);
@@ -636,8 +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);
+            // 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);
     });
@@ -646,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);
@@ -713,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
@@ -771,26 +1423,160 @@ function setupConnectionLifecycle(state, recentStderr) {
         }
     });
 }
+/** 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" };
@@ -803,13 +1589,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.
@@ -817,30 +1618,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
@@ -850,20 +1664,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;
@@ -879,9 +1859,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);
@@ -899,15 +1877,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;
@@ -919,8 +1940,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,
@@ -966,6 +2032,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;
     }
@@ -973,7 +2060,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
@@ -997,11 +2094,17 @@ 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")
+        if (outcome.status === "found") {
+            logTypeScriptPullSettle(state, normalizedPath, Date.now() - pullSettleStartedAt, pullSettleSource);
             return;
+        }
         let sawClean = outcome.status === "clean";
-        const strategy = getStrategy(state.serverId);
+        const strategy = getStrategy(state.serverId, state.launchVariant);
         const retryBudgetMs = strategy.pullRetryBudgetMs > 0
             ? Math.min(timeoutMs, strategy.pullRetryBudgetMs)
             : 0;
@@ -1016,10 +2119,16 @@ export async function clientWaitForDiagnostics(state, filePath, timeoutMs, optio
             if (outcome.status === "clean")
                 sawClean = true;
         }
-        if (options.pullOnly)
+        if (options.pullOnly) {
+            if (outcome.status === "found" || sawClean) {
+                logTypeScriptPullSettle(state, normalizedPath, Date.now() - pullSettleStartedAt, pullSettleSource);
+            }
             return;
-        if (outcome.status === "found" || sawClean)
+        }
+        if (outcome.status === "found" || sawClean) {
+            logTypeScriptPullSettle(state, normalizedPath, Date.now() - pullSettleStartedAt, pullSettleSource);
             return;
+        }
     }
     if (hasFreshDiagnostics() &&
         !isVersionStale() &&
@@ -1037,7 +2146,7 @@ export async function clientWaitForDiagnostics(state, filePath, timeoutMs, optio
                 clearTimeout(debounceTimer);
             // Adaptive debounce: use time since last push to compute remaining
             // wait instead of always waiting the full debounce window.
-            const strategy = getStrategy(state.serverId);
+            const strategy = getStrategy(state.serverId, state.launchVariant);
             const hit = state.pushDiagnosticTimestamps.get(normalizedPath);
             const timeSincePush = hit ? Date.now() - hit : Infinity;
             const remaining = Math.max(0, strategy.debounceMs - timeSincePush);
@@ -1056,6 +2165,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;
@@ -1080,7 +2204,7 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
         // Scanners that only re-scan on a fresh open (opengrep ignores didChange):
         // close + reopen so the re-edit actually triggers a re-scan instead of
         // silently publishing nothing.
-        if (getStrategy(state.serverId).reopenOnResync) {
+        if (getStrategy(state.serverId, state.launchVariant).reopenOnResync) {
             await safeSendNotification(state.connection, "textDocument/didClose", {
                 textDocument: { uri },
             });
@@ -1096,25 +2220,31 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
             // for a stale view (worse than "unknown"). Monotonic versions make that
             // late echo strictly older → dropped by isSupersededPush → never bound.
             state.documentVersions.set(normalizedPath, version);
+            state.documentOpenedAt.set(normalizedPath, Date.now());
+            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);
     state.documentVersions.set(normalizedPath, 0);
+    state.documentOpenedAt.set(normalizedPath, Date.now());
+    state.diagnosticPublicationCounts.set(normalizedPath, 0);
     clearDiagnosticsForPath(state, normalizedPath); // always clear for initial open
     // Send workspace notification first (like opencode does).
     // Skipped in silent mode — cascade reads a file for diagnostics,
@@ -1141,14 +2271,31 @@ 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);
     state.openDocumentUris?.set(normalizedPath, uri);
+    // Telemetry is deliberately detached after didOpen succeeds.
+    // #1412 H1: routed through runReadOnlyServerCommand, NOT runServerCommand —
+    // the probe must never open the serverEditsAllowed/activeMutationContext
+    // mutation-acceptance window; it is a diagnostic sample, not a mutation, and
+    // carries its own short PROBE_COMMAND_TIMEOUT_MS backstop. The probe itself
+    // is classic-only and swallows every failure.
+    void probeTsserverProjectIdentity({
+        serverId: state.serverId,
+        launchVariant: state.launchVariant,
+        clientRoot: state.root,
+        file: filePath,
+        normalizedFile: normalizedPath,
+        probedFiles: state.projectIdentityProbedFiles ??
+            (state.projectIdentityProbedFiles = new Set()),
+        commandChannel: {
+            executeCommand: (command, args) => runReadOnlyServerCommand(state, command, args),
+        },
+    });
 }
 export async function handleNotifyChange(state, filePath, content) {
     if (!isClientAlive(state))
@@ -1158,11 +2305,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);
-        recordSentContent(state, normalizedPath, 0, content);
+        state.documentOpenedAt.set(normalizedPath, Date.now());
+        state.diagnosticPublicationCounts.set(normalizedPath, 0);
+        if (fallbackOpenSent)
+            recordSentContent(state, normalizedPath, 0, content);
         state.openDocuments.add(normalizedPath);
         state.openDocumentUris?.set(normalizedPath, uri);
         return;
@@ -1172,11 +2327,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) {
@@ -1187,16 +2343,84 @@ 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);
     state.closedDocuments?.add(normalizedPath);
     state.openDocumentUris?.delete(normalizedPath);
     state.documentVersions.delete(normalizedPath);
+    state.documentOpenedAt.delete(normalizedPath);
+    state.diagnosticPublicationCounts.delete(normalizedPath);
+    // #1412 L1: projectIdentityProbedFiles is a claim-once memo scoped to the
+    // document's open lifetime (re-probing a closed-then-reopened file is
+    // harmless and cheap) — mirror openDocuments' own per-close cleanup so it
+    // doesn't grow unbounded across a long session's worth of open/close churn.
+    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;
@@ -1208,58 +2432,132 @@ export async function clientShutdown(state, options = {}) {
     state.pendingOpens.clear();
     state.openDocuments.clear();
     state.openDocumentUris?.clear();
+    // #1412 L1: mirror openDocuments' clear — a shut-down/evicted client's
+    // probe memo is moot along with everything else document-scoped.
+    state.projectIdentityProbedFiles?.clear();
     // #271: drop any pending watched-files batch + its timer (a dying client's
     // queued FS changes are moot, and the timer must not outlive the connection).
     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
@@ -1308,7 +2606,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;
         }
@@ -1326,6 +2647,109 @@ 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.
+    });
+}
 // #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
@@ -1409,12 +2833,53 @@ export async function runServerCommand(state, command, args, timeoutMs = EXECUTE
             state.activeMutationContext = undefined;
     }
 }
+// #1412 H1/H2: read-only sibling of runServerCommand for telemetry/identity
+// probes that must NOT participate in the mutation-acceptance window. Unlike
+// runServerCommand this never touches serverEditsAllowed, activeMutationDepth,
+// or activeMutationContext — a probe firing mid-flight must leave a concurrent
+// real executeCommand's mutation context untouched, and must not itself open
+// the workspace/applyEdit acceptance window (client.ts's applyEdit handler
+// gates on serverEditsAllowed > 0). Preserves the allowlist-by-advertisement
+// invariant. Short PROBE_COMMAND_TIMEOUT_MS backstop — this is a diagnostic
+// sample, not a mutation, and must never hold anything up for anywhere near
+// EXECUTE_COMMAND_TIMEOUT_MS.
+export async function runReadOnlyServerCommand(state, command, args, timeoutMs = PROBE_COMMAND_TIMEOUT_MS) {
+    if (!isClientAlive(state)) {
+        return { executed: false, reason: "lsp client not alive" };
+    }
+    if (!state.advertisedCommands.has(command)) {
+        return {
+            executed: false,
+            reason: `command "${command}" is not advertised by the ${state.serverId} server`,
+        };
+    }
+    try {
+        const result = await withTimeout(safeSendRequest(state.connection, "workspace/executeCommand", {
+            command,
+            arguments: args ?? [],
+        }), timeoutMs);
+        return { executed: true, result };
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("Timeout after")) {
+            return {
+                executed: false,
+                reason: `workspace/executeCommand timed out after ${timeoutMs}ms`,
+            };
+        }
+        throw err;
+    }
+}
 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) {
@@ -1481,7 +2946,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 ---
@@ -1578,10 +3046,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,
@@ -1592,23 +3071,34 @@ export async function createLSPClient(options) {
         documentPullDiagnosticTimestamps: new Map(),
         pullFailureHistory: [],
         pendingDiagnostics: new Map(),
+        diagnosticPublicationCounts: new Map(),
+        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(),
         openDocumentUris: new Map(),
         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,
@@ -1618,6 +3108,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
@@ -1650,7 +3141,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({
@@ -1711,6 +3202,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)) {
@@ -1752,6 +3244,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));
@@ -1759,6 +3254,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([
@@ -1775,10 +3273,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;
@@ -1817,6 +3317,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;
         },
@@ -1982,14 +3485,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;
     }
@@ -2001,7 +3515,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;
@@ -2028,9 +3542,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)) {