pi-lens 4.1.2 → 4.1.4

package/dist/clients/lsp/client.js

@@ -9,19 +9,22 @@
  */
 import { spawn as nodeSpawn } from "node:child_process";
 import { EventEmitter } from "node:events";
-import { access, readFile } from "node:fs/promises";
+import { access, lstat, 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 { incrementDegradationCount } from "../degradation-ledger.js";
+import { minimatch } from "../deps/minimatch.js";
+import { incrementDegradationCount, recordDegradationOnce, } 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 { workspaceDiagnosticsCacheSessionStart } from "./workspace-diagnostics-session.js";
 import { logLatency } from "../latency-logger.js";
 import { newLspMutationCorrelationId, } from "../lsp-mutation.js";
+import { getProcessSingleton } from "../process-singletons.js";
 import { getAmbientAbortSignal } from "../safe-spawn.js";
 import { raceToCompletion } from "./aggregation.js";
 import { hashDiagnosticContent, } from "./diagnostic-binding.js";
@@ -67,7 +70,7 @@ function extractSpawnMarker(args) {
     return undefined;
 }
 // --- Constants ---
-const INITIALIZE_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_INIT_TIMEOUT_MS", 15_000); // 15s — npx downloads are handled by ensureTool, not here
+export const INITIALIZE_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_INIT_TIMEOUT_MS", 15_000); // 15s — npx downloads are handled by ensureTool, not here
 /**
  * The client capabilities advertised in every `initialize`. The textDocument set
  * is intentionally COMPLETE and spec-compliant: servers built on
@@ -96,6 +99,11 @@ export const CLIENT_CAPABILITIES = {
         workspaceFolders: true,
         configuration: true,
         didChangeWatchedFiles: { dynamicRegistration: true },
+        fileOperations: {
+            dynamicRegistration: false,
+            willRename: true,
+            didRename: true,
+        },
     },
     textDocument: {
         synchronization: {
@@ -115,7 +123,27 @@ export const CLIENT_CAPABILITIES = {
         implementation: { dynamicRegistration: false },
         references: { dynamicRegistration: false },
         documentSymbol: { dynamicRegistration: false },
-        codeAction: { dynamicRegistration: false },
+        codeAction: {
+            dynamicRegistration: false,
+            dataSupport: true,
+            resolveSupport: { properties: ["edit", "command"] },
+            // #1971 review: without literal support, LSP 3.17 constrains
+            // textDocument/codeAction responses to Command[] — resolve of an edit
+            // would then be protocol-invalid. We parse CodeAction objects.
+            codeActionLiteralSupport: {
+                codeActionKind: {
+                    valueSet: [
+                        "quickfix",
+                        "refactor",
+                        "refactor.extract",
+                        "refactor.inline",
+                        "refactor.rewrite",
+                        "source",
+                        "source.organizeImports",
+                    ],
+                },
+            },
+        },
         rename: { dynamicRegistration: false },
         publishDiagnostics: {
             relatedInformation: true,
@@ -253,6 +281,78 @@ function installCrashGuard() {
         throw reason instanceof Error ? reason : new Error(String(reason));
     });
 }
+/** #2065: bound both the path count and UTF-16 heap represented by retained
+ * Incremental-sync text. The map keeps the newest sent paths when evicting. */
+export const MAX_INCREMENTAL_TEXT_RETAINED_ENTRIES = 128;
+export const MAX_INCREMENTAL_TEXT_RETAINED_BYTES = 64 * 1024 * 1024;
+/**
+ * #2065 fix round 1: a PROJECTION registry, not a second source of truth for
+ * "which clients are live" — its only job is letting `memory-sampler.ts`
+ * total retained-text bytes across clients without importing `LSPService`.
+ * Considered projecting straight off `LSPService.state.clients` (the
+ * manager's own client map, `clients/lsp/index.ts`) instead of keeping this
+ * Set at all, and rejected it for two reasons:
+ *   1. Import direction: `clients/lsp/index.ts` imports THIS file, not the
+ *      reverse, so reading `LSPService.state.clients` from here (or from
+ *      `memory-sampler.ts`, which every other snapshot in that module reaches
+ *      by importing the owning subsystem directly, e.g.
+ *      `getReviewGraphWorkspaceCacheSnapshot`, `getDispatchCascadeCacheStats`)
+ *      means importing the higher-level manager from the lower-level client
+ *      module — a layering inversion, not a cycle fix.
+ *   2. `LSPService.state.clients` is ITSELF only lazily reconciled against
+ *      real client death — a crashed client's slot is noticed and evicted on
+ *      the next `getClientForFile` attach, not at crash time (see
+ *      `markExitedIfUnset`'s docstring above). Projecting off it would not
+ *      give memory-sampler any more real-time accuracy than this Set; it
+ *      would just move the same "who deregisters, and when" question onto a
+ *      larger, higher-risk surface (the manager's routing map) for no gain.
+ *
+ * What makes this safe to keep as a second collection: it has exactly ONE
+ * lifecycle seam. `spawnClient` is the only writer that adds (below), and
+ * `disposeClientConnection` is the only writer that removes — and that
+ * function is itself the single convergence point every permanent-death path
+ * (`connection.onError`, `connection.onClose`, the process `exit` handler,
+ * and `clientShutdownOnce`'s `finally`) already funnels through, guarded by
+ * the same `connectionDisposed` idempotency flag that gates the connection
+ * teardown itself. Membership can therefore never drift from "has this
+ * client's connection been torn down" — there is nowhere else in the file
+ * that can flip a client from alive to permanently dead without going
+ * through `disposeClientConnection`.
+ *
+ * PROCESS-SCOPED, not module-scoped (#2130 criterion 2). This Set is what
+ * `memory_sample.subsystems.lsp.clients` counts, and a module-scope Set counted
+ * only the clients this MODULE EVALUATION spawned. pi evaluates the pi-lens
+ * graph up to nine times per process (#2146, measured `host_boot` = 9) and each
+ * evaluation builds its own `LSPService` and fleet (#2157 item 1), so a
+ * secondary root's servers — spawned by a later evaluation — were invisible to
+ * the sampler running in the first. That is the reported symptom exactly:
+ * `clients: 1` in `memory_sample` beside `lspChildCount: 2` in `instances.json`,
+ * with two tsservers alive. Sharing the Set through `getProcessSingleton` makes
+ * both the count and `roots` span every root the process serves.
+ *
+ * Both seams share it, which is the whole requirement: sharing only the add
+ * site would build a Set that never shrinks, a worse leak than the undercount.
+ */
+const ACTIVE_CLIENTS_FAMILY = "lsp-client.active-clients";
+/** Bump when the cell's shape changes. */
+const ACTIVE_CLIENTS_VERSION = 1;
+function activeLspClientSet() {
+    return getProcessSingleton(ACTIVE_CLIENTS_FAMILY, ACTIVE_CLIENTS_VERSION, () => new Set());
+}
+export function getLspDocumentTextRetentionSnapshot() {
+    let entries = 0;
+    let bytes = 0;
+    const roots = new Set();
+    const active = activeLspClientSet();
+    for (const state of active) {
+        entries += state.incrementalTextRetainedEntries ?? 0;
+        bytes += state.incrementalTextRetainedBytes ?? 0;
+        if (typeof state.root === "string" && state.root.length > 0) {
+            roots.add(state.root);
+        }
+    }
+    return { clients: active.size, entries, bytes, roots: roots.size };
+}
 function isClientAlive(state) {
     return (state.isConnected && !state.isDestroyed && !state.lspProcess.process.killed);
 }
@@ -260,6 +360,13 @@ function disposeClientConnection(state) {
     if (state.connectionDisposed)
         return;
     state.connectionDisposed = true;
+    // #2065 fix round 1: this is the ONE place every permanent-death path
+    // converges (onError, onClose, the process 'exit' handler, and
+    // clientShutdownOnce's finally) — see setupConnectionLifecycle below and
+    // clientShutdownOnce. Deregistering here, guarded by the idempotency flag
+    // above, means a crash that never re-attaches still frees its retained
+    // text instead of pinning it for the rest of the process lifetime.
+    activeLspClientSet().delete(state);
     try {
         state.connection.dispose();
     }
@@ -623,7 +730,7 @@ function retirePullSource(state, identifier) {
     for (const source of [state.pullResultIds, state.pullRequestSequences]) {
         if (!source)
             continue;
-        for (const key of [...source.keys()]) {
+        for (const key of source.keys()) {
             if (key.endsWith(suffix))
                 source.delete(key);
         }
@@ -788,6 +895,50 @@ function logTypeScriptPullSettle(state, normalizedPath, durationMs, pullSettleSo
         },
     });
 }
+/**
+ * #2066: the ONE full-document walk a send needs, replacing the two that used
+ * to run independently — a `charCodeAt` loop counting `\n` for the
+ * `lsp_document_send` line count, and a `.split(/\r\n|\r|\n/)` in
+ * `buildContentChanges` that materialized one substring per line to read the
+ * last one. The #1095 sha256 is a third walk and stays; it is native, and it
+ * is load-bearing.
+ *
+ * The two counts here are deliberately NOT the same number and must not be
+ * collapsed into one. `lfNewlineCount` counts `\n` only, because its consumer
+ * pairs against `diagnostic_past_eof`, whose gate counts LF BYTES
+ * (`clients/diagnostic-line-freshness.ts`); merging the conventions would put
+ * the two records one apart on exactly the mixed-ending documents the pairing
+ * exists to debug. `lastLine` uses the full LSP terminator set (`\r\n`, lone
+ * `\r`, `\n` — #1669 review F6), because a CRLF or classic-Mac document whose
+ * terminators went uncounted computes a range ending mid-document.
+ */
+function scanSentContent(content) {
+    let lfNewlineCount = 0;
+    let index = 0;
+    let start = 0;
+    // `charCodeAt`, not `codePointAt` (typescript:S7758, accepted): both are
+    // compared against 10/13, which no surrogate unit or astral code point can
+    // equal, so they are interchangeable here — but `codePointAt` measured 8%
+    // slower on a 400 KiB LF document (0.716 vs 0.663 ms/scan), because every
+    // ordinary character pays a surrogate-pair check this loop never uses.
+    for (let i = 0; i < content.length; i++) {
+        const code = content.charCodeAt(i);
+        if (code !== 10 && code !== 13)
+            continue;
+        if (code === 10) {
+            lfNewlineCount++;
+        }
+        else if (content.charCodeAt(i + 1) === 10) {
+            // `\r\n` is ONE line terminator, and still carries the `\n` the
+            // LF-only count wants.
+            lfNewlineCount++;
+            i++;
+        }
+        index++;
+        start = i + 1;
+    }
+    return { lfNewlineCount, lastLine: { index, start } };
+}
 /**
  * #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
@@ -796,17 +947,85 @@ function logTypeScriptPullSettle(state, normalizedPath, durationMs, pullSettleSo
  * read on the notification path (I1). Bounded by the same file-size gates the
  * caller already applies to the content it hands us.
  */
-function recordSentContent(state, normalizedPath, version, content) {
+function recordSentContent(state, normalizedPath, version, content, coalescedCount = 0) {
+    const scan = scanSentContent(content);
+    const previous = state.documentContentHashes.get(normalizedPath);
+    if (previous && previous.version > version) {
+        incrementDegradationCount({
+            kind: "lsp-document-send-order",
+            subject: `${state.serverId}:${normalizedPath}`,
+            reason: `recorded version ${version} after newer version ${previous.version}`,
+        });
+        return;
+    }
+    if (previous?.text !== undefined) {
+        state.incrementalTextRetainedEntries = Math.max(0, (state.incrementalTextRetainedEntries ?? 1) - 1);
+        state.incrementalTextRetainedBytes = Math.max(0, (state.incrementalTextRetainedBytes ?? previous.text.length * 2) -
+            previous.text.length * 2);
+        // #2065 fix round 1 F5: the path is about to be rewritten below (and
+        // possibly re-marked text-bearing) — drop the stale membership first so
+        // the reinsert further down lands at the END of the recency order
+        // instead of leaving a duplicate-free but stale position.
+        state.incrementalTextBearingPaths?.delete(normalizedPath);
+    }
+    // #2065 fix round 1 F5: eviction recency now lives in
+    // `incrementalTextBearingPaths` (above/below), not this map's own
+    // insertion order — no remaining reader iterates `documentContentHashes`
+    // for order (every other site below is a keyed `.get`/`.delete`). The
+    // reinsert is kept anyway so a log or future debug dump that DOES walk
+    // this map in insertion order still reads "most recently sent last",
+    // matching the aux set it mirrors, rather than a stale mixed order.
+    state.documentContentHashes.delete(normalizedPath);
     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.
+        // #2066: `lastLine` is that reader's answer, already computed by the
+        // scan above — it rides along with the text it describes.
         ...(state.syncKind === TEXT_DOCUMENT_SYNC_KIND_INCREMENTAL && {
             text: content,
+            lastLine: scan.lastLine,
         }),
     });
+    if (state.syncKind === TEXT_DOCUMENT_SYNC_KIND_INCREMENTAL) {
+        state.incrementalTextRetainedEntries =
+            (state.incrementalTextRetainedEntries ?? 0) + 1;
+        state.incrementalTextRetainedBytes =
+            (state.incrementalTextRetainedBytes ?? 0) + content.length * 2;
+        // #2065 fix round 1 F5: track membership in the same insertion (=
+        // recency) order as `documentContentHashes` itself, so eviction below
+        // never needs to spread and scan the full content-binding map —
+        // including paths whose text was already stripped — just to find the
+        // oldest text-bearing one.
+        if (!state.incrementalTextBearingPaths) {
+            state.incrementalTextBearingPaths = new Set();
+        }
+        state.incrementalTextBearingPaths.add(normalizedPath);
+        while ((state.incrementalTextRetainedEntries ?? 0) >
+            MAX_INCREMENTAL_TEXT_RETAINED_ENTRIES ||
+            (state.incrementalTextRetainedBytes ?? 0) >
+                MAX_INCREMENTAL_TEXT_RETAINED_BYTES) {
+            const oldestPath = state.incrementalTextBearingPaths
+                ?.values()
+                .next().value;
+            if (oldestPath === undefined)
+                break;
+            const binding = state.documentContentHashes.get(oldestPath);
+            state.incrementalTextBearingPaths.delete(oldestPath);
+            if (!binding || binding.text === undefined)
+                continue;
+            // #2066: `lastLine` is dropped here with the text it describes. The
+            // #1095 version/hash binding is what must survive the strip.
+            state.documentContentHashes.set(oldestPath, {
+                version: binding.version,
+                hash: binding.hash,
+            });
+            state.incrementalTextRetainedEntries = Math.max(0, (state.incrementalTextRetainedEntries ?? 1) - 1);
+            state.incrementalTextRetainedBytes = Math.max(0, (state.incrementalTextRetainedBytes ?? 0) - binding.text.length * 2);
+        }
+    }
     // #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
@@ -818,14 +1037,9 @@ function recordSentContent(state, normalizedPath, version, content) {
     // 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++;
-    }
+    // exists to help debug. #2066: the count comes from `scanSentContent`
+    // above, which folded this loop into the walk `buildContentChanges` was
+    // already paying for; the LF-only convention is unchanged.
     logLatency({
         type: "phase",
         phase: "lsp_document_send",
@@ -834,7 +1048,8 @@ function recordSentContent(state, normalizedPath, version, content) {
         metadata: {
             version,
             contentLength: content.length,
-            contentLineCount: newlineCount + 1,
+            contentLineCount: scan.lfNewlineCount + 1,
+            ...(coalescedCount > 0 && { coalescedCount }),
         },
     });
 }
@@ -864,23 +1079,24 @@ 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) {
+    const previous = state.documentContentHashes.get(normalizedPath);
+    if (previous?.text === 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] ?? "";
+    const previousText = previous.text;
+    // #2066: `recordSentContent` scanned this exact text when it sent it, so
+    // read where it left the last line instead of walking (and splitting) the
+    // document a second time. An entry carrying text without that position was
+    // written by something else — resolve it through the SAME scanner, never a
+    // second convention that can drift from it.
+    const lastLine = previous.lastLine ?? scanSentContent(previousText).lastLine;
+    const lastLineText = previousText.slice(lastLine.start);
     return [
         {
             range: {
                 start: { line: 0, character: 0 },
                 end: {
-                    line: lastLine,
+                    line: lastLine.index,
                     character: convertCharacterOffset(state.positionEncoding, lastLineText, lastLineText.length),
                 },
             },
@@ -1208,14 +1424,33 @@ export function setupIncomingHandlers(state, initialization) {
         if (state.serverEditsAllowed <= 0 || !params?.edit) {
             return { applied: false, failureReason: "edit not solicited" };
         }
-        const context = (state.activeMutationDepth ?? 0) === 1
-            ? state.activeMutationContext
-            : undefined;
+        // #2450 fix round 3 (F3) removed a `depth === 1` re-check here as
+        // dead code. It is not dead — it moved to the WRITE side, where it
+        // is the live invariant: `state.activeMutationContext` is assigned
+        // only by `syncMutationContextSlot` (below in this file), which
+        // populates it exactly when `activeMutationDepth === 1` and
+        // empties it on every other frame transition. The depth test
+        // therefore still runs, on each entry and each unwind; repeating
+        // it here would be a second copy of the same predicate, not an
+        // independent gate. What this handler reads is consequently either
+        // the context of the single frame currently in flight or
+        // `undefined` — never a settled frame's context, and never a
+        // context belonging to some other window that is still open
+        // (#2479 review rounds 2/3).
+        const context = state.activeMutationContext;
+        // `workspace/applyEdit` is only ever honored inside the
+        // `serverEditsAllowed` window this handler just checked, which is
+        // opened exclusively by an executeCommand call — so a fallback here is
+        // always executeCommand-solicited, never a bare edit (#2450). This
+        // fallback context carries no runtime/cacheManager (there is no live
+        // reference to those singletons at this call site); lsp-mutation.ts's
+        // bookkeepLspMutation falls back to the mutation bridge for exactly
+        // that reason rather than silently dropping the write's bookkeeping.
         const telemetryContext = context ?? {
             cwd: state.root,
             correlationId: newLspMutationCorrelationId(),
             tool: "lsp-workspace-applyEdit",
-            source: "lsp-edit",
+            source: "lsp-execute-command",
         };
         try {
             await applyWorkspaceEdit(params.edit, state.root, {
@@ -2215,7 +2450,7 @@ export function handleNotifyExternalChange(state, filePath, type) {
     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) {
+async function handleNotifyOpenOnce(state, filePath, content, languageId, preserveDiagnostics = false, silent = false, coalescedCount = 0) {
     if (!isClientAlive(state))
         return;
     const normalizedPath = normalizeMapKey(filePath);
@@ -2263,7 +2498,7 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
             // #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);
+                recordSentContent(state, normalizedPath, version, content, coalescedCount);
             state.openDocuments.add(normalizedPath);
             state.openDocumentUris?.set(normalizedPath, uri);
             return;
@@ -2273,7 +2508,7 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
             contentChanges: buildContentChanges(state, normalizedPath, content),
         });
         if (changeSent)
-            recordSentContent(state, normalizedPath, version, content);
+            recordSentContent(state, normalizedPath, version, content, coalescedCount);
         return;
     }
     state.pendingOpens.add(normalizedPath);
@@ -2308,7 +2543,7 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
         return;
     const openSent = await safeSendNotification(state.connection, "textDocument/didOpen", { textDocument: { uri, languageId, version: 0, text: content } });
     if (openSent)
-        recordSentContent(state, normalizedPath, 0, content);
+        recordSentContent(state, normalizedPath, 0, content, coalescedCount);
     state.pendingOpens.delete(normalizedPath);
     state.openDocuments.add(normalizedPath);
     state.closedDocuments?.delete(normalizedPath);
@@ -2332,10 +2567,83 @@ export async function handleNotifyOpen(state, filePath, content, languageId, pre
         },
     });
 }
-export async function handleNotifyChange(state, filePath, content) {
+/**
+ * Replace only notifications that have not started a transport write. A
+ * microtask starts the first entry so a synchronous burst of callers installs
+ * one latest entry before any bytes are handed to vscode-jsonrpc. Once an
+ * entry starts, it runs to completion; LSP has no cancellation/acknowledgement
+ * for notifications, so dropping a started write could violate didOpen before
+ * didChange ordering or leave a partial message in the pipe.
+ */
+function enqueueDocumentNotify(state, normalizedPath, run) {
+    let queue = state.notifyChangeQueues.get(normalizedPath);
+    if (!queue) {
+        queue = { running: false };
+        state.notifyChangeQueues.set(normalizedPath, queue);
+    }
+    return new Promise((resolve, reject) => {
+        const previous = queue?.pending;
+        // Keep superseded callers attached to the replacement's completion. The
+        // notification is dropped, but callers such as the auxiliary backlog
+        // ledger must not observe completion before the newest content is sent.
+        const waiters = previous?.waiters ?? [];
+        waiters.push({ resolve, reject });
+        queue.pending = {
+            run,
+            waiters,
+            coalescedCount: (previous?.coalescedCount ?? 0) + (previous ? 1 : 0),
+        };
+        if (queue.running)
+            return;
+        queue.running = true;
+        // Let same-turn callers replace the unwritten entry before the runner
+        // invokes the transport. Different path queues still start independently.
+        void Promise.resolve().then(async () => {
+            try {
+                for (;;) {
+                    const next = queue.pending;
+                    if (!next)
+                        break;
+                    queue.pending = undefined;
+                    try {
+                        await next.run(next.coalescedCount);
+                        for (const waiter of next.waiters)
+                            waiter.resolve();
+                    }
+                    catch (error) {
+                        for (const waiter of next.waiters)
+                            waiter.reject(error);
+                    }
+                }
+            }
+            finally {
+                queue.running = false;
+                if (!queue.pending &&
+                    state.notifyChangeQueues.get(normalizedPath) === queue) {
+                    state.notifyChangeQueues.delete(normalizedPath);
+                }
+            }
+        });
+    });
+}
+/** Drop unwritten document notifications when a client is torn down. */
+function cancelDocumentNotifyQueues(state) {
+    for (const queue of state.notifyChangeQueues.values()) {
+        for (const waiter of queue.pending?.waiters ?? [])
+            waiter.resolve();
+        queue.pending = undefined;
+    }
+    state.notifyChangeQueues.clear();
+}
+export function handleNotifyOpen(state, filePath, content, languageId, preserveDiagnostics = false, silent = false) {
     if (!isClientAlive(state))
-        return;
+        return Promise.resolve();
     const normalizedPath = normalizeMapKey(filePath);
+    return enqueueDocumentNotify(state, normalizedPath, (coalescedCount) => handleNotifyOpenOnce(state, filePath, content, languageId, preserveDiagnostics, silent, coalescedCount));
+}
+async function handleNotifyChangeOnce(state, filePath, content, normalizedPath, coalescedCount = 0) {
+    if (!isClientAlive(state))
+        return;
     const uri = state.openDocumentUris?.get(normalizedPath) ?? pathToFileURL(filePath).href;
     if (!state.openDocuments.has(normalizedPath)) {
         // Safety fallback: keep protocol ordering valid even if caller sends
@@ -2352,7 +2660,7 @@ export async function handleNotifyChange(state, filePath, content) {
         state.documentOpenedAt.set(normalizedPath, Date.now());
         state.diagnosticPublicationCounts.set(normalizedPath, 0);
         if (fallbackOpenSent)
-            recordSentContent(state, normalizedPath, 0, content);
+            recordSentContent(state, normalizedPath, 0, content, coalescedCount);
         state.openDocuments.add(normalizedPath);
         state.openDocumentUris?.set(normalizedPath, uri);
         return;
@@ -2367,7 +2675,18 @@ export async function handleNotifyChange(state, filePath, content) {
         contentChanges: buildContentChanges(state, normalizedPath, content),
     });
     if (changeSent)
-        recordSentContent(state, normalizedPath, version, content);
+        recordSentContent(state, normalizedPath, version, content, coalescedCount);
+}
+/**
+ * #2113: serialize the read/build/send/record transaction per document. The
+ * content-change payload must be built against the content recorded by the
+ * preceding send for this path; unrelated paths retain parallel sends.
+ */
+export function handleNotifyChange(state, filePath, content) {
+    if (!isClientAlive(state))
+        return Promise.resolve();
+    const normalizedPath = normalizeMapKey(filePath);
+    return enqueueDocumentNotify(state, normalizedPath, (coalescedCount) => handleNotifyChangeOnce(state, filePath, content, normalizedPath, coalescedCount));
 }
 /** Close a document through the same lifecycle path exposed by the client. */
 export async function closeDocument(state, filePath) {
@@ -2393,7 +2712,44 @@ export async function closeDocument(state, filePath) {
     // 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);
+    const retained = state.documentContentHashes.get(normalizedPath);
+    if (retained?.text !== undefined) {
+        state.incrementalTextRetainedEntries = Math.max(0, (state.incrementalTextRetainedEntries ?? 1) - 1);
+        state.incrementalTextRetainedBytes = Math.max(0, (state.incrementalTextRetainedBytes ?? retained.text.length * 2) -
+            retained.text.length * 2);
+        // #2065 fix round 2 N1: `recordSentContent` and the eviction loop both
+        // delete from `incrementalTextBearingPaths` when they strip a path's
+        // text, but neither runs on close — this was the missing third writer.
+        // Without it, a closed path's membership in the aux set survives
+        // forever: below the 128-entry/64 MiB cap the eviction loop that would
+        // otherwise clean it up never runs at all, so the set grows by one
+        // stale entry per open/close cycle with nothing ever draining it — the
+        // exact unbounded-per-path-store class #2065 exists to close, just
+        // moved into the aux index instead of the byte-retention count itself.
+        state.incrementalTextBearingPaths?.delete(normalizedPath);
+    }
+    // Keep the hash/version binding only while the document is open; the full
+    // text is needed for the next edit, never after didClose (#2065).
+    state.documentContentHashes.delete(normalizedPath);
     clearDiagnosticsForPath(state, normalizedPath);
+    // #2065 fix round 2 (reverts fix round 1 F4): `pullGenerations` is the
+    // eighth per-path map in this family, but it is deliberately NOT cleared
+    // here — the same reasoning `clearDiagnosticsForPath` already documents
+    // above for `pullRequestSequences` applies to this counter too, and fix
+    // round 1's F4 missed it. `pullGenerationFor` defaults a missing entry to
+    // `0`, so deleting the entry on close resets the counter. A pull already
+    // in flight before the close captured its generation BEFORE this close's
+    // `clearDiagnosticsForPath` bump above ran. If the document is closed and
+    // reopened before that in-flight pull's write lands, deleting the entry
+    // here would let the counter read back as `0` again — the exact value the
+    // stale write's stale captured generation equals — so the write-time
+    // `!== generation` check at its call site would wrongly accept a stale
+    // answer computed against the pre-close content. Leaving the counter
+    // monotonic and un-reset keeps every pre-close capture permanently
+    // distinguishable from whatever the counter reads afterward, no matter how
+    // many closes or reopens happen in between. The cost is one integer per
+    // path that outlives the document's open lifetime — negligible next to
+    // correctness here.
 }
 /**
  * #1620 residual review F1: `fast` and `processExiting` only ever escalate —
@@ -2467,6 +2823,9 @@ async function clientShutdownOnce(state, options) {
     state.pendingOpens.clear();
     state.openDocuments.clear();
     state.openDocumentUris?.clear();
+    // #2357: superseded notifications that have not started writing are moot
+    // once this client is dead; resolve their callers and release the queue.
+    cancelDocumentNotifyQueues(state);
     // #1412 L1: mirror openDocuments' clear — a shut-down/evicted client's
     // probe memo is moot along with everything else document-scoped.
     state.projectIdentityProbedFiles?.clear();
@@ -2532,6 +2891,9 @@ async function clientShutdownOnce(state, options) {
         }
     }
     finally {
+        // #2065 fix round 1: deregistration now lives in disposeClientConnection
+        // itself (the convergence point for every crash/dispose path, not just
+        // this graceful one) — see its comment.
         disposeClientConnection(state);
         const pid = state.lspProcess.pid;
         logLatency({
@@ -2908,6 +3270,35 @@ async function clientPingLiveness(state, timeoutMs = LIVENESS_PING_TIMEOUT_MS) {
     }
     return isClientAlive(state);
 }
+// #2479: `activeMutationContext` is DERIVED state, not a stack. The frame that
+// takes `activeMutationDepth` 0 -> 1 owns the context for its whole lifetime
+// (`mutationContextOwner`); the slot merely exposes that owner while it is the
+// ONLY frame in flight. Deeper or overlapping frames therefore empty the slot
+// for as long as they are open — concurrent and nested commands deliberately
+// do not cross-correlate — and it refills by itself when they unwind, with no
+// frame having to remember anything.
+//
+// Recomputing beats saving and restoring because these frames do not nest:
+// `LSPClient.executeCommand` and `LSPService.executeCommand` fan out with no
+// mutex, parallel `lsp_navigation` calls with `apply: true` overlap, and #449
+// light mode shares one client across agents. With A (the owner), B and C
+// overlapping and the MIDDLE one settling first, a per-frame restore hands A's
+// context back while C's window is the open one — and `LspMutationContext`
+// carries a cwd plus a directly-threaded runtime/cacheManager, with
+// `readTurnState` / `appendProjectChange` cwd-scoped, so that routes a live
+// edit's bookkeeping into another project's change log (strictly worse than
+// the honest fallback the pre-#2479 code gave). An owner-liveness flag does
+// not fix it either: it answers "is an owner live", not "does the slot belong
+// to the window this edit is in" — and C's own unwind then puts back the
+// `undefined` it saved while the owner is still running, resurrecting #2479
+// (review round 3). Deriving answers the second question by construction, and
+// "no command in flight == no context" — the invariant the
+// `serverEditsAllowed` gate on `workspace/applyEdit` is paired with — falls
+// out of it with no depth-0 special case.
+function syncMutationContextSlot(state) {
+    state.activeMutationContext =
+        state.activeMutationDepth === 1 ? state.mutationContextOwner : undefined;
+}
 // Run an advertised server command via workspace/executeCommand, with the
 // generous EXECUTE_COMMAND_TIMEOUT_MS anti-deadlock backstop. Preserves the
 // hardening invariants: allowlist-by-advertisement (only commands the server
@@ -2926,10 +3317,20 @@ export async function runServerCommand(state, command, args, timeoutMs = EXECUTE
     }
     state.serverEditsAllowed += 1;
     state.activeMutationDepth = (state.activeMutationDepth ?? 0) + 1;
-    if (state.activeMutationDepth === 1)
-        state.activeMutationContext = mutationContext;
-    else
-        state.activeMutationContext = undefined;
+    // #2479: the frame that takes the depth to 1 owns the context; the slot is
+    // derived from that owner (see `syncMutationContextSlot` above). The
+    // pre-#2479 shape only ever CLEARED the slot, and only once the depth
+    // returned to 0, so a nested `executeCommand` unwinding from depth 2 back
+    // to 1 left the OUTER call without its own context for the rest of its
+    // window: every server-initiated `applyEdit` it still solicited read
+    // `undefined`, fell to the mutation bridge, and carried the generic
+    // `agent-tool:lsp-workspace-applyEdit` receipt instead of the outer
+    // operation's own (`lsp-rename` / `lsp-execute-command`).
+    const isMutationContextOwner = state.activeMutationDepth === 1;
+    if (isMutationContextOwner) {
+        state.mutationContextOwner = mutationContext;
+    }
+    syncMutationContextSlot(state);
     try {
         let result;
         try {
@@ -2956,8 +3357,15 @@ export async function runServerCommand(state, command, args, timeoutMs = EXECUTE
     finally {
         state.serverEditsAllowed -= 1;
         state.activeMutationDepth = Math.max(0, (state.activeMutationDepth ?? 0) - 1);
-        if (state.activeMutationDepth === 0)
-            state.activeMutationContext = undefined;
+        // The owner drops its context; every frame then resyncs. Both the
+        // hand-back to a still-live owner once the deeper frames unwind and
+        // the empty slot while more than one frame is open are consequences of
+        // the derivation, not separate rules each frame has to get right
+        // (#2479 review rounds 2/3).
+        if (isMutationContextOwner) {
+            state.mutationContextOwner = undefined;
+        }
+        syncMutationContextSlot(state);
     }
 }
 // #1412 H1/H2: read-only sibling of runServerCommand for telemetry/identity
@@ -3060,6 +3468,14 @@ async function resolveCodeActionBestEffort(state, action) {
             edit: await normalizeClientWorkspaceEdit(state, action.edit),
         };
     }
+    if (!state.operationSupport.codeActionResolve) {
+        recordDegradationOnce({
+            kind: "lsp-capability-skip",
+            subject: `${state.serverId}:codeAction/resolve`,
+            reason: "server did not advertise codeActionProvider.resolveProvider",
+        });
+        return action;
+    }
     let resolved;
     try {
         resolved = await withTimeout(safeSendRequest(state.connection, "codeAction/resolve", action), NAV_REQUEST_TIMEOUT_MS);
@@ -3082,7 +3498,7 @@ async function resolveCodeActionBestEffort(state, action) {
 // --- Client Factory ---
 export async function createLSPClient(options) {
     installCrashGuard();
-    const { serverId, process: lspProcess, root, initialization, initializeTimeoutMs = INITIALIZE_TIMEOUT_MS, launchVariant, } = options;
+    const { serverId, process: lspProcess, root, sessionCwd, initialization, initializeTimeoutMs = INITIALIZE_TIMEOUT_MS, launchVariant, } = options;
     // #449/#472: register this LSP child in the cross-process instance registry
     // as soon as we have a live pid — BEFORE `initialize` completes, not after.
     // Registering early means a child that dies/hangs during initialize (the
@@ -3095,6 +3511,11 @@ export async function createLSPClient(options) {
         serverId,
         command: lspProcess.command,
         marker: extractSpawnMarker(lspProcess.args),
+        sessionIdentity: {
+            projectRoot: sessionCwd ?? process.cwd(),
+            rootSource: sessionCwd ? "service-cwd" : "lsp-fallback",
+            startedAt: new Date(workspaceDiagnosticsCacheSessionStart()).toISOString(),
+        },
     }).catch((err) => {
         // best-effort observability — never fail LSP startup over this
         logLatency({
@@ -3204,8 +3625,12 @@ export async function createLSPClient(options) {
         diagnosticsVersion: 0,
         diagnosticsVersionsByPath: new Map(),
         documentVersions: new Map(),
+        notifyChangeQueues: new Map(),
         diagnosticDocVersions: new Map(),
         documentContentHashes: new Map(),
+        incrementalTextRetainedEntries: 0,
+        incrementalTextBearingPaths: new Set(),
+        incrementalTextRetainedBytes: 0,
         diagnosticBindings: new Map(),
         pullResultIds: new Map(),
         documentPullDiagnosticsBySource: new Map(),
@@ -3238,6 +3663,7 @@ export async function createLSPClient(options) {
         // SAFETY: state construction completes before the flush closure can run.
         watchQueue: undefined,
     };
+    activeLspClientSet().add(state);
     // #271: batch per-file workspace/didChangeWatchedFiles into one notification
     // per debounce window, so an N-file turn re-indexes the server once, not N×.
     state.watchQueue = new WatchedFilesQueue((changes) => {
@@ -3340,6 +3766,31 @@ export async function createLSPClient(options) {
     state.workspaceDiagnosticsSupport =
         detectWorkspaceDiagnosticsSupport(initResult);
     state.operationSupport = detectOperationSupport(initResult);
+    const capabilities = (initResult
+        ?.capabilities ?? {});
+    const workspace = isCapabilityRecord(capabilities.workspace)
+        ? capabilities.workspace
+        : undefined;
+    const fileOperations = isCapabilityRecord(workspace)
+        ? workspace.fileOperations
+        : undefined;
+    const malformedFileOperationRegistrations = new Set();
+    if (isCapabilityRecord(fileOperations)) {
+        for (const operation of ["willRename", "didRename"]) {
+            if (fileOperations[operation] !== undefined &&
+                parseFileOperationFilters(fileOperations[operation]) === undefined) {
+                malformedFileOperationRegistrations.add(operation);
+            }
+        }
+    }
+    state.fileOperationMalformedRegistrations =
+        malformedFileOperationRegistrations;
+    if (isCapabilityRecord(fileOperations)) {
+        state.fileOperationFilters = {
+            willRename: parseFileOperationFilters(fileOperations.willRename),
+            didRename: parseFileOperationFilters(fileOperations.didRename),
+        };
+    }
     state.positionEncoding = negotiatePositionEncoding(initResult?.capabilities);
     state.syncKind = negotiateSyncKind(initResult?.capabilities);
     state.rawCapabilityKeys = Object.keys(initResult?.capabilities ??
@@ -3376,6 +3827,8 @@ export async function createLSPClient(options) {
         checkAlive: () => checkProcessAlive(),
         /** #1277: cheap request round-trip proving the server still responds. */
         pingLiveness: (timeoutMs) => clientPingLiveness(state, timeoutMs),
+        /** #2358: the OS pid of the live server process (see interface doc). */
+        getProcessPid: () => lspProcess.pid,
         notify: {
             async open(filePath, content, languageId, preserveDiagnostics, silent) {
                 return handleNotifyOpen(state, filePath, content, languageId, preserveDiagnostics, silent);
@@ -3444,6 +3897,9 @@ export async function createLSPClient(options) {
         getOperationSupport() {
             return state.operationSupport;
         },
+        getMalformedFileOperationRegistrations() {
+            return state.fileOperationMalformedRegistrations ?? new Set();
+        },
         getAdvertisedCommands() {
             return [...state.advertisedCommands];
         },
@@ -3521,6 +3977,9 @@ export async function createLSPClient(options) {
         isDocumentOpen(filePath) {
             return state.openDocuments.has(normalizeMapKey(filePath));
         },
+        openDocumentPaths() {
+            return [...state.openDocuments];
+        },
         isBusy() {
             return (activeRequestsByConnection.get(connection) ?? 0) > 0;
         },
@@ -3570,11 +4029,26 @@ export async function createLSPClient(options) {
         },
         closeDocument: (filePath) => closeDocument(state, filePath),
         async willRenameFiles(oldFilePath, newFilePath) {
+            if (!isClientAlive(state))
+                return null;
+            // #1971 review: the server registered WHICH paths it cares about.
+            // Sending outside those filters asks a question the server never
+            // signed up to answer.
+            const oldUri = pathToFileURL(oldFilePath).href;
+            const newUri = pathToFileURL(newFilePath).href;
+            if (!(await fileOperationFiltersMatch(state.fileOperationFilters?.willRename, oldUri, newUri, oldFilePath, newFilePath))) {
+                recordDegradationOnce({
+                    kind: "lsp-capability-skip",
+                    subject: `${state.serverId}:workspace/willRenameFiles:filter`,
+                    reason: "filter-mismatch",
+                });
+                return null;
+            }
             const result = await navRequest(state, "workspace/willRenameFiles", {
                 files: [
                     {
-                        oldUri: pathToFileURL(oldFilePath).href,
-                        newUri: pathToFileURL(newFilePath).href,
+                        oldUri,
+                        newUri,
                     },
                 ],
             });
@@ -3583,11 +4057,28 @@ export async function createLSPClient(options) {
         async didRenameFiles(oldFilePath, newFilePath, oldUri, newUri) {
             if (!isClientAlive(state))
                 return;
+            // `fileOperationFilters.didRename` is parsed by the same predicate that
+            // derives operationSupport.didRenameFiles (see
+            // isFileOperationRegistrationOptions). Thus filters undefined iff the
+            // capability is absent; the service-level gate remains the enforcement
+            // point for aggregated dispatch.
+            // #1971 review: same registration-filter discipline as willRename —
+            // the server only signed up to hear about matching paths.
+            const wireOldUri = oldUri ?? pathToFileURL(oldFilePath).href;
+            const wireNewUri = newUri ?? pathToFileURL(newFilePath).href;
+            if (!(await fileOperationFiltersMatch(state.fileOperationFilters?.didRename, wireOldUri, wireNewUri, oldFilePath, newFilePath))) {
+                recordDegradationOnce({
+                    kind: "lsp-capability-skip",
+                    subject: `${state.serverId}:workspace/didRenameFiles:filter`,
+                    reason: "filter-mismatch",
+                });
+                return;
+            }
             await safeSendNotification(state.connection, "workspace/didRenameFiles", {
                 files: [
                     {
-                        oldUri: oldUri ?? pathToFileURL(oldFilePath).href,
-                        newUri: newUri ?? pathToFileURL(newFilePath).href,
+                        oldUri: wireOldUri,
+                        newUri: wireNewUri,
                     },
                 ],
             });
@@ -3818,8 +4309,13 @@ function detectOperationSupport(initResult) {
             return false;
         if (typeof value === "boolean")
             return value;
-        return true;
+        return isCapabilityRecord(value);
     };
+    const codeActionProvider = capabilities?.codeActionProvider;
+    const workspace = capabilities?.workspace;
+    const fileOperations = isCapabilityRecord(workspace)
+        ? workspace.fileOperations
+        : undefined;
     return {
         definition: hasProvider("definitionProvider"),
         typeDefinition: hasProvider("typeDefinitionProvider"),
@@ -3830,8 +4326,135 @@ function detectOperationSupport(initResult) {
         documentSymbol: hasProvider("documentSymbolProvider"),
         workspaceSymbol: hasProvider("workspaceSymbolProvider"),
         codeAction: hasProvider("codeActionProvider"),
+        codeActionResolve: isCapabilityRecord(codeActionProvider) &&
+            codeActionProvider.resolveProvider === true,
         rename: hasProvider("renameProvider"),
+        willRenameFiles: isCapabilityRecord(fileOperations) &&
+            isFileOperationRegistrationOptions(fileOperations.willRename),
+        didRenameFiles: isCapabilityRecord(fileOperations) &&
+            isFileOperationRegistrationOptions(fileOperations.didRename),
         implementation: hasProvider("implementationProvider"),
         callHierarchy: hasProvider("callHierarchyProvider"),
     };
 }
+function isCapabilityRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFileOperationRegistrationOptions(value) {
+    return parseFileOperationFilters(value) !== undefined;
+}
+/**
+ * Parse the filters of a `FileOperationRegistrationOptions` object. Returns
+ * `undefined` when the options are absent or malformed — callers treat that as
+ * "no interest declared" and fail closed, never sending the operation.
+ */
+function parseFileOperationFilters(value) {
+    if (!isCapabilityRecord(value) || !Array.isArray(value.filters)) {
+        return undefined;
+    }
+    const filters = [];
+    for (const entry of value.filters) {
+        if (!isCapabilityRecord(entry))
+            return undefined;
+        const pattern = entry.pattern;
+        if (!isCapabilityRecord(pattern) ||
+            typeof pattern.glob !== "string" ||
+            pattern.glob.trim() === "") {
+            return undefined;
+        }
+        if (entry.scheme !== undefined &&
+            (typeof entry.scheme !== "string" ||
+                entry.scheme.trim() === "" ||
+                !/^[A-Za-z][A-Za-z0-9+.-]*$/.test(entry.scheme))) {
+            return undefined;
+        }
+        const matches = pattern.matches;
+        if (matches !== undefined && matches !== "file" && matches !== "folder") {
+            return undefined;
+        }
+        if (pattern.options !== undefined && !isCapabilityRecord(pattern.options)) {
+            return undefined;
+        }
+        const options = isCapabilityRecord(pattern.options)
+            ? pattern.options
+            : undefined;
+        if (options?.ignoreCase !== undefined &&
+            typeof options.ignoreCase !== "boolean") {
+            return undefined;
+        }
+        filters.push({
+            scheme: entry.scheme?.toLowerCase(),
+            glob: pattern.glob,
+            matches: matches === "file" || matches === "folder" ? matches : undefined,
+            ignoreCase: options?.ignoreCase === true,
+        });
+    }
+    return filters;
+}
+/**
+ * Whether ANY parsed filter expresses interest in either path of a rename.
+ * Conservative by design: unsupported URI schemes, an unresolved explicit
+ * file/folder kind, malformed URIs, and zero filters all match nothing.
+ */
+async function fileOperationFiltersMatch(filters, oldUri, newUri, oldFilePath, newFilePath) {
+    if (!filters || filters.length === 0)
+        return false;
+    const candidates = [oldUri, newUri].flatMap(fileOperationUriCandidates);
+    const entityKind = filters.some((filter) => filter.matches !== undefined)
+        ? await probeRenameEntityKind(oldFilePath, newFilePath)
+        : undefined;
+    for (const filter of filters) {
+        if (filter.scheme !== undefined && filter.scheme !== "file")
+            continue;
+        if (filter.matches !== undefined && filter.matches !== entityKind)
+            continue;
+        for (const candidate of candidates) {
+            try {
+                if (minimatch(candidate, filter.glob, {
+                    nocase: filter.ignoreCase,
+                    dot: true,
+                })) {
+                    return true;
+                }
+            }
+            catch {
+                // Malformed glob implementations must never widen server fan-out.
+            }
+        }
+    }
+    return false;
+}
+function fileOperationUriCandidates(uri) {
+    let parsed;
+    try {
+        parsed = new URL(uri);
+    }
+    catch {
+        return [];
+    }
+    // pi-lens performs local filesystem renames only. Even when a caller supplies
+    // preserved URI spelling, another scheme cannot describe that operation.
+    if (parsed.protocol.toLowerCase() !== "file:")
+        return [];
+    let uriPath;
+    try {
+        uriPath = decodeURIComponent(parsed.pathname).replace(/\\/g, "/");
+    }
+    catch {
+        return [];
+    }
+    return [uriPath];
+}
+async function probeRenameEntityKind(oldFilePath, newFilePath) {
+    for (const filePath of [oldFilePath, newFilePath]) {
+        try {
+            const info = await lstat(filePath);
+            return info.isDirectory() ? "folder" : "file";
+        }
+        catch {
+            // Before the rename the old path normally exists; after it, the new path
+            // does. Probe both instead of deriving behavior from the host OS.
+        }
+    }
+    return undefined;
+}